@jasonshimmy/vite-plugin-cer-app 0.1.2 → 0.1.4

package/docs/data-loading.md

@@ -67,7 +67,7 @@ interface PageLoaderContext<P extends Record<string, string>> {
 
 1. Browser receives the full HTML — content is immediately visible via Declarative Shadow DOM before any JS runs
 2. Client JS boots; `usePageData()` reads `window.__CER_DATA__` and returns the hydrated values
-3. The value is cleared after the first read so subsequent client-side navigations trigger a fresh fetch
+3. After the initial `router.replace()` in `app/app.ts` completes, `window.__CER_DATA__` is deleted so subsequent client-side navigations trigger a fresh fetch instead of reusing stale server data
 4. Components that received SSR data skip their `useOnConnected` fetch — no duplicate request
 
 ---
@@ -164,3 +164,47 @@ export const loader: PageLoader<
   return { user: await fetchUser(params.id), posts: await fetchPosts(params.id) }
 }
 ```
+
+---
+
+## Multi-mode data loading (SPA fallback)
+
+When building a page that needs to work in **all three modes** — SSR/SSG (with a `loader`) and SPA (no server, no loader) — use the following pattern:
+
+1. In SSR/SSG, the server runs `loader` and injects the data via `window.__CER_DATA__`. `usePageData()` returns it immediately; `useOnConnected` sees `ssrData` and skips the client fetch.
+2. In SPA mode there is no server, so `ssrData` is `null`. The client tries the API first, then falls back to a direct module import.
+
+```ts
+// app/pages/blog/index.ts
+component('page-blog-index', () => {
+  const ssrData = usePageData<{ posts: Post[] }>()
+  const posts = ref<Post[]>(ssrData?.posts ?? [])
+
+  useOnConnected(async () => {
+    if (ssrData) return  // SSR/SSG: already hydrated, skip the fetch
+
+    // SPA: try the API server first
+    try {
+      const r = await fetch('/api/posts')
+      if (r.ok) {
+        posts.value = await r.json()
+        return
+      }
+    } catch { /* no API server in static preview */ }
+
+    // SPA static fallback: import data directly from source
+    const { posts: staticPosts } = await import('../data/posts')
+    posts.value = staticPosts
+  })
+
+  return html`<ul>${posts.value.map(p => html`<li>${p.title}</li>`)}</ul>`
+})
+
+// loader runs in SSR and SSG only
+export const loader = async () => {
+  const posts = await fetch('/api/posts').then(r => r.json())
+  return { posts }
+}
+```
+
+The key rule: **always check `ssrData` before fetching on the client**. This prevents a redundant network request when the data was already serialized by the server.

package/docs/getting-started.md

@@ -135,40 +135,105 @@ component('layout-default', () => {
 
 ### 7. Create `app/app.ts` (auto-generated if absent)
 
-The framework auto-generates this file when you scaffold a new project. It includes the runtime CSS, DOM JIT CSS for light-DOM utility classes, and the router bootstrap:
+The framework generates this file when you scaffold a new project. It bootstraps the router, registers all auto-discovered components, runs plugins, and mounts the app:
 
 ```ts
 // app/app.ts
 import '@jasonshimmy/custom-elements-runtime/css'
 import 'virtual:cer-components'
 import routes from 'virtual:cer-routes'
+import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
-import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
+import { hasLoading, loadingTag } from 'virtual:cer-loading'
+import { hasError, errorTag } from 'virtual:cer-error'
+import {
+  component, ref, provide,
+  useOnConnected, useOnDisconnected,
+  registerBuiltinComponents,
+} from '@jasonshimmy/custom-elements-runtime'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
 import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
 import { createDOMJITCSS } from '@jasonshimmy/custom-elements-runtime/dom-jit-css'
 
 registerBuiltinComponents()
-
-// Enable JIT CSS globally for all Shadow DOM components.
 enableJITCSS()
 
 const router = initRouter({ routes })
 
+const isNavigating = ref(false)
+const currentError = ref(null)
+;(globalThis as any).resetError = () => {
+  currentError.value = null
+  router.replace(router.getCurrent().path)
+}
+
+const _push = router.push.bind(router)
+const _replace = router.replace.bind(router)
+router.push = async (path) => {
+  isNavigating.value = true; currentError.value = null
+  try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+router.replace = async (path) => {
+  isNavigating.value = true; currentError.value = null
+  try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+
+// _pluginProvides is populated by plugin setup and forwarded into the component
+// context tree via provide() inside cer-layout-view so inject() works in all modes.
+// Also exposed on globalThis for the SSG timing edge case — see docs/plugins.md.
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
+component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) { provide(key, value) }
+
+  const current = ref(router.getCurrent())
+  let unsub: (() => void) | undefined
+  useOnConnected(() => { unsub = router.subscribe((s) => { current.value = s }) })
+  useOnDisconnected(() => { unsub?.(); unsub = undefined })
+
+  if (currentError.value !== null) {
+    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
+  }
+  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
+
+  const matched = router.matchRoute(current.value.path)
+  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'
+  const layoutTag = (layouts as Record<string, string>)[layoutName]
+  const routerView = { tag: 'router-view', props: {}, children: [] }
+  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView
+})
+
+// Plugins run AFTER cer-layout-view is defined so provide() calls from plugins
+// are forwarded into the component tree on the very first render.
 for (const plugin of plugins ?? []) {
   if (plugin && typeof plugin.setup === 'function') {
-    await plugin.setup({ router, provide: (key, value) => { globalThis[key] = value }, config: {} })
+    await plugin.setup({ router, provide: (key, value) => { _pluginProvides.set(key, value) }, config: {} })
   }
 }
 
+// Pre-load the current page's route chunk AFTER plugins run.
+// This ensures cer-layout-view's first render (and its provide() calls) completes
+// before page component modules are imported and their renders are scheduled.
 if (typeof window !== 'undefined') {
-  await router.replace(window.location.pathname + window.location.search + window.location.hash)
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+  delete (globalThis as any).__CER_DATA__
   createDOMJITCSS().mount()
 }
 
 export { router }
 ```
 
+> **Note:** Do not move the plugin loop before `component('cer-layout-view', …)`. The layout component must be defined first so that when plugins call `app.provide()`, the values are available to the component tree from the very first render. See [Plugins](plugins.md) for details.
+
 ---
 
 ## Running the dev server

package/docs/head-management.md

@@ -9,15 +9,21 @@ The `useHead()` composable manages `<title>`, `<meta>`, `<link>`, `<script>`, an
 
 ## Import
 
+`useHead` is **not** auto-imported. You must explicitly import it in every file that uses it:
+
 ```ts
 import { useHead } from '@jasonshimmy/vite-plugin-cer-app/composables'
 ```
 
+Unlike `component`, `html`, `ref`, and other runtime APIs (which are injected automatically when `autoImports.runtime` is enabled), `useHead` comes from the framework package and requires an explicit import statement.
+
 ---
 
 ## Basic usage
 
 ```ts
+import { useHead } from '@jasonshimmy/vite-plugin-cer-app/composables'
+
 component('page-about', () => {
   useHead({
     title: 'About Us',

package/docs/plugins.md

@@ -120,6 +120,31 @@ export default {
 
 ---
 
+## SSG and `inject()`
+
+In SSG mode there is a timing subtlety: the router loads a page chunk and renders it before `<cer-layout-view>` has called `provide()`. This means `inject()` may return `undefined` on the first render in SSG — even though the plugin ran and called `app.provide()` correctly.
+
+To write pages that work correctly in **all three modes** (SPA, SSR, SSG), use `globalThis.__cerPluginProvides` as a synchronous fallback when `inject()` returns `undefined`:
+
+```ts
+// app/pages/dashboard.ts
+component('page-dashboard', () => {
+  // inject() resolves correctly in SPA and SSR modes.
+  // In SSG the page chunk may render before cer-layout-view calls provide(),
+  // so fall back to the global map that app/app.ts populates before any render.
+  const pluginProvides = (globalThis as any).__cerPluginProvides as Map<string, unknown> | undefined
+  const store = inject<Store>('store') ?? pluginProvides?.get('store') as Store | undefined
+
+  if (!store) return html`<p>Loading…</p>`
+
+  return html`<p>Count: ${store.state.count}</p>`
+})
+```
+
+The `__cerPluginProvides` map is written by the bootstrapped `app/app.ts` before any route is rendered, so it is always available as a synchronous fallback regardless of render order.
+
+---
+
 ## Virtual module
 
 The sorted plugin list is available via `virtual:cer-plugins`:

package/docs/routing.md

@@ -13,15 +13,17 @@ Routes are automatically derived from files in the `app/pages/` directory. No ma
 | `app/pages/blog/index.ts` | `/blog` | `page-blog-index` |
 | `app/pages/blog/[slug].ts` | `/blog/:slug` | `page-blog-slug` |
 | `app/pages/users/[id]/edit.ts` | `/users/:id/edit` | `page-users-id-edit` |
-| `app/pages/[...all].ts` | `/*` (catch-all) | `page-all` |
+| `app/pages/404.ts` | `/:all*` (catch-all) | `page-404` |
+| `app/pages/[...all].ts` | `/:all*` (catch-all) | `page-all` |
 | `app/pages/(auth)/login.ts` | `/login` | `page-login` |
 
 ### Rules
 
 1. **`index.ts`** — The `index` segment is stripped: `blog/index.ts` → `/blog`
 2. **`[param]`** — Dynamic segment: `[slug].ts` → `:slug`
-3. **`[...rest]`** — Catch-all segment: `[...all].ts` → `/*`
-4. **`(group)/`** — Route group: directory name stripped from path, not from tag name
+3. **`[...rest]`** — Catch-all segment: `[...all].ts` → `/:all*`
+4. **`404.ts`** — Special shorthand: treated as a catch-all (`/:all*`) — the conventional 404 page
+5. **`(group)/`** — Route group: directory name stripped from path, not from tag name
 
 ---
 
@@ -57,9 +59,27 @@ The `:slug` param is populated by the router and passed as a prop to the compone
 
 ---
 
-## Catch-all routes
+## Catch-all routes and 404 pages
 
-A file named `[...anything].ts` matches any path not matched by a more specific route:
+There are two equivalent ways to define a catch-all / 404 page:
+
+**Option A — `404.ts` (recommended shorthand)**
+
+```ts
+// app/pages/404.ts
+component('page-404', () => {
+  return html`
+    <div>
+      <h1>404 — Page not found</h1>
+      <p><a href="/">← Back home</a></p>
+    </div>
+  `
+})
+```
+
+The framework special-cases `404.ts` and automatically registers it as the catch-all route (`/:all*`). This is the conventional name and is the approach used by the kitchen-sink example.
+
+**Option B — `[...name].ts` explicit catch-all**
 
 ```ts
 // app/pages/[...all].ts
@@ -68,7 +88,7 @@ component('page-all', () => {
 })
 ```
 
-This also serves as the 404 page. The catch-all segment matches `/*`.
+Both produce the same route (`/:all*`) and either form works. Use `404.ts` for clarity.
 
 ---
 
@@ -166,6 +186,28 @@ Within each tier, routes are sorted alphabetically.
 
 ---
 
+## Navigation with `<router-link>`
+
+`initRouter()` registers a `<router-link>` built-in custom element that renders a client-side navigation link. Use it anywhere in your pages or layouts instead of a plain `<a>` tag when you want the router to handle the navigation (no full page reload):
+
+```ts
+// app/layouts/default.ts
+component('layout-default', () => {
+  return html`
+    <nav>
+      <router-link to="/">Home</router-link>
+      <router-link to="/about">About</router-link>
+      <router-link to="/blog">Blog</router-link>
+    </nav>
+    <main><slot></slot></main>
+  `
+})
+```
+
+`<router-link to="/path">` calls `router.push(path)` on click, which triggers the wrapped navigation handler (loading state, error capture, etc.). Use a plain `<a href="/path">` when you need a standard browser navigation or an external link.
+
+---
+
 ## Virtual module
 
 The route list is exposed as the virtual module `virtual:cer-routes`, which you can import directly in `app/app.ts`:

package/e2e/cypress/e2e/api.cy.ts

@@ -0,0 +1,81 @@
+/**
+ * Server API route tests.
+ *
+ * Only run in SSR mode — SSG and SPA don't have live API endpoints.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+if (mode !== 'ssr') {
+  describe('Server API routes', () => {
+    it('skipped — only tested in SSR mode', () => {
+      cy.log(`API tests skipped in ${mode} mode`)
+    })
+  })
+} else {
+  describe('Server API routes (SSR mode)', () => {
+    context('GET /api/health', () => {
+      it('returns 200 with status ok', () => {
+        cy.request('/api/health').then((response) => {
+          expect(response.status).to.eq(200)
+          expect(response.body.status).to.eq('ok')
+          expect(response.body.service).to.eq('kitchen-sink')
+        })
+      })
+    })
+
+    context('GET /api/posts', () => {
+      it('returns 200 with array of posts', () => {
+        cy.request('/api/posts').then((response) => {
+          expect(response.status).to.eq(200)
+          expect(response.body).to.be.an('array')
+          expect(response.body.length).to.be.greaterThan(0)
+        })
+      })
+
+      it('first post has slug, title, excerpt, body', () => {
+        cy.request('/api/posts').then((response) => {
+          const post = response.body[0]
+          expect(post).to.have.property('slug')
+          expect(post).to.have.property('title')
+          expect(post).to.have.property('excerpt')
+          expect(post).to.have.property('body')
+        })
+      })
+
+      it('contains first-post and second-post', () => {
+        cy.request('/api/posts').then((response) => {
+          const slugs = response.body.map((p: any) => p.slug)
+          expect(slugs).to.include('first-post')
+          expect(slugs).to.include('second-post')
+        })
+      })
+    })
+
+    context('GET /api/posts/:slug', () => {
+      it('returns the correct post for first-post', () => {
+        cy.request('/api/posts/first-post').then((response) => {
+          expect(response.status).to.eq(200)
+          expect(response.body.slug).to.eq('first-post')
+          expect(response.body.title).to.eq('First Post')
+          expect(response.body.body).to.include('First post body content')
+        })
+      })
+
+      it('returns the correct post for second-post', () => {
+        cy.request('/api/posts/second-post').then((response) => {
+          expect(response.status).to.eq(200)
+          expect(response.body.slug).to.eq('second-post')
+          expect(response.body.title).to.eq('Second Post')
+        })
+      })
+
+      it('returns 404 for unknown slug', () => {
+        cy.request({ url: '/api/posts/not-a-post', failOnStatusCode: false }).then((response) => {
+          expect(response.status).to.eq(404)
+          expect(response.body).to.have.property('error')
+        })
+      })
+    })
+  })
+}

package/e2e/cypress/e2e/data.cy.ts

@@ -0,0 +1,111 @@
+/**
+ * Data loading tests — page loaders, usePageData, dynamic params.
+ *
+ * Blog data is loaded via a page `loader` in SSR/SSG mode and falls back to
+ * client-side fetch in SPA mode. Item IDs come from route params (all modes).
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+describe('Blog list — data loader', () => {
+  // In SSR/SSG the loader runs server-side; data is embedded in HTML.
+  // In SPA the page fetches from /api/posts on mount.
+
+  if (mode !== 'spa') {
+    it('renders pre-loaded posts in initial HTML (SSR/SSG)', () => {
+      cy.request('/blog').then((response) => {
+        expect(response.body).to.include('First Post')
+        expect(response.body).to.include('Second Post')
+      })
+    })
+  }
+
+  it('blog list renders at least 2 items after hydration', () => {
+    cy.visit('/blog')
+    cy.get('[data-cy=blog-list]').should('exist')
+    // Items appear after hydration (SSR) or fetch (SPA)
+    cy.get('[data-cy=blog-item]', { timeout: 8000 }).should('have.length.at.least', 2)
+  })
+
+  it('First Post link is present', () => {
+    cy.visit('/blog')
+    cy.get('[data-cy=blog-item]').should('have.length.at.least', 1)
+    cy.get('[data-cy="blog-link-first-post"]').should('exist')
+  })
+
+  it('Second Post link is present', () => {
+    cy.visit('/blog')
+    cy.get('[data-cy="blog-link-second-post"]').should('exist')
+  })
+})
+
+describe('Blog detail — dynamic route with loader', () => {
+  it('renders "First Post" title for /blog/first-post', () => {
+    cy.visit('/blog/first-post')
+    cy.get('[data-cy=post-title]').should('contain', 'First Post')
+  })
+
+  it('renders "Second Post" title for /blog/second-post', () => {
+    cy.visit('/blog/second-post')
+    cy.get('[data-cy=post-title]').should('contain', 'Second Post')
+  })
+
+  it('shows the correct slug in the post', () => {
+    cy.visit('/blog/first-post')
+    cy.get('[data-cy=post-slug]').should('contain', 'first-post')
+  })
+
+  if (mode !== 'spa') {
+    it('body content is pre-rendered in initial HTML (SSR/SSG)', () => {
+      cy.request('/blog/first-post').then((response) => {
+        expect(response.body).to.include('First post body content')
+      })
+    })
+
+    it('second post body is pre-rendered (SSR/SSG)', () => {
+      cy.request('/blog/second-post').then((response) => {
+        expect(response.body).to.include('Second post body content')
+      })
+    })
+  }
+
+  it('renders the body content after hydration', () => {
+    cy.visit('/blog/first-post')
+    cy.get('[data-cy=post-body]', { timeout: 8000 }).should('contain', 'First post body content')
+  })
+
+  it('back link navigates to /blog', () => {
+    cy.visit('/blog/first-post')
+    cy.get('[data-cy=post-back]').first().click({ force: true })
+    cy.url().should('include', '/blog')
+    cy.get('[data-cy=blog-heading]').should('contain', 'Blog')
+  })
+})
+
+describe('Item detail — route params via useProps', () => {
+  it('shows item ID 1 for /items/1', () => {
+    cy.visit('/items/1')
+    cy.get('[data-cy=item-id]').should('contain', '1')
+  })
+
+  it('shows item ID 2 for /items/2', () => {
+    cy.visit('/items/2')
+    cy.get('[data-cy=item-id]').should('contain', '2')
+  })
+
+  it('shows correct ID for client-side nav to /items/2 from /items/1', () => {
+    cy.visit('/items/1')
+    cy.get('[data-cy=item-id]').should('contain', '1')
+    // Navigate via browser history pushState via the router
+    cy.window().then((win) => {
+      // Trigger client-side navigation
+      const router = (win as any).__cer_router__ ?? (win as any).router
+      if (router?.push) {
+        router.push('/items/2')
+      }
+    })
+    // Fallback: visit directly
+    cy.visit('/items/2')
+    cy.get('[data-cy=item-id]').should('contain', '2')
+  })
+})

package/e2e/cypress/e2e/fouc.cy.ts

@@ -0,0 +1,65 @@
+/**
+ * FOUC (Flash of Unstyled Content) tests.
+ *
+ * For SSR and SSG modes, validates that the server-rendered HTML:
+ * 1. Contains Declarative Shadow DOM templates
+ * 2. Each shadow template has its own embedded <style> block
+ * 3. Shadow DOM styles are NOT hoisted to <head> (which would break encapsulation)
+ * 4. The loading indicator is NOT present in the initial HTML
+ * 5. cer-layout-view has pre-rendered content (not empty)
+ *
+ * FOUC occurs when styles are missing from shadow roots on first parse.
+ * These checks verify the DSD structure prevents FOUC before JS hydrates.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+// Routes to check for FOUC — all pre-renderable routes
+const ROUTES_TO_CHECK = [
+  '/',
+  '/about',
+  '/counter',
+  '/head',
+  '/blog',
+  '/blog/first-post',
+  '/blog/second-post',
+  '/items/1',
+  '/items/2',
+  '/login',
+]
+
+describe('FOUC prevention', () => {
+  before(() => {
+    if (mode === 'spa') {
+      cy.log('Skipping FOUC tests in SPA mode (no server-side rendering)')
+    }
+  })
+
+  if (mode === 'spa') return
+
+  ROUTES_TO_CHECK.forEach((path) => {
+    it(`${path}: shadow templates have embedded styles (no FOUC)`, () => {
+      cy.assertNoDSD_FOUC(path)
+    })
+  })
+
+  it('DSD polyfill is placed after </cer-layout-view>, not inside it', () => {
+    cy.request('/').then((response) => {
+      const html: string = response.body
+      const clvEnd = html.lastIndexOf('</cer-layout-view>')
+      const polyfillIdx = html.indexOf('attachShadow')
+      if (polyfillIdx >= 0) {
+        expect(polyfillIdx, 'DSD polyfill must come AFTER </cer-layout-view>').to.be.greaterThan(clvEnd)
+      }
+    })
+  })
+
+  it('home page: loading indicator is not visible on first paint', () => {
+    // The loading component (page-loading) should never appear in initial HTML.
+    // If it does, it means isNavigating was true during SSR — a FOUC bug.
+    cy.request('/').then((response) => {
+      expect(response.body).not.to.include('page-loading')
+      expect(response.body).not.to.include('data-cy="loading-indicator"')
+    })
+  })
+})

package/e2e/cypress/e2e/head.cy.ts

@@ -0,0 +1,89 @@
+/**
+ * useHead() tests — verifies document title and meta tags are set correctly.
+ *
+ * In SSR/SSG: tags should be in the initial HTML (server-side injection).
+ * In all modes: tags should be set after client-side hydration.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+describe('useHead() — document title', () => {
+  it('sets title to "Home — Kitchen Sink" on home page', () => {
+    cy.visit('/')
+    cy.title().should('eq', 'Home — Kitchen Sink')
+  })
+
+  it('sets title to "About — Kitchen Sink" on about page', () => {
+    cy.visit('/about')
+    cy.title().should('eq', 'About — Kitchen Sink')
+  })
+
+  it('sets title to "Head Test — Kitchen Sink" on head page', () => {
+    cy.visit('/head')
+    cy.title().should('eq', 'Head Test — Kitchen Sink')
+  })
+
+  it('sets title to "Blog — Kitchen Sink" on blog list page', () => {
+    cy.visit('/blog')
+    cy.title().should('eq', 'Blog — Kitchen Sink')
+  })
+
+  it('updates title when navigating between pages', () => {
+    cy.visit('/')
+    cy.title().should('eq', 'Home — Kitchen Sink')
+    cy.get('[data-cy=nav-about]').first().click({ force: true })
+    cy.title().should('eq', 'About — Kitchen Sink')
+    cy.get('[data-cy=about-back]').first().click({ force: true })
+    cy.title().should('eq', 'Home — Kitchen Sink')
+  })
+})
+
+describe('useHead() — meta tags', () => {
+  it('sets meta description on home page', () => {
+    cy.visit('/')
+    cy.get('meta[name="description"]').should('have.attr', 'content', 'Kitchen sink test app.')
+  })
+
+  it('sets meta description on about page', () => {
+    cy.visit('/about')
+    cy.get('meta[name="description"]').should('have.attr', 'content', 'About the kitchen sink test app.')
+  })
+
+  it('sets meta description on head test page', () => {
+    cy.visit('/head')
+    cy.get('meta[name="description"]').should('have.attr', 'content', 'A test page for useHead().')
+  })
+
+  it('sets og:title meta on head test page', () => {
+    cy.visit('/head')
+    cy.get('meta[property="og:title"]').should('have.attr', 'content', 'Head Test')
+  })
+})
+
+if (mode !== 'spa') {
+  describe('useHead() — server-side injection (SSR/SSG)', () => {
+    it('home page title is in the initial HTML', () => {
+      cy.request('/').then((response) => {
+        expect(response.body).to.include('<title>Home — Kitchen Sink</title>')
+      })
+    })
+
+    it('about page title is in the initial HTML', () => {
+      cy.request('/about').then((response) => {
+        expect(response.body).to.include('<title>About — Kitchen Sink</title>')
+      })
+    })
+
+    it('head test page title is in the initial HTML', () => {
+      cy.request('/head').then((response) => {
+        expect(response.body).to.include('<title>Head Test — Kitchen Sink</title>')
+      })
+    })
+
+    it('meta description is in the initial HTML for home', () => {
+      cy.request('/').then((response) => {
+        expect(response.body).to.include('Kitchen sink test app.')
+      })
+    })
+  })
+}