dommief 0.1.1 → 0.1.2

package/src/search.ts

@@ -0,0 +1,88 @@
+import MiniSearch from 'minisearch';
+import type { Route, ResolvedLocale } from './types.js';
+import type { PageMeta, TextFragment } from './markdown/index.js';
+import { createMiniSearchConfig, SEARCH_FIELDS, SEARCH_STORE_FIELDS, type MiniSearchConfig } from './search-config.js';
+
+export const INDEX_BUDGET_BYTES_PER_PAGE = 5 * 1024;
+
+// Giữ re-export để không phá import cũ (`from './search.js'`) — nguồn thật đã chuyển sang
+// search-config.ts để worker (DM-802) dùng chung mà không kéo theo `minisearch`/Node-only code.
+export { createMiniSearchConfig, SEARCH_FIELDS, SEARCH_STORE_FIELDS };
+export type { MiniSearchConfig };
+
+export interface SearchDocument {
+  id: string;
+  routeId: string;
+  path: string;
+  pageTitle: string;
+  sectionTitle: string;
+  paraId: number;
+  value: string;
+  pageKey: string;
+  sectionKey: string;
+}
+
+export interface BuildSearchIndexOptions {
+  routes: Route[];
+  loadPageMeta: (route: Route) => PageMeta | Promise<PageMeta>;
+  config: { locales: ResolvedLocale[] };
+}
+
+export interface BuildSearchIndexResult {
+  locales: Record<string, unknown>;
+  stats: Record<string, { docs: number; bytes: number; pages: number }>;
+  manifest: { locales: Record<string, string> };
+}
+
+export async function buildSearchIndex(opts: BuildSearchIndexOptions): Promise<BuildSearchIndexResult> {
+  const { routes, loadPageMeta, config } = opts;
+  const cfg = createMiniSearchConfig();
+  const defaultLocale = config.locales[0]?.id;
+  const localesOut: Record<string, unknown> = {};
+  const stats: Record<string, { docs: number; bytes: number; pages: number }> = {};
+  const manifestLocales: Record<string, string> = {};
+
+  for (const loc of config.locales) {
+    const locRoutes = routes.filter((r) => (r.locale ?? defaultLocale) === loc.id);
+    if (locRoutes.length === 0) continue;
+    const ms = new MiniSearch({
+      fields: [...SEARCH_FIELDS],
+      storeFields: [...SEARCH_STORE_FIELDS],
+      ...cfg,
+    });
+    const docs: SearchDocument[] = [];
+    for (const route of locRoutes) {
+      const meta = await loadPageMeta(route);
+      const title = (meta.frontmatter?.title as string) || route.id;
+      const toc = meta.toc || [];
+      const fragments = meta.texts || [];
+      // group by tocIndex / orphan
+      for (let i = 0; i < fragments.length; i++) {
+        const f = fragments[i] as TextFragment;
+        const tocIndex = f.tocIndex;
+        const sectionTitle = tocIndex !== undefined && toc[tocIndex] ? toc[tocIndex].title : title;
+        const pageKey = route.id;
+        const sectionKey = `${route.id}::${tocIndex ?? 'orphan'}`;
+        docs.push({
+          id: `${route.id}#${f.paraId ?? i}#${i}`,
+          routeId: route.id,
+          path: route.path,
+          pageTitle: title,
+          sectionTitle,
+          paraId: f.paraId ?? 0,
+          value: f.value,
+          pageKey,
+          sectionKey,
+        });
+      }
+    }
+    ms.addAll(docs);
+    const json = ms.toJSON();
+    localesOut[loc.id] = json;
+    const bytes = Buffer.byteLength(JSON.stringify(json));
+    stats[loc.id] = { docs: docs.length, bytes, pages: locRoutes.length };
+    manifestLocales[loc.id] = `/search-index/${loc.id}.json`;
+  }
+
+  return { locales: localesOut, stats, manifest: { locales: manifestLocales } };
+}

package/src/siteFeatures.ts

@@ -0,0 +1,123 @@
+import type { Route, NavItem, SidebarGroup, SidebarItem, ResolvedLocale } from './types.js';
+import { parseFrontmatterYaml } from './markdown/remark-meta.js';
+
+export type FrontmatterMap = Record<string, Record<string, unknown>>;
+
+function fmFor(map: FrontmatterMap | undefined, route: Route): Record<string, unknown> {
+  if (!map) return {};
+  return map[route.id] ?? map[route.file] ?? {};
+}
+
+function localeId(route: Route, locales: ResolvedLocale[]): string {
+  if (route.locale) return route.locale;
+  return locales[0]?.id ?? 'default';
+}
+
+function titleOf(route: Route, fm: Record<string, unknown>): string {
+  const t = fm.title ?? fm.navTitle ?? fm.sidebarTitle;
+  if (typeof t === 'string' && t.trim()) return t;
+  return route.id.split('/').pop() ?? route.id;
+}
+
+function orderOf(fm: Record<string, unknown>): number {
+  const v = fm.order ?? fm.navOrder ?? fm.sidebarOrder;
+  return typeof v === 'number' ? v : Number(v ?? 0) || 0;
+}
+
+export function buildNav(
+  routes: Route[],
+  frontmatter?: FrontmatterMap,
+  locales: ResolvedLocale[] = [],
+): Record<string, NavItem[]> {
+  const out: Record<string, NavItem[]> = {};
+  const groups = new Map<string, NavItem[]>();
+  for (const route of routes) {
+    const lid = localeId(route, locales);
+    const fm = fmFor(frontmatter, route);
+    const navFlag = fm.nav;
+    if (navFlag === false) continue;
+    const item: NavItem = {
+      title: titleOf(route, fm),
+      link: route.path,
+      order: orderOf(fm),
+      activePath: route.path,
+    };
+    const arr = groups.get(lid) ?? [];
+    arr.push(item);
+    groups.set(lid, arr);
+  }
+  for (const [lid, items] of groups) {
+    out[lid] = items.sort((a, b) => a.order - b.order || String(a.link).localeCompare(String(b.link)));
+  }
+  // ensure every locale has an entry
+  for (const l of locales) {
+    if (!out[l.id]) out[l.id] = [];
+  }
+  return out;
+}
+
+export function buildSidebar(
+  routes: Route[],
+  frontmatter?: FrontmatterMap,
+  locales: ResolvedLocale[] = [],
+): Record<string, SidebarGroup[]> {
+  const out: Record<string, SidebarGroup[]> = {};
+  const byLocale = new Map<string, Map<string, SidebarGroup>>();
+  for (const route of routes) {
+    const lid = localeId(route, locales);
+    const fm = fmFor(frontmatter, route);
+    const groupTitle = typeof fm.group === 'string' && fm.group.trim() ? fm.group : (route.id.split('/')[0] ?? 'General');
+    const item: SidebarItem = {
+      title: titleOf(route, fm),
+      link: route.path,
+      order: orderOf(fm),
+      ...(Object.keys(fm).length ? { frontmatter: fm } : {}),
+    };
+    let groups = byLocale.get(lid);
+    if (!groups) {
+      groups = new Map();
+      byLocale.set(lid, groups);
+    }
+    let g = groups.get(groupTitle);
+    if (!g) {
+      g = { title: groupTitle, order: orderOf(fm), children: [] };
+      groups.set(groupTitle, g);
+    }
+    g.children.push(item);
+    g.order = Math.min(g.order, orderOf(fm));
+  }
+  for (const [lid, groups] of byLocale) {
+    const arr = [...groups.values()].map((g) => ({
+      ...g,
+      children: g.children.sort((a, b) => a.order - b.order || a.link.localeCompare(b.link)),
+    }));
+    out[lid] = arr.sort((a, b) => a.order - b.order || String(a.title).localeCompare(String(b.title)));
+  }
+  for (const l of locales) {
+    if (!out[l.id]) out[l.id] = [];
+  }
+  return out;
+}
+
+export interface PaginationResult {
+  prev?: Route;
+  next?: Route;
+}
+
+export function paginate(routes: Route[], currentPath: string): PaginationResult {
+  const current = routes.find((r) => r.path === currentPath);
+  if (!current) return {};
+  // chỉ trong cùng locale; thứ tự theo code point như route table
+  const cmp = (x: string, y: string) => (x < y ? -1 : x > y ? 1 : 0);
+  const sorted = routes.filter((r) => r.locale === current.locale).sort((a, b) => cmp(a.path, b.path));
+  const idx = sorted.findIndex((r) => r.path === currentPath);
+  return {
+    ...(idx > 0 ? { prev: sorted[idx - 1] } : {}),
+    ...(idx < sorted.length - 1 ? { next: sorted[idx + 1] } : {}),
+  };
+}
+
+/** @deprecated dùng `parseFrontmatterYaml` (yaml thật). Giữ lại cho tương thích export cũ, cùng chung một parser (#12). */
+export function parseFrontmatter(fileContent: string): Record<string, unknown> {
+  return parseFrontmatterYaml(fileContent);
+}

package/src/siteModule.ts

@@ -0,0 +1,47 @@
+import type { Route, SiteData, TocEntry } from './types.js';
+import { buildNav, buildSidebar, type FrontmatterMap } from './siteFeatures.js';
+
+// Đặc tả: docs/spec/CONTRACTS.md §4–§6, backlog DM-209.
+
+/** Phần config `virtual:dommief/site` cần (ResolvedConfig của DM-201 thoả). */
+export interface SiteModuleConfig {
+  base: string;
+  title: string;
+  description?: string | undefined;
+  locales: SiteData['locales'];
+  themeConfig?: Record<string, unknown> | undefined;
+  frontmatter?: FrontmatterMap | undefined;
+  search?: { enabled: boolean } | undefined;
+}
+
+/** `meta[id]` cho mỗi route: do caller tính sẵn (sitePlugin dùng `extractPageSummary`, #12 — một nguồn sự thật, không đọc `.md?meta` lần nữa qua import). */
+export type SiteModuleMeta = Record<string, { frontmatter: Record<string, unknown>; toc: TocEntry[] }>;
+
+/**
+ * Sinh code cho `virtual:dommief/site`. Mọi thứ nhúng thẳng vào JSON (không import `.md?meta`
+ * cho từng route — mở một trang trong dev từng kéo theo transform MỌI file md, #12), và không
+ * import `virtual:dommief/routes` (hai module invalidate độc lập).
+ */
+export function createSiteModule({ routes, config, meta }: { routes: Route[]; config: SiteModuleConfig; meta: SiteModuleMeta }): string {
+  const routesById = Object.fromEntries(routes.map((r) => [r.id, r]));
+  const frontmatter = config.frontmatter ?? {};
+  const nav = buildNav(routes, frontmatter, config.locales);
+  const sidebar = buildSidebar(routes, frontmatter, config.locales);
+  const head = {
+    base: config.base,
+    title: config.title,
+    ...(config.description === undefined ? {} : { description: config.description }),
+    locales: config.locales,
+    themeConfig: config.themeConfig ?? {},
+    routes: routesById,
+    search: config.search ?? { enabled: true },
+  };
+  const json = JSON.stringify(head);
+  return `export default {
+  ...${json},
+  meta: ${JSON.stringify(meta)},
+  nav: ${JSON.stringify(nav)},
+  sidebar: ${JSON.stringify(sidebar)},
+};
+`;
+}

package/src/sitemap.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Route } from './types.js';
+import { matchExclude } from './exclude.js';
+
+// Đặc tả: docs/backlog/DM-708.md, docs/spec/CONFIG.md §1.5. URL tuyệt đối theo `base` + hostname
+// cấu hình (KHÔNG đoán domain — thiếu hostname thì không phát gì, không crash). Chỉ route tĩnh
+// đã prerender (routes truyền vào phải là `plan.prerender`, không phải mọi route).
+
+export interface SitemapConfig {
+  hostname: string;
+  exclude: string[];
+}
+
+export function canonicalUrl(hostname: string, base: string, routePath: string): string {
+  const host = hostname.replace(/\/$/, '');
+  const b = base.replace(/\/$/, '');
+  const p = routePath === '/' ? '/' : routePath;
+  return host + (b + p).replace(/\/{2,}/g, '/').replace(/^(https?:\/)([^/])/, '$1/$2');
+}
+
+/** `#404`, route động (`:`/`*`), và route trong `sitemap.exclude` không vào sitemap. */
+export function buildSitemap(routes: Route[], config: SitemapConfig, base: string): string {
+  const urls = routes
+    .filter((r) => r.path !== '/404' && !/[:*]/.test(r.path) && !matchExclude(r.path, config.exclude))
+    .map((r) => `  <url><loc>${escapeXml(canonicalUrl(config.hostname, base, r.path))}</loc></url>`)
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+}
+
+export function buildRobots(sitemapUrl: string): string {
+  return `User-agent: *\nAllow: /\n\nSitemap: ${sitemapUrl}\n`;
+}
+
+export function escapeXml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]!);
+}
+
+/** emitter nối vào `build.ts`: ghi `sitemap.xml`/`robots.txt` khi config có `sitemap` (khác `false`). */
+export function writeSitemapAndRobots(opts: {
+  outDir: string;
+  routes: Route[];
+  sitemap: false | SitemapConfig;
+  robots: boolean;
+  base: string;
+  log: { warn(msg: string): void };
+}): void {
+  if (opts.sitemap === false) return;
+  if (!opts.sitemap.hostname) {
+    opts.log.warn('sitemap.hostname thiếu — bỏ qua sitemap.xml/robots.txt');
+    return;
+  }
+  const xml = buildSitemap(opts.routes, opts.sitemap, opts.base);
+  fs.writeFileSync(path.join(opts.outDir, 'sitemap.xml'), xml);
+  if (opts.robots) {
+    const sitemapUrl = canonicalUrl(opts.sitemap.hostname, opts.base, '/').replace(/\/$/, '') + '/sitemap.xml';
+    fs.writeFileSync(path.join(opts.outDir, 'robots.txt'), buildRobots(sitemapUrl));
+  }
+}

package/src/ssr-guard.ts

@@ -0,0 +1,72 @@
+import { DommiefError } from './markdown/errors.js';
+
+// Đặc tả: docs/backlog/DM-408.md. Cổng ở mức prerender: trước renderToString, cài getter trên
+// `window`/`document` để BẤT KỲ truy cập nào trong thân render ném lỗi NGAY (không chỉ warn) —
+// chạy đúng điều kiện production khi người dùng chỉ "warn rồi bỏ qua" là nhận trang trắng/
+// hydration lỗi trên site thật. Throw sớm, tại route hỏng, kèm routeId sửa được trong 1 phút.
+
+type PropertyKey2 = 'window' | 'document';
+
+interface SavedDescriptor { key: PropertyKey2; descriptor: PropertyDescriptor | undefined; }
+
+let installed: SavedDescriptor[] | null = null;
+// Đếm số lần `withSsrGuard` đang CHẠY ĐỖNG THờI: khi `config.ssg.concurrency > 1`,
+// nhiều route render SONG SONG (build.ts `mapLimit`) dùng chung `globalThis`. Nếu không đếm,
+// route A xong trước sẽ `uninstall()` và gỡ guard giữa chừng khi route B vẫn đang render
+// — B mất bảo vệ mà không ai biết. Chỉ `uninstall()` thật khi đếm về 0.
+let refCount = 0;
+
+function guardGetter(name: PropertyKey2): PropertyDescriptor {
+  return {
+    configurable: true,
+    enumerable: false,
+    get(): never {
+      throw new DommiefError(
+        `truy cập "${name}" lúc render (SSR) — lỗi \`ssr_unsafe_access\`. Chuyển vào useEffect/event handler, hoặc bọc nội dung trong <ClientOnly>. Nếu đây là code của thư viện bên thứ 3 đọc "${name}" ngay lúc import (top-level), chuyển sang import động bên trong useEffect.`,
+        { code: 'ssr_unsafe_access' },
+      );
+    },
+  };
+}
+
+/**
+ * Cài getter chặn `window`/`document` trên `globalThis`. Idempotent: gọi 2 lần không đè descriptor gốc lần 2
+ * (nếu không, `uninstall()` sau đó sẽ khôi phục nhầm descriptor-chặn thay vì descriptor thật).
+ * Tắt bằng `DOMMIEF_SSR_GUARD=0` — đường thoát cho theme bên thứ 3 đang chuyển đổi.
+ */
+export function install(): void {
+  if (process.env.DOMMIEF_SSR_GUARD === '0') return;
+  if (installed) return;
+  const saved: SavedDescriptor[] = [];
+  for (const key of ['window', 'document'] as const) {
+    saved.push({ key, descriptor: Object.getOwnPropertyDescriptor(globalThis, key) });
+    Object.defineProperty(globalThis, key, guardGetter(key));
+  }
+  installed = saved;
+}
+
+/** Gỡ getter, khôi phục descriptor gốc (kể cả khi gốc là `undefined` — Node không có sẵn `window`). PHẢI gọi trong `finally` để không rò getter sang route sau khi route hiện tại throw. */
+export function uninstall(): void {
+  if (!installed) return;
+  for (const { key, descriptor } of installed) {
+    if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+    else delete (globalThis as any)[key];
+  }
+  installed = null;
+}
+
+/**
+ * Chạy `fn` với cổng SSR-safety bật, luôn gỡ sau khi xong (kể cả throw). An toàn khi nhiều
+ * lời gọi chạy SONG SONG (reference counting): guard thật chỉ bị gỡ khi lần gọi CUỐI
+ * CÙNG đang chạy hoàn tất, không phải lần đầu tiên xong.
+ */
+export async function withSsrGuard<T>(fn: () => Promise<T>): Promise<T> {
+  refCount++;
+  install();
+  try {
+    return await fn();
+  } finally {
+    refCount--;
+    if (refCount === 0) uninstall();
+  }
+}

package/src/theme/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { loadTheme } from './loader.js';
+export type { ThemeManifest as ThemeManifestType } from './types.js';
+export { resolveSlot, resolveThemeSlots, buildAliasChain } from './resolver.js';
+export type { ThemeKind, AliasMap } from './resolver.js';

package/src/theme/loader.ts

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DommiefError } from '../markdown/errors.js';
+import type { ThemeManifest, ThemeLoaderOptions, ThemeLayoutName } from './types.js';
+
+// Đặc tả: docs/spec/THEME-API.md §2, backlog DM-501.
+// Luật quét giữ y dumi (`features/theme/loader.ts`): chỉ file/thư mục tên bắt đầu bằng chữ HOA
+// hoặc chữ số mới được coi là component; `Foo.ext` và `Foo/index.ext` cho CÙNG specifier `Foo`.
+
+const EXTS = ['.tsx', '.ts', '.jsx', '.js'];
+const DEFAULT_THEME = 'dommief-theme-default';
+
+function isComponentName(name: string): boolean {
+  return /^[A-Z0-9]/.test(name);
+}
+
+/** Thư mục chứa `packages/` của chính monorepo dommief (để test/dev dùng theme-default từ source, không cần build trước). */
+function repoPackagesDir(): string | null {
+  let cur = path.dirname(fileURLToPath(import.meta.url));
+  while (cur !== path.parse(cur).root) {
+    if (fs.existsSync(path.join(cur, 'pnpm-workspace.yaml'))) return path.join(cur, 'packages');
+    cur = path.dirname(cur);
+  }
+  return null;
+}
+
+function assertInside(cwd: string, target: string, theme: string): void {
+  const rel = path.relative(cwd, target);
+  const insideCwd = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  const insideNodeModules = target.split(path.sep).includes('node_modules');
+  if (!insideCwd && !insideNodeModules) {
+    throw new DommiefError(`đường dẫn theme "${theme}" thoát ra ngoài thư mục dự án: ${target}`, { code: 'theme_path_escape', file: target });
+  }
+}
+
+/** `theme` là path tương đối (bắt đầu bằng `.`), tên package trong `node_modules`, hoặc tên package nguồn trong monorepo (chỉ khi dev/test dommief chính nó). */
+export function resolveThemeRoot(cwd: string, theme: string): string {
+  const isPathLike = theme.startsWith('.') || theme.startsWith('/');
+  let root: string | null = null;
+  if (isPathLike) {
+    // Chỉ ĐƯỜNG DẪN tường minh (`theme: './my-theme'`) mới chịu kiểm "không thoát khỏi dự án":
+    // đây là input user viết tay trong config, khác với resolve theo tên package (node_modules/
+    // workspace symlink đã tự do trỏ ra ngoài cwd theo thiết kế của Node/pnpm).
+    const candidate = path.resolve(cwd, theme);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) root = candidate;
+    if (!root) throw new DommiefError(`không tìm thấy theme tại đường dẫn "${theme}"`, { code: 'theme_package_not_found' });
+    assertInside(cwd, root, theme);
+  } else {
+    const nmCandidate = path.resolve(cwd, 'node_modules', theme);
+    if (fs.existsSync(nmCandidate)) root = nmCandidate;
+    else {
+      // Fallback chỉ dùng khi chạy BÊN TRONG chính monorepo dommief (test/dogfood không cài qua
+      // node_modules): không áp dụng assertInside vì đây là quy ước nội bộ, không phải input user.
+      const packages = repoPackagesDir();
+      const pkgDirName = theme === DEFAULT_THEME ? 'theme-default' : theme;
+      const srcCandidate = packages ? path.join(packages, pkgDirName) : null;
+      if (srcCandidate && fs.existsSync(srcCandidate)) root = srcCandidate;
+    }
+    if (!root) {
+      throw new DommiefError(`không tìm thấy theme package "${theme}" (đã thử node_modules/${theme})`, { code: 'theme_package_not_found' });
+    }
+  }
+  // Package nguồn trong monorepo (hoặc workspace link): component nằm ở `src/`, không phải `dist/`.
+  if (fs.existsSync(path.join(root, 'src', 'layouts'))) root = path.join(root, 'src');
+  return root;
+}
+
+function pickEntry(dir: string, name: string): string | null {
+  for (const ext of EXTS) {
+    const f = path.join(dir, name + ext);
+    if (fs.existsSync(f) && fs.statSync(f).isFile()) return f;
+  }
+  const subIndexDir = path.join(dir, name);
+  if (fs.existsSync(subIndexDir) && fs.statSync(subIndexDir).isDirectory()) {
+    for (const ext of EXTS) {
+      const f = path.join(subIndexDir, 'index' + ext);
+      if (fs.existsSync(f) && fs.statSync(f).isFile()) return f;
+    }
+  }
+  return null;
+}
+
+/** Quét một thư mục (`slots/`, `builtins/`) ra `specifier -> absolute path`, theo luật "chữ hoa/chữ số đầu". */
+export function scanComponents(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const name = entry.name;
+    if (!isComponentName(name)) continue;
+    if (entry.isFile()) {
+      const ext = EXTS.find((e) => name.endsWith(e));
+      if (!ext) continue;
+      const specifier = name.slice(0, -ext.length);
+      if (!isComponentName(specifier)) continue;
+      out[specifier] ??= path.resolve(dir, name);
+    } else if (entry.isDirectory()) {
+      const found = pickEntry(dir, name);
+      if (found) out[name] = path.resolve(found);
+    }
+  }
+  return out;
+}
+
+function scanLocales(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith('.json')) {
+      out[entry.name.slice(0, -'.json'.length)] = path.resolve(dir, entry.name);
+    }
+  }
+  return out;
+}
+
+/** Quét một thư mục theme (đã resolve) ra `ThemeManifest`. KHÔNG áp dụng override — đó là việc của resolver.ts (merge theo từng component qua 2-3 manifest). */
+export function loadThemeManifest(root: string, name: string): ThemeManifest {
+  const layoutsDir = path.join(root, 'layouts');
+  const layouts = {} as Record<ThemeLayoutName, string>;
+  const missing: ThemeLayoutName[] = [];
+  for (const layoutName of ['GlobalLayout', 'DocLayout', 'DemoLayout'] as const) {
+    const p = pickEntry(layoutsDir, layoutName);
+    if (p) layouts[layoutName] = p;
+    else missing.push(layoutName);
+  }
+  if (missing.length) {
+    throw new DommiefError(`theme "${name}" thiếu layout: ${missing.join(', ')}`, { code: 'theme_layout_missing', file: layoutsDir, layout: missing.join(',') });
+  }
+  const pluginJs = ['plugin.ts', 'plugin.js', path.join('plugin', 'index.ts'), path.join('plugin', 'index.js')]
+    .map((f) => path.join(root, f))
+    .find((f) => fs.existsSync(f));
+  return {
+    name,
+    root,
+    builtins: scanComponents(path.join(root, 'builtins')),
+    slots: scanComponents(path.join(root, 'slots')),
+    layouts,
+    locales: scanLocales(path.join(root, 'locales')),
+    plugin: pluginJs ?? null,
+  };
+}
+
+/** Resolve + quét theme `opts.theme` (mặc định `dommief-theme-default`). Không áp override local — xem `loadThemeChain` trong resolver.ts. */
+export function loadTheme(opts: ThemeLoaderOptions): ThemeManifest {
+  const cwd = path.resolve(opts.cwd);
+  const theme = opts.theme ?? DEFAULT_THEME;
+  const root = resolveThemeRoot(cwd, theme);
+  return loadThemeManifest(root, theme);
+}
+
+export { DEFAULT_THEME };

package/src/theme/resolver.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DommiefError } from '../markdown/errors.js';
+import type { ResolvedConfig } from '../config.js';
+import { loadTheme, loadThemeManifest, DEFAULT_THEME } from './loader.js';
+import { scanComponents } from './loader.js';
+import type { ThemeLayoutName, ThemeManifest } from './types.js';
+
+// Đặc tả: docs/spec/THEME-API.md §3, backlog DM-502.
+// Thứ tự ưu tiên (THẮNG → THUA): `.dommief/theme/**` > theme package (config `theme`) > `dommief-theme-default`.
+// Resolve chạy THEO TỪNG component, không theo cả theme: core quét cả 3 nguồn, merge nông theo key.
+
+export type ThemeKind = 'slots' | 'builtins' | 'layouts' | 'locales';
+export type AliasMap = Record<string, string>;
+
+export interface ThemeChain {
+  /** `.dommief/theme/**` nếu tồn tại (thư mục không cần có cả 4 kind con). */
+  local: ThemeManifest | null;
+  /** Theme package khai ở config `theme`; bằng `fallback` nếu config trỏ default. */
+  pkg: ThemeManifest;
+  /** `dommief-theme-default`, luôn là đáy. */
+  fallback: ThemeManifest;
+}
+
+function tryLoadLocal(cwd: string): ThemeManifest | null {
+  const localRoot = path.resolve(cwd, '.dommief', 'theme');
+  if (!fs.existsSync(localRoot)) return null;
+  // Local override không bắt buộc có layouts (THEME-API §3: override từng component).
+  // loadThemeManifest ném lỗi khi thiếu layout -> quét thủ công, không gọi loadThemeManifest.
+  const layoutsDir = path.join(localRoot, 'layouts');
+  const layouts = {} as Record<ThemeLayoutName, string>;
+  for (const name of ['GlobalLayout', 'DocLayout', 'DemoLayout'] as const) {
+    const found = scanComponents(layoutsDir)[name];
+    if (found) layouts[name] = found;
+  }
+  return {
+    name: '.dommief/theme',
+    root: localRoot,
+    builtins: scanComponents(path.join(localRoot, 'builtins')),
+    slots: scanComponents(path.join(localRoot, 'slots')),
+    layouts,
+    locales: {},
+    plugin: null,
+  };
+}
+
+/** Quét `.dommief/theme/**` + theme package + `dommief-theme-default`. `pkg === fallback` khi config.theme là mặc định. */
+export function loadThemeChain(cwd: string, config: Pick<ResolvedConfig, 'theme'>): ThemeChain {
+  const themeName = config.theme ?? DEFAULT_THEME;
+  const pkg = loadTheme({ cwd, theme: themeName });
+  const fallback = themeName === DEFAULT_THEME ? pkg : loadTheme({ cwd, theme: DEFAULT_THEME });
+  return { local: tryLoadLocal(cwd), pkg, fallback };
+}
+
+function manifestsOf(chain: ThemeChain): ThemeManifest[] {
+  // Thứ tự ưu tiên: local trước (thắng), rồi pkg, rồi fallback. Nếu pkg === fallback, liệt kê 1 lần (không đổi kết quả, chỉ tránh việc lặp vô nghĩa).
+  const list = [chain.local, chain.pkg, chain.pkg === chain.fallback ? null : chain.fallback].filter((m): m is ThemeManifest => m !== null);
+  return list;
+}
+
+/** Trả absolute path thắng của `name` trong `kind`, duyệt `chain` theo thứ tự ưu tiên. Ném lỗi nếu không ai có. */
+export function resolveSlot(name: string, kind: ThemeKind, chain: ThemeChain): string {
+  for (const m of manifestsOf(chain)) {
+    const hit = kind === 'layouts' ? (m.layouts as Record<string, string>)[name] : kind === 'locales' ? m.locales[name] : m[kind][name];
+    if (hit) return hit;
+  }
+  throw new DommiefError(`không có theme nào cung cấp ${kind}/${name}`, { code: 'theme_slot_missing' });
+}
+
+/** Danh sách mọi specifier từng xuất hiện trong `kind`, gộp từ cả 3 manifest (để biết override gì có thể alias). */
+function allNames(chain: ThemeChain, kind: ThemeKind): string[] {
+  const names = new Set<string>();
+  for (const m of manifestsOf(chain)) {
+    const map = kind === 'layouts' ? m.layouts : kind === 'locales' ? m.locales : m[kind];
+    for (const k of Object.keys(map)) names.add(k);
+  }
+  return [...names];
+}
+
+/**
+ * Sinh bảng alias Vite cho mọi component đã quét được: `dommief/theme/<kind>/<Name>` → absolute path thắng.
+ * Cũng alias `dommief/theme` → root của theme package (không phải local, không phải default — đúng ý
+ * "theme đang dùng" cho mục đích debug/log; component thật đi qua alias riêng từng cái).
+ */
+export function buildAliasChain(cwd: string, config: Pick<ResolvedConfig, 'theme'>): AliasMap {
+  const chain = loadThemeChain(cwd, config);
+  const aliases: AliasMap = {};
+  for (const kind of ['slots', 'builtins', 'layouts'] as const) {
+    for (const name of allNames(chain, kind)) {
+      aliases[`dommief/theme/${kind}/${name}`] = resolveSlot(name, kind, chain);
+    }
+  }
+  // QUAN TRỌNG: alias tổng quát `dommief/theme` PHẢI được thêm SAU cùng. Vite/`@rollup/plugin-alias`
+  // khớp theo thứ tự chuỗi key (object → array, giữ thứ tự chèn) và dùng pattern string TRÙNG
+  // PREFIX (`importee.startsWith(pattern + '/')`) — nếu `dommief/theme` đứng TRƯỚC, nó khớp
+  // ngay cả `dommief/theme/slots/Footer` và thắng trước alias cụ thể hơn, thay thế đúng đoạn
+  // prefix bằng `pkg.root` rồi nối `/slots/Footer` → luôn ra đường dẫn DEFAULT, bỏ qua local
+  // override hoàn toàn (đã bắt trực tiếp bằng build-e2e thật: alias đúng nhưng output sai).
+  aliases['dommief/theme'] = chain.pkg.root;
+  return aliases;
+}
+
+/** Merge nông theo key, local > pkg > default (THEME-API §7.5). */
+export function mergeLocaleStrings(chain: ThemeChain, localeId: string): Record<string, string> {
+  const readJson = (file: string | undefined): Record<string, string> => {
+    if (!file) return {};
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
+  };
+  // local override không có bản dịch riêng ở v0.1 (chỉ builtins/slots/layouts) — merge chỉ pkg + fallback.
+  return { ...readJson(chain.fallback.locales[localeId]), ...readJson(chain.pkg.locales[localeId]) };
+}
+
+export function resolveThemeSlots(opts: { cwd: string; config: Pick<ResolvedConfig, 'theme'> }): AliasMap {
+  return buildAliasChain(opts.cwd, opts.config);
+}