@fecommunity/reactpress-toolkit 3.0.4 → 3.7.0

package/dist/extension/preview.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewDraftApiPath = previewDraftApiPath;
+exports.normalizePreviewDraftData = normalizePreviewDraftData;
+exports.fetchPreviewDraft = fetchPreviewDraft;
+exports.resolveThemePreviewContext = resolveThemePreviewContext;
+const axios_1 = __importDefault(require("axios"));
+const api_1 = require("../theme/api");
+const preview_draft_1 = require("../theme/preview-draft");
+const preview_mods_1 = require("../theme/preview-mods");
+const resolve_1 = require("./configuration/resolve");
+const theme_1 = require("./theme");
+/** Relative API path for a preview draft token. */
+function previewDraftApiPath(token) {
+    return `/extension/themes/preview-draft/${encodeURIComponent(token.trim())}`;
+}
+/**
+ * Normalize API or axios-interceptor output into a preview draft.
+ * Accepts either `{ success, data }` envelopes or plain draft objects.
+ */
+function normalizePreviewDraftData(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {};
+    }
+    const envelope = raw;
+    if ('success' in envelope && 'data' in envelope) {
+        if (envelope.success === false)
+            return {};
+        return normalizePreviewDraftData(envelope.data);
+    }
+    const draft = raw;
+    return {
+        themeId: typeof draft.themeId === 'string' ? draft.themeId : undefined,
+        mods: draft.mods,
+        configuration: draft.configuration,
+    };
+}
+/** Load short-lived customizer preview payload (public GET by token). */
+async function fetchPreviewDraft(token, options) {
+    const trimmed = token.trim();
+    if (!trimmed)
+        return {};
+    if (options?.fetcher) {
+        return normalizePreviewDraftData(await options.fetcher(trimmed));
+    }
+    const base = (options?.baseURL ?? (0, api_1.resolveThemeApiBaseUrl)()).replace(/\/$/, '');
+    try {
+        const { data } = await axios_1.default.get(`${base}${previewDraftApiPath(trimmed)}`, {
+            timeout: 60000,
+        });
+        return normalizePreviewDraftData(data);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve site config, setting overlays, and customizer mods for a Next.js `_app` request.
+ * Themes should call this once in `getInitialProps` and pass results into their context/provider.
+ */
+async function resolveThemePreviewContext(input) {
+    const locale = input.locale ?? 'zh';
+    const themeState = (0, theme_1.getThemeStateFromGlobalSetting)(input.globalSettingRaw);
+    const previewToken = input.ctx ? (0, preview_draft_1.parsePreviewTokenFromNextCtx)(input.ctx) : '';
+    let draft = null;
+    if (previewToken) {
+        draft = await fetchPreviewDraft(previewToken, {
+            baseURL: input.apiBaseURL,
+            fetcher: input.fetchDraft,
+        });
+    }
+    const previewConfig = draft?.configuration ?? {};
+    const previewMods = draft?.mods ?? {};
+    const configThemeId = draft?.themeId ?? themeState.activeTheme;
+    const siteConfig = (0, resolve_1.resolveSiteConfig)(input.globalSettingRaw, configThemeId, locale, input.manifest, Object.keys(previewConfig).length > 0 ? previewConfig : undefined);
+    const savedMods = themeState.mods[configThemeId] ?? {};
+    const effectiveMods = (0, preview_mods_1.mergePreviewMods)(savedMods, previewMods);
+    const setting = (0, theme_1.applyThemeModsToSiteSetting)(input.setting, effectiveMods);
+    const colorPrimary = (0, theme_1.appearancePrimaryColor)(effectiveMods);
+    return {
+        siteConfig,
+        setting,
+        colorPrimary,
+        effectiveMods,
+        configThemeId,
+        isPreview: Boolean(previewToken),
+        draft,
+    };
+}

package/dist/extension/site-notices.d.ts

@@ -0,0 +1,19 @@
+/** Single site-wide notice (stored in `Setting.systemNoticeInfo` as JSON). */
+export type SiteNoticeItem = {
+    id: string;
+    content: string;
+    /** Default true when omitted. */
+    enabled?: boolean;
+};
+/**
+ * Parse `systemNoticeInfo` from DB / API.
+ * Supports JSON array, legacy newline-separated text, or plain string.
+ */
+export declare function parseSiteNotices(raw: unknown): SiteNoticeItem[];
+/** Persist notices for `Setting.systemNoticeInfo`. */
+export declare function serializeSiteNotices(items: SiteNoticeItem[]): string;
+/** Ordered notice HTML/text lines for the visitor banner (enabled only). */
+export declare function siteNoticeDisplayLines(raw: unknown): string[];
+export declare function createEmptySiteNotice(): SiteNoticeItem;
+/** Whether theme mod `siteNotice` is empty or identical to system `systemNoticeInfo`. */
+export declare function siteNoticeModInheritsSystem(modRaw: string | undefined, systemRaw: unknown): boolean;

package/dist/extension/site-notices.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSiteNotices = parseSiteNotices;
+exports.serializeSiteNotices = serializeSiteNotices;
+exports.siteNoticeDisplayLines = siteNoticeDisplayLines;
+exports.createEmptySiteNotice = createEmptySiteNotice;
+exports.siteNoticeModInheritsSystem = siteNoticeModInheritsSystem;
+function newNoticeId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    return `notice-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function normalizeItem(raw, index) {
+    if (typeof raw === 'string') {
+        const content = raw.trim();
+        if (!content)
+            return null;
+        return { id: `legacy-${index}`, content, enabled: true };
+    }
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    const content = typeof o.content === 'string' ? o.content : typeof o.text === 'string' ? o.text : '';
+    if (!content.trim())
+        return null;
+    const id = typeof o.id === 'string' && o.id.trim() ? o.id.trim() : newNoticeId();
+    const enabled = o.enabled === false ? false : true;
+    return { id, content, enabled };
+}
+/**
+ * Parse `systemNoticeInfo` from DB / API.
+ * Supports JSON array, legacy newline-separated text, or plain string.
+ */
+function parseSiteNotices(raw) {
+    if (raw == null)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((item, i) => normalizeItem(item, i)).filter((x) => x != null);
+    }
+    const text = String(raw).trim();
+    if (!text)
+        return [];
+    if (text.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(text);
+            if (Array.isArray(parsed)) {
+                return parsed.map((item, i) => normalizeItem(item, i)).filter((x) => x != null);
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((content, i) => ({ id: `legacy-${i}`, content, enabled: true }));
+}
+/** Persist notices for `Setting.systemNoticeInfo`. */
+function serializeSiteNotices(items) {
+    const cleaned = items
+        .map((item) => ({
+        id: item.id?.trim() || newNoticeId(),
+        content: item.content?.trim() ?? '',
+        enabled: item.enabled !== false,
+    }))
+        .filter((item) => item.content.length > 0);
+    return JSON.stringify(cleaned);
+}
+/** Ordered notice HTML/text lines for the visitor banner (enabled only). */
+function siteNoticeDisplayLines(raw) {
+    return parseSiteNotices(raw)
+        .filter((n) => n.enabled !== false)
+        .map((n) => n.content);
+}
+function createEmptySiteNotice() {
+    return { id: newNoticeId(), content: '', enabled: true };
+}
+/** Whether theme mod `siteNotice` is empty or identical to system `systemNoticeInfo`. */
+function siteNoticeModInheritsSystem(modRaw, systemRaw) {
+    if (!modRaw?.trim())
+        return true;
+    const modSerialized = serializeSiteNotices(parseSiteNotices(modRaw));
+    const sysSerialized = serializeSiteNotices(parseSiteNotices(systemRaw));
+    return modSerialized === sysSerialized;
+}

package/dist/extension/site-settings.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Site-wide vs theme-owned settings.
+ *
+ * - **System settings** (`SYSTEM_SETTING_FIELD_KEYS`): shared defaults (URLs, site identity,
+ *   SEO, i18n, mail). Edited under admin → 设置.
+ * - **Theme mods** (`THEME_BRANDING_*`): per-theme overrides in `globalSetting.theme.mods[themeId]`.
+ *   Empty mod → inherit the matching system setting at runtime.
+ * - **Theme-only** (footer / 关于我们): appearance only, no system setting column.
+ */
+import { THEME_BRANDING_DIRECT_MODS } from './branding-mods';
+import { type GlobalSettingWithTheme } from './theme';
+export { applyThemeModsToSiteSetting, seedThemeModsFromLegacySetting, THEME_BRANDING_DIRECT_MODS, THEME_BRANDING_MOD_TO_SETTING, } from './branding-mods';
+/** Site identity defaults (admin → 设置 → 常规). Themes may override via customizer mods. */
+export declare const SITE_DEFAULT_SETTING_KEYS: readonly ["systemTitle", "systemSubTitle", "systemLogo", "systemFavicon", "systemNoticeInfo"];
+/** SEO defaults (admin → 设置 → SEO). Themes may override via customizer mods. */
+export declare const SEO_DEFAULT_SETTING_KEYS: readonly ["seoKeyword", "seoDesc", "baiduAnalyticsId", "googleAnalyticsId"];
+/** Theme-only appearance (no system setting column). */
+export declare const THEME_ONLY_APPEARANCE_KEYS: readonly ["systemFooterInfo", "aboutUsGithubUrl", "aboutUsCommentQr", "aboutUsWechatQr"];
+/** DB columns managed as system configuration (admin → 设置). */
+export declare const SYSTEM_SETTING_FIELD_KEYS: readonly ["i18n", "systemUrl", "adminSystemUrl", "systemTitle", "systemSubTitle", "systemLogo", "systemFavicon", "systemNoticeInfo", "seoKeyword", "seoDesc", "baiduAnalyticsId", "googleAnalyticsId", "smtpHost", "smtpPort", "smtpUser", "smtpPass", "smtpFromUser"];
+export type SystemSettingFieldKey = (typeof SYSTEM_SETTING_FIELD_KEYS)[number];
+/** @deprecated Use SITE_DEFAULT_SETTING_KEYS + SEO_DEFAULT_SETTING_KEYS */
+export declare const LEGACY_APPEARANCE_SETTING_KEYS: readonly ["systemTitle", "systemSubTitle", "systemLogo", "systemFavicon", "systemNoticeInfo", "seoKeyword", "seoDesc", "baiduAnalyticsId", "googleAnalyticsId", "systemFooterInfo", "aboutUsGithubUrl", "aboutUsCommentQr", "aboutUsWechatQr"];
+export type ThemeBrandingDirectMod = (typeof THEME_BRANDING_DIRECT_MODS)[number];
+/** Keys exposed to anonymous theme `setting/get` (plus computed appearance overlay). */
+export declare const PUBLIC_SETTING_KEYS: readonly ["i18n", "systemUrl", "adminSystemUrl", "globalSetting", "systemTitle", "systemSubTitle", "systemLogo", "systemFavicon", "systemNoticeInfo", "seoKeyword", "seoDesc", "baiduAnalyticsId", "googleAnalyticsId", "systemFooterInfo", "aboutUsGithubUrl", "aboutUsCommentQr", "aboutUsWechatQr"];
+/** Copy legacy appearance columns into theme mods when mods are empty. */
+export declare function migrateLegacyAppearanceToThemeMods(globalRaw: unknown, settingRow: Record<string, unknown>): {
+    global: GlobalSettingWithTheme;
+    changed: boolean;
+};
+/** Strip non-system fields from admin PATCH payloads. */
+export declare function pickSystemSettingPatch(patch: Record<string, unknown>): Record<string, unknown>;
+/** Overlay active theme mods onto a Setting row for runtime (themes, mail templates). */
+export declare function resolveEffectiveSettingRow<T extends Record<string, unknown>>(row: T, globalRaw?: unknown, themeId?: string): T;
+/** Public API view: system keys + branding overlay + globalSetting. */
+export declare function buildPublicSettingView(row: Record<string, unknown>): Record<string, unknown>;

package/dist/extension/site-settings.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Site-wide vs theme-owned settings.
+ *
+ * - **System settings** (`SYSTEM_SETTING_FIELD_KEYS`): shared defaults (URLs, site identity,
+ *   SEO, i18n, mail). Edited under admin → 设置.
+ * - **Theme mods** (`THEME_BRANDING_*`): per-theme overrides in `globalSetting.theme.mods[themeId]`.
+ *   Empty mod → inherit the matching system setting at runtime.
+ * - **Theme-only** (footer / 关于我们): appearance only, no system setting column.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLIC_SETTING_KEYS = exports.LEGACY_APPEARANCE_SETTING_KEYS = exports.SYSTEM_SETTING_FIELD_KEYS = exports.THEME_ONLY_APPEARANCE_KEYS = exports.SEO_DEFAULT_SETTING_KEYS = exports.SITE_DEFAULT_SETTING_KEYS = exports.THEME_BRANDING_MOD_TO_SETTING = exports.THEME_BRANDING_DIRECT_MODS = exports.seedThemeModsFromLegacySetting = exports.applyThemeModsToSiteSetting = void 0;
+exports.migrateLegacyAppearanceToThemeMods = migrateLegacyAppearanceToThemeMods;
+exports.pickSystemSettingPatch = pickSystemSettingPatch;
+exports.resolveEffectiveSettingRow = resolveEffectiveSettingRow;
+exports.buildPublicSettingView = buildPublicSettingView;
+const branding_mods_1 = require("./branding-mods");
+const theme_1 = require("./theme");
+var branding_mods_2 = require("./branding-mods");
+Object.defineProperty(exports, "applyThemeModsToSiteSetting", { enumerable: true, get: function () { return branding_mods_2.applyThemeModsToSiteSetting; } });
+Object.defineProperty(exports, "seedThemeModsFromLegacySetting", { enumerable: true, get: function () { return branding_mods_2.seedThemeModsFromLegacySetting; } });
+Object.defineProperty(exports, "THEME_BRANDING_DIRECT_MODS", { enumerable: true, get: function () { return branding_mods_2.THEME_BRANDING_DIRECT_MODS; } });
+Object.defineProperty(exports, "THEME_BRANDING_MOD_TO_SETTING", { enumerable: true, get: function () { return branding_mods_2.THEME_BRANDING_MOD_TO_SETTING; } });
+/** Site identity defaults (admin → 设置 → 常规). Themes may override via customizer mods. */
+exports.SITE_DEFAULT_SETTING_KEYS = [
+    'systemTitle',
+    'systemSubTitle',
+    'systemLogo',
+    'systemFavicon',
+    'systemNoticeInfo',
+];
+/** SEO defaults (admin → 设置 → SEO). Themes may override via customizer mods. */
+exports.SEO_DEFAULT_SETTING_KEYS = [
+    'seoKeyword',
+    'seoDesc',
+    'baiduAnalyticsId',
+    'googleAnalyticsId',
+];
+/** Theme-only appearance (no system setting column). */
+exports.THEME_ONLY_APPEARANCE_KEYS = [
+    'systemFooterInfo',
+    'aboutUsGithubUrl',
+    'aboutUsCommentQr',
+    'aboutUsWechatQr',
+];
+/** DB columns managed as system configuration (admin → 设置). */
+exports.SYSTEM_SETTING_FIELD_KEYS = [
+    'i18n',
+    'systemUrl',
+    'adminSystemUrl',
+    ...exports.SITE_DEFAULT_SETTING_KEYS,
+    ...exports.SEO_DEFAULT_SETTING_KEYS,
+    'smtpHost',
+    'smtpPort',
+    'smtpUser',
+    'smtpPass',
+    'smtpFromUser',
+];
+/** @deprecated Use SITE_DEFAULT_SETTING_KEYS + SEO_DEFAULT_SETTING_KEYS */
+exports.LEGACY_APPEARANCE_SETTING_KEYS = [
+    ...exports.SITE_DEFAULT_SETTING_KEYS,
+    ...exports.SEO_DEFAULT_SETTING_KEYS,
+    ...exports.THEME_ONLY_APPEARANCE_KEYS,
+];
+/** Keys exposed to anonymous theme `setting/get` (plus computed appearance overlay). */
+exports.PUBLIC_SETTING_KEYS = [
+    'i18n',
+    'systemUrl',
+    'adminSystemUrl',
+    'globalSetting',
+    ...exports.LEGACY_APPEARANCE_SETTING_KEYS,
+];
+function modHasValue(mods, modId) {
+    const v = mods[modId];
+    return v != null && String(v).trim() !== '';
+}
+/** Copy legacy appearance columns into theme mods when mods are empty. */
+function migrateLegacyAppearanceToThemeMods(globalRaw, settingRow) {
+    const base = globalRaw && typeof globalRaw === 'object'
+        ? { ...globalRaw }
+        : {};
+    const themeState = (0, theme_1.getThemeStateFromGlobalSetting)(base);
+    const themeIds = new Set([
+        themeState.activeTheme,
+        ...themeState.installedThemes,
+    ]);
+    const mods = themeState.mods && typeof themeState.mods === 'object'
+        ? { ...themeState.mods }
+        : {};
+    let changed = false;
+    for (const themeId of themeIds) {
+        if (!themeId)
+            continue;
+        const current = mods[themeId] ?? {};
+        const seeded = (0, branding_mods_1.seedThemeModsFromLegacySetting)(settingRow, current);
+        const currentHasValues = Object.keys(current).some((k) => modHasValue(current, k));
+        const seededHasValues = Object.keys(seeded).some((k) => modHasValue(seeded, k));
+        if (!currentHasValues && seededHasValues) {
+            mods[themeId] = seeded;
+            changed = true;
+        }
+    }
+    if (!changed) {
+        return { global: base, changed: false };
+    }
+    const next = { ...themeState, mods };
+    return { global: { ...base, theme: next }, changed: true };
+}
+/** Strip non-system fields from admin PATCH payloads. */
+function pickSystemSettingPatch(patch) {
+    const out = {};
+    for (const key of exports.SYSTEM_SETTING_FIELD_KEYS) {
+        if (key in patch)
+            out[key] = patch[key];
+    }
+    return out;
+}
+/** Overlay active theme mods onto a Setting row for runtime (themes, mail templates). */
+function resolveEffectiveSettingRow(row, globalRaw, themeId) {
+    const gs = globalRaw ?? row.globalSetting;
+    const themeState = (0, theme_1.getThemeStateFromGlobalSetting)(typeof gs === 'string'
+        ? (() => {
+            try {
+                return JSON.parse(gs);
+            }
+            catch {
+                return {};
+            }
+        })()
+        : gs);
+    const id = themeId ?? themeState.activeTheme;
+    const mods = themeState.mods[id] ?? {};
+    return (0, branding_mods_1.applyThemeModsToSiteSetting)(row, mods);
+}
+/** Public API view: system keys + branding overlay + globalSetting. */
+function buildPublicSettingView(row) {
+    const effective = resolveEffectiveSettingRow(row);
+    const out = {};
+    for (const key of exports.PUBLIC_SETTING_KEYS) {
+        if (effective[key] !== undefined)
+            out[key] = effective[key];
+    }
+    return out;
+}

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

@@ -0,0 +1,11 @@
+import type { ThemeConfigurationSchema } from './configuration/types';
+/** Customizer copy shipped with the theme (`locales/{locale}.json`). */
+export type ThemeAdminLocaleMessages = Record<string, unknown>;
+export declare const THEME_LOCALE_DIR = "locales";
+export declare function getNestedLocaleValue(obj: unknown, dotPath: string): unknown;
+export declare function getNestedLocaleString(obj: unknown, dotPath: string): string | undefined;
+/** Resolve admin copy from theme locale bundle; falls back to manifest text. */
+export declare function resolveThemeAdminLocaleText(messages: ThemeAdminLocaleMessages | null | undefined, dotPath: string, fallback?: string): string;
+export declare function resolveThemeAdminLocaleTags(messages: ThemeAdminLocaleMessages | null | undefined, fallback?: string[]): string[];
+/** Apply theme admin locale messages to options JSON Schema titles/descriptions. */
+export declare function localizeThemeConfigurationSchemaWithLocale(schema: ThemeConfigurationSchema | null | undefined, messages: ThemeAdminLocaleMessages | null | undefined): ThemeConfigurationSchema | null;

package/dist/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/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/extension/theme-admin-locale.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THEME_LOCALE_DIR = void 0;
+exports.getNestedLocaleValue = getNestedLocaleValue;
+exports.getNestedLocaleString = getNestedLocaleString;
+exports.resolveThemeAdminLocaleText = resolveThemeAdminLocaleText;
+exports.resolveThemeAdminLocaleTags = resolveThemeAdminLocaleTags;
+exports.localizeThemeConfigurationSchemaWithLocale = localizeThemeConfigurationSchemaWithLocale;
+exports.THEME_LOCALE_DIR = 'locales';
+function getNestedLocaleValue(obj, dotPath) {
+    const parts = dotPath.split('.').filter(Boolean);
+    let cur = obj;
+    for (const part of parts) {
+        if (!cur || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function getNestedLocaleString(obj, dotPath) {
+    const value = getNestedLocaleValue(obj, dotPath);
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+/** Resolve admin copy from theme locale bundle; falls back to manifest text. */
+function resolveThemeAdminLocaleText(messages, dotPath, fallback) {
+    const fromLocale = messages ? getNestedLocaleString(messages, dotPath) : undefined;
+    if (fromLocale)
+        return fromLocale;
+    return fallback?.trim() ?? '';
+}
+function resolveThemeAdminLocaleTags(messages, fallback) {
+    const raw = messages ? 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/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 '../theme/assets';
+export { appendPreviewConfigToUrl, parsePreviewConfigFromNextCtx, parsePreviewConfigFromRequestUrl, parsePreviewConfigParam, PREVIEW_CONFIG_QUERY_KEY, } from '../theme/preview-config';
+export { appendPreviewTokenToUrl, parsePreviewTokenFromNextCtx, parsePreviewTokenFromRequestUrl, PREVIEW_TOKEN_QUERY_KEY, type PreviewDraftPayload, } from '../theme/preview-draft';
+export { appendPreviewModsToUrl, mergePreviewMods, parsePreviewModsFromNextCtx, parsePreviewModsFromRequestUrl, parsePreviewModsParam, PREVIEW_MODS_QUERY_KEY, } from '../theme/preview-mods';
+export declare function mergeThemeStateIntoGlobalSetting(raw: unknown, patch: Partial<SiteThemeState>): GlobalSettingWithTheme;