@tribe-nest/forge 3.53.0 → 3.54.0

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([]);
+  });
+});

package/src/runtime/registry.ts

@@ -0,0 +1,102 @@
+import { createContext, type Context } from "react";
+
+/**
+ * The runtime a built creator site shares with the central pages bundle.
+ *
+ * A site and the hosted `/i/*` pages are two separately built bundles that have
+ * to behave as ONE app. If each carried its own React, its own router and its
+ * own copies of Forge's contexts, a fan would hold two carts, be logged in on
+ * one half of the page and anonymous on the other, and hooks would throw the
+ * moment a bundled block tried to read a provider the host had mounted.
+ *
+ * So the host publishes its runtime on a global object and the bundle reads it
+ * rather than carrying its own. First writer wins, always: the site boots
+ * first, registers, and the bundle then finds what is already there.
+ *
+ * That rule is what makes a CONTEXT shareable, which is the part worth
+ * understanding. `createContext` called twice produces two unrelated objects,
+ * and a provider mounted from one is invisible to a consumer reading the other.
+ * `createSharedContext` gives both bundles the same object instead, so the
+ * host's `<CartProvider>` is the cart the bundle's `useCart()` reads.
+ *
+ * ## The contract
+ *
+ * What lives here is a contract between a site built at one moment and a bundle
+ * published later, so it is ADDITIVE FOR EVER. A key, once published under a
+ * contract, never changes meaning and is never removed. Adding one is safe:
+ * an older bundle simply does not ask for it. Removing or repurposing one is a
+ * contract bump (`rc1` to `rc2`), which leaves old sites on the old bundle
+ * until their next build.
+ *
+ * Nothing INSIDE the bundle is covered by this. Forge's UI blocks ship in the
+ * bundle precisely so a block fix needs no contract change and no rebuild.
+ */
+
+/**
+ * Names the set of things the registry exposes. It rides in the bundle URL
+ * (`forge-pages/<contract>/latest`), so a site always asks for the bundle that
+ * matches the runtime it was built with.
+ */
+export const PAGES_RUNTIME_CONTRACT = "rc1";
+
+/**
+ * A single global, not a module-level variable. A module-level one would give
+ * each bundle its own copy, which is the exact failure this exists to prevent.
+ * The name is deliberately awkward to discourage anyone reading it directly.
+ */
+const GLOBAL_KEY = "__tribenestPagesRuntime__";
+
+type Registry = Record<string, unknown>;
+
+function registry(): Registry {
+  const scope = globalThis as unknown as Record<string, Registry | undefined>;
+  const existing = scope[GLOBAL_KEY];
+  if (existing) return existing;
+  const created: Registry = {};
+  scope[GLOBAL_KEY] = created;
+  return created;
+}
+
+/**
+ * Publish a value under `key`, or return the one already published.
+ *
+ * `create` runs only when nobody has claimed the key yet, so the host's React
+ * and the host's QueryClient are the ones everybody ends up with, whichever
+ * bundle happens to call first. Registration is therefore safe to run more than
+ * once and in any order.
+ */
+export function shareRuntimeValue<T>(key: string, create: () => T): T {
+  const reg = registry();
+  if (!(key in reg)) reg[key] = create();
+  return reg[key] as T;
+}
+
+/** Read a published value, or `undefined` when the host never published it. */
+export function readRuntimeValue<T>(key: string): T | undefined {
+  return registry()[key] as T | undefined;
+}
+
+/**
+ * A React context that is the SAME object in every bundle that asks for it.
+ *
+ * Use this instead of `createContext` for anything a hosted page consumes.
+ * `defaultValue` is only used by the bundle that gets there first; the others
+ * receive that same context and its default, which is correct, since a context
+ * with two different defaults across bundles would be two contexts again.
+ */
+export function createSharedContext<T>(key: string, defaultValue: T): Context<T> {
+  return shareRuntimeValue(`context:${key}`, () => createContext<T>(defaultValue));
+}
+
+/**
+ * Which of `required` the host never published.
+ *
+ * The bundle calls this BEFORE it renders anything. A missing key means the
+ * site was built against a runtime older than this bundle expects, and the
+ * honest response is the reload notice: rendering anyway produces a blank page
+ * or a thrown hook, and neither tells anyone what went wrong.
+ */
+export function missingRuntimeKeys(required: readonly string[]): string[] {
+  const reg = registry();
+  return required.filter((key) => !(key in reg));
+}

package/src/server/jobs.ts

@@ -246,7 +246,10 @@ export async function handleAppJobRun(
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ token }),
     });
-    valid = (await res.json())?.valid === true;
+    // Typed rather than left to inference: under Cloudflare's types `json()`
+    // resolves to `{}`, so the property read does not compile in a Worker.
+    const verified = (await res.json()) as { valid?: boolean } | null;
+    valid = verified?.valid === true;
   } catch {
     valid = false;
   }