@akinon/pz-theme 2.0.49-rc.0 → 2.0.50-beta.0

package/CHANGELOG.md

@@ -1,36 +1,25 @@
 # @akinon/pz-theme
 
-## 2.0.49-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d5]
-- Updated dependencies [51ea0688]
-- Updated dependencies
-- Updated dependencies [2fea414]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08f]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb30]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a71]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d0]
-- Updated dependencies [4ac7b2a1]
-- Updated dependencies [e9598c7]
-- Updated dependencies [4998a963]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-  - @akinon/next@2.0.49-rc.0
-  - @akinon/theme-contract@2.0.49-rc.0
+## 2.0.50-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd75]
+  - @akinon/next@2.0.50-beta.0
+  - @akinon/theme-contract@2.0.50-beta.0
+
+## 2.0.49
+
+### Patch Changes
+
+- 8b5f0b6: ZERO-4744: Let the theme editor preview behave like the live site on demand
+
+  The preview now honours `SET_PREVIEW_INTERACTION_MODE`, so the editor's "Use preview" toggle turns the canvas back into a storefront: links navigate, sliders and menus work, overlays trap focus, project-owned chrome stops swallowing the pointer, and publish windows and visibility rules apply as they do for a visitor. Editing affordances (selection chrome, click-to-select, pinned part states) come back when the designer returns.
+
+  The editor stays attached throughout — the selected breakpoint, sampled data sources and page-context discovery are unaffected — and the checkout payment internals remain sealed in both modes.
+
+  - @akinon/next@2.0.49
+  - @akinon/theme-contract@2.0.49
 
 ## 2.0.48
 

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.49-rc.0",
+  "version": "2.0.50-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.49-rc.0",
+    "@akinon/next": "2.0.50-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.49-rc.0",
+    "@akinon/theme-contract": "2.0.50-beta.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.49-rc.0",
+    "@akinon/next": "2.0.50-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/browse-mode.test.tsx

@@ -0,0 +1,313 @@
+import React from 'react';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+
+import { __resetBrowseModeForTests, useBrowseMode } from '../browse-mode';
+import { __resetEditorBridgeForTests } from '../editor-bridge';
+import { ChromeFallback } from '../chrome/chrome-fallback';
+import { CodeOwnedRegion } from '../chrome/code-owned-region';
+import { ComposableRegionClient } from '../chrome/composable-region-client';
+import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+
+/**
+ * Browse mode is the designer asking the canvas to stop being a canvas.
+ *
+ * Everything the editor needs — the forced breakpoint, the selection it is
+ * holding, the placeholder registration — has to survive that request, and
+ * everything the SHOPPER would not see has to go. The two halves are easy to
+ * conflate (they were one flag), so both directions are pinned here, plus the
+ * one thing browse mode must never do: unseal the payment internals.
+ */
+
+const EDITOR_ORIGIN = 'http://localhost:5174';
+
+const frameDocument = () =>
+  Object.defineProperty(window, 'top', {
+    configurable: true,
+    value: { name: 'designer' }
+  });
+
+const setBrowseMode = (enabled: boolean, origin = EDITOR_ORIGIN) =>
+  act(() => {
+    fireEvent(
+      window,
+      new MessageEvent('message', {
+        origin,
+        data: {
+          type: 'SET_PREVIEW_INTERACTION_MODE',
+          data: { enabled }
+        }
+      })
+    );
+  });
+
+const changeBreakpoint = (breakpoint: string) =>
+  act(() => {
+    fireEvent(
+      window,
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        data: { type: 'CHANGE_BREAKPOINT', data: { breakpoint } }
+      })
+    );
+  });
+
+const Probe = () => <span data-testid="probe">{String(useBrowseMode())}</span>;
+
+beforeEach(() => {
+  __resetBrowseModeForTests();
+  __resetEditorBridgeForTests();
+});
+
+describe('the browse-mode flag', () => {
+  beforeAll(frameDocument);
+
+  it('follows the editor and ignores anyone else', () => {
+    render(<Probe />);
+    expect(screen.getByTestId('probe')).toHaveTextContent('false');
+
+    setBrowseMode(true);
+    expect(screen.getByTestId('probe')).toHaveTextContent('true');
+
+    // A page that framed the preview without proving itself must not be able
+    // to strip the designer's chrome — or, read the other way, to make a
+    // production embed think it is being edited.
+    setBrowseMode(false, 'https://evil.example');
+    expect(screen.getByTestId('probe')).toHaveTextContent('true');
+
+    setBrowseMode(false);
+    expect(screen.getByTestId('probe')).toHaveTextContent('false');
+  });
+
+  it('survives a remount, because the editor only says it once', () => {
+    const first = render(<Probe />);
+    setBrowseMode(true);
+    first.unmount();
+
+    // An in-iframe navigation remounts every placeholder; the mode frame is not
+    // repeated for each one, so a fresh mount has to read the standing answer.
+    render(<Probe />);
+    expect(screen.getByTestId('probe')).toHaveTextContent('true');
+  });
+});
+
+describe('a composed placeholder in browse mode', () => {
+  const section = {
+    id: 's1',
+    type: 'generic-section',
+    name: 'promo',
+    label: 'Promo Section',
+    order: 0,
+    hidden: false,
+    properties: {},
+    // Deliberately different per breakpoint: this is what proves the canvas
+    // still renders at the breakpoint the editor picked.
+    styles: { 'background-color': { desktop: 'red', mobile: 'blue' } },
+    blocks: [
+      {
+        id: 'b1',
+        type: 'group',
+        label: 'Promo Card',
+        order: 0,
+        hidden: false,
+        properties: {},
+        styles: {},
+        blocks: []
+      }
+    ]
+  } as any;
+
+  const renderCanvas = () => {
+    const postMessage = jest.fn();
+    Object.defineProperty(window, 'parent', {
+      configurable: true,
+      value: { postMessage }
+    });
+
+    const view = render(
+      <ThemePlaceholderWrapper
+        slug="home-body"
+        initialSections={[section]}
+        initialPlaceholderId="home-body"
+        isDesignMode
+      />
+    );
+
+    return { ...view, postMessage };
+  };
+
+  beforeAll(frameDocument);
+
+  it('drops the editing chrome and stops claiming clicks', () => {
+    const { container, postMessage } = renderCanvas();
+
+    const blockHost = () =>
+      container.querySelector('[data-block-id="b1"]') as HTMLElement;
+    const sectionHost = () =>
+      container.querySelector('[data-section-id="s1"]') as HTMLElement;
+
+    // A frame from the editor is what proves its origin to the bridge; without
+    // one there is no trusted target and every message is dropped by design.
+    changeBreakpoint('desktop');
+
+    // Editing: both hosts advertise themselves as selectable and a click is
+    // the editor's selection, not the page's.
+    expect(blockHost().className).toContain('cursor-pointer');
+    expect(sectionHost().className).toContain('cursor-pointer');
+
+    fireEvent.click(blockHost());
+    expect(
+      postMessage.mock.calls.some(([envelope]) => envelope?.type === 'SELECT_BLOCK')
+    ).toBe(true);
+
+    postMessage.mockClear();
+    setBrowseMode(true);
+
+    expect(blockHost().className).not.toContain('cursor-pointer');
+    expect(sectionHost().className).not.toContain('cursor-pointer');
+    expect(container.querySelector('[data-part-state-preview]')).toBeNull();
+
+    // The click belongs to the page now — no selection message at all.
+    fireEvent.click(blockHost());
+    expect(
+      postMessage.mock.calls.some(([envelope]) => envelope?.type === 'SELECT_BLOCK')
+    ).toBe(false);
+  });
+
+  it('keeps rendering at the breakpoint the editor selected', () => {
+    // The trap this pins: binding the forced breakpoint to the editing flag
+    // instead of "is the editor attached" repaints the desktop layout inside a
+    // mobile-width frame, so every toggle jumps.
+    const { container } = renderCanvas();
+    changeBreakpoint('mobile');
+
+    const css = () =>
+      Array.from(container.querySelectorAll('style'))
+        .map((tag) => tag.textContent || '')
+        .join('');
+
+    const mobileCss = css();
+    expect(mobileCss).toContain('blue');
+    expect(mobileCss).not.toContain('red');
+
+    setBrowseMode(true);
+    expect(css()).toBe(mobileCss);
+
+    setBrowseMode(false);
+    expect(css()).toBe(mobileCss);
+  });
+
+  it('gives the chrome back when the designer returns', () => {
+    const { container } = renderCanvas();
+
+    setBrowseMode(true);
+    setBrowseMode(false);
+
+    expect(
+      (container.querySelector('[data-block-id="b1"]') as HTMLElement).className
+    ).toContain('cursor-pointer');
+  });
+});
+
+describe('project-owned chrome in browse mode', () => {
+  beforeAll(frameDocument);
+
+  it('hands the brand markup back its pointer', () => {
+    // This wrapper is why an uncomposed header cannot be clicked in the editor
+    // at all: its markup is wrapped in a pointer-swallowing div under a
+    // takeover scrim. Browse mode is the whole answer to that.
+    const { container } = render(
+      <ChromeFallback slug="header">
+        <a href="/women" data-testid="menu-link">
+          Women
+        </a>
+      </ChromeFallback>
+    );
+
+    const swallowsPointer = () =>
+      Array.from(container.querySelectorAll<HTMLElement>('div')).some(
+        (node) => node.style.pointerEvents === 'none'
+      );
+
+    expect(swallowsPointer()).toBe(true);
+    expect(container.querySelector('[data-chrome-managed-by]')).not.toBeNull();
+
+    setBrowseMode(true);
+
+    expect(swallowsPointer()).toBe(false);
+    expect(container.querySelector('[data-chrome-managed-by]')).toBeNull();
+    expect(screen.getByTestId('menu-link')).toBeInTheDocument();
+
+    // And no takeover affordance on hover — a visitor is never offered one.
+    fireEvent.mouseEnter(screen.getByTestId('menu-link').parentElement!);
+    expect(
+      screen.queryByRole('button', { name: /edit in theme editor/i })
+    ).toBeNull();
+  });
+
+  it('renders nothing for an empty zone, exactly like the live site', () => {
+    const { container } = render(
+      <ChromeFallback slug="checkout-bottom-body" emptyZone />
+    );
+
+    expect(container.querySelector('[data-chrome-empty-zone]')).not.toBeNull();
+
+    setBrowseMode(true);
+    expect(container.querySelector('[data-chrome-empty-zone]')).toBeNull();
+  });
+
+  it('stops explaining a code-owned region while browsing', () => {
+    const { container } = render(
+      <CodeOwnedRegion label="checkout flow">
+        <div data-testid="flow">payment steps</div>
+      </CodeOwnedRegion>
+    );
+
+    const region = container.querySelector(
+      '[data-code-owned="checkout flow"]'
+    ) as HTMLElement;
+
+    fireEvent.mouseEnter(region);
+    expect(screen.getByText(/code-owned/i)).toBeInTheDocument();
+
+    setBrowseMode(true);
+    expect(screen.queryByText(/code-owned/i)).toBeNull();
+    // The wrapper itself never leaves — the flow below it must not remount.
+    expect(screen.getByTestId('flow')).toBeInTheDocument();
+  });
+});
+
+describe('the checkout body in browse mode', () => {
+  beforeAll(() => {
+    frameDocument();
+    window.__themeEditorDesigner = true;
+  });
+
+  afterAll(() => {
+    delete window.__themeEditorDesigner;
+  });
+
+  it('stays sealed — browse mode is not a licence to place an order', () => {
+    // Browse mode restores navigation and UI interaction. It deliberately does
+    // NOT reach into the payment internals: a designer walking the preview must
+    // not be able to submit a real order from inside the editor.
+    const { container } = render(
+      <ComposableRegionClient slug="checkout-page-body">
+        <button type="button" data-testid="place-order">
+          Place order
+        </button>
+      </ComposableRegionClient>
+    );
+
+    const region = () =>
+      container.querySelector(
+        '[data-chrome-region="checkout-page-body"]'
+      ) as HTMLElement;
+
+    expect(region().style.pointerEvents).toBe('none');
+
+    setBrowseMode(true);
+
+    expect(region().style.pointerEvents).toBe('none');
+    expect(screen.getByTestId('place-order')).toBeInTheDocument();
+  });
+});

package/src/browse-mode.ts

@@ -0,0 +1,87 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+import { isTrustedEditorEvent } from './editor-bridge';
+
+/**
+ * Browse mode — the designer asking the canvas to behave like the live site.
+ *
+ * Editing needs the opposite of a working storefront: a click has to mean
+ * "select this block", so links resolve to `#`, sliders lose their arrows,
+ * menus never open and project-owned chrome swallows the pointer. That leaves
+ * no way to walk the page as a shopper — open a menu, follow a link, step
+ * through a flow — without leaving the editor, which is what the editor's
+ * "Use preview" toggle asks for over `SET_PREVIEW_INTERACTION_MODE`.
+ *
+ * Consumers treat this as the second half of a pair: `isDesigner` answers "is
+ * the editor attached" (it drives the forced breakpoint, data sampling and
+ * page-context discovery, all of which must survive the toggle), while
+ * `isDesigner && !browseMode` answers "are the editing affordances on" and is
+ * what sections and blocks receive.
+ *
+ * The flag lives on `window` rather than in a module variable for the same
+ * reason `__themeEditorDesigner` does: the editor sends its state once per
+ * document, so a component mounting later — an in-iframe route change
+ * remounts every placeholder — has to read the current answer instead of
+ * resetting it to the default.
+ */
+declare global {
+  interface Window {
+    __themeEditorBrowseMode?: boolean;
+  }
+}
+
+const listeners = new Set<() => void>();
+let listening = false;
+
+const readFlag = (): boolean =>
+  typeof window !== 'undefined' && window.__themeEditorBrowseMode === true;
+
+/** Server render is never the designer's canvas, so it never browses. */
+const readServerFlag = (): boolean => false;
+
+const handleMessage = (event: MessageEvent) => {
+  if (!isTrustedEditorEvent(event)) return;
+  if (event.data?.type !== 'SET_PREVIEW_INTERACTION_MODE') return;
+
+  const next = Boolean(event.data?.data?.enabled);
+  if (next === readFlag()) return;
+
+  window.__themeEditorBrowseMode = next;
+  listeners.forEach((listener) => listener());
+};
+
+/**
+ * The window listener is attached on first use and then kept for the life of
+ * the document — deliberately never removed. Placeholders unmount in bursts
+ * during an in-iframe navigation, and a mode frame arriving in that gap would
+ * otherwise leave the flag stale for the page that mounts next.
+ */
+const subscribe = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+
+  if (!listening && typeof window !== 'undefined') {
+    window.addEventListener('message', handleMessage);
+    listening = true;
+  }
+
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/** Imperative read, for code that is not a component. */
+export const isBrowseMode = readFlag;
+
+export function useBrowseMode(): boolean {
+  return useSyncExternalStore(subscribe, readFlag, readServerFlag);
+}
+
+/** Test-only: forget the flag and every subscriber. */
+export function __resetBrowseModeForTests(): void {
+  if (typeof window !== 'undefined') {
+    delete window.__themeEditorBrowseMode;
+  }
+  listeners.clear();
+}

package/src/chrome/chrome-fallback.tsx

@@ -2,6 +2,7 @@
 
 import React, { useEffect, useState } from 'react';
 
+import { useBrowseMode } from '../browse-mode';
 import { isTrustedEditorEvent, postToEditor } from '../editor-bridge';
 import { isSlugComposedInFrame } from './composition-state';
 
@@ -48,6 +49,7 @@ export function ChromeFallback({
   const [inDesigner, setInDesigner] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
   const [isOverridden, setIsOverridden] = useState(initiallyOverridden);
+  const isBrowseMode = useBrowseMode();
 
   useEffect(() => {
     if (typeof window !== 'undefined' && window.self !== window.top) {
@@ -80,11 +82,20 @@ export function ChromeFallback({
     return () => window.removeEventListener('message', handleMessage);
   }, [slug]);
 
-  if (!inDesigner) {
-    // Composed on the live site: the composition owns the area, the brand
-    // markup must never double-render under it. An empty zone has nothing to
-    // show a visitor either way.
-    if (initiallyOverridden || emptyZone) return null;
+  // Browse mode takes the same path as the live site, which matters most
+  // here: this wrapper is what makes an uncomposed header or footer inert in
+  // the designer, so its menus and links are exactly what a designer cannot
+  // reach while editing. No pointer swallowing, no takeover affordance, no
+  // dashed band — only what a visitor would get.
+  //
+  // `isOverridden` rather than the prop: a takeover that happened in this
+  // session has already pushed a composition, and the brand markup must stay
+  // out of its way. On the live site no theme frames arrive, so the two agree.
+  if (!inDesigner || isBrowseMode) {
+    // Composed: the composition owns the area, the brand markup must never
+    // double-render under it. An empty zone has nothing to show a visitor
+    // either way.
+    if (isOverridden || emptyZone) return null;
 
     return (
       <div data-chrome-fallback={slug} className={wrapperClassName}>

package/src/chrome/code-owned-region.tsx

@@ -2,6 +2,8 @@
 
 import React, { useEffect, useState } from 'react';
 
+import { useBrowseMode } from '../browse-mode';
+
 /**
  * Wraps markup that is deliberately not editable at all — no takeover, no
  * placement, nothing but an explanation. Without this wrapper, hovering the
@@ -36,6 +38,9 @@ export function CodeOwnedRegion({
 }) {
   const [inDesigner, setInDesigner] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
+  // Browse mode wants the live site, and the note is editor chrome — the
+  // wrapper itself stays either way, so nothing remounts on the toggle.
+  const isBrowseMode = useBrowseMode();
 
   useEffect(() => {
     if (typeof window !== 'undefined' && window.self !== window.top) {
@@ -56,7 +61,7 @@ export function CodeOwnedRegion({
     >
       {children}
 
-      {inDesigner && isHovered && (
+      {inDesigner && isHovered && !isBrowseMode && (
         <div
           style={{
             position: 'absolute',

package/src/chrome/composable-region-client.tsx

@@ -113,6 +113,11 @@ export function ComposableRegionClient({
         // target, which only exists once a composition places one. Without
         // this, a composed-but-unplaced flow would leave a working "place
         // order" button on the canvas. The live site emits no value at all.
+        //
+        // Browse mode does NOT lift this, on purpose. It restores navigation
+        // and UI interaction across the canvas, but the payment internals stay
+        // sealed — a designer walking the preview must not be able to place a
+        // real order from inside the editor. Pinned by test.
         pointerEvents: inDesigner ? 'none' : undefined
       }}
     >

package/src/index.ts

@@ -15,6 +15,10 @@ export * from './utils';
 export * from './hooks/use-designer-features';
 export * from './hooks/use-visibility-context';
 
+// Brand code that renders its own designer-aware markup needs the same answer
+// the package uses internally: is the editor attached, and is it editing.
+export { isBrowseMode, useBrowseMode } from './browse-mode';
+
 export { WithDesignerFeatures } from './components/with-designer-features';
 
 export type { Section } from './theme-section';

package/src/theme-placeholder-client.tsx

@@ -13,6 +13,7 @@ import { isPublishWindowVisible } from './utils/publish-window';
 import { useThemePageContext } from './theme-page-context';
 
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
+import { useBrowseMode } from './browse-mode';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 // Global flags that must survive component remounts (e.g. in-iframe route
 // changes): IFRAME_READY is sent once per document, and the designer flag
@@ -47,12 +48,16 @@ export default function ThemePlaceholderClient({
   const [isDesigner, setIsDesigner] = useState(
     () => typeof window !== 'undefined' && window.__themeEditorDesigner === true
   );
+  // Browse mode keeps the editor attached but hands the canvas back to the
+  // storefront; see browse-mode.ts for why the two flags are separate.
+  const isBrowseMode = useBrowseMode();
+  const isEditing = isDesigner && !isBrowseMode;
   // Null unless a ThemePageContextProvider sits above this placeholder; data
   // conditions then have nothing to read and resolve the same way on both sides.
   const pageContext = useThemePageContext();
   const visibilityContext = useVisibilityContext(currentBreakpoint, {
     pageContext,
-    isDesigner
+    isDesigner: isEditing
   });
   const renderedSections = applyVisibilityRulesToSections(
     sections,
@@ -174,7 +179,7 @@ export default function ThemePlaceholderClient({
         .filter(
           (section) =>
             !section.hidden &&
-            (isDesigner ||
+            (isEditing ||
               isPublishWindowVisible(section.properties?.['publish-window']))
         )
         .map((section) => (
@@ -186,7 +191,7 @@ export default function ThemePlaceholderClient({
               // all: the context is read for visibility rules and then dropped
               // before the section that needs it.
               pageContext={pageContext}
-              isDesigner={isDesigner}
+              isDesigner={isEditing}
               isSelected={selectedSectionId === section.id}
               selectedBlockId={selectedBlockId}
               currentBreakpoint={currentBreakpoint}

package/src/theme-placeholder-wrapper.tsx

@@ -21,6 +21,7 @@ import { isPublishWindowVisible } from './utils/publish-window';
 import { buildClientRequestUrl } from '@akinon/next/utils';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 import { parseEditorMessage, postToEditor } from './editor-bridge';
+import { useBrowseMode } from './browse-mode';
 
 // Helper function to inject theme colors as CSS custom properties
 const injectThemeColors = (settings: Record<string, unknown>) => {
@@ -310,6 +311,18 @@ export default function ThemePlaceholderWrapper({
       isDesignMode ||
       (typeof window !== 'undefined' && window.__themeEditorDesigner === true)
   );
+  // Two different questions, and they used to share one answer:
+  //
+  // `isDesigner` — is the editor attached. It drives the plumbing that has to
+  // keep working while the designer browses: the forced breakpoint, sampled
+  // data sources, page-context discovery.
+  //
+  // `isEditing` — are the editing affordances on. This is what sections and
+  // blocks receive, so browse mode turns the canvas back into a storefront
+  // (links navigate, sliders slide, overlays trap focus, publish windows and
+  // visibility rules apply) without disturbing anything above.
+  const isBrowseMode = useBrowseMode();
+  const isEditing = isDesigner && !isBrowseMode;
   const [dataSources, setDataSources] = useState<any[]>(initialDataSources);
   const [themeSettings, setThemeSettings] = useState<Record<
     string,
@@ -719,6 +732,10 @@ export default function ThemePlaceholderWrapper({
     postToEditor({ type: action, data });
   };
 
+  // Bound to `isDesigner`, NOT to `isEditing`: the canvas renders at the
+  // breakpoint the editor selected, and dropping back to real media queries
+  // when the designer starts browsing would repaint a desktop layout inside a
+  // mobile-width frame — a layout jump on every toggle.
   const dynamicCSS = useMemo(
     () =>
       generateThemeCSS(sections, isDesigner ? currentBreakpoint : undefined),
@@ -726,7 +743,7 @@ export default function ThemePlaceholderWrapper({
   );
   const visibilityContext = useVisibilityContext(currentBreakpoint, {
     pageContext: resolvedPageContext,
-    isDesigner
+    isDesigner: isEditing
   });
   const renderedSections = useMemo(
     () => applyVisibilityRulesToSections(sections, visibilityContext),
@@ -739,7 +756,12 @@ export default function ThemePlaceholderWrapper({
     // falls back to its empty state.
     <ThemePageContextProvider value={resolvedPageContext}>
     <ThemeSettingsProvider value={themeSettings}>
-      <PartStatePreview isDesigner={isDesigner} />
+      {/*
+        Pins are released while browsing — a button frozen in its hover state
+        is not what the live site looks like. The editor re-sends the pinned
+        state when the designer comes back, so the panel and the canvas agree.
+      */}
+      <PartStatePreview isDesigner={isEditing} />
       {dynamicCSS && <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />}
       <div
         data-placeholder={slug}
@@ -751,7 +773,7 @@ export default function ThemePlaceholderWrapper({
           .filter(
             (section) =>
               !section.hidden &&
-              (isDesigner ||
+              (isEditing ||
                 isPublishWindowVisible(section.properties?.['publish-window']))
           )
           .map((section) => (
@@ -760,7 +782,7 @@ export default function ThemePlaceholderWrapper({
                 section={section}
                 placeholderId={placeholderSlug}
                 pageContext={resolvedPageContext}
-                isDesigner={isDesigner}
+                isDesigner={isEditing}
                 isSelected={selectedSectionId === section.id}
                 selectedBlockId={selectedBlockId}
                 currentBreakpoint={currentBreakpoint}