tuile 0.13.0 → 0.15.0

data/ideas/binder.md

@@ -0,0 +1,177 @@
+# A Binder for Tuile — the pattern to copy, and the vocabulary that comes with it
+
+**Status:** filed 2026-09-03 as a **placeholder plus a settled vocabulary**.
+Nothing is designed here and nothing is implemented; the forms layer is not
+started. Two things earn the file: (1) Vaadin's `Binder` is the pattern to
+copy, and it is worth writing down *which parts* before anyone improvises one,
+and (2) the four-layer terminology below was settled while designing
+`HasBadInput` and has nowhere else to live until a `D_` entry exists — it is
+the reason that channel is called `bad_input` and not `presentation_error`.
+
+`D_has_value` is the standing authority on what belongs above the field:
+"Model-mapping (presentation ⟷ domain) is left to a future forms/binder layer
+*above* the field, never baked into field state", and it parks converters,
+`read_only` and the required-indicator there too. Nothing here overrides that.
+
+## The terminology (settled — this is the file's real content)
+
+Four layers, and the two arrows that matter. A `Date`-valued field bound to
+`Person#birth_date`:
+
+| layer | example | who speaks it |
+|---|---|---|
+| **model** | `Person#birth_date` | Binder only |
+| **transformations** | `birth_year` + `birth_month` + `birth_day` → a `Date`; a `birth_date_iso_string` → a `Date` | Binder only |
+| **value** | the `Date`, or `nil` — `HasValue#value` | **both** — the shared layer, which is why `HasValue` is *the* seam |
+| **input** | the glyphs the user typed, a calendar click, a mask's partial fill: `"2020-05-01"`, `"xyz"` | the field owns it; the Binder must be able to *ask about* it |
+
+| arrow | word | note |
+|---|---|---|
+| input → value | **parse** | *partial* — it can fail, and that failure is **bad input** (`D_bad_input`) |
+| value → input | **format** | *total* — formatting a `Date` into glyphs cannot fail |
+| the parse/format pair, inside a field | the field's **converter** | already the house word (`D_integer_field`: "the converter stays private and hardcoded"; `DECISIONS.md:2010`: a `parse`/`format` hook pair *is* the converter strategy) |
+| model ⟷ value, in the Binder | a **transformation** / the Binder's converters | a *chain*, possibly several steps |
+
+Why these words and not Vaadin's, in three lines:
+
+- **`presentation` is unavailable.** Vaadin's `Converter<PRESENTATION, MODEL>`
+  uses it for the **value** layer — `convertToModel` "receives a value that
+  originates from the user", `convertToPresentation` one "that originates from
+  the business object" — so it never names the glyph layer at all, and
+  `D_has_value` already adopted the same axis in prose. `Date` is the tell: it
+  *is* "the presentation" in Binder-speak while saying nothing about
+  formatting.
+- **A pair cannot name a chain.** model→value may be several transformations
+  (an old schema splitting a date across three columns), so naming one arrow
+  after the endpoints of a different chain is what made this confusing.
+- **`input` had to be freed.** Tuile's rdoc used "an input" for the *widget*
+  (~40 real sites, plus `Theme#input_bg_color`). The rule going forward:
+  **"input" alone is what the user put in; the widget is always a `field`**,
+  never "an input" — Tuile already says `field` 188 times, and TERMINOLOGY
+  already calls that background a **well**, so the token name is grandfathered
+  legacy. The sweep is a standalone mechanical pass, deliberately not bundled
+  with an unimplemented design. Note ~30 further hits are the ordinary English
+  sense ("a renderer whose *inputs* changed", "both shorter and longer *inputs*
+  are bugs") and must **not** change.
+
+**Reserved:** `model`, `transformations` and `presentation` belong to the
+layers above `value`; `domain` is the word `D_has_value` uses for the topmost
+one. Don't spend them on a field-level concept. At graduation the layer words
+go to TERMINOLOGY.md (one line each, beside `text` and `caption`) and the
+choice to a `D_` entry — a nomenclature ruling in the `D_scroll_nomenclature`
+mould.
+
+## Why Vaadin's `Binder` is the pattern
+
+It is the only one of the surveyed toolkits that keeps *form validity* as a
+single source of truth without pushing rules into the widgets — which is
+exactly the split Tuile has already committed to — the field reports what its
+own parse could not represent and never judges (`D_bad_input`), and the verdict
+lives in a slot only an outside validator writes (`D_has_validation`). The parts
+worth copying, from v25.2:
+
+- **`forField(field).withValidator(pred, message).bind(getter, setter)`** — a
+  builder per binding, rules declared beside the binding and nowhere else;
+  `asRequired("msg")` as the shorthand.
+- **`withConverter`** for the model⟷value transformations, including a
+  conversion-error message, and chains where each step sees the previous
+  step's output.
+- **`readBean` / `writeBean` / `writeBeanIfValid`**, with a write that refuses
+  when anything is invalid.
+- **`isValid` / `hasChanges` / `validate` → `BinderValidationStatus`** as the
+  aggregate the app asks.
+- **`binding.validate()`** for cross-field revalidation ("cannot return before
+  departing"), driven from the other field's value-change listener.
+- **Escape hatches that exist for real reasons:** `setValidatorsDisabled`,
+  `setDefaultValidatorsEnabled(false)` / `withDefaultValidator(false)`, and
+  `setIsAppliedPredicate` for a binding that shouldn't participate at all.
+
+What Tuile should *not* copy: `HasValidator#getDefaultValidator` and
+`addValidationStatusChangeListener`. Both exist to repair a *shared*
+`invalid`/`errorMessage` cell on the component; Tuile puts the two facts in two
+places instead, so the repair has nothing to fix (`D_bad_input`, and
+`Component::HasValidation`, shipped 2026-09-03 — `D_has_validation`: one stored
+`error_message` the field never writes, so the Binder is its sole writer and
+sets-or-clears it on every validate pass). Ruby also deletes most of the
+ceremony: a validator is a proc returning a message or `nil`, so there is no
+`Validator` interface, no `ValidationResult`, and no `Result.ok`.
+
+## What the Binder must consume from a field
+
+- **`is_a?(HasValue)` is the marker** for "this is bindable" — `D_integer_field`
+  says so explicitly.
+- **`field.respond_to?(:bad_input?) && field.bad_input?`** is the bad-input
+  question — **this half exists today** (`D_bad_input`) — asked at bind, at
+  click, at write, and whenever a sibling forces a revalidation. The *capability* is a class fact and may be cached at bind
+  time; the *status* may never be cached.
+- **Bad input must block the write even for an optional field.** This is the
+  failure Vaadin names and the whole reason the channel exists — an optional
+  field means "may be empty", not "may be garbage". And it cannot be reached
+  through `empty?`, which reports `true` for a field full of glyphs the value
+  cannot represent.
+- **A push notice (`on_bad_input_change`) is deliberately *not* built** — it
+  is needed only by a consumer that must react *between* clicks, which a Binder
+  gated at the click is not (`D_bad_input`, `D_on_blur`).
+
+## The Tuile-specific part: gating Save
+
+**The gate goes at the click, not on the button's enabled state.** Save asks
+the Binder when pressed and, on "no", opens an alert naming the problems
+(`ConfirmWindow.alert` exists — `D_confirm_window`). Vaadin's idiom is the
+other one (v25.2 `flow/binding-data/components-binder-load.md`):
+
+```java
+binder.addStatusChangeListener(event -> {
+    saveButton.setEnabled(event.getBinder().hasChanges()
+                       && event.getBinder().isValid());
+});
+```
+
+Three reasons not to copy it, ascending:
+
+- **`Button` has no disabled state** — no `enabled` axis on `Component`, no
+  `:disabled` in `BG_STATES` (AGENTS.md is explicit that the key is absent
+  because the *state* is absent). The enabled design needs framework work
+  first; the click design needs none.
+- **A disabled control says nothing about why**, and a TUI has no channel to
+  explain it: no tooltip, and hover is not even received (mode 1000 is
+  press-only — `ideas/hover.md`).
+- **It removes the only *continuous* consumer of the bad-input signal**, so
+  nothing needs a settling policy: a Binder asked only at the click sees one
+  settled state, and the flicker `D_bad_input` describes never arises on this
+  side. (The *well* still owes one, now that it ORs `bad_input?` — that debt is
+  unassigned and belongs to the first continuous consumer, per
+  `D_has_validation`.)
+
+If a settling policy is ever wanted here anyway, copy Vaadin's display rule
+rather than inventing one: errors count only after the user has edited a field
+and submitted.
+
+## Open, and deliberately not designed here
+
+Where a rule's message is *stored* and *shown* is answered by
+`D_has_validation`: stored on the field as `HasValidation#error_message`, shown
+as the field's own red *well* plus text in whatever cells surround it (the
+layout's inline-right message is still unbuilt — `ideas/form-layout.md`). The
+Binder writes it, and does not hold a per-binding cell of its own. Two
+consequences for the port: the write is a plain `field.error_message = msg_or_nil`
+per pass, and the Binder must **subscribe nothing** to show it — but it does
+compete for the single `on_error_message_change` slot with a `FormLayout` and
+with the app, which that note flags. Whether Tuile grows a `Signal` type to
+mirror Vaadin 25's `validationStatusSignal()` is untouched — Tuile's listener
+idiom is a plain proc, and nothing has asked for more.
+
+## Related
+
+`D_bad_input` (the field-side channel this consumes, already shipped),
+`D_on_blur` (the commit point that shipped, and why the push notice stays
+deferred), `D_has_validation` (the
+verdict slot this Binder is the sole writer of; where a message lives and who
+paints it), `ideas/form-layout.md` (the unbuilt container that would paint it),
+`ideas/new-components.md` (Tier 2 Form Layout, Custom Field; infra items 2–3),
+`D_has_value` (the forms layer owns converters, `read_only`, the
+required-indicator; the typed-value survey), `D_integer_field` (the field's own
+converter stays private; `is_a?(HasValue)` is the Binder's marker),
+`D_scroll_nomenclature` (the nomenclature ruling this vocabulary copies),
+`D_confirm_window` (the alert the Save button opens), `D_status_bar` (why the
+framework places no error row).

data/ideas/composite-field.md

@@ -0,0 +1,77 @@
+# `CompositeField`: several fields behind one value
+
+**Status:** filed 2026-09-04, as what was left over when
+`Component::AbstractWrappingField` shipped and its note graduated — read
+`D_wrapping_field` first, this note assumes it. Nothing here is built, and it
+waits for a **real consumer**: the two questions it turns on have no answer
+that today's components would test.
+
+The shape: a `DateTimeField` over a `DateField` plus a `TimeField`, i.e. several
+fields arranged in a layout behind one typed value. `AbstractWrappingField` is
+deliberately *one editor, full stop*, and was built as the prototype this learns
+from.
+
+What is already known about its shape:
+
+- **A sibling of `AbstractWrappingField`, not a subclass of it.** That base's
+  whole value is that one child removes the layout and the ordering; inheriting
+  from it would put both back.
+- **No auto-discovery of the fields — ever.** A tree walk for "the fields inside
+  me" would descend *through* a wrapping field into the private editor it exists
+  to hide. Registration is explicit.
+- **`active=` already gives it the right commit semantics** — see
+  `D_wrapping_field`, where that seam is chosen partly *because* it survives
+  here: focus moving between two of a composite's own fields keeps the composite
+  active, so it does not spuriously commit. The one hard part it inherits solved.
+- **The abstract pair generalizes by pluralizing.** `value` / `value=` already
+  mean "read the value out of my field(s)" and "apply the value into my
+  field(s)"; a composite changes nothing else about that contract, which is the
+  evidence the prototype transfers.
+- **It cannot inherit the "the base adds the child" guarantee**, and that is
+  another reason it is a sibling. `AbstractWrappingField` calls `add_child`
+  itself, which is what makes *own and hide* a guarantee rather than a
+  convention. A composite must let its subclass populate a layout, so something
+  else has to replace it — explicit registration of which descendants are its
+  fields.
+- **What it must solve, and a wrapping field never had to:** assembling `value`
+  from several children with a diff guard; deciding whether `bad_input?` is "any
+  child" or "the combination"; which child takes focus on `on_focus`; and how
+  the layout is expressed without becoming a container.
+
+**The hard one: which component wears the error, and it is already half
+answered.** Picture `Date: [DateField] Time: [TimeField]` — a `Horizontal` of
+four children, two of them labels. Two strategies: the composite marks *itself*
+invalid, or it marks each of its *fields*. **They are not symmetric — the first
+is already broken by the background chain.** `error_bg_color` sits at the top of
+the same chain a child walks, so a child inherits its parent's *error* level,
+not merely its normal well. Verified:
+
+```ruby
+f = Component::IntegerField.new
+f.error_message = "nope"
+label_under_it.effective_bg_color   # => Color 88 — the error well
+```
+
+So a composite that marks itself reddens its `Date:` and `Time:` labels, which
+is wrong for the same reason `D_caption_ownership` keeps a caption off a field:
+that text is chrome, and chrome is not the thing that failed. That points at
+marking the fields — but it leaves the genuinely hard case open, and it is the
+case a composite exists for: a **combination** error (`start > end`) where no
+single field is wrong. Marking one is a lie, marking all of them is loud, and
+marking none loses the signal. Unsolved, and the reason the whole area waits for
+a real consumer.
+
+**BG_INHERIT is the same question wearing a different hat** — does a composite's
+whole subtree inherit its well (and the labels sit in it), or only the fields
+(and the layout's gaps show terminal default, looking patchy)? Both readings are
+defensible, neither has a consumer, so nothing guesses yet.
+
+## Related
+
+`D_wrapping_field` (the one-editor base this generalizes — its admission test,
+its forwarding test, and `active=` as the commit point), `D_has_validation` and
+`D_bad_input` (the two error channels a composite has to combine),
+`D_caption_ownership` (why an inner label is chrome, and chrome is not what
+failed), `D_bg_surface` (the background chain that makes "mark self" redden the
+labels), `D_date_field` (`DateTimeField` is the plausible first
+consumer).

data/ideas/focus-accent.md

@@ -0,0 +1,116 @@
+# The focus accent — should `Button` / `Checkbox` / `Tabs` / `MenuBar` / `List` move onto `default_bg_color`?
+
+**Status:** measured and parked, 2026-09-01. Spun off from `D_bg_surface`,
+which introduced `Component#default_bg_color` and migrated the *well* widgets
+(`AbstractStringField`, `Select`, `ComboBox`) onto it while explicitly leaving
+this family alone. That note records the decision; this one records the
+*measurement*, so whoever revisits it doesn't re-run the experiment.
+
+## The question
+
+Five widgets highlight themselves on focus by stomping a background onto their
+painted content at repaint time:
+
+```ruby
+label = label.with_bg(screen.theme.active_bg_color) if active?   # Button, Checkbox
+segment.with_bg(screen.theme.active_bg_color)                    # Tabs, MenuBar
+is_cursor ? base.with_bg(screen.theme.active_bg_color) : base    # List
+```
+
+`default_bg_color` can express the per-component half of that —
+`{ active: screen.theme.active_bg_color }`, or the allocation-free
+`active? ? … : nil`, with no `:normal` key so an unfocused widget falls through
+to the ambient. So: should it?
+
+## Measured, not argued (Checkbox, 2026-09-01)
+
+The migration was written and run. It is:
+
+```diff
+       label = (StyledString.plain(value ? "[x] " : "[ ] ") + caption).ellipsize(rect.width)
+-      label = label.with_bg(screen.theme.active_bg_color) if active?
+       draw_text(rect.left, rect.top, label)
+     end
++
++    # @return [Color, nil]
++    def default_bg_color = active? ? screen.theme.active_bg_color : nil
+```
+
+**Net +2 lines.** Nothing is deleted, because these widgets have no *well* —
+there is no reach-around-the-chain to remove, which is exactly what the
+`AbstractStringField` migration did delete (`#background`). So it is not a
+simplification.
+
+**The whole suite passed: 2787 examples, 0 failures.** Both behavior changes
+below are unpinned by any spec — see *The missing guard*.
+
+Probed directly, migrated vs. original, on a focused `Checkbox` at 20×1:
+
+| case | original | migrated |
+|---|---|---|
+| caption span carries `bg: BLUE` | `59, 59` — accent covers it | `59, :blue` — **the span survives** |
+| `bg_color = 52` | `59, 59` — accent stomps the tint | `52, 52` — tint wins, no focus shade |
+
+## What the measurement says
+
+**A surface and an accent are different things, and the hook is only right for
+one.** A *surface* is what your cells sit on; it is legitimately the app's to
+override, which is the whole point of `bg_color` winning over
+`default_bg_color`. An *accent* is a signal painted **over** whatever is there,
+and it must be unconditional — the moment it can be selectively suppressed
+(by a caption span, by an app tint) it stops being a reliable indicator.
+
+Row 1 is therefore a regression: `with_bg` is override-all, `under_bg` (what
+`draw_text` applies) is fill-unset, so a caption carrying its own background
+punches a hole in the highlight.
+
+Row 2 is worse than it looks: `Checkbox` paints no caret, so a flat `bg_color`
+removes its only focus affordance. Recoverable with `{ normal:, active: }`, but
+the *default* got worse. This is the same objection that made `Select` the
+awkward case in `D_bg_surface` — there it was accepted because a `Select` really
+does paint a well, and the flat surface is a real thing to want.
+
+**And for three of the five it isn't even expressible.** `Tabs`, `MenuBar` and
+`List` accent a *segment or row*, not the component. A per-component hook has
+nothing to say about "the third tab" or "the cursor row". Only `Button` and
+`Checkbox` are candidates at all, which makes a partial migration a
+consistency *loss*, not a gain.
+
+## Options, when this is picked up
+
+- **(A) Leave it, pin it.** The status quo plus the specs below. Cheapest, and
+  the measurement above says the status quo is right.
+- **(B) Migrate `Button` + `Checkbox` only.** Costs +4 lines, splits the family
+  three ways, and takes both regressions. Hard to justify on this evidence.
+- **(C) Name the accent as its own concept.** The honest generalisation: a
+  paint-time `over_bg` / accent layer that is *not* part of the `bg_color`
+  chain and is applied after it, with an explicit `with_bg` (override-all)
+  contract. That would cover all five *and* the segment/row cases, because the
+  layer is applied to a `StyledString` rather than declared per component. It
+  is a second colour channel, though — weigh against `D_theme_ref`'s "not a
+  third colour channel" reasoning before adding one.
+- **(D) Make focus indication a framework concern.** `Screen` knows the focus
+  chain; it could accent the focused component's extent centrally. Almost
+  certainly wrong — it would need per-widget opt-out (a focused `TextArea` must
+  not have its whole rect stomped) and reintroduces a framework-owned paint
+  pass the top-down layout rule keeps out.
+
+## The missing guard (do this regardless of the outcome)
+
+Neither behavior in the table is asserted anywhere, which is how a future
+migration would land silently. `checkbox_spec` and `button_spec` want:
+
+- the focus accent covers a caption span that carries its own background
+  (pins `with_bg`, not `under_bg`);
+- `bg_color` set on the widget does **not** suppress the focus accent
+  (pins the accent as unconditional).
+
+Eight lines each, and they convert `D_bg_surface`'s "deliberately not migrated"
+from recorded to enforced.
+
+## Related
+
+`D_bg_surface` (the chain, the state map, the surface/accent line),
+`D_bg_inherit` (`under_bg` vs `with_bg`), `D_boolean_fields` (why the extent
+arithmetic must not vary with `bg_color`), `D_theme_ref` (why there is not a
+third colour channel).

data/ideas/form-layout.md

@@ -0,0 +1,151 @@
+# `FormLayout`: where the caption, the message and the required marker go
+
+**Status:** filed 2026-09-03 as `ideas/caption-and-error-ownership.md`, which
+asked whether a field or the container around it owns the caption and the error
+state. **That question is settled, and the field half has shipped** — read
+`D_caption_ownership` (a field carries no caption; the container does) and
+`D_has_validation` (the field stores the verdict in
+`HasValidation#error_message` and paints it as a red *well*; whoever owns the
+cells paints the *message*, subscribing to `on_error_message_change`) before
+this note. Nothing here re-argues either. Note in particular that an invalid
+field shows **no ink at all**: it gets a slight red *well*, never the red
+foreground on the glyphs that the first draft recommended.
+
+What is left — and all this note now holds — is the *container* half: the
+`FormLayout` that has the cells. Unbuilt, and still what infra item 2 of
+`ideas/new-components.md` is blocked on. Graduates into a `D_form_layout`, the
+component's rdoc, a book ch7 section, a README Components row and a CHANGELOG
+line.
+
+## What the layout has to place
+
+Three pieces of chrome, none of which the field carries or can carry:
+
+- **the caption** — `FormLayout#add(field, caption: "Username")`; the string
+  lives in the layout's per-child map, never on the field.
+- **the message** — read off `child.error_message`, painted in
+  `Theme#error_color`.
+- **the required marker** — a red dot beside the caption; chrome like the
+  caption, so it rides the container too (below).
+
+## Recommended shape: one row per field, inline on both sides
+
+```
+   Username ∙ [________________] Required
+   Password ∙ [________________] Required
+```
+
+(the `∙` is the required marker, red; whether it sits before or after the
+caption text, and whether it widens the caption column, goes with the caption
+geometry below.)
+
+- **Inline right for the message.** One row, no growth, nothing bottom-up —
+  which is the whole reason to prefer it. The message is bounded by the row, so
+  the layout truncates with an ellipsis (`InfoWindow#lines=` is the model).
+- **A form-level status row showing the first error is the *app's*** to build
+  from the same data, not the layout's — `D_status_bar` from the other side: the
+  framework reserves no row it was not asked for.
+
+## Wiring the message
+
+The layout paints the message in cells the *field* does not invalidate, so it
+has to be told: subscribe to `on_error_message_change` at `add`, unsubscribe at
+`remove`. That notice exists for exactly this consumer, and `D_has_validation`
+records why it is plain listener inversion rather than the push notice
+`D_bad_input` withheld (this fact is discrete, that one is continuous).
+
+**Open, and a real conflict:** `on_error_message_change` is a single
+`attr_accessor` slot, and its rdoc says the container painting the message
+claims it — *"an app painting its own takes it instead."* A `FormLayout` that
+claims it silently at `add` therefore disables an app that already set it,
+which is the one-callback-slot failure `D_no_key_interceptor` names (all four
+composed fields hit it). Decide with the component: either the layout refuses
+to overwrite a non-nil slot, or it chains the previous callable, or the notice
+grows a subscriber list. Do not just assign it.
+
+## Facts it rests on, so they don't get re-derived
+
+- **A per-child attribute map is a solved shape.** `Box` keeps constraints in an
+  identity-keyed per-child map that is explicitly *not* a second copy of
+  ordering (`D_box_layouts`); a `FormLayout` holding `{field => caption}` copies
+  it. `Component::Slot` is the tree-native answer for a swappable region
+  (`D_slots`).
+- **It owes an `on_child_visibility_changed` override**, like `Box` — it is the
+  rule for any container with layout arithmetic (`D_visibility`). A conditional
+  form field is *the* consumer that brought `visible=` in, so a `FormLayout`
+  that skipped this would leave the hole in exactly the place it was built for:
+  the caption row and the message cells of a hidden field must go with it.
+- **Measuring captions does not reopen bottom-up sizing.** Aligning a caption
+  column needs the *container's own* strings measured — caller-side arithmetic,
+  the same move `Select` makes when it measures its labels and assigns the rect
+  (`D_select`; `D_box_layouts`' "`align:` is legal only because the cross extent
+  is caller-supplied"). It looks like the banned channel and isn't.
+- **The layout is the authority for caption↔field lookup**, since it holds the
+  only copy of the association — so it owes a locator
+  (`form.field_for(caption: "Name")`), which is what Karibu-Testing does against
+  Vaadin 25 form items. `Component#id` + `Tuile::Testing.get`
+  (`D_component_lookup`) is a *different* handle, not a replacement:
+  an id is a tag the app assigns.
+- **Top-down layout is the heaviest prior**, and it is what makes both halves
+  inline: a field is handed one row and cannot grow a second for a caption or a
+  message.
+
+## Still open
+
+- **Caption geometry** — caption column left (aligned, measured caller-side)
+  versus a row above. Inline-left is the natural pair to the inline-right
+  message; the row-above shape wants the message on a third row and reopens the
+  growth question.
+- **Required indicator — decided in shape, open in glyph.**
+  `FormLayout#add(field, caption:, required: true)` paints a **red dot beside
+  the caption**, as Vaadin does. `D_has_value` parked the indicator; this is
+  where it lands, and the field still does not know it is required.
+
+  Three things checked against Vaadin 25.2 rather than remembered, since they
+  shape the TUI version:
+
+  - Vaadin marks a required field *"with an indicator next to the label"* — so
+    the marker rides the **caption**, which in Tuile means it rides the
+    container, exactly as `D_caption_ownership` puts the caption there. The
+    precedent lines up; nothing to re-argue.
+  - Both the glyph and its color are style properties
+    (`--vaadin-input-field-required-indicator` /
+    `-color`, `::part(required-indicator)`), i.e. Vaadin treats *which* mark as
+    a theme choice, not a semantic. Tuile's equivalent question is whether the
+    dot's red is a reused `Theme#error_color` or a token of its own — a required
+    field is not (yet) *invalid*, and every `Theme` member is validated
+    `is_a?(Color)` with a hand-rolled `Theme.new` having to pass all of them, so
+    a new token is a breaking change to weigh, not a freebie.
+  - The docs also recommend *"an instruction text at the top of the form
+    explaining the required indicator"* — worth knowing that even Vaadin does
+    not consider the marker self-explanatory. In Tuile that legend is the app's
+    row, not the layout's (`D_status_bar`).
+
+  **The glyph is the one real Tuile problem, and it is the ambiguous-width bet
+  (`D_ambiguous_width`).** Measured with the gem: `•` U+2022 and `●` U+25CF and
+  `·` U+00B7 are all East-Asian **Ambiguous** — 1 column under Tuile's policy, 2
+  under ambiguous-as-wide, so each would enlarge the inventory that keeps the
+  bet cheap to reverse. `∙` U+2219 BULLET OPERATOR and `◦` U+25E6 measure **1
+  under both policies** and are the dots that cost nothing. So: default to `∙`
+  (or ASCII `*` with the dot as an opt-in knob, per the rule that a new
+  component defaults to ASCII when the pretty glyph is Ambiguous), and if the
+  marker becomes a knob it validates at assignment that it took one cluster one
+  column wide (`D_scrollbar_ink`).
+- **Helper text**, the other half of the seam `ideas/new-components.md` infra
+  item 2 names, is undesigned — and the inline-right cells are already spoken
+  for by the message.
+
+## Related
+
+`D_caption_ownership` and `D_has_validation` (**the two entries this note's
+first half graduated into** — read them first), `D_bad_input` (the field's own
+report, which reddens the same well), `ideas/binder.md` (the writer of
+`error_message`; the four-layer vocabulary), `D_on_blur` (the commit point a
+field can canonicalize from; the bad-input push notice that is still unbuilt),
+`D_date_field` (a field whose
+input outruns its value), `ideas/new-components.md` (infra item 2; Tier 2 Form
+Layout, Custom Field), `D_box_layouts` (the per-child attribute map;
+caller-supplied cross extent), `D_slots`, `D_select` (caller-side measurement),
+`D_status_bar` (no framework-reserved row), `D_no_key_interceptor` (one callback
+slot cannot be shared), `D_has_value` (the parked required indicator),
+AGENTS.md "Input values" (caption is chrome, text is value).