From 2ef24539f9a5bd51676c35224f08a1a21af0b0e6 Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 31 Aug 2026 12:51:24 +0800 Subject: [PATCH] docs: record the two-channel input rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four things the parameter panel settled that the next input channel should not have to rediscover: where the channels meet, why a drag clamps while a field refuses, why a focused field owns its own text, and why reset disables rather than deletes. The clamp/refuse split is the one most likely to be reported as an inconsistency. It is one invariant with two honest expressions — a pointer cannot state an intent it never reached, so it stops; typed text is an intent, so rewriting it hides a typo behind a plausible number. Co-Authored-By: Claude Opus 5 (1M context) --- .trellis/spec/frontend/direct-edit-client.md | 82 ++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/.trellis/spec/frontend/direct-edit-client.md b/.trellis/spec/frontend/direct-edit-client.md index 4bde685..24d02a7 100644 --- a/.trellis/spec/frontend/direct-edit-client.md +++ b/.trellis/spec/frontend/direct-edit-client.md @@ -152,6 +152,84 @@ say so. --- +## 11. Two input channels, three shared exits + +A value can come from a drag or from a number field. They differ only in how the +scalar is produced and when the gesture closes; everything downstream is shared: + +| Exit | Meaning | +| --- | --- | +| `draftValue(handle, value)` | preview, do not commit | +| `settleValue(handle, value)` | one undoable command, or abandon if it drafts nothing | +| `abandonGesture()` | release the id, clear live overrides, re-preview the settled state | + +`EditSession` needs no change to accept a second channel: `gestureIdentity()` is +minted lazily by the first draft and released by `commitGesture()`, so `focus` / +`blur` land on the same boundary `pointerdown` / `pointerup` already used. That is +what makes typing `1.53` one undo step instead of four. + +**Forbidden**: a second preview path, debounce, or undo stack per input device. + +--- + +## 12. Continuous input clamps; discrete input refuses + +The invariant is shared — a constraint value never leaves `[min, max]` — but the +two devices express it differently. + +- A drag **clamps**. A pointer cannot state an intent it never reached, and the + handle has to stay on a road shape that can exist (§3). The clamp is visible in + the moment: the handle stops while the cursor keeps going. +- A number field **refuses**: mark it invalid, send no preview, add no undo step, + keep the last valid preview. Typed text *is* an intent, so rewriting it is a + retroactive edit — and the failure modes are asymmetric. A clamped typo (24 + becoming 5.4) reads as a plausible value and can go unnoticed; a refusal cannot. + +Offer the extremes as one click, but round them **inward**: a real max of `2.925` +renders as `2.93` under nearest-rounding, which the range it came from rejects. +`formatBoundInward()` exists for this. + +**Mistake made**: the first draft of the panel displayed and filled +`formatParameterValue(min)`, which produced a value its own range check refused. + +--- + +## 13. A field being typed in owns its own text + +Every settled preview replaces the manifest, so a controlled input bound to +`handle.value.current` is rewritten mid-keystroke: typing `1.` fires a preview for +`1`, and the response resets the field to `1`, dropping the decimal point. + +The field therefore holds local text while focused and follows the manifest only +when it is not: + +```ts +value={text ?? formatParameterValue(handle.value.current)} +``` + +There is no second number to reconcile: `numericValue()` in the solver reads the +constraint back out, so `value.current` is the request echoed, never a solved +substitute. Seed the local text from what is on screen at focus, not from the +manifest — after a drag the row can legitimately be ahead of the last settled +preview. + +--- + +## 14. Reset disables the constraint; it does not delete it + +`validateEditDocument()` rejects an operation whose `constraintIds` name a +constraint that is not in the document, so removing one would mean recording an +operation about nothing. Setting `enabled: false` is what design.md already +sanctions for undoing saved work, and `constraintFor()` skips disabled +constraints, so the handle comes back without a `constraintId` and the row reports +itself unmodified again. + +This is the one edit a drag cannot express: a drag can set a value, never withdraw +one. `handle.constraintId` — present only when a constraint exists — is also how +"untouched" is told apart from "explicitly set to the baseline number". + +--- + ## Checklist before committing edit-client changes - [ ] No baseline source is written @@ -162,3 +240,7 @@ say so. - [ ] No geometry or OL reads inside a `setState` updater - [ ] No per-`pointermove` React state updates - [ ] Flag off ⇒ no sources, no layers, no interactions, no requests +- [ ] Every input channel meets at the shared exits, not a parallel path +- [ ] Displayed bounds round inward, so an offered extreme is accepted +- [ ] A focused field is not rewritten by an arriving preview +