dsh-ui-controller 0.0.1 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ Notable changes to `dsh-ui-controller`.
4
+
5
+ ## 0.1.1 — 2026-11-14
6
+
7
+ ### Added
8
+
9
+ - **Three-state settings rail.** The left column of the settings dialog is now
10
+ `full` (188px), an `icon rail` (56px — labels hidden, each button keeps its
11
+ name as a tooltip) or `collapsed` (0px). It defaults to **following the host
12
+ sidebar**, using the same two readings the shipped code uses (an explicit
13
+ `data-sidebar-collapsed` marker, or a sidebar measured 1–64px wide); turn
14
+ following off to pick a state yourself. New settings field `nav`, stored with
15
+ the rest, with no settings-version bump.
16
+
17
+ ## 0.1.0 — 2026-11-14
18
+
19
+ First release with the inventory page.
20
+
21
+ ### Added
22
+
23
+ - **Inventory of every slot in the running build.** 109 slots, grouped into a
24
+ risk zone and a safe zone, with the entries the host is holding right now
25
+ (`slots.snapshot()`) and a bundled 109-key table as the fallback.
26
+ - **Hide an entry** with a CSS rule you can undo, plus a locator you bind by
27
+ clicking the element once (the host exposes no entry→DOM mapping, so a
28
+ binding is required before a row can be hidden).
29
+ - **Visual order inside one container** via `style.order`; the host gives no
30
+ runtime hook to change another plugin's registration order, and the UI says so.
31
+ - **Three filters** (search, risk, bound/unbound) and collapsible zones and slot
32
+ groups; the collapse state survives the host's 30-second refresh because it is
33
+ kept in module scope, not in component state.
34
+ - **Presets** that save and restore the whole hidden/order state.
35
+ - Display metadata: a Chinese title and description, plus an icon, for the
36
+ plugin list (`locale/zh.json`, `locale/en.json`, `package.json` `icon`).
37
+
38
+ ### Deliberately not done
39
+
40
+ - Registering on another plugin's behalf, rewriting another plugin's React tree,
41
+ or disabling a bundle. A bundle-level toggle needs a restart and belongs to the
42
+ host, not to this plugin.
package/README.md CHANGED
@@ -1,20 +1,238 @@
1
- # UI Controller · 界面控制器
1
+ # dsh-ui-controller
2
2
 
3
- **This is a placeholder release (0.0.1).** The package name is reserved and the
4
- plugin is a no-op: installing it changes nothing in the UI.
3
+ > Inspect and control the UI that other plugins register into DeepSeek Harness slots.
5
4
 
6
- Planned scope:
5
+ DSH renders its interface from **slots**: named seats that plugins register entries
6
+ into. This plugin shows you every seat, who is sitting in it, and lets you hide or
7
+ re-order the ones you did not write yourself — without touching their code, their
8
+ registration, or their React tree.
7
9
 
8
- - List every slot entry registered by every plugin, with its owner, priority and order.
9
- - Hide or reorder those entries from one page, without editing the other plugins.
10
- - Mirror a plugin entry into a different slot and forward clicks to the original.
10
+ It is a plugin-*management* tool, not a theming tool. If you want to restyle DSH,
11
+ use CSS. If you want to know why the same entry appears twice, or why the gear menu
12
+ is missing, this is the plugin that answers that.
11
13
 
12
- Until then, nothing is registered and nothing is styled.
14
+ ## What it does
15
+
16
+ 1. **Inventory (read-only).** A settings section lists every slot of the running
17
+ build — **109** of them in this one: `single 43 · list 42 · keyed 20 · chain 4`,
18
+ scoped `root 53 · session 51 · session-maybe 5`. The list comes from
19
+ `slots.snapshot()` at runtime; the bundled table (same 109 keys, generated from
20
+ `CLIENT_SLOT_API`) is only the fallback when the registry is unavailable, plus the
21
+ source of the `replaceRisk` and `purpose` annotations, which are documentation
22
+ rather than runtime state.
23
+
24
+ The page is **grouped by slot**, because 269 entries in one flat list is not a
25
+ directory, it is a haystack. Three zones, in this order: **risky**
26
+ (`shadows-shipped-ui` seats, hatched), **safe**, and **empty seats**. Every zone
27
+ and every slot starts **folded**; the slot head already tells you the key, the
28
+ kind, the declared risk and how many entries are inside, so scanning the folded
29
+ list is the fast path. Unfolding is per slot, and the state lives outside the
30
+ component (`openNodes`), so a host re-render or the two-second inventory tick
31
+ does **not** spring it back open.
32
+
33
+ Three filters sit above the zones and combine: a **search** box (matches the slot
34
+ key, the declared purpose, the entry id, and either registrant column), a **risk**
35
+ filter (`all` / `risky` / `safe`), and a **binding** filter (`all` / `bound` /
36
+ `unbound`; empty seats cannot be bound, so they drop out of `bound`). The count
37
+ next to them is the number of entries that survived, not the number of slots —
38
+ that is the number you were hunting for.
39
+
40
+ Each entry row shows the entry id, the live registrant with the static inference
41
+ beside it, priority, host order, our visual order, state tags, and the controls.
42
+ 2. **Visibility switches (CSS layer).** For a **third-party** entry in a repeatable
43
+ (`list` / `keyed` / `chain`) slot you can bind the element it renders once, then
44
+ hide and restore it at will. Hiding sets one `data-uic-hidden` attribute and one
45
+ stylesheet rule; it never unmounts the component, never removes somebody else's
46
+ node, and is undone by a single click. Entries we cannot locate honestly say
47
+ **"cannot locate"** and explain why: the host exposes no entry→DOM mapping, so a
48
+ binding is required first.
49
+ 3. **Visual order (CSS `order`).** For any bound third-party entry, `↑`/`↓` step a
50
+ number that is written to the element's inline `style.order`. Elements are
51
+ re-read on every pass and grouped by `parentElement`; only containers whose
52
+ computed `display` is `flex`, `inline-flex` or `grid` are touched, because those
53
+ are the only ones where CSS can re-order children. Slot entries sit inside a
54
+ `[data-slot]` anchor with `display: contents`, so the search walks outward past
55
+ every `contents` ancestor until it finds the element that actually lays out the
56
+ box — judging the anchor would refuse every entry the host renders. Nothing is normalised: negative values
57
+ are kept (they paint before the shipped entries), and a value of `0` drops the key
58
+ instead of being stored. Unbinding, restoring defaults or tearing the plugin down
59
+ clears `style.order` on every node we wrote to.
60
+ 4. **Binding and unbinding.** An entry only becomes controllable once you bind it
61
+ to a DOM element (the host publishes no entry→DOM map). A bound row carries an
62
+ **Unbind** button; unbinding drops the binding *and* the visual order stored for
63
+ that key in the same write, so no number is left behind that could never be
64
+ applied again.
65
+ 5. **Presets.** Hide-marks and visual order can be captured as named presets, applied,
66
+ and deleted; storage follows the same rules as `better-notice` (unknown keys are
67
+ preserved, user changes are marked, upgrades do not overwrite).
68
+ 6. **Settings rail width.** The left column of the settings dialog has three states:
69
+ **full** (188px, the default), an **icon rail** (56px — labels hidden, each button
70
+ keeps its name as a `title` tooltip) and **collapsed** (0px). By default it
71
+ **follows the host sidebar**: when the host's own session list is a rail, this one
72
+ is too, and the stored three-way choice is not read at all. Turn *Follow the host
73
+ sidebar* off to pick one of the three yourself. Only the first grid track and a
74
+ few `title` attributes are touched — no slot is registered, and `settings.header`
75
+ is never involved, so the shipped title is never shadowed.
76
+
77
+ The follow switch reads the same two signals the shipped behaviour does: an
78
+ explicit `data-sidebar-collapsed` marker in the document, or a sidebar element
79
+ measured between 1px and 64px wide. A different threshold would make the two
80
+ disagree the moment the host changes its width.
81
+
82
+ ## What it deliberately does **not** do
83
+
84
+ - **No moving other plugins' entries.** An entry's props come from the slot spec
85
+ that declared it. Re-registering it elsewhere loses that context and is how you
86
+ get a blank panel instead of a working one.
87
+ - **No unregistering, no unmounting.** Everything this plugin does is reversible by
88
+ removing an attribute, an inline style, or a stylesheet rule.
89
+ - **No switch on a `single` slot.** A `single` slot has exactly one occupant, so
90
+ re-registering it *replaces* that occupant: the shipped UI leaves the DOM. Rows
91
+ for an occupied `single` show the reason and no controls at all — hiding there is
92
+ shadowing, and `sidebar.settings` already taught the project what that costs
93
+ (`TypeError: c is not a function`, gear row and settings panel gone together).
94
+ - **No controls on built-in entries.** Two independent flags decide what a row may
95
+ do, and neither is the live registrant:
96
+ - `builtin` — the entry id *is* a shipped package (`@deepseek-ai/dsh…`,
97
+ `dsh-client-ui-…`, `dsh-experimental-…`), or the slot is `single` and its
98
+ static registrar is a shipped package. Such rows are read-only and say
99
+ **"built-in UI · hiding it removes shipped chrome"**.
100
+ - `risky` — the *slot* is marked `shadows-shipped-ui`. That is an annotation
101
+ about the seat, not about the entry in it, so a third-party entry sitting in a
102
+ risky slot keeps its controls and only carries a risk tag.
103
+ - `shippedSlot` — every registrar listed for this (non-`single`) slot is a
104
+ shipped package. That is a *note*, not a gate: keyed slots register per key
105
+ with no entry→registrar map, so the slot cannot say which row came from where.
106
+ Rows there say **"shipped slot"** and keep their controls, because cleaning up
107
+ host menu items is the whole point — the three states never impersonate one
108
+ another.
109
+
110
+ The live registrant cannot answer this question: every dynamically loaded plugin
111
+ reports the same runner name (`tk`), so both our own entries and the shipped ones
112
+ look identical there.
113
+ - **No registration into `root`** — the one slot in this build marked
114
+ "DO NOT register".
115
+ - **No disabling plugins.** That is the profile's job (`dsh plugin remove`), and
116
+ doing it from the browser half would leave the host half loaded.
117
+
118
+ Honest limits of v1: hiding and re-ordering work only for entries you have bound by
119
+ hand (the host does not publish an entry→DOM map); visual order only changes paint
120
+ order, so keyboard Tab order is unaffected; the inventory refreshes on a 2-second
121
+ timer rather than pushing.
13
122
 
14
123
  ## Install
15
124
 
16
- dsh plugin --profile <profile> add dsh-ui-controller
125
+ ```
126
+ dsh plugin --profile <profile> add dsh-ui-controller
127
+ ```
128
+
129
+ Then reload that profile's window (`Ctrl+R` is enough for a client-only change).
130
+ The new **界面控制 / UI controller** section appears in Settings. Do not install it
131
+ into the profile you use as your production desktop unless you want to experiment
132
+ on it.
133
+
134
+ ## JavaScript API
135
+
136
+ ```js
137
+ const api = window.__UI_CONTROLLER__;
138
+
139
+ api.version // '0.1.1'
140
+ api.catalog() // → [{ key, kind, scope, risk, purpose, registrantStatic, injectStatic }]
141
+ api.catalogSummary() // → { total: 109, kinds: {...} }
142
+ api.inventory() // → { rows, empty, totalSlots, occupiedSlots, hiddenCount,
143
+ // riskyCount, locatorCount, orderedCount, catalogSource }
144
+
145
+ api.settings.get() // → { version, hidden, locators, visualOrder, presets, activePreset }
146
+ api.settings.set({ hidden: {...} }) // merge, then apply immediately
147
+ api.settings.reset() // back to defaults
148
+ api.settings.presets() // → ['compact', ...]
149
+ api.settings.savePreset('compact') // → { ok, presets, activePreset }
150
+ api.settings.applyPreset('compact') // → { ok, hidden, visualOrder, activePreset }
151
+
152
+ api.apply() // re-run the CSS layer now
153
+ ```
154
+
155
+ Entry keys in `hidden`, `locators` and `visualOrder` are `"<slotKey>::<entryId>"`.
156
+ The field used to be called `order`; old saves are read through an alias, so nothing
157
+ has to be re-entered (settings version stays `1`).
158
+
159
+ ### For an assistant reading this on a user's behalf
160
+
161
+ Everything the settings page shows is also in `api.inventory()` as plain data, so
162
+ you can answer "why is my gear menu gone" or "which slot is this plugin using"
163
+ without scraping the DOM. When a user wants an entry hidden, prefer the settings
164
+ page (it binds the element by clicking); when they want an audit, read
165
+ `api.inventory()` and filter by `registrant` or `risk`.
166
+
167
+ Two sentences that belong in any answer about ordering:
168
+
169
+ - **Visual order only changes CSS `order`; the keyboard Tab order does not change.**
170
+ - **Where another plugin's entry sits is decided by that plugin at registration
171
+ time — the host exposes no runtime hook for it.** This plugin can only change
172
+ paint order inside a shared parent.
173
+
174
+ ## Test
175
+
176
+ ```
177
+ node --check client.js
178
+ node --check index.js
179
+ node --check test/classify.test.mjs
180
+ node test/classify.test.mjs # expect: PASS — 35 groups
181
+ node ..\..\cangku\tmp\261114_gate_ui_controller.mjs # static gate, separate script
182
+ ```
183
+
184
+ The unit tests load the real `client.js` with a React stub and a tiny DOM. They pin
185
+ the catalog shape (109 slots, 50 `shadows-shipped-ui`, the kind/scope split, the
186
+ `registrantStatic` 93 / `injectStatic` 84 coverage), the runtime-snapshot-over-static
187
+ priority, the inventory/empty split, the hide gate (no switch on shipped entries or
188
+ `single` slots), that hiding writes only our own record, the CSS order layer (flex
189
+ parents only, stale value cleared when the binding goes away), presets, sanitising
190
+ with the old `order` alias, and the zh/en dictionary parity. The grouped page has
191
+ its own groups: entries group under their slot with empty seats in their own zone,
192
+ the three filters count what they keep, folding starts closed and survives a
193
+ re-render, and the static fallback still draws slot heads when no live snapshot is
194
+ available. The settings rail has four groups of its own: each state owns its grid
195
+ track (56px / 0px, and `full` claims none so a wider host rail is inherited
196
+ instead of pinned), following the host sidebar ignores the stored three-way
197
+ choice (and reads the same 64px threshold the host does), the attribute plus
198
+ tooltips are painted on the panel and taken back off, and picking a state stops
199
+ following while the follow switch writes it straight back.
200
+
201
+ ## Known limits
202
+
203
+ 1. **Folded/unfolded is in-memory.** Reloading the page folds everything again. The
204
+ point of folding is to get back to the list quickly; persisting it would mean
205
+ another storage key to migrate, and the filters already narrow the page to
206
+ three or four rows.
207
+ 2. **No entry→DOM mapping.** The slots core renders entries itself and marks
208
+ nothing, so binding is manual. Rows without a binding show "cannot locate" with
209
+ the reason instead of a control that does nothing.
210
+ 3. **Hiding is not unloading.** A hidden entry still runs. If it is expensive, this
211
+ plugin is not the tool — talk to the plugin's author.
212
+ 4. **Visual order is CSS only.** It applies inside one flex/grid parent; a child of
213
+ a `display: contents` or block parent is skipped, and nothing outside our bound
214
+ elements is touched.
215
+ 5. **Hash class names change every build.** Nothing here keys off them; only
216
+ `data-*`, `role`, `aria-label`, `name` and `id` are used to build selectors.
217
+ 6. **`root` is off limits.** Listing it is fine; registering into it is not.
218
+ 7. **`registrant` is an inference.** The live value (`entry.registrant`) is only
219
+ readable at runtime for entries present in the registry; the column shows the
220
+ static proxy scanned out of the shipped bundles, so an entry registered by code
221
+ that ships no literal key can read as "—".
222
+ 8. **The rail only collapses above 768px.** Below that breakpoint the host turns the
223
+ settings nav into a horizontal tab strip, where hiding the labels would leave an
224
+ unlabelled bar; the three states are inert there. Collapsing changes width and
225
+ paint order only — the keyboard order and the DOM order stay exactly as shipped.
226
+ 9. **Following is read at paint time, not subscribed to.** The rail re-reads the host
227
+ sidebar on the same two-second pass that applies visibility and order, so a manual
228
+ host collapse is reflected within that window rather than instantly.
229
+ 10. **Collapsed hides the section list.** With `Collapsed` the settings nav is 0px
230
+ wide, so while it is collapsed you cannot switch to another settings section.
231
+ Turn it back on from this page, or run
232
+ `__UI_CONTROLLER__.settings.set({ nav: { follow: false, state: 'rail' } })` in
233
+ the console. `Follow the host sidebar` (the default) never lands you there on
234
+ its own — only an explicit choice does.
17
235
 
18
236
  ## License
19
237
 
20
- MIT
238
+ MIT