Sync document head metadata on SPA navigations

packages/worker/client/client-router.tsx

@@ -1,7 +1,7 @@
 import { addEventListeners, type Handle } from 'remix/ui'
 import { createMultiMatcher } from 'remix/route-pattern/match'
 import { type AppLoaderData } from '#app/loader-data.ts'
-import { applyDocumentTitle } from './document-title.ts'
+import { applyDocumentHead } from './document-head.ts'
 import {
 	abortIntentPrefetch,
 	prefetchRouteOnIntent,
@@ -503,11 +503,12 @@ async function runNavigationWithLoader(
 			setPreloadedNavigationData(nextPath, loadedData)
 		}
 
-		// Document title lives outside the hydrated `#root` tree, so SSR
-		// `<title>` would otherwise stick across SPA navigations. Resolve from
-		// the shared registry (+ loader data for dynamic routes) here so every
-		// route gets a title update without per-page wiring.
-		applyDocumentTitle(destination.pathname, loadedData)
+		// Document head lives outside the hydrated `#root` tree, so SSR
+		// `<title>` / OG / canonical tags would otherwise stick across SPA
+		// navigations. Resolve from the shared registry (+ loader data for
+		// dynamic routes) here so every route stays in sync without per-page
+		// wiring.
+		applyDocumentHead(destination.pathname, loadedData)
 
 		if (options?.skipPushState) {
 			notify()
@@ -522,7 +523,7 @@ async function runNavigationWithLoader(
 		// current URL) have no href change to trigger a route's fallback
 		// refetch, so mark the destination stale for routes to consume.
 		markNavigationDataStale(nextPath)
-		applyDocumentTitle(destination.pathname)
+		applyDocumentHead(destination.pathname)
 		if (options?.skipPushState) {
 			notify()
 		} else {

packages/worker/client/document-head.ts

@@ -0,0 +1,133 @@
+import {
+	absolutizeDocumentHead,
+	DOCUMENT_HEAD_ATTR,
+	resolveDocumentHead,
+	type ResolvedDocumentHead,
+} from '#app/document-head.ts'
+import { type AppLoaderData } from '#app/loader-data.ts'
+
+export {
+	DEFAULT_DOCUMENT_TITLE,
+	NOT_FOUND_DOCUMENT_TITLE,
+	resolveDocumentHead,
+	resolveDocumentTitle,
+} from '#app/document-head.ts'
+
+function removeManagedHeadNodes(head: HTMLHeadElement) {
+	for (const node of head.querySelectorAll(`[${DOCUMENT_HEAD_ATTR}]`)) {
+		node.remove()
+	}
+}
+
+function appendMeta(
+	head: HTMLHeadElement,
+	key: string,
+	attrs: Record<string, string>,
+) {
+	const element = document.createElement('meta')
+	element.setAttribute(DOCUMENT_HEAD_ATTR, key)
+	for (const [name, value] of Object.entries(attrs)) {
+		element.setAttribute(name, value)
+	}
+	head.append(element)
+}
+
+function appendLink(
+	head: HTMLHeadElement,
+	key: string,
+	attrs: Record<string, string | undefined>,
+) {
+	const element = document.createElement('link')
+	element.setAttribute(DOCUMENT_HEAD_ATTR, key)
+	for (const [name, value] of Object.entries(attrs)) {
+		if (value === undefined) continue
+		element.setAttribute(name, value)
+	}
+	head.append(element)
+}
+
+function applyResolvedDocumentHead(resolved: ResolvedDocumentHead) {
+	const head = document.head
+	document.title = resolved.title
+
+	// Drop previous managed tags first so leaving a public page also clears
+	// stale OG/canonical/RSS nodes that no longer apply.
+	removeManagedHeadNodes(head)
+
+	if (resolved.og && resolved.canonicalUrl) {
+		appendMeta(head, 'og:title', {
+			property: 'og:title',
+			content: resolved.og.title,
+		})
+		appendMeta(head, 'og:description', {
+			property: 'og:description',
+			content: resolved.og.description,
+		})
+		appendMeta(head, 'og:image', {
+			property: 'og:image',
+			content: resolved.og.imageUrl,
+		})
+		appendMeta(head, 'og:type', {
+			property: 'og:type',
+			content: 'website',
+		})
+		appendMeta(head, 'og:url', {
+			property: 'og:url',
+			content: resolved.canonicalUrl,
+		})
+		appendMeta(head, 'twitter:card', {
+			name: 'twitter:card',
+			content: 'summary_large_image',
+		})
+		appendMeta(head, 'twitter:title', {
+			name: 'twitter:title',
+			content: resolved.og.title,
+		})
+		appendMeta(head, 'twitter:description', {
+			name: 'twitter:description',
+			content: resolved.og.description,
+		})
+		appendMeta(head, 'twitter:image', {
+			name: 'twitter:image',
+			content: resolved.og.imageUrl,
+		})
+		appendLink(head, 'canonical', {
+			rel: 'canonical',
+			href: resolved.canonicalUrl,
+		})
+	}
+
+	for (const [index, link] of (resolved.links ?? []).entries()) {
+		appendLink(head, `link:${index}`, {
+			rel: link.rel,
+			href: link.href,
+			type: link.type,
+			title: link.title,
+		})
+	}
+}
+
+/**
+ * Sync managed document head tags from the current route + optional loader
+ * data. Title, OG/Twitter, canonical, and registry links are updated/cleared
+ * together so SPA navigations do not leave the previous page's metadata behind.
+ */
+export function applyDocumentHead(
+	pathname: string,
+	loaderData?: Partial<AppLoaderData>,
+): void {
+	if (typeof document === 'undefined') return
+	const resolved = absolutizeDocumentHead(
+		resolveDocumentHead(pathname, loaderData),
+		window.location.origin,
+	)
+	applyResolvedDocumentHead(resolved)
+}
+
+/** @deprecated Prefer `applyDocumentHead` — titles are part of document head. */
+export function applyDocumentTitle(
+	pathname: string,
+	loaderData?: Partial<AppLoaderData>,
+): void {
+	applyDocumentHead(pathname, loaderData)
+}

packages/worker/client/document-title.ts

@@ -1,17 +1,11 @@
-import { resolveDocumentTitle } from '#app/document-title.ts'
-import { type AppLoaderData } from '#app/loader-data.ts'
-
+/**
+ * Back-compat title helpers. Prefer `#client/document-head.ts` for new work.
+ */
 export {
 	DEFAULT_DOCUMENT_TITLE,
 	NOT_FOUND_DOCUMENT_TITLE,
+	applyDocumentHead,
+	applyDocumentTitle,
+	resolveDocumentHead,
 	resolveDocumentTitle,
-} from '#app/document-title.ts'
-
-/** Sync `document.title` from the current route + optional loader data. */
-export function applyDocumentTitle(
-	pathname: string,
-	loaderData?: Partial<AppLoaderData>,
-): void {
-	if (typeof document === 'undefined') return
-	document.title = resolveDocumentTitle(pathname, loaderData)
-}
+} from './document-head.ts'

packages/worker/client/routes/community-detail.tsx

@@ -113,6 +113,7 @@ export async function communityDetailRouteLoader(
 			ok: true,
 			listingId,
 			name: payload.listing.name,
+			description: payload.listing.description,
 			forkPrompt: payload.forkPrompt,
 			loggedIn: payload.loggedIn,
 			viewerIsAdmin: payload.viewerIsAdmin,

packages/worker/client/routes/profile.tsx

@@ -93,6 +93,7 @@ export async function profileRouteLoader(
 			ok: true,
 			username: payload.profile.username,
 			displayName: payload.profile.displayName,
+			bio: payload.profile.bio,
 			isSelf: payload.isSelf,
 			loggedIn: payload.loggedIn,
 			isFollowing: payload.isFollowing,
@@ -146,6 +147,7 @@ export function ProfileRoute(handle: Handle) {
 				ok: true,
 				username: payload.profile.username,
 				displayName: payload.profile.displayName,
+				bio: payload.profile.bio,
 				isSelf: payload.isSelf,
 				loggedIn: payload.loggedIn,
 				isFollowing: payload.isFollowing,

packages/worker/src/app/document-head.node.test.ts

@@ -0,0 +1,130 @@
+import { expect, test } from 'vitest'
+import {
+	absolutizeDocumentHead,
+	DEFAULT_DOCUMENT_TITLE,
+	NOT_FOUND_DOCUMENT_TITLE,
+	resolveDocumentHead,
+	resolveDocumentTitle,
+} from './document-head.ts'
+
+test('resolveDocumentTitle returns static titles for known routes', () => {
+	expect(resolveDocumentTitle('/')).toBe(DEFAULT_DOCUMENT_TITLE)
+	expect(resolveDocumentTitle('/account')).toBe('Account')
+	expect(resolveDocumentTitle('/blog')).toBe('Blog')
+	expect(resolveDocumentTitle('/community')).toBe('Community packages')
+	expect(resolveDocumentTitle('/timeline')).toBe('Timeline')
+	expect(resolveDocumentTitle('/admin/users')).toBe('Admin users')
+	expect(resolveDocumentTitle('/privacy')).toBe('Privacy')
+})
+
+test('resolveDocumentHead attaches OG metadata for public registry pages', () => {
+	const home = resolveDocumentHead('/')
+	expect(home.og?.title).toBe("Kody — your assistant's home")
+	expect(home.og?.imagePath).toBe('/og/home.png')
+	expect(home.canonicalPath).toBe('/')
+
+	const login = resolveDocumentHead('/login')
+	expect(login.og?.title).toBe('Sign in — Kody')
+	expect(login.title).toBe(DEFAULT_DOCUMENT_TITLE)
+
+	const blog = resolveDocumentHead('/blog')
+	expect(blog.links).toEqual([
+		{
+			rel: 'alternate',
+			type: 'application/rss+xml',
+			title: 'Kody Blog RSS',
+			hrefPath: '/blog/rss.xml',
+		},
+	])
+})
+
+test('resolveDocumentHead derives dynamic OG from loader data', () => {
+	const blogPost = resolveDocumentHead('/blog/hello-world', {
+		blogPost: {
+			ok: true,
+			slug: 'hello-world',
+			title: 'Hello World',
+			date: '2026-01-01',
+			description: 'A post',
+			body: '# Hello',
+		},
+	})
+	expect(blogPost.title).toBe('Hello World — Kody Blog')
+	expect(blogPost.og).toEqual({
+		title: 'Hello World — Kody Blog',
+		description: 'A post',
+		imagePath: '/blog/hello-world/og.png',
+	})
+
+	const community = resolveDocumentHead('/community/listing-1', {
+		communityDetailShell: {
+			ok: true,
+			listingId: 'listing-1',
+			name: 'Calendar helper',
+			description: 'Helps with calendars.',
+			forkPrompt: 'fork',
+			loggedIn: false,
+			viewerIsAdmin: false,
+			trusted: false,
+			featured: false,
+			readmeContent: null,
+			starCount: 0,
+			starredByViewer: false,
+		},
+	})
+	expect(community.title).toBe('Calendar helper — Kody community package')
+	expect(community.og?.description).toBe('Helps with calendars.')
+	expect(community.og?.imagePath).toBe('/community/listing-1/og.png')
+
+	const publicProfile = resolveDocumentHead('/@kent', {
+		profileShell: {
+			ok: true,
+			username: 'kent',
+			displayName: 'Kent C. Dodds',
+			bio: 'Builder of things.',
+			isSelf: false,
+			loggedIn: false,
+			isFollowing: false,
+			visibility: 'public',
+		},
+	})
+	expect(publicProfile.title).toBe('Kent C. Dodds')
+	expect(publicProfile.og?.title).toBe('Kent C. Dodds (@kent) — Kody')
+	expect(publicProfile.og?.description).toBe('Builder of things.')
+
+	const privateProfile = resolveDocumentHead('/@kent', {
+		profileShell: {
+			ok: true,
+			username: 'kent',
+			displayName: 'Kent C. Dodds',
+			bio: 'Hidden bio',
+			isSelf: false,
+			loggedIn: false,
+			isFollowing: false,
+			visibility: 'private',
+		},
+	})
+	expect(privateProfile.title).toBe('Kent C. Dodds')
+	expect(privateProfile.og).toBeUndefined()
+})
+
+test('resolveDocumentHead falls back when dynamic loader data is missing', () => {
+	expect(resolveDocumentHead('/blog/hello-world')).toEqual({ title: 'Blog' })
+	expect(resolveDocumentHead('/community/listing-1')).toEqual({
+		title: 'Community packages',
+	})
+	expect(resolveDocumentHead('/@kent').title).toBe('@kent')
+	expect(resolveDocumentHead('/this-route-does-not-exist').title).toBe(
+		NOT_FOUND_DOCUMENT_TITLE,
+	)
+})
+
+test('absolutizeDocumentHead expands origin-relative paths', () => {
+	const resolved = absolutizeDocumentHead(
+		resolveDocumentHead('/blog', undefined),
+		'https://heykody.dev',
+	)
+	expect(resolved.canonicalUrl).toBe('https://heykody.dev/blog')
+	expect(resolved.og?.imageUrl).toBe('https://heykody.dev/og/blog.png')
+	expect(resolved.links?.[0]?.href).toBe('https://heykody.dev/blog/rss.xml')
+})