2.4 KiB
G-078 punk::ansi ANSI->HTML rendering api (developer-surfaced, documented)
Status: proposed
Scope: src/modules/punk/ansi-999999.0a1.0.tm (or a new punk::ansi::html module), src/scriptapps/tools/punkargs_punknative.tcl + scratch prototypes (ansi2html_core.tcl, ansicat_gallery.tcl) as reference implementations to be retired into consumers, src/scriptapps/tools/fontprep/ (asset + geometry contract), new testsuite under src/tests/modules/punk/ansi/
Goal: a documented public api converting ANSI/SGR text to html: a fragment converter (spans for a <pre>) plus a page assembler with -assets embed|link|none (punkdoc-mono data-uri / relative file / stack-only), -palette vga|campbell|vscode|<list> (16-colour table - classic art needs VGA where SGR 33 is brown), art mode (bold-as-bright for basic colours, no font-weight, solid-block background sealing, tight pitch + scaleY aspect correction per the settled recipe) and doc mode (text-oriented pitch), and a headless flatten entry for files/captures (ansicat semantics - cursor movement/wrap/SAUCE/cp437 - without repl/console dependencies).
Acceptance: renders the prototype corpus (src/testansi gallery samples incl. octants, textblock::periodic, punk::args::usage tables) with parity to the settled recipe; runs headless in a plain tclsh with declared package deps only (no punk::console load, no fcat/global-alias assumptions); covered by tests incl. SGR state-machine cases (reset/bold/dim/italic/underline/reverse, 16/256/truecolour, bold-as-bright) and an artifact pin of a small converted sample; the scriptapps prototypes become thin consumers of the api.
Context
Prototyped 2026-07-13/14 (scratch/argdoc2man-trial-2026-07-13). The settled empirical recipe and its rejected alternatives (larger row pitches, font line-metric normalization - wrong-coloured bleed bars) are recorded in src/scriptapps/tools/fontprep/README.md and the prototype comments; cell geometry contract: punkdoc-mono advance exactly 0.5859375em (integer 9px cells at font-size 15.36px), blocks paint the 1.3213em win cell, art aspect restored via transform:scaleY(1.3212890625) over a line-height:1.0 layout. This api is also the docs-screenshot enabler (ansicat/textblock output embedded in generated documentation) identified in the punk::args-as-doc-source-of-truth assessment. Related: G-079 (default-colour semantics), G-080 (deterministic cell-grid mode), G-081 (docs build pipeline consumer).