dsh-arrowkey-nav

Readme

# dsh-arrowkey-nav

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.

## Install

```sh
dsh plugin --profile web add E:\test\rewrite-agently\dsh-arrowkey-nav
```

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:

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

### Remove

```sh
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.sessions.open(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

```sh
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.
- **Pinned to dsh 0.1.2-rc.1.** `sessions` and `workspaces` snapshot fields are
  pre-stable. 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.

## Version compatibility

This branch (`compat/0.1.1`) targets **DSH ≤ 0.1.1-rc.2** (the
`dsh-client-runtime` generation).

- `package.json → dsh.client.inject` is empty: 0.1.1 predates
  `dsh-api-session-controller`, and declaring bundles that do not exist on this
  generation risks breaking the client combo. Services are resolved through
  Cordis injection (`sessions`, `workspaces`) alone.
- `uiWorkspace` is not injected and is optional: on builds without it the
  empty-workspace fallback is skipped (blank-first / newest-first still work).
- If either snapshot service is missing at runtime the plugin stays attached
  but inert, and every arrow press logs `services missing` — it never throws.
- Live verification on 0.1.1-rc.2 is pending; run `diagnose-console.js` in the
  web console and check `__dshArrowkeyNav.snapshot()` before first use.

For DSH 0.1.5-rc.x, see the `compat/0.1.5-rc` branch.

## 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