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

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.43-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea23]
-- Updated dependencies [324f97d5]
-- Updated dependencies [51ea0688]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08f]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f4]
-- 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 [e9598c71]
-- Updated dependencies [4998a963]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b2]
-  - @akinon/next@2.0.43-rc.0
-  - @akinon/theme-contract@2.0.43-rc.0
+## 2.0.43
+
+### Patch Changes
+
+- 0e384d73: ZERO-4730: Make the checkout page composable with a checkout pieces bridge, outlet blocks and a body takeover region
+  - @akinon/next@2.0.43
+  - @akinon/theme-contract@2.0.43
 
 ## 2.0.42
 

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

package/src/__tests__/checkout-pieces.test.tsx

@@ -0,0 +1,420 @@
+import React, { useState } from 'react';
+import { act, fireEvent, render, within } from '@testing-library/react';
+
+import { CheckoutPiece } from '../chrome/checkout-piece';
+import { CheckoutPiecesProvider } from '../chrome/checkout-pieces-provider';
+import {
+  announceCheckoutPiece,
+  getCheckoutFlowVariantOverride,
+  getCheckoutOutletClaim,
+  isCheckoutOutletWinner,
+  isCheckoutPieceMounted,
+  isThemeEditorDesigner,
+  registerCheckoutOutlet,
+  resetCheckoutPiecesForTests,
+  retractCheckoutPiece,
+  subscribeCheckoutPieces,
+  unregisterCheckoutOutlet,
+  updateCheckoutOutletFlowVariant
+} from '../chrome/checkout-pieces';
+
+/**
+ * The checkout pieces bridge carries the feature's safety invariants, so each
+ * one is pinned here rather than eyeballed:
+ *
+ * - byte-identical uncomposed page: an unclaimed piece adds ZERO wrapper DOM;
+ * - one React tree: teleporting is `createPortal`, so child state survives;
+ * - flow never lost: a latched outlet that disappears sends the piece home,
+ *   and a live page never latches onto an outlet that arrived late;
+ * - sealed reuse: outside the provider the wrapper never teleports anything.
+ */
+
+const outletNodes: HTMLElement[] = [];
+
+const createOutletNode = () => {
+  const node = document.createElement('div');
+  document.body.appendChild(node);
+  outletNodes.push(node);
+
+  return node;
+};
+
+beforeEach(() => resetCheckoutPiecesForTests());
+
+afterEach(() => {
+  outletNodes.forEach((node) => node.remove());
+  outletNodes.length = 0;
+});
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <button type="button" onClick={() => setCount((value) => value + 1)}>
+      count:{count}
+    </button>
+  );
+};
+
+describe('CheckoutPiece on the live site', () => {
+  beforeAll(() => {
+    // No editor handshake happened: the designer flag is unset.
+    delete window.__themeEditorDesigner;
+  });
+
+  it('adds zero DOM when nothing claims the piece', () => {
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span data-x="1">hi</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    // Exact string equality: no wrapper element, no attribute — the uncomposed
+    // checkout page must stay byte-identical to a build without the bridge.
+    expect(container.innerHTML).toBe('<span data-x="1">hi</span>');
+  });
+
+  it('never teleports outside the provider, even with an outlet registered', () => {
+    const outletNode = createOutletNode();
+    registerCheckoutOutlet('flow', { id: 'outlet-a', node: outletNode });
+
+    const { container } = render(
+      <CheckoutPiece piece="flow">
+        <span>in place</span>
+      </CheckoutPiece>
+    );
+
+    expect(container.innerHTML).toBe('<span>in place</span>');
+    expect(outletNode).toBeEmptyDOMElement();
+  });
+
+  it('teleports into an outlet registered before mount and keeps child state', () => {
+    const outletNode = createOutletNode();
+    registerCheckoutOutlet('flow', { id: 'outlet-a', node: outletNode });
+
+    const { container, rerender } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <Counter />
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    // Not in place — the child lives inside the outlet node.
+    expect(container).toBeEmptyDOMElement();
+
+    fireEvent.click(within(outletNode).getByRole('button'));
+    expect(within(outletNode).getByRole('button')).toHaveTextContent('count:1');
+
+    // A parent re-render must not remount the portaled child (one React tree).
+    rerender(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <Counter />
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(within(outletNode).getByRole('button')).toHaveTextContent('count:1');
+  });
+
+  it('ignores an outlet registered after the piece latched unclaimed', () => {
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>home</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(container.innerHTML).toBe('<span>home</span>');
+
+    const outletNode = createOutletNode();
+    act(() => {
+      registerCheckoutOutlet('flow', { id: 'late', node: outletNode });
+    });
+
+    // The unclaimed latch is permanent until navigation: a publish applies on
+    // the next full load, never mid-session under a payment surface.
+    expect(container.innerHTML).toBe('<span>home</span>');
+    expect(outletNode).toBeEmptyDOMElement();
+  });
+
+  it('returns home when the latched outlet disappears', () => {
+    const outletNode = createOutletNode();
+    registerCheckoutOutlet('flow', { id: 'outlet-a', node: outletNode });
+
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>flow</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(container).toBeEmptyDOMElement();
+
+    act(() => unregisterCheckoutOutlet('flow', 'outlet-a'));
+
+    // Ordering must never become impossible: with the outlet gone the flow
+    // renders in its default in-place position again.
+    expect(container.innerHTML).toBe('<span>flow</span>');
+    expect(outletNode).toBeEmptyDOMElement();
+  });
+});
+
+describe('CheckoutPiece in a framed but NOT edited window', () => {
+  // A production storefront legitimately iframed (partner portal, kiosk
+  // shell) is framed but never receives the editor handshake. It must keep
+  // live semantics: the one-shot latch, no claim-following — a portaled flow
+  // hosting a payment iframe must never be re-targeted mid-session.
+  beforeAll(() => {
+    delete window.__themeEditorDesigner;
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: { name: 'embedder' }
+    });
+  });
+
+  afterAll(() => {
+    Object.defineProperty(window, 'top', {
+      configurable: true,
+      value: window
+    });
+  });
+
+  it('ignores a late outlet: being framed is not the same as being edited', () => {
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>home</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(container.innerHTML).toBe('<span>home</span>');
+
+    const outletNode = createOutletNode();
+    act(() => {
+      registerCheckoutOutlet('flow', { id: 'late', node: outletNode });
+    });
+
+    expect(container.innerHTML).toBe('<span>home</span>');
+    expect(outletNode).toBeEmptyDOMElement();
+  });
+
+  it('never inherits a duplicate outlet claim when the winner dies', () => {
+    const first = createOutletNode();
+    const second = createOutletNode();
+    registerCheckoutOutlet('flow', { id: 'first', node: first });
+    registerCheckoutOutlet('flow', { id: 'second', node: second });
+
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>flow</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(first.innerHTML).toBe('<span>flow</span>');
+
+    // The latched outlet dies mid-session (e.g. its section errored away).
+    act(() => unregisterCheckoutOutlet('flow', 'first'));
+
+    // The claim passes to the duplicate in the registry, but the piece must
+    // come HOME, not chase it — retargeting would remount a payment iframe.
+    expect(container.innerHTML).toBe('<span>flow</span>');
+    expect(second).toBeEmptyDOMElement();
+  });
+});
+
+describe('CheckoutPiece in the designer', () => {
+  beforeAll(() => {
+    // The canvas is detected by the editor-proven flag, set only after a
+    // trusted SET_THEME_EDITOR_COOKIE through the origin-guarded bridge —
+    // never by mere framing.
+    window.__themeEditorDesigner = true;
+  });
+
+  afterAll(() => {
+    delete window.__themeEditorDesigner;
+  });
+
+  it('follows registration, removal and re-registration on the canvas', () => {
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>flow</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(container.innerHTML).toBe('<span>flow</span>');
+
+    const outletNode = createOutletNode();
+    act(() => {
+      registerCheckoutOutlet('flow', { id: 'outlet-a', node: outletNode });
+    });
+
+    // Late registration teleports here — the author must see the edit land.
+    expect(container).toBeEmptyDOMElement();
+    expect(outletNode.innerHTML).toBe('<span>flow</span>');
+
+    act(() => unregisterCheckoutOutlet('flow', 'outlet-a'));
+
+    expect(container.innerHTML).toBe('<span>flow</span>');
+    expect(outletNode).toBeEmptyDOMElement();
+
+    act(() => {
+      registerCheckoutOutlet('flow', { id: 'outlet-b', node: outletNode });
+    });
+
+    expect(container).toBeEmptyDOMElement();
+    expect(outletNode.innerHTML).toBe('<span>flow</span>');
+  });
+
+  it('adopts designer semantics when the handshake lands after mount', () => {
+    // The canvas bootstraps live-first: the flag rides a postMessage and can
+    // arrive after the page hydrated. The bridge re-checks it on pieces-store
+    // notifications, and every claim change notifies the store — so the flag
+    // is always seen before designer/live behavior could diverge.
+    delete window.__themeEditorDesigner;
+
+    const { container } = render(
+      <CheckoutPiecesProvider>
+        <CheckoutPiece piece="flow">
+          <span>flow</span>
+        </CheckoutPiece>
+      </CheckoutPiecesProvider>
+    );
+
+    expect(container.innerHTML).toBe('<span>flow</span>');
+
+    const outletNode = createOutletNode();
+    act(() => {
+      // SET_THEME_EDITOR_COOKIE landed, then the first canvas edit mounts an
+      // outlet — the registration notifies the store, the bridge re-checks.
+      window.__themeEditorDesigner = true;
+      registerCheckoutOutlet('flow', { id: 'outlet-a', node: outletNode });
+    });
+
+    expect(container).toBeEmptyDOMElement();
+    expect(outletNode.innerHTML).toBe('<span>flow</span>');
+  });
+});
+
+describe('checkout pieces registry', () => {
+  it('resolves duplicate outlets first-wins', () => {
+    const first = createOutletNode();
+    const second = createOutletNode();
+
+    registerCheckoutOutlet('summary', { id: 'first', node: first });
+    registerCheckoutOutlet('summary', { id: 'second', node: second });
+
+    expect(getCheckoutOutletClaim('summary')?.id).toBe('first');
+    expect(isCheckoutOutletWinner('summary', 'first')).toBe(true);
+    expect(isCheckoutOutletWinner('summary', 'second')).toBe(false);
+
+    // A duplicate id (an effect re-run) must not queue a second claim.
+    registerCheckoutOutlet('summary', { id: 'first', node: second });
+    expect(getCheckoutOutletClaim('summary')?.node).toBe(first);
+
+    // The next-in-line outlet inherits the claim when the winner leaves.
+    unregisterCheckoutOutlet('summary', 'first');
+    expect(getCheckoutOutletClaim('summary')?.id).toBe('second');
+
+    unregisterCheckoutOutlet('summary', 'second');
+    expect(getCheckoutOutletClaim('summary')).toBeNull();
+  });
+
+  it('reads the flow variant preference from the first-wins flow claim only', () => {
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+
+    const first = createOutletNode();
+    const second = createOutletNode();
+
+    registerCheckoutOutlet('flow', { id: 'first', node: first });
+    // A claim without a preference means inherit.
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+
+    registerCheckoutOutlet('flow', {
+      id: 'second',
+      node: second,
+      flowVariant: 'one-page'
+    });
+    // The duplicate outlet's preference never steers — first-wins.
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+
+    unregisterCheckoutOutlet('flow', 'first');
+    expect(getCheckoutFlowVariantOverride()).toBe('one-page');
+  });
+
+  it('updates a registration in place: no reorder, notify only on change', () => {
+    const first = createOutletNode();
+    const second = createOutletNode();
+
+    registerCheckoutOutlet('flow', {
+      id: 'first',
+      node: first,
+      flowVariant: 'one-page'
+    });
+    registerCheckoutOutlet('flow', { id: 'second', node: second });
+
+    const listener = jest.fn();
+    const unsubscribe = subscribeCheckoutPieces(listener);
+
+    updateCheckoutOutletFlowVariant('flow', 'first', 'step-by-step');
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(getCheckoutFlowVariantOverride()).toBe('step-by-step');
+    // Still first-wins: the update never re-queues the registration.
+    expect(getCheckoutOutletClaim('flow')?.id).toBe('first');
+    expect(getCheckoutOutletClaim('flow')?.node).toBe(first);
+
+    // Same value again: nothing changed, nobody re-renders.
+    updateCheckoutOutletFlowVariant('flow', 'first', 'step-by-step');
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Clearing back to inherit.
+    updateCheckoutOutletFlowVariant('flow', 'first', undefined);
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+
+    // Unknown ids and pieces are a no-op, never a crash.
+    updateCheckoutOutletFlowVariant('flow', 'ghost', 'one-page');
+    updateCheckoutOutletFlowVariant('steps', 'first', 'one-page');
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+
+    unsubscribe();
+  });
+
+  it('detects the designer only through the editor-proven flag', () => {
+    delete window.__themeEditorDesigner;
+    expect(isThemeEditorDesigner()).toBe(false);
+
+    window.__themeEditorDesigner = true;
+    expect(isThemeEditorDesigner()).toBe(true);
+
+    delete window.__themeEditorDesigner;
+  });
+
+  it('refcounts piece presence across announce and retract', () => {
+    expect(isCheckoutPieceMounted('steps')).toBe(false);
+
+    announceCheckoutPiece('steps');
+    announceCheckoutPiece('steps');
+    expect(isCheckoutPieceMounted('steps')).toBe(true);
+
+    retractCheckoutPiece('steps');
+    expect(isCheckoutPieceMounted('steps')).toBe(true);
+
+    retractCheckoutPiece('steps');
+    expect(isCheckoutPieceMounted('steps')).toBe(false);
+
+    // A stray retract must not push the count negative and mask a later mount.
+    retractCheckoutPiece('steps');
+    announceCheckoutPiece('steps');
+    expect(isCheckoutPieceMounted('steps')).toBe(true);
+  });
+});

package/src/__tests__/chrome-empty-zone.test.tsx

@@ -62,11 +62,11 @@ describe('ChromeFallback empty zone in the designer', () => {
       value: { postMessage }
     });
 
-    render(<ChromeFallback slug="checkout-summary-body" emptyZone />);
+    render(<ChromeFallback slug="checkout-bottom-body" emptyZone />);
 
     // A frame from the editor is what proves its origin to the bridge;
     // without one there is no trusted target and the message is dropped.
-    pushTheme([], 'checkout-summary-body');
+    pushTheme([], 'checkout-bottom-body');
 
     fireEvent.click(
       screen.getByRole('button', { name: /edit in theme editor/i })
@@ -76,7 +76,7 @@ describe('ChromeFallback empty zone in the designer', () => {
     const [envelope, targetOrigin] = postMessage.mock.calls[0];
     expect(envelope).toMatchObject({
       type: 'REQUEST_CHROME_OVERRIDE',
-      data: { slug: 'checkout-summary-body' }
+      data: { slug: 'checkout-bottom-body' }
     });
     expect(envelope.protocolVersion).toBeGreaterThan(0);
     expect(targetOrigin).toBe(EDITOR_ORIGIN);

package/src/__tests__/code-owned-region.test.tsx

@@ -4,10 +4,14 @@ import { render, screen, fireEvent } from '@testing-library/react';
 import { CodeOwnedRegion } from '../chrome/code-owned-region';
 
 /**
- * The checkout flow offers no takeover affordance on purpose, but silence
- * reads as breakage: a designer hovering it sees the same nothing a bug would
- * produce. These tests pin the explainer that fills that gap — and pin that
- * it never leaks to visitors and never blocks the flow it wraps.
+ * Some regions offer no takeover on purpose, but silence reads as breakage: a
+ * designer hovering one sees the same nothing a bug would produce. These tests
+ * pin the explainer that fills that gap — and pin that it never leaks to
+ * visitors and never blocks what it wraps.
+ *
+ * The reference app's checkout no longer mounts this: its body IS composable,
+ * so it takes `ComposableRegion` and a real affordance. The template app's
+ * checkout, which has no body zone at all, still does.
  */
 
 describe('CodeOwnedRegion in the designer', () => {
@@ -18,7 +22,7 @@ describe('CodeOwnedRegion in the designer', () => {
     });
   });
 
-  it('explains the region on hover and says where the composable zones are', () => {
+  it('explains the region on hover without promising outlet placement', () => {
     render(
       <CodeOwnedRegion label="checkout flow">
         <div data-testid="flow">payment steps</div>
@@ -31,12 +35,32 @@ describe('CodeOwnedRegion in the designer', () => {
 
     const note = screen.getByText(/checkout flow is code-owned/i);
     expect(note).toBeInTheDocument();
-    expect(note.textContent).toMatch(/zones above and below/i);
+    expect(note.textContent).toMatch(/is code-owned/i);
+    expect(note.textContent).toMatch(/internals cannot be edited here/i);
+    // The default used to promise placement through outlet blocks, which is
+    // false for any mount without a composable body zone — and outlets only
+    // register inside one. A mount that has the zone passes its own note.
+    expect(note.textContent).not.toMatch(/outlet blocks/i);
 
     fireEvent.mouseLeave(screen.getByTestId('flow').parentElement!);
     expect(screen.queryByText(/code-owned/i)).not.toBeInTheDocument();
   });
 
+  it('lets the mounting layout replace the default sentence with its own note', () => {
+    render(
+      <CodeOwnedRegion label="checkout flow" note="Compose the Checkout Body zone.">
+        <div data-testid="flow">payment steps</div>
+      </CodeOwnedRegion>
+    );
+
+    fireEvent.mouseEnter(screen.getByTestId('flow').parentElement!);
+
+    expect(
+      screen.getByText('Compose the Checkout Body zone.')
+    ).toBeInTheDocument();
+    expect(screen.queryByText(/is code-owned —/)).not.toBeInTheDocument();
+  });
+
   it('never intercepts the pointer, so the flow stays usable in the preview', () => {
     render(
       <CodeOwnedRegion label="checkout flow">