@mintfolio/core 0.1.5

package/dist/client/postList.js

@@ -0,0 +1,71 @@
+import { emptyFilters, searchPosts } from '@mintfolio/theme-api/search';
+function positiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${field} must be a positive safe integer`);
+    return value;
+}
+/**
+ * Shared search, combined tag/category filtering, facets, and load-more state.
+ * @returns A controller whose subscriptions receive the initial state immediately.
+ */
+export function createPostListController(options) {
+    const indexed = options.items.map((item) => ({ ...options.index(item), item }));
+    const pageSize = positiveInteger(options.pageSize ?? (indexed.length || 1), 'pageSize');
+    let limit = positiveInteger(options.initialLimit ?? pageSize, 'initialLimit');
+    let filters = { ...emptyFilters(), ...options.initialFilters };
+    if (Object.values(filters).some((item) => typeof item !== 'string'))
+        throw new Error('Filters must be strings');
+    let disposed = false;
+    const listeners = new Set();
+    const facets = () => ({
+        tags: [...new Set(searchPosts(indexed, { category: filters.category }).flatMap((entry) => entry.tags))],
+        categories: [...new Set(searchPosts(indexed, { tag: filters.tag }).map((entry) => entry.category))],
+    });
+    const reconcile = () => {
+        if (!options.reconcileFacets)
+            return;
+        if (filters.tag && !facets().tags.includes(filters.tag.toLowerCase()))
+            filters.tag = '';
+        if (filters.category && !facets().categories.includes(filters.category.toLowerCase()))
+            filters.category = '';
+    };
+    reconcile();
+    const value = () => {
+        const matches = searchPosts(indexed, filters).map((entry) => entry.item);
+        return { filters: { ...filters }, matches, visible: matches.slice(0, limit), total: matches.length, limit, hasMore: matches.length > limit, facets: facets() };
+    };
+    const emit = () => { if (!disposed)
+        for (const listener of listeners)
+            listener(value()); };
+    return {
+        value,
+        setFilters(next) {
+            if (disposed)
+                return;
+            const changed = { ...filters, ...next };
+            if (Object.values(changed).some((item) => typeof item !== 'string'))
+                throw new Error('Filters must be strings');
+            if (changed.q !== filters.q || changed.tag !== filters.tag || changed.category !== filters.category)
+                limit = pageSize;
+            filters = changed;
+            reconcile();
+            emit();
+        },
+        loadMore() { if (!disposed) {
+            limit = Math.min(Number.MAX_SAFE_INTEGER, limit + pageSize);
+            emit();
+        } },
+        setLimit(next) { if (!disposed) {
+            limit = positiveInteger(next, 'limit');
+            emit();
+        } },
+        subscribe(listener) {
+            if (disposed)
+                return () => { };
+            listeners.add(listener);
+            listener(value());
+            return () => { listeners.delete(listener); };
+        },
+        dispose() { disposed = true; listeners.clear(); },
+    };
+}

package/dist/client/protectedArticle.d.ts

@@ -0,0 +1,26 @@
+import { type ArticleUnlockError, type UnlockedArticle } from '@mintfolio/theme-api/client';
+import type { Cleanup } from './lifecycle.js';
+export type ProtectedArticleStatus = 'locked' | 'unlocking' | 'unlocked';
+/** The theme owns DOM rendering; Core owns the short-lived unlock operation. */
+export interface ProtectedArticleOptions {
+    postId: string;
+    payload: unknown;
+    /** Mount the returned fragment once; do not persist or retain plaintext. */
+    onUnlock(content: UnlockedArticle): void;
+    /** Clear article nodes, TOC nodes, preview images, password values and error UI. */
+    onClear(): void;
+    onState?(state: ProtectedArticleStatus): void;
+    onError?(error: ArticleUnlockError | Error): void;
+    signal?: AbortSignal;
+}
+export interface ProtectedArticleController {
+    /** Returns false if disposed, already busy, rejected, or superseded by a lock. */
+    unlock(password: string): Promise<boolean>;
+    lock(): void;
+    dispose: Cleanup;
+}
+/**
+ * Own authentication races and navigation cleanup once for all themes. No secret
+ * enters storage, history, callbacks other than onUnlock, or error messages.
+ */
+export declare function createProtectedArticleController(options: ProtectedArticleOptions): ProtectedArticleController;

package/dist/client/protectedArticle.js

@@ -0,0 +1,64 @@
+import { unlockArticle } from '@mintfolio/theme-api/client';
+/**
+ * Own authentication races and navigation cleanup once for all themes. No secret
+ * enters storage, history, callbacks other than onUnlock, or error messages.
+ */
+export function createProtectedArticleController(options) {
+    let generation = 0;
+    let disposed = false;
+    let busy = false;
+    let active = true;
+    const lifetime = new AbortController();
+    const lock = () => {
+        generation += 1;
+        busy = false;
+        options.onClear();
+        options.onState?.('locked');
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        lifetime.abort();
+        options.signal?.removeEventListener('abort', dispose);
+        lock();
+    };
+    window.addEventListener('pagehide', () => { active = false; lock(); }, { signal: lifetime.signal });
+    window.addEventListener('pageshow', () => { active = true; lock(); }, { signal: lifetime.signal });
+    document.addEventListener('astro:before-swap', dispose, { signal: lifetime.signal });
+    options.signal?.addEventListener('abort', dispose, { once: true });
+    if (options.signal?.aborted)
+        dispose();
+    return {
+        async unlock(password) {
+            if (disposed || !active || busy || !password)
+                return false;
+            const operation = ++generation;
+            busy = true;
+            options.onState?.('unlocking');
+            try {
+                const content = await unlockArticle(options.payload, password, options.postId);
+                if (disposed || !active || operation !== generation)
+                    return false;
+                options.onUnlock(content);
+                options.onState?.('unlocked');
+                return true;
+            }
+            catch (error) {
+                if (disposed || !active || operation !== generation)
+                    return false;
+                // Also clear any partial mount if the theme's onUnlock callback fails.
+                options.onClear();
+                options.onState?.('locked');
+                options.onError?.(error instanceof Error ? error : new Error('Article unlocking failed'));
+                return false;
+            }
+            finally {
+                if (operation === generation)
+                    busy = false;
+            }
+        },
+        lock,
+        dispose,
+    };
+}

package/dist/client/toc.d.ts

@@ -0,0 +1,22 @@
+import { type Cleanup } from './lifecycle.js';
+/** Element references make TOC behavior independent of layout and class names. */
+export interface TocOptions {
+    headings: readonly HTMLElement[];
+    links?: readonly HTMLAnchorElement[];
+    /** Sticky header offset in pixels; use a function for responsive layouts. */
+    offset?: number | (() => number);
+    activeClass?: string;
+    scrollActiveLink?: boolean;
+    onActive?(headingId: string): void;
+    /** Document reading progress from 0 to 100. */
+    onProgress?(percentage: number): void;
+    onNavigate?(headingId: string): void;
+    signal?: AbortSignal;
+}
+export interface TocController {
+    refresh(): void;
+    scrollTo(headingId: string): void;
+    dispose: Cleanup;
+}
+/** Track headings and navigate without adding a history entry for each section. */
+export declare function createTocController(options: TocOptions): TocController;

package/dist/client/toc.js

@@ -0,0 +1,90 @@
+import { createPageScope } from './lifecycle.js';
+/** Track headings and navigate without adding a history entry for each section. */
+export function createTocController(options) {
+    const scope = createPageScope();
+    let activeId = '';
+    let pending = false;
+    const offset = () => typeof options.offset === 'function' ? options.offset() : options.offset ?? 0;
+    const headingFor = (link) => {
+        let id;
+        try {
+            id = decodeURIComponent(new URL(link.href).hash.slice(1));
+        }
+        catch {
+            return undefined;
+        }
+        return options.headings.find((heading) => heading.id === id);
+    };
+    const setActive = (id) => {
+        if (!id || activeId === id)
+            return;
+        activeId = id;
+        for (const link of options.links ?? []) {
+            const active = headingFor(link)?.id === id;
+            if (options.activeClass)
+                link.classList.toggle(options.activeClass, active);
+            if (active) {
+                link.setAttribute('aria-current', 'true');
+                if (options.scrollActiveLink)
+                    link.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+            }
+            else
+                link.removeAttribute('aria-current');
+        }
+        options.onActive?.(id);
+    };
+    const refresh = () => {
+        if (scope.signal.aborted)
+            return;
+        const entries = options.headings.filter((heading) => heading.isConnected);
+        let current = entries[0];
+        let nearest = Infinity;
+        for (const heading of entries) {
+            const distance = heading.getBoundingClientRect().top - offset();
+            if (distance <= 0 && Math.abs(distance) < nearest) {
+                nearest = Math.abs(distance);
+                current = heading;
+            }
+        }
+        const height = document.documentElement.scrollHeight - window.innerHeight;
+        if (window.scrollY >= height - 50)
+            current = entries.at(-1);
+        if (current)
+            setActive(current.id);
+        options.onProgress?.(height > 0 ? Math.max(0, Math.min(100, window.scrollY / height * 100)) : 0);
+    };
+    const schedule = () => {
+        if (pending)
+            return;
+        pending = true;
+        scope.frame(() => { pending = false; refresh(); });
+    };
+    const scrollTo = (id) => {
+        const heading = options.headings.find((entry) => entry.id === id);
+        if (!heading || scope.signal.aborted)
+            return;
+        window.scrollTo({ top: heading.getBoundingClientRect().top + window.scrollY - offset(), behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' });
+        const url = new URL(location.href);
+        url.hash = id;
+        history.replaceState(history.state, '', url);
+        setActive(id);
+        options.onNavigate?.(id);
+    };
+    for (const link of options.links ?? [])
+        link.addEventListener('click', (event) => {
+            const heading = headingFor(link);
+            if (!heading)
+                return;
+            event.preventDefault();
+            scrollTo(heading.id);
+        }, { signal: scope.signal });
+    window.addEventListener('scroll', schedule, { signal: scope.signal, passive: true });
+    window.addEventListener('resize', schedule, { signal: scope.signal });
+    options.signal?.addEventListener('abort', scope.dispose, { once: true });
+    scope.add(() => options.signal?.removeEventListener('abort', scope.dispose));
+    if (options.signal?.aborted)
+        scope.dispose();
+    else
+        schedule();
+    return { refresh, scrollTo, dispose: scope.dispose };
+}

package/dist/public/astro.d.ts

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

package/dist/public/astro.js

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

package/dist/public/client.d.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/dist/public/client.js

@@ -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/dist/public/config.d.ts

@@ -0,0 +1,32 @@
+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 declare function defineSiteConfig(input: SiteConfigInput): SiteConfig;

package/dist/public/config.js

@@ -0,0 +1,21 @@
+/**
+ * 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) {
+    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/dist/public/search.d.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/dist/public/search.js

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

package/dist/public/theme.d.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/dist/public/theme.js

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

package/docs/cli.md

@@ -0,0 +1,118 @@
+# Mintfolio 命令行
+
+CLI 随 `@mintfolio/core` 发布，包提供 `mintfolio` 可执行命令。支持 Windows、macOS 和 Linux，要求 Node.js >= 22.12.0。
+
+## 安装和入口
+
+在已安装 Core 的站点里，使用 `npx mintfolio`；全局安装后可直接使用 `mintfolio`：
+
+```sh
+npm install -g @mintfolio/core
+mintfolio --help
+mintfolio --version
+```
+
+全局安装只提供命令；每个站点仍独立安装并锁定自己的 Core、Astro 和主题。开发及构建使用该站点安装的 Astro。`mintfolio doctor` 可同时查看 CLI 和站点的版本。已有站点可使用 `mintfolio upgrade` 更新 Core；更新前先停止开发服务，更新后重新启动。
+
+多数命令会从当前目录向上找到站点根目录，因此在 `content/blog` 子目录也能操作。`mintfolio --cwd <站点目录> ...` 或 `mintfolio -C <站点目录> ...` 可指定站点；该选项放在命令前。
+
+## 新站点与日常运行
+
+```sh
+mintfolio create my-blog
+mintfolio create my-blog --theme verdant
+cd my-blog
+mintfolio dev
+mintfolio build
+mintfolio preview
+mintfolio check
+mintfolio doctor --json
+```
+
+`create` 需要空目录，会安装 Core、生成网站配置与示例文章，可同时安装并启用主题。
+
+已有目录按传统流程安装 Core 后，执行 `mintfolio init` 补齐文件。初始化不会覆盖已有配置、文章或同名 npm scripts。若安装中断，可在新目录内继续 `npm install` 和 `mintfolio init`。
+
+`dev/build/preview/sync` 的附加参数传给 Astro，例如 `mintfolio dev --port 4322`。`check` 运行站点/主题检查和 Astro sync；生产构建仍使用 `build`，它们不代替编辑器或项目自己的 TypeScript 检查。CLI 不自动部署站点。
+
+## 文章
+
+```sh
+mintfolio post new "我的第一篇文章" --slug first-post
+mintfolio post new "一次旅行" --slug life/travel --description "沿途见闻" --category 生活 --tags 旅行,随笔
+mintfolio post new "准备发布的文章" --slug ready --date 2026-09-11 --publish
+mintfolio post list
+mintfolio post list --draft --json
+mintfolio post publish first-post
+mintfolio post draft first-post
+```
+
+新文章位于 `content/blog`，默认 `draft: true`。省略 `--slug` 时按标题生成名称，保留中文；显式 ID 可以包含目录，例如 `life/travel`。同名文件不会被覆盖。`--date` 使用本地当天日期作为默认值。
+
+`publish` 只把草稿字段设为 false，使文章可进入下一次构建；它不会执行部署。`draft` 将文章移回草稿状态。修改保留其他 frontmatter 字段、注释及 Markdown 正文，并备份原文件。`list` 只显示 ID、标题、日期和草稿状态，不输出密码或正文。
+
+CLI 的文章命令采用默认 `content/blog` 目录。自行更换内容集合 loader/base 的站点，应直接管理其自定义目录中的文章。
+
+## 主题
+
+```sh
+mintfolio theme list
+mintfolio theme current
+mintfolio theme install default
+mintfolio theme install @example/theme@1.2.3 --use
+mintfolio theme use default
+mintfolio theme use minimal
+mintfolio theme use ./my-theme
+mintfolio theme init default
+mintfolio theme sync
+mintfolio theme check
+```
+
+`install` 接收 npm 包名，可附加版本、范围或标签；`default` 和 `happyhues` 都映射到 `@mintfolio/theme-default`。安装后生成完整主题配置，只有加 `--use` 才同时切换。再次生成配置保留已有文件。
+
+`use` 校验目标主题并修改 `theme.config.mjs`，保留显式页面 overrides。旧的内联 `settings` 会先迁移到旧主题自己的配置文件，再清空内联覆盖，因此切回旧主题时仍保留个性化设置。动态内联表达式不能自动迁移，CLI 会明确报错且不切换主题。
+
+`theme list` 显示内置 Minimal、直接依赖中的主题包及当前本地主题。没有删除或卸载命令；这版聚焦创建、安装、选择和编辑。
+
+兼容旧命令：`theme:add` → `theme install`，`theme:init` → `theme init`，`theme:sync` → `theme sync`，`theme:check` → `theme check`。
+
+## 配置
+
+```sh
+mintfolio config get site
+mintfolio config get site site.title
+mintfolio config set site site.title "新的博客名称"
+mintfolio config set site profile.bio "记录与分享"
+mintfolio config get theme
+mintfolio config set theme initialPalette 3
+mintfolio config set theme homePageSize 9
+mintfolio config set theme sidebar.quote.enabled true
+mintfolio config set theme sidebar.quote.text "保持好奇。"
+mintfolio config set theme maxWidth 900 --theme minimal
+mintfolio config schema theme
+mintfolio config path theme
+mintfolio config edit theme
+```
+
+`site` 修改 `site.config.ts`，也识别主题选择配置中明确指定的 `siteConfig` 路径；`theme` 修改当前主题的专属文件。添加 `--theme <主题>` 可编辑未启用主题。主题配置文件支持要求站点 Core >= 0.1.1，旧版请先 `mintfolio upgrade`。
+
+字段用点号分隔，例如 `sidebar.quote.enabled`；已存在的数组元素可用 `social.0.url`。数组和对象整体传 JSON，示例：
+
+```sh
+mintfolio config set site contact.social '["github","email"]'
+mintfolio config set theme sidebar.tools '[{"name":"示例工具","description":"工具说明","url":"https://example.com"}]'
+```
+
+默认按照字段类型读取值：配色编号 `3` 保持字符串，文章数量 `9` 是数字，开关 `true` 是布尔值。`--json` 强制将参数作为 JSON；不同终端有自己的引号规则，复杂数组也可通过 `config edit` 修改。
+
+站点配置按语法读取，不执行图片导入、函数或其他表达式；动态叶子会显示为 `{ "$expression": "原表达式" }`。支持直接导出的对象、顶层 `const` 别名、`defineSiteConfig({...})`、TypeScript `as`/`satisfies`。含展开、计算属性或不明确容器的字段不能自动改写，可用 `config edit` 编辑。普通字段修改保留 imports、注释和其他字段，只替换目标值。
+
+主题 `get` 返回合并默认值后的有效设置。若旧的 `theme.config.mjs.settings` 正在覆盖某个字段，`set` 会修改该内联字段并输出实际文件路径，避免写入一个会被忽略的值。
+
+`config edit` 默认在 Windows 使用记事本、macOS 使用默认文本编辑器、Linux 使用 `xdg-open`。可设置 `VISUAL`/`EDITOR`，或传 `--editor <可执行文件路径>`。编辑器选项只接收程序路径，不接受 shell 命令或附加参数。
+
+## 保留与恢复
+
+配置和草稿状态修改前，会将原文件完整备份到 `.mintfolio/backups/<时间和唯一编号>/`，命令输出具体位置。需要恢复时，把备份复制回对应原路径即可。新站点的 `.gitignore` 已忽略 `.mintfolio/`；旧站点可把该目录加入自己的忽略文件。
+
+未知命令、无效配置值、重复文章和失败的 npm/Astro 命令都会以非零状态退出，可用于脚本。CLI 不覆盖已有文章、不移除主题包、不操作 Git 提交，也不自动发布到远程服务器。

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@mintfolio/core",
+  "version": "0.1.5",
+  "description": "A Markdown blog and personal site toolkit, built with Astro.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "mintfolio": "./bin/mintfolio.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "README.md",
+    "docs/cli.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/integration.d.ts",
+      "import": "./src/integration.mjs"
+    },
+    "./config": {
+      "types": "./dist/public/config.d.ts",
+      "import": "./dist/public/config.js"
+    },
+    "./theme": {
+      "types": "./dist/public/theme.d.ts",
+      "import": "./dist/public/theme.js"
+    },
+    "./astro": {
+      "types": "./dist/public/astro.d.ts",
+      "import": "./dist/public/astro.js"
+    },
+    "./client": {
+      "types": "./dist/public/client.d.ts",
+      "import": "./dist/public/client.js"
+    },
+    "./search": {
+      "types": "./dist/public/search.d.ts",
+      "import": "./dist/public/search.js"
+    },
+    "./content": {
+      "types": "./src/content.d.ts",
+      "import": "./src/content.mjs"
+    },
+    "./components/*": "./src/components/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@astrojs/compiler": "^2.13.1",
+    "@babel/parser": "^7.29.8",
+    "@mintfolio/theme-api": "^1.0.0",
+    "astro": "^7.3.2",
+    "es-module-lexer": "^1.7.0",
+    "import-meta-resolve": "^4.2.0",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "@types/semver": "^7.8.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "scripts": {
+    "build": "node node_modules/@typescript/native/bin/tsc -p tsconfig.json",
+    "check": "npm run build",
+    "prepack": "npm run build",
+    "test": "npm run test:unit && npm run test:boundaries",
+    "test:unit": "npm run build && node --experimental-strip-types --test tests/*.test.mjs",
+    "test:boundaries": "npm run build && node tools/verify-theme-boundaries.mjs",
+    "deps:update": "node tools/update-local-deps.mjs"
+  },
+  "license": "GPL-3.0-only",
+  "author": "CNFLWZH",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cnflwzh/mintfolio.git"
+  },
+  "homepage": "https://github.com/cnflwzh/mintfolio/wiki",
+  "bugs": {
+    "url": "https://github.com/cnflwzh/mintfolio/issues"
+  }
+}

package/src/client/archive.ts

@@ -0,0 +1,45 @@
+import { createSearchEntry, readFiltersFromUrl, writeFiltersToUrl } from '@mintfolio/theme-api/search';
+import type { PostSummary } from '@mintfolio/theme-api';
+import { createPostListController } from './postList.js';
+import type { PageScope } from './lifecycle.js';
+
+/**
+ * Default semantic binding for Core's optional PostArchive component. Custom
+ * themes can use createPostListController directly and supply their own markup.
+ * The root owns all selectors; multiple unrelated forms never get global handlers.
+ */
+export function bindPostArchive(root: HTMLElement, scope: PageScope): void {
+  const form = root.querySelector<HTMLFormElement>('[data-filter-form]');
+  const query = form?.querySelector<HTMLInputElement>('[name="q"]');
+  const tag = form?.querySelector<HTMLSelectElement>('[name="tag"]');
+  const category = form?.querySelector<HTMLSelectElement>('[name="category"]');
+  const status = root.querySelector<HTMLElement>('[data-filter-status]');
+  const more = root.querySelector<HTMLButtonElement>('[data-load-more]');
+  if (!form || !query || !tag || !category) return;
+  const posts: PostSummary[] = JSON.parse(root.dataset.posts ?? '[]');
+  const controller = createPostListController({ items: posts, index: createSearchEntry, initialFilters: readFiltersFromUrl(location.href), ...(root.dataset.pageSize ? { pageSize: Number(root.dataset.pageSize) } : {}) });
+  scope.add(controller.dispose);
+  const rows = Array.from(root.querySelectorAll<HTMLElement>('[data-post-id]'));
+  scope.add(controller.subscribe((state) => {
+    // Preserve a URL filter even if no select option exists: a miss is zero matches.
+    for (const [select, value] of [[tag, state.filters.tag], [category, state.filters.category]] as const) {
+      if (value && !Array.from(select.options).some((option) => option.value === value)) select.add(new Option(value, value));
+      select.value = value;
+    }
+    if (document.activeElement !== query) query.value = state.filters.q;
+    const ids = new Set(state.visible.map((post) => post.id));
+    rows.forEach((row) => { row.hidden = !ids.has(row.dataset.postId ?? ''); });
+    if (status) status.textContent = `共 ${state.total} 篇文章`;
+    if (more) more.hidden = !state.hasMore;
+  }));
+  const update = (): void => {
+    controller.setFilters({ q: query.value.trim(), tag: tag.value, category: category.value });
+    history.replaceState(history.state, '', writeFiltersToUrl(controller.value().filters, new URL(location.href)));
+  };
+  const eventOptions = { signal: scope.signal };
+  form.addEventListener('submit', (event) => { event.preventDefault(); update(); }, eventOptions);
+  form.addEventListener('input', update, eventOptions);
+  form.addEventListener('change', update, eventOptions);
+  more?.addEventListener('click', controller.loadMore, eventOptions);
+  window.addEventListener('popstate', () => controller.setFilters(readFiltersFromUrl(location.href)), eventOptions);
+}