drscrewdriver/dsh-arrowkey-nav

English | 简体中文 | 日本語 | 한국어 | Français | Deutsch | Italiano | Русский | Español

Arrow-key navigation for the DSH Web GUI. Switch sessions without leaving the keyboard:

Key	Action	Scope
↑	previous session	inside the current workspace
↓	next session	inside the current workspace
←	previous workspace	all workspaces
→	next workspace	all workspaces

↑/↓ wrap around at the ends of the workspace and never cross into a neighbouring one; crossing is what ←/→ are for. After a switch the target row is scrolled into view, and focus returns to the composer if that is where the press started, so typing can continue immediately.

Branches and DSH versions

Branch	DSH range	Status
master	~0.1.2 (original baseline)	verified at development time
compat/0.2.0	>=0.2.0-rc.1 <0.2.1-0	0.4.1 restores arrow-key navigation broken by two host API removals (ISessions.open, SessionListState.current); the earlier "metadata-only adaptation" claim was wrong; lint + typecheck + 60/60 tests green; published under the dsh-0.2.0 dist-tag
compat/0.1.7	>=0.1.7-rc.1 <0.1.8-0	0.3.4 applies the same fix on the 0.1.7 line; lint + typecheck + 60/60 tests green; published under the dsh-0.1.7 dist-tag
compat/0.1.5-rc	>=0.1.5-alpha.1 <0.2.0-0	adaptation done on this branch (console evidence accessor + narrowed engines.dsh); typecheck + 52/52 tests green here; live load evidence pending
compat/0.1.1	≤ 0.1.1-rc.2 (dsh-client-runtime generation)	defensive adaptation done; live verification pending

Install from the branch whose range covers your DSH build. lib/ is committed on every branch, so a GitHub-based install needs no build step.

Install

dsh plugin --profile web add github:drscrewdriver/dsh-arrowkey-nav#compat/0.2.0 -w

#compat/0.2.0 is the DSH 0.2.0 line, which is what this branch is. lib/ is committed on it, so a GitHub install needs no build step. The registry package installs by dist-tag (dsh plugin --profile web add dsh-arrowkey-nav@dsh-0.2.0 -w); a bare dsh-arrowkey-nav still resolves to latest, which lags this line.

Restart the profile afterwards — a running instance does not hot-load a new bundle layer. Then reload http://127.0.0.1:3080.

Confirm the row is in the composed tree:

dsh web --dump-config | Select-String dsh-arrowkey-nav

A local checkout can be registered instead with dsh plugin --profile web add <absolute path to the checkout> -w; see INSTALL.md for the full guide, including upgrades, verification and removal.

Remove

dsh plugin --profile web remove dsh-arrowkey-nav

Restart, and the keys behave exactly as before the install: the listener is owned by the plugin's Cordis effect and is removed with it.

How it works

Identity comes from the two client controllers, never from the DOM: rows carry no data-* and no id, so a row cannot be asked what session it is.

• ctx.uiWorkspace.openSession(id) performs every switch. The details panel needs no handling: the shipped frame already closes it when the current session changes.
• ctx.workspaces.list.getSnapshot() supplies the workspace order — the order ←/→ walks, and the source of each workspace's member list.

Which session is "next" follows the order the sidebar is drawing, not the controller's member order. Those disagree in exactly the case you notice: the sidebar reconciles its own persisted order with the membership and promotes recently-active sessions to the top, so an old session jumps to the first row the moment you open it. The plugin therefore reads the rendered row order out of the sidebar, and falls back to the controller order when the sidebar is not mounted (collapsed rail). A section is accepted only when its rows account for every session the controller reports for that workspace; an ambiguous or mismatched section falls back instead of guessing.

Keys are left alone when the event already belongs to somebody else: any modifier, IME composition, an event already handled upstream, or a focus inside a dialog, menu or another editable field (the sidebar's session search, a rename box). The listener registers in the capture phase but only calls preventDefault() when it actually navigates.

The composer is the one conditional case. An empty composer yields its arrow keys — there is no caret to move, so the key is free — which is what lets you navigate right after sending a message, while the composer still holds focus. Once the composer holds a draft, its arrow keys belong to the caret again, so editing a prompt is never hijacked.

The browser half has no React components, no CSS and no platform-module requests, and the package has no runtime dependencies — lib/client.js is generated by scripts/build-client.mjs into the module-loader contract the page expects.

Development

npm run typecheck   # both compiler faces
npm test            # resolver unit tests + built-bundle smoke tests
npm run build       # regenerate lib/client.js after editing src/client

npm run build needs typescript; if it is not installed in this package, point DSH_TYPESCRIPT at an existing typescript module directory.

Known limitations

• A collapsed workspace group does not scroll. Its rows are not mounted, and dsh exposes no public way to expand a group, so the switch happens but the target row stays out of sight. The workspace holding the current session is kept expanded by dsh itself, so ↑/↓ are unaffected.
• A rail-collapsed sidebar does not scroll for the same reason: the tree is not mounted. The switch still happens.
• "In one list" mode has no workspace sections, but ←/→ still walk the controller's workspace order, so the list may appear to jump between sections.
• Scrolling is best effort. Any lookup failure is swallowed: the selection has already moved, and a missing row must never turn into a wrong one.
• Snapshot fields are pre-stable. sessions and workspaces snapshot shapes are pre-stable — this branch is the DSH 0.2.0 line (engines.dsh: >=0.2.0-rc.1 <0.2.1-0). If a dsh upgrade changes them, src/client/navigate.ts and src/client/apply.ts are the only files to revisit; a service that is gone leaves the plugin pending rather than failing the page.

Layout

src/index.ts                node half: loader entry, installs nothing
src/client/constants.ts     keys owned, DOM anchors read
src/client/navigate.ts      narrow waist: snapshot types + arrow resolver
src/client/apply.ts         execution: open / blank-first / connectWorkspace
src/client/dom.ts           read-only DOM: scroller, section binding, scroll, focus
src/client/session-nav.ts   key guards + one arrow press end to end
src/client/index.ts         Cordis entry: inject + one capturing listener
scripts/build-client.mjs    generates lib/client.js
tests/                      resolver unit tests + bundle smoke tests

License

MIT