dsh-a11y

Accessibility layer for the DeepSeek Harness Web UI. This is v1: the
announcement coordinator, keyboard navigation, and an Accessibility settings
page. The v2 author kit (ctx.a11y, `,useFocusTrap,useRovingTabIndex,auditSubtree`) is deliberately not part of this build.

The plugin adds coverage; it does not replace the shipped chat UI.

npm: dsh-a11y@0.1.0

Presentation: PPTX · PDF

Related work and the gap check (2026-11-11)

This package publishes as dsh-a11y on npm. When the build started, the bare
name was unclaimed, but the brief's "no accessibility plugin exists" premise was
already stale:

• @oh-my-dsh/dsh-accessibility
  (published 0.1.0-beta.3, repo omdsh-dev/dsh-accessibility) is a
  present-day companion with a Settings → Accessibility diagnostic, a
  screen-reader guide, and an experimental Accessible View reading tab. Its
  published line targets DSH 0.1.1-rc.2/0.1.2-rc.1; the repo's migration
  candidate targets 0.2.0-rc.2. Its own README states that it "cannot safely
  replace focus traps, composite-widget keyboard behavior, landmarks, or
  live-region policy from outside the owning components."
• dsh-a11y-scan runs
  axe-core over local HTML, build output, or URLs. It is a content scanner, not
  a UI live-announcement layer.

dsh-a11y targets the installed DSH 0.2.2-rc.1 and fills the specific gap
the other two leave: a coordinated announcement layer for tool lifecycle,
approvals, and questions, plus skip/latest navigation and the announcement
settings. It overlaps the diagnostic/settings surface only partially.

Install

From npm:

dsh plugin --profile web add dsh-a11y

The latest npm release is 0.1.0.

Or install this checkout as a profile bundle:

# plugin_manager -> install_bundle ->

If you previously installed a local development copy, remove it before
installing the npm package; both register the same slot ids.

The bundle has a no-op Host half (index.js) and a browser half
(client.js, declared by package.json's dsh.client). It installs as a normal
profile bundle; no app.asar edits are involved.

What the host already announces (do not duplicate)

Verified against the shipped @deepseek-ai/dsh-client-ui-chat 0.2.2-rc.1
bundle, lib/client.js:

Tool rows also render visually-hidden row.running / row.failed text, but
those spans are not live regions; adding/removing them does not announce on
its own. That is part of the gap this plugin fills.

How dsh-a11y coordinates

dsh-a11y never emits turn start or turn end announcements. Its only live
regions are the new pair in shell.overlay (polite + assertive). Turn start,
turn end, retry, terminal turn errors, and token-cap notices stay owned by the
host regions above. This was a deliberate "stay silent" choice, not blind
muting: the host's two role="status" regions are visible in the installed
chat component and their copy was verified from both the installed package and
the extracted app bundle.

If the host later removes those regions, this plugin becomes the only coverage
for tool activity, approvals, and questions, but turn start/end would need a
follow-up.

Announcements

Source: Client state only.

• Tool started — useChat(snapshot => snapshot.legacy.runningCalls),
  announced when a call reaches phase === 'start' (preparing calls stay
  silent).
• Tool finished / failed — useChat(snapshot => snapshot.legacy.nodes),
  correlated by callId with the running call. Failure is isError: true;
  the detailed summary comes from error.reason / error.code / the first
  text block, truncated to 96 characters.
• Approval requested — useSessionStatus(...).pendingInteraction with
  kind === 'approval'; assertive. The tool name and request reason are
  included.
• Question asked — the same pending-interaction source with
  kind === 'question' or kind === 'plan-review'; assertive.
• Settings test — the Test button in the Accessibility page pushes a
  forced polite announcement so users can verify the route to their screen
  reader.

Streaming assistant tokens are never announced. Announcements are triggered by
state transitions, not by render counts or token deltas.

Announcements follow the Chat transcript target. In the Trajectory view the
Chat target may not be materialized, so tool transitions can be unavailable
there; the host's own turn boundary regions have the same dependency. This is a
known v1 limitation.

Verbosity and merging

• Off — no polite announcements. Focus management still runs. The Test
  button still works.
• Concise — "Tool bash started", "Tool bash finished", "Tool bash failed",
  approvals and questions.
• Detailed — finished results include a short result summary and duration
  ("Tool read finished in 0.4 seconds. package.json").

Fast tools are merged in the queue: a still-queued start is replaced by its
finish, so a 50 ms tool is spoken once, not twice. The announcement speed
setting controls the gap between queued messages (250 / 700 / 1400 ms). The
queue is capped at 30 items, and identical consecutive text is alternated with
a zero-width space so screen readers do not suppress a repeat.

History paging does not replay old tools: the coordinator primes a sequence
watermark on mount and only treats newer tool-result nodes as live. A tool
that was already running when the session opened still gets its finish
announced.

Navigation

• Skip link — a visually hidden "Skip to conversation" link is the first
  Tab stop from the document root. The plugin captures the first Tab when
  nothing is focused and focuses the link; Enter (or the next Tab) lands on the
  latest turn boundary inside the transcript, falling back to the composer
  input when there is no turn yet. The link becomes visible when focused.
• Landmarks — the skip link sits in a labelled nav; the jump button sits
  in a "Conversation navigation" nav; the settings page is a labelled
  section.
• Per-turn headings — each completed turn contributes an
  h2 ("Turn 3: completed") in conversation.chat.turnTail. It is visually
  hidden, tabIndex=-1, and is the focus target used by the skip link. The
  latest turn's heading carries id="dsh-a11y-turn-latest".
• Jump to latest turn — a compact button in conversation.composer.dock
  focuses the most recent visible turn heading.
• Approval focus — when an approval becomes pending, the plugin stores the
  previously focused element, moves focus to the approval card's detail group
  (the host card has no focus move of its own), and on settlement restores the
  previous focus target, or the composer input.
• Focus ring — the Accessibility settings page can add a 3 px brand-colored
  :focus-visible outline to every control.

The host settings panel already uses its useModalLayer primitive for the
dialog focus trap and focus restore; the plugin does not add a second trap
inside it. Only the approval takeover needed a focus move and restore, which the
coordinator supplies.

Known limitation: the plugin cannot own the transcript container. The host
offers no additive slot at the start of the transcript, so the skip target and
per-turn headings live at turn boundaries (turn tails). Per-turn headings are
therefore navigable in the heading list but describe a turn from its end.
Fixing that properly needs a host change (see "Host findings").

Settings

The Accessibility page is its own settings.section (id: accessibility,
order 30) with:

• Announcements: Off / Concise / Detailed.
• Announcement speed: Fast / Normal / Slow.
• Focus ring: Default / Emphasized.
• Motion: Follow system / Reduce motion / Allow motion.
• Text size: 12–22 px, delegated to the host's theme.setFontSize('text', px)
  so it is the same preference as Appearance → Text size.
• Test announcement and Reset preferences.

Preferences other than text size are stored in localStorage under
dsh-a11y.settings.v1. They are browser-local, normalized on read, and applied
through data-dsh-a11y-focus / data-dsh-a11y-motion on the document root.
There is no Host Config in v1, so nothing is written to the profile patch.

Motion override:

• Follow system leaves the host's existing prefers-reduced-motion media
  queries untouched.
• Reduce motion forces near-zero animation and transition durations on the
  document, including when the OS preference is off.
• Allow motion restores short transitions (150 ms) and 1 s animations when
  the OS preference is on. This is intentionally a broad, opt-in override; it
  is documented as such because it deliberately contradicts the OS.

All styles use --dsw-alias-* color tokens. The only other values are spacing,
type sizes, and radius fallbacks.

Verification status (this build)

Installed with plugin_manager install_bundle into the current profile;
application: applied, no warnings. Live client registration was confirmed by
cordis_inspect_query:

• settings.section → occupant accessibility, order 30, active.
• conversation.composer.dock → occupant a11y-coordinator, order 2, active.
• shell.overlay → occupants a11y-skip-link and a11y-announcer, active.
• conversation.chat.turnTail → occupant a11y-turn-heading, order 1000,
  active.

Not verified in this environment: no browser-control or screen-reader
automation was available, so the rendered settings page, Narrator/NVDA speech,
zoom, and axe results remain manual. Automated tests cover the formatter,
queue merging, settings normalization, and locale parity:

node test/run.mjs
# or, in a shell that expands globs:
node test/*.mjs

Manual test protocol

1. Turn start/end, no double-speak. With Narrator or NVDA, send a prompt
   with 3+ tool calls. You should hear "Deep diving" at start and one
   worked/stopped/failed turn-end message, never a second "Turn started" or
   "Turn finished" from this plugin.
2. Concise. At Concise, each tool's start and finish is distinguishable by
   tool name; failures say "failed".
3. Detailed. Switch to Detailed and confirm finished messages include a
   result summary and duration.
4. Approvals. Trigger a tool that requires approval. You should hear the
   assertive approval announcement, focus should land in the approval card, and
   after answering, focus should return to the composer (or the previously
   focused control).
5. Questions. Trigger a question and confirm one assertive question
   announcement; the host question composer already autofocuses its input.
6. Skip link. Reload with no focus. Press Tab once: the skip link appears.
   Press Enter (or Tab again): focus lands at the latest turn boundary; the
   screen reader reads the turn heading.
7. Keyboard only. Start a session, send, stop, approve, and switch sessions
   without a mouse. With the focus-ring setting on Emphasized, every control
   should show a visible outline.
8. Reduced motion. Set OS reduced motion on, choose Allow motion, and
   confirm host transitions return; then choose Reduce motion with the OS
   preference off and confirm they collapse.
9. Zoom and width. Browser zoom 200% and a 320 px viewport: the
   Accessibility page rows stack; selects and buttons do not clip.
10. axe. Run axe-core over the app shell. Plugin-owned surfaces should have
    zero critical violations. Host findings below are recorded, not silently
    patched.

Host findings (for the DSH team)

These are host-level gaps observed while building this plugin. They are not
fixed by global CSS or DOM hacks here. They are tracked in
issue #1.

1. No skip link. The shell has no "skip to main content" control. The
   plugin can only put its link in shell.overlay, which is after the main
   content in DOM order; the first-Tab focus is implemented with a capture
   handler.
2. No additive slot at the start of the transcript. Turn tails are the
   earliest plugin-owned position inside the chat flow, so per-turn headings
   describe a turn from its end and the skip target is the latest turn
   boundary. A conversation.chat.turnHead/turn-start list slot (or a
   transcript-start anchor slot) would make this correct.
3. Approval card has no dialog/landmark/live region and no focus move.
   ApprovalPanel renders a warning strip and buttons inside the composer
   takeover but does not focus it; dsh-a11y supplies the announcement and
   focus move. A role="region"/aria-labelledby and focus move in the host
   would remove the need for both.
4. Tool lifecycle is silent. row.running / row.failed are visually
   hidden but not live regions. The host could own a single polite tool
   announcer; until then this plugin does.
5. Question and plan-review cards expose only error role="status". The
   question text itself is not announced when the card appears. The composer
   autofocuses its input, which mitigates but does not cover a pending card
   that appears while focus is elsewhere.
6. role="status" is used for several unrelated notices (retry, turn
   error, token cap) without an explicit aria-live; behavior depends on the
   screen reader. A consistent polite/assertive policy would help.
7. Heading order in the shell is uneven. There is no single main landmark
   in the frame; the center column and rightbar are generic containers. A
   `` around the active panel would give screen readers a reliable
   landmark.
8. Focus ring styling is per-component. Most controls have a visible
   focus style, but the plugin's Emphasized setting is still useful because
   some host controls inherit only a subtle outline.

v2 (not in this build)

The author kit remains the next step:

• ctx.a11y provided by this package, with announce(), `,useFocusTrap,useRovingTabIndex, andauditSubtree(ref)`.
• The audit panel that runs the kit against a plugin's own slot and produces
  pass/fail paths plus a manual checklist.
• Tests for the audit rules against fixture DOM.

ctx.provide() is available to a Client half, so ctx.a11y is feasible. The
kit must audit only the caller's own subtree, never a foreign plugin's DOM.

Package layout

License

MIT. See LICENSE.