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

package/e2e/kitchen-sink/app/pages/blog/[slug].ts

@@ -0,0 +1,54 @@
+interface Post {
+  slug: string
+  title: string
+  body: string
+}
+
+component('page-blog-slug', () => {
+  const props = useProps<{ slug: string }>({ slug: '' })
+  const ssrData = usePageData<Post>()
+
+  const title = ref(ssrData?.title ?? '')
+  const body = ref(ssrData?.body ?? '')
+
+  useOnConnected(async () => {
+    if (ssrData) return  // already hydrated
+    if (!props.slug) return
+    try {
+      const r = await fetch(`/api/posts/${props.slug}`)
+      if (r.ok) {
+        const post: Post | null = await r.json()
+        if (post) { title.value = post.title; body.value = post.body; return }
+      }
+    } catch { /* no API server (SPA mode) */ }
+    // SPA fallback: import post data directly from the source module
+    const { posts } = await import('../../../server/data/posts')
+    const post = posts.find((p) => p.slug === props.slug)
+    if (post) { title.value = post.title; body.value = post.body }
+  })
+
+  return html`
+    <div>
+      <h1 data-cy="post-title">${title.value || props.slug}</h1>
+      <p data-cy="post-slug"><em>slug: <code>${props.slug}</code></em></p>
+      <div data-cy="post-body">${body.value}</div>
+      <p><a href="/blog" data-cy="post-back">← Back to blog</a></p>
+    </div>
+  `
+})
+
+export const loader = async ({ params }: { params: { slug: string } }) => {
+  const { posts } = await import('../../../server/data/posts')
+  const post = posts.find((p) => p.slug === params.slug)
+  if (!post) throw new Error('Post not found')
+  return { slug: post.slug, title: post.title, body: post.body }
+}
+
+export const meta = {
+  ssg: {
+    paths: async () => [
+      { params: { slug: 'first-post' } },
+      { params: { slug: 'second-post' } },
+    ],
+  },
+}

package/e2e/kitchen-sink/app/pages/blog/index.ts

@@ -0,0 +1,46 @@
+interface Post {
+  slug: string
+  title: string
+  excerpt: string
+}
+
+component('page-blog', () => {
+  useHead({ title: 'Blog — Kitchen Sink' })
+
+  const ssrData = usePageData<{ posts: Post[] }>()
+  const posts = ref<Post[]>(ssrData?.posts ?? [])
+
+  useOnConnected(async () => {
+    if (ssrData) return  // already hydrated — skip client fetch
+    try {
+      const r = await fetch('/api/posts')
+      if (r.ok) {
+        const data: Post[] = await r.json()
+        if (Array.isArray(data)) { posts.value = data; return }
+      }
+    } catch { /* no API server (SPA mode) */ }
+    // SPA fallback: import post data directly from the source module
+    const { posts: staticPosts } = await import('../../../server/data/posts')
+    posts.value = staticPosts
+  })
+
+  return html`
+    <div>
+      <h1 data-cy="blog-heading">Blog</h1>
+      <p>Posts are loaded via a page <strong>loader</strong> (SSR/SSG) or client-side fetch (SPA).</p>
+      <ul data-cy="blog-list">
+        ${posts.value.map(post => html`
+          <li data-cy="blog-item">
+            <a href="/blog/${post.slug}" data-cy="blog-link-${post.slug}"><strong>${post.title}</strong></a>
+            <p>${post.excerpt}</p>
+          </li>
+        `)}
+      </ul>
+    </div>
+  `
+})
+
+export const loader = async () => {
+  const { posts } = await import('../../../server/data/posts')
+  return { posts }
+}

package/e2e/kitchen-sink/app/pages/counter.ts

@@ -0,0 +1,17 @@
+// Tests auto-imported composable (useKsCounter) + reactive state
+component('page-counter', () => {
+  const { count, increment, decrement, reset } = useKsCounter()
+
+  return html`
+    <div>
+      <h1 data-cy="counter-heading">Counter</h1>
+      <p>Tests auto-imported <code>useKsCounter</code> composable and reactive state.</p>
+      <div data-cy="counter-widget">
+        <p>Count: <strong data-cy="count">${count.value}</strong></p>
+        <button data-cy="decrement" @click="${decrement}">−</button>
+        <button data-cy="reset" @click="${reset}">Reset</button>
+        <button data-cy="increment" @click="${increment}">+</button>
+      </div>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/head.ts

@@ -0,0 +1,20 @@
+component('page-head', () => {
+  useHead({
+    title: 'Head Test — Kitchen Sink',
+    meta: [
+      { name: 'description', content: 'A test page for useHead().' },
+      { property: 'og:title', content: 'Head Test' },
+    ],
+    link: [
+      { rel: 'canonical', href: 'http://localhost/head' },
+    ],
+  })
+
+  return html`
+    <div>
+      <h1 data-cy="head-heading">Head Test</h1>
+      <p data-cy="head-description">This page sets document title and meta tags via <code>useHead()</code>.</p>
+      <p>Check the page <code>&lt;title&gt;</code> and <code>&lt;meta name="description"&gt;</code> tags.</p>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/index.ts

@@ -0,0 +1,27 @@
+component('page-index', () => {
+  useHead({
+    title: 'Home — Kitchen Sink',
+    meta: [{ name: 'description', content: 'Kitchen sink test app.' }],
+  })
+
+  return html`
+    <div>
+      <ks-badge>v1</ks-badge>
+      <h1 data-cy="home-heading">Kitchen Sink</h1>
+      <p data-cy="home-description">A comprehensive test app for vite-plugin-cer-app.</p>
+      <nav data-cy="page-nav">
+        <ul>
+          <li><a href="/about">About (minimal layout)</a></li>
+          <li><a href="/counter">Counter (reactive state + composable)</a></li>
+          <li><a href="/head">Head management (useHead)</a></li>
+          <li><a href="/blog">Blog (data loader)</a></li>
+          <li><a href="/blog/first-post">Blog post (dynamic route)</a></li>
+          <li><a href="/items/1">Item detail (route params)</a></li>
+          <li><a href="/protected">Protected (middleware)</a></li>
+          <li><a href="/login">Login</a></li>
+          <li><a href="/not-a-real-page">404 catch-all</a></li>
+        </ul>
+      </nav>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/items/[id].ts

@@ -0,0 +1,20 @@
+component('page-items-id', () => {
+  const props = useProps<{ id: string }>({ id: '' })
+
+  return html`
+    <div>
+      <h1 data-cy="item-heading">Item Detail</h1>
+      <p data-cy="item-id-display">Item ID: <strong data-cy="item-id">${props.id}</strong></p>
+      <p><a href="/" data-cy="item-back">← Home</a></p>
+    </div>
+  `
+})
+
+export const meta = {
+  ssg: {
+    paths: async () => [
+      { params: { id: '1' } },
+      { params: { id: '2' } },
+    ],
+  },
+}

package/e2e/kitchen-sink/app/plugins/01.setup.ts

@@ -0,0 +1,7 @@
+// Plugin 01: provides a greeting string via app.provide()
+export default {
+  name: 'ks-setup',
+  setup(app: any) {
+    app.provide('ks-greeting', 'Hello from ks-setup plugin!')
+  },
+}

package/e2e/kitchen-sink/cer-auto-imports.d.ts

@@ -0,0 +1,50 @@
+// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app
+// Do not edit — regenerated automatically on dev server start and build.
+
+export {}
+
+declare global {
+  const component: typeof import('@jasonshimmy/custom-elements-runtime')['component']
+  const html: typeof import('@jasonshimmy/custom-elements-runtime')['html']
+  const css: typeof import('@jasonshimmy/custom-elements-runtime')['css']
+  const ref: typeof import('@jasonshimmy/custom-elements-runtime')['ref']
+  const computed: typeof import('@jasonshimmy/custom-elements-runtime')['computed']
+  const watch: typeof import('@jasonshimmy/custom-elements-runtime')['watch']
+  const watchEffect: typeof import('@jasonshimmy/custom-elements-runtime')['watchEffect']
+  const useProps: typeof import('@jasonshimmy/custom-elements-runtime')['useProps']
+  const useEmit: typeof import('@jasonshimmy/custom-elements-runtime')['useEmit']
+  const useOnConnected: typeof import('@jasonshimmy/custom-elements-runtime')['useOnConnected']
+  const useOnDisconnected: typeof import('@jasonshimmy/custom-elements-runtime')['useOnDisconnected']
+  const useOnAttributeChanged: typeof import('@jasonshimmy/custom-elements-runtime')['useOnAttributeChanged']
+  const useOnError: typeof import('@jasonshimmy/custom-elements-runtime')['useOnError']
+  const useStyle: typeof import('@jasonshimmy/custom-elements-runtime')['useStyle']
+  const useDesignTokens: typeof import('@jasonshimmy/custom-elements-runtime')['useDesignTokens']
+  const useGlobalStyle: typeof import('@jasonshimmy/custom-elements-runtime')['useGlobalStyle']
+  const useExpose: typeof import('@jasonshimmy/custom-elements-runtime')['useExpose']
+  const useSlots: typeof import('@jasonshimmy/custom-elements-runtime')['useSlots']
+  const provide: typeof import('@jasonshimmy/custom-elements-runtime')['provide']
+  const inject: typeof import('@jasonshimmy/custom-elements-runtime')['inject']
+  const createComposable: typeof import('@jasonshimmy/custom-elements-runtime')['createComposable']
+  const nextTick: typeof import('@jasonshimmy/custom-elements-runtime')['nextTick']
+  const defineModel: typeof import('@jasonshimmy/custom-elements-runtime')['defineModel']
+  const getCurrentComponentContext: typeof import('@jasonshimmy/custom-elements-runtime')['getCurrentComponentContext']
+  const isReactiveState: typeof import('@jasonshimmy/custom-elements-runtime')['isReactiveState']
+  const unsafeHTML: typeof import('@jasonshimmy/custom-elements-runtime')['unsafeHTML']
+  const decodeEntities: typeof import('@jasonshimmy/custom-elements-runtime')['decodeEntities']
+  const useTeleport: typeof import('@jasonshimmy/custom-elements-runtime')['useTeleport']
+
+  const when: typeof import('@jasonshimmy/custom-elements-runtime/directives')['when']
+  const each: typeof import('@jasonshimmy/custom-elements-runtime/directives')['each']
+  const match: typeof import('@jasonshimmy/custom-elements-runtime/directives')['match']
+  const anchorBlock: typeof import('@jasonshimmy/custom-elements-runtime/directives')['anchorBlock']
+
+  const useHead: typeof import('@jasonshimmy/vite-plugin-cer-app/composables')['useHead']
+  const usePageData: typeof import('@jasonshimmy/vite-plugin-cer-app/composables')['usePageData']
+
+  const useKsCounter: typeof import('./app/composables/useKsCounter')['useKsCounter']
+
+  // SSR loader data injected as window.__CER_DATA__ by the server.
+  // Consumed once by usePageData() during client hydration.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var __CER_DATA__: any
+}

package/e2e/kitchen-sink/cer-env.d.ts

@@ -0,0 +1,36 @@
+// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app
+// Do not edit — regenerated automatically on dev server start and build.
+
+declare module 'virtual:cer-routes' {
+  import type { Route } from '@jasonshimmy/custom-elements-runtime/router'
+  const routes: Route[]
+  export default routes
+}
+
+declare module 'virtual:cer-layouts' {}
+declare module 'virtual:cer-components' {}
+
+declare module 'virtual:cer-plugins' {
+  import type { AppPlugin } from '@jasonshimmy/vite-plugin-cer-app/types'
+  const plugins: AppPlugin[]
+  export default plugins
+}
+
+declare module 'virtual:cer-composables' {
+  export { useKsCounter } from './app/composables/useKsCounter'
+}
+
+declare module 'virtual:cer-middleware' {
+  const middleware: Record<string, Function>
+  export { middleware }
+}
+
+declare module 'virtual:cer-loading' {
+  export const hasLoading: boolean
+  export const loadingTag: string | null
+}
+
+declare module 'virtual:cer-error' {
+  export const hasError: boolean
+  export const errorTag: string | null
+}

package/e2e/kitchen-sink/cer-tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "~/*": [
+        "./app/*"
+      ],
+      "~/pages/*": [
+        "./app/pages/*"
+      ],
+      "~/layouts/*": [
+        "./app/layouts/*"
+      ],
+      "~/components/*": [
+        "./app/components/*"
+      ],
+      "~/composables/*": [
+        "./app/composables/*"
+      ],
+      "~/plugins/*": [
+        "./app/plugins/*"
+      ],
+      "~/middleware/*": [
+        "./app/middleware/*"
+      ],
+      "~/assets/*": [
+        "./app/assets/*"
+      ]
+    }
+  }
+}

package/e2e/kitchen-sink/cer.config.ts

@@ -0,0 +1,6 @@
+// Kitchen sink configuration — mode is overridden by --mode CLI flag
+export default {
+  ssr: { dsd: true, streaming: false },
+  ssg: { routes: 'auto', concurrency: 2 },
+  autoImports: { runtime: true, components: true, composables: true },
+}

package/e2e/kitchen-sink/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Kitchen Sink</title>
+  </head>
+  <body>
+    <cer-layout-view></cer-layout-view>
+    <script type="module" src="/app/app.ts"></script>
+  </body>
+</html>

package/e2e/kitchen-sink/server/api/health.ts

@@ -0,0 +1,3 @@
+export const GET = (_req: any, res: any) => {
+  res.json({ status: 'ok', service: 'kitchen-sink' })
+}

package/e2e/kitchen-sink/server/api/posts/[slug].ts

@@ -0,0 +1,11 @@
+import { posts } from '../../data/posts'
+
+export const GET = (req: any, res: any) => {
+  const { slug } = req.params
+  const post = posts.find((p) => p.slug === slug)
+  if (!post) {
+    res.statusCode = 404
+    return res.json({ error: 'Not found' })
+  }
+  res.json(post)
+}

package/e2e/kitchen-sink/server/api/posts/index.ts

@@ -0,0 +1,5 @@
+import { posts } from '../../data/posts'
+
+export const GET = (_req: any, res: any) => {
+  res.json(posts)
+}

package/e2e/kitchen-sink/server/data/posts.ts

@@ -0,0 +1,21 @@
+export interface Post {
+  slug: string
+  title: string
+  excerpt: string
+  body: string
+}
+
+export const posts: Post[] = [
+  {
+    slug: 'first-post',
+    title: 'First Post',
+    excerpt: 'The very first post in the kitchen sink.',
+    body: 'First post body content. This was loaded via a page loader.',
+  },
+  {
+    slug: 'second-post',
+    title: 'Second Post',
+    excerpt: 'The second post in the kitchen sink.',
+    body: 'Second post body content. Dynamic routes and loaders work together.',
+  },
+]

package/e2e/scripts/clean.mjs

@@ -0,0 +1,8 @@
+import { rmSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const root = fileURLToPath(new URL('../kitchen-sink', import.meta.url))
+rmSync(join(root, 'dist'), { recursive: true, force: true })
+rmSync(join(root, 'node_modules', '.cer-app-cache'), { recursive: true, force: true })
+console.log('[e2e] Cleaned kitchen-sink/dist and cache')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [
@@ -48,7 +48,22 @@
     "dev": "tsc -p tsconfig.build.json --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "e2e:clean": "node e2e/scripts/clean.mjs",
+    "e2e:build:spa": "npm run e2e:clean && node dist/cli/index.js build --mode spa --root e2e/kitchen-sink",
+    "e2e:build:ssr": "npm run e2e:clean && node dist/cli/index.js build --mode ssr --root e2e/kitchen-sink",
+    "e2e:build:ssg": "npm run e2e:clean && node dist/cli/index.js build --mode ssg --root e2e/kitchen-sink",
+    "e2e:serve:spa": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4174",
+    "e2e:serve:ssr": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4175 --ssr",
+    "e2e:serve:ssg": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4176",
+    "e2e:run:spa": "cypress run --config baseUrl=http://localhost:4174 --env mode=spa",
+    "e2e:run:ssr": "cypress run --config baseUrl=http://localhost:4175 --env mode=ssr",
+    "e2e:run:ssg": "cypress run --config baseUrl=http://localhost:4176 --env mode=ssg",
+    "e2e:spa": "npm run e2e:build:spa && start-server-and-test e2e:serve:spa http://localhost:4174 e2e:run:spa",
+    "e2e:ssr": "npm run e2e:build:ssr && start-server-and-test e2e:serve:ssr http://localhost:4175 e2e:run:ssr",
+    "e2e:ssg": "npm run e2e:build:ssg && start-server-and-test e2e:serve:ssg http://localhost:4176 e2e:run:ssg",
+    "e2e": "npm run e2e:ssr && npm run e2e:ssg && npm run e2e:spa",
+    "cypress:open": "cypress open"
   },
   "peerDependencies": {
     "@jasonshimmy/custom-elements-runtime": ">=3.0.0",
@@ -64,7 +79,9 @@
     "@jasonshimmy/custom-elements-runtime": "^3.1.3",
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "cypress": "^15.12.0",
     "happy-dom": "^20.8.4",
+    "start-server-and-test": "^2.0.0",
     "typescript": "^5.4.0",
     "vite": "^8.0.0",
     "vitest": "^4.1.0"

package/src/__tests__/plugin/build-ssg-render.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Integration tests for the build-ssg renderPath success path.
+ *
+ * These tests use a real temporary ESM module as the "server bundle" so that
+ * the dynamic import() inside renderPath actually resolves, exercising the
+ * success branches (writeRenderedPath call, generatedPaths.push, etc.) that
+ * are unreachable when the bundle is absent.
+ *
+ * A separate test file is required so the node:fs/promises mock does NOT
+ * shadow the real writeFile/mkdir used to set up the temp bundle.
+ */
+import { vi, describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'pathe'
+
+// Mock buildSSR so the SSG pipeline skips the Vite build step.
+vi.mock('../../plugin/build-ssr.js', () => ({ buildSSR: vi.fn().mockResolvedValue(undefined) }))
+vi.mock('fast-glob', () => ({ default: vi.fn().mockResolvedValue([]) }))
+// Intentionally NOT mocking node:fs or node:fs/promises so real writes work.
+
+import type { ResolvedCerConfig } from '../../plugin/dev-server.js'
+
+let tmpRoot: string
+
+beforeAll(() => {
+  // Create a minimal "server bundle" that exports a handler.
+  // The handler writes a minimal HTML string to res.end so renderPath captures it.
+  tmpRoot = join(tmpdir(), `cer-ssg-render-${Date.now()}`)
+  const serverDir = join(tmpRoot, 'dist', 'server')
+  mkdirSync(serverDir, { recursive: true })
+  writeFileSync(
+    join(serverDir, 'server.js'),
+    // ESM module — works because Vitest runs with Node's native ESM loader.
+    `export const handler = async (req, res) => {
+      res.setHeader('Content-Type', 'text/html');
+      res.end('<!DOCTYPE html><html><head></head><body>Hello from ' + req.url + '</body></html>');
+    };
+    export const apiRoutes = [];
+    export const plugins = [];
+    export const layouts = {};
+    `,
+    'utf-8',
+  )
+})
+
+afterAll(() => {
+  rmSync(tmpRoot, { recursive: true, force: true })
+})
+
+function makeConfig(overrides: Partial<ResolvedCerConfig> = {}): ResolvedCerConfig {
+  return {
+    root: tmpRoot,
+    srcDir: join(tmpRoot, 'app'),
+    pagesDir: join(tmpRoot, 'app', 'pages'),
+    mode: 'ssg',
+    ssr: { dsd: true },
+    ssg: { routes: ['/'], concurrency: 1 },
+    ...overrides,
+  } as unknown as ResolvedCerConfig
+}
+
+describe('buildSSG — renderPath success (real server bundle)', () => {
+  it('writes rendered HTML for the root path to dist/index.html', async () => {
+    // Reset module registry so _serverMod cache is cleared between test runs.
+    await vi.resetModules()
+    const { buildSSG } = await import('../../plugin/build-ssg.js')
+    await buildSSG(makeConfig())
+
+    const { readFileSync, existsSync } = await import('node:fs')
+    const outPath = join(tmpRoot, 'dist', 'index.html')
+    expect(existsSync(outPath)).toBe(true)
+    const html = readFileSync(outPath, 'utf-8')
+    expect(html).toContain('Hello from /')
+  })
+
+  it('records the path in the ssg-manifest paths array', async () => {
+    await vi.resetModules()
+    const { buildSSG } = await import('../../plugin/build-ssg.js')
+    await buildSSG(makeConfig())
+
+    const { readFileSync } = await import('node:fs')
+    const manifest = JSON.parse(readFileSync(join(tmpRoot, 'dist', 'ssg-manifest.json'), 'utf-8'))
+    expect(manifest.paths).toContain('/')
+    expect(manifest.errors).toHaveLength(0)
+  })
+
+  it('renders multiple paths with concurrency > 1', async () => {
+    await vi.resetModules()
+    const { buildSSG } = await import('../../plugin/build-ssg.js')
+    const config = makeConfig({ ssg: { routes: ['/', '/about'], concurrency: 2 } } as Partial<ResolvedCerConfig>)
+    await buildSSG(config)
+
+    const { readFileSync, existsSync } = await import('node:fs')
+    expect(existsSync(join(tmpRoot, 'dist', 'index.html'))).toBe(true)
+    expect(existsSync(join(tmpRoot, 'dist', 'about', 'index.html'))).toBe(true)
+    const manifest = JSON.parse(readFileSync(join(tmpRoot, 'dist', 'ssg-manifest.json'), 'utf-8'))
+    expect(manifest.paths).toHaveLength(2)
+  })
+
+  it('uses cached _serverMod on second renderPath call (no double import)', async () => {
+    // In a fresh module instance, render two paths sequentially.
+    // The second renderPath call hits the !_serverMod === false branch (cache).
+    await vi.resetModules()
+    const { buildSSG } = await import('../../plugin/build-ssg.js')
+    const config = makeConfig({ ssg: { routes: ['/', '/page2'], concurrency: 1 } } as Partial<ResolvedCerConfig>)
+    // Should complete without error — second call uses cached module
+    await expect(buildSSG(config)).resolves.not.toThrow()
+  })
+})

package/src/__tests__/plugin/build-ssg.test.ts

@@ -19,7 +19,7 @@ import fg from 'fast-glob'
 import { createServer } from 'vite'
 import { buildSSR } from '../../plugin/build-ssr.js'
 import { buildRouteEntry } from '../../plugin/path-utils.js'
-import { buildSSG } from '../../plugin/build-ssg.js'
+import { buildSSG, writeRenderedPath } from '../../plugin/build-ssg.js'
 import type { ResolvedCerConfig } from '../../plugin/dev-server.js'
 
 function makeConfig(overrides: Partial<ResolvedCerConfig> = {}): ResolvedCerConfig {
@@ -263,3 +263,49 @@ describe('buildSSG — path collection', () => {
     expect(manifest.paths.length + manifest.errors.length).toBe(1)
   })
 })
+
+// ─── writeRenderedPath ────────────────────────────────────────────────────────
+
+describe('writeRenderedPath', () => {
+  beforeEach(() => {
+    vi.mocked(writeFile).mockClear()
+    vi.mocked(mkdir).mockClear()
+  })
+
+  it('writes root path to dist/index.html', async () => {
+    await writeRenderedPath('/', '<html>home</html>', '/project/dist')
+    const [writePath] = vi.mocked(writeFile).mock.calls[0]
+    expect(String(writePath)).toMatch(/dist\/index\.html$/)
+  })
+
+  it('writes /about to dist/about/index.html', async () => {
+    await writeRenderedPath('/about', '<html>about</html>', '/project/dist')
+    const [writePath] = vi.mocked(writeFile).mock.calls[0]
+    expect(String(writePath)).toMatch(/dist\/about\/index\.html$/)
+  })
+
+  it('writes nested path to correct subdirectory', async () => {
+    await writeRenderedPath('/blog/first-post', '<html>post</html>', '/project/dist')
+    const [writePath] = vi.mocked(writeFile).mock.calls[0]
+    expect(String(writePath)).toMatch(/dist\/blog\/first-post\/index\.html$/)
+  })
+
+  it('writes the provided html content', async () => {
+    const html = '<html><body>Hello</body></html>'
+    await writeRenderedPath('/page', html, '/project/dist')
+    const [, content] = vi.mocked(writeFile).mock.calls[0]
+    expect(content).toBe(html)
+  })
+
+  it('creates the output directory before writing', async () => {
+    await writeRenderedPath('/nested/deep', '<html/>', '/project/dist')
+    expect(mkdir).toHaveBeenCalledWith(expect.stringContaining('nested/deep'), { recursive: true })
+  })
+
+  it('strips leading and trailing slashes from path', async () => {
+    await writeRenderedPath('/trailing/', '<html/>', '/project/dist')
+    const [writePath] = vi.mocked(writeFile).mock.calls[0]
+    expect(String(writePath)).toMatch(/trailing\/index\.html$/)
+    expect(String(writePath)).not.toMatch(/\/\//)
+  })
+})