dommief 0.1.0 → 0.1.2

package/src/markdown/remark-meta.ts

@@ -0,0 +1,73 @@
+import yaml from 'yaml';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import Slugger from 'github-slugger';
+import { visit } from 'unist-util-visit';
+import type { TocItem } from './index.js';
+
+export interface RemarkMetaOptions { filename?: string; }
+
+function textOf(node: any): string {
+  let out = '';
+  if (node.type === 'text') out += node.value || '';
+  if (node.children) for (const c of node.children) out += textOf(c);
+  return out;
+}
+
+/** Parser frontmatter dùng chung (yaml thật, không phải regex tự chế — tránh #12). */
+export function parseFrontmatterYaml(raw: string, opts: { file?: string; onWarn?: (msg: string) => void } = {}): Record<string, unknown> {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m || m[1] === undefined) return {};
+  try {
+    return (yaml.parse(m[1]) as Record<string, unknown>) ?? {};
+  } catch (e) {
+    opts.onWarn?.(`frontmatter_invalid_yaml: ${opts.file ?? ''}: ${(e as Error).message}`);
+    return {};
+  }
+}
+
+export function remarkMeta(options: RemarkMetaOptions = {}) {
+  return (tree: any, file: any) => {
+    const filename = options.filename ?? file?.path ?? file?.history?.[0] ?? '';
+    file.data = file.data || {};
+    // frontmatter: cùng một parser với `parseFrontmatterYaml` (#12) — không tự gọi `yaml.parse` lần thứ hai ở đây.
+    let frontmatter: Record<string, unknown> = {};
+    if (tree.children?.[0]?.type === 'yaml') {
+      frontmatter = parseFrontmatterYaml('---\n' + tree.children[0].value + '\n---', { file: filename });
+      tree.children.shift();
+    }
+    // title fallback from first h1
+    if (frontmatter.title == null) {
+      let firstH1: string | null = null;
+      visit(tree, 'heading', (node: any) => {
+        if (node.depth === 1 && firstH1 === null) firstH1 = textOf(node).trim();
+      });
+      if (firstH1) frontmatter.title = firstH1;
+    }
+    file.data.frontmatter = frontmatter;
+    file.data.filename = filename;
+  };
+}
+
+/**
+ * `frontmatter` + `toc` NHẸ cho `virtual:dommief/site` (#12): chỉ `remark-parse`, không chạy cả
+ * pipeline rehype (docgen `<API>`, demo, slug...). Dùng cùng logic title-fallback và cùng
+ * `parseFrontmatterYaml` với `remarkMeta`/`transformMarkdown` — một nguồn sự thật cho "title của trang là gì".
+ */
+export function extractPageSummary(raw: string, file: string, onWarn?: (msg: string) => void): { frontmatter: Record<string, unknown>; toc: TocItem[] } {
+  const frontmatter = parseFrontmatterYaml(raw, onWarn ? { file, onWarn } : { file });
+  const tree = unified().use(remarkParse).use(remarkFrontmatter, ['yaml']).parse(raw);
+  const toc: TocItem[] = [];
+  const slugger = new Slugger();
+  let firstH1: string | null = null;
+  visit(tree, 'heading', (node: any) => {
+    const title = textOf(node).trim();
+    if (!title) return;
+    const id = slugger.slug(title);
+    toc.push({ id, depth: node.depth, title });
+    if (node.depth === 1 && firstH1 === null) firstH1 = title;
+  });
+  if (frontmatter.title == null && firstH1) frontmatter.title = firstH1;
+  return { frontmatter, toc };
+}

package/src/markdown/to-module.ts

@@ -0,0 +1,35 @@
+import { toEstree } from 'hast-util-to-estree';
+import { toJs, jsx } from 'estree-util-to-js';
+
+/** Specifier mà plugin `dommief:markdown` resolve về `client/index.tsx` của package. */
+export const CLIENT_MODULE = 'dommief/client';
+
+export interface ModuleImage { name: string; specifier: string }
+
+export function toModule(hast: any, meta: { frontmatter: unknown; toc: unknown; texts?: unknown }, images: ModuleImage[] = [], demos: { id: string; source: string; src?: string }[] = []): string {
+  // `texts` chỉ dùng để build search index lúc build (buildSearchIndex nhận trực tiếp PageMeta từ
+  // transformMarkdown, không đọc export này) — bỏ khỏi bundle gửi cho trình duyệt (#20).
+  const { texts: _texts, ...clientMeta } = meta;
+  const estree = toEstree(hast, { elementAttributeNameCase: 'react' }) as any;
+  const { value: code } = toJs(estree, { handlers: jsx });
+  let body = code.replace(/;\s*$/, '').trim();
+  const imageImports = images.map((im, i) => {
+    body = body.split(`src="${im.name}"`).join(`src={__dmImg${i}}`);
+    return `import __dmImg${i} from ${JSON.stringify(im.specifier)};\n`;
+  }).join('');
+  const used = ['DomDemo', 'DumiDemo', 'DomApi', 'DumiApi'].filter((n) => new RegExp(`<${n}[\\s/>]`).test(body));
+  const clientNames = [...used];
+  if (demos.length) clientNames.push('registerDemo');
+  const clientImport = clientNames.length ? `import { ${Array.from(new Set(clientNames)).join(', ')} } from '${CLIENT_MODULE}';\n` : '';
+  const demoImports = demos.map((d) => {
+    const specifier = d.src ? d.src : `virtual:dommief-demo/${d.id}`;
+    return `import Demo_${d.id} from ${JSON.stringify(specifier)};\n`;
+  }).join('');
+  const demoRegs = demos.map((d) => `registerDemo(${JSON.stringify(d.id)}, Demo_${d.id});\n`).join('');
+  return `import React from 'react';
+${imageImports}${clientImport}${demoImports}${demoRegs}export default function Content(){ return (
+${body}
+); }
+export const meta = ${JSON.stringify(clientMeta)};
+`;
+}

package/src/paths.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { DommiefError } from './markdown/errors.js';
+
+/**
+ * Tìm file trong `client/` của chính package này. Từ source (`src/*.ts`) file nằm ở `./client/`;
+ * từ bản build (`dist/*.js`, tsup gộp mọi thứ vào một cấp) nằm ở `../src/client/`.
+ * Ném lỗi có tên nếu cả hai đều không có — thay vì để Vite báo UNRESOLVED_ENTRY khó hiểu.
+ */
+export function resolveClientFile(name: string): string {
+  const candidates = [`./client/${name}`, `../src/client/${name}`].map((rel) => fileURLToPath(new URL(rel, import.meta.url)));
+  const hit = candidates.find((p) => fs.existsSync(p));
+  if (!hit) {
+    throw new DommiefError(`không tìm thấy client/${name} của dommief (đã thử: ${candidates.join(', ')}). Package cài thiếu thư mục "src".`, { code: 'client_entry_missing' });
+  }
+  return hit;
+}
+
+/**
+ * Absolute path tới `theme-api.tsx` NGUỒN (không phải `dist/theme-api.js`).
+ *
+ * Quan trọng: `package.json` export `./theme-api` trỏ `dist/theme-api.js`, nhưng `entry-client`/
+ * `entry-server` (bản thân `dommief/client`, luôn là SOURCE) import `theme-api` qua đường dẫn
+ * tương đối `../theme-api.js` — tức là SOURCE. Nếu theme-default import `dommief/theme-api`
+ * (qua alias package) mà Vite resolve ra `dist/theme-api.js`, đó là MỘT module KHÁC với
+ * `SiteContext`/`createContext` riêng — `SiteProvider` (trong entry) set context nguồn, còn
+ * `useSiteData()` (trong theme, qua dist) đọc context đích khác, luôn `null`. Hậu quả quan
+ * sát được: `Navbar`/`Sidebar` render rỗng dù `virtual:dommief/site` có đầy đủ dữ liệu.
+ * Vite plugin phải alias `dommief/theme-api` → đúng file này để luôn chỉ có MỘT instance.
+ */
+export function resolveThemeApiFile(): string {
+  const candidates = ['./theme-api.tsx', '../src/theme-api.tsx'].map((rel) => fileURLToPath(new URL(rel, import.meta.url)));
+  const hit = candidates.find((p) => fs.existsSync(p));
+  if (!hit) {
+    throw new DommiefError(`không tìm thấy theme-api.tsx của dommief (đã thử: ${candidates.join(', ')})`, { code: 'client_entry_missing' });
+  }
+  return hit;
+}

package/src/plugins.ts

@@ -0,0 +1,131 @@
+import type { Route } from './types.js';
+import { DommiefError } from './markdown/errors.js';
+import type { ResolvedConfig } from './config.js';
+
+export interface BuildEndContext {
+  config: ResolvedConfig;
+  outDir: string;
+  routes?: Route[];
+}
+
+export type DommiefPluginObject = {
+  name?: string;
+  /** Đồng bộ: hook phải được `tap` xong trước khi hàm trả về. */
+  setup?: (hooks: PluginHookHost) => void;
+  modifyConfig?: (config: unknown) => unknown;
+  modifyRoutes?: (routes: Route[]) => Route[] | void;
+  addRemarkPlugins?: () => unknown | unknown[];
+  addRehypePlugins?: () => unknown | unknown[];
+  addHtmlHeadTags?: () => string | string[] | void;
+  onBuildEnd?: (ctx: BuildEndContext) => void | Promise<void>;
+};
+
+export type PluginSetup = (hooks: PluginHookHost) => void;
+export type DommiefPlugin = DommiefPluginObject | PluginSetup;
+
+export class Hook<TArg = unknown, TResult = unknown> {
+  name: string;
+  constructor(name = '') { this.name = name; }
+  taps: { name: string; fn: (arg: TArg) => TResult | void | Promise<TResult | void> }[] = [];
+  tap(name: string, fn: (arg: TArg) => TResult | void | Promise<TResult | void>) {
+    this.taps.push({ name, fn });
+  }
+  call(arg: TArg): TArg {
+    let value: any = arg;
+    for (const t of this.taps) {
+      const r = (t.fn as any)(value);
+      if (r !== undefined) value = r;
+    }
+    return value as TArg;
+  }
+  async callAsync(arg: TArg): Promise<TArg> {
+    let value: any = arg;
+    for (const t of this.taps) {
+      const r = await (t.fn as any)(value);
+      if (r !== undefined) value = r;
+    }
+    return value as TArg;
+  }
+}
+
+export class PluginHookHost {
+  modifyConfig = new Hook<unknown, unknown>('modifyConfig' as any);
+  modifyRoutes = new Hook<Route[], Route[]>('modifyRoutes' as any);
+  addRemarkPlugins = new Hook<void, unknown[]>('addRemarkPlugins' as any);
+  addRehypePlugins = new Hook<void, unknown[]>('addRehypePlugins' as any);
+  addHtmlHeadTags = new Hook<void, string | string[]>('addHtmlHeadTags' as any);
+  onBuildEnd = new Hook<BuildEndContext, void>('onBuildEnd' as any);
+
+  applyModifyConfig(config: unknown): Record<string, unknown> {
+    return this.modifyConfig.call(config) as Record<string, unknown>;
+  }
+  applyModifyRoutes(routes: Route[]): Route[] {
+    const r = this.modifyRoutes.call(routes);
+    return (r as Route[]) ?? routes;
+  }
+  collectRemarkPlugins(): unknown[] {
+    const out: unknown[] = [];
+    for (const t of this.addRemarkPlugins.taps) {
+      const r = (t.fn as any)();
+      if (Array.isArray(r)) out.push(...r);
+      else if (r !== undefined && r !== null) out.push(r);
+    }
+    return out;
+  }
+  collectRehypePlugins(): unknown[] {
+    const out: unknown[] = [];
+    for (const t of this.addRehypePlugins.taps) {
+      const r = (t.fn as any)();
+      if (Array.isArray(r)) out.push(...r);
+      else if (r !== undefined && r !== null) out.push(r);
+    }
+    return out;
+  }
+  collectHtmlHeadTags(): string[] {
+    const out: string[] = [];
+    for (const t of this.addHtmlHeadTags.taps) {
+      const r = (t.fn as any)();
+      if (Array.isArray(r)) out.push(...r.map(String));
+      else if (r !== undefined && r !== null) out.push(String(r));
+    }
+    return out;
+  }
+  async runBuildEnd(ctx: BuildEndContext): Promise<void> {
+    for (const t of this.onBuildEnd.taps) {
+      await (t.fn as any)(ctx);
+    }
+  }
+}
+
+function assertSync(result: unknown, name: string): void {
+  if (result && typeof (result as { then?: unknown }).then === 'function') {
+    throw new DommiefError(`plugin "${name}": setup phải đồng bộ — hook tap sau \`await\` sẽ không bao giờ chạy`, { code: 'plugin_setup_async' });
+  }
+}
+
+export function registerPlugin(host: PluginHookHost, plugin: DommiefPlugin | null | undefined): void {
+  if (!plugin) return;
+  if (typeof plugin === 'function') {
+    assertSync((plugin as PluginSetup)(host), plugin.name || 'plugin');
+    return;
+  }
+  const p = plugin as DommiefPluginObject;
+  const name = p.name ?? 'plugin';
+  if (typeof p.setup === 'function') assertSync(p.setup(host), name); // không return: setup + hook khai báo cùng tồn tại
+  if (typeof p.modifyConfig === 'function') host.modifyConfig.tap(name, p.modifyConfig as any);
+  if (typeof p.modifyRoutes === 'function') host.modifyRoutes.tap(name, p.modifyRoutes as any);
+  if (typeof p.addRemarkPlugins === 'function') host.addRemarkPlugins.tap(name, p.addRemarkPlugins as any);
+  if (typeof p.addRehypePlugins === 'function') host.addRehypePlugins.tap(name, p.addRehypePlugins as any);
+  if (typeof p.addHtmlHeadTags === 'function') host.addHtmlHeadTags.tap(name, p.addHtmlHeadTags as any);
+  if (typeof p.onBuildEnd === 'function') host.onBuildEnd.tap(name, p.onBuildEnd as any);
+}
+
+export function createPluginHost(plugins: unknown[] = []): PluginHookHost {
+  const host = new PluginHookHost();
+  for (const p of plugins ?? []) registerPlugin(host, p as DommiefPlugin);
+  return host;
+}
+
+export function definePlugin(plugin: DommiefPlugin): DommiefPlugin {
+  return plugin;
+}

package/src/prefers-color.ts

@@ -0,0 +1,28 @@
+// Hằng số + hàm thuần (KHÔNG import 'react') cho cơ chế dark mode (THEME-API §7.6, §9.2).
+//
+// LÝ DO TÁCH FILE RIÊNG (đã crash thật, không phải suy đoán): `vite/plugin.ts` chạy TRỰC TIẾP
+// trong tiến trình Node của CLI (build-time), không qua bundle SSR của Vite. Nếu nó `import`
+// thẳng từ `theme-api.tsx` (file có JSX + hook `react`), react bị nạp vào TIẾN TRÌNH CLI qua một
+// đường resolve khác với bản mà `server.mjs` (nạp bằng `import()` động sau khi Vite build xong)
+// dùng để `renderToPipeableStream` — kết quả: `TypeError: dispatcher.getOwner is not a function`
+// (hai "bản" react không chia sẻ cùng dispatcher nội bộ). `theme-api.tsx` import lại từ đây để
+// không trùng lặp định nghĩa, nhưng bản thân file này không bao giờ được import 'react'.
+export type ColorValue = 'light' | 'dark';
+export type PrefersColorValue = ColorValue | 'auto';
+
+export const PREFERS_COLOR_ATTR = 'data-prefers-color';
+export const PREFERS_COLOR_STORAGE_KEY = 'dommief:prefers-color';
+
+/**
+ * Inline script < 1KB, không `async`/`defer` (DM-510 tiêu chí #1), chạy TRƯỚC paint để không
+ * nháy sáng rồi sang tối (FOUC). Chỉ **ghi đè** khi `localStorage` có lựa chọn (THEME-API
+ * Amendment 2026-10-22 #1): giá trị mặc định từ config đã được SSR render thẳng vào
+ * `<html data-prefers-color>` (xem vite/plugin.ts), nên trang vẫn đúng màu khi tắt JS.
+ */
+export const PREFERS_COLOR_BOOT_SCRIPT = `(function(){try{var k=${JSON.stringify(PREFERS_COLOR_STORAGE_KEY)},a=${JSON.stringify(PREFERS_COLOR_ATTR)},v=localStorage.getItem(k);if(v!=='light'&&v!=='dark'&&v!=='auto')return;var c=v==='auto'?(matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light'):v;document.documentElement.setAttribute(a,c)}catch(e){}})();`;
+
+/** `'auto'|'dark'|'light'` khác `'auto'` → màu áp dụng thật (để SSR render attribute trên `<html>`). */
+export function resolveConfiguredColor(defaultValue: PrefersColorValue | undefined): ColorValue | undefined {
+  if (!defaultValue || defaultValue === 'auto') return undefined; // 'auto' KHÔNG BAO GIỜ ghi vào attribute (§9.2)
+  return defaultValue;
+}

package/src/preview.ts

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { preview as vitePreview, type PreviewServer, type Connect, type Plugin } from 'vite';
+import { DommiefError } from './markdown/errors.js';
+
+// Đặc tả: docs/backlog/DM-411.md. Dùng `vite preview` thật (không tự viết static server) + SPA
+// fallback cho route bị `ssg.exclude` (shell không có `index.html` ĐÚNG NGHĨA — build.ts đã ghi
+// shell = template, nên thực ra MỌI route đều có file; fallback ở đây chỉ cần khi route không có
+// thư mục nào khớp, vd điều hướng client-side tới URL động chưa từng build).
+
+export interface PreviewOptions {
+  root: string;
+  base: string;
+  outDir: string;
+  port?: number;
+  host?: string | boolean;
+  open?: boolean;
+}
+
+/** Kiểm outDir TRƯỚC khi nghe cổng — preview không tự build (phải nhanh, tất định, "xem đúng cái vừa build"). */
+export function assertBuildOutput(outDir: string): void {
+  const indexHtml = path.join(outDir, 'index.html');
+  if (!fs.existsSync(outDir) || !fs.existsSync(indexHtml)) {
+    throw new DommiefError(`không có build output ở "${outDir}". Chạy \`dommief build\` trước.`, { code: 'no_build_output', file: outDir });
+  }
+}
+
+export async function startPreview(opts: PreviewOptions): Promise<PreviewServer> {
+  assertBuildOutput(opts.outDir);
+  const server = await vitePreview({
+    root: opts.root,
+    base: opts.base,
+    preview: {
+      ...(opts.port !== undefined ? { port: opts.port } : {}),
+      ...(opts.host !== undefined ? { host: opts.host } : {}),
+      ...(opts.open !== undefined ? { open: opts.open } : {}),
+    },
+    build: { outDir: opts.outDir },
+    plugins: [spaFallbackPlugin(opts)],
+  });
+  return server;
+}
+
+/**
+ * `configurePreviewServer` chỉ tồn tại trên `Plugin`, không phải trên `InlineConfig` trực tiếp
+ * — phải khai qua `plugins: [...]`.
+ *
+ * Middleware được cài TRỰC TIẾP trong hook (pre-hook), KHÔNG qua hàm trả về (post-hook): Vite
+ * preview có sẵn SPA fallback riêng (`htmlFallbackMiddleware`) chạy trước post-hook, và nó trả
+ * `index.html` GỐC cho mọi URL không có dấu `/` cuối — đã bắt trực tiếp: `/sub/guide/get-started`
+ * trả nội dung trang chủ trong khi `/sub/guide/get-started/` trả đúng trang. Static host thật
+ * (Netlify, Cloudflare Pages, nginx try_files) đều phục vụ `<dir>/index.html` cho URL không dấu `/`,
+ * nên preview phải làm đúng như vậy, nếu không người dùng sẽ thấy bug chỉ có ở preview.
+ *
+ * Thứ tự: file trùng route (`<rel>/index.html` hoặc `<rel>.html`) -> phục vụ file đó; asset
+ * (không phải request HTML) -> để static handler của Vite lo; còn lại (URL client-only chưa build)
+ * -> shell gốc để router client tự render.
+ */
+function spaFallbackPlugin(opts: PreviewOptions): Plugin {
+  const shellPath = path.join(opts.outDir, 'index.html');
+  const base = opts.base.replace(/\/$/, '');
+  const serveHtml = (res: ServerResponse, file: string, status = 200) => {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    fs.createReadStream(file).pipe(res);
+  };
+  return {
+    name: 'dommief:preview-spa-fallback',
+    configurePreviewServer(s) {
+      s.middlewares.use((req: IncomingMessage, res: ServerResponse, next: Connect.NextFunction) => {
+        // KHÔNG lọc theo header `Accept`: trong Node, `fetch()` mặc định gửi `Accept: */*`
+        // (không phải `text/html` như trong trình duyệt), nên lọc theo header sẽ bỏ qua middleware
+        // cho chính cách test (và nhiều HTTP client khác) gọi đến — đã bắt trực tiếp: với header
+        // lọc, `fetch('/sub/guide/get-started')` trả nhầm trang chủ (Vite fallback thay vì middleware
+        // này xử lý). Lọc theo đuôi file: bỏ qua request rõ ràng là asset (có đuôi khác .html).
+        let urlPath: string;
+        try {
+          urlPath = decodeURIComponent((req.url ?? '/').split('?')[0] ?? '/');
+        } catch {
+          res.statusCode = 400;
+          res.end('Invalid URL');
+          return;
+        }
+        if (req.method !== 'GET') return next();
+        // Ngoài base: TỰ trả 404, KHÔNG `next()` — static handler của Vite (sirv) không biết về
+        // `base`, nó phục vụ `index.html` ở gốc `outDir` cho BẤT KỲ path nào không khớp asset —
+        // đã bắt trực tiếp: `next()` khi path ngoài base trả nhầm 200 + trang chủ (tiêu chí
+        // §3: GET '/' với `base: '/sub/'` PHẢI không phải 200).
+        if (base && urlPath !== base && !urlPath.startsWith(base + '/')) {
+          res.statusCode = 404;
+          res.end('Not Found');
+          return;
+        }
+        const rel = base ? urlPath.slice(base.length) || '/' : urlPath;
+        // THử tìm file HTML khớp route TRƯỚC khi quyết định next(): heuristic đuôi file cũ
+        // (`/\.[a-z0-9]+$/`) coi mọi segment cuối có dấu chấm là asset, nên route thật kiểu
+        // `/guide/v1.2` hay `/api/node.js` bị rơi về static handler và nhận lại đúng bug
+        // trailing-slash đã sửa (chưa thử khhớp đã kết luận là asset). Dùng `path.resolve`
+        // (không phải so sánh chuỗi prefix) cho traversal guard: `/dist-evil` không được
+        // qua chỉ vì cùng tiền tố ký tự với `outDir`.
+        const outDirResolved = path.resolve(opts.outDir);
+        const safe = (p: string) => {
+          const r = path.resolve(p);
+          return r === outDirResolved || r.startsWith(outDirResolved + path.sep);
+        };
+        const candidates = [
+          path.join(opts.outDir, rel, 'index.html'),
+          path.join(opts.outDir, rel.endsWith('.html') ? rel : rel.replace(/\/$/, '') + '.html'),
+        ];
+        const hit = candidates.find((p) => safe(p) && fs.existsSync(p) && fs.statSync(p).isFile());
+        if (hit) return serveHtml(res, hit);
+        // Không khớp HTML nào: request có đuôi file rõ ràng (asset thật, vd .js/.css/.png) ->
+        // nhường static handler của Vite xử lý (404 thật nếu không tồn tại); còn lại -> shell
+        // (SPA fallback cho URL client-only chưa build).
+        if (/\.[a-z0-9]+$/i.test(rel.replace(/\.html$/i, ''))) return next();
+        // URL chưa từng build: static host thật (Netlify/CF Pages/GitHub Pages) phục vụ `404.html` với
+        // status 404, không phải trang chủ — phục vụ shell ở đây từng làm preview hydrate nội dung
+        // trang chủ ở URL lạ (React #418, bắt bằng e2e trình duyệt thật). Chỉ rơi về shell khi build
+        // không có 404.html (render 404 lỗi).
+        const notFound = path.join(opts.outDir, '404.html');
+        if (fs.existsSync(notFound)) { serveHtml(res, notFound, 404); return; }
+        serveHtml(res, shellPath);
+      });
+    },
+  };
+}

package/src/routes.ts

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { DommiefError } from './markdown/errors.js';
+import { winPath } from './utils/path.js';
+import type { ResolvedLocale, Route, RouteConfig, RouteTable } from './types.js';
+import { createPluginHost, type PluginHookHost } from './plugins.js';
+
+// Đặc tả: docs/spec/ROUTING.md §1–§5. Thứ tự bắt buộc trong normalizeRoutes:
+// locale → index/README → '.'→'/' → kebab → validate → trùng id/path.
+
+export interface RouteScan { routes: Route[]; warnings: string[] }
+
+const INDEX_NAMES = new Set(['index', 'README']); // case-sensitive (ROUTING §2.3.1)
+const SEGMENT_OK = /^[\p{L}\p{N}_-]+$/u;
+
+/**
+ * Liệt kê `*.md` (đuôi chữ thường; `.MD`/`.mdx` không nhận) dưới `dir`, absolute POSIX, đã sort.
+ * Bỏ tên bắt đầu bằng `.`/`_`, `node_modules`; không theo symlink.
+ */
+function listMarkdownFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith('.') || e.name.startsWith('_') || e.name === 'node_modules') continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile() && e.name.endsWith('.md')) out.push(winPath(p));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/** Route thô: `id` = đường dẫn tương đối docDir bỏ `.md`, `path` tạm = `/${id}`. */
+export function scanRoutes({ cwd, config }: { cwd: string; config: RouteConfig }): RouteScan {
+  const routes: Route[] = [];
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+  const docDirs = config.preset === 'library' && !(config.docDirs || []).some((d) => d.dir === 'src')
+    ? [...(config.docDirs || []), { dir: 'src' }]
+    : (config.docDirs || []);
+  for (const { dir } of docDirs) {
+    const absDir = path.resolve(cwd, dir);
+    if (!fs.existsSync(absDir)) {
+      // ponytail: luôn là warning (RouteConfig không biết docDirs có phải mặc định không); CONFIG §3.3 lỗi cứng cho docDirs user khai thuộc config.ts.
+      warnings.push(`doc_dir_missing: docDirs "${dir}" không tồn tại (${winPath(absDir)})`);
+      continue;
+    }
+    for (const file of listMarkdownFiles(absDir)) {
+      if (seen.has(file)) {
+        warnings.push(`route_duplicate_file: ${file} nằm trong nhiều docDirs, giữ docDir khai trước`);
+        continue;
+      }
+      seen.add(file);
+      const id = path.posix.relative(winPath(absDir), file).slice(0, -'.md'.length);
+      routes.push({ id, path: `/${id}`, file });
+    }
+  }
+  return { routes, warnings };
+}
+
+/** ROUTING §3.1 — chỉ áp cho một segment, không tạo/xoá `/`. */
+function kebab(segment: string, localeId: string): string {
+  return segment
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLocaleLowerCase(localeId);
+}
+
+interface Normalized {
+  route: Route;
+  routePath: string; // trước khi ghép locale, dạng 'guide/intro'
+  locale: ResolvedLocale;
+  suffixStripped: boolean;
+  indexName?: string;
+  dir: string; // thư mục chứa file, tương đối docDir
+  dotted: boolean; // có '.' bị đổi thành '/'
+}
+
+/**
+ * Từ route thô (scanRoutes) tính `path`/`locale` theo ROUTING §2.2–§2.3, kiểm §4.
+ * Không mutate input. Gom mọi lỗi rồi ném **một** DommiefError (code của lỗi đầu tiên).
+ */
+export function normalizeRoutes(raw: Route[], { cwd, config }: { cwd: string; config: RouteConfig }): RouteScan {
+  const warnings: string[] = [];
+  const errors: { code: string; message: string }[] = [];
+  const show = (file: string) => path.posix.relative(winPath(cwd), file) || file;
+  const defaultLocale = config.locales[0]!; // config luôn có ≥1 locale (zod default)
+  const items: Normalized[] = [];
+
+  for (const r of raw) {
+    const segs = r.id.split('/');
+    let name = segs.pop()!;
+    const dir = segs.join('/');
+
+    // 1. locale: hậu tố chỉ ở tên file, so theo locale.id, locale khai trước thắng
+    let locale = defaultLocale;
+    let suffixStripped = false;
+    const hit = config.locales.find((l) => name.endsWith('.' + l.id));
+    if (hit) {
+      locale = hit;
+      suffixStripped = true;
+      name = name.slice(0, -(hit.id.length + 1));
+    } else {
+      const last = name.slice(name.lastIndexOf('.') + 1);
+      const typo = name.includes('.') && config.locales.find((l) => l.id.toLowerCase() === last.toLowerCase());
+      if (typo) warnings.push(`locale_unknown_suffix: ${show(r.file)} có hậu tố ".${last}" gần giống locale "${typo.id}" nhưng không khớp; xử lý như file thường`);
+    }
+
+    // 2. index/README chỉ ở segment cuối
+    const indexName = INDEX_NAMES.has(name) ? name : undefined;
+    const parts = indexName ? segs : [...segs, name];
+
+    // 3. '.' → '/', 4. kebab, bỏ segment rỗng, NFC
+    const split = parts.flatMap((s) => s.split('.'));
+    const dotted = split.length !== parts.length;
+    const routePath = split
+      .filter(Boolean)
+      .map((s) => (config.forceKebabCase ? kebab(s, locale.id) : s))
+      .join('/')
+      .normalize('NFC');
+
+    // 5. validate ký tự (trước khi ghép suffix locale, vì suffix có '.')
+    const bad = routePath.split('/').find((s) => s && !SEGMENT_OK.test(s));
+    if (bad) {
+      const ch = [...bad].find((c) => !SEGMENT_OK.test(c))!;
+      errors.push({
+        code: 'route_invalid_path',
+        message: `dommief: routes: ký tự không hợp lệ "${ch}" trong đường dẫn của file\n  ${show(r.file)}\n  segment chỉ được chứa chữ, số, "-" và "_". Đổi tên file.`,
+      });
+      // eslint-disable-next-line no-control-regex -- \x00 là biên dưới của dải ASCII (cố ý), không phải ký tự điều khiển lọt vào nhầm.
+    } else if (/[^\x00-\x7F]/.test(routePath)) {
+      warnings.push(`route_non_ascii: ${show(r.file)} → "/${routePath}" có ký tự ngoài ASCII; NFC/NFD và hosting tĩnh có thể lệch, nên đặt tên file ASCII`);
+    }
+
+    // ghép locale: suffix mode khi suffix !== '', ngược lại base mode
+    const joined = locale.suffix ? `/${routePath}${locale.suffix}` : `${locale.base}${routePath}`;
+    const p = joined.replace(/\/{2,}/g, '/').replace(/(.)\/$/, '$1');
+    items.push({
+      // locale mặc định ⇒ không có key (JSON round-trip giữ nguyên object)
+      route: { id: r.id, path: p, file: r.file, ...(locale === defaultLocale ? {} : { locale: locale.id }) },
+      routePath, locale, suffixStripped, ...(indexName === undefined ? {} : { indexName }), dir, dotted,
+    });
+  }
+
+  // 6. trùng id (giữa các docDir)
+  const byId = new Map<string, Normalized[]>();
+  for (const it of items) byId.set(it.route.id, [...(byId.get(it.route.id) ?? []), it]);
+  for (const [id, group] of byId) {
+    if (group.length < 2) continue;
+    errors.push({
+      code: 'route_duplicate',
+      message: `dommief: routes: trùng route id "${id}" (${group.length} file)\n${group.map((g) => `  ${show(g.route.file)}`).join('\n')}\n  id là đường dẫn tương đối trong docDir. Đổi tên file hoặc tách docDir thành 2 site.`,
+    });
+  }
+
+  // 7. trùng path — so cả biến thể lowercase để bắt Intro.md/intro.md
+  const byPath = new Map<string, Normalized[]>();
+  for (const it of items) {
+    if ((byId.get(it.route.id)?.length ?? 0) > 1) continue;
+    const key = it.route.path.toLowerCase();
+    byPath.set(key, [...(byPath.get(key) ?? []), it]);
+  }
+  for (const group of byPath.values()) {
+    if (group.length < 2) continue;
+    errors.push({
+      code: 'route_duplicate',
+      message: `dommief: routes: trùng đường dẫn "${group[0]!.route.path}" (${group.length} file)\n${group.map((g) => `  ${show(g.route.file)}`).join('\n')}\n  nguyên nhân: ${duplicateCause(group[0]!, group[1]!)}`,
+    });
+  }
+
+  if (errors.length) {
+    throw new DommiefError(errors.map((e) => e.message).join('\n\n'), { code: errors[0]!.code });
+  }
+  return { routes: items.map((it) => it.route), warnings };
+}
+
+function duplicateCause(a: Normalized, b: Normalized): string {
+  const base = (n: Normalized) => path.posix.basename(n.route.file);
+  const stripped = a.suffixStripped ? a : b.suffixStripped ? b : undefined;
+  if (stripped && a.locale === b.locale) {
+    const other = stripped === a ? b : a;
+    const owner = stripped.route.locale ? `locale "${stripped.locale.id}"` : 'locale mặc định';
+    return `"${base(stripped)}" thuộc ${owner} nên trùng "${base(other)}"`;
+  }
+  const dirName = (n: Normalized) => n.dir || '/';
+  if (a.indexName && b.indexName) return `cả "${a.indexName}.md" và "${b.indexName}.md" đều gộp vào "${dirName(a)}"`;
+  const idx = a.indexName ? a : b.indexName ? b : undefined;
+  if (idx) return `"${idx.indexName}.md" gộp vào thư mục "${dirName(idx)}"`;
+  if (a.route.id.toLowerCase() === b.route.id.toLowerCase()) return 'trùng sau khi kebab (macOS/Windows không phân biệt hoa thường)';
+  if (a.dotted || b.dotted) return '"." trong tên file được đổi thành "/"';
+  return 'kebab-case làm hai file trùng nhau';
+}
+
+/** sha256 (8 ký tự) của các key ảnh hưởng route. Khác `transformHash` của cache md (DM-406). */
+export function routeConfigHash(config: RouteConfig): string {
+  const { srcDir, docDirs, locales, forceKebabCase, preset } = config;
+  const json = JSON.stringify({
+    srcDir,
+    docDirs: docDirs.map((d) => d.dir),
+    locales: locales.map(({ id, name, base, suffix }) => ({ id, name, base, suffix })),
+    forceKebabCase,
+    preset: preset ?? 'docs',
+  });
+  return createHash('sha256').update(json).digest('hex').slice(0, 8);
+}
+
+/** Điểm vào duy nhất của tầng route: scan → normalize → sort → map tra cứu. JSON-safe. */
+export function buildRouteTable({ cwd, config, hooks, plugins }: { cwd: string; config: RouteConfig; hooks?: PluginHookHost; plugins?: unknown[] }): RouteTable {
+  const host = hooks ?? (plugins ? createPluginHost(plugins) : (config as any)?.plugins ? createPluginHost((config as any).plugins) : undefined);
+  const scan = scanRoutes({ cwd, config });
+  const norm = normalizeRoutes(scan.routes, { cwd, config });
+  const cmp = (x: string, y: string) => (x < y ? -1 : x > y ? 1 : 0);
+  let routes = norm.routes;
+  if (host) routes = host.applyModifyRoutes(routes);
+  routes = routes.sort((a, b) => cmp(a.path, b.path) || cmp(a.id, b.id));
+  const table: RouteTable = {
+    warnings: [...scan.warnings, ...norm.warnings],
+    routes,
+    byId: {},
+    byPath: {},
+    byFile: {},
+    configHash: routeConfigHash(config),
+  };
+  for (const r of routes) {
+    table.byId[r.id] = r;
+    table.byPath[r.path] = r;
+    table.byFile[r.file] = r;
+  }
+  return table;
+}