@mintfolio/core 0.1.5

package/bin/theme-config.mjs

@@ -0,0 +1,111 @@
+import { readFile, writeFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadTheme, isWithin } from '../src/engine/loader.mjs';
+import { resolveSettings } from '../src/engine/schema.mjs';
+import { themeConfigPath } from '../src/engine/theme-config.mjs';
+
+const aliases = { verdant: '@mintfolio/theme-default', default: '@mintfolio/theme-default', happyhues: '@mintfolio/theme-default' };
+
+/** @param {string} name Installed npm package or built-in theme selector. @returns {string} */
+export function normalizeThemeName(name) { return Object.hasOwn(aliases, name) ? aliases[name] : name; }
+
+/** Read package metadata without importing theme code or its configuration template. */
+async function packageAt(directory) {
+  try { return JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+/**
+ * Theme packages opt into automatic discovery with mintfolio.configTemplate.
+ * The path is relative to the owning package, checked after resolving symlinks.
+ * @param {string} manifestPath Resolved theme.mjs path.
+ * @returns {Promise<string|null>} Safe template filename, or generic schema generation.
+ */
+async function templateFor(manifestPath) {
+  let directory = path.dirname(manifestPath);
+  while (directory !== path.dirname(directory)) {
+    const pkg = await packageAt(directory);
+    if (pkg) {
+      const relative = pkg.mintfolio?.configTemplate;
+      if (relative === undefined) return null;
+      if (typeof relative !== 'string' || !relative.startsWith('./') || !relative.endsWith('.mjs')) throw new Error('[theme:config] configTemplate must be a relative .mjs file');
+      const filename = await realpath(path.resolve(directory, relative));
+      if (!isWithin(filename, await realpath(directory)) || !(await stat(filename)).isFile()) throw new Error('[theme:config] Template escapes its package');
+      return filename;
+    }
+    directory = path.dirname(directory);
+  }
+  return null;
+}
+
+/** Render all schema fields, including commented examples for initially empty arrays. */
+function schemaSource(schema, values, depth=1) {
+  const indent = '  '.repeat(depth);
+  return Object.entries(schema).flatMap(([name, setting]) => {
+    const help = [setting.label, setting.description,
+      setting.type === 'select' ? `可选值：${setting.options.join(' / ')}` : null,
+      setting.type === 'number' ? `范围：${setting.min ?? '不限'} 至 ${setting.max ?? '不限'}` : null,
+    ].filter(Boolean).join('；').replace(/[\r\n\u2028\u2029]+/g, ' ');
+    const value = Object.hasOwn(values, name) ? values[name] : setting.default;
+    const key = JSON.stringify(name);
+    if (setting.type === 'object') return [`${indent}// ${help}`, `${indent}${key}: {`, schemaSource(setting.properties, value, depth+1), `${indent}},`];
+    if (setting.type === 'array' && value.length === 0 && setting.items.type === 'object') {
+      const sample = [`${indent}  {`,schemaSource(setting.items.properties,setting.items.default,depth+2),`${indent}  },`].join('\n').split('\n').map((line)=>`${indent}  // ${line.slice(indent.length+2)}`).join('\n');
+      return [`${indent}// ${help}`,`${indent}${key}: [`,sample,`${indent}],`];
+    }
+    return [`${indent}// ${help}`, `${indent}${key}: ${JSON.stringify(value)},`];
+  }).join('\n');
+}
+
+/**
+ * Create one editable host config from a theme-owned template or its full schema.
+ * Existing files are never changed, including invalid or manually edited files.
+ * @param {string} root Host root with installed dependencies.
+ * @param {string} theme Installed package, local theme selector, or Minimal.
+ * @returns {Promise<{filename:string,created:boolean}>} The host file and whether it was created.
+ */
+export async function createThemeConfig(root, theme) {
+  const active = await loadTheme({root,theme:normalizeThemeName(theme),readUserConfig:false});
+  const filename = themeConfigPath(root, active.definition.manifest.id);
+  const template = await templateFor(active.manifestPath);
+  let source;
+  if (template) {
+    // Templates are plain ESM settings owned by the installed package. Validate
+    // their defaults with the same manifest that will validate host edits.
+    resolveSettings(active.definition, (await import(pathToFileURL(template).href)).default);
+    source = await readFile(template, 'utf8');
+  } else {
+    source = `/** ${active.definition.manifest.name.replace(/\*\//g,'')} 的设置。仅在选择此主题时生效；重复生成不会覆盖本文件。 */\nexport default {\n${schemaSource(active.definition.settings,active.settings)}\n};\n`;
+  }
+  try { await writeFile(filename, source, {flag:'wx'}); return {filename,created:true}; }
+  catch (error) { if (error.code === 'EEXIST') return {filename,created:false}; throw error; }
+}
+
+/**
+ * Find theme packages declared by this site, not arbitrary transitive packages.
+ * Used by init/dev/build and the explicit sync command, independently of npm
+ * dependency lifecycle permissions. It never changes the selected layout.
+ * @param {string} root Host root.
+ * @returns {Promise<Array<{filename:string,created:boolean}>>}
+ */
+export async function syncThemeConfigs(root) {
+  try { await stat(path.join(root,'site.config.ts')); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  const pkg = await packageAt(root);
+  if (!pkg) return [];
+  const results = [await createThemeConfig(root,'minimal')];
+  const dependencies = {...pkg.dependencies,...pkg.devDependencies,...pkg.optionalDependencies};
+  for (const name of Object.keys(dependencies)) {
+    const directory = path.resolve(root,'node_modules',name);
+    if (!isWithin(directory,path.join(root,'node_modules'))) continue;
+    const installed = await packageAt(directory);
+    if (installed?.mintfolio?.configTemplate) results.push(await createThemeConfig(root,name));
+  }
+  return results;
+}
+
+/** @param {Array<{filename:string,created:boolean}>} results Report only new files during automatic sync. */
+export function reportThemeConfigs(results) {
+  for (const result of results) if (result.created) process.stdout.write(`Created ${path.basename(result.filename)}\n`);
+}

package/dist/client/archive.d.ts

@@ -0,0 +1,7 @@
+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 declare function bindPostArchive(root: HTMLElement, scope: PageScope): void;

package/dist/client/archive.js

@@ -0,0 +1,47 @@
+import { createSearchEntry, readFiltersFromUrl, writeFiltersToUrl } from '@mintfolio/theme-api/search';
+import { createPostListController } from './postList.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, scope) {
+    const form = root.querySelector('[data-filter-form]');
+    const query = form?.querySelector('[name="q"]');
+    const tag = form?.querySelector('[name="tag"]');
+    const category = form?.querySelector('[name="category"]');
+    const status = root.querySelector('[data-filter-status]');
+    const more = root.querySelector('[data-load-more]');
+    if (!form || !query || !tag || !category)
+        return;
+    const posts = 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('[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]]) {
+            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 = () => {
+        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);
+}

package/dist/client/code.d.ts

@@ -0,0 +1,4 @@
+export declare function formatLanguageLabel(language: string): string;
+export declare function resolveCodeLanguage(pre: HTMLPreElement, code: HTMLElement): string;
+export declare function copyText(text: string): Promise<boolean>;
+export declare function extractCodeText(code: HTMLElement, pre: HTMLPreElement): string;

package/dist/client/code.js

@@ -0,0 +1,126 @@
+/** Shared code-language labels, rendered-text extraction, and clipboard access. No UI is mounted on import. */
+const languageLabels = {
+    bash: 'Bash',
+    c: 'C',
+    cpp: 'C++',
+    csharp: 'C#',
+    cs: 'C#',
+    css: 'CSS',
+    docker: 'Docker',
+    dockerfile: 'Dockerfile',
+    go: 'Go',
+    gql: 'GraphQL',
+    graphql: 'GraphQL',
+    html: 'HTML',
+    java: 'Java',
+    javascript: 'JavaScript',
+    js: 'JavaScript',
+    json: 'JSON',
+    jsx: 'JSX',
+    kotlin: 'Kotlin',
+    kt: 'Kotlin',
+    less: 'Less',
+    markdown: 'Markdown',
+    md: 'Markdown',
+    mdx: 'MDX',
+    php: 'PHP',
+    powershell: 'PowerShell',
+    ps1: 'PowerShell',
+    py: 'Python',
+    python: 'Python',
+    rb: 'Ruby',
+    ruby: 'Ruby',
+    rs: 'Rust',
+    rust: 'Rust',
+    sass: 'Sass',
+    scss: 'SCSS',
+    shell: 'Shell',
+    sh: 'Shell',
+    sql: 'SQL',
+    svelte: 'Svelte',
+    swift: 'Swift',
+    text: 'Text',
+    toml: 'TOML',
+    ts: 'TypeScript',
+    tsx: 'TSX',
+    typescript: 'TypeScript',
+    vue: 'Vue',
+    xml: 'XML',
+    yaml: 'YAML',
+    yml: 'YAML',
+    zsh: 'Zsh',
+};
+export function formatLanguageLabel(language) {
+    const normalized = (language ?? '').trim().toLowerCase();
+    if (!normalized) {
+        return 'Text';
+    }
+    if (languageLabels[normalized]) {
+        return languageLabels[normalized];
+    }
+    const words = normalized
+        .replace(/[._-]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+    if (words.length === 0) {
+        return 'Text';
+    }
+    return words
+        .map((word) => {
+        if (word.length <= 4) {
+            return word.toUpperCase();
+        }
+        return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+    })
+        .join(' ');
+}
+export function resolveCodeLanguage(pre, code) {
+    const preLanguage = pre.getAttribute('data-language') ?? pre.dataset.language;
+    if (preLanguage) {
+        return formatLanguageLabel(preLanguage);
+    }
+    const className = Array.from(code.classList).find((value) => value.startsWith('language-'));
+    if (className) {
+        return formatLanguageLabel(className.replace('language-', ''));
+    }
+    return 'Text';
+}
+function fallbackCopyText(text) {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.setAttribute('readonly', 'true');
+    textarea.style.cssText = 'position:fixed;top:-9999px;left:-9999px';
+    document.body.appendChild(textarea);
+    textarea.select();
+    let copied = false;
+    try {
+        copied = document.execCommand('copy');
+    }
+    catch {
+        copied = false;
+    }
+    textarea.remove();
+    return copied;
+}
+export async function copyText(text) {
+    if (window.isSecureContext && navigator.clipboard?.writeText) {
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            return fallbackCopyText(text);
+        }
+    }
+    return fallbackCopyText(text);
+}
+export function extractCodeText(code, pre) {
+    const renderedLines = Array.from(code.children).filter((child) => child.classList?.contains('line'));
+    if (renderedLines.length > 0) {
+        return renderedLines
+            .map((line) => line.textContent ?? '')
+            .join('\n')
+            .replace(/\n$/, '');
+    }
+    return (code.textContent ?? pre.textContent ?? '').replace(/\n$/, '');
+}

package/dist/client/lifecycle.d.ts

@@ -0,0 +1,18 @@
+export type Cleanup = () => void;
+/** Resources owned by one mounted page or widget; disposal is idempotent. */
+export interface PageScope {
+    readonly signal: AbortSignal;
+    add(cleanup: Cleanup): void;
+    timeout(callback: () => void, delay: number): number;
+    frame(callback: FrameRequestCallback): number;
+    dispose(): void;
+}
+/** Create a scope for listeners, timers, animation frames, and caller cleanups. */
+export declare function createPageScope(): PageScope;
+/**
+ * Mount behavior on ordinary documents, Astro swaps, and BFCache restores.
+ * @param target A theme selector or a function resolving its current root.
+ * @param setup Attach behavior to that root and register cleanup with its scope.
+ * @returns Stop listening and dispose the current mount.
+ */
+export declare function onPage(target: string | (() => HTMLElement | null), setup: (root: HTMLElement, scope: PageScope) => void): Cleanup;

package/dist/client/lifecycle.js

@@ -0,0 +1,82 @@
+/** Create a scope for listeners, timers, animation frames, and caller cleanups. */
+export function createPageScope() {
+    const controller = new AbortController();
+    const cleanups = [];
+    const timers = new Set();
+    const frames = new Set();
+    return {
+        signal: controller.signal,
+        add(cleanup) { if (controller.signal.aborted)
+            cleanup();
+        else
+            cleanups.push(cleanup); },
+        timeout(callback, delay) {
+            const id = window.setTimeout(() => { timers.delete(id); if (!controller.signal.aborted)
+                callback(); }, delay);
+            timers.add(id);
+            return id;
+        },
+        frame(callback) {
+            const id = window.requestAnimationFrame((time) => { frames.delete(id); if (!controller.signal.aborted)
+                callback(time); });
+            frames.add(id);
+            return id;
+        },
+        dispose() {
+            if (controller.signal.aborted)
+                return;
+            controller.abort();
+            timers.forEach((id) => window.clearTimeout(id));
+            frames.forEach((id) => window.cancelAnimationFrame(id));
+            // Run every cleanup even if one widget fails; protected content must still clear.
+            const errors = [];
+            for (const cleanup of cleanups.reverse()) {
+                try {
+                    cleanup();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            cleanups.length = 0;
+            timers.clear();
+            frames.clear();
+            if (errors.length)
+                console.error('[mintfolio:lifecycle] Widget cleanup failed', errors);
+        },
+    };
+}
+/**
+ * Mount behavior on ordinary documents, Astro swaps, and BFCache restores.
+ * @param target A theme selector or a function resolving its current root.
+ * @param setup Attach behavior to that root and register cleanup with its scope.
+ * @returns Stop listening and dispose the current mount.
+ */
+export function onPage(target, setup) {
+    const lifetime = new AbortController();
+    let root = null;
+    let scope = null;
+    const dispose = () => { scope?.dispose(); scope = null; root = null; };
+    const mount = () => {
+        const next = typeof target === 'string' ? document.querySelector(target) : target();
+        if (root === next)
+            return;
+        dispose();
+        if (!next)
+            return;
+        root = next;
+        scope = createPageScope();
+        setup(root, scope);
+    };
+    const options = { signal: lifetime.signal };
+    document.addEventListener('astro:before-swap', dispose, options);
+    document.addEventListener('astro:page-load', mount, options);
+    document.addEventListener('article:content-changed', mount, options);
+    window.addEventListener('pagehide', dispose, options);
+    window.addEventListener('pageshow', mount, options);
+    if (document.readyState === 'loading')
+        document.addEventListener('DOMContentLoaded', mount, { ...options, once: true });
+    else
+        mount();
+    return () => { lifetime.abort(); dispose(); };
+}

package/dist/client/lightbox.d.ts

@@ -0,0 +1,24 @@
+import { type Cleanup } from './lifecycle.js';
+/** Theme-owned image-preview elements. Core supplies zoom, pan, keyboard and cleanup behavior. */
+export interface LightboxOptions {
+    root: HTMLElement;
+    dialog: HTMLDialogElement;
+    image: HTMLImageElement;
+    viewport: HTMLElement;
+    zoomIn: HTMLButtonElement;
+    zoomOut: HTMLButtonElement;
+    zoomLevel: HTMLOutputElement;
+    reset: HTMLElement;
+    close?: HTMLElement | null;
+    minScale?: number;
+    maxScale?: number;
+    step?: number;
+    signal?: AbortSignal;
+}
+export interface LightboxController {
+    close(): void;
+    reset(): void;
+    dispose: Cleanup;
+}
+/** Mount one preview; linked article images keep their original navigation. */
+export declare function createLightboxController(input: LightboxOptions): LightboxController;

package/dist/client/lightbox.js

@@ -0,0 +1,142 @@
+import { createPageScope } from './lifecycle.js';
+/** Mount one preview; linked article images keep their original navigation. */
+export function createLightboxController(input) {
+    const { root, dialog, image, viewport, zoomIn, zoomOut, zoomLevel, reset } = input;
+    const scope = createPageScope();
+    const options = { signal: scope.signal };
+    const minScale = input.minScale ?? 0.5;
+    const maxScale = input.maxScale ?? 4;
+    const step = input.step ?? 0.25;
+    if (![minScale, maxScale, step].every((value) => Number.isFinite(value) && value > 0) || minScale > 1 || maxScale < 1) {
+        throw new Error('Lightbox scale bounds must include 1 and the step must be positive and finite');
+    }
+    let scale = 1;
+    let x = 0;
+    let y = 0;
+    let drag = null;
+    const render = () => {
+        const maxX = Math.max(0, (image.offsetWidth * scale - viewport.clientWidth) / 2);
+        const maxY = Math.max(0, (image.offsetHeight * scale - viewport.clientHeight) / 2);
+        x = Math.max(-maxX, Math.min(maxX, x));
+        y = Math.max(-maxY, Math.min(maxY, y));
+        image.style.transform = `translate(${x}px, ${y}px) scale(${scale})`;
+        image.style.cursor = maxX || maxY ? (drag ? 'grabbing' : 'grab') : 'default';
+        zoomLevel.value = `${Math.round(scale * 100)}%`;
+        zoomIn.disabled = scale >= maxScale;
+        zoomOut.disabled = scale <= minScale;
+    };
+    const stopDragging = () => {
+        const pointerId = drag?.id;
+        drag = null;
+        if (pointerId !== undefined && image.hasPointerCapture(pointerId))
+            image.releasePointerCapture(pointerId);
+        render();
+    };
+    const resetView = () => {
+        scale = 1;
+        x = 0;
+        y = 0;
+        stopDragging();
+    };
+    const setScale = (value) => {
+        const next = Math.max(minScale, Math.min(maxScale, value));
+        x *= next / scale;
+        y *= next / scale;
+        scale = next;
+        render();
+    };
+    zoomIn.addEventListener('click', () => setScale(scale + step), options);
+    zoomOut.addEventListener('click', () => setScale(scale - step), options);
+    reset.addEventListener('click', resetView, options);
+    image.addEventListener('load', render, options);
+    window.addEventListener('resize', () => { if (dialog.open)
+        render(); }, options);
+    viewport.addEventListener('wheel', (event) => {
+        event.preventDefault();
+        if (event.deltaY)
+            setScale(scale - Math.sign(event.deltaY) * step);
+    }, { ...options, passive: false });
+    dialog.addEventListener('keydown', (event) => {
+        if (event.ctrlKey || event.metaKey || event.altKey)
+            return;
+        if (['+', '=', '-', '0'].includes(event.key)) {
+            event.preventDefault();
+            if (event.key === '0')
+                resetView();
+            else
+                setScale(scale + (event.key === '-' ? -step : step));
+        }
+    }, options);
+    image.addEventListener('pointerdown', (event) => {
+        if (!event.isPrimary || event.button !== 0 || scale <= 1)
+            return;
+        event.preventDefault();
+        drag = { id: event.pointerId, clientX: event.clientX, clientY: event.clientY, x, y };
+        image.setPointerCapture(event.pointerId);
+        render();
+    }, options);
+    image.addEventListener('pointermove', (event) => {
+        if (!drag || event.pointerId !== drag.id)
+            return;
+        x = drag.x + event.clientX - drag.clientX;
+        y = drag.y + event.clientY - drag.clientY;
+        render();
+    }, options);
+    image.addEventListener('pointerup', stopDragging, options);
+    image.addEventListener('pointercancel', stopDragging, options);
+    image.addEventListener('lostpointercapture', stopDragging, options);
+    for (const source of root.querySelectorAll('img')) {
+        // Linked images retain their author's navigation behavior.
+        if (source.closest('a'))
+            continue;
+        const attributes = ['tabindex', 'role', 'aria-haspopup', 'aria-label'].map((name) => [name, source.getAttribute(name)]);
+        const cursor = source.style.cursor;
+        scope.add(() => {
+            for (const [name, value] of attributes) {
+                if (value === null)
+                    source.removeAttribute(name);
+                else
+                    source.setAttribute(name, value);
+            }
+            source.style.cursor = cursor;
+        });
+        source.tabIndex = 0;
+        source.setAttribute('role', 'button');
+        source.setAttribute('aria-haspopup', 'dialog');
+        source.setAttribute('aria-label', `放大图片：${source.alt || '文章插图'}`);
+        source.style.cursor = 'zoom-in';
+        const open = () => {
+            image.src = source.currentSrc || source.src;
+            image.alt = source.alt;
+            dialog.showModal();
+            resetView();
+        };
+        source.addEventListener('click', open, options);
+        source.addEventListener('keydown', (event) => {
+            if (['Enter', ' '].includes(event.key)) {
+                event.preventDefault();
+                open();
+            }
+        }, options);
+    }
+    input.close?.addEventListener('click', () => dialog.close(), options);
+    dialog.addEventListener('click', (event) => {
+        if (event.target === dialog || event.target === viewport)
+            dialog.close();
+    }, options);
+    const clearImage = () => {
+        image.removeAttribute('src');
+        image.alt = '图片预览';
+        resetView();
+    };
+    dialog.addEventListener('close', clearImage, options);
+    scope.add(() => {
+        dialog.close();
+        clearImage();
+    });
+    input.signal?.addEventListener('abort', scope.dispose, { once: true });
+    scope.add(() => input.signal?.removeEventListener('abort', scope.dispose));
+    if (input.signal?.aborted)
+        scope.dispose();
+    return { close: () => dialog.close(), reset: resetView, dispose: scope.dispose };
+}

package/dist/client/navigation.d.ts

@@ -0,0 +1,22 @@
+export interface ResolveStoredArticleBackHrefInput {
+    /** Optional saved list URL, including its filter query and content anchor. */
+    storedHref: string | null;
+    currentPath: string;
+    currentOrigin: string;
+    /** The archive destination injected by Core into this page's document. */
+    fallbackHref: string;
+}
+/**
+ * Return a saved same-origin list destination or Core's archive URL. Reject
+ * external targets and self-navigation without knowing the host's route shape.
+ */
+export declare function resolveStoredArticleBackHref({ storedHref, currentPath, currentOrigin, fallbackHref, }: ResolveStoredArticleBackHrefInput): string;
+export interface ShouldPersistArticleBackHrefInput {
+    linkHref: string;
+    currentOrigin: string;
+    currentPath: string;
+    /** Only links rendered from public PostSummary.url carry this theme marker. */
+    isArticleLink: boolean;
+}
+/** Save list position only when the visitor follows an internal article link. */
+export declare function shouldPersistArticleBackHref({ linkHref, currentOrigin, currentPath, isArticleLink, }: ShouldPersistArticleBackHrefInput): boolean;

package/dist/client/navigation.js

@@ -0,0 +1,29 @@
+/**
+ * Return a saved same-origin list destination or Core's archive URL. Reject
+ * external targets and self-navigation without knowing the host's route shape.
+ */
+export function resolveStoredArticleBackHref({ storedHref, currentPath, currentOrigin, fallbackHref, }) {
+    if (!storedHref)
+        return fallbackHref;
+    try {
+        const target = new URL(storedHref, currentOrigin);
+        if (target.origin !== currentOrigin || target.pathname === currentPath)
+            return fallbackHref;
+        return `${target.pathname}${target.search}${target.hash}`;
+    }
+    catch {
+        return fallbackHref;
+    }
+}
+/** Save list position only when the visitor follows an internal article link. */
+export function shouldPersistArticleBackHref({ linkHref, currentOrigin, currentPath, isArticleLink, }) {
+    if (!isArticleLink)
+        return false;
+    try {
+        const target = new URL(linkHref, currentOrigin);
+        return target.origin === currentOrigin && target.pathname !== currentPath;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/client/postList.d.ts

@@ -0,0 +1,41 @@
+import type { PostFilters, SearchEntry } from '@mintfolio/theme-api';
+import type { Cleanup } from './lifecycle.js';
+/** Filtered content and pagination state; UI structure is entirely caller-owned. */
+export interface PostListState<T> {
+    filters: PostFilters;
+    matches: T[];
+    visible: T[];
+    total: number;
+    limit: number;
+    hasMore: boolean;
+    /** Facets ignore q, matching the blog's existing taxonomy navigation behavior. */
+    facets: {
+        tags: string[];
+        categories: string[];
+    };
+}
+export interface PostListOptions<T> {
+    /** Safe public DTOs or theme models derived exclusively from those DTOs. */
+    items: readonly T[];
+    /** Map each model to Core's normalized public search fields. Called once. */
+    index: (item: T) => SearchEntry;
+    initialFilters?: Partial<PostFilters>;
+    pageSize?: number;
+    initialLimit?: number;
+    /** Optional radio-group UX: clear a selection made unavailable by the other facet. */
+    reconcileFacets?: boolean;
+}
+/** No DOM, storage, history, sorting policy, or theme classes are hidden here. */
+export interface PostListController<T> {
+    value(): PostListState<T>;
+    setFilters(filters: Partial<PostFilters>): void;
+    loadMore(): void;
+    setLimit(limit: number): void;
+    subscribe(listener: (state: PostListState<T>) => void): Cleanup;
+    dispose(): void;
+}
+/**
+ * Shared search, combined tag/category filtering, facets, and load-more state.
+ * @returns A controller whose subscriptions receive the initial state immediately.
+ */
+export declare function createPostListController<T>(options: PostListOptions<T>): PostListController<T>;