feat: color editing as a widget-editor mode, with per-widget overrides under Powerline themes - #346

Add onTabSwap optional callback to HandleNormalInputModeArgs and Tab key
handling that invokes it when the selected widget supports colors.
Separators and flex-separators are excluded from Tab activation.

- Destructure onTabSwap, onWidgetHighlight, and initialWidgetId props
- Use lazy useState initializer to position cursor from initialWidgetId on mount
- Add useEffect to track cursor position and call onWidgetHighlight
- Pass onTabSwap through to handleNormalInputMode
- Add Tab hint in help text, grayed out when widget is not colorable

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

… hidden when unavailable

Verify Tab key behavior: calls onTabSwap for colorable widgets,
skips separators and flex-separators, and does nothing when
onTabSwap is not provided.

Per-channel pins let a widget's own colour override an active Powerline
theme. Optional so existing settings load with no migration.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

A pinned foreground/background keeps the widget's own colour instead of
the theme's; unpinned channels are unchanged. The theme colour index still
advances for pinned widgets so sibling widgets' colours don't shift.
preserveColors keeps precedence over the fg pin.

Guarantee: an unpinned colour persisted before a theme was enabled stays
dormant, so existing themed configs render identically (no migration).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

pinWidgetColor sets a channel's pin and non-destructively surfaces the
existing colour (seeds only when unset). unpinWidgetColor removes the pin
flag but keeps the colour (not an undo). clearAllPins unpins every widget.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

When the user commits a theme change and any widget has pinned colour
overrides, prompt whether to keep them (carry to the new theme) or remove
them (clearAllPins) so the new theme fully applies. No prompt when nothing
is pinned or the theme is unchanged.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Adds a [PINNED] / [unpinned - theme applies] indicator to the current
foreground/background row when a theme is active, so the editor is honest
about pinned vs dormant. Fixes two phase-1 UX defects: no way to tell if a
channel is pinned, and a dormant stored colour being shown as if effective.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The top-level "Edit Colors" entry no longer opens the standalone color
line-selector. It now lands on a notice screen explaining that color
editing lives in the widget editor (Tab from a highlighted widget), with
an action that jumps straight to the line selector for items.

The 'colorLines'/'colors' screens are left in place - 'colors' is still
reached via Tab from the widget editor - so the change is reversible.

Main-menu navigation is extracted into getMainMenuScreenTarget() so the
routing decision is unit-testable alongside the other App helpers.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

sirmalloc asked for escape from color editing to go back one menu to the
line selector. Color editing is now reached by pressing Tab inside the
widget editor, so "the line selector" is the one the widget editor backs
out to ("Select Line to Edit Items") - escape lands in the same place
whichever mode you were in, and the selected line is preserved.

Tab behaviour is unchanged; the toggle and the shared back target are
extracted as getTabSwapScreen()/getEditorBackScreen() so both are
covered by tests.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Nothing routes to the 'colorLines' screen any more - the main menu
signposts the widget editor instead, and Tab/escape use the items line
selector. Removing the screen leaves LineSelector's blockIfPowerlineActive
prop (and the "colors are managed by the Powerline theme, press any key to
go back" block it rendered) with no callers; that guard also contradicts
this branch, which exists so colors can be pinned over an active theme.

allowEditing goes the same way: the single remaining caller passes true,
so the read-only variant of the line selector was unreachable too.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The selector's two ink-driven tests advanced on 25ms sleeps, so they
failed whenever the machine was busy - the preview test failed every time
when the file ran in isolation, and both started failing in full-suite
runs once more ink tests were added alongside them.

Each step now polls for the state it is actually waiting on (the preview
update, the remove-pins prompt, the selector closing) with a labelled
timeout, so a stall names the step that stalled. A short settle remains
before each follow-up keystroke: ink writes the frame before the next
screen's input handler attaches, so a keypress sent the instant the frame
appears is dropped.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

sirmalloc asked that color editing keep the widget editor's shape. The
two editors built their rows separately, so the same widget rendered
differently in each: "1. Model (merged→)" in one, a tinted "1: Model" in
the other.

Extract WidgetRow plus getWidgetRowLabel/getWidgetRowTags so both modes
share numbering, indicator and the dim structure markers, and title the
widget editor "Edit Line N [WIDGETS]" so the two modes share a title
stem. ColorMenu adopts the same row in the following commit.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Color editing now reads as the same screen in a different mode rather
than a separate one:

- title is "Edit Line N [COLORS]", matching the widget editor's stem,
  with [BACKGROUND] as a sub-mode tag
- rows come from the shared WidgetRow, so they carry the same numbering,
  indicator and structure markers, tinted with the color they hold
- rows are numbered by position in the full line, so a widget keeps its
  number across modes and skipped widgets leave a gap
- ink-select-input is gone; ColorMenu owns its up/down navigation, which
  also removes the remount-on-highlight hack and the duplicate static
  list used during hex/ansi256 entry
- the in-list "← Back" row is dropped (the widget editor has none, and
  ESC is documented in both help texts)
- (s)how separators folds into the help line and the VSCode contrast
  warning collapses to one line, so both modes put their list in the
  same place

Row parity is deliberately not attempted: Tab only enters color editing
from a colorable widget, so padding the list with unselectable rows would
confuse more than the renumbering it would fix.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

ColorMenu was the only consumer and it now renders the shared WidgetRow
list, so nothing in the repo imports ink-select-input. Also switch the
ColorMenu test's ANSI stripping to the strip-ansi package the other TUI
tests already use, instead of a hand-rolled regex.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Both editor modes put conditions that override what you do here next to
the title - the powerline warning in the widget editor, the global colour
override warning here. The VSCode contrast note is not that: it never
changes with state and is environmental, so wearing the same ⚠ glyph made
it read as a misplaced peer of those warnings rather than as a footnote.

Also drops a stray '.' that separated the title from the global override
warning.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The color editor needs to know which theme color a widget actually
renders in, and re-deriving that would drift from the renderer the first
time either side changed.

assignPowerlineThemeSlots() now owns the rule - merged widgets share a
slot, separators break a merge run, widgets that render nothing take no
slot - and both callers read from it. The renderer replaces its inline
index counter with a lookup, countPowerlineThemeSlots() is expressed in
terms of the assignment, and getEffectiveThemeColors() maps widget id to
the theme colors that win over the widget's own, leaving pinned channels
(and a preserve-colors custom command's foreground) undefined so callers
fall back to the stored color.

getActiveThemeColors() also replaces the renderer's inline theme lookup,
so the color-level key mapping lives in one place too.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…heme

An unpinned channel under an active theme renders the theme's colour, but
the editor showed the widget's dormant stored value - both on the
current-style row and in the row tinting - so the editor disagreed with
the preview about what was on screen.

Both now read from getEffectiveThemeColors, so an unpinned row is tinted
with its theme colour and the current-style row reports it as "(theme)"
instead of a palette position that does not apply. Pinned channels are
unchanged: they still show the widget's own colour with [PINNED].

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Theme colours are positional - a widget's colour comes from its slot, and
slots move when you reorder or merge widgets. That is precisely what the
widget editor does, so it was the one place you could not see the effect
without tabbing across to the colour editor and back.

Rows are now tinted through the same styleWidgetRowLabel helper the
colour editor uses, so outside move mode the two lists render identically
- a new parity test asserts the rows are byte-identical, ANSI included.
Selection is shown by the indicator alone, as it already is in colour
mode. Move mode drops the tint and keeps the blue row, so the row being
dragged stays trackable; the change of rendering doubles as the mode
signal. A custom command preserving its own output colours is left
untinted, since its colours are not ours to predict.

This inverts the direction of sirmalloc's request - it changes the widget
editor to match the colour editor rather than the reverse - and it costs
the green selected-row highlight, so it is deliberately the last commit
on the branch and can be dropped on its own.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The list no longer has a "← Back" row, so highlightedItemId can never be
'back' and the nine guards checking for it were unreachable conditions.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The feature had no user-facing documentation: pinning a colour over a
Powerline theme, the (p) keybind, the automatic pin when editing under a
theme, and the fact that colour editing is now reached with Tab from the
widget editor were all undocumented.

Adds a "Pinning Colors Over a Powerline Theme" section covering the pin
model (independent per channel, non-destructive unpin, dormant colours
left alone) and notes the Tab route and the shared escape target in the
widget editor keybinds.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Pin state is per widget and per channel, but it was reported on a status
line that only ever describes the highlighted widget - so you could not
see which widgets carried overrides without visiting each one. That line
also restated the channel being edited, which the header already showed
in background mode, and paired "(theme)" with "[unpinned - theme
applies]", saying the same thing twice.

Pins now appear as row tags - (fg pinned), (bg pinned), (fg+bg pinned) -
alongside (merged→) and friends, shown only when a theme is active and in
both editor modes, since the row renderer is shared. The header names the
channel symmetrically ([FOREGROUND] as well as [BACKGROUND]), and the
status line is left with just the value it exists to show.

isPowerlineThemeActive() replaces ColorMenu's inline theme check, so that
condition now lives with the rest of the theme logic.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Cycling a colour under a theme used to pin the channel automatically. That
made a stray arrow key destructive: it pinned AND overwrote the widget's
stored colour, and because unpinning is non-destructive by design, the
original value was gone with no way back - exactly the dormant colour the
no-appearance-change guarantee promises to leave alone. The colour keys
sit one row from the navigation keys.

Under a theme, the colour keys (arrows, hex, ansi256, gradient) now do
nothing until the channel is pinned, and the current-style row says
"- theme applies, press (p) to override" rather than leaving them looking
broken. Bold, dim, reset and clear-all are not theme-driven and stay live,
and nothing changes when no theme is active.

Pinning now seeds from the theme colour the widget is actually rendering
when it has no colour of its own, instead of the widget's default. That
was the behaviour promised on the PR, it makes taking control leave the
appearance untouched, and it means edits start from the value on screen
rather than jumping to an unrelated one.

commitColorEdit goes away with the auto-pin it existed for.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

The colour editor computed powerline theme slots from different inputs than
the renderer, so under a theme it could preview - and pin - a colour the
status line never used.

getEffectiveThemeColors called assignPowerlineThemeSlots with placeholder
content for every widget and the default startIndex of 0, while the renderer
passes real pre-rendered content and the cross-line offset. Two divergences
followed: with continueThemeAcrossLines every line after the first was
previewed in the previous line's colours, and any widget that rendered empty
consumed a slot in the editor but not in the renderer, shifting everything
after it.

getEffectiveThemeColors now requires a ThemeSlotContext holding both inputs,
so no call site can silently default them. App owns a single memoised
pre-render and derives per-line contexts from it; StatusLinePreview consumes
that instead of pre-rendering again, which also stops custom commands being
executed twice per keystroke.

Also in the same area:

- applyCustomPowerlineTheme walked its own slot index, so (c)ustomize wrote
  different colours than the theme it promised to copy - merged widgets most
  visibly. It now uses the shared helper. It passes placeholder content on
  purpose, because it bakes colours in for every future render.
- renderer.ts re-implemented keepsOwnForeground inline. Both sides now read
  the one predicate, so the pin gate and the render cannot disagree.
- (r)eset and (c)lear-all bypassed the pin gate and deleted colours the theme
  was hiding, with no visible change to warn the user. Under a theme they now
  clear bold, dim and pinned channels only.
- Cycling a pinned channel onto the palette's Default entry left it pinned
  with no colour, suppressing the theme with nothing to replace it. Pinned
  channels no longer offer that entry.
- Adding a widget under a theme assigned a random background that the theme
  then hid, which pinning would later seed from. That assignment is now
  limited to the case where the widget's own background is what renders.

USAGE.md dropped the claim that pinning never changes appearance: it does
when the widget has a dormant colour, which is the case the feature exists
for. It now documents that, the reset/clear behaviour, and that theme colours
follow position among the widgets that actually render.

eslint.config.js ignores .claude/, whose nested worktrees are outside this
project's tsconfig and made `bun run lint` fail with parser errors.

bun run lint clean; bun test 1950 pass, 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Follow-up to c178ed7, covering the rest of the review findings.

Data loss and unreachable exits:

- The remove-pins prompt applied the theme on Yes, No and ESC alike, so the
  "ESC cancel" the screen advertises committed a theme the user was only
  previewing. ConfirmDialog gained an optional onEscape for dialogs whose
  "No" still commits something; the prompt now restores the original settings.
- That prompt is reached by Enter and had "Yes" preselected, so a repeated
  Enter wiped every pin. ConfirmDialog gained defaultChoice, defaulting to
  'yes' so no other dialog changes, and the prompt asks for 'no'.
- Selecting the 'custom' theme offered to remove pins that override nothing
  there, and (c)ustomize kept pins that had become redundant - invisible,
  because the row tag needs a real theme, and revived by the next theme
  change. The prompt now skips 'custom' and the customizer drops the pins.
- Pins survived a theme being turned off with no way to see or clear them:
  the tag, the (p) key and the help text were all gated on an active theme,
  while the baked colour kept rendering. Tags now show as "(fg pinned,
  inactive)" and (p) unpins without a theme, though pinning still needs one.

Editor swap:

- editingBackground and showSeparators were local state, and Tab swaps by
  changing screen, so both silently reset - the header could read
  [FOREGROUND] while the user believed they were editing a background. App
  owns them now.
- Tab was refused on rows the colour editor can still highlight, making it a
  one-way door out of the widget editor. It is a mode switch, so it always
  works; the colour editor already falls back to its first colourable row.
- Tab was also swallowed on the empty colour list, sending the user to the
  line selector from the screen that says to go add a widget.
- Flex separators were listed as colourable, because getWidget returns null
  for them and the filter treats unknown types as colourable. They render no
  text and take no theme slot, so they are excluded - which also stops a
  meaningless pin latching hasPins on for good.

Row tinting reproduced the theme but not the rest of the renderer's
precedence, so rows advertised colours the status line does not use. Global
foreground/background overrides now win, globalBold ORs with the widget's own
bold, and under powerline a gradient collapses to its first stop.

Tests and docs: the editor-row-parity fixture was all-colourable, so it could
not catch divergence; a mixed fixture now pins the real contract - the widget
editor lists 1,2,3,4,5 where the colour editor lists 1,5, leaving gaps rather
than renumbering. USAGE.md no longer claims both modes list the same widgets.

Cleanup: isMergedIntoPreviousWidget exported instead of duplicated;
getEffectiveThemeColors and the derived row lists memoised, which also
stabilises the highlight-repair effect's dependencies; getEditorBackScreen()
became the EDITOR_BACK_SCREEN constant; getMainMenuScreenTarget enumerates
its action-only options behind a never check so a new entry cannot compile
clean and do nothing; a tinted selected row is underlined, since the
selection colour cannot apply to a label that carries its own; the dead digit
guard and the stale ink-select-input comments are gone.

.at(-1) and Object.hasOwn are replaced at all four runtime call sites rather
than just the one on the theme path - engines.node >=14 and the Node 14 build
target lower syntax but do not polyfill prototype methods, so fixing one site
would have achieved nothing.

bun run lint clean; bun test 1960 pass, 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Follow-up to a6de0b5, from a review of that commit.

Row tinting reproduced the renderer's precedence as if both render paths shared
it, so a row could still advertise a colour the status line does not use:

- A global background override was applied to every row, but only the standard
  path reads overrideBackgroundColor - renderPowerlineStatusLine never mentions
  it. Under a theme every row showed the override while the line showed the
  theme. It now applies with powerline off, which is where it renders.
- A gradient foreground override was treated as a solid per-widget colour, which
  neither path does: it is painted across the finished line, so each widget shows
  a slice of it. At ansi16 that pass is a no-op and the widget keeps its own
  colour, which the row now does too. Above ansi16 the row paints the gradient
  across its label rather than claiming one stop for every row, since no row can
  know its own slice.
- Collapsing a widget's own gradient under powerline went through a hand-rolled
  hex: conversion, and getColorAnsiCode's hex: branch ignores colorLevel - so it
  emitted truecolor at ansi16, where the renderer emits nothing, and at ansi256,
  where it emits a 256-color escape. applyColors gained collapseGradient, which
  takes the existing fall-through to getColorAnsiCode instead, and the local
  first-stop helper is gone.

Editor swap:

- Tab is checked before the input-mode guards so it works on an empty line, but
  it was also reaching across them: from half-typed hex it discarded the entry,
  and from the clear-all prompt it abandoned the dialog, both without asking.
  A confirmation or text entry now holds the key, as it did before Tab existed.
- Swapping from a row the colour editor cannot show - a flex separator, or a
  separator while hidden - made it fall back to its first colourable row and
  report that as the highlight, overwriting the caller's cursor. Two Tabs from
  row 4 landed on row 1. A fallback is a guess, not a choice, so it is no longer
  reported; the guess is spent once the highlight moves.

showSeparators moved to App in a6de0b5 and so no longer resets on entry, which
made it unresettable: the (s) toggle is refused under powerline or a default
separator, but the row filter was not, so rows turned on beforehand stayed
visible with a dead toggle. Both now read one canShowSeparators predicate,
along with the help text that offers the key.

bun run lint clean; bun test 1977 pass, 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Follow-up to 8a725bd, from a review of that commit. Two of the three were
introduced by it.

A default separator does not replace separator widgets already on a line. It
only supplies the character for separators that have none: renderer.ts:1053
uses widget.character ?? settings.defaultSeparator and colours with
widget.color ?? 'gray', so [text, separator '#', text] with defaultSeparator
'~' renders "AAA~#~BBB". Gating the row list on it therefore hid rows for
widgets that still render, and neither the list nor the (s) toggle could bring
them back - trading the dead toggle 8a725bd fixed for unreachable rows.

Separator rows are now listed whenever they render, which powerline alone
decides, and the toggle reads the same predicate so the two cannot disagree.
This does relax a pre-existing gate: (s) previously refused while a default
separator was set. That rule belongs to adding NEW separators, which is what
widgets.ts:46 governs; recolouring the ones already on the line is a different
question, and refusing it left rendered output unreachable.

Also:

- guessedHighlightId stored the guessed id directly, so "no guess" and "guessed
  null" were the same value. On a line with nothing colourable the guess is
  null, the guard did not fire, and onWidgetHighlight(null) cleared the caller's
  cursor - reintroducing the jump to row 1 that 8a725bd set out to prevent. The
  ref now wraps the id so the two states are distinct.
- The gradient override branch keyed off isGradientSpec, which is prefix-only,
  while what renders is decided by parseGradientSpec - null below two resolvable
  stops. For a spec like "gradient:FF0000" the row handed applyColors something
  that produces no code at all. The paths differ here, so both are reproduced:
  powerline keeps the widget's own foreground, while the standard path has
  already dropped it and then paints no gradient over it.

Verified by rendering each case through preRenderAllWidgets/renderStatusLine and
comparing the row to the line.

bun run lint clean; bun test 1981 pass, 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>