@mintfolio/core 0.1.5

package/src/fallback/styles/minimal.css

@@ -0,0 +1,109 @@
+.mintfolio-minimal {
+  color-scheme: light;
+  font-family: ui-monospace, 'SFMono-Regular', Consolas, 'Liberation Mono', monospace;
+  background: #fcfcfa;
+  color: #171717;
+}
+
+.mintfolio-minimal * { box-sizing: border-box; }
+
+html.mintfolio-minimal { min-width: 320px; }
+
+.mintfolio-minimal body {
+  margin: 0;
+  min-height: 100vh;
+  background: #fcfcfa;
+  color: #171717;
+  font-size: 16px;
+  line-height: 1.7;
+}
+
+.mintfolio-minimal a { color: var(--minimal-accent); text-underline-offset: 0.18em; }
+.mintfolio-minimal a:hover { text-decoration-thickness: 2px; }
+
+.mintfolio-minimal :is(button, input, select) { font: inherit; }
+
+.mintfolio-minimal .sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+}
+
+.minimal-shell {
+  width: min(calc(100% - 2rem), var(--minimal-width));
+  margin: 0 auto;
+  padding: 2.5rem 0 4rem;
+}
+
+.minimal-site-name { color: inherit; font-weight: 700; text-decoration: none; }
+
+.minimal-navigation {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem 1rem;
+  margin: 0.65rem 0 3.25rem;
+}
+
+.minimal-navigation a { color: #4c4c4c; }
+
+.minimal-main > * + * { margin-top: 2.25rem; }
+
+.minimal-kicker, .minimal-meta, .minimal-empty, .minimal-footer {
+  color: #666;
+  font-size: 0.9rem;
+}
+
+.minimal-title {
+  max-width: 22ch;
+  margin: 0;
+  font-size: clamp(2rem, 7vw, 3.8rem);
+  line-height: 1.08;
+  letter-spacing: -0.065em;
+}
+
+.minimal-description { max-width: 58ch; margin: 1.25rem 0 0; }
+
+.minimal-post-list { list-style: none; margin: 0; padding: 0; }
+.minimal-post-list > li { border-top: 1px solid #d8d8d4; padding: 1.1rem 0 1.2rem; }
+.minimal-post-list > li:last-child { border-bottom: 1px solid #d8d8d4; }
+.minimal-post-list h2 { margin: 0; font-size: 1.1rem; line-height: 1.45; }
+.minimal-post-list p { margin: 0.35rem 0 0; color: #4c4c4c; }
+
+.minimal-terms { display: flex; flex-wrap: wrap; gap: 0.35rem 0.75rem; margin-top: 0.45rem; font-size: 0.85rem; }
+.minimal-terms a { color: #5b5b5b; }
+
+.minimal-article header { border-bottom: 1px solid #d8d8d4; padding-bottom: 1.5rem; }
+.minimal-article h1 { margin: 0; font-size: clamp(2rem, 6vw, 3.25rem); line-height: 1.15; letter-spacing: -0.055em; }
+.minimal-article header p { margin: 0.85rem 0 0; }
+
+.minimal-prose { margin-top: 2.25rem; }
+.minimal-prose :is(h2, h3, h4) { line-height: 1.25; margin-top: 2.4em; }
+.minimal-prose img { height: auto; max-width: 100%; }
+.minimal-prose pre { max-width: 100%; overflow: auto; padding: 1rem; background: #efefea; }
+.minimal-prose blockquote { border-left: 2px solid #aaa; margin-left: 0; padding-left: 1rem; color: #4c4c4c; }
+
+.minimal-protected { border: 1px solid #c8c8c2; padding: 1.25rem; }
+.minimal-protected p { margin-top: 0; }
+.minimal-protected form { display: flex; flex-wrap: wrap; gap: 0.7rem; }
+.minimal-protected input { min-width: min(100%, 18rem); border: 1px solid #999; border-radius: 0; padding: 0.45rem 0.55rem; }
+.minimal-protected button { border: 1px solid var(--minimal-accent); border-radius: 0; background: var(--minimal-accent); color: white; cursor: pointer; padding: 0.45rem 0.75rem; }
+.minimal-protected button[hidden], .minimal-protected [hidden] { display: none; }
+.minimal-protected .minimal-relock { background: transparent; color: var(--minimal-accent); }
+.minimal-protected-error { color: #a60000; }
+
+.minimal-filter-form { display: grid; gap: 0.8rem; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.minimal-filter-form label { display: grid; gap: 0.25rem; font-size: 0.9rem; }
+.minimal-filter-form input, .minimal-filter-form select { min-width: 0; border: 1px solid #999; border-radius: 0; background: #fff; padding: 0.45rem; }
+.minimal-filter-status { color: #666; font-size: 0.9rem; }
+
+.minimal-pager { display: flex; justify-content: space-between; gap: 1rem; border-top: 1px solid #d8d8d4; padding-top: 1.25rem; }
+.minimal-footer { border-top: 1px solid #d8d8d4; margin-top: 4rem; padding-top: 1rem; }
+
+@media (max-width: 620px) {
+  .minimal-shell { padding-top: 1.5rem; }
+  .minimal-navigation { margin-bottom: 2.25rem; }
+  .minimal-filter-form { grid-template-columns: 1fr; }
+}

package/src/fallback/theme.mjs

@@ -0,0 +1,48 @@
+import { defineTheme } from '@mintfolio/theme-api';
+
+/**
+ * The Minimal theme deliberately keeps presentation to a text-first reading
+ * experience. Content, routing, and protected-article handling remain owned
+ * by the Mintfolio runtime and are supplied through the public theme API.
+ */
+export default defineTheme({
+  manifest: {
+    id: 'minimal',
+    name: 'Minimal',
+    version: '1.0.0',
+    author: 'Mintfolio contributors',
+    description: '用于阅读和文字归档的单栏博客主题。',
+    engine: '^1.0.0',
+  },
+  capabilities: {
+    search: true,
+    tags: true,
+    categories: true,
+    toc: false,
+    darkMode: false,
+    encryptedPosts: true,
+  },
+  pages: {
+    home: './pages/home.astro',
+    post: './pages/post.astro',
+    archive: './pages/archive.astro',
+    page: './pages/page.astro',
+    notFound: './pages/not-found.astro',
+  },
+  settings: {
+    maxWidth: {
+      type: 'number',
+      label: '正文宽度',
+      description: '阅读栏的最大宽度，单位为像素。',
+      default: 760,
+      min: 480,
+      max: 1200,
+    },
+    accentColor: {
+      type: 'color',
+      label: '强调色',
+      description: '链接和交互控件使用的颜色。',
+      default: '#2255aa',
+    },
+  },
+});

package/src/integration.d.ts

@@ -0,0 +1,10 @@
+import type { AstroIntegration } from 'astro';
+import type { ThemeConfiguration } from '@mintfolio/theme-api';
+
+/** Build-time engine options. Omitted theme selects Core's lightweight Minimal. */
+export interface MintfolioOptions extends Partial<ThemeConfiguration> {
+  /** Site module is compiled by Astro, so local image imports remain supported. */
+  siteConfig?: string;
+}
+/** Inject Core-owned blog routes and compile exactly one selected theme. */
+export default function mintfolio(options?: MintfolioOptions): AstroIntegration;

package/src/integration.mjs

@@ -0,0 +1,10 @@
+import themeRuntime from './engine/integration.mjs';
+
+/**
+ * Public engine entry: a consuming site owns content/config, Core injects routes.
+ * @param {import('./integration').MintfolioOptions} [options]
+ * @returns {import('astro').AstroIntegration}
+ */
+export default function mintfolio(options = {}) {
+  return themeRuntime(options, { routes: true, siteConfig: options.siteConfig });
+}

package/src/public/astro.ts

@@ -0,0 +1,2 @@
+/** Renderer props and page semantics shared by every theme. */
+export * from '@mintfolio/theme-api/astro';

package/src/public/client.ts

@@ -0,0 +1,10 @@
+/** Optional browser behavior; importing a controller does not mount global UI. */
+export * from '@mintfolio/theme-api/client';
+export * from '../client/lifecycle.js';
+export * from '../client/postList.js';
+export * from '../client/protectedArticle.js';
+export * from '../client/toc.js';
+export * from '../client/lightbox.js';
+export * from '../client/archive.js';
+export * from '../client/code.js';
+export * from '../client/navigation.js';

package/src/public/config.ts

@@ -0,0 +1,43 @@
+import type { ContactInfo, Project, PublicProfile, SkillCategory, SocialLink } from '@mintfolio/theme-api';
+
+/** Host-owned content. Theme-specific display settings belong in theme.config.mjs. */
+export interface SiteConfig {
+  site: { title: string; url: string; description: string; language: string };
+  profile: PublicProfile;
+  social: SocialLink[];
+  skills: SkillCategory[];
+  projects: Project[];
+  contact: ContactInfo;
+  icp?: string;
+}
+
+/** Only a title and absolute HTTP(S) site URL are required to create a blog. */
+export interface SiteConfigInput {
+  site: Pick<SiteConfig['site'], 'title' | 'url'> & Partial<Omit<SiteConfig['site'], 'title' | 'url'>>;
+  profile?: Partial<PublicProfile>;
+  social?: SocialLink[];
+  skills?: SkillCategory[];
+  projects?: Project[];
+  contact?: Partial<ContactInfo>;
+  icp?: string;
+}
+
+/**
+ * Complete optional author fields without exposing any theme-specific defaults.
+ * @param input Public site content, including the deployment URL.
+ * @returns Fully populated content suitable for Core's explicit public projection.
+ */
+export function defineSiteConfig(input: SiteConfigInput): SiteConfig {
+  const url = new URL(input.site.url);
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('[mintfolio:config] site.url must use HTTP or HTTPS');
+  if (!input.site.title.trim()) throw new Error('[mintfolio:config] site.title must not be empty');
+  return {
+    site: { description: '', language: 'zh-CN', ...input.site },
+    profile: { name: input.site.title, avatar: '', bio: '', location: '', signature: '', ...input.profile },
+    social: input.social ?? [],
+    skills: input.skills ?? [],
+    projects: input.projects ?? [],
+    contact: { email: '', social: [], ...input.contact },
+    ...(input.icp ? { icp: input.icp } : {}),
+  };
+}

package/src/public/search.ts

@@ -0,0 +1,2 @@
+/** Pure matching and URL helpers are safe in both build and browser code. */
+export * from '@mintfolio/theme-api/search';

package/src/public/theme.ts

@@ -0,0 +1,2 @@
+/** Theme authors depend on this contract, never on Core's routes or content readers. */
+export * from '@mintfolio/theme-api';

package/src/routes/404.astro

@@ -0,0 +1,9 @@
+---
+import { activeTheme, getRenderer } from 'virtual:mintfolio/theme';
+import { createThemeContext } from '../engine/context';
+import { notFoundPage } from '../server/pages';
+const theme = await createThemeContext(activeTheme);
+const page = notFoundPage(theme);
+const Renderer = getRenderer('notFound');
+---
+<Renderer theme={theme} page={page} />

package/src/routes/about.astro

@@ -0,0 +1,9 @@
+---
+import { activeTheme, getRenderer } from 'virtual:mintfolio/theme';
+import { createThemeContext } from '../engine/context';
+import { aboutPage } from '../server/pages';
+const theme = await createThemeContext(activeTheme);
+const page = aboutPage(theme);
+const Renderer = getRenderer('page');
+---
+<Renderer theme={theme} page={page} />

package/src/routes/blog/[...slug].astro

@@ -0,0 +1,17 @@
+---
+import { render, type CollectionEntry } from 'astro:content';
+import { getPublishedPosts } from '../../server/posts';
+import PostPage from '../../engine/runtime/post-page.astro';
+
+/** Core generates article routes; a theme supplies only the page renderer. */
+export async function getStaticPaths() {
+  return (await getPublishedPosts()).map((post) => ({
+    params: { slug: post.id },
+    props: { post },
+  }));
+}
+interface Props { post: CollectionEntry<'blog'> }
+const { post } = Astro.props;
+const { Content, headings } = await render(post);
+---
+<PostPage entry={post} headings={headings}><Content /></PostPage>

package/src/routes/blog/index.astro

@@ -0,0 +1,9 @@
+---
+import { activeTheme, getRenderer } from 'virtual:mintfolio/theme';
+import { createThemeContext } from '../../engine/context';
+import { archivePage } from '../../server/pages';
+const theme = await createThemeContext(activeTheme);
+const page = await archivePage(theme);
+const Renderer = getRenderer('archive');
+---
+<Renderer theme={theme} page={page} />

package/src/routes/index.astro

@@ -0,0 +1,9 @@
+---
+import { activeTheme, getRenderer } from 'virtual:mintfolio/theme';
+import { createThemeContext } from '../engine/context';
+import { homePage } from '../server/pages';
+const theme = await createThemeContext(activeTheme);
+const page = await homePage(theme);
+const Renderer = getRenderer('home');
+---
+<Renderer theme={theme} page={page} />

package/src/routes/rss.xml.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview RSS feed generator for blog posts.
+ * 
+ * Generates an RSS 2.0 XML feed at /rss.xml containing the 50 most recent
+ * published blog posts with title, link, description, and publication date.
+ */
+
+import { getPublishedPosts, isProtectedPost } from '../server/posts';
+import { urls } from '../server/routing';
+import { xmlEscape } from '../server/xml';
+import { getPublicSite } from '../server/site';
+const site = getPublicSite();
+
+export async function GET(): Promise<Response> {
+  const siteUrl = site.url.replace(/\/$/, '');
+  const posts = (await getPublishedPosts()).filter((post) => !isProtectedPost(post)).slice(0, 50);
+
+  const itemsXml = posts.map((post) => {
+    const link = xmlEscape(`${siteUrl}${urls.post(post.id)}`);
+    const title = xmlEscape(post.data.title);
+    const description = xmlEscape(post.data.description || '');
+    const pubDate = post.data.pubDate.toUTCString();
+
+    return `<item><title>${title}</title><link>${link}</link><guid>${link}</guid><description>${description}</description><pubDate>${pubDate}</pubDate></item>`;
+  }).join('');
+
+  const rssXml = `<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel><title>${xmlEscape(site.title)}</title><link>${xmlEscape(siteUrl)}</link><description>${xmlEscape(site.description)}</description><language>${xmlEscape(site.language)}</language>${itemsXml}</channel></rss>`;
+
+  return new Response(rssXml, {
+    headers: {
+      'Content-Type': 'application/rss+xml; charset=utf-8',
+    },
+  });
+}

package/src/routes/sitemap.xml.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Sitemap generator for SEO.
+ * 
+ * Generates an XML sitemap at /sitemap.xml containing all public pages:
+ * - Static pages (home, about, blog index)
+ * - All published blog posts
+ */
+
+import { getPublishedPosts, isProtectedPost } from '../server/posts';
+import { urls } from '../server/routing';
+import { xmlEscape } from '../server/xml';
+import { getPublicSite } from '../server/site';
+const site = getPublicSite();
+
+export async function GET(): Promise<Response> {
+  const siteUrl = site.url.replace(/\/$/, '');
+  const now = new Date().toISOString();
+  const posts = (await getPublishedPosts()).filter((post) => !isProtectedPost(post));
+
+  const staticUrls = [
+    { loc: `${siteUrl}${urls.home()}`, lastmod: now },
+    { loc: `${siteUrl}${urls.page('about')}/`, lastmod: now },
+    { loc: `${siteUrl}${urls.archive()}/`, lastmod: now },
+  ];
+
+  const postUrls = posts.map((post) => ({
+    loc: `${siteUrl}${urls.post(post.id)}/`,
+    lastmod: post.data.pubDate.toISOString(),
+  }));
+
+  const allUrls = [...staticUrls, ...postUrls]
+    .map((entry) => `<url><loc>${xmlEscape(entry.loc)}</loc><lastmod>${entry.lastmod}</lastmod></url>`)
+    .join('');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${allUrls}</urlset>`;
+
+  return new Response(xml, {
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+    },
+  });
+}

package/src/server/pages.ts

@@ -0,0 +1,34 @@
+import type { ThemeContext } from '@mintfolio/theme-api';
+import type { ArchivePageData, HomePageData, NotFoundPageData, StaticPageData } from '@mintfolio/theme-api/astro';
+import { pageSeo } from './seo';
+
+/** Page semantics are independent of the chosen renderer and visual structure. */
+export async function homePage(theme: ThemeContext): Promise<HomePageData> {
+  const { title, description } = theme.site;
+  const url = theme.urls.home();
+  return { kind: 'home', title, description, url, seo: pageSeo(theme.site, title, description, url), posts: (await theme.content.posts()).items };
+}
+
+/** Query parameters are applied by the browser because this is a static route. */
+export async function archivePage(theme: ThemeContext): Promise<ArchivePageData> {
+  const title = '全部文章';
+  const description = '记录开发、设计与生活中的探索。';
+  const url = theme.urls.archive();
+  return { kind: 'archive', title, description, url, seo: pageSeo(theme.site, title, description, url), posts: (await theme.content.posts()).items, filters: { q: '', tag: '', category: '' } };
+}
+
+/** The first standalone page is derived from existing author configuration. */
+export function aboutPage(theme: ThemeContext): StaticPageData {
+  const title = `关于我 - ${theme.site.title}`;
+  const description = theme.site.description;
+  const url = theme.urls.page('about');
+  return { kind: 'page', id: 'about', title, description, url, seo: pageSeo(theme.site, title, description, url), profile: theme.site.profile };
+}
+
+/** Static hosting must serve this artifact with an actual 404 status. */
+export function notFoundPage(theme: ThemeContext): NotFoundPageData {
+  const title = '页面未找到';
+  const description = '这个地址没有对应的页面。';
+  const url = '/404.html';
+  return { kind: 'notFound', title, description, url, seo: pageSeo(theme.site, title, description, url, undefined, true) };
+}

package/src/server/postModel.ts

@@ -0,0 +1,98 @@
+import type { PostSummary, PublicImage, TaxonomyTerm, TaxonomyCount, ArchivePeriod } from '@mintfolio/theme-api';
+import { urls } from './routing.ts';
+
+/**
+ * The fields Core needs from a validated content entry. Astro's collection entry
+ * structurally satisfies this interface, but raw content remains private. Keeping
+ * the projection independent of Astro lets policy tests use in-memory records.
+ */
+export interface PostSource {
+  id: string;
+  data: {
+    title: string;
+    description: string;
+    pubDate: Date;
+    tags?: string[];
+    category?: string;
+    cover?: string | PublicImage;
+    draft: boolean;
+    password?: string;
+  };
+}
+
+export const UNCATEGORIZED = '未分类';
+export const PROTECTED_POST_DESCRIPTION = '这是一篇加密文章，请输入密码后阅读。';
+
+/** A present password enables protection, including during development. */
+export function isProtectedPost(post: Pick<PostSource, 'data'>): boolean {
+  return post.data.password !== undefined;
+}
+
+/** Public previews never expose the protected frontmatter description. */
+export function getPostDescription(post: Pick<PostSource, 'data'>): string {
+  return isProtectedPost(post) ? PROTECTED_POST_DESCRIPTION : post.data.description;
+}
+
+/**
+ * Shared publication policy used by the real collection reader. Drafts never
+ * enter public content services; newest articles come first. Input order and
+ * records are untouched, including when multiple articles share a date.
+ */
+export function selectPublishedPosts<T extends PostSource>(posts: readonly T[]): T[] {
+  return posts.filter((post) => !post.data.draft)
+    .toSorted((left, right) => right.data.pubDate.valueOf() - left.data.pubDate.valueOf());
+}
+
+/** Convert one taxonomy label into a link using the host's route policy. */
+function term(label: string, kind: 'tag' | 'category'): TaxonomyTerm {
+  return { id: label, label, url: urls[kind](label) };
+}
+
+/**
+ * Explicit allowlist projection, not `{ ...entry.data }`. Future private
+ * frontmatter fields stay private unless this function deliberately exposes them.
+ * @param post Validated private record selected by the publication policy.
+ * @returns Serializable public metadata, with a safe protected description.
+ */
+export function toPostSummary(post: PostSource): PostSummary {
+  return {
+    id: post.id,
+    url: urls.post(post.id),
+    title: post.data.title,
+    description: getPostDescription(post),
+    publishedAt: post.data.pubDate.toISOString(),
+    tags: (post.data.tags ?? []).map((label) => term(label, 'tag')),
+    category: term(post.data.category || UNCATEGORIZED, 'category'),
+    ...(post.data.cover ? { cover: post.data.cover } : {}),
+    protected: isProtectedPost(post),
+  };
+}
+
+/** Count labels once per article and keep the existing frequency-first order. */
+export function collectTaxonomy(posts: readonly PostSummary[], kind: 'tags' | 'categories'): TaxonomyCount[] {
+  const counts = new Map<string, TaxonomyCount>();
+  for (const post of posts) {
+    const terms = kind === 'tags' ? post.tags : [post.category];
+    for (const entry of new Map(terms.map((item) => [item.id, item])).values()) {
+      const previous = counts.get(entry.id);
+      counts.set(entry.id, { ...entry, count: (previous?.count ?? 0) + 1 });
+    }
+  }
+  return [...counts.values()].toSorted((left, right) => right.count - left.count || left.label.localeCompare(right.label, 'zh-CN'));
+}
+
+/** UTC calendar groups are deterministic across Windows and Linux build hosts. */
+export function collectArchives(posts: readonly PostSummary[]): ArchivePeriod[] {
+  const groups = new Map<string, ArchivePeriod>();
+  for (const post of posts) {
+    const date = new Date(post.publishedAt);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const id = `${year}-${String(month).padStart(2, '0')}`;
+    const group = groups.get(id) ?? { id, label: `${year}年${month}月`, year, month, count: 0, posts: [] };
+    group.posts.push(post);
+    group.count += 1;
+    groups.set(id, group);
+  }
+  return [...groups.values()].toSorted((left, right) => right.id.localeCompare(left.id));
+}

package/src/server/posts.ts

@@ -0,0 +1,15 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import { selectPublishedPosts } from './postModel';
+
+export {
+  UNCATEGORIZED, PROTECTED_POST_DESCRIPTION, isProtectedPost, getPostDescription,
+  toPostSummary, collectTaxonomy, collectArchives, selectPublishedPosts,
+} from './postModel';
+
+/** Private collection entry. Never pass this type or its data object to a theme. */
+export type InternalPost = CollectionEntry<'blog'>;
+
+/** Reuse Astro's collection, then apply the shared publication and ordering policy. */
+export async function getPublishedPosts(): Promise<InternalPost[]> {
+  return selectPublishedPosts(await getCollection('blog'));
+}

package/src/server/routing.ts

@@ -0,0 +1,32 @@
+import type { PostFilters, ThemeUrls } from '@mintfolio/theme-api';
+
+/**
+ * The site's route policy lives here. Themes receive this service and resolved
+ * links; they never need to know how nested article ids or filters are encoded.
+ * Root hosting and the existing /blog URLs are intentionally preserved.
+ */
+export const urls: ThemeUrls = {
+  home: (): string => '/',
+  archive: (filters: Partial<PostFilters> = {}): string => {
+    const params = new URLSearchParams();
+    for (const key of ['q', 'tag', 'category'] as const) {
+      const value = filters[key]?.trim();
+      if (value) params.set(key, value);
+    }
+    return params.size ? `/blog?${params}` : '/blog';
+  },
+  page: (id: string): string => {
+    if (id !== 'about') throw new Error(`Unknown Core page: ${id}`);
+    return '/about';
+  },
+  post: (id: string): string => `/blog/${id.split('/').map(encodeURIComponent).join('/')}`,
+  tag: (label: string): string => urls.archive({ tag: label }),
+  category: (label: string): string => urls.archive({ category: label }),
+  rss: (): string => '/rss.xml',
+  sitemap: (): string => '/sitemap.xml',
+};
+
+/** Resolve a Core-relative URL against the configured public origin. */
+export function absoluteUrl(relative: string, siteUrl: string): string {
+  return new URL(relative, siteUrl).href;
+}

package/src/server/seo.ts

@@ -0,0 +1,14 @@
+import type { PostSummary, PublicSite } from '@mintfolio/theme-api';
+import type { SeoData } from '@mintfolio/theme-api/astro';
+import { absoluteUrl } from './routing';
+
+/** Core decides indexability; themes can render this data without copying policy. */
+export function pageSeo(site: PublicSite, title: string, description: string, url: string, post?: PostSummary, notFound = false): SeoData {
+  const image = typeof post?.cover === 'string' ? post.cover : post?.cover?.src;
+  return {
+    title, description, language: site.language,
+    canonical: absoluteUrl(url, site.url),
+    robots: post?.protected || notFound ? 'noindex,nofollow' : 'index,follow',
+    ...(image ? { image: absoluteUrl(image, site.url) } : {}),
+  };
+}

package/src/server/site.ts

@@ -0,0 +1,28 @@
+import type { PublicImage, PublicSite } from '@mintfolio/theme-api';
+import type { ImageMetadata } from 'astro';
+import input from 'virtual:mintfolio/site-config';
+import { defineSiteConfig } from '../../dist/public/config';
+
+const config = defineSiteConfig(input);
+
+/** Strip build-only image details while preserving Astro's optimization inputs. */
+export function publicImage(source: string | ImageMetadata): string | PublicImage {
+  if (typeof source === 'string') return source;
+  return { src: source.src, width: source.width, height: source.height, format: source.format };
+}
+
+/** Shared author/site content, independent of Default's sidebar and other UI. */
+export function getPublicSite(): PublicSite {
+  return {
+    title: config.site.title,
+    description: config.site.description,
+    url: config.site.url,
+    language: config.site.language,
+    profile: { ...config.profile, avatar: publicImage(config.profile.avatar) },
+    social: config.social.map((link) => ({ ...link })),
+    skills: config.skills.map((group) => ({ category: group.category, items: group.items.map((item) => ({ ...item })) })),
+    projects: config.projects.map((project) => ({ ...project, tags: [...project.tags] })),
+    contact: { ...config.contact, social: [...config.contact.social] },
+    icp: config.icp,
+  };
+}

package/src/server/xml.ts

@@ -0,0 +1,8 @@
+export function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}