@popcorn245/cornfield 0.7.0 → 0.8.0

package/README.md

@@ -42,6 +42,7 @@ ssh -L 3350:127.0.0.1:3350 you@the-machine
 - **Derived, not drawn by hand.** `cornfield sync` runs the derivers named in your config and merges what they find into `topology.json`; hand-written parts (descriptions, flows, anything of a type no deriver owns) are kept. `cornfield validate` fails on drift, so CI keeps the map honest.
 - **Proposals.** `docs/specs/proposals/NNNN-slug.json` says what a change would add, change and remove, with scenarios. cornfield lists them from your checkout, from every git worktree in the configured worktrees folder and, with sign-in, from your open spec PRs, and shows Before / Diff / After, the scenario player, what-if edits, and Approve / Send back. Writing, reviewing and landing one in your repo: [docs/proposals.md](docs/proposals.md). The format and its validator: [core/proposal.js](core/proposal.js).
 - **Issues and pull requests.** With a forge in the config and sign-in, a panel of its pull requests and issues (GitHub; Forgejo behind the same interface), with filters. Select a pull request and the nodes its files are light up on the map, and a failing check lights the tests it names. A Deploys list reads the forge's workflow runs and lights what a selected deploy restarted, from a mapping in the config ([docs/deploys.md](docs/deploys.md)). A maintainer can land a green pull request, re-run a failed check, start a spec on an issue and open the build issue of an approved spec, each one button with a confirm step. A bottom sheet on a phone. A **Release notes** tab drafts the notes from the pull requests merged since the last tag, grouped by what they changed on the map, to copy or to post as a draft release (never published); `cornfield notes` prints the same Markdown. [docs/issues-and-prs.md](docs/issues-and-prs.md).
+- **Threads.** The panel's Threads tab shows ideas (issues labelled `idea`) and spec PRs' conversations from the forge, read-only, and lights the nodes they mention with `[[node-id]]` or `[[repo/path]]`; a node's panel lists the threads that mention it. "New idea" opens an issue as you. Hooks tell outside code when a thread opens, gets a comment or is linked to the map. Nothing is kept in cornfield. [docs/threads.md](docs/threads.md).
 - **Agents, tracked.** The panel's Agents tab groups branches, spec PRs and PRs by the issue and the proposal they belong to, and marks the work agents made (by author, bot account, label or branch prefix, set in the config). Nothing is launched. [docs/agents.md](docs/agents.md).
 - **Personas, not people.** `topology.personas.json` holds archetypes (Admin, Member, Guest); scenarios act as them, never as a real person.
 - **The cloud you do not control.** `topology.cloud.json` describes the outside services; the cloud deriver's detectors (hosts in code, Dockerfiles, container images, CI workflows, a Caddyfile) keep it complete in both directions. "Cloudflare is down" plays as an outage: what breaks now, at the next deploy, at the next certificate renewal. [docs/cloud.md](docs/cloud.md).

package/core/config.js

@@ -23,7 +23,8 @@
  *     personas: { roles: null },              // the roles a persona may have (null: any)
  *     releaseNotes: { breakingLabel: 'breaking' },   // the pull request label that lists a change under "Breaking" in the release notes
  *     hooks: [],                              // [{ url, events }]: signed JSON events posted to outside code (docs/config.md#hooks); the secret is env only
- *     hookPoll: { specs: '5m' },              // how often cornfield looks for ready specs on its own, for the spec.ready hook; false turns it off (docs/config.md#hook-poll)
+ *     hookPoll: { specs: '5m' },              // how often cornfield looks for ready specs and thread activity on its own, for the spec.ready and thread.* hooks; false turns it off (docs/config.md#hook-poll)
+ *     threads: { label: 'idea' },             // an idea is an issue with this label, its thread the issue's comments; false turns threads off (docs/threads.md)
  *     links: [],                              // [{ label, href }] shown in the explorer's header
  *     proxy: {},                              // { '/api/': 'http://127.0.0.1:3245' }: same-origin paths for a live source
  *     importMap: {},                          // bare imports a repo-local browser module needs: { name: '/repo/path.js' }
@@ -66,7 +67,12 @@ export const FORGE_TYPES = ['github', 'forgejo'];
 /** How a pull request cornfield lands is merged (`forge.mergeMethod`): the way the repo lands its pull requests */
 export const MERGE_METHODS = ['merge', 'squash', 'rebase'];
 /** The events a hook may ask for (`hooks[].events`), and what each one means: docs/config.md#hooks */
-export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring']);
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring', 'thread.opened', 'thread.message', 'thread.linked']);
+/** The events that come from looking at threads (server/threads.js): a poll that wants any of them looks at threads too */
+export const THREAD_EVENTS = Object.freeze(['thread.opened', 'thread.message', 'thread.linked']);
+/** The keys of `threads` when it is an object, and the label's longest length */
+export const THREADS_KEYS = Object.freeze(['label']);
+export const MAX_LABEL = 50;
 /** The most hooks a config lists */
 export const MAX_HOOKS = 20;
 /** The bounds of `hookPoll.specs` in milliseconds: not under a minute (the forge is not hammered), not over an hour */
@@ -85,14 +91,26 @@ export function parseDuration(v) {
   return m ? Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000 }[m[2]] : null;
 }
 
+/** Whether some hook subscribes to any of `events` (by name, or with '*') */
+export function hookWants(config, events) {
+  return Array.isArray(config.hooks) && config.hooks.some((h) => h.events === '*' || (Array.isArray(h.events) && h.events.some((e) => events.includes(e))));
+}
+
+/** Whether threads are on: `threads: false` turns them off, anything else (the default included) leaves them on */
+export const threadsOn = (config) => config.threads !== false;
+
+/** The label that makes an issue an idea, or null when threads are off */
+export const ideaLabel = (config) => (threadsOn(config) ? (config.threads && config.threads.label) || DEFAULTS.threads.label : null);
+
 /**
- * How often cornfield looks at the open spec PRs by itself, in milliseconds, or null when it does not: when `hookPoll.specs`
- * is false, or no hook subscribes to `spec.ready` (by name or with '*').
- * @param {{ hooks?: { events: string[] | '*' }[], hookPoll?: { specs?: string | false } | false }} config a loaded config
+ * How often cornfield looks by itself, in milliseconds, or null when it does not: when `hookPoll.specs` is false, or no
+ * hook subscribes to something the look finds (`spec.ready`, or a `thread.*` event while threads are on), by name or with '*'.
+ * One look covers both: the open spec PRs and the threads (server/spec-poll.js).
+ * @param {{ hooks?: { events: string[] | '*' }[], hookPoll?: { specs?: string | false } | false, threads?: false | { label?: string } }} config a loaded config
  * @returns {number | null}
  */
 export function specPollMs(config) {
-  const wanted = Array.isArray(config.hooks) && config.hooks.some((h) => h.events === '*' || (Array.isArray(h.events) && h.events.includes('spec.ready')));
+  const wanted = hookWants(config, ['spec.ready']) || (threadsOn(config) && hookWants(config, THREAD_EVENTS));
   const every = config.hookPoll === false ? false : config.hookPoll ? config.hookPoll.specs : DEFAULTS.hookPoll.specs;
   return wanted && every !== false ? parseDuration(every ?? DEFAULTS.hookPoll.specs) : null;
 }
@@ -115,6 +133,7 @@ export const DEFAULTS = Object.freeze({
   agents: { authors: [], labels: [], branchPrefixes: [], bots: true },
   hooks: [],
   hookPoll: { specs: '5m' },
+  threads: { label: 'idea' },
   links: [],
   proxy: {},
   importMap: {},
@@ -241,6 +260,14 @@ export function configProblems(c) {
       }
     }
   }
+  if (c.threads !== undefined && c.threads !== false) {
+    if (!isObject(c.threads)) out.push('"threads" is { label: "idea" }, or false to turn threads off.');
+    else {
+      for (const k of Object.keys(c.threads)) if (!THREADS_KEYS.includes(k)) out.push(`threads.${k}: the key is ${THREADS_KEYS.join(', ')}.`);
+      const l = c.threads.label;
+      if (l !== undefined && (!isText(l) || l.includes(',') || l.trim() !== l || l.length > MAX_LABEL)) out.push(`threads.label is the name of the label that makes an issue an idea, like "idea": text of at most ${MAX_LABEL} characters, no comma, no space at either end.`);
+    }
+  }
   if (c.releaseNotes !== undefined) {
     if (!isObject(c.releaseNotes)) out.push('"releaseNotes" is { breakingLabel }.');
     else if (c.releaseNotes.breakingLabel !== undefined && (!isText(c.releaseNotes.breakingLabel) || c.releaseNotes.breakingLabel.includes(','))) out.push('releaseNotes.breakingLabel is a label\'s name, like "breaking".');
@@ -323,7 +350,7 @@ export async function loadConfig(root, { env = process.env, file } = {}) {
     if (problems.length) throw new Error(`${path.relative(absRoot, configFile) || CONFIG_FILE}:\n  ${problems.join('\n  ')}`);
   }
   const config = {
-    ...structuredClone({ ...DEFAULTS, sources: { ...DEFAULTS.sources }, personas: { ...DEFAULTS.personas }, cloud: { ...DEFAULTS.cloud }, agents: { ...DEFAULTS.agents }, releaseNotes: { ...DEFAULTS.releaseNotes } }),
+    ...structuredClone({ ...DEFAULTS, sources: { ...DEFAULTS.sources }, personas: { ...DEFAULTS.personas }, cloud: { ...DEFAULTS.cloud }, agents: { ...DEFAULTS.agents }, releaseNotes: { ...DEFAULTS.releaseNotes }, threads: { ...DEFAULTS.threads } }),
     ...raw,
     sources: { ...DEFAULTS.sources, ...(raw.sources || {}) },
     personas: { ...DEFAULTS.personas, ...(raw.personas || {}) },
@@ -332,6 +359,8 @@ export async function loadConfig(root, { env = process.env, file } = {}) {
     deploys: { ...DEFAULTS.deploys, ...(raw.deploys || {}) },
     agents: { ...DEFAULTS.agents, ...(raw.agents || {}) },
   };
+  // `threads: false` stays false; an object is read over the default
+  config.threads = raw.threads === false ? false : { ...DEFAULTS.threads, ...(raw.threads || {}) };
   // `hookPoll: false` is `{ specs: false }`; an object is read over the default
   config.hookPoll = raw.hookPoll === false ? { specs: false } : { ...DEFAULTS.hookPoll, ...(raw.hookPoll || {}) };
   // `proposals` is the folder to everything downstream, whichever way the file wrote it; the options are read from `approveLands`

package/core/mentions.js

@@ -0,0 +1,239 @@
+/**
+ * @module core/mentions
+ *
+ * How a thread points at the map (spec 0005, D7). Pure: no I/O, no DOM, no Node built-ins, so the server (a hook's
+ * payload) and the explorer (the lights, a node's "Mentioned in") load the same file.
+ *
+ *   - **Mentions.** People write `[[core-server-auth]]` (a node's id) or `[[server/auth.js]]` (a repo path) in prose.
+ *     `parseMentions` reads them outside code: a fenced block and an inline code span are text about code, not links.
+ *   - **A block.** Tools and agents may write a fenced block for precise links:
+ *
+ *         ```cornfield-thread
+ *         { "nodes": ["core-server-auth", "server/hooks.js"], "proposal": "0013-meals" }
+ *         ```
+ *
+ *     `nodes` are read like mentions (an id or a path); `proposal` is a proposal's slug. A block that is not that shape
+ *     is ignored, and prose is read as before.
+ *   - **Resolving.** `resolveMention` answers a reference in this order: a node's id; a node whose `file` is exactly
+ *     that path; the node(s) that own the path (the deepest `file` that is the path or a folder above it, as a file
+ *     lights its node for a pull request, `nodesForFile`). A reference that is none of these resolves to nothing and
+ *     stays plain text, which reads sensibly on the forge without cornfield.
+ *   - **Caps.** At most `MAX_MENTIONS` distinct references are read from one text, and a reference is at most
+ *     `MAX_REF` characters, so a comment cannot make the map light up everything or cost a lot to read.
+ *   - **Links.** `threadOfPull` reads the thread a spec PR names: `Thread: #n` or `Closes #n` (also Fixes and Resolves).
+ */
+
+/** The most distinct references read from one text, and the longest one */
+export const MAX_MENTIONS = 50;
+export const MAX_REF = 200;
+/** The most a `cornfield-thread` block may name */
+export const MAX_BLOCK_NODES = 50;
+/** The fence's info string that marks a block of links */
+export const THREAD_BLOCK = 'cornfield-thread';
+
+const SLUG = /^[a-z0-9][a-z0-9._-]{0,99}$/i;
+
+const clean = (p) => String(p).replace(/^\.\//, '').replace(/\/+$/, '');
+
+/**
+ * The node(s) whose `file` holds a path: the node's `file` is the path itself or a folder above it, and the deepest
+ * (longest) `file` wins. A file that holds several nodes (a page and what renders it) lights all of them. (The explorer's
+ * forge panel lights a pull request's files with this same rule.)
+ * @param {string} path a repo-relative path
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {object[]} the nodes, [] when none holds it
+ */
+export function nodesForFile(path, nodes) {
+  const p = clean(path);
+  let best = -1;
+  let out = [];
+  for (const node of nodes) {
+    if (typeof node.file !== 'string' || node.file === '') continue;
+    const file = clean(node.file);
+    if (p !== file && !p.startsWith(`${file}/`)) continue;
+    if (file.length > best) { best = file.length; out = [node]; } else if (file.length === best) out.push(node);
+  }
+  return out;
+}
+
+/**
+ * Splits text into prose and code: `prose` is the text with every fenced block and inline code span blanked (same length,
+ * so offsets hold), `fences` are the fenced blocks as `{ info, body }`.
+ * @param {string} text
+ * @returns {{ prose: string, fences: { info: string, body: string }[] }}
+ */
+export function scan(text) {
+  const src = String(text ?? '');
+  const lines = src.split('\n');
+  const fences = [];
+  const out = [];
+  let open = null; // { char, len, info, body: [] }
+  for (const line of lines) {
+    if (open) {
+      const close = new RegExp(`^ {0,3}${open.char}{${open.len},}[ \\t]*\\r?$`).test(line);
+      if (close) { fences.push({ info: open.info, body: open.body.join('\n') }); open = null; } else open.body.push(line.replace(/\r$/, ''));
+      out.push(' '.repeat(line.length));
+      continue;
+    }
+    const m = /^ {0,3}(`{3,}|~{3,})[ \t]*([^\r]*)$/.exec(line);
+    // An info string of a backtick fence cannot hold a backtick (then it is an inline span, not a fence)
+    if (m && !(m[1][0] === '`' && m[2].includes('`'))) {
+      open = { char: m[1][0], len: m[1].length, info: m[2].trim(), body: [] };
+      out.push(' '.repeat(line.length));
+      continue;
+    }
+    out.push(line);
+  }
+  // A fence left open runs to the end of the text, as the forge's Markdown reads it
+  if (open) fences.push({ info: open.info, body: open.body.join('\n') });
+  return { prose: blankSpans(out.join('\n')), fences };
+}
+
+/** Inline code spans blanked: a run of backticks closes at the next run of the same length */
+function blankSpans(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] !== '`') { out += text[i++]; continue; }
+    let n = 0;
+    while (text[i + n] === '`') n++;
+    let j = i + n;
+    let end = -1;
+    while (j < text.length) {
+      if (text[j] !== '`') { j++; continue; }
+      let m = 0;
+      while (text[j + m] === '`') m++;
+      if (m === n) { end = j + m; break; }
+      j += m;
+    }
+    if (end === -1) { out += text.slice(i, i + n); i += n; continue; }
+    out += text.slice(i, end).replace(/[^\n]/g, ' ');
+    i = end;
+  }
+  return out;
+}
+
+/** A reference as written, made comparable: no `./`, no trailing slash, no `#L10` or `:10` line suffix; or null when it is not one */
+export function normalizeRef(raw) {
+  let ref = String(raw ?? '').trim();
+  if (ref === '' || ref.length > MAX_REF || /[\0\n\r]/.test(ref)) return null;
+  ref = ref.replace(/#.*$/, '').replace(/:\d+(?:-\d+)?$/, '');
+  ref = clean(ref).trim();
+  if (ref === '' || ref.startsWith('/') || ref.split('/').some((p) => p === '..' || p === '.')) return null;
+  return ref;
+}
+
+/**
+ * The `cornfield-thread` block of a text, or null: the first well-formed one wins.
+ * @param {{ info: string, body: string }[]} fences
+ * @returns {{ nodes: string[], proposal: string | null } | null}
+ */
+function blockOf(fences) {
+  for (const f of fences) {
+    if (f.info.split(/\s+/)[0] !== THREAD_BLOCK) continue;
+    let json;
+    try { json = JSON.parse(f.body); } catch { continue; }
+    if (json === null || typeof json !== 'object' || Array.isArray(json)) continue;
+    const nodes = Array.isArray(json.nodes) ? json.nodes.map((n) => (typeof n === 'string' ? normalizeRef(n) : null)).filter((r) => r !== null).slice(0, MAX_BLOCK_NODES) : [];
+    const proposal = typeof json.proposal === 'string' && SLUG.test(json.proposal) ? json.proposal : null;
+    if (!nodes.length && !proposal) continue;
+    return { nodes: [...new Set(nodes)], proposal };
+  }
+  return null;
+}
+
+/**
+ * What a text points at, before the map is asked: the `[[…]]` references outside code (each once, in order, at most
+ * `MAX_MENTIONS`), and the `cornfield-thread` block when there is one.
+ * @param {string} text
+ * @returns {{ refs: string[], block: { nodes: string[], proposal: string | null } | null, truncated: boolean }}
+ */
+export function parseMentions(text) {
+  const { prose, fences } = scan(text);
+  const refs = [];
+  let truncated = false;
+  for (const m of prose.matchAll(/(?<!\\)\[\[([^[\]\n]{1,400})\]\]/g)) {
+    const ref = normalizeRef(m[1]);
+    if (ref === null || refs.includes(ref)) continue;
+    if (refs.length >= MAX_MENTIONS) { truncated = true; break; }
+    refs.push(ref);
+  }
+  return { refs, block: blockOf(fences), truncated };
+}
+
+/**
+ * The nodes one reference stands for, in order of how sure it is: the id; else nodes whose `file` is exactly the path;
+ * else the nodes that own the path.
+ * @param {string} ref
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {object[]}
+ */
+export function resolveMention(ref, nodes) {
+  const r = normalizeRef(ref);
+  if (r === null) return [];
+  const byId = nodes.filter((n) => n.id === r);
+  if (byId.length) return byId;
+  const exact = nodes.filter((n) => typeof n.file === 'string' && n.file !== '' && clean(n.file) === r);
+  if (exact.length) return exact;
+  return nodesForFile(r, nodes);
+}
+
+/**
+ * References resolved against a map.
+ * @param {string[]} refs references as `parseMentions` gives them (or a block's `nodes`)
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {{ resolved: { ref: string, ids: string[] }[], ids: string[], unresolved: string[] }} `ids`: every node once, in
+ *   order; `unresolved`: the references that are on no node (they stay text)
+ */
+export function resolveMentions(refs, nodes) {
+  const resolved = [];
+  const unresolved = [];
+  const seen = new Set();
+  const list = Array.isArray(refs) ? refs.slice(0, MAX_MENTIONS + MAX_BLOCK_NODES) : [];
+  for (const ref of list) {
+    const found = resolveMention(ref, nodes);
+    if (!found.length) { unresolved.push(ref); continue; }
+    const ids = found.map((n) => n.id);
+    resolved.push({ ref, ids });
+    for (const id of ids) seen.add(id);
+  }
+  return { resolved, ids: [...seen], unresolved };
+}
+
+/**
+ * Everything a set of texts (a thread's messages) points at, before the map is asked: the references of every text and of
+ * its blocks, each once, and the proposal a block names (the first).
+ * @param {string[]} texts
+ * @returns {{ refs: string[], proposal: string | null, truncated: boolean }}
+ */
+export function linksOf(texts) {
+  const refs = [];
+  let proposal = null;
+  let truncated = false;
+  const cap = MAX_MENTIONS * 2;
+  for (const text of texts) {
+    const got = parseMentions(text);
+    truncated ||= got.truncated;
+    for (const ref of [...got.refs, ...(got.block ? got.block.nodes : [])]) {
+      if (refs.includes(ref)) continue;
+      if (refs.length >= cap) { truncated = true; break; }
+      refs.push(ref);
+    }
+    if (proposal === null && got.block && got.block.proposal) proposal = got.block.proposal;
+  }
+  return { refs, proposal, truncated };
+}
+
+/**
+ * The thread a spec PR's text names: `Thread: #n`, or `Closes #n` (also Fixes and Resolves, and their other tenses), outside
+ * code. The first one named. An issue in another repo (`owner/name#n`) is not this repo's thread.
+ * @param {string} body
+ * @returns {number | null}
+ */
+export function threadOfPull(body) {
+  const { prose } = scan(body);
+  // `(?:\s*:)?\s+` and not `\s*:?\s+`: two whitespace runs side by side backtrack against each other, which made a long
+  // run of spaces after "Closes" (or a code block, blanked to spaces) quadratic; this way each run is read once
+  const m = /(?:^|[\s(])(?:thread\s*:|(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)(?:\s*:)?)\s+#([1-9]\d{0,8})\b/i.exec(prose);
+  return m ? Number(m[1]) : null;
+}

package/explorer/explorer.css

@@ -913,3 +913,12 @@ a.hx-forge-row:hover, button.hx-forge-row:hover { background: var(--hx-control-h
 :root[data-theme="light"] .hx-forge-tab[aria-pressed="true"] { box-shadow: 0 1px 3px rgba(15, 23, 42, 0.25); }
 :root[data-theme="light"] .hx-forge { box-shadow: 10px 0 30px -12px rgba(15, 23, 42, 0.18); }
 :root[data-theme="light"] .hx-forge:not(.forge-open) { box-shadow: none; }
+
+/* Threads (forge-panel.js, docs/threads.md): messages as written, read-only; a node's "Mentioned in" opens one */
+.hx-thread-msgs { display: flex; flex-direction: column; gap: 8px; margin: 0; padding: 0; list-style: none; }
+.hx-thread-msg { display: flex; flex-direction: column; gap: 4px; padding: 8px 10px; border: 1px solid var(--hx-line); border-radius: 10px; background: var(--hx-control); }
+.hx-thread-body { margin: 0; color: var(--hx-ink); line-height: 1.5; white-space: pre-wrap; overflow-wrap: anywhere; user-select: text; }
+.hx-thread-nodes { padding-left: 0; }
+.hx-thread-compose { font-family: inherit; min-height: 8em; }
+.hx-thread-open { display: block; max-width: 100%; text-align: left; overflow-wrap: anywhere; }
+#forge-idea[hidden], #idea-form[hidden], #idea-message[hidden] { display: none; }

package/explorer/forge-panel-model.js

@@ -24,17 +24,21 @@
  *                             where a step's plan is read, what the confirm step shows of it, what is sent to confirm it, and what is said of one that is made already
  *   landingUrl, cancelLandingUrl, landingWords
  *                             a spec pull request waiting to land on its approval (`proposals.approveLands`, server/lander.js): where it is read, where it is cancelled, and the words
+ *   threadsUrl, threadUrl, IDEAS_URL, threadKindWords, threadMeta, litForThread, mentionsIndex, mentionsOf, messageNodes, ideaRequest, ideaWords
+ *                             the Threads tab (docs/threads.md): what to ask, a thread's words, which nodes its text lights and which threads mention a node
  *   notesUrl, sinceChoices, notesSummary, validTag, confirmWords, postedWords, draftRequest
  *                             the Release notes view: what to ask, the tags to start from, and the words around a draft
  */
 
 import { relativeTime } from './review-model.js';
+import { nodesForFile, linksOf, parseMentions, resolveMentions } from '../core/mentions.js';
 
-export const KINDS = Object.freeze(['pulls', 'issues', 'deploys', 'notes']);
+export const KINDS = Object.freeze(['pulls', 'issues', 'threads', 'deploys', 'notes']);
 /** The states a list offers: [value, label]; a pull request that landed is "merged", one closed without landing "closed" */
 export const STATES = Object.freeze({
   pulls: [['open', 'Open'], ['merged', 'Merged'], ['closed', 'Closed'], ['all', 'All']],
   issues: [['open', 'Open'], ['closed', 'Closed'], ['all', 'All']],
+  threads: [['open', 'Open'], ['closed', 'Closed'], ['all', 'All']],
   deploys: [['all', 'All'], ['success', 'Succeeded'], ['failure', 'Failed'], ['running', 'Running or waiting'], ['other', 'Cancelled or skipped']],
 });
 /** How many a list asks for (the server's own default; its most is 300) */
@@ -50,9 +54,13 @@ export const defaultFilters = (kind = 'pulls') => ({ state: kind === 'deploys' ?
 export const serverState = (state) => (state === 'merged' ? 'closed' : state);
 
 /** The address of a list */
-export const listUrl = (kind, state) => (kind === 'deploys' ? `/api/forge/deploys?limit=${LIST_LIMIT}` : `/api/forge/${kind}?state=${serverState(state)}&limit=${LIST_LIMIT}`);
+export const listUrl = (kind, state) => (kind === 'deploys' ? `/api/forge/deploys?limit=${LIST_LIMIT}` : kind === 'threads' ? threadsUrl(state) : `/api/forge/${kind}?state=${serverState(state)}&limit=${LIST_LIMIT}`);
 /** What a list is kept under: a deploys list is filtered by state here, so every state is one list */
 export const listKeyOf = (kind, state) => (kind === 'deploys' ? 'deploys' : `${kind}|${serverState(state)}`);
+/** The address of the threads list for a state, of one thread, and where a new idea is posted */
+export const threadsUrl = (state) => `/api/forge/threads?state=${state}&limit=${LIST_LIMIT}`;
+export const threadUrl = (n) => `/api/forge/threads/${n}`;
+export const IDEAS_URL = '/api/forge/threads';
 /** The address of one pull request with its files and checks */
 export const pullUrl = (n) => `/api/forge/pulls/${n}`;
 
@@ -152,25 +160,8 @@ export function checksWords(checks) {
 
 const clean = (p) => String(p).replace(/^\.\//, '').replace(/\/+$/, '');
 
-/**
- * The node(s) whose `file` holds a path: the node's `file` is the path itself or a folder above it, and the deepest
- * (longest) `file` wins. A file that holds several nodes (a page and what renders it) lights all of them.
- * @param {string} path a repo-relative path
- * @param {{ id: string, file?: string }[]} nodes
- * @returns {object[]} the nodes, [] when none holds it
- */
-export function nodesForFile(path, nodes) {
-  const p = clean(path);
-  let best = -1;
-  let out = [];
-  for (const node of nodes) {
-    if (typeof node.file !== 'string' || node.file === '') continue;
-    const file = clean(node.file);
-    if (p !== file && !p.startsWith(`${file}/`)) continue;
-    if (file.length > best) { best = file.length; out = [node]; } else if (file.length === best) out.push(node);
-  }
-  return out;
-}
+// The map's rule for a file's node(s) is core/mentions.js's too (a thread's [[server/auth.js]] resolves the same way)
+export { nodesForFile };
 
 const TEST_PATH = /(?:^|\/)(?:tests?|__tests__|spec|specs)\/|\.(?:test|spec)\.[a-z]+$|_test\.[a-z]+$|(?:^|\/)test_[^/]+\.py$/i;
 /** Whether a path looks like a test file */
@@ -279,6 +270,82 @@ export function litForDeploy(deploy, nodes) {
     : { nodes: hit, missing, changed: ids, failing: new Set() };
 }
 
+// ---------------------------------------------------------------------------
+//  Threads: a conversation on the forge that points at the map (core/mentions.js)
+// ---------------------------------------------------------------------------
+
+/** "Idea", or "Proposal 0040-meals" for a spec PR's conversation */
+export const threadKindWords = (t) => (t.kind === 'proposal' ? `Proposal${t.slugs && t.slugs.length ? ` ${t.slugs.join(', ')}` : ''}` : 'Idea');
+
+/** "#41 · maintainer-one · 3 comments · 2 days ago" (the time of the last message) */
+export function threadMeta(t, nowMs) {
+  const count = t.kind === 'proposal' && !t.comments ? 'no comments' : `${t.comments} ${t.comments === 1 ? 'comment' : 'comments'}`;
+  return [`#${t.number}`, t.author ? t.author.login : 'someone', count, relativeTime(t.updatedAt, nowMs)].filter(Boolean).join(' · ');
+}
+
+/**
+ * The nodes the references in some texts stand for, against the map now on screen. `refs` are as the server gives them (or
+ * as `linksOf` finds them); what is on no node stays text.
+ * @param {string[]} refs
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {{ ids: string[], nodes: object[], unresolved: string[], resolved: { ref: string, ids: string[] }[] }}
+ */
+export function mentionsOf(refs, nodes) {
+  const got = resolveMentions(refs, nodes);
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  return { ...got, nodes: got.ids.map((id) => byId.get(id)).filter(Boolean) };
+}
+
+/**
+ * What an open thread lights: the nodes its messages mention, as a pull request's files light theirs (amber, the rest
+ * faded). `messages` carry `body`; each message also says which nodes are its own (for the chips under it).
+ * @param {{ messages: { id: string, body: string }[] }} thread
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {{ nodes: object[], unresolved: string[], changed: Set<string>, failing: Set<string>, perMessage: Map<string, { nodes: object[], unresolved: string[] }> }}
+ */
+export function litForThread(thread, nodes) {
+  const all = linksOf(thread.messages.map((m) => m.body));
+  const got = mentionsOf(all.refs, nodes);
+  const perMessage = new Map();
+  for (const m of thread.messages) perMessage.set(m.id, messageNodes(m.body, nodes));
+  return { nodes: got.nodes, unresolved: got.unresolved, changed: new Set(got.ids), failing: new Set(), perMessage };
+}
+
+/** The nodes one message mentions (its `[[…]]` and its `cornfield-thread` block), and the references that are on none */
+export function messageNodes(body, nodes) {
+  const got = parseMentions(body);
+  const found = mentionsOf([...got.refs, ...(got.block ? got.block.nodes : [])], nodes);
+  return { nodes: found.nodes, unresolved: found.unresolved };
+}
+
+/**
+ * Which threads mention which nodes, from the list the server gave (each thread's references as written), against the map
+ * on screen.
+ * @param {{ number: number, refs: string[] }[]} items
+ * @param {{ id: string, file?: string }[]} nodes
+ * @returns {Map<string, object[]>} node id -> the threads, in the order of `items`
+ */
+export function mentionsIndex(items, nodes) {
+  const index = new Map();
+  for (const t of items) {
+    for (const id of resolveMentions(t.refs || [], nodes).ids) index.set(id, [...(index.get(id) || []), t]);
+  }
+  return index;
+}
+
+/** A new idea's request body: the title and the text, trimmed, or null when there is no title */
+export function ideaRequest(title, body) {
+  const t = String(title ?? '').trim();
+  return t ? { title: t, body: String(body ?? '').trim() } : null;
+}
+
+/** What a new idea came to, in words */
+export function ideaWords(forgeName, res) {
+  if (res.ok) return `Opened idea #${res.body.number} on ${forgeName}. It shows in the list within a minute.`;
+  if (res.status === 401) return 'Your sign-in has ended. Sign in again to open an idea.';
+  return errorWords(res.status, res.body);
+}
+
 // ---------------------------------------------------------------------------
 //  The picture
 // ---------------------------------------------------------------------------