From 6bef4e69dfd69e93fda4caf60dda7bbee1bc5ee4 Mon Sep 17 00:00:00 2001
From: AropJoe <josephbusa@outlook.com>
Date: Sat, 10 Oct 2026 00:23:21 +0100
Subject: [PATCH] Accessibility: WCAG 2.2 AA fixes, keyboard reading, and
 checks in CI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Contrast: dim text, red and field borders now meet AA (4.5:1 text, 3:1 fields).
- Focus is always visible in fields; a Skip to content link; the documents list
  is a proper table for screen readers.
- Keyboard: in a document, up and down select a paragraph and Enter adds it to
  notes; ⌘⇧N / Ctrl+Shift+N and ⌘⇧M work on any selection; the notebook menu
  moves with arrows.
- Reflow at 400% zoom without sideways scrolling, in the app and the workspace.
- The / shortcut can be turned off; the mascot stops moving within 5 seconds;
  workspace messages are announced.
- npm run a11y checks every main screen with axe-core against WCAG 2.2 A and
  AA; CI runs it on macOS.
---
 .github/workflows/ci.yml  | 13 ++++++
 .gitignore                |  1 +
 assets/ui/app.css         | 26 +++++++++--
 assets/ui/app.js          | 24 +++++++---
 assets/ui/index.html      |  5 ++-
 package-lock.json         | 11 +++++
 package.json              |  4 +-
 scripts/a11y-electron.cjs | 92 +++++++++++++++++++++++++++++++++++++++
 src/island.ts             |  2 +-
 src/viewer.ts             |  2 +-
 src/workspace.ts          | 77 ++++++++++++++++++++++++++++++--
 11 files changed, 238 insertions(+), 19 deletions(-)
 create mode 100644 scripts/a11y-electron.cjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index abd8003..431e408 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,3 +42,16 @@ jobs:
         with:
           name: dist
           path: dist/
+
+  accessibility:
+    # Every main screen against WCAG 2.2 A and AA with axe-core, in Chromium (scripts/a11y-electron.cjs).
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run a11y
diff --git a/.gitignore b/.gitignore
index b6ff400..98a6e66 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ ANNOUNCEMENT.md
 *.DS_Store
 social-preview.html
 release/
+a11y-report.json
diff --git a/assets/ui/app.css b/assets/ui/app.css
index f5f83f7..960764c 100644
--- a/assets/ui/app.css
+++ b/assets/ui/app.css
@@ -5,7 +5,8 @@
   --s3: #1f1f1d;
   --border: #252522;
   --border2: #34342f;
-  --muted: #6a6a65;
+  --field-border: #6a6a65;   /* text fields: 3:1 against every panel (WCAG 1.4.11) */
+  --muted: #888883;   /* 4.6:1 on the darkest panel: WCAG AA for small text */
   --subtle: #9a9a93;
   --body: #CFCEC6;
   --text: #F0EFE8;
@@ -15,7 +16,7 @@
   --lime-mark: #23310a;
   --warn: #E8A020;
   --warn-bg: #1E1408;
-  --danger: #E05555;
+  --danger: #E85E5E;
   --danger-bg: #1E0808;
   --mono: 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
   --sans: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', sans-serif;
@@ -84,7 +85,7 @@ body.no-mascot .mascot-slot { display: none; }
 .app { height: 100%; display: flex; flex-direction: column; }
 .topbar { display: flex; align-items: center; gap: 14px; padding: 10px 16px; border-bottom: 1px solid var(--border); background: var(--s1); }
 .brand { display: flex; align-items: center; gap: 8px; color: var(--text); text-decoration: none; font-family: var(--mono); font-weight: 650; font-size: 17px; letter-spacing: -0.03em; flex-shrink: 0; }
-.searchbar { flex: 1; max-width: 760px; margin: 0 auto; display: flex; align-items: center; gap: 8px; background: var(--bg); border: 1px solid var(--border2); border-radius: 12px; padding: 4px 10px 4px 4px; transition: border-color .15s; }
+.searchbar { flex: 1; max-width: 760px; margin: 0 auto; display: flex; align-items: center; gap: 8px; background: var(--bg); border: 1px solid var(--field-border); border-radius: 12px; padding: 4px 10px 4px 4px; transition: border-color .15s; }
 .searchbar:focus-within { border-color: var(--lime); }
 .searchbar input { flex: 1; min-width: 0; background: transparent; border: 0; outline: none; color: var(--text); font-size: 15px; padding: 8px 4px; }
 .searchbar input::-webkit-search-cancel-button { filter: invert(.6); }
@@ -435,3 +436,22 @@ dialog::backdrop { background: rgba(0,0,0,.55); }
 .visibility-row select, .visibility-row input { background: var(--bg); color: var(--text); border: 1px solid var(--border2); border-radius: var(--r); padding: 5px 8px; font: inherit; font-size: 12.5px; }
 .visibility-row input { flex: 1; min-width: 180px; }
 .visibility-row small { flex-basis: 100%; }
+
+/* Read by screen readers, not shown. */
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+
+/* Fields are outlined so they can be found (WCAG 1.4.11), and show where the keyboard is (2.4.7). */
+input:not([type=checkbox]):not([type=radio]):not([type=range]), select, textarea { border-color: var(--field-border); }
+input:focus-visible, select:focus-visible, textarea:focus-visible { outline: 2px solid var(--lime) !important; outline-offset: 1px; }
+.searchbar input:focus-visible { outline: none !important; }   /* the bar around it lights up instead */
+
+.skip-link { position: absolute; left: 12px; top: -48px; z-index: 100; background: var(--lime); color: #0C0C0B; font-weight: 600; padding: 8px 14px; border-radius: var(--r); text-decoration: none; }
+.skip-link:focus { top: 12px; }
+
+/* Zoomed in or narrow (WCAG 1.4.10: no sideways scrolling at 320 CSS pixels). */
+.result-actions { flex-wrap: wrap; }
+@media (max-width: 480px) {
+  .searchbar { min-width: 0; padding-left: 2px; }
+  .mode-switch .labs { display: none; }
+  .mode-switch .mode { padding-left: 8px; padding-right: 8px; }
+}
diff --git a/assets/ui/app.js b/assets/ui/app.js
index 46d51d0..9589486 100644
--- a/assets/ui/app.js
+++ b/assets/ui/app.js
@@ -263,11 +263,17 @@ function renderFeatureList(prefs, shortcut) {
   let html = FEATURE_GROUPS.map(g => '<h3>' + esc(g.title) + '</h3>' + g.items.map(([name, label, help]) => check('data-feature="' + name + '"', feature(name), label, help, !admin)).join('')).join('')
   html += '<h3>File types Duct reads</h3><p class="hint">Switched-off types are skipped when indexing and hidden from search. Turning one back on rescans watched folders.</p>'
   html += Object.keys(KIND_LABELS).map(kind => check('data-format-kind="' + kind + '"', kindOn(kind), KIND_LABELS[kind], '', !admin)).join('')
+  // Single-key shortcuts can be turned off (WCAG 2.1.4): speech input can type "/" by accident.
+  html += '<h3>Keyboard</h3>' + check('data-local="slashKey"', slashKeyOn(), 'Press / to search', 'Typing / anywhere outside a text box jumps to the search box. ⌘K or Ctrl+K always works.', false)
   if (prefs) html += '<h3>This computer</h3>' + DESKTOP_PREFS.map(([name, label, help]) => check('data-pref="' + name + '"', prefs[name] !== false, label, help, false) + (name === 'shortcut' ? shortcutRow(shortcut) : '')).join('')
   $('#featureList').innerHTML = html
   $('#featuresHint').textContent = admin ? 'Turn off anything you don’t use. Switched-off features disappear from Duct and its API.' : 'Only an admin can change these.'
 }
 
+function slashKeyOn() {
+  try { return localStorage.getItem('duct.slashKey') !== 'off' } catch { return true }
+}
+
 const DAY = 86400000
 const DATE_RANGES = [
   { id: 'week', label: 'Past week', after: () => Date.now() - 7 * DAY },
@@ -424,6 +430,9 @@ async function renderMascots() {
       canvas.height = slot.clientHeight * 2
       slot.appendChild(canvas)
       slot.player = new DotLottie({ canvas, src: '/mascot/mascot.lottie', animationId: POSES[pose], autoplay: !reduceMotion, loop: true })
+      // Movement stops by itself within 5 seconds (WCAG 2.2.2): it finishes the loop it's in and rests.
+      const player = slot.player
+      setTimeout(() => { try { player.setLoop(false) } catch {} }, 5000)
       slot.dataset.pose = pose
       slot.player.addEventListener('load', () => {
         if (reduceMotion) slot.player.setFrame(Math.floor(slot.player.totalFrames / 2))
@@ -1047,7 +1056,7 @@ $('#q').addEventListener('keydown', e => {
 
 document.addEventListener('keydown', e => {
   const typing = e.target.closest && e.target.closest('input, textarea, select, [contenteditable]')
-  if ((e.key === '/' && !typing) || ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k')) { e.preventDefault(); focusSearch() }
+  if ((e.key === '/' && !typing && slashKeyOn()) || ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k')) { e.preventDefault(); focusSearch() }
 })
 
 function focusSearch() {
@@ -1078,7 +1087,7 @@ function renderDocuments() {
     (docs.length === 1 ? 'Duct couldn’t read this file.' : 'Duct couldn’t read these ' + fmt(docs.length) + ' files.') + '</strong> ' +
     'Under each one is why, and what usually fixes it. Everything else is searchable meanwhile.</p></div>' : ''
   const statusOf = d => d.status === 'failed' ? '<span class="status bad">Couldn’t read</span>' : d.status === 'no-text' ? '<span class="status warn">No text (scan?)</span>' : '<span class="status ok">Indexed</span>'
-  $('#docTable').innerHTML = attentionNote + '<div class="doc-row head" role="row"><span></span><span>Name</span><span class="folder-col">Folder</span><span>Status</span><span></span></div>' +
+  $('#docTable').innerHTML = attentionNote + '<div class="doc-row head" role="row"><span role="columnheader"><span class="sr-only">Type</span></span><span role="columnheader">Name</span><span class="folder-col" role="columnheader">Folder</span><span role="columnheader">Status</span><span role="columnheader"><span class="sr-only">Actions</span></span></div>' +
     docs.slice(0, 2000).map(d => {
       const link = isLink(d.path)
       const actions = []
@@ -1087,12 +1096,12 @@ function renderDocuments() {
       if (d.status === 'no-text' && !link && isAdmin() && feature('ocrOnDemand')) actions.push('<button class="btn btn-sm" data-doc-act="ocr">Read with OCR</button>')
       if (desktop && desktop.revealDocument && !link) actions.push('<button class="btn btn-sm" data-doc-act="reveal">Show</button>')
       if (isAdmin()) actions.push('<button class="btn btn-sm btn-danger" data-doc-act="remove" title="Remove from Duct">✕</button>')
-      return '<div class="doc-row" role="row" data-path="' + esc(d.path) + '">' + badge(d.format) +
-        '<span class="name-cell"><span class="name" title="' + esc((d.displayName || fileName(d.path)) + '\n' + d.path) + '">' + esc(d.displayName || fileName(d.path)) + '</span>' +
+      return '<div class="doc-row" role="row" data-path="' + esc(d.path) + '"><span role="cell">' + badge(d.format) + '</span>' +
+        '<span class="name-cell" role="cell"><span class="name" title="' + esc((d.displayName || fileName(d.path)) + '\n' + d.path) + '">' + esc(d.displayName || fileName(d.path)) + '</span>' +
         ((d.tags || []).length ? '<span class="tags">' + d.tags.map(t => '<span class="tag">' + esc(t) + '</span>').join('') + '</span>' : '') + '</span>' +
-        '<span class="folder">' + esc(link ? d.path : d.source === 'library' ? 'Duct Library' : folderOf(d.path)) + '</span>' +
-        statusOf(d) + '<span class="row-actions">' + actions.join('') + '</span>' +
-        (d.status === 'failed' && d.error ? '<span class="err" title="' + esc(d.error) + '">' + esc(fileProblem(d.error)) + '</span>' : '') + '</div>'
+        '<span class="folder" role="cell">' + esc(link ? d.path : d.source === 'library' ? 'Duct Library' : folderOf(d.path)) + '</span>' +
+        '<span role="cell">' + statusOf(d) + '</span><span class="row-actions" role="cell">' + actions.join('') + '</span>' +
+        (d.status === 'failed' && d.error ? '<span class="err" role="cell" title="' + esc(d.error) + '">' + esc(fileProblem(d.error)) + '</span>' : '') + '</div>'
     }).join('')
   if (attention) renderMascots()
 }
@@ -1781,6 +1790,7 @@ $('#settings').addEventListener('change', async e => {
     } catch (err) { el.checked = !el.checked; toast('Couldn’t save that. ' + err.message, true) }
     return
   }
+  if (el.dataset.local === 'slashKey') { try { localStorage.setItem('duct.slashKey', el.checked ? 'on' : 'off') } catch {} return }
   if (el.dataset.pref) {
     const ok = await desktop.setPref(el.dataset.pref, el.checked).catch(() => false)
     if (!ok) { el.checked = !el.checked; toast('Couldn’t save that. Try again?', true); return }
diff --git a/assets/ui/index.html b/assets/ui/index.html
index 72a93b7..4acfaa1 100644
--- a/assets/ui/index.html
+++ b/assets/ui/index.html
@@ -9,6 +9,7 @@
   <script type="module" src="/ui/app.js"></script>
 </head>
 <body>
+  <a class="skip-link" href="#content">Skip to content</a>
   <div class="offline-note" id="offlineNote" role="status" hidden>You’re offline. Everything in Duct is still searchable.</div>
   <!-- First run: shown until something has been added (or the person skips it). -->
   <section id="welcome" class="welcome" hidden aria-labelledby="welcomeTitle">
@@ -116,7 +117,7 @@ <h2>Sources</h2>
         </div>
       </aside>
 
-      <main class="content" id="content">
+      <main class="content" id="content" tabindex="-1">
         <section id="viewHome" class="view" aria-label="Home">
           <div class="home">
             <div class="mascot-slot mascot-lg" data-mascot="idle" aria-hidden="true"></div>
@@ -405,7 +406,7 @@ <h2 id="feedbackTitle">Send feedback</h2>
     <div class="collect-body">
       <p class="hint">Tell us what worked, what didn’t, or what you expected. It goes to the Duct team at Tensflare.</p>
       <label class="field"><span>Your message</span><textarea id="feedbackMessage" rows="6" maxlength="5000" placeholder="What happened? What did you expect?"></textarea></label>
-      <label class="field"><span>Email <small>optional, if you’d like a reply</small></span><input type="email" id="feedbackEmail" maxlength="254"></label>
+      <label class="field"><span>Email <small>optional, if you’d like a reply</small></span><input type="email" id="feedbackEmail" maxlength="254" autocomplete="email"></label>
       <label class="check"><input type="checkbox" id="feedbackDiag" checked> <span><strong>Include diagnostics</strong><small>Version, operating system, settings and error codes. Never your documents, file names, paths or searches.</small></span></label>
       <details class="telemetry-details"><summary>See exactly what’s included</summary><pre id="feedbackDiagPreview"></pre></details>
       <label class="check" id="feedbackCrashRow" hidden><input type="checkbox" id="feedbackCrashes"> <span><strong>Include crash reports (<span id="feedbackCrashCount">0</span>)</strong><small>The type of error and the place in Duct’s code where it happened. No messages, documents or paths.</small></span></label>
diff --git a/package-lock.json b/package-lock.json
index 9a6ee33..a5e584c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -40,6 +40,7 @@
         "@types/express": "^4.17.0",
         "@types/multer": "^1.4.0",
         "@types/node": "^22.20.5",
+        "axe-core": "^4.14.0",
         "cohere-ai": "^8.0.0",
         "electron": "^42.3.0",
         "electron-builder": "^26.8.1",
@@ -3296,6 +3297,16 @@
         "node": ">= 4.0.0"
       }
     },
+    "node_modules/axe-core": {
+      "version": "4.14.0",
+      "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz",
+      "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/balanced-match": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
diff --git a/package.json b/package.json
index fac56df..b9cbe6d 100644
--- a/package.json
+++ b/package.json
@@ -38,7 +38,8 @@
     "electron:build": "npm run build && electron-builder --mac --linux --win",
     "electron:build:mac": "npm run build && electron-builder --mac",
     "icons": "node scripts/build-icons.mjs",
-    "bench": "node scripts/bench.mjs"
+    "bench": "node scripts/bench.mjs",
+    "a11y": "electron scripts/a11y-electron.cjs"
   },
   "build": {
     "appId": "com.docfide.duct",
@@ -135,6 +136,7 @@
     "@types/express": "^4.17.0",
     "@types/multer": "^1.4.0",
     "@types/node": "^22.20.5",
+    "axe-core": "^4.14.0",
     "cohere-ai": "^8.0.0",
     "electron": "^42.3.0",
     "electron-builder": "^26.8.1",
diff --git a/scripts/a11y-electron.cjs b/scripts/a11y-electron.cjs
new file mode 100644
index 0000000..2160bc6
--- /dev/null
+++ b/scripts/a11y-electron.cjs
@@ -0,0 +1,92 @@
+// Accessibility check: starts Duct with a small sample library, opens every main screen in Chromium and runs axe-core
+// with the WCAG 2.2 A and AA rules. Exits 1 if any screen has a violation. Runs inside Electron, as the desktop app
+// does, so the pages are checked in the browser that shows them.
+//
+//   npm run build && npm run a11y            # also writes a11y-report.json
+//
+// What it can't check (the screen reader experience, whether the wording makes sense, keyboard flows end to end) is
+// in docs/accessibility.md, with how we test those by hand.
+const { app, BrowserWindow } = require('electron')
+const { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const { join } = require('node:path')
+
+const root = join(__dirname, '..')
+const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa']
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function main() {
+  const { Duct } = await import(join(root, 'dist/index.js'))
+  const { createServer } = await import(join(root, 'dist/server.js'))
+  const { default: JSZip } = await import('jszip')
+  const work = mkdtempSync(join(tmpdir(), 'duct-a11y-'))
+  const lib = join(work, 'Contracts')
+  mkdirSync(lib, { recursive: true })
+  writeFileSync(join(lib, 'Lease renewal.md'), '# Lease renewal\n\nThe tenant may terminate the lease on 90 days notice.\n\nRent is reviewed every two years.\n')
+  writeFileSync(join(lib, 'Board minutes.txt'), 'The board approved the lease renewal and the tax holiday application.')
+  const zip = new JSZip()
+  zip.file('[Content_Types].xml', '<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>')
+  zip.file('_rels/.rels', '<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>')
+  zip.file('word/document.xml', '<?xml version="1.0"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p><w:r><w:t>Supply agreement. The supplier may terminate on 30 days notice.</w:t></w:r></w:p></w:body></w:document>')
+  writeFileSync(join(lib, 'Supply agreement.docx'), await zip.generateAsync({ type: 'nodebuffer' }))
+
+  const duct = new Duct({ embed: false, persistPath: join(work, 'index') })
+  await duct.index(lib)
+  const server = createServer(duct, { libraryDir: join(work, 'library') }).listen(0, '127.0.0.1')
+  await new Promise(r => server.once('listening', r))
+  const base = `http://127.0.0.1:${server.address().port}`
+  const post = (path, body) => fetch(base + path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }).then(r => r.json())
+  const { notebook } = await post('/api/notebooks', { name: 'Lease review' })
+  await post(`/api/notebooks/${notebook.id}/notes`, { path: join(lib, 'Lease renewal.md'), quote: 'The tenant may terminate the lease on 90 days notice.' })
+  const page = await (await fetch(`${base}/api/notebooks/${notebook.id}/export?format=html`)).text()
+  writeFileSync(join(work, 'notebook.html'), page)
+
+  const enc = encodeURIComponent
+  const screens = [
+    { name: 'Home', url: base + '/' },
+    { name: 'Search results with preview', url: base + '/', js: "const q=document.querySelector('#q'); q.value='terminate'; q.dispatchEvent(new Event('input'))" },
+    { name: 'Search that finds nothing', url: base + '/', js: "const q=document.querySelector('#q'); q.value='zebracorn'; q.dispatchEvent(new Event('input'))" },
+    { name: 'All documents', url: base + '/', js: "document.querySelector('[data-view=documents]').click()" },
+    { name: 'Notebooks', url: base + '/', js: "document.querySelector('[data-view=notebooks]').click()" },
+    { name: 'Settings', url: base + '/', js: 'window.duct.openSettings()' },
+    { name: 'Workspace, one document', url: `${base}/workspace?layout=one&left=${enc(join(lib, 'Supply agreement.docx'))}&lterms=${enc('["terminate"]')}` },
+    { name: 'Workspace, side by side with notes', url: `${base}/workspace?layout=cols&left=${enc(join(lib, 'Lease renewal.md'))}&right=${enc(join(lib, 'Board minutes.txt'))}&notebook=${notebook.id}` },
+    { name: 'Shared notebook page', url: 'file://' + join(work, 'notebook.html') },
+  ]
+
+  const axe = readFileSync(require.resolve('axe-core/axe.min.js'), 'utf8')
+  const report = []
+  // One window for every screen: creating and destroying offscreen windows in a row can crash Electron.
+  const win = new BrowserWindow({ width: 1400, height: 900, show: false, webPreferences: { offscreen: true } })
+  for (const screen of screens) {
+    try {
+      await win.loadURL(screen.url)
+      await sleep(1500)
+      if (screen.js) { await win.webContents.executeJavaScript(`{ ${screen.js} }`); await sleep(1200) }
+      await win.webContents.executeJavaScript(axe)
+      const result = await win.webContents.executeJavaScript(`axe.run(document, { runOnly: { type: 'tag', values: ${JSON.stringify(TAGS)} }, resultTypes: ['violations'] })
+        .then(r => ({ passes: r.passes.length, violations: r.violations.map(v => ({ id: v.id, impact: v.impact, help: v.help, helpUrl: v.helpUrl, nodes: v.nodes.map(n => ({ target: n.target, summary: n.failureSummary })) })) }))`)
+      report.push({ name: screen.name, ...result })
+    } catch (err) {
+      report.push({ name: screen.name, passes: 0, violations: [{ id: 'page-failed', impact: 'critical', help: String((err && err.message) || err), nodes: [] }] })
+    }
+  }
+  win.destroy()
+  writeFileSync(join(root, 'a11y-report.json'), JSON.stringify(report, null, 2))
+  let total = 0
+  for (const s of report) {
+    total += s.violations.length
+    console.log(`${s.violations.length ? '✗' : '✓'} ${s.name}: ${s.violations.length ? s.violations.length + ' problem(s)' : `no problems (${s.passes} checks passed)`}`)
+    for (const v of s.violations) {
+      console.log(`    [${v.impact}] ${v.id}: ${v.help}`)
+      for (const n of v.nodes.slice(0, 4)) console.log(`        ${n.target.join(' ')}  ${n.summary ? '— ' + n.summary.split('\n').slice(0, 2).join(' ') : ''}`)
+    }
+  }
+
+  server.close()
+  duct.close()
+  rmSync(work, { recursive: true, force: true })
+  return total
+}
+
+app.whenReady().then(main).then(total => app.exit(total ? 1 : 0), err => { console.error(err); app.exit(2) })
diff --git a/src/island.ts b/src/island.ts
index 64822b0..8ea5e72 100644
--- a/src/island.ts
+++ b/src/island.ts
@@ -10,7 +10,7 @@ export const islandHtml = `<!DOCTYPE html>
 <style>
 :root {
   --black: #000000; --s1: #111110; --s2: #181816; --border: #252522; --border2: #333330;
-  --muted: #6b6b67; --subtle: #9a9a95; --body: #C8C7C0; --text: #F0EFE8; --lime: #A3E635;
+  --muted: #888883; --subtle: #9a9a95; --body: #C8C7C0; --text: #F0EFE8; --lime: #A3E635;
   --mono: 'SF Mono','Fira Code','Cascadia Code','Consolas',monospace;
   --sans: -apple-system,BlinkMacSystemFont,'Inter',sans-serif;
   --ease: cubic-bezier(.2, .9, .25, 1.1);
diff --git a/src/viewer.ts b/src/viewer.ts
index b1a910e..306787c 100644
--- a/src/viewer.ts
+++ b/src/viewer.ts
@@ -12,7 +12,7 @@ export const viewerHtml = `<!DOCTYPE html>
 <style>
 :root {
   --black: #0C0C0B; --s1: #111110; --s2: #181816; --border: #252522; --border2: #333330;
-  --muted: #555552; --subtle: #888883; --text: #F0EFE8; --lime: #A3E635; --lime-bg: #141A06;
+  --muted: #888883; --subtle: #9a9a93; --text: #F0EFE8; --lime: #A3E635; --lime-bg: #141A06;
   --mono: 'SF Mono','Fira Code','Cascadia Code','Consolas',monospace;
   --sans: -apple-system,BlinkMacSystemFont,'Inter',sans-serif;
 }
diff --git a/src/workspace.ts b/src/workspace.ts
index db8e3ff..e9a608e 100644
--- a/src/workspace.ts
+++ b/src/workspace.ts
@@ -18,7 +18,7 @@ export const workspaceHtml = `<!DOCTYPE html>
 <style>
 :root {
   --black: #0C0C0B; --s1: #111110; --s2: #181816; --border: #252522; --border2: #333330;
-  --muted: #555552; --subtle: #888883; --text: #F0EFE8; --lime: #A3E635; --lime-bg: #141A06; --red: #F87171;
+  --field-border: #6a6a65; --muted: #888883; --subtle: #9a9a93; --text: #F0EFE8; --lime: #A3E635; --lime-bg: #141A06; --red: #F87171;
   --mono: 'SF Mono','Fira Code','Cascadia Code','Consolas',monospace;
   --sans: -apple-system,BlinkMacSystemFont,'Inter',sans-serif;
 }
@@ -34,7 +34,7 @@ button:disabled { opacity: .4; cursor: default; }
 button.primary { background: var(--lime); border-color: var(--lime); color: #0C0C0B; font-weight: 600; }
 button.ghost { border-color: transparent; color: var(--subtle); padding: 4px 6px; }
 button.ghost:hover:not(:disabled) { color: var(--text); border-color: transparent; }
-select, input, textarea { background: var(--black); border: 1px solid var(--border2); border-radius: 6px; padding: 4px 8px; }
+select, input, textarea { background: var(--black); border: 1px solid var(--field-border); border-radius: 6px; padding: 4px 8px; }
 :focus-visible { outline: 2px solid var(--lime); outline-offset: 1px; }
 
 .top { height: 44px; flex: none; display: flex; align-items: center; gap: 10px; padding: 0 14px; background: var(--s1); border-bottom: 1px solid var(--border); font-family: var(--mono); font-size: 12px; }
@@ -112,6 +112,9 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
 .transcript .line .time { flex: none; font-family: var(--mono); font-size: 11px; color: var(--lime); padding: 0 4px; }
 .transcript .line.playing { background: var(--lime-bg); border-radius: 4px; }
 .text-view { padding: 24px clamp(16px, 4vw, 48px) 60px; background: var(--black); min-height: 100%; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; }
+.text-view .para { margin: 0 0 .8em; white-space: pre-wrap; }
+.scroller:focus-visible { outline: 2px solid var(--lime); outline-offset: -2px; }
 .text-view .sec { max-width: 78ch; margin: 0 auto 26px; }
 .text-view .sec-label { user-select: none; -webkit-user-select: none; font-family: var(--mono); font-size: 10px; letter-spacing: .08em; text-transform: uppercase; color: var(--lime); margin: 0 0 8px; padding-top: 8px; border-top: 1px solid var(--border); }
 .text-view .sec-text { white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.6; font-size: 14px; }
@@ -124,6 +127,14 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
 .textLayer .highlight { background-color: rgba(163, 230, 53, 0.35) !important; border-radius: 2px; }
 .textLayer .highlight.selected { background-color: rgba(163, 230, 53, 0.75) !important; }
 
+@media (max-width: 720px) {
+  /* Narrow or zoomed in: the notes go under the documents, and the bars wrap (WCAG 1.4.10). */
+  main { flex-direction: column; }
+  .notes { width: auto !important; max-height: 33%; border-top: 1px solid var(--border); }
+  .rich { margin: 8px; padding: 16px; }
+  .text-view { padding: 12px; }
+  .top, .pane-head { height: auto; min-height: 38px; flex-wrap: wrap; padding-top: 4px; padding-bottom: 4px; }
+}
 .notes { width: 340px; flex: none; display: flex; flex-direction: column; background: var(--s1); min-height: 0; }
 .notes[hidden] { display: none; }
 .notes-head { flex: none; padding: 10px; display: flex; flex-direction: column; gap: 8px; border-bottom: 1px solid var(--border); font-family: var(--mono); font-size: 12px; }
@@ -212,13 +223,14 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
   <button class="primary go" id="addPopGo">Add to notes</button><button class="primary more" id="addPopMore" aria-haspopup="true" aria-expanded="false" title="Choose a notebook" aria-label="Choose a notebook">▾</button>
   <div class="menu-pop" id="addPopMenu" hidden></div>
 </div>
-<div class="toast" id="toast" hidden></div>
+<div class="toast" id="toast" role="status" aria-live="polite" hidden></div>
 <script type="module">
   const $ = id => document.getElementById(id)
   const params = new URLSearchParams(location.search)
   const TEXT_FORMATS = new Set(['md', 'code', 'txt'])
   const RASTER = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp'])
   const WS = new RegExp('\\\\s+', 'g')
+  const PARA = new RegExp('\\\\n\\\\s*\\\\n')
   const WORD_CHAR = new RegExp('[\\\\p{L}\\\\p{N}]', 'u')
 
   function h(tag, props, ...kids) {
@@ -509,6 +521,7 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
       })
       const scroller = h('div', { class: 'scroller' }, view)
       this.body.append(h('div', { class: 'audio-pane' }, bar, scroller))
+      this.keyboardReading(view, scroller)
       // From a result: cue the recording at its minute (it doesn't start playing by itself).
       if (this.page > 1) {
         const first = lines.find(l => Number(l.dataset.at) >= (this.page - 1) * 60)
@@ -538,11 +551,46 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
       }
       scroller.append(page)
       this.body.append(scroller)
+      this.keyboardReading(page, scroller)
       this.findInput.hidden = false
       this.findInput.value = this.terms.join(' ')
       if (this.terms.length) this.domFind(false, false)
     }
 
+    /**
+     * Reading with the keyboard (text, formatted and transcript views): Tab to the document, then up and down select a
+     * paragraph at a time, and Enter adds it to notes. Screen readers hear each paragraph as it's selected.
+     */
+    keyboardReading(root, scroller) {
+      scroller.tabIndex = 0
+      scroller.setAttribute('role', 'region')
+      scroller.setAttribute('aria-label', 'Document. Up and down arrows select a paragraph; Enter adds it to notes.')
+      const live = h('div', { class: 'sr-only', 'aria-live': 'polite' })
+      scroller.append(live)
+      let at = -1
+      const blocks = () => [...root.querySelectorAll('p, li, td, th, h1, h2, h3, h4, h5, h6, blockquote, pre, dd, .line')]
+        .filter(el => el.textContent.trim() && !el.querySelector('p, li, .line'))
+      scroller.addEventListener('keydown', e => {
+        if (e.target !== scroller) return
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+          const all = blocks()
+          if (!all.length) return
+          e.preventDefault()
+          at = Math.max(0, Math.min(all.length - 1, at + (e.key === 'ArrowDown' ? 1 : -1)))
+          const el = all[at]
+          const range = document.createRange()
+          range.selectNodeContents(el)
+          const sel = getSelection(); sel.removeAllRanges(); sel.addRange(range)
+          el.scrollIntoView({ block: 'nearest' })
+          live.textContent = el.textContent.trim().slice(0, 300)
+          checkSelection()
+        } else if (e.key === 'Enter' && pending) {
+          e.preventDefault()
+          addPending(addGo.dataset.target)
+        }
+      })
+    }
+
     /** Find in the formatted or text view: marks every match, and steps through them in order. */
     domFind(again, previous) {
       const root = this.body.querySelector('.rich, .text-view')
@@ -612,11 +660,12 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
         shown += s.text.length
         view.append(h('div', { class: 'sec', 'data-page': s.page || false },
           s.title ? h('p', { class: 'sec-label', text: s.title }) : null,
-          h('div', { class: 'sec-text', text: s.text })))
+          h('div', { class: 'sec-text' }, s.text.split(PARA).filter(t => t.trim()).map(t => h('p', { class: 'para', text: t })))))
       }
       if (!data.sections.length) view.append(h('div', { class: 'empty', text: 'Duct found no text in this document.' }))
       const scroller = h('div', { class: 'scroller' }, view)
       this.body.append(scroller)
+      this.keyboardReading(view, scroller)
       const paged = data.sections.filter(s => s.page)
       if (paged.length > 1) {
         this.pageInput.hidden = this.pageCount.hidden = false
@@ -1184,6 +1233,18 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
   }
   document.addEventListener('mouseup', e => { if (!addPop.contains(e.target)) setTimeout(checkSelection, 0) })
   document.addEventListener('keyup', e => { if (e.key.startsWith('Arrow') && e.shiftKey) checkSelection(); if (e.key === 'Escape') hidePop() })
+  // Without a mouse: select with the keyboard (caret browsing: F7 in the desktop app), then ⌘⇧N or Ctrl+Shift+N adds
+  // the selection to the notebook shown, and ⌘⇧M or Ctrl+Shift+M opens the menu of notebooks.
+  document.addEventListener('keydown', e => {
+    if (!(e.metaKey || e.ctrlKey) || !e.shiftKey) return
+    const key = e.key.toLowerCase()
+    if (key !== 'n' && key !== 'm') return
+    checkSelection()
+    if (!pending) { toast('Select some text in a document first.'); return }
+    e.preventDefault()
+    if (key === 'n') addPending(addGo.dataset.target)
+    else { drawAddMenu(); addMenu.hidden = false; addMore.setAttribute('aria-expanded', 'true'); addMenu.querySelector('button')?.focus({ preventScroll: true }) }
+  })
   addPop.addEventListener('mousedown', e => e.preventDefault())  // keep the selection while clicking
   addGo.addEventListener('click', () => addPending(addGo.dataset.target))
   addMore.addEventListener('click', () => {
@@ -1193,6 +1254,14 @@ mark.ws-find.current { background: var(--lime); outline: 2px solid var(--lime);
     addMore.setAttribute('aria-expanded', String(open))
     if (open) addMenu.querySelector('button')?.focus({ preventScroll: true })
   })
+  addMenu.addEventListener('keydown', e => {
+    // Up and down move through the notebooks; Escape closes the menu.
+    const items = [...addMenu.querySelectorAll('button')]
+    const i = items.indexOf(document.activeElement)
+    if (e.key === 'ArrowDown') { e.preventDefault(); items[(i + 1) % items.length]?.focus() }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); items[(i - 1 + items.length) % items.length]?.focus() }
+    else if (e.key === 'Escape') { closeAddMenu(); addMore.focus() }
+  })
   addMenu.addEventListener('click', e => { const t = e.target.closest('[data-target]'); if (t) addPending(t.dataset.target) })
 
   /** Adds the selected text to notebook target (an id, or "new" to start one named after the document). */