@ashley-shrok/viewmodel-shell 5.1.2 → 5.2.0

package/dist/index.d.ts

@@ -281,18 +281,62 @@ export interface FormNode {
     submitOnEnter?: boolean;
     children: ViewNode[];
 }
+/**
+ * Phase 21 (LOOK-01) — one reference in a `lookup` / `lookup-multiple` field:
+ * an id, optionally the label to show for it, optionally what KIND of thing it
+ * is. Used by BOTH `FieldNode.selected` (what is currently chosen) and
+ * `FieldNode.candidates` (the current search results) — the same shape in both
+ * places, which is what lets a picked value and an invented one stay
+ * homogeneous (see `allowCustom`).
+ *
+ * `value` is the id and the only thing that ever round-trips. It is typed as a
+ * `string` deliberately — not `string | number` — so the wire stays
+ * byte-identical across backends (the same rationale as `min`/`max`/`step`
+ * above): a numeric id serialized by System.Text.Json and by `JSON.stringify`
+ * must produce the same bytes, and a union invites exactly that drift.
+ *
+ * `label` is OPTIONAL and MUST be **omitted when it equals `value`** — an
+ * option not set is simply absent, and a label that merely repeats the id
+ * carries no information. This is exactly the free-form-tag case: a tag is a
+ * value whose label is itself, so the label is absent. (Salesforce models the
+ * same rule: `displayValue` is null for a plain string field and populated
+ * only when it carries something `value` doesn't — a localization, a format,
+ * or a related record's name.)
+ *
+ * `type` is the polymorphic-reference tag, and it exists because an id alone is
+ * not an identity. Microsoft, on Dataverse's `_ownerid_value`, verbatim: the
+ * GUID *"doesn't tell you whether the owner of the record is a user or a
+ * team."* Set it when one field can reference more than one kind of record;
+ * **omit it for monomorphic references**, where it would say nothing the field
+ * doesn't already say.
+ */
+export interface LookupItem {
+    /** The id. The only half that round-trips. */
+    value: string;
+    /** Display text for `value`. Omitted = the label equals the value. */
+    label?: string;
+    /** What KIND of record `value` names. Omitted = a monomorphic reference. */
+    type?: string;
+}
 export interface FieldNode {
     type: "field";
     name: string;
-    inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "code";
+    inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "lookup" | "lookup-multiple" | "code";
     /** Path into state where this input reads its current value and writes user
      *  changes (e.g. `fields.title`). REQUIRED for value-bearing inputs
      *  (text/email/password/number/date/time/datetime-local/textarea/select/
-     *  select-multiple/checkbox/code) and OPTIONAL for `file` inputs — a file
+     *  select-multiple/checkbox/lookup/lookup-multiple/code) and OPTIONAL for
+     *  `file` inputs — a file
      *  input's binary rides the multipart side channel (fileRegistry keyed on
      *  `name`), so omit `bind` on a file input to avoid writing a
      *  `{filename,size}` placeholder object into state (which breaks a
-     *  string/string-map state slot on round-trip). */
+     *  string/string-map state slot on round-trip).
+     *
+     *  For the lookup inputTypes this path holds the ID and NOTHING ELSE:
+     *  `lookup` binds a `string` (one id), `lookup-multiple` binds a `string[]`
+     *  (the ids). The human-readable label never lives here — it travels on
+     *  `selected`, server→client only (see the `selected` doc). The id is state;
+     *  the label is view. */
     bind?: string;
     label?: string;
     placeholder?: string;
@@ -310,7 +354,27 @@ export interface FieldNode {
      *  `.vms-field--error`, the control's `aria-invalid="true"`, and wires the
      *  message into `aria-describedby`. The view-side complement to the
      *  response-level `rejected` channel — set it on the offending field when you
-     *  build the tree. Omitted = no error shown. */
+     *  build the tree. Omitted = no error shown.
+     *
+     *  **Lookup note (5.2.0, OPEN-5): a SEARCH failure reuses this slot** — if the
+     *  directory query behind a `lookup` / `lookup-multiple` fails, put the message
+     *  here. Do NOT swallow it: react-select actively discards fetch errors
+     *  (`loader.then(callback, () => callback())`), which makes a dead backend
+     *  indistinguishable from "no results" — a direct violation of principle 8
+     *  (nothing important fails quietly), and no surveyed library has a
+     *  search-error state at all. Reusing `error` closes that gap at zero wire
+     *  cost, and §7 item 9 reserves the assertive channel for errors, so a genuine
+     *  search failure is a correct fit for this slot's `role="alert"`.
+     *
+     *  ⚠️ **The known, accepted wart:** this overloads the slot. "The server is
+     *  down" is NOT "your input is invalid", so the `aria-invalid="true"` it sets
+     *  on the combobox is semantically wrong for a search failure; and one slot
+     *  with two meanings COLLIDES if a field has a live search failure and a
+     *  pending validation error at once (last writer wins). Accepted for v1: the
+     *  app owns which message it puts here, the collision needs both conditions
+     *  simultaneously on the same field, and a distinct search-error slot is
+     *  purely additive later. Recorded rather than hidden, so a future phase can
+     *  promote it with the reasoning already written down. */
     error?: string;
     /** Hint/help text rendered below the control as `.vms-field__help` and wired
      *  into the control's `aria-describedby`. Omitted = no hint. */
@@ -330,6 +394,198 @@ export interface FieldNode {
         value: string;
         label: string;
     }>;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-01). What is currently chosen, resolved
+     * to display text by the server.
+     *
+     * 🚨 **THE LOAD-BEARING INVARIANT: `selected` is VIEW, not STATE.** It travels
+     * **server→client ONLY**, is recomputed on every render, and is **NEVER
+     * authoritative and NEVER trusted coming back from the client.** `bind` holds
+     * the id and is the only authoritative thing. **Direction is the entire safety
+     * argument** — a client cannot forge a label into a handler because a client
+     * never sends one. Why, from our own principles: the view is a pure function
+     * of state; the id persists and round-trips (state), while the label is
+     * derived, server-owned, and recomputed every render (view). Putting the label
+     * in the bind is putting view into state, and it manufactures a
+     * cache-invalidation problem that every mature enterprise reference field
+     * designed away by storing the id alone — rename a user and every label on
+     * every referencing record changes with zero writes.
+     *
+     * 🚨 **`selected` and `candidates` are SEPARATE FIELDS ON PURPOSE, and the
+     * selected label is NEVER resolved from `candidates`.** Fusing them is the
+     * original sin. With an id-valued field, *"filter the candidate list"* and
+     * *"forget what's selected"* are **the same operation** — so a picker that
+     * resolves its label out of the candidate list renders a raw database id the
+     * moment a form loads with a value already set and no search has occurred
+     * (the cold-start case, which is the case that matters most). Ant Design ships
+     * this failure silently (`label: ... ?? item.value`); Zag chased it across
+     * four changelog entries and two years. Read the label from `selected` and
+     * only from `selected`.
+     *
+     * **Always an array**, including for single `lookup`, where it holds 0 or 1
+     * entries. This is deliberate and there is no precedent for it elsewhere in
+     * this file, so the reasoning lives here: a `T | T[]` union drifts across
+     * backends (it does not serialize byte-identically under both
+     * System.Text.Json and `JSON.stringify`), and the banked parity lesson is to
+     * prefer the shape that cannot drift over the shape that reads nicer.
+     *
+     * `selected[].value` duplicating `bind` is **accepted, deliberate
+     * redundancy** — keying by value is robust; positional parallel arrays are
+     * not.
+     *
+     * Omitted = nothing currently selected.
+     */
+    selected?: LookupItem[];
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-01). The current search results — what
+     * the popup listbox offers. Feeds the popup and **nothing else**. **NEVER the
+     * source of a selected label** (see `selected`).
+     *
+     * 🚨 **ORDER IS MEANINGFUL APP DATA. The renderer presents candidates AS
+     * GIVEN — it sorts nothing, dedupes nothing, and truncates nothing.** The app
+     * decides what comes back and in what order; **relevance ordering is the
+     * SERVER's judgment, never the widget's.** This is universal in mature
+     * pickers: Salesforce's picker `searchType` **defaults to `Recent`**, and
+     * Dynamics shows the five most-recently-used rows plus five favourites,
+     * explicitly NOT filtered by the search term. A renderer that "helpfully"
+     * alphabetized for tidiness would **silently destroy a server-side ranking
+     * with no way for the app to stop it** — a real consumer sorts candidates by
+     * recency-weighted mention frequency in their own provider handler, and that
+     * ranking is the whole product. (Scope: this governs the PRESENTATION of
+     * `candidates`. It is not a ban on the renderer having logic — deduping
+     * `bind` on commit in `lookup-multiple` is a state write about the user's own
+     * accumulated selection, and is correct.)
+     *
+     * 🚨 **Any cap MUST be VISIBLE in the tree. Nothing truncates silently.**
+     * There is no wire field for a cap: the app renders a `TextNode` saying so —
+     * *"Refine your filter — N matches, max is X"*, the canonical table-workflow
+     * pattern. The anti-pattern is ServiceNow's 15-result cap applied post-ACL
+     * behind a hard 250-row SQL ceiling, where **an exact-match record can be
+     * silently invisible** in a large table. A cap the user cannot see is a
+     * correctness bug wearing a performance knob's clothes.
+     *
+     * 🚨 **The picker's filter is UX, NEVER authorization.** Narrowing what is
+     * *offered* is not a security boundary, and a filter that looks like one is
+     * precisely what gets trusted by mistake. ServiceNow says it outright: *"To
+     * restrict what data specific users can access, use ACLs not reference
+     * qualifiers."* Salesforce runs two separate layers for exactly this reason —
+     * a metadata `lookupFilter` enforced server-side on save, versus the
+     * component's UI-only `filter`. **The server authorizes in the action
+     * handler, with the real auth context, exactly as every other VMS action
+     * does.** Omitting a record from `candidates` hides it from the dropdown and
+     * from nothing else — a client that already knows an id can still put it in
+     * `bind`, so the handler is the only thing standing between a user and a
+     * record they may not touch.
+     *
+     * Omitted = no results to offer.
+     */
+    candidates?: LookupItem[];
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-04). Path into state where the typed
+     * query lives, so the server can see it and the view stays a pure function of
+     * state. Separate from `bind`, which holds the id — the query and the
+     * selection are different facts and never share a slot.
+     *
+     * Required for a working search: with a `searchAction` but no `searchBind`,
+     * the query is dispatched but the server can never read what was typed — a
+     * silently dead search that renders perfectly and returns nothing forever. The
+     * browser warns `[vms:lookup-no-searchbind]`.
+     *
+     * Keystrokes write here immediately (the query is state); **Enter** dispatches
+     * `searchAction`. That is the same cadence `TableNode.filterAction` uses.
+     *
+     * 🚨 The query is what the user TYPED. It is **not** the display text: an
+     * input showing the selected label (a form loaded with a reference already
+     * set) holds a label, not a query, and the renderer does not flush it here.
+     * Clearing the box clears the query and reveals the label again — clearing the
+     * SEARCH TEXT is not clearing the SELECTION (only `bind` holds that).
+     *
+     * Omitted = the query is not round-tripped.
+     */
+    searchBind?: string;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21). Dispatched **on ENTER**, as an **ordinary
+     * action** — the same cadence `TableNode.filterAction` uses, and the same one
+     * `action` above uses. Keystrokes write `searchBind` and dispatch nothing;
+     * there is **no debounce** and **no live-query lane**.
+     *
+     * 🚨 **`blocking` means exactly what it means everywhere else, and the
+     * framework NEVER sets it.** Your `ActionEvent` is dispatched as you declared
+     * it — omit `blocking` (the default, blocking/serialized lane) unless you have
+     * a specific reason not to.
+     *
+     * **Leaving it blocking is the recommended default, and it is a correctness
+     * property, not a preference:** a blocking action is serialized by the shell's
+     * dispatch guard (a second action cannot dispatch while a round trip is in
+     * flight), so a stale search response can never land after — and clobber — a
+     * newer action. Opting into `blocking: false` means *this response may be
+     * discarded, may arrive out of order, and may coexist with another in flight*;
+     * that is yours to choose, and yours to handle.
+     *
+     * 🚨 **Do NOT combine with {@link FieldNode.allowCustom} — it is UNSUPPORTED
+     * in v1 and warns `[vms:lookup-ambiguous-enter]`.** One Enter cannot both
+     * invent a value and run a search. The two supported shapes are: this field
+     * WITHOUT `allowCustom` (a directory/reference picker — Enter searches,
+     * arrow+Enter accepts a candidate), or `allowCustom` WITHOUT `searchAction`
+     * (a free-form tags field — Enter invents). Declaring both is ignored in
+     * favour of the search, loudly.
+     *
+     * ⚠️ **`searchAction` OCCUPIES Enter, so {@link FieldNode.action} is
+     * unreachable on a lookup that declares one.** This is a deliberate
+     * limitation, not a bug: Enter is this control's only dispatch key and the
+     * search owns it — there is no second Enter to give `action`, and inventing a
+     * second submit gesture is a keybinding no combobox pattern sanctions. **On a
+     * searching lookup, put the submit on a `ButtonNode`.**
+     *
+     * **There is NO minimum-character gate**, deliberately. **An EMPTY query is a
+     * legitimate query and IS dispatched**, so an app may answer it with
+     * most-recently-used candidates rather than nothing (Salesforce's picker
+     * `searchType` defaults to `Recent`).
+     *
+     * Omitted = no search; the field is a plain id input.
+     */
+    searchAction?: ActionEvent;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-06). The **declared** custom-entry axis:
+     * may the user commit a value that isn't one of the offered candidates?
+     *
+     * **Never inferred from behavior.** *Choosing somebody to mention* is very
+     * different from *inventing a new tag* — different ACTS sharing one widget —
+     * so the control DECLARES which it is doing rather than leaving it to be
+     * guessed from what the user typed.
+     *
+     * An invented value stays a homogeneous {@link LookupItem}, **never a bare
+     * string**, so no `LookupItem | string` union ever arises. MUI's `multiple +
+     * freeSolo` yields exactly that heterogeneous union — forcing every consumer
+     * to branch on `typeof`, and their own docs warn it *"may cause type
+     * mismatch."* We never admit a bare string, so it cannot happen here. A
+     * free-form tag is simply a value whose label equals itself (and is therefore
+     * omitted — see {@link LookupItem}).
+     *
+     * ⇒ `allowCustom: true` + no `candidates` + labels omitted **is a free-form
+     * tags input, with NO special case in the renderer.** This supersedes the
+     * separately-designed `inputType: "tags"` proposal.
+     *
+     * 🚨 **Do NOT combine with {@link FieldNode.searchAction} — it is UNSUPPORTED
+     * in v1 and warns `[vms:lookup-ambiguous-enter]`.** Type "urgent", press
+     * Enter: invent the tag, or search for it? Both are legitimate readings of the
+     * same keystroke, and no precedence serves both (invent-first starves the
+     * search; search-first starves invention forever) — that there is no good
+     * ordering is the tell that the shape is wrong, so v1 does not guess.
+     * Suggestions on a tags field are deferred, exactly as the parked `tags`
+     * design already deferred them. Declaring both ignores `allowCustom`.
+     *
+     * Whether a given value was picked or invented is **server-decidable** — the
+     * server produced every candidate it ever offered, so it can test the id
+     * against its own id space. There is deliberately no wire marker for
+     * provenance (no `__isNew__`): react-select needs one because it is
+     * client-only and has no server to ask; we have a server. The explicitness
+     * this decision demands is satisfied by `allowCustom` being a declared axis on
+     * the node — the app declares the act — not by a per-value flag.
+     *
+     * Omitted = false (custom entries rejected; only offered candidates commit).
+     */
+    allowCustom?: boolean;
     /** Optional language hint for `inputType: "code"`. Emitted as a class
      *  (`vms-field--code-{language}`) so apps can attach a syntax-highlighter
      *  library (CodeMirror, Monaco, etc.) — the framework only ships

package/dist/server.js

@@ -107,6 +107,12 @@ function collectActions(node, enclosingForm, out) {
             const field = node;
             if (field.action)
                 recordAction(field.action, enclosingForm, out);
+            // Phase 21 (LOOK-01) — a lookup's debounced search is a real dispatch to a
+            // real handler, so its name participates in uniqueness like every other
+            // dispatch site. `action` and `searchAction` are independent: a lookup may
+            // carry both (Enter commits, typing searches).
+            if (field.searchAction)
+                recordAction(field.searchAction, enclosingForm, out);
             return;
         }
         case "checkbox": {

package/dist/tui.js

@@ -1254,6 +1254,26 @@ function FormView({ node, ctx }) {
 //                                B3 ships single-select; select-multiple semantics
 //                                are deferred (no native OpenTUI multi-select
 //                                widget; would need a custom focusable list — B5).
+//   lookup / lookup-multiple  → <text label> + <input value=the ID at `bind`> +
+//                                a <text> line listing the `selected` labels
+//                                (label ?? value, per the wire's "label omitted
+//                                = label equals value" rule). Both inputTypes get
+//                                the SAME layout; lookup-multiple joins its
+//                                selected labels with ", ".
+//                                🚨 The debounced `searchAction`, the popup
+//                                listbox, the chips, the roving tabindex, and the
+//                                aria-live region are DELIBERATELY NOT ported.
+//                                This is the ARCHITECTURE WORKING AS DESIGNED,
+//                                not a gap: `bind` holds the id and nothing else,
+//                                so — per the lookup design of record §6 — "an
+//                                agent sets `bind` to the id and never touches the
+//                                search UI. It does not need to know the label."
+//                                A terminal user does exactly what an agent does.
+//                                Everything omitted here is a browser/DOM concept
+//                                with no OpenTUI analog (the a11y spec is a
+//                                screen-reader contract that means nothing in a
+//                                terminal). Same honest-degradation precedent as
+//                                select-multiple → single-select above.
 //   checkbox                  → <text "[x] label" or "[ ] label"> — decorative
 //                                for B3 (toggle interactivity in B5).
 //   file                      → <text "{label}: [file: …]"> placeholder —
@@ -1327,6 +1347,27 @@ function FieldView({ node, ctx }) {
                         handleSubmit(next);
                     } }, `${node.name}::wire::${wireValue}`)] }));
     }
+    // ── lookup / lookup-multiple: honest degradation to a bound id input ───
+    // See the per-inputType layout contract in the header comment above for WHY
+    // this is a complete implementation for the terminal rather than a stub: the
+    // id is the only thing that round-trips, and typing it directly is precisely
+    // the agent-drivable path the design of record §6 describes. No search
+    // machinery is ported (no debounce, no searchAction dispatch, no popup, no
+    // chips, no live region) — those are DOM concepts, and the a11y baseline they
+    // implement is a screen-reader contract with no terminal meaning.
+    if (node.inputType === "lookup" || node.inputType === "lookup-multiple") {
+        // Read the display text from `selected` and ONLY from `selected` — never
+        // from `candidates`. That is the load-bearing invariant of the whole
+        // primitive (the label is view, server-owned, recomputed every render;
+        // `candidates` is the search result set and says nothing about what is
+        // currently chosen). `label ?? value` implements the wire rule that a label
+        // equal to its value is omitted — a free-form tag shows as its own id.
+        const selectedLabels = (node.selected ?? []).map((s) => s.label ?? s.value);
+        const selectedLine = selectedLabels.length > 0 ? selectedLabels.join(", ") : "(none selected)";
+        return (_jsxs("box", { flexDirection: "column", gap: 0, children: [_jsx("text", { fg: "#888888", children: label }), _jsx("input", { value: currentValue, placeholder: node.placeholder ?? "", focused: focused, onInput: (v) => ctx.setFieldValue(node.name, v), onSubmit: (v) => {
+                        handleSubmit(typeof v === "string" ? v : undefined);
+                    } }, `${node.name}::wire::${wireValue}`), _jsxs("text", { fg: "#888888", children: ["Selected: ", selectedLine] })] }));
+    }
     // ── checkbox: decorative glyph for B3 (toggle wiring is B5) ───────────
     if (node.inputType === "checkbox") {
         // Wire contract: checkbox-typed field's value is "true" | "false".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",

package/styles/default.css

@@ -574,6 +574,231 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   overflow: auto;
 }
 
+/* Lookup / reference picker (FieldNode inputType="lookup" / "lookup-multiple",
+   Phase 21) — an editable combobox whose listbox popup floats over the page.
+   Built entirely from the existing .vms-field__* tokens: no new colors, no new
+   custom properties, so every theme recolors it automatically. */
+.vms-field--lookup { position: relative; }
+.vms-field__popup {
+  /* Anchored to .vms-field--lookup's positioning context, floating over what
+     follows so the popup never reflows the form when it opens. */
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  z-index: 20;
+  margin-top: var(--vms-space-2xs);
+  max-height: 16rem;
+  overflow-y: auto;
+  background: var(--vms-surface);
+  border: 1px solid var(--vms-border);
+  border-radius: var(--vms-radius);
+  /* A literal rgba, matching the toast overlay's shadow (the house precedent
+     for a floating surface) — there is no --vms-shadow token, and inventing
+     one would mean touching all 12 themes for a drop shadow. */
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.24);
+  color-scheme: var(--vms-color-scheme);
+}
+/* The popup is rendered ALWAYS and hidden when closed (aria-controls must stay
+   valid while hidden). This rule is LOAD-BEARING: the UA's [hidden] default is
+   display:none, but the block above would otherwise win on specificity and the
+   popup would be permanently visible. */
+.vms-field__popup[hidden] { display: none; }
+/* The lookup's aria-live status regions and its assistive hint: available to
+   assistive tech, invisible on screen. Deliberately NOT display:none and NOT
+   visibility:hidden — both REMOVE the element from the accessibility tree, so a
+   live region styled that way is never announced and the hint is never read.
+   This is the standard visually-hidden clip; it must stay clipped-but-rendered. */
+.vms-field__live {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.vms-field__option {
+  padding: var(--vms-space-xs) var(--vms-space-md);
+  font-size: var(--vms-text-md);
+  line-height: var(--vms-control-line);
+  color: var(--vms-text);
+  cursor: pointer;
+  /* §7 item 33 (reflow) — option text WRAPS rather than truncating: a
+     candidate is a person's or record's name, not a status word, and at high
+     magnification a truncated option is unreadable. The border delimits a
+     wrapped option so it never reads as two separate suggestions (GOV.UK's 12x
+     tester: "the words just looked like separate suggestions that didn't make
+     much sense"). */
+  overflow-wrap: anywhere;
+  border-bottom: 1px solid var(--vms-border);
+}
+.vms-field__option:last-child { border-bottom: none; }
+.vms-field__option:hover { background: var(--vms-surface-2); }
+/* The active (aria-activedescendant) option. DOM focus stays in the input, so
+   :focus cannot express this — the highlight must be driven off aria-selected,
+   which is the same fact the live region announces. */
+.vms-field__option[aria-selected="true"] {
+  background: var(--vms-accent-glow);
+  color: var(--vms-text);
+}
+
+/* ── lookup chips (Phase 21, LOOK-03; BOTH modes since 21-14 / D2a) ──
+   The selection, rendered OUTSIDE the combobox as chip(s) — for `lookup` AND
+   `lookup-multiple`, from ONE implementation. The only difference between the
+   two is arity (single replaces on pick, multi appends), which lives in
+   browser.ts and has no expression here at all: a chip is a chip.
+
+   🚨 We diverge from SLDS deliberately and it is worth knowing why, because the
+   survey says the opposite: Salesforce renders single-select's selection INSIDE
+   the input and ships no pill element for single at all. 21-13 followed them,
+   and the operator found that model has NOWHERE TO CLICK TO TYPE — the pill was
+   the input, so clicking in just appended to the name. Their model is coherent
+   given clear-then-search; ours is coherent given always-typeable. (There is no
+   `.vms-field--lookup-selected` any more; do not resurrect it.)
+
+   Structure is role=list/listitem + a real <button> (design §7 item 24) — see
+   browser.ts. This is presentation only; nothing here is on the wire.
+
+   ⚠️ CONTRAST: the chip's fg/bg pair is NOT covered by the fixed 13-pair
+   check:aa-contrast gate, so it is hand-measured across the shipped default +
+   all 12 themes: 10.63:1 worst (dark-*), 13.60:1 (light-*), vs a 4.5:1 text bar.
+   Single-select reuses this exact pair rather than inventing a token, so it adds
+   no new pair to measure. Re-measure if --_chip-tone ever stops being
+   --vms-text. */
+.vms-field__chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--vms-space-2xs);
+  /* Reset the <ul>. NOTE this is exactly why browser.ts sets role="list"
+     EXPLICITLY: `list-style: none` strips the implicit list/listitem roles in
+     Safari/VoiceOver, so a styled <ul> silently stops being a list — the
+     accessibility regression is caused BY this line and repaired in the
+     renderer. Do not "clean up" that seemingly-redundant role. */
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.vms-field__chip {
+  /* The .vms-badge private-tone technique (default.css, .vms-badge): ONE private
+     custom property holds the working color and the fill, text and border all
+     derive from it, so EVERY THEME RECOLORS AUTOMATICALLY — --vms-text and
+     --vms-surface are theme-owned. Retoning a chip would be one line. */
+  --_chip-tone: var(--vms-text);
+  display: inline-flex;
+  align-items: center;
+  /* Hug content in ANY parent layout. Carried over from .vms-badge's comment
+     (written in 5.1.2 for exactly this failure mode) because the chip hits it
+     IDENTICALLY: a chip is semantically inline, but as a flex item it is
+     BLOCKIFIED (inline-flex → flex) and the chip row's align-items would then
+     stretch it. A definite cross-size opts out of that stretch —
+     align-items:stretch only stretches items whose cross size is `auto`.
+     Deliberately NOT align-self:start, which would top-anchor the chip since a
+     child's align-self beats the parent's align-items. */
+  width: fit-content;
+  max-width: 100%;
+  gap: var(--vms-space-2xs);
+  font-size: var(--vms-text-xs);
+  font-weight: 600;
+  /* Not the badge's `1`: a chip's text WRAPS (below), and line-height:1 makes
+     wrapped lines collide. */
+  line-height: 1.35;
+  /* Tighter on the right — the remove button carries its own hit area. */
+  padding: 0.2em 0.3em 0.2em 0.6em;
+  border-radius: 999px;
+  /* 🚨 DELIBERATELY NOT `white-space: nowrap` — the ONE thing not copied from
+     .vms-badge, and the easiest to reintroduce by "consistency". Design §7 item
+     33: chip text must WRAP WITHOUT TRUNCATION. A badge is a short status word;
+     a chip holds a PERSON'S NAME. GOV.UK's 12x-magnification tester on the
+     truncation failure: "Some larger country names may take over two lines. It
+     wasn't always clear to him that this had happened — the words just looked
+     like separate suggestions that didn't make much sense." The pill border-
+     radius + the surface knockout are what delimit a wrapped chip so it never
+     reads as two. (The popup's options carry the same rule and their own
+     delimiting border — see .vms-field__option.) */
+  overflow-wrap: anywhere;
+  /* The polarity-adaptive knockout — the house technique, used 18x in this file.
+     Mixing TOWARD --vms-surface (never toward white/black) auto-adapts to light
+     AND dark themes with ZERO per-theme deepening.
+     ⚠️ PROVISIONAL MIX RATIO — 12%, not the badge's 16%, and Plan 21-09's
+     hand-check owns the final number. Two reasons it must not simply inherit
+     16%: (1) the fg/bg pair here is a NEW one the fixed 13-pair check:aa-contrast
+     gate does NOT auto-cover; (2) the badge's 16% was tuned for a small badge on
+     a PAGE surface. This is deliberately conservative — the tone is --vms-text
+     (near-maximal contrast against a 12% tint of ITSELF in the surface), not the
+     badge's --vms-text-muted, because a chip carries CONTENT (a name) rather
+     than muted status. The chip's background is opaque, so the field's input
+     backdrop does not enter the contrast pair. */
+  background: color-mix(in srgb, var(--_chip-tone) 12%, var(--vms-surface));
+  color: var(--_chip-tone);
+  border: 1px solid transparent;
+}
+/* §7 item 31 — the two-step Backspace's ARMED chip: the first press highlights
+   the last chip rather than deleting it. This is the VISUAL half only; the
+   announcement is the half that matters (browser.ts), because an arm that were
+   only a CSS class would leave an AT user pressing Backspace, hearing nothing,
+   pressing again, and deleting something they were never told about. Border, not
+   a fill swap, so it cannot disturb the contrast pair above. */
+.vms-field__chip--armed { border-color: var(--_chip-tone); }
+.vms-field__chip-remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  /* Never let the button shrink or wrap away from its label — the chip's text
+     wraps; its remove affordance must not. */
+  flex: none;
+  align-self: flex-start;
+  width: 1.4em;
+  height: 1.4em;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  /* Inherit the chip's tone rather than re-deriving it, so a retoned chip keeps
+     a consistent remove button for free. */
+  color: inherit;
+  font-family: inherit;
+  font-size: 1.1em;
+  line-height: 1;
+  cursor: pointer;
+}
+.vms-field__chip-remove:hover {
+  background: color-mix(in srgb, var(--_chip-tone) 22%, transparent);
+}
+/* The chip is INTERACTIVE where the badge is inert, so its remove button needs a
+   visible focus ring: it is a REAL focusable button (§7 item 26 gives the chips a
+   roving tabindex precisely so DOM focus lands here), and it is reachable by
+   keyboard alone. :focus-visible, so a mouse click doesn't ring it.
+
+   🚨 DELIBERATELY --_chip-tone, NOT --vms-accent (which is what
+   .vms-field__input:focus uses, and what this rule used before Plan 21-09's
+   hand-check). Measured, not assumed: --vms-accent clears the 3:1 non-text bar
+   (SC 1.4.11) against --vms-surface on all 13 targets, but only BARELY on
+   light-amber/light-green/light-teal (3.34 / 3.23 / 3.28). The chip's fill is a
+   TINTED surface, and that tint eats the entire remaining margin — the accent
+   ring measures 2.63 / 2.54 / 2.58 against the chip fill on those three themes:
+   a FAILING focus indicator on a keyboard-only affordance.
+
+   The mix ratio is NOT the lever, which is the non-obvious part: the ring still
+   fails at a 4% tint and only reaches 3.10:1 at 2% — a chip with no visible fill
+   at all. No chip worth rendering can rescue the accent here.
+
+   --_chip-tone is the structural fix and needs no per-theme rule: it is the same
+   polarity-adaptive knockout pair as the chip's TEXT (mixing toward
+   --vms-surface), so it inherits that pair's measured headroom — 10.63:1 worst
+   (dark-*), 13.60:1 (light-*), vs a 3:1 bar. It is also what the chip's own
+   private-tone technique already does everywhere else: .vms-field__chip--armed
+   borders with it and this button's `color` inherits it. The accent ring was the
+   outlier, not the convention. Re-measure if --_chip-tone ever stops being
+   --vms-text. */
+.vms-field__chip-remove:focus-visible {
+  outline: 2px solid var(--_chip-tone);
+  outline-offset: 1px;
+}
+
 /* Form-collected checkbox (FieldNode inputType="checkbox") — inline label. */
 .vms-field--checkbox { flex-direction: row; align-items: center; gap: var(--vms-space-xs); }
 .vms-field--checkbox .vms-field__input {