@feelgxxd/textel 0.0.0-stage → 0.2.0

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;

package/dist/cli/commands/render.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { recordLoop, stringifyFrames } from "../../frames.js";
+import { createRenderer } from "../../render.js";
+import { mergeStyles } from "../../style.js";
+import { fail, HELP_OPTIONS, INPUT_HELP, INPUT_OPTIONS, loadInput, num, parse, STYLE_HELP, STYLE_OPTIONS, styleFrom } from "../shared.js";
+export const summary = 'record a spinning loop into a .textel.json file';
+export const HELP = `textel render: record a spinning loop into a .textel.json file
+
+usage
+  textel render <model> [-o out.textel.json] [options]
+  textel render --example <name> [options]
+
+${INPUT_HELP}
+
+recording
+  -o, --out <file>          output file (default: <name>.textel.json here)
+      --frames <n>          frames in the loop (default 120)
+      --fps <n>             playback rate (default 30)
+      --turns <n>           turns over the loop; negative spins the other way (default 1)
+      --force               overwrite an existing file
+
+${STYLE_HELP}
+
+  the grid defaults to 112x56 at aspect 2 (terminals); for a web page pass the
+  aspect of its font, for example --aspect 1.5
+`;
+const OPTIONS = {
+    ...INPUT_OPTIONS,
+    ...STYLE_OPTIONS,
+    ...HELP_OPTIONS,
+    out: { type: 'string', short: 'o' },
+    frames: { type: 'string' },
+    fps: { type: 'string' },
+    turns: { type: 'string' },
+    force: { type: 'boolean' },
+};
+const kb = (n) => (n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`);
+function version() {
+    return JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version;
+}
+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 frames = num(o.frames, '--frames') ?? 120, fps = num(o.fps, '--fps') ?? 30, turns = num(o.turns, '--turns') ?? 1;
+    if (!(frames >= 1 && frames <= 10000 && Number.isInteger(frames)))
+        fail('--frames is a whole number from 1 to 10000');
+    if (!(fps > 0 && fps <= 120))
+        fail('--fps is between 0 and 120');
+    if (turns === 0)
+        fail('--turns cannot be 0');
+    const stem = o.example ? o.example.toLowerCase() : basename(positionals[0], extname(positionals[0]));
+    const out = resolve(o.out ?? `${stem}.textel.json`);
+    if (existsSync(out) && !o.force)
+        fail(`${basename(out)} exists; pass --force to overwrite`);
+    const flags = styleFrom(o, input.style);
+    const style = mergeStyles({ width: 112, height: 56, aspect: 2 }, flags);
+    let renderer;
+    try {
+        renderer = createRenderer(input.mesh, style);
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    const progress = process.stderr.isTTY;
+    const t0 = performance.now();
+    let shown = -1;
+    const { width: _w, height: _h, ...look } = style;
+    const rec = recordLoop(renderer, {
+        frames, fps, turns,
+        // enough to render the same file again
+        meta: { title: input.name, generator: `textel ${version()}`, turns, style: look },
+        onFrame: (i, total) => {
+            const pct = Math.floor((i / total) * 100);
+            if (!progress || pct === shown)
+                return;
+            shown = pct;
+            process.stderr.write(`\rrendering ${i}/${total} (${pct}%)`);
+        },
+    });
+    const json = stringifyFrames(rec);
+    writeFileSync(out, json);
+    if (progress)
+        process.stderr.write('\r\x1b[K');
+    const secs = ((performance.now() - t0) / 1000).toFixed(1);
+    process.stderr.write(`wrote ${basename(out)}: ${frames} frames, ${rec.width}x${rec.height}, ${kb(json.length)} (${kb(gzipSync(json).length)} gzipped), ${secs}s\n`);
+}

package/dist/cli/live.d.ts

@@ -0,0 +1,13 @@
+import type { Mesh } from '../mesh.ts';
+import { type ColorDepth } from '../output.ts';
+import { type StyleInput } from '../style.ts';
+export interface LiveOptions {
+    mesh: Mesh;
+    name: string;
+    style: StyleInput;
+    fixedSize: [number, number] | null;
+    depth: ColorDepth;
+    fps: number;
+}
+/** Full-screen live rendering in the terminal until q / Ctrl+C. */
+export declare function live(opts: LiveOptions): void;

package/dist/cli/live.js

@@ -0,0 +1,116 @@
+import { toANSI } from "../output.js";
+import { createRenderer } from "../render.js";
+import { CHARSETS, mergeStyles, resolveStyle } from "../style.js";
+import { Screen } from "../terminal.js";
+const EDGE_MODES = [false, 'outline', 'depth'];
+/** Full-screen live rendering in the terminal until q / Ctrl+C. */
+export function live(opts) {
+    const base = resolveStyle(opts.style);
+    let screen;
+    const size = () => opts.fixedSize ?? [Math.max(10, screen.columns), Math.max(5, screen.rows - 1)];
+    const charsets = Object.keys(CHARSETS);
+    const initialCharset = opts.style.chars !== undefined ? 'custom' : opts.style.charset ?? 'classic';
+    let charsetName = initialCharset;
+    let edgeMode = EDGE_MODES.indexOf(base.edges);
+    let yaw = 0, pitchOffset = 0, zoom = base.zoom, light = 0, paused = base.spin === 0;
+    const spin = base.spin || 0.66;
+    let fps = 0, frames = 0, acc = 0, last = performance.now();
+    let timer;
+    const quit = (code = 0) => {
+        clearInterval(timer);
+        screen.close();
+        process.exit(code);
+    };
+    const onKey = (key) => {
+        switch (key) {
+            case 'q':
+            case 'Q':
+            case '\x03':
+            case '\x1b':
+                quit();
+                break;
+            case ' ':
+                paused = !paused;
+                break;
+            case '\x1b[C':
+                yaw += 0.2;
+                break;
+            case '\x1b[D':
+                yaw -= 0.2;
+                break;
+            case '\x1b[A':
+                pitchOffset -= 0.15;
+                break;
+            case '\x1b[B':
+                pitchOffset += 0.15;
+                break;
+            case '+':
+            case '=':
+                zoom *= 1.1;
+                renderer.setStyle({ zoom });
+                break;
+            case '-':
+            case '_':
+                zoom /= 1.1;
+                renderer.setStyle({ zoom });
+                break;
+            case 'c': {
+                const i = charsets.indexOf(charsetName);
+                charsetName = charsets[(i + 1) % charsets.length];
+                renderer.setStyle({ charset: charsetName, chars: undefined });
+                break;
+            }
+            case 'e':
+                edgeMode = (edgeMode + 1) % EDGE_MODES.length;
+                renderer.setStyle({ edges: EDGE_MODES[edgeMode] });
+                break;
+            case 'l': {
+                // swing the light around the model in 45° steps
+                light = (light + 1) % 8;
+                const a = (light * Math.PI) / 4, [lx, ly, lz] = base.light;
+                renderer.setStyle({ light: [lx * Math.cos(a) + lz * Math.sin(a), ly, -lx * Math.sin(a) + lz * Math.cos(a)] });
+                break;
+            }
+            case 'r':
+                yaw = 0;
+                pitchOffset = 0;
+                zoom = base.zoom;
+                light = 0;
+                edgeMode = EDGE_MODES.indexOf(base.edges);
+                charsetName = initialCharset;
+                renderer.setStyle({ ...opts.style, zoom, light: base.light, edges: base.edges });
+                break;
+        }
+    };
+    screen = new Screen({
+        onKey,
+        onResize: () => {
+            if (opts.fixedSize)
+                return;
+            const [w, h] = size();
+            renderer.setStyle({ width: w, height: h });
+        },
+    });
+    process.on('SIGTERM', () => quit());
+    process.on('uncaughtException', (e) => { screen.close(); console.error(e); process.exit(1); });
+    const [w0, h0] = size();
+    const renderer = createRenderer(opts.mesh, mergeStyles(opts.style, { width: w0, height: h0 }));
+    const tick = () => {
+        const now = performance.now(), dt = Math.min(now - last, 100) / 1000;
+        last = now;
+        frames++;
+        acc += dt;
+        if (acc >= 0.5) {
+            fps = Math.round(frames / acc);
+            frames = 0;
+            acc = 0;
+        }
+        if (!paused)
+            yaw += spin * dt;
+        const frame = renderer.render({ yaw, pitch: base.pitch + pitchOffset });
+        const edge = EDGE_MODES[edgeMode] || 'off';
+        screen.draw(toANSI(frame, opts.depth), ` ${opts.name} · ${frame.width}×${frame.height} · ${charsetName} · edges ${edge} · ${fps}fps${paused ? ' · paused' : ''}   ←→↑↓ rotate  +/- zoom  c chars  e edges  l light  space pause  r reset  q quit`);
+    };
+    tick();
+    timer = setInterval(tick, 1000 / Math.max(1, Math.min(120, opts.fps)));
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import * as list from "./commands/list.js";
+import * as play from "./commands/play.js";
+import * as preview from "./commands/preview.js";
+import * as render from "./commands/render.js";
+import { fail } from "./shared.js";
+const COMMANDS = { preview, render, play, list };
+const HELP = `textel: 3D models as animated ASCII art
+
+usage
+  textel <model> [options]       spin it in the terminal (same as textel preview)
+  textel <command> [options]
+
+commands
+${Object.entries(COMMANDS).map(([name, c]) => `  ${name.padEnd(10)} ${c.summary}`).join('\n')}
+  help       help for a command: textel help preview
+
+  -v, --version
+  -h, --help
+
+examples
+  textel model.glb
+  textel --example gem --color "#301000,#ffb000"
+  textel render logo.glb -o logo.textel.json
+  textel play logo.textel.json
+  textel model.stl --once --size 80x40 > art.txt
+`;
+function version() {
+    return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+}
+function main(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first === '-h' || first === '--help')
+        return void process.stdout.write(HELP);
+    if (first === '-v' || first === '--version')
+        return void process.stdout.write(version() + '\n');
+    if (first === 'help') {
+        if (!rest[0])
+            return void process.stdout.write(HELP);
+        const c = COMMANDS[rest[0]] ?? fail(`no command "${rest[0]}" (have: ${Object.keys(COMMANDS).join(', ')})`);
+        return void process.stdout.write(c.HELP);
+    }
+    // kept from 0.1
+    if (first === '--list')
+        return list.run(rest);
+    const command = COMMANDS[first];
+    if (command)
+        return command.run(rest);
+    // anything else is a model path or preview flags
+    preview.run(argv);
+}
+main(process.argv.slice(2));

package/dist/cli/shared.d.ts

@@ -0,0 +1,103 @@
+import { type ParseArgsConfig } from 'node:util';
+import type { Mesh } from '../mesh.ts';
+import type { ColorDepth } from '../output.ts';
+import { type StyleInput } from '../style.ts';
+export declare function fail(msg: string): never;
+export declare const num: (s: string | undefined, what: string) => number | undefined;
+/**
+ * `--edges` may come without a value (it then means outline), and values may be negative numbers,
+ * which parseArgs would otherwise read as flags: `--pitch -0.3` becomes `--pitch=-0.3`.
+ */
+export declare function normalizeArgv(argv: string[]): string[];
+type Options = NonNullable<ParseArgsConfig['options']>;
+/** where the model comes from */
+export declare const INPUT_OPTIONS: {
+    example: {
+        type: "string";
+        short: string;
+    };
+};
+/** everything that changes the look; all of it can also come from a preset file */
+export declare const STYLE_OPTIONS: {
+    chars: {
+        type: "string";
+        short: string;
+    };
+    preset: {
+        type: "string";
+        short: string;
+    };
+    color: {
+        type: "string";
+    };
+    'no-color': {
+        type: "boolean";
+    };
+    edges: {
+        type: "string";
+    };
+    light: {
+        type: "string";
+    };
+    ambient: {
+        type: "string";
+    };
+    shading: {
+        type: "string";
+    };
+    pitch: {
+        type: "string";
+    };
+    spin: {
+        type: "string";
+    };
+    zoom: {
+        type: "string";
+    };
+    distance: {
+        type: "string";
+    };
+    size: {
+        type: "string";
+        short: string;
+    };
+    aspect: {
+        type: "string";
+        short: string;
+    };
+};
+export declare const HELP_OPTIONS: {
+    help: {
+        type: "boolean";
+        short: string;
+    };
+};
+export declare const INPUT_HELP = "input\n  <model>                   a .glb, .gltf, .obj or .stl file\n  -e, --example <name>      a built-in scene instead (textel list)";
+export declare const STYLE_HELP = "look\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)";
+/** parseArgs with our argv fixes; errors become a clean message */
+export declare function parse<O extends Options>(argv: string[], options: O): {
+    values: O extends import("util").ParseArgsOptionsConfig ? { -readonly [LongOption in keyof O]?: { [LongOption_2 in keyof O]: O[LongOption_2]["multiple"] extends infer T ? T extends O[LongOption_2]["multiple"] ? T extends false ? O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean : T extends true ? (O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean)[] : O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean : never : never; }[LongOption] | undefined; } & { [LongOption_1 in keyof O as O[LongOption_1]["default"] extends {} ? LongOption_1 : never]: { [LongOption_3 in keyof O]: O[LongOption_3]["multiple"] extends infer T ? T extends O[LongOption_3]["multiple"] ? T extends false ? O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean : T extends true ? (O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean)[] : O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean : never : never; }[LongOption_1]; } extends infer P ? { [K in keyof P]: P[K]; } : never : {};
+    positionals: string[];
+};
+type StyleValues = {
+    [K in keyof typeof STYLE_OPTIONS]?: (typeof STYLE_OPTIONS)[K]['type'] extends 'boolean' ? boolean : string;
+};
+type InputValues = {
+    example?: string;
+};
+export interface Input {
+    mesh: Mesh;
+    /** shown in status lines and metadata */
+    name: string;
+    /** the example's own look, if it is one */
+    style: StyleInput;
+}
+/** the model from `--example` or the first positional; null when neither was given */
+export declare function loadInput(values: InputValues, positionals: string[]): Input | null;
+/** `--size WxH`, or null */
+export declare function parseSize(s: string | undefined): [number, number] | null;
+/** the final style: the example's look < preset file < flags */
+export declare function styleFrom(o: StyleValues, base: StyleInput): StyleInput;
+/** what stdout can show, honoring NO_COLOR / FORCE_COLOR and --no-color */
+export declare function colorDepth(noColor: boolean | undefined): ColorDepth;
+export {};

package/dist/cli/shared.js

@@ -0,0 +1,178 @@
+// Pieces every command shares: argument parsing, model input, style flags, color detection.
+import { readFileSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { buildExample, EXAMPLES, findExample } from "../examples.js";
+import { parseModel } from "../loaders/index.js";
+import { detectColorDepth } from "../terminal.js";
+import { CHARSETS, mergeStyles } from "../style.js";
+export function fail(msg) {
+    process.stderr.write(`textel: ${msg}\n`);
+    process.exit(1);
+}
+export const num = (s, what) => {
+    if (s === undefined)
+        return undefined;
+    const v = Number(s);
+    if (!Number.isFinite(v))
+        fail(`${what} is not a number: ${s}`);
+    return v;
+};
+const nums = (s, n, what) => {
+    const v = s.split(',').map(Number);
+    if (v.length !== n || v.some((x) => !Number.isFinite(x)))
+        fail(`${what} needs ${n} comma separated numbers`);
+    return v;
+};
+/**
+ * `--edges` may come without a value (it then means outline), and values may be negative numbers,
+ * which parseArgs would otherwise read as flags: `--pitch -0.3` becomes `--pitch=-0.3`.
+ */
+export function normalizeArgv(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i], next = argv[i + 1];
+        if (a === '--edges' && !['outline', 'depth', 'off'].includes(next))
+            out.push('--edges=outline');
+        else if (/^--?[a-z]/i.test(a) && !a.includes('=') && next !== undefined && /^-[\d.]/.test(next)) {
+            out.push(`${a}=${next}`);
+            i++;
+        }
+        else
+            out.push(a);
+    }
+    return out;
+}
+/** where the model comes from */
+export const INPUT_OPTIONS = {
+    example: { type: 'string', short: 'e' },
+};
+/** everything that changes the look; all of it can also come from a preset file */
+export const STYLE_OPTIONS = {
+    chars: { type: 'string', short: 'c' },
+    preset: { type: 'string', short: 'p' },
+    color: { type: 'string' },
+    'no-color': { type: 'boolean' },
+    edges: { type: 'string' },
+    light: { type: 'string' },
+    ambient: { type: 'string' },
+    shading: { type: 'string' },
+    pitch: { type: 'string' },
+    spin: { type: 'string' },
+    zoom: { type: 'string' },
+    distance: { type: 'string' },
+    size: { type: 'string', short: 's' },
+    aspect: { type: 'string', short: 'a' },
+};
+export const HELP_OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+};
+export const INPUT_HELP = `input
+  <model>                   a .glb, .gltf, .obj or .stl file
+  -e, --example <name>      a built-in scene instead (textel list)`;
+export const STYLE_HELP = `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
+      --no-color            plain characters
+      --edges [depth]       outline the silhouette; depth also marks depth steps; off
+      --light <x,y,z>       direction toward the light (x right, y up, z toward you)
+      --ambient <0..1>      brightness floor
+      --shading <mode>      auto | flat | smooth
+
+camera
+      --pitch <rad>         resting tilt; positive shows the top
+      --spin <rad/s>        auto rotation speed (0 = still)
+      --zoom <n>            1 fills the grid
+      --distance <n>        camera distance in model radii (perspective)
+  -s, --size <WxH>          grid size
+  -a, --aspect <n>          character height / width (default 2)`;
+/** parseArgs with our argv fixes; errors become a clean message */
+export function parse(argv, options) {
+    try {
+        return parseArgs({ args: normalizeArgv(argv), allowPositionals: true, options, strict: true });
+    }
+    catch (e) {
+        fail(e.message);
+    }
+}
+/** the model from `--example` or the first positional; null when neither was given */
+export function loadInput(values, positionals) {
+    if (values.example) {
+        const ex = findExample(values.example) ?? fail(`no example "${values.example}" (have: ${EXAMPLES.map((e) => e.name).join(', ')})`);
+        return { mesh: buildExample(ex), name: ex.title, style: ex.style };
+    }
+    const arg = positionals[0];
+    if (!arg)
+        return null;
+    const file = resolve(arg);
+    let bytes;
+    try {
+        bytes = readFileSync(file);
+    }
+    catch {
+        fail(`cannot read ${arg}`);
+    }
+    try {
+        return { mesh: parseModel(bytes, file, { resolve: (uri) => readFileSync(resolve(dirname(file), uri)) }), name: basename(file), style: {} };
+    }
+    catch (e) {
+        fail(`${basename(file)}: ${e.message}`);
+    }
+}
+/** `--size WxH`, or null */
+export function parseSize(s) {
+    if (!s)
+        return null;
+    const m = /^(\d+)x(\d+)$/i.exec(s) ?? fail('--size looks like 112x56');
+    return [+m[1], +m[2]];
+}
+/** the final style: the example's look < preset file < flags */
+export function styleFrom(o, base) {
+    let preset = {};
+    if (o.preset) {
+        try {
+            preset = JSON.parse(readFileSync(resolve(o.preset), 'utf8'));
+        }
+        catch (e) {
+            fail(`preset: ${e.message}`);
+        }
+    }
+    const flags = {};
+    if (o.chars !== undefined) {
+        if (CHARSETS[o.chars])
+            flags.charset = o.chars;
+        else
+            flags.chars = o.chars;
+    }
+    if (o.color)
+        flags.color = o.color.includes(',') ? o.color.split(',') : o.color;
+    if (o.edges !== undefined) {
+        if (o.edges !== 'outline' && o.edges !== 'depth' && o.edges !== 'off')
+            fail('--edges is outline, depth or off');
+        flags.edges = o.edges === 'off' ? false : o.edges;
+    }
+    if (o.light)
+        flags.light = nums(o.light, 3, '--light');
+    if (o.shading) {
+        if (o.shading !== 'auto' && o.shading !== 'flat' && o.shading !== 'smooth')
+            fail('--shading is auto, flat or smooth');
+        flags.shading = o.shading;
+    }
+    flags.ambient = num(o.ambient, '--ambient');
+    flags.pitch = num(o.pitch, '--pitch');
+    flags.spin = num(o.spin, '--spin');
+    flags.zoom = num(o.zoom, '--zoom');
+    flags.distance = num(o.distance, '--distance');
+    flags.aspect = num(o.aspect, '--aspect');
+    const size = parseSize(o.size);
+    if (size)
+        [flags.width, flags.height] = size;
+    // a custom ramp from -c replaces the example's charset as well
+    const b = flags.chars !== undefined ? { ...base, charset: undefined } : base;
+    return mergeStyles(b, preset, flags);
+}
+/** what stdout can show, honoring NO_COLOR / FORCE_COLOR and --no-color */
+export function colorDepth(noColor) {
+    return noColor ? 'none' : detectColorDepth(process.stdout);
+}

package/dist/examples.d.ts

@@ -0,0 +1,13 @@
+import type { Mesh } from './mesh.ts';
+import type { StyleInput } from './style.ts';
+export interface Example {
+    name: string;
+    title: string;
+    description: string;
+    /** look that suits the scene; user options are merged on top */
+    style: StyleInput;
+    build: () => Generator<void, Mesh>;
+}
+export declare const EXAMPLES: Example[];
+export declare function findExample(name: string): Example | undefined;
+export declare function buildExample(e: Example): Mesh;