fix: resolve race condition where Design Notes button never appeared in hub top bar

The hpux-prototypes iframe posts hpux-prototype-loaded during bootstrap, which
fires before the hub's useEffect listener is registered when the iframe loads from
cache. Fix: hub now sends an hpux-hub-ready ping to the iframe 100 ms after mount
(and on each prototype change), and PrototypeContext re-sends hpux-prototype-loaded
on receiving that ping if a prototype is already loaded.

Also adds designNotes to shiri-alerting-ui-v2 so the button appears for both
shiri-alerting-ui-v2 and observability-agentic-troubleshooting-ai as intended.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: matthewcarleton

hpux-prototypes/src/app/core/PrototypeContext.tsx

@@ -24,6 +24,10 @@ export const PrototypeProvider: React.FC<PrototypeProviderProps> = ({ children }
   const [isBootstrapping, setIsBootstrapping] = useState(true);
   const [error, setError] = useState<Error | null>(null);
 
+  // Ref keeps current prototype accessible inside event handlers without stale closures.
+  const currentPrototypeRef = useRef<PrototypeModule | null>(null);
+  currentPrototypeRef.current = currentPrototype;
+
   /**
    * Load a prototype by ID
    */
@@ -84,6 +88,34 @@ export const PrototypeProvider: React.FC<PrototypeProviderProps> = ({ children }
   const loadPrototypeRef = useRef(loadPrototype);
   loadPrototypeRef.current = loadPrototype;
 
+  // When embedded in the hub, respond to the hub's ready ping by re-sending prototype data.
+  // This resolves the race where the iframe's postMessage fires before the hub's listener
+  // is registered (common with cached/fast loads).
+  useEffect(() => {
+    if (window.parent === window) return;
+    const handleHubReady = (event: MessageEvent) => {
+      if (
+        event.data !== null &&
+        typeof event.data === 'object' &&
+        event.data.type === 'hpux-hub-ready' &&
+        currentPrototypeRef.current
+      ) {
+        const proto = currentPrototypeRef.current;
+        window.parent.postMessage(
+          {
+            type: 'hpux-prototype-loaded',
+            designNotes: proto.config.designNotes ?? null,
+            prototypeName: proto.config.name,
+            status: proto.config.status,
+          },
+          '*',
+        );
+      }
+    };
+    window.addEventListener('message', handleHubReady);
+    return () => window.removeEventListener('message', handleHubReady);
+  }, []);
+
   /**
    * Initialize registry, then load prototype from (in order): ?prototype=, URL path match,
    * or last session — supports GitHub Pages shared links and same-tab reload.

hpux-prototypes/src/app/prototypes/shiri-alerting-ui-v2/prototype.config.ts

@@ -45,4 +45,23 @@ export const config: PrototypeConfig = {
   // Metadata
   createdAt: '2025-12-24',
   updatedAt: '2025-12-24',
+
+  designNotes: {
+    overview:
+      'v2 of the Multi-cluster Alerting UI. Navigation moves from a dedicated Alerting page to a filtering model: clicking a cluster in the heatmap filters the Firing alerts tab in place. Keeps the SRE in one context rather than bouncing between views.',
+    pages: [
+      {
+        name: 'Clusters Health',
+        path: '/fleet-management/alerting',
+        notes:
+          'Heatmap entry point. Each cluster cell is clickable and sets the active filter for the Firing Alerts tab. Severity bands and cluster status badges are the primary scannable signal.',
+      },
+      {
+        name: 'Firing Alerts',
+        path: '/fleet-management/alerting/firing',
+        notes:
+          'Full alert table filtered by the selected cluster. Column set, sort order, and bulk-action affordances are open for stakeholder review — confirm with Shiri before finalising.',
+      },
+    ],
+  },
 };

hub/src/App.tsx

@@ -1,5 +1,5 @@
 import type { Dispatch, SetStateAction } from "react";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 
 import {
   Link,
@@ -1306,6 +1306,8 @@ function HpuxPrototypesEmbedFullscreenPage() {
   const [isDesignNotesOpen, setIsDesignNotesOpen] = useState(false);
   const [prototypeStatus, setPrototypeStatus] = useState<string | undefined>(undefined);
 
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
   const prototype = searchParams.get("prototype")?.trim() ?? "";
   const valid = prototype.length > 0 && HPUX_PROTOTYPE_ID_RE.test(prototype);
 
@@ -1327,6 +1329,16 @@ function HpuxPrototypesEmbedFullscreenPage() {
     return () => window.removeEventListener("message", handler);
   }, []);
 
+  // Fix race condition: after the prototype iframe (re)loads, ping it so it re-sends its data
+  // even if its postMessage fired before our listener was registered.
+  useEffect(() => {
+    if (!valid) return;
+    const t = setTimeout(() => {
+      iframeRef.current?.contentWindow?.postMessage({ type: "hpux-hub-ready" }, "*");
+    }, 100);
+    return () => clearTimeout(t);
+  }, [prototype, valid]);
+
   // Reset design notes and status when the prototype param changes so stale data never shows.
   useEffect(() => {
     setDesignNotes(null);
@@ -1436,7 +1448,7 @@ function HpuxPrototypesEmbedFullscreenPage() {
         className="ops-hub-design-notes-drawer"
       >
         <DrawerContent panelContent={designNotesPanelContent}>
-          <iframe key={src} title={label} className="ops-hub-embed-fullscreen-frame" src={src} />
+          <iframe ref={iframeRef} key={src} title={label} className="ops-hub-embed-fullscreen-frame" src={src} />
         </DrawerContent>
       </Drawer>
     </div>