# G-056 punk::args display-time word wrapping for help content

Status: proposed
Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error table and string renderers, helpers), src/modules/textblock-999999.0a1.0.tm (only if cell/column-level wrap is the chosen mechanism), src/tests/modules/punk/args/testsuites/args/ (new wrapping characterization + existing rendering suites)
Goal: punk::args help display (@cmd -help, argument -help, choicelabels) word-wraps over-width lines to the effective display width at render time - ANSI/grapheme aware, splitting long logical lines but never joining existing ones, so deliberately structured content (hand-folded blocks, choice tables, art choicelabels, indented continuations) is preserved by construction - letting definitions store unfolded verbatim text (retiring the G-055 re-folding exception for new work) while usage output stays terminal-width friendly.
Acceptance: a definition whose -help/choicelabel contains a single long unfolded line renders fully within the effective display width in both the table and -return string renderers (no truncation, no overflow, wrapped continuations indented to match the field's existing paramindent alignment); wrap-point calculation is ANSI-aware (SGR sequences measure zero width; styling in effect carries across the wrap) and grapheme/double-width aware to the same standard as existing punk::ansi/textblock width handling; existing hand-folded and structured help renders byte-identical (full existing args rendering/usagemarking/deferredhelp suites pass unchanged - never-join semantics verified by characterization tests); effective width derives from the terminal when available with the current -maxwidth 80 table default as fallback, and an explicit width option overrides; the chosen mechanism (punk::args-side pre-wrap of field text vs textblock table column wrap support) and its rationale are recorded in the detail file; G-055's folding exception is marked lapsed for new work once this ships.

## Context

punk::args help rendering has no word wrapping: -help and choicelabel text renders
exactly as authored, so authors hand-fold lines short to stay terminal-friendly
(the convention throughout the codebase and the module documentation templates).
That convention forced a fidelity exception in the G-055 tclcore moduledoc
regeneration workflow: imported man-page prose must be manually re-folded rather
than stored verbatim. Renderer-side wrapping removes the need - definitions can
store unfolded verbatim text and the display adapts to the terminal.

## Approach

Core semantics: **split-only, never-join**. The renderer wraps logical lines that
exceed the effective width but never reflows or joins existing line breaks. This
preserves deliberately structured content (hand-folded paragraphs, embedded choice
tables, textblock-frame art choicelabels, indented continuation blocks) by
construction, with no per-field opt-in/opt-out annotation machinery - and makes
"existing content renders byte-identical" a directly testable invariant.

Width handling to the same standard as the rest of the punk display stack:
ANSI-aware (SGR sequences measure zero width; styling in effect at a wrap point
carries onto the continuation), grapheme-cluster and double-width aware
(punk::ansi / punk::char facilities). Wrapped continuations indent to the field's
existing alignment (the paramindent machinery from G-046 governs where
continuation lines sit today - wrapping must land continuations at the same
column, not at column 0).

Effective width: terminal width when detectable (punk::console), falling back to
the current table -maxwidth 80 default; an explicit width option overrides both.

### Mechanism alternatives (decide during the work, record here)

- **punk::args-side pre-wrap**: wrap field text in the arg_error/usage renderers
  before handing cells to textblock::table (and before the -return string
  renderer's line assembly). Smaller blast radius; wrap width must anticipate the
  table's computed column widths - a chicken-and-egg with column autosizing that
  may need a measure pass or fixed help-column budget.
- **textblock table column wrap**: a -wrap/-maxwidth-aware column feature in
  textblock::class::table cells. More general (benefits every table consumer),
  heavier; interacts with existing cell padding/ansibase handling and the table's
  width negotiation. If chosen, textblock's buildversion and tests are in scope.

## Notes

- Cross-link: [[G-055]] - its "re-folding to display width" exception to verbatim
  text lapses for new work once this ships (mark it there on achievement).
- The -return string renderer has its own continuation-alignment conventions
  (Description-label alignment added in G-046); wrapped continuations must respect
  those, not just the table path.
- Characterization first: pin current no-wrap rendering of an over-width line
  (overflow behaviour) before changing it, per the usual GAP-pin workflow.
- Archived-goal references in this file: G-046 achieved 2026-07-10 (goals/archive/G-046-punkargs-deferred-help-and-fixes.md).