Merge pull request #345 from quarto-dev/feature/bd-9x3zbuj8-preview-hierarchy-nav-overlap

q2 preview: hierarchical block navigator + fix breadcrumb/toolbar overlap (bd-9x3zbuj8)

Author: cscheid

claude-notes/plans/2026-06-25-q2-preview-hierarchy-nav-and-overlap.md

@@ -15,6 +15,10 @@ be in reverse chronological order (latest first).
 
 -->
 
+### 2026-06-25
+
+- [`15b9287c`](https://github.com/quarto-dev/q2/commits/15b9287c): The block-hierarchy navigator (◀ Dv ¶ ▶) now sits inline to the right of the rich-text formatting buttons instead of overlapping them, and `q2 preview --allow-edit` shows the navigator by default (matching the hub editor).
+
 ### 2026-06-24
 
 - [`0ccf989a`](https://github.com/quarto-dev/q2/commits/0ccf989a): The editor no longer auto-inserts a second backtick — typing `` ` `` at the end of a word to close inline code now adds just one backtick instead of two (selecting a word and typing `` ` `` still wraps it).

hub-client/changelog.md

@@ -68,7 +68,12 @@ test.afterEach(async () => {
 });
 
 test('paragraph: active region height and following heading top unchanged on activation', async ({ page }) => {
-    await page.goto(server.url);
+    // Pin richText=0: these no-reflow tests use the textarea as the activation
+    // baseline (assertNoReflowOnActivation waits for a <textarea>). Since rich-text
+    // is the q2-preview default (bd-j1nto6eq), Para/Header would otherwise open in
+    // the rich editor and no textarea would mount. Same baseline pin as the
+    // hub-client e2e (bd-038tnyqy). Tracked: bd-n4v4phe4.
+    await page.goto(`${server.url}${server.url.includes('?') ? '&' : '?'}richText=0`);
     await waitForEditableBlocks(page);
     const iframe = page.frameLocator('iframe');
     await assertNoReflowOnActivation(
@@ -80,7 +85,12 @@ test('paragraph: active region height and following heading top unchanged on act
 });
 
 test('heading: active region height and following list top unchanged on activation', async ({ page }) => {
-    await page.goto(server.url);
+    // Pin richText=0: these no-reflow tests use the textarea as the activation
+    // baseline (assertNoReflowOnActivation waits for a <textarea>). Since rich-text
+    // is the q2-preview default (bd-j1nto6eq), Para/Header would otherwise open in
+    // the rich editor and no textarea would mount. Same baseline pin as the
+    // hub-client e2e (bd-038tnyqy). Tracked: bd-n4v4phe4.
+    await page.goto(`${server.url}${server.url.includes('?') ? '&' : '?'}richText=0`);
     await waitForEditableBlocks(page);
     const iframe = page.frameLocator('iframe');
     await assertNoReflowOnActivation(
@@ -92,7 +102,12 @@ test('heading: active region height and following list top unchanged on activati
 });
 
 test('paragraph above list: active region height and list top unchanged on activation', async ({ page }) => {
-    await page.goto(server.url);
+    // Pin richText=0: these no-reflow tests use the textarea as the activation
+    // baseline (assertNoReflowOnActivation waits for a <textarea>). Since rich-text
+    // is the q2-preview default (bd-j1nto6eq), Para/Header would otherwise open in
+    // the rich editor and no textarea would mount. Same baseline pin as the
+    // hub-client e2e (bd-038tnyqy). Tracked: bd-n4v4phe4.
+    await page.goto(`${server.url}${server.url.includes('?') ? '&' : '?'}richText=0`);
     await waitForEditableBlocks(page);
     const iframe = page.frameLocator('iframe');
     await assertNoReflowOnActivation(

q2-preview-spa/e2e/edit-cell-sizing.spec.ts

@@ -5,12 +5,15 @@
  * embeds the SPA + WASM through `include_dir!`. Asserts the §3a/§3b nesting-cursor
  * RESOLUTION that no existing q2-preview-spa spec covers:
  *
- *   - WITH `?nestingCursor=1` (+ `--allow-edit`): a leaf-click on a blockquote
+ *   - DEFAULT boot (no param, + `--allow-edit`, bd-9x3zbuj8): the nesting cursor
+ *     is now ON by default (matching hub-client). A leaf-click on a blockquote
  *     child opens THAT child with a CLEAN, AST-regenerated buffer (no `>`
- *     markers) — proving leaf resolution + nested-buffer regeneration end to
- *     end through the binary's embedded SPA + WASM.
- *   - WITHOUT the param: clicking the blockquote opens the WHOLE quote WITH `>`
- *     markers (Phase-2 locked, prefixing-atomic) — proving the unlock is gated.
+ *     markers), and the breadcrumb navigator chip is visible — proving leaf
+ *     resolution + nested-buffer regeneration end to end through the binary's
+ *     embedded SPA + WASM, with no query param required.
+ *   - WITH the explicit `?nestingCursor=0` opt-out: clicking the blockquote
+ *     opens the WHOLE quote WITH `>` markers (Phase-2 locked, prefixing-atomic)
+ *     — proving the unlock can still be turned off.
  *
  * The boot path is covered at jsdom in
  * `q2-preview-spa/src/p3-2-nesting-cursor-spa.integration.test.tsx`; the
@@ -76,25 +79,70 @@ test.describe('P3.5 — SPA nesting-cursor resolution (real q2 preview binary)',
         );
     }
 
-    test('with ?nestingCursor=1: leaf-click opens the blockquote child with a clean buffer (no `>`)', async ({ page }) => {
-        // server.url already carries the CLI's `?page=index.qmd` query (previewServer
-        // waitForUrl captures it), so append nestingCursor with the correct separator —
-        // `${server.url}?nestingCursor=1` would produce the malformed `?page=index.qmd?nestingCursor=1`
-        // (nestingCursor parses to null → the unlock silently never engages).
+    test('default boot (no param): leaf-click opens the blockquote child in the RICH editor with the navigator INLINE in the toolbar (no overlap)', async ({ page }) => {
+        // bd-9x3zbuj8: the nesting cursor is now ON by default — no query param.
+        // Combined with rich-text being the SPA default, leaf-clicking a paragraph
+        // opens the rich editor (ProseMirror), and the hierarchy navigator renders
+        // INLINE in the toolbar row (Task 2) instead of as a floating chip.
+        await page.goto(server.url);
+        await waitForBlockquote(page);
+
+        const iframe = page.frameLocator('iframe');
+
+        // Leaf-click the blockquote CHILD (the inner paragraph). In unlocked mode
+        // this resolves to the child Para, which opens in the rich editor.
+        await iframe.locator('blockquote p[data-block-pool-id]').first().click();
+
+        // The rich editor (ProseMirror) — NOT a textarea — must open, showing the
+        // rendered quote text with no `>` source markers.
+        const pm = iframe.locator('.q2-richtext-editor .ProseMirror').first();
+        await pm.waitFor({ timeout: 10_000 });
+        await expect
+            .poll(async () => pm.textContent(), {
+                timeout: 8000,
+                message: 'rich editor should show the blockquote-child text',
+            })
+            .toContain('Quote line one.');
+        const text = (await pm.textContent()) ?? '';
+        expect(text, 'rich editor shows both lines').toContain('Quote line two.');
+        expect(text, 'rich editor renders text without `>` markers').not.toContain('>');
+        expect(text, 'leaf edit must not include the Intro paragraph').not.toContain('Intro paragraph.');
+
+        // Task 2: the navigator renders INLINE inside the toolbar row (to the right
+        // of the formatting buttons), and the standalone floating chip is suppressed
+        // — so the two never overlap.
+        const toolbar = iframe.locator('.q2-rt-toolbar').first();
+        await expect(toolbar, 'rich-text toolbar must be present').toBeVisible({ timeout: 5000 });
+        await expect(
+            toolbar.locator('.q2-breadcrumb-out'),
+            'navigator ◀ must be inside the toolbar row (inline breadcrumb)',
+        ).toBeVisible();
+        await expect(
+            toolbar.locator('.q2-crumb').last(),
+            'current crumb (¶) must be inside the toolbar row',
+        ).toHaveText('¶');
+        await expect(
+            iframe.locator('[data-testid="q2-breadcrumb-chip"]'),
+            'standalone floating chip must be suppressed when the inline breadcrumb shows',
+        ).toHaveCount(0);
+
+        await pm.press('Escape');
+    });
+
+    test('default nesting cursor with ?richText=0: leaf-click opens the blockquote child as a clean textarea buffer (no `>`)', async ({ page }) => {
+        // With rich text opted OUT, the nested leaf opens in the textarea — this is
+        // where the clean-buffer REGENERATION (markers stripped) is observable. Also
+        // proves the nesting-cursor default-on is independent of the rich-text flag.
         const sep = server.url.includes('?') ? '&' : '?';
-        await page.goto(`${server.url}${sep}nestingCursor=1`);
+        await page.goto(`${server.url}${sep}richText=0`);
         await waitForBlockquote(page);
 
         const iframe = page.frameLocator('iframe');
 
-        // Leaf-click the blockquote CHILD (the inner paragraph). In unlocked
-        // mode this resolves to the child, not the whole quote.
         await iframe.locator('blockquote p[data-block-pool-id]').first().click();
         const ta = iframe.locator('textarea').first();
         await ta.waitFor({ timeout: 10_000 });
 
-        // The textarea must carry the CLEAN regenerated buffer: both quote lines,
-        // and crucially NO `>` markers (regeneration stripped them).
         await expect
             .poll(async () => ta.inputValue(), {
                 timeout: 8000,
@@ -108,20 +156,29 @@ test.describe('P3.5 — SPA nesting-cursor resolution (real q2 preview binary)',
             value,
             'clean nested buffer must NOT contain `>` markers (leaf resolution + regeneration)',
         ).not.toContain('>');
-        // And it must not have pulled in the surrounding paragraphs.
         expect(value, 'leaf edit must not include the Intro paragraph').not.toContain('Intro paragraph.');
 
+        // The standalone navigator chip is the breadcrumb home in plain/textarea mode.
+        const chip = iframe.locator('[data-testid="q2-breadcrumb-chip"]');
+        await expect(chip, 'breadcrumb navigator chip must be visible by default').toBeVisible({ timeout: 5000 });
+
         await ta.press('Escape');
     });
 
-    test('without the param: clicking the blockquote opens the whole quote with `>` (locked)', async ({ page }) => {
-        await page.goto(server.url);
+    test('with ?nestingCursor=0 (opt-out): clicking the blockquote opens the whole quote with `>` (locked)', async ({ page }) => {
+        // server.url already carries the CLI's `?page=index.qmd` query (previewServer
+        // waitForUrl captures it), so append nestingCursor with the correct separator —
+        // `${server.url}?nestingCursor=0` would produce the malformed `?page=index.qmd?nestingCursor=0`
+        // (nestingCursor parses to null → defaults back ON, defeating the opt-out).
+        const sep = server.url.includes('?') ? '&' : '?';
+        await page.goto(`${server.url}${sep}nestingCursor=0`);
         await waitForBlockquote(page);
 
         const iframe = page.frameLocator('iframe');
 
-        // Click inside the blockquote. In locked mode (default), prefixing-atomic
-        // resolution opens the WHOLE quote as one buffer, markers included.
+        // Click inside the blockquote. In locked mode (explicit opt-out),
+        // prefixing-atomic resolution opens the WHOLE quote as one buffer,
+        // markers included.
         await iframe.locator('blockquote p[data-block-pool-id]').first().click();
         const ta = iframe.locator('textarea').first();
         await ta.waitFor({ timeout: 10_000 });

q2-preview-spa/e2e/nesting-cursor.spec.ts

@@ -275,16 +275,21 @@ const CONNECTION_BANNER_STYLE: React.CSSProperties = {
 };
 
 /**
- * P3.2: parse `?nestingCursor=1` from the boot URL search string.
- * Returns true only when the param is exactly `"1"`. Read-at-load;
- * the SPA does not react to URL changes after mount.
+ * Parse `?nestingCursor` from the boot URL (P3.2; default flipped in
+ * bd-9x3zbuj8). The hierarchical block navigator (BreadcrumbChip) is now the
+ * DEFAULT in q2 preview, matching hub-client (which defaults the
+ * `unlockNestingCursor` preference on): only an explicit `?nestingCursor=0`
+ * opts OUT; an absent param, `?nestingCursor=1`, or any other value keeps it
+ * on. Read-at-load; the SPA does not react to URL changes after mount.
+ *
+ * Safe to default on globally: the navigator self-gates on an active edit
+ * target, so a read-only preview (no `--allow-edit`) never shows it.
  */
-function parseNestingCursorParam(search: string): boolean {
-  if (!search) return false;
+export function parseNestingCursorParam(search: string): boolean {
   try {
-    return new URLSearchParams(search).get('nestingCursor') === '1';
+    return new URLSearchParams(search).get('nestingCursor') !== '0';
   } catch {
-    return false;
+    return true;
   }
 }
 

q2-preview-spa/src/PreviewApp.tsx

@@ -193,7 +193,7 @@ describe('P3.2 SPA query param: ?nestingCursor=1 → iframe receives unlockNesti
     expect(mockRegenerateNestedBuffers).toHaveBeenCalledWith(CONTENT, AST);
   });
 
-  it('passes unlockNestingCursor: false (or absent) when no ?nestingCursor param', async () => {
+  it('passes unlockNestingCursor: true by default when no ?nestingCursor param (bd-9x3zbuj8)', async () => {
     Object.defineProperty(window, 'location', {
       value: {
         ...window.location,
@@ -214,8 +214,13 @@ describe('P3.2 SPA query param: ?nestingCursor=1 → iframe receives unlockNesti
     );
 
     const props = capturedIframeProps[capturedIframeProps.length - 1];
-    // No param → nestingCursor defaults to false → unlockNestingCursor should be false/absent.
-    expect(props?.unlockNestingCursor).toBeFalsy();
+    // The navigator is now default-ON (matching hub-client): no param ⇒
+    // unlockNestingCursor: true. It still self-gates on an edit target, so a
+    // read-only preview shows nothing.
+    expect(props?.unlockNestingCursor).toBe(true);
+    // On-path: with nestingCursor on AND non-empty content + AST, the nested
+    // buffer regen runs (same assertion as the ?nestingCursor=1 case).
+    expect(mockRegenerateNestedBuffers).toHaveBeenCalledWith(CONTENT, AST);
   });
 
   it('passes unlockNestingCursor: false when ?nestingCursor=0', async () => {

q2-preview-spa/src/p3-2-nesting-cursor-spa.integration.test.tsx

@@ -0,0 +1,40 @@
+/**
+ * The hierarchical block navigator (BreadcrumbChip) is now the DEFAULT in
+ * q2 preview, matching hub-client (which defaults the `unlockNestingCursor`
+ * preference on). Only an explicit `?nestingCursor=0` opts out (bd-9x3zbuj8).
+ * These assert that default-on / opt-out contract.
+ *
+ * Note: the navigator self-gates on an active edit target, so it only becomes
+ * visible when actually editing — i.e. under `q2 preview --allow-edit`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseNestingCursorParam } from './PreviewApp';
+
+describe('parseNestingCursorParam — the nesting navigator is the default', () => {
+  it('defaults ON when no query string is present', () => {
+    expect(parseNestingCursorParam('')).toBe(true);
+  });
+
+  it('defaults ON when the nestingCursor param is absent', () => {
+    expect(parseNestingCursorParam('?page=index.qmd')).toBe(true);
+  });
+
+  it('stays ON for ?nestingCursor=1', () => {
+    expect(parseNestingCursorParam('?nestingCursor=1')).toBe(true);
+  });
+
+  it('turns OFF only for the explicit ?nestingCursor=0 opt-out', () => {
+    expect(parseNestingCursorParam('?nestingCursor=0')).toBe(false);
+  });
+
+  it('keeps ON for any other value (only "0" disables)', () => {
+    expect(parseNestingCursorParam('?nestingCursor=true')).toBe(true);
+    expect(parseNestingCursorParam('?nestingCursor=')).toBe(true);
+  });
+
+  it('works mixed with other params', () => {
+    expect(parseNestingCursorParam('?page=a.qmd&nestingCursor=0&richText=1')).toBe(false);
+    expect(parseNestingCursorParam('?page=a.qmd&richText=0')).toBe(true);
+  });
+});