toiljs 0.0.12 → 0.0.15

package/src/compiler/ssg.ts

@@ -0,0 +1,126 @@
+/**
+ * Build-time SSG for dynamic routes. After the client bundle is written, this loads each dynamic
+ * route that exports `generateStaticParams`, enumerates its concrete URLs, runs the route's
+ * `generateMetadata` per URL, and bakes a `<url>/index.html` (so JS-less crawlers get per-page tags)
+ * plus a `sitemap.xml` entry. Opt-in: a route without `generateStaticParams` is untouched, and the
+ * whole pass is skipped when no such route exists or `seo` is unconfigured. Build-only.
+ *
+ * Runs from `build()` (not the prerender Vite plugin) so it can reuse `createViteConfig` without the
+ * `vite.ts` <-> `prerender.ts` import cycle; it spins up a short-lived SSR server to load route source.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createServer } from 'vite';
+
+import { type ResolvedToilConfig } from './config.js';
+import { scanRoutes } from './routes.js';
+import { injectSeoHtml, routeSeo, sitemapXml } from './seo.js';
+import { createViteConfig } from './vite.js';
+
+type StaticParams = Record<string, string | string[]>;
+
+interface RouteModule {
+    generateStaticParams?: () => StaticParams[] | Promise<StaticParams[]>;
+    generateMetadata?: (args: {
+        params: StaticParams;
+        searchParams: URLSearchParams;
+        data: unknown;
+    }) => unknown;
+    loader?: (args: { params: StaticParams; searchParams: URLSearchParams }) => unknown;
+    metadata?: Record<string, unknown>;
+}
+
+/** Substitutes `:param` / `*catch-all` segments in a route pattern with concrete param values. */
+export function fillPattern(pattern: string, params: StaticParams): string {
+    return pattern.replace(/[:*]([A-Za-z0-9_]+)/g, (_m, name: string) => {
+        const value = params[name] as string | string[] | undefined;
+        if (Array.isArray(value)) return value.join('/');
+        return value ?? '';
+    });
+}
+
+/** Coerces an unknown module export to a typed Metadata-ish record, or null. */
+function asMetadata(value: unknown): Record<string, unknown> | null {
+    return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+/**
+ * Pre-renders every dynamic route that opts in via `generateStaticParams`. Bakes per-URL HTML into
+ * `outDir` and rewrites `sitemap.xml` with the generated URLs. Returns the list of generated URLs.
+ */
+export async function prerenderStaticParams(cfg: ResolvedToilConfig): Promise<string[]> {
+    if (!cfg.seo) return [];
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    // Prefer the clean shell stashed by the prerender plugin (no per-route SEO baked in); fall back
+    // to the built index.html.
+    const stashed = path.join(cfg.toilDir, 'shell.html');
+    const shellPath = fs.existsSync(stashed) ? stashed : path.join(outDir, 'index.html');
+    if (!fs.existsSync(shellPath)) return [];
+
+    const allRoutes = scanRoutes(cfg.routesAbsDir);
+    const dynamic = allRoutes.filter(
+        (r) => r.slot === undefined && !r.intercept && /[:*]/.test(r.pattern),
+    );
+    if (dynamic.length === 0) return [];
+
+    const shell = fs.readFileSync(shellPath, 'utf8');
+    const server = await createServer({
+        ...(await createViteConfig(cfg)),
+        server: { middlewareMode: true, hmr: false },
+        appType: 'custom',
+        logLevel: 'silent',
+    });
+
+    const generated: string[] = [];
+    const warn = (msg: string): void => {
+        process.stderr.write(`  toil: SSG ${msg}\n`);
+    };
+    try {
+        for (const route of dynamic) {
+            let mod: RouteModule;
+            try {
+                mod = (await server.ssrLoadModule(route.file)) as RouteModule;
+            } catch (err) {
+                warn(`skipped ${route.pattern} (${err instanceof Error ? err.message : String(err)})`);
+                continue;
+            }
+            if (typeof mod.generateStaticParams !== 'function') continue;
+            const paramSets = await mod.generateStaticParams();
+            for (const params of paramSets) {
+                const url = fillPattern(route.pattern, params);
+                let metadata: Record<string, unknown> | null = null;
+                try {
+                    if (typeof mod.generateMetadata === 'function') {
+                        const searchParams = new URLSearchParams();
+                        const data =
+                            typeof mod.loader === 'function'
+                                ? await mod.loader({ params, searchParams })
+                                : undefined;
+                        metadata = asMetadata(await mod.generateMetadata({ params, searchParams, data }));
+                    } else if (mod.metadata) {
+                        metadata = asMetadata(mod.metadata);
+                    }
+                } catch (err) {
+                    warn(`metadata failed for ${url} (${err instanceof Error ? err.message : String(err)})`);
+                }
+                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, url));
+                const target = path.join(outDir, url.replace(/^\//, ''), 'index.html');
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, html);
+                generated.push(url);
+            }
+        }
+    } finally {
+        await server.close();
+    }
+
+    if (generated.length > 0) {
+        const sitemap = sitemapXml(cfg.seo, allRoutes, generated);
+        if (sitemap) fs.writeFileSync(path.join(outDir, 'sitemap.xml'), sitemap);
+        process.stdout.write(
+            `  ✓ prerendered ${String(generated.length)} dynamic route${generated.length === 1 ? '' : 's'}\n`,
+        );
+    }
+    return generated;
+}

package/test/dom/error-overlay.test.tsx

@@ -1,44 +1,44 @@
-// @vitest-environment jsdom
-import { act, cleanup, fireEvent, render } from '@testing-library/react';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import {
-    DevErrorBoundary,
-    DevErrorOverlay,
-    initDevErrorOverlay,
-} from '../../src/client/dev/error-overlay';
-
-afterEach(cleanup);
-
-function Boom(): never {
-    throw new Error('render boom');
-}
-
-describe('dev error overlay', () => {
-    it('surfaces an uncaught render error', () => {
-        // React logs caught boundary errors to console.error — silence it for a clean test run.
-        const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
-        const { getByRole } = render(
-            <>
-                <DevErrorBoundary>
-                    <Boom />
-                </DevErrorBoundary>
-                <DevErrorOverlay />
-            </>,
-        );
-        expect(getByRole('alert').textContent).toContain('render boom');
-        spy.mockRestore();
-    });
-
-    it('surfaces an unhandled window error and dismisses it', async () => {
-        initDevErrorOverlay();
-        const { findByRole, queryByRole, getByText } = render(<DevErrorOverlay />);
-        act(() => {
-            window.dispatchEvent(new ErrorEvent('error', { error: new Error('async boom') }));
-        });
-        const alert = await findByRole('alert');
-        expect(alert.textContent).toContain('async boom');
-        fireEvent.click(getByText('Dismiss'));
-        expect(queryByRole('alert')).toBeNull();
-    });
-});
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+    DevErrorBoundary,
+    DevErrorOverlay,
+    initDevErrorOverlay,
+} from '../../src/client/dev/error-overlay';
+
+afterEach(cleanup);
+
+function Boom(): never {
+    throw new Error('render boom');
+}
+
+describe('dev error overlay', () => {
+    it('surfaces an uncaught render error', () => {
+        // React logs caught boundary errors to console.error, silence it for a clean test run.
+        const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const { getByRole } = render(
+            <>
+                <DevErrorBoundary>
+                    <Boom />
+                </DevErrorBoundary>
+                <DevErrorOverlay />
+            </>,
+        );
+        expect(getByRole('alert').textContent).toContain('render boom');
+        spy.mockRestore();
+    });
+
+    it('surfaces an unhandled window error and dismisses it', async () => {
+        initDevErrorOverlay();
+        const { findByRole, queryByRole, getByText } = render(<DevErrorOverlay />);
+        act(() => {
+            window.dispatchEvent(new ErrorEvent('error', { error: new Error('async boom') }));
+        });
+        const alert = await findByRole('alert');
+        expect(alert.textContent).toContain('async boom');
+        fireEvent.click(getByText('Dismiss'));
+        expect(queryByRole('alert')).toBeNull();
+    });
+});

package/test/dom/router-loading.test.tsx

@@ -17,7 +17,7 @@ const routes: RouteDef[] = [
         load: () => Promise.resolve({ default: () => <div>HOME</div> }),
     },
     {
-        // Page chunk never resolves, so the route stays suspended — exercising the fallback path.
+        // Page chunk never resolves, so the route stays suspended, exercising the fallback path.
         pattern: '/slow',
         load: () => new Promise<{ default: () => null }>(() => undefined),
         loading: () => Promise.resolve({ default: () => <div>LOADING</div> }),

package/test/dom/use-metadata.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+
+import { Metadata, useMetadata } from '../../src/client/head/metadata';
+import { setRouteHead } from '../../src/client/head/head';
+
+afterEach(() => {
+    cleanup();
+    setRouteHead(null);
+});
+
+const meta = (key: string): string | null =>
+    document.head.querySelector(`meta[${key}]`)?.getAttribute('content') ?? null;
+
+describe('useMetadata / <Metadata>', () => {
+    it('applies a full Metadata object to the document head from a component', () => {
+        function Article() {
+            useMetadata({
+                title: 'Article',
+                description: 'an article',
+                openGraph: { title: 'og title', type: 'website' },
+            });
+            return null;
+        }
+        render(<Article />);
+        expect(document.title).toBe('Article');
+        expect(meta('name="description"')).toBe('an article');
+        expect(meta('property="og:title"')).toBe('og title');
+    });
+
+    it('reverts the head when the component unmounts', () => {
+        function Article() {
+            useMetadata({ title: 'Temp' });
+            return null;
+        }
+        const { unmount } = render(<Article />);
+        expect(document.title).toBe('Temp');
+        unmount();
+        expect(document.title).not.toBe('Temp');
+    });
+
+    it('the declarative <Metadata> form applies too', () => {
+        render(<Metadata title="Declarative" />);
+        expect(document.title).toBe('Declarative');
+    });
+
+    it("a route's metadata still wins over a component's useMetadata", () => {
+        function Article() {
+            useMetadata({ title: 'Component' });
+            return null;
+        }
+        render(<Article />);
+        // The route baseline (applied last) takes precedence for keys it sets.
+        setRouteHead({ title: 'Route' });
+        expect(document.title).toBe('Route');
+    });
+});

package/test/seo.test.ts

@@ -1,164 +1,164 @@
-import { describe, expect, it } from 'vitest';
-
-import type { ScannedRoute } from '../src/compiler/routes';
-import {
-    injectSeoHtml,
-    llmsTxt,
-    robotsTxt,
-    routeSeo,
-    seoHeadTags,
-    sitemapXml,
-} from '../src/compiler/seo';
-
-const routes: ScannedRoute[] = [
-    { file: 'a', pattern: '/' },
-    { file: 'b', pattern: '/about' },
-    { file: 'c', pattern: '/blog/:id' }, // dynamic — excluded from sitemap
-    { file: 'd', pattern: '/photo/:id', slot: 'modal', intercept: true }, // slot/intercept — excluded
-];
-
-describe('seoHeadTags', () => {
-    it('bakes description, OG, canonical, preconnect, and JSON-LD', () => {
-        const html = seoHeadTags({
-            url: 'https://x.test',
-            title: 'Home',
-            description: 'desc',
-            openGraph: { type: 'website', image: 'https://x.test/og.png' },
-            preconnect: ['https://cdn.test'],
-            jsonLd: { '@context': 'https://schema.org', '@type': 'WebSite' },
-        });
-        expect(html).toContain('<meta name="description" content="desc" />');
-        expect(html).toContain('<meta property="og:title" content="Home" />');
-        expect(html).toContain('<meta property="og:image" content="https://x.test/og.png" />');
-        expect(html).toContain('<link rel="canonical" href="https://x.test" />');
-        expect(html).toContain('<link rel="preconnect" href="https://cdn.test" />');
-        expect(html).toContain('application/ld+json');
-        expect(html).toContain('"@type":"WebSite"');
-    });
-
-    it('escapes attribute values', () => {
-        expect(seoHeadTags({ description: 'a "b" <c>' })).toContain(
-            'content="a &quot;b&quot; &lt;c&gt;"',
-        );
-    });
-
-    it('renders a full Twitter card + OG image dimensions + fb:app_id', () => {
-        const html = seoHeadTags({
-            title: 'Home',
-            description: 'd',
-            openGraph: {
-                image: 'https://x.test/og.png',
-                imageAlt: 'alt',
-                imageWidth: 1200,
-                imageHeight: 630,
-            },
-            twitter: { site: '@x' },
-            facebook: { appId: '123' },
-        });
-        expect(html).toContain('<meta name="twitter:card" content="summary_large_image" />');
-        expect(html).toContain('<meta name="twitter:site" content="@x" />');
-        expect(html).toContain('<meta name="twitter:title" content="Home" />');
-        expect(html).toContain('<meta name="twitter:image" content="https://x.test/og.png" />');
-        expect(html).toContain('<meta property="og:image:width" content="1200" />');
-        expect(html).toContain('<meta property="og:image:alt" content="alt" />');
-        expect(html).toContain('<meta property="fb:app_id" content="123" />');
-    });
-
-    it('neutralizes </script> in JSON-LD (no script breakout)', () => {
-        const html = seoHeadTags({ jsonLd: { x: '</script><img src=x onerror=alert(1)>' } });
-        expect(html).not.toContain('</script><img');
-        expect(html).toContain('\\u003c/script');
-    });
-});
-
-describe('routeSeo', () => {
-    it("overlays a route's metadata over the site defaults and points URLs at the route", () => {
-        const site = { url: 'https://x.test', title: 'Site', description: 'site desc' };
-        const out = routeSeo(site, { title: 'About', description: 'about desc' }, '/about');
-        expect(out.title).toBe('About');
-        expect(out.description).toBe('about desc');
-        expect(out.url).toBe('https://x.test/about');
-    });
-
-    it('falls back to the site defaults when a route has no metadata', () => {
-        const site = { url: 'https://x.test', title: 'Site' };
-        expect(routeSeo(site, null, '/x')).toMatchObject({
-            title: 'Site',
-            url: 'https://x.test/x',
-        });
-    });
-});
-
-describe('injectSeoHtml', () => {
-    it('replaces the title + description and inserts the rest before </head>', () => {
-        const shell =
-            '<!doctype html><html><head><title>old</title><meta name="description" content="" /></head><body></body></html>';
-        const out = injectSeoHtml(shell, {
-            title: 'New',
-            description: 'fresh',
-            url: 'https://x.test',
-        });
-        expect(out).toContain('<title>New</title>');
-        expect(out).not.toContain('<title>old</title>');
-        expect(out.match(/name="description"/g)).toHaveLength(1);
-        expect(out).toContain('content="fresh"');
-        expect(out).toContain('<link rel="canonical" href="https://x.test" />');
-    });
-});
-
-describe('robotsTxt', () => {
-    it('allows all + lists AI crawlers + links the sitemap by default', () => {
-        const txt = robotsTxt({ url: 'https://x.test' });
-        expect(txt).toContain('User-agent: *');
-        expect(txt).toContain('Allow: /');
-        expect(txt).toContain('User-agent: GPTBot');
-        expect(txt).toContain('User-agent: ClaudeBot');
-        expect(txt).toContain('Sitemap: https://x.test/sitemap.xml');
-    });
-
-    it('disallows AI crawlers when ai: "disallow"', () => {
-        const txt = robotsTxt({ url: 'https://x.test', robots: { ai: 'disallow' } });
-        expect(txt).toMatch(/User-agent: GPTBot\nDisallow: \//);
-    });
-
-    it('is empty when robots: false', () => {
-        expect(robotsTxt({ robots: false })).toBe('');
-    });
-});
-
-describe('sitemapXml', () => {
-    it('lists only static routes, absolute', () => {
-        const xml = sitemapXml({ url: 'https://x.test' }, routes);
-        expect(xml).toContain('<loc>https://x.test</loc>');
-        expect(xml).toContain('<loc>https://x.test/about</loc>');
-        expect(xml).not.toContain(':id');
-        expect(xml).not.toContain('/photo');
-    });
-
-    it('is empty without a base url', () => {
-        expect(sitemapXml({}, routes)).toBe('');
-    });
-});
-
-describe('llmsTxt', () => {
-    it('renders title, summary, instructions, and pages', () => {
-        const txt = llmsTxt(
-            {
-                url: 'https://x.test',
-                title: 'My Site',
-                description: 'a site',
-                llms: { instructions: 'Be nice.' },
-            },
-            routes,
-        );
-        expect(txt).toContain('# My Site');
-        expect(txt).toContain('> a site');
-        expect(txt).toContain('Be nice.');
-        expect(txt).toContain('[Home](https://x.test)');
-        expect(txt).toContain('[/about](https://x.test/about)');
-    });
-
-    it('is empty when llms: false', () => {
-        expect(llmsTxt({ llms: false }, routes)).toBe('');
-    });
-});
+import { describe, expect, it } from 'vitest';
+
+import type { ScannedRoute } from '../src/compiler/routes';
+import {
+    injectSeoHtml,
+    llmsTxt,
+    robotsTxt,
+    routeSeo,
+    seoHeadTags,
+    sitemapXml,
+} from '../src/compiler/seo';
+
+const routes: ScannedRoute[] = [
+    { file: 'a', pattern: '/' },
+    { file: 'b', pattern: '/about' },
+    { file: 'c', pattern: '/blog/:id' }, // dynamic, excluded from sitemap
+    { file: 'd', pattern: '/photo/:id', slot: 'modal', intercept: true }, // slot/intercept, excluded
+];
+
+describe('seoHeadTags', () => {
+    it('bakes description, OG, canonical, preconnect, and JSON-LD', () => {
+        const html = seoHeadTags({
+            url: 'https://x.test',
+            title: 'Home',
+            description: 'desc',
+            openGraph: { type: 'website', image: 'https://x.test/og.png' },
+            preconnect: ['https://cdn.test'],
+            jsonLd: { '@context': 'https://schema.org', '@type': 'WebSite' },
+        });
+        expect(html).toContain('<meta name="description" content="desc" />');
+        expect(html).toContain('<meta property="og:title" content="Home" />');
+        expect(html).toContain('<meta property="og:image" content="https://x.test/og.png" />');
+        expect(html).toContain('<link rel="canonical" href="https://x.test" />');
+        expect(html).toContain('<link rel="preconnect" href="https://cdn.test" />');
+        expect(html).toContain('application/ld+json');
+        expect(html).toContain('"@type":"WebSite"');
+    });
+
+    it('escapes attribute values', () => {
+        expect(seoHeadTags({ description: 'a "b" <c>' })).toContain(
+            'content="a &quot;b&quot; &lt;c&gt;"',
+        );
+    });
+
+    it('renders a full Twitter card + OG image dimensions + fb:app_id', () => {
+        const html = seoHeadTags({
+            title: 'Home',
+            description: 'd',
+            openGraph: {
+                image: 'https://x.test/og.png',
+                imageAlt: 'alt',
+                imageWidth: 1200,
+                imageHeight: 630,
+            },
+            twitter: { site: '@x' },
+            facebook: { appId: '123' },
+        });
+        expect(html).toContain('<meta name="twitter:card" content="summary_large_image" />');
+        expect(html).toContain('<meta name="twitter:site" content="@x" />');
+        expect(html).toContain('<meta name="twitter:title" content="Home" />');
+        expect(html).toContain('<meta name="twitter:image" content="https://x.test/og.png" />');
+        expect(html).toContain('<meta property="og:image:width" content="1200" />');
+        expect(html).toContain('<meta property="og:image:alt" content="alt" />');
+        expect(html).toContain('<meta property="fb:app_id" content="123" />');
+    });
+
+    it('neutralizes </script> in JSON-LD (no script breakout)', () => {
+        const html = seoHeadTags({ jsonLd: { x: '</script><img src=x onerror=alert(1)>' } });
+        expect(html).not.toContain('</script><img');
+        expect(html).toContain('\\u003c/script');
+    });
+});
+
+describe('routeSeo', () => {
+    it("overlays a route's metadata over the site defaults and points URLs at the route", () => {
+        const site = { url: 'https://x.test', title: 'Site', description: 'site desc' };
+        const out = routeSeo(site, { title: 'About', description: 'about desc' }, '/about');
+        expect(out.title).toBe('About');
+        expect(out.description).toBe('about desc');
+        expect(out.url).toBe('https://x.test/about');
+    });
+
+    it('falls back to the site defaults when a route has no metadata', () => {
+        const site = { url: 'https://x.test', title: 'Site' };
+        expect(routeSeo(site, null, '/x')).toMatchObject({
+            title: 'Site',
+            url: 'https://x.test/x',
+        });
+    });
+});
+
+describe('injectSeoHtml', () => {
+    it('replaces the title + description and inserts the rest before </head>', () => {
+        const shell =
+            '<!doctype html><html><head><title>old</title><meta name="description" content="" /></head><body></body></html>';
+        const out = injectSeoHtml(shell, {
+            title: 'New',
+            description: 'fresh',
+            url: 'https://x.test',
+        });
+        expect(out).toContain('<title>New</title>');
+        expect(out).not.toContain('<title>old</title>');
+        expect(out.match(/name="description"/g)).toHaveLength(1);
+        expect(out).toContain('content="fresh"');
+        expect(out).toContain('<link rel="canonical" href="https://x.test" />');
+    });
+});
+
+describe('robotsTxt', () => {
+    it('allows all + lists AI crawlers + links the sitemap by default', () => {
+        const txt = robotsTxt({ url: 'https://x.test' });
+        expect(txt).toContain('User-agent: *');
+        expect(txt).toContain('Allow: /');
+        expect(txt).toContain('User-agent: GPTBot');
+        expect(txt).toContain('User-agent: ClaudeBot');
+        expect(txt).toContain('Sitemap: https://x.test/sitemap.xml');
+    });
+
+    it('disallows AI crawlers when ai: "disallow"', () => {
+        const txt = robotsTxt({ url: 'https://x.test', robots: { ai: 'disallow' } });
+        expect(txt).toMatch(/User-agent: GPTBot\nDisallow: \//);
+    });
+
+    it('is empty when robots: false', () => {
+        expect(robotsTxt({ robots: false })).toBe('');
+    });
+});
+
+describe('sitemapXml', () => {
+    it('lists only static routes, absolute', () => {
+        const xml = sitemapXml({ url: 'https://x.test' }, routes);
+        expect(xml).toContain('<loc>https://x.test</loc>');
+        expect(xml).toContain('<loc>https://x.test/about</loc>');
+        expect(xml).not.toContain(':id');
+        expect(xml).not.toContain('/photo');
+    });
+
+    it('is empty without a base url', () => {
+        expect(sitemapXml({}, routes)).toBe('');
+    });
+});
+
+describe('llmsTxt', () => {
+    it('renders title, summary, instructions, and pages', () => {
+        const txt = llmsTxt(
+            {
+                url: 'https://x.test',
+                title: 'My Site',
+                description: 'a site',
+                llms: { instructions: 'Be nice.' },
+            },
+            routes,
+        );
+        expect(txt).toContain('# My Site');
+        expect(txt).toContain('> a site');
+        expect(txt).toContain('Be nice.');
+        expect(txt).toContain('[Home](https://x.test)');
+        expect(txt).toContain('[/about](https://x.test/about)');
+    });
+
+    it('is empty when llms: false', () => {
+        expect(llmsTxt({ llms: false }, routes)).toBe('');
+    });
+});

package/test/ssg.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { sitemapXml, type SeoConfig } from '../src/compiler/seo';
+import { fillPattern } from '../src/compiler/ssg';
+import { type ScannedRoute } from '../src/compiler/routes';
+
+describe('fillPattern', () => {
+    it('substitutes :param and *catch-all segments', () => {
+        expect(fillPattern('/:a/:b/:c', { a: 'x', b: 'y', c: 'z' })).toBe('/x/y/z');
+        expect(fillPattern('/blog/:id', { id: '42' })).toBe('/blog/42');
+        expect(fillPattern('/docs/*slug', { slug: ['a', 'b'] })).toBe('/docs/a/b');
+        expect(fillPattern('/static', {})).toBe('/static');
+    });
+});
+
+describe('sitemapXml with SSG paths', () => {
+    const seo: SeoConfig = { url: 'https://x.dev' };
+    const routes: ScannedRoute[] = [
+        { file: 'a', pattern: '/' },
+        { file: 'b', pattern: '/about' },
+        { file: 'c', pattern: '/blog/:id' },
+    ];
+
+    it('lists static routes plus enumerated SSG URLs, deduped, never the bare pattern', () => {
+        const xml = sitemapXml(seo, routes, ['/blog/1', '/blog/2', '/about']);
+        expect(xml).toContain('https://x.dev/blog/1');
+        expect(xml).toContain('https://x.dev/blog/2');
+        expect(xml).toContain('https://x.dev/about');
+        expect(xml).not.toContain('/blog/:id'); // dynamic pattern is never listed literally
+        expect((xml.match(/<loc>[^<]*\/about<\/loc>/g) ?? []).length).toBe(1); // deduped
+    });
+
+    it('is empty without a base url', () => {
+        expect(sitemapXml({}, routes, ['/blog/1'])).toBe('');
+    });
+});