feat: terminal padding

[griffinwork40]

Terminal Padding

Adds configurable inner margins around the terminal content area — the #1 most-requested visual improvement across terminal design discussions.

Config

Two forms accepted in ~/.config/umber/config.json:

// Uniform padding (px)
"padding": 8

// Separate horizontal/vertical
"padding": { "x": 12, "y": 8 }

Default: 4px (subtle but noticeable). Max: 100px. Negative values clamped to 0. Bad values degrade to 4 with a stderr warning — same fail-soft pattern as every other config field.

How it works

• Padding is applied at the container level (DocumentAreaViewController), not inside the terminal view — TerminalPane.swift (at 346/350 LOC) was not touched
• A paddingBackdrop view fills the content area with the terminal's background color, making the inset seamless — text appears to float, not boxed
• Editor tabs are unaffected — FileViewerPane gets zero padding (it has its own textContainerInset)
• ⌘R reloads padding live
• Works with both SwiftTerm and Ghostty engines

Files changed

File	Change
Config.swift	PaddingSpec Decodable (scalar or object), terminalPadding on AppConfig
Config+Padding.swift	New — fail-soft padding resolver with rationale
DocumentAreaViewController.swift	Backdrop view + frame inset layout
SpaceViewController.swift	Applies padding on document select + config reload
StarterConfig.swift	Config template documentation

All files pass check-file-size.sh (350 LOC ceiling).

[griffinwork40]

Confirmed: no gate script covers Config+Padding.swift or applyPadding. T-1's absence claim is confirmed-absent. However, the project explicitly has no test target — all verification is via check-*.sh scripts. T-1 is valid as observed, but the suggestion should reference a check-padding.sh script rather than an XCTestCase.

Wave 1.5 Verification Manifest:

ID	Type	Status	Notes
C-1	citation	false-finding	load() always starts from defaults() — terminalPadding is (4,4) when over-cap branch fires. Warning is accurate. DROPPED.
C-2	citation	verified	Negative clamping is silent; code at lines 55-56 confirmed.
C-3	citation	verified	Lines 82-83 confirmed: view.needsLayout = true then viewDidLayout().
S-1	citation	false-finding	The (0,0) call on non-terminal documents is correct — it clears padding from a prior terminal. Without it, padding bleeds into editor tabs. DROPPED.
T-1	absence	confirmed-absent	No check-*.sh script covers applyPadding.

Now I dispatch Wave 2 (synthesis) with the filtered findings:

Surviving findings after Wave 1.5:

ID	Severity	Blocking	Dimension
C-2	medium	true	correctness — negative clamping is silent
C-3	low	false	correctness — redundant needsLayout
T-1	low	false	test-coverage — no gate covers padding

One blocking finding remains (C-2). Let me evaluate whether C-2 warrants a blocking override. The negative clamping is silent — but is it a likely production failure under normal usage? A user would have to intentionally type a negative number in their config. That's rare, not normal. The stated intent says "Negative values clamped to 0" which implies the clamping is a known degradation worth warning about, but the blast radius is zero (padding just becomes 0 instead of negative — the visual result is correct). This is a bounded, non-data-affecting defect the author can land and follow up.

Synthesis output:

---

PR #60 — feat: terminal padding — Review

Ref: e0404bbc73376d58f2a2f6b527bf43ef41c53248 · Branch: afk/terminal-padding → main · Change type: feature · Regime: light
Stated intent: PR #60 title+body — spec-compliance assessed.

Findings

1. medium · blocking:false · confidence:high · dimension:correctness · Config+Padding.swift:54–60 · ref:e0404bb · citation-type:file-state · waived: bounded non-data-affecting defect — negative padding is clamped to 0 (correct visual result), the only gap is the missing warning; author can land and follow up

Negative values are silently clamped to 0 with no warning, contrary to the fail-soft contract where every degradation appends a warning to stderr. A config like "padding": -5 resolves to (0, 0) with no feedback.

let px = max(0, x), py = max(0, y)
if px > 100 || py > 100 {
    warnings.append(
        "padding values (\(x), \(y)) exceed the 100px cap — using default 4")
} else {
    terminalPadding = (x: px, y: py)   // negative → 0, silently
}

Suggestion: Add before the cap guard: if x < 0 || y < 0 { warnings.append("padding \(x),\(y) contains negatives — clamped to 0") }

---

2. low · blocking:false · confidence:high · dimension:correctness · DocumentAreaViewController.swift:82–83 · ref:e0404bb · citation-type:file-state

setTerminalPadding sets view.needsLayout = true then immediately calls viewDidLayout() — the flag is superfluous since layout ran synchronously, and AppKit will run a second redundant layout pass on the next run loop tick.

view.needsLayout = true
viewDidLayout()

Suggestion: Remove view.needsLayout = true.

---

3. low · blocking:false · confidence:high · dimension:test-coverage · Config+Padding.swift · ref:e0404bb · citation-type:file-state

No check-*.sh gate covers applyPadding for any boundary input (negative clamping, over-cap fallback, uniform vs x/y decode). The file is pure Foundation and follows the same standalone-compilable pattern as check-keybindings.sh — it is a natural candidate for a headless gate.

Suggestion: Add check-padding.sh compiling Config+Padding.swift standalone with cases for: scalar decode → (4,4), x/y object → (8,4), negative → (0,0) + warning, over-cap → (4,4) + warning.

---

Dropped findings (Wave 1.5 filtering)

Original ID	Reason
C-1 (medium, stale padding on ⌘R)	False finding. load() always starts from defaults(), which sets terminalPadding = (4,4). The over-cap branch's skip of the assignment keeps the correct default — the warning is accurate.
S-1 (medium, spurious layout on non-terminal)	False finding. The (0,0) call on non-terminal tabs is correct: it clears padding set by a prior terminal tab. Without it, switching terminal→editor would leave the terminal's padding visually active on the editor.

What was not checked

• Citations verified inline against branch HEAD e0404bb.
• Stated intent: PR feat: terminal padding #60 title+body — spec-compliance assessed.
• Not checked: runtime visual rendering of padding (seamless backdrop colour match, Liquid Glass interaction, split-pane geometry with padding active).
• Not checked: interaction with the Ghostty engine (GhosttyPane files do not exist at this ref).
• Not checked: check-file-size.sh gate pass (SpaceViewController.swift is at exactly 350/350 — verified by wc -l, passes but has zero margin).

Decision: MERGE — 0 blocking (1 medium waived, 2 low).

The single medium (silent negative clamping) is waived: the visual result is correct (0px padding), the blast radius is zero, and the gap is a missing warning message the author can add in a follow-up. No data integrity, security, or production-failure risk.

---

Done

• What was done: Reviewed PR feat: terminal padding #60 (feat: terminal padding) across all six dimensions — 3 findings survived Wave 1.5 citation verification, 2 findings dropped as false positives.
• Evidence: Review output above; citations verified against e0404bbc73376d58f2a2f6b527bf43ef41c53248.
• What changed: Nothing — read-only review.
• Deferred: none.

---

🤖 Posted by agent-afk /review --post github