@riducms/plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haniel Ubogu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# `@riducms/plugin`
+
+Svelte and TypeScript APIs for Ridu admin plugins. Import field props, extension types, and
+`defineFieldPlugin` from this package.
+
+```ts
+import { defineFieldPlugin, type FieldComponentProps } from "@riducms/plugin";
+```
+
+`defineAdminPlugin` also exposes collision-checked static extension surfaces for login, profile,
+security, navigation, logout, dashboard, routes, list cells, document actions, and document views.
+Core-view replacements receive a `defaultView` snippet so a plugin can wrap the existing screen.
+Auth and account components receive hosts for login, logout, identity refresh, and notifications.
+
+Collection list/create/edit, global, and not-found replacements use the same model. They can be
+registered for one resource or as a surface-wide fallback; exact resource registrations win over
+fallbacks. Their host exposes manifest refresh, document-change invalidation, and notifications,
+and application data remains available through the generated SDK.
+
+Fine-grained shell registrations cover login/navigation graphics, the account avatar, global
+header and action slots, account settings items, and ordered provider wrappers. Replacement
+graphics allow one registration per surface; additive shell components and providers keep plugin
+order.
+
+A paired backend plugin may also assign an exact `componentKey` to a renderer for a built-in field
+type. These renderers keep the core field's storage semantics and receive the public form resource,
+content locale, a detached current-form `snapshot()`, and the narrow `requestPlugin` authoring host.
+That host calls only the paired backend plugin's namespaced endpoints.
+
+Arrays and blocks may also select an exact paired-plugin row-label component. Register it with
+`defineRowLabelPlugin({ key, componentKey, component })` and author the matching Go option with
+`field.RowLabelComponent`. The component receives the manifest field, a detached deeply frozen row
+snapshot, its 1-based visual `rowNumber`, current i18n, and deterministic JSON config. Registration
+identities are collision checked before mount, and a manifest that selects a missing
+plugin/component fails with a field-specific diagnostic. The legacy single-child
+`field.RowLabel(path)` behavior remains available for arrays.
+
+Use `@riducms/ui` for shared interaction components and the generated SDK for application data.

package/package.json

@@ -0,0 +1,38 @@
+{
+	"bugs": {
+		"url": "https://github.com/riducms/ridu/issues"
+	},
+	"dependencies": {
+		"@riducms/protocol": "0.1.0",
+		"@riducms/translations": "0.1.0"
+	},
+	"description": "Public TypeScript contracts for statically registered Ridu admin plugins.",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"LICENSE"
+	],
+	"homepage": "https://riducms.com",
+	"license": "MIT",
+	"name": "@riducms/plugin",
+	"peerDependencies": {
+		"svelte": "^5.56.8"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"repository": {
+		"directory": "packages/plugin",
+		"type": "git",
+		"url": "git+https://github.com/riducms/ridu.git"
+	},
+	"scripts": {
+		"check": "tsc -p tsconfig.json",
+		"test": "bun test"
+	},
+	"type": "module",
+	"version": "0.1.0"
+}

package/src/authoring.ts

@@ -0,0 +1,54 @@
+import type { SchemaCollection, SchemaField } from "@riducms/protocol";
+import type { Component } from "svelte";
+
+export type FieldDocument = Record<string, unknown> & {
+	id: string;
+	createdAt?: string;
+	updatedAt?: string;
+	deletedAt?: string;
+	_status?: "draft" | "published";
+	_revision?: number;
+	_localization?: {
+		sources: Record<string, string>;
+	};
+};
+
+export interface FieldReferenceFilter {
+	field: string;
+	operator:
+		| "equals"
+		| "notEquals"
+		| "like"
+		| "contains"
+		| "greaterThan"
+		| "greaterThanEqual"
+		| "lessThan"
+		| "lessThanEqual";
+	value: string | number | boolean;
+}
+
+export interface FieldReferenceBrowserProps {
+	open?: boolean;
+	field: SchemaField;
+	collection: SchemaCollection;
+	hasMany: boolean;
+	selectedIDs: readonly string[];
+	readOnly?: boolean;
+	initialDocument?: FieldDocument;
+	initialDocumentID?: string;
+	optionFilter?: FieldReferenceFilter | readonly FieldReferenceFilter[];
+	defaultValues?: Readonly<Record<string, unknown>>;
+	allowCreate?: boolean;
+	locale?: string;
+	onCommit: (ids: string[]) => void | boolean | Promise<void | boolean>;
+	onClose: () => void;
+}
+
+export interface FieldAuthoringHost {
+	readonly collections: readonly SchemaCollection[];
+	readonly documentRevision: number;
+	readonly locale?: string;
+	referenceBrowser: Component<FieldReferenceBrowserProps>;
+	findDocument(collection: string, id: string, signal?: AbortSignal): Promise<FieldDocument>;
+	requestPlugin?<Result>(path: string, body: unknown, signal?: AbortSignal): Promise<Result>;
+}

package/src/field.ts

@@ -0,0 +1,26 @@
+import type { FieldType, SchemaField } from "@riducms/protocol";
+import type { Component } from "svelte";
+
+import type { FieldAuthoringHost } from "./authoring";
+import type { FieldForm } from "./form";
+import type { AdminI18n } from "./i18n";
+
+export interface FieldComponentProps {
+	field: SchemaField;
+	form: FieldForm;
+	i18n: AdminI18n;
+	authoring?: FieldAuthoringHost;
+}
+
+export interface FieldPlugin {
+	type: FieldType;
+	key?: string;
+	/** Named renderer selected by field.admin.component for built-in field semantics. */
+	componentKey?: string;
+	component?: Component<FieldComponentProps>;
+	canRender(field: SchemaField): boolean;
+}
+
+export function defineFieldPlugin<const Plugin extends FieldPlugin>(plugin: Plugin): Plugin {
+	return plugin;
+}

package/src/form.ts

@@ -0,0 +1,17 @@
+import type { ValidationIssue } from "@riducms/protocol";
+
+export interface FieldFormResource {
+	collection: string;
+	id?: string;
+	global?: boolean;
+}
+
+export interface FieldForm {
+	readonly contentLocale?: string;
+	readonly resource?: FieldFormResource;
+	get(path: string): unknown;
+	issuesFor(path: string): readonly ValidationIssue[];
+	register(path: string): () => void;
+	set(path: string, value: unknown): void;
+	snapshot?(): Record<string, unknown>;
+}

package/src/i18n.ts

@@ -0,0 +1,97 @@
+import type {
+	AdminI18n,
+	PluginMessageCatalog,
+	PluginTranslationKey,
+	TranslationMessage,
+} from "@riducms/translations";
+import { validatePluginMessageCatalog } from "@riducms/translations";
+import { createContext } from "svelte";
+
+type ExactCatalog<Source extends Readonly<Record<string, TranslationMessage>>> = Readonly<{
+	[Key in keyof Source]: TranslationMessage;
+}>;
+
+type MessageText<Message> = Message extends string
+	? Message
+	: Message extends Readonly<Record<string, unknown>>
+		? Extract<Message[keyof Message], string>
+		: never;
+type PlaceholderNames<Text extends string> = Text extends `${string}{${infer Name}}${infer Rest}`
+	? Name | PlaceholderNames<Rest>
+	: never;
+type SamePlaceholders<Source, Candidate> = [
+	Exclude<PlaceholderNames<MessageText<Source>>, PlaceholderNames<MessageText<Candidate>>>,
+] extends [never]
+	? [
+			Exclude<PlaceholderNames<MessageText<Candidate>>, PlaceholderNames<MessageText<Source>>>,
+		] extends [never]
+		? true
+		: false
+	: false;
+type CompatibleMessage<Source, Candidate> =
+	SamePlaceholders<Source, Candidate> extends true
+		? Source extends string
+			? Candidate extends string
+				? Candidate
+				: never
+			: Candidate extends string
+				? never
+				: Candidate
+		: never;
+type CheckedCatalog<
+	Source extends Readonly<Record<string, TranslationMessage>>,
+	Candidate extends ExactCatalog<Source>,
+> = Readonly<{
+	[Key in keyof Source]: CompatibleMessage<Source[Key], Candidate[Key]>;
+}> &
+	Readonly<Record<Exclude<keyof Candidate, keyof Source>, never>>;
+type AdminMessagesShape = Readonly<{
+	fallback: Readonly<Record<string, TranslationMessage>>;
+	translations?: Readonly<Record<string, Readonly<Record<string, TranslationMessage>>>>;
+}>;
+type CheckedAdminMessages<Input extends AdminMessagesShape> =
+	Input["translations"] extends Readonly<
+		Record<string, Readonly<Record<string, TranslationMessage>>>
+	>
+		? {
+				translations: {
+					[
+						Language in keyof Input["translations"]
+					]: Input["translations"][Language] extends ExactCatalog<Input["fallback"]>
+						? CheckedCatalog<Input["fallback"], Input["translations"][Language]>
+						: never;
+				};
+			}
+		: unknown;
+
+export interface DefineAdminMessagesInput<
+	Fallback extends Readonly<Record<string, TranslationMessage>>,
+> {
+	fallback: Fallback;
+	translations?: Readonly<Record<string, ExactCatalog<Fallback>>>;
+}
+
+/** Defines one plugin-owned message catalog with exact translated key coverage. */
+export function defineAdminMessages<const Input extends AdminMessagesShape>(
+	input: Input & CheckedAdminMessages<Input>
+): DefineAdminMessagesInput<Input["fallback"]> {
+	validatePluginMessageCatalog("definition", input);
+	return freezeAdminMessages(input) as DefineAdminMessagesInput<Input["fallback"]>;
+}
+
+export function validateAdminMessages(key: string, messages: PluginMessageCatalog) {
+	validatePluginMessageCatalog(key, messages);
+}
+
+export function freezeAdminMessages(messages: PluginMessageCatalog): PluginMessageCatalog {
+	if (Object.isFrozen(messages)) return messages;
+	Object.freeze(messages.fallback);
+	for (const catalog of Object.values(messages.translations ?? {})) Object.freeze(catalog);
+	if (messages.translations !== undefined) Object.freeze(messages.translations);
+	return Object.freeze(messages);
+}
+
+const [getAdminI18n, setAdminI18n] = createContext<AdminI18n>();
+
+export { getAdminI18n, setAdminI18n };
+export type { AdminI18n, PluginMessageCatalog, PluginTranslationKey };

package/src/index.ts

@@ -0,0 +1,73 @@
+export type {
+	FieldAuthoringHost,
+	FieldDocument,
+	FieldReferenceBrowserProps,
+	FieldReferenceFilter,
+} from "./authoring";
+export { defineFieldPlugin, type FieldComponentProps, type FieldPlugin } from "./field";
+export {
+	defineRowLabelPlugin,
+	type RowLabelComponentProps,
+	type RowLabelPlugin,
+	type RowLabelSnapshot,
+	type RowLabelValue,
+} from "./row-label";
+export type { FieldForm, FieldFormResource } from "./form";
+export {
+	defineAdminMessages,
+	getAdminI18n,
+	setAdminI18n,
+	validateAdminMessages,
+	type AdminI18n,
+	type DefineAdminMessagesInput,
+	type PluginMessageCatalog,
+	type PluginTranslationKey,
+} from "./i18n";
+export {
+	ADMIN_PLUGIN_API_VERSION,
+	defineAdminPlugin,
+	resolveAdminPluginExtensions,
+	resolveAdminPluginPairs,
+	type AdminPlugin,
+	type AdminDashboardPanel,
+	type AdminDashboardPanelProps,
+	type AdminExtensionProps,
+	type AdminLoginComponent,
+	type AdminLoginComponentProps,
+	type AdminLoginExtensionHost,
+	type AdminAccountComponent,
+	type AdminAccountComponentProps,
+	type AdminAccountExtensionHost,
+	type AdminAccountSurface,
+	type AdminNavigationComponent,
+	type AdminNavigationComponentProps,
+	type AdminNavigationPosition,
+	type AdminLogoutButton,
+	type AdminLogoutButtonProps,
+	type AdminLogoutExtensionHost,
+	type AdminCoreView,
+	type AdminCoreViewHost,
+	type AdminCoreViewProps,
+	type AdminCoreViewSurface,
+	type AdminBrandComponent,
+	type AdminBrandComponentProps,
+	type AdminBrandSurface,
+	type AdminShellComponent,
+	type AdminShellComponentProps,
+	type AdminShellPosition,
+	type AdminProvider,
+	type AdminProviderProps,
+	type AdminDocumentAction,
+	type AdminDocumentExtensionHost,
+	type AdminDocumentExtensionProps,
+	type AdminDocumentView,
+	type AdminExtensionNotificationTone,
+	type AdminListCell,
+	type AdminListCellProps,
+	type AdminPluginNavigation,
+	type AdminPluginPair,
+	type AdminPluginRoute,
+	type BackendAdminPlugin,
+	type ResolvedAdminPluginExtensions,
+	type ResolvedAdminPluginPairs,
+} from "./plugin";

package/src/plugin.ts

@@ -0,0 +1,665 @@
+import type { FieldPlugin } from "./field";
+import { ADMIN_PLUGIN_API_VERSION } from "@riducms/protocol";
+import type {
+	OperationCapabilities,
+	SchemaCollection,
+	SchemaField,
+	SchemaGlobal,
+	SchemaManifest,
+} from "@riducms/protocol";
+import type { Component, Snippet } from "svelte";
+
+import type { FieldDocument } from "./authoring";
+import type { AdminI18n, PluginMessageCatalog, PluginTranslationKey } 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.
+ */
+export interface AdminPlugin {
+	/** Framework admin-plugin contract version compiled by this package. */
+	apiVersion: typeof ADMIN_PLUGIN_API_VERSION;
+	/** Stable key matching the compiled Go plugin. */
+	key: string;
+	/** Plugin-owned backend/admin compatibility version. */
+	pairingVersion: number;
+	/** Field renderers contributed by this package. */
+	fields: readonly FieldPlugin[];
+	/** Array and blocks row-label components contributed by this package. */
+	rowLabels?: readonly RowLabelPlugin[];
+	/** Statically bundled, plugin-owned interface messages. */
+	messages?: PluginMessageCatalog;
+	/** Authenticated admin routes contributed by this package. */
+	routes?: readonly AdminPluginRoute[];
+	/** Panels composed into or replacing the authenticated dashboard. */
+	dashboard?: readonly AdminDashboardPanel[];
+	/** Components composed around or replacing the sign-in screen. */
+	login?: readonly AdminLoginComponent[];
+	/** Components composed around or replacing the framework account screens. */
+	account?: readonly AdminAccountComponent[];
+	/** Components composed around or replacing the framework navigation. */
+	navigation?: readonly AdminNavigationComponent[];
+	/** Replaces the default sign-out control in the account menu. */
+	logoutButton?: AdminLogoutButton;
+	/** Wraps or replaces framework collection, global, and not-found views. */
+	views?: readonly AdminCoreView[];
+	/** Replaces framework-owned brand graphics at exact shell surfaces. */
+	branding?: readonly AdminBrandComponent[];
+	/** Adds global header, action, or account-settings menu components. */
+	shell?: readonly AdminShellComponent[];
+	/** Wraps the admin in statically ordered Svelte context providers. */
+	providers?: readonly AdminProvider[];
+	/** Collection list cells rendered for exact collection/field pairs. */
+	listCells?: readonly AdminListCell[];
+	/** Actions rendered alongside framework-owned document actions. */
+	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[];
+}
+
+export interface AdminExtensionProps {
+	manifest: SchemaManifest;
+	user?: FieldDocument;
+	i18n: AdminI18n;
+}
+
+export interface AdminLoginExtensionHost {
+	/** Authenticates, evaluates admin access, and enters the authenticated shell. */
+	login: (credentials: { email: string; password: string }) => Promise<void>;
+	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
+}
+
+export interface AdminLoginComponentProps extends AdminExtensionProps {
+	/** The complete framework sign-in screen, available to replacement wrappers. */
+	defaultView: Snippet;
+	host: AdminLoginExtensionHost;
+}
+
+export interface AdminLoginComponent {
+	key: string;
+	component: Component<AdminLoginComponentProps>;
+	position?: "before" | "after" | "replace";
+}
+
+export type AdminAccountSurface = "profile" | "security";
+
+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>;
+	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
+}
+
+export interface AdminAccountComponentProps extends AdminExtensionProps {
+	surface: AdminAccountSurface;
+	/** The complete framework account screen, available to replacement wrappers. */
+	defaultView: Snippet;
+	host: AdminAccountExtensionHost;
+}
+
+export interface AdminAccountComponent {
+	key: string;
+	surface: AdminAccountSurface;
+	component: Component<AdminAccountComponentProps>;
+	position?: "before" | "after" | "replace";
+}
+
+export type AdminNavigationPosition = "before" | "beforeLinks" | "afterLinks" | "after" | "replace";
+
+export interface AdminNavigationComponentProps extends AdminExtensionProps {
+	/** The complete framework navigation, available to replacement wrappers. */
+	defaultView: Snippet;
+}
+
+export interface AdminNavigationComponent {
+	key: string;
+	component: Component<AdminNavigationComponentProps>;
+	position: AdminNavigationPosition;
+}
+
+export interface AdminLogoutExtensionHost {
+	logout: () => Promise<void>;
+}
+
+export interface AdminLogoutButtonProps extends AdminExtensionProps {
+	host: AdminLogoutExtensionHost;
+}
+
+export interface AdminLogoutButton {
+	key: string;
+	component: Component<AdminLogoutButtonProps>;
+}
+
+export type AdminCoreViewSurface =
+	"collectionList" | "collectionCreate" | "collectionEdit" | "global" | "notFound";
+
+export interface AdminCoreViewHost {
+	refreshManifest: () => Promise<void>;
+	documentsChanged: () => void;
+	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
+}
+
+export interface AdminCoreViewProps extends AdminExtensionProps {
+	surface: AdminCoreViewSurface;
+	collection?: SchemaCollection;
+	global?: SchemaGlobal;
+	documentID?: string;
+	/** The complete framework route, available to replacement wrappers. */
+	defaultView: Snippet;
+	host: AdminCoreViewHost;
+}
+
+interface AdminCollectionCoreView {
+	key: string;
+	surface: "collectionList" | "collectionCreate" | "collectionEdit";
+	/** Omit to replace this surface for every collection. */
+	collection?: string;
+	component: Component<AdminCoreViewProps>;
+}
+
+interface AdminGlobalCoreView {
+	key: string;
+	surface: "global";
+	/** Omit to replace this surface for every global. */
+	global?: string;
+	component: Component<AdminCoreViewProps>;
+}
+
+interface AdminNotFoundCoreView {
+	key: string;
+	surface: "notFound";
+	component: Component<AdminCoreViewProps>;
+}
+
+export type AdminCoreView = AdminCollectionCoreView | AdminGlobalCoreView | AdminNotFoundCoreView;
+
+export type AdminBrandSurface = "loginLogo" | "navigationLogo" | "accountAvatar";
+
+export interface AdminBrandComponentProps extends AdminExtensionProps {
+	surface: AdminBrandSurface;
+}
+
+export interface AdminBrandComponent {
+	key: string;
+	surface: AdminBrandSurface;
+	component: Component<AdminBrandComponentProps>;
+}
+
+export type AdminShellPosition = "header" | "actions" | "settingsMenu";
+
+export interface AdminShellComponentProps extends AdminExtensionProps {
+	position: AdminShellPosition;
+}
+
+export interface AdminShellComponent {
+	key: string;
+	position: AdminShellPosition;
+	component: Component<AdminShellComponentProps>;
+}
+
+export interface AdminProviderProps {
+	/** The remaining provider stack and framework admin application. */
+	defaultView: Snippet;
+	i18n: AdminI18n;
+}
+
+export interface AdminProvider {
+	key: string;
+	component: Component<AdminProviderProps>;
+}
+
+export interface AdminDashboardPanelProps {
+	manifest: SchemaManifest;
+	user?: FieldDocument;
+	i18n: AdminI18n;
+}
+
+export interface AdminDashboardPanel {
+	/** Plugin-owned identity used for deterministic ordering and collision checks. */
+	key: string;
+	component: Component<AdminDashboardPanelProps>;
+	/** Replace suppresses the framework overview and may only be registered once. */
+	position?: "before" | "after" | "replace";
+}
+
+export interface AdminListCellProps {
+	collection: SchemaCollection;
+	field: SchemaField;
+	document: FieldDocument;
+	value: unknown;
+	i18n: AdminI18n;
+}
+
+export interface AdminListCell {
+	key: string;
+	collection: string;
+	field: string;
+	label: string;
+	labelKey?: PluginTranslationKey;
+	component: Component<AdminListCellProps>;
+}
+
+export type AdminExtensionNotificationTone = "success" | "error";
+
+export interface AdminDocumentExtensionHost {
+	refresh: () => Promise<void>;
+	notify: (tone: AdminExtensionNotificationTone, title: string, message?: string) => void;
+}
+
+export interface AdminDocumentExtensionProps {
+	collection: SchemaCollection;
+	document: FieldDocument;
+	host: AdminDocumentExtensionHost;
+	i18n: AdminI18n;
+}
+
+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. */
+	requires?: keyof OperationCapabilities;
+	component: Component<AdminDocumentExtensionProps>;
+}
+
+export interface AdminDocumentView {
+	key: string;
+	label: string;
+	labelKey?: PluginTranslationKey;
+	/** Omit to show the view for every collection and global. */
+	collection?: string;
+	component: Component<AdminDocumentExtensionProps>;
+}
+
+export interface AdminPluginNavigation {
+	/** Human-readable navigation label inside the authenticated admin shell. */
+	label: string;
+	labelKey?: PluginTranslationKey;
+	/** 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. */
+	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;
+}
+
+/** Metadata emitted from the compiled Go plugin into the generated registry. */
+export interface BackendAdminPlugin {
+	/** Framework admin-plugin API required by the compiled backend. */
+	apiVersion: number;
+	/** Named AdminPlugin export in package. */
+	export: string;
+	/** Stable backend plugin key. */
+	key: string;
+	/** Installed bare JavaScript package specifier. */
+	package: string;
+	/** Plugin-owned backend/admin compatibility version. */
+	pairingVersion: number;
+	/** Exact ordered route paths declared by the compiled backend. */
+	routes?: readonly string[];
+	/** Exact ordered package-relative static assets declared by the backend. */
+	assets?: readonly string[];
+}
+
+export interface AdminPluginPair {
+	admin: AdminPlugin;
+	backend: BackendAdminPlugin;
+}
+
+export interface ResolvedAdminPluginPairs {
+	plugins: readonly AdminPlugin[];
+	fields: readonly FieldPlugin[];
+	rowLabels: readonly RowLabelPlugin[];
+	routes: readonly AdminPluginRoute[];
+	dashboard: readonly AdminDashboardPanel[];
+	login: readonly AdminLoginComponent[];
+	account: readonly AdminAccountComponent[];
+	navigation: readonly AdminNavigationComponent[];
+	logoutButton: AdminLogoutButton | undefined;
+	views: readonly AdminCoreView[];
+	branding: readonly AdminBrandComponent[];
+	shell: readonly AdminShellComponent[];
+	providers: readonly AdminProvider[];
+	listCells: readonly AdminListCell[];
+	documentActions: readonly AdminDocumentAction[];
+	documentViews: readonly AdminDocumentView[];
+	messages: Readonly<Record<string, PluginMessageCatalog>>;
+}
+
+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;
+}
+
+/**
+ * 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.
+ */
+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}`;
+		if (keys.has(backend.key))
+			throw new Error(`Admin plugin ${backend.key} is paired more than once`);
+		if (backend.apiVersion !== ADMIN_PLUGIN_API_VERSION) {
+			throw new Error(
+				`Backend plugin ${backend.key} requires admin plugin API ${backend.apiVersion}, but this admin supports ${ADMIN_PLUGIN_API_VERSION}`
+			);
+		}
+		if (admin.apiVersion !== ADMIN_PLUGIN_API_VERSION) {
+			throw new Error(
+				`Admin plugin ${identity} uses API ${admin.apiVersion}, but this admin supports ${ADMIN_PLUGIN_API_VERSION}`
+			);
+		}
+		if (admin.key !== backend.key) {
+			throw new Error(
+				`Admin plugin ${identity} declares key ${admin.key}, but the compiled backend expects ${backend.key}`
+			);
+		}
+		if (admin.pairingVersion !== backend.pairingVersion) {
+			throw new Error(
+				`Admin plugin ${backend.key} pairing version ${admin.pairingVersion} does not match backend version ${backend.pairingVersion}; install matching plugin packages`
+			);
+		}
+		assertSameValues(
+			`${backend.key} routes`,
+			backend.routes ?? [],
+			(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);
+		}
+		keys.add(backend.key);
+		plugins.push(admin);
+	}
+	const extensions = resolveAdminPluginExtensions(plugins);
+
+	return {
+		plugins: Object.freeze(plugins),
+		fields: Object.freeze(fields),
+		...extensions,
+	};
+}
+
+/** Finalizes frontend-only extension registrations before the admin mounts. */
+export function resolveAdminPluginExtensions(
+	plugins: readonly AdminPlugin[]
+): ResolvedAdminPluginExtensions {
+	const routes: AdminPluginRoute[] = [];
+	const dashboard: AdminDashboardPanel[] = [];
+	const login: AdminLoginComponent[] = [];
+	const account: AdminAccountComponent[] = [];
+	const navigation: AdminNavigationComponent[] = [];
+	const views: AdminCoreView[] = [];
+	const branding: AdminBrandComponent[] = [];
+	const shell: AdminShellComponent[] = [];
+	const providers: AdminProvider[] = [];
+	const listCells: AdminListCell[] = [];
+	const documentActions: AdminDocumentAction[] = [];
+	const documentViews: AdminDocumentView[] = [];
+	const rowLabels: RowLabelPlugin[] = [];
+	const messages: Record<string, PluginMessageCatalog> = Object.create(null) as Record<
+		string,
+		PluginMessageCatalog
+	>;
+	const identities = new Set<string>();
+	let replacementDashboard: string | undefined;
+	let replacementLogin: string | undefined;
+	const replacementAccounts = new Map<AdminAccountSurface, string>();
+	let replacementNavigation: string | undefined;
+	let logoutButton: AdminLogoutButton | undefined;
+
+	for (const plugin of plugins) {
+		for (const rowLabel of plugin.rowLabels ?? []) {
+			if (rowLabel.key !== plugin.key) {
+				throw new Error(
+					`Admin plugin ${plugin.key} registered row label component for plugin ${rowLabel.key}`
+				);
+			}
+			if (!adminComponentKeyPattern.test(rowLabel.componentKey)) {
+				throw new Error(
+					`Admin row label component ${rowLabel.key}:${rowLabel.componentKey} has an invalid component key`
+				);
+			}
+			claim(
+				identities,
+				`row-label:${rowLabel.key}:${rowLabel.componentKey}`,
+				`Admin row label component ${rowLabel.key}:${rowLabel.componentKey}`
+			);
+			rowLabels.push(rowLabel);
+		}
+		if (plugin.messages !== undefined) {
+			if (messages[plugin.key] !== undefined) {
+				throw new Error(`Admin plugin messages for ${plugin.key} are registered more than once`);
+			}
+			validateAdminMessages(plugin.key, plugin.messages);
+			messages[plugin.key] = freezeAdminMessages(plugin.messages);
+		}
+		for (const route of plugin.routes ?? []) {
+			validatePluginLabelKey(plugin, route.navigation?.labelKey, `route ${route.path}`);
+			claim(identities, `route:${route.path}`, `Admin plugin route ${route.path}`);
+			routes.push(route);
+		}
+		for (const panel of plugin.dashboard ?? []) {
+			claim(identities, `dashboard:${panel.key}`, `Admin dashboard panel ${panel.key}`);
+			if (panel.position === "replace") {
+				if (replacementDashboard !== undefined) {
+					throw new Error(
+						`Admin dashboard replacements ${replacementDashboard} and ${panel.key} are both registered`
+					);
+				}
+				replacementDashboard = panel.key;
+			}
+			dashboard.push(panel);
+		}
+		for (const component of plugin.login ?? []) {
+			claim(identities, `login:${component.key}`, `Admin login component ${component.key}`);
+			if (component.position === "replace") {
+				if (replacementLogin !== undefined) {
+					throw new Error(
+						`Admin login replacements ${replacementLogin} and ${component.key} are both registered`
+					);
+				}
+				replacementLogin = component.key;
+			}
+			login.push(component);
+		}
+		for (const component of plugin.account ?? []) {
+			claim(
+				identities,
+				`account:${component.surface}:${component.key}`,
+				`Admin account component ${component.key}`
+			);
+			if (component.position === "replace") {
+				const replacement = replacementAccounts.get(component.surface);
+				if (replacement !== undefined) {
+					throw new Error(
+						`Admin ${component.surface} account replacements ${replacement} and ${component.key} are both registered`
+					);
+				}
+				replacementAccounts.set(component.surface, component.key);
+			}
+			account.push(component);
+		}
+		for (const component of plugin.navigation ?? []) {
+			claim(
+				identities,
+				`navigation:${component.key}`,
+				`Admin navigation component ${component.key}`
+			);
+			if (component.position === "replace") {
+				if (replacementNavigation !== undefined) {
+					throw new Error(
+						`Admin navigation replacements ${replacementNavigation} and ${component.key} are both registered`
+					);
+				}
+				replacementNavigation = component.key;
+			}
+			navigation.push(component);
+		}
+		if (plugin.logoutButton !== undefined) {
+			if (logoutButton !== undefined) {
+				throw new Error(
+					`Admin logout buttons ${logoutButton.key} and ${plugin.logoutButton.key} are both registered`
+				);
+			}
+			claim(
+				identities,
+				`logout-button:${plugin.logoutButton.key}`,
+				`Admin logout button ${plugin.logoutButton.key}`
+			);
+			logoutButton = plugin.logoutButton;
+		}
+		for (const view of plugin.views ?? []) {
+			const resource =
+				"collection" in view
+					? (view.collection ?? "*")
+					: "global" in view
+						? (view.global ?? "*")
+						: "*";
+			claim(
+				identities,
+				`core-view:${view.surface}:${resource}`,
+				`Admin core view ${view.surface}.${resource}`
+			);
+			views.push(view);
+		}
+		for (const component of plugin.branding ?? []) {
+			claim(
+				identities,
+				`branding:${component.surface}`,
+				`Admin branding surface ${component.surface}`
+			);
+			branding.push(component);
+		}
+		for (const component of plugin.shell ?? []) {
+			claim(
+				identities,
+				`shell:${component.position}:${component.key}`,
+				`Admin shell component ${component.key}`
+			);
+			shell.push(component);
+		}
+		for (const provider of plugin.providers ?? []) {
+			claim(identities, `provider:${provider.key}`, `Admin provider ${provider.key}`);
+			providers.push(provider);
+		}
+		for (const cell of plugin.listCells ?? []) {
+			validatePluginLabelKey(plugin, cell.labelKey, `list cell ${cell.collection}.${cell.field}`);
+			claim(
+				identities,
+				`list-cell:${cell.collection}:${cell.field}`,
+				`Admin list cell ${cell.collection}.${cell.field}`
+			);
+			listCells.push(cell);
+		}
+		for (const action of plugin.documentActions ?? []) {
+			claim(
+				identities,
+				`document-action:${action.collection ?? "*"}:${action.key}`,
+				`Admin document action ${action.key}`
+			);
+			documentActions.push(action);
+		}
+		for (const view of plugin.documentViews ?? []) {
+			validatePluginLabelKey(plugin, view.labelKey, `document view ${view.key}`);
+			if (view.key === "edit" || view.key === "api") {
+				throw new Error(`Admin document view ${view.key} collides with a framework view`);
+			}
+			claim(
+				identities,
+				`document-view:${view.collection ?? "*"}:${view.key}`,
+				`Admin document view ${view.key}`
+			);
+			documentViews.push(view);
+		}
+	}
+
+	return {
+		rowLabels: Object.freeze(rowLabels),
+		routes: Object.freeze(routes),
+		dashboard: Object.freeze(dashboard),
+		login: Object.freeze(login),
+		account: Object.freeze(account),
+		navigation: Object.freeze(navigation),
+		logoutButton,
+		views: Object.freeze(views),
+		branding: Object.freeze(branding),
+		shell: Object.freeze(shell),
+		providers: Object.freeze(providers),
+		listCells: Object.freeze(listCells),
+		documentActions: Object.freeze(documentActions),
+		documentViews: Object.freeze(documentViews),
+		messages: Object.freeze(messages),
+	};
+}
+
+const adminComponentKeyPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+function validatePluginLabelKey(
+	plugin: AdminPlugin,
+	labelKey: PluginTranslationKey | undefined,
+	surface: string
+) {
+	if (labelKey === undefined) return;
+	const prefix = `plugin.${plugin.key}:`;
+	if (!labelKey.startsWith(prefix)) {
+		throw new Error(
+			`Admin plugin ${plugin.key} ${surface} label key must use its own ${prefix} namespace`
+		);
+	}
+	const messageKey = labelKey.slice(prefix.length);
+	if (plugin.messages?.fallback[messageKey] === undefined) {
+		throw new Error(
+			`Admin plugin ${plugin.key} ${surface} label key ${labelKey} is not defined in its messages`
+		);
+	}
+}
+
+function claim(identities: Set<string>, identity: string, label: string) {
+	if (identities.has(identity)) throw new Error(`${label} is already registered`);
+	identities.add(identity);
+}
+
+function assertSameValues(label: string, backend: readonly string[], admin: readonly string[]) {
+	if (backend.length !== admin.length || backend.some((value, index) => value !== admin[index])) {
+		throw new Error(`Admin plugin ${label} do not match the compiled backend declaration`);
+	}
+}

package/src/row-label.ts

@@ -0,0 +1,37 @@
+import type { SchemaField } from "@riducms/protocol";
+import type { Component } from "svelte";
+
+import type { AdminI18n } from "./i18n";
+
+export type RowLabelValue =
+	| string
+	| number
+	| boolean
+	| null
+	| undefined
+	| readonly RowLabelValue[]
+	| { readonly [key: string]: RowLabelValue };
+
+/** A detached, deeply frozen view of the current array or blocks row. */
+export type RowLabelSnapshot = Readonly<Record<string, RowLabelValue>>;
+
+export interface RowLabelComponentProps {
+	field: SchemaField;
+	row: RowLabelSnapshot;
+	/** The current visual position, starting at one. */
+	rowNumber: number;
+	i18n: AdminI18n;
+	/** Deterministic JSON from field.nested.rowLabelComponent.config. */
+	config: unknown;
+}
+
+/** One exact plugin-owned component available to array and blocks headings. */
+export interface RowLabelPlugin {
+	key: string;
+	componentKey: string;
+	component: Component<RowLabelComponentProps>;
+}
+
+export function defineRowLabelPlugin<const Plugin extends RowLabelPlugin>(plugin: Plugin): Plugin {
+	return plugin;
+}