@akinon/pz-theme 2.0.71-beta.0 → 2.0.71

package/src/placeholder-registry.ts

@@ -1,29 +1,181 @@
-import { postToEditor } from './editor-bridge';
+import { getCustomCatalog } from './custom/catalog';
+import type { CustomCatalog } from './custom/types';
+import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
+
+/**
+ * The single announce the storefront makes to the editor: which placeholder
+ * slugs this document mounted, and — only for a proven designer — which
+ * developer-authored blocks this build can render.
+ *
+ * One debounced flush carries both. Placeholders register as their components
+ * mount, while custom blocks register at module evaluation (before any
+ * placeholder exists), so the catalog re-arms the SAME timer instead of owning
+ * one: two timers would mean two frames, and the editor treats every frame as
+ * a complete answer.
+ */
 const placeholderRegistry = new Set<string>();
 let registryTimeout: NodeJS.Timeout | null = null;
+let listeningForDesigner = false;
+/**
+ * The designer re-announce is a ONE-SHOT. See `handleEditorMessage` — the
+ * editor answers every announce with the same cookie it answered the last one
+ * with, so an unlatched re-arm is an endless round trip.
+ */
+let designerReannounceSpent = false;
 
-export const registerPlaceholder = (slug: string) => {
-  placeholderRegistry.add(slug);
+interface PlaceholdersAvailablePayload {
+  placeholders: string[];
+  /**
+   * ALWAYS THE WHOLE CATALOG, never a delta. An in-iframe route change
+   * remounts every placeholder and produces a second announce; the receiver
+   * must replace what it holds rather than merge, or a block the build no
+   * longer registers would live on in the picker and be offered for a type
+   * nothing can render.
+   */
+  customBlocks?: CustomCatalog;
+}
+
+const isFramed = (): boolean =>
+  typeof window !== 'undefined' &&
+  Boolean(window.parent) &&
+  window.self !== window.top;
+
+/**
+ * The editor-proven designer flag — the same signal `chrome/checkout-pieces.ts`
+ * exports as `isThemeEditorDesigner`, set only after a trusted
+ * SET_THEME_EDITOR_COOKIE arrives through the origin-guarded bridge.
+ *
+ * Read inline rather than imported so the module every placeholder pulls in
+ * does not drag the checkout outlet store into its graph.
+ */
+const isDesignerAttached = (): boolean =>
+  typeof window !== 'undefined' &&
+  (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner ===
+    true;
+
+const flush = () => {
+  registryTimeout = null;
+
+  // An empty announce is not a harmless no-op. The editor's only
+  // PLACEHOLDERS_AVAILABLE subscriber (loadThemeForPlaceholders) runs
+  // setIsLoadingTheme, clears its cache and swaps the active placeholder set
+  // before its first await — so a frame carrying no slugs makes it reload the
+  // theme against nothing. The custom-block re-arm below fires before any
+  // placeholder has mounted, which is exactly when that would happen.
+  if (placeholderRegistry.size === 0) return;
+  if (!isFramed()) return;
 
+  const data: PlaceholdersAvailablePayload = {
+    placeholders: Array.from(placeholderRegistry)
+  };
+
+  // Being framed is NOT enough to hand the catalog over. A storefront is
+  // legitimately framed in production — payment providers, marketplace
+  // previews — and the catalog is brand IP: every block name, every setting
+  // key and every option list this build ships. The placeholder slugs are
+  // route names and keep their existing behaviour; the catalog waits for the
+  // editor to have proven itself.
+  if (isDesignerAttached()) {
+    const customBlocks = getCustomCatalog();
+    // Omitted entirely rather than sent empty: a build with no custom blocks
+    // must be indistinguishable from one whose catalog simply is not this
+    // frame's business.
+    if (customBlocks) data.customBlocks = customBlocks;
+  }
+
+  postToEditor({
+    type: 'PLACEHOLDERS_AVAILABLE',
+    data
+  });
+};
+
+const scheduleAnnounce = () => {
   if (registryTimeout) {
     clearTimeout(registryTimeout);
   }
 
-  registryTimeout = setTimeout(() => {
-    if (
-      typeof window !== 'undefined' &&
-      window.parent &&
-      window.self !== window.top
-    ) {
-      const availablePlaceholders = Array.from(placeholderRegistry);
-      postToEditor({
-        type: 'PLACEHOLDERS_AVAILABLE',
-        data: { placeholders: availablePlaceholders }
-      });
-    }
-  }, 100);
+  registryTimeout = setTimeout(flush, 100);
+};
+
+/**
+ * Re-announce once the editor proves itself.
+ *
+ * The designer flag arrives in the editor's reply to IFRAME_READY, which is a
+ * postMessage round trip — nothing guarantees it lands inside the 100ms
+ * debounce. Without this the first flush would go out gated shut and the
+ * catalog would never be offered again for the life of the document, leaving
+ * the picker with no custom blocks on exactly the loads where the handshake
+ * was slow.
+ *
+ * The listener is attached on first placeholder registration (never at module
+ * scope, which would give the barrel an import side effect) and then kept for
+ * the life of the document, like the one in browse-mode.ts.
+ *
+ * AT MOST ONCE, and only when there is something a frame could not already
+ * carry. The editor does not send this cookie once — it answers EVERY
+ * PLACEHOLDERS_AVAILABLE with it (`theme-iframe-service.ts`, the same handler
+ * that ingests the catalog), so an unlatched re-arm is a ping-pong:
+ * announce -> cookie -> announce, every 100ms for the life of the document.
+ * Each lap costs the editor a full theme reload, because that announce is what
+ * `loadThemeForPlaceholders` subscribes to — it clears the widget cache,
+ * rewrites the active placeholder set and refetches every widget.
+ */
+const handleEditorMessage = (event: MessageEvent) => {
+  if (!isTrustedEditorEvent(event)) return;
+  if (event.data?.type !== 'SET_THEME_EDITOR_COOKIE') return;
+  if (designerReannounceSpent) return;
+  designerReannounceSpent = true;
+
+  // A build that registers no custom block has nothing to add to a frame it
+  // has already sent, so it stays at exactly one announce — the behaviour
+  // every brand shipping no custom block had before any of this existed.
+  if (!getCustomCatalog()) return;
+
+  // Re-arm rather than flush: the flag itself is set by the placeholder
+  // client's own listener, and listener order across modules is not ours to
+  // depend on. By the time the timer fires both have run.
+  scheduleAnnounce();
+};
+
+const listenForDesigner = () => {
+  if (listeningForDesigner || typeof window === 'undefined') return;
+  listeningForDesigner = true;
+  window.addEventListener('message', handleEditorMessage);
+};
+
+export const registerPlaceholder = (slug: string) => {
+  placeholderRegistry.add(slug);
+  listenForDesigner();
+  scheduleAnnounce();
+};
+
+/**
+ * Re-arms the placeholder announce so a registered barrel rides the next
+ * flush. Called by `registerCustomBlocks` at module evaluation; posts nothing
+ * on its own, because a document with no placeholders has nothing to say.
+ */
+export const announceCustomBlocks = () => {
+  scheduleAnnounce();
 };
 
 export const unregisterPlaceholder = (slug: string) => {
   placeholderRegistry.delete(slug);
 };
+
+/**
+ * Test-only. Module state outlives a test file, and the window listener
+ * outlives even a re-imported copy of this module — one jsdom window collects
+ * every copy's listener, so without this each test would announce for all of
+ * its predecessors as well.
+ */
+export const __resetPlaceholderRegistryForTests = () => {
+  if (registryTimeout) clearTimeout(registryTimeout);
+  registryTimeout = null;
+  placeholderRegistry.clear();
+  designerReannounceSpent = false;
+
+  if (typeof window !== 'undefined') {
+    window.removeEventListener('message', handleEditorMessage);
+  }
+  listeningForDesigner = false;
+};