@tribe-nest/forge 1.13.0

package/src/server/index.ts

@@ -0,0 +1,260 @@
+// Forge server entry — framework-agnostic, React-free data fetchers for SSR.
+//
+// Route `loader`s run OUTSIDE React, so they can't use the `useForge()` context;
+// these functions take the per-tenant config (apiUrl / profileId / …) as plain
+// arguments instead. Import from `@tribe-nest/forge/server` (kept separate from
+// the main entry so no React/JSX is pulled into the server bundle). Because this
+// lives in the versioned Forge package, fetch logic + fixes propagate to every
+// deployed site via a Forge version bump — never freeze a server call into a
+// site's own files.
+//
+// Each fetcher hits a public endpoint with plain `fetch`, so it works in both
+// the SSR pass and client-side navigation. Failures degrade to a safe fallback
+// (`null` / an empty document) rather than throwing out of the loader.
+
+// App background-job runtime (no-config wrapper over the JobsDO). Server-only.
+export * from "./jobs";
+
+import { emptyContentDocument, type ContentDocument } from "../content/types";
+import type {
+  IEvent,
+  IPublicProduct,
+  PublicCourse,
+  CoachingProduct,
+  BlogPost,
+  BlogCategory,
+  PodcastShow,
+  Collection,
+  CollectionEntry,
+  CollectionQueryParams,
+  CollectionQuery,
+  CollectionSearchResult,
+} from "../types/models";
+import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
+import type { SiteConfig } from "../data/queries/useWebsite";
+
+/** GET a public endpoint and parse JSON, returning `null` on any failure. */
+async function getJson<T>(apiUrl: string, path: string, params?: Record<string, string | undefined>): Promise<T | null> {
+  try {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params ?? {})) if (v != null) qs.set(k, v);
+    const query = qs.toString();
+    const res = await fetch(`${apiUrl}${path}${query ? `?${query}` : ""}`);
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** POST a JSON body to a public endpoint and parse JSON, `null` on any failure. */
+async function postJson<T>(apiUrl: string, path: string, body: unknown): Promise<T | null> {
+  try {
+    const res = await fetch(`${apiUrl}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch a site's content document for SSR (version + state). */
+export async function fetchContentDocument(opts: {
+  apiUrl: string;
+  websiteVersionId?: string;
+  state?: "draft" | "published";
+}): Promise<ContentDocument> {
+  const { apiUrl, websiteVersionId, state = "published" } = opts;
+  if (!websiteVersionId) return emptyContentDocument();
+  const doc = await getJson<ContentDocument>(apiUrl, "/public/websites/content", {
+    websiteVersionId,
+    state,
+  });
+  return doc ?? emptyContentDocument();
+}
+
+/**
+ * Fetch a tenant's runtime config (settlement currency, Meta Pixel id, payment
+ * provider) for SSR by profile id. Seed the result into `<ForgeProvider
+ * initialSiteConfig={…}>` so `useSiteConfig()` has it on the first paint — no
+ * client fetch flash, no hydration mismatch. Returns `null` on failure.
+ */
+export function fetchSiteConfig(opts: { apiUrl: string; profileId?: string }): Promise<SiteConfig | null> {
+  if (!opts.profileId) return Promise.resolve(null);
+  return getJson<SiteConfig>(opts.apiUrl, "/public/websites/site-config", { profileId: opts.profileId });
+}
+
+/** Fetch a single event by id or slug for SSR. */
+export function fetchEventServer(opts: { apiUrl: string; profileId?: string; idOrSlug: string }): Promise<IEvent | null> {
+  return getJson<IEvent>(opts.apiUrl, `/public/events/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+/** Fetch a single product by id or slug for SSR. */
+export function fetchProductServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<IPublicProduct | null> {
+  return getJson<IPublicProduct>(opts.apiUrl, `/public/products/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+/** Fetch a single course by id or slug for SSR. */
+export function fetchCourseServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<PublicCourse | null> {
+  return getJson<PublicCourse>(opts.apiUrl, `/public/courses/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+/** Fetch a single coaching product by id or slug for SSR. */
+export function fetchCoachingProductServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<CoachingProduct | null> {
+  return getJson<CoachingProduct>(opts.apiUrl, `/public/coaching/products/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+/** Fetch a single blog post by id or slug for SSR. */
+export function fetchBlogPostServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<BlogPost | null> {
+  return getJson<BlogPost>(opts.apiUrl, `/public/blog/posts/${encodeURIComponent(opts.idOrSlug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+/** Fetch a single blog category by slug for SSR. */
+export function fetchBlogCategoryServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+}): Promise<BlogCategory | null> {
+  return getJson<BlogCategory>(opts.apiUrl, `/public/blog/posts/categories/${encodeURIComponent(opts.slug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
+// --- Podcasts (SSR) — podcasts are podcast-type blog categories ---
+
+/** All podcast shows for the profile, for SSR of the podcasts index. */
+export async function fetchPodcastsServer(opts: { apiUrl: string; profileId?: string }): Promise<PodcastShow[]> {
+  return (await getJson<PodcastShow[]>(opts.apiUrl, `/public/blog/posts/podcasts`, { profileId: opts.profileId })) ?? [];
+}
+
+/** A show's episodes (audio posts) in feed order, for SSR of a show/episode page. */
+export async function fetchPodcastEpisodesServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+}): Promise<BlogPost[]> {
+  const res = await getJson<{ data: BlogPost[] }>(
+    opts.apiUrl,
+    `/public/blog/posts/categories/${encodeURIComponent(opts.slug)}/posts`,
+    { profileId: opts.profileId, page: "1", limit: "100" },
+  );
+  return (res?.data ?? []).filter((p) => (p.media ?? []).some((m) => (m.type || "").startsWith("audio")));
+}
+
+// --- CMS collections (SSR) ---
+
+/** Fetch a collection's definition + field schema by slug for SSR. */
+export function fetchCollectionServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+}): Promise<Collection | null> {
+  return getJson<Collection>(opts.apiUrl, `/public/collections/${encodeURIComponent(opts.slug)}/schema`, {
+    profileId: opts.profileId,
+  });
+}
+
+/**
+ * Search/filter/sort/geo over a collection's published entries for SSR (GET).
+ * @deprecated Prefer {@link fetchCollectionQueryServer} (the full query engine).
+ * Kept for backwards compatibility.
+ */
+export function fetchCollectionEntriesServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+  params?: CollectionQueryParams;
+}): Promise<CollectionSearchResult | null> {
+  return getJson<CollectionSearchResult>(
+    opts.apiUrl,
+    `/public/collections/${encodeURIComponent(opts.slug)}/entries`,
+    collectionParamsToQuery(opts.profileId, opts.params),
+  );
+}
+
+/** Rich structured query over a collection for SSR (POST /query). */
+export function fetchCollectionQueryServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+  query?: CollectionQuery;
+}): Promise<CollectionSearchResult | null> {
+  const { scope, query } = splitCollectionQuery(opts.query);
+  return postJson<CollectionSearchResult>(
+    opts.apiUrl,
+    `/public/collections/${encodeURIComponent(opts.slug)}/query`,
+    { profileId: opts.profileId, scope, query },
+  );
+}
+
+/** Fetch a single published entry by slug for SSR. */
+export function fetchCollectionEntryServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+  entrySlug: string;
+}): Promise<CollectionEntry | null> {
+  return getJson<CollectionEntry>(
+    opts.apiUrl,
+    `/public/collections/${encodeURIComponent(opts.slug)}/entries/${encodeURIComponent(opts.entrySlug)}`,
+    { profileId: opts.profileId },
+  );
+}
+
+// --- PWA (installable code sites) — React-free manifest/SW/head builders ---
+export {
+  buildWebManifest,
+  forgeServiceWorkerScript,
+  buildPwaHead,
+  FORGE_PWA_VERSION,
+  type WebManifest,
+  type WebManifestIcon,
+  type WebManifestShortcut,
+  type BuildWebManifestOptions,
+  type BuildPwaHeadOptions,
+  type PwaHead,
+  type HeadLink,
+  type HeadMeta,
+} from "./pwa";
+
+/** Strip HTML tags + collapse whitespace for a plain-text SEO meta description. */
+export function toPlainText(html?: string, max = 200): string | undefined {
+  if (!html) return undefined;
+  const text = html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&[a-z]+;/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return undefined;
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}

package/src/server/jobs.ts

@@ -0,0 +1,104 @@
+// App background-job runtime — the thin, no-config wrapper over the host-owned
+// JobsDO (bound as `env.JOBS` at deploy; see apps/dispatch-worker/jobsDO.ts and
+// docs/cms-mini-apps-scaffold-and-recipe.md). The app author only ever touches
+// these three functions + a job map — the DO id-ing, dedup hashing, and callback
+// verification are hidden here. All are SERVER-ONLY (they need the Worker `env`).
+
+// The bits of the app Worker's `env` this runtime needs. Injected at deploy:
+// JOBS (the DO binding), plus the app's identity + script name + API base.
+export interface AppJobsEnv {
+  JOBS: {
+    idFromName: (name: string) => unknown;
+    get: (id: unknown) => AppJobsStub;
+  };
+}
+
+interface AppJobsStub {
+  reconcile: (script: string, appId: string, desired: JobSchedule[], hash: string) => Promise<{ changed: boolean }>;
+  enqueue: (script: string, appId: string, name: string, payload: unknown, delayMs: number) => Promise<void>;
+}
+
+export interface JobSchedule {
+  /** Stable job name — also the key in your job map + the `scheduleId` in the token. */
+  name: string;
+  /** How often to run, in milliseconds (e.g. 60_000 = every minute). */
+  intervalMs: number;
+}
+
+export type JobHandler = (payload: unknown, env: unknown) => Promise<void> | void;
+
+export interface AppJobsConfig {
+  /** The app id (VITE_APP_ID). */
+  appId: string;
+  /** This Worker's script name in the dispatch namespace (VITE_APP_SCRIPT). */
+  script: string;
+  /** The TribeNest public API base (VITE_API_URL) — used to verify the callback token. */
+  apiUrl: string;
+}
+
+const stub = (env: AppJobsEnv, appId: string): AppJobsStub => env.JOBS.get(env.JOBS.idFromName(appId));
+
+// A stable fingerprint of the desired schedule set, so the DO skips reconcile
+// when nothing changed (sorted by name → order-independent).
+function scheduleHash(schedules: JobSchedule[]): string {
+  return JSON.stringify([...schedules].sort((a, b) => a.name.localeCompare(b.name)).map((s) => [s.name, s.intervalMs]));
+}
+
+/**
+ * Reconcile the app's recurring schedules with the DO — call ONCE per deploy
+ * (guard with a module flag + ctx.waitUntil so it isn't per-request). Idempotent:
+ * unchanged schedules keep their timing, a changed interval re-times only that
+ * one, a removed one is pruned.
+ */
+export async function reconcileAppJobs(env: AppJobsEnv, cfg: AppJobsConfig, schedules: JobSchedule[]): Promise<void> {
+  await stub(env, cfg.appId).reconcile(cfg.script, cfg.appId, schedules, scheduleHash(schedules));
+}
+
+/** Enqueue a durable one-time job (survives redeploys, retried on failure). */
+export async function enqueueAppJob(
+  env: AppJobsEnv,
+  cfg: AppJobsConfig,
+  name: string,
+  payload?: unknown,
+  delayMs = 0,
+): Promise<void> {
+  await stub(env, cfg.appId).enqueue(cfg.script, cfg.appId, name, payload ?? null, delayMs);
+}
+
+/**
+ * Handle the DO's alarm callback (`POST /_jobs/run`). Verifies the platform
+ * token, looks up the named handler in your job map, and runs it with the app's
+ * `env` (so `env.SHOPIFY_TOKEN` etc. are available). Wire your `/_jobs/run` route
+ * to this.
+ */
+export async function handleAppJobRun(
+  request: Request,
+  env: unknown,
+  cfg: AppJobsConfig,
+  jobs: Record<string, JobHandler>,
+): Promise<Response> {
+  const token = request.headers.get("x-app-sync-token") ?? "";
+  let valid = false;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/public/apps/${cfg.appId}/verify-sync`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token }),
+    });
+    valid = (await res.json())?.valid === true;
+  } catch {
+    valid = false;
+  }
+  if (!valid) return new Response("unauthorized", { status: 401 });
+
+  const body = (await request.json().catch(() => ({}))) as { job?: string; payload?: unknown };
+  const handler = body.job ? jobs[body.job] : undefined;
+  if (!handler) return new Response("unknown job", { status: 404 });
+  try {
+    await handler(body.payload ?? null, env);
+    return new Response("ok");
+  } catch (err) {
+    // Non-2xx → the DO retries (one-time) / re-fires next interval (recurring).
+    return new Response(`job failed: ${(err as Error).message}`, { status: 500 });
+  }
+}

package/src/server/pwa.ts

@@ -0,0 +1,332 @@
+// PWA server helpers — framework-agnostic, React-free (imported from
+// `@tribe-nest/forge/server`). These build the web app manifest, the service
+// worker source, and the head <link>/<meta> tags for an installable code site.
+//
+// Everything lives here (the versioned Forge package), NOT in per-site files, so
+// a fix propagates to every deployed site on its next Forge version bump — the
+// core Forge invariant ("never freeze logic into site files"). The site carries
+// only three thin route shells (`/manifest.webmanifest`, `/sw.js`, `/offline`)
+// that call these functions.
+//
+// See docs/pwa-custom-code-initiative.md (locked decisions).
+
+import type { ContentDocument } from "../content/types";
+import type { SiteConfig } from "../data/queries/useWebsite";
+
+// The Forge package version, baked into the SW cache name so a version bump
+// purges old caches on `activate`. Bumped with the package; a literal here keeps
+// this module dependency-free (no JSON import in the SSR/Workers bundle).
+export const FORGE_PWA_VERSION = "1.1.0";
+
+// Forge baseline theme colors (kept in sync with `defaultForgeTheme` in
+// ui/theme/ForgeThemeProvider — duplicated here as literals so this server
+// module stays React-free and never pulls the UI layer into the SSR bundle).
+const DEFAULT_PRIMARY = "#6d28d9";
+const DEFAULT_BACKGROUND = "#ffffff";
+
+/**
+ * Read a `color`-typed field's value from the content document, tolerating both
+ * localized and bare storage. Returns `undefined` when the field is unset so the
+ * caller can fall back. Content-doc keys are already camelCase/dotted (theme.*),
+ * so no jsonb-key mangling applies here.
+ */
+function readThemeColor(doc: ContentDocument | undefined | null, path: string): string | undefined {
+  const rec = doc?.fields?.[path];
+  if (!rec) return undefined;
+  const v = rec.value;
+  if (typeof v === "string" && v) return v;
+  // Localized value map — take the default locale, then any first entry.
+  if (v && typeof v === "object") {
+    const map = v as Record<string, unknown>;
+    const dl = doc?.defaultLocale;
+    const pick = (dl && map[dl]) || Object.values(map)[0];
+    if (typeof pick === "string" && pick) return pick;
+  }
+  return undefined;
+}
+
+export interface WebManifestIcon {
+  src: string;
+  sizes: string;
+  type: string;
+  purpose?: string;
+}
+
+export interface WebManifestShortcut {
+  name: string;
+  short_name?: string;
+  description?: string;
+  url: string;
+  icons?: { src: string; sizes: string }[];
+}
+
+export interface WebManifest {
+  name: string;
+  short_name?: string;
+  description?: string;
+  start_url: string;
+  scope: string;
+  display: string;
+  orientation?: string;
+  background_color?: string;
+  theme_color?: string;
+  lang?: string;
+  dir?: string;
+  prefer_related_applications?: boolean;
+  icons: WebManifestIcon[];
+  categories?: string[];
+  shortcuts?: WebManifestShortcut[];
+  screenshots?: {
+    src: string;
+    sizes: string;
+    type: string;
+    form_factor?: string;
+    label?: string;
+  }[];
+}
+
+export interface BuildWebManifestOptions {
+  siteConfig: SiteConfig | null | undefined;
+  contentDoc?: ContentDocument | null;
+  overrides?: Partial<WebManifest>;
+}
+
+/**
+ * Build the web app manifest for a code site from the extended `site-config`
+ * `pwa` block + the content document's `theme.*` colors. When the creator has no
+ * `pwaConfig` (`siteConfig.pwa` is null), returns a minimal name-only manifest
+ * (no icons) — not installable, parity with the client's `{}` behavior — so the
+ * route always returns valid JSON and an admin nudge can prompt setup.
+ *
+ * - `theme_color` = content `theme.primary`, `background_color` = content
+ *   `theme.background` (code sites' theme source of truth), Forge defaults
+ *   otherwise. Improves on the client's primary-for-both.
+ * - `screenshots` omitted entirely when the creator hasn't uploaded them.
+ * - No hardcoded shortcuts — pass `overrides.shortcuts` (the starter points
+ *   them at `/i/*` pages).
+ */
+export function buildWebManifest(opts: BuildWebManifestOptions): WebManifest {
+  const { siteConfig, contentDoc, overrides } = opts;
+  const pwa = siteConfig?.pwa ?? null;
+
+  const themeColor = readThemeColor(contentDoc, "theme.primary") ?? DEFAULT_PRIMARY;
+  const backgroundColor = readThemeColor(contentDoc, "theme.background") ?? DEFAULT_BACKGROUND;
+
+  const name = pwa?.name || siteConfig?.siteName || "App";
+
+  // No PWA identity → minimal, non-installable manifest (valid JSON, no icons).
+  if (!pwa) {
+    return {
+      name,
+      short_name: siteConfig?.siteName || name,
+      start_url: "/",
+      scope: "/",
+      display: "standalone",
+      background_color: backgroundColor,
+      theme_color: themeColor,
+      icons: [],
+      ...overrides,
+    };
+  }
+
+  const icons: WebManifestIcon[] = [];
+  if (pwa.icon192) icons.push({ src: pwa.icon192, sizes: "192x192", type: "image/png", purpose: "maskable" });
+  if (pwa.icon512) icons.push({ src: pwa.icon512, sizes: "512x512", type: "image/png", purpose: "any" });
+
+  const screenshots: NonNullable<WebManifest["screenshots"]> = [];
+  if (pwa.screenshotWide1280X720)
+    screenshots.push({
+      src: pwa.screenshotWide1280X720,
+      sizes: "1280x720",
+      type: "image/png",
+      form_factor: "wide",
+      label: "Desktop view",
+    });
+  if (pwa.screenshotNarrow750X1334)
+    screenshots.push({
+      src: pwa.screenshotNarrow750X1334,
+      sizes: "750x1334",
+      type: "image/png",
+      form_factor: "narrow",
+      label: "Mobile view",
+    });
+
+  const manifest: WebManifest = {
+    name: pwa.name || name,
+    short_name: pwa.shortName || pwa.name || name,
+    description: pwa.description || undefined,
+    start_url: "/",
+    scope: "/",
+    display: "standalone",
+    orientation: "portrait-primary",
+    background_color: backgroundColor,
+    theme_color: themeColor,
+    lang: "en",
+    dir: "ltr",
+    prefer_related_applications: false,
+    icons,
+    categories: ["social", "business", "productivity"],
+    // `screenshots` omitted entirely when absent — installability never required it.
+    ...(screenshots.length ? { screenshots } : {}),
+    ...overrides,
+  };
+  return manifest;
+}
+
+export interface BuildPwaHeadOptions {
+  siteConfig: SiteConfig | null | undefined;
+  contentDoc?: ContentDocument | null;
+  /** Where the manifest route lives (default `/manifest.webmanifest`). */
+  manifestHref?: string;
+}
+
+/** A TanStack `head()`-shaped link entry. */
+export interface HeadLink {
+  rel: string;
+  href: string;
+  sizes?: string;
+  type?: string;
+}
+/** A TanStack `head()`-shaped meta entry. */
+export interface HeadMeta {
+  name?: string;
+  content: string;
+}
+
+export interface PwaHead {
+  links: HeadLink[];
+  metas: HeadMeta[];
+}
+
+/**
+ * The head <link>/<meta> entries an installable code site needs: manifest link,
+ * `apple-touch-icon` (icon192 — the client app is missing this; don't repeat
+ * that bug), `theme-color`, and the iOS standalone metas. Merge `links`/`metas`
+ * into the route's `head()` return. iOS 16.4+ web push only works from the
+ * installed (Home Screen) PWA — `<InstallBanner/>` is the gateway on iOS.
+ */
+export function buildPwaHead(opts: BuildPwaHeadOptions): PwaHead {
+  const { siteConfig, contentDoc } = opts;
+  const manifestHref = opts.manifestHref ?? "/manifest.webmanifest";
+  const themeColor = readThemeColor(contentDoc, "theme.primary") ?? DEFAULT_PRIMARY;
+  const appleIcon = siteConfig?.pwa?.icon192 || siteConfig?.pwa?.icon512;
+
+  const links: HeadLink[] = [{ rel: "manifest", href: manifestHref }];
+  if (appleIcon) links.push({ rel: "apple-touch-icon", href: appleIcon, sizes: "192x192" });
+
+  const metas: HeadMeta[] = [
+    { name: "theme-color", content: themeColor },
+    { 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: siteConfig?.pwa?.shortName || siteConfig?.pwa?.name || siteConfig?.siteName || "App" },
+  ];
+  return { links, metas };
+}
+
+/**
+ * The service-worker source, as a dependency-free vanilla-JS string served by
+ * the starter's `/sw.js` route (Content-Type: application/javascript). No
+ * Workbox, no vite-plugin-pwa — SSR sites want the network, so the SW earns its
+ * keep on offline UX + push, not shell caching:
+ *
+ *   - Navigations: network-first, no caching of SSR HTML; `/offline` on failure.
+ *   - `/assets/*` (hashed, immutable): cache-first.
+ *   - `push` + `notificationclick`: the FROZEN payload contract shared with the
+ *     client SW ({ type, title, body, url, profileId, channelId?, ...icon }).
+ *   - Cache name includes the Forge version; old caches purged on `activate`.
+ *   - `skipWaiting()` + `clients.claim()` (safe — no HTML precache).
+ *
+ * The `/offline` page is precached on install so the fallback renders with no
+ * network.
+ */
+export function forgeServiceWorkerScript(version: string = FORGE_PWA_VERSION): string {
+  const cacheName = `forge-pwa-v${version}`;
+  return `// Auto-generated Forge service worker (v${version}). Do not edit — served by /sw.js.
+const CACHE = ${JSON.stringify(cacheName)};
+const OFFLINE_URL = "/offline";
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE).then((cache) => cache.addAll([OFFLINE_URL])).catch(() => {})
+  );
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)))
+    ).then(() => self.clients.claim())
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const req = event.request;
+  if (req.method !== "GET") return;
+  const url = new URL(req.url);
+  if (url.origin !== self.location.origin) return;
+
+  // Hashed, immutable build assets: cache-first.
+  if (url.pathname.startsWith("/assets/") || url.pathname.startsWith("/_build/")) {
+    event.respondWith(
+      caches.open(CACHE).then((cache) =>
+        cache.match(req).then((hit) =>
+          hit ||
+          fetch(req).then((res) => {
+            if (res && res.status === 200) cache.put(req, res.clone());
+            return res;
+          })
+        )
+      )
+    );
+    return;
+  }
+
+  // Navigations (SSR HTML): network-first, no HTML caching, offline fallback.
+  if (req.mode === "navigate") {
+    event.respondWith(
+      fetch(req).catch(() =>
+        caches.open(CACHE).then((cache) => cache.match(OFFLINE_URL)).then((r) => r || Response.error())
+      )
+    );
+    return;
+  }
+});
+
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+  try {
+    const data = event.data.json();
+    const { title, body, type, url, profileId, channelId, spaceId, icon } = data;
+    const options = {
+      body: body,
+      icon: icon || undefined,
+      tag:
+        type === "chat_message" || type === "dm"
+          ? "chat-" + (channelId || profileId)
+          : spaceId
+          ? "space-" + spaceId
+          : "post-" + profileId,
+      data: { url: url, type: type },
+    };
+    event.waitUntil(self.registration.showNotification(title, options));
+  } catch (err) {
+    // swallow — a malformed push must not crash the SW
+  }
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const target = (event.notification.data && event.notification.data.url) || "/";
+  event.waitUntil(
+    self.clients.matchAll({ type: "window", includeUncontrolled: true }).then((clientList) => {
+      for (const client of clientList) {
+        if (client.url.indexOf(target) !== -1 && "focus" in client) return client.focus();
+      }
+      if (self.clients.openWindow) return self.clients.openWindow(target);
+    })
+  );
+});
+`;
+}