fix(preview): flip edit chrome below the block when cropped at the viewport top (bd-pvcnea83)

Editing the first block of a title-less document (or any block scrolled near the
viewport top) cropped the floating edit chrome: the rich-text toolbar and the
standalone breadcrumb chip float ABOVE the edit box (`bottom:100%`), so for a
block flush against the top of the scroll area they landed above the viewport
(scrollTop already 0) and were clipped — only a sliver showed. The inline nesting
breadcrumb lives in the toolbar, so it cropped too.

Collision-aware flip: when there isn't room above
(`surfaceTop - chromeHeight - gap < 0`, viewport-relative), render the chrome
BELOW the block instead. Parity-neutral (no change to document spacing) and
generalizes to any near-top block, not just the literal first one.

- New pure helper `editChromeGeometry.shouldPlaceChromeBelow` (unit-tested).
- `RichTextToolbar`: useLayoutEffect measures the edit box top + toolbar height
  and adds `q2-rt-toolbar-below` (`top:100%`) when it would clip; guarded on a
  non-zero measured height so degenerate (jsdom) layouts keep the default above.
- `BreadcrumbChip`: the geometry effect flips `top` below the surface under the
  same condition (guarded on `sRect.height > 0`); horizontal left-spill geometry
  unchanged.

Both decide from the surface's stable top (not the chrome's flipped position), so
there is no flip/re-measure loop.

Verified end-to-end in the q2 binary: editing the first paragraph flips the
toolbar below (top 48.5, uncropped); editing a first code block flips the
standalone chip below (top 83.8, uncropped). e2e:
q2-preview-spa/e2e/edit-chrome-placement.spec.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cscheid

q2-preview-spa/e2e/edit-chrome-placement.spec.ts

@@ -0,0 +1,99 @@
+/**
+ * bd-pvcnea83 — floating edit chrome must not be cropped at the top of the
+ * viewport. Editing the first block of a title-less document (flush against the
+ * scroll-area top) previously clipped the chrome, which floats ABOVE the edit
+ * box (`bottom:100%`), above the viewport top with no way to scroll up to it.
+ * The fix flips the chrome BELOW the block when there's no room above.
+ *
+ * Real-binary e2e (drives target/debug/q2 via startPreviewServer). The pure
+ * placement threshold is unit-tested in
+ * ts-packages/preview-renderer/src/q2-preview/editChromeGeometry.test.ts; jsdom
+ * rects are degenerate, so the actual flip is only observable here.
+ *
+ * Build chain prerequisite (the binary does NOT auto-rebuild the embedded SPA):
+ *   cargo xtask build-q2-preview-spa
+ *   cargo build -p quarto --bin q2
+ */
+
+import { test, expect, type Page } from '@playwright/test';
+import { startPreviewServer, type PreviewServerHandle } from './helpers/previewServer';
+
+let server: PreviewServerHandle;
+
+/** Viewport-relative top of an element inside the preview iframe (0 = top of the
+ *  visible scroll area). A clipped-above-the-top element has a negative top. */
+async function iframeRectTop(page: Page, selector: string): Promise<number> {
+    return page.frameLocator('iframe').locator(selector).first().evaluate(
+        (el) => el.getBoundingClientRect().top,
+    );
+}
+
+test.describe('bd-pvcnea83 — edit chrome flips below at the top of the viewport', () => {
+    test.setTimeout(120_000);
+
+    test.afterEach(async () => {
+        await server?.stop();
+    });
+
+    test('rich-text toolbar: editing the first (title-less) paragraph flips the toolbar below, uncropped', async ({ page }) => {
+        server = await startPreviewServer({
+            allowEdit: true,
+            fixtureFiles: [{
+                path: 'index.qmd',
+                // No title front matter: the first paragraph is flush against the top.
+                content: 'First paragraph at the very top.\n\nSecond paragraph.\n',
+            }],
+        });
+        await page.goto(server.url);
+        const iframe = page.frameLocator('iframe');
+        await page.waitForFunction(() => {
+            const inner = document.querySelector('iframe')?.contentDocument;
+            return inner?.querySelector('p[data-block-pool-id]') != null;
+        }, null, { timeout: 30_000 });
+
+        await iframe.locator('p[data-block-pool-id]').first().click();
+
+        const toolbar = iframe.locator('.q2-rt-toolbar').first();
+        await toolbar.waitFor({ timeout: 10_000 });
+
+        // Flipped below (the collision-avoidance class) ...
+        await expect(toolbar, 'toolbar must flip below at the top of the document')
+            .toHaveClass(/q2-rt-toolbar-below/);
+        // ... and consequently not cropped above the viewport top.
+        await expect
+            .poll(() => iframeRectTop(page, '.q2-rt-toolbar'), {
+                timeout: 8000,
+                message: 'toolbar top must be >= 0 (not clipped above the viewport)',
+            })
+            .toBeGreaterThanOrEqual(0);
+    });
+
+    test('standalone breadcrumb chip: editing a first (title-less) code block flips the chip below, uncropped', async ({ page }) => {
+        server = await startPreviewServer({
+            allowEdit: true,
+            fixtureFiles: [{
+                path: 'index.qmd',
+                // First block is a code block (non-rich) → textarea + standalone chip.
+                content: '```python\nx = 1\ny = 2\n```\n\nA paragraph after.\n',
+            }],
+        });
+        await page.goto(server.url);
+        const iframe = page.frameLocator('iframe');
+        await page.waitForFunction(() => {
+            const inner = document.querySelector('iframe')?.contentDocument;
+            return inner?.querySelector('[data-block-pool-id]') != null;
+        }, null, { timeout: 30_000 });
+
+        await iframe.locator('[data-block-pool-id]').first().click();
+        await iframe.locator('#q2-active-edit-region textarea').first().waitFor({ timeout: 10_000 });
+
+        const chip = iframe.locator('[data-testid="q2-breadcrumb-chip"]');
+        await chip.waitFor({ timeout: 5000 });
+        await expect
+            .poll(() => iframeRectTop(page, '[data-testid="q2-breadcrumb-chip"]'), {
+                timeout: 8000,
+                message: 'standalone chip top must be >= 0 (not clipped above the viewport)',
+            })
+            .toBeGreaterThanOrEqual(0);
+    });
+});

ts-packages/preview-renderer/src/q2-preview/BreadcrumbChip.tsx

@@ -57,6 +57,10 @@ import { buildAncestorPath, currentSourceNodeType } from './nestingNav';
 import type { AncestorCrumb } from './nestingNav';
 import { BreadcrumbCrumbs, type CrumbDisplayItem } from './BreadcrumbCrumbs';
 import { richEditorActiveForType } from './richTextSupport';
+import { shouldPlaceChromeBelow } from './editChromeGeometry';
+
+/** Gap (px) between the chip and the surface when flipped below it (bd-pvcnea83). */
+const CHIP_FLIP_GAP = 4;
 
 // ── Constants ──────────────────────────────────────────────────────────────────
 
@@ -255,9 +259,20 @@ export function BreadcrumbChip(): React.ReactElement | null {
         );
         const displayItems = selectDisplayItems(crumbs, slots);
 
-        // --- Chip top: bottom edge flush at surface top ---
+        // --- Chip top: above the surface by default; flip below when clipped ---
+        // Default: bottom edge flush at the surface top (top = surfaceTop − chipH).
+        // But for a surface flush against the viewport top (e.g. the first block of
+        // a title-less document) that lands above the scroll area and is cropped, so
+        // flip BELOW the surface instead (bd-pvcnea83). Decide from the surface's
+        // viewport-relative top (sRect.top), guarded on real geometry so jsdom's
+        // zero-rects keep the default 'above' placement.
         const chipH = chipRef.current?.getBoundingClientRect().height ?? 0;
-        const top = surfaceTop - chipH;
+        const haveRealGeometry = sRect.height > 0;
+        const flipBelow = haveRealGeometry
+            && shouldPlaceChromeBelow(sRect.top, chipH, CHIP_FLIP_GAP);
+        const top = flipBelow
+            ? (sRect.bottom - hostRect.top) + CHIP_FLIP_GAP // below the surface
+            : surfaceTop - chipH;                           // above (default)
 
         setGeom({ top, chipLeft, bandWidth, displayItems });
     }, [active, et?.anchorR0, et?.anchorR1, ctx?.activeEditRegionRef, ctx?.sourceIndex]);

ts-packages/preview-renderer/src/q2-preview/editChromeGeometry.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Unit tests for shouldPlaceChromeBelow (bd-pvcnea83): floating edit chrome
+ * flips below the surface when there isn't room above it at the viewport top.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { shouldPlaceChromeBelow } from './editChromeGeometry';
+
+describe('shouldPlaceChromeBelow', () => {
+  it('flips below when the chrome would clip above the viewport top (the measured first-block case)', () => {
+    // editor top 15, toolbar height 26, gap 4 → 15 - 26 - 4 = -15 < 0.
+    expect(shouldPlaceChromeBelow(15, 26, 4)).toBe(true);
+  });
+
+  it('stays above when there is ample room above', () => {
+    expect(shouldPlaceChromeBelow(100, 26, 4)).toBe(false);
+  });
+
+  it('stays above with exactly enough room (chromeHeight + gap)', () => {
+    // surfaceTop === chromeHeight + gap → 30 - 26 - 4 = 0, not < 0.
+    expect(shouldPlaceChromeBelow(30, 26, 4)).toBe(false);
+  });
+
+  it('flips below one pixel short of enough room', () => {
+    expect(shouldPlaceChromeBelow(29, 26, 4)).toBe(true);
+  });
+
+  it('flips below for a surface flush at the viewport top', () => {
+    expect(shouldPlaceChromeBelow(0, 26, 4)).toBe(true);
+  });
+});

ts-packages/preview-renderer/src/q2-preview/editChromeGeometry.ts

@@ -0,0 +1,25 @@
+/**
+ * editChromeGeometry.ts — shared vertical-placement geometry for floating edit
+ * chrome (the rich-text toolbar and the standalone breadcrumb chip). Pure (no
+ * DOM, no React) so it is unit-testable; the components measure rects and call
+ * in. bd-pvcnea83.
+ */
+
+/**
+ * True when floating chrome of `chromeHeight` placed ABOVE a surface whose
+ * viewport-relative top edge is `surfaceTop` would be clipped above the viewport
+ * top — i.e. there isn't `chromeHeight + gap` of room above it. The caller then
+ * flips the chrome BELOW the surface instead.
+ *
+ * `surfaceTop` is the surface's `getBoundingClientRect().top` (viewport
+ * coordinates; in the preview iframe, 0 is the top of the visible scroll area).
+ * Computing from the *surface's* top (which doesn't move when the chrome flips)
+ * keeps the decision stable — no flip/re-measure loop.
+ */
+export function shouldPlaceChromeBelow(
+  surfaceTop: number,
+  chromeHeight: number,
+  gap: number,
+): boolean {
+  return surfaceTop - chromeHeight - gap < 0;
+}

ts-packages/preview-renderer/src/q2-preview/richtext/RichTextToolbar.tsx

@@ -13,8 +13,12 @@
 // input DOES take focus; the editor's commit is scoped to "focus left the whole
 // edit box" (see RichTextEditor), so focusing the input keeps the session open.
 
-import { useEffect, useRef, useState, type MouseEvent, type ReactNode } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState, type MouseEvent, type ReactNode } from 'react';
 import type { Editor } from '@tiptap/core';
+import { shouldPlaceChromeBelow } from '../editChromeGeometry';
+
+/** Gap (px) between the toolbar and the edit box, matching the CSS margin. */
+const TOOLBAR_GAP = 4;
 
 interface MarkSpec {
   name: string;
@@ -51,6 +55,26 @@ export function RichTextToolbar({
     };
   }, [editor]);
 
+  // Vertical placement (bd-pvcnea83): the toolbar floats ABOVE the edit box by
+  // default, but flips BELOW when there isn't room above (e.g. editing the first
+  // block of a title-less document, flush against the viewport top — otherwise it
+  // is clipped above the scroll area, with no way to scroll up to it).
+  const toolbarRef = useRef<HTMLDivElement | null>(null);
+  const [placeBelow, setPlaceBelow] = useState(false);
+  useLayoutEffect(() => {
+    const tb = toolbarRef.current;
+    const box = tb?.closest('.q2-richtext-editor');
+    if (!tb || !box) return;
+    const height = tb.offsetHeight;
+    // Degenerate layout (jsdom zero-rects): keep the default 'above' placement.
+    if (height <= 0) return;
+    const surfaceTop = box.getBoundingClientRect().top;
+    setPlaceBelow(shouldPlaceChromeBelow(surfaceTop, height, TOOLBAR_GAP));
+    // Mount-only: the toolbar remounts per edit target, and the edit box's top is
+    // stable for a given target, so a single measurement suffices.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   const [linkOpen, setLinkOpen] = useState(false);
   const [linkUrl, setLinkUrl] = useState('');
   const linkInputRef = useRef<HTMLInputElement | null>(null);
@@ -103,7 +127,11 @@ export function RichTextToolbar({
   };
 
   return (
-    <div className="q2-rt-toolbar" contentEditable={false}>
+    <div
+      ref={toolbarRef}
+      className={`q2-rt-toolbar${placeBelow ? ' q2-rt-toolbar-below' : ''}`}
+      contentEditable={false}
+    >
       {!linkOpen ? (
         <>
           {MARKS.map((m) => (

ts-packages/preview-renderer/src/q2-preview/richtext/styles.ts

@@ -78,6 +78,15 @@ const CSS = `
   font-size: 0.8rem;
   line-height: 1;
 }
+/* bd-pvcnea83: flip below the edit box when there is no room above (e.g. the
+   first block of a title-less document, flush against the viewport top — the
+   default bottom:100% placement would clip the toolbar above the scroll area). */
+.q2-rt-toolbar.q2-rt-toolbar-below {
+  bottom: auto;
+  top: 100%;
+  margin-bottom: 0;
+  margin-top: 4px;
+}
 .q2-rt-tb-btn {
   appearance: none;
   border: none;