feat(highlights): paint and clear valid non-palette API hex (YPE-4494)

[cameronapak]

Review feedback (Cam)

Addresses blocking review on #131:

1. Docs — AGENTS.md and ADR 0017 now document YPE-4494 behavior: palette-only apply, valid non-palette hex paints and clears (ANY rule + exact hex remove circles), invalid hex dropped.
2. Dead seam — Removed unused projectPaintColors; production paint already filters via isValidHighlightHex inside deriveServerColors.

Still open from review (not in this commit)

• Spec drift: activePaletteColors.size > 1 vs web activeHighlights.size > 1 when selection mixes palette + non-palette (threads on verse-action-swatches.ts).

  

Visual context (YPE-4494)

Same contract as web #330, split across core paint + native tray:

on(server color / tray action)
  invalid hex        -> drop from paint and swatches
  valid non-palette  -> paint via deriveServerColors + exact Clear swatch
  palette            -> paint + Clear; apply allowed
  apply (any)        -> palette-only write

Ownership:

packages/
|-- core/src/highlights/
|   |-- paint-projection.ts  # isValidHighlightHex
|   |-- cache.ts             # filter projected server colors
|   `-- use-highlights.ts    # remove allows custom hex; apply palette-only
`-- ui/src/lib/
    `-- verse-action-swatches.ts  # Clear for exact custom colors

Call shape for Clear on a near-black API color (0a0000):

deriveServerColors(highlights)
  -> isValidHighlightHex keeps 0a0000
buildVerseActionSwatches({ verses, colors })
  -> remove swatch { color: '0a0000', state: 'remove' }
  -> apply row stays HIGHLIGHT_COLORS only

Greptile’s flowchart below still describes the validation gate; this section adds ownership + the tray call path.

Greptile Summary

The PR enables valid six-digit non-palette API highlight colors to paint and be cleared while keeping apply actions palette-only.

• Adds shared six-digit hex validation and filters invalid server colors from paint projection.
• Allows exact-color removal for valid custom hex values while retaining palette-only apply validation.
• Adds custom-color remove swatches and updates the web reader dependency, tests, and architecture documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/core/src/highlights/paint-projection.ts	Adds a shared, case-insensitive validator for unprefixed six-digit highlight hex values.
packages/core/src/highlights/cache.ts	Normalizes valid API colors to lowercase and excludes malformed colors from server paint projection.
packages/core/src/highlights/use-highlights.ts	Permits valid custom hex for exact-color removal while preserving palette-only apply validation.
packages/ui/src/lib/verse-action-swatches.ts	Adds normalized custom-color remove swatches, excludes invalid colors, and keeps the apply row palette-only.
packages/ui/package.json	Updates the web UI dependency to the release containing corresponding custom-highlight paint behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  API[API highlight color] --> Validate{Valid six-digit hex?}
  Validate -- No --> Drop[Drop from paint and swatches]
  Validate -- Yes --> Paint[Normalize and paint]
  Paint --> Palette{Palette color?}
  Palette -- Yes --> RemovePalette[Show palette remove swatch]
  Palette -- No --> RemoveCustom[Show exact custom remove swatch]
  Apply[Apply action] --> ApplyPalette{Palette color?}
  ApplyPalette -- Yes --> Write[Paint and write]
  ApplyPalette -- No --> Reject[Reject as invalid]

Loading

_{Reviews (4): Last reviewed commit: "fix(ui): pin platform-react-ui@2.6.2 for..." | Re-trigger Greptile}

[cameronapak]

Spec

Mostly pass vs YPE-4494.

Locked rules look implemented:

• Apply stays palette-only (startWrite rejects non-palette apply)
• Paint keeps valid non-palette via isValidHighlightHex in deriveServerColors
• Remove tray shows exact non-palette hex + checkmark (buildVerseActionSwatches); invalid dropped
• Remove write allows valid non-palette; invalid rejected
• ANY remove kept; stacked on highlights / #100
• Locked seam tests present (swatches, paint-projection, useHighlights clear/apply)

Partial: projectPaintColors is tested/exported but not used on the production paint path (deriveServerColors inlines the same filter). Ticket asked to prefer existing helpers / paint-projection seam — either wire it or drop the unused export.

Standards

Changes requested (docs).

1. Hard: AGENTS.md still says both apply and remove reject non-palette (Do not relax this…). Code + constants.ts prose already relax remove/paint. Update AGENTS (and ADR 0017’s “colors outside the five swatches are ignored”) in this PR so the written standard matches.
2. Hard/soft: Core Exports list in AGENTS should include isValidHighlightHex (and projectPaintColors only if it stays public).
3. Judgement: unused projectPaintColors + duplicated normalize/validate across cache/swatches.
4. Soft: no changeset here — OK if the #100 stack carries one at ship time; call that out before merge.

---

Code Reviewer bot, sent on behalf of Cam. Own-PR review → COMMENT (GitHub blocks self-approve).

[cameronapak]

Spec follow-up

One more Spec gap vs web parity (YPE-4494 “web matching helpers”):

showAllApplyColors on Expo uses activePaletteColors.size > 1, while web uses activeHighlights.size > 1 (includes non-palette).

Mixed fully-highlighted selection {1:'123456', 2:YELLOW} currently omits yellow from the apply row (locked by the new swatch test). Web would re-offer the full palette so the user can paint yellow onto the non-palette verse.

Please align Expo with web (activeHighlights / total distinct valid colors), and flip that test expectation.

---

Code Reviewer bot, sent on behalf of Cam.

[cameronapak]

Re-review @ 9d8a1d6

Follow-ups address the prior Spec + Standards blockers.

Spec

Pass.

• showAllApplyColors now uses activeHighlights.size > 1 (web parity)
• Swatch test expects full apply row for {123456, YELLOW}
• Apply palette-only / paint+clear valid non-palette / invalid dropped / ANY remove still hold
• Unused projectPaintColors removed; isValidHighlightHex remains on the paint path

Standards

Pass.

• AGENTS.md apply/remove/paint rules updated for YPE-4494
• ADR 0017 no longer says non-palette colors are ignored

Soft (non-blocking): Core Exports bullet in AGENTS.md still lists HIGHLIGHT_COLORS / isHighlightColor only — consider adding isValidHighlightHex since it is public from core.

No remaining blocking findings from my side.

---

Code Reviewer bot, sent on behalf of Cam. Own-PR review → COMMENT (GitHub blocks self-approve).

[bmanquen]

Two-axis review of highlights...HEAD — Standards (repo docs + smell baseline) and Spec (YPE-4494). Findings are inline, labelled by axis; the two are reported separately and not reranked against each other.

Standards: 6. Spec: 5, two blocking.