@fecommunity/reactpress-toolkit 3.0.4 → 3.7.0

package/dist/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("../theme/assets");
+Object.defineProperty(exports, "resolvePublicAssetUrl", { enumerable: true, get: function () { return assets_1.resolvePublicAssetUrl; } });
+var preview_config_1 = require("../theme/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("../theme/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("../theme/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/extension/twentytwentyfive-vars.d.ts

@@ -0,0 +1,7 @@
+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 Twenty Twenty-Five appearance color mods to theme CSS variables. */
+export declare function buildTwentyTwentyFiveAppearanceCss(mods: ThemeMods): string;

package/dist/extension/twentytwentyfive-vars.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appearanceBackgroundColor = appearanceBackgroundColor;
+exports.appearanceSecondaryBackgroundColor = appearanceSecondaryBackgroundColor;
+exports.appearanceLinkColor = appearanceLinkColor;
+exports.appearancePrimaryColorForMode = appearancePrimaryColorForMode;
+exports.buildTwentyTwentyFiveAppearanceCss = buildTwentyTwentyFiveAppearanceCss;
+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 Twenty Twenty-Five appearance color mods to theme CSS variables. */
+function buildTwentyTwentyFiveAppearanceCss(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');
+}

package/dist/index.d.ts

@@ -1,11 +1,19 @@
-import { api, createApiInstance } from './api/instance';
-import * as types from './types';
-import * as utils from './utils';
-import * as config from './config';
-declare const http: {
+export * as config from './config';
+export * as plugin from './plugin';
+export * as theme from './theme';
+export * as types from './types';
+export * as ui from './ui';
+export * as utils from './utils';
+/** @deprecated Prefer `@fecommunity/reactpress-toolkit/api` subpath imports. */
+export { api, createApiInstance, http as httpInstance } from './api/instance';
+export * from './config';
+export * from './types';
+export * from './utils';
+import { createApiInstance } from './api/instance';
+/** @deprecated Prefer `createApiInstance` from `@fecommunity/reactpress-toolkit/api/instance`. */
+export declare const http: {
     createApiInstance: typeof createApiInstance;
     instance: import("axios").AxiosInstance;
-    setSecurityData: (data: unknown) => void;
+    setSecurityData: (data: SecurityDataType | null) => void;
     request: <T = any, _E = any>({ secure, path, type, query, format, body, ...params }: import("./api/HttpClient").FullRequestParams) => Promise<T>;
 };
-export { api, types, utils, config, http };

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
-// Automatically generated API toolkit for ReactPress
-// Do not manually modify this file
-// Generated at: 9/25/2025, 9:47:27 PM
+// Public subpath modules: api, types, ui, utils, theme, plugin, config
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[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];
@@ -14,25 +16,45 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
+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;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.http = exports.config = exports.utils = exports.types = exports.api = void 0;
-const instance_1 = require("./api/instance");
+exports.http = exports.httpInstance = exports.createApiInstance = exports.api = exports.utils = exports.ui = exports.types = exports.theme = exports.plugin = exports.config = void 0;
+exports.config = __importStar(require("./config"));
+exports.plugin = __importStar(require("./plugin"));
+exports.theme = __importStar(require("./theme"));
+exports.types = __importStar(require("./types"));
+exports.ui = __importStar(require("./ui"));
+exports.utils = __importStar(require("./utils"));
+/** @deprecated Prefer `@fecommunity/reactpress-toolkit/api` subpath imports. */
+var instance_1 = require("./api/instance");
 Object.defineProperty(exports, "api", { enumerable: true, get: function () { return instance_1.api; } });
-const types = __importStar(require("./types"));
-exports.types = types;
-const utils = __importStar(require("./utils"));
-exports.utils = utils;
-const config = __importStar(require("./config"));
-exports.config = config;
-const http = {
-    ...instance_1.http,
-    createApiInstance: instance_1.createApiInstance,
+Object.defineProperty(exports, "createApiInstance", { enumerable: true, get: function () { return instance_1.createApiInstance; } });
+Object.defineProperty(exports, "httpInstance", { enumerable: true, get: function () { return instance_1.http; } });
+__exportStar(require("./config"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+const instance_2 = require("./api/instance");
+/** @deprecated Prefer `createApiInstance` from `@fecommunity/reactpress-toolkit/api/instance`. */
+exports.http = {
+    ...instance_2.http,
+    createApiInstance: instance_2.createApiInstance,
 };
-exports.http = http;

package/dist/plugin/admin/index.d.ts

@@ -0,0 +1,2 @@
+export * from './permissions';
+export * from './registry';

package/dist/plugin/admin/index.js

@@ -0,0 +1,18 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./permissions"), exports);
+__exportStar(require("./registry"), exports);

package/dist/plugin/admin/permissions.d.ts

@@ -0,0 +1,5 @@
+/** Admin capability strings — keep in sync with server guards. */
+export type Permission = 'article:read' | 'article:write' | 'article:publish' | 'media:manage' | 'page:manage' | 'user:manage' | 'setting:manage' | 'extension:manage' | 'comment:manage' | 'view:read';
+export declare const ADMIN_PERMISSIONS: Permission[];
+/** Map legacy server roles to capability strings. */
+export declare function permissionsForRole(role: string | undefined): Permission[];

package/dist/plugin/admin/permissions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMIN_PERMISSIONS = void 0;
+exports.permissionsForRole = permissionsForRole;
+exports.ADMIN_PERMISSIONS = [
+    'article:read',
+    'article:write',
+    'article:publish',
+    'media:manage',
+    'page:manage',
+    'user:manage',
+    'setting:manage',
+    'extension:manage',
+    'comment:manage',
+    'view:read',
+];
+/** Map legacy server roles to capability strings. */
+function permissionsForRole(role) {
+    if (role === 'admin')
+        return [...exports.ADMIN_PERMISSIONS];
+    if (role === 'editor') {
+        return [
+            'article:read',
+            'article:write',
+            'article:publish',
+            'media:manage',
+            'page:manage',
+            'comment:manage',
+            'view:read',
+        ];
+    }
+    return ['article:read', 'view:read'];
+}

package/dist/plugin/admin/plugin-admin.d.ts

@@ -0,0 +1,37 @@
+import type { AdminSlotId } from './slots';
+export interface PluginAdminContext {
+    id: string;
+    config: Record<string, unknown>;
+}
+/** Plugin admin entry — called once per active plugin when admin shell loads. */
+export interface PluginAdminModule {
+    registerAdmin(registry: PluginAdminRegistry, ctx: PluginAdminContext): void | Promise<void>;
+}
+/** Opaque component type — React `ComponentType` lives in `@fecommunity/reactpress-toolkit/plugin/react`. */
+export type PluginAdminSlotComponent = (props: PluginAdminSlotComponentProps<unknown>) => unknown;
+export interface PluginAdminSlotComponentProps<TContext = unknown> {
+    context: TContext;
+    pluginId: string;
+    config: Record<string, unknown>;
+}
+export interface PluginAdminSlotContribution {
+    pluginId: string;
+    slot: AdminSlotId;
+    priority: number;
+    Component: PluginAdminSlotComponent;
+}
+export interface PluginAdminRegistry {
+    registerSlot<TContext = unknown>(slot: AdminSlotId, component: (props: PluginAdminSlotComponentProps<TContext>) => unknown, options?: {
+        priority?: number;
+    }): void;
+}
+export interface PluginAdminSlotHost {
+    registerSlot<TContext = unknown>(pluginId: string, slot: AdminSlotId, component: (props: PluginAdminSlotComponentProps<TContext>) => unknown, options?: {
+        priority?: number;
+    }): void;
+    getContributions(slot: AdminSlotId): PluginAdminSlotContribution[];
+    reset(): void;
+}
+export declare function createPluginAdminSlotHost(): PluginAdminSlotHost;
+/** Registry passed to `registerAdmin` — scopes contributions to one plugin id. */
+export declare function createPluginAdminRegistry(pluginId: string, host: PluginAdminSlotHost): PluginAdminRegistry;

package/dist/plugin/admin/plugin-admin.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginAdminSlotHost = createPluginAdminSlotHost;
+exports.createPluginAdminRegistry = createPluginAdminRegistry;
+function createPluginAdminSlotHost() {
+    const contributions = [];
+    return {
+        registerSlot(pluginId, slot, component, options) {
+            const priority = options?.priority ?? 10;
+            const existing = contributions.findIndex((item) => item.pluginId === pluginId && item.slot === slot);
+            const entry = {
+                pluginId,
+                slot,
+                Component: component,
+                priority,
+            };
+            if (existing >= 0) {
+                contributions[existing] = entry;
+            }
+            else {
+                contributions.push(entry);
+            }
+        },
+        getContributions(slot) {
+            return contributions
+                .filter((item) => item.slot === slot)
+                .sort((a, b) => a.priority - b.priority);
+        },
+        reset() {
+            contributions.length = 0;
+        },
+    };
+}
+/** Registry passed to `registerAdmin` — scopes contributions to one plugin id. */
+function createPluginAdminRegistry(pluginId, host) {
+    return {
+        registerSlot(slot, component, options) {
+            host.registerSlot(pluginId, slot, component, options);
+        },
+    };
+}

package/dist/plugin/admin/registry.d.ts

@@ -0,0 +1,62 @@
+import type { Permission } from './permissions';
+export type MenuNodeKind = 'group' | 'item';
+export interface AdminMenuItem {
+    id: string;
+    kind: MenuNodeKind;
+    title: string;
+    path: string | null;
+    icon?: string | null;
+    sort?: number;
+    hidden?: boolean;
+    permissions?: Permission[] | null;
+    children?: AdminMenuItem[];
+}
+export interface MenuRegisterInput {
+    id: string;
+    title: string;
+    path?: string | null;
+    icon?: string | null;
+    sort?: number;
+    hidden?: boolean;
+    permissions?: Permission[] | null;
+    children?: MenuRegisterInput[];
+}
+export interface SettingsTabInput {
+    id: string;
+    title: string;
+    path: string;
+    permission?: Permission;
+    sort?: number;
+}
+export interface RoutePermissionInput {
+    path: string;
+    permission: Permission | null;
+}
+export interface MenuRegistry {
+    register(input: MenuRegisterInput): void;
+    getTree(): AdminMenuItem[];
+}
+export interface SettingsRegistry {
+    registerTab(input: SettingsTabInput): void;
+    getTabs(): SettingsTabInput[];
+}
+export interface PermissionRegistry {
+    register(perms: Permission[]): void;
+    getAll(): Permission[];
+}
+export interface RouteRegistry {
+    registerRoute(input: RoutePermissionInput): void;
+    getRoutePermissions(): RoutePermissionInput[];
+}
+export interface AdminContext {
+    menu: MenuRegistry;
+    settings: SettingsRegistry;
+    permissions: PermissionRegistry;
+    routes: RouteRegistry;
+}
+export interface AdminModule {
+    id: string;
+    register(ctx: AdminContext): void;
+}
+export declare function createAdminRegistry(): AdminContext;
+export declare function filterMenuByPermissions(nodes: AdminMenuItem[], granted: Set<string>): AdminMenuItem[];

package/dist/plugin/admin/registry.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdminRegistry = createAdminRegistry;
+exports.filterMenuByPermissions = filterMenuByPermissions;
+function normalizeMenuInput(input) {
+    const hasChildren = Boolean(input.children?.length);
+    return {
+        id: input.id,
+        kind: hasChildren && !input.path ? 'group' : 'item',
+        title: input.title,
+        path: input.path ?? (hasChildren ? null : '/'),
+        icon: input.icon ?? null,
+        sort: input.sort ?? 0,
+        hidden: input.hidden ?? false,
+        permissions: input.permissions ?? null,
+        children: input.children?.map(normalizeMenuInput),
+    };
+}
+function createAdminRegistry() {
+    const menuItems = [];
+    const settingsTabs = [];
+    const permissions = new Set();
+    const routePermissions = [];
+    const menu = {
+        register(input) {
+            menuItems.push(normalizeMenuInput(input));
+        },
+        getTree() {
+            return [...menuItems].sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0));
+        },
+    };
+    const settings = {
+        registerTab(input) {
+            settingsTabs.push(input);
+        },
+        getTabs() {
+            return [...settingsTabs].sort((a, b) => (a.sort ?? 0) - (b.sort ?? 0));
+        },
+    };
+    const permissionRegistry = {
+        register(perms) {
+            for (const p of perms)
+                permissions.add(p);
+        },
+        getAll() {
+            return [...permissions];
+        },
+    };
+    const routes = {
+        registerRoute(input) {
+            routePermissions.push(input);
+        },
+        getRoutePermissions() {
+            return routePermissions;
+        },
+    };
+    return { menu, settings, permissions: permissionRegistry, routes };
+}
+function filterMenuByPermissions(nodes, granted) {
+    const can = (required) => {
+        if (!required?.length)
+            return true;
+        return required.every((p) => granted.has(p));
+    };
+    const walk = (list) => list
+        .map((node) => {
+        if (!can(node.permissions))
+            return null;
+        if (node.children?.length) {
+            const children = walk(node.children);
+            if (children.length === 0)
+                return null;
+            return { ...node, children };
+        }
+        return node;
+    })
+        .filter((n) => n != null);
+    return walk(nodes);
+}

package/dist/plugin/admin/slots.d.ts

@@ -0,0 +1,36 @@
+/** Built-in admin UI slot identifiers. Plugins register React components against these ids. */
+export declare const AdminSlotIds: {
+    /** 文章编辑器 · 摘要面板下方（SEO、自定义 meta 等） */
+    readonly ARTICLE_EDITOR_META_AFTER_SUMMARY: "article.editor.meta.afterSummary";
+    /** 文章编辑器 · 右侧发布框下方 */
+    readonly ARTICLE_EDITOR_SIDEBAR_AFTER_PUBLISH: "article.editor.sidebar.afterPublish";
+};
+export type AdminSlotId = (typeof AdminSlotIds)[keyof typeof AdminSlotIds];
+/** All built-in slot ids — used for manifest validation and JSON Schema enum. */
+export declare const ALL_ADMIN_SLOT_IDS: readonly AdminSlotId[];
+export declare function isAdminSlotId(value: string): value is AdminSlotId;
+export interface AdminSlotDefinition {
+    id: AdminSlotId;
+    /** Human-readable label for plugin authors / docs */
+    title: string;
+    /** Core module that owns the host surface */
+    module: string;
+    description?: string;
+}
+/** Draft fields exposed to article editor slots. Host pages may extend via `context`. */
+export interface ArticleEditorDraftFields {
+    title: string;
+    summary: string;
+    slug: string;
+    seoKeywords: string;
+    seoDescription: string;
+    status: 'draft' | 'publish';
+}
+/** Context passed to `article.editor.*` slot components from the article editor page. */
+export interface ArticleEditorAdminSlotContext {
+    articleId?: string;
+    draft: ArticleEditorDraftFields;
+    patch: <K extends keyof ArticleEditorDraftFields>(key: K, value: ArticleEditorDraftFields[K]) => void;
+    /** Host-provided i18n helper (typically `react-i18next` `t`). */
+    translate: (key: string) => string;
+}

package/dist/plugin/admin/slots.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_ADMIN_SLOT_IDS = exports.AdminSlotIds = void 0;
+exports.isAdminSlotId = isAdminSlotId;
+/** Built-in admin UI slot identifiers. Plugins register React components against these ids. */
+exports.AdminSlotIds = {
+    /** 文章编辑器 · 摘要面板下方（SEO、自定义 meta 等） */
+    ARTICLE_EDITOR_META_AFTER_SUMMARY: 'article.editor.meta.afterSummary',
+    /** 文章编辑器 · 右侧发布框下方 */
+    ARTICLE_EDITOR_SIDEBAR_AFTER_PUBLISH: 'article.editor.sidebar.afterPublish',
+};
+/** All built-in slot ids — used for manifest validation and JSON Schema enum. */
+exports.ALL_ADMIN_SLOT_IDS = Object.values(exports.AdminSlotIds);
+function isAdminSlotId(value) {
+    return exports.ALL_ADMIN_SLOT_IDS.includes(value);
+}