bearings 0.5.3 → 0.5.5

package/templates/agents/skills/checklist/previewer/viewer.js

@@ -2,22 +2,30 @@
   'use strict';
 
   var STATES = ['not-started', 'complete', 'failed', 'blocked', 'not-applicable'];
-  var STATE_LABELS = {
-    'not-started': 'Not started',
-    complete: 'Complete',
-    failed: 'Failed',
-    blocked: 'Blocked',
-    'not-applicable': 'Not applicable',
+  var STATE_META = {
+    'not-started': { label: 'Not started', symbol: '○' },
+    complete: { label: 'Complete', symbol: '✓' },
+    failed: { label: 'Failed', symbol: '×' },
+    blocked: { label: 'Blocked', symbol: 'Ⅱ' },
+    'not-applicable': { label: 'Not applicable', symbol: '—' },
   };
   var payload = window.BEARINGS_CHECKLISTS;
   var currentEntry = null;
-  var currentStates = {};
+  var currentStates = Object.create(null);
   var storageAvailable = true;
   var refreshPending = false;
+  var taskViews = Object.create(null);
+  var taskSequence = [];
+  var groupViews = [];
+  var sectionViews = [];
+  var keyboardCursor = null;
+  var nextDomId = 0;
 
   var picker = document.getElementById('checklist-picker');
   var content = document.getElementById('content');
   var status = document.getElementById('status');
+  var actionStatus = document.getElementById('action-status');
+  var actionMenu = document.getElementById('action-menu');
   var warning = document.getElementById('storage-warning');
 
   function element(tag, className, text) {
@@ -27,34 +35,67 @@
     return node;
   }
 
-  function setStatus(message) {
+  function html(tag, className, markup) {
+    var node = element(tag, className);
+    if (markup !== undefined) node.innerHTML = markup;
+    return node;
+  }
+
+  function setStatus(message, isError) {
     status.textContent = message;
+    status.dataset.tone = isError ? 'error' : 'info';
+    status.setAttribute('role', isError ? 'alert' : 'status');
+  }
+
+  function setActionStatus(message, isError) {
+    actionStatus.hidden = false;
+    actionStatus.textContent = message;
+    actionStatus.dataset.tone = isError ? 'error' : 'info';
+    actionStatus.setAttribute('role', isError ? 'alert' : 'status');
+    if (isError) actionMenu.open = true;
   }
 
   function reportStorageFailure() {
     storageAvailable = false;
     warning.hidden = false;
-    warning.textContent = 'Browser storage is unavailable. Progress works in this tab only; use Export to keep a copy.';
+    warning.textContent = 'Browser storage is unavailable. Progress works in this tab only; use Export progress to keep a copy.';
   }
 
   function storageKey(entry) {
     return 'bearings-checklists:' + payload.repositoryId + ':' + entry.identity;
   }
 
-  function executableIds(entry) {
-    var ids = [];
-    entry.checklist.sections.forEach(function (section) {
+  function hasOwnTaskContent(item) {
+    return Boolean(
+      item.instruction || item.warning || item.expectedResult || item.failureGuidance ||
+      (item.codeBlocks && item.codeBlocks.length) || (item.links && item.links.length)
+    );
+  }
+
+  function isGroupOnly(item) {
+    return Boolean(item.subItems && item.subItems.length && !hasOwnTaskContent(item));
+  }
+
+  function executableItems(entry) {
+    var items = [];
+    entry.checklist.sections.forEach(function (section, sectionIndex) {
       if (section.kind === 'info') return;
       section.items.forEach(function (item) {
-        ids.push(item.id);
-        (item.subItems || []).forEach(function (subItem) { ids.push(subItem.id); });
+        if (!isGroupOnly(item)) items.push({ id: item.id, title: item.title, sectionIndex: sectionIndex });
+        (item.subItems || []).forEach(function (subItem) {
+          items.push({ id: subItem.id, title: subItem.title, sectionIndex: sectionIndex });
+        });
       });
     });
-    return ids;
+    return items;
+  }
+
+  function executableIds(entry) {
+    return executableItems(entry).map(function (item) { return item.id; });
   }
 
   function normalizedStates(entry, candidate) {
-    var states = {};
+    var states = Object.create(null);
     executableIds(entry).forEach(function (id) {
       if (candidate && STATES.indexOf(candidate[id]) !== -1 && candidate[id] !== 'not-started') {
         states[id] = candidate[id];
@@ -64,14 +105,14 @@
   }
 
   function loadProgress(entry) {
-    if (!storageAvailable) return {};
+    if (!storageAvailable) return Object.create(null);
     try {
       var saved = JSON.parse(localStorage.getItem(storageKey(entry)) || 'null');
-      if (!saved || saved.contentHash !== entry.contentHash) return {};
+      if (!saved || saved.contentHash !== entry.contentHash) return Object.create(null);
       return normalizedStates(entry, saved.states);
     } catch (error) {
       reportStorageFailure();
-      return {};
+      return Object.create(null);
     }
   }
 
@@ -92,22 +133,211 @@
       setStatus('Progress saved in this browser.');
     } catch (error) {
       reportStorageFailure();
-      setStatus('Progress changed, but browser storage could not save it.');
+      setStatus('Progress changed, but browser storage could not save it.', true);
     }
   }
 
-  function updateProgress() {
-    var ids = currentEntry ? executableIds(currentEntry) : [];
-    var resolved = ids.filter(function (id) {
-      return currentStates[id] && currentStates[id] !== 'not-started';
-    }).length;
-    document.getElementById('progress-copy').textContent = resolved + ' / ' + ids.length + ' resolved';
-    document.getElementById('progress-fill').style.width = (ids.length ? resolved / ids.length * 100 : 0) + '%';
+  function itemState(id) {
+    return currentStates[id] || 'not-started';
+  }
+
+  function tally(ids) {
+    var counts = { complete: 0, failed: 0, blocked: 0, 'not-applicable': 0, 'not-started': 0 };
+    ids.forEach(function (id) { counts[itemState(id)] += 1; });
+    return counts;
+  }
+
+  function setBadge(badge, stateName, label) {
+    var meta = STATE_META[stateName] || STATE_META['not-started'];
+    badge.dataset.state = stateName;
+    badge.replaceChildren(
+      element('span', 'status-symbol', meta.symbol),
+      document.createTextNode(label || meta.label)
+    );
+    badge.firstChild.setAttribute('aria-hidden', 'true');
+  }
+
+  function setExpanded(view, expanded) {
+    view.body.hidden = !expanded;
+    view.toggle.setAttribute('aria-expanded', String(expanded));
+    view.toggle.textContent = expanded ? 'Hide details' : 'Show details';
+  }
+
+  function isUnresolved(id) {
+    var stateName = itemState(id);
+    return stateName !== 'complete' && stateName !== 'not-applicable';
+  }
+
+  function tasksInSection(sectionIndex) {
+    return taskSequence.filter(function (task) { return task.sectionIndex === sectionIndex; });
+  }
+
+  function preferredTaskInSection(sectionIndex) {
+    var tasks = tasksInSection(sectionIndex);
+    return tasks.find(function (task) { return isUnresolved(task.id); }) || tasks[0] || null;
+  }
+
+  function firstUnresolvedTask() {
+    return taskSequence.find(function (task) { return isUnresolved(task.id); }) || null;
+  }
+
+  function nextUnresolvedTaskAfter(id) {
+    var index = taskSequence.findIndex(function (task) { return task.id === id; });
+    return taskSequence.slice(index + 1).find(function (task) { return isUnresolved(task.id); }) || null;
+  }
+
+  function hasTextSelection() {
+    var selection = window.getSelection && window.getSelection();
+    return Boolean(selection && !selection.isCollapsed);
+  }
+
+  function isNativeShortcutTarget(target) {
+    if (!target || target.nodeType !== 1) return false;
+    return target.isContentEditable || Boolean(target.closest('input, select, textarea, button, a, summary, [contenteditable]:not([contenteditable="false"])'));
+  }
+
+  function setKeyboardCursor(sectionIndex, actionId, options) {
+    options = options || {};
+    if (!currentEntry || !sectionViews.length) {
+      keyboardCursor = null;
+      return;
+    }
+
+    var section = sectionViews.find(function (view) { return view.index === sectionIndex; }) || sectionViews[0];
+    var action = actionId && taskSequence.find(function (task) {
+      return task.id === actionId && task.sectionIndex === section.index;
+    });
+    var previous = keyboardCursor;
+    var changed = !previous || previous.sectionIndex !== section.index || previous.actionId !== (action ? action.id : null);
+    keyboardCursor = { sectionIndex: section.index, actionId: action ? action.id : null };
+    if (changed) {
+      var chooser = content.querySelector('.copy-chooser');
+      if (chooser) {
+        if (chooser.open) chooser.close();
+        chooser.remove();
+      }
+    }
+
+    sectionViews.forEach(function (view) {
+      var current = view.index === keyboardCursor.sectionIndex;
+      view.element.dataset.keyboardCurrent = String(current);
+      if (current) view.link.setAttribute('aria-current', 'location');
+      else view.link.removeAttribute('aria-current');
+    });
+
+    Object.keys(taskViews).forEach(function (id) {
+      var view = taskViews[id];
+      var current = id === keyboardCursor.actionId;
+      view.article.dataset.keyboardCurrent = String(current);
+      view.focusMarker.hidden = !current;
+      if (current) view.article.setAttribute('aria-current', 'step');
+      else view.article.removeAttribute('aria-current');
+      if (!changed) return;
+      if (current || view.childIds.indexOf(keyboardCursor.actionId) !== -1) setExpanded(view, true);
+      else setExpanded(view, view.manualExpanded === undefined ? false : view.manualExpanded);
+    });
+
+    var target = action ? taskViews[action.id].article : section.element;
+    if (options.focus) {
+      try { target.focus({ preventScroll: true }); } catch (error) { target.focus(); }
+    }
+    if (options.scroll) target.scrollIntoView({ block: action ? 'center' : 'start' });
+  }
+
+  function setTaskVisual(view, stateName) {
+    view.article.dataset.state = stateName;
+    setBadge(view.badge, stateName);
+    view.buttons.forEach(function (button) {
+      var selected = button.dataset.stateValue === stateName;
+      button.dataset.selected = String(selected);
+      button.setAttribute('aria-pressed', String(selected));
+    });
+    if (view.failure) view.failure.hidden = stateName !== 'failed' && stateName !== 'blocked';
+  }
+
+  function updateGroupViews(nextUnresolvedId) {
+    groupViews.forEach(function (view) {
+      var counts = tally(view.ids);
+      var stateName = 'not-started';
+      if (counts.failed) stateName = 'failed';
+      else if (counts.blocked) stateName = 'blocked';
+      else if (counts.complete + counts['not-applicable'] === view.ids.length) {
+        stateName = counts.complete ? 'complete' : 'not-applicable';
+      }
+      var label = counts.complete + ' / ' + view.ids.length + ' complete';
+      if (counts.failed) label += ' · ' + counts.failed + ' failed';
+      if (counts.blocked) label += ' · ' + counts.blocked + ' blocked';
+      setBadge(view.badge, stateName, label);
+      view.article.dataset.state = stateName;
+      view.article.dataset.containsNext = String(view.ids.indexOf(nextUnresolvedId) !== -1);
+      if (view.counter) view.counter.textContent = label;
+    });
+  }
+
+  function updateDashboard() {
+    var entries = currentEntry ? executableItems(currentEntry) : [];
+    var ids = entries.map(function (entry) { return entry.id; });
+    var counts = tally(ids);
+    var total = ids.length;
+    var nextUnresolved = entries.find(function (entry) { return isUnresolved(entry.id); });
+    var nextUnresolvedIndex = nextUnresolved ? entries.indexOf(nextUnresolved) : -1;
+    var followingUnresolved = nextUnresolvedIndex === -1 ? null : entries.slice(nextUnresolvedIndex + 1).find(function (entry) { return isUnresolved(entry.id); });
+
+    document.getElementById('progress-copy').textContent = counts.complete + ' / ' + total + ' complete';
+    document.getElementById('failed-count').textContent = counts.failed;
+    document.getElementById('blocked-count').textContent = counts.blocked;
+    document.getElementById('na-count').textContent = counts['not-applicable'];
+    var track = document.getElementById('progress-track');
+    track.max = total || 1;
+    track.value = counts.complete;
+    track.setAttribute('aria-valuetext', counts.complete + ' of ' + total + ' complete; ' + counts.failed + ' failed; ' + counts.blocked + ' blocked; ' + counts['not-applicable'] + ' not applicable');
+
+    var currentLink = document.getElementById('current-task-link');
+    var nextCopy = document.getElementById('next-task-copy');
+    if (nextUnresolved && taskViews[nextUnresolved.id]) {
+      currentLink.textContent = nextUnresolved.id + ' ' + nextUnresolved.title;
+      currentLink.title = currentLink.textContent;
+      currentLink.href = '#' + taskViews[nextUnresolved.id].domId;
+      nextCopy.textContent = followingUnresolved ? 'Next: ' + followingUnresolved.id + ' ' + followingUnresolved.title : 'Next: finish this task';
+    } else if (currentEntry && total) {
+      currentLink.textContent = 'Checklist complete';
+      currentLink.removeAttribute('title');
+      currentLink.removeAttribute('href');
+      nextCopy.textContent = 'No open tasks';
+    } else {
+      currentLink.textContent = 'Choose a checklist';
+      currentLink.removeAttribute('title');
+      currentLink.href = '#content';
+      nextCopy.textContent = 'Next: —';
+    }
+
+    Object.keys(taskViews).forEach(function (id) {
+      var view = taskViews[id];
+      var isNextUnresolved = Boolean(nextUnresolved && id === nextUnresolved.id);
+      var containsNext = Boolean(nextUnresolved && view.childIds.indexOf(nextUnresolved.id) !== -1);
+      view.article.dataset.nextUnresolved = String(isNextUnresolved);
+      view.article.dataset.containsNext = String(containsNext);
+      view.marker.hidden = !isNextUnresolved;
+    });
+
+    updateGroupViews(nextUnresolved && nextUnresolved.id);
+    updateSubstepCounters();
+    sectionViews.forEach(function (view) {
+      if (view.kind === 'info') {
+        view.count.textContent = 'Info';
+      } else {
+        var sectionCounts = tally(view.ids);
+        var sectionLabel = sectionCounts.complete + '/' + view.ids.length;
+        if (sectionCounts.failed) sectionLabel += ' · ' + sectionCounts.failed + ' failed';
+        else if (sectionCounts.blocked) sectionLabel += ' · ' + sectionCounts.blocked + ' blocked';
+        view.count.textContent = sectionLabel;
+      }
+    });
   }
 
   function textBlock(className, label, value) {
-    var block = element('div', className);
-    block.append(element('span', 'field-label', label), document.createTextNode(value));
+    var block = element('div', 'step-block ' + className);
+    block.append(element('span', 'field-label', label), html('div', '', value));
     return block;
   }
 
@@ -127,104 +357,574 @@
     return item;
   }
 
-  function stateControl(item, article) {
-    var label = element('label', 'state-label', 'State');
-    var select = element('select', 'state-select');
-    select.setAttribute('aria-label', 'State for ' + item.id + ': ' + item.title);
-    STATES.forEach(function (stateName) {
-      var option = element('option', '', STATE_LABELS[stateName]);
-      option.value = stateName;
-      select.append(option);
+  function fallbackCopy(value) {
+    var input = element('textarea');
+    input.value = value;
+    input.className = 'copy-source';
+    input.setAttribute('readonly', '');
+    document.body.append(input);
+    input.select();
+    var copied = false;
+    try { copied = document.execCommand('copy'); } catch (error) { copied = false; }
+    input.remove();
+    return copied;
+  }
+
+  function copyCode(value, button) {
+    function copied() {
+      button.textContent = 'Copied';
+      setStatus('Command copied.');
+    }
+    function fallback() {
+      if (fallbackCopy(value)) copied();
+      else setStatus('Copy failed. Select the command and copy it manually.', true);
+    }
+    button.textContent = 'Copying…';
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(value).then(copied, fallback);
+    } else fallback();
+  }
+
+  function codeBlock(block) {
+    var wrapper = element('div', 'code-block');
+    var heading = element('div', 'code-heading');
+    var copy = element('button', 'copy-button', 'Copy');
+    copy.type = 'button';
+    copy.setAttribute('aria-label', 'Copy ' + block.language + ' command');
+    copy.addEventListener('click', function () { copyCode(block.content, copy); });
+    heading.append(element('span', 'language', block.language), copy);
+    var pre = element('pre');
+    pre.append(element('code', '', block.content));
+    wrapper.append(heading, pre);
+    return wrapper;
+  }
+
+  function appendItemContent(item, body, kind) {
+    var failure = null;
+    if (item.warning) body.append(textBlock('warning', 'Warning', item.warning));
+    if (item.instruction) body.append(textBlock('instruction', kind === 'info' ? 'Information' : 'Do', item.instruction));
+    (item.codeBlocks || []).forEach(function (block) { body.append(codeBlock(block)); });
+    if (item.expectedResult) body.append(textBlock('expected', 'Verify', item.expectedResult));
+    if (item.failureGuidance) {
+      failure = textBlock('failure', 'Recovery', item.failureGuidance);
+      body.append(failure);
+    }
+    if (item.links && item.links.length) {
+      var resources = element('div', 'resources');
+      var links = element('ul', 'links');
+      item.links.forEach(function (link) { links.append(safeLink(link)); });
+      resources.append(element('span', 'field-label', 'Resources'), links);
+      body.append(resources);
+    }
+    return failure;
+  }
+
+  function stateButton(item, stateName, label, className, menu) {
+    var button = element('button', 'state-action' + (className ? ' ' + className : ''), label);
+    button.type = 'button';
+    button.dataset.stateValue = stateName;
+    button.setAttribute('aria-label', label + ' for ' + item.id + ': ' + item.title);
+    button.addEventListener('click', function () {
+      if (menu) menu.open = false;
+      changeItemState(item.id, stateName);
     });
-    select.value = currentStates[item.id] || 'not-started';
-    article.dataset.state = select.value;
-    select.addEventListener('change', function () {
-      if (select.value === 'not-started') delete currentStates[item.id];
-      else currentStates[item.id] = select.value;
-      article.dataset.state = select.value;
-      saveProgress();
-      updateProgress();
+    return button;
+  }
+
+  function stateActions(item) {
+    var actions = element('div', 'state-actions');
+    var buttons = [];
+    var complete = stateButton(item, 'complete', 'Mark complete', 'primary-action');
+    var blocked = stateButton(item, 'blocked', 'Blocked');
+    var failed = stateButton(item, 'failed', 'Failed');
+    var more = element('details', 'state-more');
+    var moreSummary = element('summary', '', 'More');
+    var menu = element('div', 'state-more-menu');
+    var notApplicable = stateButton(item, 'not-applicable', 'Not applicable', '', more);
+    var notStarted = stateButton(item, 'not-started', 'Mark not started', '', more);
+    buttons.push(complete, blocked, failed, notApplicable, notStarted);
+    menu.append(notApplicable, notStarted);
+    more.append(moreSummary, menu);
+    actions.append(complete, blocked, failed, more);
+    return { element: actions, buttons: buttons };
+  }
+
+  function scrollToNextTask(id) {
+    var index = taskSequence.findIndex(function (task) { return task.id === id; });
+    var next = taskSequence.slice(index + 1).find(function (task) {
+      var stateName = itemState(task.id);
+      return stateName !== 'complete' && stateName !== 'not-applicable';
     });
-    label.append(select);
-    return label;
+    if (next && taskViews[next.id]) taskViews[next.id].article.scrollIntoView({ block: 'center' });
   }
 
-  function renderItem(item, kind, isSubItem) {
-    var article = element('article', 'item' + (kind === 'info' ? ' info' : ''));
-    var head = element('div', 'item-head');
-    var headingWrap = element('div', 'item-heading');
+  function changeItemState(id, stateName) {
+    var wasComplete = itemState(id) === 'complete';
+    if (stateName === 'not-started') delete currentStates[id];
+    else currentStates[id] = stateName;
+    var view = taskViews[id];
+    view.manualExpanded = stateName === 'complete' || stateName === 'not-applicable' ? false : true;
+    var focusWasInBody = view.body.contains(document.activeElement);
+    setExpanded(view, view.manualExpanded);
+    setTaskVisual(view, stateName);
+    saveProgress();
+    updateDashboard();
+    if (stateName === 'complete' && !wasComplete) scrollToNextTask(id);
+    if (focusWasInBody && view.body.hidden) {
+      try { view.article.focus({ preventScroll: true }); } catch (error) { view.article.focus(); }
+    }
+    setStatus(id + ': ' + STATE_META[stateName].label + (storageAvailable ? '.' : '. Progress is only in this tab.'), !storageAvailable);
+  }
+
+  function itemHeading(item, isSubItem, label) {
+    var wrap = element('div', 'item-heading');
+    wrap.append(element('span', 'hierarchy-label', label));
     var heading = element(isSubItem ? 'h4' : 'h3');
     heading.append(element('span', 'item-id', item.id), document.createTextNode(item.title));
     if (item.optional) heading.append(element('span', 'optional', 'Optional'));
-    headingWrap.append(heading);
-    head.append(headingWrap);
-    if (kind === 'checklist') head.append(stateControl(item, article));
-    article.append(head);
-
-    if (item.warning) article.append(textBlock('warning', 'Warning', item.warning));
-    if (item.instruction) article.append(element('p', 'instruction', item.instruction));
-    (item.codeBlocks || []).forEach(function (block) {
-      var pre = element('pre');
-      pre.append(element('span', 'language', block.language), element('code', '', block.content));
-      article.append(pre);
-    });
-    if (item.expectedResult) article.append(textBlock('expected', 'Expected result', item.expectedResult));
-    if (item.failureGuidance) article.append(textBlock('failure', 'If this fails', item.failureGuidance));
-    if (item.links && item.links.length) {
-      var links = element('ul', 'links');
-      item.links.forEach(function (link) { links.append(safeLink(link)); });
-      article.append(links);
+    wrap.append(heading);
+    return wrap;
+  }
+
+  function renderSubItems(item, target, kind, sectionIndex) {
+    if (!item.subItems || !item.subItems.length) return { ids: [], counter: null };
+    var wrapper = element('div', 'substeps');
+    var heading = element('div', 'substeps-heading');
+    var counter = element('span', '', '0 / ' + item.subItems.length + ' complete');
+    heading.append(element('span', '', 'Substeps'), counter);
+    var items = element('div', 'sub-items');
+    item.subItems.forEach(function (subItem) { items.append(renderItem(subItem, kind, true, sectionIndex)); });
+    wrapper.append(heading, items);
+    target.append(wrapper);
+    return { ids: item.subItems.map(function (subItem) { return subItem.id; }), counter: counter };
+  }
+
+  function renderItem(item, kind, isSubItem, sectionIndex) {
+    var groupOnly = kind === 'checklist' && isGroupOnly(item);
+    var article = element('article', 'item' + (kind === 'info' ? ' info' : '') + (groupOnly ? ' task-group' : ''));
+    article.id = 'task-' + (++nextDomId);
+    var head = element('div', 'item-head');
+
+    if (kind === 'info') {
+      head.append(itemHeading(item, isSubItem, 'Reference'));
+      var infoBadge = element('span', 'status-badge');
+      setBadge(infoBadge, 'not-applicable', 'Reference');
+      head.append(infoBadge);
+      var infoBody = element('div', 'item-body');
+      appendItemContent(item, infoBody, kind);
+      article.append(head, infoBody);
+      renderSubItems(item, infoBody, kind, sectionIndex);
+      article.addEventListener('click', function (event) {
+        setKeyboardCursor(sectionIndex, null, { focus: !isNativeShortcutTarget(event.target) && !hasTextSelection() });
+      });
+      article.addEventListener('focusin', function () { setKeyboardCursor(sectionIndex, null); });
+      return article;
     }
-    if (item.subItems && item.subItems.length) {
-      var subItems = element('div', 'sub-items');
-      item.subItems.forEach(function (subItem) { subItems.append(renderItem(subItem, kind, true)); });
-      article.append(subItems);
+
+    if (groupOnly) {
+      head.append(itemHeading(item, false, 'Task group'));
+      var groupBadge = element('span', 'status-badge');
+      head.append(groupBadge);
+      article.append(head);
+      var groupChildren = renderSubItems(item, article, kind, sectionIndex);
+      groupViews.push({ article: article, badge: groupBadge, ids: groupChildren.ids, counter: groupChildren.counter });
+      article.addEventListener('click', function (event) {
+        if (!event.target.closest('[data-keyboard-task]')) {
+          setKeyboardCursor(sectionIndex, null, { focus: !isNativeShortcutTarget(event.target) && !hasTextSelection() });
+        }
+      });
+      article.addEventListener('focusin', function (event) {
+        if (!event.target.closest('[data-keyboard-task]')) setKeyboardCursor(sectionIndex, null);
+      });
+      return article;
     }
+
+    var hierarchy = isSubItem ? 'Substep' : (item.subItems && item.subItems.length ? 'Parent task' : 'Task');
+    var headingWrap = itemHeading(item, isSubItem, hierarchy);
+    var marker = element('span', 'next-unresolved-marker', 'Next unresolved');
+    marker.hidden = true;
+    var focusMarker = element('span', 'focused-task-marker', 'Focused action');
+    focusMarker.hidden = true;
+    headingWrap.append(marker, focusMarker);
+    var badge = element('span', 'status-badge');
+    var toggle = element('button', 'item-toggle', 'Show details');
+    toggle.type = 'button';
+    var body = element('div', 'item-body');
+    var view = {
+      article: article,
+      badge: badge,
+      body: body,
+      toggle: toggle,
+      marker: marker,
+      focusMarker: focusMarker,
+      buttons: [],
+      copyButtons: [],
+      failure: null,
+      childIds: [],
+      substepCounter: null,
+      manualExpanded: undefined,
+      domId: article.id,
+    };
+    taskViews[item.id] = view;
+    taskSequence.push({ id: item.id, title: item.title, sectionIndex: sectionIndex });
+    article.dataset.keyboardTask = item.id;
+    article.tabIndex = -1;
+    toggle.setAttribute('aria-controls', article.id + '-body');
+    body.id = article.id + '-body';
+    toggle.addEventListener('click', function () {
+      view.manualExpanded = body.hidden;
+      setExpanded(view, view.manualExpanded);
+    });
+    article.addEventListener('focusin', function (event) {
+      if (event.target.closest('[data-keyboard-task]') !== article) return;
+      setKeyboardCursor(sectionIndex, item.id);
+    });
+    article.addEventListener('click', function (event) {
+      if (!event.isTrusted || event.target.closest('[data-keyboard-task]') !== article) return;
+      var focusTask = !isNativeShortcutTarget(event.target) && !hasTextSelection();
+      setKeyboardCursor(sectionIndex, item.id, { focus: focusTask });
+    });
+    head.append(headingWrap, badge, toggle);
+    article.append(head, body);
+    view.failure = appendItemContent(item, body, kind);
+    view.copyButtons = Array.prototype.slice.call(body.querySelectorAll('.copy-button'));
+    var children = renderSubItems(item, body, kind, sectionIndex);
+    view.childIds = children.ids;
+    view.substepCounter = children.counter;
+    var actions = stateActions(item);
+    view.buttons = actions.buttons;
+    body.append(actions.element);
+    setTaskVisual(view, itemState(item.id));
     return article;
   }
 
+  function updateSubstepCounters() {
+    Object.keys(taskViews).forEach(function (id) {
+      var view = taskViews[id];
+      if (!view.substepCounter) return;
+      var counts = tally(view.childIds);
+      var label = counts.complete + ' / ' + view.childIds.length + ' complete';
+      if (counts.failed) label += ' · ' + counts.failed + ' failed';
+      else if (counts.blocked) label += ' · ' + counts.blocked + ' blocked';
+      view.substepCounter.textContent = label;
+    });
+  }
+
+  function moveActionCursor(delta) {
+    if (!keyboardCursor) return false;
+    var tasks = tasksInSection(keyboardCursor.sectionIndex);
+    if (!tasks.length) return false;
+    var index = tasks.findIndex(function (task) { return task.id === keyboardCursor.actionId; });
+    var target = index === -1 ? tasks[delta > 0 ? 0 : tasks.length - 1] : tasks[index + delta];
+    if (!target) return false;
+    setKeyboardCursor(target.sectionIndex, target.id, { focus: true, scroll: true });
+    return true;
+  }
+
+  function moveSectionCursor(delta) {
+    if (!keyboardCursor) return false;
+    var position = sectionViews.findIndex(function (view) { return view.index === keyboardCursor.sectionIndex; });
+    var section = sectionViews[position + delta];
+    if (!section) return false;
+    var target = section.kind === 'checklist' ? preferredTaskInSection(section.index) : null;
+    setKeyboardCursor(section.index, target && target.id, { focus: true, scroll: true });
+    return true;
+  }
+
+  function changeCursorState(stateName, advance) {
+    if (!keyboardCursor || !keyboardCursor.actionId) return false;
+    var changedTask = taskSequence.find(function (task) { return task.id === keyboardCursor.actionId; });
+    if (!changedTask) return false;
+    changeItemState(changedTask.id, stateName);
+    var target = advance && nextUnresolvedTaskAfter(changedTask.id);
+    target = target || changedTask;
+    setKeyboardCursor(target.sectionIndex, target.id, { focus: true, scroll: Boolean(advance && target !== changedTask) });
+    return true;
+  }
+
+  function toggleCursorDetails() {
+    if (!keyboardCursor || !keyboardCursor.actionId) return false;
+    var view = taskViews[keyboardCursor.actionId];
+    if (!view) return false;
+    view.manualExpanded = view.body.hidden;
+    setExpanded(view, view.manualExpanded);
+    return true;
+  }
+
+  function dismissCopyChooser(message, restoreFocus) {
+    var chooser = content.querySelector('.copy-chooser');
+    if (!chooser) return false;
+    if (chooser.open) chooser.close();
+    chooser.remove();
+    if (restoreFocus && keyboardCursor) {
+      setKeyboardCursor(keyboardCursor.sectionIndex, keyboardCursor.actionId, { focus: true });
+    }
+    if (message) setStatus(message);
+    return true;
+  }
+
+  function showCopyChooser(buttons, action, section) {
+    dismissCopyChooser();
+    var chooser = element('dialog', 'copy-chooser');
+    var title = element('h2', 'copy-chooser-title', 'Copy which command?');
+    var hintText = element('p', 'copy-chooser-hint');
+    var choices = element('div', 'copy-choices');
+    var actions = element('div', 'copy-chooser-actions');
+    var cancel = element('button', '', 'Cancel');
+    var titleId = (action ? action.article.id : section.element.id) + '-copy-chooser-title';
+    var hintId = titleId + '-hint';
+    title.id = titleId;
+    hintText.id = hintId;
+    chooser.setAttribute('aria-labelledby', titleId);
+    chooser.setAttribute('aria-describedby', hintId);
+    cancel.type = 'button';
+    cancel.addEventListener('click', function () { dismissCopyChooser('Copy choice canceled.', true); });
+    actions.append(cancel);
+
+    buttons.forEach(function (button, index) {
+      var code = button.closest('.code-block').querySelector('code');
+      var command = code ? code.textContent.trim() : 'Command ' + (index + 1);
+      var preview = command.split('\n')[0];
+      var choice = element('button', 'copy-choice');
+      choice.type = 'button';
+      choice.dataset.copyChoice = String(index);
+      choice.setAttribute('aria-label', 'Copy command ' + (index + 1) + ': ' + command);
+      if (index < 9) choice.setAttribute('aria-keyshortcuts', String(index + 1));
+      choice.append(
+        element('span', 'copy-choice-key', String(index + 1)),
+        element('code', 'copy-choice-command', preview),
+      );
+      choice.addEventListener('click', function () {
+        dismissCopyChooser('', true);
+        button.click();
+      });
+      choices.append(choice);
+    });
+
+    var directCount = Math.min(buttons.length, 9);
+    var directKeys = directCount === 2 ? '1 or 2' : '1 through ' + directCount;
+    var hint = 'Press ' + directKeys + ' to copy; use j/k or Up/Down and Enter, or Escape to cancel.';
+    hintText.textContent = hint;
+    chooser.append(title, hintText, choices, actions);
+    chooser.addEventListener('cancel', function (event) {
+      event.preventDefault();
+      dismissCopyChooser('Copy choice canceled.', true);
+    });
+    content.append(chooser);
+    chooser.showModal();
+    setStatus(buttons.length + ' commands available. ' + hint);
+    try { choices.firstChild.focus({ preventScroll: true }); } catch (error) { choices.firstChild.focus(); }
+  }
+
+  function copyKeyboardTarget() {
+    if (!keyboardCursor) return false;
+    var section = sectionViews.find(function (view) { return view.index === keyboardCursor.sectionIndex; });
+    var action = keyboardCursor.actionId && taskViews[keyboardCursor.actionId];
+    var buttons = action
+      ? action.copyButtons
+      : (section ? Array.prototype.slice.call(section.element.querySelectorAll('.copy-button')) : []);
+    if (buttons.length === 1) {
+      buttons[0].click();
+      return true;
+    }
+    if (buttons.length > 1) showCopyChooser(buttons, action, section);
+    else setStatus('No copyable item in the focused ' + (action ? 'action.' : 'section.'));
+    return true;
+  }
+
+  function handleCopyChooserShortcut(event, target) {
+    var chooser = content.querySelector('.copy-chooser');
+    if (!chooser) return false;
+    var choices = Array.prototype.slice.call(chooser.querySelectorAll('.copy-choice'));
+    if (event.key === 'Escape') return dismissCopyChooser('Copy choice canceled.', true);
+    if (event.key >= '1' && event.key <= '9') {
+      if (!event.repeat && choices[Number(event.key) - 1]) choices[Number(event.key) - 1].click();
+      return true;
+    }
+    if (event.key === 'j' || event.key === 'k' || event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+      var current = choices.indexOf(target.closest('.copy-choice'));
+      var delta = event.key === 'j' || event.key === 'ArrowDown' ? 1 : -1;
+      var next = current === -1
+        ? (delta > 0 ? 0 : choices.length - 1)
+        : (current + delta + choices.length) % choices.length;
+      choices[next].focus();
+      setStatus('Command ' + (next + 1) + ' of ' + choices.length + ' selected. Press Enter to copy or Escape to cancel.');
+      return true;
+    }
+    if (event.key === 'Enter' && target.closest('.copy-choice')) {
+      if (!event.repeat) target.closest('.copy-choice').click();
+      return true;
+    }
+    return false;
+  }
+
+  function resetProgress() {
+    if (!currentEntry || !window.confirm('Clear progress for this checklist?')) return false;
+    currentStates = Object.create(null);
+    saveProgress();
+    renderChecklist(currentEntry, currentStates);
+    setActionStatus('Progress reset.');
+    actionMenu.open = false;
+    return true;
+  }
+
+  function handleEscape(target) {
+    var taskArticle = target && target.closest && target.closest('[data-keyboard-task]');
+    var details = target && target.closest && target.closest('details[open]');
+    if (!details && taskArticle) details = taskArticle.querySelector('details[open]');
+    if (!details && actionMenu.open) details = actionMenu;
+    if (details) details.open = false;
+
+    if (keyboardCursor && (details || (content.contains(target) && isNativeShortcutTarget(target)))) {
+      setKeyboardCursor(keyboardCursor.sectionIndex, keyboardCursor.actionId, { focus: true });
+      return true;
+    }
+    if (details) {
+      var summary = details.querySelector('summary');
+      if (summary) summary.focus();
+      return true;
+    }
+    var nextUnresolved = keyboardCursor && content.contains(target) && firstUnresolvedTask();
+    if (nextUnresolved) {
+      setKeyboardCursor(nextUnresolved.sectionIndex, nextUnresolved.id, { focus: true, scroll: true });
+      return true;
+    }
+    return false;
+  }
+
+  function handleKeyboardShortcut(event) {
+    if (event.defaultPrevented || event.isComposing || event.keyCode === 229) return;
+    if (event.ctrlKey || event.metaKey || event.altKey || hasTextSelection()) return;
+    var target = event.target && event.target.nodeType === 1 ? event.target : document.activeElement;
+    if (content.querySelector('.copy-chooser')) {
+      if (handleCopyChooserShortcut(event, target)) event.preventDefault();
+      return;
+    }
+    if (event.key === 'Escape') {
+      if (handleEscape(target)) event.preventDefault();
+      return;
+    }
+    if (!currentEntry || !keyboardCursor || !content.contains(document.activeElement) || isNativeShortcutTarget(target)) return;
+
+    var stateByKey = {
+      'x': 'complete',
+      'f': 'failed',
+      'b': 'blocked',
+      '-': 'not-applicable',
+      'u': 'not-started',
+    };
+    if ((stateByKey[event.key] || event.key === 'R' || event.key === 'y') && event.repeat) return;
+
+    var handled = false;
+    if (event.key === 'j') handled = moveActionCursor(1);
+    else if (event.key === 'k') handled = moveActionCursor(-1);
+    else if (event.key === ']') handled = moveSectionCursor(1);
+    else if (event.key === '[') handled = moveSectionCursor(-1);
+    else if (event.key === 'y') handled = copyKeyboardTarget();
+    else if (event.key === 'Enter') handled = toggleCursorDetails();
+    else if (event.key === 'R') handled = resetProgress();
+    else if (stateByKey[event.key]) handled = changeCursorState(stateByKey[event.key], event.key === 'x' || event.key === '-');
+    if (handled) event.preventDefault();
+  }
+
   function renderChecklist(entry, inMemoryStates) {
     currentEntry = entry;
     currentStates = inMemoryStates === undefined ? loadProgress(entry) : normalizedStates(entry, inMemoryStates);
+    taskViews = Object.create(null);
+    taskSequence = [];
+    groupViews = [];
+    sectionViews = [];
+    keyboardCursor = null;
+    nextDomId = 0;
     var checklist = entry.checklist;
     document.title = checklist.title + ' - Checklist';
     document.getElementById('title').textContent = checklist.title;
     document.getElementById('summary').textContent = checklist.summary;
     content.className = '';
     content.replaceChildren();
-    if (checklist.intro) content.append(element('p', 'intro', checklist.intro));
-    if (checklist.callout) content.append(element('div', 'callout', checklist.callout));
-    if (checklist.conventions) content.append(element('div', 'conventions', checklist.conventions));
 
-    checklist.sections.forEach(function (section) {
-      var sectionElement = element('section');
+    var shell = element('div', 'checklist-shell');
+    var navigation = element('nav', 'section-nav');
+    navigation.setAttribute('aria-label', 'Checklist sections');
+    navigation.append(element('p', 'section-nav-title field-label', 'Sections'));
+    var navigationList = element('ol', 'section-nav-list');
+    navigation.append(navigationList);
+    var checklistBody = element('div', 'checklist-body');
+    if (checklist.intro) checklistBody.append(html('div', 'intro', checklist.intro));
+    if (checklist.callout) checklistBody.append(textBlock('callout', 'Important', checklist.callout));
+    if (checklist.conventions) checklistBody.append(textBlock('conventions', 'Conventions', checklist.conventions));
+
+    checklist.sections.forEach(function (section, sectionIndex) {
+      var sequenceStart = taskSequence.length;
+      var sectionElement = element('section', 'checklist-section');
+      sectionElement.id = 'section-' + (sectionIndex + 1);
+      sectionElement.tabIndex = -1;
       var heading = element('div', 'section-heading');
       heading.append(element('span', 'section-number', section.number), element('h2', '', section.title));
       sectionElement.append(heading);
-      if (section.intro) sectionElement.append(element('p', 'section-intro', section.intro));
+      if (section.intro) sectionElement.append(html('div', 'section-intro', section.intro));
       var items = element('div', 'items');
-      section.items.forEach(function (item) { items.append(renderItem(item, section.kind, false)); });
+      section.items.forEach(function (item) { items.append(renderItem(item, section.kind, false, sectionIndex)); });
       sectionElement.append(items);
-      content.append(sectionElement);
+      checklistBody.append(sectionElement);
+
+      var navItem = element('li');
+      var navLink = element('a', 'section-nav-link');
+      navLink.href = '#' + sectionElement.id;
+      var navCount = element('span', 'nav-count');
+      navLink.append(
+        element('span', 'nav-number', section.number),
+        element('span', 'nav-title', section.title),
+        navCount
+      );
+      navItem.append(navLink);
+      navigationList.append(navItem);
+      var sectionView = {
+        index: sectionIndex,
+        kind: section.kind,
+        ids: taskSequence.slice(sequenceStart).map(function (task) { return task.id; }),
+        element: sectionElement,
+        link: navLink,
+        count: navCount,
+      };
+      sectionViews.push(sectionView);
+      navLink.addEventListener('focus', function () {
+        var task = section.kind === 'checklist' ? preferredTaskInSection(sectionIndex) : null;
+        setKeyboardCursor(sectionIndex, task && task.id);
+      });
+      navLink.addEventListener('click', function () {
+        var task = section.kind === 'checklist' ? preferredTaskInSection(sectionIndex) : null;
+        setKeyboardCursor(sectionIndex, task && task.id);
+      });
     });
-    updateProgress();
+    shell.append(navigation, checklistBody);
+    content.append(shell);
+    updateDashboard();
+    var initialTask = firstUnresolvedTask();
+    setKeyboardCursor(initialTask ? initialTask.sectionIndex : 0, initialTask && initialTask.id, { focus: true, scroll: true });
     setStatus('Opened ' + entry.identity + '.');
   }
 
   function showMessage(message, isError) {
     currentEntry = null;
-    currentStates = {};
+    currentStates = Object.create(null);
+    taskViews = Object.create(null);
+    taskSequence = [];
+    groupViews = [];
+    sectionViews = [];
+    keyboardCursor = null;
     document.title = 'Checklist library';
     document.getElementById('title').textContent = 'Choose a checklist';
     document.getElementById('summary').textContent = 'Browse the checklists generated from this repository.';
     content.className = isError ? 'error' : 'empty';
     content.textContent = message;
-    updateProgress();
+    updateDashboard();
   }
 
   function renderLibrary(selectedIdentity) {
     document.documentElement.dataset.viewerReady = 'false';
-    picker.replaceChildren(element('option', '', payload && payload.checklists.length ? 'Choose a checklist...' : 'No checklists found'));
+    var hasChecklists = payload && Array.isArray(payload.checklists) && payload.checklists.length;
+    picker.replaceChildren(element('option', '', hasChecklists ? 'Choose a checklist...' : 'No checklists found'));
     picker.firstChild.value = '';
     if (!payload || !Array.isArray(payload.checklists)) {
       showMessage('No generated payload was loaded. Run the checklist build script, then reload this page.', true);
@@ -232,7 +932,7 @@
       return;
     }
 
-    payload.categories.forEach(function (category) {
+    (payload.categories || []).forEach(function (category) {
       var group = element('optgroup');
       group.label = category;
       payload.checklists.filter(function (entry) { return entry.category === category; }).forEach(function (entry) {
@@ -256,14 +956,15 @@
   }
 
   function exportProgress() {
-    if (!currentEntry) return setStatus('Choose a checklist before exporting progress.');
+    if (!currentEntry) return setActionStatus('Choose a checklist before exporting progress.', true);
     var blob = new Blob([JSON.stringify(progressRecord(), null, 2) + '\n'], { type: 'application/json' });
     var anchor = document.createElement('a');
     anchor.href = URL.createObjectURL(blob);
     anchor.download = currentEntry.identity.replaceAll('/', '-') + '.progress.json';
     anchor.click();
     URL.revokeObjectURL(anchor.href);
-    setStatus('Progress export created.');
+    setActionStatus('Progress export created.');
+    actionMenu.open = false;
   }
 
   function importProgress(file) {
@@ -279,12 +980,13 @@
         currentStates = normalizedStates(currentEntry, imported.states);
         saveProgress();
         renderChecklist(currentEntry, currentStates);
-        setStatus('Progress imported.');
+        setActionStatus('Progress imported.');
+        actionMenu.open = false;
       } catch (error) {
-        setStatus('Progress import failed: ' + error.message);
+        setActionStatus('Progress import failed: ' + error.message, true);
       }
     });
-    reader.addEventListener('error', function () { setStatus('Progress import failed: the file could not be read.'); });
+    reader.addEventListener('error', function () { setActionStatus('Progress import failed: the file could not be read.', true); });
     reader.readAsText(file);
   }
 
@@ -308,7 +1010,7 @@
     script.addEventListener('error', function () {
       refreshPending = false;
       script.remove();
-      setStatus('Could not refresh the generated checklist payload.');
+      setStatus('Could not refresh the generated checklist payload.', true);
     });
     document.head.append(script);
   }
@@ -320,19 +1022,23 @@
   });
   document.getElementById('export-progress').addEventListener('click', exportProgress);
   document.getElementById('import-progress').addEventListener('click', function () {
-    if (!currentEntry) return setStatus('Choose a checklist before importing progress.');
+    if (!currentEntry) return setActionStatus('Choose a checklist before importing progress.', true);
     document.getElementById('import-file').click();
   });
   document.getElementById('import-file').addEventListener('change', function (event) {
     importProgress(event.target.files[0]);
     event.target.value = '';
   });
-  document.getElementById('reset-progress').addEventListener('click', function () {
-    if (!currentEntry || !window.confirm('Clear progress for this checklist?')) return;
-    currentStates = {};
-    saveProgress();
-    renderChecklist(currentEntry);
-    setStatus('Progress reset.');
+  document.getElementById('reset-progress').addEventListener('click', resetProgress);
+  document.getElementById('current-task-link').addEventListener('click', function (event) {
+    var task = currentEntry && firstUnresolvedTask();
+    if (!task) return;
+    event.preventDefault();
+    setKeyboardCursor(task.sectionIndex, task.id, { focus: true, scroll: true });
+  });
+  document.addEventListener('keydown', handleKeyboardShortcut);
+  document.addEventListener('click', function (event) {
+    if (actionMenu.open && !actionMenu.contains(event.target)) actionMenu.open = false;
   });
   window.addEventListener('focus', refreshPayload);