@mintfolio/core 0.1.5

package/src/engine/loader.mjs

@@ -0,0 +1,114 @@
+// @ts-check
+import { realpath, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { resolve as resolveImport } from 'import-meta-resolve';
+import semver from 'semver';
+import { PAGE_KINDS, validateTheme, resolveSettings } from './schema.mjs';
+import { checkManifestImports } from './import-boundary.mjs';
+import { mergeThemeSettings, readThemeSettings, themeConfigPath } from './theme-config.mjs';
+
+let manifestRevision = 0;
+
+/** @param {string} filename @param {string} directory @returns {boolean} */
+export function isWithin(filename, directory) {
+  const relative = path.relative(directory, filename);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/**
+ * Locate the explicit theme entry. Packages must export './theme'; there is no
+ * implicit search through dependencies and no automatic same-name override.
+ * @param {string | undefined} specifier Omitted/Minimal, directory/manifest path, or installed npm name.
+ * @param {string} root Host project root.
+ * @returns {Promise<string>} Real manifest filename.
+ */
+async function resolveManifest(specifier, root) {
+  let filename;
+  if (!specifier || specifier === 'minimal') {
+    filename = fileURLToPath(new URL('../fallback/theme.mjs', import.meta.url));
+  } else if (['verdant', 'default', 'happyhues'].includes(specifier)) {
+    return resolveManifest('@mintfolio/theme-default', root);
+  } else if (specifier.startsWith('.') || path.isAbsolute(specifier)) {
+    filename = path.resolve(root, specifier);
+    if ((await stat(filename)).isDirectory()) filename = path.join(filename, 'theme.mjs');
+  } else {
+    const require = createRequire(path.join(root, 'package.json'));
+    filename = fileURLToPath(resolveImport(`${specifier}/theme`, pathToFileURL(path.join(root, 'package.json')).href));
+    // A package's renderer version is separate from its Theme API engine range.
+    const manifestDirectory = path.dirname(filename);
+    let directory = manifestDirectory;
+    while (directory !== path.dirname(directory)) {
+      try {
+        const packageData = JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+        if (packageData.name === specifier) {
+          const astroRange = packageData.peerDependencies?.astro;
+          const installedAstro = JSON.parse(await readFile(require.resolve('astro/package.json'), 'utf8')).version;
+          if (astroRange && !semver.satisfies(installedAstro, astroRange)) throw new Error(`[theme:renderer] ${specifier} requires Astro ${astroRange}; installed ${installedAstro}`);
+          break;
+        }
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith('[theme:renderer]')) throw error;
+      }
+      directory = path.dirname(directory);
+    }
+  }
+  return realpath(filename);
+}
+
+/**
+ * Validate one renderer path after resolving symlinks. Theme declarations stay
+ * within the theme; explicit user overrides stay within the host workspace.
+ * @param {string} source Relative renderer filename.
+ * @param {string} directory Allowed root and resolution base.
+ * @param {string} kind Semantic page key for diagnostics.
+ * @returns {Promise<string>}
+ */
+async function resolvePage(source, directory, kind) {
+  const filename = await realpath(path.resolve(directory, source));
+  if (!isWithin(filename, await realpath(directory)) || path.extname(filename) !== '.astro' || !(await stat(filename)).isFile()) {
+    throw new Error(`[theme:page] ${kind}: renderer must be an Astro file inside ${directory}`);
+  }
+  return filename;
+}
+
+/**
+ * Load a single theme for the current build. The caller owns routes and Vite
+ * compilation; this function never runs Astro components or writes resources.
+ * @param {{root:string, theme?:string, settings?:unknown, overrides?:{pages?:Record<string,string>}, fresh?:boolean, readUserConfig?:boolean}} options
+ * readUserConfig is disabled only while creating configuration files; normal loads
+ * always combine the host's theme-specific file with explicit inline settings.
+ */
+export async function loadTheme({ root, theme, settings = {}, overrides = {}, fresh = false, readUserConfig = true }) {
+  const manifestPath = await resolveManifest(theme, root);
+  const themeRoot = path.dirname(manifestPath);
+  // Native ESM loading does not run Vite's hooks. Inspect its local dependency
+  // graph first so a forbidden helper cannot execute before schema validation.
+  const manifestDependencies = await checkManifestImports(manifestPath, root);
+  const entryUrl = pathToFileURL(manifestPath);
+  // Development restarts need a fresh manifest, not Node's old ESM module entry.
+  if (fresh) entryUrl.searchParams.set('revision', `${Date.now()}-${++manifestRevision}`);
+  const definition = validateTheme((await import(entryUrl.href)).default, manifestPath);
+  const userConfig = readUserConfig ? await readThemeSettings(root, definition.manifest.id)
+    : { filename: themeConfigPath(root, definition.manifest.id), settings: {} };
+  const resolvedSettings = resolveSettings(definition, mergeThemeSettings(userConfig.settings, settings));
+  /** @type {Record<string,string>} */
+  const pages = {};
+  for (const [kind, source] of Object.entries(definition.pages)) {
+    if (source) pages[kind] = await resolvePage(source, themeRoot, kind);
+  }
+  const overrideRoots = [];
+  const overrideEntries = [];
+  if (Object.keys(overrides).some((key) => key !== 'pages')) throw new Error('[theme:overrides] Only explicit pages overrides are supported');
+  for (const [kind, source] of Object.entries(overrides.pages ?? {})) {
+    if (!PAGE_KINDS.includes(kind) || typeof source !== 'string') throw new Error(`[theme:overrides] Invalid page ${kind}`);
+    const filename = await resolvePage(source, root, kind);
+    const relative = path.relative(root, filename).replaceAll('\\', '/');
+    if (relative.startsWith('src/core/') || relative.startsWith('src/pages/') || relative.startsWith('src/theme/') || relative.startsWith('packages/core/src/engine/') || relative.startsWith('packages/core/src/server/') || relative.startsWith('packages/core/src/routes/')) throw new Error(`[theme:overrides] ${kind}: Core files cannot be used as theme overrides`);
+    pages[kind] = filename;
+    overrideRoots.push(path.dirname(filename));
+    overrideEntries.push(filename);
+  }
+  return { definition, settings: resolvedSettings, pages, manifestPath, manifestDependencies, themeRoot, overrideRoots, overrideEntries, themeConfigFile: userConfig.filename };
+}

package/src/engine/runtime/post-page.astro

@@ -0,0 +1,35 @@
+---
+import type { CollectionEntry } from 'astro:content';
+import type { ArticleHeading, ArticleBody, PostPageData } from '@mintfolio/theme-api/astro';
+import { encryptArticle } from '@mintfolio/theme-api/crypto';
+import { activeTheme, getRenderer } from 'virtual:mintfolio/theme';
+import { createThemeContext } from '../context';
+import { toPostSummary, isProtectedPost } from '../../server/posts';
+import { pageSeo } from '../../server/seo';
+
+/** Private adapter props; only the Core article route can supply collection data. */
+interface Props {
+  entry: CollectionEntry<'blog'>;
+  headings: ArticleHeading[];
+}
+const { entry, headings } = Astro.props;
+const theme = await createThemeContext(activeTheme);
+const post = toPostSummary(entry);
+// The slot is compiled by Astro before any theme sees the result. Protected
+// content and headings are encrypted together and never become renderer props.
+const html = await Astro.slots.render('default');
+const body: ArticleBody = isProtectedPost(entry)
+  ? { kind: 'protected', postId: entry.id, payload: await encryptArticle(JSON.stringify({ version: 1, html, headings }), entry.data.password!, entry.id) }
+  : { kind: 'public', html, headings };
+const posts = (await theme.content.posts()).items;
+const index = posts.findIndex((item) => item.id === entry.id);
+const page: PostPageData = {
+  kind: 'post', post, body,
+  title: post.title, description: post.description, url: post.url,
+  seo: pageSeo(theme.site, post.title, post.description, post.url, post),
+  previous: posts[index - 1] ?? null,
+  next: posts[index + 1] ?? null,
+};
+const Renderer = getRenderer('post');
+---
+<Renderer theme={theme} page={page} />

package/src/engine/schema.mjs

@@ -0,0 +1,125 @@
+// @ts-check
+import { z } from 'astro/zod';
+import semver from 'semver';
+
+/** Theme contract version; independent of the application and Astro versions. */
+export const THEME_ENGINE_VERSION = '1.0.0';
+export const PAGE_KINDS = ['home', 'post', 'page', 'archive', 'notFound'];
+
+const label = { label: z.string().min(1), description: z.string().optional() };
+const color = z.string().regex(/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i, 'Expected a hexadecimal CSS color');
+/** @type {import('astro/zod').z.ZodType<import('@mintfolio/theme-api').SettingDefinition>} */
+const settingSchema = z.lazy(() => z.discriminatedUnion('type', [
+  z.object({ ...label, type: z.literal('string'), default: z.string() }).strict(),
+  z.object({ ...label, type: z.literal('boolean'), default: z.boolean() }).strict(),
+  z.object({ ...label, type: z.literal('number'), default: z.number(), min: z.number().optional(), max: z.number().optional() }).strict(),
+  z.object({ ...label, type: z.literal('select'), default: z.string(), options: z.array(z.string()).min(1) }).strict(),
+  z.object({ ...label, type: z.literal('color'), default: color }).strict(),
+  z.object({ ...label, type: z.literal('object'), default: z.record(z.string(), z.unknown()), properties: z.record(z.string(), settingSchema) }).strict(),
+  z.object({ ...label, type: z.literal('array'), default: z.array(z.unknown()), items: settingSchema }).strict(),
+]).superRefine((setting, context) => {
+  if (setting.type === 'number') {
+    if ((setting.min !== undefined && setting.default < setting.min) || (setting.max !== undefined && setting.default > setting.max) || (setting.min !== undefined && setting.max !== undefined && setting.min > setting.max)) {
+      context.addIssue({ code: 'custom', message: 'The default and bounds must describe a valid number interval' });
+    }
+  }
+  if (setting.type === 'select' && (!setting.options.includes(setting.default) || new Set(setting.options).size !== setting.options.length)) {
+    context.addIssue({ code: 'custom', message: 'Select options must be unique and include the default' });
+  }
+}));
+
+const pagePath = z.string().startsWith('./').endsWith('.astro');
+const pagesSchema = z.object({
+  home: pagePath, post: pagePath,
+  page: pagePath.optional(), archive: pagePath.optional(), notFound: pagePath.optional(),
+}).strict();
+
+const definitionSchema = z.object({
+  manifest: z.object({
+    id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    name: z.string().min(1), version: z.string().refine((value) => semver.valid(value) !== null, 'Invalid semantic version'),
+    author: z.string().min(1), description: z.string().min(1),
+    engine: z.string().refine((value) => semver.validRange(value) !== null, 'Invalid engine range'),
+  }).strict(),
+  capabilities: z.object({
+    search: z.boolean().default(false), tags: z.boolean().default(false), categories: z.boolean().default(false),
+    toc: z.boolean().default(false), darkMode: z.boolean().default(false), encryptedPosts: z.boolean().default(false),
+    comments: z.boolean().default(false), i18n: z.boolean().default(false),
+  }).strict().default({ search: false, tags: false, categories: false, toc: false, darkMode: false, encryptedPosts: false, comments: false, i18n: false }),
+  pages: pagesSchema,
+  settings: z.record(z.string(), settingSchema).default({}),
+  build: z.object({ react: z.boolean().optional(), tailwind: z.boolean().optional() }).strict().optional(),
+}).strict();
+
+/**
+ * Parse untrusted theme metadata before any renderer is imported.
+ * Errors include the field path and source so both CLI and build logs are useful.
+ * @param {unknown} input Module default export.
+ * @param {string} source Manifest path used in diagnostics.
+ * @returns {import('@mintfolio/theme-api').ThemeDefinition}
+ */
+export function validateTheme(input, source) {
+  const result = definitionSchema.safeParse(input);
+  if (!result.success) {
+    const details = result.error.issues.map((issue) => `${issue.path.join('.') || 'theme'}: ${issue.message}`).join('\n');
+    throw new Error(`[theme:manifest] ${source}\n${details}`);
+  }
+  if (!semver.satisfies(THEME_ENGINE_VERSION, result.data.manifest.engine)) {
+    throw new Error(`[theme:engine] ${result.data.manifest.id} requires ${result.data.manifest.engine}; runtime is ${THEME_ENGINE_VERSION}`);
+  }
+  // Validate nested defaults through the same path used for user overrides.
+  resolveSettings(result.data, {});
+  return result.data;
+}
+
+/**
+ * Resolve declarative visual settings. Unknown keys and invalid values fail early
+ * instead of silently producing a partially configured theme.
+ * @param {import('@mintfolio/theme-api').ThemeDefinition} definition Validated theme.
+ * @param {unknown} input User overrides; defaults are applied when absent.
+ * @returns {Record<string, unknown>}
+ */
+export function resolveSettings(definition, input = {}) {
+  const user = z.record(z.string(), z.unknown()).parse(input);
+  return resolveObject(definition.settings, user, definition.manifest.id);
+}
+
+/**
+ * Recursively merge validated object defaults, preserving explicit array order.
+ * @param {import('@mintfolio/theme-api').SettingsSchema} schema
+ * @param {Record<string, unknown>} user
+ * @param {string} field
+ * @returns {Record<string, unknown>}
+ */
+function resolveObject(schema, user, field) {
+  /** @type {Record<string, unknown>} */
+  const values = {};
+  for (const key of Object.keys(user)) {
+    if (!Object.hasOwn(schema, key)) throw new Error(`[theme:settings] ${field}.${key}: unknown setting`);
+  }
+  for (const [key, setting] of Object.entries(schema)) {
+    const value = resolveValue(setting, Object.hasOwn(user, key) ? user[key] : setting.default, `${field}.${key}`);
+    Object.defineProperty(values, key, { value, enumerable: true });
+  }
+  return values;
+}
+
+/** @param {import('@mintfolio/theme-api').SettingDefinition} setting @param {unknown} value @param {string} field @returns {unknown} */
+function resolveValue(setting, value, field) {
+  let valid = false;
+  switch (setting.type) {
+    case 'boolean': valid = typeof value === 'boolean'; break;
+    case 'number': valid = typeof value === 'number' && Number.isFinite(value) && (setting.min === undefined || value >= setting.min) && (setting.max === undefined || value <= setting.max); break;
+    case 'select': valid = typeof value === 'string' && setting.options.includes(value); break;
+    case 'color': valid = color.safeParse(value).success; break;
+    case 'string': valid = typeof value === 'string'; break;
+    case 'array':
+      if (Array.isArray(value)) return value.map((item, index) => resolveValue(setting.items, item, `${field}[${index}]`));
+      break;
+    case 'object':
+      if (value && typeof value === 'object' && !Array.isArray(value)) return resolveObject(setting.properties, { ...setting.default, ...value }, field);
+      break;
+  }
+  if (!valid) throw new Error(`[theme:settings] ${field}: invalid ${setting.type} value`);
+  return value;
+}

package/src/engine/theme-config.mjs

@@ -0,0 +1,67 @@
+// @ts-check
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+let revision = 0;
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+/**
+ * A theme gets one predictable settings file in the host root. Theme ids must
+ * already satisfy the manifest rules; never accept directory components here.
+ * @param {string} root Absolute host project root.
+ * @param {string} id Validated theme manifest id.
+ * @returns {string} Absolute host-owned settings filename.
+ */
+export function themeConfigPath(root, id) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) throw new Error('[theme:config] Invalid theme id');
+  return path.join(root, `theme-${id}.config.mjs`);
+}
+
+/**
+ * Merge a theme settings file with legacy inline settings. Inline values win;
+ * nested objects merge recursively, while arrays are replaced as complete lists.
+ * @param {unknown} fileSettings Default export of the theme-specific config.
+ * @param {unknown} inlineSettings Explicit theme.config.mjs settings.
+ * @returns {Record<string, unknown>} Unvalidated combined settings, without mutating either input.
+ */
+export function mergeThemeSettings(fileSettings, inlineSettings) {
+  if (!isRecord(fileSettings) || !isRecord(inlineSettings)) throw new Error('[theme:config] Settings must be a plain object');
+  return Object.fromEntries([...new Set([...Object.keys(fileSettings), ...Object.keys(inlineSettings)])].map((key) => {
+    if (!Object.hasOwn(inlineSettings, key)) return [key, fileSettings[key]];
+    const fromFile = fileSettings[key];
+    const inline = inlineSettings[key];
+    return [key, isRecord(fromFile) && isRecord(inline) ? mergeThemeSettings(fromFile, inline) : inline];
+  }));
+}
+
+/**
+ * Read the site's own ESM settings. Missing files preserve existing defaults;
+ * syntax errors and invalid exports fail with the exact editable filename.
+ * @param {string} root Absolute host root.
+ * @param {string} id Validated manifest id.
+ * @returns {Promise<{filename:string, settings:Record<string,unknown>}>}
+ */
+export async function readThemeSettings(root, id) {
+  const filename = themeConfigPath(root, id);
+  try { await stat(filename); }
+  catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return { filename, settings: {} };
+    throw error;
+  }
+  try {
+    // A config watcher restarts the integration; do not reuse the previous ESM value.
+    const entry = pathToFileURL(filename);
+    entry.searchParams.set('revision', `${Date.now()}-${++revision}`);
+    const value = (await import(entry.href)).default;
+    if (!isRecord(value)) throw new Error('default export must be a plain settings object');
+    return { filename, settings: value };
+  } catch (error) {
+    throw new Error(`[theme:config] ${filename}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}

package/src/engine/virtual.d.ts

@@ -0,0 +1,12 @@
+declare module 'virtual:mintfolio/theme' {
+  /** Host-only selected theme; theme packages consume injected public props. */
+  export const activeTheme: import('./context').ActiveTheme;
+  /** Each concrete renderer narrows page/settings; the dispatcher accepts the public union. */
+  export function getRenderer(kind: import('@mintfolio/theme-api').PageKind):
+    (props: import('@mintfolio/theme-api/astro').PageProps) => ReturnType<typeof import('../fallback/pages/not-found.astro').default>;
+}
+
+declare module 'virtual:mintfolio/site-config' {
+  const config: import('../public/config').SiteConfigInput;
+  export default config;
+}

package/src/fallback/layouts/MinimalLayout.astro

@@ -0,0 +1,45 @@
+---
+import SeoHead from '@mintfolio/theme-api/SeoHead.astro';
+import '../styles/minimal.css';
+import type { MinimalSettings } from '../settings';
+import type { PublicSite, NavigationLink } from '@mintfolio/theme-api';
+import type { SeoData } from '@mintfolio/theme-api/astro';
+
+interface Props {
+  /** Public, projected site information supplied by the runtime. */
+  readonly site: Pick<PublicSite, 'title' | 'profile'>;
+  /** Core-owned destinations that the theme may render in its own navigation. */
+  readonly navigation: readonly NavigationLink[];
+  /** Core-owned canonical home address; never reconstructed from a route string. */
+  readonly homeUrl: string;
+  /** Metadata calculated by Core; the theme does not infer canonical URLs itself. */
+  readonly seo: SeoData;
+  /** Validated Minimal theme settings. */
+  readonly settings: Partial<MinimalSettings> | Record<string, unknown>;
+}
+
+const { site, navigation, homeUrl, seo, settings } = Astro.props;
+// An optional-page fallback can receive another theme's settings. Use only
+// Minimal's own validated primitives and apply its defaults when absent.
+const width = typeof settings.maxWidth === 'number' && Number.isFinite(settings.maxWidth) ? Math.max(480, Math.min(1200, settings.maxWidth)) : 760;
+const accent = typeof settings.accentColor === 'string' && /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(settings.accentColor) ? settings.accentColor : '#2255aa';
+---
+
+<!doctype html>
+<html lang={seo.language} class="mintfolio-minimal">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <SeoHead seo={seo} />
+  </head>
+  <body style={`--minimal-width: ${width}px; --minimal-accent: ${accent};`}>
+    <div class="minimal-shell">
+      <a class="minimal-site-name" href={homeUrl}>{site.title}</a>
+      <nav class="minimal-navigation" aria-label="网站导航">
+        {navigation.map((item) => <a href={item.url}>{item.label}</a>)}
+      </nav>
+      <main class="minimal-main"><slot /></main>
+      <footer class="minimal-footer">{site.profile.signature ?? site.profile.name}</footer>
+    </div>
+  </body>
+</html>

package/src/fallback/pages/archive.astro

@@ -0,0 +1,13 @@
+---
+import type { ListPageData, PageProps } from '@mintfolio/core/astro';
+import PostArchive from '@mintfolio/core/components/PostArchive.astro';
+import MinimalLayout from '../layouts/MinimalLayout.astro';
+import type { MinimalSettings } from '../settings';
+interface Props extends PageProps<MinimalSettings, ListPageData> {}
+const { theme, page } = Astro.props;
+const [tags, categories] = await Promise.all([theme.taxonomy.tags(), theme.taxonomy.categories()]);
+---
+<MinimalLayout site={theme.site} navigation={theme.navigation} homeUrl={theme.urls.home()} seo={page.seo} settings={theme.settings}>
+  <header><p class="minimal-kicker">文章归档</p><h1 class="minimal-title">{page.title}</h1><p class="minimal-description">{page.description}</p></header>
+  <PostArchive posts={page.posts} tags={tags} categories={categories} filters={page.filters} language={theme.site.language} />
+</MinimalLayout>

package/src/fallback/pages/home.astro

@@ -0,0 +1,44 @@
+---
+import type { HomePageData, PageProps } from '@mintfolio/theme-api/astro';
+import MinimalLayout from '../layouts/MinimalLayout.astro';
+import type { MinimalSettings } from '../settings';
+
+interface Props extends PageProps<MinimalSettings, HomePageData> {}
+
+const { theme, page } = Astro.props;
+
+/** Converts the Core ISO date DTO to the visitor's readable locale date. */
+const formatDate = (value: string): string => new Intl.DateTimeFormat(theme.site.language, {
+  dateStyle: 'medium',
+}).format(new Date(value));
+---
+
+<MinimalLayout site={theme.site} navigation={theme.navigation} homeUrl={theme.urls.home()} seo={page.seo} settings={theme.settings}>
+  <section aria-labelledby="minimal-home-title">
+    <p class="minimal-kicker">{theme.site.profile.name}</p>
+    <h1 id="minimal-home-title" class="minimal-title">{page.title}</h1>
+    <p class="minimal-description">{page.description || theme.site.description}</p>
+  </section>
+
+  <section aria-label="文章">
+    {page.posts.length === 0 ? (
+      <p class="minimal-empty">暂时还没有发布文章。</p>
+    ) : (
+      <ol class="minimal-post-list">
+        {page.posts.map((post) => (
+          <li>
+            <h2><a href={post.url}>{post.title}</a></h2>
+            <p class="minimal-meta"><time datetime={post.publishedAt}>{formatDate(post.publishedAt)}</time>{post.protected ? ' · 受保护' : ''}</p>
+            <p>{post.description}</p>
+            <div class="minimal-terms" aria-label="Post taxonomy">
+              <a href={post.category.url}>{post.category.label}</a>
+              {post.tags.map((tag) => <a href={tag.url}>#{tag.label}</a>)}
+            </div>
+          </li>
+        ))}
+      </ol>
+    )}
+  </section>
+
+  <p><a href={theme.urls.archive()}>浏览文章归档 →</a></p>
+</MinimalLayout>

package/src/fallback/pages/not-found.astro

@@ -0,0 +1,18 @@
+---
+import type { NotFoundPageData, PageProps } from '@mintfolio/theme-api/astro';
+import MinimalLayout from '../layouts/MinimalLayout.astro';
+import type { MinimalSettings } from '../settings';
+
+interface Props extends PageProps<MinimalSettings, NotFoundPageData> {}
+
+const { theme, page } = Astro.props;
+---
+
+<MinimalLayout site={theme.site} navigation={theme.navigation} homeUrl={theme.urls.home()} seo={page.seo} settings={theme.settings}>
+  <section aria-labelledby="minimal-not-found-title">
+    <p class="minimal-kicker">404</p>
+    <h1 id="minimal-not-found-title" class="minimal-title">{page.title}</h1>
+    <p class="minimal-description">{page.description}</p>
+    <p><a href={theme.urls.home()}>返回首页</a> · <a href={theme.urls.archive()}>浏览文章归档</a></p>
+  </section>
+</MinimalLayout>

package/src/fallback/pages/page.astro

@@ -0,0 +1,39 @@
+---
+import type { PageProps, StaticPageData } from '@mintfolio/theme-api/astro';
+import MinimalLayout from '../layouts/MinimalLayout.astro';
+import type { MinimalSettings } from '../settings';
+
+interface Props extends PageProps<MinimalSettings, StaticPageData> {}
+
+const { theme, page } = Astro.props;
+const profile = page.profile;
+---
+
+<MinimalLayout site={theme.site} navigation={theme.navigation} homeUrl={theme.urls.home()} seo={page.seo} settings={theme.settings}>
+  <article class="minimal-article">
+    <header>
+      <p class="minimal-kicker">{page.id}</p>
+      <h1>{page.title}</h1>
+      <p>{page.description}</p>
+    </header>
+    <div class="minimal-prose">
+      <p>{profile.bio}</p>
+      <dl>
+        <dt>姓名</dt>
+        <dd>{profile.name}</dd>
+        <dt>所在地</dt>
+        <dd>{profile.location}</dd>
+        <dt>联系方式</dt>
+        <dd><a href={`mailto:${theme.site.contact.email}`}>{theme.site.contact.email}</a></dd>
+      </dl>
+      {theme.site.social.length > 0 && (
+        <section aria-labelledby="minimal-social-title">
+          <h2 id="minimal-social-title">其他平台</h2>
+          <ul>
+            {theme.site.social.map((social) => <li><a href={social.url}>{social.platform}</a></li>)}
+          </ul>
+        </section>
+      )}
+    </div>
+  </article>
+</MinimalLayout>

package/src/fallback/pages/post.astro

@@ -0,0 +1,41 @@
+---
+import type { PageProps, PostPageData } from '@mintfolio/theme-api/astro';
+import ProtectedArticle from '@mintfolio/core/components/ProtectedArticle.astro';
+import MinimalLayout from '../layouts/MinimalLayout.astro';
+import type { MinimalSettings } from '../settings';
+
+interface Props extends PageProps<MinimalSettings, PostPageData> {}
+
+const { theme, page } = Astro.props;
+const formatDate = (value: string): string => new Intl.DateTimeFormat(theme.site.language, {
+  dateStyle: 'long',
+}).format(new Date(value));
+const protectedBody = page.body.kind === 'protected' ? page.body : undefined;
+---
+
+<MinimalLayout site={theme.site} navigation={theme.navigation} homeUrl={theme.urls.home()} seo={page.seo} settings={theme.settings}>
+  <article class="minimal-article">
+    <header>
+      <p class="minimal-kicker"><a href={page.post.category.url}>{page.post.category.label}</a></p>
+      <h1>{page.post.title}</h1>
+      <p class="minimal-meta"><time datetime={page.post.publishedAt}>{formatDate(page.post.publishedAt)}</time></p>
+      <p>{page.post.description}</p>
+      {page.post.tags.length > 0 && (
+        <div class="minimal-terms" aria-label="标签">
+          {page.post.tags.map((tag) => <a href={tag.url}>#{tag.label}</a>)}
+        </div>
+      )}
+    </header>
+
+    {page.body.kind === 'public' ? (
+      <div class="minimal-prose" set:html={page.body.html} />
+    ) : protectedBody && (
+      <ProtectedArticle body={protectedBody} />
+    )}
+  </article>
+
+  <nav class="minimal-pager" aria-label="相邻文章">
+    <span>{page.previous ? <a href={page.previous.url}>← {page.previous.title}</a> : ''}</span>
+    <span>{page.next ? <a href={page.next.url}>{page.next.title} →</a> : ''}</span>
+  </nav>
+</MinimalLayout>

package/src/fallback/settings.ts

@@ -0,0 +1,8 @@
+/**
+ * Values validated from Minimal's manifest settings before a page renderer runs.
+ * maxWidth is a pixel value; accentColor is a validated hexadecimal CSS color.
+ */
+export interface MinimalSettings {
+  readonly maxWidth: number;
+  readonly accentColor: string;
+}