@tribe-nest/forge 3.4.0 → 3.9.0

package/src/ui/shell/PreviewDiagnostics.tsx

@@ -0,0 +1,80 @@
+import { useState } from "react";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+import { previewDiagnosticsMessage } from "./diagnosticsGating";
+
+/**
+ * The loud failure. Rendered by `<TribeNestApp>` in the builder preview and on
+ * review Workers — never on the live published site (see
+ * `previewDiagnosticsEnabled`).
+ *
+ * EVERY COLOR HERE IS A LITERAL, on purpose. This banner announces that the
+ * theme could not be fetched, so it cannot itself be themed: `var(--forge-*)`
+ * would resolve to the very fallbacks it is warning about, and on a dark-ish
+ * default it could render invisible. It is also the one component that must
+ * survive a totally broken render, so it takes nothing from context.
+ */
+export function PreviewDiagnostics({ diagnostics }: { diagnostics: ForgeSsrDiagnostics }) {
+  const [open, setOpen] = useState(false);
+  const msg = previewDiagnosticsMessage(diagnostics);
+
+  return (
+    <div
+      role="alert"
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        right: 0,
+        // Above anything a site can reasonably stack, including sticky navs.
+        zIndex: 2147483000,
+        background: "#7f1d1d",
+        color: "#fef2f2",
+        borderBottom: "1px solid #dc2626",
+        fontFamily:
+          'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+        fontSize: 13,
+        lineHeight: 1.45,
+        boxShadow: "0 2px 12px rgba(0,0,0,0.35)",
+      }}
+    >
+      <div style={{ maxWidth: 900, margin: "0 auto", padding: "10px 14px" }}>
+        <div style={{ display: "flex", alignItems: "flex-start", gap: 10 }}>
+          <span aria-hidden style={{ fontSize: 15, lineHeight: 1.3 }}>
+            ⚠️
+          </span>
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <strong style={{ fontWeight: 700 }}>{msg.title}</strong>
+            <div style={{ marginTop: 3, color: "#fecaca" }}>{msg.consequence}</div>
+          </div>
+          <button
+            type="button"
+            onClick={() => setOpen((v) => !v)}
+            aria-expanded={open}
+            style={{
+              flexShrink: 0,
+              background: "transparent",
+              border: "1px solid #f87171",
+              borderRadius: 6,
+              color: "#fef2f2",
+              cursor: "pointer",
+              fontSize: 12,
+              padding: "3px 9px",
+            }}
+          >
+            {open ? "Hide" : "Details"}
+          </button>
+        </div>
+
+        {open && (
+          <ul style={{ margin: "9px 0 0", padding: "0 0 0 26px", color: "#fecaca" }}>
+            {msg.details.map((line) => (
+              <li key={line} style={{ marginTop: 2, wordBreak: "break-word" }}>
+                {line}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/ui/shell/TribeNestApp.tsx

@@ -8,7 +8,10 @@ import { CookieConsent } from "../styled/CookieConsent";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
 import { PoweredBy } from "./PoweredBy";
+import { PreviewDiagnostics } from "./PreviewDiagnostics";
 import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
+import { previewDiagnosticsEnabled, resolvePreviewDiagnostics } from "./diagnosticsGating";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
 import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
 
@@ -38,6 +41,13 @@ export interface TribeNestAppProps extends Omit<ForgeProviderProps, "children">
   state?: "draft" | "published";
   /** Href for the client-injected manifest link fallback. */
   manifestHref?: string;
+  /**
+   * What failed while bootstrapping this render, from `fetchSiteBootstrap`.
+   * Surfaced as a banner in the editor preview / review Workers only. Optional:
+   * a shell that still calls `fetchContentDocument`/`fetchSiteConfig` separately
+   * gets a less detailed banner inferred from a null `initialSiteConfig`.
+   */
+  diagnostics?: ForgeSsrDiagnostics | null;
   /** Turn individual shell concerns off (all default on). */
   analytics?: boolean;
   pwa?: boolean;
@@ -100,6 +110,7 @@ export function TribeNestApp({
   editable,
   state,
   manifestHref = "/manifest.webmanifest",
+  diagnostics,
   analytics = true,
   pwa = true,
   cookieConsent = true,
@@ -108,8 +119,21 @@ export function TribeNestApp({
   // Register the SW + offer install only on the live published site — never in
   // the HMR editor or on a preview-<versionId>.* review Worker (state="draft").
   const pwaEnabled = shellPwaEnabled({ pwa, editable, state });
+  // A failed SSR bootstrap renders a complete-looking page built entirely from
+  // fallbacks — indistinguishable from an unconfigured site. Say so, where the
+  // people who can fix it are looking.
+  const ssrFailure = previewDiagnosticsEnabled({ editable, state })
+    ? resolvePreviewDiagnostics({
+        diagnostics,
+        profileId: forgeProps.profileId,
+        siteConfig: forgeProps.initialSiteConfig,
+        apiUrl: forgeProps.apiUrl,
+      })
+    : null;
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
+      {/* First in the tree: it must render even if everything below it doesn't. */}
+      {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
       {children}
       {/* "Powered by TribeNest" — last in the page flow, so it sits below the
           tenant's own footer. Released builds only (live + published). */}

package/src/ui/shell/diagnosticsGating.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import {
+  previewDiagnosticsEnabled,
+  resolvePreviewDiagnostics,
+  previewDiagnosticsMessage,
+} from "./diagnosticsGating";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+
+describe("previewDiagnosticsEnabled", () => {
+  it("shows in the in-editor sandbox", () => {
+    expect(previewDiagnosticsEnabled({ editable: true, state: "draft" })).toBe(true);
+    // editable wins even if a shell mislabels the state.
+    expect(previewDiagnosticsEnabled({ editable: true, state: "published" })).toBe(true);
+  });
+
+  it("shows on a draft review Worker, which is not editable", () => {
+    expect(previewDiagnosticsEnabled({ editable: false, state: "draft" })).toBe(true);
+  });
+
+  it("NEVER shows on the live published site", () => {
+    expect(previewDiagnosticsEnabled({ editable: false, state: "published" })).toBe(false);
+    expect(previewDiagnosticsEnabled({ state: "published" })).toBe(false);
+    // A shell that passes neither must not leak the banner to visitors.
+    expect(previewDiagnosticsEnabled({})).toBe(false);
+  });
+});
+
+describe("resolvePreviewDiagnostics", () => {
+  const failed: ForgeSsrDiagnostics = {
+    apiUrl: "https://api.tribenest.co",
+    failures: [{ what: "content", error: "fetch failed" }],
+  };
+
+  it("passes through real diagnostics from fetchSiteBootstrap", () => {
+    expect(resolvePreviewDiagnostics({ diagnostics: failed, profileId: "p1", siteConfig: {} })).toBe(failed);
+  });
+
+  it("returns null on a healthy render", () => {
+    expect(resolvePreviewDiagnostics({ diagnostics: null, profileId: "p1", siteConfig: { currency: "USD" } })).toBeNull();
+  });
+
+  it("ignores an empty failure list", () => {
+    const clean: ForgeSsrDiagnostics = { apiUrl: "https://api.tribenest.co", failures: [] };
+    expect(resolvePreviewDiagnostics({ diagnostics: clean, profileId: "p1", siteConfig: {} })).toBeNull();
+  });
+
+  // The fallback that covers every already-deployed shell still calling
+  // fetchContentDocument/fetchSiteConfig separately — no file edit needed.
+  it("infers a failure from a null siteConfig when a profileId IS baked in", () => {
+    const d = resolvePreviewDiagnostics({ profileId: "p1", siteConfig: null, apiUrl: "https://api.tribenest.co" });
+    expect(d).toEqual({
+      apiUrl: "https://api.tribenest.co",
+      failures: [{ what: "siteConfig", error: "no response" }],
+    });
+  });
+
+  it("does NOT infer a failure when there was no profile to fetch for", () => {
+    // No profileId baked in → nothing was requested → a null config is correct,
+    // not a failure. Crying wolf here would train people to ignore the banner.
+    expect(resolvePreviewDiagnostics({ profileId: undefined, siteConfig: null })).toBeNull();
+    expect(resolvePreviewDiagnostics({ profileId: "", siteConfig: null })).toBeNull();
+  });
+});
+
+describe("previewDiagnosticsMessage", () => {
+  it("names the network as the cause when the probe also failed", () => {
+    const msg = previewDiagnosticsMessage({
+      apiUrl: "https://api.tribenest.co",
+      failures: [
+        { what: "content", error: "fetch failed" },
+        { what: "siteConfig", error: "fetch failed" },
+      ],
+      probe: { ok: false, url: "https://api.tribenest.co/healthcheck", error: "no response within 5000ms", ms: 5001 },
+    });
+    expect(msg.title).toBe("This preview can't reach the TribeNest API");
+    expect(msg.details.some((l) => l.includes("no route to the API"))).toBe(true);
+    expect(msg.details).toContain("API: https://api.tribenest.co");
+  });
+
+  it("distinguishes a reachable API from a per-route failure", () => {
+    const msg = previewDiagnosticsMessage({
+      apiUrl: "https://api.tribenest.co",
+      failures: [{ what: "content", error: "HTTP 500", status: 500 }],
+      probe: { ok: true, url: "https://api.tribenest.co/healthcheck", status: 200, ms: 42 },
+    });
+    expect(msg.title).toBe("This preview couldn't load your site data");
+    expect(msg.details.some((l) => l.includes("per-route failure"))).toBe(true);
+  });
+
+  it("always states that the defaults on screen are the symptom, not the setting", () => {
+    // This sentence is the entire point of the banner — the failure mode it was
+    // built for is a preview that looks configured-but-wrong rather than broken.
+    const msg = previewDiagnosticsMessage({ apiUrl: "", failures: [{ what: "siteConfig", error: "no response" }] });
+    expect(msg.consequence).toContain("default theme");
+    expect(msg.consequence).toContain("published site is unaffected");
+  });
+
+  it("omits the API line when the shell baked in no url", () => {
+    const msg = previewDiagnosticsMessage({ apiUrl: "", failures: [{ what: "content", error: "boom" }] });
+    expect(msg.details.some((l) => l.startsWith("API:"))).toBe(false);
+  });
+});

package/src/ui/shell/diagnosticsGating.ts

@@ -0,0 +1,90 @@
+// Pure logic for the preview's SSR-failure banner, kept React-free so it's
+// unit-testable in the node test env (no jsdom) — same split as `shellGating.ts`,
+// which is also why this is not named after the component it feeds: a
+// `previewDiagnostics.ts` next to `PreviewDiagnostics.tsx` differs only in
+// casing, which tsc rejects outright on a case-insensitive filesystem.
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+
+/**
+ * WHERE the banner is allowed to appear: any build that is NOT the released live
+ * site — the in-editor sandbox (`editable`) or a preview-<versionId> review
+ * Worker (`state === "draft"`).
+ *
+ * The inverse of `shellPwaEnabled` / `shellPoweredByEnabled`, and deliberately so:
+ * a visitor to a live site must never be shown our plumbing. On the live site the
+ * degraded render is still the right behaviour — the point of this banner is that
+ * the person who can FIX it (the creator, or us) is the one looking at it.
+ */
+export function previewDiagnosticsEnabled(opts: { editable?: boolean; state?: "draft" | "published" }): boolean {
+  return !!opts.editable || opts.state === "draft";
+}
+
+/**
+ * WHETHER there is anything to report, and what.
+ *
+ * Two sources, because the shells are versioned independently of Forge:
+ *
+ *  1. `diagnostics` — the precise answer, from `fetchSiteBootstrap`. Only shells
+ *     that have been updated to call it supply this.
+ *  2. The fallback — a deploy that HAS a `profileId` baked in but rendered with a
+ *     null `siteConfig` cannot be healthy: the fetch went out and came back with
+ *     nothing. Every already-deployed site whose `__root.tsx` still calls the old
+ *     `fetchSiteConfig` gets a (less detailed) banner from this on a Forge bump
+ *     alone, with no file edit.
+ *
+ * Returns null when there is nothing wrong.
+ */
+export function resolvePreviewDiagnostics(opts: {
+  diagnostics?: ForgeSsrDiagnostics | null;
+  profileId?: string;
+  siteConfig?: unknown;
+  apiUrl?: string;
+}): ForgeSsrDiagnostics | null {
+  if (opts.diagnostics && opts.diagnostics.failures.length > 0) return opts.diagnostics;
+  if (opts.profileId && opts.siteConfig == null) {
+    return {
+      apiUrl: opts.apiUrl ?? "",
+      failures: [{ what: "siteConfig", error: "no response" }],
+    };
+  }
+  return null;
+}
+
+export type PreviewDiagnosticsMessage = {
+  title: string;
+  /** The one sentence that resolves the confusion this banner exists for. */
+  consequence: string;
+  /** Specifics — one line per failure, plus the probe verdict. */
+  details: string[];
+};
+
+const WHAT_LABEL: Record<string, string> = {
+  content: "content document (your text, images and theme)",
+  siteConfig: "site config (currency, payment provider, tracking)",
+};
+
+/** Human copy for the banner. Pure — no React, no formatting concerns. */
+export function previewDiagnosticsMessage(d: ForgeSsrDiagnostics): PreviewDiagnosticsMessage {
+  const details = d.failures.map((f) => `Couldn't load the ${WHAT_LABEL[f.what] ?? f.what} — ${f.error}.`);
+
+  if (d.probe) {
+    details.push(
+      d.probe.ok
+        ? `The API answered ${d.probe.url} in ${d.probe.ms}ms, so this looks like a per-route failure rather than a network one.`
+        : `Couldn't reach ${d.probe.url} either — ${d.probe.error ?? `HTTP ${d.probe.status}`} after ${d.probe.ms}ms. This preview has no route to the API.`,
+    );
+  }
+  if (d.apiUrl) details.push(`API: ${d.apiUrl}`);
+
+  return {
+    title:
+      d.probe && !d.probe.ok
+        ? "This preview can't reach the TribeNest API"
+        : "This preview couldn't load your site data",
+    // The sentence that would have saved the debugging session this was built
+    // after: the defaults on screen are a symptom, not the setting.
+    consequence:
+      "You're seeing Forge's default theme (white background, purple accent) and empty content because the data never arrived — not because of how your site is configured. Your published site is unaffected.",
+    details,
+  };
+}

package/src/ui/shell/shellGating.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
+import { poweredByHref, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 
 // The PWA (SW register + install prompt) must be ON only for the live published
 // site, and OFF everywhere else (editor, preview/draft), so review Workers never
@@ -46,3 +46,42 @@ describe("shellPoweredByEnabled", () => {
     expect(shellPoweredByEnabled({ editable: false, state: "published", hideBadge: false })).toBe(true);
   });
 });
+
+// The badge is only worth carrying if we can tell WHICH site sent the visitor,
+// so the identifying params are the point of the link, not decoration.
+describe("poweredByHref", () => {
+  const parse = (href: string) => new URL(href).searchParams;
+
+  it("identifies the referring site by subdomain", () => {
+    const p = parse(poweredByHref({ subdomain: "ladygaga", profileId: "prof-1" }));
+    expect(p.get("utm_source")).toBe("powered_by");
+    expect(p.get("utm_medium")).toBe("badge");
+    expect(p.get("utm_campaign")).toBe("creator_site");
+    expect(p.get("utm_content")).toBe("ladygaga");
+  });
+
+  it("falls back to the profileId when no subdomain is baked in", () => {
+    expect(parse(poweredByHref({ profileId: "prof-1" })).get("utm_content")).toBe("prof-1");
+  });
+
+  it("distinguishes a mini-app from a website, and one app from another", () => {
+    const p = parse(poweredByHref({ subdomain: "ladygaga", appId: "app-7" }));
+    expect(p.get("utm_campaign")).toBe("creator_app");
+    expect(p.get("utm_content")).toBe("ladygaga"); // the tenant
+    expect(p.get("utm_term")).toBe("app-7"); // the deploy
+  });
+
+  it("omits utm_content rather than emitting an empty one when identity is missing", () => {
+    expect(parse(poweredByHref({})).has("utm_content")).toBe(false);
+  });
+
+  it("url-encodes an identity that needs it", () => {
+    // A subdomain can't contain these, but utm_content also carries profile ids
+    // and one day whatever replaces them — encode rather than trust the shape.
+    expect(parse(poweredByHref({ subdomain: "a b&c" })).get("utm_content")).toBe("a b&c");
+  });
+
+  it("always points at the marketing site", () => {
+    expect(poweredByHref({ subdomain: "x" }).startsWith("https://tribenest.co/?")).toBe(true);
+  });
+});

package/src/ui/shell/shellGating.ts

@@ -23,3 +23,36 @@ export function shellPoweredByEnabled(opts: {
 }): boolean {
   return !opts.hideBadge && !opts.editable && opts.state === "published";
 }
+
+/** Marketing site the badge points at. */
+const TRIBENEST_URL = "https://tribenest.co/";
+
+/**
+ * The badge href, tagged so a signup can be traced back to the exact site that
+ * referred it.
+ *
+ *   utm_source=powered_by   the badge, as against any other tribenest.co inbound
+ *   utm_medium=badge
+ *   utm_campaign            creator_site | creator_app — which surface it was
+ *   utm_content             WHICH site: the tenant subdomain, falling back to the
+ *                           profileId when a deploy has no subdomain baked in
+ *   utm_term                the appId on a mini-app, so two apps on one profile
+ *                           stay distinguishable (utm_content is the tenant, not
+ *                           the deploy)
+ *
+ * Built from the identity `ForgeProvider` was constructed with — baked at build
+ * time — never from `window.location`. That keeps it identical on the server and
+ * the client (no hydration mismatch), and correct on custom domains, where the
+ * hostname says nothing about which tenant it is.
+ */
+export function poweredByHref(opts: { subdomain?: string; profileId?: string; appId?: string }): string {
+  const params = new URLSearchParams({
+    utm_source: "powered_by",
+    utm_medium: "badge",
+    utm_campaign: opts.appId ? "creator_app" : "creator_site",
+  });
+  const site = opts.subdomain || opts.profileId;
+  if (site) params.set("utm_content", site);
+  if (opts.appId) params.set("utm_term", opts.appId);
+  return `${TRIBENEST_URL}?${params.toString()}`;
+}