@tribe-nest/forge 3.60.0 → 3.63.0

package/src/seo/resolve.ts

@@ -0,0 +1,211 @@
+import type { SeoHeadContext, SeoPageOverride, SeoPageType, SeoRecord } from "./types";
+
+// Pure resolution: one place decides what a page's SEO is, so the server render,
+// the hydrated page and an in-site navigation all compute the same tags from
+// the same serialized record.
+//
+// The order, field by field:
+//   1. the creator's approved override for this exact pathname,
+//   2. then the override for the route pattern ("/team/$slug"),
+//   3. then what the code passed in,
+//   4. then the page type's template,
+//   5. then the site defaults.
+
+export const DEFAULT_TITLE_TEMPLATE = "{title} | {site}";
+
+/** "/about/" and "/about" are one page. The root stays "/". */
+export function normalizePathname(pathname: string | undefined | null): string {
+  if (!pathname) return "/";
+  const bare = pathname.split(/[?#]/)[0] || "/";
+  const withSlash = bare.startsWith("/") ? bare : `/${bare}`;
+  return withSlash.length > 1 ? withSlash.replace(/\/+$/, "") || "/" : withSlash;
+}
+
+/** Hosted pages render centrally and emit their own canonical. */
+export function isHostedPath(pathname: string): boolean {
+  const p = normalizePathname(pathname);
+  return p === "/i" || p.startsWith("/i/");
+}
+
+/**
+ * The record a site's root loader returned, read from the root match.
+ *
+ * `undefined` and `null` both mean "no record": an old backend, a failed fetch,
+ * or a site whose root loader predates the field. Every caller degrades to the
+ * code's own values in that case.
+ */
+export function seoRecordFromContext(ctx: SeoHeadContext | undefined | null): SeoRecord | null {
+  const root = ctx?.matches?.[0]?.loaderData as { seo?: SeoRecord | null } | null | undefined;
+  const seo = root?.seo;
+  return seo && typeof seo === "object" && typeof seo.siteName === "string" ? seo : null;
+}
+
+/** The leaf pathname: the last match is the page being rendered. */
+export function pathnameFromContext(ctx: SeoHeadContext | undefined | null): string {
+  const matches = ctx?.matches ?? [];
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const pathname = matches[i]?.pathname;
+    if (pathname) return normalizePathname(pathname);
+  }
+  return normalizePathname(ctx?.match?.pathname);
+}
+
+/** The route pattern of the match whose head() is running ("/team/$slug"). */
+export function routePatternFromContext(ctx: SeoHeadContext | undefined | null): string | undefined {
+  const match = ctx?.match;
+  const pattern = match?.fullPath ?? match?.routeId;
+  return pattern ? normalizePathname(pattern) : undefined;
+}
+
+/** The route pattern of the leaf match, for the root, which renders above it. */
+export function leafRoutePatternFromContext(ctx: SeoHeadContext | undefined | null): string | undefined {
+  const matches = ctx?.matches ?? [];
+  const leaf = matches[matches.length - 1];
+  const pattern = leaf?.fullPath ?? leaf?.routeId;
+  return pattern ? normalizePathname(pattern) : undefined;
+}
+
+const present = <T>(value: T | null | undefined): value is T =>
+  value !== null && value !== undefined && !(typeof value === "string" && value.trim() === "");
+
+/**
+ * The override for one page, merged field by field: the exact pathname wins,
+ * the route pattern fills what it leaves unset.
+ */
+export function findOverride(
+  seo: SeoRecord | null | undefined,
+  pathname: string,
+  routePattern?: string,
+): SeoPageOverride | null {
+  if (!seo?.pages) return null;
+  const exact = seo.pages[normalizePathname(pathname)];
+  const pattern = routePattern ? seo.pages[normalizePathname(routePattern)] : undefined;
+  if (!exact && !pattern) return null;
+  const merged: SeoPageOverride = {};
+  for (const key of ["title", "description", "image", "canonical", "noindex"] as const) {
+    const value = present(exact?.[key]) ? exact?.[key] : pattern?.[key];
+    if (present(value)) (merged as Record<string, unknown>)[key] = value;
+  }
+  return merged;
+}
+
+/** Fill `{title}` and `{site}` (or `{site.name}`) in a template. */
+export function fillTemplate(template: string, values: { title: string; site: string }): string {
+  return template
+    .replace(/\{title\}/g, values.title)
+    .replace(/\{site(?:\.name)?\}/g, values.site)
+    .trim();
+}
+
+/**
+ * The document title for a code title.
+ *
+ * The template is skipped when the title already names the site, so a code
+ * title of "Clay Studio | Pottery in Hackney" does not become
+ * "Clay Studio | Pottery in Hackney | Clay Studio".
+ */
+export function applyTitleTemplate(title: string, siteName: string, template?: string | null): string {
+  const site = siteName.trim();
+  const base = title.trim();
+  if (!site) return base;
+  if (!base) return site;
+  if (base.toLowerCase().includes(site.toLowerCase())) return base;
+  const filled = fillTemplate(template?.trim() || DEFAULT_TITLE_TEMPLATE, { title: base, site });
+  return filled || base;
+}
+
+/** The canonical URL for a page: the override's, else origin + pathname. */
+export function canonicalFor(
+  seo: SeoRecord,
+  pathname: string,
+  override?: SeoPageOverride | null,
+  options?: { entity?: boolean },
+): string {
+  if (present(override?.canonical)) return override!.canonical!;
+  const origin = (options?.entity ? seo.defaultWebsiteOrigin || seo.origin : seo.origin).replace(/\/+$/, "");
+  const path = normalizePathname(pathname);
+  return path === "/" ? `${origin}/` : `${origin}${path}`;
+}
+
+export type ResolvedPageSeo = {
+  /** The document title, template applied. */
+  title: string;
+  /** The title for share cards, without the site suffix. */
+  shareTitle: string;
+  description: string;
+  image?: string;
+  noindex: boolean;
+  /** Null when there is no record, so no canonical can be stated. */
+  canonical: string | null;
+  /** True when a creator override supplied at least one field. */
+  overridden: boolean;
+};
+
+export type ResolveInput = {
+  pathname: string;
+  routePattern?: string;
+  type?: SeoPageType;
+  title?: string;
+  description?: string;
+  image?: string;
+  noindex?: boolean;
+  /** Entity pages canonicalize to the profile's default website. */
+  entity?: boolean;
+};
+
+export function resolvePageSeo(seo: SeoRecord | null | undefined, input: ResolveInput): ResolvedPageSeo {
+  const codeTitle = input.title?.trim() ?? "";
+
+  if (!seo) {
+    // No record: today's behaviour, exactly. The code's values stand as given.
+    const title = codeTitle;
+    return {
+      title,
+      shareTitle: title,
+      description: input.description || title,
+      image: input.image || undefined,
+      noindex: !!input.noindex,
+      canonical: null,
+      overridden: false,
+    };
+  }
+
+  const override = findOverride(seo, input.pathname, input.routePattern);
+  const typeTemplate = input.type ? seo.typeTemplates?.[input.type] : undefined;
+  const site = seo.siteName ?? "";
+
+  let title: string;
+  let shareTitle: string;
+  if (present(override?.title)) {
+    // An approved title is what the creator signed off on, so it is used
+    // verbatim: no template, no suffix.
+    title = override!.title!.trim();
+    shareTitle = title;
+  } else {
+    shareTitle = codeTitle || site;
+    title = applyTitleTemplate(shareTitle, site, typeTemplate?.title || seo.titleTemplate);
+  }
+
+  const description =
+    (present(override?.description) ? override!.description! : undefined) ||
+    input.description ||
+    (typeTemplate?.description ? fillTemplate(typeTemplate.description, { title: shareTitle, site }) : undefined) ||
+    seo.defaultDescription ||
+    shareTitle;
+
+  const image = (present(override?.image) ? override!.image! : undefined) || input.image || seo.defaultImage || undefined;
+
+  const noindex =
+    seo.indexing === false ||
+    (typeof override?.noindex === "boolean" ? override.noindex : !!input.noindex);
+
+  return {
+    title,
+    shareTitle,
+    description,
+    image,
+    noindex,
+    canonical: canonicalFor(seo, input.pathname, override, { entity: input.entity }),
+    overridden: !!override && Object.keys(override).length > 0,
+  };
+}

package/src/seo/seoHead.ts

@@ -0,0 +1,61 @@
+import {
+  pathnameFromContext,
+  resolvePageSeo,
+  routePatternFromContext,
+  seoRecordFromContext,
+  type ResolvedPageSeo,
+} from "./resolve";
+import type { SeoHeadContext, SeoHeadInput, SeoMetaEntry } from "./types";
+
+/** JSON-LD nodes as head() meta entries. TanStack renders each as a script tag. */
+export function jsonLdMeta(jsonLd?: object | object[] | null): SeoMetaEntry[] {
+  const nodes = Array.isArray(jsonLd) ? jsonLd : jsonLd ? [jsonLd] : [];
+  return nodes.filter((n) => !!n && typeof n === "object").map((n) => ({ "script:ld+json": n }));
+}
+
+/** The per-page share and robots tags for one resolved page. */
+export function pageMeta(resolved: ResolvedPageSeo, ogType = "website"): SeoMetaEntry[] {
+  const { title, shareTitle, description, image, noindex, canonical } = resolved;
+  return [
+    { title },
+    { name: "description", content: description },
+    { property: "og:title", content: shareTitle },
+    { property: "og:description", content: description },
+    { property: "og:type", content: ogType },
+    ...(canonical ? [{ property: "og:url", content: canonical }] : []),
+    ...(image ? [{ property: "og:image", content: image }] : []),
+    { name: "twitter:card", content: "summary_large_image" },
+    { name: "twitter:title", content: shareTitle },
+    { name: "twitter:description", content: description },
+    ...(image ? [{ name: "twitter:image", content: image }] : []),
+    ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
+  ];
+}
+
+/**
+ * A route's SEO, declared in code with the creator's edits resolved over it.
+ *
+ *   head: (ctx) => seoHead(ctx, { title: "About Clay Studio", description: "..." })
+ *
+ * Reads the site's SEO record from the root match (the root loader fetched it
+ * with `fetchSiteBootstrap`) and returns `{ meta }` ONLY. Never links: TanStack
+ * concatenates links across every match, so a canonical here would sit beside
+ * the root's and the page would carry two. The root's `siteSeoHead` is the one
+ * place a canonical comes from.
+ *
+ * With no record (an older backend, or a failed fetch) it emits what
+ * `buildHeadMeta` always did, minus the links.
+ */
+export function seoHead(ctx: SeoHeadContext | undefined | null, input: SeoHeadInput): { meta: SeoMetaEntry[] } {
+  const seo = seoRecordFromContext(ctx);
+  const resolved = resolvePageSeo(seo, {
+    pathname: pathnameFromContext(ctx),
+    routePattern: routePatternFromContext(ctx),
+    type: input.type ?? "page",
+    title: input.title,
+    description: input.description,
+    image: input.image,
+    noindex: input.noindex,
+  });
+  return { meta: [...pageMeta(resolved), ...jsonLdMeta(input.jsonLd)] };
+}

package/src/seo/siteSeoHead.ts

@@ -0,0 +1,97 @@
+import { buildIdentitySchema, buildWebSiteSchema, identitySchemaId } from "../utils/structuredData";
+import {
+  canonicalFor,
+  findOverride,
+  isHostedPath,
+  leafRoutePatternFromContext,
+  pathnameFromContext,
+  seoRecordFromContext,
+} from "./resolve";
+import { jsonLdMeta } from "./seoHead";
+import type { SeoHeadContext, SeoLinkEntry, SeoMetaEntry } from "./types";
+
+export type SiteSeoFallback = {
+  /** Used when there is no SEO record, e.g. the site config's name. */
+  siteName?: string | null;
+  description?: string | null;
+  image?: string | null;
+};
+
+/**
+ * Site-wide head tags, for the ROOT route's `head()`.
+ *
+ *   head: (ctx) => siteSeoHead(ctx)
+ *
+ * Every tag here is a fallback a page can replace (TanStack keeps the deepest
+ * title and the deepest meta of each name), except two things only the root
+ * may emit:
+ *
+ *  - the canonical link, because links are concatenated across matches rather
+ *    than replaced. It is skipped under `/i/`, where the hosted page emits its
+ *    own (an entity's canonical is on the default website, which only that page
+ *    knows to say);
+ *  - the WebSite and identity JSON-LD, on "/" only.
+ *
+ * `robots` is set here when the whole site is noindex or this path's override
+ * says so, so it holds even on a page whose code never calls `seoHead`.
+ */
+export function siteSeoHead(
+  ctx: SeoHeadContext | undefined | null,
+  fallback: SiteSeoFallback = {},
+): { meta: SeoMetaEntry[]; links: SeoLinkEntry[] } {
+  const seo = seoRecordFromContext(ctx);
+  const pathname = pathnameFromContext(ctx);
+
+  if (!seo) {
+    const name = fallback.siteName?.trim();
+    return {
+      meta: [
+        ...(name ? [{ title: name }, { property: "og:site_name", content: name }] : []),
+        ...(fallback.description ? [{ name: "description", content: fallback.description }] : []),
+        ...(fallback.image ? [{ property: "og:image", content: fallback.image }] : []),
+        { name: "twitter:card", content: "summary_large_image" },
+      ],
+      links: [],
+    };
+  }
+
+  const override = findOverride(seo, pathname, leafRoutePatternFromContext(ctx));
+  const description = seo.defaultDescription || fallback.description || undefined;
+  const image = seo.defaultImage || fallback.image || undefined;
+  const noindex = seo.indexing === false || override?.noindex === true;
+
+  const meta: SeoMetaEntry[] = [
+    { title: seo.siteName },
+    ...(description ? [{ name: "description", content: description }] : []),
+    { property: "og:site_name", content: seo.siteName },
+    ...(image ? [{ property: "og:image", content: image }] : []),
+    { name: "twitter:card", content: "summary_large_image" },
+    ...(seo.verification?.google ? [{ name: "google-site-verification", content: seo.verification.google }] : []),
+    ...(seo.verification?.bing ? [{ name: "msvalidate.01", content: seo.verification.bing }] : []),
+    ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
+  ];
+
+  if (pathname === "/") {
+    const origin = seo.origin.replace(/\/+$/, "");
+    const identity = buildIdentitySchema(seo.identity, { origin });
+    meta.push(
+      ...jsonLdMeta(
+        [
+          buildWebSiteSchema({
+            name: seo.siteName,
+            url: `${origin}/`,
+            description: seo.defaultDescription,
+            publisherId: identity ? identitySchemaId(origin) : null,
+          }),
+          identity,
+        ].filter((n): n is Record<string, unknown> => !!n),
+      ),
+    );
+  }
+
+  const links: SeoLinkEntry[] = isHostedPath(pathname)
+    ? []
+    : [{ rel: "canonical", href: canonicalFor(seo, pathname, override) }];
+
+  return { meta, links };
+}

package/src/seo/types.ts

@@ -0,0 +1,99 @@
+// The SEO record, as `GET /public/websites/seo` returns it.
+//
+// The backend owns the data (settings, templates, the creator's approved page
+// overrides); code owns the defaults. These types are the seam between the two,
+// and the backend returns exactly this shape. Change one side, change both.
+
+export type SeoPageType =
+  | "page"
+  | "product"
+  | "event"
+  | "course"
+  | "coaching"
+  | "blog_post"
+  | "blog_category"
+  | "podcast"
+  | "podcast_episode"
+  | "community"
+  | "series"
+  | "film";
+
+export type SeoPageOverride = {
+  title?: string | null;
+  description?: string | null;
+  image?: string | null;
+  /** Absolute URL. */
+  canonical?: string | null;
+  noindex?: boolean | null;
+};
+
+export type SeoIdentity = {
+  kind: "person" | "organization" | "local_business";
+  name: string;
+  logo?: string | null;
+  sameAs: string[];
+  address?: { street?: string; locality?: string; region?: string; postalCode?: string; country?: string } | null;
+  phone?: string | null;
+};
+
+export type SeoRecord = {
+  websiteId: string;
+  /** "https://claystudio.com": the primary verified custom domain, else https://{subdomain}.{ROOT_DOMAIN}. */
+  origin: string;
+  isDefaultWebsite: boolean;
+  /** Origin of the profile's default website. Entity canonicals point here. */
+  defaultWebsiteOrigin: string;
+  siteName: string;
+  defaultDescription: string | null;
+  defaultImage: string | null;
+  /** Default "{title} | {site}". */
+  titleTemplate: string;
+  typeTemplates: Partial<Record<SeoPageType, { title?: string; description?: string }>>;
+  identity: SeoIdentity | null;
+  verification: { google?: string | null; bing?: string | null };
+  /** false = the whole site is noindex. */
+  indexing: boolean;
+  /**
+   * Key = exact pathname ("/about", "/i/store/mug") OR route pattern
+   * ("/team/$slug"). Entity overrides arrive already expanded to their /i/
+   * pathname.
+   */
+  pages: Record<string, SeoPageOverride>;
+  /** Max updatedAt of the inputs, ISO. */
+  version: string;
+};
+
+/** What a route's code says its SEO is, before any creator edit. */
+export type SeoHeadInput = {
+  title: string;
+  description?: string;
+  image?: string;
+  noindex?: boolean;
+  type?: SeoPageType;
+  jsonLd?: object | object[];
+};
+
+/**
+ * The part of TanStack's `head()` context Forge reads.
+ *
+ * Structural rather than imported, so Forge does not pin a router version and a
+ * site can pass `ctx` straight through.
+ */
+export type SeoMatchLike = {
+  pathname?: string;
+  routeId?: string;
+  fullPath?: string;
+  loaderData?: unknown;
+};
+
+export type SeoHeadContext = {
+  matches?: ReadonlyArray<SeoMatchLike | undefined>;
+  match?: SeoMatchLike;
+  params?: Record<string, string>;
+  loaderData?: unknown;
+};
+
+/** One `head()` meta entry. A JSON-LD node rides as `{ "script:ld+json": obj }`. */
+export type SeoMetaEntry = Record<string, unknown>;
+
+export type SeoLinkEntry = { rel: string; href: string };

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

@@ -129,3 +129,68 @@ describe("fetchSiteBootstrap", () => {
     expect(r.diagnostics?.probe).toBeUndefined();
   });
 });
+
+describe("fetchSiteBootstrap: the SEO record", () => {
+  const RECORD = {
+    websiteId: "w1",
+    origin: "https://clay.example",
+    isDefaultWebsite: true,
+    defaultWebsiteOrigin: "https://clay.example",
+    siteName: "Clay",
+    defaultDescription: null,
+    defaultImage: null,
+    titleTemplate: "{title} | {site}",
+    typeTemplates: {},
+    identity: null,
+    verification: {},
+    indexing: true,
+    pages: {},
+    version: "2026-10-01T00:00:00.000Z",
+  };
+
+  it("fetches it alongside the rest when a websiteId is given", async () => {
+    const seen: string[] = [];
+    stubFetch((url) => {
+      seen.push(url);
+      if (url.includes("/websites/seo")) return json(RECORD);
+      return url.includes("/content") ? json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} }) : json({});
+    });
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteId: "w1", websiteVersionId: "v1" });
+    expect(seen).toContain(`${API}/public/websites/seo?websiteId=w1`);
+    expect(r.seo).toEqual(RECORD);
+    expect(r.diagnostics).toBeNull();
+  });
+
+  it("does not ask for it without a websiteId", async () => {
+    const seen: string[] = [];
+    stubFetch((url) => {
+      seen.push(url);
+      return json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} });
+    });
+    const r = await fetchSiteBootstrap({ apiUrl: API, websiteVersionId: "v1" });
+    expect(seen.some((u) => u.includes("/websites/seo"))).toBe(false);
+    expect(r.seo).toBeNull();
+  });
+
+  it("is null on a 404, a network error or a body that is not a record, and never a diagnostics failure", async () => {
+    for (const fail of [
+      () => new Response("no", { status: 404 }),
+      () => {
+        throw new TypeError("fetch failed");
+      },
+      () => json({ error: "nope" }),
+    ]) {
+      stubFetch((url) =>
+        url.includes("/websites/seo")
+          ? fail()
+          : url.includes("/content")
+            ? json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} })
+            : json({}),
+      );
+      const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteId: "w1", websiteVersionId: "v1" });
+      expect(r.seo).toBeNull();
+      expect(r.diagnostics).toBeNull();
+      vi.unstubAllGlobals();
+    }
+  });
+});

package/src/server/index.ts

@@ -56,6 +56,8 @@ import { seoContextFromSiteConfig, type ReviewSchemaReview, type SiteSeoContext
 // each route that needs share tags.
 import { buildHeadMeta } from "../utils/headMeta";
 export type { SiteSeoContext };
+import type { SeoRecord } from "../seo/types";
+export type { SeoRecord };
 import type { SiteConfig } from "../data/queries/useWebsite";
 // Type-only, so nothing from the React data layer reaches this React-free entry.
 // Re-exported so a route loader can name the shape it got back without importing
@@ -241,20 +243,31 @@ export async function probeApi(apiUrl: string, opts?: { timeoutMs?: number }): P
 export async function fetchSiteBootstrap(opts: {
   apiUrl: string;
   profileId?: string;
+  /**
+   * The website being rendered. When given, the SEO record is fetched in the
+   * same round trip and returned as `seo`, for `siteSeoHead` / `seoHead`.
+   */
+  websiteId?: string;
   websiteVersionId?: string;
   state?: "draft" | "published";
   /** Set false to skip the reachability probe even when a fetch failed. */
   probe?: boolean;
-}): Promise<{ contentDoc: ContentDocument; siteConfig: SiteConfig | null; diagnostics: ForgeSsrDiagnostics | null }> {
-  const { apiUrl, profileId, websiteVersionId, state = "published" } = opts;
-
-  const [content, siteConfig] = await Promise.all([
+}): Promise<{
+  contentDoc: ContentDocument;
+  siteConfig: SiteConfig | null;
+  seo: SeoRecord | null;
+  diagnostics: ForgeSsrDiagnostics | null;
+}> {
+  const { apiUrl, profileId, websiteId, websiteVersionId, state = "published" } = opts;
+
+  const [content, siteConfig, seo] = await Promise.all([
     websiteVersionId
       ? getJsonResult<ContentDocument>(apiUrl, "/public/websites/content", { websiteVersionId, state })
       : Promise.resolve<JsonResult<ContentDocument>>({ ok: true, data: emptyContentDocument() }),
     profileId
       ? getJsonResult<SiteConfig>(apiUrl, "/public/websites/site-config", { profileId })
       : Promise.resolve<JsonResult<SiteConfig | null>>({ ok: true, data: null }),
+    websiteId ? fetchSeoRecordServer({ apiUrl, websiteId }) : Promise.resolve(null),
   ]);
 
   // A deploy with no version / no profile baked in isn't a failure — there was
@@ -270,10 +283,26 @@ export async function fetchSiteBootstrap(opts: {
   return {
     contentDoc: content.ok ? (content.data ?? emptyContentDocument()) : emptyContentDocument(),
     siteConfig: siteConfig.ok ? (siteConfig.data ?? null) : null,
+    // Not a diagnostics failure: a site renders correctly without it, on the
+    // code's own SEO, and an older API simply does not have the route.
+    seo,
     diagnostics,
   };
 }
 
+/**
+ * The website's SEO record (settings, templates, approved page overrides).
+ *
+ * `null` on ANY failure, including a 404 from an API that predates the route
+ * and a body that is not a record: every SEO function treats `null` as "use
+ * the code's own values", so a missing record degrades to today's tags rather
+ * than to a broken page.
+ */
+export async function fetchSeoRecordServer(opts: { apiUrl: string; websiteId: string }): Promise<SeoRecord | null> {
+  const record = await getJson<SeoRecord>(opts.apiUrl, "/public/websites/seo", { websiteId: opts.websiteId });
+  return record && typeof record === "object" && typeof record.siteName === "string" ? record : null;
+}
+
 /** Fetch a single event by id or slug for SSR. */
 /**
  * Every published event, for SSR of the events list.

package/src/types/models.ts

@@ -474,6 +474,11 @@ export interface PublicAuthUser {
   updatedAt: string;
   id: string;
   membership?: Membership;
+  /**
+   * Set when this is a read-only "Preview as client" session: a creator viewing
+   * the portal as this person. Null (or absent on older APIs) otherwise.
+   */
+  preview?: { previewedByName: string; expiresAt: string } | null;
 }
 
 export type UpdateLocalUserPayload = Pick<PublicAuthUser, "firstName">;
@@ -550,6 +555,12 @@ export interface PublicAuthContextType extends PublicAuthState {
   validateLoginCredentials: (data: LoginInput & { profileId: string }) => Promise<string>;
   verifyLoginCode: (email: string, code: string, profileId: string) => Promise<{ smartLinkPath: string | undefined }>;
   resendLoginCode: (email: string) => Promise<void>;
+  /**
+   * Sign in with a session another call already minted, e.g. the email-first
+   * flow's `signed_in` answer: stores the token pair exactly as the code
+   * sign-ins do and sets the user.
+   */
+  adoptSession: (session: { token: string; refreshToken?: string; account: PublicAuthUser }) => void;
   logout: (persist?: boolean) => Promise<void>;
   updateLocalUser: (data: UpdateLocalUserPayload) => void;
   clearErrorMessage: () => void;