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

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.51-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- 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 [4ac7b2a1e]
-- Updated dependencies [e9598c7]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-  - @akinon/next@2.0.51-rc.0
-  - @akinon/theme-contract@2.0.51-rc.0
+## 2.0.51
+
+### Patch Changes
+
+- 3f806d3: ZERO-4747: Stop the chrome placeholder painting a background behind composed sections
+  - @akinon/next@2.0.51
+  - @akinon/theme-contract@2.0.51
 
 ## 2.0.50
 

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

package/src/__tests__/placeholder-background.test.tsx

@@ -0,0 +1,153 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+// The Node build, not the browser one: it is the path a storefront actually
+// server-renders through, and the browser build wants a MessageChannel jsdom
+// does not have.
+import { renderToStaticMarkup } from 'react-dom/server.node';
+
+import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+import type { Section } from '../theme-section';
+
+/**
+ * Two defects that shared one element.
+ *
+ * The placeholder wrapper painted `var(--theme-background)` from an inline
+ * style, and it sits behind every section of the slot. A section asking for
+ * `background-color: transparent` — the shipped default — therefore still had
+ * the theme colour behind it, which is why a composed header could never sit
+ * over a hero.
+ *
+ * The variable it painted with is written from an effect, so the two renders
+ * of that same element disagreed: the server sent an unresolved var (nothing
+ * painted) and hydration resolved it to the theme colour. A visible flip on
+ * every first load.
+ */
+
+const THEME_BACKGROUND = '#ffffff';
+const THEME_SETTINGS = { backgroundColor: THEME_BACKGROUND };
+
+const transparentSection = {
+  id: 'composed-header',
+  type: 'generic-section',
+  name: 'header',
+  label: 'Header',
+  order: 0,
+  hidden: false,
+  properties: {},
+  styles: { 'background-color': { desktop: 'transparent' } },
+  blocks: [
+    {
+      id: 'logo',
+      type: 'group',
+      label: 'Logo',
+      order: 0,
+      hidden: false,
+      properties: {},
+      styles: {},
+      blocks: []
+    }
+  ]
+} as unknown as Section;
+
+const composedSlot = (
+  settings: Record<string, unknown> | null = THEME_SETTINGS
+) => (
+  <ThemePlaceholderWrapper
+    slug="header"
+    initialSections={[transparentSection]}
+    initialPlaceholderId="header"
+    isDesignMode={false}
+    initialThemeSettings={settings}
+  />
+);
+
+const placeholderOf = (root: ParentNode) =>
+  root.querySelector('.theme-placeholder') as HTMLElement;
+
+const ssrDocument = (element: React.ReactElement) =>
+  new DOMParser().parseFromString(
+    renderToStaticMarkup(element),
+    'text/html'
+  );
+
+beforeEach(() => {
+  document.body.style.backgroundColor = '';
+});
+
+describe('a transparent section in a composed slot', () => {
+  it('has nothing painted behind it', () => {
+    const { container } = render(composedSlot());
+
+    const section = container.querySelector(
+      '[data-section-id="composed-header"]'
+    ) as HTMLElement;
+    expect(section).not.toBeNull();
+
+    // Every ancestor up to the render root, not just the immediate one: a
+    // colour anywhere on that path is a colour the section cannot see through.
+    for (
+      let node: HTMLElement | null = section;
+      node && node !== container;
+      node = node.parentElement
+    ) {
+      expect(node.style.backgroundColor).toBe('');
+    }
+
+    expect(placeholderOf(container).getAttribute('style')).toBeNull();
+  });
+
+  it('still asks for transparent in the generated CSS', () => {
+    // The section keeps expressing the request; this pins that the fix removed
+    // what was covering it, not the request itself.
+    const { container } = render(composedSlot());
+
+    const css = Array.from(container.querySelectorAll('style'))
+      .map((tag) => tag.textContent || '')
+      .join('');
+
+    expect(css).toContain('[data-section-id="composed-header"]');
+    expect(css).toContain('transparent');
+  });
+
+  it('leaves the page colour to the body', () => {
+    // Removing the wrapper's paint must not lose the colour: on a slot that
+    // overlaps nothing, the page still looks exactly as it did.
+    const { container } = render(composedSlot());
+
+    expect(document.body.style.backgroundColor).toBe('rgb(255, 255, 255)');
+    expect(placeholderOf(container).style.backgroundColor).toBe('');
+  });
+});
+
+describe('the placeholder background across hydration', () => {
+  it('is the same on the server and after the effects run', () => {
+    const server = placeholderOf(ssrDocument(composedSlot()));
+    const { container } = render(composedSlot());
+
+    expect(server.getAttribute('style')).toBe(
+      placeholderOf(container).getAttribute('style')
+    );
+    expect(server.getAttribute('style')).toBeNull();
+  });
+
+  it('server-renders the page colour instead of waiting for the effect', () => {
+    // The flip this pins: the colour used to exist only as an inline style
+    // written by `injectThemeColors`, so the first paint was the browser
+    // default and the second was the theme.
+    expect(renderToStaticMarkup(composedSlot())).toContain(
+      `body{background-color:${THEME_BACKGROUND}}`
+    );
+
+    render(composedSlot());
+    expect(document.body.style.backgroundColor).toBe('rgb(255, 255, 255)');
+  });
+
+  it('emits no background rule when the theme has no colour', () => {
+    const markup = renderToStaticMarkup(composedSlot(null));
+
+    // A slot rendered before the theme config resolves must not guess a
+    // colour for the page — the section's own rule is all that is left.
+    expect(markup).not.toContain('body{background-color');
+    expect(placeholderOf(ssrDocument(composedSlot(null)))).not.toBeNull();
+  });
+});

package/src/theme-placeholder-wrapper.tsx

@@ -22,6 +22,7 @@ import { buildClientRequestUrl } from '@akinon/next/utils';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 import { parseEditorMessage, postToEditor } from './editor-bridge';
 import { useBrowseMode } from './browse-mode';
+import { neutralizeStyleTagBreakout } from './utils/css-safety';
 
 // Helper function to inject theme colors as CSS custom properties
 const injectThemeColors = (settings: Record<string, unknown>) => {
@@ -114,6 +115,34 @@ const injectThemeColors = (settings: Record<string, unknown>) => {
   }
 };
 
+/**
+ * The page background as real CSS, emitted from the same render that produced
+ * the markup.
+ *
+ * `injectThemeColors` can only run in an effect, so the server painted the
+ * browser default and the browser repainted the theme colour a frame later —
+ * a visible flip on every first load. The settings are already in hand when
+ * the server renders (they arrive as `initialThemeSettings`), so the same
+ * declarations the effect will write are emitted up front and the two paints
+ * agree. The effect still runs: it is what keeps the colour live while the
+ * editor pushes UPDATE_THEME, and its inline values outrank this rule.
+ */
+const buildThemeBackgroundCss = (
+  settings: Record<string, unknown> | null
+): string => {
+  const backgroundColor = settings?.backgroundColor;
+
+  if (typeof backgroundColor !== 'string' || !backgroundColor.trim()) {
+    return '';
+  }
+
+  // Editor-controlled value on its way into a <style> tag — same breakout
+  // neutralization the generated section CSS goes through.
+  const value = neutralizeStyleTagBreakout(backgroundColor.trim());
+
+  return `:root{--theme-background:${value}}body{background-color:${value}}`;
+};
+
 // Helper function to load Google Font
 const loadGoogleFont = (fontFamily: string, fontWeight?: string) => {
   if (!fontFamily || fontFamily === 'inherit') return;
@@ -741,6 +770,10 @@ export default function ThemePlaceholderWrapper({
       generateThemeCSS(sections, isDesigner ? currentBreakpoint : undefined),
     [sections, isDesigner, currentBreakpoint]
   );
+  const themeBackgroundCSS = useMemo(
+    () => buildThemeBackgroundCss(themeSettings),
+    [themeSettings]
+  );
   const visibilityContext = useVisibilityContext(currentBreakpoint, {
     pageContext: resolvedPageContext,
     isDesigner: isEditing
@@ -762,12 +795,20 @@ export default function ThemePlaceholderWrapper({
         state when the designer comes back, so the panel and the canvas agree.
       */}
       <PartStatePreview isDesigner={isEditing} />
+      {themeBackgroundCSS && (
+        <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
+      )}
       {dynamicCSS && <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />}
-      <div
-        data-placeholder={slug}
-        className="theme-placeholder"
-        style={{ backgroundColor: 'var(--theme-background)' }}
-      >
+      {/*
+        Deliberately unpainted. This wrapper sits behind every section of the
+        slot, so any colour on it showed through a section that asked for
+        `background-color: transparent` — the shipped default. That is why a
+        composed header could not sit over a hero: the section was transparent
+        and the wrapper behind it was not. The page colour belongs to `body`
+        (see buildThemeBackgroundCss), which paints the same pixels everywhere
+        the slot does not overlap something else.
+      */}
+      <div data-placeholder={slug} className="theme-placeholder">
         {renderedSections
           .sort((a, b) => a.order - b.order)
           .filter(