@mintfolio/core 0.1.5

package/src/components/Image.astro

@@ -0,0 +1,28 @@
+---
+import { Image, type LocalImageProps } from 'astro:assets';
+import type { HTMLAttributes } from 'astro/types';
+import type { PublicImage } from '@mintfolio/theme-api';
+
+/**
+ * Images declare display dimensions, including
+ * remote URLs. Keep the SDK's local metadata intact so Astro can optimize it.
+ * Responsive widths and the remaining transform options are forwarded to Astro.
+ */
+type Props = Omit<HTMLAttributes<'img'>, 'src' | 'alt' | 'width' | 'height' | 'srcset'>
+  & Pick<LocalImageProps, 'layout' | 'widths' | 'quality' | 'format' | 'priority' | 'fit' | 'position' | 'background'>
+  & {
+    src: string | PublicImage;
+    alt: string;
+    width: number;
+    height: number;
+  };
+
+// Forward every other attribute, including parent-generated scoped CSS markers.
+// Narrowing each branch lets Astro select its remote/local prop contract safely.
+const { src, ...attributes } = Astro.props;
+const placeholder = 'data:image/svg+xml,' + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200"><rect width="200" height="200" fill="#eee"/><circle cx="100" cy="75" r="30" fill="#aaa"/><path d="M40 185v-15a60 60 0 0 1 120 0v15" fill="#aaa"/></svg>');
+---
+
+{!src ? <img src={placeholder} {...attributes} /> : typeof src === 'string'
+  ? <Image src={src} {...attributes} />
+  : <Image src={src} {...attributes} />}

package/src/components/PostArchive.astro

@@ -0,0 +1,48 @@
+---
+import type { PostFilters, PostSummary, TaxonomyCount } from '@mintfolio/theme-api';
+interface Props {
+  /** Safe public metadata supplied by Core's page/context APIs. */
+  posts: PostSummary[];
+  tags: TaxonomyCount[];
+  categories: TaxonomyCount[];
+  filters?: Partial<PostFilters>;
+  language?: string;
+  /** Omit to display every match; supply a positive integer to enable load more. */
+  pageSize?: number;
+}
+const { posts, tags, categories, filters = {}, language = 'zh-CN', pageSize } = Astro.props;
+const formatDate = (value: string): string => new Intl.DateTimeFormat(language, { dateStyle: 'medium' }).format(new Date(value));
+---
+<section class="mintfolio-archive" data-core-archive data-archive data-posts={JSON.stringify(posts)} data-page-size={pageSize}>
+  <form class="mintfolio-filters" data-filter-form aria-label="筛选文章">
+    <label>搜索<input name="q" type="search" value={filters.q ?? ''} autocomplete="off" /></label>
+    <label>标签<select name="tag"><option value="">全部标签</option>{tags.map((tag) => <option value={tag.label} selected={filters.tag === tag.label}>{tag.label} ({tag.count})</option>)}</select></label>
+    <label>分类<select name="category"><option value="">全部分类</option>{categories.map((term) => <option value={term.label} selected={filters.category === term.label}>{term.label} ({term.count})</option>)}</select></label>
+  </form>
+  <p data-filter-status aria-live="polite"></p>
+  <ol class="mintfolio-posts">
+    {posts.map((post) => <li data-post-id={post.id}>
+      <h2><a href={post.url}>{post.title}</a></h2>
+      <p><time datetime={post.publishedAt}>{formatDate(post.publishedAt)}</time>{post.protected ? ' · 受保护' : ''}</p>
+      <p>{post.description}</p>
+      <div class="mintfolio-terms"><a href={post.category.url}>{post.category.label}</a>{post.tags.map((tag) => <a href={tag.url}>#{tag.label}</a>)}</div>
+    </li>)}
+  </ol>
+  <button type="button" data-load-more hidden>加载更多</button>
+</section>
+<style>
+  .mintfolio-filters { display: grid; gap: .8rem; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  .mintfolio-filters label { display: grid; gap: .25rem; }
+  .mintfolio-filters :is(input,select) { min-width: 0; font: inherit; padding: .45rem; }
+  .mintfolio-posts { list-style: none; margin: 0; padding: 0; }
+  .mintfolio-posts > li { padding: 1rem 0; border-top: 1px solid #8886; }
+  .mintfolio-posts h2 { font-size: 1.15rem; margin: 0; }
+  .mintfolio-posts p { margin: .4rem 0; }
+  .mintfolio-terms { display: flex; flex-wrap: wrap; gap: .75rem; }
+  .mintfolio-archive [hidden] { display: none; }
+  @media (max-width: 620px) { .mintfolio-filters { grid-template-columns: 1fr; } }
+</style>
+<script>
+  import { bindPostArchive, onPage } from '@mintfolio/core/client';
+  onPage('[data-core-archive]', (root, scope) => bindPostArchive(root, scope));
+</script>

package/src/components/ProtectedArticle.astro

@@ -0,0 +1,56 @@
+---
+import type { ArticleBody } from '@mintfolio/theme-api/astro';
+interface Props {
+  /** Core supplies only authenticated ciphertext, never the password or plaintext. */
+  body: Extract<ArticleBody, { kind: 'protected' }>;
+}
+const { body } = Astro.props;
+---
+<section class="mintfolio-protected" data-core-protected data-protected-article data-payload={JSON.stringify(body.payload)} data-post-id={body.postId} aria-label="受保护的文章">
+  <p data-protected-intro>这篇文章受保护。请输入密码以在当前标签页中阅读。</p>
+  <form data-protected-form>
+    <label>文章密码<input data-protected-password type="password" autocomplete="current-password" required /></label>
+    <button type="submit">解锁文章</button>
+  </form>
+  <p data-protected-error role="alert" hidden></p>
+  <div class="mintfolio-prose" data-protected-output hidden tabindex="-1"></div>
+  <button type="button" data-protected-relock hidden>重新锁定</button>
+</section>
+<style>
+  .mintfolio-protected { border: 1px solid #8888; padding: 1.25rem; }
+  .mintfolio-protected form, .mintfolio-protected label { display: flex; flex-wrap: wrap; align-items: center; gap: .7rem; }
+  .mintfolio-protected :is(input,button) { font: inherit; max-width: 100%; padding: .4rem .65rem; }
+  .mintfolio-protected [hidden] { display: none; }
+  .mintfolio-protected [role="alert"] { color: #a60000; }
+  .mintfolio-prose { overflow-wrap: anywhere; }
+  .mintfolio-prose :global(img) { max-width: 100%; height: auto; }
+  .mintfolio-prose :global(pre) { overflow: auto; }
+</style>
+<script>
+  import { createProtectedArticleController, onPage } from '@mintfolio/core/client';
+  onPage('[data-core-protected]', (root, scope) => {
+    const form = root.querySelector<HTMLFormElement>('[data-protected-form]');
+    const input = root.querySelector<HTMLInputElement>('[data-protected-password]');
+    const output = root.querySelector<HTMLElement>('[data-protected-output]');
+    const status = root.querySelector<HTMLElement>('[data-protected-error]');
+    const button = form?.querySelector<HTMLButtonElement>('button');
+    const relock = root.querySelector<HTMLButtonElement>('[data-protected-relock]');
+    if (!form || !input || !output || !status || !button || !relock) return;
+    const controller = createProtectedArticleController({
+      payload: JSON.parse(root.dataset.payload ?? 'null'), postId: root.dataset.postId ?? '', signal: scope.signal,
+      onUnlock: ({ fragment }) => { output.replaceChildren(fragment); input.value = ''; },
+      onClear: () => { output.replaceChildren(); input.value = ''; status.textContent = ''; status.hidden = true; },
+      onState: (state) => {
+        input.disabled = button.disabled = state === 'unlocking';
+        button.textContent = state === 'unlocking' ? '正在解锁…' : '解锁文章';
+        form.hidden = state === 'unlocked';
+        output.hidden = relock.hidden = state !== 'unlocked';
+        if (state === 'unlocked') output.focus({ preventScroll: true });
+        form.setAttribute('aria-busy', String(state === 'unlocking'));
+      },
+      onError: () => { status.textContent = '无法解锁文章，请检查密码后重试。'; status.hidden = false; },
+    });
+    form.addEventListener('submit', (event) => { event.preventDefault(); void controller.unlock(input.value); }, { signal: scope.signal });
+    relock.addEventListener('click', () => { controller.lock(); input.focus(); }, { signal: scope.signal });
+  });
+</script>

package/src/components/SeoHead.astro

@@ -0,0 +1,7 @@
+---
+import SeoHead from '@mintfolio/theme-api/SeoHead.astro';
+import type { SeoData } from '@mintfolio/theme-api/astro';
+interface Props { /** SEO policy already computed by Core. */ seo: SeoData; }
+const { seo } = Astro.props;
+---
+<SeoHead seo={seo} />

package/src/content.d.ts

@@ -0,0 +1,15 @@
+import type { Loader } from 'astro/loaders';
+import type { z } from 'astro/zod';
+/** The validated frontmatter shape; raw records remain accessible only to the host. */
+export interface BlogFrontmatter {
+  title: string;
+  pubDate: Date;
+  description: string;
+  category?: string;
+  tags?: string[];
+  cover?: string;
+  draft: boolean;
+  password?: string;
+}
+/** Markdown location is relative to the consuming site's project root. */
+export function createBlogCollection(options?: { base?: string }): { loader: Loader; schema: z.ZodType<BlogFrontmatter> };

package/src/content.mjs

@@ -0,0 +1,19 @@
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
+import { glob } from 'astro/loaders';
+
+/**
+ * Blog schema and Markdown loader owned by Core. Call from src/content.config.ts.
+ * @param {{base?:string}} [options] Markdown directory relative to the site root.
+ */
+export function createBlogCollection({ base = './content/blog' } = {}) {
+  return defineCollection({
+    loader: glob({ pattern: '**/*.md', base }),
+    schema: z.object({
+      title: z.string(), pubDate: z.coerce.date(), description: z.string(),
+      category: z.string().optional(), tags: z.array(z.string()).optional(),
+      cover: z.string().optional(), draft: z.boolean().default(false),
+      password: z.string().refine((value) => value.trim().length > 0, '文章密码不能为空').optional(),
+    }),
+  });
+}

package/src/engine/context.ts

@@ -0,0 +1,55 @@
+import type { PostQuery, PostSummary, ThemeContext, ThemeDefinition } from '@mintfolio/theme-api';
+import { createSearchEntry, filterPosts } from '@mintfolio/theme-api/search';
+import { getPublishedPosts, toPostSummary, collectTaxonomy, collectArchives } from '../server/posts';
+import { getPublicSite } from '../server/site';
+import { urls } from '../server/routing';
+
+/** Only validated manifest data and recursively validated settings cross this boundary. */
+export interface ActiveTheme {
+  definition: ThemeDefinition;
+  settings: Record<string, unknown>;
+}
+
+/** Reject invalid paging values before slicing, including NaN and fractions. */
+function pageNumber(value: number | undefined, field: string, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`content.posts(): ${field} must be a non-negative safe integer`);
+  return value;
+}
+
+/**
+ * Construct one immutable-by-convention render context. A snapshot belongs to
+ * this render, so dev content edits cannot be hidden by a process-wide cache.
+ * Neither functions nor internal collection entries are serialized to browsers.
+ */
+export async function createThemeContext(active: ActiveTheme): Promise<ThemeContext> {
+  const posts = (await getPublishedPosts()).map(toPostSummary);
+  if (posts.some((post) => post.protected) && !active.definition.capabilities.encryptedPosts) {
+    throw new Error(`[theme:capability] ${active.definition.manifest.id} does not support encryptedPosts, but the site has protected articles`);
+  }
+  return {
+    site: getPublicSite(),
+    navigation: [
+      { id: 'home', label: '首页', url: urls.home() },
+      { id: 'archive', label: '全部文章', url: urls.archive() },
+      { id: 'about', label: '关于我', url: urls.page('about') },
+    ],
+    settings: active.settings,
+    content: {
+      posts: async (query: PostQuery = {}): Promise<{ items: PostSummary[]; total: number }> => {
+        const matches = filterPosts(posts, query);
+        const offset = pageNumber(query.offset, 'offset', 0);
+        const limit = pageNumber(query.limit, 'limit', matches.length);
+        return { items: matches.slice(offset, offset + limit), total: matches.length };
+      },
+      post: async (id: string): Promise<PostSummary | null> => posts.find((post) => post.id === id) ?? null,
+    },
+    taxonomy: {
+      tags: async () => collectTaxonomy(posts, 'tags'),
+      categories: async () => collectTaxonomy(posts, 'categories'),
+      archives: async () => collectArchives(posts),
+    },
+    urls,
+    search: { index: async () => posts.map(createSearchEntry) },
+  };
+}

package/src/engine/import-boundary.mjs

@@ -0,0 +1,154 @@
+// @ts-check
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { init, parse } from 'es-module-lexer';
+import { resolve as resolveImport } from 'import-meta-resolve';
+
+const PRIVATE_SPECIFIERS = new Set(['astro:content', 'astro/loaders', 'node:fs', 'node:fs/promises', 'fs', 'fs/promises']);
+const PRIVATE_DIRECTORIES = ['src/core', 'src/theme', 'src/lib', 'src/utils', 'src/scripts', 'src/pages', 'content', 'src/content'];
+const PRIVATE_CONFIGS = ['site.config.ts', 'theme.config.mjs', 'astro.config.mjs', 'src/content.config.ts'];
+const CORE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+
+/** @param {string} filename @param {string} directory @returns {boolean} */
+function isWithin(filename, directory) {
+  const relative = path.relative(directory, filename);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/**
+ * Read static imports, re-exports, and literal dynamic imports without executing
+ * the module. Vite callers may ignore computed imports that Vite expands later;
+ * native manifest loading rejects them because it has no such expansion step.
+ * This inspects module dependencies, not arbitrary JavaScript execution.
+ * @param {string} source JavaScript module source (Astro callers extract scripts first).
+ * @param {string} importer Filename used in actionable diagnostics.
+ * @param {{rejectComputedImports?:boolean}} options
+ * @returns {Promise<string[]>} Decoded import specifiers, excluding import.meta.
+ */
+export async function readModuleImports(source, importer, { rejectComputedImports = false } = {}) {
+  await init;
+  let imports;
+  try {
+    [imports] = parse(source, importer);
+  } catch {
+    throw new Error(`[theme:boundary] Cannot inspect module imports in ${importer}; use valid ES module syntax`);
+  }
+  const specifiers = [];
+  for (const entry of imports) {
+    if (entry.d === -2) continue; // import.meta is metadata, not a dependency.
+    if (entry.n !== undefined) specifiers.push(entry.n);
+    else if (rejectComputedImports) {
+      throw new Error(`[theme:boundary] ${importer} uses a computed import; manifest helpers must use literal module specifiers`);
+    }
+  }
+  return specifiers;
+}
+
+/**
+ * Reject private entry points before resolver plugins consume them.
+ * @param {string} specifier Module identifier from the theme source.
+ * @param {string} importer Filename used in diagnostics.
+ */
+export function assertPublicThemeSpecifier(specifier, importer) {
+  if ((specifier === '@mintfolio/core' || specifier.startsWith('@mintfolio/core/')) &&
+    !['@mintfolio/core/theme', '@mintfolio/core/astro', '@mintfolio/core/client', '@mintfolio/core/search'].includes(specifier) &&
+    !specifier.startsWith('@mintfolio/core/components/')) {
+    throw new Error(`[theme:boundary] ${importer} cannot import host-only Core entry ${specifier}; use its public theme API`);
+  }
+  if (PRIVATE_SPECIFIERS.has(specifier) || specifier.startsWith('virtual:mintfolio/')) {
+    throw new Error(`[theme:boundary] ${importer} cannot import ${specifier}; consume the public SDK and page props`);
+  }
+}
+
+/**
+ * Apply the same host-private path policy to native manifests and Vite modules.
+ * Resolvers must supply a real absolute path, with Vite queries already removed.
+ * path.relative also treats equivalent casing consistently on Windows.
+ * @param {string} filename Resolved dependency filename.
+ * @param {string} root Host project root.
+ * @param {string} importer Theme module that requested the dependency.
+ * @param {string} specifier Original import text for diagnostics.
+ */
+export function assertPublicThemeFile(filename, root, importer, specifier = filename) {
+  const privateDirectory = PRIVATE_DIRECTORIES.some((directory) => isWithin(filename, path.join(root, directory)));
+  const privateConfig = PRIVATE_CONFIGS.some((config) => path.relative(path.join(root, config), filename) === '');
+  const corePrivate = ['src/server', 'src/engine', 'src/routes'].some((directory) => isWithin(filename, path.join(CORE_ROOT, directory)));
+  if (privateDirectory || privateConfig || corePrivate) {
+    throw new Error(`[theme:boundary] ${importer} imports private host module ${specifier}`);
+  }
+}
+
+/**
+ * .js/.ts helpers need an explicit ESM package scope; CommonJS require() is not
+ * part of this static import contract. Explicit .mjs/.mts helpers need no scope.
+ * @param {string} filename Real helper filename.
+ * @returns {Promise<boolean>}
+ */
+async function isEsmHelper(filename) {
+  const extension = path.extname(filename).toLowerCase();
+  if (extension === '.mjs' || extension === '.mts') return true;
+  if (extension !== '.js' && extension !== '.ts') return false;
+  let directory = path.dirname(filename);
+  while (true) {
+    const packageSource = await readFile(path.join(directory, 'package.json'), 'utf8').catch(() => null);
+    if (packageSource !== null) {
+      try { return JSON.parse(packageSource).type === 'module'; }
+      catch { return false; }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return false;
+    directory = parent;
+  }
+}
+
+/**
+ * Check the manifest's local ESM graph before native import evaluates any of it.
+ * Literal package imports use their public exports; local helpers, including
+ * helpers outside the theme directory, are followed after realpath resolution.
+ * Package implementations remain dependencies rather than host/theme internals.
+ * This is a development contract check, not a sandbox for untrusted JavaScript.
+ * @param {string} manifestPath Real filename of the selected theme.mjs.
+ * @param {string} root Host project root used for private-path checks.
+ * @returns {Promise<string[]>} Inspected source files, for diagnostics/dev tooling.
+ */
+export async function checkManifestImports(manifestPath, root) {
+  /** @type {Set<string>} */
+  const visited = new Set();
+
+  /** @param {string} filename */
+  async function inspect(filename) {
+    if (visited.has(filename)) return;
+    visited.add(filename);
+    const source = await readFile(filename, 'utf8');
+    for (const specifier of await readModuleImports(source, filename, { rejectComputedImports: true })) {
+      assertPublicThemeSpecifier(specifier, filename);
+      let resolved;
+      try {
+        resolved = resolveImport(specifier, pathToFileURL(filename).href);
+      } catch {
+        throw new Error(`[theme:boundary] Cannot resolve ${specifier} imported by ${filename}`);
+      }
+      if (resolved.startsWith('node:')) continue;
+      if (!resolved.startsWith('file:')) {
+        throw new Error(`[theme:boundary] ${filename} must import local modules or installed packages, received ${specifier}`);
+      }
+      const dependency = await realpath(fileURLToPath(resolved));
+      assertPublicThemeFile(dependency, root, filename, specifier);
+
+      const packageImport = !specifier.startsWith('.') && !specifier.startsWith('/') && !specifier.startsWith('file:') && !specifier.startsWith('#') && !path.isAbsolute(specifier);
+      // Resolving a package's public export is sufficient here. Following the
+      // SDK's or a framework's internals would incorrectly classify them as themes.
+      if (packageImport) continue;
+      const extension = path.extname(dependency).toLowerCase();
+      if (extension === '.json') continue; // Data cannot import another module.
+      if (!await isEsmHelper(dependency)) {
+        throw new Error(`[theme:boundary] ${filename} imports ${specifier}; local manifest helpers must use .mjs/.mts or a package with type: "module"`);
+      }
+      await inspect(dependency);
+    }
+  }
+
+  await inspect(manifestPath);
+  return [...visited];
+}

package/src/engine/integration.mjs

@@ -0,0 +1,166 @@
+// @ts-check
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import { resolve as resolveImport } from 'import-meta-resolve';
+import { parse as parseAstro } from '@astrojs/compiler';
+import { loadTheme, isWithin } from './loader.mjs';
+import { readModuleImports, assertPublicThemeSpecifier, assertPublicThemeFile } from './import-boundary.mjs';
+
+const VIRTUAL_ID = 'virtual:mintfolio/theme';
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+const SITE_ID = 'virtual:mintfolio/site-config';
+const RESOLVED_SITE_ID = `\0${SITE_ID}`;
+
+/** @param {string} id Vite module id, possibly including an Astro script query. */
+function filenameFromId(id) {
+  const filename = id.split('?')[0].replace(/^\/@fs\//, '');
+  return filename.startsWith('file:') ? fileURLToPath(filename) : path.normalize(filename);
+}
+
+/**
+ * Inspect authored frontmatter/scripts before Astro rewrites special imports.
+ * Using the official parser avoids treating examples in HTML or JSON as code.
+ * @param {string} filename Absolute path to an authored Astro component.
+ * @returns {Promise<string[]>} Executable module fragments only.
+ */
+async function astroModuleSources(filename) {
+  const { ast } = await parseAstro(await readFile(filename, 'utf8'));
+  /** @type {string[]} */
+  const modules = [];
+  /** @param {import('@astrojs/compiler/types').RootNode['children'][number]} node */
+  const visit = (node) => {
+    if (node.type === 'frontmatter') modules.push(node.value);
+    if (node.type === 'element' && node.name === 'script') {
+      const type = node.attributes.find((attribute) => attribute.name === 'type')?.value;
+      if (!type || ['module', 'text/javascript', 'application/javascript'].includes(type)) {
+        modules.push(node.children.filter((child) => child.type === 'text').map((child) => child.value).join('\n'));
+      }
+    } else if ('children' in node) node.children.forEach(visit);
+  };
+  ast.children.forEach(visit);
+  return modules;
+}
+
+/**
+ * Only Core installs this integration. Themes declare page paths; they receive
+ * neither Astro integration hooks nor route injection callbacks.
+ * @param {import('@mintfolio/theme-api').ThemeConfiguration} selection
+ * @param {{routes?:boolean,siteConfig?:string}} [engine] Only the public Core entry enables owned routes.
+ * @returns {import('astro').AstroIntegration}
+ */
+export default function themeRuntime(selection = {}, engine = {}) {
+  return {
+    name: 'mintfolio:theme-runtime',
+    hooks: {
+      'astro:config:setup': async ({ config, updateConfig, addWatchFile, injectRoute, command, logger }) => {
+        const root = fileURLToPath(config.root);
+        const themeName = process.env.MINTFOLIO_THEME || selection.theme;
+        const changedSelection = Boolean(process.env.MINTFOLIO_THEME) && themeName !== selection.theme;
+        const active = await loadTheme({ root, theme: themeName, settings: changedSelection ? {} : selection.settings, overrides: changedSelection ? {} : selection.overrides, fresh: command === 'dev' });
+        const minimal = active.definition.manifest.id === 'minimal' ? active : await loadTheme({ root, theme: 'minimal', readUserConfig: false });
+        const siteConfig = path.resolve(root, engine.siteConfig ?? './site.config.ts');
+        if (engine.routes) {
+          addWatchFile(siteConfig);
+          for (const [pattern, source] of [
+            ['/', 'index.astro'], ['/about', 'about.astro'], ['/blog', 'blog/index.astro'],
+            ['/blog/[...slug]', 'blog/[...slug].astro'], ['/404', '404.astro'],
+            ['/rss.xml', 'rss.xml.ts'], ['/sitemap.xml', 'sitemap.xml.ts'],
+          ]) injectRoute({ pattern, entrypoint: new URL(`../routes/${source}`, import.meta.url) });
+        }
+        // Themes declare supported toolchains, not arbitrary engine hooks. The
+        // dependencies are resolved from the selected theme, so Core stays lean.
+        if (active.definition.build?.react) {
+          const react = (await import(resolveImport('@astrojs/react', pathToFileURL(active.manifestPath).href))).default;
+          updateConfig({ integrations: [react()] });
+        }
+        if (active.definition.build?.tailwind) {
+          const tailwind = (await import(resolveImport('@tailwindcss/vite', pathToFileURL(active.manifestPath).href))).default;
+          updateConfig({ vite: { plugins: [tailwind()] } });
+        }
+        // Classify explicit override modules, never their entire parent directory:
+        // a valid ./custom-post.astro must not classify the host itself as a theme.
+        const themeModules = new Set(active.overrideEntries);
+        const manifestPath = path.join(root, 'theme.config.mjs');
+        addWatchFile(manifestPath);
+        addWatchFile(active.themeConfigFile);
+        for (const filename of active.manifestDependencies) addWatchFile(filename);
+        logger.info(`Theme: ${active.definition.manifest.name} ${active.definition.manifest.version}`);
+        if (themeName === 'happyhues' || themeName === 'default') logger.warn('Use the installed package name "@mintfolio/theme-default". Only Minimal is bundled with Core.');
+        const optionalMissing = ['page', 'archive', 'notFound'].filter((kind) => !active.pages[kind]);
+        if (optionalMissing.length) logger.info(`Using lightweight Minimal renderers for: ${optionalMissing.join(', ')}`);
+        /** @type {Array<keyof import('@mintfolio/theme-api').ThemeCapabilities>} */
+        const features = ['search', 'tags', 'categories'];
+        for (const capability of features) {
+          if (!active.definition.capabilities[capability]) logger.warn(`${active.definition.manifest.id} does not declare ${capability}; its UI may omit that feature.`);
+        }
+
+        /** @type {import('vite').Plugin} */
+        const plugin = {
+          name: 'mintfolio:theme-module',
+          enforce: 'pre',
+          async transform(code, id) {
+            const filename = filenameFromId(id);
+            if (!(isWithin(filename, active.themeRoot) || themeModules.has(filename))) return null;
+            if (!/\.(?:astro|[cm]?[jt]sx?)$/.test(filename)) return null;
+            // A resolveId hook alone is insufficient: Astro can resolve its own
+            // virtual collection module before a user plugin sees the specifier.
+            const modules = filename.endsWith('.astro') ? await astroModuleSources(filename) : [code];
+            for (const source of modules) {
+              for (const specifier of await readModuleImports(source, filename)) assertPublicThemeSpecifier(specifier, filename);
+            }
+            return null;
+          },
+          async resolveId(source, importer, options) {
+            const importerFile = importer ? filenameFromId(importer) : '';
+            const isTheme = Boolean(importer) && (isWithin(importerFile, active.themeRoot) || themeModules.has(importerFile));
+            if (isTheme) assertPublicThemeSpecifier(source, importerFile);
+            if (source === VIRTUAL_ID) return RESOLVED_ID;
+            if (source === SITE_ID) return RESOLVED_SITE_ID;
+            if (!isTheme) return null;
+            const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+            if (!resolved) return null;
+            const filename = filenameFromId(resolved.id);
+            assertPublicThemeFile(filename, root, importerFile, source);
+            // Continue the boundary through user helpers. SDK/framework packages
+            // own their implementation; theme-local helpers cannot launder a Core import.
+            if (!resolved.external && path.isAbsolute(filename) && !isWithin(filename, path.join(root, 'node_modules')) && !isWithin(filename, path.join(root, 'packages/theme-api'))) {
+              themeModules.add(filename);
+            }
+            return resolved;
+          },
+          load(id) {
+            if (id === RESOLVED_SITE_ID) return `export { default } from ${JSON.stringify(siteConfig.replaceAll('\\', '/'))};`;
+            if (id !== RESOLVED_ID) return null;
+            // Explicit imports preserve Astro compilation and include only the
+            // chosen renderer's dependency graph, including its own CSS/assets.
+            const imports = [];
+            const renderers = [];
+            const fallbacks = [];
+            for (const [kind, filename] of Object.entries(active.pages)) {
+              imports.push(`import Page_${kind} from ${JSON.stringify(filename.replaceAll('\\', '/'))};`);
+              renderers.push(`${JSON.stringify(kind)}: Page_${kind}`);
+            }
+            // Import only missing semantic pages. A full theme does not pay for
+            // Minimal's document, article components, or client-side behaviors.
+            for (const kind of ['page', 'archive', 'notFound']) {
+              if (active.pages[kind]) continue;
+              imports.push(`import Fallback_${kind} from ${JSON.stringify(minimal.pages[kind].replaceAll('\\', '/'))};`);
+              fallbacks.push(`${JSON.stringify(kind)}: Fallback_${kind}`);
+            }
+            return `${imports.join('\n')}
+export const activeTheme = ${JSON.stringify({ definition: active.definition, settings: active.settings })};
+const pages = {${renderers.join(',')}};
+const fallbacks = {${fallbacks.join(',')}};
+export function getRenderer(kind) {
+  if (pages[kind]) return pages[kind];
+  if (kind === 'home' || kind === 'post') throw new Error('Missing required theme renderer: ' + kind);
+  return fallbacks[kind] || fallbacks.archive;
+}`;
+          },
+        };
+        updateConfig({ vite: { plugins: [plugin] } });
+      },
+    },
+  };
+}