@techninja/clearstack 0.3.36 → 0.3.38

package/bin/cli.js

@@ -5,7 +5,9 @@
  * Usage:
  *   clearstack init [-y] [--static|--fullstack] [--port 3000]
  *   clearstack update [--force]
- *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
+ *   clearstack build [og|og-images|all] → generate OG pages and/or images
+ *   clearstack check [code|docs|imports|lint|format|types|audit|all]
+ *   clearstack report --json      → structured JSON output for tooling
  *   clearstack                   → interactive menu
  */
 
@@ -35,7 +37,8 @@ async function interactive() {
         { name: 'Initialize a new project', value: 'init' },
         { name: 'Update spec docs + configs', value: 'update' },
         { name: 'Run spec compliance check', value: 'check' },
-        { name: 'Build OG metadata pages', value: 'build' },
+        { name: 'Entropy report (drift summary)', value: 'report' },
+        { name: 'Build OG pages + images', value: 'build' },
       ],
     });
     await run(action);
@@ -60,15 +63,32 @@ async function run(action) {
     const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
     const { check } = await import('../lib/check.js');
     await check(process.cwd(), subs.join(' ') || undefined);
+  } else if (action === 'report') {
+    const { report } = await import('../lib/report.js');
+    report(process.cwd(), { json: !!flags.json });
   } else if (action === 'build') {
     const sub = args.find((a) => a !== 'build' && !a.startsWith('-'));
-    const { buildOG } = await import('../lib/build-og.js');
-    if (!sub || sub === 'og') {
+    if (sub === 'og-images' || sub === 'images') {
+      const mod = await import('../lib/build-og-images.js');
+      const common = { projectDir: process.cwd(), outDir: flags.out || 'dist', logo: flags.logo || '', siteName: flags.site || '' };
+      if (flags.slug) await mod.buildOneOGImage({ ...common, slug: flags.slug });
+      else await mod.buildOGImages(common);
+    } else {
+      const { buildOG } = await import('../lib/build-og.js');
       buildOG({
         projectDir: process.cwd(),
         outDir: flags.out || 'dist',
         baseUrl: flags.url || '',
       });
+      if (sub === 'all') {
+        const { buildOGImages } = await import('../lib/build-og-images.js');
+        await buildOGImages({
+          projectDir: process.cwd(),
+          outDir: flags.out || 'dist',
+          logo: flags.logo || '',
+          siteName: flags.site || '',
+        });
+      }
     }
   } else {
     console.log('Usage: clearstack [init|update|check|build] [-y]');

package/docs/OG_METADATA_SPEC.md

@@ -8,73 +8,120 @@ only read static HTML — they don't execute JavaScript. Since Clearstack apps a
 SPAs with a single `index.html`, every shared link shows the same generic
 metadata regardless of the actual page content.
 
-This is a baseline expectation for any web project in 2025. If your link preview
-looks sketchy, people don't click.
-
-## Proposal
+## Solution
+
+Clearstack generates two things from the route config:
+
+1. **Static HTML shells** with OG meta tags (for crawlers)
+2. **Dynamic OG images** (1200×630 PNGs rendered via Playwright)
+
+Both are driven by the same `clearstack.routes.json` config and data sources.
+
+## Route Config
+
+```json
+{
+  "/trait/:slug": {
+    "title": "{slug.name}",
+    "description": "{slug.description}",
+    "image": "{slug.cover_image.url}",
+    "data": "src/data/trait_manifest.json:traits",
+    "ogTemplate": "trait"
+  },
+  "/shop/product/:sku": {
+    "title": "{sku.name} | {store.name}",
+    "description": "{sku.description}",
+    "image": "{store.url}{sku.images.0}",
+    "data": "src/data/products.json",
+    "ogTemplate": "product"
+  }
+}
+```
 
-Clearstack already requires routes to be defined in the app spec with metadata
-(title, description). The build system should use this to generate static HTML
-shells for each route — just enough for crawlers to read OG tags, while the SPA
-still handles rendering for real users.
+### Fields
 
-## How it should work
+| Field          | Required | Description                                             |
+| -------------- | -------- | ------------------------------------------------------- |
+| `title`        | yes      | Template string with `{path.to.data}` interpolation     |
+| `description`  | yes      | Template string for meta description                    |
+| `image`        | no       | Template string for og:image URL                        |
+| `data`         | no       | Data source — `filepath:jsonPath` (supports arrays/objects) |
+| `ogTemplate`   | no       | Template name → resolves to `src/og-templates/{name}.html`  |
 
-1. **Spec defines routes with metadata:**
+### Data Sources
 
-   ```yaml
-   routes:
-     /traits/:id:
-       title: '{trait.emoji} {trait.name} | {app.name}'
-       description: '{trait.description}'
-       image: '{trait.cover_image.url}'
-       data: trait_manifest.traits
-   ```
+- **Arrays** — each item becomes a page
+- **Objects** — entries become arrays with the key set as `slug`
+- **JSON path** — dot notation into nested structures (e.g. `manifest.json:traits`)
 
-2. **Build reads the spec + data sources:**
-   - For static routes (`/about`, `/pricing`): generate one HTML file
-   - For dynamic routes (`/traits/:id`): iterate over the data source, generate
-     one HTML file per entry
+## OG Image Templates
 
-3. **Generated HTML contains:**
-   - Correct `<title>` and `<meta name="description">`
-   - `og:title`, `og:description`, `og:image`, `og:url`
-   - `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`
-   - The same `<body>` as index.html (SPA takes over client-side)
+Templates are HTML files at `src/og-templates/` rendered by Playwright at
+1200×630 and screenshotted to PNG.
 
-4. **Deploy serves these files:**
-   - Cloudflare Pages / Netlify / Vercel serve the static file if it exists
-   - Falls back to `404.html` (SPA) for routes without generated pages
+### Resolution Order
 
-## Requirements
+1. `src/og-templates/{ogTemplate}.html` (route-specific)
+2. `src/og-templates/default.html` (project default)
+3. Built-in default (gradient card with title/description)
 
-- Zero config for basic cases (route title + description → OG tags)
-- Opt-in image support (from data source or static asset)
-- Works with any deploy target that supports static files + SPA fallback
-- Doesn't require a server or edge function
-- Build is fast (64 pages in <1s, 648 pages in <5s)
+### Template Conventions
 
-## Prior art
+- Use `{tokenName}` interpolation for data (word chars + dots only)
+- Local assets (`src="/logo.svg"`) are inlined as data URIs automatically
+- Remote images (`https://...`) load via Playwright's network
+- CSS custom properties from project tokens are injected into context
+- Available computed fields: `{variantsFormatted}`, `{uniqueFormatted}`
 
-- Asili's `scripts/build-og.js` — generates 64 trait pages from manifest data
-- Next.js `generateMetadata` — server-side, requires Node runtime
-- Astro content collections — static generation from markdown frontmatter
+### Available Context Variables
 
-## Implementation notes
+| Variable             | Source                              |
+| -------------------- | ----------------------------------- |
+| `{title}`            | Resolved + truncated route title    |
+| `{description}`      | Resolved + truncated description    |
+| `{image}`            | Resolved image URL                  |
+| `{emoji}`            | From item data                      |
+| `{bg}`, `{primary}`  | From project CSS tokens             |
+| `{variantsFormatted}`| Formatted number (K/M suffix)       |
+| All item fields      | Spread directly (e.g. `{name}`, `{pgs_count}`) |
 
-This could be a `clearstack build` subcommand or a plugin:
+## CLI Commands
 
 ```bash
-clearstack build og          # Generate OG pages from spec
-clearstack build             # Full build including OG
+# Generate OG HTML pages (for crawlers)
+clearstack build og --url=https://mysite.com --out=dist
+
+# Generate OG images (all routes)
+clearstack build og-images --site=MySite --out=dist
+
+# Generate a single image (fast iteration)
+clearstack build og-images --slug=EFO_0004279 --site=MySite --out=dist/og
+
+# Generate both HTML + images
+clearstack build all --url=https://mysite.com --site=MySite --out=dist
 ```
 
-The spec parser already knows all routes. The data source connection is the new
-piece — reading from JSON manifests, markdown frontmatter, or API responses at
-build time.
+### Flags
+
+| Flag       | Description                          |
+| ---------- | ------------------------------------ |
+| `--out`    | Output directory (default: `dist`)   |
+| `--url`    | Base URL for og:url tags             |
+| `--site`   | Site name for badge/branding         |
+| `--logo`   | Logo path or URL                     |
+| `--slug`   | Single item slug (fast iteration)    |
+
+## Requirements
+
+- Zero config for basic cases (route title + description → OG tags)
+- Custom templates per page type via `ogTemplate` field
+- Design tokens (CSS variables) automatically available in templates
+- Local assets inlined as data URIs (no file:// security issues)
+- Fast iteration: `--slug` flag renders one image in ~2s
+- Full batch: 64 pages in <60s
+- Works with any static deploy target (Cloudflare Pages, Netlify, Vercel)
 
-## Open questions
+## Dependencies
 
-- Should this live in core clearstack or as an optional plugin?
-- How to handle routes that need auth/user data (skip them? generic fallback?)
-- Image generation (dynamic OG images with text overlay) — future scope?
+- **Playwright** (devDependency) — for OG image rendering
+- No runtime dependencies — generated files are static PNGs + HTML

package/docs/SPEC_WORKFLOW.md

@@ -0,0 +1,116 @@
+# Spec Workflow: LLM Sessions & Compliance
+
+## The Problem
+
+LLM coding sessions move fast. Features emerge through rapid iteration,
+and stopping to run `npm run spec` after every file edit creates friction
+that kills creative velocity. But ignoring the spec entirely leads to
+a costly batch refactor at the end — splitting files, fixing lint, and
+chasing type errors across dozens of changes.
+
+## The Balance: Feature Checkpoints
+
+Don't run spec after every change. Don't ignore it until deploy. Instead,
+run spec at **natural feature boundaries**:
+
+```
+Feature unit complete → npm run spec code
+Section complete → npm run spec all
+Pre-deploy → npm run spec all + types
+```
+
+A "feature unit" is a logical chunk: "media grid view works," "portfolio
+section complete," "name correction system done." Not every file save.
+
+## Project Rules for LLM Context
+
+The biggest spec compliance gap is **the LLM not knowing the rules exist.**
+Spec docs live in `docs/` but aren't automatically loaded into session
+context. Fix this with a project-level rules file:
+
+```
+.amazonq/rules/clearstack.md   # Loaded every session automatically
+```
+
+This file should state:
+
+- The 150-line limit and what to do at 120 lines
+- Decomposition patterns (what to extract when)
+- Code style enforcement (so the LLM writes compliant code from the start)
+- The assumption that spec watch may be running
+
+When an LLM knows the constraint exists, it naturally writes smaller
+files, adds `SPLIT CANDIDATE` comments, and avoids patterns that will
+need refactoring later.
+
+## The SPLIT CANDIDATE Pattern
+
+When a file passes ~120 lines during development:
+
+```javascript
+// SPLIT CANDIDATE: keyboard handler → utils/mediaKeys.js
+// SPLIT CANDIDATE: carousel template → utils/mediaCarousel.js
+```
+
+These comments serve two purposes:
+
+1. Signal to the current session where to split if the file goes over
+2. Signal to a future session exactly how to decompose without re-reading
+
+## Spec Watch Mode (Proposed)
+
+A dashboard that runs continuously during development:
+
+```bash
+npm run spec --watch
+```
+
+Displays a compact status board:
+
+```
+  ✅ code (67 files)
+  ✅ lint (44 files)
+  ⚠️  types (1 warning)
+  ✅ docs (12 files)
+```
+
+When a violation occurs, it shows the error inline and provides a
+copy-pasteable block the developer can drop into their LLM session:
+
+```
+  ❌ code: src/pages/media/media-detail-view.js (167 lines, max 150)
+     Split candidates: L45 data loading, L89 carousel template, L140 related grid
+```
+
+This gives the LLM everything it needs to fix the issue without running
+the check itself, re-reading the file, or guessing at the structure.
+
+## Automated Ignore Configuration
+
+The spec checker should manage ignore paths centrally rather than
+requiring manual duplication across eslint, prettier, stylelint, and
+jsconfig. A single `SPEC_IGNORE_DIRS` in `.env` should propagate to
+all tools automatically, or the spec checker should inject ignores
+when running each tool.
+
+Current pain: adding `src/space/` required editing 5 different config
+files. It should require editing one.
+
+## Decomposition Patterns for Views
+
+View components (page-level) are the most common files to exceed 150
+lines because they combine: imports, data loading, state management,
+keyboard handlers, and large template literals.
+
+Extraction priority (most reusable → most specific):
+
+| What to extract | Where to put it | When |
+|----------------|-----------------|------|
+| Data loading/caching | `src/utils/{feature}Loader.js` | >20 lines of fetch/transform |
+| Keyboard/event handlers | `src/utils/{feature}Keys.js` | >10 lines of handler logic |
+| Repeated template fragments | `src/utils/{feature}Template.js` | Used in 2+ views |
+| Render sub-sections | `src/utils/{feature}Render.js` | Single view, but >30 lines |
+| Shared UI (header, breadcrumb) | `src/components/` | Used site-wide |
+
+The goal isn't to have zero logic in view files — it's to keep each
+file answerable with "what does this do?" in one pass.

package/docs/app-spec/SPEC_WATCH_PROPOSAL.md

@@ -0,0 +1,80 @@
+# Spec Watch Dashboard Mode
+
+## Summary
+
+A continuous-running spec compliance dashboard for development that
+displays real-time status and produces LLM-friendly output on violations.
+
+## Command
+
+```bash
+clearstack check --watch     # or: npm run spec --watch
+```
+
+## Display
+
+Compact terminal dashboard, updates on file changes:
+
+```
+┌─ Clearstack Spec Watch ─────────────────────────┐
+│  ✅ code    67 files    all ≤150 lines           │
+│  ✅ lint    44 files    0 errors                 │
+│  ✅ types   44 files    0 errors                 │
+│  ✅ docs    12 files    all ≤500 lines           │
+│                                                  │
+│  watching src/ scripts/ docs/                    │
+│  last check: 2s ago                              │
+└──────────────────────────────────────────────────┘
+```
+
+On violation:
+
+```
+┌─ Clearstack Spec Watch ─────────────────────────┐
+│  ❌ code    1 violation                          │
+│  ✅ lint    44 files                             │
+│  ✅ types   44 files                             │
+│  ✅ docs    12 files                             │
+│                                                  │
+│  ─── Copy below into your LLM session ───       │
+│                                                  │
+│  src/pages/media/media-detail-view.js            │
+│  167 lines (max 150, +17 over)                   │
+│  Split candidates:                               │
+│    L15-42: data loading → utils/mediaLoader.js   │
+│    L58-89: carousel render → utils/carousel.js   │
+│    L140-167: related grid → utils/related.js     │
+│                                                  │
+└──────────────────────────────────────────────────┘
+```
+
+## Key Design Decisions
+
+- **LLM-friendly output**: The violation block is designed to be
+  copy-pasted into a chat session. It contains file path, line numbers,
+  exact overage, and actionable split suggestions.
+
+- **Split candidate detection**: Reads `// SPLIT CANDIDATE:` comments
+  from the file. If none exist, uses heuristics (comment headers,
+  export boundaries, function declarations) to suggest seams.
+
+- **Debounced**: Doesn't re-check on every keystroke. Waits 500ms after
+  last file change, then runs only the relevant check (code check for
+  .js/.css changes, lint for .js changes, etc).
+
+- **No blocking**: Never prevents saves or interrupts workflow. It's
+  purely informational — a dashboard you glance at.
+
+## Implementation Notes
+
+- Use `fs.watch` or chokidar for file watching
+- Re-run only affected checks (file changed → which check cares?)
+- Terminal UI via basic ANSI escape codes (no heavy TUI library)
+- Exit with Ctrl+C, summary of current state on exit
+
+## Integration with IDE
+
+If the user's IDE has a terminal panel, this runs there. The
+"copy below" block is the key UX innovation — it bridges the gap
+between the spec checker (which knows the problem) and the LLM
+(which can fix it but needs context).

package/lib/build-og-images.js

@@ -0,0 +1,122 @@
+/**
+ * OG image generator — renders HTML templates with Playwright, saves PNGs.
+ * Generates 1200×630 social preview images per route from the same data
+ * sources used by the OG HTML page builder.
+ * @module lib/build-og-images
+ */
+
+import { mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { loadRoutes, resolveDataSource } from './build-og.js';
+import { resolveTemplate, renderTemplate, buildContext, loadTokens, WIDTH, HEIGHT } from './og-image-template.js';
+
+/**
+ * @typedef {Object} BuildOGImagesOptions
+ * @property {string} projectDir
+ * @property {string} [outDir] - Default: "dist"
+ * @property {string} [logo] - Path or URL to logo
+ * @property {string} [siteName] - Site name for badge
+ * @property {Record<string, unknown>} [context] - Extra interpolation data
+ */
+
+/**
+ * Generate OG images for all configured routes.
+ * @param {BuildOGImagesOptions} opts
+ * @returns {Promise<{ images: number, routes: number }>}
+ */
+export async function buildOGImages(opts) {
+  const { projectDir, outDir = 'dist', logo, siteName, context = {} } = opts;
+  const routes = loadRoutes(projectDir);
+  if (!routes) {
+    console.log('⚠ No routes config found. Create clearstack.routes.json');
+    return { images: 0, routes: 0 };
+  }
+
+  const tokens = loadTokens(projectDir);
+  const site = { tokens, logo, siteName };
+  const start = performance.now();
+
+  const { chromium } = await import('playwright');
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });
+  const out = resolve(projectDir, outDir);
+  let images = 0;
+
+  for (const [pattern, config] of Object.entries(routes)) {
+    const template = resolveTemplate(projectDir, config.ogTemplate);
+    const isDynamic = pattern.includes(':');
+
+    if (!isDynamic) {
+      const data = { app: { name: siteName }, ...context };
+      const ctx = buildContext(config, data, site);
+      await screenshot(page, renderTemplate(template, ctx, projectDir), out, pattern);
+      images++;
+    } else if (config.data) {
+      const items = resolveDataSource(config.data, projectDir);
+      const paramName = pattern.match(/:(\w+)/)?.[1] || 'id';
+      for (const item of items) {
+        const slug = item.slug || item.id || item.sku || item[paramName];
+        if (!slug) continue;
+        const path = pattern.replace(`:${paramName}`, String(slug));
+        const data = { [paramName]: item, item, app: { name: siteName }, ...context };
+        const ctx = buildContext(config, data, site);
+        await screenshot(page, renderTemplate(template, ctx, projectDir), out, path);
+        images++;
+      }
+    }
+  }
+
+  await browser.close();
+  const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+  console.log(`✅ Generated ${images} OG images from ${Object.keys(routes).length} route(s) (${elapsed}s)`);
+  return { images, routes: Object.keys(routes).length };
+}
+
+/**
+ * Build a single OG image for one slug (fast iteration).
+ * @param {BuildOGImagesOptions & { slug: string }} opts
+ * @returns {Promise<string>} Path to generated image
+ */
+export async function buildOneOGImage(opts) {
+  const { projectDir, outDir = 'dist', logo, siteName, slug, context = {} } = opts;
+  const routes = loadRoutes(projectDir);
+  if (!routes) throw new Error('No routes config found');
+
+  const tokens = loadTokens(projectDir);
+  const site = { tokens, logo, siteName };
+  const { chromium } = await import('playwright');
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });
+  const out = resolve(projectDir, outDir);
+  let result = '';
+
+  for (const [pattern, config] of Object.entries(routes)) {
+    if (!pattern.includes(':') || !config.data) continue;
+    const template = resolveTemplate(projectDir, config.ogTemplate);
+    const items = resolveDataSource(config.data, projectDir);
+    const paramName = pattern.match(/:(\w+)/)?.[1] || 'id';
+    const item = items.find((i) => (i.slug || i.id || i.sku) === slug);
+    if (!item) continue;
+    const path = pattern.replace(`:${paramName}`, String(slug));
+    const data = { [paramName]: item, item, app: { name: siteName }, ...context };
+    const ctx = buildContext(config, data, site);
+    await screenshot(page, renderTemplate(template, ctx, projectDir), out, path);
+    result = resolve(out, path.slice(1) + '.png');
+    break;
+  }
+
+  await browser.close();
+  if (result) console.log(`✅ ${result}`);
+  else console.log(`⚠ Slug "${slug}" not found in any route data`);
+  return result;
+}
+
+/** Render HTML content and save screenshot to disk. */
+async function screenshot(page, html, outDir, routePath) {
+  await page.setContent(html, { waitUntil: 'networkidle' });
+  const imgPath = routePath === '/'
+    ? resolve(outDir, 'og-image.png')
+    : resolve(outDir, routePath.slice(1) + '.png');
+  mkdirSync(dirname(imgPath), { recursive: true });
+  await page.screenshot({ path: imgPath, type: 'png' });
+}

package/lib/build-og.js

@@ -10,26 +10,17 @@ import { injectMeta, interpolate } from './og-template.js';
 
 /**
  * @typedef {Object} RouteConfig
- * @property {string} title - Template string, e.g. "{trait.name} | My App"
- * @property {string} description - Template string
- * @property {string} [image] - Template string for og:image
- * @property {string} [data] - Dot-path to JSON data source, e.g. "traits.json:traits"
+ * @property {string} title @property {string} description
+ * @property {string} [image] @property {string} [data] @property {string} [ogTemplate]
  */
 
 /**
  * @typedef {Object} BuildOGOptions
- * @property {string} projectDir - Project root
- * @property {string} [outDir] - Output directory (default: "dist")
- * @property {string} [baseUrl] - Site base URL for og:url
- * @property {string} [htmlPath] - Path to index.html shell
- * @property {Record<string, unknown>} [context] - Extra data for interpolation
+ * @property {string} projectDir @property {string} [outDir] @property {string} [baseUrl]
+ * @property {string} [htmlPath] @property {Record<string, unknown>} [context]
  */
 
-/**
- * Load route config from clearstack.routes.json or package.json.
- * @param {string} projectDir
- * @returns {Record<string, RouteConfig> | null}
- */
+/** Load route config from clearstack.routes.json or package.json. */
 export function loadRoutes(projectDir) {
   const routesFile = resolve(projectDir, 'clearstack.routes.json');
   if (existsSync(routesFile)) {
@@ -45,10 +36,7 @@ export function loadRoutes(projectDir) {
 
 /**
  * Resolve a data source reference like "data/traits.json:traits".
- * Format: "filepath:jsonPath" where jsonPath is dot-notation into the file.
- * @param {string} ref
- * @param {string} projectDir
- * @returns {unknown[]}
+ * Supports arrays and objects (objects become arrays with key as slug).
  */
 export function resolveDataSource(ref, projectDir) {
   const [filePart, ...pathParts] = ref.split(':');
@@ -56,16 +44,15 @@ export function resolveDataSource(ref, projectDir) {
   const filePath = resolve(projectDir, filePart);
   if (!existsSync(filePath)) return [];
   const content = JSON.parse(readFileSync(filePath, 'utf-8'));
-  if (!jsonPath) return Array.isArray(content) ? content : [content];
-  const data = jsonPath.split('.').reduce((obj, key) => obj?.[key], content);
-  return Array.isArray(data) ? data : [];
+  const data = jsonPath ? jsonPath.split('.').reduce((obj, key) => obj?.[key], content) : content;
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === 'object') {
+    return Object.entries(data).map(([key, val]) => ({ slug: key, ...val }));
+  }
+  return [data];
 }
 
-/**
- * Generate OG pages for all configured routes.
- * @param {BuildOGOptions} opts
- * @returns {{ pages: number, routes: number }}
- */
+/** Generate OG pages for all configured routes. */
 export function buildOG(opts) {
   const { projectDir, outDir = 'dist', baseUrl = '', htmlPath } = opts;
   const routes = loadRoutes(projectDir);
@@ -112,13 +99,7 @@ export function buildOG(opts) {
   return { pages, routes: Object.keys(routes).length };
 }
 
-/**
- * Resolve meta from config + data context.
- * @param {RouteConfig} config
- * @param {Record<string, unknown>} data
- * @param {string} baseUrl
- * @param {string} path
- */
+/** Resolve meta from config + data context. */
 function resolveMeta(config, data, baseUrl, path) {
   return {
     title: interpolate(config.title, data),
@@ -128,17 +109,16 @@ function resolveMeta(config, data, baseUrl, path) {
   };
 }
 
-/**
- * Write a single HTML page to the output directory.
- * @param {string} outDir
- * @param {string} routePath
- * @param {string} shell
- * @param {import('./og-template.js').OGMeta} meta
- */
+/** Write a single HTML page to the output directory. */
 function writePage(outDir, routePath, shell, meta) {
-  const filePath = routePath.endsWith('/')
-    ? resolve(outDir, routePath.slice(1), 'index.html')
-    : resolve(outDir, routePath.slice(1), 'index.html');
+  let filePath;
+  if (routePath === '/') {
+    filePath = resolve(outDir, 'index.html');
+  } else {
+    // Write as flat file (e.g. /dna-sources → dna-sources.html)
+    // Cloudflare Pages serves dna-sources.html for /dna-sources without redirect
+    filePath = resolve(outDir, routePath.slice(1) + '.html');
+  }
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, injectMeta(shell, meta));
 }