@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/components/ForgeErrorBeacon.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * DEV-ONLY storefront error beacon. Renders nothing.
+ *
+ * Registers `window.onerror` + `window.onunhandledrejection` and POSTs the failure
+ * detail to the same-origin Next API route `/__forge_beacon`, which forwards it
+ * server-side to the in-pod workspace-manager receiver. This surfaces the crash
+ * class the pod's dev-server stderr scan CANNOT see: a client-component runtime
+ * error or a hydration/SSR-boundary throw that never reaches the dev-server's
+ * output. The browser only ever talks SAME-ORIGIN — the API route is the only thing
+ * that knows the pod-internal receiver address.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is inlined
+ * by the bundler, so the effect body is dead-code-eliminated from `next build` /
+ * `next start` output — a deployed storefront registers no global error handlers and
+ * has no beacon API route reachable in prod (the route itself is dev-gated too).
+ *
+ * The beacon is best-effort and never blocks the page: the POST is fire-and-forget
+ * with `keepalive` so it survives an unload, and a delivery failure is swallowed —
+ * the page's own error boundary still renders. The full
+ * browser → API route → pod → supervisor-fold path is exercised at the e2e layer,
+ * not in this template.
+ *
+ * Every report carries the revision the PAGE WAS SERVED AT (#847), read out of the
+ * `forge-revision` meta tag the server wrote into this document rather than looked
+ * up fresh at throw time. That distinction is the entire point: a fresh lookup would
+ * answer whatever is live NOW, so a promote landing between serve and throw would
+ * make this report blame the new revision for the old one's crash — and the pod's
+ * same-revision fold would then mark a healthy tree DEGRADED. The tag cannot drift,
+ * because it was rendered with the markup that broke.
+ */
+export function ForgeErrorBeacon() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+
+    /**
+     * The revision this document was SERVED at, or `undefined` when the server
+     * did not stamp one (production, or a pod that cannot resolve it — both
+     * normal). `'forge-revision'` is repeated here as a literal on purpose: the
+     * resolver lives in `src/server/forge/live-revision.ts`, which a client
+     * component must not import, so this is the same repeated-contract shape the
+     * `/__forge_beacon` URL already uses across this feature's producers.
+     *
+     * An absent tag, an absent attribute and an empty value all answer
+     * `undefined`, which `JSON.stringify` then omits from the body entirely —
+     * so an unstamped page sends exactly the payload it sent before, and the pod
+     * keeps its existing untagged behaviour instead of receiving a blank string
+     * it would have to interpret.
+     */
+    const readServedRevision = (): string | undefined => {
+      const content = document
+        .querySelector('meta[name="forge-revision"]')
+        ?.getAttribute('content');
+      if (!content) return undefined;
+      return content;
+    };
+
+    const send = (message: string, stack?: string) => {
+      const body = JSON.stringify({
+        message,
+        stack,
+        route: window.location.pathname,
+        source: 'browser',
+        atRevision: readServedRevision(),
+      });
+      // Same-origin POST; keepalive lets it survive a navigation/unload. A failed
+      // delivery is intentionally swallowed — the beacon is a backstop signal, not
+      // a hard dependency of the page.
+      void fetch('/__forge_beacon', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        keepalive: true,
+      }).catch(() => undefined);
+    };
+
+    const onError = (event: ErrorEvent) => {
+      send(event.message || 'window.onerror', event.error?.stack);
+    };
+    const onRejection = (event: PromiseRejectionEvent) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason ?? 'unhandledrejection');
+      const stack = reason instanceof Error ? reason.stack : undefined;
+      send(message, stack);
+    };
+
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+    return () => {
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+    };
+  }, []);
+
+  return null;
+}

package/templates/storefront-shadcn/src/components/ForgeTracker.tsx

@@ -0,0 +1,479 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+import {
+  type MarketingIdentifier,
+  parseMarketingParams,
+  type UtmParams,
+} from '../lib/marketing-params';
+import { mintUuid } from '../lib/uuid';
+
+/**
+ * Storefront event tracker (design doc S7). Renders nothing.
+ *
+ * The single client-side emitter of marketing events. Everything goes through
+ * the same-origin `/__fc/track` relay — NEVER the SDK's WebSocket singleton,
+ * whose connection pins one identity and would mis-attribute every event after
+ * a login. The relay replays the shopper's `forgecart-session` cookie per
+ * request, so attribution follows the identity.
+ *
+ * What it emits:
+ *   - `page_view` on the initial load and on every App-Router route change
+ *     (client-effect emission is the only prefetch-safe choice — `<Link>`
+ *     prefetches run middleware and RSC fetches but no client effects).
+ *     `properties.referrerPath` is the module-tracked previous pathname:
+ *     `document.referrer` is frozen across soft navigations and must not be
+ *     read per-view; only the initial load additionally carries it (origin
+ *     level under the default Referrer-Policy) as `properties.referrer`.
+ *   - `cta_click` from ONE delegated capture-phase click listener for any
+ *     `[data-fc-track]` element — the element stays dumb (a semantic slug in
+ *     `properties.trackId`); what the click MEANS is backend automation
+ *     config, never deployed code.
+ *   - `heartbeat` every {@link HEARTBEAT_MS} while the tab is visible (plus
+ *     one on refocus) — liveness plumbing only, excluded from aggregates.
+ *
+ * What a landing additionally does: a view whose URL carries marketing
+ * parameters reads them once (`lib/marketing-params`). The click IDs go to
+ * {@link IDENTIFY_ENDPOINT} and that request is AWAITED before the view is
+ * enqueued, so the identity the relay mints carries them instead of the two
+ * racing; the campaign tags are held for the rest of the visit and ride every
+ * later event. A URL without any of them does nothing at all — no request, no
+ * stored state, no change to the events below.
+ *
+ * Delivery: events buffer and flush as one batch at {@link FLUSH_MAX_EVENTS}
+ * events or after an age timer via `fetch(keepalive)` — the FIRST batch waits
+ * {@link ESTABLISHMENT_GRACE_MS}, every later batch {@link FLUSH_INTERVAL_MS}
+ * (see the grace rationale on the constant); `sendBeacon` is used ONLY for the
+ * `pagehide` flush (its unload-time queueing guarantee is the one thing
+ * keepalive fetch lacks). Every event carries a client-minted `eventId`
+ * (`crypto.randomUUID`) — the server dedupes on it, so an accidental
+ * double-send is harmless. Delivery is fire-and-forget: failures are
+ * swallowed and never retried; analytics must never break the storefront.
+ *
+ * Deliberately NO 30-second same-path dedup (the old `ForgeAnalytics`
+ * behavior): it was live-map-correct but funnel-lossy — A→B→A inside 30s
+ * dropped the return view. The short same-signal suppressors (300ms; also what
+ * keeps StrictMode's double-mount from double-emitting, via module scope) plus
+ * the server-side `eventId` dedupe replace it, so revisits are recorded.
+ *
+ * Two deliberate suppressions:
+ *   - missing config (the pod image pre-renders the template before
+ *     `forgecart init` writes `.env`) → the tracker is inert;
+ *   - framed embeds (`window.parent !== window`) → the visual editor's
+ *     artboard preview emits nothing, so funnels stay production-visitor-only.
+ */
+
+const HEARTBEAT_MS = 60_000;
+/** Minimum spacing between heartbeats (refocus storms, StrictMode remounts). */
+const HEARTBEAT_MIN_SPACING_MS = 30_000;
+/** Batch flush thresholds: whichever of size / age is hit first sends. */
+const FLUSH_MAX_EVENTS = 10;
+const FLUSH_INTERVAL_MS = 500;
+/**
+ * Age timer for the FIRST batch only. On a cookie-less first touch the relay
+ * and the first cart Server Action race to mint the shopper session, and the
+ * browser keeps whichever `Set-Cookie` lands last — if the tracker's ~500ms
+ * page_view batch wins that race against a fast add-to-cart, the cookie flips
+ * away from the session holding the just-created cart. Holding the initial
+ * flush for this grace lets the cart's cookie land first, so the relay batch
+ * then CARRIES it and rides the cart's session instead of minting a rival
+ * (design doc S7: the first tracked interaction establishes the identity the
+ * cart later reuses — establishment still happens, just not mid-race).
+ * Events are timestamped at enqueue (`occurredAt`), so deferral loses nothing.
+ */
+const ESTABLISHMENT_GRACE_MS = 2_000;
+/** Same-signal suppression window (per click slug; per page_view path). */
+const SUPPRESS_MS = 300;
+/**
+ * Minimum VISIBLE dwell before a route's scroll_depth summary is worth a
+ * row (#1022 phase 2b) — filters bounce-through navigations and StrictMode's
+ * dev-only phantom unmount.
+ */
+const ENGAGEMENT_MIN_DWELL_MS = 250;
+const TRACK_ENDPOINT = '/__fc/track';
+/** Landing-only: where a captured click ID is attached to the shopper. */
+const IDENTIFY_ENDPOINT = '/__fc/identify';
+
+/** One buffered event — the relay forwards these fields to `trackEvent`. */
+interface TrackedEvent {
+  eventType: string;
+  eventId: string;
+  occurredAt: string;
+  properties?: Record<string, unknown>;
+  /**
+   * The campaign this visit arrived on, repeated on every event of the visit.
+   *
+   * Spelled out rather than reused from the parser's `UtmParams` because the
+   * five fields are a CONTRACT with the relay's allowlist, not a shape that
+   * should follow the parser if it ever grows a sixth tag. An absent tag is an
+   * absent KEY here, never `''`: the backend stores a present empty string as a
+   * real ClickHouse dimension, where it can no longer be told apart from a
+   * campaign that genuinely has no medium.
+   */
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}
+
+// Module scope on purpose: the buffer, timers and suppressors must survive
+// StrictMode's mount → unmount → mount cycle (a ref would reset) and there is
+// exactly one tracker per page.
+let buffer: TrackedEvent[] = [];
+let flushTimer: number | null = null;
+/** True once any batch has gone out — ends the establishment grace. */
+let firstBatchSent = false;
+const lastClickAtBySlug = new Map<string, number>();
+let lastPageView: { path: string; at: number } | null = null;
+let previousPathname: string | null = null;
+let lastHeartbeatAt = 0;
+/**
+ * The campaign tags of the landing that started this visit. Module scope for
+ * the same reason as the buffer — StrictMode remounts the component and a ref
+ * would reset — and because there is nowhere else to read them from: an
+ * internal navigation carries no query string.
+ */
+let capturedUtm: UtmParams = {};
+/**
+ * The click IDs already sent to {@link IDENTIFY_ENDPOINT}, as `key=value&…`.
+ *
+ * Module scope so StrictMode's mount → unmount → mount sends ONE identify for
+ * one landing. A signature rather than a boolean because "once per captured
+ * landing" is not "once per visit": a shopper who clicks a second ad back into
+ * the store brings a different click ID that must still be delivered, while a
+ * revisit of the same landing URL must not send the same one twice.
+ */
+let identifiedClickIds: string | null = null;
+
+/**
+ * Consent extension point. Tracking currently needs no opt-in, so this is a
+ * no-op returning `true`; the merchant cookie-banner fast-follow implements
+ * the real gate HERE (read the stored consent state) and every emission path
+ * already respects it — nothing enters the buffer without consent.
+ */
+function hasTrackingConsent(): boolean {
+  return true;
+}
+
+/**
+ * Client-side idempotency key via the shared insecure-context-safe minter
+ * (lib/uuid.ts) — a thrown TypeError inside a click listener would violate
+ * the "analytics never breaks the storefront" invariant.
+ */
+function mintEventId(): string {
+  return mintUuid();
+}
+
+/** Stamp and buffer one event; flush on size, else arm the age timer. */
+function enqueue(eventType: string, properties?: Record<string, unknown>): void {
+  if (!hasTrackingConsent()) return;
+  const event: TrackedEvent = {
+    eventType,
+    eventId: mintEventId(),
+    occurredAt: new Date().toISOString(),
+    // Spreading an empty object adds no keys, so an organic visit emits exactly
+    // the event shape it did before any of this existed.
+    ...capturedUtm,
+  };
+  if (properties) event.properties = properties;
+  buffer.push(event);
+
+  if (buffer.length >= FLUSH_MAX_EVENTS) {
+    flush();
+    return;
+  }
+  if (flushTimer === null) {
+    const delay = firstBatchSent ? FLUSH_INTERVAL_MS : ESTABLISHMENT_GRACE_MS;
+    flushTimer = window.setTimeout(flush, delay);
+  }
+}
+
+/** Drain the buffer, returning the batch to send (empties module state). */
+function drain(): TrackedEvent[] {
+  if (flushTimer !== null) {
+    window.clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  const events = buffer;
+  buffer = [];
+  // The grace ends once a batch actually goes out — from then on the age
+  // timer runs at the normal cadence.
+  if (events.length > 0) firstBatchSent = true;
+  return events;
+}
+
+/** Primary delivery: keepalive fetch, fire-and-forget, failures swallowed. */
+function flush(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ events }),
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+/**
+ * Read this URL's marketing parameters and act on what it carries.
+ *
+ * Resolves once the click IDs have been delivered — the caller awaits it so the
+ * identify request and the first tracked batch cannot race. Does nothing
+ * whatsoever for a URL that carries none, which is the overwhelmingly common
+ * case and the reason the parser returns a union.
+ */
+async function captureLanding(search: string): Promise<void> {
+  // Consent is checked HERE as well as in `enqueue` because the identify
+  // request is not a buffered event: it leaves on its own, carrying a click ID
+  // that identifies the visitor more directly than anything in the buffer, so
+  // a gate that only guards `enqueue` would let it past a visitor who declined.
+  if (!hasTrackingConsent()) return;
+  const marketing = parseMarketingParams(search);
+  if (marketing.kind === 'none') return;
+
+  // Merge, never clear — the same semantics `middleware.ts` uses for the
+  // `fc-exp` cookie. Only a URL that carries tags updates them, so an internal
+  // navigation keeps the campaign the visitor arrived on, and a second ad
+  // landing legitimately overwrites the tags it brings.
+  capturedUtm = { ...capturedUtm, ...marketing.utm };
+
+  if (marketing.identifiers.length === 0) return;
+  const signature = signClickIds(marketing.identifiers);
+  if (signature === identifiedClickIds) return;
+  // Recorded BEFORE the await: StrictMode's second mount runs while this
+  // request is still in flight and must find the landing already claimed.
+  identifiedClickIds = signature;
+  await fetch(IDENTIFY_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ identifiers: marketing.identifiers }),
+    keepalive: true,
+  }).catch(() => undefined); // same swallow as flush(): analytics never breaks the storefront
+}
+
+/** The click IDs of one landing as a comparable string, in parser order. */
+function signClickIds(identifiers: readonly MarketingIdentifier[]): string {
+  return identifiers.map(({ key, value }) => `${key}=${value}`).join('&');
+}
+
+/**
+ * Capture the landing, THEN record the view.
+ *
+ * The order is the whole point. The first request of a visit is what mints the
+ * shopper session, so sending the identify and the page_view in parallel would
+ * mint one identity per request and split the visit in two — the click ID on
+ * one, every tracked event on the other, and no attribution joining them.
+ */
+async function emitPageView(properties: Record<string, unknown>): Promise<void> {
+  await captureLanding(window.location.search);
+  enqueue('page_view', properties);
+}
+
+/**
+ * `pagehide` delivery: `sendBeacon` — the only flush that uses it, for its
+ * survive-the-unload queueing guarantee. Falls back to keepalive fetch where
+ * the API is unavailable.
+ */
+function flushOnPagehide(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  const body = JSON.stringify({ events });
+  if (typeof navigator.sendBeacon === 'function') {
+    navigator.sendBeacon(TRACK_ENDPOINT, new Blob([body], { type: 'application/json' }));
+    return;
+  }
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+/**
+ * `enabled` is computed SERVER-side (env presence) and passed as a boolean —
+ * the tracker only needs to know whether the relay is configured; the channel
+ * token itself must never serialize into the RSC payload.
+ */
+export function ForgeTracker({ enabled }: { enabled: boolean }) {
+  const pathname = usePathname();
+
+  // page_view — initial load + every route change.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+    const now = Date.now();
+    if (lastPageView && lastPageView.path === pathname && now - lastPageView.at < SUPPRESS_MS) {
+      return;
+    }
+    lastPageView = { path: pathname, at: now };
+    const properties: Record<string, unknown> = { path: pathname };
+    if (previousPathname !== null) {
+      properties.referrerPath = previousPathname;
+    } else if (document.referrer) {
+      properties.referrer = document.referrer;
+    }
+    previousPathname = pathname;
+    // The suppressor above is already stamped, so the double mount StrictMode
+    // performs while this is in flight still emits exactly one view.
+    void emitPageView(properties);
+  }, [enabled, pathname]);
+
+  // cta_click — one delegated capture-phase listener — and the pagehide flush.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    const onClick = (event: Event): void => {
+      if (!(event.target instanceof Element)) return;
+      const tracked = event.target.closest('[data-fc-track]');
+      if (!tracked) return;
+      const trackId = tracked.getAttribute('data-fc-track');
+      if (!trackId) return;
+      const now = Date.now();
+      const lastAt = lastClickAtBySlug.get(trackId);
+      if (lastAt !== undefined && now - lastAt < SUPPRESS_MS) return;
+      lastClickAtBySlug.set(trackId, now);
+      enqueue('cta_click', { trackId, path: window.location.pathname });
+    };
+    const onPagehide = (): void => flushOnPagehide();
+
+    // Capture phase so the event is seen even when a handler below stops
+    // propagation (e.g. a framework's synthetic-event stopPropagation).
+    document.addEventListener('click', onClick, true);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      document.removeEventListener('click', onClick, true);
+      window.removeEventListener('pagehide', onPagehide);
+    };
+  }, [enabled]);
+
+  // heartbeat — while visible, plus one on refocus; paused while hidden.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let interval: ReturnType<typeof setInterval> | null = null;
+
+    const beat = (): void => {
+      const now = Date.now();
+      if (now - lastHeartbeatAt < HEARTBEAT_MIN_SPACING_MS) return;
+      lastHeartbeatAt = now;
+      enqueue('heartbeat');
+    };
+    const start = (): void => {
+      if (interval !== null) return;
+      interval = setInterval(beat, HEARTBEAT_MS);
+    };
+    const stop = (): void => {
+      if (interval === null) return;
+      clearInterval(interval);
+      interval = null;
+    };
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'visible') {
+        beat();
+        start();
+      } else {
+        stop();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisibility);
+    if (document.visibilityState === 'visible') start();
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      stop();
+    };
+  }, [enabled]);
+
+  // scroll_depth — ONE engagement summary per route (#1022 phase 2b): the
+  // max scroll depth reached (percent, 0-100) and the VISIBLE dwell time,
+  // emitted when the route unmounts (client-side navigation) or the page
+  // hides. Rides the dormant `scroll_depth` event type already in the
+  // default shop allowlist; the server hoists both properties into the
+  // typed `scrollDepth`/`durationMs` ClickHouse columns (CH 005).
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let maxDepthPct = 0;
+    let visibleMs = 0;
+    let visibleSince: number | null =
+      document.visibilityState === 'visible' ? performance.now() : null;
+    let ticking = false;
+    let emitted = false;
+
+    const measure = (): void => {
+      ticking = false;
+      const doc = document.documentElement;
+      // A page shorter than the viewport is fully seen — 100 by definition;
+      // otherwise percent of total document height brought into view.
+      const pct =
+        doc.scrollHeight <= window.innerHeight
+          ? 100
+          : Math.min(
+              100,
+              Math.round(((window.scrollY + window.innerHeight) / doc.scrollHeight) * 100),
+            );
+      if (pct > maxDepthPct) maxDepthPct = pct;
+    };
+    const onScroll = (): void => {
+      if (ticking) return;
+      ticking = true;
+      requestAnimationFrame(measure);
+    };
+    const onVisibility = (): void => {
+      const now = performance.now();
+      if (document.visibilityState === 'visible') {
+        visibleSince ??= now;
+        return;
+      }
+      if (visibleSince !== null) {
+        visibleMs += now - visibleSince;
+        visibleSince = null;
+      }
+    };
+    const emit = (): void => {
+      if (emitted) return;
+      if (visibleSince !== null) {
+        visibleMs += performance.now() - visibleSince;
+        visibleSince = null;
+      }
+      // Dwell floor: a route that never accumulated meaningful visible time
+      // has no engagement story — this also swallows StrictMode's dev-only
+      // mount/unmount phantom, which would otherwise emit a zero-dwell row.
+      if (visibleMs < ENGAGEMENT_MIN_DWELL_MS) return;
+      emitted = true;
+      enqueue('scroll_depth', {
+        path: window.location.pathname,
+        scrollDepth: maxDepthPct,
+        durationMs: Math.round(visibleMs),
+      });
+    };
+    const onPagehide = (): void => {
+      // Emit BEFORE the flush so the summary rides the pagehide beacon —
+      // flushOnPagehide drains-and-no-ops on empty, so the sibling pagehide
+      // listener's own call stays harmless.
+      emit();
+      flushOnPagehide();
+    };
+
+    measure(); // above-the-fold baseline before any scroll fires
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('pagehide', onPagehide);
+      emit(); // client-side route change: summarize the route being left
+    };
+  }, [enabled, pathname]);
+
+  return null;
+}

package/templates/storefront-shadcn/src/components/ForgecartDesigner.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Mounts the ForgeCart visual-editor guest runtime. Renders nothing.
+ *
+ * The runtime stays dormant until activated: it registers a single `message`
+ * listener and posts a READY beacon, then waits for the dashboard host to
+ * drive a nonce-gated handshake over `postMessage` (the activation nonce
+ * arrives via the `#fcd=` URL fragment — there is no env switch). On a page
+ * that is not embedded in an iframe it never even loads.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is
+ * inlined by the bundler, so the effect body — including the dynamic import
+ * and its chunk — is dead-code-eliminated from `next build` output.
+ */
+export function ForgecartDesigner() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+    // Top-level pages have no designer host; skip loading the chunk entirely.
+    if (window.parent === window) {
+      return;
+    }
+    let cancelled = false;
+    let dispose: (() => void) | undefined;
+    const install = async () => {
+      const mod = await import('@forgecart/designer-runtime');
+      if (cancelled) {
+        return;
+      }
+      dispose = mod.installDesignerRuntime();
+    };
+    void install();
+    return () => {
+      cancelled = true;
+      dispose?.();
+    };
+  }, []);
+  return null;
+}