dsh-ui-controller 0.0.1 → 0.1.0

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,30 @@
1
+ # Changelog
2
+
3
+ Notable changes to `dsh-ui-controller`.
4
+
5
+ ## 0.1.0 — 2026-11-14
6
+
7
+ First release with the inventory page.
8
+
9
+ ### Added
10
+
11
+ - **Inventory of every slot in the running build.** 109 slots, grouped into a
12
+ risk zone and a safe zone, with the entries the host is holding right now
13
+ (`slots.snapshot()`) and a bundled 109-key table as the fallback.
14
+ - **Hide an entry** with a CSS rule you can undo, plus a locator you bind by
15
+ clicking the element once (the host exposes no entry→DOM mapping, so a
16
+ binding is required before a row can be hidden).
17
+ - **Visual order inside one container** via `style.order`; the host gives no
18
+ runtime hook to change another plugin's registration order, and the UI says so.
19
+ - **Three filters** (search, risk, bound/unbound) and collapsible zones and slot
20
+ groups; the collapse state survives the host's 30-second refresh because it is
21
+ kept in module scope, not in component state.
22
+ - **Presets** that save and restore the whole hidden/order state.
23
+ - Display metadata: a Chinese title and description, plus an icon, for the
24
+ plugin list (`locale/zh.json`, `locale/en.json`, `package.json` `icon`).
25
+
26
+ ### Deliberately not done
27
+
28
+ - Registering on another plugin's behalf, rewriting another plugin's React tree,
29
+ or disabling a bundle. A bundle-level toggle needs a restart and belongs to the
30
+ host, not to this plugin.
package/README.md CHANGED
@@ -1,20 +1,207 @@
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
+
69
+ ## What it deliberately does **not** do
70
+
71
+ - **No moving other plugins' entries.** An entry's props come from the slot spec
72
+ that declared it. Re-registering it elsewhere loses that context and is how you
73
+ get a blank panel instead of a working one.
74
+ - **No unregistering, no unmounting.** Everything this plugin does is reversible by
75
+ removing an attribute, an inline style, or a stylesheet rule.
76
+ - **No switch on a `single` slot.** A `single` slot has exactly one occupant, so
77
+ re-registering it *replaces* that occupant: the shipped UI leaves the DOM. Rows
78
+ for an occupied `single` show the reason and no controls at all — hiding there is
79
+ shadowing, and `sidebar.settings` already taught the project what that costs
80
+ (`TypeError: c is not a function`, gear row and settings panel gone together).
81
+ - **No controls on built-in entries.** Two independent flags decide what a row may
82
+ do, and neither is the live registrant:
83
+ - `builtin` — the entry id *is* a shipped package (`@deepseek-ai/dsh…`,
84
+ `dsh-client-ui-…`, `dsh-experimental-…`), or the slot is `single` and its
85
+ static registrar is a shipped package. Such rows are read-only and say
86
+ **"built-in UI · hiding it removes shipped chrome"**.
87
+ - `risky` — the *slot* is marked `shadows-shipped-ui`. That is an annotation
88
+ about the seat, not about the entry in it, so a third-party entry sitting in a
89
+ risky slot keeps its controls and only carries a risk tag.
90
+ - `shippedSlot` — every registrar listed for this (non-`single`) slot is a
91
+ shipped package. That is a *note*, not a gate: keyed slots register per key
92
+ with no entry→registrar map, so the slot cannot say which row came from where.
93
+ Rows there say **"shipped slot"** and keep their controls, because cleaning up
94
+ host menu items is the whole point — the three states never impersonate one
95
+ another.
96
+
97
+ The live registrant cannot answer this question: every dynamically loaded plugin
98
+ reports the same runner name (`tk`), so both our own entries and the shipped ones
99
+ look identical there.
100
+ - **No registration into `root`** — the one slot in this build marked
101
+ "DO NOT register".
102
+ - **No disabling plugins.** That is the profile's job (`dsh plugin remove`), and
103
+ doing it from the browser half would leave the host half loaded.
104
+
105
+ Honest limits of v1: hiding and re-ordering work only for entries you have bound by
106
+ hand (the host does not publish an entry→DOM map); visual order only changes paint
107
+ order, so keyboard Tab order is unaffected; the inventory refreshes on a 2-second
108
+ timer rather than pushing.
13
109
 
14
110
  ## Install
15
111
 
16
- dsh plugin --profile <profile> add dsh-ui-controller
112
+ ```
113
+ dsh plugin --profile <profile> add dsh-ui-controller
114
+ ```
115
+
116
+ Then reload that profile's window (`Ctrl+R` is enough for a client-only change).
117
+ The new **界面控制 / UI controller** section appears in Settings. Do not install it
118
+ into the profile you use as your production desktop unless you want to experiment
119
+ on it.
120
+
121
+ ## JavaScript API
122
+
123
+ ```js
124
+ const api = window.__UI_CONTROLLER__;
125
+
126
+ api.version // '0.1.0'
127
+ api.catalog() // → [{ key, kind, scope, risk, purpose, registrantStatic, injectStatic }]
128
+ api.catalogSummary() // → { total: 109, kinds: {...} }
129
+ api.inventory() // → { rows, empty, totalSlots, occupiedSlots, hiddenCount,
130
+ // riskyCount, locatorCount, orderedCount, catalogSource }
131
+
132
+ api.settings.get() // → { version, hidden, locators, visualOrder, presets, activePreset }
133
+ api.settings.set({ hidden: {...} }) // merge, then apply immediately
134
+ api.settings.reset() // back to defaults
135
+ api.settings.presets() // → ['compact', ...]
136
+ api.settings.savePreset('compact') // → { ok, presets, activePreset }
137
+ api.settings.applyPreset('compact') // → { ok, hidden, visualOrder, activePreset }
138
+
139
+ api.apply() // re-run the CSS layer now
140
+ ```
141
+
142
+ Entry keys in `hidden`, `locators` and `visualOrder` are `"<slotKey>::<entryId>"`.
143
+ The field used to be called `order`; old saves are read through an alias, so nothing
144
+ has to be re-entered (settings version stays `1`).
145
+
146
+ ### For an assistant reading this on a user's behalf
147
+
148
+ Everything the settings page shows is also in `api.inventory()` as plain data, so
149
+ you can answer "why is my gear menu gone" or "which slot is this plugin using"
150
+ without scraping the DOM. When a user wants an entry hidden, prefer the settings
151
+ page (it binds the element by clicking); when they want an audit, read
152
+ `api.inventory()` and filter by `registrant` or `risk`.
153
+
154
+ Two sentences that belong in any answer about ordering:
155
+
156
+ - **Visual order only changes CSS `order`; the keyboard Tab order does not change.**
157
+ - **Where another plugin's entry sits is decided by that plugin at registration
158
+ time — the host exposes no runtime hook for it.** This plugin can only change
159
+ paint order inside a shared parent.
160
+
161
+ ## Test
162
+
163
+ ```
164
+ node --check client.js
165
+ node --check index.js
166
+ node --check test/classify.test.mjs
167
+ node test/classify.test.mjs # expect: PASS — 26 groups
168
+ node ..\..\cangku\tmp\261114_gate_ui_controller.mjs # static gate, separate script
169
+ ```
170
+
171
+ The unit tests load the real `client.js` with a React stub and a tiny DOM. They pin
172
+ the catalog shape (109 slots, 50 `shadows-shipped-ui`, the kind/scope split, the
173
+ `registrantStatic` 93 / `injectStatic` 84 coverage), the runtime-snapshot-over-static
174
+ priority, the inventory/empty split, the hide gate (no switch on shipped entries or
175
+ `single` slots), that hiding writes only our own record, the CSS order layer (flex
176
+ parents only, stale value cleared when the binding goes away), presets, sanitising
177
+ with the old `order` alias, and the zh/en dictionary parity. The grouped page has
178
+ its own groups: entries group under their slot with empty seats in their own zone,
179
+ the three filters count what they keep, folding starts closed and survives a
180
+ re-render, and the static fallback still draws slot heads when no live snapshot is
181
+ available.
182
+
183
+ ## Known limits
184
+
185
+ 1. **Folded/unfolded is in-memory.** Reloading the page folds everything again. The
186
+ point of folding is to get back to the list quickly; persisting it would mean
187
+ another storage key to migrate, and the filters already narrow the page to
188
+ three or four rows.
189
+ 2. **No entry→DOM mapping.** The slots core renders entries itself and marks
190
+ nothing, so binding is manual. Rows without a binding show "cannot locate" with
191
+ the reason instead of a control that does nothing.
192
+ 3. **Hiding is not unloading.** A hidden entry still runs. If it is expensive, this
193
+ plugin is not the tool — talk to the plugin's author.
194
+ 3. **Visual order is CSS only.** It applies inside one flex/grid parent; a child of
195
+ a `display: contents` or block parent is skipped, and nothing outside our bound
196
+ elements is touched.
197
+ 4. **Hash class names change every build.** Nothing here keys off them; only
198
+ `data-*`, `role`, `aria-label`, `name` and `id` are used to build selectors.
199
+ 5. **`root` is off limits.** Listing it is fine; registering into it is not.
200
+ 6. **`registrant` is an inference.** The live value (`entry.registrant`) is only
201
+ readable at runtime for entries present in the registry; the column shows the
202
+ static proxy scanned out of the shipped bundles, so an entry registered by code
203
+ that ships no literal key can read as "—".
17
204
 
18
205
  ## License
19
206
 
20
- MIT
207
+ MIT