@tribe-nest/forge 3.52.0 → 3.54.0

package/src/runtime/RemotePage.tsx

@@ -0,0 +1,110 @@
+import { useEffect, useState, type ComponentType } from "react";
+import { missingRuntimeKeys } from "./registry";
+import { REQUIRED_RUNTIME_KEYS } from "./hostRuntime";
+import type { RemotePageResult } from "./pagesClient";
+
+/**
+ * A hosted `/i/*` page, inside the creator's own shell.
+ *
+ * Two halves arrive from different places. The markup was rendered by the
+ * central pages Worker and comes down with the document, so a crawler and a
+ * link preview see a complete page. The interactive version comes from the
+ * central browser bundle, which loads after paint and takes over.
+ *
+ * The takeover is a REPLACEMENT, not a hydration. The bundle hands back an
+ * ordinary component and it renders inside this tree, under the host's
+ * providers, so there is one React root and one of everything else. Hydrating
+ * across two independently built bundles would mean matching markup exactly
+ * between two Reacts, which is the brittleness this design exists to avoid.
+ */
+
+type HostedPageProps = { params: Record<string, string>; search: URLSearchParams; data: unknown };
+
+type PagesBundle = {
+  getPage(path: string): ComponentType<HostedPageProps> | null;
+};
+
+/** Bundles already fetched, by URL, so a second page view does not refetch. */
+const loaded = new Map<string, Promise<PagesBundle>>();
+
+function loadBundle(url: string): Promise<PagesBundle> {
+  const existing = loaded.get(url);
+  if (existing) return existing;
+  // The URL is only known at runtime, from the render response, so the bundler
+  // must not try to resolve it.
+  const pending = import(/* @vite-ignore */ url) as Promise<PagesBundle>;
+  loaded.set(url, pending);
+  return pending;
+}
+
+function ensureStylesheet(href: string): void {
+  if (!href || typeof document === "undefined") return;
+  if (document.querySelector(`link[data-forge-pages="${CSS.escape(href)}"]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = href;
+  link.dataset.forgePages = href;
+  document.head.appendChild(link);
+}
+
+type Status = "server" | "live" | "failed";
+
+export function RemotePage({ result, path, search = "" }: { result: RemotePageResult; path: string; search?: string }) {
+  const [Page, setPage] = useState<ComponentType<HostedPageProps> | null>(null);
+  const [status, setStatus] = useState<Status>("server");
+
+  useEffect(() => {
+    if (!result.bundle.js) {
+      // No server render happened either, so there is nothing on screen and
+      // nothing to load. Say so rather than showing an empty page for ever.
+      setStatus(result.html ? "server" : "failed");
+      return;
+    }
+    // Check the contract BEFORE importing. A site built against an older
+    // runtime cannot satisfy this bundle, and finding that out halfway through
+    // a render produces a thrown hook rather than a message anyone can act on.
+    const missing = missingRuntimeKeys(REQUIRED_RUNTIME_KEYS);
+    if (missing.length > 0) {
+      console.error(`[forge-pages] this site does not publish: ${missing.join(", ")}`);
+      setStatus("failed");
+      return;
+    }
+    let cancelled = false;
+    ensureStylesheet(result.bundle.css);
+    loadBundle(result.bundle.js)
+      .then((bundle) => {
+        if (cancelled) return;
+        const component = bundle.getPage(path);
+        if (!component) {
+          setStatus("failed");
+          return;
+        }
+        setPage(() => component);
+        setStatus("live");
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        console.error("[forge-pages] bundle failed to load", err);
+        setStatus("failed");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [result.bundle.js, result.bundle.css, result.html, path]);
+
+  if (Page && status === "live") return <Page params={{}} search={new URLSearchParams(search)} data={result.data} />;
+
+  return (
+    <>
+      <div dangerouslySetInnerHTML={{ __html: result.html }} />
+      {status === "failed" && (
+        <div className="fg:mx-auto fg:my-6 fg:max-w-md fg:rounded-lg fg:border fg:p-4 fg:text-center fg:text-sm">
+          <p>This page could not finish loading.</p>
+          <button type="button" className="fg:mt-2 fg:underline" onClick={() => window.location.reload()}>
+            Reload the page
+          </button>
+        </div>
+      )}
+    </>
+  );
+}

package/src/runtime/hostRuntime.ts

@@ -0,0 +1,84 @@
+import * as React from "react";
+import * as ReactJsxRuntime from "react/jsx-runtime";
+import * as ReactDom from "react-dom";
+import * as ReactQuery from "@tanstack/react-query";
+import { shareRuntimeValue, readRuntimeValue } from "./registry";
+
+/**
+ * What a built site publishes for the hosted pages bundle to use.
+ *
+ * Only libraries that OWN A CONTEXT of their own need to be here. Forge's
+ * contexts do not: they go through `createSharedContext`, so even two copies of
+ * Forge resolve to the same context object and the host's cart is the cart the
+ * bundle reads. React, the router and React Query have contexts we did not
+ * create and cannot route through the registry, so the bundle must use the
+ * host's module rather than its own.
+ *
+ * React is the strict one. Two Reacts in one tree means hooks throw, because
+ * the second copy has no current dispatcher during the first copy's render.
+ */
+export const RUNTIME_KEYS = {
+  react: "react",
+  reactDom: "react-dom",
+  reactJsxRuntime: "react/jsx-runtime",
+  reactQuery: "@tanstack/react-query",
+  router: "@tanstack/react-router",
+  queryClient: "queryClient",
+} as const;
+
+/** Every key a hosted page needs before it can render. */
+export const REQUIRED_RUNTIME_KEYS: readonly string[] = [
+  RUNTIME_KEYS.react,
+  RUNTIME_KEYS.reactDom,
+  RUNTIME_KEYS.reactJsxRuntime,
+  RUNTIME_KEYS.reactQuery,
+  RUNTIME_KEYS.router,
+  RUNTIME_KEYS.queryClient,
+];
+
+/**
+ * Publish what Forge itself can reach. Called at module scope by
+ * `TribeNestApp`, so it has run long before any page asks for a bundle.
+ *
+ * The router is NOT here. Forge does not depend on `@tanstack/react-router`,
+ * and adding the dependency just to republish the host's copy would give Forge
+ * a second one. The site registers it instead, from the catch-all route that
+ * already imports it (see `registerRouterRuntime`).
+ */
+export function registerHostRuntime(): void {
+  shareRuntimeValue(RUNTIME_KEYS.react, () => React);
+  shareRuntimeValue(RUNTIME_KEYS.reactDom, () => ReactDom);
+  shareRuntimeValue(RUNTIME_KEYS.reactJsxRuntime, () => ReactJsxRuntime);
+  shareRuntimeValue(RUNTIME_KEYS.reactQuery, () => ReactQuery);
+}
+
+/**
+ * Publish the site's router module. Called by the `/i/$` catch-all, which is a
+ * chassis file, so this stays platform-owned even though it lives in the site.
+ */
+export function registerRouterRuntime(routerModule: unknown): void {
+  shareRuntimeValue(RUNTIME_KEYS.router, () => routerModule);
+}
+
+/**
+ * Publish the query client the provider tree actually mounted.
+ *
+ * Unlike the modules above this is per render, not per module: `ForgeProvider`
+ * makes one client per instance (per SSR request). The bundle needs THAT one,
+ * or a hosted page would fetch into a cache nothing else reads and a fan would
+ * watch the same data load twice.
+ */
+export function registerQueryClient(client: unknown): void {
+  // Browser only, and this guard is load-bearing. The registry is a global, and
+  // on a Worker one global serves every request in the isolate. Publishing a
+  // per-request client there would hand request 2 the client request 1 created,
+  // which is a cross-request cache and a data leak between two fans. Server
+  // rendering does not need it: the pages Worker mounts its own providers.
+  if (typeof window === "undefined") return;
+  shareRuntimeValue(RUNTIME_KEYS.queryClient, () => client);
+}
+
+/** The host's query client, for the bundle. */
+export function hostQueryClient<T>(): T | undefined {
+  return readRuntimeValue<T>(RUNTIME_KEYS.queryClient);
+}

package/src/runtime/pages.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { INTERNAL_PAGES, internalLink, internalPath, isInternalPage } from "./pages";
+
+describe("internal page links", () => {
+  it("builds a path for a page with no parameters", () => {
+    expect(internalPath("checkout")).toBe("/i/checkout");
+  });
+
+  it("fills parameters in order", () => {
+    expect(internalPath("films/$slug/watch/$episodeId", { slug: "dune", episodeId: "e2" })).toBe(
+      "/i/films/dune/watch/e2",
+    );
+  });
+
+  it("returns a router target that spreads into a Link", () => {
+    expect(internalLink("store/$slug", { slug: "tee" })).toEqual({ to: "/i/$", params: { _splat: "store/tee" } });
+  });
+
+  it("encodes a value so it cannot become two segments", () => {
+    // A slug carrying a slash would otherwise silently address a different page.
+    expect(internalPath("store/$slug", { slug: "a/b" })).toBe("/i/store/a%2Fb");
+  });
+
+  it("refuses to build a half-formed path", () => {
+    // Throwing beats emitting "/i/store/undefined", which returns a 404 page to
+    // the fan and looks like a missing product rather than a missing argument.
+    expect(() => internalPath("store/$slug", { slug: "" } as { slug: string })).toThrow(/missing the "slug" parameter/);
+  });
+
+  it("recognises its own pages and nothing else", () => {
+    expect(isInternalPage("store/tee")).toBe(true);
+    expect(isInternalPage("account")).toBe(true);
+    expect(isInternalPage("store")).toBe(true);
+    expect(isInternalPage("store/tee/extra")).toBe(false);
+    expect(isInternalPage("not-a-page")).toBe(false);
+  });
+
+  it("carries every page exactly once", () => {
+    expect(new Set(INTERNAL_PAGES).size).toBe(INTERNAL_PAGES.length);
+  });
+});

package/src/runtime/pages.ts

@@ -0,0 +1,183 @@
+/**
+ * Every built-in page a site can link to, and the helpers for linking to one.
+ *
+ * These pages no longer live in the site. They are published once and rendered
+ * through the catch-all route `/i/$`, so a literal `to="/i/store/abc"` no
+ * longer type-checks against anything: there is no `/i/store/$slug` route file
+ * for TanStack to know about. That is the reason this helper exists, and it is
+ * why the build guide forbids writing an `/i/` path by hand.
+ *
+ * The page list is the CONTRACT between a site and the hosted pages, so it only
+ * ever grows. Removing a page breaks links on sites already published, so a
+ * retired page keeps its entry and redirects.
+ *
+ *     <Link {...internalLink("store/$slug", { slug: product.slug })}>Buy</Link>
+ *     navigate(internalLink("checkout"))
+ *     const href = internalPath("events/$slug", { slug });
+ *
+ * A wrong page name, a missing parameter or one that does not exist on that
+ * page all fail type-check.
+ */
+
+/** The catch-all that renders every hosted page. */
+export const INTERNAL_ROUTE = "/i/$" as const;
+
+/** Every hosted page, by its path pattern. Generated from the route table. */
+export const INTERNAL_PAGES = [
+  "account",
+  "blog",
+  "blog-category/$slug",
+  "blog/$slug",
+  "chat",
+  "checkout",
+  "checkout/finalise",
+  "checkout/resume",
+  "coaching",
+  "coaching/$slug",
+  "coaching/$slug/finalise",
+  "cohorts/$cohortId",
+  "cohorts/$cohortId/finalise",
+  "community",
+  "community/leaderboard",
+  "community/notifications",
+  "community/posts/$postId",
+  "community/spaces/$spaceId",
+  "confirm-subscription",
+  "course-access/$accessId",
+  "courses",
+  "courses/$slug",
+  "courses/$slug/finalise",
+  "courses/claim",
+  "documents/$token",
+  "donation",
+  "events",
+  "events/$slug",
+  "events/$slug/finalise",
+  "films",
+  "films/$slug",
+  "films/$slug/watch/$episodeId",
+  "films/library",
+  "forgot-password",
+  "forms/$formId",
+  "invoice/$invoiceId",
+  "invoice/$invoiceId/finalise",
+  "lead/$leadMagnetId",
+  "live",
+  "live/$broadcastId",
+  "login",
+  "members",
+  "members/calendar",
+  "members/chat",
+  "members/collections",
+  "members/collections/$slug",
+  "members/spaces",
+  "members/spaces/$slug",
+  "members/spaces/leaderboard",
+  "members/spaces/notifications",
+  "members/spaces/profile/$accountId",
+  "members/spaces/thread/$postId",
+  "membership",
+  "membership/checkout",
+  "payment-link/$paymentLinkId",
+  "payment-link/$paymentLinkId/finalise",
+  "podcasts",
+  "podcasts/$showSlug",
+  "podcasts/$showSlug/$episodeSlug",
+  "replay",
+  "reset-password",
+  "reviews/$token",
+  "series/$slug",
+  "signup",
+  "store",
+  "store/$slug",
+  "tickets/claim",
+  "video-calls/$callId",
+  "work",
+  "work/accept-invite",
+  "work/projects/$projectId",
+  "work/projects/$projectId/tasks/$taskId",
+  "work/time-report/$token",
+] as const;
+
+export type InternalPage = (typeof INTERNAL_PAGES)[number];
+
+/**
+ * The `$name` segments in a pattern, as a union of their names.
+ *
+ * `"films/$slug/watch/$episodeId"` gives `"slug" | "episodeId"`, so the params
+ * object is checked against the page rather than being a loose record.
+ */
+type PathParamNames<S extends string> = S extends `${string}$${infer Rest}`
+  ? Rest extends `${infer Name}/${infer Tail}`
+    ? Name | PathParamNames<Tail>
+    : Rest
+  : never;
+
+type ParamsFor<P extends InternalPage> = Record<PathParamNames<P>, string>;
+
+/**
+ * The pages that take no parameters.
+ *
+ * Useful when a list of pages is built at runtime (a nav menu, say): with the
+ * whole union, TypeScript cannot prove no parameters are needed and demands the
+ * second argument for every entry. Narrowing to these makes `internalLink(page)`
+ * type-check with one argument, and adding a parameterised page to such a list
+ * then fails at the list rather than at the call.
+ */
+export type StaticInternalPage = {
+  [P in InternalPage]: [PathParamNames<P>] extends [never] ? P : never;
+}[InternalPage];
+
+/** Pages with no `$` take no second argument; pages with one require it. */
+type ParamsArg<P extends InternalPage> = [PathParamNames<P>] extends [never]
+  ? [params?: undefined]
+  : [params: ParamsFor<P>];
+
+function fill(page: string, params?: Record<string, string>): string {
+  return page
+    .split("/")
+    .map((segment) => {
+      if (!segment.startsWith("$")) return segment;
+      const value = params?.[segment.slice(1)];
+      if (value === undefined || value === "") {
+        throw new Error(`internalPath("${page}") is missing the "${segment.slice(1)}" parameter`);
+      }
+      // The value is one path segment, so it is encoded as one. A slug with a
+      // slash in it would otherwise silently become two segments and match a
+      // different page, or no page at all.
+      return encodeURIComponent(value);
+    })
+    .join("/");
+}
+
+/**
+ * The plain URL for a hosted page. Use it for `href`, redirects, emails and
+ * anywhere server-side that needs a string rather than a router target.
+ */
+export function internalPath<P extends InternalPage>(page: P, ...args: ParamsArg<P>): string {
+  return `/i/${fill(page, args[0] as Record<string, string> | undefined)}`;
+}
+
+/**
+ * The router target for a hosted page, ready to spread into `<Link>` or pass to
+ * `navigate()`.
+ *
+ * It resolves to the catch-all with the rest of the path as the splat, which is
+ * what makes it type-check with no casts: `/i/$` is a real route in the site.
+ */
+export function internalLink<P extends InternalPage>(
+  page: P,
+  ...args: ParamsArg<P>
+): { to: typeof INTERNAL_ROUTE; params: { _splat: string } } {
+  return { to: INTERNAL_ROUTE, params: { _splat: fill(page, args[0] as Record<string, string> | undefined) } };
+}
+
+/** Is this path one of ours? Used by the catch-all to 404 an unknown one. */
+export function isInternalPage(splat: string): boolean {
+  const segments = splat.split("/").filter(Boolean);
+  return INTERNAL_PAGES.some((page) => {
+    const parts = page.split("/");
+    if (parts.length !== segments.length) return false;
+    return parts.every((part, i) => part.startsWith("$") || part === segments[i]);
+  });
+}

package/src/runtime/pagesClient.ts

@@ -0,0 +1,127 @@
+import { PAGES_RUNTIME_CONTRACT } from "./registry";
+
+/**
+ * Talking to the central pages Worker.
+ *
+ * A site's catch-all route calls `fetchRemotePage` in its loader and renders
+ * `<RemotePage>` with the result. Everything else about hosted pages is an
+ * implementation detail of the bundle.
+ */
+
+export type RemotePageBundle = {
+  /** Absolute URL of the browser bundle that rendered this HTML. */
+  js: string;
+  /** Its stylesheet. Forge utilities are `fg:` prefixed and ship with it. */
+  css: string;
+};
+
+export type RemotePageResult = {
+  /** Server-rendered markup for the page body. */
+  html: string;
+  /** Head for TanStack's `head()`, in the shape `buildHeadMeta` already returns. */
+  head: {
+    meta?: Array<Record<string, string>>;
+    links?: Array<Record<string, string>>;
+    scripts?: Array<Record<string, string>>;
+  };
+  status: number;
+  /** Full-bleed pages opt out of the `/i` layout's reading column. */
+  fullWidth: boolean;
+  /** Set when the page wants the visitor somewhere else. */
+  redirect?: string;
+  /**
+   * Whatever the page's server loader returned.
+   *
+   * It rides back with the markup so the browser bundle can render the live
+   * page from the data that produced the HTML, rather than fetching it a second
+   * time and making the fan watch the same product load twice.
+   */
+  data: unknown;
+  /**
+   * The bundle that produced this HTML. It comes back with the render rather
+   * than being baked into the site, so the browser always runs the same version
+   * that rendered the markup it is replacing. A build-time URL would drift the
+   * moment a new bundle was published.
+   */
+  bundle: RemotePageBundle;
+};
+
+export type FetchRemotePageInput = {
+  /** The page path below `/i/`, e.g. `store/tee`. */
+  path: string;
+  /** Query string as it arrived, without the `?`. Pages parse their own. */
+  search?: string;
+  profileId: string;
+  websiteId?: string;
+  websiteVersionId?: string;
+  state: "draft" | "published";
+  /**
+   * How to reach the pages Worker. Three ways in, one Worker behind them:
+   *
+   *  - `service`: the `PAGES` binding a published site is deployed with. The
+   *    Worker has no public route, so this is the only path in production.
+   *  - `endpoint`: an absolute URL, for a laptop and the preview sandbox, which
+   *    have no bindings.
+   *  - also `endpoint`: a same-origin path, used by the BROWSER on a client-side
+   *    navigation. The site proxies it to the binding, because a browser cannot
+   *    reach a Worker that has no public route, and a page navigated to rather
+   *    than landed on still needs its title and its meta tags.
+   *
+   * There is no fourth path and no local-only shortcut, so the seam is
+   * exercised on every page view in every environment.
+   */
+  transport: { service: { fetch: typeof fetch } } | { endpoint: string };
+  signal?: AbortSignal;
+};
+
+/** The placeholder a site renders when the pages Worker cannot be reached. */
+export const REMOTE_PAGE_UNAVAILABLE: RemotePageResult = {
+  html: "",
+  head: {},
+  data: null,
+  status: 200,
+  fullWidth: false,
+  bundle: { js: "", css: "" },
+};
+
+/**
+ * Ask the pages Worker to render one page.
+ *
+ * Never throws. A page that cannot be server-rendered still works: the browser
+ * bundle renders it in full, and the cost is that this one request served no
+ * markup to a crawler. Throwing instead would turn a rendering outage into a
+ * broken site.
+ */
+export async function fetchRemotePage(input: FetchRemotePageInput): Promise<RemotePageResult> {
+  const body = JSON.stringify({
+    contract: PAGES_RUNTIME_CONTRACT,
+    path: input.path,
+    search: input.search ?? "",
+    profileId: input.profileId,
+    websiteId: input.websiteId,
+    websiteVersionId: input.websiteVersionId,
+    state: input.state,
+  });
+  const request = new Request("https://pages.internal/render", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body,
+    signal: input.signal,
+  });
+  try {
+    const response =
+      "service" in input.transport
+        ? await input.transport.service.fetch(request)
+        : await fetch(input.transport.endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body,
+            signal: input.signal,
+          });
+    if (response.status === 404) return { ...REMOTE_PAGE_UNAVAILABLE, status: 404 };
+    if (!response.ok) return REMOTE_PAGE_UNAVAILABLE;
+    return (await response.json()) as RemotePageResult;
+  } catch {
+    return REMOTE_PAGE_UNAVAILABLE;
+  }
+}

package/src/runtime/registry.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { createSharedContext, missingRuntimeKeys, readRuntimeValue, shareRuntimeValue } from "./registry";
+
+/**
+ * The registry's whole job is that a second caller gets the FIRST caller's
+ * object. In production the two callers are two separately built bundles (the
+ * creator's site and the central pages bundle); here they are two calls, which
+ * exercises the same global and the same first-writer-wins rule.
+ */
+describe("pages runtime registry", () => {
+  it("hands the second caller the first caller's context", () => {
+    const first = createSharedContext<string | null>("spec:greeting", null);
+    const second = createSharedContext<string | null>("spec:greeting", "ignored");
+    // Identity, not equality. Two contexts that merely look alike are exactly
+    // the bug this prevents: a provider mounted from one is invisible to a
+    // consumer reading the other.
+    expect(second).toBe(first);
+  });
+
+  it("keeps the value the first caller published", () => {
+    shareRuntimeValue("spec:client", () => ({ id: "host" }));
+    const value = shareRuntimeValue("spec:client", () => ({ id: "bundle" }));
+    expect(value).toEqual({ id: "host" });
+    expect(readRuntimeValue("spec:client")).toEqual({ id: "host" });
+  });
+
+  it("never runs the second factory at all", () => {
+    let calls = 0;
+    shareRuntimeValue("spec:once", () => ++calls);
+    shareRuntimeValue("spec:once", () => ++calls);
+    expect(calls).toBe(1);
+  });
+
+  it("reports nothing for a key that was never published", () => {
+    expect(readRuntimeValue("spec:absent")).toBeUndefined();
+  });
+
+  it("names the keys a bundle needs that the host never published", () => {
+    shareRuntimeValue("spec:present", () => true);
+    // The bundle checks this BEFORE rendering: a site built against an older
+    // runtime must produce a named missing key, not a blank page.
+    expect(missingRuntimeKeys(["spec:present", "spec:gone", "spec:alsoGone"])).toEqual(["spec:gone", "spec:alsoGone"]);
+    expect(missingRuntimeKeys(["spec:present"])).toEqual([]);
+  });
+});