Remix 3 SSR: server-rendered, hydrated SPA for all HTML pages

docs/contributing/frames.md

@@ -0,0 +1,66 @@
+# Remix frames
+
+Remix 3 `<Frame>` lets a page embed a server-rendered HTML fragment and reload
+it without full navigation (`frame.reload()`). Kody routes frame fetches through
+the same handler as the parent page so auth and user scoping stay consistent.
+
+## Naming
+
+- **`name`** (client): app-wide unique frame id passed to `<Frame name={...}>`.
+  Register it once in `frame-registry.ts` via `registerFrame(name, ...)`.
+  Duplicate names throw at module load.
+- **`src`** (client): the page URL that serves the fragment. Always build with
+  `routes.<routeKey>.href(...)` (the `kody-custom/no-literal-frame-src` lint
+  rule enforces this).
+
+## Registry and handlers
+
+1. Add `packages/worker/src/app/frames/<name>.ts` calling `registerFrame` with
+   `routePathname: routes.<key>.href()` and a `render` function that returns
+   fragment HTML (usually `renderToString` of a server component).
+2. Import the module from `frame-registrations.ts`.
+3. In the route handler, before `renderAppPage`:
+
+```ts
+const frameResponse = await handleFrameRequest(request, env, routes.foo.href())
+if (frameResponse) return frameResponse
+```
+
+`handleFrameRequest` checks `x-remix-target` (see `frame-constants.ts`). When
+the header matches a frame registered for that pathname, it returns bare
+fragment HTML with `Cache-Control: no-store`. Otherwise it returns `null` and
+the handler falls through to the full page.
+
+SSR inlines frames via the same registry: `ssr-render.tsx` calls
+`resolveRegisteredFrameHtml` inside `resolveFrame`. Unknown targets throw during
+SSR (fail loud in dev).
+
+## Target header contract
+
+- Constant: `REMIX_FRAME_TARGET_HEADER` (`x-remix-target`) in
+  `frame-constants.ts`.
+- Client `entry.tsx` `resolveFrame` sets the header to the frame `name` when
+  fetching `src`.
+- Server `handleFrameRequest` reads the header and selects the registered frame.
+
+## Auth scoping
+
+Frames that render user-scoped data must derive auth from the **same `Request`**
+as the full page — use `loadResolvedRequestAuth`, `readAuthenticatedAppUser`, or
+the same loader helpers the page handler uses. Never read user state from global
+module variables.
+
+## Client typed routes
+
+Client code imports `routes` from `#app/routes.ts` (included in
+`tsconfig-client.json`). The route table is isomorphic plain data from
+`remix/routes`; esbuild bundles it via the root `package.json` `imports` map.
+
+Example (`client/routes/community.tsx`):
+
+```tsx
+<Frame name={COMMUNITY_LISTINGS_TARGET} src={frameSrc} />
+```
+
+`COMMUNITY_LISTINGS_TARGET` lives in `community-frame-constants.ts` alongside
+the server-side `registerFrame` call in `frames/community-listings.ts`.

docs/contributing/index.md

@@ -9,7 +9,7 @@ style, tests, MCP capabilities, and runtime architecture.
 - [Optional Cloudflare offerings](./cloudflare-offerings.md)
 - [Setup](./setup.md), [code style](./code-style.md),
   [testing](./testing-principles.md)
-- [Remix skills](./remix.md)
+- [Remix skills](./remix.md), [frames](./frames.md)
 - [Packages and manifests](./packages-and-manifests.md)
 - [Community packages](./community-packages.md)
 - [External package invocation API](./package-invocation-api.md)

docs/contributing/remix.md

@@ -9,7 +9,9 @@ The repo-local skill lives at:
 
 Load that skill before changing Remix routes, controllers, middleware, data
 access, validation, auth, sessions, file uploads, server setup, UI components,
-hydration, navigation, or tests.
+hydration, navigation, frames, or tests.
+
+For `<Frame>` partial reloads, see [frames](./frames.md).
 
 `npx remix@next new <app>` copies this skill from the Remix CLI bootstrap
 template. The CLI does not expose a standalone `remix skills install` command.

e2e/admin-rbac.spec.ts

@@ -59,6 +59,25 @@ test('admin RBAC controls access, role assignment, and privacy boundaries', asyn
 	await expect(
 		page.getByRole('link', { name: 'Admin', exact: true }),
 	).toBeVisible()
+
+	await page.evaluate(() => {
+		;(window as Window & { __e2eMarker?: boolean }).__e2eMarker = true
+	})
+	await page.getByRole('link', { name: 'Admin', exact: true }).click()
+	await expect(page).toHaveURL(/\/admin\/users\/?$/)
+	await expect(page.getByRole('heading', { name: 'Admin users' })).toBeVisible()
+	// The first user is auto-selected, so the email can render in both the
+	// list and the detail panel — assert on the list entry specifically.
+	await expect(
+		page.getByRole('button', { name: adminUser.username }),
+	).toBeVisible()
+	await expect(page.getByText('Unable to load admin users.')).toHaveCount(0)
+	expect(
+		await page.evaluate(
+			() => (window as Window & { __e2eMarker?: boolean }).__e2eMarker,
+		),
+	).toBe(true)
+
 	await page.goto('/admin/users?pageSize=100')
 	await expect(page.getByRole('heading', { name: 'Admin users' })).toBeVisible()
 	await expect(page.getByText(memberUser.email)).toBeVisible()

e2e/community-frames.spec.ts

@@ -0,0 +1,123 @@
+import { expect, test } from '@playwright/test'
+import { ensurePrimaryUserExists, primaryTestUser } from './auth-test-user.ts'
+import {
+	seedCommunityForkInE2eDatabase,
+	seedCommunityListingInE2eDatabase,
+	updateCommunityListingDescriptionInE2eDatabase,
+} from './d1-utils.ts'
+
+const staleListing = {
+	listingId: 'e2e-frame-stale-listing',
+	name: '@kody/frame-stale-package',
+	description: 'Original description before back-navigation.',
+	tags: ['stale', 'frame'],
+}
+
+test('community listings frame reloads fresh data on back-navigation', async ({
+	page,
+	request,
+}) => {
+	await ensurePrimaryUserExists(request)
+	await seedCommunityListingInE2eDatabase({
+		...staleListing,
+		ownerEmail: primaryTestUser.email,
+	})
+
+	await page.goto('/community')
+	await expect(
+		page.getByTestId(`community-listing-description-${staleListing.listingId}`),
+	).toHaveText(staleListing.description)
+
+	await page.evaluate(() => {
+		;(window as Window & { __e2eStaleMarker?: boolean }).__e2eStaleMarker = true
+	})
+
+	await page.getByRole('link', { name: staleListing.name }).click()
+	await expect(page).toHaveURL(
+		new RegExp(`/community/${staleListing.listingId}$`),
+	)
+
+	const updatedDescription = 'Updated description after detail visit.'
+	updateCommunityListingDescriptionInE2eDatabase({
+		listingId: staleListing.listingId,
+		description: updatedDescription,
+	})
+
+	const frameReload = page.waitForResponse(
+		(response) =>
+			response.request().headers()['x-remix-target'] === 'community-listings' &&
+			response.url().includes('/community') &&
+			response.status() === 200,
+	)
+
+	await page.getByRole('link', { name: 'Community packages' }).click()
+	await expect(page).toHaveURL(/\/community$/)
+	await frameReload
+
+	await expect(
+		page.getByTestId(`community-listing-description-${staleListing.listingId}`),
+	).toHaveText(updatedDescription)
+	expect(
+		await page.evaluate(
+			() =>
+				(window as Window & { __e2eStaleMarker?: boolean }).__e2eStaleMarker,
+		),
+	).toBe(true)
+})
+
+test('community detail frame reloads fresh fork counts on return navigation', async ({
+	page,
+	request,
+}) => {
+	await ensurePrimaryUserExists(request)
+	await seedCommunityListingInE2eDatabase({
+		...staleListing,
+		listingId: 'e2e-frame-detail-stale-listing',
+		name: '@kody/frame-detail-stale-package',
+		ownerEmail: primaryTestUser.email,
+	})
+
+	const listingId = 'e2e-frame-detail-stale-listing'
+
+	await page.goto(`/community/${listingId}`)
+	const initialForkCount = Number(
+		(await page.getByTestId('community-detail-forks').textContent()) ?? '0',
+	)
+
+	await page.evaluate(() => {
+		;(window as Window & { __e2eDetailMarker?: boolean }).__e2eDetailMarker =
+			true
+	})
+
+	await page.getByRole('link', { name: 'Community packages' }).click()
+	await expect(page).toHaveURL(/\/community$/)
+
+	await seedCommunityForkInE2eDatabase({
+		listingId,
+		forkerEmail: primaryTestUser.email,
+		forkId: `fork-${listingId}-${Date.now()}`,
+	})
+
+	const frameReload = page.waitForResponse(
+		(response) =>
+			response.request().headers()['x-remix-target'] === 'community-detail' &&
+			response.url().includes(`/community/${listingId}`) &&
+			response.status() === 200,
+	)
+
+	await page
+		.getByRole('link', { name: '@kody/frame-detail-stale-package' })
+		.click()
+	await expect(page).toHaveURL(new RegExp(`/community/${listingId}$`))
+	await frameReload
+
+	await expect(page.getByTestId('community-detail-forks')).toHaveText(
+		String(initialForkCount + 1),
+	)
+	expect(
+		await page.evaluate(
+			() =>
+				(window as Window & { __e2eDetailMarker?: boolean }).__e2eDetailMarker,
+		),
+	).toBe(true)
+})