@akinon/pz-theme 2.0.133-rc.0 → 2.0.134-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.133-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- 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 [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d458]
-- Updated dependencies [dca12811]
-  - @akinon/next@2.0.133-rc.0
-  - @akinon/theme-contract@2.0.133-rc.0
+## 2.0.134-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.134-beta.0
+  - @akinon/theme-contract@2.0.134-beta.0
+
+## 2.0.133
+
+### Patch Changes
+
+- 114d857: ZERO-5164: Report a composed section becoming visible as section.seen
+  - @akinon/next@2.0.133
+  - @akinon/theme-contract@2.0.133
 
 ## 2.0.132
 

package/package.json

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

package/src/hooks/__tests__/use-section-seen.test.tsx

@@ -0,0 +1,316 @@
+import React, { useRef } from 'react';
+import { act, render } from '@testing-library/react';
+
+let pathname = '/';
+jest.mock('next/navigation', () => ({
+  usePathname: () => pathname
+}));
+
+import {
+  FRAMED_SECTION_SEEN_DWELL_MS,
+  SECTION_SEEN_DWELL_MS,
+  useSectionSeen
+} from '../use-section-seen';
+import {
+  __resetThemeSignalsForTests,
+  subscribeToThemeSignals,
+  type ThemeSignalDetail
+} from '../../utils/theme-signal';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+/**
+ * A recording stand-in, in the shape `video-block.test.tsx` already uses.
+ *
+ * The package's jsdom setup fills `IntersectionObserver` with a no-op whose
+ * callback is never called, so a test that only asserts "no event" passes
+ * whether the code is right or wrong. Every negative case below is therefore
+ * paired with a positive one driven through this class.
+ */
+class RecordingObserver {
+  static instances: RecordingObserver[] = [];
+
+  callback: IntersectionObserverCallback;
+  options: IntersectionObserverInit | undefined;
+  observed: Element[] = [];
+  disconnected = false;
+
+  constructor(
+    callback: IntersectionObserverCallback,
+    options?: IntersectionObserverInit
+  ) {
+    this.callback = callback;
+    this.options = options;
+    RecordingObserver.instances.push(this);
+  }
+
+  observe(node: Element) {
+    this.observed.push(node);
+  }
+
+  unobserve() {}
+
+  disconnect() {
+    this.disconnected = true;
+  }
+
+  takeRecords() {
+    return [];
+  }
+
+  /** Drive an intersection, the way the browser would. */
+  cross(isIntersecting: boolean, ratio = 1) {
+    act(() => {
+      this.callback(
+        [
+          {
+            isIntersecting,
+            intersectionRatio: ratio,
+            target: this.observed[0]
+          } as unknown as IntersectionObserverEntry
+        ],
+        this as unknown as IntersectionObserver
+      );
+    });
+  }
+}
+
+const latest = () =>
+  RecordingObserver.instances[RecordingObserver.instances.length - 1];
+
+const DEFAULT_SECTION = { id: 'sec_hero', type: 'custom', order: 2 };
+
+const Section = ({
+  placeholderId = 'home-body',
+  section = DEFAULT_SECTION
+}: {
+  placeholderId?: string;
+  section?: { id: string; type: string; order?: number };
+}) => {
+  const ref = useRef<HTMLDivElement>(null);
+  useSectionSeen({ ref, section: section as never, placeholderId });
+
+  return <div ref={ref} data-testid="section" />;
+};
+
+const tick = (ms: number) =>
+  act(() => {
+    jest.advanceTimersByTime(ms);
+  });
+
+describe('section.seen (ZERO-5164)', () => {
+  let received: ThemeSignalDetail[];
+  let detach: () => void;
+  let originalObserver: unknown;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    pathname = '/';
+    received = [];
+    detach = subscribeToThemeSignals((detail) => received.push(detail));
+    __resetThemeSignalsForTests();
+    delete window.__themeEditorDesigner;
+
+    RecordingObserver.instances = [];
+    originalObserver = (window as unknown as Record<string, unknown>)
+      .IntersectionObserver;
+    (window as unknown as Record<string, unknown>).IntersectionObserver =
+      RecordingObserver;
+  });
+
+  afterEach(() => {
+    detach();
+    (window as unknown as Record<string, unknown>).IntersectionObserver =
+      originalObserver;
+    delete window.__themeEditorDesigner;
+    jest.useRealTimers();
+  });
+
+  it('reports once the section has held the band for the dwell', () => {
+    render(<Section />);
+
+    latest().cross(true);
+    expect(received).toEqual([]);
+
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received).toEqual([
+      {
+        name: 'section.seen',
+        placeholderId: 'home-body',
+        sectionId: 'sec_hero',
+        sectionType: 'custom',
+        order: 2
+      }
+    ]);
+  });
+
+  it('watches a band across the middle of the viewport, not a share of the section', () => {
+    // A hero taller than the viewport can never reach a ratio threshold, so
+    // the question has to be height-independent.
+    render(<Section />);
+
+    expect(latest().options).toEqual({
+      threshold: 0,
+      rootMargin: '-50% 0px -50% 0px'
+    });
+  });
+
+  it('reports a section far taller than the viewport', () => {
+    render(<Section />);
+
+    latest().cross(true, 0.08);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received).toHaveLength(1);
+  });
+
+  it('does not report a section scrolled straight past', () => {
+    render(<Section />);
+
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS - 100);
+    latest().cross(false);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received).toEqual([]);
+  });
+
+  it('reports once per route however often it crosses', () => {
+    render(<Section />);
+
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+    latest().cross(false);
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received).toHaveLength(1);
+  });
+
+  it('stops observing once it has reported', () => {
+    render(<Section />);
+
+    const observer = latest();
+    observer.cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(observer.disconnected).toBe(true);
+  });
+
+  it('reports again after a client-side navigation', () => {
+    // ChromeSlot mounts the header in the root layout, which the app router
+    // never unmounts — so a per-mount latch would report it once per visit.
+    const { rerender } = render(<Section />);
+
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    pathname = '/kadin';
+    rerender(<Section />);
+
+    // The rebuilt observer re-delivers the intersection for a header that
+    // never left the screen.
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received).toHaveLength(2);
+    expect(received.every((d) => d.sectionId === 'sec_hero')).toBe(true);
+  });
+
+  it('counts the same section under two placeholders separately', () => {
+    render(
+      <>
+        <Section placeholderId="home-body" />
+        <Section placeholderId="footer" />
+      </>
+    );
+
+    RecordingObserver.instances.forEach((observer) => observer.cross(true));
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received.map((d) => d.placeholderId).sort()).toEqual([
+      'footer',
+      'home-body'
+    ]);
+  });
+
+  it('omits the order when the section has none', () => {
+    render(<Section section={{ id: 'sec_hero', type: 'custom' }} />);
+
+    latest().cross(true);
+    tick(SECTION_SEEN_DWELL_MS);
+
+    expect(received[0]).not.toHaveProperty('order');
+  });
+
+  describe('the editor', () => {
+    it('reports nothing while the editor is attached', () => {
+      window.__themeEditorDesigner = true;
+
+      render(<Section />);
+      latest().cross(true);
+      tick(FRAMED_SECTION_SEEN_DWELL_MS);
+
+      expect(received).toEqual([]);
+    });
+
+    it('does not latch on a muted attempt', () => {
+      // Latching first and emitting second would silence the section for the
+      // rest of the page on the strength of a render nobody saw.
+      window.__themeEditorDesigner = true;
+
+      render(<Section />);
+      latest().cross(true);
+      tick(FRAMED_SECTION_SEEN_DWELL_MS);
+
+      delete window.__themeEditorDesigner;
+      latest().cross(false);
+      latest().cross(true);
+      tick(FRAMED_SECTION_SEEN_DWELL_MS);
+
+      expect(received).toHaveLength(1);
+    });
+  });
+
+  describe('inside an iframe', () => {
+    const framed = () => {
+      Object.defineProperty(window, 'top', {
+        configurable: true,
+        value: {}
+      });
+    };
+
+    afterEach(() => {
+      Object.defineProperty(window, 'top', {
+        configurable: true,
+        value: window
+      });
+    });
+
+    it('waits longer, because the editor flag lands after the first callback', () => {
+      framed();
+      render(<Section />);
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+      expect(received).toEqual([]);
+
+      tick(FRAMED_SECTION_SEEN_DWELL_MS - SECTION_SEEN_DWELL_MS);
+      expect(received).toHaveLength(1);
+    });
+  });
+
+  it('does nothing where the browser has no IntersectionObserver', () => {
+    delete (window as unknown as Record<string, unknown>).IntersectionObserver;
+
+    expect(() => render(<Section />)).not.toThrow();
+    tick(FRAMED_SECTION_SEEN_DWELL_MS);
+
+    expect(received).toEqual([]);
+  });
+});

package/src/hooks/use-section-seen.ts

@@ -0,0 +1,161 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+
+import { useThemeSignal } from './use-theme-signal';
+import type { Section } from '../theme-section';
+
+/**
+ * Report a composed section becoming visible to the shopper (ZERO-5164).
+ *
+ * The anchor of the reporting feature: a merchant adds a campaign band and
+ * asks whether anyone saw it. Nothing in this package observed a section
+ * before — the five existing IntersectionObservers all answer other questions
+ * (a pagination sentinel, a gallery's active image, a video's autoplay, the
+ * header's scroll state, a popup's scroll depth).
+ *
+ * One hook, called from the two places a section root is actually rendered:
+ * `SectionWrapper` for custom and registered-renderer sections, and the
+ * generic branch of `theme-section.tsx`. Both already hold a `sectionRef` for
+ * the editor's scroll-to, so nothing about either component's signature
+ * changes.
+ */
+
+/**
+ * A zero-height band across the middle of the viewport, rather than a share
+ * of the section.
+ *
+ * `intersectionRatio` is relative to the TARGET, so a hero taller than the
+ * viewport can never reach 0.5 and a three-screen listing can never reach any
+ * meaningful ratio at all: a fixed ratio would silently never report on
+ * exactly the sections this exists for. A band asks a height-independent
+ * question — did this section cross the middle of the screen — and is the
+ * shape `chrome/scroll-state.tsx` already uses for the header.
+ */
+const SEEN_BAND = { threshold: 0, rootMargin: '-50% 0px -50% 0px' };
+
+/** How long a section must hold the band before it counts as seen. */
+export const SECTION_SEEN_DWELL_MS = 500;
+
+/**
+ * The dwell used while the storefront is inside an iframe.
+ *
+ * `window.__themeEditorDesigner` is only set once the editor's handshake
+ * arrives, and an IntersectionObserver delivers its first callback as soon as
+ * it observes a visible target — so an immediate report from the editor canvas
+ * would count a designer as a shopper before the flag that mutes them exists.
+ * A production storefront is legitimately framed too (payment providers,
+ * marketplace previews) and loses nothing by reporting an impression a second
+ * later, so the longer dwell is the cheap way to close the race for both.
+ */
+export const FRAMED_SECTION_SEEN_DWELL_MS = 1500;
+
+const isFramed = (): boolean => {
+  try {
+    return window.self !== window.top;
+  } catch {
+    // A cross-origin parent throws on access, which is itself evidence of one.
+    return true;
+  }
+};
+
+export interface UseSectionSeenOptions {
+  ref: React.RefObject<HTMLElement>;
+  section: Pick<Section, 'id' | 'type' | 'order'>;
+  placeholderId: string;
+}
+
+export const useSectionSeen = ({
+  ref,
+  section,
+  placeholderId
+}: UseSectionSeenOptions): void => {
+  const pathname = usePathname();
+  const signal = useThemeSignal({
+    placeholderId,
+    sectionId: section.id,
+    sectionType: section.type
+  });
+
+  /**
+   * The last key actually reported.
+   *
+   * Keyed on the route rather than the mount: `ChromeSlot` mounts the header
+   * and footer in the root layout, and the app router does not unmount a
+   * shared layout segment on a client-side navigation — so a per-mount latch
+   * would report those sections once per VISIT while every other section
+   * reports once per page. Rebuilding the observer on a pathname change
+   * re-delivers the intersection, which is what makes the re-report happen
+   * for a header that never left the screen.
+   */
+  const reported = useRef<string | null>(null);
+
+  const order = section.order;
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    if (typeof IntersectionObserver === 'undefined') return;
+
+    const latchKey = `${pathname}:${placeholderId}:${section.id}`;
+    if (reported.current === latchKey) return;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const dwell = isFramed()
+      ? FRAMED_SECTION_SEEN_DWELL_MS
+      : SECTION_SEEN_DWELL_MS;
+
+    const clear = () => {
+      if (timer === undefined) return;
+      clearTimeout(timer);
+      timer = undefined;
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+
+      // Left the band before the dwell elapsed: scrolled past, not seen.
+      if (!entry.isIntersecting) {
+        clear();
+        return;
+      }
+
+      if (timer !== undefined) return;
+
+      timer = setTimeout(() => {
+        timer = undefined;
+        if (reported.current === latchKey) return;
+
+        const sent = signal(
+          'section.seen',
+          {
+            ...(typeof order === 'number' && Number.isFinite(order)
+              ? { order }
+              : null)
+          },
+          { key: latchKey, once: true }
+        );
+
+        // Latched only on a report that actually left. Writing the latch
+        // first and emitting second is how a muted render — the editor
+        // canvas, or a consent gate that has not answered yet — silences a
+        // section for the rest of the page with nothing to show for it.
+        if (sent) {
+          reported.current = latchKey;
+          observer.disconnect();
+        }
+      }, dwell);
+    }, SEEN_BAND);
+
+    observer.observe(node);
+
+    return () => {
+      clear();
+      observer.disconnect();
+    };
+  }, [ref, pathname, placeholderId, section.id, order, signal]);
+};
+
+export default useSectionSeen;

package/src/sections/section-wrapper.tsx

@@ -9,6 +9,7 @@ import { SECTION_CONTENT_ATTRIBUTE } from '../utils/section-content-width';
 
 import { isTrustedEditorEvent, postToEditor } from '../editor-bridge';
 import { resolveSectionPartName } from '../hooks/use-designer-features';
+import { useSectionSeen } from '../hooks/use-section-seen';
 
 
 interface SectionWrapperProps {
@@ -65,6 +66,12 @@ export default function SectionWrapper({
 
   const sectionRef = useRef<HTMLElement>(null);
 
+  // Report this section becoming visible (ZERO-5164). Inert in the editor:
+  // the emitter reads the editor handshake flag itself, so there is no
+  // `isDesigner` check here — that prop goes false in browse mode while the
+  // editor is still attached.
+  useSectionSeen({ ref: sectionRef, section, placeholderId });
+
   // Custom-renderer sections render through this wrapper instead of the
   // default <section> in theme-section, so the editor's SCROLL_TO_SECTION
   // must be handled here too.

package/src/theme-section.tsx

@@ -29,6 +29,7 @@ import { getCustomSectionDefinition } from './custom/section-definitions';
 import { isCustomThemeType } from './custom/types';
 import { ThemeSectionDataProvider } from './theme-section-data-context';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
+import { useSectionSeen } from './hooks/use-section-seen';
 export interface Section {
   id: string;
   type: string;
@@ -137,6 +138,11 @@ export default function ThemeSection({
 
   const sectionRef = useRef<HTMLElement>(null);
 
+  // Report this section becoming visible (ZERO-5164). The generic branch
+  // below renders its own <section>; sections that go through SectionWrapper
+  // are reported there, so exactly one of the two runs per section.
+  useSectionSeen({ ref: sectionRef, section: effectiveSection, placeholderId });
+
   const constrainsContent = hasSectionContentWidth(effectiveSection.styles);
 
   // Bound prices are formatted deep inside the binding walk, which has no