@aphexcms/cms-core 9.3.0 → 9.5.0

package/dist/field-validation/utils.js

@@ -18,6 +18,69 @@ export function isFieldRequired(field) {
         return false;
     }
 }
+function describeValue(value) {
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'object')
+        return 'an object';
+    return `a ${typeof value}`;
+}
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Structural (shape) validation for a field's stored value — the depth=0 write
+ * shape. This catches a caller (notably an AI agent over MCP) sending the wrong
+ * JSON shape that presence/required checks would miss: a slug as `{ current }`
+ * (Sanity's convention — AphexCMS stores slugs as plain strings), or a
+ * reference/image missing its `_ref`. Runs before the user's Rule validation
+ * and only when a value is meaningfully present (absent/empty is a required-ness
+ * concern, handled separately), so optional and half-filled fields are left
+ * alone. Returns an error message, or null when the shape is acceptable.
+ *
+ * Intentionally conservative: only unambiguous mismatches error, and empty
+ * placeholders (`''`, an image with no `asset`) are treated as absent so the
+ * admin's in-progress edit states don't trip it.
+ */
+export function validateValueShape(field, value) {
+    // Absent (or an empty-string placeholder for a non-string field) → shape is
+    // irrelevant here; presence is enforced by Rule().required().
+    if (value === null || value === undefined)
+        return null;
+    switch (field.type) {
+        case 'string':
+        case 'text':
+        case 'slug':
+        case 'url':
+            return typeof value === 'string' ? null : `expected a string, got ${describeValue(value)}`;
+        case 'reference':
+            if (value === '')
+                return null;
+            return isPlainObject(value) && typeof value._ref === 'string'
+                ? null
+                : `expected a reference object { _type: 'reference', _ref: '<documentId>' }, got ${describeValue(value)}`;
+        case 'image':
+        case 'file': {
+            if (value === '')
+                return null;
+            if (!isPlainObject(value))
+                return `expected an ${field.type} object { _type: '${field.type}', asset: { _type: 'reference', _ref: '<assetId>' } }, got ${describeValue(value)}`;
+            // An object with no asset yet is a valid empty/in-progress state.
+            if (value.asset === undefined || value.asset === null)
+                return null;
+            return isPlainObject(value.asset) && typeof value.asset._ref === 'string'
+                ? null
+                : `${field.type} asset must be { _type: 'reference', _ref: '<assetId>' }`;
+        }
+        case 'array':
+            return Array.isArray(value) ? null : `expected an array, got ${describeValue(value)}`;
+        case 'object':
+            return isPlainObject(value) ? null : `expected an object, got ${describeValue(value)}`;
+        default:
+            // number/boolean/date/datetime — left to existing auto-rules / user rules.
+            return null;
+    }
+}
 /**
  * Validate a field value against its validation rules
  */
@@ -28,6 +91,17 @@ export async function validateField(field, value, context = {}) {
         hasValidation: !!field.validation
     });
     const allErrors = [];
+    // Structural shape check first: if the value is the wrong JSON shape (e.g. a
+    // slug sent as `{ current }`, or a reference without `_ref`), report that and
+    // stop — the type-assuming auto-rules and user rules below expect the correct
+    // primitive/shape and would otherwise throw or emit confusing errors.
+    const shapeError = validateValueShape(field, value);
+    if (shapeError) {
+        return {
+            isValid: false,
+            errors: [{ level: 'error', message: `Field "${field.name}" ${shapeError}` }]
+        };
+    }
     // Add automatic validation for date/datetime/url fields based on type
     if (field.type === 'date') {
         const dateField = field;

package/dist/graphql/resolvers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../../src/lib/graphql/resolvers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAS,MAAM,kBAAkB,CAAC;AA4H1D,wBAAgB,eAAe,CAC9B,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,UAAU,EAAE,EACzB,kBAAkB,GAAE,OAAO,GAAG,WAAyB,uBA2tBvD"}
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../../src/lib/graphql/resolvers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAS,MAAM,kBAAkB,CAAC;AAyH1D,wBAAgB,eAAe,CAC9B,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,UAAU,EAAE,EACzB,kBAAkB,GAAE,OAAO,GAAG,WAAyB,uBA4tBvD"}

package/dist/graphql/resolvers.js

@@ -2,9 +2,7 @@ import { GraphQLError } from 'graphql';
 import { authToContext } from '../local-api/auth-helpers.js';
 import { getDefaultValueForFieldType } from '../utils/field-defaults.js';
 import { cmsLogger } from '../utils/logger.js';
-function capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
-}
+import { toPascalCase, toCamelCase } from '../utils/string-case.js';
 // Normalize null/undefined field values to type-appropriate defaults (recursive)
 function normalizeDocumentFields(data, schemaType, allSchemaTypes) {
     if (!data)
@@ -130,7 +128,7 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
     // Generate reference field resolvers for all types
     function generateReferenceFieldResolvers() {
         schemaTypes.forEach((schemaType) => {
-            const typeName = capitalizeFirst(schemaType.name);
+            const typeName = toPascalCase(schemaType.name);
             function processFields(fields, currentTypeName) {
                 fields.forEach((field) => {
                     // Handle reference fields
@@ -244,7 +242,7 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
                     }
                     // Handle nested objects
                     if (field.type === 'object' && field.fields) {
-                        const nestedTypeName = capitalizeFirst(`${schemaType.name}${field.name}Object`);
+                        const nestedTypeName = toPascalCase(`${schemaType.name}${field.name}Object`);
                         processFields(field.fields, nestedTypeName);
                     }
                 });
@@ -262,11 +260,11 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
                     if (field.type === 'array' && field.of && field.of.length > 1) {
                         const validTypes = field.of.filter((item) => schemaTypes.find((s) => s.name === item.type));
                         if (validTypes.length > 1) {
-                            const unionName = `${capitalizeFirst(parentName)}${capitalizeFirst(field.name)}Item`;
+                            const unionName = `${toPascalCase(parentName)}${toPascalCase(field.name)}Item`;
                             resolvers[unionName] = {
                                 __resolveType(obj) {
                                     if (obj._type) {
-                                        return capitalizeFirst(obj._type);
+                                        return toPascalCase(obj._type);
                                     }
                                     return null;
                                 }
@@ -286,7 +284,8 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
     // Generate resolvers for each document type
     const documentTypes = schemaTypes.filter((type) => type.type === 'document');
     documentTypes.forEach((schemaType) => {
-        const typeName = capitalizeFirst(schemaType.name);
+        const typeName = toPascalCase(schemaType.name);
+        const fieldName = toCamelCase(schemaType.name);
         // Singleton resolvers: no-arg query, no-id mutations.
         // Schema/codegen already differs for singletons (see schema.ts) — the
         // resolver just delegates to the singleton-aware CollectionAPI methods.
@@ -306,7 +305,7 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
                     ...normalizedData
                 };
             };
-            resolvers.Query[schemaType.name] = async (_, args, context) => {
+            resolvers.Query[fieldName] = async (_, args, context) => {
                 try {
                     const { localAPI, auth } = context;
                     const apiContext = authToContext(auth);
@@ -404,7 +403,7 @@ export function createResolvers(cms, schemaTypes, defaultPerspective = 'publishe
             return; // skip the regular per-type resolvers below for singletons
         }
         // Single document resolver: page(id: "123", perspective: "draft")
-        resolvers.Query[schemaType.name] = async (_, args, context) => {
+        resolvers.Query[fieldName] = async (_, args, context) => {
             try {
                 const { localAPI, auth } = context;
                 const apiContext = authToContext(auth);

package/dist/graphql/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/lib/graphql/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAkD,MAAM,kBAAkB,CAAC;AA0YnG,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CA2FvE"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/lib/graphql/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAkD,MAAM,kBAAkB,CAAC;AAyYnG,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CA2FvE"}

package/dist/graphql/schema.js

@@ -1,6 +1,4 @@
-function capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
-}
+import { toPascalCase, toCamelCase } from '../utils/string-case.js';
 function generateGraphQLField(field, schemaTypes, parentName = '') {
     const nullability = isFieldRequired(field) ? '!' : '';
     const fieldType = getGraphQLType(field, schemaTypes, parentName);
@@ -44,7 +42,7 @@ function handleArrayField(field, schemaTypes, parentName = '') {
         const refItem = refItems[0];
         const to = refItem.to;
         if (to && to.length === 1) {
-            return `[${capitalizeFirst(to[0].type)}]`;
+            return `[${toPascalCase(to[0].type)}]`;
         }
         return '[JSON]';
     }
@@ -56,22 +54,22 @@ function handleArrayField(field, schemaTypes, parentName = '') {
     // If array contains only one type
     if (validTypes.length === 1) {
         const itemType = validTypes[0];
-        return `[${capitalizeFirst(itemType.type)}]`;
+        return `[${toPascalCase(itemType.type)}]`;
     }
     // For multiple types in array, create union type with parent prefix
-    const unionName = `${capitalizeFirst(parentName)}${capitalizeFirst(field.name)}Item`;
+    const unionName = `${toPascalCase(parentName)}${toPascalCase(field.name)}Item`;
     return `[${unionName}]`;
 }
 function handleObjectField(field, _schemaTypes, parentName = '') {
     if (field.fields && field.fields.length > 0) {
         // Inline object - create a unique type name with parent prefix
-        return capitalizeFirst(`${parentName}${field.name}Object`);
+        return toPascalCase(`${parentName}${field.name}Object`);
     }
     return 'String'; // JSON string fallback
 }
 function handleReferenceField(field) {
     if (field.to && field.to.length === 1) {
-        return capitalizeFirst(field.to[0].type);
+        return toPascalCase(field.to[0].type);
     }
     return 'String'; // ID reference for MVP
 }
@@ -82,7 +80,7 @@ function isFieldRequired(field) {
     return field.validation.toString().includes('required');
 }
 function generateObjectType(schemaType, allSchemaTypes) {
-    const typeName = capitalizeFirst(schemaType.name);
+    const typeName = toPascalCase(schemaType.name);
     const fields = schemaType.fields
         .map((field) => generateGraphQLField(field, allSchemaTypes, schemaType.name))
         .join('\n');
@@ -91,7 +89,7 @@ ${fields}
 }`;
 }
 function generateDocumentType(schemaType, allSchemaTypes) {
-    const typeName = capitalizeFirst(schemaType.name);
+    const typeName = toPascalCase(schemaType.name);
     const customFields = schemaType.fields
         .map((field) => generateGraphQLField(field, allSchemaTypes, schemaType.name))
         .join('\n');
@@ -111,7 +109,7 @@ function generateInlineObjectTypes(schemaTypes) {
         fields.forEach((field) => {
             if (field.type === 'object' && field.fields) {
                 const objectField = field;
-                const typeName = capitalizeFirst(`${parentName}${field.name}Object`);
+                const typeName = toPascalCase(`${parentName}${field.name}Object`);
                 const fieldDefs = objectField.fields
                     .map((f) => generateGraphQLField(f, schemaTypes, `${parentName}${field.name}`))
                     .join('\n');
@@ -127,8 +125,8 @@ ${fieldDefs}
                     // Only create union for types that exist in schemaTypes
                     const validTypes = arrayField.of.filter((item) => schemaTypes.find((s) => s.name === item.type));
                     if (validTypes.length > 1) {
-                        const unionName = `${capitalizeFirst(parentName)}${capitalizeFirst(field.name)}Item`;
-                        const unionTypes = validTypes.map((item) => capitalizeFirst(item.type)).join(' | ');
+                        const unionName = `${toPascalCase(parentName)}${toPascalCase(field.name)}Item`;
+                        const unionTypes = validTypes.map((item) => toPascalCase(item.type)).join(' | ');
                         inlineTypes.push(`union ${unionName} = ${unionTypes}`);
                     }
                 }
@@ -186,7 +184,7 @@ input IDFilter {
 }
 // Generate where input type for a specific document type
 function generateWhereInputType(schemaType, _allSchemaTypes) {
-    const typeName = capitalizeFirst(schemaType.name);
+    const typeName = toPascalCase(schemaType.name);
     const whereTypeName = `${typeName}WhereInput`;
     // Generate field filters
     const fieldFilters = [];
@@ -223,7 +221,7 @@ function getFilterType(field) {
 }
 // Generate data input type for mutations
 function generateDataInputType(schemaType, allSchemaTypes) {
-    const typeName = capitalizeFirst(schemaType.name);
+    const typeName = toPascalCase(schemaType.name);
     const inputTypeName = `${typeName}DataInput`;
     const fields = [];
     schemaType.fields.forEach((field) => {
@@ -268,16 +266,17 @@ function generateQueryFields(schemaTypes) {
     const documentTypes = schemaTypes.filter((type) => type.type === 'document');
     return documentTypes
         .map((schemaType) => {
-        const typeName = capitalizeFirst(schemaType.name);
+        const typeName = toPascalCase(schemaType.name);
         // Singletons resolve to a single canonical row — no id arg, no
         // `all` query. Lazy-creates on first access via the resolver.
+        const fieldName = toCamelCase(schemaType.name);
         if (schemaType.singleton) {
             return `  # Get the ${schemaType.name} singleton (lazy-creates an empty draft on first access)
-  ${schemaType.name}(perspective: String, depth: Int): ${typeName}!`;
+  ${fieldName}(perspective: String, depth: Int): ${typeName}!`;
         }
         const whereInputType = `${typeName}WhereInput`;
         return `  # Get a single ${schemaType.name} by ID
-  ${schemaType.name}(id: ID!, perspective: String, depth: Int): ${typeName}
+  ${fieldName}(id: ID!, perspective: String, depth: Int): ${typeName}
 
   # Get all ${schemaType.name} documents with filtering
   all${typeName}(
@@ -295,7 +294,7 @@ function generateMutationFields(schemaTypes) {
     const documentTypes = schemaTypes.filter((type) => type.type === 'document');
     return documentTypes
         .map((schemaType) => {
-        const typeName = capitalizeFirst(schemaType.name);
+        const typeName = toPascalCase(schemaType.name);
         const dataInputType = `${typeName}DataInput`;
         // Singletons skip create/delete/all: there's only ever one row, with
         // a deterministic id, so update/publish/unpublish operate on it

package/dist/hooks.d.ts

@@ -9,8 +9,10 @@ import type { AuthProvider } from './auth/provider.js';
 import type { GraphQLSettings } from './graphql/index.js';
 import type { Logger } from './utils/logger.js';
 import { RolesService } from './services/roles-service.js';
+import { PluginSettingsService } from './services/plugin-settings-service.js';
 import { CMSEngine } from './engine.js';
 import { type LocalAPI } from './local-api/index.js';
+import { type PartResolver } from './plugins/resolver.js';
 import { type AphexEnv } from './server/api/index.js';
 export interface CMSInstances {
     config: CMSConfig;
@@ -21,10 +23,14 @@ export interface CMSInstances {
     cmsEngine: CMSEngine;
     localAPI: LocalAPI;
     rolesService: RolesService;
+    /** Per-(org, plugin) settings store — the config plane for plugins. */
+    pluginSettingsService: PluginSettingsService;
     logger: Logger;
     auth?: AuthProvider;
     graphqlSettings?: GraphQLSettings | null;
     apiApp: Hono<AphexEnv>;
+    /** Indexed plugin parts (routes, document actions, admin tools, field components). */
+    partResolver: PartResolver;
 }
 /**
  * Called by the Vite HMR plugin (`@aphexcms/cms-core/vite`) when schema

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/lib/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAK7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAa,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAIN,KAAK,QAAQ,EACb,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;CACvB;AAQD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAGrE;AAgBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA0JvD"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/lib/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAO7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAa,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAIN,KAAK,QAAQ,EACb,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAC3B,uEAAuE;IACvE,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvB,sFAAsF;IACtF,YAAY,EAAE,YAAY,CAAC;CAC3B;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAGrE;AAgBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAmMvD"}

package/dist/hooks.js

@@ -1,11 +1,35 @@
 import { handleAuthHook } from './auth/auth-hooks.js';
+import { getPreviewPerspective } from './preview/perspective.js';
+import { resolveCapabilities } from './types/capabilities.js';
 import { cmsLogger, setLogLevel, setLogger } from './utils/logger.js';
 import { createStorageAdapter as createStorageAdapterProvider } from './storage/providers/storage.js';
 import { AssetService as AssetServiceClass } from './services/asset-service.js';
 import { RolesService } from './services/roles-service.js';
+import { PluginSettingsService } from './services/plugin-settings-service.js';
 import { createCMS } from './engine.js';
 import { createLocalAPI } from './local-api/index.js';
+import { createPartResolver } from './plugins/resolver.js';
 import { createAphexApi, mountAphexBuiltins, toHonoHandler } from './server/api/index.js';
+/**
+ * Wrap a plugin route handler so it enforces `requiredCapabilities` before running.
+ * 401 when there's no authenticated principal at all; 403 when authenticated but
+ * missing a required capability. Uses the same server-resolved capability set every
+ * core resource checks — the client can't forge it.
+ */
+function gateHandler(handler, required) {
+    return (c) => {
+        const auth = c.var.auth;
+        if (!auth || auth.type === 'partial_session') {
+            return c.json({ success: false, error: 'Authentication required' }, 401);
+        }
+        const caps = resolveCapabilities(auth);
+        const missing = required.filter((cap) => !caps.has(cap));
+        if (missing.length > 0) {
+            return c.json({ success: false, error: 'Insufficient permissions', missingCapabilities: missing }, 403);
+        }
+        return handler(c);
+    };
+}
 let cmsInstances = null;
 let schemaError = null;
 let initPromise = null;
@@ -89,8 +113,28 @@ export function createCMSHook(config) {
             // Build the Hono API app shell. User middleware/overrides register
             // FIRST (so they sit ahead of built-ins in the chain), then we mount
             // the built-in routes, then GraphQL.
+            // Index plugin parts (validates duplicate part ids). Mount plugin server
+            // routes after the user's `api` hook and before built-ins, so a plugin's
+            // `POST /bookings` becomes `POST /api/bookings`, overridable by the app.
+            const partResolver = createPartResolver(currentConfig.plugins ?? []);
+            // Per-(org, plugin) config store — merges declared defaults with stored
+            // values and writes edits back, scoped to the org. The encryption key gates
+            // `secret` fields (absent → secrets disabled, fail safe).
+            const pluginSettingsService = new PluginSettingsService(databaseAdapter, partResolver, currentConfig.security?.secretEncryptionKey ?? null);
             const apiApp = createAphexApi();
             currentConfig.api?.(apiApp);
+            for (const route of partResolver.serverRoutes()) {
+                // Gate every plugin route by its declared `requiredCapabilities` before the
+                // handler runs, so a declared capability is ENFORCED rather than merely
+                // documented. `'public'` is the single ungated path and the author had to
+                // write it: an empty list still requires authentication, and omitting the
+                // field entirely doesn't type-check. Ungated is therefore always a choice,
+                // never an oversight.
+                const handler = route.requiredCapabilities === 'public'
+                    ? route.handler
+                    : gateHandler(route.handler, route.requiredCapabilities);
+                apiApp.on(route.method, route.path, handler);
+            }
             mountAphexBuiltins(apiApp);
             // Initialize schemas with validation
             try {
@@ -115,9 +159,11 @@ export function createCMSHook(config) {
                         cmsEngine,
                         localAPI,
                         rolesService,
+                        pluginSettingsService,
                         logger: cmsLogger,
                         auth: currentConfig.auth?.provider,
-                        apiApp
+                        apiApp,
+                        partResolver
                     }, currentConfig.schemaTypes, graphqlConfig);
                     // Register GraphQL directly on the Hono app. The Yoga handler
                     // internally distinguishes GET (GraphiQL UI) from POST (queries),
@@ -147,10 +193,12 @@ export function createCMSHook(config) {
                 cmsEngine: cmsEngine,
                 localAPI: localAPI,
                 rolesService,
+                pluginSettingsService,
                 logger: cmsLogger,
                 auth: currentConfig.auth?.provider,
                 graphqlSettings,
-                apiApp
+                apiApp,
+                partResolver
             };
             resolveInit();
         }
@@ -166,6 +214,15 @@ export function createCMSHook(config) {
             if (authResponse)
                 return authResponse;
         }
+        // Resolve the read perspective once per request so site loads inherit it
+        // (published normally / draft in an authenticated `?aphex-preview` session)
+        // via `locals.previewPerspective` — no per-load wiring. Apps can override the
+        // policy with `config.preview.resolvePerspective`.
+        event.locals.previewPerspective =
+            currentConfig.preview?.resolvePerspective?.({
+                auth: event.locals.auth,
+                url: event.url
+            }) ?? getPreviewPerspective(event.locals.auth, event.url);
         return resolve(event);
     };
 }

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './field-validation/rule.js';
 export * from './field-validation/utils.js';
 export { createContentHash, hasUnpublishedChanges } from './utils/content-hash.js';
 export * from './schema-utils/index.js';
+export * from './theme/index.js';
+export * from './plugins/index.js';
 export * from './utils/index.js';
 export * from './api/index.js';
 export type { ApiResponse } from './api/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAkBA,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGjG,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAGzC,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAkBA,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGjG,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAGzC,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAI9B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,eAAe,CAAC;AAG9B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -23,6 +23,11 @@ export * from './field-validation/utils.js';
 export { createContentHash, hasUnpublishedChanges } from './utils/content-hash.js';
 // Schema utilities
 export * from './schema-utils/index.js';
+// Theme design-system tokens — plain TS (Svelte-free), safe for the universal barrel.
+export * from './theme/index.js';
+// Plugin API — definePlugin(), part types, part resolver. Runtime is plain JS
+// (svelte/hono imports are type-only), so it's safe on both server and client.
+export * from './plugins/index.js';
 // General utility functions (logger, image URL builder, etc)
 export * from './utils/index.js';
 // Unified API client

package/dist/lib/admin/block-previews.svelte.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Rich-text block preview registry (client-side context).
+ *
+ * By default a custom Portable Text block renders in the editor as a generic card
+ * (title/subtitle from its `preview` config). That's fine for data-ish blocks, but for
+ * visual ones — an embed, a gallery, a button — authors expect to see the real thing
+ * inline while writing (the Ghost/Sanity "what you see is what you get" editor).
+ *
+ * An app registers a preview per block `_type`; RichtextField resolves it and the
+ * ProseMirror node view mounts it INSTEAD of the generic card. The preview still gets
+ * `onEdit`/`onDelete` so the block stays editable and removable.
+ *
+ * Deliberately separate from the field-component registry: that one supplies *inputs*
+ * (`field`/`value`/`onUpdate`); this one supplies *renderers* (`data`/`onEdit`). Same
+ * idea, different contract.
+ */
+import { type Component } from 'svelte';
+import type { PreviewSource } from '../utils/preview.js';
+/**
+ * The stable props a block preview component receives.
+ *
+ * Also the contract for core's own built-in views (the generic card and the image
+ * view), so all three are mountable by the node view through one type.
+ */
+export interface BlockPreviewProps {
+    /** The block's `_type`. */
+    type: string;
+    /** The block's `_key` — its stable identity within the field's array. */
+    nodeKey: string;
+    /** The block's stored data (its fields). */
+    data: Record<string, unknown>;
+    /** The block type's schema, for reading its `preview` config if useful. */
+    schema?: PreviewSource;
+    /** True while the block is selected in the editor. */
+    selected?: boolean;
+    /** Open the block's edit modal — wire this to a click/edit affordance. */
+    onEdit: () => void;
+    /** Remove the block. */
+    onDelete: () => void;
+}
+export type BlockPreviewLookup = (type: string) => Component<BlockPreviewProps> | undefined;
+/** Publish the block-preview lookup to descendants (call in the admin shell). */
+export declare function setBlockPreviews(lookup: BlockPreviewLookup): void;
+/** Resolve the lookup. Returns a no-op lookup outside the admin shell. */
+export declare function useBlockPreviews(): BlockPreviewLookup;
+//# sourceMappingURL=block-previews.svelte.d.ts.map

package/dist/lib/admin/block-previews.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-previews.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/admin/block-previews.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;AAI5F,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAEjE;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,kBAAkB,CAErD"}

package/dist/lib/admin/block-previews.svelte.js

@@ -0,0 +1,27 @@
+/**
+ * Rich-text block preview registry (client-side context).
+ *
+ * By default a custom Portable Text block renders in the editor as a generic card
+ * (title/subtitle from its `preview` config). That's fine for data-ish blocks, but for
+ * visual ones — an embed, a gallery, a button — authors expect to see the real thing
+ * inline while writing (the Ghost/Sanity "what you see is what you get" editor).
+ *
+ * An app registers a preview per block `_type`; RichtextField resolves it and the
+ * ProseMirror node view mounts it INSTEAD of the generic card. The preview still gets
+ * `onEdit`/`onDelete` so the block stays editable and removable.
+ *
+ * Deliberately separate from the field-component registry: that one supplies *inputs*
+ * (`field`/`value`/`onUpdate`); this one supplies *renderers* (`data`/`onEdit`). Same
+ * idea, different contract.
+ */
+import { getContext, setContext } from 'svelte';
+const BLOCK_PREVIEWS_KEY = Symbol.for('aphex.admin.block-previews');
+/** Publish the block-preview lookup to descendants (call in the admin shell). */
+export function setBlockPreviews(lookup) {
+    setContext(BLOCK_PREVIEWS_KEY, lookup);
+}
+/** Resolve the lookup. Returns a no-op lookup outside the admin shell. */
+export function useBlockPreviews() {
+    return getContext(BLOCK_PREVIEWS_KEY) ?? (() => undefined);
+}
+//# sourceMappingURL=block-previews.svelte.js.map

package/dist/lib/admin/block-previews.svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-previews.svelte.js","sourceRoot":"","sources":["../../../src/lib/admin/block-previews.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAkB,MAAM,QAAQ,CAAC;AA4BhE,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAEpE,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,MAA0B;IAC1D,UAAU,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB;IAC/B,OAAO,UAAU,CAAiC,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAC5F,CAAC"}

package/dist/lib/admin/field-components.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Field-input widget registry (client-side context).
+ *
+ * Plugins contribute custom input widgets via `aphex/field/component` parts, keyed
+ * by an `input` string. A field opts into one with `{ …, input: 'color' }`.
+ * The admin shell publishes a lookup here; SchemaField (however deeply nested)
+ * resolves the widget and renders it in place of the built-in for that field type.
+ */
+import { type Component } from 'svelte';
+import type { FieldComponentProps } from '../plugins/types.js';
+export type FieldComponentLookup = (input: string) => Component<FieldComponentProps> | undefined;
+/** Publish the widget lookup to descendants (call in the admin shell). */
+export declare function setFieldComponents(lookup: FieldComponentLookup): void;
+/** Resolve the widget lookup. Returns a no-op lookup outside the admin shell. */
+export declare function useFieldComponents(): FieldComponentLookup;
+//# sourceMappingURL=field-components.svelte.d.ts.map

package/dist/lib/admin/field-components.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-components.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/admin/field-components.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC,mBAAmB,CAAC,GAAG,SAAS,CAAC;AAIjG,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAErE;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,IAAI,oBAAoB,CAEzD"}

package/dist/lib/admin/field-components.svelte.js

@@ -0,0 +1,19 @@
+/**
+ * Field-input widget registry (client-side context).
+ *
+ * Plugins contribute custom input widgets via `aphex/field/component` parts, keyed
+ * by an `input` string. A field opts into one with `{ …, input: 'color' }`.
+ * The admin shell publishes a lookup here; SchemaField (however deeply nested)
+ * resolves the widget and renders it in place of the built-in for that field type.
+ */
+import { getContext, setContext } from 'svelte';
+const FIELD_COMPONENTS_KEY = Symbol.for('aphex.admin.field-components');
+/** Publish the widget lookup to descendants (call in the admin shell). */
+export function setFieldComponents(lookup) {
+    setContext(FIELD_COMPONENTS_KEY, lookup);
+}
+/** Resolve the widget lookup. Returns a no-op lookup outside the admin shell. */
+export function useFieldComponents() {
+    return getContext(FIELD_COMPONENTS_KEY) ?? (() => undefined);
+}
+//# sourceMappingURL=field-components.svelte.js.map

package/dist/lib/admin/field-components.svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-components.svelte.js","sourceRoot":"","sources":["../../../src/lib/admin/field-components.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAkB,MAAM,QAAQ,CAAC;AAKhE,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AAExE,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAAC,MAA4B;IAC9D,UAAU,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB;IACjC,OAAO,UAAU,CAAmC,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAChG,CAAC"}

package/dist/lib/admin/nav.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { AdminArea } from './types.js';
+/** The known admin URL params. Central list so intents never typo a key. */
+export type AdminParam = 'view' | 'docType' | 'docId' | 'action' | 'stack' | 'history' | 'focus' | 'orgId' | 'fromDocId' | 'fromDocType';
+/** A set of param changes: a value sets the key, `null` clears it. */
+export type ParamPatch = Partial<Record<AdminParam, string | null>>;
+export interface AdminNav {
+    /** Apply a param patch and navigate. `replace` defaults to true. */
+    patch(changes: ParamPatch, opts?: {
+        replace?: boolean;
+    }): Promise<void>;
+    /** Switch the top-level area/tab. `structure` clears `?view`; others set it. */
+    openArea(area: AdminArea): Promise<void>;
+    /** Show a document type's list (structure area). */
+    openType(docType: string): Promise<void>;
+    /**
+     * Open a document in the editor (structure area). `docType` is optional — when
+     * omitted the existing `?docType` is preserved (the URL effect resolves it).
+     */
+    openDocument(docId: string, docType?: string, opts?: {
+        replace?: boolean;
+    }): Promise<void>;
+    /** Start creating a new document of a type. */
+    createDocument(docType: string): Promise<void>;
+    /** Close the current document, back to its type's list. */
+    closeToType(docType: string): Promise<void>;
+    /** Back to the dashboard (no type, no doc). */
+    goHome(): Promise<void>;
+}
+/** Create an admin nav and publish it to descendants (call once in the shell). */
+export declare function setAdminNav(basePath?: string): AdminNav;
+/** Read the admin nav. `undefined` outside the admin shell (safe to guard). */
+export declare function useAdminNav(): AdminNav | undefined;
+export declare function createAdminNav(basePath?: string): AdminNav;
+//# sourceMappingURL=nav.svelte.d.ts.map

package/dist/lib/admin/nav.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/admin/nav.svelte.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GACnB,MAAM,GACN,SAAS,GACT,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,OAAO,GACP,OAAO,GACP,WAAW,GACX,aAAa,CAAC;AAEjB,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;AAEpE,MAAM,WAAW,QAAQ;IACxB,oEAAoE;IACpE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3F,+CAA+C;IAC/C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,2DAA2D;IAC3D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,+CAA+C;IAC/C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,QAAQ,SAAW,GAAG,QAAQ,CAIzD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,IAAI,QAAQ,GAAG,SAAS,CAElD;AAED,wBAAgB,cAAc,CAAC,QAAQ,SAAW,GAAG,QAAQ,CAgE5D"}