goals: G-078..G-081 - ansi->html api, default-colour semantics, cell-grid mode, argdoc build pipeline

Formalize the follow-on work identified during the punk::args documentation
trials and ansi->html prototyping (2026-07-13/14):

- G-078 punk::ansi ANSI->HTML rendering api: promote the prototype ansi2html
  converter + headless ansicat flatten entry into a documented punk::ansi
  api (palette option, art mode with bold-as-bright and block sealing,
  -assets embed|link|none using the vendored punkdoc-mono; docs-screenshot
  enabler)
- G-079 default-colour semantics: renderspace replay output bakes explicit
  SGR 40 for never-set backgrounds; preserve default fg/bg semantically so
  html can theme-match any page background (current workaround: black pre)
- G-080 deterministic cell-grid rendering mode: inline-block cell emulation
  to eliminate the residual sub-pixel seams the span-mode recipe accepts
- G-081 argdoc build pipeline: dev doc.* generation of doctools + punk-native
  html + markdown from punk::args definitions against dev modules, incl.
  per-form table rendering, deeper-namespace pages, @package surfacing
  (G-075) and shared doc-set font assets

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

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

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 `<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).

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 `<pre>` 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.

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.

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).