dsh-client-ui-gpt-helper

A DeepSeek Harness client (browser) plugin
that replaces the Web composer's model seat with a ChatGPT-desktop-style control: a popover with
the provider-grouped model list and an animated thinking-level slider carrying a particle
trail, plus a lightning fast-mode toggle.

The interaction design and every timing value are ported from a self-contained prototype that
ships in this repository — open docs/chatgpt-pc-ui-prototype.html
in a browser to see the original.

What it does

• Model selection — the real catalog, grouped by provider, searchable past four entries.
• Thinking level — the selected model's advertised levels become tick marks on a slider with
  a filled track and a 28px thumb. Drag, click a tick, or use the arrow keys; the value snaps to
  the nearest level and submits through the shared session directory.
• Fast mode — a bolt toggle that lights a particle trail. Visual only: DSH has no
  fast-mode concept, so it changes nothing except the animation. Turning it on ignites the trail
  and turning it off coasts it down (see the ramp).
• Fast-mode lock — hold the bolt for 600 ms to pin fast mode on. The hold is stored, so the
  bolt is lit again after a reload, in a new session and after restarting the app; the trigger
  grows a small lock badge and the popover swaps its bolt for a lock. A plain click is inert while
  the lock is held, and a second hold releases it (leaving fast mode on).
• Colour configuration — press Ctrl+Shift+Alt+G to open the colour panel and theme the
  control without editing this file (see Colours).

It replaces the shipped composer control rather than sitting beside it, and it reuses that
control's data layer, so the /model command and the next request stay in sync.

Requirements

• DeepSeek Harness with the Web client (the desktop profile or any profile mounting
  @deepseek-ai/dsh-web-app).
• No build step. The lib/*.js files are authored directly in the shipped bundle format, so
  cloning the repository is enough.

Install

This package is a dsh bundle: package.json declares dsh.bundle.patch, so dsh treats
cordis.patch.yml as a composition layer and mounts it for you.

dsh plugin --profile  add dsh-client-ui-gpt-helper

That installs the package into the profile and appends it to the profile's bundle list. The
profile is watched, so dsh recomposes without a restart. Remove it with
dsh plugin --profile remove dsh-client-ui-gpt-helper.

From a local checkout

dsh plugin --profile desktop add /absolute/path/to/dsh-client-ui-gpt-helper

Mounting by hand

Compose cordis.patch.yml into the profile's own patch file, and make the
package resolvable from the profile directory:

pnpm add link:/absolute/path/to/dsh-client-ui-gpt-helper --dir "$DSH_HOME/profiles/desktop"

# $DSH_HOME/profiles//cordis.patch.yml
- insert:
- id: gpt-helper
name: dsh-client-ui-gpt-helper

A patch insert row may also name a path instead of a package — dsh rewrites ./-relative and
absolute names to file URLs anchored at the patch file — which needs no install at all.

How the takeover works

conversation.input.model is a single slot owned by
@deepseek-ai/dsh-client-ui-conversation, occupied by @deepseek-ai/dsh-client-ui-model-selection
at the default priority 0.

A second registration at the same priority throws — single slot "…" already has a registration. But the registry sorts a cell's entries by priority ascending and renders the
first, and its own error text says "register at a different priority to shadow it (lowest
renders)". This plugin therefore must pass an explicit negative priority:

ctx.slots.register({ name: 'conversation.input.model', priority: -1, … })

> The decreasing auto-allocation in dsh-cordis-client-runner belongs to a different loader
> (agent-authored runtime plugins, whose ledger carries agentId/pluginRunId). A boot-graph
> plugin like this one is not covered by it, and omitting the priority makes registration throw
> while the shipped control silently stays in place.

Keeping the shipped package enabled is the point: its ctx.modelDirectories service and the
/model slash command keep working, and only the UI is replaced. Data and submission ride
the same per-session ModelDirectory, so a switch made in either entry is what the other and the
next request see.

The control

Trigger — a bolt (only while fast mode is lit, with a lock badge while the lock is held), the
model name, the thinking level and a caret; a spinner while a selection settles.

Thinking pane (default)

• Header — the 32×32 fast-mode bolt toggle, a status button showing the level over the model
  name that opens the model pane, and a reset button. The header is a 34px 1fr 34px grid. The
  bolt is replaced by a lock while the lock is held, and the status button then says so instead of
  naming the level; the reset button clears the lock too, since fast mode was always part of what
  it resets.
• Slider — level positions follow the prototype's rule: even fractions of the track clamped to
  the thumb's travel, clamp(i/(n-1), .055, .945), which reproduces its
  [.055, .25, .5, .75, .945] exactly. Ticks are anchored to those same ratios rather than
  flex-distributed as in the prototype, whose interior ticks land up to ~7px away from the thumb
  positions they mark.
• Colours — the rail is the theme's own surface and the fill is solid #5184f4; a gradient
  appears only at the top level. Every one of them is a token — see Colours.
• Particle trail — 42 deterministic particles in a trail element sized to --value, so they
  are clipped to the filled pill. 18 of them are streaks. Every particle carries two complete
  geometries: the drifting trail and the in-place tremble shown at the top level with fast mode
  off, which is what makes those particles small slow dots instead of flat streaks.
• Quota notice — entering the top level briefly collapses the header and swaps the title for
  更快消耗使用额度, as the prototype does.
• Hint — one line naming the hold gesture, because a press that must be held has no affordance
  of its own.

Model pane — a back button, search past four models, and the provider-grouped list with the
current model checked.

How a token resolves

Every colour is a literal, and no colour ever travels through a var(). The stylesheet writes
each token's shipped value inline; the injected rule carries only what the user overrode.

/* the plugin's stylesheet — the shipped pair, no variables anywhere */
.gptm-track { background: #e8e7e8; }
:root[data-dsw-theme="light"] { --c-trigger.model: #242527; }   /* 6 tokens differ */
.gptm-root  { --c-trigger.model: #ffffff; }                      /* the dark default */

/* injected into  by applyTheme — only the overrides, as literals */
:root { --c-trigger.model: #ff0000; }

applyTheme writes nothing at all when no token is overridden: the stylesheet's own literals are
the appearance. An override is published on a bare :root, which beats the shipped
:root[data-dsw-theme="light"] block by specificity — that is what makes your colour hold in
both themes while the six shipped theme-dependent tokens keep following the app.

Colours

The control's palette is a table of 24 tokens, each with two literals: default (used inline in the
stylesheet and on `-level dark) andlight` (published under the light-theme selector). Six
tokens differ between the two; the rest are tuned for a surface that is the same in both themes.

> A colour must never be written var(--c-x) or var(--c-x, fallback). This app's Chromium
> drops any declaration whose value is only a var(…) — including color, background,
> transform and box-shadow — regardless of whether the variable is defined and regardless of a
> fallback being present. Measured on the running page: CSS.supports('background', 'var(--x, #fff)')
> answers false, and a rule written color: var(--c-trigger.level) reaches the document as an
> empty declaration block. That is what made the slider invisible for several rounds — its track,
> fill, thumb and ticks had their paint silently dropped while their geometry measured perfectly
> (235x24 at the right position, background-color: rgba(0,0,0,0)). selfcheck.mjs fails if the
> stylesheet regrows a var(--c-…) reference or if a published override contains a var().

Press Ctrl+Shift+Alt+G to open the colour panel:

• one row per token: a colour well, a text field for the literal (rgba(…), gradients, and so on),
  and a ↺ that drops that one override;
• a hotkey field, so the chord above is itself editable (it is validated, and a half-typed chord
  is refused rather than allowed to break the working one);
• a JSON surface holding the exact document the settings are stored as, with Import and
  Copy config JSON;
• Restore default colours, which empties every override at once.

A row always shows a concrete colour — the override, or the literal the stylesheet carries — and its
placeholder names the theme token that row would follow if left alone. An untouched token follows
the DSH theme; an edited token is pinned to your colour in both themes; ↺, a cleared field, or
Restore is how a token goes back to following the theme.

Storage is localStorage under dsh-client-ui-gpt-helper:config:v1 (and …:fast:v1 for the fast
lock), because a browser bundle cannot touch a file on disk. The JSON surface exists so that the
same document can live in a file you keep: copy it out, edit it, paste it back. Values are
validated on the way in and on the way out of storage — a hand-edited blob cannot close a
declaration and inject CSS.

The tokens, in panel order: trigger.bolt, trigger.model, trigger.level, trigger.levelMax,
trigger.caret, trigger.lockMark, menu.bolt, menu.boltLit, menu.level, menu.levelMax,
menu.levelGrad, menu.quota, menu.quotaGrad, slider.track, slider.fill, slider.fillGrad,
slider.thumb, slider.tick, slider.tickPast, slider.tickCurrent, slider.particle,
slider.particleGlow, slider.particleIdle, slider.particleIdleGlow.

Shipped themes

Two ready-made schemes live in docs/, each with all 24 tokens and validated contrast. Paste one
into the panel's JSON surface and press Import, or apply it from the console:

// docs/theme-sunset.json — warm gold, for a dark app
localStorage.setItem('dsh-client-ui-gpt-helper:config:v1', JSON.stringify({
version: 1, hotkey: 'Ctrl+Shift+Alt+G',
colors: {
'trigger.bolt': '#f0b429', 'trigger.model': '#e8e6e3', 'trigger.level': '#ffc857',
'trigger.levelMax': '#ff8a5b', 'trigger.caret': '#9b948c', 'trigger.lockMark': '#ff6b6b',
'menu.bolt': '#f0b429', 'menu.boltLit': '#ffc857', 'menu.level': '#ffc857',
'menu.levelMax': '#ff9e64', 'menu.levelGrad': 'linear-gradient(90deg, #ffe08a, #ffb454 48%, #ff7a59)',
'menu.quota': '#ff9e64', 'menu.quotaGrad': 'linear-gradient(90deg, #ffd166, #ff7a59)',
'slider.track': '#3a332b', 'slider.fill': '#f0b429',
'slider.fillGrad': 'linear-gradient(90deg, #ffe08a 0%, #ffc857 34%, #ff9e64 68%, #ff6b6b 100%)',
'slider.thumb': '#fffaf0', 'slider.tick': '#5a5145',
'slider.tickPast': 'rgba(48,36,20,.55)', 'slider.tickCurrent': 'rgba(48,36,20,.62)',
'slider.particle': '#fff3d1', 'slider.particleGlow': 'rgba(255,214,120,.85)',
'slider.particleIdle': '#ffd8a8', 'slider.particleIdleGlow': 'rgba(255,216,168,.35)'
}
}));
location.reload();

docs/theme-neon.json is the other one — cyan-to-magenta, for maximum separation from the shipped
blue. Both were measured with the same luminance maths as
Why the accents are those accents; the ticks are the token
worth re-checking when you invent a scheme, because they sit on the FILL, not on the popover: a
light tick disappears into a pale fill.

Why the accents are those accents

Six tokens differ between the shipped dark and light values — the four trigger accents plus the
caret and the lock badge — because the trigger sits on the composer, which is light in the light
theme. The other accents have no theme pair, and they are tuned for the surface they are drawn on:
that surface is the same in both themes, because the popover is a dark translucent layer over
whatever is behind it. White text is therefore correct in both, while a mid-tone accent that looks
fine on a white page is close to invisible on the popover. That was the readability report: the rail
and thumb are near-white and always readable, but the level blue and the model name under it were
not.

Measured contrast against the popover surface (WCAG relative luminance; 4.5 for body text, 3.0 for
large text and graphical objects):

scripts/contrast.mjs reprints this table from the token table in lib/client.js, which is how the
numbers above were produced rather than guessed.

Implementation notes

These are the non-obvious things, kept because each one cost a debugging round.

The particle ramp

The prototype had no ramp: it cross-faded a container whose particle cycles were already in
flight, and the level changed only the trail's width and gradient. Here a --spin intensity is
eased onto the slider node with requestAnimationFrame — up over ~600 ms, down over ~900 ms, so
extinguishing has the inertia of coasting — and it scales each particle's peak opacity through
the keyframes. At steady state --spin is 1, so the rendered opacities are exactly the
prototype's.

The squircle trap

DSH's theme plugin injects, under @supports (corner-shape: superellipse(1.5)), a universal rule
over *, :before and :after:

:root { --dsw-corner-shape: superellipse(1.5) }
*, :before, :after { corner-shape: var(--dsw-corner-shape) }

So every rounded corner in the app is a superellipse, not a circular arc. A
border-radius: 50% circle becomes a squircle — a rounded square — and pill ends deform. The
theme README states the rule: full-round shapes must pair corner-shape: round with their radius
in the owning stylesheet, which is why every shipped DSH component sheet carries that line beside
its radii.

Every full-round radius here — track, fill, trail, thumb, ticks, particles, streak particles, the
busy spinner and the slider's focus ring — pairs corner-shape: round. Decorative radii (menu,
trigger, rows, notes) deliberately do not, so they keep the theme's intended smoothing.

The box-sizing reset

The prototype opens with * { box-sizing: border-box }. DSH does not set that globally — it
declares box-sizing per component — so without a reset the popover is sized by content width
and the track comes out ~22px wider than the prototype's 236px, shifting every level position.
The plugin scopes its own reset to its two subtrees.

The clamped corner radius

border-radius: 999px is clamped by the box. On the ~13px fill the lowest level produces, the
browser scales every radius by width / (radius sum) and the cap comes out at ~6.4px instead of
12px; a squared-off cap then pokes past the 28px thumb by ~1.3px near the top and bottom. The fill
and trail therefore carry min-width: 24px, so the cap is always a true semicircle. The extra
width sits under the thumb and changes nothing else. Verified numerically: 12.87px → 1.31px
protrusion, 24px → fully covered.

Dragging

The drag is driven from window pointermove/pointerup/pointercancel listeners filtered by
an active pointer id, as the prototype does, with the handler table held in a ref. Binding the
moves to the track instead drops the gesture the moment the pointer leaves it, and lets a
re-render land a stale dragging: false closure mid-drag — together those made a rightward drag
die. The visuals follow the pointer continuously; only the nearest level is committed on release.

Scrolling

Like the prototype, the popover is not a scroll container — it grows with its content, bounded
only by max-height — and the model list is the single scrolling region. This matters: giving the
whole body overflow-y: auto also computes overflow-x to auto, so any sub-pixel overflow
grows scrollbars on both edges. The list region pins overflow-x: hidden.

One gradient, not two

A deliberate deviation. The prototype declares a second top-level gradient for fast-mode-off
(#3941c4 → #a987ff → #7d57eb) after the first, so the track jumps colour the instant the bolt is
toggled. This plugin uses the fast-mode gradient for both states, leaving fast mode to change only
the particles and the trail's opacity.

What it reads

From the shared directory snapshot: current (provider/model/reasoningEffort), groups
([{ id, name, models: [{ id, name, reasoning }] }]), status, pending, error,
retainedEffort. From reasoning: defaultEffort and efforts ([{ id, name }]). Submission is
directory.select({ provider, model, reasoningEffort? }), which forwards to the host through
sessions.selectModel.

Development

npm run validate          # or: node scripts/validate-plugin.mjs .
npm run selfcheck         # or: node scripts/selfcheck.mjs
npm run contrast          # or: node scripts/contrast.mjs
npm run loadcheck         # or: node scripts/loadcheck.mjs

The validator is read-only and asserts the contract the client module system relies on: the
dsh.client declaration, the exports map, the __ModuleLoader__ wrapper, that the factory id
equals the package name, that the CSS template literal contains no stray backtick or ${, and
that every t('key') the component uses exists in both locale dictionaries.

selfcheck.mjs covers what the validator cannot: the colour table, the hotkey parser, the published
overrides and the two stores. The bundle's factory needs a browser, a cordis context and a live model
directory, so the check cuts the factory body out of lib/client.js verbatim, evaluates it against
a small React-and-DOM stub, and then exercises the real functions and renders the real components.
It asserts, among other things, that the stylesheet never reads a colour through a var(), that a
declaration-escape attempt is refused, and that a hold locks fast mode while a click cannot unlock it.

contrast.mjs reads the token table and prints each colour's WCAG contrast against the popover
surface, failing when anything drops under 3.0 there. It is how the accent values in
Why the accents are those accents were chosen.

loadcheck.mjs loads the bundle the way the app loads it — as a classic script calling
window.__ModuleLoader__.load, then factory(require), then apply() and one render — and reports
the stage that failed. That path is worth checking on its own because a failure there does not stay
in the plugin: the app logs web boot: 1 entry did not activate and restarts, so "did my edit keep
the bundle importable" is a question to answer before reloading the page, not after.

Client bundles are hot-reloaded: DSH's client-HMR polls each bundle's mtime and republishes it, so
editing lib/client.js reaches the running page within about a second. Changes to package.json
or the mount row need a page reload.

The build marker, and why a crash here is not local

lib/client.js carries const BUILD, and the control writes it onto its root as data-build
beside a console.info('[gpt-helper] client half applied — build …'). The reason is that a
browser cannot be asked what code it is running: this control's markup is indistinguishable
between versions, so a page that loaded a stale module looks exactly like one that did not. Ask the
page instead:

document.querySelector('[data-gpt-helper="root"]')?.dataset.build

Bump BUILD by hand whenever a change has to be confirmed in a running page.

Three traps, each of which cost a debugging round:

• A render-time ReferenceError fails the whole web boot. An extra element that referenced a
  constant defined elsewhere in the factory threw inside ModelEffortControl, and the app reported
  web boot: 1 entry did not activate in
  %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log and restarted. The slot entry has
  no error boundary of its own: it "fails loudly" by taking the boot with it. Keep anything new in
  the render path defined in the same scope, or pass it in.
• HMR swaps the module under a live tree. During the swap one more render can run against the
  outgoing module, so a ReferenceError and the new build's applied log line can appear together
  in one console dump. Read the LAST line, and hard-refresh (Ctrl+Shift+R) before believing any of
  it.
• A crash log with an EMPTY renderer console is usually the editor, not the app. Saving
  lib/client.js several times in a row means the HMR poll can read the file mid-write; the import
  then fails with nothing to report, and the log is left behind. Before investigating one, compare
  its timestamp with the file's mtime and run npm run loadcheck: if the current file loads, the log
  is a fossil. data-build and the log's own error level are what distinguish a real failure.

The consequence for anyone building on this: prefer a data- attribute over a new node when adding
a marker, and check the console after every edit rather than assuming the reload was clean.

Repository layout

lib/index.js                    host half — an empty apply(), mirroring shipped client-only packages
lib/client.js                   browser half — styles, locale dictionaries, and the control
cordis.patch.yml                the bundle layer: the row that mounts the plugin
scripts/validate-plugin.mjs     structural validator (see Development)
scripts/selfcheck.mjs           behavioural check for the colours, the hotkey and the fast lock
scripts/contrast.mjs            WCAG contrast of the shipped palette on the popover surface
docs/chatgpt-pc-ui-prototype.html   the original design prototype

Caveats

• This is a UI replacement for a slot DSH owns, taken over by priority. A future DSH release
  may change the slot's props or the shipped control's priority, in which case the selectors and
  the registration here need revisiting. The plugin fails loudly rather than silently: a broken
  slot entry reports slot entry crashed in 'conversation.input.model'.
• Fast mode is presentation only: DSH has no fast-mode concept, so the toggle and its lock change
  nothing but the animation. The lock persists the toggle, not any request behaviour.
• Colour settings live in localStorage, which is per browser profile rather than per DSH profile.
  A second window sees them, a second machine does not; move them with Copy config JSON.

License

MIT