diffninja 0.1.1 → 0.3.0

package/dist/review/connected-html.js

@@ -36,6 +36,26 @@ export function renderConnectedPage(csrf) {
         `<p class="brand">${BRAND_MARK}<span>diffninja</span></p>`,
         '<h1 id="page-title">Pull request review</h1>',
         '<p id="page-meta" class="page-meta" hidden></p>',
+        '<section id="pr-goal" class="pr-goal" aria-labelledby="pr-goal-heading" hidden>',
+        '<h2 id="pr-goal-heading" class="pr-goal-heading">Goal</h2>',
+        '<p id="pr-goal-text" class="pr-goal-text"></p>',
+        '<p id="pr-goal-by" class="pr-goal-by" hidden></p>',
+        "</section>",
+        '<section id="pr-how" class="pr-how" aria-labelledby="pr-how-heading" hidden>',
+        '<details class="pr-how-fold" open>',
+        '<summary class="pr-how-head"><h2 id="pr-how-heading" class="pr-goal-heading">How it works</h2></summary>',
+        '<div class="pr-how-tools">',
+        '<p id="pr-how-by" class="pr-goal-by"></p>',
+        '<button type="button" id="pr-how-open" class="btn btn-quiet btn-sm" data-action="open-how" aria-label="Open how it works beside the diff">Open beside the diff</button>',
+        "</div>",
+        '<iframe id="pr-how-frame" class="pr-how-frame" title="How it works: the business processes and rules this change touches"></iframe>',
+        "</details>",
+        "</section>",
+        '<details id="pr-description" class="pr-description" hidden>',
+        '<summary>Original PR description</summary>',
+        '<p class="note">The author’s own words, as written, including any generated notes. Raw HTML is shown as text, images as links, and nothing here is loaded from another host. It is the author’s claim, not evidence that the changes achieve it.</p>',
+        '<div id="pr-description-body" class="pr-description-body"></div>',
+        "</details>",
         '<p id="lede" class="lede">Load a GitHub pull request, read its diff in a recommended order, and post your own review through the <span class="mono">gh</span> CLI. Nothing is posted until you press Submit.</p>',
         '<p id="message-note" class="note" role="status" aria-live="polite" hidden></p>',
         "</header>",
@@ -840,6 +860,8 @@ function script(csrf) {
     show(el.lede, !snap);
     show(el.loadSection, !snap || showLoad);
     show(el.pageMeta, Boolean(snap));
+    show(el.prDescription, Boolean(snap));
+    renderDescription();
     el.pageMeta.textContent = '';
     el.snapshotBody.textContent = '';
     if (!snap) {
@@ -854,10 +876,6 @@ function script(csrf) {
     el.pageMeta.appendChild(make('span', 'meta-item sha', shortSha(snap.headSha)));
     var login = reviewerLogin();
     if (login !== '') el.pageMeta.appendChild(make('span', 'meta-item', 'Reviewing as ' + login));
-    var description = make('details', '');
-    description.appendChild(make('summary', '', 'Description (the author\u2019s claims)'));
-    description.appendChild(make('pre', '', typeof snap.body === 'string' && snap.body ? snap.body : 'No description.'));
-    el.snapshotBody.appendChild(description);
     var dl = make('dl', 'facts');
     addLinkFact(dl, 'Pull request', snap.url, typeof snap.url === 'string' ? snap.url : 'unknown');
     addFact(dl, 'GitHub state', typeof snap.state === 'string' ? snap.state : 'unknown');
@@ -905,9 +923,248 @@ function script(csrf) {
     return wrap;
   }
 
+  /* ---------------------------------------------------------- description -- */
+
+  /**
+   * The author's description, rendered from the node tree the server parsed out
+   * of their Markdown. This page may not set markup directly, so every node
+   * becomes a whitelisted element and every string a text node: raw HTML
+   * arrives as text, an image arrives as a link, and an anchor is created only
+   * for an http(s) URL. The body is never summarized, shortened or rewritten
+   * here — the snapshot's own body text stays the untouched source, and the
+   * goal above it is the agent's sentence about the goal, not a rewrite of
+   * this text.
+   */
+  function inlineNodesInto(host, nodes, depth) {
+    if (!Array.isArray(nodes) || depth > 16) return;
+    for (var i = 0; i < nodes.length; i += 1) {
+      var node = nodes[i];
+      if (!node || typeof node !== 'object') continue;
+      var type = typeof node.t === 'string' ? node.t : '';
+      if (type === 'text') {
+        if (typeof node.v === 'string') host.appendChild(document.createTextNode(node.v));
+        continue;
+      }
+      if (type === 'code') {
+        host.appendChild(make('code', 'pr-inline-code', typeof node.v === 'string' ? node.v : ''));
+        continue;
+      }
+      if (type === 'br') { host.appendChild(document.createElement('br')); continue; }
+      if (type === 'strong' || type === 'em' || type === 'del') {
+        var wrapper = document.createElement(type);
+        inlineNodesInto(wrapper, node.c, depth + 1);
+        host.appendChild(wrapper);
+        continue;
+      }
+      if (type === 'link') {
+        var inner = document.createDocumentFragment();
+        inlineNodesInto(inner, node.c, depth + 1);
+        // The URL is checked here too: no anchor is built for anything but http(s).
+        if (typeof node.href === 'string' && /^https?:\\/\\//i.test(node.href)) {
+          var link = document.createElement('a');
+          link.href = node.href;
+          link.target = '_blank';
+          link.rel = 'noopener noreferrer';
+          link.appendChild(inner);
+          host.appendChild(link);
+        } else {
+          host.appendChild(inner);
+        }
+        continue;
+      }
+      // Anything this page does not know is shown as its own text.
+      if (typeof node.v === 'string') host.appendChild(document.createTextNode(node.v));
+    }
+  }
+
+  function blockNodesInto(host, nodes, depth) {
+    if (!Array.isArray(nodes) || depth > 16) return;
+    for (var i = 0; i < nodes.length; i += 1) {
+      var node = nodes[i];
+      if (!node || typeof node !== 'object') continue;
+      var type = typeof node.t === 'string' ? node.t : '';
+      if (type === 'para') {
+        var para = document.createElement('p');
+        inlineNodesInto(para, node.c, depth + 1);
+        host.appendChild(para);
+        continue;
+      }
+      if (type === 'heading') {
+        // Demoted: the page owns h1 and h2, so a description's headings stay below them.
+        var level = typeof node.d === 'number' && isFinite(node.d) ? Math.min(Math.max(Math.floor(node.d) + 2, 3), 6) : 3;
+        var heading = document.createElement('h' + String(level));
+        inlineNodesInto(heading, node.c, depth + 1);
+        host.appendChild(heading);
+        continue;
+      }
+      if (type === 'quote') {
+        var quote = document.createElement('blockquote');
+        blockNodesInto(quote, node.c, depth + 1);
+        host.appendChild(quote);
+        continue;
+      }
+      if (type === 'code') {
+        var lang = typeof node.lang === 'string' ? node.lang : '';
+        var pre = make('pre', 'pr-code', typeof node.v === 'string' ? node.v : '');
+        if (lang !== '') pre.setAttribute('data-lang', lang);
+        host.appendChild(pre);
+        continue;
+      }
+      if (type === 'raw') {
+        // Markup in the description is shown verbatim, as text.
+        host.appendChild(make('pre', 'pr-raw', typeof node.v === 'string' ? node.v : ''));
+        continue;
+      }
+      if (type === 'rule') { host.appendChild(document.createElement('hr')); continue; }
+      if (type === 'list') {
+        var ordered = node.ordered === true;
+        var list = document.createElement(ordered ? 'ol' : 'ul');
+        if (ordered && typeof node.start === 'number' && isFinite(node.start) && node.start > 1) list.start = Math.floor(node.start);
+        var items = Array.isArray(node.items) ? node.items : [];
+        for (var j = 0; j < items.length; j += 1) {
+          var item = items[j] && typeof items[j] === 'object' ? items[j] : {};
+          var entry = document.createElement('li');
+          if (item.task === true) {
+            entry.className = 'pr-task';
+            var box = document.createElement('input');
+            box.type = 'checkbox';
+            box.disabled = true;
+            box.checked = item.checked === true;
+            box.setAttribute('aria-label', item.checked === true ? 'Task done' : 'Task not done');
+            entry.appendChild(box);
+          }
+          blockNodesInto(entry, item.c, depth + 1);
+          list.appendChild(entry);
+          if (!entry.hasChildNodes()) entry.appendChild(document.createTextNode('(empty)'));
+        }
+        host.appendChild(list);
+        continue;
+      }
+      if (type === 'table') {
+        var align = Array.isArray(node.align) ? node.align : [];
+        var table = make('table', 'pr-table');
+        var head = Array.isArray(node.head) ? node.head : [];
+        if (head.length > 0) {
+          var headRow = document.createElement('tr');
+          for (var h = 0; h < head.length; h += 1) {
+            var th = make('th', 'pr-align-' + (align[h] === 'center' || align[h] === 'right' ? align[h] : 'left'));
+            inlineNodesInto(th, head[h], depth + 1);
+            headRow.appendChild(th);
+          }
+          var thead = document.createElement('thead');
+          thead.appendChild(headRow);
+          table.appendChild(thead);
+        }
+        var rows = Array.isArray(node.rows) ? node.rows : [];
+        var body = document.createElement('tbody');
+        for (var r = 0; r < rows.length; r += 1) {
+          var row = Array.isArray(rows[r]) ? rows[r] : [];
+          var rowElement = document.createElement('tr');
+          for (var c = 0; c < row.length; c += 1) {
+            var td = make('td', 'pr-align-' + (align[c] === 'center' || align[c] === 'right' ? align[c] : 'left'));
+            inlineNodesInto(td, row[c], depth + 1);
+            rowElement.appendChild(td);
+          }
+          body.appendChild(rowElement);
+        }
+        table.appendChild(body);
+        host.appendChild(table);
+        continue;
+      }
+      // An unknown block that carries children or text is still readable as that.
+      if (Array.isArray(node.c)) { blockNodesInto(host, node.c, depth + 1); continue; }
+      if (typeof node.v === 'string' && node.v !== '') host.appendChild(make('p', null, node.v));
+    }
+  }
+
+  function renderDescription() {
+    var snap = snapshot();
+    var host = el.prDescriptionBody;
+    host.textContent = '';
+    var blocks = snap && Array.isArray(snap.bodyBlocks) ? snap.bodyBlocks : null;
+    var plain = snap && typeof snap.body === 'string' ? snap.body.trim() : '';
+    host.className = 'pr-description-body';
+    if (blocks && blocks.length > 0) { blockNodesInto(host, blocks, 0); return; }
+    // No parsed form in this response, or one this server would not hold in full:
+    // the author's own bytes, unwrapped, rather than a cut-off rendering.
+    if (plain !== '') {
+      host.appendChild(make('div', 'pr-plain', plain));
+      if (snap.bodyTooLarge === true) {
+        host.appendChild(make('p', 'note', 'This description is longer than this page will format, so it is shown as the author wrote it, in full and unformatted.'));
+      }
+      return;
+    }
+    setText(host, 'The author has not provided a PR description. No expected outcome was stated.');
+  }
+
+  /**
+   * The goal the reviewing agent recorded for this revision, at the top of the
+   * page: the reading the review was done against, in the agent's own words. It
+   * belongs to the revision on screen — an analysis of another revision shows
+   * nothing rather than a stale goal — and when none was recorded the block
+   * says so instead of describing the pull request itself.
+   */
+  function renderGoal() {
+    var snap = snapshot();
+    // A revision that cannot be reviewed gets no goal block: there is nothing to aim the reading at.
+    var reviewable = Boolean(snap) && !(typeof snap.unavailableReason === 'string' && snap.unavailableReason !== '');
+    show(el.prGoal, reviewable);
+    if (!reviewable) return;
+    var current = currentAnalysis();
+    var source = current && current.summary && typeof current.summary === 'object' ? current.summary : null;
+    var text = source && typeof source.text === 'string' ? source.text.trim() : '';
+    setText(el.prGoalText, '');
+    setText(el.prGoalBy, '');
+    show(el.prGoalBy, false);
+    if (text !== '') {
+      el.prGoal.className = 'pr-goal';
+      el.prGoalText.className = 'pr-goal-text';
+      setText(el.prGoalText, text);
+      var by = typeof source.summarizedBy === 'string' ? source.summarizedBy.trim() : '';
+      setText(el.prGoalBy, 'Recorded by ' + (by === '' ? 'your review agent' : by) + ' from the pull request title and description. It is the agent\u2019s reading of the goal, not a check that the changes reach it.');
+      show(el.prGoalBy, true);
+      return;
+    }
+    el.prGoal.className = 'pr-goal is-empty';
+    el.prGoalText.className = 'pr-goal-note';
+    setText(el.prGoalText, goalAbsentReason(snap));
+  }
+
+  /**
+   * The agent's business view under the goal: the processes and rules this
+   * change touches, drawn by the server into a same-origin frame that reports
+   * its own height. Shown only once the agent's explanation was accepted for the
+   * revision on screen; the frame reloads only when that revision changes.
+   */
+  function renderHow() {
+    var snap = snapshot();
+    var current = currentAnalysis();
+    var explanation = current && current.explanation && typeof current.explanation === 'object' ? current.explanation : null;
+    var ready = Boolean(snap) && explanation !== null && current.snapshotId === snap.id;
+    show(el.prHow, ready);
+    if (!ready) { if (el.prHowFrame.getAttribute('src')) el.prHowFrame.removeAttribute('src'); return; }
+    var by = typeof explanation.explainedBy === 'string' && explanation.explainedBy.trim() !== '' ? explanation.explainedBy.trim() : 'your review agent';
+    var processes = Array.isArray(explanation.processes) ? explanation.processes.length : 0;
+    setText(el.prHowBy, 'Explained by ' + by + ' from the code: ' + processes + (processes === 1 ? ' process' : ' processes') + ' and ' + (explanation.rules || 0) + ((explanation.rules || 0) === 1 ? ' business rule' : ' business rules') + '. Its reading, not a verdict; the diff below is the ground truth.');
+    var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + '&view=business';
+    if (el.prHowFrame.getAttribute('src') !== src) el.prHowFrame.setAttribute('src', src);
+  }
+
+  /** Why no goal is on screen: the analysis is still coming, is of another revision, or recorded none. */
+  function goalAbsentReason(snap) {
+    if (!analysis || analysisFor !== snap.id) return 'Waiting for the local analysis of this revision\u2026';
+    if (analysis.available !== true) {
+      var reason = typeof analysis.reason === 'string' && analysis.reason !== '' ? analysis.reason : 'no local analysis is attached to this session.';
+      return 'No agent-stated goal for this revision: ' + reason;
+    }
+    if (analysis.snapshotId !== snap.id) return 'The pull request changed; waiting for the analysis of this revision before any goal is shown.';
+    return 'No goal was recorded for this revision. The reviewing agent records one when it finishes its review; the original description below is the author\u2019s own words.';
+  }
+
   /* ------------------------------------------------------------ analysis -- */
 
   var STATUS_ORDER = ['attention', 'uncertain', 'low', 'passed'];
+  var CHANGE_WORD = { added: 'New', changed: 'Changed', removed: 'Removed' };
 
   function currentAnalysis() {
     var snap = snapshot();
@@ -915,17 +1172,12 @@ function script(csrf) {
     return analysis;
   }
 
-  function worstStatusFor(path) {
+  function fileHasUncertainty(path) {
     var current = currentAnalysis();
-    if (!current || !Array.isArray(current.hunks)) return '';
-    var best = STATUS_ORDER.length;
-    for (var i = 0; i < current.hunks.length; i += 1) {
-      var hunk = current.hunks[i];
-      if (!hunk || hunk.file !== path) continue;
-      var rank = STATUS_ORDER.indexOf(hunk.status);
-      if (rank >= 0 && rank < best) best = rank;
-    }
-    return best < STATUS_ORDER.length ? STATUS_ORDER[best] : '';
+    if (!current || !Array.isArray(current.hunks)) return false;
+    return current.hunks.some(function (hunk) {
+      return hunk && hunk.file === path && hunk.status === 'uncertain';
+    });
   }
 
   function scheduleAnalysis(delay) {
@@ -956,7 +1208,9 @@ function script(csrf) {
       var pendingAnswers = analysis && analysis.available === true && analysis.questions && analysis.questions.answered < analysis.questions.total;
       var pendingOrder = analysis && analysis.available === true && !(analysis.order && analysis.order.source === 'agent');
       var pendingSuggestions = analysis && analysis.available === true && !analysis.suggestions;
-      if (pendingAnswers || pendingOrder || pendingSuggestions) scheduleAnalysis(10000);
+      // The goal of the revision is recorded when the agent finishes, which can be after its order arrived.
+      var pendingGoal = analysis && analysis.available === true && !analysis.summary;
+      if (pendingAnswers || pendingOrder || pendingSuggestions || pendingGoal) scheduleAnalysis(10000);
     });
   }
 
@@ -979,12 +1233,8 @@ function script(csrf) {
     return out;
   }
 
-  var STATUS_LABEL = { attention: 'Attention', uncertain: 'Uncertain', low: 'Low', passed: 'Passed' };
-
-  /** A status as a small tinted label; the word is the text, the tint only repeats it. */
-  function statusTag(status) {
-    var known = STATUS_ORDER.indexOf(status) >= 0 ? status : 'uncertain';
-    return make('span', 'status-tag status-' + known, STATUS_LABEL[known]);
+  function uncertaintyTag() {
+    return make('span', 'status-tag status-uncertain', 'Uncertain');
   }
 
   /** A path with its directory muted, so the file name reads first. */
@@ -1013,7 +1263,7 @@ function script(csrf) {
     return go;
   }
 
-  /** One station of the rail: where the change is and whether it asks for attention; what to look at lives beside the code. */
+  /** One station of the rail: where the change is; what to look at lives beside the code. */
   function renderHunkEntry(hunk, rank) {
     var entry = make('li', 'order-item');
     entry.dataset.action = 'goto-stop';
@@ -1028,8 +1278,7 @@ function script(csrf) {
     where.appendChild(make('span', 'path-line', ':' + String(hunk.line)));
     main.appendChild(where);
     var meta = make('div', 'order-meta');
-    // Only a status that asks for something is shown; low and passed stay quiet.
-    if (hunk.status === 'attention' || hunk.status === 'uncertain') meta.appendChild(statusTag(hunk.status));
+    if (hunk.status === 'uncertain') meta.appendChild(uncertaintyTag());
     meta.appendChild(sizeNode(hunk.added, hunk.removed));
     main.appendChild(meta);
     var jump = make('a', 'sr-only', 'Go to change ' + rank + ', ' + hunk.file + ' line ' + hunk.line);
@@ -1049,7 +1298,8 @@ function script(csrf) {
     var verdicts = answeredVerdicts(hunk);
     var facts = Array.isArray(hunk.facts) ? hunk.facts : [];
     var note = typeof hunk.note === 'string' ? hunk.note : '';
-    if (rank === 0 && verdicts.length === 0 && facts.length === 0 && note === '') return null;
+    var business = Array.isArray(hunk.business) ? hunk.business : [];
+    if (rank === 0 && verdicts.length === 0 && facts.length === 0 && note === '' && business.length === 0) return null;
     var why = make('div', 'stop-why' + (rank > 0 ? ' has-rank' : ''));
     if (rank > 0) {
       var badge = make('span', 'why-rank', String(rank));
@@ -1057,6 +1307,19 @@ function script(csrf) {
       why.appendChild(badge);
     }
     var main = make('div', 'why-main');
+    if (business.length > 0) {
+      var steps = make('div', 'tag-row business-row');
+      steps.appendChild(make('span', 'tag-lead', 'In the business'));
+      for (var b = 0; b < business.length; b += 1) {
+        var link = business[b];
+        var change = typeof link.change === 'string' ? link.change : 'unchanged';
+        var step = make('span', 'business-step change-' + change);
+        if (change !== 'unchanged') step.appendChild(make('span', 'business-change', CHANGE_WORD[change] || change));
+        step.appendChild(make('span', 'business-text', (typeof link.process === 'string' ? link.process + ': ' : 'Rule: ') + String(link.text)));
+        steps.appendChild(step);
+      }
+      main.appendChild(steps);
+    }
     if (verdicts.length > 0) {
       var said = make('div', 'tag-row');
       said.appendChild(make('span', 'sr-only', 'Your agent says: '));
@@ -1117,6 +1380,9 @@ function script(csrf) {
 
   function renderAnalysis() {
     var snap = snapshot();
+    // The goal rides on the analysis, so it re-renders wherever the analysis does — every poll included.
+    renderGoal();
+    renderHow();
     show(el.analysisSection, Boolean(snap) && !(typeof snap.unavailableReason === 'string' && snap.unavailableReason !== ''));
     el.analysisBody.textContent = '';
     el.analysisActions.textContent = '';
@@ -1506,8 +1772,9 @@ function script(csrf) {
     var src = '/flow?snapshot=' + encodeURIComponent(current.snapshotId) + (path === '' ? '' : '&file=' + encodeURIComponent(path));
     if (el.flowFrame.getAttribute('src') !== src) el.flowFrame.setAttribute('src', src);
     flowSnapshot = current.snapshotId;
-    setText(el.flowTitle, path === '' ? 'Call flows' : 'Call flow: ' + path);
-    el.flowFrame.title = path === '' ? 'Call flows of every changed file' : 'Call flow of ' + path;
+    var explained = Boolean(current.explanation);
+    setText(el.flowTitle, path === '' ? (explained ? 'How it works and call flows' : 'Call flows') : 'Call flow: ' + path);
+    el.flowFrame.title = path === '' ? (explained ? 'How it works, and the call flows of every changed file' : 'Call flows of every changed file') : 'Call flow of ' + path;
     if (el.flowDrawer.hidden) flowReturn = opener || document.activeElement;
     show(el.flowDrawer, true);
     document.body.classList.add('flow-open');
@@ -1531,7 +1798,16 @@ function script(csrf) {
 
   /** The diagram in the drawer opened or closed: the drawer takes the whole window while it is open. */
   function onFlowMessage(event_) {
-    if (event_.origin !== window.location.origin || event_.source !== el.flowFrame.contentWindow) return;
+    if (event_.origin !== window.location.origin) return;
+    // The inline business view reports its height; nothing else it sends is read.
+    if (event_.source === el.prHowFrame.contentWindow) {
+      var sized = event_.data;
+      if (sized && sized.type === 'diffninja-business-height' && typeof sized.height === 'number' && isFinite(sized.height)) {
+        el.prHowFrame.style.height = Math.max(120, Math.min(20000, Math.ceil(sized.height))) + 'px';
+      }
+      return;
+    }
+    if (event_.source !== el.flowFrame.contentWindow) return;
     var data = event_.data;
     if (!data || data.type !== 'diffninja-diagram') return;
     document.body.classList.toggle('flow-full', data.open === true);
@@ -1867,7 +2143,7 @@ function script(csrf) {
     where.appendChild(make('span', 'path-line', ':' + String(lead.line)));
     head.appendChild(where);
     head.appendChild(sizeOf([stop.segment]));
-    if (lead.status === 'attention' || lead.status === 'uncertain') head.appendChild(statusTag(lead.status));
+    if (lead.status === 'uncertain') head.appendChild(uncertaintyTag());
     var tools = make('span', 'file-tools');
     if (hasCallFlow(stop.path)) tools.appendChild(flowButton(stop.path, 'Call flow'));
     head.appendChild(tools);
@@ -1891,8 +2167,7 @@ function script(csrf) {
     var head = make('summary', 'file-head');
     head.appendChild(pathNode(group.path, 'file-path'));
     head.appendChild(sizeOf(segments));
-    var worst = worstStatusFor(group.path);
-    if (worst === 'attention' || worst === 'uncertain') head.appendChild(statusTag(worst));
+    if (fileHasUncertainty(group.path)) head.appendChild(uncertaintyTag());
     var tools = make('span', 'file-tools');
     if (hasCallFlow(group.path)) tools.appendChild(flowButton(group.path, 'Call flow'));
     head.appendChild(tools);
@@ -2280,6 +2555,7 @@ function script(csrf) {
     placeAnchor = action === 'preview' || action === 'submit' || action === 'refresh' ? node : null;
     if (action === 'comment') { event_.preventDefault(); addComment(node); return; }
     if (action === 'open-flow') { event_.preventDefault(); openFlow(node.getAttribute('data-path') || '', node); return; }
+    if (action === 'open-how') { event_.preventDefault(); openFlow('', node); return; }
     if (action === 'close-flow') { event_.preventDefault(); closeFlow(); return; }
     if (action === 'add-suggestion') { event_.preventDefault(); addSuggestion(node); return; }
     if (action === 'add-all-suggestions') { event_.preventDefault(); addAllSuggestions(); return; }
@@ -2334,6 +2610,14 @@ function script(csrf) {
     el.refreshButton = byId('refresh-button');
     el.pageTitle = byId('page-title');
     el.pageMeta = byId('page-meta');
+    el.prGoal = byId('pr-goal');
+    el.prGoalText = byId('pr-goal-text');
+    el.prGoalBy = byId('pr-goal-by');
+    el.prHow = byId('pr-how');
+    el.prHowBy = byId('pr-how-by');
+    el.prHowFrame = byId('pr-how-frame');
+    el.prDescription = byId('pr-description');
+    el.prDescriptionBody = byId('pr-description-body');
     el.lede = byId('lede');
     el.loadSection = byId('load-section');
     el.detailsSection = byId('details-section');
@@ -2451,6 +2735,63 @@ ${BRAND_MARK_STYLES}
 .brand .brand-mark { width: 20px; height: 20px; }
 .page-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 12px; font-size: 13px; color: var(--ink-soft); }
 .page-meta a { font-weight: 600; }
+/* The agent's stated goal, first thing under the masthead: one sentence, with its attribution. */
+.pr-goal { margin-top: 6px; padding: 14px 16px; border: 1px solid var(--line); border-left: 3px solid var(--accent); border-radius: var(--radius); background: var(--panel); }
+.pr-goal.is-empty { border-left-color: var(--line-strong); background: var(--sunken); }
+.pr-goal-heading { font-size: 11.5px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: var(--ink-soft); }
+.pr-goal-text { margin: 6px 0 0; font-size: 15.5px; font-weight: 600; line-height: 1.5; overflow-wrap: anywhere; max-width: 90ch; }
+.pr-goal-note { margin: 6px 0 0; font-size: 13px; color: var(--ink-soft); overflow-wrap: anywhere; max-width: 90ch; }
+.pr-goal-by { margin: 6px 0 0; font-size: 12.5px; color: var(--ink-faint); overflow-wrap: anywhere; max-width: 90ch; }
+.pr-how { margin-top: 10px; padding: 14px 16px 10px; border: 1px solid var(--line); border-left: 3px solid var(--ok); border-radius: var(--radius); background: var(--panel); }
+.pr-how-head { cursor: pointer; width: fit-content; }
+.pr-how-head h2 { display: inline; }
+.pr-how-tools { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; flex-wrap: wrap; }
+.pr-how-tools .pr-goal-by { flex: 1 1 320px; }
+.pr-how-frame { display: block; width: 100%; height: 480px; margin-top: 10px; border: 0; background: transparent; color-scheme: normal; }
+.business-row { align-items: flex-start; }
+.business-step { display: inline-flex; align-items: baseline; gap: 6px; max-width: 100%; padding: 2px 8px; border: 1px solid var(--line); border-radius: 6px; font-size: 12.5px; color: var(--ink); background: var(--panel); overflow-wrap: anywhere; }
+.business-step.change-added { border-color: var(--ok); background: var(--ok-soft); }
+.business-step.change-changed { border-color: var(--warn); background: var(--warn-soft); }
+.business-step.change-removed { border-color: var(--alarm); background: var(--alarm-bg); }
+.business-change { flex: none; font-size: 10px; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; color: var(--ink-soft); }
+.change-added .business-change { color: var(--ok); }
+.change-changed .business-change { color: var(--warn); }
+.change-removed .business-change { color: var(--alarm); }
+.pr-description { margin-top: 6px; padding: 12px 16px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--panel); }
+.pr-description > summary { cursor: pointer; font-size: 14px; font-weight: 600; }
+.pr-description > .note { margin-top: 10px; }
+.pr-description-body { margin-top: 10px; overflow-wrap: anywhere; font: 14px/1.6 var(--sans); max-width: 90ch; }
+/* No parsed form in the response, or one too large to hold: the author's own bytes, unwrapped. */
+.pr-description-body .pr-plain { white-space: pre-wrap; }
+/* The author's Markdown, laid out as the document it is; every size stays below the page's own headings. */
+.pr-description-body > *:first-child { margin-top: 0; }
+.pr-description-body > *:last-child { margin-bottom: 0; }
+.pr-description-body p, .pr-description-body blockquote, .pr-description-body table, .pr-description-body pre, .pr-description-body ul, .pr-description-body ol { margin: 0 0 10px; }
+.pr-description-body h3, .pr-description-body h4, .pr-description-body h5, .pr-description-body h6 { margin: 16px 0 6px; line-height: 1.3; }
+.pr-description-body h3 { font-size: 15px; }
+.pr-description-body h4 { font-size: 14px; }
+.pr-description-body h5, .pr-description-body h6 { font-size: 13px; color: var(--ink-soft); }
+.pr-description-body ul, .pr-description-body ol { padding-left: 22px; }
+.pr-description-body li { margin: 2px 0; }
+.pr-description-body li > ul, .pr-description-body li > ol { margin: 2px 0 0; }
+.pr-description-body li > p { margin: 0 0 6px; }
+.pr-description-body blockquote { padding: 2px 0 2px 12px; border-left: 3px solid var(--line-strong); color: var(--ink-soft); }
+.pr-description-body hr { margin: 14px 0; border: 0; border-top: 1px solid var(--line); }
+.pr-description-body a { color: var(--accent); text-decoration: underline; text-underline-offset: 2px; }
+.pr-description-body code { font: 12.5px var(--mono); background: var(--sunken); border: 1px solid var(--line-soft); border-radius: 4px; padding: 1px 4px; }
+.pr-description-body pre { padding: 9px 11px; background: var(--sunken); border: 1px solid var(--line); border-radius: 6px; overflow-x: auto; font: 12.5px/1.5 var(--mono); white-space: pre; }
+.pr-description-body pre code { padding: 0; border: 0; background: none; font: inherit; }
+/* Raw HTML in a description is shown, not run: dimmed, so it reads as text the author wrote. */
+.pr-description-body .pr-raw { color: var(--ink-soft); white-space: pre-wrap; }
+.pr-description-body .pr-task { list-style: none; }
+.pr-description-body .pr-task input { margin-right: 6px; vertical-align: baseline; }
+/* The marker sits beside the item's first line, not above the paragraph it labels. */
+.pr-description-body .pr-task > p:first-of-type { display: inline; margin: 0; }
+.pr-description-body table.pr-table { width: 100%; border-collapse: collapse; font-size: 13px; display: block; overflow-x: auto; }
+.pr-description-body .pr-table th, .pr-description-body .pr-table td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; vertical-align: top; }
+.pr-description-body .pr-table th { background: var(--panel-head, var(--sunken)); font-weight: 650; }
+.pr-description-body .pr-align-center { text-align: center; }
+.pr-description-body .pr-align-right { text-align: right; }
 .meta-item.sha { font: 12px var(--mono); padding: 2px 7px; border-radius: 6px; background: var(--neutral-soft); color: var(--ink); }
 .state-badge {
   display: inline-flex; align-items: center; height: 24px; padding: 0 10px; border-radius: 999px;
@@ -2529,7 +2870,6 @@ body.is-busy button { cursor: progress; }
   font-size: 11.5px; font-weight: 600; white-space: nowrap;
   color: var(--ink-soft); background: var(--neutral-soft);
 }
-.status-tag.status-attention { color: var(--alarm); background: var(--alarm-bg); }
 .status-tag.status-uncertain { color: var(--warn); background: var(--warn-soft); }
 .tag-row { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 6px; }
 .tag {

package/dist/review/connected.d.ts

@@ -1,10 +1,22 @@
 import { type Server } from "node:http";
 import { ConnectedReview } from "./github.js";
+import { type MarkdownBlock } from "./markdown.js";
 import type { ConnectedAnalysisView } from "./connected-analysis.js";
 export interface ConnectedSession {
     server: Server;
     url: string;
 }
+/**
+ * What `GET /api/state` adds to the snapshot: the author's description already
+ * parsed into the nodes the page renders. The snapshot's own `body` is left
+ * exactly as GitHub returned it; these nodes are how the page shows it.
+ */
+export interface ConnectedDescription {
+    /** The description as nodes. Absent when the body is empty, or too large to hold in full. */
+    readonly bodyBlocks?: readonly MarkdownBlock[];
+    /** The body was larger than this parser will hold: the page shows it as plain text rather than cut off. */
+    readonly bodyTooLarge?: true;
+}
 /** Read-only extras a connected session can serve beside the review itself. */
 export interface ConnectedOptions {
     /**
@@ -14,10 +26,12 @@ export interface ConnectedOptions {
     readonly analysis?: () => Promise<ConnectedAnalysisView>;
     /**
      * The call-flow page of the analysis of snapshot `snapshotId`, for one changed
-     * file or all of them, for `GET /flow`. Undefined when that snapshot is not
-     * the one analyzed or it has no call flows there.
+     * file or all of them, for `GET /flow`; with `view` "business", the business
+     * view alone (`GET /flow?snapshot=&view=business`), which the page shows under
+     * its goal. Undefined when that snapshot is not the one analyzed or it has
+     * nothing to show there.
      */
-    readonly flow?: (snapshotId: string, file: string | undefined) => Promise<string | undefined>;
+    readonly flow?: (snapshotId: string, file: string | undefined, view: "flow" | "business") => Promise<string | undefined>;
 }
 /** A single ephemeral session; never exposes a general GitHub API proxy. */
 export declare function serveConnected(review?: ConnectedReview, options?: ConnectedOptions): Promise<ConnectedSession>;

package/dist/review/connected.js

@@ -3,6 +3,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { z } from "zod";
 import { ConnectedReview } from "./github.js";
 import { renderConnectedPage } from "./connected-html.js";
+import { markdownBlocks } from "./markdown.js";
 import { reportPolicy } from "./report-pages.js";
 const MAX_BODY = 256 * 1024;
 const loadSchema = z.object({ url: z.string() }).strict();
@@ -12,6 +13,25 @@ const reviewSchema = z.object({
 }).strict();
 const emptySchema = z.object({}).strict();
 const tokenSchema = z.string().regex(/^[a-f0-9]{64}$/);
+function described(state) {
+    const snap = state.snapshot;
+    if (snap === undefined)
+        return state;
+    const body = snap.body;
+    if (body === undefined || body.trim() === "")
+        return state;
+    const parsed = markdownBlocks(body);
+    if (parsed.truncated)
+        return { ...state, snapshot: { ...snap, bodyTooLarge: true } };
+    return { ...state, snapshot: { ...snap, bodyBlocks: parsed.blocks } };
+}
+function withDescription(response) {
+    if ("status" in response)
+        return described(response);
+    if ("state" in response && response.state !== undefined)
+        return { ...response, state: described(response.state) };
+    return response;
+}
 const NO_ANALYSIS = {
     available: false,
     reason: "No local analysis is attached to this session.",
@@ -52,7 +72,7 @@ export async function serveConnected(review = new ConnectedReview(), options = {
         res.setHeader("X-Frame-Options", "DENY");
         res.setHeader("Referrer-Policy", "no-referrer");
         res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${csrf}'; style-src 'nonce-${csrf}'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`);
-        const json = (code, value) => { res.writeHead(code, { "Content-Type": "application/json" }); res.end(JSON.stringify(value)); };
+        const json = (code, value) => { res.writeHead(code, { "Content-Type": "application/json" }); res.end(JSON.stringify(withDescription(value))); };
         if (!requestIsTrusted(req, origin)) {
             json(403, { error: "Untrusted Host or Origin." });
             return;
@@ -79,9 +99,10 @@ export async function serveConnected(review = new ConnectedReview(), options = {
             const query = new URL(req.url ?? "", origin).searchParams;
             const snapshotId = query.get("snapshot") ?? "";
             const file = query.get("file") ?? undefined;
+            const view = query.get("view") === "business" ? "business" : "flow";
             let html;
             try {
-                html = options.flow === undefined ? undefined : await options.flow(snapshotId, file);
+                html = options.flow === undefined ? undefined : await options.flow(snapshotId, file, view);
             }
             catch {
                 html = undefined;