Merge pull request #11 from huggingface/bugfixes

Four fixes: agent subpages, the pending selection, overlapping marks, the star

client/app.css

@@ -387,6 +387,15 @@ textarea { resize: vertical; }
 .tiptap img.ProseMirror-selectednode { outline: 3px solid var(--accent-soft); outline-offset: 2px; }
 .tiptap .comment-hl { background: var(--hl); border-bottom: 1.5px solid var(--hl-edge); cursor: pointer; }
 .tiptap .comment-hl.active { background: var(--hl-active); }
+/* What the open composer is about. The browser drops its own selection
+   highlight the moment focus moves to the box, so this stands in for it —
+   dashed, to read as "not committed yet" next to real comment highlights. */
+.tiptap .pending-hl { background: var(--hl-weak); border-bottom: 1.5px dashed var(--hl-edge); }
+/* A comment and a suggestion over the same words: the comment keeps its
+   underline but drops the fill, so the suggestion's inserted and deleted spans
+   are not two tints deep and stay legible. */
+.tiptap .comment-hl.with-sugg { background: transparent; border-bottom-style: dotted; }
+.tiptap .comment-hl.with-sugg.active { background: transparent; border-bottom-width: 2px; }
 .tiptap .suggestion-hl { background: transparent; position: relative; }
 .tiptap .suggestion-hl::before { content: ''; position: absolute; left: -16px; top: 2px; bottom: 2px; width: 2.5px; background: var(--sugg-bar); }
 .tiptap p.is-editor-empty:first-child::before { color: var(--text-3); content: attr(data-placeholder); float: left; height: 0; pointer-events: none; }
@@ -817,7 +826,15 @@ body.suggesting .tiptap { caret-color: transparent; cursor: default; }
 #page-tree .group-row.lvl-3 .group-label,
 #page-tree .group-row.lvl-4 .group-label { color: var(--text-2); font-size: 12px; }
 #page-tree .group-row:hover { --sidebar-row-bg: var(--hl-weak); background: var(--sidebar-row-bg); }
-#page-tree .home-star { width: 12px; height: 12px; flex: 0 0 12px; color: var(--text-3); }
+#page-tree .home-star {
+  width: 12px; height: 12px; flex: 0 0 12px; color: var(--text-3);
+  /* out of the flow: the row's caret gutter is 16px, and the star sits in it so
+     home's title lines up with every other page's */
+  position: absolute; left: 2px; top: 50%; transform: translateY(-50%); pointer-events: none;
+}
+/* home with children: the caret owns the gutter, so the star trails the title
+   instead of landing on top of it — still without moving the title */
+#page-tree .home-star.trailing { position: static; transform: none; margin: 0 4px 0 2px; }
 #page-tree .sidebar-rename {
   flex: 1; min-width: 0; margin: 1px 3px; padding: 3px 5px; border: 1px solid var(--accent); border-radius: 5px;
   background: var(--surface); color: var(--text); font: inherit; font-size: 13px;

client/src/doc.js

@@ -1720,12 +1720,18 @@ async function loadStructure() {
           if (!known.has(node.slug)) return
           beginPageRename(a, node.slug, pageTitle)
         })
+        row.appendChild(a)
         if (node.slug === 'home') {
+          // The star marks the project's front page. It used to sit before the
+          // label, which pushed home's title right of every other top-level
+          // page; it now hangs in the row's own left gutter so all the titles
+          // start at the same x — except when home has children, because then
+          // the caret already owns that gutter, so the star follows the title.
           const star = icon('star')
           star.classList.add('home-star')
+          if (hasChildren) star.classList.add('trailing')
           row.appendChild(star)
         }
-        row.appendChild(a)
         if (deletablePage(node.slug)) row.appendChild(pageDeleteBtn(node.slug))
       }
       li.appendChild(row)
@@ -2024,11 +2030,42 @@ function buildDecorations(pmState) {
   if (!ystate?.binding) return DecorationSet.empty
   const decos = []
 
+  // Suggestion ranges come first because the comment highlight has to know
+  // whether it is sharing text with one: two filled highlights over the same
+  // words cancel each other out (see below).
+  const suggestionRanges = []
+  for (const chain of suggestionChains()) {
+    if (chain.display.status !== 'open' && chain.display.status !== 'superseded') continue
+    const range = suggestionRange(pmState, chain.display)
+    if (range) suggestionRanges.push(range)
+  }
+  const overlapsSuggestion = range => suggestionRanges.some(r => r.from < range.to && range.from < r.to)
+
+  // What you are about to comment on. Focusing the composer moves focus out of
+  // the editor, which drops the browser's own selection highlight — so without
+  // this the text you selected is no longer marked anywhere while you type
+  // about it.
+  for (const [anchors, boxId] of [
+    [state.composerAnchors, 'composer'],
+    [state.suggestAnchors, 'suggest-composer'],
+  ]) {
+    if (!anchors || document.getElementById(boxId)?.classList.contains('hidden') !== false) continue
+    const range = anchorsToRange(pmState, ystate, anchors.start, anchors.end)
+    if (!range || range.from >= range.to) continue
+    decos.push(Decoration.inline(range.from, range.to, { class: 'pending-hl' }))
+  }
+
   threads.forEach((ythread, id) => {
     if (ythread.get('resolved') || ythread.get('suggestionId')) return
     const range = anchorsToRange(pmState, ystate, ythread.get('anchorStart'), ythread.get('anchorEnd'))
     if (!range || range.from >= range.to) return
-    const cls = 'comment-hl' + (state.activeItem === id ? ' active' : '')
+    // A comment and a suggestion on the same words: the comment gives up its
+    // fill and keeps only its underline, so the suggestion's own inserted and
+    // deleted spans stay readable. Two tints stacked made the change invisible.
+    const cls =
+      'comment-hl' +
+      (state.activeItem === id ? ' active' : '') +
+      (overlapsSuggestion(range) ? ' with-sugg' : '')
     decos.push(Decoration.inline(range.from, range.to, { class: cls, 'data-thread': id }))
   })
 
@@ -2588,6 +2625,13 @@ function poke(editor) {
   editor.view.dispatch(editor.view.state.tr.setMeta('collab-refresh', true))
 }
 
+// Hide a composer box AND drop the highlight that marked what it was about.
+function hideComposerBox(id) {
+  document.getElementById(id)?.classList.add('hidden')
+  const editor = window.__editor
+  if (editor && !editor.isDestroyed) poke(editor)
+}
+
 function setActive(id) {
   state.activeItem = id
   // revealing a specific item un-hides the comments panel
@@ -2921,7 +2965,7 @@ function openForSelection(editor) {
 function closeAutoComposer() {
   if (!state.autoComposer || state.composerDirty) return
   const isSuggest = state.autoComposer === 'suggest'
-  document.getElementById(isSuggest ? 'suggest-composer' : 'composer').classList.add('hidden')
+  hideComposerBox(isSuggest ? 'suggest-composer' : 'composer')
   if (!isSuggest) document.getElementById('composer-text').value = ''
   state.autoComposer = null
   state.suggestRange = null
@@ -2959,7 +3003,7 @@ function openComposer(editor, opts = {}) {
     excerpt: editor.state.doc.textBetween(from, to, ' ', leafText).slice(0, 200),
   }
   document.getElementById('composer-quote').textContent = state.composerAnchors.excerpt
-  document.getElementById('suggest-composer').classList.add('hidden')
+  hideComposerBox('suggest-composer')
   document.getElementById('composer').classList.remove('hidden')
   document.getElementById('selection-menu').classList.add('hidden')
   const text = document.getElementById('composer-text')
@@ -2983,6 +3027,7 @@ function openComposer(editor, opts = {}) {
     })
   }
   state.autoComposer = opts.auto ? 'comment' : null
+  poke(editor) // mark the pending range now that composerAnchors is set
   setMarginHidden(false, false) // the composer lives in the comments panel
   renderMargin(editor)
   // an auto-opened box must not steal the keyboard: selecting text and typing
@@ -3082,7 +3127,7 @@ function wireComposer() {
     state.composerDirty = true
   })
   document.getElementById('composer-cancel').addEventListener('click', () => {
-    document.getElementById('composer').classList.add('hidden')
+    hideComposerBox('composer')
     text.value = ''
     state.composerDirty = false
     state.autoComposer = null
@@ -3106,7 +3151,7 @@ function wireComposer() {
     text.value = ''
     state.composerDirty = false
     state.autoComposer = null
-    document.getElementById('composer').classList.add('hidden')
+    hideComposerBox('composer')
     setActive(id)
   })
   wireMentionMenu(text, document.getElementById('composer-mentions'))
@@ -3154,7 +3199,7 @@ async function openSuggestComposer(editor, opts = {}) {
     start: encodeRel(Y.createRelativePositionFromTypeIndex(fragment, blockFrom)),
     end: encodeRel(Y.createRelativePositionFromTypeIndex(fragment, blockTo + 1)),
   }
-  document.getElementById('composer').classList.add('hidden')
+  hideComposerBox('composer')
   document.getElementById('selection-menu').classList.add('hidden')
   const composer = document.getElementById('suggest-composer')
   composer.classList.remove('hidden')
@@ -3183,7 +3228,7 @@ function wireSuggestComposer() {
     })
   }
   document.getElementById('suggest-cancel').addEventListener('click', () => {
-    document.getElementById('suggest-composer').classList.add('hidden')
+    hideComposerBox('suggest-composer')
     state.composerDirty = false
     state.autoComposer = null
     state.suggestRange = null
@@ -3202,7 +3247,7 @@ function wireSuggestComposer() {
       },
     })
     if (res.error) return uiAlert(res.error)
-    document.getElementById('suggest-composer').classList.add('hidden')
+    hideComposerBox('suggest-composer')
     document.getElementById('suggest-text').value = ''
     document.getElementById('suggest-rationale').value = ''
     state.composerDirty = false

server/api.js

@@ -183,13 +183,20 @@ export function apiRouter() {
     // a page parent is its slug, a group parent is its path array. Checked here
     // so a proposal for a parent that does not exist is refused now, rather than
     // landing in the wrong place when someone accepts it.
-    const { parent = null, index = null } = req.body || {}
-    if (parent != null) {
+    const rawParent = req.body?.parent ?? req.body?.parent_slug ?? req.body?.parent_page ?? req.body?.under ?? null
+    const index = req.body?.index ?? null
+    let parent = null
+    if (rawParent != null) {
       await collab.ensureStructurePage(req.params.id)
       const structure = getProjectStructure(hocuspocus, req.params.id)
-      if (!findStructureNode(structure?.tree || [], parent)) {
-        return res.status(400).json({ error: `unknown parent ${JSON.stringify(parent)} — a page parent is its slug, a group parent is its path array (GET /api/docs/:id/structure)` })
+      const resolved = resolveParentRef(structure, rawParent, structure?.titles)
+      if (!resolved) {
+        return res.status(400).json({
+          error: `unknown parent ${JSON.stringify(rawParent)} — pass a page's slug or title, or a group's label (GET /api/docs/:id/structure lists them)`,
+          pages: Object.keys(structure?.titles || {}),
+        })
       }
+      parent = resolved.ref
     }
     if (index != null && !Number.isInteger(index)) return res.status(400).json({ error: 'index must be an integer' })
     const result = await collab.createPageProposal(req.params.id, {
@@ -203,7 +210,7 @@ export function apiRouter() {
     })
     if (result.error) return res.status(400).json({ error: result.error })
     if (identity.authorType === 'agent') collab.completeMention(mention_id, {})
-    res.json({ ok: true, page_suggestion_id: result.id, slug: result.slug })
+    res.json({ ok: true, page_suggestion_id: result.id, slug: result.slug, parent, index })
   })
 
   router.get('/docs/:id/page-suggestions/:pid', requireUser, checkDocId, requireDocAccess, async (req, res) => {
@@ -218,6 +225,8 @@ export function apiRouter() {
       author: p.author,
       author_type: p.authorType,
       status: p.status,
+      parent: p.parent ?? null,
+      index: Number.isInteger(p.index) ? p.index : null,
     })
   })
 
@@ -516,16 +525,56 @@ function checkDocId(req, res, next) {
   next()
 }
 
-// Does a {parent} ref name a real node in the tree? A page is its slug, a group
-// is its path array (['design', '"Ideas"']) — see pages.js.
-function findStructureNode(nodes, ref, path = []) {
-  for (const node of nodes) {
-    const here = [...path, node.group != null ? `"${node.group}"` : node.slug]
-    if (typeof ref === 'string' ? node.slug === ref : Array.isArray(ref) && ref.length === here.length && ref.every((e, i) => e === here[i])) return node
-    const hit = findStructureNode(node.children || [], ref, here)
-    if (hit) return hit
+// Resolve a caller's idea of a parent into the ref the yaml editor takes: a page
+// is its slug, a group is its path array (['design', '"Ideas"']) — see pages.js.
+//
+// An agent works from whatever it can see, and the first thing it sees is a
+// TITLE. Sending "Notes" for the page `notes`, or `Getting started` for the
+// group `"Getting started"`, is the obvious guess and used to be a 400 — which
+// is how a subpage ended up at the top level instead. So the natural spellings
+// resolve, and only a genuinely unknown parent is refused.
+//
+// Returns { ref } for the canonical ref, or null when nothing matches.
+export function resolveParentRef(structure, ref, titles = {}) {
+  if (ref == null) return { ref: null }
+  const nodes = structure?.tree || []
+  const norm = v => String(v).trim().toLowerCase()
+
+  // exact refs first, so a precise caller is never second-guessed
+  const exact = (list, path = []) => {
+    for (const node of list) {
+      const here = [...path, node.group != null ? `"${node.group}"` : node.slug]
+      const hit =
+        typeof ref === 'string'
+          ? node.group == null && node.slug === ref
+          : Array.isArray(ref) && ref.length === here.length && ref.every((e, i) => e === here[i])
+      if (hit) return { ref: node.group == null ? node.slug : here }
+      const deeper = exact(node.children || [], here)
+      if (deeper) return deeper
+    }
+    return null
   }
-  return null
+  const precise = exact(nodes)
+  if (precise) return precise
+
+  // then the forgiving pass: a page title, or a group label written without its
+  // quotes. Single-element arrays are unwrapped ("['Notes']" is the same guess).
+  const wanted = norm(Array.isArray(ref) && ref.length === 1 ? ref[0] : ref).replace(/^"|"$/g, '')
+  if (!wanted) return null
+  const loose = (list, path = []) => {
+    for (const node of list) {
+      const here = [...path, node.group != null ? `"${node.group}"` : node.slug]
+      if (node.group != null) {
+        if (norm(node.group) === wanted) return { ref: here }
+      } else if (norm(node.slug) === wanted || norm(titles[node.slug] || '') === wanted) {
+        return { ref: node.slug }
+      }
+      const deeper = loose(node.children || [], here)
+      if (deeper) return deeper
+    }
+    return null
+  }
+  return loose(nodes)
 }
 
 // Markdown bodies arrive under a field name the caller had to guess right.
@@ -643,9 +692,10 @@ Work loop — repeat until the user tells you to stop:
    To propose a NEW page, POST a single new-page suggestion with its title and full content:
    curl -s "\${AUTH[@]}" -X POST "${HOST}/api/docs/<doc_id>/page-suggestions" -H 'content-type: application/json' \\
      -d '{"title": "Page Title", "content_markdown": "# Page Title\\n\\n...", "rationale": "why", "as_agent": "${handle}"}'
-   Say WHERE it belongs with "parent" and "index" — the same refs /structure/move takes: a
-   page parent is its slug, a group parent is its path array, and no parent means top level.
-   Index is the position among that parent's children (omit for last):
+   Say WHERE it belongs with "parent" and "index", or it lands at the top level. A parent can
+   be a page's slug OR its title, or a group's label; no parent means top level. Index is the
+   position among that parent's children (omit for last). The response echoes the parent and
+   index it understood, so you can check the page is going where you meant:
      -d '{"title": "Setup", "content_markdown": "# Setup\\n\\n...", "parent": ["\\"Getting started\\""], "index": 0, "as_agent": "${handle}"}'
      -d '{"title": "Notes on X", "content_markdown": "...", "parent": "research", "as_agent": "${handle}"}'
    An unknown parent is refused, so read GET .../structure first. It appears in the sidebar

test/browser.js

@@ -501,6 +501,8 @@ async function main() {
   await waitFor(async () => (await page.innerHTML('.tiptap')).includes('<strong>energetic</strong>'), 'suggestion applied with marks')
   console.log('✓ suggestion accepted -> text replaced with marks')
 
+
+
   // closed items are hidden by default, shown with the toggle
   await waitFor(async () => !(await page.$('.card.suggestion')), 'accepted suggestion hidden')
   await page.check('#show-resolved')
@@ -1262,6 +1264,33 @@ async function main() {
   await page.evaluate(() => window.dispatchEvent(new Event('afterprint')))
   await waitFor(async () => page.evaluate(() => !document.getElementById('print-view') && !document.body.classList.contains('printing')), 'print view is torn down afterwards')
   console.log('✓ download: page/project × markdown/pdf, print shows the document alone')
+  // --- the home star must not indent home's title ---
+  // top-level real pages only: a nested page or a proposal is indented on purpose
+  const titleXs = await page.evaluate(() =>
+    [...document.querySelectorAll('#page-tree .page-row[data-depth="0"]:not(.proposal-row)')].map(r => ({
+      title: r.querySelector('a')?.textContent.trim(),
+      left: Math.round(r.querySelector('a')?.getBoundingClientRect().left),
+      star: !!r.querySelector('.home-star'),
+    }))
+  )
+  const starred = titleXs.find(t => t.star)
+  assert.ok(starred, 'the front page still carries its star: ' + JSON.stringify(titleXs))
+  // and it must not land on the caret when home has children of its own
+  const starClash = await page.evaluate(() => {
+    const row = document.querySelector('#page-tree .page-row:has(.home-star)')
+    const star = row?.querySelector('.home-star')
+    const caret = row?.querySelector('.tree-caret')
+    if (!star || !caret) return { bothPresent: false }
+    const l = n => n.getBoundingClientRect().left
+    return { bothPresent: true, apart: Math.abs(l(star) - l(caret)) >= 12 }
+  })
+  if (starClash.bothPresent) assert.ok(starClash.apart, 'star and caret do not sit on top of each other: ' + JSON.stringify(starClash))
+  const others = titleXs.filter(t => !t.star)
+  assert.ok(others.length > 0, 'there are sibling pages to compare against: ' + JSON.stringify(titleXs))
+  for (const other of others) {
+    assert.strictEqual(starred.left, other.left, `"${starred.title}" starts where "${other.title}" does: ` + JSON.stringify(titleXs))
+  }
+  console.log('✓ the star sits in the gutter; every sidebar title starts at the same x')
 
   // return to the home page for the remaining playground sub-tests
   await page.evaluate(() => [...document.querySelectorAll('#page-tree a')].find(a => a.textContent.trim() === 'Playground')?.click())
@@ -1370,6 +1399,80 @@ async function main() {
   await page.waitForTimeout(800)
   console.log('✓ link bubble: a plain click offers Open, ctrl+click still follows')
 
+  // --- what you are commenting on stays marked while you type about it ---
+  // Focusing the composer moves focus out of the editor, which drops the
+  // browser's own selection highlight: the text you picked went unmarked while
+  // the box asked you about it.
+  await focusDocEnd(page)
+  await page.keyboard.press('Enter')
+  await page.keyboard.type('A line worth discussing at some length.')
+  await page.waitForTimeout(400)
+  const pickLine = () => page.evaluate(() => {
+    const target = [...document.querySelectorAll('.tiptap p')].find(n => n.textContent.startsWith('A line worth discussing'))
+    const pos = window.__editor.view.posAtDOM(target, 0)
+    window.__editor.commands.setTextSelection({ from: pos, to: pos + target.textContent.length })
+  })
+  await pickLine()
+  await page.waitForSelector('#composer:not(.hidden)', { timeout: 10000 })
+  await page.click('#composer-text')
+  await waitFor(async () => page.evaluate(() => document.querySelectorAll('.tiptap .pending-hl').length === 1), 'the pending range is marked once the composer has focus')
+  const pending = await page.evaluate(() => {
+    const n = document.querySelector('.tiptap .pending-hl')
+    const cs = getComputedStyle(n)
+    return { text: n.textContent, bg: cs.backgroundColor, style: cs.borderBottomStyle, nativeSelectionGone: getSelection().isCollapsed }
+  })
+  assert.ok(pending.text.startsWith('A line worth discussing'), 'it marks the text the composer is about: ' + JSON.stringify(pending))
+  assert.notStrictEqual(pending.bg, 'rgba(0, 0, 0, 0)', 'and it is actually visible: ' + JSON.stringify(pending))
+  assert.strictEqual(pending.style, 'dashed', 'dashed, to read as not-yet-committed: ' + JSON.stringify(pending))
+
+  // and it is scaffolding: cancelling must not leave it behind
+  await page.evaluate(() => [...document.querySelectorAll('#composer button')].find(b => /cancel/i.test(b.textContent))?.click())
+  await waitFor(async () => page.evaluate(() => document.querySelectorAll('.tiptap .pending-hl').length === 0), 'cancelling clears the mark')
+  console.log('✓ composer marks the text it is about, and clears it on cancel')
+
+  // --- a comment and a suggestion on the same words ---
+  // Two filled highlights over one range cancelled each other out: the
+  // suggestion's insert/delete spans were invisible under the comment tint.
+  // the box opens when the selection CHANGES, so move the caret before picking
+  // the same line again
+  await focusDocEnd(page)
+  await page.waitForTimeout(200)
+  await pickLine()
+  await page.waitForSelector('#composer:not(.hidden)', { timeout: 10000 })
+  await page.fill('#composer-text', 'can this be tightened?')
+  await page.click('#composer .primary, #composer button:has-text("Comment")')
+  await page.waitForSelector('.card.thread', { timeout: 10000 })
+  await page.click('.card.thread') // active, as it is right after commenting
+  await page.waitForTimeout(300)
+  await page.evaluate(async () => {
+    const id = location.pathname.split('/d/')[1].split('/')[0]
+    const snap = await (await fetch(`/api/docs/${id}`)).json()
+    const idx = (snap.blocks || []).findIndex(b => (b.markdown || '').includes('A line worth discussing'))
+    await fetch(`/api/docs/${id}/suggestions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ block_index: idx, replacement_markdown: 'A line worth debating at some length.', rationale: 'sharper verb' }),
+    })
+  })
+  await waitFor(async () => page.evaluate(() => document.querySelectorAll('.tiptap .sugg-ins').length > 0), 'the suggestion reaches the document')
+  const overlap = await page.evaluate(() => {
+    const opaque = c => c !== 'rgba(0, 0, 0, 0)' && c !== 'transparent'
+    const commentHl = [...document.querySelectorAll('.tiptap .comment-hl')]
+    const ins = [...document.querySelectorAll('.tiptap .sugg-ins')]
+    return {
+      commentMarked: commentHl.every(n => n.classList.contains('with-sugg')),
+      commentUnderlined: commentHl.every(n => ['dotted', 'dashed', 'solid'].includes(getComputedStyle(n).borderBottomStyle)),
+      commentFilled: commentHl.some(n => opaque(getComputedStyle(n).backgroundColor)),
+      insFilled: ins.length > 0 && ins.every(n => opaque(getComputedStyle(n).backgroundColor)),
+      insText: ins.map(n => n.textContent.trim()),
+    }
+  })
+  assert.ok(overlap.commentMarked, 'the comment knows it is sharing text with a suggestion: ' + JSON.stringify(overlap))
+  assert.ok(!overlap.commentFilled, 'so it gives up its fill: ' + JSON.stringify(overlap))
+  assert.ok(overlap.commentUnderlined, 'but stays marked by its underline: ' + JSON.stringify(overlap))
+  assert.ok(overlap.insFilled, 'and the inserted words keep a visible fill of their own: ' + JSON.stringify(overlap))
+  console.log('✓ a suggestion stays visible on text that already carries a comment')
+
   // 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`)

test/smoke.js

@@ -897,6 +897,59 @@ async function main() {
     ['notes-on-x'],
     'and a page-parented proposal nests under that page: ' + JSON.stringify(placedTree)
   )
+  // An agent works from what it can see, and what it sees is a TITLE. Sending
+  // "Research Notes" for the page `research-notes`, or a group's label without
+  // its quotes, used to be a 400 — which is how a requested subpage ended up at
+  // the top level instead.
+  await api('dev:alice', `/api/docs/${npjProj.id}/pages`, { method: 'POST', body: { title: 'Research Notes' } })
+  const guesses = [
+    ['the exact slug', 'research-notes', 'research-notes'],
+    ['the page title', 'Research Notes', 'research-notes'],
+    ['the title in another case', 'research notes', 'research-notes'],
+    ['a group label without quotes', 'Getting started', ['"Getting started"']],
+    ['a one-element array holding a title', ['Research Notes'], 'research-notes'],
+  ]
+  for (const [what, parent, expected] of guesses) {
+    const r = await api(AGENT, `/api/docs/${npjProj.id}/page-suggestions`, {
+      method: 'POST',
+      body: { title: `Placed by ${what}`, content_markdown: '# X', parent },
+    })
+    assert.ok(r.ok, `${what} is accepted as a parent: ${JSON.stringify(r)}`)
+    assert.deepEqual(r.parent, expected, `${what} resolves to the canonical ref, and the response says so: ${JSON.stringify(r)}`)
+    await api('dev:alice', `/api/docs/${npjProj.id}/page-suggestions/${r.page_suggestion_id}/reject`, { method: 'POST' })
+  }
+  // the aliases an agent is likely to reach for
+  for (const field of ['parent_slug', 'parent_page', 'under']) {
+    const r = await api(AGENT, `/api/docs/${npjProj.id}/page-suggestions`, {
+      method: 'POST',
+      body: { title: `Via ${field}`, content_markdown: '# X', [field]: 'Research Notes' },
+    })
+    assert.equal(r.parent, 'research-notes', `"${field}" works as a parent field: ${JSON.stringify(r)}`)
+    await api('dev:alice', `/api/docs/${npjProj.id}/page-suggestions/${r.page_suggestion_id}/reject`, { method: 'POST' })
+  }
+  // a name nothing matches is still refused, with the pages listed to choose from
+  const noSuch = await api(AGENT, `/api/docs/${npjProj.id}/page-suggestions`, {
+    method: 'POST',
+    body: { title: 'Nowhere', content_markdown: '# X', parent: 'Marketing Plan' },
+  })
+  assert.ok(noSuch.error?.includes('unknown parent'), 'an unknown parent is refused: ' + JSON.stringify(noSuch))
+  assert.ok(noSuch.pages?.includes('research-notes'), 'and the reply lists real pages to choose from: ' + JSON.stringify(noSuch))
+  // reading a proposal back shows where it is headed
+  const titleParented = await api(AGENT, `/api/docs/${npjProj.id}/page-suggestions`, {
+    method: 'POST',
+    body: { title: 'Child By Title', content_markdown: '# Child', parent: 'Research Notes' },
+  })
+  const readBack = await api('dev:alice', `/api/docs/${npjProj.id}/page-suggestions/${titleParented.page_suggestion_id}`)
+  assert.equal(readBack.parent, 'research-notes', 'GET shows the resolved parent: ' + JSON.stringify(readBack))
+  await api('dev:alice', `/api/docs/${npjProj.id}/page-suggestions/${titleParented.page_suggestion_id}/accept`, { method: 'POST' })
+  const guessTree = (await api('dev:alice', `/api/docs/${npjProj.id}/structure`)).tree
+  assert.deepEqual(
+    guessTree.find(n => n.slug === 'research-notes')?.children?.map(c => c.slug),
+    ['child-by-title'],
+    'and a title-parented proposal lands under that page: ' + JSON.stringify(guessTree)
+  )
+  console.log('✓ a parent can be named by slug, title or group label — an agent\'s guess is not silently flattened')
+
   console.log('✓ page proposals carry a place in the hierarchy, and accepting files them there')
 
   // 11i. markdown export: a zip that renders outside cowrite. The images matter