@teamscala/service-boot 0.23.284

package/src/register-registry-page-route.ts

@@ -0,0 +1,765 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Reads `page_route` registry rows for the current service slug and registers
+ * Hono routes that resolve data via `resource_loader` graph-based sources.
+ *
+ * Every page_route uses pattern `/:id` and every resource_loader uses a
+ * `sources[]` dependency graph. When header/footer sources are present in
+ * the resolved graph, the output includes a `regions` array for shell rendering.
+ * Otherwise it produces single-page puckData.
+ */
+
+import type { RenderModeLiteral } from "./page-route-shell-types.ts";
+import { PageRouteConfigSchema } from "@teamscala/db-validation/registry-schemas/page-route";
+import { ResourceLoaderConfigSchema } from "@teamscala/db-validation/registry-schemas/resource-loader";
+import {
+	loadRegistryConfig,
+	loadRegistryConfigsByType,
+} from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+import { fetchOrganisationPageBranding } from "@teamscala/db/fetch-organisation-page-branding";
+import { getPlatformOrgId } from "@teamscala/db/registry/platform";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import type { Hono } from "hono";
+import { bindPageHandler } from "./bind-page-handler.ts";
+import { getServerClient } from "./page-server-orpc/server-client.ts";
+import { resolveFromLoaderConfig } from "./resolve-from-loader-config.ts";
+import { runContentGate } from "./content-gate/gate.ts";
+import { agreementGateConfig } from "./agreement-gate.ts";
+import { proposalGateConfig } from "./proposal-gate.ts";
+import { gptGateConfig } from "./gpt-gate.ts";
+import { extractOrgIdFromCallbackPath } from "./resolvers/portal-route-paths.ts";
+import { PrimaryResourceMissingError } from "./resource-not-found.ts";
+import { decideContentPageFloor } from "./content-page-floor.ts";
+import type { CreatePageHandler, RendererComponentEntry } from "./types.ts";
+import {
+	staticShellGraphCache,
+	paramRouteGraphCache,
+	readCachedGraph,
+} from "./register-registry-page-route/graph-cache.ts";
+import { resolvedToPageData } from "./register-registry-page-route/resolve-page-data.ts";
+import {
+	buildMetaFromContext,
+	resolveTemplateTitle,
+} from "./register-registry-page-route/meta-title.ts";
+import { prefetchAiChatSession } from "./register-registry-page-route/ai-chat-prefetch.ts";
+import {
+	applyApprovalEmailToken,
+} from "./register-registry-page-route/proposal-approval-email-token.ts";
+import {
+	applyPartnerBrand,
+	applyClientLogo,
+} from "./register-registry-page-route/proposal-brand-stamping.ts";
+
+interface PageRouteConfig {
+	pattern: string;
+	service: string;
+	loader_slug: string;
+	meta_context?: Record<string, Record<string, string>>;
+	resource_type?: string;
+	providers?: string[];
+}
+
+interface RegistryRouteArgs {
+	app: Hono;
+	serviceSlug: string;
+	components: Record<string, RendererComponentEntry>;
+	createPageHandler: CreatePageHandler;
+	authMode: string;
+	renderMode: RenderModeLiteral;
+	providers: string[];
+}
+
+function extractUrlParams(
+	pattern: string,
+	pathname: string,
+): Record<string, string> {
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = pathname.split("/").filter(Boolean);
+	const params: Record<string, string> = {};
+	for (let i = 0; i < patternParts.length; i++) {
+		const pp = patternParts[i];
+		if (pp.startsWith(":")) {
+			params[pp.slice(1)] = pathParts[i] ?? "";
+		} else if (pp === "*") {
+			params._wildcard = pathParts.slice(i).join("/");
+			break;
+		}
+	}
+	return params;
+}
+
+export async function registerRegistryPageRoute(
+	args: RegistryRouteArgs,
+): Promise<string[]> {
+	const {
+		app,
+		serviceSlug,
+		components,
+		createPageHandler,
+		authMode,
+		renderMode,
+		providers: baseProviders,
+	} = args;
+	const log = getAppLogger();
+
+	const allRoutes = await loadRegistryConfigsByType(
+		"page_route",
+		PageRouteConfigSchema,
+	);
+	const serviceRoutes = allRoutes.filter(
+		(r) => r.config.service === serviceSlug,
+	);
+	if (serviceRoutes.length === 0) return [];
+
+	// Only a service serving arbitrary portal paths (a `/*` catchall route —
+	// the portal) redirects signed-in users from `/` into
+	// /<website>/<org>/dashboard. Single-site portal-mode services (the
+	// fleet dashboard) serve their real page AT `/` — the unconditional
+	// redirect 404-looped them (2026-06-06; service-runtime@1.15.82 made
+	// the redirect opt-in via this flag).
+	const servesPortalCatchall = serviceRoutes.some(
+		(r) => r.config.pattern === "/*",
+	);
+
+	// Sort routes so more specific patterns register before wildcard/param routes.
+	// Hono matches by registration order, so `/*` (the portal catchall) registered
+	// before `/sign-in` would swallow the sign-in page and render it inside the
+	// PortalTemplate instead of the standalone PublicTemplate shell.
+	serviceRoutes.sort((a, b) => {
+		const pa = a.config.pattern;
+		const pb = b.config.pattern;
+		// Wildcard `/*` goes last
+		if (pa === "/*") return 1;
+		if (pb === "/*") return -1;
+		// Param routes `/:param` sort after literal routes
+		const aIsLiteral = !pa.includes(":") && !pa.includes("*");
+		const bIsLiteral = !pb.includes(":") && !pb.includes("*");
+		if (aIsLiteral && !bIsLiteral) return -1;
+		if (!aIsLiteral && bIsLiteral) return 1;
+		return 0;
+	});
+
+	const registeredPatterns: string[] = [];
+
+	for (const routeRow of serviceRoutes) {
+		const routeConfig = routeRow.config;
+		const pattern = routeConfig.pattern;
+		const loaderSlug = routeConfig.loader_slug;
+		const routeProviders = routeConfig.providers ?? baseProviders;
+
+		let loaderConfig: Awaited<
+			ReturnType<typeof loadRegistryConfig<typeof ResourceLoaderConfigSchema>>
+		> | null = null;
+		try {
+			loaderConfig = await loadRegistryConfig(
+				"resource_loader",
+				loaderSlug,
+				ResourceLoaderConfigSchema,
+			);
+		} catch (err) {
+			if (
+				err instanceof Error &&
+				err.constructor.name === "RegistryConfigMissingError"
+			) {
+				log.warn(
+					`[scala-install:${serviceSlug}] page_route "${routeRow.slug}" references resource_loader "${loaderSlug}" which does not exist — skipping`,
+				);
+				continue;
+			}
+			throw err;
+		}
+
+		// Gate for the static-shell graph cache (see module header).
+		const isStaticShell =
+			!routeConfig.resource_type &&
+			!pattern.includes(":") &&
+			!pattern.includes("*");
+
+		const loadData = async (request: Request) => {
+			// A bare root ("/") that declares a resource_type is a UUID-driven
+			// public site (proposals/forms/quiz) with no resource selected — it
+			// must render the branded holding/not-found page ("no <resource> at
+			// this link"), never fall through the shared public loader to the
+			// marketing site. PrimaryResourceMissingError is the existing signal
+			// the page binder maps to buildResourceNotFoundResponse. A "/" route
+			// WITHOUT a resource_type (e.g. scala-public's marketing root) is
+			// unaffected and still renders its content.
+			if (pattern === "/" && routeConfig.resource_type) {
+				// Status 200: the bare root is a valid "no <resource> selected"
+				// landing, not an error — and kind:ui services must answer GET /
+				// with 200 (verify-prod-persistent-slot). An invalid /:id keeps
+				// the default 404 (genuinely not found).
+				throw new PrimaryResourceMissingError(routeConfig.resource_type, 200);
+			}
+			const url = new URL(request.url);
+			const params = extractUrlParams(pattern, url.pathname);
+			params.host = request.headers.get("host")?.split(":")[0] || url.hostname;
+			params.path = url.pathname || "/";
+			const graphKey = `graph:${routeRow.slug}:${params.host}:${params.path}`;
+			const primaryType = routeConfig.resource_type;
+			const hasPrimarySource =
+				!!primaryType &&
+				!!(loaderConfig as { sources?: { key: string }[] }).sources?.some(
+					(s) => s.key === primaryType,
+				);
+			const graphCache = isStaticShell
+				? staticShellGraphCache
+				: paramRouteGraphCache;
+			const typedLoaderConfig = loaderConfig as v.InferOutput<
+				typeof ResourceLoaderConfigSchema
+			> & {
+				sources: NonNullable<
+					v.InferOutput<typeof ResourceLoaderConfigSchema>["sources"]
+				>;
+			};
+			let resolved: Record<string, unknown>;
+			// SWR read over @teamscala/cache: fresh hit serves the cached graph, stale
+			// hit serves it AND fires ONE background refresh (refreshInBackground,
+			// single-flight via the cache's in-flight map), miss returns undefined.
+			// The refresh callback re-resolves + stores a clone; a primary-missing
+			// (dead-link) graph THROWS so the cache is not updated — a dead link must
+			// stay per-request so a just-created record appears immediately
+			// (refreshInBackground catches, leaves the stale entry, logs one line).
+			const cachedGraph = readCachedGraph(
+				graphCache,
+				graphKey,
+				() =>
+					resolveFromLoaderConfig(typedLoaderConfig, params).then(
+						(freshGraph) => {
+							const freshPrimaryMissing =
+								hasPrimarySource &&
+								primaryType &&
+								freshGraph[primaryType] == null;
+							if (freshPrimaryMissing) {
+								throw new Error(
+									`primary resource "${primaryType}" missing — skip cache update for ${graphKey}`,
+								);
+							}
+							return structuredClone(freshGraph);
+						},
+					),
+			);
+			if (cachedGraph !== undefined) {
+				// Clone-on-get: gateAgreementContent + block resolution MUTATE the
+				// graph in place, so each request gets its own copy.
+				resolved = structuredClone(cachedGraph) as Record<string, unknown>;
+			} else {
+				resolved = await resolveFromLoaderConfig(typedLoaderConfig, params);
+				const primaryMissing =
+					hasPrimarySource && primaryType && resolved[primaryType] == null;
+				if (!primaryMissing) {
+					// Defensive clone: structuredClone throws on non-cloneable loader
+					// graphs (functions/Proxies/Prisma instances). A swallowed throw
+					// here used to SILENTLY disable the graph cache for this key
+					// (fail-open-silent — forbidden by protective-layers-fail-explicitly),
+					// which left affected routes re-resolving the loader graph every
+					// request (measured ~1.2s on the projects utility shell). JSON-clone
+					// preserves the data graph (dropping functions/undefined a loader
+					// graph shouldn't carry) so the cache stays effective; both fallbacks
+					// are LOGGED so the offending non-cloneable source is observable +
+					// fixable, never silently disabling the cache again.
+					let cloned: unknown;
+					try {
+						cloned = structuredClone(resolved);
+					} catch (err) {
+						log.warn(
+							`[scala-install:${serviceSlug}] graph-cache structuredClone failed for ${graphKey} — falling back to JSON-clone (non-cloneable value in loader graph): ${err instanceof Error ? err.message : err}`,
+						);
+						try {
+							cloned = JSON.parse(JSON.stringify(resolved));
+						} catch (err2) {
+							log.warn(
+								`[scala-install:${serviceSlug}] graph-cache JSON-clone also failed for ${graphKey} — cache disabled for this key (observable): ${err2 instanceof Error ? err2.message : err2}`,
+							);
+							cloned = undefined;
+						}
+					}
+					if (cloned !== undefined) {
+						graphCache.set(graphKey, cloned);
+					}
+				}
+			}
+			// A route that declares resource_type is meaningless without that
+			// entity: a dead link (wrong id, deleted row) must 404 with the
+			// branded not-found page — never fall through to default content
+			// (the "Vision Toolbar" leak, operator-observed 2026-06-05).
+			if (hasPrimarySource && primaryType && resolved[primaryType] == null) {
+				throw new PrimaryResourceMissingError(primaryType);
+			}
+			// A CONTENT route (no resource_type) whose loader resolves a `page`
+			// body source must not synthesize an empty page for an unmatched path
+			// and serve a cacheable 200 — the generalized "Vision Toolbar" leak
+			// (operator-reported 5×: a deleted page, e.g. /roadmap, returned 200
+			// with an empty body instead of not-found). No page row → dead link →
+			// branded 404 floor. A page row that exists but has zero blocks → a
+			// content gap → the floor's empty-page surface (200). Both carry the
+			// "Take me home" action. The pure decision lives in content-page-floor.ts
+			// (unit-tested without the Hono/DB/graph machinery). Region-slot
+			// (utility/portal) shells without a `page` source are untouched.
+			const contentFloorError = decideContentPageFloor({
+				hasResourceType: !!primaryType,
+				hasPageContentSource: !!(loaderConfig as { sources?: { key: string }[] }).sources?.some(
+					(s) => s.key === "page",
+				),
+				page: resolved.page,
+			});
+			if (contentFloorError) throw contentFloorError;
+			// Withhold gated content from the SSR unless the request carries a valid
+			// signed access token — the single server-side scrape gate. One engine
+			// (runContentGate), one config per content type. Proposals run first
+			// (an authorized viewer's gate is removed, so the agreement gate then
+			// no-ops); each config scopes to its own resource/field so they never
+			// collide.
+			const gateCookie = request.headers.get("cookie");
+			const gateNow = Date.now();
+			// Resolve the signed-in viewer from the unified auth session (local
+			// verify, works on Railway) and stamp it on the graph, so a gate can
+			// release on a standard OTP-login session (config.sessionAuthorize) —
+			// the unified path, no per-gate OTP code. Anonymous if no session.
+			let sessionUserId: string | undefined;
+			let sessionOrgId: string | undefined;
+			try {
+				const { getSession } = await import("@teamscala/auth/get-session.ts");
+				const sess = await getSession(request.headers);
+				if (sess?.user?.email) {
+					(resolved as { sessionVisitor?: { email: string; name?: string } }).sessionVisitor =
+						{
+							email: sess.user.email,
+							name: sess.user.name ?? undefined,
+						};
+					sessionUserId = sess.user.id;
+					sessionOrgId = sess.session?.activeOrganizationId ?? undefined;
+					// Stamp the per-request portal identity so block portal context
+					// (useBlockPortal().userId) is populated for authed users on
+					// org/hub pages — the SSR-side WRITER the connections-block reader
+					// (ClientBlockServicesProvider → __PAGE_DATA__.portalContext.user.id)
+					// depends on. Rides the same per-request path as sessionVisitor
+					// above (never the cached loader graph); merge preserves any
+					// portalContext fields set elsewhere (e.g. viewAsMembers). Without
+					// this, connections-block short-circuits at SignInPrompt.
+					const rc = resolved as {
+						portalContext?: {
+							user?: { id?: string } | null;
+							orgId?: string;
+						};
+					};
+					rc.portalContext = {
+						...(rc.portalContext ?? {}),
+						user: sessionUserId ? { id: sessionUserId } : null,
+						orgId: sessionOrgId,
+					};
+					// Read pane widths from the portal cookie (the client writes
+					// it immediately on resize via setPortalCookie; the cookie is
+					// sent with every HTTP request so the SSR reads it here).
+					// This renders the correct pane width from the first byte —
+					// no post-hydration shift, no client-side state read.
+					const paneWidthsMatch = gateCookie?.match(
+						/portal_pane_widths=([^;]+)/,
+					);
+					if (paneWidthsMatch) {
+						try {
+							const parsed = JSON.parse(
+								decodeURIComponent(paneWidthsMatch[1]),
+							);
+							if (parsed.left)
+								(rc.portalContext as Record<string, unknown>).paneLeftWidth =
+									parsed.left;
+							if (parsed.right)
+								(rc.portalContext as Record<string, unknown>).paneRightWidth =
+									parsed.right;
+						} catch {
+							// Malformed cookie — fall back to defaults.
+						}
+					}
+					if (sessionUserId) {
+						try {
+							const dbClient = getServerClient() as unknown as {
+								user: {
+									findUnique: (args: {
+										where: { id: string };
+										select: { preferences: boolean };
+									}) => Promise<{ preferences: unknown } | null>;
+								};
+							};
+							const userRow = await dbClient.user.findUnique({
+								where: { id: sessionUserId },
+								select: { preferences: true },
+							});
+							const portalPrefs = (
+								(userRow?.preferences as Record<string, unknown> | null)
+									?.portal as Record<string, unknown> | undefined
+							);
+							if (portalPrefs?.paneLeftWidth) {
+								(rc.portalContext as Record<string, unknown>).paneLeftWidth =
+									portalPrefs.paneLeftWidth;
+							}
+							if (portalPrefs?.paneRightWidth) {
+								(rc.portalContext as Record<string, unknown>).paneRightWidth =
+									portalPrefs.paneRightWidth;
+							}
+						} catch {
+							// Pane widths are non-critical — fall back to defaults.
+						}
+					}
+				}
+			} catch {
+				// No auth factory / no session → anonymous; gates fall back to token.
+			}
+			await runContentGate(resolved, gateCookie, gateNow, proposalGateConfig);
+			await runContentGate(resolved, gateCookie, gateNow, agreementGateConfig);
+				// The public GPT identity gate: seeds resolved.initialVisitor from the
+				// signed gpt_token cookie so a returning visitor's conversation renders
+				// at SSR (no capture-gate→chat flash). Open capture, seed-only — it
+				// never withholds page content (gpt-gate.ts).
+				await runContentGate(resolved, gateCookie, gateNow, gptGateConfig);
+			const meta = buildMetaFromContext(routeConfig.meta_context, resolved);
+		// /sign-in brand override: a shared org-scoped link 302→/sign-in for the
+		// unauthed crawler (WhatsApp), which saw the service's default website
+		// brand (the platform owner). The callbackURL carries the destination org
+		// — override resolved.brand (before the title/meta/og are built from it)
+		// so the page reflects the org the visitor is signing in to. Scoped to
+		// /sign-in; resource pages keep their own brand.
+		//
+		// The org is segment 1 of the canonical portal shape /<websiteId>/<orgId>/
+		// <path>, NOT segment 0 (the website id): reading segment 0 fed a website id
+		// into fetchOrganisationPageBranding, which resolved no org and left the
+		// default (super-admin) brand — the cross-tenant mis-branding this override
+		// exists to prevent (portal-branding-resolves-page-org-first, 2026-07-21).
+		// Shared helper so this and bind-page-handler cannot drift on the answer.
+		try {
+			const reqUrl = new URL(request.url);
+			if (reqUrl.pathname === "/sign-in") {
+				const cb = reqUrl.searchParams.get("callbackURL") ?? "";
+				const cbOrgId = extractOrgIdFromCallbackPath(cb);
+				const currentBrandOrgId =
+					(resolved.brand as { orgId?: string } | undefined)?.orgId ??
+					(resolved as { orgId?: string }).orgId;
+				if (cbOrgId && cbOrgId !== currentBrandOrgId) {
+					const branding = await fetchOrganisationPageBranding(
+						getServerClient() as never,
+						cbOrgId,
+					);
+					if (branding) {
+						const existing = (resolved.brand as Record<string, unknown>) ?? {};
+						const existingLogo =
+							(existing.logo as Record<string, unknown> | undefined) ?? {};
+						resolved.brand = {
+							...existing,
+							companyName: branding.company_name,
+							companyFriendlyName: branding.company_name,
+							primaryColor: branding.brand_primary_color ?? existing.primaryColor,
+							headingFont: branding.brand_heading_font ?? existing.headingFont,
+							bodyFont: branding.brand_body_font ?? existing.bodyFont,
+							logo: {
+								light: branding.company_logo_for_light_theme,
+								dark: branding.company_logo_for_dark_theme,
+								brand: existingLogo.brand ?? null,
+							},
+						};
+					}
+				}
+			}
+		} catch {
+			// Branding fetch failed — keep the default brand (no regression).
+		}
+		const pageMetaTitle =
+			(
+				(resolved.loaderData as { page?: { meta_title?: unknown } } | undefined)
+					?.page?.meta_title ??
+				(resolved.page as { meta_title?: unknown } | undefined)?.meta_title
+			);
+		if (
+			typeof pageMetaTitle === "string" &&
+			pageMetaTitle.trim() &&
+			new URL(request.url).pathname === "/sign-in"
+		) {
+			meta.title = pageMetaTitle.trim();
+		}
+		const templateTitle = resolveTemplateTitle(serviceSlug, resolved);
+		if (templateTitle && !meta.title) {
+			const resolvedEntity =
+				(resolved.agent as { name?: string } | undefined)?.name ||
+				(resolved.proposal as { name?: string } | undefined)?.name ||
+				(resolved.form as { name?: string } | undefined)?.name ||
+				(resolved.quiz as { title?: string } | undefined)?.title;
+			if (!resolvedEntity) {
+				meta.title = templateTitle;
+			}
+		}
+			const regionSlots = (
+				loaderConfig as v.InferOutput<typeof ResourceLoaderConfigSchema> & {
+					region_slots?: string[];
+				}
+			).region_slots;
+			const themeParam = url.searchParams.get("theme");
+			// ?theme is the EMBED override — only honor it when this page is
+			// actually framed (a form/quiz in a GPT tool panel, sec-fetch-dest:
+			// iframe). A DIRECT visit carrying ?theme= (e.g. copied from a GPT
+			// embed URL) must NOT override the org's DB theme — what the visitor
+			// sees is org-driven, never URL-driven.
+			const isFramedEmbed =
+				request.headers.get("sec-fetch-dest") === "iframe";
+			const themeOverride =
+				isFramedEmbed &&
+				(themeParam === "light" || themeParam === "dark")
+					? (themeParam as "light" | "dark")
+					: undefined;
+			const pageData = resolvedToPageData(
+				resolved,
+				meta,
+				request,
+				routeProviders !== baseProviders ? routeProviders : undefined,
+				regionSlots,
+				themeOverride,
+			);
+			const panelSlug = new URL(request.url).searchParams.get("panel");
+			if (panelSlug) {
+				try {
+					const dbReg = getServerClient() as unknown as {
+						registry_entries: { findFirst: (a: { where: unknown; select: unknown }) => Promise<{ config: Record<string, unknown> } | null> };
+					};
+					const pv = await dbReg.registry_entries.findFirst({
+						where: { type: "panel_view", slug: panelSlug, is_active: true },
+						select: { config: true },
+					});
+					const pageSlug = (pv?.config?.content as { page_slug?: string })?.page_slug;
+					if (pageSlug) {
+						const dbPages = getServerClient() as unknown as {
+							builda_pages: { findFirst: (a: { where: unknown; select: unknown }) => Promise<{ puck_data: unknown } | null> };
+						};
+						const panelPage = await dbPages.builda_pages.findFirst({
+							where: { path: `/${pageSlug}`, is_active: true },
+							select: { puck_data: true },
+						});
+						if (panelPage?.puck_data) {
+							(pageData as Record<string, unknown>).panelPageData = panelPage.puck_data;
+							(pageData as Record<string, unknown>).activePanel = panelSlug;
+						}
+					}
+				} catch { /* non-critical */ }
+			}
+			if (
+				new URL(request.url).pathname === "/sign-in" &&
+				typeof pageMetaTitle === "string" &&
+				pageMetaTitle.trim()
+			) {
+				pageData.meta = {
+					...(pageData.meta as Record<string, unknown>),
+					title: pageMetaTitle.trim(),
+				};
+			}
+			// brand-is-org-owned-full-scheme, reconciled with page-org-first
+			// (portal-branding-resolves-page-org-first): the session override now
+			// personalizes ONLY platform pages (page org === website owning-org).
+			// Tenant pages keep their resolved page-org brand — the page is
+			// authoritative, the menu switcher changes which tenant's pages you
+			// view. Anonymous/public (no session) keeps the resolved brand. Same
+			// fetchOrganisationPageBranding pattern as the /sign-in brand override.
+			if (
+				sessionOrgId &&
+				sessionOrgId !== (pageData.orgId as string | undefined) &&
+				// Page-org-first (portal-branding-resolves-page-org-first): the
+				// session override personalizes ONLY the shared PLATFORM website
+				// (super-admin org). A TENANT-owned site (a customer GPT/quiz/portal)
+				// keeps its page-org brand regardless of the viewer session org. The
+				// old pageData.orgId===website.org mis-fired for a tenant whose page org equals their own website org.
+				getPlatformOrgId() ===
+					((pageData.website as { organisation_id?: string | null } | undefined)
+						?.organisation_id ?? undefined)
+			) {
+				try {
+					const branding = await fetchOrganisationPageBranding(
+						getServerClient() as never,
+						sessionOrgId,
+					);
+					if (branding) {
+						pageData.orgId = sessionOrgId;
+						const existing = (pageData.brand as Record<string, unknown>) ?? {};
+						const existingLogo =
+							(existing.logo as Record<string, unknown>) ?? {};
+						pageData.brand = {
+							...existing,
+							companyName: branding.company_name,
+							companyFriendlyName: branding.company_name,
+							primaryColor: branding.brand_primary_color ?? existing.primaryColor,
+							headingFont: branding.brand_heading_font ?? existing.headingFont,
+							bodyFont: branding.brand_body_font ?? existing.bodyFont,
+							logo: {
+								light: branding.company_logo_for_light_theme,
+								dark: branding.company_logo_for_dark_theme,
+								brand: existingLogo.brand ?? null,
+							},
+						};
+					}
+				} catch {
+					// Branding fetch failed — keep the default brand (no regression).
+				}
+			}
+			warnUncoveredBlocks(pageData, components, serviceSlug, params.path, log);
+			// Fire the AI-chat conversation prefetch NOW (in parallel with the
+			// proposal/partner/client post-processors below) so its ~eager cost is
+			// hidden in their window, then await it just before return. orgId is the
+			// URL :orgId (org-scoped routing — the same source AiChat uses); pageData
+			// .orgId is stamped later in service-runtime, not yet set here.
+			// A canonical portal URL is /<websiteId>/<organisationId>/<path> — the
+			// org is segment 1, NOT segment 0. Reading segment 0 captured the
+			// WEBSITE id and passed it as an organisation id, which failed silently
+			// because both are well-formed UUIDs: the prefetch simply warmed a
+			// session against the wrong tenant (found 2026-07-21).
+			//
+			// Prefer segment 1; fall back to segment 0 only when segment 1 is not a
+			// UUID (the single-UUID shape, which is live and supported — NOT
+			// transitional). The fallback is deliberately kept
+			// UNCHANGED-BEHAVIOUR rather than "fixed": a UUID in segment 0 is
+			// genuinely ambiguous — of the 40 UUID-first page paths in builda_pages,
+			// ZERO are websites and ZERO are organisations, so segment 0 can also be
+			// an unrelated record id. Position alone cannot resolve that; only
+			// validating the id against organisation_profile can, and that is a DB
+			// read this hot prefetch path should not take without caching
+			// (`hot-path-resolutions-are-cached`). Preferring segment 1 is strictly
+			// better for the canonical shape and no worse for any other.
+			const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+			const pathSegments = new URL(request.url).pathname.split("/").filter(Boolean);
+			const aiOrgId = UUID_RE.test(pathSegments[1] ?? "")
+				? pathSegments[1]
+				: UUID_RE.test(pathSegments[0] ?? "")
+					? pathSegments[0]
+					: undefined;
+			// Detached (NOT awaited into the response). prefetchAiChatSession ->
+			// createOrRestore is DB-heavy (~1.1s), per-user, and uncached, and was
+			// awaited on EVERY loadData — the dominant board loadMs cost (confirmed
+			// aiChatPrefetch=1145ms = the full loadMs). Fire it in the background so
+			// it still warms the server-side session (users who open chat find it
+			// warm via their live fetch) without blocking the page response. The SSR
+			// chat seed (pageData.aiChatSession) is sacrificed — chat opens with a
+			// live fetch instead of SSR-instant — the right trade: most loads never
+			// open chat, so eager-awaited prefetch was the waste.
+			void prefetchAiChatSession(resolved, sessionUserId, aiOrgId).catch((err) =>
+				log.warn(
+					`[scala-install:${serviceSlug}] background ai-chat prefetch failed: ${err instanceof Error ? err.message : err}`,
+				),
+			);
+			// Proposal pages: resolve the {{approvalEmail}} button token to the
+			// org's registered company email (creator email as fallback).
+			if (resolved.proposal) {
+				await applyApprovalEmailToken(
+					pageData as Record<string, unknown>,
+					resolved.proposal as { created_by?: string } | undefined,
+				);
+				// Stash the partner logo from the partnerOrg loader source (CRM record
+				// loaded by partner_id) onto pageData.partnerLogo — header fills
+				// automatically, no inline body-Hero prop needed.
+				applyPartnerBrand(
+					pageData as Record<string, unknown>,
+					resolved.partnerOrg as
+						| { logo_url?: string | null; brand_primary_color?: string | null }
+						| undefined
+						| null,
+				);
+				// Auto-resolve the client's company logo from the clientOrg loader
+				// source (contact → company → crm_organisations.logo_url). Only
+				// injects when the Hero's clientLogo prop is empty — a manually set
+				// logo always wins.
+				applyClientLogo(
+					pageData as Record<string, unknown>,
+					resolved.clientOrg as
+						| { logo_url?: string | null; name?: string | null }
+						| undefined
+						| null,
+				);
+			}
+			return pageData;
+		};
+
+		const routeRenderMode: "public" | "portals" | "utility" =
+			routeConfig.render_mode === "portal"
+				? "portals"
+				: routeConfig.render_mode === "public"
+					? "public"
+					: routeConfig.render_mode === "utility"
+						? "utility"
+						: renderMode;
+
+		const handler = createPageHandler({
+			components,
+			providers: routeProviders,
+			renderMode: routeRenderMode,
+			loadData: loadData as never,
+			portalHomeRedirect: servesPortalCatchall,
+			serviceSlug,
+		});
+
+		app.get(pattern, async (c) => {
+			const routeOrgId = c.req.param("orgId");
+			return bindPageHandler(
+				c,
+				handler as never,
+				authMode,
+				serviceSlug,
+				`registry:${routeRow.slug}`,
+				routeOrgId,
+			);
+		});
+
+		registeredPatterns.push(pattern);
+		log.info(
+			`[scala-install:${serviceSlug}] registered registry page route "${pattern}" → resource_loader "${loaderSlug}"`,
+		);
+	}
+
+	return registeredPatterns;
+}
+
+/**
+ * Block-coverage guard (protective-layers-fail-explicitly). A page that renders
+ * a block whose component is NOT registered — because its package is missing
+ * from service_install.config.block_packages — silently renders BLANK. That is
+ * the exact failure behind the 2026-06-04 scala-sign regression (sign-in-block
+ * dropped from block_packages → the gate + signature fields vanished) which left
+ * only a benign boot WARN. This turns that silent blank into a loud,
+ * GlitchTip-visible ERROR naming the page + block, throttled to once per
+ * (service, block type) so a hot path can never spam it.
+ */
+const uncoveredBlocksLogged = new Set<string>();
+
+function collectBlockTypes(node: unknown, out: Set<string>): void {
+	if (Array.isArray(node)) {
+		for (const child of node) collectBlockTypes(child, out);
+		return;
+	}
+	if (node && typeof node === "object") {
+		const obj = node as Record<string, unknown>;
+		if (
+			typeof obj.type === "string" &&
+			obj.props &&
+			typeof obj.props === "object"
+		) {
+			out.add(obj.type);
+		}
+		for (const value of Object.values(obj)) collectBlockTypes(value, out);
+	}
+}
+
+function warnUncoveredBlocks(
+	pageData: unknown,
+	components: Record<string, RendererComponentEntry>,
+	serviceSlug: string,
+	path: unknown,
+	log: ReturnType<typeof getAppLogger>,
+): void {
+	const used = new Set<string>();
+	collectBlockTypes(pageData, used);
+	for (const type of used) {
+		if (type in components) continue;
+		const key = `${serviceSlug}:${type}`;
+		if (uncoveredBlocksLogged.has(key)) continue;
+		uncoveredBlocksLogged.add(key);
+		log.error(
+			`[scala-install:${serviceSlug}] page "${String(path)}" renders block "${type}" but NO component is registered for it — its package is almost certainly missing from service_install.config.block_packages, so it renders BLANK. Add the owning @teamscala/* package to block_packages and restart. (block-coverage guard)`,
+		);
+	}
+}