feat: keyboard-accessible canvas (WCAG 2.2 AA) + installable PWA (#27)

Accessibility (a governance MUST, and a genuine differentiator — a
spatial PKM you can drive without a mouse):
- Navigation.res: pure geometry to find the nearest note in a direction;
  arrow keys move the selection, Alt+arrow nudges the selected note.
  Wired through new NavigateCanvas / NudgeSelectedNote messages so the
  logic sees current state (the global key handler is registered once).
  Suppressed while typing in inputs/textareas.
- ARIA + focus: sidebar rows are real <button>s inside <li> (valid list
  semantics); canvas notes are role=button, focusable, Enter/Space edits;
  toolbar has role=toolbar with aria-pressed toggles; search/zoom/clear
  controls get accessible names; error banner is role=alert.
- styles.css: :focus-visible rings, prefers-reduced-motion, and contrast
  fixes — a darker --accent-strong behind light text on the primary and
  active buttons, and a lighter dirty-indicator, clearing the last
  sub-4.5:1 nodes.

PWA (true offline, local-first):
- manifest.webmanifest + icon.svg, plain-JS service-worker.js (precache
  app shell + wasm, cache-first). Registered best-effort at startup;
  theme-color + manifest/icon links in index.html. build/dev scripts now
  copy the icon too.

Verified: cargo test (5 suites), deno test:ui (7, incl. new Navigation
geometry), deno lint. E2E (headless Chromium): ArrowRight moves selection
between canvas notes, Alt+ArrowRight nudges +20px, service worker reaches
ready, manifest/theme/icon load, and axe-core reports 0 serious/critical
WCAG 2.2 AA violations in the canvas-active state.


Claude-Session: https://claude.ai/code/session_01PAEqVP7Y3bZDhtAaPUTbps

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

scripts/build.js

@@ -27,6 +27,7 @@ for (
     "styles.css",
     "manifest.webmanifest",
     "service-worker.js",
+    "icon.svg",
   ]
 ) {
   try {

scripts/dev.js

@@ -34,6 +34,7 @@ for (
     "styles.css",
     "manifest.webmanifest",
     "service-worker.js",
+    "icon.svg",
   ]
 ) {
   try {

ui/src/Main.res

@@ -33,21 +33,42 @@ module App = {
       let handleKeyDown = (e: DomBindings.keyboardEvent) => {
         let key = DomBindings.key(e)
         let modKey = DomBindings.ctrlKey(e) || DomBindings.metaKey(e)
+        let typing = DomBindings.isTyping(e)
 
-        switch (modKey, key) {
-        | (true, "n") => {
+        // Arrow keys drive keyboard-only canvas navigation. Alt+arrow nudges
+        // the selected note; a plain arrow moves the selection. Suppressed
+        // while typing so text fields keep their caret movement.
+        let arrow = switch key {
+        | "ArrowUp" => Some(Types.Up)
+        | "ArrowDown" => Some(Types.Down)
+        | "ArrowLeft" => Some(Types.Left)
+        | "ArrowRight" => Some(Types.Right)
+        | _ => None
+        }
+
+        switch (modKey, key, arrow, typing) {
+        | (true, "n", _, _) => {
             DomBindings.preventDefault(e)
             dispatch(Msg.CreateNote)
           }
-        | (true, "s") => {
+        | (true, "s", _, _) => {
             DomBindings.preventDefault(e)
             dispatch(Msg.SaveNotebook)
           }
-        | (false, "Escape") => {
+        | (_, _, Some(direction), false) => {
+            DomBindings.preventDefault(e)
+            if DomBindings.altKey(e) {
+              dispatch(Msg.NudgeSelectedNote(direction))
+            } else {
+              dispatch(Msg.NavigateCanvas(direction))
+            }
+          }
+        | (false, "Escape", _, _) => {
             dispatch(Msg.ClearSelection)
             dispatch(Msg.StopEditingNote)
           }
-        | (false, "Delete") | (false, "Backspace") => dispatch(Msg.DeleteSelectedNotes)
+        | (false, "Delete", _, false) | (false, "Backspace", _, false) =>
+          dispatch(Msg.DeleteSelectedNotes)
         | _ => ()
         }
       }
@@ -60,6 +81,15 @@ module App = {
   }
 }
 
+// Register the offline service worker (best-effort; never blocks startup).
+%%raw(`
+if ("serviceWorker" in navigator) {
+  globalThis.addEventListener("load", () => {
+    navigator.serviceWorker.register("./service-worker.js").catch(() => {});
+  });
+}
+`)
+
 let start = async () => {
   try {
     await WasmStore.init("./wasm/nexia_core_bg.wasm")

ui/src/Msg.res

@@ -33,6 +33,9 @@ type msg =
   | PanCanvas(float, float)
   | ZoomCanvas(float)
   | ResetViewport
+  // Keyboard canvas navigation
+  | NavigateCanvas(direction)
+  | NudgeSelectedNote(direction)
   // Search
   | SetSearchQuery(string)
   | ClearSearch

ui/src/Navigation.res

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MPL-2.0
+/// Pure geometry for keyboard navigation on the spatial canvas: given a
+/// focused note and a direction, find the nearest note that lies (mostly) in
+/// that direction. Kept side-effect-free so it is unit-testable under
+/// `deno test` without a DOM.
+
+open Types
+
+let positionOf = (note: note): option<point2D> => note.position
+
+/// Candidate must lie in the half-plane of `direction` from `origin`, then we
+/// score by along-axis distance plus a penalty for lateral drift so a note
+/// straight ahead beats one far off to the side.
+let score = (~origin: point2D, ~target: point2D, ~direction: direction): option<float> => {
+  let dx = target.x -. origin.x
+  let dy = target.y -. origin.y
+  let (along, lateral) = switch direction {
+  | Up => (-.dy, dx)
+  | Down => (dy, dx)
+  | Left => (-.dx, dy)
+  | Right => (dx, dy)
+  }
+  if along <= 0.0 {
+    None
+  } else {
+    Some(along +. Js.Math.abs_float(lateral) *. 2.0)
+  }
+}
+
+/// The nearest positioned note to `fromId` in `direction`, if any.
+let nearestInDirection = (
+  ~notes: array<note>,
+  ~fromId: noteId,
+  ~direction: direction,
+): option<noteId> => {
+  switch notes->Array.find(n => n.id == fromId) {
+  | None => None
+  | Some(current) =>
+    switch positionOf(current) {
+    | None => None
+    | Some(origin) =>
+      notes->Array.reduce(None, (best, candidate) => {
+        if candidate.id == fromId {
+          best
+        } else {
+          switch positionOf(candidate) {
+          | None => best
+          | Some(target) =>
+            switch score(~origin, ~target, ~direction) {
+            | None => best
+            | Some(s) =>
+              switch best {
+              | Some((_, bestScore)) if bestScore <= s => best
+              | _ => Some((candidate.id, s))
+              }
+            }
+          }
+        }
+      })->Option.map(((id, _)) => id)
+    }
+  }
+}
+
+/// The step, in canvas units, that a modifier+arrow nudge moves a note.
+let nudgeStep = 20.0
+
+/// Apply a nudge to a position in the given direction.
+let nudge = (~position: point2D, ~direction: direction): point2D =>
+  switch direction {
+  | Up => {...position, y: position.y -. nudgeStep}
+  | Down => {...position, y: position.y +. nudgeStep}
+  | Left => {...position, x: position.x -. nudgeStep}
+  | Right => {...position, x: position.x +. nudgeStep}
+  }

ui/src/Types.res

@@ -45,6 +45,13 @@ type selection =
   | SingleNote(noteId)
   | MultipleNotes(array<noteId>)
 
+/// A cardinal direction for keyboard navigation on the canvas.
+type direction =
+  | Up
+  | Down
+  | Left
+  | Right
+
 /// Canvas viewport state
 type viewport = {
   offsetX: float,

ui/src/Update.res

@@ -197,6 +197,39 @@ let rec update = (model: model, msg: msg): model => {
 
   | ResetViewport => {...model, viewport: Viewport.initial()}
 
+  // Move the selection to the nearest note in a direction (keyboard nav).
+  | NavigateCanvas(direction) =>
+    switch model.selection {
+    | SingleNote(id) =>
+      switch Navigation.nearestInDirection(~notes=allNotes(model), ~fromId=id, ~direction) {
+      | Some(next) => {...model, selection: SingleNote(next)}
+      | None => model
+      }
+    | _ =>
+      // Nothing focused yet: select the first positioned note, if any.
+      switch allNotes(model)->Array.find(n => n.position->Option.isSome) {
+      | Some(note) => {...model, selection: SingleNote(note.id)}
+      | None => model
+      }
+    }
+
+  // Nudge the selected note (modifier+arrow); the mouse equivalent is PR-D.
+  | NudgeSelectedNote(direction) =>
+    switch model.selection {
+    | SingleNote(id) =>
+      switch Model.getNote(model, id) {
+      | Some(note) =>
+        let base = switch note.position {
+        | Some(p) => p
+        | None => {x: 0.0, y: 0.0}
+        }
+        let next = Navigation.nudge(~position=base, ~direction)
+        patchNote(model, WasmStore.moveNote(id, next.x, next.y))
+      | None => model
+      }
+    | _ => model
+    }
+
   // Search
   | SetSearchQuery(query) => {
       ...model,

ui/src/View.res

@@ -5,6 +5,15 @@ open Types
 open Model
 open Msg
 
+// Enter / Space activate an element exposed as role="button".
+let onActivateKey = (handler: unit => unit, e: ReactEvent.Keyboard.t) =>
+  switch ReactEvent.Keyboard.key(e) {
+  | "Enter" | " " =>
+    ReactEvent.Keyboard.preventDefault(e)
+    handler()
+  | _ => ()
+  }
+
 module Sidebar = {
   @react.component
   let make = (~model: model, ~dispatch: msg => unit) => {
@@ -23,16 +32,18 @@ module Sidebar = {
         <input
           type_="text"
           placeholder="Search notes..."
+          ariaLabel="Search notes"
           value={model.searchQuery}
           onChange={e => dispatch(SetSearchQuery(ReactEvent.Form.target(e)["value"]))}
         />
         {model.searchQuery != ""
-          ? <button onClick={_ => dispatch(ClearSearch)} className="btn-clear">
+          ? <button
+              ariaLabel="Clear search" onClick={_ => dispatch(ClearSearch)} className="btn-clear">
               {React.string("×")}
             </button>
           : React.null}
       </div>
-      <ul className="note-list">
+      <ul className="note-list" ariaLabel="Notes">
         {(
           model.searchQuery != "" ? model.searchResults : notes->Array.map(n => n.id)
         )
@@ -44,18 +55,21 @@ module Sidebar = {
             | MultipleNotes(ids) => Array.includes(ids, id)
             | NoSelection => false
             }
-            <li
-              key={id}
-              className={isSelected ? "note-item selected" : "note-item"}
-              onClick={_ => dispatch(SelectNote(id))}>
-              <span className="note-title">
-                {React.string(note.title != "" ? note.title : "Untitled")}
-              </span>
-              <span className="note-meta">
-                {React.string(
-                  `${Array.length(note.links)->Int.toString} links`,
-                )}
-              </span>
+            let label = note.title != "" ? note.title : "Untitled"
+            <li key={id}>
+              <button
+                type_="button"
+                ariaPressed={(isSelected) ? #"true" : #"false"}
+                ariaLabel={label}
+                className={isSelected ? "note-item selected" : "note-item"}
+                onClick={_ => dispatch(SelectNote(id))}>
+                <span className="note-title"> {React.string(label)} </span>
+                <span className="note-meta">
+                  {React.string(
+                    `${Array.length(note.links)->Int.toString} links`,
+                  )}
+                </span>
+              </button>
             </li>
           | None => React.null
           }
@@ -168,22 +182,26 @@ module CanvasView = {
           | MultipleNotes(ids) => Array.includes(ids, note.id)
           | NoSelection => false
           }
+          let label = note.title != "" ? note.title : "Untitled"
           <div
             key={note.id}
+            role="button"
+            tabIndex={0}
+            ariaPressed={(isSelected) ? #"true" : #"false"}
+            ariaLabel={label}
             className={isSelected ? "canvas-note selected" : "canvas-note"}
             style={ReactDOM.Style.make(
               ~left=`${pos.x->Float.toString}px`,
               ~top=`${pos.y->Float.toString}px`,
               (),
             )}
             onClick={_ => dispatch(SelectNote(note.id))}
+            onKeyDown={e => onActivateKey(() => dispatch(StartEditingNote(note.id)), e)}
             onDoubleClick={e => {
               ReactEvent.Mouse.stopPropagation(e)
               dispatch(StartEditingNote(note.id))
             }}>
-            <div className="canvas-note-title">
-              {React.string(note.title != "" ? note.title : "Untitled")}
-            </div>
+            <div className="canvas-note-title"> {React.string(label)} </div>
             {note.content != ""
               ? <div className="canvas-note-preview">
                   {React.string(
@@ -197,9 +215,15 @@ module CanvasView = {
         ->React.array}
       </div>
       <div className="canvas-controls">
-        <button onClick={_ => dispatch(ZoomCanvas(1.2))}> {React.string("+")} </button>
-        <button onClick={_ => dispatch(ZoomCanvas(0.8))}> {React.string("-")} </button>
-        <button onClick={_ => dispatch(ResetViewport)}> {React.string("Reset")} </button>
+        <button ariaLabel="Zoom in" onClick={_ => dispatch(ZoomCanvas(1.2))}>
+          {React.string("+")}
+        </button>
+        <button ariaLabel="Zoom out" onClick={_ => dispatch(ZoomCanvas(0.8))}>
+          {React.string("-")}
+        </button>
+        <button ariaLabel="Reset view" onClick={_ => dispatch(ResetViewport)}>
+          {React.string("Reset")}
+        </button>
       </div>
     </div>
   }
@@ -208,22 +232,25 @@ module CanvasView = {
 module Toolbar = {
   @react.component
   let make = (~model: model, ~dispatch: msg => unit) => {
-    <div className="toolbar">
+    <div className="toolbar" role="toolbar" ariaLabel="Main toolbar">
       <div className="toolbar-left">
         <button
           onClick={_ => dispatch(ToggleSidebar)}
+          ariaPressed={(model.sidebarOpen) ? #"true" : #"false"}
           className={model.sidebarOpen ? "btn-active" : ""}>
           {React.string("Sidebar")}
         </button>
       </div>
       <div className="toolbar-center">
         <button
           onClick={_ => dispatch(SetViewMode(ListView))}
+          ariaPressed={(model.viewMode == ListView) ? #"true" : #"false"}
           className={model.viewMode == ListView ? "btn-active" : ""}>
           {React.string("List")}
         </button>
         <button
           onClick={_ => dispatch(SetViewMode(CanvasView))}
+          ariaPressed={(model.viewMode == CanvasView) ? #"true" : #"false"}
           className={model.viewMode == CanvasView ? "btn-active" : ""}>
           {React.string("Canvas")}
         </button>
@@ -254,9 +281,11 @@ module ErrorBanner = {
   let make = (~error: option<string>, ~dispatch: msg => unit) => {
     switch error {
     | Some(message) =>
-      <div className="error-banner">
+      <div className="error-banner" role="alert">
         <span> {React.string(message)} </span>
-        <button onClick={_ => dispatch(ClearError)}> {React.string("×")} </button>
+        <button ariaLabel="Dismiss error" onClick={_ => dispatch(ClearError)}>
+          {React.string("×")}
+        </button>
       </div>
     | None => React.null
     }