@riducms/plugin 0.1.4 → 0.2.0

package/src/plugin.ts

@@ -1,4 +1,6 @@
-import type { FieldPlugin } from "./field";
+import type { FieldType } from "@riducms/protocol";
+import type { RegisteredPluginField } from "./field";
+import { resolvePluginFields, type ResolvedPluginField } from "./plugin-registry";
 import { ADMIN_PLUGIN_API_VERSION } from "@riducms/protocol";
 import type {
 	OperationCapabilities,
@@ -10,32 +12,64 @@ import type {
 import type { Component, Snippet } from "svelte";
 
 import type { FieldDocument } from "./authoring";
-import type { AdminI18n, PluginMessageCatalog, PluginTranslationKey } from "./i18n";
+import type { AdminI18n, PluginMessageCatalog, ExtensionTranslationKey } from "./i18n";
 import { freezeAdminMessages, validateAdminMessages } from "./i18n";
 import type { RowLabelPlugin } from "./row-label";
 
 export { ADMIN_PLUGIN_API_VERSION };
 
 /**
- * Describes the admin half exported by a statically installed plugin package.
- * Pairing versions are plugin-owned and must change when its Go and admin
- * halves are no longer mutually compatible.
+ * The browser UI supplied by an installed Go/admin plugin pair.
+ * Create this with `defineAdminPlugin` from `@riducms/plugin/authoring/v1`,
+ * which supplies the framework API version. Go declares the plugin's server
+ * behaviour; this object connects its fields and other admin UI components.
  */
-export interface AdminPlugin {
-	/** Framework admin-plugin contract version compiled by this package. */
+export interface AdminPlugin extends AdminContributions {
+	/** Supplied by the versioned authoring import. Authors must not set this themselves. */
 	apiVersion: typeof ADMIN_PLUGIN_API_VERSION;
-	/** Stable key matching the compiled Go plugin. */
+	/** Owning Go plugin's key, for example `"editorial-tools"`; not necessarily a field-type key. */
 	key: string;
-	/** Plugin-owned backend/admin compatibility version. */
+	/** Positive integer matching the Go descriptor; bump it when the two halves become incompatible. */
 	pairingVersion: number;
-	/** Field renderers contributed by this package. */
-	fields: readonly FieldPlugin[];
+	/**
+	 * Default editors for field types declared by this Go plugin. Each map key is a
+	 * globally unique field-type name; each value comes from `definePluginField`.
+	 * For example, one plugin may provide both `"review-note"` and `"color-swatch"`.
+	 */
+	fields?: Readonly<
+		Record<string, RegisteredPluginField & { readonly type: "plugin"; readonly fieldType?: never }>
+	>;
+	/**
+	 * Alternative editors made with `defineFieldComponent`, keyed by component name.
+	 * Go chooses one with `.Admin(field.Admin{Editor: field.PluginComponent(pluginKey, componentName, config)})`.
+	 * These may edit built-in fields or an explicitly named plugin field type.
+	 */
+	components?: Readonly<
+		Record<
+			string,
+			RegisteredPluginField &
+				(
+					| { readonly type: Exclude<FieldType, "plugin"> }
+					| { readonly type: "plugin"; readonly fieldType: string }
+				)
+		>
+	>;
 	/** Array and blocks row-label components contributed by this package. */
 	rowLabels?: readonly RowLabelPlugin[];
 	/** Statically bundled, plugin-owned interface messages. */
 	messages?: PluginMessageCatalog;
+	/** Package-relative modules/styles to import at build time; must match the Go descriptor's list. */
+	assets?: readonly string[];
+}
+
+/**
+ * Places where a plugin or application can add admin UI. Arrays keep registration
+ * order; application entries follow plugin entries. Replacement slots allow one
+ * matching replacement. Conflicts are reported instead of silently overriding UI.
+ */
+export interface AdminContributions {
 	/** Authenticated admin routes contributed by this package. */
-	routes?: readonly AdminPluginRoute[];
+	routes?: readonly AdminRoute[];
 	/** Panels composed into or replacing the authenticated dashboard. */
 	dashboard?: readonly AdminDashboardPanel[];
 	/** Components composed around or replacing the sign-in screen. */
@@ -60,65 +94,77 @@ export interface AdminPlugin {
 	documentActions?: readonly AdminDocumentAction[];
 	/** Read-only or operational views rendered beside Edit and API. */
 	documentViews?: readonly AdminDocumentView[];
-	/** Package-relative static modules imported by the generated admin registry. */
-	assets?: readonly string[];
 }
 
+/** Common data supplied to admin extension components. Use the generated SDK for requests. */
 export interface AdminExtensionProps {
+	/** Resolved Go schema available to this admin session; it may omit inaccessible resources. */
 	manifest: SchemaManifest;
+	/** Signed-in user document, absent on screens where no user is signed in yet. */
 	user?: FieldDocument;
+	/** Current admin interface translations and formatting preferences. */
 	i18n: AdminI18n;
 }
 
+/** Sign-in operations provided to a custom login screen. */
 export interface AdminLoginExtensionHost {
-	/** Authenticates, evaluates admin access, and enters the authenticated shell. */
+	/** Sign in, check admin access and enter the admin. Rejects if authentication/access fails. */
 	login: (credentials: { email: string; password: string }) => Promise<void>;
+	/** Show a temporary success or error message. Does not perform an operation itself. */
 	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
 }
 
 export interface AdminLoginComponentProps extends AdminExtensionProps {
-	/** The complete framework sign-in screen, available to replacement wrappers. */
+	/** Render with `{@render defaultView()}` to keep Ridu's sign-in screen inside your wrapper. */
 	defaultView: Snippet;
 	host: AdminLoginExtensionHost;
 }
 
+/** Add content before/after sign-in, or replace it with a custom screen. */
 export interface AdminLoginComponent {
 	key: string;
 	component: Component<AdminLoginComponentProps>;
+	/** Defaults to after. Only one replace entry is allowed across plugins and the application. */
 	position?: "before" | "after" | "replace";
 }
 
 export type AdminAccountSurface = "profile" | "security";
 
+/** Operations for keeping a custom account screen in sync with the signed-in session. */
 export interface AdminAccountExtensionHost {
 	/** Reloads the signed-in document and updates the shell identity. */
 	refreshUser: () => Promise<FieldDocument | undefined>;
 	/** Ends the current session and returns to sign-in. */
 	logout: () => Promise<void>;
+	/** Show a temporary success or error message. */
 	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
 }
 
 export interface AdminAccountComponentProps extends AdminExtensionProps {
 	surface: AdminAccountSurface;
-	/** The complete framework account screen, available to replacement wrappers. */
+	/** Render with `{@render defaultView()}` to keep Ridu's account screen inside your wrapper. */
 	defaultView: Snippet;
 	host: AdminAccountExtensionHost;
 }
 
+/** Add to or replace the profile/security screen identified by `surface`. */
 export interface AdminAccountComponent {
 	key: string;
 	surface: AdminAccountSurface;
 	component: Component<AdminAccountComponentProps>;
+	/** Defaults to after. Each account surface permits at most one replacement. */
 	position?: "before" | "after" | "replace";
 }
 
+/** Choose the whole navigation's boundary, the resource-link list's boundary, or replace navigation. */
 export type AdminNavigationPosition = "before" | "beforeLinks" | "afterLinks" | "after" | "replace";
 
 export interface AdminNavigationComponentProps extends AdminExtensionProps {
-	/** The complete framework navigation, available to replacement wrappers. */
+	/** Render with `{@render defaultView()}` to include Ridu's navigation in a replacement. */
 	defaultView: Snippet;
 }
 
+/** Insert a component at a navigation position. At most one entry can replace navigation. */
 export interface AdminNavigationComponent {
 	key: string;
 	component: Component<AdminNavigationComponentProps>;
@@ -126,6 +172,7 @@ export interface AdminNavigationComponent {
 }
 
 export interface AdminLogoutExtensionHost {
+	/** End the current session and return to sign-in. Await this instead of only changing local UI. */
 	logout: () => Promise<void>;
 }
 
@@ -133,6 +180,7 @@ export interface AdminLogoutButtonProps extends AdminExtensionProps {
 	host: AdminLogoutExtensionHost;
 }
 
+/** Replace the account menu's sign-out button; call the supplied `host.logout()` on activation. */
 export interface AdminLogoutButton {
 	key: string;
 	component: Component<AdminLogoutButtonProps>;
@@ -141,9 +189,13 @@ export interface AdminLogoutButton {
 export type AdminCoreViewSurface =
 	"collectionList" | "collectionCreate" | "collectionEdit" | "global" | "notFound";
 
+/** Refresh tools for a custom collection/global screen. They do not save documents. */
 export interface AdminCoreViewHost {
+	/** Fetch the current Go schema again and update the admin's schema-dependent UI. */
 	refreshManifest: () => Promise<void>;
+	/** Notify Ridu that your code changed documents so dependent lists/lookups can refresh. */
 	documentsChanged: () => void;
+	/** Show a temporary success or error message. */
 	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
 }
 
@@ -152,7 +204,7 @@ export interface AdminCoreViewProps extends AdminExtensionProps {
 	collection?: SchemaCollection;
 	global?: SchemaGlobal;
 	documentID?: string;
-	/** The complete framework route, available to replacement wrappers. */
+	/** Render with `{@render defaultView()}` to wrap the normal screen rather than rebuilding it. */
 	defaultView: Snippet;
 	host: AdminCoreViewHost;
 }
@@ -179,6 +231,11 @@ interface AdminNotFoundCoreView {
 	component: Component<AdminCoreViewProps>;
 }
 
+/**
+ * Replace a collection/global/not-found screen. A resource-specific registration
+ * wins over an all-resources fallback for that surface; duplicate targets fail.
+ * The supplied `defaultView` lets your component wrap the existing screen.
+ */
 export type AdminCoreView = AdminCollectionCoreView | AdminGlobalCoreView | AdminNotFoundCoreView;
 
 export type AdminBrandSurface = "loginLogo" | "navigationLogo" | "accountAvatar";
@@ -187,6 +244,7 @@ export interface AdminBrandComponentProps extends AdminExtensionProps {
 	surface: AdminBrandSurface;
 }
 
+/** Replace one logo/avatar location. Only one component may claim each surface. */
 export interface AdminBrandComponent {
 	key: string;
 	surface: AdminBrandSurface;
@@ -199,6 +257,7 @@ export interface AdminShellComponentProps extends AdminExtensionProps {
 	position: AdminShellPosition;
 }
 
+/** Add UI to the global header, actions area or account settings menu in registration order. */
 export interface AdminShellComponent {
 	key: string;
 	position: AdminShellPosition;
@@ -206,11 +265,12 @@ export interface AdminShellComponent {
 }
 
 export interface AdminProviderProps {
-	/** The remaining provider stack and framework admin application. */
+	/** Render `{@render defaultView()}` after setting context so the nested providers/admin appear. */
 	defaultView: Snippet;
 	i18n: AdminI18n;
 }
 
+/** Wrap the admin in a Svelte context provider. Render the supplied `defaultView` to continue the UI. */
 export interface AdminProvider {
 	key: string;
 	component: Component<AdminProviderProps>;
@@ -222,38 +282,50 @@ export interface AdminDashboardPanelProps {
 	i18n: AdminI18n;
 }
 
+/** Add dashboard content before/after Ridu's overview, or replace that overview. */
 export interface AdminDashboardPanel {
-	/** Plugin-owned identity used for deterministic ordering and collision checks. */
+	/** Unique name among dashboard entries; duplicates throw. Array order controls display order. */
 	key: string;
 	component: Component<AdminDashboardPanelProps>;
-	/** Replace suppresses the framework overview and may only be registered once. */
+	/** Defaults to after. Replace hides Ridu's overview and may only be registered once. */
 	position?: "before" | "after" | "replace";
 }
 
+/** Data for displaying a collection table cell. This is not an editable document-form binding. */
 export interface AdminListCellProps {
 	collection: SchemaCollection;
 	field: SchemaField;
 	document: FieldDocument;
+	/** This field's saved value. Check its type before rendering; changing it does not save a document. */
 	value: unknown;
 	i18n: AdminI18n;
 }
 
+/** Replace the cell display for one collection/field pair; duplicate targets are rejected. */
 export interface AdminListCell {
 	key: string;
+	/** Collection slug, for example `"posts"`. */
 	collection: string;
+	/** Top-level field name/path in that collection, for example `"title"`. */
 	field: string;
+	/** Fallback column heading. */
 	label: string;
-	labelKey?: PluginTranslationKey;
+	/** Optional translation key from this plugin's messages, or app:... for application entries. */
+	labelKey?: ExtensionTranslationKey;
 	component: Component<AdminListCellProps>;
 }
 
 export type AdminExtensionNotificationTone = "success" | "error";
 
+/** Tools for a document action or extra document tab after it completes its own operation. */
 export interface AdminDocumentExtensionHost {
+	/** Reload the current document from the server. This is not a save of unsaved form edits. */
 	refresh: () => Promise<void>;
+	/** Show a temporary success or error message. */
 	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
 }
 
+/** Saved document data for actions/tabs; use the generated SDK for application-specific operations. */
 export interface AdminDocumentExtensionProps {
 	collection: SchemaCollection;
 	document: FieldDocument;
@@ -261,43 +333,49 @@ export interface AdminDocumentExtensionProps {
 	i18n: AdminI18n;
 }
 
+/** Add a component alongside the document's standard actions. Implement the operation in that component. */
 export interface AdminDocumentAction {
 	key: string;
 	/** Omit to show the action for every non-global collection. */
 	collection?: string;
-	/** Hide the action unless the evaluated document operation is allowed. */
+	/** Hide unless this document operation is allowed. Visibility does not replace server authorization. */
 	requires?: keyof OperationCapabilities;
 	component: Component<AdminDocumentExtensionProps>;
 }
 
+/** Add a tab beside Edit and API. Keys `edit` and `api` are reserved for Ridu. */
 export interface AdminDocumentView {
 	key: string;
 	label: string;
-	labelKey?: PluginTranslationKey;
-	/** Omit to show the view for every collection and global. */
+	labelKey?: ExtensionTranslationKey;
+	/** Collection or global slug; omit to show for every collection and global. */
 	collection?: string;
 	component: Component<AdminDocumentExtensionProps>;
 }
 
-export interface AdminPluginNavigation {
+export interface AdminRouteNavigation {
 	/** Human-readable navigation label inside the authenticated admin shell. */
 	label: string;
-	labelKey?: PluginTranslationKey;
+	labelKey?: ExtensionTranslationKey;
 	/** Optional grouping hint reserved for shells that render grouped plugin navigation. */
 	group?: string;
 }
 
 /** One statically bundled route mounted beneath the authenticated admin layout. */
-export interface AdminPluginRoute {
-	/** Relative route path; it must exactly match the compiled backend descriptor. */
+export interface AdminRoute {
+	/** Relative admin path, without a leading slash. Paired plugins must match their Go descriptor. */
 	path: string;
 	/** Svelte route component rendered by the framework router. */
 	component: Component;
 	/** Optional navigation entry; omit it for a route reachable only by links or redirects. */
-	navigation?: AdminPluginNavigation;
+	navigation?: AdminRouteNavigation;
 }
 
-/** Metadata emitted from the compiled Go plugin into the generated registry. */
+/**
+ * Go plugin metadata written into Ridu's generated admin registration file.
+ * Do not hand-maintain a second copy: `ridu generate` resolves the executable Go
+ * configuration and emits the matching imports and compatibility checks.
+ */
 export interface BackendAdminPlugin {
 	/** Framework admin-plugin API required by the compiled backend. */
 	apiVersion: number;
@@ -313,18 +391,22 @@ export interface BackendAdminPlugin {
 	routes?: readonly string[];
 	/** Exact ordered package-relative static assets declared by the backend. */
 	assets?: readonly string[];
+	/** Exact field-type keys declared by this backend plugin. */
+	fieldTypes?: readonly string[];
 }
 
+/** One imported admin plugin and its generated Go metadata, compared before use. */
 export interface AdminPluginPair {
 	admin: AdminPlugin;
 	backend: BackendAdminPlugin;
 }
 
+/** Checked plugin registrations collected for Ridu's admin runtime. Normally consumed by generated code. */
 export interface ResolvedAdminPluginPairs {
 	plugins: readonly AdminPlugin[];
-	fields: readonly FieldPlugin[];
+	fields: readonly ResolvedPluginField[];
 	rowLabels: readonly RowLabelPlugin[];
-	routes: readonly AdminPluginRoute[];
+	routes: readonly AdminRoute[];
 	dashboard: readonly AdminDashboardPanel[];
 	login: readonly AdminLoginComponent[];
 	account: readonly AdminAccountComponent[];
@@ -338,27 +420,22 @@ export interface ResolvedAdminPluginPairs {
 	documentActions: readonly AdminDocumentAction[];
 	documentViews: readonly AdminDocumentView[];
 	messages: Readonly<Record<string, PluginMessageCatalog>>;
+	applicationMessages: PluginMessageCatalog | undefined;
 }
 
-export type ResolvedAdminPluginExtensions = Omit<ResolvedAdminPluginPairs, "plugins" | "fields">;
-
-/** Defines one package export consumed by Ridu's generated static registry. */
-export function defineAdminPlugin<const Plugin extends AdminPlugin>(plugin: Plugin): Plugin {
-	return plugin;
-}
+export type ResolvedAdminExtensions = Omit<ResolvedAdminPluginPairs, "plugins" | "fields">;
 
 /**
- * Validates every compiled-backend/admin-package pair before exposing its
- * field registrations. Missing packages still fail at the static import, while
- * stale or mismatched packages fail here with a plugin-specific diagnostic.
+ * Check that installed Go/admin plugin packages agree on identity, API version,
+ * pairing version, routes, assets and field types. Ridu's generated file calls this;
+ * authors should fix mismatched packages rather than editing generated metadata.
+ * Missing imports fail during compilation; incompatible pairs throw here.
  */
 export function resolveAdminPluginPairs(
 	pairs: readonly AdminPluginPair[]
 ): ResolvedAdminPluginPairs {
 	const keys = new Set<string>();
-	const fieldIdentities = new Set<string>();
 	const plugins: AdminPlugin[] = [];
-	const fields: FieldPlugin[] = [];
 
 	for (const { admin, backend } of pairs) {
 		const identity = `${backend.package}#${backend.export}`;
@@ -390,39 +467,33 @@ export function resolveAdminPluginPairs(
 			(admin.routes ?? []).map((route) => route.path)
 		);
 		assertSameValues(`${backend.key} assets`, backend.assets ?? [], admin.assets ?? []);
-		for (const field of admin.fields) {
-			if (
-				(field.type === "plugin" || field.componentKey !== undefined) &&
-				field.key !== backend.key
-			) {
-				throw new Error(
-					`Admin plugin ${backend.key} registered plugin field ${field.key ?? "<missing>"}`
-				);
-			}
-			const fieldIdentity = `${field.type}:${field.key ?? ""}:${field.componentKey ?? ""}`;
-			if (fieldIdentities.has(fieldIdentity)) {
-				throw new Error(`Admin field renderer ${fieldIdentity} is registered more than once`);
-			}
-			fieldIdentities.add(fieldIdentity);
-			fields.push(field);
-		}
+		assertSameValues(
+			`${backend.key} field types`,
+			[...(backend.fieldTypes ?? [])].sort(),
+			Object.keys(admin.fields ?? {}).sort()
+		);
 		keys.add(backend.key);
 		plugins.push(admin);
 	}
-	const extensions = resolveAdminPluginExtensions(plugins);
+	const extensions = resolveAdminExtensions(plugins);
 
 	return {
 		plugins: Object.freeze(plugins),
-		fields: Object.freeze(fields),
+		fields: resolvePluginFields(plugins),
 		...extensions,
 	};
 }
 
-/** Finalizes frontend-only extension registrations before the admin mounts. */
-export function resolveAdminPluginExtensions(
-	plugins: readonly AdminPlugin[]
-): ResolvedAdminPluginExtensions {
-	const routes: AdminPluginRoute[] = [];
+/**
+ * Collect plugin UI first, then application UI, preserving order and rejecting
+ * duplicate identities or competing replacements. Used by Ridu's admin runtime;
+ * application authors normally provide `defineAdmin` configuration instead.
+ */
+export function resolveAdminExtensions(
+	plugins: readonly AdminPlugin[],
+	application?: AdminContributions & { messages?: PluginMessageCatalog }
+): ResolvedAdminExtensions {
+	const routes: AdminRoute[] = [];
 	const dashboard: AdminDashboardPanel[] = [];
 	const login: AdminLoginComponent[] = [];
 	const account: AdminAccountComponent[] = [];
@@ -446,7 +517,14 @@ export function resolveAdminPluginExtensions(
 	let replacementNavigation: string | undefined;
 	let logoutButton: AdminLogoutButton | undefined;
 
-	for (const plugin of plugins) {
+	const sources = [
+		...plugins.map((plugin) => ({ ...plugin, namespace: `plugin.${plugin.key}:` })),
+		...(application === undefined
+			? []
+			: [{ ...application, key: "application", namespace: "app:", rowLabels: [] }]),
+	];
+	for (const plugin of sources) {
+		validateContributions(plugin, plugin.namespace === "app:");
 		for (const rowLabel of plugin.rowLabels ?? []) {
 			if (rowLabel.key !== plugin.key) {
 				throw new Error(
@@ -465,7 +543,7 @@ export function resolveAdminPluginExtensions(
 			);
 			rowLabels.push(rowLabel);
 		}
-		if (plugin.messages !== undefined) {
+		if (plugin.messages !== undefined && plugin.namespace !== "app:") {
 			if (messages[plugin.key] !== undefined) {
 				throw new Error(`Admin plugin messages for ${plugin.key} are registered more than once`);
 			}
@@ -474,7 +552,7 @@ export function resolveAdminPluginExtensions(
 		}
 		for (const route of plugin.routes ?? []) {
 			validatePluginLabelKey(plugin, route.navigation?.labelKey, `route ${route.path}`);
-			claim(identities, `route:${route.path}`, `Admin plugin route ${route.path}`);
+			claim(identities, `route:${route.path.toLowerCase()}`, `Admin plugin route ${route.path}`);
 			routes.push(route);
 		}
 		for (const panel of plugin.dashboard ?? []) {
@@ -613,6 +691,8 @@ export function resolveAdminPluginExtensions(
 	}
 
 	return {
+		applicationMessages:
+			application?.messages === undefined ? undefined : freezeAdminMessages(application.messages),
 		rowLabels: Object.freeze(rowLabels),
 		routes: Object.freeze(routes),
 		dashboard: Object.freeze(dashboard),
@@ -634,12 +714,12 @@ export function resolveAdminPluginExtensions(
 const adminComponentKeyPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
 function validatePluginLabelKey(
-	plugin: AdminPlugin,
-	labelKey: PluginTranslationKey | undefined,
+	plugin: { key: string; namespace: string; messages?: PluginMessageCatalog },
+	labelKey: ExtensionTranslationKey | undefined,
 	surface: string
 ) {
 	if (labelKey === undefined) return;
-	const prefix = `plugin.${plugin.key}:`;
+	const prefix = plugin.namespace;
 	if (!labelKey.startsWith(prefix)) {
 		throw new Error(
 			`Admin plugin ${plugin.key} ${surface} label key must use its own ${prefix} namespace`
@@ -663,3 +743,114 @@ function assertSameValues(label: string, backend: readonly string[], admin: read
 		throw new Error(`Admin plugin ${label} do not match the compiled backend declaration`);
 	}
 }
+
+// Application routes are literal paths: no router
+// patterns, query strings, normalization aliases or framework namespace shadowing.
+const reservedRouteRoots = new Set([
+	"account",
+	"collections",
+	"globals",
+	"login",
+	"create-first-user",
+	"forgot-password",
+	"reset-password",
+	"request-verification",
+	"verify-email",
+]);
+function validateContributions(
+	source: AdminContributions & { messages?: PluginMessageCatalog },
+	local: boolean
+) {
+	if (source.messages !== undefined) validateAdminMessages("application", source.messages);
+	const groups = [
+		"routes",
+		"dashboard",
+		"login",
+		"account",
+		"navigation",
+		"views",
+		"branding",
+		"shell",
+		"providers",
+		"listCells",
+		"documentActions",
+		"documentViews",
+	] as const;
+	const positions = {
+		dashboard: ["before", "after", "replace"],
+		login: ["before", "after", "replace"],
+		account: ["before", "after", "replace"],
+		navigation: ["before", "beforeLinks", "afterLinks", "after", "replace"],
+		shell: ["header", "actions", "settingsMenu"],
+	} as const;
+	for (const group of groups) {
+		const entries = source[group];
+		if (entries === undefined) continue;
+		if (!Array.isArray(entries)) throw new Error(`Admin ${group} registrations must be an array.`);
+		for (const entry of entries) {
+			if (entry === null || typeof entry !== "object" || typeof entry.component !== "function")
+				throw new Error(`Admin ${group} registration requires a Svelte component.`);
+			if (
+				"key" in entry &&
+				(typeof entry.key !== "string" || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(entry.key))
+			)
+				throw new Error(`Admin ${group} registration has an invalid key.`);
+			if (group !== "routes" && !("key" in entry))
+				throw new Error(`Admin ${group} registration requires a key.`);
+			if (group in positions) {
+				const allowed: readonly string[] = positions[group as keyof typeof positions];
+				const position = "position" in entry ? entry.position : undefined;
+				if (
+					(position === undefined && (group === "navigation" || group === "shell")) ||
+					(position !== undefined && !allowed.includes(position))
+				)
+					throw new Error(`Admin ${group} registration has an invalid position.`);
+			}
+			if (group === "account" || group === "branding" || group === "views") {
+				const allowed =
+					group === "account"
+						? ["profile", "security"]
+						: group === "branding"
+							? ["loginLogo", "navigationLogo", "accountAvatar"]
+							: ["collectionList", "collectionCreate", "collectionEdit", "global", "notFound"];
+				if (!("surface" in entry) || !allowed.includes(entry.surface))
+					throw new Error(`Admin ${group} registration has an invalid surface.`);
+			}
+		}
+	}
+	for (const route of local ? (source.routes ?? []) : []) {
+		if (
+			typeof route.path !== "string" ||
+			!/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(route.path) ||
+			reservedRouteRoots.has(route.path.split("/")[0]!.toLowerCase())
+		)
+			throw new Error(
+				`Admin route ${route.path} must be a literal relative path outside framework namespaces.`
+			);
+	}
+	if (
+		source.logoutButton !== undefined &&
+		(typeof source.logoutButton.component !== "function" || !source.logoutButton.key)
+	)
+		throw new Error("Admin logout button requires a key and Svelte component.");
+	for (const action of source.documentActions ?? []) {
+		if (
+			action.requires !== undefined &&
+			![
+				"admin",
+				"create",
+				"read",
+				"readVersions",
+				"update",
+				"delete",
+				"duplicate",
+				"publish",
+				"unpublish",
+				"restoreDeleted",
+				"deletePermanent",
+				"selectAll",
+			].includes(action.requires)
+		)
+			throw new Error(`Admin document action ${action.key} has an invalid required operation.`);
+	}
+}