@akinon/pz-theme 2.0.144-rc.0 → 2.0.145-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.144-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 [1595d458e]
-- Updated dependencies [dca128112]
-  - @akinon/next@2.0.144-rc.0
-  - @akinon/theme-contract@2.0.144-rc.0
+## 2.0.145-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.145-beta.0
+  - @akinon/theme-contract@2.0.145-beta.0
+
+## 2.0.144
+
+### Patch Changes
+
+- fc64466: ZERO-5222: Honour the merchant's section tracking settings in the renderer
+  - @akinon/next@2.0.144
+  - @akinon/theme-contract@2.0.144
 
 ## 2.0.143
 

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.144-rc.0",
+  "version": "2.0.145-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.144-rc.0",
+    "@akinon/next": "2.0.145-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.144-rc.0",
+    "@akinon/theme-contract": "2.0.145-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.144-rc.0",
+    "@akinon/next": "2.0.145-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

@@ -8,9 +8,11 @@ jest.mock('next/navigation', () => ({
 
 import {
   FRAMED_SECTION_SEEN_DWELL_MS,
-  SECTION_SEEN_DWELL_MS,
   useSectionSeen
 } from '../use-section-seen';
+import { DEFAULT_SECTION_TRACKING } from '../../utils/section-tracking';
+
+const SECTION_SEEN_DWELL_MS = DEFAULT_SECTION_TRACKING.dwellMs;
 import {
   __resetThemeSignalsForTests,
   subscribeToThemeSignals,
@@ -89,7 +91,12 @@ const Section = ({
   section = DEFAULT_SECTION
 }: {
   placeholderId?: string;
-  section?: { id: string; type: string; order?: number };
+  section?: {
+    id: string;
+    type: string;
+    order?: number;
+    properties?: Record<string, unknown>;
+  };
 }) => {
   const ref = useRef<HTMLDivElement>(null);
   useSectionSeen({ ref, section: section as never, placeholderId });
@@ -144,7 +151,10 @@ describe('section.seen (ZERO-5164)', () => {
         placeholderId: 'home-body',
         sectionId: 'sec_hero',
         sectionType: 'custom',
-        order: 2
+        order: 2,
+        // Every report says why it was made, so a brand bridge can gate
+        // consent on one field rather than on a list of section ids.
+        purpose: 'analytics'
       }
     ]);
   });
@@ -305,6 +315,119 @@ describe('section.seen (ZERO-5164)', () => {
     });
   });
 
+  describe('what the merchant authored (ZERO-5222)', () => {
+    const tracked = (viewTracking: Record<string, unknown>) => ({
+      id: 'sec_hero',
+      type: 'custom',
+      order: 2,
+      properties: { viewTracking }
+    });
+
+    it('carries the authored name and purpose', () => {
+      render(
+        <Section
+          section={tracked({ name: 'home_hero_summer', purpose: 'marketing' })}
+        />
+      );
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0]).toMatchObject({
+        sectionName: 'home_hero_summer',
+        purpose: 'marketing'
+      });
+    });
+
+    it('reports a name the merchant could not have typed as unnamed', () => {
+      // The same composition is written by the API and the AI generator, so
+      // the pattern is enforced on read rather than trusted from the panel.
+      render(<Section section={tracked({ name: 'Yaz İndirimi!' })} />);
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0]).not.toHaveProperty('sectionName');
+      expect(received).toHaveLength(1);
+    });
+
+    it('watches from the first pixel when asked to', () => {
+      render(<Section section={tracked({ seenWhen: 'appears' })} />);
+
+      expect(latest().options).toEqual({ threshold: 0, rootMargin: '0px' });
+    });
+
+    it('honours an authored dwell', () => {
+      render(<Section section={tracked({ dwellMs: 2000 })} />);
+
+      latest().cross(true);
+      tick(1900);
+      expect(received).toEqual([]);
+
+      tick(100);
+      expect(received).toHaveLength(1);
+    });
+
+    it('treats the framed dwell as a floor, not a default', () => {
+      // A merchant typing 0 does not make the editor handshake arrive sooner.
+      Object.defineProperty(window, 'top', { configurable: true, value: {} });
+
+      render(<Section section={tracked({ dwellMs: 0 })} />);
+      latest().cross(true);
+      tick(FRAMED_SECTION_SEEN_DWELL_MS - 1);
+      expect(received).toEqual([]);
+
+      tick(1);
+      expect(received).toHaveLength(1);
+
+      Object.defineProperty(window, 'top', {
+        configurable: true,
+        value: window
+      });
+    });
+
+    it('reports every time the section comes back when asked to', () => {
+      render(<Section section={tracked({ frequency: 'every-view' })} />);
+
+      const observer = latest();
+      observer.cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+      observer.cross(false);
+      observer.cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received).toHaveLength(2);
+      // Still watching, because there may be a third time.
+      expect(observer.disconnected).toBe(false);
+    });
+
+    it('does not report twice for one uninterrupted stay', () => {
+      render(<Section section={tracked({ frequency: 'every-view' })} />);
+
+      const observer = latest();
+      observer.cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+      // A ratio change while it is still on screen is the same stay.
+      observer.cross(true, 0.9);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received).toHaveLength(1);
+    });
+
+    it('reads settings the editor bucketed by breakpoint', () => {
+      render(
+        <Section
+          section={tracked({ desktop: { name: 'bucketed_hero' } } as never)}
+        />
+      );
+
+      latest().cross(true);
+      tick(SECTION_SEEN_DWELL_MS);
+
+      expect(received[0].sectionName).toBe('bucketed_hero');
+    });
+  });
+
   it('does nothing where the browser has no IntersectionObserver', () => {
     delete (window as unknown as Record<string, unknown>).IntersectionObserver;
 

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

@@ -4,10 +4,15 @@ import { useEffect, useRef } from 'react';
 import { usePathname } from 'next/navigation';
 
 import { useThemeSignal } from './use-theme-signal';
+import {
+  normalizeSectionTracking,
+  SECTION_TRACKING_PROPERTY_KEY
+} from '../utils/section-tracking';
 import type { Section } from '../theme-section';
 
 /**
- * Report a composed section becoming visible to the shopper (ZERO-5164).
+ * Report a composed section becoming visible to the shopper (ZERO-5164),
+ * the way the merchant asked for it (ZERO-5222).
  *
  * 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
@@ -22,32 +27,25 @@ import type { Section } from '../theme-section';
  * 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' };
+/** A zero-height band across the middle of the viewport. */
+const BAND: IntersectionObserverInit = {
+  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;
+/** From the first pixel, for a section the merchant wants counted early. */
+const ANY_PART: IntersectionObserverInit = { threshold: 0, rootMargin: '0px' };
 
 /**
- * The dwell used while the storefront is inside an iframe.
+ * The dwell an unauthored section waits, and the floor for an authored one
+ * while the storefront is framed.
  *
  * `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.
+ * 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. That race does not go away because a merchant typed 0, which is why
+ * the framed value is a floor rather than a default.
  */
 export const FRAMED_SECTION_SEEN_DWELL_MS = 1500;
 
@@ -62,7 +60,7 @@ const isFramed = (): boolean => {
 
 export interface UseSectionSeenOptions {
   ref: React.RefObject<HTMLElement>;
-  section: Pick<Section, 'id' | 'type' | 'order'>;
+  section: Pick<Section, 'id' | 'type' | 'order' | 'properties'>;
   placeholderId: string;
 }
 
@@ -79,7 +77,7 @@ export const useSectionSeen = ({
   });
 
   /**
-   * The last key actually reported.
+   * The last key actually reported, for a section counted once per page.
    *
    * 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
@@ -92,6 +90,8 @@ export const useSectionSeen = ({
   const reported = useRef<string | null>(null);
 
   const order = section.order;
+  const { name, purpose, seenWhen, dwellMs, frequency } =
+    normalizeSectionTracking(section.properties?.[SECTION_TRACKING_PROPERTY_KEY]);
 
   useEffect(() => {
     const node = ref.current;
@@ -99,12 +99,18 @@ export const useSectionSeen = ({
     if (typeof IntersectionObserver === 'undefined') return;
 
     const latchKey = `${pathname}:${placeholderId}:${section.id}`;
-    if (reported.current === latchKey) return;
+    const countsOnce = frequency === 'once-per-view';
+    if (countsOnce && reported.current === latchKey) return;
 
     let timer: ReturnType<typeof setTimeout> | undefined;
+    // Whether this uninterrupted stay on screen has already been reported.
+    // Without it a second callback for the same entry — a ratio change, a
+    // resize — would start a fresh dwell and report the same stay twice.
+    let reportedThisEntry = false;
+
     const dwell = isFramed()
-      ? FRAMED_SECTION_SEEN_DWELL_MS
-      : SECTION_SEEN_DWELL_MS;
+      ? Math.max(dwellMs, FRAMED_SECTION_SEEN_DWELL_MS)
+      : dwellMs;
 
     const clear = () => {
       if (timer === undefined) return;
@@ -116,38 +122,54 @@ export const useSectionSeen = ({
       const entry = entries[entries.length - 1];
       if (!entry) return;
 
-      // Left the band before the dwell elapsed: scrolled past, not seen.
+      // Left before the dwell elapsed: scrolled past, not seen. Leaving also
+      // ends the stay, so a section the merchant asked to count every time
+      // can count the next one.
       if (!entry.isIntersecting) {
         clear();
+        reportedThisEntry = false;
         return;
       }
 
-      if (timer !== undefined) return;
+      if (timer !== undefined || reportedThisEntry) return;
 
       timer = setTimeout(() => {
         timer = undefined;
-        if (reported.current === latchKey) return;
+        if (countsOnce && reported.current === latchKey) return;
 
         const sent = signal(
           'section.seen',
           {
+            purpose,
+            // `sectionName`, not `name`: the emitter owns `name` as the
+            // moment's own identity and ignores a fact that tries to use it,
+            // so a merchant label sent under that key would vanish without a
+            // word. It also reads better beside `sectionId` and `sectionType`.
+            ...(name ? { sectionName: name } : null),
             ...(typeof order === 'number' && Number.isFinite(order)
               ? { order }
               : null)
           },
-          { key: latchKey, once: true }
+          // `every-view` deliberately does not take the module latch, so it
+          // falls back on the ordinary per-key ceiling: a section entering
+          // and leaving twenty times still cannot flood the route budget.
+          countsOnce ? { key: latchKey, once: true } : { key: latchKey }
         );
 
         // 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) {
+        if (!sent) return;
+
+        reportedThisEntry = true;
+
+        if (countsOnce) {
           reported.current = latchKey;
           observer.disconnect();
         }
       }, dwell);
-    }, SEEN_BAND);
+    }, seenWhen === 'appears' ? ANY_PART : BAND);
 
     observer.observe(node);
 
@@ -155,7 +177,19 @@ export const useSectionSeen = ({
       clear();
       observer.disconnect();
     };
-  }, [ref, pathname, placeholderId, section.id, order, signal]);
+  }, [
+    ref,
+    pathname,
+    placeholderId,
+    section.id,
+    order,
+    signal,
+    name,
+    purpose,
+    seenWhen,
+    dwellMs,
+    frequency
+  ]);
 };
 
 export default useSectionSeen;

package/src/utils/__tests__/section-tracking.test.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_SECTION_TRACKING,
+  MAX_SECTION_DWELL_MS,
+  normalizeSectionTracking,
+  sanitizeSectionTrackingName
+} from '../section-tracking';
+
+describe('section tracking settings (ZERO-5222)', () => {
+  describe('the name', () => {
+    it('takes a well-formed one as authored', () => {
+      expect(sanitizeSectionTrackingName('home_hero_summer')).toBe(
+        'home_hero_summer'
+      );
+    });
+
+    it('lowercases and trims what the merchant typed', () => {
+      expect(sanitizeSectionTrackingName('  Home_Hero  ')).toBe('home_hero');
+    });
+
+    it.each([
+      ['2026_campaign', 'starts with a digit'],
+      ['home hero', 'has a space'],
+      ['home-hero', 'has a hyphen'],
+      ['müşteri_bandı', 'is not ascii'],
+      ['a'.repeat(41), 'is too long'],
+      ['', 'is empty'],
+      ['__proto__', 'starts with an underscore']
+    ])('drops %s, which %s', (value) => {
+      expect(sanitizeSectionTrackingName(value)).toBe('');
+    });
+
+    it('drops anything that is not a string', () => {
+      expect(sanitizeSectionTrackingName({ name: 'hero' })).toBe('');
+      expect(sanitizeSectionTrackingName(42)).toBe('');
+      expect(sanitizeSectionTrackingName(null)).toBe('');
+    });
+
+    it('refuses a huge string without working through it', () => {
+      // Sliced before the lowercase and the match, so a stored megabyte is
+      // rejected on its first 96 characters.
+      expect(sanitizeSectionTrackingName('a'.repeat(1_000_000))).toBe('');
+    });
+  });
+
+  describe('the whole object', () => {
+    it('falls back to the defaults when nothing is authored', () => {
+      expect(normalizeSectionTracking(undefined)).toEqual(
+        DEFAULT_SECTION_TRACKING
+      );
+      expect(normalizeSectionTracking(null)).toEqual(DEFAULT_SECTION_TRACKING);
+      expect(normalizeSectionTracking('tracked')).toEqual(
+        DEFAULT_SECTION_TRACKING
+      );
+      expect(normalizeSectionTracking([])).toEqual(DEFAULT_SECTION_TRACKING);
+    });
+
+    it('reads what the merchant authored', () => {
+      expect(
+        normalizeSectionTracking({
+          name: 'home_hero_summer',
+          purpose: 'marketing',
+          seenWhen: 'appears',
+          dwellMs: 2000,
+          frequency: 'every-view'
+        })
+      ).toEqual({
+        name: 'home_hero_summer',
+        purpose: 'marketing',
+        seenWhen: 'appears',
+        dwellMs: 2000,
+        frequency: 'every-view'
+      });
+    });
+
+    it('falls back field by field rather than dropping the lot', () => {
+      // An unparseable setting must not cost the impression it describes.
+      expect(
+        normalizeSectionTracking({
+          name: 'campaign_band',
+          purpose: 'profiling',
+          seenWhen: 'halfway',
+          dwellMs: 'soon',
+          frequency: 'always'
+        })
+      ).toEqual({
+        ...DEFAULT_SECTION_TRACKING,
+        name: 'campaign_band'
+      });
+    });
+
+    it('clamps a dwell nobody meant', () => {
+      expect(normalizeSectionTracking({ dwellMs: -500 }).dwellMs).toBe(0);
+      expect(normalizeSectionTracking({ dwellMs: 60_000 }).dwellMs).toBe(
+        MAX_SECTION_DWELL_MS
+      );
+      expect(normalizeSectionTracking({ dwellMs: 1200.6 }).dwellMs).toBe(1201);
+    });
+
+    it('reads a value the editor bucketed by breakpoint', () => {
+      // The editor wraps anything it does not know to be primitive into a
+      // breakpoint bucket, and the API and the AI generator write the same
+      // row. Tracking that differed by viewport would be meaningless, so the
+      // bucket is read as the value rather than honoured as one.
+      expect(
+        normalizeSectionTracking({
+          desktop: { name: 'home_hero', purpose: 'marketing' }
+        })
+      ).toEqual({
+        ...DEFAULT_SECTION_TRACKING,
+        name: 'home_hero',
+        purpose: 'marketing'
+      });
+    });
+
+    it('prefers the flat value when a stray bucket key sits beside it', () => {
+      expect(
+        normalizeSectionTracking({
+          name: 'flat_name',
+          desktop: { name: 'bucketed_name' }
+        }).name
+      ).toBe('flat_name');
+    });
+
+    it('does not recurse forever on an empty object', () => {
+      expect(normalizeSectionTracking({})).toEqual(DEFAULT_SECTION_TRACKING);
+      expect(normalizeSectionTracking({ desktop: {} })).toEqual(
+        DEFAULT_SECTION_TRACKING
+      );
+    });
+  });
+});

package/src/utils/section-tracking.ts

@@ -0,0 +1,172 @@
+/**
+ * What a merchant authored about reporting a section (ZERO-5222).
+ *
+ * `section.seen` already reports every composed section with what the
+ * renderer knows by itself — the section id, its type and its authored order.
+ * A report that says `sec_8f2c` is of limited use to a marketer, and those
+ * ids are re-minted by "Reset to code", so a brand cannot reliably map them
+ * by hand either. This is the vocabulary behind the panel that lets a
+ * merchant name one.
+ *
+ * Deliberately NOT an on/off switch. Reporting already happens for every
+ * section: a toggle that turned it off would take away what shipped, and one
+ * that did not would be a lie. The panel names a section; a brand that wants
+ * one out of its reports filters it in its own bridge or container.
+ */
+
+/** Where the authored object lives on the section. */
+export const SECTION_TRACKING_PROPERTY_KEY = 'viewTracking';
+
+/**
+ * Why this section is reported — the brand's bridge gates consent on it.
+ *
+ * `analytics` is the default because it is the narrowest claim: a section
+ * nobody has spoken about is counted, not profiled.
+ */
+export type SectionTrackingPurpose =
+  | 'analytics'
+  | 'marketing'
+  | 'personalization';
+
+/** Which geometry counts as seen. */
+export type SectionSeenWhen = 'appears' | 'middle';
+
+/** Whether the section may be reported more than once on one page. */
+export type SectionTrackingFrequency = 'once-per-view' | 'every-view';
+
+export interface SectionTracking {
+  /** Empty when the merchant has not named this section. */
+  name: string;
+  purpose: SectionTrackingPurpose;
+  seenWhen: SectionSeenWhen;
+  dwellMs: number;
+  frequency: SectionTrackingFrequency;
+}
+
+/**
+ * What an unauthored section reports, i.e. what ZERO-5164 already does.
+ *
+ * Changing one of these changes every section on every storefront that has
+ * never opened the panel, so they are the conservative end of each choice:
+ * the band rather than the first pixel, a dwell long enough to exclude a
+ * section scrolled straight past, and once per page.
+ */
+export const DEFAULT_SECTION_TRACKING: SectionTracking = {
+  name: '',
+  purpose: 'analytics',
+  seenWhen: 'middle',
+  dwellMs: 500,
+  frequency: 'once-per-view'
+};
+
+/** Longest a merchant may ask a section to be held before it counts. */
+export const MAX_SECTION_DWELL_MS = 5000;
+
+/**
+ * Lowercase, underscore-separated, starts with a letter.
+ *
+ * The same shape GA4 and every tag manager treat as an ordinary dimension
+ * value, so a name travels from the panel to a report without anyone having
+ * to quote or escape it.
+ */
+export const SECTION_TRACKING_NAME_PATTERN = /^[a-z][a-z0-9_]{0,39}$/;
+
+const PURPOSES: readonly SectionTrackingPurpose[] = [
+  'analytics',
+  'marketing',
+  'personalization'
+];
+const SEEN_WHEN: readonly SectionSeenWhen[] = ['appears', 'middle'];
+const FREQUENCIES: readonly SectionTrackingFrequency[] = [
+  'once-per-view',
+  'every-view'
+];
+
+/**
+ * A name, or nothing.
+ *
+ * Sanitized on READ rather than trusted from the panel: the same composition
+ * is written by the editor, by the Omnitron API and by the AI generator, and
+ * only one of those three has a text field with a pattern on it. A name that
+ * does not survive this is dropped and the section reports unnamed — losing
+ * the label is a smaller failure than putting an unconstrained merchant
+ * string on the wire.
+ */
+export const sanitizeSectionTrackingName = (value: unknown): string => {
+  if (typeof value !== 'string') return '';
+
+  // Sliced before the work, not after: a stored 10 MB string must not be
+  // lowercased and matched in full to be rejected.
+  const name = value.slice(0, 96).trim().toLowerCase();
+
+  return SECTION_TRACKING_NAME_PATTERN.test(name) ? name : '';
+};
+
+const readNumber = (value: unknown): number | null => {
+  const parsed = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/**
+ * The authored settings, or the defaults.
+ *
+ * Every field is re-validated and a bad one falls back on its own rather than
+ * failing the whole object: an unparseable setting must not cost the
+ * impression it was describing.
+ *
+ * The `{ desktop: … }` unwrap mirrors `normalizePublishWindowValue`. The
+ * editor wraps any value it does not know to be primitive into a breakpoint
+ * bucket, and a composition written before the key was declared primitive —
+ * or by hand, or by the API — arrives in that shape. Tracking that differed
+ * by viewport would be meaningless, so a bucket is read as the value rather
+ * than honoured as one.
+ */
+export const normalizeSectionTracking = (value: unknown): SectionTracking => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return DEFAULT_SECTION_TRACKING;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  const hasOwnFields =
+    'name' in record ||
+    'purpose' in record ||
+    'seenWhen' in record ||
+    'dwellMs' in record ||
+    'frequency' in record;
+
+  if (!hasOwnFields) {
+    const bucketed = record.desktop ?? record.tablet ?? record.mobile;
+    if (bucketed && bucketed !== value) {
+      return normalizeSectionTracking(bucketed);
+    }
+    return DEFAULT_SECTION_TRACKING;
+  }
+
+  const purpose = PURPOSES.includes(record.purpose as SectionTrackingPurpose)
+    ? (record.purpose as SectionTrackingPurpose)
+    : DEFAULT_SECTION_TRACKING.purpose;
+
+  const seenWhen = SEEN_WHEN.includes(record.seenWhen as SectionSeenWhen)
+    ? (record.seenWhen as SectionSeenWhen)
+    : DEFAULT_SECTION_TRACKING.seenWhen;
+
+  const frequency = FREQUENCIES.includes(
+    record.frequency as SectionTrackingFrequency
+  )
+    ? (record.frequency as SectionTrackingFrequency)
+    : DEFAULT_SECTION_TRACKING.frequency;
+
+  const dwell = readNumber(record.dwellMs);
+
+  return {
+    name: sanitizeSectionTrackingName(record.name),
+    purpose,
+    seenWhen,
+    dwellMs:
+      dwell === null
+        ? DEFAULT_SECTION_TRACKING.dwellMs
+        : Math.min(Math.max(Math.round(dwell), 0), MAX_SECTION_DWELL_MS),
+    frequency
+  };
+};