@fecommunity/reactpress-toolkit 3.0.4 → 3.1.0

package/dist/theme/extension/theme-admin-locale.io.d.ts

@@ -0,0 +1,2 @@
+import { type ThemeAdminLocaleMessages } from './theme-admin-locale';
+export declare function readThemeAdminLocaleFile(themeDir: string, locale: string): ThemeAdminLocaleMessages | null;

package/dist/theme/extension/theme-admin-locale.io.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readThemeAdminLocaleFile = readThemeAdminLocaleFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const theme_admin_locale_1 = require("./theme-admin-locale");
+function readThemeAdminLocaleFile(themeDir, locale) {
+    const safeLocale = /^[a-z]{2}(?:-[a-z]{2})?$/i.test(locale) ? locale : 'en';
+    const filePath = path.join(themeDir, theme_admin_locale_1.THEME_LOCALE_DIR, `${safeLocale}.json`);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return raw && typeof raw === 'object' && !Array.isArray(raw)
+            ? raw
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/theme/extension/theme-admin-locale.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestedLocaleValue = exports.getNestedLocaleString = exports.THEME_LOCALE_DIR = void 0;
+exports.resolveThemeAdminLocaleText = resolveThemeAdminLocaleText;
+exports.resolveThemeAdminLocaleTags = resolveThemeAdminLocaleTags;
+exports.localizeThemeConfigurationSchemaWithLocale = localizeThemeConfigurationSchemaWithLocale;
+const object_1 = require("../../utils/object");
+Object.defineProperty(exports, "getNestedLocaleString", { enumerable: true, get: function () { return object_1.getNestedLocaleString; } });
+Object.defineProperty(exports, "getNestedLocaleValue", { enumerable: true, get: function () { return object_1.getNestedLocaleValue; } });
+exports.THEME_LOCALE_DIR = 'locales';
+/** Resolve admin copy from theme locale bundle; falls back to manifest text. */
+function resolveThemeAdminLocaleText(messages, dotPath, fallback) {
+    const fromLocale = messages ? (0, object_1.getNestedLocaleString)(messages, dotPath) : undefined;
+    if (fromLocale)
+        return fromLocale;
+    return fallback?.trim() ?? '';
+}
+function resolveThemeAdminLocaleTags(messages, fallback) {
+    const raw = messages ? (0, object_1.getNestedLocaleValue)(messages, 'meta.tags') : undefined;
+    if (Array.isArray(raw) && raw.every((item) => typeof item === 'string')) {
+        return raw;
+    }
+    return fallback ?? [];
+}
+function localizeSchemaField(field, pathParts, resolve) {
+    if (typeof field.title === 'string') {
+        field.title = resolve([...pathParts, 'title'].join('.'), field.title);
+    }
+    if (typeof field.description === 'string') {
+        field.description = resolve([...pathParts, 'description'].join('.'), field.description);
+    }
+    if (field.properties) {
+        for (const [key, child] of Object.entries(field.properties)) {
+            localizeSchemaField(child, [...pathParts, key], resolve);
+        }
+    }
+    const items = field.items;
+    if (items && typeof items === 'object' && !Array.isArray(items)) {
+        const itemSchema = items;
+        if (itemSchema.properties) {
+            for (const [key, child] of Object.entries(itemSchema.properties)) {
+                localizeSchemaField(child, [...pathParts, 'items', key], resolve);
+            }
+        }
+        else {
+            localizeSchemaField(itemSchema, [...pathParts, 'items'], resolve);
+        }
+    }
+}
+/** Apply theme admin locale messages to options JSON Schema titles/descriptions. */
+function localizeThemeConfigurationSchemaWithLocale(schema, messages) {
+    if (!schema)
+        return null;
+    const out = structuredClone(schema);
+    const resolve = (dotPath, fallback) => resolveThemeAdminLocaleText(messages, `options.${dotPath}`, fallback);
+    if (typeof out.title === 'string') {
+        out.title = resolve('title', out.title);
+    }
+    if (typeof out.description === 'string') {
+        out.description = resolve('description', out.description);
+    }
+    if (out.properties) {
+        for (const [key, field] of Object.entries(out.properties)) {
+            localizeSchemaField(field, [key], resolve);
+        }
+    }
+    return out;
+}

package/dist/theme/extension/theme.d.ts

@@ -0,0 +1,89 @@
+/** WordPress-style theme manifest and site theme state (shared by server / web / themes). */
+import type { ThemeConfigurationSchema } from './configuration/types';
+export interface ThemeAppearanceChoice {
+    value: string;
+    label: string;
+}
+/** Appearance control (declared in `theme.json` → `appearance.sections`). */
+export interface ThemeAppearanceSetting {
+    id: string;
+    type: 'color' | 'text' | 'image' | 'textarea' | 'checkbox' | 'select' | 'noticeList';
+    label: string;
+    default?: string;
+    description?: string;
+    choices?: ThemeAppearanceChoice[];
+    /** Sub-group within a section (e.g. light vs dark colors). */
+    group?: string;
+}
+/** Sidebar nav panel (Site Identity, Colors, …). */
+export interface ThemeAppearancePanel {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** Control group inside a section panel (e.g. Light / Dark). */
+export interface ThemeAppearanceGroup {
+    id: string;
+    title: string;
+    description?: string;
+}
+export interface ThemeAppearanceSection {
+    id: string;
+    title: string;
+    /** Nav panel id (`appearance.panels[].id`). */
+    panel?: string;
+    settings?: ThemeAppearanceSetting[];
+    groups?: ThemeAppearanceGroup[];
+    /** Embed the theme `options` schema form instead of inline controls. */
+    embed?: 'options';
+    description?: string;
+}
+export interface ThemeAppearanceManifest {
+    panels?: ThemeAppearancePanel[];
+    sections: ThemeAppearanceSection[];
+}
+export type { ThemeMods } from './branding-mods';
+export { applyThemeModsToSiteSetting, seedThemeModsFromLegacySetting, THEME_BRANDING_DIRECT_MODS, THEME_BRANDING_MOD_TO_SETTING, } from './branding-mods';
+import type { ThemeMods } from './branding-mods';
+export { appearancePrimaryColorForMode } from './twentytwentyfive-vars';
+/** Primary color from appearance mods (Ant Design / CSS), light mode. */
+export declare function appearancePrimaryColor(mods: ThemeMods, fallback?: string): string;
+export interface ThemeManifest {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    authorUri?: string;
+    themeUri?: string;
+    tags?: string[];
+    /** Theme cover image path (relative to theme root). Shown in admin theme list / preview. */
+    cover?: string;
+    requires?: string;
+    supports?: Record<string, unknown>;
+    templates?: Record<string, string>;
+    options?: ThemeConfigurationSchema;
+    appearance?: ThemeAppearanceManifest;
+}
+export interface SiteThemeState {
+    activeTheme: string;
+    installedThemes: string[];
+    mods: Record<string, ThemeMods>;
+    previewThemeId?: string;
+}
+export declare const DEFAULT_ACTIVE_THEME = "twentytwentyfive";
+export declare const defaultSiteThemeState: SiteThemeState;
+export interface GlobalSettingWithTheme {
+    zh?: unknown;
+    en?: unknown;
+    theme?: SiteThemeState;
+    config?: Record<string, Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export declare function parseThemeManifest(raw: unknown): ThemeManifest | null;
+export declare function getThemeStateFromGlobalSetting(raw: unknown): SiteThemeState;
+export { resolvePublicAssetUrl } from '../content/assets';
+export { appendPreviewConfigToUrl, parsePreviewConfigFromNextCtx, parsePreviewConfigFromRequestUrl, parsePreviewConfigParam, PREVIEW_CONFIG_QUERY_KEY, } from '../preview/preview-config';
+export { appendPreviewTokenToUrl, parsePreviewTokenFromNextCtx, parsePreviewTokenFromRequestUrl, PREVIEW_TOKEN_QUERY_KEY, type PreviewDraftPayload, } from '../preview/preview-draft';
+export { appendPreviewModsToUrl, mergePreviewMods, parsePreviewModsFromNextCtx, parsePreviewModsFromRequestUrl, parsePreviewModsParam, PREVIEW_MODS_QUERY_KEY, } from '../preview/preview-mods';
+export declare function mergeThemeStateIntoGlobalSetting(raw: unknown, patch: Partial<SiteThemeState>): GlobalSettingWithTheme;

package/dist/theme/extension/theme.js

@@ -0,0 +1,93 @@
+"use strict";
+/** WordPress-style theme manifest and site theme state (shared by server / web / themes). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_MODS_QUERY_KEY = exports.parsePreviewModsParam = exports.parsePreviewModsFromRequestUrl = exports.parsePreviewModsFromNextCtx = exports.mergePreviewMods = exports.appendPreviewModsToUrl = exports.PREVIEW_TOKEN_QUERY_KEY = exports.parsePreviewTokenFromRequestUrl = exports.parsePreviewTokenFromNextCtx = exports.appendPreviewTokenToUrl = exports.PREVIEW_CONFIG_QUERY_KEY = exports.parsePreviewConfigParam = exports.parsePreviewConfigFromRequestUrl = exports.parsePreviewConfigFromNextCtx = exports.appendPreviewConfigToUrl = exports.resolvePublicAssetUrl = exports.defaultSiteThemeState = exports.DEFAULT_ACTIVE_THEME = exports.appearancePrimaryColorForMode = exports.THEME_BRANDING_MOD_TO_SETTING = exports.THEME_BRANDING_DIRECT_MODS = exports.seedThemeModsFromLegacySetting = exports.applyThemeModsToSiteSetting = void 0;
+exports.appearancePrimaryColor = appearancePrimaryColor;
+exports.parseThemeManifest = parseThemeManifest;
+exports.getThemeStateFromGlobalSetting = getThemeStateFromGlobalSetting;
+exports.mergeThemeStateIntoGlobalSetting = mergeThemeStateIntoGlobalSetting;
+const manifest_normalize_1 = require("./manifest-normalize");
+var branding_mods_1 = require("./branding-mods");
+Object.defineProperty(exports, "applyThemeModsToSiteSetting", { enumerable: true, get: function () { return branding_mods_1.applyThemeModsToSiteSetting; } });
+Object.defineProperty(exports, "seedThemeModsFromLegacySetting", { enumerable: true, get: function () { return branding_mods_1.seedThemeModsFromLegacySetting; } });
+Object.defineProperty(exports, "THEME_BRANDING_DIRECT_MODS", { enumerable: true, get: function () { return branding_mods_1.THEME_BRANDING_DIRECT_MODS; } });
+Object.defineProperty(exports, "THEME_BRANDING_MOD_TO_SETTING", { enumerable: true, get: function () { return branding_mods_1.THEME_BRANDING_MOD_TO_SETTING; } });
+const twentytwentyfive_vars_1 = require("./twentytwentyfive-vars");
+var twentytwentyfive_vars_2 = require("./twentytwentyfive-vars");
+Object.defineProperty(exports, "appearancePrimaryColorForMode", { enumerable: true, get: function () { return twentytwentyfive_vars_2.appearancePrimaryColorForMode; } });
+/** Primary color from appearance mods (Ant Design / CSS), light mode. */
+function appearancePrimaryColor(mods, fallback = '#f44336') {
+    return (0, twentytwentyfive_vars_1.appearancePrimaryColorForMode)(mods, false, fallback);
+}
+exports.DEFAULT_ACTIVE_THEME = 'twentytwentyfive';
+exports.defaultSiteThemeState = {
+    activeTheme: exports.DEFAULT_ACTIVE_THEME,
+    installedThemes: [exports.DEFAULT_ACTIVE_THEME],
+    mods: {},
+};
+function parseThemeManifest(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (typeof o.id !== 'string' || typeof o.name !== 'string')
+        return null;
+    const platform = (0, manifest_normalize_1.normalizePlatformFields)(o);
+    const appearance = (0, manifest_normalize_1.normalizeAppearance)(o.appearance);
+    return {
+        id: o.id,
+        name: o.name,
+        version: typeof o.version === 'string' ? o.version : '1.0.0',
+        description: typeof o.description === 'string' ? o.description : undefined,
+        author: typeof o.author === 'string' ? o.author : undefined,
+        authorUri: typeof o.authorUri === 'string' ? o.authorUri : undefined,
+        themeUri: typeof o.themeUri === 'string' ? o.themeUri : undefined,
+        tags: Array.isArray(o.tags) ? o.tags.filter((t) => typeof t === 'string') : undefined,
+        cover: typeof o.cover === 'string' ? o.cover : undefined,
+        ...platform,
+        appearance,
+    };
+}
+function getThemeStateFromGlobalSetting(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { ...exports.defaultSiteThemeState };
+    const gs = raw;
+    const theme = gs.theme;
+    if (!theme || typeof theme !== 'object')
+        return { ...exports.defaultSiteThemeState };
+    return {
+        activeTheme: typeof theme.activeTheme === 'string' ? theme.activeTheme : exports.defaultSiteThemeState.activeTheme,
+        installedThemes: Array.isArray(theme.installedThemes)
+            ? theme.installedThemes.filter((id) => typeof id === 'string')
+            : [...exports.defaultSiteThemeState.installedThemes],
+        mods: theme.mods && typeof theme.mods === 'object'
+            ? theme.mods
+            : {},
+        previewThemeId: typeof theme.previewThemeId === 'string' ? theme.previewThemeId : undefined,
+    };
+}
+var assets_1 = require("../content/assets");
+Object.defineProperty(exports, "resolvePublicAssetUrl", { enumerable: true, get: function () { return assets_1.resolvePublicAssetUrl; } });
+var preview_config_1 = require("../preview/preview-config");
+Object.defineProperty(exports, "appendPreviewConfigToUrl", { enumerable: true, get: function () { return preview_config_1.appendPreviewConfigToUrl; } });
+Object.defineProperty(exports, "parsePreviewConfigFromNextCtx", { enumerable: true, get: function () { return preview_config_1.parsePreviewConfigFromNextCtx; } });
+Object.defineProperty(exports, "parsePreviewConfigFromRequestUrl", { enumerable: true, get: function () { return preview_config_1.parsePreviewConfigFromRequestUrl; } });
+Object.defineProperty(exports, "parsePreviewConfigParam", { enumerable: true, get: function () { return preview_config_1.parsePreviewConfigParam; } });
+Object.defineProperty(exports, "PREVIEW_CONFIG_QUERY_KEY", { enumerable: true, get: function () { return preview_config_1.PREVIEW_CONFIG_QUERY_KEY; } });
+var preview_draft_1 = require("../preview/preview-draft");
+Object.defineProperty(exports, "appendPreviewTokenToUrl", { enumerable: true, get: function () { return preview_draft_1.appendPreviewTokenToUrl; } });
+Object.defineProperty(exports, "parsePreviewTokenFromNextCtx", { enumerable: true, get: function () { return preview_draft_1.parsePreviewTokenFromNextCtx; } });
+Object.defineProperty(exports, "parsePreviewTokenFromRequestUrl", { enumerable: true, get: function () { return preview_draft_1.parsePreviewTokenFromRequestUrl; } });
+Object.defineProperty(exports, "PREVIEW_TOKEN_QUERY_KEY", { enumerable: true, get: function () { return preview_draft_1.PREVIEW_TOKEN_QUERY_KEY; } });
+var preview_mods_1 = require("../preview/preview-mods");
+Object.defineProperty(exports, "appendPreviewModsToUrl", { enumerable: true, get: function () { return preview_mods_1.appendPreviewModsToUrl; } });
+Object.defineProperty(exports, "mergePreviewMods", { enumerable: true, get: function () { return preview_mods_1.mergePreviewMods; } });
+Object.defineProperty(exports, "parsePreviewModsFromNextCtx", { enumerable: true, get: function () { return preview_mods_1.parsePreviewModsFromNextCtx; } });
+Object.defineProperty(exports, "parsePreviewModsFromRequestUrl", { enumerable: true, get: function () { return preview_mods_1.parsePreviewModsFromRequestUrl; } });
+Object.defineProperty(exports, "parsePreviewModsParam", { enumerable: true, get: function () { return preview_mods_1.parsePreviewModsParam; } });
+Object.defineProperty(exports, "PREVIEW_MODS_QUERY_KEY", { enumerable: true, get: function () { return preview_mods_1.PREVIEW_MODS_QUERY_KEY; } });
+function mergeThemeStateIntoGlobalSetting(raw, patch) {
+    const base = raw && typeof raw === 'object' ? { ...raw } : {};
+    const current = getThemeStateFromGlobalSetting(base);
+    base.theme = { ...current, ...patch };
+    return base;
+}

package/dist/theme/extension/twentytwentyfive-vars.d.ts

@@ -0,0 +1,9 @@
+import { type ThemeMods } from './branding-mods';
+export declare function appearanceBackgroundColor(mods: ThemeMods, fallback?: string): string | undefined;
+export declare function appearanceSecondaryBackgroundColor(mods: ThemeMods): string | undefined;
+export declare function appearanceLinkColor(mods: ThemeMods): string | undefined;
+export declare function appearancePrimaryColorForMode(mods: ThemeMods, dark: boolean, fallback?: string): string;
+/** Maps theme appearance color mods to standard CSS variables (`--primary-color`, `--bg`, …). */
+export declare function buildBrandingAppearanceCss(mods: ThemeMods): string;
+/** @deprecated Use `buildBrandingAppearanceCss`. */
+export declare const buildTwentyTwentyFiveAppearanceCss: typeof buildBrandingAppearanceCss;

package/dist/theme/extension/twentytwentyfive-vars.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTwentyTwentyFiveAppearanceCss = void 0;
+exports.appearanceBackgroundColor = appearanceBackgroundColor;
+exports.appearanceSecondaryBackgroundColor = appearanceSecondaryBackgroundColor;
+exports.appearanceLinkColor = appearanceLinkColor;
+exports.appearancePrimaryColorForMode = appearancePrimaryColorForMode;
+exports.buildBrandingAppearanceCss = buildBrandingAppearanceCss;
+const branding_mods_1 = require("./branding-mods");
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function normalizeHexColor(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!HEX_COLOR.test(trimmed))
+        return undefined;
+    if (trimmed.length === 4) {
+        const [, r, g, b] = trimmed;
+        return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
+    }
+    return trimmed.toLowerCase();
+}
+function hexToRgbChannels(hex) {
+    const normalized = normalizeHexColor(hex);
+    if (!normalized)
+        return null;
+    const raw = normalized.slice(1);
+    const r = parseInt(raw.slice(0, 2), 16);
+    const g = parseInt(raw.slice(2, 4), 16);
+    const b = parseInt(raw.slice(4, 6), 16);
+    if ([r, g, b].some((n) => Number.isNaN(n)))
+        return null;
+    return `${r}, ${g}, ${b}`;
+}
+const LIGHT_COLOR_KEYS = {
+    primary: 'primaryColor',
+    background: 'backgroundColor',
+    secondaryBackground: 'secondaryBackgroundColor',
+    link: 'linkColor',
+};
+const DARK_COLOR_KEYS = {
+    primary: 'darkPrimaryColor',
+    background: 'darkBackgroundColor',
+    secondaryBackground: 'darkSecondaryBackgroundColor',
+    link: 'darkLinkColor',
+};
+function buildModeColorDeclarations(mods, keys) {
+    const primary = normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, keys.primary));
+    const background = normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, keys.background));
+    const secondaryBg = normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, keys.secondaryBackground));
+    const link = normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, keys.link));
+    const declarations = [];
+    if (primary)
+        declarations.push(`--primary-color: ${primary};`);
+    if (background) {
+        declarations.push(`--bg: ${background};`);
+        declarations.push(`--bg-body: ${background};`);
+    }
+    if (secondaryBg) {
+        declarations.push(`--bg-second: ${secondaryBg};`);
+        declarations.push(`--bg-box: ${secondaryBg};`);
+        const rgb = hexToRgbChannels(secondaryBg);
+        if (rgb)
+            declarations.push(`--rgb-bg-second: ${rgb};`);
+    }
+    else if (background) {
+        declarations.push(`--bg-box: ${background};`);
+    }
+    if (link)
+        declarations.push(`--link-color: ${link};`);
+    return declarations;
+}
+function appearanceBackgroundColor(mods, fallback) {
+    const v = (0, branding_mods_1.brandingModValue)(mods, LIGHT_COLOR_KEYS.background);
+    return normalizeHexColor(v) ?? (fallback ? normalizeHexColor(fallback) : undefined);
+}
+function appearanceSecondaryBackgroundColor(mods) {
+    return normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, LIGHT_COLOR_KEYS.secondaryBackground));
+}
+function appearanceLinkColor(mods) {
+    return normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, LIGHT_COLOR_KEYS.link));
+}
+function appearancePrimaryColorForMode(mods, dark, fallback = '#f44336') {
+    const keys = dark ? DARK_COLOR_KEYS : LIGHT_COLOR_KEYS;
+    return (normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, keys.primary)) ??
+        normalizeHexColor((0, branding_mods_1.brandingModValue)(mods, LIGHT_COLOR_KEYS.primary)) ??
+        fallback);
+}
+/** Maps theme appearance color mods to standard CSS variables (`--primary-color`, `--bg`, …). */
+function buildBrandingAppearanceCss(mods) {
+    const lightDecl = buildModeColorDeclarations(mods, LIGHT_COLOR_KEYS);
+    const darkDecl = buildModeColorDeclarations(mods, DARK_COLOR_KEYS);
+    const blocks = [];
+    if (lightDecl.length > 0) {
+        blocks.push(`body:not(.dark) { ${lightDecl.join(' ')} }`);
+    }
+    if (darkDecl.length > 0) {
+        blocks.push(`body.dark { ${darkDecl.join(' ')} }`);
+    }
+    return blocks.join('\n');
+}
+/** @deprecated Use `buildBrandingAppearanceCss`. */
+exports.buildTwentyTwentyFiveAppearanceCss = buildBrandingAppearanceCss;

package/dist/theme/fetch.d.ts

@@ -0,0 +1,134 @@
+import type { ThemeApi } from './api';
+import type { ParseSiteLocaleOptions } from './locale';
+import type { ThemeRuntime } from './runtime';
+import type { SiteMeta } from './setting';
+/** Default ISR interval for theme list/home pages. */
+export declare const THEME_ISR_REVALIDATE_SECONDS = 60;
+/** Retry SSR API calls while the dev server is still starting (ECONNREFUSED). */
+export declare function withApiRetry<T>(fn: () => Promise<T>, attempts?: number, delayMs?: number): Promise<T>;
+/** Articles, categories, and tags for home / toolkit demo pages. */
+export declare function fetchThemeCatalog(api: ThemeApi): Promise<{
+    articles: unknown[];
+    categories: unknown[];
+    tags: unknown[];
+}>;
+/** Strip `undefined` values so Next.js can serialize `getStaticProps` results. */
+export declare function sanitizeNextProps<T>(props: T): T;
+export declare function themeStaticProps<T extends Record<string, unknown>>(props: T, revalidate?: number): {
+    props: T;
+    revalidate: number;
+};
+/** Visitor context for `getStaticProps` — `_app.getInitialProps` does not run on SSR for static pages. */
+export declare function resolveStaticVisitorContext(): Promise<VisitorContextProps>;
+/** All categories — `getStaticProps` for `pages/category/index.tsx`. */
+export declare function fetchCategoryIndex(api: ThemeApi): Promise<{
+    categories: unknown[];
+}>;
+/** All tags — `getStaticProps` for `pages/tag/index.tsx`. */
+export declare function fetchTagIndex(api: ThemeApi): Promise<{
+    tags: unknown[];
+}>;
+/** Site settings for about/footer pages (`getStaticProps`). */
+export declare function fetchSiteSettings<T extends Record<string, {
+    key: string;
+    default: string;
+}>>(api: ThemeApi, schema: T): Promise<{
+    [K in keyof T]: string;
+}>;
+export interface FetchVisitorContextOptions extends ParseSiteLocaleOptions {
+    themeId: string;
+    honorPreview?: boolean;
+}
+/** Props for `ReactPressProvider` — fetch once in `_app.getInitialProps` or `getStaticProps`. */
+export interface VisitorContextProps {
+    locale: string;
+    locales: string[];
+    messages: Record<string, string>;
+    catalog: Record<string, Record<string, string>>;
+    themeId: string;
+    activeThemeId: string;
+    mods: ThemeRuntime['mods'];
+    isPreview: boolean;
+    /** Site settings (`systemTitle`, `systemSubTitle`, …) for branding fallbacks. */
+    siteMeta: SiteMeta;
+}
+/** Safe defaults when API is unreachable (still wraps pages in Provider). */
+export declare function createDefaultVisitorContext(themeId: string, partial?: Partial<VisitorContextProps>): VisitorContextProps;
+export declare function fetchVisitorContext(api: ThemeApi, options: FetchVisitorContextOptions): Promise<VisitorContextProps>;
+/** Common site meta from the Setting row (`systemTitle`, `systemSubTitle`, …). */
+export declare function fetchSiteMeta(api: ThemeApi): Promise<SiteMeta>;
+/** Category archive — `getStaticProps` for `pages/category/[category].tsx`. */
+export declare function fetchCategoryArchive(api: ThemeApi, category: string): Promise<{
+    category: string;
+    articles: unknown[];
+    categories: unknown[];
+}>;
+/** Tag archive — `getStaticProps` for `pages/tag/[tag].tsx`. */
+export declare function fetchTagArchive(api: ThemeApi, tag: string): Promise<{
+    tag: string;
+    articles: unknown[];
+    tags: unknown[];
+}>;
+/** Article shape returned by theme article detail pages. */
+export type ThemeArticlePage = {
+    id: string;
+    title: string;
+    summary?: string;
+    html?: string;
+    cover?: string;
+    publishAt?: string;
+    views?: number;
+    category?: {
+        label: string;
+        value: string;
+    };
+    tags?: Array<{
+        label: string;
+        value: string;
+    }>;
+};
+/** Single article — `getStaticProps` for `pages/article/[id].tsx`. */
+export declare function fetchSingleArticle(api: ThemeApi, id: string): Promise<{
+    article: ThemeArticlePage | null;
+}>;
+/** Site search — `getServerSideProps` / `getStaticProps` helper. */
+export declare function fetchSearchArticles(api: ThemeApi, keyword: string): Promise<{
+    query: string;
+    articles: Array<{
+        id: string;
+        title: string;
+        summary?: string;
+        publishAt?: string;
+        category?: {
+            label: string;
+            value: string;
+        };
+    }>;
+}>;
+export type ThemeArchiveKind = 'category' | 'tag';
+type StaticPropsContext = {
+    params?: Record<string, string | string[] | undefined>;
+};
+/**
+ * Wrap `getStaticProps` fetchers with consistent logging and ISR fallback props.
+ */
+export declare function withThemeStaticProps<T extends Record<string, unknown>>(label: string, fetchFn: () => Promise<T>, fallback: T | ((error: unknown) => T)): Promise<{
+    props: T & {
+        reactPress: VisitorContextProps;
+    };
+    revalidate: number;
+}>;
+/** Factory for category/tag archive pages — removes duplicated `getStaticProps` boilerplate. */
+export declare function createArchiveGetStaticProps<T extends Record<string, unknown>>(kind: ThemeArchiveKind, fetchArchive: (api: ThemeApi, slug: string) => Promise<T>, emptyFallback: (slug: string) => T): (ctx: StaticPropsContext) => Promise<{
+    notFound: true;
+} | {
+    props: T & {
+        reactPress: VisitorContextProps;
+    };
+    revalidate: number;
+}>;
+/** Standard on-demand article page props. */
+export declare function fetchArticlePageProps(api: ThemeApi, id: string | undefined): Promise<{
+    article: ThemeArticlePage | null;
+}>;
+export {};