@teamscala/service-boot 0.23.284

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

@@ -0,0 +1,518 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Converts the resolved loader-graph into the pageData shape the renderer
+ * consumes — three branches: arbitrary region-slots (portal/utility), the
+ * header/body/footer public shell, and the single-page fallback. Extracted
+ * from register-registry-page-route.ts (single-purpose-file split).
+ */
+import { resolveThemeMode } from "../resolve-theme-mode.ts";
+import { composePageTitle } from "../compose-page-title.ts";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+/**
+ * Local structural type for Puck page data. Avoids a type-only import of
+ * `@puckeditor/core`, which is NOT a runtime dependency — `deps-derived-from-source`
+ * excludes whole-statement type-only imports, so the bare specifier has no
+ * installed package to resolve against at publish typecheck time. The shape used
+ * here (root/content/zones) is all this module reads or constructs.
+ */
+type PuckData = {
+	root: { props?: Record<string, unknown> };
+	content: unknown[];
+	zones?: Record<string, unknown>;
+};
+
+const EMPTY_PUCK_DATA: PuckData = { root: { props: {} }, content: [] };
+
+// Returns null on malformed JSON (observed via warn log) instead of a silent
+// masking empty fallback — protective-layers-fail-explicitly. Callers default
+// to EMPTY_PUCK_DATA where an empty render is the intended degradation.
+function extractPuckData(source: Record<string, unknown>): PuckData | null {
+	const raw = source.puck_data ?? source.puckData;
+	if (!raw) return EMPTY_PUCK_DATA;
+	if (typeof raw === "string") {
+		try {
+			return JSON.parse(raw) as PuckData;
+		} catch (err) {
+			getAppLogger().warn(
+				"[extractPuckData] malformed puck_data JSON — rendering empty",
+				{ err },
+			);
+			return null;
+		}
+	}
+	return raw as PuckData;
+}
+
+function applyLayoutDefaults(
+	puckData: PuckData,
+	defaults: Record<string, string>,
+): void {
+	if (!defaults || Object.keys(defaults).length === 0) return;
+	const data = puckData as { root?: { props?: Record<string, unknown> } };
+	if (!data.root) data.root = { props: {} };
+	if (!data.root.props) data.root.props = {};
+	for (const [key, value] of Object.entries(defaults)) {
+		if (data.root.props[key] == null) data.root.props[key] = value;
+	}
+}
+
+function pickRootProp<T>(regions: RegionEntry[], key: string): T | undefined {
+	for (const region of regions) {
+		const props = (
+			region.puckData as { root?: { props?: Record<string, unknown> } } | null
+		)?.root?.props;
+		const value = props?.[key];
+		if (value != null && value !== "") return value as T;
+	}
+	return undefined;
+}
+
+interface RegionEntry {
+	slot: string;
+	puckData: PuckData;
+	pageId: string;
+	website?: { slug: string; name: string; organisation_id?: string | null };
+	metaTitle?: string | null;
+	metaDescription?: string | null;
+}
+
+export function resolvedToPageData(
+	resolved: Record<string, unknown>,
+	meta: Record<string, unknown>,
+	request: Request,
+	providers: string[] | undefined,
+	regionSlots?: string[],
+	// ?theme=light|dark from the URL — wins over per-page/brand/website theme so
+	// a page framed inside another shell (e.g. a form in a GPT tool panel)
+	// matches the host's light/dark scheme so an embedded page doesn't flash.
+	themeOverride?: "light" | "dark",
+): Record<string, unknown> {
+	const brand = (resolved.brand as Record<string, unknown>) ?? {};
+	const primaryColor = (brand.primaryColor as string) ?? "";
+	const headingFont = (brand.headingFont as string) ?? null;
+	const bodyFont = (brand.bodyFont as string) ?? null;
+	const logo = (brand.logo as {
+		light: string | null;
+		dark: string | null;
+		brand: string | null;
+	}) ?? { light: null, dark: null, brand: null };
+
+	const brandTheme = typeof brand.theme === "string" ? brand.theme : undefined;
+
+	// Branch 1: arbitrary regions (portal/agents/docs) — region_slots from loader config
+	if (regionSlots && regionSlots.length > 0) {
+		const website = (resolved.website as Record<string, unknown>) ?? {};
+		const layoutDefaults =
+			(website.layout_defaults as Record<string, string>) ??
+			(website.layout_settings as Record<string, string>) ??
+			{};
+		const layoutSettings = website.layout_settings as
+			| { theme?: unknown }
+			| null
+			| undefined;
+		const websiteTheme =
+			layoutSettings && typeof layoutSettings.theme === "string"
+				? layoutSettings.theme
+				: undefined;
+
+		// Title derives from the primary resolved entity (e.g. the GPT agent),
+		// matching the flat-page branch — so a utility-shell GPT shows the agent
+		// name in <title>/OG, not the generic "Portal". Falls back to the website
+		// name, then "Portal". Without this, the region-slots branch returned
+		// early with a hardcoded "Portal" title (gpt-test: SSR/DOM/OG title FAIL).
+		const entityTitle =
+			(resolved.form as { name?: string })?.name ||
+			(resolved.quiz as { title?: string })?.title ||
+			(resolved.proposal as { name?: string })?.name ||
+			(resolved.agent as { name?: string })?.name;
+
+		const regions: RegionEntry[] = [];
+		for (const slot of regionSlots) {
+			const source = resolved[slot] as Record<string, unknown> | undefined;
+			if (!source) continue;
+			const puckData = extractPuckData(source) ?? EMPTY_PUCK_DATA;
+			applyLayoutDefaults(puckData, layoutDefaults);
+			regions.push({
+				slot,
+				puckData,
+				pageId: (source.id as string) ?? "",
+			});
+		}
+
+		if (regions.length === 0) {
+			return {
+				puckData: { root: { props: {} }, content: [] } as PuckData,
+				theme: "dark" as const,
+				brand: {
+					primaryColor,
+					backgroundColor: (brand.backgroundColor as string | null) ?? null,
+					lightSurface: (brand.lightSurface as string | null) ?? null,
+					darkSurface: (brand.darkSurface as string | null) ?? null,
+					headingFont,
+					bodyFont,
+					logo,
+					companyName: (brand.companyName as string) ?? null,
+					companyFriendlyName: (brand.companyFriendlyName as string) ?? null,
+					contactEmail: (brand.contactEmail as string) ?? null,
+					favicon: (brand.favicon as string) ?? null,
+				},
+				meta: {
+					title: composePageTitle({
+						templateTitle: (meta.title as string) || undefined,
+						websiteName: (website.name as string) || undefined,
+						entityTitle: entityTitle || undefined,
+					}),
+				},
+			};
+		}
+
+		const rootTheme = pickRootProp<string>(regions, "theme");
+		const { theme } = resolveThemeMode({
+			override: themeOverride,
+			candidates: [rootTheme, brandTheme, websiteTheme],
+		});
+
+		const overrideColor = pickRootProp<string>(regions, "primaryColor");
+		const overrideHeading = pickRootProp<string>(regions, "headingFont");
+		const overrideBody = pickRootProp<string>(regions, "bodyFont");
+		// The page the user is viewing is the main content region (center for
+		// portal, body for utility). Its name ("Dashboard") is the title subject.
+		const contentSlot = regionSlots.find((s) => s === "center" || s === "body");
+		const contentPageName = contentSlot
+			? ((resolved[contentSlot] as Record<string, unknown> | undefined)?.name as
+					| string
+					| undefined)
+			: undefined;
+
+		return {
+			puckData: { root: { props: {} }, content: [] } as PuckData,
+			regions,
+			// Region-shell blocks (e.g. the GPT chat in the center region) read
+			// their resolved entities from pageData.loaderData — same surface the
+			// flat single-page branch exposes. Without it the chat block has no
+			// agent and renders "Custom GPT not found".
+			loaderData: resolved,
+			website: {
+				slug: website.slug as string,
+				name: website.name as string,
+				organisation_id: website.organisation_id as string | null,
+				// header_settings carries the DB-driven header config (e.g.
+				// backdropBlur) the public shell applies — PublicTemplate reads
+				// pageData.website.header_settings.backdropBlur. Dropping it here
+				// silently kills the header blur even though the DB switch is set
+				// (the 2026-06-17 regression). Pass it through verbatim.
+				header_settings:
+					(website.header_settings as Record<string, unknown> | null) ?? null,
+			},
+			orgId:
+				((resolved.center as Record<string, unknown> | undefined)
+					?.organisation_id as string | null) ??
+				((resolved.agent as Record<string, unknown> | undefined)
+					?.organisation_id as string | null) ??
+				null,
+			brand: {
+				primaryColor: overrideColor ?? primaryColor,
+				backgroundColor: (brand.backgroundColor as string | null) ?? null,
+				lightSurface: (brand.lightSurface as string | null) ?? null,
+				darkSurface: (brand.darkSurface as string | null) ?? null,
+				headingFont: overrideHeading ?? headingFont,
+				bodyFont: overrideBody ?? bodyFont,
+				logo,
+				companyName: (brand.companyName as string) ?? null,
+				companyFriendlyName: (brand.companyFriendlyName as string) ?? null,
+				contactEmail: (brand.contactEmail as string) ?? null,
+					favicon: (brand.favicon as string) ?? null,
+			},
+			theme,
+			meta: {
+				title: composePageTitle({
+					templateTitle: (meta.title as string) || undefined,
+					websiteName: (website.name as string) || undefined,
+					pageName: contentPageName,
+					entityTitle: entityTitle || undefined,
+				}),
+			},
+		};
+	}
+
+	// Branch 2: public shell (header/body/footer regions from header/footer sources)
+	const headerSource = resolved.header as Record<string, unknown> | undefined;
+	const footerSource = resolved.footer as Record<string, unknown> | undefined;
+
+	if (headerSource || footerSource) {
+		const page = (resolved.page as Record<string, unknown>) ?? {};
+		const website =
+			(resolved.website_by_host as Record<string, unknown>) ??
+			(resolved.website as Record<string, unknown>) ??
+			{};
+		const layoutDefaults =
+			(website.layout_defaults as Record<string, string>) ??
+			(website.layout_settings as Record<string, string>) ??
+			{};
+		const layoutSettings = website.layout_settings as
+			| { theme?: unknown }
+			| null
+			| undefined;
+		const websiteTheme =
+			layoutSettings && typeof layoutSettings.theme === "string"
+				? layoutSettings.theme
+				: undefined;
+
+		const regions: RegionEntry[] = [];
+
+		if (headerSource) {
+			const headerPuck = extractPuckData(headerSource) ?? EMPTY_PUCK_DATA;
+			applyLayoutDefaults(headerPuck, layoutDefaults);
+			regions.push({
+				slot: "header",
+				puckData: headerPuck,
+				pageId: (headerSource.id as string) ?? "",
+			});
+		}
+
+		const bodyPuck = extractPuckData(page) ?? EMPTY_PUCK_DATA;
+		applyLayoutDefaults(bodyPuck, layoutDefaults);
+		regions.push({
+			slot: "body",
+			puckData: bodyPuck,
+			pageId: (page.id as string) ?? "",
+			metaTitle: (page.meta_title as string) ?? null,
+			metaDescription: (page.meta_description as string) ?? null,
+		});
+
+		if (footerSource) {
+			const footerPuck = extractPuckData(footerSource) ?? EMPTY_PUCK_DATA;
+			applyLayoutDefaults(footerPuck, layoutDefaults);
+			regions.push({
+				slot: "footer",
+				puckData: footerPuck,
+				pageId: (footerSource.id as string) ?? "",
+			});
+		}
+
+		const rootTheme = pickRootProp<string>(regions, "theme");
+		const { theme } = resolveThemeMode({
+			override: themeOverride,
+			candidates: [rootTheme, brandTheme, websiteTheme],
+		});
+
+		const overrideColor = pickRootProp<string>(regions, "primaryColor");
+		const overrideBg = pickRootProp<string>(regions, "backgroundColor");
+		const overrideHeading = pickRootProp<string>(regions, "headingFont");
+		const overrideBody = pickRootProp<string>(regions, "bodyFont");
+
+		const pageName = (page.name as string) || null;
+		const entityTitle =
+			(resolved.proposal as { name?: string })?.name ||
+			(resolved.form as { name?: string })?.name ||
+			(resolved.quiz as { title?: string })?.title ||
+			(resolved.agent as { name?: string })?.name;
+		const bodyMetaTitle = regions.find((r) => r.slot === "body")?.metaTitle;
+		const pageRootTitle = pickRootProp<string>(regions, "title");
+		const pageDescription =
+			regions.find((r) => r.slot === "body")?.metaDescription ??
+			pickRootProp<string>(regions, "description") ??
+			null;
+
+		return {
+			puckData: { root: { props: {} }, content: [] } as PuckData,
+			regions,
+			// Region-shell blocks (e.g. the header Navigation deriving the body's
+			// document sections) read the resolved entity graph from
+			// pageData.loaderData — the same surface Branch 1 exposes. Without it a
+			// header/footer block serverLoader gets ctx.loaderData=undefined and
+			// cannot see the body page, so a server-derived nav produced no items
+			// and the menu was client-only (vanished on stale tabs / narrow views).
+			loaderData: resolved,
+			website: {
+				slug: website.slug as string,
+				name: website.name as string,
+				organisation_id: website.organisation_id as string | null,
+				// header_settings carries the DB-driven header config (e.g.
+				// backdropBlur) the public shell applies — PublicTemplate reads
+				// pageData.website.header_settings.backdropBlur. Dropping it here
+				// silently kills the header blur even though the DB switch is set
+				// (the 2026-06-17 regression). Pass it through verbatim.
+				header_settings:
+					(website.header_settings as Record<string, unknown> | null) ?? null,
+			},
+			orgId:
+				(page.organisation_id as string) ??
+				null,
+			brand: {
+				primaryColor: overrideColor ?? primaryColor,
+				// Thread the org brand's dark surface (brand_background_color /
+				// brand_dark_color) when the page sets no explicit override — so
+				// dark-mode pages use the brand's real dark colour, not a
+				// primary-derived tint. Uses the org brand's real dark colour.
+				backgroundColor:
+					overrideBg ?? (brand.backgroundColor as string | null) ?? null,
+				lightSurface: (brand.lightSurface as string | null) ?? null,
+				darkSurface: (brand.darkSurface as string | null) ?? null,
+				accentColor: (brand.accentColor as string | null) ?? null,
+				secondaryColor: (brand.secondaryColor as string | null) ?? null,
+				mutedColor: (brand.mutedColor as string | null) ?? null,
+				headingFont: overrideHeading ?? headingFont,
+				bodyFont: overrideBody ?? bodyFont,
+				logo,
+				companyName: (brand.companyName as string) ?? null,
+				companyFriendlyName: (brand.companyFriendlyName as string) ?? null,
+				contactEmail: (brand.contactEmail as string) ?? null,
+					favicon: (brand.favicon as string) ?? null,
+			},
+			theme,
+			meta: {
+				title: composePageTitle({
+					pageMetaTitle: bodyMetaTitle,
+					templateTitle: (meta.title as string) || undefined,
+					websiteName: (website.name as string) || undefined,
+					pageName: pageName ?? pageRootTitle,
+					entityTitle: entityTitle || undefined,
+				}),
+				...(pageDescription ? { description: pageDescription } : {}),
+			},
+		};
+	}
+
+	const page = (resolved.page as Record<string, unknown>) ?? null;
+	const puckData = page
+		? extractPuckData(page) ?? EMPTY_PUCK_DATA
+		: ({ root: { props: {} }, content: [] } as PuckData);
+
+	const website = (resolved.website as Record<string, unknown>) ?? {};
+	const layoutSettings = (website.layout_settings ??
+		resolved.websiteDefaults) as { theme?: unknown } | null | undefined;
+	const websiteTheme =
+		layoutSettings && typeof layoutSettings.theme === "string"
+			? layoutSettings.theme
+			: undefined;
+
+	const pageRoot = (
+		puckData as { root?: { props?: Record<string, unknown> } } | null
+	)?.root?.props;
+	const rootTheme =
+		pageRoot && typeof pageRoot.theme === "string" ? pageRoot.theme : undefined;
+	const agent = (resolved.agent as Record<string, unknown>) ?? null;
+	// A GPT page's mode is the agent's dark_theme flag (the DB switch). It's the
+	// top candidate so the SSR :root matches the GPT shell's own scope (both
+	// derive from the same ai_agents.dark_theme) — flip the flag, the whole GPT
+	// + everything it frames flips. themeOverride (?theme=) still wins for an
+	// embedded render.
+	const agentTheme =
+		typeof agent?.dark_theme === "boolean"
+			? agent.dark_theme
+				? "dark"
+				: "light"
+			: undefined;
+	// themeOverride (?theme=) wins so a form/quiz framed in a GPT panel matches
+	// the host shell's light/dark scheme — this single-page branch serves
+	// form/quiz/proposal/gpt pages.
+	const { theme } = resolveThemeMode({
+		override: themeOverride,
+		candidates: [agentTheme, rootTheme, brandTheme, websiteTheme],
+	});
+	const orgId =
+		(page?.organisation_id as string) ??
+		(agent?.organisation_id as string) ??
+		null;
+
+	const overrideColor =
+		pageRoot &&
+		typeof pageRoot.primaryColor === "string" &&
+		pageRoot.primaryColor
+			? pageRoot.primaryColor
+			: null;
+	const overrideHeading =
+		pageRoot && typeof pageRoot.headingFont === "string" && pageRoot.headingFont
+			? pageRoot.headingFont
+			: null;
+	const overrideBody =
+		pageRoot && typeof pageRoot.bodyFont === "string" && pageRoot.bodyFont
+			? pageRoot.bodyFont
+			: null;
+
+	const screenMode = pageRoot?.screenMode as string | undefined;
+
+	const pageName = (page?.name as string) || null;
+	const entityTitle =
+		(resolved.form as { name?: string })?.name ||
+		(resolved.quiz as { title?: string })?.title ||
+		(resolved.proposal as { name?: string })?.name ||
+		(resolved.agent as { name?: string })?.name;
+	const entityDescription =
+		((resolved.form as Record<string, unknown>)?.description as string) ||
+		((resolved.quiz as Record<string, unknown>)?.description as string) ||
+		((resolved.proposal as Record<string, unknown>)?.description as string) ||
+		((resolved.agent as Record<string, unknown>)?.description as string);
+	const pageDescription =
+		(page?.meta_description as string) ||
+		entityDescription ||
+		(pageRoot?.description as string) ||
+		null;
+	const loaderDataPageMetaTitle = (
+		resolved.loaderData as { page?: { meta_title?: unknown } } | undefined
+	)?.page?.meta_title;
+	const pageMetaTitle =
+		(typeof loaderDataPageMetaTitle === "string" &&
+		loaderDataPageMetaTitle.trim()
+			? loaderDataPageMetaTitle.trim()
+			: typeof page?.meta_title === "string" && page.meta_title.trim()
+				? page.meta_title.trim()
+				: null) || null;
+
+	// Title is DERIVED via the single composer: meta_title is an explicit
+	// per-page OVERRIDE (priority 1), a curated resource template wins for
+	// resource surfaces (priority 2), otherwise <website>: <subject>. The
+	// /sign-in special-case is gone — pageMetaTitle now wins uniformly, so a
+	// sign-in page with a meta_title is honoured on every path, not just /sign-in.
+	const mergedMeta: Record<string, unknown> = {
+		...(pageDescription ? { description: pageDescription } : {}),
+		...meta,
+	};
+	mergedMeta.title = composePageTitle({
+		pageMetaTitle,
+		templateTitle: (meta.title as string) || undefined,
+		websiteName: (website.name as string) || undefined,
+		pageName: pageName ?? ((pageRoot?.title as string) || undefined),
+		entityTitle: entityTitle || undefined,
+	});
+
+	return {
+		puckData,
+		website: {
+			slug: website.slug as string,
+			name: website.name as string,
+			organisation_id: website.organisation_id as string | null,
+			// Pass header_settings through (DB-driven header blur etc.) — see the
+			// other two website assignments above. Dropping it kills the blur.
+			header_settings:
+				(website.header_settings as Record<string, unknown> | null) ?? null,
+		},
+		brand: {
+			primaryColor: overrideColor ?? primaryColor,
+			backgroundColor: (brand.backgroundColor as string | null) ?? null,
+			lightSurface: (brand.lightSurface as string | null) ?? null,
+			darkSurface: (brand.darkSurface as string | null) ?? null,
+			headingFont: overrideHeading ?? headingFont,
+			bodyFont: overrideBody ?? bodyFont,
+			logo,
+			companyName: (brand.companyName as string) ?? null,
+			companyFriendlyName: (brand.companyFriendlyName as string) ?? null,
+			contactEmail: (brand.contactEmail as string) ?? null,
+					favicon: (brand.favicon as string) ?? null,
+		},
+		theme,
+		orgId,
+		loaderData: resolved,
+		...(screenMode ? { fullScreen: screenMode === "full-screen" } : {}),
+		...(pageRoot?.standalone != null
+			? { standalone: pageRoot.standalone === false ? false : undefined }
+			: {}),
+		...(providers ? { providerKeys: providers } : {}),
+		meta: mergedMeta,
+	};
+}