@tribe-nest/forge 1.13.0

package/src/provider/ForgeAppProvider.tsx

@@ -0,0 +1,149 @@
+import { useState, type ReactNode } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "./ForgeProvider";
+import { SiteConfigProvider } from "./SiteConfigProvider";
+import { ForgeContentProvider } from "../content/ForgeContentProvider";
+import { useField } from "../content/useField";
+import { emptyContentDocument, type ContentDocument } from "../content/types";
+import { PublicAuthProvider } from "../contexts/PublicAuthContext";
+import { AppAuthProvider } from "../contexts/AppAuthContext";
+import { CartProvider } from "../contexts/CartContext";
+import { AudioPlayerProvider } from "../contexts/AudioPlayerContext";
+import { ForgeThemeProvider, type ForgeTheme } from "../ui/theme/ForgeThemeProvider";
+import { readableTextOn } from "../ui/theme/contrast";
+import type { SiteConfig } from "../data/queries/useWebsite";
+
+/** Forge's baseline theme — shown until the creator edits the `theme.*` content fields. */
+const BASE_THEME: ForgeTheme = {
+  colors: { text: "#0f0f10", background: "#ffffff", primary: "#6d28d9" },
+  cornerRadius: 8,
+};
+
+/**
+ * Reads the theme from `theme.*` content fields and feeds `ForgeThemeProvider`
+ * (which also publishes the `--forge-*` CSS vars). Lives inside
+ * `ForgeContentProvider` so the agent/creator can recolor the whole site via
+ * `set_content_fields`. `defaultTheme` supplies the brand defaults for fields
+ * the creator hasn't set.
+ */
+function ThemeFromContent({ defaultTheme, children }: { defaultTheme: ForgeTheme; children: ReactNode }) {
+  const primary = useField("theme.primary", { type: "color", default: defaultTheme.colors.primary, label: "Primary color" });
+  const background = useField("theme.background", {
+    type: "color",
+    default: defaultTheme.colors.background,
+    label: "Background color",
+  });
+  const text = useField("theme.text", { type: "color", default: defaultTheme.colors.text, label: "Text color" });
+  // Text/icon color placed ON the primary (buttons etc.) — defaults to an
+  // auto-contrast color against the primary.
+  const textPrimary = useField("theme.textPrimary", {
+    type: "color",
+    default: readableTextOn(primary.value),
+    label: "Text on primary",
+  });
+  // Richer, optional brand tokens — each falls back to a sensible derived value.
+  const secondary = useField("theme.secondary", { type: "color", default: primary.value, label: "Secondary color" });
+  const surface = useField("theme.surface", { type: "color", default: background.value, label: "Surface / card color" });
+  const theme: ForgeTheme = {
+    colors: {
+      primary: primary.value,
+      secondary: secondary.value,
+      background: background.value,
+      surface: surface.value,
+      text: text.value,
+      textPrimary: textPrimary.value,
+    },
+    cornerRadius: defaultTheme.cornerRadius,
+  };
+  return <ForgeThemeProvider theme={theme}>{children}</ForgeThemeProvider>;
+}
+
+export interface ForgeProviderProps {
+  /** Base URL of the TribeNest public API. */
+  apiUrl: string;
+  /** The tenant this deploy is pinned to. */
+  profileId?: string;
+  /** The app this deploy is the frontend for (mini-apps only; baked at build). */
+  appId?: string;
+  /** The tenant subdomain (also used to fetch site config). */
+  subdomain?: string;
+  rootDomain?: string;
+  publishableKey?: string;
+  /** Optional initial member token (e.g. restored from storage). */
+  initialToken?: string | null;
+  /** Editing affordances (the in-place content editor). Off for a live site. */
+  editable?: boolean;
+  /** Content locale. */
+  locale?: string;
+  /** SSR content document (from `fetchContentDocument`). Defaults to empty. */
+  initialContentDoc?: ContentDocument;
+  /** SSR site config (from `fetchSiteConfig`) — seeds `useSiteConfig` so runtime
+   * settings (currency, pixel, Stripe) are present on first paint, no flash. */
+  initialSiteConfig?: SiteConfig | null;
+  /** Brand default theme, shown until the creator edits the `theme.*` fields. */
+  defaultTheme?: ForgeTheme;
+  /** Supply your own React Query client; otherwise one is created per provider. */
+  queryClient?: QueryClient;
+  children: ReactNode;
+}
+
+/**
+ * The all-in-one root provider for a Forge-powered site. Nests, in order:
+ * `ForgeClientProvider` (tenant/client) → React Query → `SiteConfigProvider`
+ * (SSR runtime config) → `ForgeContentProvider` → auth → cart → audio player →
+ * theme-from-content. Wrap your app once and every Forge hook/block works — the
+ * whole provider tree is owned here so it can be updated centrally without
+ * touching each site.
+ *
+ *     <ForgeProvider apiUrl={API_URL} profileId={PROFILE_ID} subdomain={SUBDOMAIN}
+ *       editable={FORGE_EDIT} initialContentDoc={contentDoc} initialSiteConfig={siteConfig}>
+ *       <App />
+ *     </ForgeProvider>
+ */
+export function ForgeProvider({
+  apiUrl,
+  profileId,
+  appId,
+  subdomain,
+  rootDomain,
+  publishableKey,
+  initialToken = null,
+  editable = false,
+  locale,
+  initialContentDoc,
+  initialSiteConfig,
+  defaultTheme = BASE_THEME,
+  queryClient,
+  children,
+}: ForgeProviderProps) {
+  // One client per provider instance (per SSR request), unless the host supplies one.
+  const [client] = useState(() => queryClient ?? new QueryClient());
+
+  return (
+    <ForgeClientProvider
+      apiUrl={apiUrl}
+      rootDomain={rootDomain}
+      profileId={profileId}
+      appId={appId}
+      subdomain={subdomain}
+      publishableKey={publishableKey}
+      initialToken={initialToken}
+    >
+      <QueryClientProvider client={client}>
+        <SiteConfigProvider initialConfig={initialSiteConfig}>
+          <ForgeContentProvider initialDoc={initialContentDoc ?? emptyContentDocument(locale)} locale={locale} editable={editable}>
+            <PublicAuthProvider>
+              <AppAuthProvider>
+                <CartProvider>
+                  <AudioPlayerProvider>
+                    <ThemeFromContent defaultTheme={defaultTheme}>{children}</ThemeFromContent>
+                  </AudioPlayerProvider>
+                </CartProvider>
+              </AppAuthProvider>
+            </PublicAuthProvider>
+          </ForgeContentProvider>
+        </SiteConfigProvider>
+      </QueryClientProvider>
+    </ForgeClientProvider>
+  );
+}

package/src/provider/ForgeProvider.tsx

@@ -0,0 +1,91 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import type { AxiosInstance } from "axios";
+import { createForgeClient } from "../client/createForgeClient";
+
+export interface ForgeContextValue {
+  /** Base URL of the TribeNest public API. */
+  apiUrl: string;
+  /** Root domain (e.g. tribenest.co). Empty when not relevant. */
+  rootDomain: string;
+  /** The tenant this site is pinned to (one deploy = one profileId). */
+  profileId?: string;
+  /** The app this deploy is the frontend for (mini-apps only; baked at build). */
+  appId?: string;
+  /** The tenant subdomain, when resolved. */
+  subdomain?: string;
+  /** Per-tenant publishable key (`pk_site_…`), sent as `x-forge-key`. */
+  publishableKey?: string;
+  /** The configured Axios client, scoped to this tenant. */
+  client: AxiosInstance;
+  /** Current member bearer token, or null when anonymous. */
+  token: string | null;
+  /** Set/clear the member bearer token. */
+  setToken: (token: string | null) => void;
+}
+
+const ForgeContext = createContext<ForgeContextValue | null>(null);
+
+export interface ForgeClientProviderProps {
+  apiUrl: string;
+  rootDomain?: string;
+  profileId?: string;
+  appId?: string;
+  subdomain?: string;
+  publishableKey?: string;
+  /** Optional initial token (e.g. restored from storage on mount). */
+  initialToken?: string | null;
+  children: React.ReactNode;
+}
+
+/**
+ * Low-level tenant/client provider — supplies the `useForge()` context (Axios
+ * client, tenant ids, token). Most sites use the all-in-one `<ForgeProvider>`
+ * (which wraps this plus query/content/auth/cart/audio/site-config/theme); reach
+ * for `ForgeClientProvider` only when composing the tree yourself.
+ *
+ * The Axios client is created once per `apiUrl` and reads the token from a ref,
+ * so changing the token never tears down/recreates the client.
+ */
+export const ForgeClientProvider = ({
+  apiUrl,
+  rootDomain = "",
+  profileId,
+  appId,
+  subdomain,
+  publishableKey,
+  initialToken = null,
+  children,
+}: ForgeClientProviderProps) => {
+  const [token, setTokenState] = useState<string | null>(initialToken);
+
+  // The client reads the token from this ref per-request. `setToken` updates the
+  // ref *synchronously* (so a request fired immediately after setToken uses the
+  // new token) and the state (to re-render consumers of `token`).
+  const tokenRef = useRef<string | null>(initialToken);
+
+  const setToken = useCallback((next: string | null) => {
+    tokenRef.current = next;
+    setTokenState(next);
+  }, []);
+
+  const client = useMemo(
+    () => createForgeClient({ baseURL: apiUrl, publishableKey, getToken: () => tokenRef.current }),
+    [apiUrl, publishableKey],
+  );
+
+  const value = useMemo<ForgeContextValue>(
+    () => ({ apiUrl, rootDomain, profileId, appId, subdomain, publishableKey, client, token, setToken }),
+    [apiUrl, rootDomain, profileId, appId, subdomain, publishableKey, client, token, setToken],
+  );
+
+  return <ForgeContext.Provider value={value}>{children}</ForgeContext.Provider>;
+};
+
+/** Access the Forge context. Throws if used outside a `<ForgeProvider>`. */
+export const useForge = (): ForgeContextValue => {
+  const ctx = useContext(ForgeContext);
+  if (!ctx) {
+    throw new Error("useForge must be used within a <ForgeProvider>");
+  }
+  return ctx;
+};

package/src/provider/SiteConfigProvider.tsx

@@ -0,0 +1,27 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { SiteConfig } from "../data/queries/useWebsite";
+
+/**
+ * Holds an SSR-fetched site config so `useSiteConfig()` can seed React Query
+ * with it (as `initialData`) and have the value on the very first render — no
+ * client-fetch flash, no hydration mismatch. `undefined` when the site config
+ * wasn't fetched on the server, in which case `useSiteConfig` just fetches on
+ * the client as before.
+ */
+const SiteConfigContext = createContext<SiteConfig | undefined>(undefined);
+
+/** Seed the SSR-fetched site config (see `fetchSiteConfig` in `@tribe-nest/forge/server`). */
+export function SiteConfigProvider({
+  initialConfig,
+  children,
+}: {
+  initialConfig?: SiteConfig | null;
+  children: ReactNode;
+}) {
+  return <SiteConfigContext.Provider value={initialConfig ?? undefined}>{children}</SiteConfigContext.Provider>;
+}
+
+/** The SSR-seeded site config, if a `SiteConfigProvider` supplied one. */
+export function useInitialSiteConfig(): SiteConfig | undefined {
+  return useContext(SiteConfigContext);
+}

package/src/server/_tests/buildPwaHead.spec.ts

@@ -0,0 +1,182 @@
+// Unit tests for buildPwaHead() — the React-free Forge server builder that emits
+// the manifest <link>, apple-touch-icon, theme-color, and iOS standalone metas
+// for a code site's route head(). Pure function, no DB, no network.
+//
+// Coverage:
+//  - happy path: full link/meta set with deep assertions
+//  - apple-touch-icon derive (icon192 preferred, icon512 fallback, absent → omit)
+//  - theme-color derivation + default fallback (bare + localized + no doc)
+//  - manifestHref override / default
+//  - apple-mobile-web-app-title fallback chain (shortName → name → siteName → "App")
+//  - null/undefined siteConfig degradation (never throws)
+//  - the known client bug this fixes: apple-touch-icon is always emitted when an icon exists
+//
+// Source: packages/forge/src/server/pwa.ts. Spec: docs/pwa-custom-code-initiative.md.
+
+import { describe, it, expect } from "vitest";
+import { buildPwaHead } from "../pwa";
+import type { SiteConfig, PwaConfig } from "../../data/queries/useWebsite";
+import type { ContentDocument } from "../../content/types";
+import type { HeadMeta as HeadMetaT } from "../pwa";
+
+const DEFAULT_PRIMARY = "#6d28d9";
+
+function fullPwa(overrides: Partial<PwaConfig> = {}): PwaConfig {
+  return {
+    name: "Nova Sound",
+    shortName: "Nova",
+    description: "The Nova Sound fan app",
+    icon96: "https://cdn.tribenest.co/p/nova/icon-96.png",
+    icon192: "https://cdn.tribenest.co/p/nova/icon-192.png",
+    icon512: "https://cdn.tribenest.co/p/nova/icon-512.png",
+    ...overrides,
+  };
+}
+
+function siteConfig(overrides: Partial<SiteConfig> = {}): SiteConfig {
+  return {
+    currency: "USD",
+    metaPixelId: null,
+    stripeAccountId: null,
+    paystackAccountId: null,
+    paymentProviderName: null,
+    paymentProviderPublicKey: null,
+    stripePublishableKey: null,
+    siteName: "Nova Sound",
+    pwa: fullPwa(),
+    ...overrides,
+  };
+}
+
+function themedDoc(primary?: string): ContentDocument {
+  const fields: ContentDocument["fields"] = {};
+  if (primary !== undefined) fields["theme.primary"] = { type: "color", localized: false, value: primary };
+  return { version: 1, defaultLocale: "en", locales: ["en"], fields };
+}
+
+function metaFor(metas: HeadMetaT[], name: string): HeadMetaT | undefined {
+  return metas.find((m) => m.name === name);
+}
+
+describe("buildPwaHead — happy path (full pwaConfig)", () => {
+  const head = buildPwaHead({ siteConfig: siteConfig(), contentDoc: themedDoc("#0a0a0a") });
+
+  it("emits the manifest link + apple-touch-icon with deep assertions", () => {
+    expect(head.links).toEqual([
+      { rel: "manifest", href: "/manifest.webmanifest" },
+      { rel: "apple-touch-icon", href: "https://cdn.tribenest.co/p/nova/icon-192.png", sizes: "192x192" },
+    ]);
+  });
+
+  it("emits theme-color from content theme.primary + the iOS standalone metas", () => {
+    expect(head.metas).toEqual([
+      { name: "theme-color", content: "#0a0a0a" },
+      { name: "mobile-web-app-capable", content: "yes" },
+      { name: "apple-mobile-web-app-capable", content: "yes" },
+      { name: "apple-mobile-web-app-status-bar-style", content: "default" },
+      { name: "apple-mobile-web-app-title", content: "Nova" },
+    ]);
+  });
+});
+
+describe("buildPwaHead — apple-touch-icon derivation", () => {
+  it("prefers icon192", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig() });
+    const touch = head.links.find((l) => l.rel === "apple-touch-icon");
+    expect(touch?.href).toBe("https://cdn.tribenest.co/p/nova/icon-192.png");
+  });
+
+  it("falls back to icon512 when icon192 is empty", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: fullPwa({ icon192: "" as unknown as string }) }) });
+    const touch = head.links.find((l) => l.rel === "apple-touch-icon");
+    expect(touch?.href).toBe("https://cdn.tribenest.co/p/nova/icon-512.png");
+  });
+
+  it("omits apple-touch-icon entirely when the profile has no pwaConfig", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null }) });
+    expect(head.links.some((l) => l.rel === "apple-touch-icon")).toBe(false);
+    // the manifest link is always present (installability nudge)
+    expect(head.links).toContainEqual({ rel: "manifest", href: "/manifest.webmanifest" });
+  });
+
+  it("omits apple-touch-icon when both icons are empty", () => {
+    const head = buildPwaHead({
+      siteConfig: siteConfig({ pwa: fullPwa({ icon192: "" as unknown as string, icon512: "" as unknown as string }) }),
+    });
+    expect(head.links.some((l) => l.rel === "apple-touch-icon")).toBe(false);
+  });
+});
+
+describe("buildPwaHead — theme-color derivation + fallback", () => {
+  it("falls back to the Forge default when the content doc has no theme.primary", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig(), contentDoc: themedDoc() });
+    expect(metaFor(head.metas, "theme-color")?.content).toBe(DEFAULT_PRIMARY);
+  });
+
+  it("falls back to default when contentDoc is null / omitted", () => {
+    expect(metaFor(buildPwaHead({ siteConfig: siteConfig(), contentDoc: null }).metas, "theme-color")?.content).toBe(
+      DEFAULT_PRIMARY,
+    );
+    expect(metaFor(buildPwaHead({ siteConfig: siteConfig() }).metas, "theme-color")?.content).toBe(DEFAULT_PRIMARY);
+  });
+
+  it("resolves a localized theme.primary via defaultLocale", () => {
+    const doc: ContentDocument = {
+      version: 1,
+      defaultLocale: "de",
+      locales: ["de", "en"],
+      fields: { "theme.primary": { type: "color", localized: true, value: { en: "#111", de: "#999" } } },
+    };
+    expect(metaFor(buildPwaHead({ siteConfig: siteConfig(), contentDoc: doc }).metas, "theme-color")?.content).toBe(
+      "#999",
+    );
+  });
+});
+
+describe("buildPwaHead — manifestHref override", () => {
+  it("defaults the manifest link href to /manifest.webmanifest", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig() });
+    expect(head.links[0]).toEqual({ rel: "manifest", href: "/manifest.webmanifest" });
+  });
+
+  it("honors an explicit manifestHref", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig(), manifestHref: "/app.webmanifest" });
+    expect(head.links[0]).toEqual({ rel: "manifest", href: "/app.webmanifest" });
+  });
+});
+
+describe("buildPwaHead — apple-mobile-web-app-title fallback chain", () => {
+  it("uses shortName first", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: fullPwa({ shortName: "Nv" }) }) });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Nv");
+  });
+
+  it("falls back to pwa.name when shortName is empty", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: fullPwa({ shortName: "" }) }) });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Nova Sound");
+  });
+
+  it("falls back to siteName when there is no pwaConfig", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Fallback Site" }) });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Fallback Site");
+  });
+
+  it("falls back to 'App' when nothing is set", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: null }) });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("App");
+  });
+});
+
+describe("buildPwaHead — degradation (never throws)", () => {
+  it("returns manifest link + default metas when siteConfig is null", () => {
+    const head = buildPwaHead({ siteConfig: null });
+    expect(head.links).toEqual([{ rel: "manifest", href: "/manifest.webmanifest" }]);
+    expect(metaFor(head.metas, "theme-color")?.content).toBe(DEFAULT_PRIMARY);
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("App");
+  });
+
+  it("returns identical output for identical input (determinism)", () => {
+    const opts = { siteConfig: siteConfig(), contentDoc: themedDoc("#424242") };
+    expect(buildPwaHead(opts)).toEqual(buildPwaHead(opts));
+  });
+});