dsh-model-flatmap 1.0.3 → 1.1.0

package/docs/DETAIL.md

@@ -195,6 +195,126 @@ and the agent teamwork switch are all visible at once.
   the shared footer line described under *Reasoning levels*, immediately right
   of the reasoning group when both fit on one line.
 
+## The trigger
+
+The trigger is the same chip the shipped picker draws (13/20 regular, 28 px,
+rounded-sm), and it shows the same *content* — which is more than a model name.
+
+**The name is a slot, not a string.** The shipped `ModelSelect` does not paint
+`model.name` on its trigger: it renders `conversation.input.model.label` with
+`placement: 'trigger'` and lets the winning contributor decorate the name. That
+is where a connection plugin puts things the catalog does not carry: a promotion
+chip (`夜间折扣`), a rate, a "new on this machine" marker, and — in the case of
+`dsh-connect-workbuddy` — a load mark: one, two or three queued people, or a
+rocket when nothing is waiting. A bare name therefore shows strictly less than
+the native trigger, which is what this plugin used to do.
+
+**This plugin renders that slot's winner.** It cannot *declare* the child slot
+(the shipped entry already did, and a second declaration throws
+`already declared`) — but declaring is not needed to read it. The declaration
+outlives the shadowing entry, so `slots.entriesOfSlot('conversation.input.model.label')`
+still names the winning entry, and its `component` can be rendered with the
+seats the renderer would have supplied:
+
+- `t` — bound from the entry's own `locale` namespace through `locale.bind(ns)`;
+- the business face — `entry.inject(sessionId)`, the renderer's own contract for
+  a session-scoped entry;
+- the owner props — `{ provider, model, placement: 'trigger', selected: true }`,
+  exactly the share the shipped picker passes.
+
+**The occupant is third-party code, so it is contained.** It runs without the
+renderer's per-entry error boundary, so a separate `LabelBoundary` wraps it. A
+crash costs the decoration and never the seat: the boundary answers `undefined`
+and the trigger falls through to the catalog name. The failure is logged once.
+
+**No occupant still gets the catalog badge.** When the cell is empty — or the
+occupant is absent, crashed, or on a Host without `entriesOfSlot` — the trigger
+draws the shipped fallback: the model's own `model.badge` as a chip before the
+name. This is reproduced rather than imported (the host's `Tag` lives in a
+primitives package this plugin does not depend on), and it matters even with an
+occupant installed: an occupant that does not reproduce a sibling's `model.badge`
+would otherwise lose the promotion marker.
+
+**Registrations that land late still appear.** The trigger subscribes to the
+slot through `slots.subscribe(key, fn)` / `slots.getVersion(key)`, so a
+connection plugin that registers a moment after boot gets its chip on the
+trigger without a page reload. A Host without those accessors keeps the first
+read and never notifies.
+
+Because native mode (below) hands the seat to the Host, which renders the same
+slot, the trigger is now *one* implementation in both modes — the consistency
+this feature exists for.
+
+## Native mode
+
+The footer's trailing `默认样式` / `Default style` button hands the composer's model seat
+back to whatever the Host ships in `conversation.input.model`, and back again.
+
+**How the switch works.** The plugin does NOT render the host's control — it
+stops shadowing it. This entry registers at a negative priority, so it wins the
+`single` slot; a `single` slot keeps every registration and renders only the
+highest-priority live one. Native mode therefore `dispose()`s this plugin's
+entry, which elects the shipped one underneath: the host mounts its own
+`ModelSelect`, whatever that is in the installed version. Nothing is imported,
+copied, or re-mounted, so an upgraded DSH shows its own newest picker and this
+mode structurally cannot drift out of date.
+
+The alternative — pulling the shipped component into our own tree — is not
+available: the `model-selection` package exports no component, and every
+`renderSlot` child (`conversation.input.model.label` / `.options`) is bound to
+the entry that declares it, so another entry calling it throws
+`StaleAuthorizationError` / `SlotOwnershipError`. See DEC-027.
+
+**Stepping aside is verified, never assumed.** Before disposing, the plugin asks
+`slots.entries('conversation.input.model')` for the registrations other than its
+own. If there is none — the shipped package disabled, uninstalled, or a Host too
+old to enumerate entries — the panel stays mounted and the button reads disabled
+with a tooltip explaining why. A persisted `native` mode from a previous install
+therefore lands on the flat panel instead of an empty composer.
+
+**The way back.** Native mode disposes the entry that owns the footer button, so
+the button cannot switch back. The return trip instead rides the HOST picker's
+own panel: `conversation.input.model.options` is the list child slot the shipped
+`ModelSelect` declares and renders directly after its Model / Effort rows, so our
+control appears at the bottom of the native menu itself. It belongs to the
+shipped entry, not to ours, so it outlives the disposal; and it renders `null` in
+flat mode, so the shipped menu looks exactly as shipped while the panel is on
+screen. Clicking it dismisses the host menu first (the entry that owns the menu
+is about to be disposed) and then flips the mode back.
+
+**It does not look like a menu row.** Every row above it answers "which value?";
+this one performs an action. So it is drawn as a separated bottom band — a 1px
+`--dsw-alias-border-l2` rule above, then a full-width 30 px outlined button
+(`--dsw-alias-border-l3`, `--dsw-radius-sm`, 12/18 medium label, 14 px icon) with
+a hover fill and a focus ring. The slot gives occupants only a `display: contents`
+anchor, so that whole box is ours; nothing about the host menu's own rows has to
+be imitated. The distinction is pinned by a test that asserts the button carries
+no `role="menuitem"`.
+
+Nothing here is a copy of the host control: the row is one entry in a slot the
+installed package publicly declares. The former placement — a chip in
+`conversation.input.right`, beside the native
+trigger — was dropped because it read as a toolbar control belonging to nothing
+in particular, and because it forced the mode control to sit outside the panel
+it acts on.
+
+**One shared store.** Both controls read one page-wide mode store, so a flip made
+from either is what the other sees. The store persists the choice to
+`localStorage` (`dshmf:mode`, the same origin-scoped mechanism as the grouping
+choice) and degrades to `flat` whenever storage is unavailable — a missing store
+must never leave the composer without a model control.
+
+**Reported state is the visible state.** The panel only renders while it owns the
+cell, so the stored mode and the on-screen mode can disagree in exactly one case:
+`native` persisted with nothing to inherit the cell. The button's `aria-pressed`
+then reports flat, because it describes what is on screen, not what is in
+storage.
+
+**What changes across a switch.** Coming back from native mode remounts the
+panel, so it opens closed with an empty query. Focus follows the disposed
+button down to the document; cross-plugin DOM queries for focus are not allowed,
+so it is not chased.
+
 ## Data and interaction
 
 Everything goes through public Client APIs:
@@ -217,6 +337,12 @@ Everything goes through public Client APIs:
 - `ctx.get('remote').agentTeams.setEnabled()` writes the teamwork selection.
 - `ctx.locale` supplies the copy, resolves catalog badge text, and prefers the
   host's own `agent-team` wording when that namespace is registered.
+- `slots.register()` / its disposer and `slots.entries()` / `slots.subscribe()`
+  drive native mode: disposing this plugin's `conversation.input.model` entry
+  elects whatever the Host registered underneath, and `entries()` is what makes
+  that verifiable before the switch. `slots.subscribe()` re-runs the reconcile,
+  so a shipped picker that appears (or disappears) later enables or disables the
+  button without a reload.
 
 No host component, stylesheet, or DOM is read or restyled.
 
@@ -284,10 +410,16 @@ the measured overflow, and the duration is that distance divided by 50 px/s
 ## Limitations
 
 - The panel replaces the composer seat only; the `/model` popup is untouched.
-- The panel does not host the `conversation.input.model.label` and
-  `conversation.input.model.options` child slots. The shipped registration keeps
-  those declarations alive, so other plugins' contributions stay valid; their
-  content simply is not drawn inside this panel.
+- The panel's GRID does not host the `conversation.input.model.label` child
+  slot: rows draw the catalog name plus `model.badge`. Only the TRIGGER renders
+  that slot's winner, because that is what the native trigger does. The
+  `conversation.input.model.options` slot is not drawn anywhere in the panel.
+  The shipped registration keeps both declarations alive, so other plugins'
+  contributions stay valid either way.
+- The trigger's label cell renders ANOTHER PLUGIN'S component. It is written
+  against the documented `ModelLabelOwner` props, but nothing guarantees every
+  future contributor stays compatible; `LabelBoundary` degrades a crash to the
+  catalog name, which is the same fallback the host uses for an empty cell.
 - Addressed subagent sessions hide the seat, matching the shipped selector.
 - The badge comes from the catalog entry, so a provider that publishes no badge
   shows none.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-flatmap",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Flat, two-level-free model picker for the DSH composer: every model and reasoning level on one surface.",
   "type": "module",
   "exports": {