@akinon/pz-theme 2.0.79-rc.0 → 2.0.79

package/CHANGELOG.md

@@ -1,38 +1,17 @@
 # @akinon/pz-theme
 
-## 2.0.79-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.79-rc.0
-  - @akinon/theme-contract@2.0.79-rc.0
+## 2.0.79
+
+### Patch Changes
+
+- 945e153d: ZERO-4669: Keep the designer action toolbar reachable at the top of the canvas.
+
+  The toolbar is portaled to `<body>` (ZERO-4651), so nothing can clip it any more — but hanging above its host still draws it at a negative y when the host sits at the viewport top: the first section at scroll 0, and any section in a chrome slot pinned with `position: sticky; top: 0`, which reports the same box at every scroll position and so was unreachable permanently. The toolbar now flips inside its host when there is not enough room above it on screen, while the portal frame stays pinned to the host's box.
+
+  Also adds the `@akinon/pz-theme` content globs to the app's Tailwind config: without them the toolbar's own utilities (`-top-0.5`, `top-1`, `-translate-y-full`, `bg-[#4482ff]`) are never generated, so the designer chrome rendered unstyled. The app template carries the same two lines, so scaffolded brand apps are not shipping unstyled designer chrome either.
+
+  - @akinon/next@2.0.79
+  - @akinon/theme-contract@2.0.79
 
 ## 2.0.78
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.79-rc.0",
+  "version": "2.0.79",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.79-rc.0",
+    "@akinon/next": "2.0.79",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.79-rc.0",
+    "@akinon/theme-contract": "2.0.79",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.79-rc.0",
+    "@akinon/next": "2.0.79",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/chrome/__tests__/composition-source.test.ts

@@ -27,12 +27,17 @@ jest.mock('react', () => {
 const getWidgetData = jest.fn();
 const getWidgetSchemaData = jest.fn();
 const getCollectionWidgetData = jest.fn();
+// Named preview snapshot reader (draft mode only). Resolves null by default:
+// "not a preview", the live path.
+const getPreviewSnapshot = jest.fn(async () => null as unknown);
 
 jest.mock('@akinon/next/data/server', () => ({
   getWidgetData: (...args: unknown[]) => getWidgetData(...args),
   getWidgetSchemaData: (...args: unknown[]) => getWidgetSchemaData(...args),
   getCollectionWidgetData: (...args: unknown[]) =>
-    getCollectionWidgetData(...args)
+    getCollectionWidgetData(...args),
+  getPreviewSnapshot: (...args: unknown[]) =>
+    (getPreviewSnapshot as (...a: unknown[]) => unknown)(...args)
 }));
 
 jest.mock(
@@ -123,3 +128,76 @@ describe('shared placeholder widget fetch', () => {
     expect(attempts).toBe(3);
   });
 });
+
+describe('named preview snapshots', () => {
+  beforeEach(() => {
+    getWidgetData.mockReset();
+    getWidgetSchemaData.mockReset();
+    getCollectionWidgetData.mockReset();
+    getPreviewSnapshot.mockReset();
+    getPreviewSnapshot.mockResolvedValue(null);
+  });
+
+  const blob = {
+    version: 1,
+    themeSettings: { mainMenuSticky: true },
+    dataSources: [],
+    sections: [
+      {
+        id: 'sec-preview',
+        type: 'custom',
+        label: 'Preview hero',
+        properties: {},
+        styles: {},
+        blocks: [],
+        order: 0
+      }
+    ]
+  };
+
+  it('composes the slot and loads the sections from the blob, never the live widget', async () => {
+    getPreviewSnapshot.mockResolvedValue(blob);
+    getWidgetData.mockResolvedValue(placeholderPayload('preview-slot-a'));
+
+    const state = await getSlugCompositionState('preview-slot-a');
+    const loaded = await loadPlaceholderSections('preview-slot-a');
+
+    expect(state).toEqual({ kind: 'composed', sectionCount: 1 });
+    expect(loaded?.sections.map((s) => s.id)).toEqual(['sec-preview']);
+    expect(loaded?.placeholderId).toBe('preview-slot-a');
+    expect(loaded?.themeSettings).toEqual({ mainMenuSticky: true });
+    // The blob owns the render: no per-section or theme-config reads.
+    expect(getWidgetData).not.toHaveBeenCalled();
+    expect(getWidgetSchemaData).not.toHaveBeenCalled();
+  });
+
+  it('an empty blob withdraws the slot even when live is composed', async () => {
+    getPreviewSnapshot.mockResolvedValue({ ...blob, sections: [] });
+    getWidgetData.mockResolvedValue(placeholderPayload('preview-slot-b'));
+
+    expect(await getSlugCompositionState('preview-slot-b')).toEqual({
+      kind: 'empty'
+    });
+    expect((await loadPlaceholderSections('preview-slot-b'))?.sections).toEqual(
+      []
+    );
+  });
+
+  it('falls through to the live path without a blob or when the reader throws', async () => {
+    getPreviewSnapshot.mockRejectedValue(new Error('backend down'));
+    getWidgetData.mockResolvedValue(placeholderPayload('preview-slot-c'));
+    getWidgetSchemaData.mockResolvedValue({
+      schema: { 'sec-a': { metadata: { blocks: [] } } }
+    });
+
+    expect(await getSlugCompositionState('preview-slot-c')).toEqual({
+      kind: 'composed',
+      sectionCount: 1
+    });
+    expect(
+      (await loadPlaceholderSections('preview-slot-c'))?.sections.map(
+        (s) => s.id
+      )
+    ).toEqual(['sec-a']);
+  });
+});

package/src/chrome/__tests__/sticky-slot.test.tsx

@@ -27,6 +27,14 @@ jest.mock('../theme-config-source', () => ({
   getThemeConfig: () => themeConfig()
 }));
 
+// A named preview's snapshot owns the theme settings; null = not a preview.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const previewSnapshot = jest.fn<any, [string]>(() => null);
+
+jest.mock('../preview-snapshot-source', () => ({
+  getPlaceholderPreviewSnapshot: (slug: string) => previewSnapshot(slug)
+}));
+
 // The placeholder is an async server component that reaches for the data
 // layer; what the slot decides about itself is what is under test.
 jest.mock('../../theme-placeholder', () => ({
@@ -221,3 +229,35 @@ describe('ChromeSlot sticky', () => {
     expect(themeConfig).not.toHaveBeenCalled();
   });
 });
+
+describe('ChromeSlot sticky in a named preview', () => {
+  afterEach(() => {
+    cleanup();
+    previewSnapshot.mockReset();
+    previewSnapshot.mockReturnValue(null);
+  });
+
+  it('follows the preview snapshot, not the live theme-config', async () => {
+    compositionState.mockResolvedValue(composed);
+    themeConfig.mockResolvedValue({ settings: { mainMenuSticky: false } });
+    previewSnapshot.mockResolvedValue({
+      version: 1,
+      sections: [{ id: 'sec' }],
+      themeSettings: { mainMenuSticky: true }
+    });
+
+    await renderSlot({ slug: 'header', fallback: <div>brand</div> });
+
+    expect(slotElement('header').dataset.sticky).toBe('true');
+  });
+
+  it('falls back to the live theme-config when the preview has no blob', async () => {
+    compositionState.mockResolvedValue(composed);
+    themeConfig.mockResolvedValue({ settings: { mainMenuSticky: true } });
+    previewSnapshot.mockResolvedValue(null);
+
+    await renderSlot({ slug: 'header', fallback: <div>brand</div> });
+
+    expect(slotElement('header').dataset.sticky).toBe('true');
+  });
+});

package/src/chrome/chrome-slot.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import ThemePlaceholder from '../theme-placeholder';
 import { warnAboutUncomposedSlot } from './composition-state';
 import { getSlugCompositionState } from './composition-source';
+import { getPlaceholderPreviewSnapshot } from './preview-snapshot-source';
 import { getThemeConfig } from './theme-config-source';
 import { ChromeFallback } from './chrome-fallback';
 import { ChromeScrollState } from './scroll-state';
@@ -79,9 +80,16 @@ export default async function ChromeSlot({
   warnAboutUncomposedSlot(slug, state);
 
   // Only read when the mounting code said nothing, and memoized per request, so
-  // a page full of slots costs at most one theme-config read.
+  // a page full of slots costs at most one theme-config read. In a named
+  // preview the snapshot blob owns the theme settings (theme-config is never
+  // preview-transformed), so the pin must follow the blob the placeholder
+  // renders from — otherwise "sticky header" toggled in the preview would
+  // only show once published.
   const themeSettings =
-    sticky === undefined ? (await getThemeConfig()).settings : null;
+    sticky === undefined
+      ? (await getPlaceholderPreviewSnapshot(slug))?.themeSettings ??
+        (await getThemeConfig()).settings
+      : null;
   const pinned = resolveSlotSticky({
     slug,
     sticky,

package/src/chrome/composition-source.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 
 import { CompositionState, readCompositionState } from './composition-state';
+import { getPlaceholderPreviewSnapshot } from './preview-snapshot-source';
 import { getWidgetDataWithRetry } from './retrying-widget-data';
 
 // `React.cache` exists on the RSC-capable React this package renders under;
@@ -49,6 +50,16 @@ export const getPlaceholderWidget = cache
  */
 const load = async (slug: string): Promise<CompositionState> => {
   try {
+    // A named preview (draft mode) composes from its snapshot, not from the
+    // live placeholder: a slug composed only in the preview must still take
+    // the slot over there, and one emptied in the preview must give it back.
+    const preview = await getPlaceholderPreviewSnapshot(slug);
+    if (preview) {
+      return preview.sections.length > 0
+        ? { kind: 'composed', sectionCount: preview.sections.length }
+        : { kind: 'empty' };
+    }
+
     const data = await getPlaceholderWidget(slug);
 
     return readCompositionState(data);

package/src/chrome/preview-snapshot-source.ts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import * as serverData from '@akinon/next/data/server';
+
+/**
+ * Whole-placeholder snapshot the theme editor writes for a named preview
+ * (`<slug>-preview-<id>`, `preview_snapshot` attribute). Sections arrive in
+ * render shape. See akinon-next's `getPreviewSnapshot` for the contract.
+ */
+export interface PreviewSnapshot {
+  version: number;
+  savedAt?: string;
+  themeSettings?: Record<string, unknown> | null;
+  dataSources?: unknown[];
+  sections: unknown[];
+}
+
+type GetPreviewSnapshot = (args: {
+  slug: string;
+}) => Promise<PreviewSnapshot | null>;
+
+const fetchPreviewSnapshot = async (
+  slug: string
+): Promise<PreviewSnapshot | null> => {
+  // v1 cores predate widget preview: no reader means never a preview. The
+  // reader itself answers null outside draft mode or without a preview id.
+  const fn = (
+    serverData as unknown as { getPreviewSnapshot?: GetPreviewSnapshot }
+  ).getPreviewSnapshot;
+  if (!fn) return null;
+
+  try {
+    return (await fn({ slug })) ?? null;
+  } catch {
+    // A failed preview read must fall back to the live render, never blank it.
+    return null;
+  }
+};
+
+// `React.cache` exists on the RSC-capable React this package renders under;
+// fall back to the raw function on older cores, where correctness is identical
+// and the only cost is a second fetch.
+const cache = (React as { cache?: <T>(fn: T) => T }).cache;
+
+/**
+ * The one preview-snapshot read per placeholder per request — shared by the
+ * slot's composed/uncomposed decision and the section loader so the two can
+ * never disagree about which content a preview shows.
+ */
+export const getPlaceholderPreviewSnapshot = cache
+  ? cache(fetchPreviewSnapshot)
+  : fetchPreviewSnapshot;

package/src/components/__tests__/action-toolbar.test.tsx

@@ -0,0 +1,338 @@
+import React from 'react';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import ActionToolbar from '../action-toolbar';
+
+/**
+ * The toolbar is portaled to <body> and pinned onto its host's viewport box, so
+ * everything here is read off `document`, never off the render container, and
+ * the host has to carry `[data-block-id]` / `[data-section-id]` — that is the
+ * selector the toolbar resolves its host with.
+ *
+ * These are the placement cases; that the portal escapes every clipping
+ * declaration a composition can set is covered in
+ * `src/__tests__/designer-chrome-clipping.test.tsx`.
+ */
+
+/** Mirrors the component's own constants: 40px tall + the 2px `-top-0.5`. */
+const SPACE_NEEDED_ABOVE = 42;
+const CHROME_Z_BASE = 2147483000;
+
+const rectAt = (top: number, left = 40) => ({
+  top,
+  left,
+  right: left + 300,
+  bottom: top + 200,
+  width: 300,
+  height: 200,
+  x: left,
+  y: top
+});
+
+/**
+ * A complete rect for the host and a zero rect for everything else — the shape
+ * `getBoundingClientRect` really has. A partial mock leaves `rect.left`
+ * undefined, which used to turn the every-render measure into an infinite
+ * render loop; `nonFiniteHostRect` below pins the guard that stops it.
+ */
+const ZERO_RECT = {
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  width: 0,
+  height: 0,
+  x: 0,
+  y: 0
+};
+
+const mockHostRect = (rect: ReturnType<typeof rectAt>) =>
+  jest
+    .spyOn(Element.prototype, 'getBoundingClientRect')
+    .mockImplementation(function (this: Element) {
+      const value = this.hasAttribute('data-block-id') ? rect : ZERO_RECT;
+      return { ...value, toJSON: () => value } as DOMRect;
+    });
+
+const renderToolbar = (
+  props: Partial<React.ComponentProps<typeof ActionToolbar>> = {}
+) =>
+  render(
+    <div data-block-id="b1">
+      <ActionToolbar label="My Section" {...props} />
+    </div>
+  );
+
+const toolbarEl = () =>
+  document.querySelector('[data-action-toolbar]') as HTMLElement;
+
+const frameEl = () => toolbarEl().parentElement as HTMLElement;
+
+/** Every re-measure but a re-render is coalesced into a frame. */
+const flushFrame = () =>
+  act(() => {
+    jest.advanceTimersByTime(20);
+  });
+
+describe('ActionToolbar placement', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('hangs above the host when there is room above it on screen', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('-top-0.5');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+    expect(toolbarEl().className).not.toContain('top-1');
+  });
+
+  /**
+   * The case the portal alone does not solve. Hanging above a host at the
+   * viewport top draws the toolbar at y = -42, off-screen, and nothing scrolls
+   * above 0 — rename / duplicate / delete would be unreachable. A chrome slot
+   * pinned with `position: sticky; top: 0` reports this rect at *every* scroll
+   * position, so there it is unreachable permanently.
+   */
+  it('flips inside the host when the host sits at the viewport top', () => {
+    mockHostRect(rectAt(0));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    expect(toolbarEl().className).not.toContain('-translate-y-full');
+    expect(toolbarEl().className).not.toContain('-top-0.5');
+  });
+
+  /**
+   * The flip must be expressed in the toolbar's own classes and nowhere else.
+   * Clamping or offsetting the frame instead would break the contract that the
+   * frame is pinned to the host's box
+   * (`designer-chrome-clipping.test.tsx` → 'pins a nested block toolbar…').
+   */
+  it('leaves the frame pinned to the host box when the toolbar flips', () => {
+    mockHostRect(rectAt(0, 220));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    expect(frameEl().style.position).toBe('fixed');
+    expect(frameEl().style.top).toBe('0px');
+    expect(frameEl().style.left).toBe('220px');
+  });
+
+  it('flips one pixel short of the room it needs and not one pixel over', () => {
+    mockHostRect(rectAt(SPACE_NEEDED_ABOVE - 1));
+    const short = render(
+      <div data-block-id="b1">
+        <ActionToolbar label="My Section" />
+      </div>
+    );
+    expect(toolbarEl().className).toContain('top-1');
+    short.unmount();
+
+    mockHostRect(rectAt(SPACE_NEEDED_ABOVE));
+    renderToolbar();
+    expect(toolbarEl().className).toContain('-translate-y-full');
+  });
+
+  /**
+   * Documented limitation, asserted so that fixing it is a deliberate change:
+   * once the host's top has scrolled *past* the viewport edge, neither branch
+   * puts the toolbar on screen — flipped it lands at `origin.top + 4`. The
+   * in-tree predecessor had the same hole. The fix is to slide the toolbar
+   * down inside the host by a computed amount, which needs the host's height
+   * carried in the measured origin.
+   */
+  it('still flips, but cannot rescue a host scrolled above the viewport', () => {
+    mockHostRect(rectAt(-300));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    // The frame is where the host is, i.e. off-screen; the flip does not clamp.
+    expect(frameEl().style.top).toBe('-300px');
+  });
+
+  it('repositions and re-evaluates placement on scroll', () => {
+    const spy = mockHostRect(rectAt(200));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('200px');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(0));
+    fireEvent.scroll(window);
+    flushFrame();
+
+    expect(frameEl().style.top).toBe('0px');
+    expect(toolbarEl().className).toContain('top-1');
+    expect(toolbarEl().className).not.toContain('-translate-y-full');
+  });
+
+  it('repositions and re-evaluates placement on resize', () => {
+    const spy = mockHostRect(rectAt(0));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('0px');
+    expect(toolbarEl().className).toContain('top-1');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(200));
+    fireEvent.resize(window);
+    flushFrame();
+
+    expect(frameEl().style.top).toBe('200px');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+  });
+
+  /**
+   * Move Up / Move Down are buttons on this toolbar: they move the host to a
+   * different y without resizing it, scrolling it or touching its attributes,
+   * so no listener fires. The canvas re-renders, so a render has to be a
+   * measuring point too.
+   */
+  it('re-evaluates placement on a re-render that moved the host', () => {
+    const spy = mockHostRect(rectAt(200));
+    const { rerender } = renderToolbar();
+    expect(toolbarEl().className).toContain('-translate-y-full');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(0));
+    rerender(
+      <div data-block-id="b1">
+        <ActionToolbar label="My Section" isLocked />
+      </div>
+    );
+
+    expect(toolbarEl().className).toContain('top-1');
+  });
+
+  /**
+   * The measure runs on every render and its only brake is an unchanged
+   * origin, so a coordinate that is not a number (`NaN !== NaN`) would set a
+   * fresh origin every commit and render forever.
+   */
+  it('ignores an unreadable rect instead of re-rendering forever', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('200px');
+
+    jest.restoreAllMocks();
+    jest
+      .spyOn(Element.prototype, 'getBoundingClientRect')
+      .mockReturnValue({ top: 10 } as DOMRect);
+
+    expect(() => {
+      fireEvent.scroll(window);
+      flushFrame();
+    }).not.toThrow();
+
+    // Left exactly where the last good measurement put it.
+    expect(frameEl().style.top).toBe('200px');
+    expect(frameEl().style.left).toBe('40px');
+  });
+
+  it('marks the toolbar with data-action-toolbar for outside-click guards', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    // `accordion-block` reads this off the click target to tell chrome clicks
+    // from content clicks; portaled events still bubble through the React tree.
+    expect(toolbarEl()).toBeInTheDocument();
+  });
+});
+
+describe('ActionToolbar stacking', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  /**
+   * At <body> the toolbar no longer inherits the host's stacking context, so
+   * the frame carries an absolute z-index and `zIndex` is only the relative
+   * order of block chrome (default 30) over section chrome (20).
+   */
+  it('stacks the frame above page chrome and leaves the toolbar unstyled', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(frameEl().style.zIndex).toBe(String(CHROME_Z_BASE + 30));
+    expect(toolbarEl().style.zIndex).toBe('');
+  });
+
+  it('orders section chrome below block chrome', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar({ zIndex: 20 });
+
+    expect(frameEl().style.zIndex).toBe(String(CHROME_Z_BASE + 20));
+    expect(Number(frameEl().style.zIndex)).toBeLessThan(CHROME_Z_BASE + 30);
+  });
+
+  /**
+   * `zIndex` is added to a base that already sits just under the 32-bit
+   * maximum browsers clamp z-index to, so only a small range is usable: a
+   * larger value silently ties with everything else past the clamp instead of
+   * ordering above it.
+   */
+  it('keeps the default inside the range a browser can represent', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(Number(frameEl().style.zIndex)).toBeLessThanOrEqual(2147483647);
+  });
+});
+
+describe('ActionToolbar rename', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('starts rename on label click and commits the trimmed value on Enter', () => {
+    mockHostRect(rectAt(200));
+    const onRename = jest.fn();
+    renderToolbar({ onRename });
+
+    fireEvent.click(screen.getByText('My Section'));
+    const input = screen.getByDisplayValue('My Section');
+    fireEvent.change(input, { target: { value: '  Renamed  ' } });
+    fireEvent.keyDown(input, { key: 'Enter' });
+
+    expect(onRename).toHaveBeenCalledWith('Renamed');
+  });
+
+  it('cancels rename on Escape without calling onRename', () => {
+    mockHostRect(rectAt(200));
+    const onRename = jest.fn();
+    renderToolbar({ onRename });
+
+    fireEvent.click(screen.getByText('My Section'));
+    const input = screen.getByDisplayValue('My Section');
+    fireEvent.change(input, { target: { value: 'Changed' } });
+    fireEvent.keyDown(input, { key: 'Escape' });
+
+    expect(onRename).not.toHaveBeenCalled();
+    expect(screen.getByText('My Section')).toBeInTheDocument();
+  });
+
+  /**
+   * The renaming input's `border-2` makes the control strip 44px, so a
+   * measured height would move the flip threshold mid-interaction and could
+   * pull the toolbar out from under the cursor. The height is a constant
+   * precisely so it cannot.
+   */
+  it('does not move the toolbar when a rename starts', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar({ onRename: jest.fn() });
+    const before = toolbarEl().className;
+
+    fireEvent.click(screen.getByText('My Section'));
+
+    expect(toolbarEl().className).toBe(before);
+  });
+});

package/src/components/action-toolbar.tsx

@@ -30,6 +30,27 @@ const HOST_SELECTOR = '[data-block-id],[data-section-id]';
  */
 const CHROME_Z_BASE = 2147483000;
 
+/**
+ * The toolbar's own height, as a constant rather than a measurement: it is
+ * fully determined by this file's markup — the control strip is `h-10` and the
+ * label column is a `text-sm` 20px line box inside `p-2.5` — and nothing about
+ * the host or the composition can change it. Measuring would need a ref on an
+ * element that does not exist until `origin` is known, i.e. a second pass and
+ * a frame of wrong placement, and it would make the placement depend on
+ * `isRenaming` (the input's `border-2` makes the row 44px), so starting a
+ * rename could move the toolbar out from under the cursor.
+ */
+const TOOLBAR_HEIGHT = 40;
+
+/** The `-top-0.5` nudge above the host's edge, in pixels. */
+const TOOLBAR_TOP_OFFSET = 2;
+
+/**
+ * Room the toolbar needs above the host to be fully on screen. Hanging above,
+ * it occupies `[origin.top - 42, origin.top - 2]`.
+ */
+const SPACE_NEEDED_ABOVE = TOOLBAR_HEIGHT + TOOLBAR_TOP_OFFSET;
+
 // `useLayoutEffect` would warn during SSR; the toolbar only ever mounts in the
 // designer, but the module is part of a server-rendered package.
 const useIsomorphicLayoutEffect =
@@ -140,6 +161,13 @@ export default function ActionToolbar({
         left: rect.left + host.clientLeft
       };
 
+      // A coordinate that is not a number would defeat the bail-out below
+      // (`NaN !== NaN`), and this effect runs on every render — so the measure
+      // would set a fresh origin every commit and re-render forever. Leaving
+      // the toolbar where it is is also the right answer: an unreadable rect
+      // is a failed measurement, not a moved host.
+      if (!Number.isFinite(next.top) || !Number.isFinite(next.left)) return;
+
       setOrigin((previous) =>
         previous && previous.top === next.top && previous.left === next.left
           ? previous
@@ -232,10 +260,38 @@ export default function ActionToolbar({
       handleCancelRename();
     }
   };
+
+  /**
+   * Portaled to <body>, no ancestor can clip the toolbar any more, so the one
+   * reason left to draw it *inside* its host is that there is no room above it
+   * on screen: a host whose top is at the viewport edge would have its toolbar
+   * drawn at a negative y, painted off-screen with no scroll position that
+   * reveals it — and rename / duplicate / delete exist nowhere else. Two hosts
+   * sit there in the canvas: the top-most section at scroll 0, and anything in
+   * a chrome slot pinned with `position: sticky; top: 0`, which reports
+   * `rect.top === 0` at every scroll position and so is unreachable
+   * permanently.
+   *
+   * This covers `0 <= origin.top < SPACE_NEEDED_ABOVE` only. A host whose top
+   * has scrolled *past* the viewport edge keeps an off-screen toolbar, exactly
+   * as it did when the toolbar rendered in-tree; fixing that means sliding the
+   * toolbar down inside the host by a computed amount, which needs the host's
+   * height carried in `origin`.
+   *
+   * Derived from `origin` during render rather than kept in its own state:
+   * `origin` is the only input, so a second state set from an effect would buy
+   * an extra render and one painted frame in the old place. It cannot feed
+   * back either — the toolbar is `fixed` inside a zero-size frame at <body>
+   * and contributes no layout, so flipping it can never move the host.
+   */
+  const placeInside = origin !== null && origin.top < SPACE_NEEDED_ABOVE;
+
   const toolbar = (
     <div
       data-action-toolbar=""
-      className="absolute -top-0.5 left-0 -translate-y-full flex items-center pointer-events-auto gap-1 min-w-max"
+      className={`absolute left-0 flex items-center pointer-events-auto gap-1 min-w-max ${
+        placeInside ? 'top-1' : '-top-0.5 -translate-y-full'
+      }`}
     >
       <div className="flex items-center gap-1">
         {isRenaming ? (

package/src/load-placeholder-sections.ts

@@ -8,6 +8,10 @@ import { Section } from './theme-section';
 import { devWarn } from './utils/dev-warn';
 import { validateThemeSectionsInDev } from './schemas/theme-schema';
 import { getPlaceholderWidget } from './chrome/composition-source';
+import {
+  getPlaceholderPreviewSnapshot,
+  PreviewSnapshot
+} from './chrome/preview-snapshot-source';
 import { getThemeConfig, ThemeConfig } from './chrome/theme-config-source';
 
 const { getWidgetData } = serverData;
@@ -58,6 +62,135 @@ const getWidgetSchemaData = async <T,>(args: {
   return directFetch<T>(`/widgets/${args.widgetSlug}/schema/`);
 };
 
+/**
+ * Resolves a section's data source reference into the object the renderer
+ * expects, fetching collection data for collection-backed sources. Shared by
+ * the live render path and the preview-snapshot path so the two cannot drift.
+ */
+async function resolveSectionDataSource(
+  dataSourceId: string | undefined,
+  dataSources: ThemeConfig['dataSources'],
+  sectionSlug: string
+): Promise<any | undefined> {
+  if (!dataSourceId) {
+    return undefined;
+  }
+
+  const dataSource = dataSources.find((ds) => ds.id === dataSourceId);
+
+  if (!dataSource) {
+    devWarn(
+      'ThemePlaceholder',
+      `Section "${sectionSlug}" references data source "${dataSourceId}" which was not found; rendering placeholder items`
+    );
+    return undefined;
+  }
+
+  if (!dataSource.details) {
+    return dataSource;
+  }
+
+  // Only fetch collection data if we have a valid widget slug
+  // (not the section's own slug which contains config, not products)
+  const collectionSlug = dataSource.details.collection?.slug;
+  if (!collectionSlug) {
+    // The saved products from the editor (details.collection.products)
+    // will be used as fallback
+    return dataSource;
+  }
+
+  try {
+    let collectionData = await getWidgetData<{
+      [key: string]: unknown;
+    }>({
+      slug: collectionSlug
+    });
+
+    if (!collectionData) {
+      collectionData = await getCollectionWidgetData<{
+        [key: string]: unknown;
+      }>({
+        slug: collectionSlug
+      });
+    }
+
+    if (collectionData) {
+      return {
+        ...dataSource,
+        details: {
+          ...dataSource.details,
+          collection: {
+            ...dataSource.details.collection,
+            data: collectionData
+          }
+        }
+      };
+    }
+  } catch (error) {
+    console.error(
+      `Error fetching widget data for section ${sectionSlug}:`,
+      error
+    );
+  }
+
+  return dataSource;
+}
+
+/**
+ * Preview (draft mode): the theme editor writes the whole placeholder as one
+ * snapshot blob — sections arrive in render shape, so none of the per-widget
+ * fetches of the live path happen. The blob also owns the theme settings and
+ * data sources it was saved with.
+ */
+async function loadFromPreviewSnapshot(
+  slug: string,
+  snapshot: PreviewSnapshot
+): Promise<LoadedPlaceholder> {
+  const dataSources: ThemeConfig['dataSources'] = Array.isArray(
+    snapshot.dataSources
+  )
+    ? (snapshot.dataSources as any[])
+    : [];
+
+  const resolved = await Promise.all(
+    snapshot.sections.map(async (raw: any): Promise<Section | null> => {
+      if (!raw?.id) {
+        return null;
+      }
+
+      return {
+        id: raw.id,
+        type: raw.type || 'default',
+        name: raw.name || raw.id,
+        label: raw.label || raw.id,
+        properties: raw.properties || {},
+        styles: raw.styles || {},
+        blocks: Array.isArray(raw.blocks) ? raw.blocks : [],
+        order: raw.order ?? 0,
+        hidden: raw.hidden || false,
+        dataSourceId: raw.dataSourceId,
+        dataSource: await resolveSectionDataSource(
+          raw.dataSourceId,
+          dataSources,
+          raw.id
+        )
+      };
+    })
+  );
+
+  const sections = resolved.filter((s): s is Section => s !== null);
+
+  validateThemeSectionsInDev(sections);
+
+  return {
+    sections,
+    placeholderId: slug,
+    dataSources,
+    themeSettings:
+      (snapshot.themeSettings as Record<string, unknown> | null) ?? null
+  };
+}
+
 export interface LoadedPlaceholder {
   sections: Section[];
   placeholderId: string;
@@ -81,6 +214,12 @@ export async function loadPlaceholderSections(
   slug: string
 ): Promise<LoadedPlaceholder | null> {
   try {
+    // Absent/malformed blob (or no draft mode) falls through to the live path.
+    const previewSnapshot = await getPlaceholderPreviewSnapshot(slug);
+    if (previewSnapshot) {
+      return loadFromPreviewSnapshot(slug, previewSnapshot);
+    }
+
     // theme-config is optional for placeholder rendering, and the reader is
     // memoized per request — a page with several placeholders, or a ChromeSlot
     // asking the same question to decide whether it is pinned, reads it once.
@@ -224,60 +363,11 @@ export async function loadPlaceholderSections(
             (getBlockValue('dataSourceId') as string | undefined) ||
             (getBlockValue('selectedDataSourceId') as string | undefined);
 
-          const dataSource = dataSourceId
-            ? dataSources.find((ds) => ds.id === dataSourceId)
-            : undefined;
-
-          if (dataSourceId && !dataSource) {
-            devWarn(
-              'ThemePlaceholder',
-              `Section "${sectionSlug}" references data source "${dataSourceId}" which was not found; rendering placeholder items`
-            );
-          }
-
-          let dataSourceWithData = dataSource;
-          if (dataSource && dataSource.details) {
-            // Only fetch collection data if we have a valid widget slug
-            // (not the section's own slug which contains config, not products)
-            const collectionSlug = dataSource.details.collection?.slug;
-            if (collectionSlug) {
-              try {
-                let collectionData = await getWidgetData<{
-                  [key: string]: unknown;
-                }>({
-                  slug: collectionSlug
-                });
-
-                if (!collectionData) {
-                  collectionData = await getCollectionWidgetData<{
-                    [key: string]: unknown;
-                  }>({
-                    slug: collectionSlug
-                  });
-                }
-
-                if (collectionData) {
-                  dataSourceWithData = {
-                    ...dataSource,
-                    details: {
-                      ...dataSource.details,
-                      collection: {
-                        ...dataSource.details.collection,
-                        data: collectionData
-                      }
-                    }
-                  };
-                }
-              } catch (error) {
-                console.error(
-                  `Error fetching widget data for section ${sectionSlug}:`,
-                  error
-                );
-              }
-            }
-            // If no collection slug, the saved products from editor
-            // (details.collection.products) will be used as fallback
-          }
+          const dataSourceWithData = await resolveSectionDataSource(
+            dataSourceId,
+            dataSources,
+            sectionSlug
+          );
 
           const section: Section = {
             id: sectionSlug,