Merge pull request #346 from quarto-dev/bugfix/bd-pvcnea83-edit-chrome-top-crop

Fix edit chrome cropped at top of viewport for first/top block (bd-pvcnea83)

Author: cscheid

claude-notes/plans/2026-06-25-edit-chrome-top-crop.md

@@ -0,0 +1,88 @@
+# Fix: edit chrome cropped at the top of the viewport
+
+**Strand:** bd-pvcnea83
+**Date:** 2026-06-25
+**Status:** in progress
+
+## Problem (confirmed in the binary)
+
+Editing the first block of a title-less document (or any block scrolled near the
+viewport top) crops the floating edit chrome. The rich-text toolbar is
+`position:absolute; bottom:100%; margin-bottom:4px` (floats *above* the edit
+box); for a block flush against the top of the scroll area it lands at negative
+`top` (above the iframe viewport, `scrollTop` already 0) and is clipped — only a
+sliver shows. Measured: editor `top:15`, toolbar `top:-15.4 → bottom:11`
+(height 26.4). The inline nesting breadcrumb lives in the toolbar, so it crops
+too. The standalone `BreadcrumbChip` (non-rich blocks at the top) has the same
+top-crop: its geometry sets `top = surfaceTop − chipH`, negative for a top
+surface.
+
+## Approach: collision-aware flip (above → below)
+
+Standard floating-toolbar behavior. When there isn't room above
+(`surfaceTop − chromeHeight − gap < 0`, viewport-relative), render the chrome
+**below** the block instead of above. While editing a top block the chrome then
+sits just under it (briefly over the next block), fully visible; the edited text
+is never covered. Parity-neutral (no change to the rendered/preview document
+spacing). Generalizes correctly to any near-top block, not just the literal
+first one.
+
+Shared pure helper (mirrors the chip's existing `computeChipGeometry` pattern):
+
+```ts
+// editChromeGeometry.ts
+export function shouldPlaceChromeBelow(surfaceTop: number, chromeHeight: number, gap: number): boolean {
+  return surfaceTop - chromeHeight - gap < 0;
+}
+```
+
+- **Toolbar** (`RichTextToolbar`): `useLayoutEffect` measures the
+  `.q2-richtext-editor` box's viewport top + the toolbar's height; if it would
+  clip above, set a `q2-rt-toolbar-below` class (`top:100%; bottom:auto;
+  margin-top:4px`). Guard: skip when `offsetHeight <= 0` (degenerate jsdom rects)
+  so the default `above` placement is kept there.
+- **Chip** (`BreadcrumbChip`): in the geometry effect, when
+  `shouldPlaceChromeBelow(sRect.top, chipH, GAP)` (and real geometry —
+  `sRect.height > 0`), set `top = (sRect.bottom − hostRect.top) + GAP` (below)
+  instead of `surfaceTop − chipH` (above). Horizontal left-spill geometry is
+  unchanged.
+
+Both compute placement from the *surface's* stable top (not the chrome's flipped
+position), so there is no flip/re-measure loop.
+
+## Tests (TDD)
+
+1. **Unit (RED first):** `editChromeGeometry.test.ts` — `shouldPlaceChromeBelow`
+   true for `(15, 26, 4)` (the measured case), false for `(100, 26, 4)`, and
+   boundary cases.
+2. **Real-binary e2e:** title-less fixture; edit the first block →
+   - rich Para: `.q2-rt-toolbar` has `q2-rt-toolbar-below` and its rect top ≥ 0
+     (not clipped);
+   - first block is a code block (non-rich): standalone chip rect top ≥ 0
+     (placed below).
+   Follow the established floating-chrome testing pattern (pure unit + real e2e;
+   jsdom rects are degenerate, so vertical placement is not asserted in jsdom).
+
+## Notes / known interactions
+
+- The hub-client `q2-preview-breadcrumb-geometry` e2e asserts "chip above
+  surface" for a TOP paragraph. That suite is already red (bd-fpys25b0,
+  rich-text default-on) and will need its top-block expectation updated to the
+  flipped (below) placement when bd-fpys25b0 is addressed. Out of scope here;
+  noted on that strand.
+
+## Work items
+
+- [x] `editChromeGeometry.ts` + unit test (`shouldPlaceChromeBelow`, 5 cases)
+- [x] Toolbar: `useLayoutEffect` measure + `q2-rt-toolbar-below` class + CSS
+- [x] Chip: flip `top` below when clipped (guarded on `sRect.height > 0`)
+- [x] preview-renderer unit (505) + integration (515) suites green
+- [x] Real-binary e2e on title-less fixtures (toolbar + chip),
+      `q2-preview-spa/e2e/edit-chrome-placement.spec.ts` (2 tests); full spa e2e
+      suite green (39). Verified live in Chrome: toolbar flips below (top 48.5,
+      uncropped) for the first paragraph; chip flips below (top 83.8, uncropped)
+      for a first code block.
+- [x] hub-client build + unit (662) + integration (76) green;
+      `cargo xtask verify --skip-hub-build` green (one flaky pampa-oracle spike
+      failure on first run, passed on re-run — unrelated to this change)
+- [ ] hub-client/changelog.md (two-commit) — pending commit

hub-client/changelog.md

@@ -17,6 +17,7 @@ be in reverse chronological order (latest first).
 
 ### 2026-06-25
 
+- [`d6066dc9`](https://github.com/quarto-dev/q2/commits/d6066dc9): The editing toolbar (and breadcrumb navigator) no longer gets cut off when you edit the very first block of a document with no title — it now flips below the block when there isn't room above.
 - [`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

hub-client/e2e/q2-preview-breadcrumb-geometry.spec.ts

@@ -65,11 +65,14 @@ test.describe('Phase 4 — Breadcrumb chip geometry (real browser)', () => {
     });
 
     // -------------------------------------------------------------------------
-    // Existing vertical test (P3.5 tier i item 1) — kept byte-for-byte.
-    // Guards: chip sits above the active edit surface, never occluding line 1.
+    // Vertical placement at the top of the document (P3.5 tier i item 1).
+    // The first block is flush against the viewport top, so there is no room
+    // ABOVE it for the chip — it must flip BELOW the edit surface rather than be
+    // clipped above the scroll area (bd-pvcnea83). Guards: chip flipped below,
+    // anchored near the surface bottom, and never clipped above the viewport.
     // -------------------------------------------------------------------------
 
-    test('chip sits above the active edit surface, never occluding line 1', async ({ page }) => {
+    test('chip flips below the edit surface at the document top (uncropped, never occluding the edited text)', async ({ page }) => {
         // Enable the nesting-cursor BEFORE any navigation — addInitScript re-applies
         // on every document load, including the iframe.
         await page.addInitScript(() => {
@@ -129,30 +132,33 @@ test.describe('Phase 4 — Breadcrumb chip geometry (real browser)', () => {
         // TypeScript narrowing (already asserted above).
         if (!chipBox || !taBox) throw new Error('impossible — asserted above');
 
+        const surfaceBottom = taBox.y + taBox.height;
         console.log(
             `Chip box: y=${chipBox.y.toFixed(2)}, bottom=${(chipBox.y + chipBox.height).toFixed(2)}, height=${chipBox.height.toFixed(2)}\n` +
-            `Textarea box: y=${taBox.y.toFixed(2)}`,
+            `Textarea box: y=${taBox.y.toFixed(2)}, bottom=${surfaceBottom.toFixed(2)}`,
         );
 
-        // Step 5: assertions.
+        // Step 5: assertions (bd-pvcnea83 — flipped-below placement at the top).
         const TOL = 2;
 
-        // (a) Chip bottom is AT OR ABOVE surface top — never occludes line 1.
+        // (a) Chip top is AT OR BELOW the surface bottom — the chip flipped below the
+        //     edit box (no room above at the document top), so it never overlaps the
+        //     edited text.
         expect(
-            chipBox.y + chipBox.height,
-            `chip bottom (${(chipBox.y + chipBox.height).toFixed(2)}) must be ≤ textarea top (${taBox.y.toFixed(2)}) + ${TOL}px tolerance`,
-        ).toBeLessThanOrEqual(taBox.y + TOL);
+            chipBox.y,
+            `chip top (${chipBox.y.toFixed(2)}) must be ≥ surface bottom (${surfaceBottom.toFixed(2)}) − ${TOL}px — flipped below, not overlapping the surface`,
+        ).toBeGreaterThanOrEqual(surfaceBottom - TOL);
 
-        // (b) Chip bottom is anchored close to the surface top (not floating far above).
+        // (b) Chip is anchored close to the surface bottom (not floating far below).
         //     The gap must be less than ~one chip-gap (12 px) so the chip is still
         //     visually attached and the useLayoutEffect positioning is doing real work.
         expect(
-            taBox.y - (chipBox.y + chipBox.height),
-            `chip must be anchored near the surface top — gap (${(taBox.y - (chipBox.y + chipBox.height)).toFixed(2)}px) must be < 12px`,
+            chipBox.y - surfaceBottom,
+            `chip must be anchored near the surface bottom — gap (${(chipBox.y - surfaceBottom).toFixed(2)}px) must be < 12px`,
         ).toBeLessThan(12);
 
-        // (c) At the document top, the chip sits in the page margin (not clipped above
-        //     the viewport — `top` is clamped to ≥ 0 in real CSS).
+        // (c) The chip is not clipped above the viewport top (the whole point of the
+        //     flip — `top` is ≥ 0 in real CSS).
         expect(
             chipBox.y,
             `chip top (${chipBox.y.toFixed(2)}) must be ≥ 0 — not clipped above the viewport`,
@@ -162,6 +168,80 @@ test.describe('Phase 4 — Breadcrumb chip geometry (real browser)', () => {
         await iframe.locator('textarea').first().press('Escape');
     });
 
+    // -------------------------------------------------------------------------
+    // Companion to the above: the flip is CONDITIONAL. When a block has room
+    // above it (not at the document top), the chip stays in its default ABOVE
+    // placement — proving bd-pvcnea83 only flips when there isn't room, rather
+    // than always rendering below.
+    // -------------------------------------------------------------------------
+
+    test('chip stays above the edit surface when there is room above (non-top block)', async ({ page }) => {
+        await page.addInitScript(() => {
+            localStorage.setItem('quarto-hub:preferences', JSON.stringify({
+                version: 1,
+                scrollSyncEnabled: true,
+                errorOverlayCollapsed: true,
+                colorScheme: 'auto',
+                unlockNestingCursor: true,
+            }));
+        });
+
+        const serverUrl = getServerUrl();
+        // A title plus several paragraphs gives a later paragraph ample headroom
+        // above it, so the chip is NOT clipped and keeps its default above placement.
+        const QMD = [
+            '---',
+            'title: With a title',
+            'format: q2-preview',
+            '---',
+            '',
+            'Para one.',
+            '',
+            'Para two.',
+            '',
+            'Para three.',
+            '',
+            'Para four.',
+            '',
+        ].join('\n');
+
+        const docId = await createProjectOnServer(serverUrl, [
+            { path: '_quarto.yml', content: 'project:\n  type: default\n', contentType: 'text' },
+            { path: 'breadcrumb-above.qmd', content: QMD, contentType: 'text' },
+        ]);
+
+        const iframe = await openFile(page, serverUrl, docId, 'breadcrumb-above.qmd');
+
+        // Edit a LATER paragraph (index 2 → "Para three.") — well below the top.
+        await iframe.locator('p[data-block-pool-id]').nth(2).click();
+        await iframe.locator('textarea').first().waitFor({ timeout: 10_000 });
+        const chip = iframe.locator('[data-testid="q2-breadcrumb-chip"]');
+        await chip.waitFor({ timeout: 5000 });
+
+        const chipBox = await chip.boundingBox();
+        const taBox = await iframe.locator('textarea').first().boundingBox();
+        if (!chipBox || !taBox) throw new Error('chip/textarea bounding box must be non-null');
+
+        console.log(
+            `Chip box: y=${chipBox.y.toFixed(2)}, bottom=${(chipBox.y + chipBox.height).toFixed(2)}\n` +
+            `Textarea box: y=${taBox.y.toFixed(2)}`,
+        );
+
+        const TOL = 2;
+        // Default ABOVE placement: chip bottom sits at or above the surface top.
+        expect(
+            chipBox.y + chipBox.height,
+            `chip bottom (${(chipBox.y + chipBox.height).toFixed(2)}) must be ≤ surface top (${taBox.y.toFixed(2)}) + ${TOL}px — default above placement`,
+        ).toBeLessThanOrEqual(taBox.y + TOL);
+        // Anchored near the surface top.
+        expect(
+            taBox.y - (chipBox.y + chipBox.height),
+            `chip must be anchored near the surface top — gap (${(taBox.y - (chipBox.y + chipBox.height)).toFixed(2)}px) must be < 12px`,
+        ).toBeLessThan(12);
+
+        await iframe.locator('textarea').first().press('Escape');
+    });
+
     // -------------------------------------------------------------------------
     // 4a — DESIGN GO/NO-GO GATE (not a regression guard).
     //

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]);