diff --git a/GOALS.md b/GOALS.md index 7c5ad0f4..c54c01a9 100644 --- a/GOALS.md +++ b/GOALS.md @@ -297,3 +297,19 @@ Detail: goals/G-076-tcl9-deadconsole-fix-adoption.md ### G-077 [proposed] punk executable -e one-liner support: make the tclsh-agent instinct work Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch), src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms), src/tests/shell/testsuites/punkexe/scriptexec.test Detail: goals/G-077-punkexe-dash-e-oneliner.md + +### G-078 [proposed] punk::ansi ANSI->HTML rendering api (developer-surfaced, documented) +Scope: src/modules/punk/ansi-999999.0a1.0.tm (or new punk::ansi::html module), src/scriptapps/tools prototypes as reference implementations, src/scriptapps/tools/fontprep/ (asset + cell-geometry contract), new testsuite under src/tests/modules/punk/ansi/ +Detail: goals/G-078-punkansi-tohtml-api.md + +### G-079 [proposed] default-colour semantics through renderspace/flattened output +Scope: src/modules/overtype-999999.0a1.0.tm (renderspace/renderline replay-code emission), punk::ansi flatten consumers (ansicat), ansi2html consumer mapping (G-078) +Detail: goals/G-079-renderspace-default-colour-semantics.md + +### G-080 [proposed] deterministic cell-grid html rendering mode (seamless block art) +Scope: the G-078 punk::ansi html api (additional rendering mode); scratch prototypes as baseline +Detail: goals/G-080-ansi2html-cellgrid-mode.md + +### G-081 [proposed] punk::args documentation build pipeline (dev doc.* integration) +Scope: src/modules/punk/mix/commandset/doc-999999.0a1.0.tm (doc.* generation subcommands), src/scriptapps/tools/punkargs_to_doctools.tcl + punkargs_punknative.tcl (productize), src/scriptapps/tools/fontprep/ (shared doc-set asset), src/doc tree conventions, src/tests coverage +Detail: goals/G-081-argdoc-build-pipeline.md diff --git a/goals/G-078-punkansi-tohtml-api.md b/goals/G-078-punkansi-tohtml-api.md new file mode 100644 index 00000000..335f50d4 --- /dev/null +++ b/goals/G-078-punkansi-tohtml-api.md @@ -0,0 +1,20 @@ +# 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 `
`) plus a page assembler with `-assets embed|link|none` (punkdoc-mono data-uri / relative file / stack-only), `-palette vga|campbell|vscode|` (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). diff --git a/goals/G-079-renderspace-default-colour-semantics.md b/goals/G-079-renderspace-default-colour-semantics.md new file mode 100644 index 00000000..b3ef76c9 --- /dev/null +++ b/goals/G-079-renderspace-default-colour-semantics.md @@ -0,0 +1,17 @@ +# G-079 default-colour semantics through renderspace/flattened output + +Status: proposed +Scope: src/modules/overtype-999999.0a1.0.tm (renderspace/renderline replay-code emission), punk::ansi flatten consumers (ansicat), ansi2html consumer mapping (G-078) +Goal: flattened/rendered ANSI output preserves "default foreground/background" as a semantic value (SGR 39/49 or absence) instead of baking in explicit colours (replay/overlay output currently emits literal `0;40` - black background - for cells whose background was never set). Consumers can then map defaults to their own backdrop: html pages theme-match any page background, terminal replays keep the user's colour scheme. +Acceptance: ansicat/usage flattened output for content that never sets a background contains no explicit SGR 40/black-bg codes for those cells; the punk-native html pages render example-helper top/bottom bars (e.g. grepstr @cmd -help examples) blending with a NON-black page background with no contrasting bars; existing terminal display output is visually unchanged (regression-checked against current renderings). + +## Context + +Found 2026-07-14 while reviewing the punk::ansi punknative doc page: example blocks +produced by the punk::ansi example helper show bars whose "background half" rendered +as black boxes contrasting with a grey page. Probe evidence: renderspace overlay +replay emits `replay_codes_overlay: ESC[0;40m`. Interim workaround (shipped in the +punknative generator): the `
` backdrop is hard black so baked-black blends - +this constrains doc page theming and leaves lighter antialiasing seams at half-block +edges against non-matching content. Proper fix is upstream in the renderer's +replay-code model, then a `-defaultbg`/`-defaultfg` mapping option in the G-078 api. diff --git a/goals/G-080-ansi2html-cellgrid-mode.md b/goals/G-080-ansi2html-cellgrid-mode.md new file mode 100644 index 00000000..438473bf --- /dev/null +++ b/goals/G-080-ansi2html-cellgrid-mode.md @@ -0,0 +1,18 @@ +# G-080 deterministic cell-grid html rendering mode (seamless block art) + +Status: proposed +Scope: the G-078 punk::ansi html api (additional rendering mode); scratch prototypes as baseline +Goal: an optional rendering mode that emulates the terminal cell grid explicitly - each styled run emitted as inline-block with exact integer-px cell width/height, inner line-height equal to the cell, overflow hidden, vertical-align top (newlines outside spans) - making row/column geometry fully deterministic instead of dependent on font metrics, inline-background box heights and sub-pixel glyph rasterization. Optionally decompose half-block cells (U+2580/2584/258C/2590 and quadrants) into sized background rectangles for complete seam-proofing. +Acceptance: the testansi gallery samples show no vertical or horizontal seams in chrome and firefox at 100%/125%/150% zoom (the residual shade/half-block seams accepted in the span-mode recipe are eliminated); cost (page size, loss of text selectability granularity if any) measured and documented; span mode remains the default with cell-grid selectable per block. + +## Context + +The 2026-07-14 seam investigation (scratch/argdoc2man-trial-2026-07-13/seam_compare.tcl) +settled a span-mode recipe (integer 9px advance, tight pitch + scaleY aspect, solid-block +background sealing, integer 17px doc pitch) that reduces but cannot eliminate seams: +shade (U+2591-2593) and half-block glyph edges still antialias against differing +neighbours at fractional device-pixel positions (display scaling), and inline background +box height is a font-metric browsers don't agree on (metric normalization was tried and +rejected - see fontprep/README.md). Cell-grid emulation removes every one of those +degrees of freedom at the cost of heavier markup. Only worth building if/when the +accepted residual seams stop passing review - the glance test passes today. diff --git a/goals/G-081-argdoc-build-pipeline.md b/goals/G-081-argdoc-build-pipeline.md new file mode 100644 index 00000000..7aa86d86 --- /dev/null +++ b/goals/G-081-argdoc-build-pipeline.md @@ -0,0 +1,18 @@ +# G-081 punk::args documentation build pipeline (dev doc.* integration) + +Status: proposed +Scope: src/modules/punk/mix/commandset/doc-999999.0a1.0.tm (doc.* commandset - new generation subcommands), src/scriptapps/tools/punkargs_to_doctools.tcl + punkargs_punknative.tcl (prototypes to productize), src/scriptapps/tools/fontprep/ (shared doc-set asset in link mode), src/doc tree conventions, src/tests coverage +Goal: 'dev doc.*' generates the external documentation set from punk::args definitions as the source of truth, per package, against the DEV modules (src/modules 999999 versions - not bootsupport snapshots): (a) doctools .man output (Tcl-standard synopsis conventions) validated via dev doc.validate/dtplite and feeding the existing kettle machinery; (b) punk-native html via the G-078 api with a shared punkdoc-mono.woff2 + css (assets link mode, one cached font per doc set) and (c) GFM markdown. Includes the productization items the prototypes deferred: per-form arg tables without repeated panels (prototype has a trim heuristic - production should render per-form tables directly from the spec), deeper-namespace/ensemble command pages (e.g. punk::ansi::ansistring - the prototypes' one-level namespace filter skips them), module/package-level info at page top once G-075 surfaces @package ids, large choice sets as structured lists in markdown, and doctools emitter gaps (@examples -> [example], @seealso/@doc -> [see_also]/[uri], choicelabels). +Acceptance: a doc.* subcommand generates all three formats for a nominated package list from dev modules in one run; doctools output validates clean (dtplite) and html pages carry the shared font/css by reference; deeper-namespace registered ids appear on the owning package's page (or their own); output tree location and vcs policy decided and documented (generated-vs-committed); at least punk::path + punk::ansi + one ensemble-rich package covered by a regression pin. + +## Context + +Follows the 2026-07-13 assessment (punk::args -> doctools expressibility) and trials: +punkargs_to_doctools.tcl (doctools, Tcl-standard by decision - punk s-style is out of +scope for that target) and punkargs_punknative.tcl (terminal-faithful html + markdown) +both work per-package against bootsupport modules, invoked manually. The doctools +comment blocks in source remain interim until this pipeline is validated, after which +worthwhile prose migrates into punk::args blocks (original long-term plan). dtplite +validation infrastructure (bin/dtplite.cmd + dev doc.validate) is in place. +Related: G-075 (@package ids), G-078 (html api), G-079 (default colours), G-014/G-068 +(argdoc/moduledoc workflows).