test: run the config-settings render golden in the test runner

A byte-identity gate CI never runs will rot, and a rotted gate is worse
than no gate. Adds the render harness as Phase 4, in the same shape as the
vault suite: its own process, its own sandbox, no loaded config needed.

Kept to one self-contained block so it can be dropped or re-applied by
hand if the runner is restructured. The functional suite's 317/317 count
is untouched; the render cases report separately.

functions/__config_settings_draw.fish

@@ -38,20 +38,21 @@ function __config_settings_draw
     set -l cur_scope $argv[2]
     set -l vars      $argv[3..]
 
-    set -l c_ok    (set_color green)
-    set -l c_err   (set_color red)
     set -l c_dim (set_color brblack)
-    set -l c_sel   (set_color --bold magenta)
-    set -l c_hi    (set_color --bold white)
     set -l c_head (set_color --bold cyan)
     set -l c_reset (set_color normal)
 
     set -l labels Aliases Auto-exec Overrides Integrations Logging Greeting Master
 
-    # ── Width tier: 6-col buffer per side before stepping up ──────────────
+    # ── Width tier ────────────────────────────────────────────────────────
+    # The tier thresholds live in __config_settings_frame; this file only
+    # chooses which hand-authored description set goes with the width.
     # IW = inner width (chars between │ │); desc field = IW - 33.
     # All four layouts are exactly 16 lines tall — panel_h in caller stays 16.
-    set -l iw 50
+    # Descriptions are authored to fit their field exactly at every tier
+    # (43/43, 39/39, 35/35, 17/17), which is why the rows below pass `pad`
+    # and not `cut` -- see the NOTES in __config_settings_frame.
+    set -l iw (__config_settings_frame width)
     set -l descs \
         "cmd shadows" \
         startup \
@@ -61,8 +62,8 @@ function __config_settings_draw
         fish_greeting \
         "disable all"
 
-    if test "$COLUMNS" -ge 90
-        set iw 76
+    switch $iw
+        case 76
             set descs \
                 "shadows: ls→eza, cat→bat, cd→z, rm→trash" \
                 "Fisher bootstrap, themes, py-venv activate" \
@@ -71,8 +72,7 @@ function __config_settings_draw
                 "scrollback capture & paru/yay AUR wrappers" \
                 "fish_greeting & first-run welcome banner" \
                 "master off-switch: overrides all categories"
-    else if test "$COLUMNS" -ge 86
-        set iw 72
+        case 72
             set descs \
                 "ls→eza, cat→bat, cd→zoxide, rm→trash" \
                 "Fisher bootstrap, themes, py-venv auto" \
@@ -81,8 +81,7 @@ function __config_settings_draw
                 "scrollback capture & paru/yay wrappers" \
                 "fish_greeting: first-run welcome banner" \
                 "master off-switch for all categories"
-    else if test "$COLUMNS" -ge 82
-        set iw 68
+        case 68
             set descs \
                 "ls→eza, cat→bat, cd→z, rm→trash" \
                 "Fisher, themes, py-venv activate" \
@@ -101,8 +100,7 @@ function __config_settings_draw
 
     # ── Top border ────────────────────────────────────────────────────────
     # ┌─ Opinionated Settings (iw-23)×─ ┐  total = iw+2
-    printf '%s┌─%s Opinionated Settings %s┐\n' \
-        $p $c_head $c_reset(string repeat -n (math $iw - 23) '─')
+    __config_settings_frame title $iw $p "$c_head Opinionated Settings $c_reset"
 
     # ── Page-tab header ───────────────────────────────────────────────────
     set -l active_idx 0
@@ -115,36 +113,18 @@ function __config_settings_draw
     printf '%s│%s│\n' $p $HBR
 
     # ── Category rows 0–5 ─────────────────────────────────────────────────
+    # Label field 12 wide; the description field falls out of it inside the
+    # frame (field_w = iw - 21 - label_w = iw - 33). `pad`, not `cut`: these
+    # descriptions are authored per tier to fit exactly, so truncating them
+    # would be a silent no-op that discards that property.
     for i in (seq 0 5)
         set -l idx (math $i + 1)
-        set -l var   $vars[$idx]
-        set -l label $labels[$idx]
-        set -l desc  $descs[$idx]
-
-        set -l val (__config_settings_get_val $var $cur_scope)
-
-        # Badge: 7 visible chars, coloured
-        set -l badge
-        switch $val
-            case on
-                set badge "$c_ok""     ON$c_reset"
-            case off
-                set badge "$c_err""OFF    $c_reset"
-            case '*'
-                set badge "$c_dim""DEFAULT$c_reset"
-        end
-
-        # Cursor: 2 visible chars
-        set -l curs "  "
-        if test $i -eq $cur_row
-            set curs "$c_sel▶$c_reset "
-        end
-
-        # Label padded to 12, desc padded to (iw-33), right margin 3
-        set -l lpad (string pad -r -w 12 -- $label)
-        set -l dpad (string pad -r -w (math $iw - 33) -- $desc)
-
-        printf '%s│  %s%s [ %s ]  %s   │\n' $p $curs $lpad $badge $dpad
+        set -l val (__config_settings_get_val $vars[$idx] $cur_scope)
+        __config_settings_frame row $iw $p \
+            (__config_settings_frame cursor $i $cur_row) \
+            $labels[$idx] 12 \
+            (__config_settings_frame badge $val) \
+            $descs[$idx] pad
     end
 
     # ── Separator before Master ───────────────────────────────────────────
@@ -152,24 +132,11 @@ function __config_settings_draw
 
     # ── Master row (index 6) ──────────────────────────────────────────────
     set -l val (__config_settings_get_val $vars[7] $cur_scope)
-    set -l badge
-    switch $val
-        case on
-            set badge "$c_ok""     ON$c_reset"
-        case off
-            set badge "$c_err""OFF    $c_reset"
-        case '*'
-            set badge "$c_dim""DEFAULT$c_reset"
-    end
-    set -l curs "  "
-    if test $cur_row -eq 6
-        set curs "$c_sel▶$c_reset "
-    end
-    printf '%s│  %s%s [ %s ]  %s   │\n' \
-        $p $curs \
-        (string pad -r -w 12 -- Master) \
-        $badge \
-        (string pad -r -w (math $iw - 33) -- $descs[7])
+    __config_settings_frame row $iw $p \
+        (__config_settings_frame cursor 6 $cur_row) \
+        Master 12 \
+        (__config_settings_frame badge $val) \
+        $descs[7] pad
 
     # ── Filler (Dots Path moved to the Paths page) ────────────────────────
     printf '%s│  %s%s│\n' $p \

functions/__config_settings_draw_subcat.fish

@@ -41,10 +41,7 @@ function __config_settings_draw_subcat
     set -l cur_scope    $argv[2]
     set -l category_var $argv[3]
 
-    set -l c_ok    (set_color green)
-    set -l c_err   (set_color red)
     set -l c_dim (set_color brblack)
-    set -l c_sel   (set_color --bold magenta)
     set -l c_head (set_color --bold cyan)
     set -l c_reset (set_color normal)
 
@@ -52,23 +49,14 @@ function __config_settings_draw_subcat
     set -l n (count $rows)
 
     # ── Width tier: matches __config_settings_draw's 6-col-per-side steps ──
-    set -l iw 50
-    if test "$COLUMNS" -ge 90
-        set iw 76
-    else if test "$COLUMNS" -ge 86
-        set iw 72
-    else if test "$COLUMNS" -ge 82
-        set iw 68
-    end
+    set -l iw (__config_settings_frame width)
     set -l HBR (string repeat -n $iw '─')
     set -l p (string repeat -n (math --scale=0 "max(0, ($COLUMNS - ($iw + 2)) / 2)") ' ')
 
     # Label field is 13 wide (one wider than __config_settings_draw's 12) --
-    # the longest real sub-category label ("Notifications") is 13 chars.
-    # Description field absorbs the difference so every row still totals
-    # iw+2, matching the surrounding box lines exactly.
-    set -l label_w 13
-    set -l desc_w (math $iw - 34)
+    # the longest real sub-category label ("Notifications") is 13 chars. The
+    # description field absorbs the difference inside the frame
+    # (field_w = iw - 21 - label_w = iw - 34), so every row still totals iw+2.
 
     set -l cat_label (string replace -r '^__fish_config_op_' '' -- $category_var)
     # Scope indicator: toggling a row on this page writes -U (Universal,
@@ -77,32 +65,18 @@ function __config_settings_draw_subcat
     set -l scope_label Universal
     test "$cur_scope" = session; and set scope_label Session
     # Title layout is "┌─ Sub-categories: <label> (<scope>) ───┐"; the
-    # dash count must absorb every visible char added around cat_label so
-    # the line still totals iw+2, matching the surrounding box exactly --
-    # see the DESCRIPTION doc comment above for why this is hand-verified,
-    # not eyeballed.
-    set -l title_dashes (math $iw - (string length -- $cat_label) - (string length -- $scope_label) - 22)
-    printf '%s┌─%s Sub-categories: %s (%s)%s %s┐\n' \
-        $p $c_head "$cat_label" $scope_label "$c_reset" (string repeat -n (math "max(0, $title_dashes)") '─')
+    # dash count absorbs every visible char added around cat_label so the
+    # line still totals iw+2, matching the surrounding box exactly. The
+    # frame derives it from the segment's visible width, so it no longer
+    # has to be hand-verified here.
+    __config_settings_frame title $iw $p \
+        "$c_head Sub-categories: $cat_label ($scope_label)$c_reset "
 
     printf '%s│%s│\n' $p $HBR
 
     # Row 0: the category's own toggle, still meaningful as the cascade
     # default any DEFAULT-valued sub-category below falls back to.
     set -l cat_val (__config_settings_get_val $category_var $cur_scope)
-    set -l cat_badge
-    switch $cat_val
-        case on
-            set cat_badge "$c_ok""     ON$c_reset"
-        case off
-            set cat_badge "$c_err""OFF    $c_reset"
-        case '*'
-            set cat_badge "$c_dim""DEFAULT$c_reset"
-    end
-    set -l cat_curs "  "
-    if test $cur_row -eq 0
-        set cat_curs "$c_sel▶$c_reset "
-    end
     set -l cat_desc "cascade default"
     if test $iw -ge 68
         set cat_desc "default for all sub-cats below"
@@ -110,38 +84,35 @@ function __config_settings_draw_subcat
     if test $iw -ge 72
         set cat_desc "default for all sub-categories below"
     end
-    printf '%s│  %s%s [ %s ]  %s   │\n' $p $cat_curs \
-        (string pad -r -w $label_w -- "(category)") $cat_badge \
-        (string pad -r -w $desc_w -- (string sub -l $desc_w -- $cat_desc))
+    # `cut` for the same reason as the sub-category rows below. It also
+    # truncates the label, which the old code did not -- provably inert here,
+    # since "(category)" is a 10-char literal against a 13-wide field.
+    __config_settings_frame row $iw $p \
+        (__config_settings_frame cursor 0 $cur_row) \
+        "(category)" 13 \
+        (__config_settings_frame badge $cat_val) \
+        $cat_desc cut
 
     printf '%s│    %s  │\n' $p (string repeat -n (math $iw - 6) '─')
 
     for i in (seq 1 $n)
         set -l fields (string split -- \t $rows[$i])
-        set -l slug  $fields[1]
         set -l label $fields[2]
         set -l desc $fields[3]
-        set -l subcat_var "$category_var"_(string replace -a -- '-' '_' $slug)
-
+        set -l subcat_var "$category_var"_(string replace -a -- '-' '_' $fields[1])
         set -l val (__config_settings_get_val $subcat_var $cur_scope)
-        set -l badge
-        switch $val
-            case on
-                set badge "$c_ok""     ON$c_reset"
-            case off
-                set badge "$c_err""OFF    $c_reset"
-            case '*'
-                set badge "$c_dim""DEFAULT$c_reset"
-        end
-
-        set -l curs "  "
-        if test $i -eq $cur_row
-            set curs "$c_sel▶$c_reset "
-        end
-
-        set -l lpad (string pad -r -w $label_w -- (string sub -l $label_w -- $label))
-        set -l dpad (string pad -r -w $desc_w -- (string sub -l $desc_w -- $desc))
-        printf '%s│  %s%s [ %s ]  %s   │\n' $p $curs $lpad $badge $dpad
+        # `cut`: these labels and descriptions are static data from
+        # __config_settings_subcats, not authored per width tier the way
+        # __config_settings_draw's are, and several run well past the
+        # narrower tiers' fields. `string pad` only ever grows a string, so
+        # they must be truncated before padding or the box stops being
+        # rectangular. This is the divergence the DESCRIPTION block above
+        # documents -- do not "simplify" it to `pad`.
+        __config_settings_frame row $iw $p \
+            (__config_settings_frame cursor $i $cur_row) \
+            $label 13 \
+            (__config_settings_frame badge $val) \
+            $desc cut
     end
 
     printf '%s│%s│\n' $p $HBR

functions/__config_settings_draw_value.fish

@@ -34,9 +34,7 @@ function __config_settings_draw_value
     set -l edit_buf  $argv[4]
 
     set -l c_ok (set_color green)
-    set -l c_err   (set_color red)
     set -l c_dim (set_color brblack)
-    set -l c_sel   (set_color --bold magenta)
     set -l c_head (set_color --bold cyan)
     set -l c_reset (set_color normal)
 
@@ -65,21 +63,12 @@ function __config_settings_draw_value
     set -l nrows (count $vars)
 
     # ── Width tier (same thresholds as the toggle page) ───────────────────
-    set -l iw 50
-    if test "$COLUMNS" -ge 90
-        set iw 76
-    else if test "$COLUMNS" -ge 86
-        set iw 72
-    else if test "$COLUMNS" -ge 82
-        set iw 68
-    end
+    set -l iw (__config_settings_frame width)
     set -l HBR (string repeat -n $iw '─')
     set -l p (string repeat -n (math --scale=0 "max(0, ($COLUMNS - ($iw + 2)) / 2)") ' ')
 
     # ── Line 1: top border with title ─────────────────────────────────────
-    set -l title_dashes (math $iw - (string length -- $title) - 3)
-    printf '%s┌─%s %s %s┐\n' \
-        $p $c_head "$title$c_reset" (string repeat -n $title_dashes '─')
+    __config_settings_frame title $iw $p "$c_head $title$c_reset "
 
     # ── Line 2: page-tab header ───────────────────────────────────────────
     printf '%s│%s│\n' $p (__config_settings_pagetab $active_idx $iw)
@@ -100,15 +89,9 @@ function __config_settings_draw_value
         set -l field
         if test $type = bool
             # Booleans store true/false (sponge convention); unset = DEFAULT.
-            set -l val (__config_settings_get_raw $var)
-            switch $val
-                case true
-                    set badge "$c_ok""     ON$c_reset"
-                case false
-                    set badge "$c_err""OFF    $c_reset"
-                case '*'
-                    set badge "$c_dim""DEFAULT$c_reset"
-            end
+            # The frame is told this page's vocabulary rather than merging
+            # true/on: a hand-set "on" here must keep rendering DEFAULT.
+            set badge (__config_settings_frame badge (__config_settings_get_raw $var) true false)
             set field "default: $hint"
         else
             set -l raw (__config_settings_get_raw $var)
@@ -144,23 +127,18 @@ function __config_settings_draw_value
             set field "$shown"(set_color --reverse)" "(set_color normal)
         end
 
-        set -l curs "  "
-        if test $i -eq $cur_row
-            set curs "$c_sel▶$c_reset "
-        end
-
-        set -l fw (math $iw - 33)
-        set -l lpad (string pad -r -w 12 -- $label)
-        # The edit field is already length-constrained and contains a reverse
-        # caret; running it through `string shorten` miscounts the escapes, so
-        # pad it directly. Non-edit fields still shorten to add an ellipsis.
-        set -l fpad
+        # `shorten` ellipsises the value: unlike the toggle page's per-tier
+        # descriptions, these fields hold arbitrary user values. The edit row
+        # is the exception -- its field is already length-constrained above
+        # and carries a reverse-video caret whose escapes `string shorten`
+        # miscounts, so it pads directly.
+        set -l fit shorten
         if test "$edit_mode" = edit -a $i -eq $cur_row
-            set fpad (string pad -r -w $fw -- "$field")
-        else
-            set fpad (string pad -r -w $fw -- (string shorten -m $fw -- "$field"))
+            set fit pad
         end
-        printf '%s│  %s%s [ %s ]  %s   │\n' $p $curs $lpad $badge $fpad
+        __config_settings_frame row $iw $p \
+            (__config_settings_frame cursor $i $cur_row) \
+            $label 12 $badge $field $fit
     end
 
     # ── Pad blank rows so chrome(6) + nrows + blanks = 16 ─────────────────

functions/__config_settings_frame.fish

@@ -0,0 +1,155 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   __config_settings_frame width
+#   __config_settings_frame title  <iw> <p> <segment>
+#   __config_settings_frame badge  <value> [<on_word> <off_word>]
+#   __config_settings_frame cursor <row> <cur_row>
+#   __config_settings_frame row    <iw> <p> <curs> <label> <label_w> <badge> <field> <fit>
+#
+# DESCRIPTION
+#   The pieces of the config-settings panel that every page draws identically:
+#   the width tier, the title border, the ON/OFF/DEFAULT badge, the cursor cell
+#   and one table row. __config_settings_draw, __config_settings_draw_subcat
+#   and __config_settings_draw_value each keep their own sequence of lines and
+#   their own per-tier text; only these shared computations live here.
+#
+#   Deliberately owns no page height. Every verb prints exactly one line or one
+#   fragment, so how tall a page is remains a property of its caller's line
+#   sequence: __config_settings_draw and __config_settings_draw_value are a
+#   fixed 16 lines, __config_settings_draw_subcat is 7 + <sub-category count>,
+#   and config-settings.fish's wrap-aware erase (\e[<N>A\e[J, sized from
+#   panel_h) depends on that difference surviving exactly as it is.
+#
+#   Row geometry. A row is
+#     │ + 2 spaces + cursor(2) + label(label_w) + " [ " + badge(7) + " ]  "
+#       + field(field_w) + 3 spaces + │
+#   which totals 23 + label_w + field_w and must equal iw + 2. So
+#     field_w = iw - 21 - label_w
+#   and that single sum reproduces both hand-maintained constants: label_w 12
+#   gives iw-33 (the toggle and value pages), label_w 13 gives iw-34 (the
+#   sub-category page, whose description field absorbs its wider label).
+#
+#   Title geometry. "┌─" + segment + dashes + "┐" totals iw + 2, so
+#     dashes = iw - visible(segment) - 1
+#   The segment arrives already coloured because the three pages place their
+#   set_color reset at different byte offsets around the same visible text
+#   (__config_settings_draw resets after the trailing space, the other two
+#   before it). That difference is invisible on screen and visible to cmp, so
+#   each page keeps its own bytes while sharing the arithmetic; --visible
+#   discounts the escapes.
+#
+# ARGUMENTS
+#   width   No arguments. Prints the inner width for the current $COLUMNS:
+#           >= 90 -> 76, >= 86 -> 72, >= 82 -> 68, otherwise 50.
+#   title   iw, the centering prefix, and the pre-coloured title segment.
+#   badge   The stored value, then optionally the words this page uses for true
+#           and false (default on/off; the value pages store true/false).
+#           Anything else renders DEFAULT.
+#   cursor  This row's index and the highlighted row's index.
+#   row     iw, centering prefix, cursor cell, label, label field width,
+#           rendered badge, field text, and the fit policy:
+#             pad      pad label and field, never shrink either
+#             cut      truncate both to their field width, then pad
+#             shorten  pad the label, ellipsise the field with string shorten
+#
+# EXIT STATUS
+#   0  Verb recognised
+#   1  Unknown verb
+#
+# RETURNS
+#   The requested panel line or fragment, printed to stdout
+#
+# NOTES
+#   `string pad` only ever grows a string, never shrinks it. That is the whole
+#   reason `cut` and `shorten` exist: a caller whose text can exceed its field
+#   must shrink it first, or the box stops being rectangular.
+#
+#   `pad` is not "the default when you don't care". __config_settings_draw's
+#   descriptions are authored per width tier to fit their field exactly -- at
+#   every tier the longest is precisely the field width -- so applying `cut`
+#   there would be a byte-for-byte no-op that silently discards that property
+#   and passes the render golden. Which policy a page uses is a real decision,
+#   named at each call site. See tests/config-settings-render.fish.
+#
+# EXAMPLE
+#   set -l iw (__config_settings_frame width)
+#   __config_settings_frame row $iw $p (__config_settings_frame cursor 0 0) \
+#       Aliases 12 (__config_settings_frame badge on) "cmd shadows" pad
+function __config_settings_frame
+    switch $argv[1]
+        # ── Width tier: 6-col buffer per side before stepping up ──────────
+        case width
+            if test "$COLUMNS" -ge 90
+                echo 76
+            else if test "$COLUMNS" -ge 86
+                echo 72
+            else if test "$COLUMNS" -ge 82
+                echo 68
+            else
+                echo 50
+            end
+
+            # ── Title border: ┌─<segment><dashes>┐ ────────────────────────────
+        case title
+            set -l iw $argv[2]
+            set -l vis (string length --visible -- "$argv[4]")
+            set -l dashes (math "max(0, $iw - $vis - 1)")
+            printf '%s┌─%s%s┐\n' $argv[3] "$argv[4]" (string repeat -n $dashes '─')
+
+            # ── Badge: 7 visible columns, coloured ────────────────────────────
+            # The truthy/falsy words are arguments rather than one merged
+            # vocabulary: merging would make a hand-set "on" in a true/false
+            # variable render as ON where it renders DEFAULT today.
+        case badge
+            set -l on_word on
+            set -l off_word off
+            if test (count $argv) -ge 4
+                set on_word $argv[3]
+                set off_word $argv[4]
+            end
+            switch "$argv[2]"
+                case $on_word
+                    printf '%s     ON%s' (set_color green) (set_color normal)
+                case $off_word
+                    printf '%sOFF    %s' (set_color red) (set_color normal)
+                case '*'
+                    printf '%sDEFAULT%s' (set_color brblack) (set_color normal)
+            end
+
+            # ── Cursor cell: 2 visible columns ────────────────────────────────
+        case cursor
+            if test $argv[2] -eq $argv[3]
+                printf '%s▶%s ' (set_color --bold magenta) (set_color normal)
+            else
+                printf '  '
+            end
+
+            # ── One table row ─────────────────────────────────────────────────
+        case row
+            set -l iw $argv[2]
+            set -l p $argv[3]
+            set -l curs $argv[4]
+            set -l label "$argv[5]"
+            set -l label_w $argv[6]
+            set -l badge $argv[7]
+            set -l field "$argv[8]"
+            set -l fit $argv[9]
+            set -l field_w (math $iw - 21 - $label_w)
+            switch $fit
+                case cut
+                    set label (string sub -l $label_w -- "$label")
+                    set field (string sub -l $field_w -- "$field")
+                case shorten
+                    set field (string shorten -m $field_w -- "$field")
+            end
+            printf '%s│  %s%s [ %s ]  %s   │\n' $p $curs \
+                (string pad -r -w $label_w -- "$label") $badge \
+                (string pad -r -w $field_w -- "$field")
+
+        case '*'
+            echo "__config_settings_frame: unknown verb '$argv[1]'" >&2
+            return 1
+    end
+end

tests/config-settings-render.fish

@@ -0,0 +1,279 @@
+#!/usr/bin/env fish
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Golden-output harness for the config-settings TUI renderer.
+#
+#   fish tests/config-settings-render.fish             compare against the golden
+#   fish tests/config-settings-render.fish --update    rewrite the golden
+#
+# __config_settings_draw, __config_settings_draw_subcat and
+# __config_settings_draw_value are hand-tuned layout code: field widths, dash
+# counts and pad targets are arithmetic on the width tier, verified by eye once
+# and never since. Any refactor of them has to be byte-identical, so this
+# renders every page at every width tier, in both scopes, with the cursor on
+# every row, and byte-compares the result against a committed baseline.
+#
+# The golden holds RAW output: the set_color escapes and box drawing exactly as
+# the draw functions emit them, plus the \e[<N>A\e[J erase config-settings.fish
+# would emit for that panel. Nothing is normalized, folded or pretty-printed --
+# the gate is cmp(1) over the bytes, and a one-space change anywhere fails it.
+# `diff` is only used to *display* a failure, through cat -v.
+#
+# Everything runs inside a throwaway HOME/XDG_CONFIG_HOME sandbox. The fixtures
+# have to be real universal variables (the Universal page reads universal scope
+# through `set --show`), and this repo doubles as a live ~/.config/fish whose
+# fish_variables must never be touched by a test run. `fish --no-config` is not
+# an option here: under -N, `set -U` silently degrades to global scope, which
+# would render the Universal page as all-DEFAULT and prove nothing.
+#
+# Every external utility below is called through `command`. The outer pass runs
+# under the user's real config, which shadows rm (-> trash), cat (-> bat) and
+# mkdir, and aliases cp to `cp -i` -- a bare `cp` over an existing golden would
+# sit waiting for a confirmation that never comes.
+
+set -l self (command realpath (status filename))
+set -l repo (command realpath (command dirname $self)/..)
+set -l golden $repo/tests/golden/config-settings-render.txt
+
+# ╭──────────────────────────────────────────────────────────────────────────╮
+# │ Outer pass: sandbox, run the render, compare or update                   │
+# ╰──────────────────────────────────────────────────────────────────────────╯
+if not set -q CS_RENDER_OUT
+    set -l sandbox (command mktemp -d)
+    command mkdir -p $sandbox/home $sandbox/xdg/fish
+    set -l out (command mktemp)
+    set -l errf (command mktemp)
+
+    # TERM is pinned so set_color emits a fixed sequence set regardless of the
+    # terminal this runs from; COLUMNS is set per case inside the render pass.
+    command env -i \
+        HOME=$sandbox/home \
+        XDG_CONFIG_HOME=$sandbox/xdg \
+        PATH="$PATH" \
+        TERM=xterm-256color \
+        CS_RENDER_OUT=$out \
+        fish $self >/dev/null 2>$errf
+    set -l render_status $status
+    command rm -rf $sandbox
+
+    if test $render_status -ne 0
+        echo "  FAIL  render pass exited $render_status"
+        command cat $errf >&2
+        command rm -f $out $errf
+        exit 1
+    end
+
+    set -l cases (command grep -c '^### ' $out)
+    if contains -- --update $argv
+        command mkdir -p (command dirname $golden)
+        command cp $out $golden
+        echo "golden updated: $cases cases, "(command wc -l <$golden | string trim)" lines, "(command wc -c <$golden | string trim)" bytes"
+        command rm -f $out $errf
+        exit 0
+    end
+
+    if not test -f $golden
+        echo "  FAIL  no golden at $golden -- run with --update to create it"
+        command rm -f $out $errf
+        exit 1
+    end
+
+    if command cmp -s $out $golden
+        echo "$cases/$cases config-settings render cases byte-identical"
+        command rm -f $out $errf
+        exit 0
+    end
+
+    echo "  FAIL  rendering differs from $golden"
+    # cat -v only to make the escapes readable in the report; the gate above is
+    # a raw byte compare, never this.
+    command diff (command cat -v $golden | psub) (command cat -v $out | psub) | command head -40
+    command rm -f $out $errf
+    exit 1
+end
+
+# ╭──────────────────────────────────────────────────────────────────────────╮
+# │ Render pass (inside the sandbox)                                         │
+# ╰──────────────────────────────────────────────────────────────────────────╯
+# Sourced, not autoloaded: XDG_CONFIG_HOME points at the empty sandbox. Only
+# the draw path is ever called -- __config_settings_apply and
+# __config_settings_set_value are defined here and never invoked.
+for f in $repo/functions/__config_settings_*.fish
+    source $f
+end
+
+set -l toggle_vars \
+    __fish_config_op_aliases \
+    __fish_config_op_autoexec \
+    __fish_config_op_overrides \
+    __fish_config_op_integrations \
+    __fish_config_op_logging \
+    __fish_config_op_greeting \
+    __fish_config_opinionated
+
+set -l categories $toggle_vars[1..6]
+
+# ── Fixtures ──────────────────────────────────────────────────────────────
+# Chosen so every badge branch is live somewhere in the golden: an explicit
+# truthy (ON), an explicit falsy (OFF), and an unset variable (DEFAULT). The
+# session values deliberately differ from the universal ones so the two pages
+# cannot render identically by accident.
+set -U __fish_config_op_aliases on
+set -U __fish_config_op_autoexec off
+set -U __fish_config_op_integrations on
+set -U __fish_config_op_logging off
+set -U __fish_config_opinionated off
+# __fish_config_op_overrides, __fish_config_op_greeting: unset -> DEFAULT
+
+set -g __fish_config_op_aliases off
+set -g __fish_config_op_overrides on
+set -g __fish_config_op_greeting off
+
+# Sub-category fixtures. "Notifications" is the 13-char label the subcat page's
+# label field was widened for; multiplexer-capture exercises the slug's '-'->'_'
+# rewrite into a variable name.
+set -U __fish_config_op_aliases_filesystem on
+set -U __fish_config_op_aliases_search off
+set -U __fish_config_op_integrations_notifications on
+set -U __fish_config_op_logging_multiplexer_capture off
+set -g __fish_config_op_aliases_search on
+
+# Value-page fixtures: one per type badge (INT / LIST / PATH) plus unset rows
+# for DEFAULT, plus a value long enough to force `string shorten`'s ellipsis at
+# every tier.
+set -U sponge_delay 5
+set -U sponge_purge_only_on_exit true
+set -U sponge_allow_previously_successful false
+set -U __fish_sponge_extra_sensitive KOPIA_PASSWORD MY_CORP_AUTH
+# sponge_successful_exit_codes: unset -> DEFAULT
+set -U __fish_scrollback_history_dir /home/tester/very/long/scrollback/history/directory
+set -U __fish_user_dots_path /home/tester/.config/.user-dots/fish
+set -U __fish_user_dots_symlink false
+# __fish_scrollback_history_max_files: unset -> DEFAULT
+
+# ── Case emitter ──────────────────────────────────────────────────────────
+# panel_h is passed in by the caller, mirroring __cs_dispatch_draw in
+# config-settings.fish: the category list and both value pages are a fixed 16
+# lines, a sub-category page is 7 + <sub-category count>. The golden records
+# the declared height, the measured line count, and the erase sequence derived
+# from the declared height -- so flattening the fixed/dynamic divergence, or
+# changing a page's height at all, breaks the compare three ways.
+function _cs_render_case --argument-names label panel_h
+    set -l cmd $argv[3..]
+    set -l t (command mktemp)
+    $cmd >$t
+    set -l lines (command wc -l <$t | string trim)
+
+    # Wrap-aware erase, byte-for-byte what config-settings.fish emits for a
+    # panel of this height at this width in the steady state (last_cols ==
+    # COLUMNS). 78 is the widest box (IW=76 + 2 borders).
+    set -l pml (math --scale=0 "($COLUMNS + 78) / 2")
+    set -l eh (math --scale=0 "$panel_h * max(1, ceil($pml / $COLUMNS))")
+
+    printf '### %s COLUMNS=%d PANEL_H=%d LINES=%d ERASE=' $label $COLUMNS $panel_h $lines
+    printf '\e[%dA\e[J' $eh
+    printf '\n'
+    command cat $t
+    command rm -f $t
+end
+
+# ── Frame-verb fragments ──────────────────────────────────────────────────
+# The shared computations pinned directly, not only through the pages that use
+# them. <END> marks the end of each fragment so trailing padding -- which is
+# the entire point of a 7-column badge or a 2-column cursor cell -- shows up in
+# a diff instead of being invisible whitespace.
+function _cs_frame_case --argument-names label
+    printf '### frame %s\n' $label
+    $argv[2..]
+    printf '<END>\n'
+end
+
+# ── Cases ─────────────────────────────────────────────────────────────────
+# 100 -> IW 76, 88 -> IW 72, 84 -> IW 68, 70 -> IW 50: one COLUMNS value per
+# width tier, each a few columns above its threshold.
+begin
+    for cols in 100 88 84 70
+        set -g COLUMNS $cols
+
+        for scope in universal session
+            for row in (seq 0 6)
+                _cs_render_case "toggle scope=$scope row=$row" 16 \
+                    __config_settings_draw $row $scope $toggle_vars
+            end
+        end
+
+        for category in $categories
+            set -l n (count (__config_settings_subcats $category))
+            for scope in universal session
+                for row in (seq 0 $n)
+                    _cs_render_case "subcat cat=$category scope=$scope row=$row" (math 7 + $n) \
+                        __config_settings_draw_subcat $row $scope $category
+                end
+            end
+        end
+
+        for row in (seq 0 4)
+            _cs_render_case "value page=sponge row=$row" 16 \
+                __config_settings_draw_value $row sponge
+        end
+        for row in (seq 0 3)
+            _cs_render_case "value page=paths row=$row" 16 \
+                __config_settings_draw_value $row paths
+        end
+
+        # Inline editor: only reachable on non-bool rows. Short buffer, a
+        # buffer long enough to tail-anchor against the caret, and an empty one.
+        _cs_render_case "edit page=sponge row=0 buf=short" 16 \
+            __config_settings_draw_value 0 sponge edit 12
+        _cs_render_case "edit page=sponge row=4 buf=long" 16 \
+            __config_settings_draw_value 4 sponge edit "KOPIA_PASSWORD MY_CORP_AUTH ANOTHER_SECRET_NAME"
+        _cs_render_case "edit page=paths row=0 buf=long" 16 \
+            __config_settings_draw_value 0 paths edit /home/tester/very/long/scrollback/history/directory
+        _cs_render_case "edit page=paths row=2 buf=empty" 16 \
+            __config_settings_draw_value 2 paths edit ""
+    end
+
+    # Emitted last on purpose: everything above is page output, so the page
+    # section's byte offsets never move when this section grows.
+    for cols in 100 88 84 70
+        set -g COLUMNS $cols
+        _cs_frame_case "width cols=$cols" __config_settings_frame width
+    end
+    set -g COLUMNS 100
+
+    set -l head (set_color --bold cyan)
+    set -l rst (set_color normal)
+    set -l p_test (string repeat -n 11 ' ')
+
+    for v in on off DEFAULT ''
+        _cs_frame_case "badge onoff val=$v" __config_settings_frame badge $v
+    end
+    for v in true false DEFAULT
+        _cs_frame_case "badge boolean val=$v" __config_settings_frame badge $v true false
+    end
+
+    _cs_frame_case "cursor hit" __config_settings_frame cursor 3 3
+    _cs_frame_case "cursor miss" __config_settings_frame cursor 3 4
+
+    _cs_frame_case "title toggle-page" __config_settings_frame title 76 $p_test \
+        "$head Opinionated Settings $rst"
+    _cs_frame_case "title subcat-page" __config_settings_frame title 76 $p_test \
+        "$head Sub-categories: aliases (Universal)$rst "
+    _cs_frame_case "title value-page" __config_settings_frame title 76 $p_test \
+        "$head Sponge Settings$rst "
+
+    set -l badge_on (__config_settings_frame badge on)
+    _cs_frame_case "row pad lw=12" __config_settings_frame row 76 $p_test \
+        (__config_settings_frame cursor 0 0) Aliases 12 $badge_on "cmd shadows" pad
+    _cs_frame_case "row cut lw=13" __config_settings_frame row 76 $p_test \
+        (__config_settings_frame cursor 0 1) Notifications 13 $badge_on "done, WakaTime hook" cut
+    _cs_frame_case "row cut lw=13 overlong" __config_settings_frame row 50 $p_test \
+        (__config_settings_frame cursor 0 0) Notifications 13 $badge_on \
+        "ls, cat, cd, du, mkdir, rm, mv, zoxide" cut
+    _cs_frame_case "row shorten lw=12" __config_settings_frame row 76 $p_test \
+        (__config_settings_frame cursor 0 0) "Log dir" 12 $badge_on \
+        /home/tester/very/long/scrollback/history/directory shorten
+    _cs_frame_case "row shorten lw=12 empty" __config_settings_frame row 50 $p_test \
+        (__config_settings_frame cursor 1 0) "Log max" 12 $badge_on "" shorten
+end >$CS_RENDER_OUT

tests/run-tests.fish

@@ -100,4 +100,15 @@ if test $status -ne 0
     set overall_failed 1
 end
 
+# ---- Phase 4: config-settings render golden ------------------------------
+# Byte-identity gate for the TUI's three draw functions. Runs as its own
+# process: like the vault suite it builds its own throwaway
+# HOME/XDG_CONFIG_HOME sandbox and needs no loaded config.
+echo ""
+echo "== config-settings render golden =="
+fish $repo_root/tests/config-settings-render.fish
+if test $status -ne 0
+    set overall_failed 1
+end
+
 exit $overall_failed