projectkeeper 0.0.0-stage → 1.0.0

package/ui/popover.js

@@ -0,0 +1,198 @@
+// The details popover (Spec §6.4; CKC-09 AC-34, AC-36): one floating window beside the object that was picked. It takes
+// no column and moves nothing else. This module is only its mechanics — where it stands (popover-place.js), following
+// its object while the graph pans, a list scrolls or the main view changes width, keyboard and focus, closing, and
+// updating in place without a redraw when nothing changed. What is shown inside it comes from the caller.
+import { placePopover } from './popover-place.js';
+
+const FOCUSABLE = 'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), summary, [tabindex]:not([tabindex="-1"])';
+
+/**
+ * @param {{ bounds: () => {left:number,top:number,right:number,bottom:number}, sheet: () => boolean,
+ *   normalize?: (html: string) => string, keepsOpen?: (target: Element) => boolean, onClose?: (why: string) => void,
+ *   avoid?: () => Array<{left:number,top:number,right:number,bottom:number}> }} o
+ *   `bounds` is the main view's visible area; `sheet` says the window is narrow, where the popover is an overlay along
+ *   the bottom instead; `normalize` strips what changes without meaning (relative clocks) before two renderings are
+ *   compared; `keepsOpen` names the places where a press does not count as "elsewhere" (the Keeper, used beside it);
+ *   `avoid` names rectangles it keeps off when it can (the pill at the bottom right).
+ */
+export function createPopover({ bounds, sheet, normalize = (s) => s, keepsOpen = () => false, onClose = () => {}, avoid = () => [] }) {
+  const content = document.createElement('div');
+  content.className = 'popover-content';
+  const el = document.createElement('section');
+  el.className = 'popover';
+  el.id = 'popover';
+  el.hidden = true;
+  el.tabIndex = -1;
+  el.setAttribute('role', 'dialog');
+  el.setAttribute('aria-label', 'Details');
+  el.append(content);
+  const scrim = document.createElement('div');
+  scrim.className = 'popover-scrim';
+  scrim.hidden = true;
+  document.body.append(scrim, el);
+
+  /** @type {null | { key: string, anchor: () => (object|null), opener: () => (Element|null), render: Function, sig: string|null, side: string|null, lastAnchor: object|null }} */
+  let current = null;
+  let pending = 0;
+  let frame = 0;
+  let natural = null;                       // its size with no limit applied, measured when the content changes
+  let dismissed = { key: '', at: 0 };
+
+  const focusables = () => [...el.querySelectorAll(FOCUSABLE)].filter((n) => n.getClientRects().length > 0);
+  const scroller = () => content.querySelector('.popover-body');
+
+  function place({ measure = false } = {}) {
+    if (!current || el.hidden) return;
+    if (sheet()) {
+      // Narrow window: an overlay along the bottom (Spec §6.15); the stylesheet places it.
+      el.classList.add('sheet');
+      scrim.hidden = false;
+      for (const p of ['left', 'top', 'width', 'maxHeight']) el.style[p] = '';
+      el.dataset.side = 'sheet';
+      natural = null;
+      return;
+    }
+    el.classList.remove('sheet');
+    scrim.hidden = true;
+    const area = bounds();
+    const found = current.anchor();
+    if (found) current.lastAnchor = found;
+    // No object to stand beside (it is not on screen in any form): the top left of the main view.
+    const anchor = current.lastAnchor ?? { left: area.left + 16, top: area.top + 16, right: area.left + 16, bottom: area.top + 16 };
+    let scrollTop = null;
+    if (measure || !natural) {
+      // Lifting the height limit to measure would throw away how far its body is scrolled, so that is put back.
+      scrollTop = scroller()?.scrollTop ?? 0;
+      el.style.maxHeight = '';
+      el.style.width = '';
+      natural = { width: el.offsetWidth, height: el.offsetHeight };
+    }
+    const p = placePopover({ anchor, size: natural, bounds: area, keepSide: current.side, avoid: avoid() });
+    current.side = p.side;
+    el.style.left = `${p.left}px`;
+    el.style.top = `${p.top}px`;
+    el.style.width = p.width < natural.width ? `${p.width}px` : '';
+    el.style.maxHeight = p.height < natural.height ? `${p.height}px` : '';
+    el.dataset.side = p.side;
+    if (scrollTop !== null && scroller()) scroller().scrollTop = scrollTop;
+  }
+  /** Follow the object: at most once a frame, however many pan, scroll and resize events arrive. */
+  function reposition(opts) {
+    if (!current) return;
+    if (opts?.measure) natural = null;
+    if (frame) return;
+    frame = requestAnimationFrame(() => { frame = 0; place(); });
+  }
+
+  async function draw({ force = false, focus = false } = {}) {
+    const mine = current;
+    if (!mine) return;
+    const token = ++pending;
+    const mount = document.createElement('div');
+    try { await mine.render(mount, api); }
+    catch (e) { const box = document.createElement('div'); box.className = 'popover-body faint'; box.textContent = e.message; mount.replaceChildren(box); }
+    if (token !== pending || current !== mine) return;
+    const sig = normalize(mount.innerHTML);
+    if (!force && sig === mine.sig) { reposition(); return; }   // nothing changed: nothing is redrawn
+    mine.sig = sig;
+    const hadFocus = el.contains(document.activeElement);
+    const index = hadFocus ? focusables().indexOf(document.activeElement) : -1;
+    const scrollTop = scroller()?.scrollTop ?? 0;
+    content.replaceChildren(...mount.childNodes);
+    el.hidden = false;
+    place({ measure: true });
+    if (scroller()) scroller().scrollTop = scrollTop;
+    if (focus) el.focus({ preventScroll: true });
+    else if (hadFocus) (focusables()[index] ?? el).focus({ preventScroll: true });
+  }
+
+  function close(why = 'close') {
+    if (!current) return;
+    const was = current;
+    current = null;
+    pending++;
+    const hadFocus = el.contains(document.activeElement);
+    el.hidden = true;
+    scrim.hidden = true;
+    content.replaceChildren();
+    natural = null;
+    // Focus goes back to where it was before the popover opened — unless the owner has already put it somewhere else
+    // (a press on another control). A press on something that takes no focus leaves it on the page body; that is
+    // settled a moment later, once the browser has finished with the press.
+    const opener = () => { const to = was.opener(); return to?.isConnected ? to : null; };
+    if (why === 'escape' || why === 'button') opener()?.focus({ preventScroll: true });
+    else if (hadFocus) setTimeout(() => { if (!current && (document.activeElement === document.body || !document.activeElement)) opener()?.focus({ preventScroll: true }); }, 0);
+    onClose(why);
+  }
+
+  const api = {
+    el,
+    isOpen: () => Boolean(current),
+    key: () => current?.key ?? null,
+    /**
+     * Open beside an object, or move to another one. `anchor()` returns the object's rectangle now (null when it is
+     * not on screen); `opener()` the element focus returns to; `render(mount, popover)` fills the content.
+     * Picking the object whose popover the same press has just closed leaves it closed: that press put it away.
+     */
+    open({ key, anchor, opener, render, label = 'Details' }) {
+      if (dismissed.key === key && performance.now() - dismissed.at < 700) { dismissed = { key: '', at: 0 }; return false; }
+      const same = current?.key === key;
+      current = { key, anchor, opener: opener ?? (() => null), render, sig: null, side: same ? current.side : null, lastAnchor: null };
+      el.setAttribute('aria-label', label);
+      if (!same) { el.hidden = true; content.replaceChildren(); natural = null; }
+      void draw({ force: true, focus: true });
+      return true;
+    },
+    /** Another page in the same popover (an object's note, and back): same place, same opener. */
+    show({ key, render, label }) {
+      if (!current) return;
+      current = { ...current, key, render, sig: null };
+      if (label) el.setAttribute('aria-label', label);
+      void draw({ force: true, focus: true });
+    },
+    /** The assets changed: the content is fetched again and swapped only if it differs; the popover stays where it is. */
+    refresh: (opts) => draw(opts),
+    /** A new anchor for the same popover (the view was rebuilt around it, or it was sent to the graph). */
+    reanchor(anchor) { if (current) { current.anchor = anchor; current.lastAnchor = null; current.side = null; reposition(); } },
+    reposition,
+    close,
+    focus: () => el.focus({ preventScroll: true }),
+  };
+
+  // Escape closes it and hands focus back; Tab moves through its items and stays inside it. One Escape closes one
+  // thing: a dialog on top of the popover takes it first, and the floating Keeper window does not also get it.
+  document.addEventListener('keydown', (e) => {
+    if (!current) return;
+    if (e.key === 'Escape') {
+      if (document.querySelector('dialog[open]')) return;
+      e.preventDefault();
+      e.stopPropagation();
+      close('escape');
+      return;
+    }
+    if (e.key !== 'Tab' || !el.contains(document.activeElement)) return;
+    const items = focusables();
+    if (!items.length) { e.preventDefault(); return; }
+    const at = items.indexOf(document.activeElement);
+    if (e.shiftKey && at <= 0) { e.preventDefault(); items[items.length - 1].focus(); }
+    else if (!e.shiftKey && at === items.length - 1) { e.preventDefault(); items[0].focus(); }
+  }, true);
+
+  // A press elsewhere closes it. The Keeper is not elsewhere (it is used beside the popover), nor is a dialog opened
+  // from it, nor the graph's canvas, which says for itself what a tap means (another object, the background, a pan).
+  document.addEventListener('pointerdown', (e) => {
+    if (!current || !(e.target instanceof Element)) return;
+    if (el.contains(e.target) || e.target.closest('dialog, #toast') || keepsOpen(e.target)) return;
+    dismissed = { key: current.key, at: performance.now() };
+    close('outside');
+  }, true);
+  scrim.addEventListener('click', () => close('outside'));
+
+  // It follows its object: a scroll anywhere (the List, the rail, the bottom strip) and any change of the window.
+  document.addEventListener('scroll', (e) => { if (current && !el.contains(e.target)) reposition(); }, true);
+  addEventListener('resize', () => reposition({ measure: true }));
+  // A fold opened inside it changes its height: measure again and check it still fits. (`toggle` does not bubble.)
+  el.addEventListener('toggle', () => reposition({ measure: true }), true);
+
+  return api;
+}

package/ui/project-folder.js

@@ -0,0 +1,37 @@
+// The project-folder authorization on the Keeper page (Spec §1.14): what the page says in each state, the words recorded
+// as the owner's when they press Authorize, and what a grant did. Text only, so it is tested without a browser
+// (src/ui/project-folder.test.ts); keeper-view.js draws it.
+
+const same = (t) => t;
+
+/** The state in one word, and the lines under the sentence that says what the authorization allows. */
+export function folderStatus(pf, { time = same, rel = same } = {}) {
+  if (pf.granted) {
+    const w = pf.lastWrite;
+    return {
+      tag: 'granted', tone: 'green', action: 'withdraw',
+      lines: [
+        `Folder: ${pf.path}`,
+        pf.commits ? 'The Keeper commits it itself: each commit contains only this folder and is never pushed.' : 'Write-only: the Keeper commits nothing; what it writes appears as uncommitted changes.',
+        `Granted ${time(pf.grantedAt)} · ${w ? `last written ${rel(w.at)}${w.commit ? ` in commit ${w.commit.slice(0, 7)}` : ', not committed'}` : 'not written yet'}`,
+      ],
+    };
+  }
+  const lines = ['Not granted: the Keeper writes nothing into the project.'];
+  if (pf.withdrawnAt) lines.push(`Withdrawn ${time(pf.withdrawnAt)}.${pf.exists ? ` ${pf.path} is still in the project, with its commits; it is yours to keep or delete.` : ''}`);
+  return { tag: 'not granted', tone: '', action: 'grant', lines };
+}
+
+/** The owner's statement a press of Authorize stands for: it is recorded with the authorization, as their words are. */
+export function grantWords({ folder, commits }) {
+  const name = String(folder).replace(/[\\/]+$/, '');
+  return `Authorized on the Keeper page: the Keeper may maintain ${name}/ in this project and ${commits ? 'commit that folder alone' : 'write it without committing'}; it never pushes.`;
+}
+
+/** What the grant did, for the message after it: the files written, the commit, or why there is none. */
+export function grantOutcome(sync) {
+  if (!sync || sync.status === 'not-authorized') return 'Authorized';
+  const files = sync.changedFiles?.length ?? 0;
+  const wrote = files ? `wrote ${files} file${files === 1 ? '' : 's'}` : 'the folder was already up to date';
+  return `Authorized: ${wrote}${sync.commit ? `, commit ${sync.commit.slice(0, 7)}` : ''}${sync.reason ? `. ${sync.reason}` : ''}`;
+}

package/ui/shell-state.js

@@ -0,0 +1,40 @@
+// The workbench's panels (Spec §6.1, D100; CKC-09 AC-43, AC-44): what the shell remembers and decides, apart from the
+// DOM, so the rules are tested with `node --test` (src/ui/shell-state.test.ts). app.js applies them to the page.
+
+/**
+ * Whether the left rail is folded to its strip. A choice of this browser, like the theme (Spec §6.1, §6.16): it lives in
+ * `localStorage`, never in the project's assets. Storage can be missing or throw (a private window, blocked site data);
+ * the choice then holds on this page only, and the page works the same.
+ */
+export const RAIL_KEY = 'pk.rail.folded';
+
+export function railMemory(storage = globalThis.localStorage) {
+  let here = null;   // the choice on this page, when the browser keeps none
+  return {
+    folded() {
+      try {
+        const v = storage?.getItem(RAIL_KEY);
+        if (v === '1' || v === '0') return v === '1';
+      } catch { /* no storage: the choice made on this page */ }
+      return here ?? false;
+    },
+    setFolded(folded) {
+      here = Boolean(folded);
+      try { storage?.setItem(RAIL_KEY, here ? '1' : '0'); } catch { /* remembered on this page only */ }
+      return here;
+    },
+  };
+}
+
+/**
+ * What one Escape does in the workbench, when nothing on top of it has taken it (a dialog, the popover and the control
+ * row's panels take theirs first, in the capture phase): close the reading sheet over the drawer, else restore the
+ * maximised main panel. A key pressed inside the Keeper conversation (its window closes itself on Escape; in the docked
+ * panel the owner is typing) does not restore the layout under it.
+ */
+export function escapeAction({ dialogOpen = false, sheetOpen = false, maximised = false, inKeeper = false } = {}) {
+  if (dialogOpen) return null;
+  if (sheetOpen) return 'close-sheet';
+  if (maximised && !inKeeper) return 'restore';
+  return null;
+}

package/ui/strip-rows.js

@@ -0,0 +1,171 @@
+// The bottom strip, one line per item (Spec §6.2; CKC-09 AC-38, after WorkflowKeeper's D55): every row is the same four
+// slots — mark · one sentence · object · time — and what used to be tags written into the line are its leading marks,
+// named on hover. This module says how the slots of a row are taken from an item of /overview, which mark stands for
+// which word, and what the header of `Notes (attention)` says about the notes that are not in it (D50). No DOM here:
+// items in, rows out, so the rules are tested with `node --test` (src/ui/strip-rows.test.ts). views.js draws them.
+//
+// A row is { key, marks: [{ glyph, tone, title }], text, object: { text, title }, time, noteId, opens }. `tone` is a
+// class of the stylesheet, which gives it one of the colours the interface already has; `time` is an ISO string or
+// null; `opens` is an object the row stands for (it then opens that object instead of unfolding).
+
+/** What a note asks of the owner. WorkflowKeeper's ladder for the same three steps (‼ ! ·); the first is the strongest. */
+const ASK = Object.freeze({
+  'For your decision': { glyph: '‼', tone: 'decide' },
+  'Worth discussing': { glyph: '!', tone: 'discuss' },
+  'For information': { glyph: '·', tone: 'info' },
+});
+/** How a note came about (Spec §4.1): a letter in a dashed frame, as the origin tag had a dashed frame. */
+const ORIGIN = Object.freeze({ 'Product re-look': 'R', 'Change follow-up': 'C', 'Investigation': 'I', 'Owner question': 'Q' });
+/** What is listed with the notes and is not one. */
+const NOT_A_NOTE = Object.freeze({
+  'scope-question': { glyph: '?', tone: 'decide', name: 'Scope question', about: 'Project scope' },
+  job: { glyph: '✓', tone: 'good', name: 'Request finished', about: 'Your request' },
+  round: { glyph: '↻', tone: 'info', name: 'Follow up result', about: 'Change follow-up' },
+});
+/** How a piece of work was cut out of the stream (Spec §1.8, D56). */
+const WORK = Object.freeze({ Session: 'S', Execution: 'E', 'Time range': 'T' });
+/** The effect of a record written before pieces of work; the tones are the colours the effect tags had. */
+const EFFECT = Object.freeze({
+  Added: { glyph: '+', tone: 'good' }, Approved: { glyph: '✓', tone: 'good' }, Completed: { glyph: '■', tone: 'good' },
+  Replaced: { glyph: '⇄', tone: 'bad' }, Abandoned: { glyph: '×', tone: 'bad' }, Deferred: { glyph: '‖', tone: 'wait' },
+  Corrected: { glyph: '~', tone: 'plain' }, Removed: { glyph: '−', tone: 'plain' },
+});
+const PROGRESS = Object.freeze({ Planned: '○', 'In progress': '◑', Done: '●', 'On hold': '‖' });
+
+const NONE = Object.freeze({ text: '', title: '' });
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const askMark = (ask, prefix = '') => { const a = ASK[ask]; return a ? { glyph: a.glyph, tone: a.tone, title: `${prefix}${ask}` } : null; };
+const effectMark = (effect) => { const e = EFFECT[effect] ?? { glyph: '•', tone: 'plain' }; return { glyph: e.glyph, tone: e.tone, title: effect ?? 'Change' }; };
+
+/** The object slot of a note: what it hangs on. One object by name, the first of several with how many more, or the project. */
+function mountSlot(object) {
+  if (!object) return NONE;
+  if (object.kind === 'project') return { text: 'Whole project', title: 'Whole project' };
+  const names = (object.objects ?? []).map((o) => o.label);
+  if (names.length === 0) return NONE;
+  return { text: names.length === 1 ? names[0] : `${names[0]} +${names.length - 1}`, title: names.join('\n') };
+}
+
+/** A row of `Notes (attention)`: a note, a scope question, a finished request or a Follow up result. */
+export function attentionRow(x) {
+  const base = { key: `${x.kind}:${x.id}`, text: x.label ?? '', time: x.at ?? null, noteId: null, opens: null };
+  if (x.kind === 'note') {
+    const origin = x.cameFrom?.kind ? { glyph: ORIGIN[x.cameFrom.kind] ?? '•', tone: 'origin', title: `Came from: ${x.cameFrom.kind}${x.cameFrom.changes?.length ? ` — ${x.cameFrom.changes.map((c) => c.title).join('; ')}` : ''}` } : null;
+    return { ...base, marks: [askMark(x.ask), origin].filter(Boolean), object: mountSlot(x.object), noteId: x.id };
+  }
+  const k = NOT_A_NOTE[x.kind] ?? { glyph: '•', tone: 'info', name: x.kind, about: '' };
+  // A Follow up result with news names the objects its news is about, as a note names what it hangs on; one without
+  // (a round closed before rounds counted their news) says where it belongs.
+  const objects = x.kind === 'round' && x.news ? mountSlot(x.object) : NONE;
+  return { ...base, marks: [{ glyph: k.glyph, tone: k.tone, title: x.ask ? `${k.name} · ${x.ask}` : k.name }], object: objects.text ? objects : { text: k.about, title: k.about } };
+}
+
+/** A row of `Recent changes`: one piece of work with how many net changes it made; an older record by effect and title. */
+export function changeRow(c) {
+  const removed = c.removed?.length ? { glyph: '−', tone: 'bad', title: `Removed: ${c.removed.map((x) => x.label).join(', ')}` } : null;
+  if (c.work) {
+    const n = (c.items ?? []).length || 1;
+    const count = plural(n, 'change');
+    return { key: `change:${c.id}`, marks: [{ glyph: WORK[c.work.kind] ?? '•', tone: 'work', title: c.work.kind }, removed].filter(Boolean), text: c.work.label, object: { text: count, title: count }, time: c.at ?? null, noteId: null, opens: null };
+  }
+  return { key: `change:${c.id}`, marks: [effectMark(c.effect), removed].filter(Boolean), text: c.title ?? '', object: NONE, time: c.at ?? null, noteId: null, opens: null };
+}
+
+/**
+ * The rows of `Since last visit`: each Follow up round since then, summed up in one line as `Notes (attention)` gives it —
+ * the same row, opened or not (Spec §3.8, §5.5) — then the work that moved on (each is an object, and opens it), the
+ * changes, the new notes.
+ */
+export function sinceRows(s) {
+  if (!s) return [];
+  return [
+    ...(s.rounds ?? []).map((r) => attentionRow(r)),
+    ...(s.threads ?? []).map((t) => ({ key: `work:${t.id}`, marks: [{ glyph: PROGRESS[t.progress] ?? '○', tone: 'work', title: `Work · ${t.progress}` }], text: t.title, object: { text: t.progress ?? '', title: t.progress ?? '' }, time: t.updatedAt ?? null, noteId: null, opens: { kind: 'node', id: t.id, label: t.title } })),
+    ...(s.changes ?? []).map((c) => ({ key: `change:${c.id}`, marks: [effectMark(c.effect)], text: c.title, object: NONE, time: c.at ?? null, noteId: null, opens: null })),
+    ...(s.notes ?? []).map((n) => ({ key: `note:${n.id}`, marks: [askMark(n.ask)].filter(Boolean), text: n.title, object: mountSlot(n.object), time: n.at ?? null, noteId: n.id, opens: null })),
+  ];
+}
+
+// ── The drawer and the ❓ on objects (Spec §6.1, §6.2; D100; CKC-09 AC-38) ─────────────────────────────────────
+/**
+ * Whether an item of `Notes (attention)` is marked ❓ on its objects instead of listed in the drawer: a note that hangs on
+ * a node, a relation or a path the project still has (§2.7 keeps it in `Notes (attention)`; D100 puts it on the object).
+ * A note on the whole project, one whose objects are all gone, and everything that is not a note stay in the drawer —
+ * an item with nowhere to be marked is never dropped.
+ */
+export function markedOnObjects(item) {
+  return item?.kind === 'note' && Boolean(item.object) && item.object.kind !== 'project' && (item.object.objects?.length ?? 0) > 0;
+}
+
+/**
+ * The attention notes marked ❓ on objects. SEAM (CF → CE): the Graph and the List draw the ❓ marks from CE's own
+ * `objectAttentionNotes(view)`; until that lands, the drawer counts with this, which follows the same rule
+ * (`markedOnObjects`). Once CE exports it, views.js `onObjectNotes` calls CE's function and this stays as its test.
+ */
+export function objectAttentionNotes(ov) {
+  return (ov?.needsYou ?? []).filter(markedOnObjects);
+}
+
+/** What the drawer's `Notes (attention)` lists: the whole-project part (Spec §6.2). */
+export function drawerAttention(ov) {
+  return (ov?.needsYou ?? []).filter((x) => !markedOnObjects(x));
+}
+
+/**
+ * The objects the ❓ count shows when it is pressed (the Graph and the List see only these, with what they need to be
+ * understood): each note's nodes, a relation by its two ends (the line is drawn between them), every object of a path.
+ * `relations` are the graph's, to find a relation's ends; one the graph does not have is left out.
+ */
+export function attentionTargets(notes, relations = []) {
+  const ends = new Map((relations ?? []).map((r) => [r.id, [r.from, r.to]]));
+  const ids = new Set();
+  for (const n of notes ?? []) {
+    for (const o of n.object?.objects ?? []) {
+      if (o.kind === 'relation') for (const id of ends.get(o.id) ?? []) ids.add(id);
+      else ids.add(o.id);
+    }
+  }
+  return [...ids];
+}
+
+/**
+ * The drawer's one line (Spec §6.1, §6.2): how many rows `Notes (attention)` and `Recent changes` have, whether there is a
+ * `Since last visit`, and how many attention notes are marked ❓ on objects. `onObjects` defaults to the rule above.
+ */
+export function drawerSummary(ov, onObjects = objectAttentionNotes(ov)) {
+  return {
+    attention: drawerAttention(ov).length,
+    changes: (ov?.recentChanges ?? []).length,
+    since: Boolean(ov?.sinceLastVisit),
+    onObjects: onObjects.length,
+  };
+}
+
+/**
+ * The header of `Notes (attention)` (D50; CKC-09 AC-1, AC-38; Spec §6.2): it says, in sight, why this list holds fewer
+ * notes than the project has — how many only inform, how many the owner has answered, how many wait on objects (❓) —
+ * and counts what is listed here and is not a note apart, never folded into the note number (§2.4). `hint` is the same
+ * in full sentences, for the hover. `onObjects` is the number of attention notes marked ❓ on objects.
+ */
+export function attentionHeader(ov, onObjects = objectAttentionNotes(ov).length) {
+  const list = drawerAttention(ov);
+  const of = (kind) => list.filter((x) => x.kind === kind).length;
+  const notes = of('note'), questions = of('scope-question'), finished = of('job'), rounds = of('round');
+  // A Follow up result is here when its round found something new (it carries the news, CKC-07 AC-27); one from a round
+  // closed before rounds counted their news is here, as it always was, when it left objects on the old understanding.
+  const withNews = list.filter((x) => x.kind === 'round' && x.news).length;
+  const earlier = rounds - withNews;
+  const c = ov?.noteCounts ?? null;
+  const count = c ? `${notes} of ${plural(c.current, 'note')}` : notes ? plural(notes, 'note') : '';
+  const why = c ? [c.information ? `${c.information} for information` : '', c.answered ? `${c.answered} answered` : '', onObjects ? `❓ ${onObjects} on objects` : ''].filter(Boolean).join(' · ') : onObjects ? `❓ ${onObjects} on objects` : '';
+  const also = [questions ? plural(questions, 'scope question') : '', finished ? `${plural(finished, 'request')} done` : '', rounds ? plural(rounds, 'Follow up result') : ''].filter(Boolean).join(' · ');
+  const onObjectsSaid = onObjects ? ` ${onObjects} ${onObjects === 1 ? 'waits' : 'wait'} on you on ${onObjects === 1 ? 'its object' : 'their objects'}, marked ❓ there; press the ❓ count to see only those objects.` : '';
+  const hint = [
+    c ? `${notes} of the project's ${c.current} current notes wait on you here. The other ${c.current - notes} are not here: ${c.information} are for information only and ${c.answered} you have already answered.${onObjectsSaid} The Notes log has all of them.` : `Notes on the whole project that ask something of you and you have not answered yet.${onObjectsSaid} The Notes log has all of them.`,
+    questions ? `Also here, counted separately: ${plural(questions, 'unanswered scope question')}.` : '',
+    finished ? `${plural(finished, 'request')} you gave finished and wait${finished === 1 ? 's' : ''} for you to look.` : '',
+    withNews ? `${plural(withNews, 'Follow up result')} with something new.` : '',
+    earlier ? `${plural(earlier, 'Follow up result')} from before rounds counted what they found new, with objects still on the old understanding.` : '',
+  ].filter(Boolean).join(' ');
+  return { count, why: why ? `Not here: ${why}` : '', also: also ? `Also here: ${also}` : '', hint, onObjects };
+}