References, out of three general primitives

client/app.css

@@ -749,6 +749,54 @@ body.suggesting .tiptap { caret-color: transparent; cursor: default; }
 .card.thread .head .resolve-btn { color: var(--accent); }
 
 
+/* --- collapsible headings ---------------------------------------------------
+   The arrow lives in the sheet's left margin so it never moves the text, and
+   stays invisible until the pointer is in the document (or the section is shut,
+   which has to be legible at a glance). Folding is a local view state: what you
+   collapse is collapsed for you only. */
+.tiptap .cw-heading { position: relative; }
+.fold-arrow {
+  position: absolute; left: -1.35em; top: 0.1em; width: 1.05em; height: 1.05em; padding: 0;
+  display: inline-flex; align-items: center; justify-content: center;
+  border: none; background: none; color: var(--doc-text-3); cursor: pointer;
+  opacity: 0; transition: opacity .12s, transform .12s; user-select: none;
+  touch-action: manipulation;
+}
+.fold-arrow .icon { width: 1em; height: 1em; stroke-width: 2; }
+.tiptap:hover .fold-arrow, .fold-arrow:focus-visible { opacity: 0.55; }
+.fold-arrow:hover { opacity: 1 !important; color: var(--doc-text); }
+.fold-arrow.collapsed { opacity: 0.75; transform: rotate(-90deg); }
+.tiptap .cw-hidden-by-fold { display: none; }
+/* a shut section says so, so a short page and a folded one are not confused */
+.tiptap .cw-heading.cw-folded::after {
+  content: '···'; margin-left: 0.5em; font-size: 0.7em; letter-spacing: 0.15em;
+  color: var(--doc-text-3); vertical-align: 0.15em;
+}
+/* arriving from a #anchor link: a brief wash, then out of the way */
+@keyframes cw-jump-fade { from { background: var(--hl-active); } to { background: transparent; } }
+.tiptap .cw-jumped { animation: cw-jump-fade 1.4s ease-out; border-radius: 3px; }
+@media (prefers-reduced-motion: reduce) { .tiptap .cw-jumped { animation: none; } }
+/* on a touch screen there is no hover to reveal them by */
+@media (hover: none) { .fold-arrow { opacity: 0.5; } }
+
+/* --- link preview ------------------------------------------------------------
+   What is on the other end of an internal link: the section's heading, its
+   source and the start of its summary. */
+#link-preview {
+  position: fixed; z-index: 80; width: min(360px, calc(100vw - 16px));
+  background: var(--surface); border: 1px solid var(--border); border-radius: 10px;
+  box-shadow: var(--shadow-md); padding: 11px 13px; pointer-events: none;
+  font-family: var(--ui);
+}
+#link-preview.hidden { display: none; }
+#link-preview .lp-title { font-weight: 600; font-size: 13.5px; line-height: 1.35; color: var(--text); }
+#link-preview .lp-url { font-size: 11.5px; color: var(--accent); margin-top: 2px; word-break: break-all; }
+#link-preview .lp-summary { font-size: 12.5px; color: var(--text-2); margin-top: 6px; line-height: 1.45; }
+#link-preview .lp-page {
+  font-size: 11px; color: var(--text-3); margin-top: 8px; padding-top: 6px;
+  border-top: 1px solid var(--border); text-transform: uppercase; letter-spacing: 0.05em;
+}
+
 /* --- page-link autocomplete + links --- */
 #pagelink-menu { position: fixed; z-index: 70; }
 .tiptap a { cursor: pointer; }

client/src/doc.js

@@ -200,6 +200,8 @@ import { Plugin, PluginKey, TextSelection } from '@tiptap/pm/state'
 import { Decoration, DecorationSet } from '@tiptap/pm/view'
 import { initAuth, api, el, esc, icon, colorFor, timeAgo, statusLabel, renderMentionText, agentKeyBox, wireTheme, wireDocStyle } from './common.js'
 import { wordDiff, arrayDiff, styledWordDiff, markKeyOf } from './diff.js'
+import { HeadingFold, outlineOf, resetFolds, unfold } from './fold.js'
+import { markdownSections, parseInternalLink } from './outline.js'
 
 const docId = location.pathname.split('/').filter(Boolean)[1]
 // current page — mutable: switching pages swaps the document client-side
@@ -293,11 +295,23 @@ async function main() {
   // back/forward navigates between pages client-side
   window.addEventListener('popstate', () => {
     const slug = location.pathname.split('/').filter(Boolean)[2] || 'home'
-    if (slug !== pageSlug) openPage(slug, { push: false })
+    const anchor = decodeURIComponent(location.hash.replace(/^#/, '')) || null
+    if (slug !== pageSlug) openPage(slug, { push: false, anchor })
+    else if (anchor) revealSection(anchor)
   })
 
+  // a hash arriving any other way (pasted, edited in the bar, an in-page anchor)
+  window.addEventListener('hashchange', () => {
+    const anchor = decodeURIComponent(location.hash.replace(/^#/, ''))
+    if (anchor) revealSection(anchor)
+  })
+
+  wireLinkPreview()
+
   loadStructure() // in flight while the document syncs, not after it
   await initPage()
+  // a link into a section, pasted or followed from outside, lands on the section
+  if (location.hash) revealSection(decodeURIComponent(location.hash.slice(1)))
 
   setInterval(loadStructure, 15000)
   window.addEventListener('focus', () => loadStructure())
@@ -470,6 +484,7 @@ function teardownPage() {
   state.chainPos = {}
   state.composerAnchors = null
   state.suggestAnchors = null
+  resetFolds() // which sections are shut is a fact about the page you were on
   document.getElementById('composer').classList.add('hidden')
   document.getElementById('suggest-composer').classList.add('hidden')
   document.getElementById('selection-menu').classList.add('hidden')
@@ -477,22 +492,45 @@ function teardownPage() {
 }
 
 // switch pages client-side: swap the document, keep header + sidebar
-async function openPage(slug, { push = true } = {}) {
+async function openPage(slug, { push = true, anchor = null } = {}) {
   closeDrawerOnPhone() // the drawer covers the document it just navigated to
+  const hash = anchor ? `#${anchor}` : ''
   if (slug === pageSlug && !document.getElementById('proposal-view')?.classList.contains('hidden')) {
     // leaving a proposal preview back to the same page
   } else if (slug === pageSlug) {
+    // already here: a link into a section of this page is just a jump
+    if (anchor) {
+      if (push) history.replaceState({}, '', location.pathname + hash)
+      revealSection(anchor)
+    }
     return
   }
   exitProposalPreview()
   teardownPage()
   setPage(slug)
-  if (push) history.pushState({}, '', slug === 'home' ? `/d/${docId}` : `/d/${docId}/${slug}`)
+  if (push) history.pushState({}, '', (slug === 'home' ? `/d/${docId}` : `/d/${docId}/${slug}`) + hash)
   showDocSkeleton({ delay: 180 })
   await initPage()
+  if (anchor) revealSection(anchor)
   loadStructure()
 }
 
+// Jump to a heading by its slug — unfolding it first if it is collapsed, since
+// scrolling to something that is hidden is no answer at all.
+function revealSection(anchor, tries = 0) {
+  if (!anchor) return
+  unfold(anchor)
+  const target = document.querySelector(`.tiptap [data-anchor="${CSS.escape(anchor)}"]`)
+  if (!target) {
+    // the page may still be syncing; a few frames of patience, then give up
+    if (tries < 20) setTimeout(() => revealSection(anchor, tries + 1), 100)
+    return
+  }
+  target.scrollIntoView({ block: 'start', behavior: 'smooth' })
+  target.classList.add('cw-jumped')
+  setTimeout(() => target.classList.remove('cw-jumped'), 1400)
+}
+
 // Is this tab's collaboration socket actually delivering changes? Everything
 // typed or accepted while it is down never reaches the server, so actions that
 // must persist check this first.
@@ -578,6 +616,11 @@ function pageLinkKey(key) {
   return pageLinkController ? pageLinkController(key) : false
 }
 
+// the headings of the page in front of you, in the shape sectionsFor() returns
+function pageOutline(editor) {
+  return outlineOf(editor.state.doc).map(h => ({ slug: h.slug, title: h.node.textContent, summary: '', url: '' }))
+}
+
 function wirePageLinkMenu(editor) {
   document.getElementById('pagelink-menu')?.remove()
   const menu = el('div', { class: 'mention-menu hidden', id: 'pagelink-menu' })
@@ -594,7 +637,8 @@ function wirePageLinkMenu(editor) {
 
   const apply = item => {
     if (!range) return
-    const href = item.slug === 'home' ? `/d/${docId}` : `/d/${docId}/${item.slug}`
+    const path = item.slug === 'home' ? `/d/${docId}` : `/d/${docId}/${item.slug}`
+    const href = item.anchor ? `${path}#${item.anchor}` : path
     editor
       .chain()
       .focus()
@@ -612,7 +656,7 @@ function wirePageLinkMenu(editor) {
       ...items.map((item, i) => {
         const row = el('div', { class: 'mention-item' + (i === sel ? ' selected' : '') })
         row.appendChild(el('span', {}, item.title))
-        row.appendChild(el('span', { class: 'muted', style: 'margin-left:8px;font-size:11px' }, item.slug))
+        row.appendChild(el('span', { class: 'muted', style: 'margin-left:8px;font-size:11px' }, item.anchor ? `#${item.anchor}` : item.slug))
         row.addEventListener('mousedown', e => {
           e.preventDefault()
           apply(item)
@@ -626,10 +670,35 @@ function wirePageLinkMenu(editor) {
     const { state: pmState } = editor
     const { from, empty } = pmState.selection
     if (!empty) return hide()
-    const before = pmState.doc.textBetween(Math.max(0, from - 42), from, '\n', '\n')
-    const m = before.match(/\[\[([^\[\]]{0,32})$/)
+    const before = pmState.doc.textBetween(Math.max(0, from - 80), from, '\n', '\n')
+    const m = before.match(/\[\[([^\[\]]{0,64})$/)
     if (!m) return hide()
     const q = m[1].toLowerCase()
+    // "[[page#" switches to that page's headings — how you cite one entry of a
+    // references page rather than the whole list
+    const deep = q.match(/^(.*?)#(.*)$/)
+    if (deep) {
+      const [, pageQ, headQ] = deep
+      const page = Object.entries(state.pageTitles || {})
+        .map(([slug, title]) => ({ slug, title }))
+        .find(p => p.slug === pageQ || p.title.toLowerCase() === pageQ)
+      if (!page) return hide()
+      // the target page's own headings, unless it IS this page (already in hand)
+      const load = page.slug === pageSlug ? Promise.resolve(pageOutline(editor)) : sectionsFor(page.slug)
+      Promise.resolve(load).then(sections => {
+        if (!range) return
+        items = sections
+          .filter(s => s.slug.includes(headQ) || s.title.toLowerCase().includes(headQ))
+          .slice(0, 8)
+          .map(s => ({ slug: page.slug, title: s.title, anchor: s.slug }))
+        if (!items.length) return hide()
+        sel = Math.min(sel, items.length - 1)
+        render()
+        menu.classList.remove('hidden')
+      })
+      range = { from: from - m[0].length, to: from }
+      return
+    }
     items = Object.entries(state.pageTitles || {})
       .filter(([slug]) => slug !== '_structure' && slug !== pageSlug)
       .map(([slug, title]) => ({ slug, title }))
@@ -672,6 +741,76 @@ function wirePageLinkMenu(editor) {
   }
 }
 
+// --- link previews --------------------------------------------------------------
+// Hovering a link to another page in this project shows what is on the other
+// end: for "…/references#attention-is-all-you-need" that is the section's
+// heading, its source URL and the start of its summary. Nothing here knows what
+// a reference IS — it previews any internal link, and a references page is just
+// the page where that happens to be most useful.
+
+const pageCache = new Map() // slug -> { at, sections: Promise }
+const PREVIEW_TTL = 30000 // a page being edited next door should not stay stale
+
+function sectionsFor(slug) {
+  const hit = pageCache.get(slug)
+  if (hit && Date.now() - hit.at < PREVIEW_TTL) return hit.sections
+  const sections = api(`/api/docs/${docId}${slug === 'home' ? '' : `?page=${slug}`}`)
+    .then(res => markdownSections(res?.markdown || ''))
+    .catch(() => [])
+  pageCache.set(slug, { at: Date.now(), sections })
+  return sections
+}
+
+function wireLinkPreview() {
+  const pop = el('div', { id: 'link-preview', class: 'hidden' })
+  document.body.appendChild(pop)
+  let over = null
+  let timer = null
+
+  const hide = () => {
+    clearTimeout(timer)
+    over = null
+    pop.classList.add('hidden')
+  }
+
+  const show = async (a, target) => {
+    const sections = await sectionsFor(target.slug)
+    if (over !== a) return // the pointer moved on while we were fetching
+    const section = target.anchor ? sections.find(s => s.slug === target.anchor) : sections[0]
+    const title = section?.title || state.pageTitles?.[target.slug] || target.slug
+    const summary = section?.summary || ''
+    if (!title && !summary) return
+    pop.replaceChildren(
+      el('div', { class: 'lp-title' }, title),
+      ...(section?.url ? [el('div', { class: 'lp-url' }, section.url.replace(/^https?:\/\//, ''))] : []),
+      ...(summary ? [el('div', { class: 'lp-summary' }, summary.slice(0, 220) + (summary.length > 220 ? '…' : ''))] : []),
+      el('div', { class: 'lp-page' }, state.pageTitles?.[target.slug] || target.slug)
+    )
+    pop.classList.remove('hidden')
+    // place it under the link, kept inside the window
+    const r = a.getBoundingClientRect()
+    const w = pop.offsetWidth
+    pop.style.left = `${Math.max(8, Math.min(window.innerWidth - w - 8, r.left))}px`
+    const below = r.bottom + 8
+    pop.style.top = `${below + pop.offsetHeight > window.innerHeight - 8 ? Math.max(8, r.top - pop.offsetHeight - 8) : below}px`
+  }
+
+  document.addEventListener('mouseover', e => {
+    const a = e.target?.closest?.('.tiptap a, .proposal-content a, #margin-items a')
+    if (!a) {
+      if (over && !e.target?.closest?.('#link-preview')) hide()
+      return
+    }
+    if (a === over) return
+    const target = parseInternalLink(a.getAttribute('href'), docId)
+    if (!target) return hide()
+    hide()
+    over = a
+    timer = setTimeout(() => show(a, target), 280) // not on every passing pointer
+  })
+  document.addEventListener('scroll', hide, true)
+}
+
 // --- table controls -----------------------------------------------------------
 // A floating bar that appears above the table your cursor is in, with add/remove
 // row & column and delete-table actions (TipTap has no default table UI).
@@ -1254,6 +1393,7 @@ function buildEditor(provider) {
         user: { name: state.me.username, color: colorFor(state.me.username) },
       }),
       Highlights,
+      HeadingFold,
     ],
     editorProps: {
       handleClick: (view, pos, event) => {
@@ -1263,8 +1403,8 @@ function buildEditor(provider) {
         const touch = window.matchMedia('(hover: none)').matches
         if (!a?.getAttribute('href') || !(event.ctrlKey || event.metaKey || touch)) return false
         const url = new URL(a.getAttribute('href'), location.origin)
-        const internal = url.origin === location.origin && url.pathname.match(new RegExp(`^/d/${docId}(?:/([A-Za-z0-9_-]+))?$`))
-        if (internal) openPage(internal[1] || 'home')
+        const internal = parseInternalLink(a.getAttribute('href'), docId)
+        if (internal) openPage(internal.slug, { anchor: internal.anchor })
         else if (url.origin === location.origin) location.href = url.pathname + url.search
         else window.open(url.href, '_blank', 'noopener')
         return true

client/src/fold.js

@@ -0,0 +1,121 @@
+// Collapsible headings.
+//
+// A long page — a references list above all — is only navigable if its sections
+// can be shut. Folding is a VIEW state, not document content: it lives in this
+// module, never in the Yjs doc, so collapsing a section on your screen does not
+// collapse it on everyone else's, and nothing about it is persisted or synced.
+//
+// Sections are keyed by heading slug (the same slug a "#anchor" link uses), so
+// the fold survives edits elsewhere in the page and a link can open a folded
+// section by name.
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import { makeSlugger } from './outline.js'
+
+export const foldKey = new PluginKey('headingFold')
+
+const folded = new Set()
+let onToggle = () => {}
+
+export function resetFolds() {
+  folded.clear()
+}
+
+export function isFolded(slug) {
+  return folded.has(slug)
+}
+
+export function unfold(slug) {
+  if (!folded.delete(slug)) return false
+  onToggle()
+  return true
+}
+
+// The page's headings in document order, each with the slug everything else
+// addresses it by.
+export function outlineOf(doc) {
+  const slugOf = makeSlugger()
+  const out = []
+  doc.forEach((node, offset) => {
+    if (node.type.name !== 'heading') return
+    out.push({ slug: slugOf(node.textContent), level: node.attrs.level || 1, pos: offset, node })
+  })
+  return out
+}
+
+// Walk the top level once: every heading gets its slug and a fold arrow, and
+// everything under a folded heading — up to the next heading of the same or a
+// higher rank — gets hidden.
+function decorate(doc) {
+  const decos = []
+  const headings = outlineOf(doc)
+  const hidden = []
+  headings.forEach((h, i) => {
+    if (!folded.has(h.slug)) return
+    const next = headings.slice(i + 1).find(n => n.level <= h.level)
+    hidden.push([h.pos + h.node.nodeSize, next ? next.pos : doc.content.size])
+  })
+
+  let hi = 0
+  doc.forEach((node, offset) => {
+    const end = offset + node.nodeSize
+    const heading = headings[hi]
+    if (heading && heading.pos === offset) {
+      hi++
+      const collapsed = folded.has(heading.slug)
+      decos.push(
+        Decoration.node(offset, end, {
+          class: `cw-heading${collapsed ? ' cw-folded' : ''}`,
+          'data-anchor': heading.slug,
+        })
+      )
+      decos.push(
+        Decoration.widget(offset + 1, () => foldArrow(heading.slug, collapsed), {
+          side: -1,
+          key: `fold-${heading.slug}-${collapsed}`,
+        })
+      )
+      return
+    }
+    if (hidden.some(([from, to]) => offset >= from && end <= to)) {
+      decos.push(Decoration.node(offset, end, { class: 'cw-hidden-by-fold' }))
+    }
+  })
+  return DecorationSet.create(doc, decos)
+}
+
+function foldArrow(slug, collapsed) {
+  const btn = document.createElement('button')
+  btn.className = 'fold-arrow' + (collapsed ? ' collapsed' : '')
+  btn.type = 'button'
+  btn.contentEditable = 'false'
+  btn.setAttribute('aria-expanded', String(!collapsed))
+  btn.title = collapsed ? 'Expand section' : 'Collapse section'
+  btn.innerHTML = '<svg viewBox="0 0 22 22" class="icon"><path d="M6 9l5 5 5-5"/></svg>'
+  // mousedown, not click: ProseMirror would otherwise move the caret into the
+  // heading first and scroll the section you are trying to shut
+  btn.addEventListener('mousedown', e => {
+    e.preventDefault()
+    e.stopPropagation()
+    if (!folded.delete(slug)) folded.add(slug)
+    onToggle()
+  })
+  return btn
+}
+
+export const HeadingFold = Extension.create({
+  name: 'headingFold',
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    onToggle = () => editor.view.dispatch(editor.state.tr.setMeta('fold', true))
+    return [
+      new Plugin({
+        key: foldKey,
+        props: {
+          decorations: state => decorate(state.doc),
+        },
+      }),
+    ]
+  },
+})

client/src/outline.js

@@ -0,0 +1,89 @@
+// Headings as addressable sections.
+//
+// One slug rule, used in three places that have to agree: the fold state, the
+// "#anchor" at the end of a page link, and the hover preview that reads the
+// target section. Anything that can name a heading names it this way.
+
+export function headingSlug(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64)
+}
+
+// Slugs are unique within a page: repeats take -2, -3 … in document order, so
+// two sections called "Method" stay separately addressable.
+export function makeSlugger() {
+  const seen = new Map()
+  return text => {
+    const base = headingSlug(text) || 'section'
+    const n = (seen.get(base) || 0) + 1
+    seen.set(base, n)
+    return n === 1 ? base : `${base}-${n}`
+  }
+}
+
+// Split page markdown into sections: the heading, its slug, the prose under it
+// and the first link in that prose. For a references page that is exactly the
+// source's title, its URL and the start of its summary — but nothing here knows
+// what a reference is, so it works for any page.
+export function markdownSections(markdown) {
+  const slugOf = makeSlugger()
+  const sections = []
+  let fenced = false
+  for (const line of String(markdown || '').split('\n')) {
+    if (/^\s*```/.test(line)) fenced = !fenced
+    const head = !fenced && line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/)
+    if (head) {
+      sections.push({ level: head[1].length, title: stripMarkup(head[2]), slug: slugOf(head[2]), body: [] })
+    } else if (sections.length) {
+      sections[sections.length - 1].body.push(line)
+    }
+  }
+  return sections.map(s => {
+    const text = s.body.join('\n').trim()
+    return { ...s, summary: stripMarkup(firstProse(text)), url: firstUrl(text) }
+  })
+}
+
+// The first paragraph that is prose rather than a bare link line — a reference
+// usually leads with its URL, and "https://…" is a poor preview of a source.
+function firstProse(text) {
+  for (const para of text.split(/\n\s*\n/)) {
+    const p = para.trim()
+    if (!p || /^\[?https?:\/\//.test(p) || /^<https?:\/\//.test(p)) continue
+    return p.replace(/\s+/g, ' ')
+  }
+  return ''
+}
+
+function firstUrl(text) {
+  return text.match(/https?:\/\/[^\s)>\]]+/)?.[0] || ''
+}
+
+// Markdown left in a heading or a summary should read as text in a preview
+// card, not as syntax.
+function stripMarkup(s) {
+  return String(s || '')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/[*_`]+/g, '')
+    .trim()
+}
+
+// "/d/<doc>/<page>#<anchor>" → the parts, for any link that points inside this
+// project. Returns null for anything else (external links, other documents).
+export function parseInternalLink(href, docId) {
+  if (!href) return null
+  let url
+  try {
+    url = new URL(href, location.origin)
+  } catch {
+    return null
+  }
+  if (url.origin !== location.origin) return null
+  const m = url.pathname.match(new RegExp(`^/d/${docId}(?:/([A-Za-z0-9_-]+))?/?$`))
+  if (!m) return null
+  return { slug: m[1] || 'home', anchor: decodeURIComponent(url.hash.replace(/^#/, '')) || null }
+}

server/api.js

@@ -483,7 +483,18 @@ Work loop — repeat until the user tells you to stop:
    the page with your content and adds it to the structure) or rejects it. To reorganize
    EXISTING pages, suggest an edit to the _structure page's YAML as an ordinary suggestion.
    Removing a page's line never deletes it — it just moves to "unfiled" in the sidebar.
-   Cross-reference pages in any markdown you write as [Title](/d/<doc_id>/<slug>).
+   Cross-reference pages in any markdown you write as [Title](/d/<doc_id>/<slug>),
+   or a single section as [Title](/d/<doc_id>/<slug>#<heading-slug>) — the slug of a
+   heading is its text lowercased with every run of non-alphanumerics turned into a
+   hyphen ("Attention Is All You Need" -> attention-is-all-you-need). Readers get a
+   preview of the section when they hover the link.
+
+   Sources: when you cite anything, keep a "references" page and cite INTO it.
+   Create it if it does not exist (a new-page suggestion titled "References").
+   One "### Source title" section per source, and under it the URL on its own line
+   followed by a 1-3 sentence summary of what it says. Then cite it from the text as
+   [Source title](/d/<doc_id>/references#source-title). Never paste bare URLs into
+   the prose, and never repeat a source's summary outside its section.
 
 3. Do the task the instruction asks for, using your own tools and judgment.
 

test/browser.js

@@ -1035,6 +1035,132 @@ async function main() {
   await waitFor(async () => page.evaluate(() => [...document.querySelectorAll('.tiptap a')].some(a => a.textContent === 'Notes' && a.getAttribute('href').endsWith('/notes'))), 'cross-reference link inserted')
   console.log('✓ [[ page cross-references')
 
+  // --- references: sections are addressable, previewable and collapsible ---
+  // No references machinery exists: an agent writes an ordinary page with one
+  // heading per source, and these three primitives make it work as a citation
+  // system. The test therefore builds that page the way an agent would.
+  const refsMd = [
+    '# References',
+    '',
+    '### Attention Is All You Need',
+    '',
+    'https://arxiv.org/abs/1706.03762',
+    '',
+    'Introduces the transformer: attention replaces recurrence entirely.',
+    '',
+    '### Deep Residual Learning',
+    '',
+    'https://arxiv.org/abs/1512.03385',
+    '',
+    'Residual connections let very deep networks train at all.',
+    '',
+  ].join('\n')
+  const refsDocId = page.url().split('/d/')[1].split('/')[0]
+  const refsPage = await page.evaluate(
+    async ([id, md]) => {
+      const post = (path, body) =>
+        fetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }).then(r => r.json())
+      const proposed = await post(`/api/docs/${id}/page-suggestions`, { title: 'References', content_markdown: md })
+      return post(`/api/docs/${id}/page-suggestions/${proposed.page_suggestion_id}/accept`, {})
+    },
+    [refsDocId, refsMd]
+  )
+  assert.ok(refsPage.ok, 'references page created: ' + JSON.stringify(refsPage))
+  // the sidebar polls the structure; the autocomplete reads the same list
+  await waitFor(
+    async () => page.evaluate(() => [...document.querySelectorAll('#page-tree a')].some(a => a.textContent.includes('References'))),
+    'the references page reaches the page tree',
+    20000
+  )
+
+  // cite it: "[[references#att" offers the section, and links straight into it
+  await focusDocEnd(page)
+  await page.keyboard.press('Enter')
+  await page.keyboard.type('As shown in [[references#att')
+  await waitFor(
+    async () => !(await page.evaluate(() => document.getElementById('pagelink-menu').classList.contains('hidden'))),
+    'the heading autocomplete offers sections of the target page'
+  )
+  await page.keyboard.press('Enter')
+  const citationHref = () =>
+    page.evaluate(() =>
+      [...document.querySelectorAll('.tiptap a')].map(a => a.getAttribute('href')).find(h => h.includes('/references#'))
+    )
+  await waitFor(citationHref, 'a citation links into the section')
+  const citation = await citationHref()
+  assert.ok(citation.endsWith('#attention-is-all-you-need'), 'the anchor is the heading slug: ' + citation)
+
+  // hovering it shows what is on the other end
+  await page.hover(`.tiptap a[href$="#attention-is-all-you-need"]`)
+  await waitFor(async () => !(await page.evaluate(() => document.getElementById('link-preview').classList.contains('hidden'))), 'a preview appears')
+  const preview = await page.evaluate(() => ({
+    title: document.querySelector('#link-preview .lp-title')?.textContent,
+    url: document.querySelector('#link-preview .lp-url')?.textContent,
+    summary: document.querySelector('#link-preview .lp-summary')?.textContent,
+    page: document.querySelector('#link-preview .lp-page')?.textContent,
+  }))
+  assert.strictEqual(preview.title, 'Attention Is All You Need', 'the preview names the source')
+  assert.ok(preview.url?.includes('arxiv.org/abs/1706.03762'), 'and carries its link: ' + preview.url)
+  assert.ok(preview.summary?.startsWith('Introduces the transformer'), 'and the start of the summary: ' + preview.summary)
+  assert.strictEqual(preview.page, 'References', 'and says which page it is on')
+
+  // following it lands on that section, not merely on the page
+  await page.click(`.tiptap a[href$="#attention-is-all-you-need"]`, { modifiers: ['Control'] })
+  await waitFor(async () => (await page.evaluate(() => location.hash)) === '#attention-is-all-you-need', 'the link carries the anchor')
+  await waitFor(
+    async () => page.evaluate(() => !!document.querySelector('.tiptap [data-anchor="attention-is-all-you-need"]')),
+    'the references page is open with its sections addressable'
+  )
+  const jumped = await page.evaluate(() => {
+    const h = document.querySelector('.tiptap [data-anchor="attention-is-all-you-need"]')
+    return { onScreen: h.getBoundingClientRect().top < innerHeight, marked: h.classList.contains('cw-jumped') }
+  })
+  assert.ok(jumped.onScreen, 'the section was scrolled into view')
+
+  // and a section can be shut, locally
+  const folding = async () =>
+    page.evaluate(() => ({
+      hidden: document.querySelectorAll('.tiptap .cw-hidden-by-fold').length,
+      folded: [...document.querySelectorAll('.tiptap .cw-folded')].map(n => n.dataset.anchor),
+      bodyVisible: document.querySelector('.tiptap').innerText.includes('attention replaces recurrence'),
+    }))
+  const clickArrow = anchor =>
+    page.evaluate(
+      a =>
+        document
+          .querySelector(`.tiptap [data-anchor="${a}"] .fold-arrow`)
+          .dispatchEvent(new MouseEvent('mousedown', { bubbles: true })),
+      anchor
+    )
+  assert.ok((await folding()).bodyVisible, 'the section reads before folding')
+  await clickArrow('attention-is-all-you-need')
+  await page.waitForTimeout(250)
+  const shut = await folding()
+  assert.deepStrictEqual(shut.folded, ['attention-is-all-you-need'], 'the heading shows as folded')
+  assert.ok(shut.hidden > 0 && !shut.bodyVisible, 'its body is hidden, and only its body')
+  assert.ok(
+    await page.evaluate(() => document.querySelector('.tiptap').innerText.includes('Deep Residual Learning')),
+    'the next section is untouched'
+  )
+  await clickArrow('attention-is-all-you-need')
+  await page.waitForTimeout(250)
+  assert.ok((await folding()).bodyVisible, 'unfolding brings it back')
+
+  // a link INTO a folded section has to open it, or the jump lands on nothing
+  await clickArrow('attention-is-all-you-need')
+  await page.waitForTimeout(250)
+  await page.evaluate(() => {
+    location.hash = ''
+    location.hash = 'attention-is-all-you-need'
+  })
+  await page.waitForTimeout(600)
+  assert.ok((await folding()).bodyVisible, 'following an anchor unfolds the section it points at')
+  console.log('✓ references: #section links, hover previews, collapsible headings')
+
+  await page.goto(`${BASE}/d/${refsDocId}`)
+  await page.waitForSelector('.tiptap', { timeout: 10000 })
+  await page.waitForTimeout(800)
+
   // ghost page: visiting a slug that does not exist creates it, titled by slug
   const projId = page.url().split('/d/')[1].split('/')[0]
   await page.goto(`${BASE}/d/${projId}/road-map`)