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

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.134-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.134-rc.0
-  - @akinon/theme-contract@2.0.134-rc.0
+## 2.0.135-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.135-beta.0
+  - @akinon/theme-contract@2.0.135-beta.0
+
+## 2.0.134
+
+### Patch Changes
+
+- f03a0af: ZERO-5165: Announce what the storefront can report to the theme editor
+  - @akinon/next@2.0.134
+  - @akinon/theme-contract@2.0.134
 
 ## 2.0.133
 

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

@@ -381,6 +381,20 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     ]);
   });
 
+  it('announces what this build can report, on the same terms', () => {
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // Literal rather than the constant, like the action list above: the editor
+    // matches by name and drops a name it does not know, so a rename here has
+    // to be a visible change on both sides rather than a silent narrowing.
+    // Without this field the editor offers no tracking panel at all, which is
+    // the correct reading of every renderer built before it existed.
+    expect(frames()[0].signalCapabilities).toEqual(['section-seen']);
+  });
+
   it('keeps the action capability on the designer re-announce too', () => {
     const { registry, register } = load();
 
@@ -407,6 +421,14 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
       ['add-to-cart-after-add', 'localized-video'],
       ['add-to-cart-after-add', 'localized-video']
     ]);
+
+    // The reporting list rides every frame for the same reason: the editor
+    // replaces what it holds, so a later frame without it would take the
+    // merchant's tracking panel away halfway through a session.
+    expect(frames().map((frame) => frame.signalCapabilities)).toEqual([
+      ['section-seen'],
+      ['section-seen']
+    ]);
   });
 
   it('sends the whole catalog every time, so a re-announce replaces', () => {

package/src/placeholder-registry.ts

@@ -5,6 +5,10 @@ import {
   ACTION_CAPABILITIES,
   type ActionCapability
 } from './action-capabilities';
+import {
+  SIGNAL_CAPABILITIES,
+  type SignalCapability
+} from './signal-capabilities';
 import {
   STATE_PIN_CAPABILITIES,
   type StatePinCapability
@@ -107,6 +111,14 @@ interface PlaceholdersAvailablePayload {
    * out before the designer flag arrived (see `handleEditorMessage`).
    */
   actionCapabilities?: readonly ActionCapability[];
+  /**
+   * Which moments this build can report.
+   *
+   * Same terms as `actionCapabilities` above and on every frame for the same
+   * reason: the editor replaces what it holds with each frame, so a frame
+   * without the field would put it back to reporting nothing.
+   */
+  signalCapabilities?: readonly SignalCapability[];
 }
 
 const isFramed = (): boolean =>
@@ -147,7 +159,11 @@ const flush = () => {
     // withhold. Gated, it would be lost for the life of the document on a slow
     // handshake: the designer re-announce only fires for a build that
     // registers a custom catalog, and most brands register none.
-    actionCapabilities: ACTION_CAPABILITIES
+    actionCapabilities: ACTION_CAPABILITIES,
+    // Outside the designer gate for the same reason, and for one more: the
+    // panel it gates is the merchant's, so a slow handshake must not be the
+    // difference between a section being trackable and not.
+    signalCapabilities: SIGNAL_CAPABILITIES
   };
 
   // Omitted entirely when nothing is registered: a build with no brand pages

package/src/signal-capabilities.ts

@@ -0,0 +1,39 @@
+/**
+ * What this build can REPORT, announced to the editor (ZERO-5165).
+ *
+ * The sibling of `action-capabilities.ts`, for the other half of the same
+ * problem. That one says what a stored action will do; this one says which
+ * moments the renderer is able to observe and emit at all.
+ *
+ * The editor is one deployment serving channels whose storefronts pin their
+ * own pz-theme version, so it cannot assume that what the repo can do is what
+ * the storefront in front of it can do. Without this, a tracking panel would
+ * be authorable on every brand and dead on every brand below the line: the
+ * merchant types a name, saves, and nothing ever happens, with no error
+ * anywhere. That is the failure this ecosystem keeps producing, and a name
+ * list is what stops it.
+ *
+ *  - `section-seen`  the renderer observes composed sections and emits
+ *                    `section.seen` when one crosses the middle of the
+ *                    viewport and stays there. The editor reads it to decide
+ *                    whether to offer the section tracking panel at all.
+ *
+ * Names rather than a version number, for the reason the action capabilities
+ * are: the editor must not have to know which release added what. A build that
+ * does not send the list is read as reporting nothing, which is exactly what
+ * every renderer shipped before this one did.
+ *
+ * The editor matches these strings exactly and silently drops one it does not
+ * know, so a rename here narrows the editor back to its baseline instead of
+ * failing anywhere. Change one only together with `StorefrontSignalCapability`
+ * in pz-dynamic-widget, which has a parity test against this file.
+ *
+ * Its own module rather than a constant beside the hook that implements it:
+ * the placeholder registry announces this, and it must not have to pull a
+ * client component in to say one list of strings.
+ */
+export type SignalCapability = 'section-seen';
+
+export const SIGNAL_CAPABILITIES: readonly SignalCapability[] = [
+  'section-seen'
+];