@riducms/plugin 0.1.5 → 0.2.0

package/README.md

@@ -1,38 +1,352 @@
 # `@riducms/plugin`
 
-Svelte and TypeScript APIs for Ridu admin plugins. Import field props, extension types, and
-`defineFieldPlugin` from this package.
+Build Svelte components that work inside Ridu's admin. Ridu provides the document form,
+validation messages, access state and tools for related documents. Your component supplies the UI.
+The admin is built into static files and served by the Go application; these components run in
+the browser, without a JavaScript server in production.
+
+## Choose the API for your job
+
+| Job | Import | Register/select it |
+| --- | --- | --- |
+| Add a field type with its own Go rules and structured value | `defineAdminPlugin`, `definePluginField` from `@riducms/plugin/authoring/v1` | Plugin `fields` map; matching field-type key declared in Go |
+| Supply an alternative advanced field editor in a paired plugin | `defineFieldComponent` from `@riducms/plugin/authoring/v1` | Plugin `components` map; Go `.Admin(field.Admin{Editor: field.PluginComponent(owner, name, config)})` |
+| Change how one application's text/number/checkbox-style field looks | `defineFieldEditor` from `@riducms/plugin/editor` | `defineAdmin({ fields })`; Go `.Admin(field.Admin{Editor: field.Component("app:name", config)})` |
+| Add application routes, dashboard panels or other admin UI | `defineAdmin` from `@riducms/plugin/admin` | `admin/src/admin.config.ts` |
+| Customize an application's array/block row headings | `defineRowLabel` from `@riducms/plugin/admin` | `defineAdmin({ rowLabels })`; Go `.Admin(field.Admin{RowLabel: field.Component("app:name", config)})` |
+| Use the shared visual controls | `@riducms/ui` | Compose controls in your component |
+
+Public component/host types are exported from `@riducms/plugin`. The versioned authoring import
+also exports the plugin field types. Do not import private `admin/src` implementations.
+
+## A plugin has a server half and a browser half
+
+The **Go half** declares the plugin's field types, settings, validation and any server endpoints.
+The **Svelte/TypeScript half** displays those fields and implements browser interactions.
+Ridu generates the glue that checks both halves agree and chooses the correct component.
+
+There are three separate names:
+
+- **Plugin key**, such as `editorial-tools`: identifies the installed Go/admin pair.
+- **Field-type key**, such as `review-note`: identifies a kind of value supplied by that plugin.
+  One plugin can provide several types; field-type keys must be unique across installed plugins.
+- **Field name**, such as `review`: identifies where a value lives in a document. Several fields
+  can use the same `review-note` type, including fields inside repeatable rows.
+
+Use `ridu plugin new` to start a paired package and `ridu plugin add` to install it into an app.
+The app retains `generatedAdminPlugins` in `defineAdmin({ plugins: generatedAdminPlugins })`.
+This keeps the generated Go/admin checks. Authors using explicit imports still supply an ordinary
+plugin array, such as `plugins: [outlineAdminPlugin, seoAdminPlugin]`, alongside the corresponding
+Go registrations and generated checks.
+
+`pairingVersion` is a positive integer you maintain in both halves. Increase it when the Go and
+admin packages can no longer work together. It is separate from your package release version.
+The `/authoring/v1` import supplies Ridu's `apiVersion`; do not stamp it onto a declaration yourself.
+Changing that number does not make incompatible code compatible.
+
+## Example: a note with a “Use note as title” button
+
+This editor stores `{ text: string }`. Its Go field settings contain `{ "copyTo": "title" }`,
+meaning the button should copy into the containing document's Title field.
+
+First define checked data/settings in `value.ts`. A decoder is simply a function that checks
+unknown data, returns the shape your component expects, or throws a useful error.
+
+```ts
+export interface NoteValue {
+  text: string;
+}
+export interface NoteConfig {
+  copyTo: string;
+}
+
+export function decodeNote(raw: unknown): NoteValue {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) ||
+      !("text" in raw) || typeof raw.text !== "string" || Object.keys(raw).length !== 1) {
+    throw new Error("A note must be an object containing only a text string.");
+  }
+  return { text: raw.text };
+}
+
+export function decodeNoteConfig(raw: unknown): NoteConfig {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) ||
+      !("copyTo" in raw) || typeof raw.copyTo !== "string" || !raw.copyTo.trim() ||
+      Object.keys(raw).length !== 1) {
+    throw new Error("Note settings must contain a nonempty copyTo field path.");
+  }
+  return { copyTo: raw.copyTo };
+}
+```
+
+Then write `note-field.svelte`:
+
+```svelte
+<script lang="ts">
+  import type { PluginFieldProps } from "@riducms/plugin/authoring/v1";
+  import type { NoteValue, NoteConfig } from "./value";
+
+  let { field, config, form }: PluginFieldProps<NoteValue, NoteConfig> = $props();
+  // Remember this document's Title field while this note editor is open.
+  // svelte-ignore state_referenced_locally
+  const title = form.bind(config.copyTo);
+</script>
+
+<label for={field.schema.id}>{field.schema.admin.label}</label>
+<textarea
+  id={field.schema.id}
+  name={field.schema.path}
+  required={field.schema.required}
+  readonly={field.readOnly}
+  aria-invalid={field.issues.length > 0}
+  aria-describedby={`${field.schema.id}-issues`}
+  value={field.value?.text ?? ""}
+  oninput={(event) => field.set({ text: event.currentTarget.value })}
+></textarea>
+<div id={`${field.schema.id}-issues`} aria-live="polite">
+  {#each field.issues as issue}<p>{issue.message}</p>{/each}
+</div>
+<button
+  type="button"
+  disabled={field.readOnly || title.readOnly || !field.value?.text}
+  onclick={() => title.set(field.value?.text ?? null)}
+>
+  Use note as title
+</button>
+```
+
+Register it in `index.ts`:
 
 ```ts
-import { defineFieldPlugin, type FieldComponentProps } from "@riducms/plugin";
+import { defineAdminPlugin, definePluginField } from "@riducms/plugin/authoring/v1";
+import NoteField from "./note-field.svelte";
+import { decodeNote, decodeNoteConfig } from "./value";
+
+export const editorialAdminPlugin = defineAdminPlugin({
+  key: "editorial-tools",
+  pairingVersion: 1,
+  fields: {
+    "review-note": definePluginField({
+      component: NoteField,
+      decodeValue: decodeNote,
+      decodeConfig: decodeNoteConfig,
+    }),
+  },
+});
 ```
 
-`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.
+The Go descriptor must declare the same plugin/field-type keys, admin package/export and pairing
+version, plus its value types and validation. The application must actually contain a `title`
+field. The config decoder above checks the setting's shape; it does not prove that path exists.
+`form.bind` checks the current form when the component starts. See the
+[plugin guide](https://riducms.com/docs/plugins/) for the Go registration side.
+
+The flow is:
+
+1. Ridu opens the document and supplies its form to your component.
+2. Typing calls `field.set({ text: ... })`, changing the note in the **unsaved form**.
+3. Clicking the button copies the note's current text into Title in that same form.
+4. This is a one-time copy. Further typing does not update Title until another click.
+5. Saving the document sends the form through Ridu's normal server permissions and validation.
+   If validation fails, Ridu supplies the returned issues to the field.
+
+Nothing in this button calls AI or saves to the database. A note inside `reviews.0.note` still
+copies to the document-root `title`, because that is what its config says.
+
+## What `form.bind` means
+
+A **binding** is a connection to one particular field in the open form. For example:
+
+```ts
+const note = form.bind("reviews.0.note");
+```
+
+This selects the first review **at the time of the call**. If that review later moves to the
+third position, `note.set(...)` still edits the same review. Keeping the text `"reviews.0.note"`
+and looking it up again later would select whoever occupies the first position then.
+
+Create bindings during component setup or before starting delayed work, and keep the returned
+object in your callback. Ridu stops that connection from being used after its target is removed,
+the source editor unmounts, or the document, content locale, schema or saved/reset form values
+are replaced. Reading/writing then throws. `binding.stale` remains safe to inspect, and
+`binding.readOnly` becomes true. Neither a timeout nor a late response may reuse that old connection
+to edit a new row/document. A new mounted editor gets new bindings.
+
+A title binding also respects the note editor's editability: the button cannot update Title while
+the source note is read-only, even if Title itself is editable. The server independently checks
+permissions on save.
+
+The operation engine assigns missing `_key` IDs to every declared array and block row, including
+rows created through the API. Keys are nonempty and unique within each list. Keep returned keys
+when editing or reordering existing rows; document duplication assigns fresh identities.
+
+`form.bind(path)` returns `PluginFieldBinding<unknown>`, because TypeScript cannot infer a value
+shape from an arbitrary string path. Check values you read and write the shape the target field
+expects. This is different from your own `field`, which has your registered decoder types.
+
+## Values, config and validation
+
+| API | Meaning |
+| --- | --- |
+| `field.value` | Latest checked form value, including unsaved edits. Objects/arrays are copies. |
+| `field.rawValue` | Copied data before decoding, useful for recovery UI when old data is unsupported. |
+| `field.set(next)` | Replace this value in the normal unsaved form. Use `null` to clear; undefined is rejected. |
+| `field.issues` | Current form/server validation issues for the field and its children. |
+| `form.get(path)` | Copy a value at its current document-root path; does not remember a row's identity. |
+| `form.snapshot()` | Copy current form values once. It is neither live state nor a server fetch. |
+
+Changing an object returned by a read does not edit the form. Call `set` with a replacement value.
+Ridu copies values supplied to `set` too, so mutating your original object afterward does not
+silently change saved or unsaved form data.
+
+`PluginFieldProps<Value, Config, Type, Input>` uses `Input = Value` by default. When the server
+accepts a different write shape from its returned data, supply `decodeInput` too. Until a save
+returns normalized data, `field.value` can contain either checked `Value` or checked `Input`.
+The host tries the output decoder first, then the supplied input decoder. Do not assume it has
+invented server-generated properties for an unsaved edit. Null/undefined reads are empty states
+handled separately from the decoders.
+
+Decoders must be synchronous and safe to run repeatedly. Value data must be plain JSON-shaped
+data: no class instances, functions, cycles or non-finite numbers. Config arrives as serialized
+Go settings and must be checked before it becomes typed component data. For a selected component,
+omit the Go configuration argument when there are no settings; no decoder or `config` prop is needed.
+Every supplied object, including `{}`, requires `decodeConfig`, and a declared decoder requires an
+object. Plugin-owned value configuration keeps its descriptor defaults and may use an empty
+object without a decoder.
+
+Let registration helpers infer the result. Their types check component props against decoder
+results; generated TypeScript checks the declared saved/write types against the Go descriptor.
+Type annotations do not execute validation, and `any`/assertions can bypass static checks. A
+poorly written decoder can still accept invalid data. Go validation and authorization remain the
+final checks on saving; UI customization does not change storage, filtering or operation rules.
+
+## Related documents and server requests
+
+`authoring` supplies Ridu's tools to a field component:
+
+- `collections`: available collection definitions, not the documents themselves.
+- `locale`: content locale, separate from the admin interface language.
+- `documentRevision`: an admin change counter for refreshing UI, not a saved `_revision` number.
+- `findDocument(collection, id, signal?)`: fetch a saved document in the current locale. It does
+  not read the current form's unsaved changes.
+- `referenceBrowser`: the related-document picker/editor. Render it and update your field in
+  `onCommit(ids)`. Return false to keep it open; otherwise it closes after acceptance. Saving a
+  related document inside the picker is a separate server operation.
+- `requestPlugin<Result>(path, body, signal?)`: POST to this renderer's paired Go plugin endpoint,
+  using a relative path such as `generate-title`. The response generic does not validate data;
+  request `unknown` and decode it when needed. This does not update your form automatically.
+
+Async authoring calls check that the field is still usable when they complete. An expired field
+rejects the result. This cannot undo server work already dispatched, and it does not choose
+between two requests made while the same field stays open. Your component must handle errors,
+cancel unnecessary requests and prevent an older response overwriting a newer result.
+
+## Ordinary fields inside a structured plugin value
+
+A plugin such as rich text can contain cards with ordinary Ridu fields inside them. The Go field
+must declare those embedded trees, cases and variants. Here, **payload** means the ordinary field
+data inside one such item, not the whole plugin value or the Payload CMS product.
+
+To edit an existing item's fields directly in the parent form, render:
+
+```svelte
+{#if selectedIdentity !== undefined && authoring.schemaForm !== undefined}
+  {@render authoring.schemaForm({ treeKey: "widgets", identity: selectedIdentity })}
+{/if}
+```
+
+The plugin provides `selectedIdentity` from its own selection UI. `treeKey` matches the Go-declared
+tree, and `identity` identifies the existing item. Ridu finds its current position and renders its
+ordinary fields. Edits immediately enter the parent form; this does not save the document.
+Removed/malformed items show recovery UI rather than another item's fields.
+
+For **Apply/Cancel**, use a temporary embedded draft:
+
+1. Call `beginSchemaDraft({ treeKey, identity })` for an existing item, or
+   `beginSchemaDraft({ treeKey, caseTag, variantSlug })` to prepare a new item with field defaults.
+2. Render `schemaDraftEditor({ draft, title, onApply, onCancel })` as a Svelte snippet.
+3. `onApply(payload)` receives checked field data. Update your plugin/editor state and serialize
+   it through `field.set`; Ridu does not insert the item into your value for you. Close the drawer
+   in your Apply/Cancel callbacks. Apply/Cancel releases the draft.
+4. Call `discard()` if you abandon a draft outside the drawer. Closing the field also cleans it up.
+
+These drafts are temporary forms, not saved document versions. They reuse Ridu's form controller
+and cannot save independently. Pending insertions or dirty drafts block outer Save until the user
+applies/cancels them. Apply checks declared field rules; executable Go validators run on parent save.
+
+Drafts follow the same item through reorder. Removal, changed source data, document/locale/schema
+or relevant access changes expire them; reopen instead of applying old data.
+`schemaIssues({ treeKey, identity })` supplies current issues for an item's badge.
+`copySchemaPayload({ treeKey, caseTag, variantSlug }, payload)` copies ordinary field data with
+fresh IDs for schema-declared nested rows/items. Your plugin still manages the copied outer item.
+The host interprets only declared schema structure, not arbitrary JSON with similar property names.
+
+See the [Outline fixture](../../tests/contracts/admin_app/outline-field.svelte) for a compact
+embedded-form example and the [rich-text package](../plugin-richtext/) for an editor integration.
+
+## Other admin UI
+
+Both paired plugins and `defineAdmin` can register `routes`, `dashboard`, `login`, `account`,
+`navigation`, `logoutButton`, `views`, `branding`, `shell`, `providers`, `listCells`,
+`documentActions` and `documentViews`.
+
+Replacement login/account/navigation/core-view components receive a `defaultView` snippet.
+Render `{@render defaultView()}` to keep the normal screen inside your wrapper. Providers must
+render their `defaultView` to include the nested admin. Host methods perform login/logout,
+refreshes and notifications; application-specific operations use the generated SDK.
+
+Collection/global view replacements may target one resource or act as a fallback. An exact
+resource match wins over its fallback; duplicate targets and exclusive replacements fail.
+Table cells and document action/view props contain document data, not a field-form binding.
+Use their hosts to refresh after your operation; `refresh()` fetches data, it does not save edits.
+
+Paired plugins register row headings with `defineRowLabelPlugin({ key, componentKey, component })`
+and Go `.Admin(field.Admin{RowLabel: field.PluginComponent(key, componentKey, config)})`. The heading
+receives a copied, deeply frozen `row` and a 1-based visual `rowNumber`. Its config is unknown: validate it inside the component. Application-local
+headings use `defineRowLabel`, adding a config decoder only when settings are supplied, and select
+`.Admin(field.Admin{RowLabel: field.Component("app:name", config)})` in Go. Use
+`field.Admin{RowLabelPath: path}` for array headings based on one child field.
+
+Use `defineAdminMessages` for interface messages. Catalog keys have no prefix; refer to them as
+`plugin.editorial-tools:messageName` for that plugin or `app:messageName` for the application.
+
+## Local field editors and visual wrappers
+
+Local editors support string, number, boolean, text-list, and number-list value shapes.
+`FieldEditorProps<"text-list">` uses `string[]`; `FieldEditorProps<"number-list">` uses `number[]`.
+Lists remain one field occurrence and arrays are copied on reads and writes. The host rejects
+mixed types, non-finite numbers, and null elements at runtime. A built-in numeric control can retain
+unfinished input in its form draft; a custom binding rejects such values instead of claiming they
+are `number[]`.
+
+```ts
+const editor = defineFieldEditor({ type: "text-list", component: SellingPoints });
+// SellingPoints.svelte receives FieldEditorProps<"text-list"> and can call:
+// field.set([...(field.value ?? []), "Solid oak"]);
+```
+
+Application-local editors support text, textarea, email, date, code, number and checkbox fields.
+They receive `FieldEditorProps<Type, Config>` and their own `field.set`, plus document reads and
+related-document browsing/lookup. They cannot bind another field for writing or call plugin
+endpoints, and do not expose embedded draft forms. Advanced `AdminComponent` renderers stay on
+the paired-plugin API. Packaged distribution of application-local components is still deferred.
+
+`Field` from `@riducms/plugin/editor/field` is an optional wrapper for a local field editor's label,
+description and issues. `FieldFrame` from `@riducms/ui` is the underlying visual component, also
+usable by plugin editors. Neither owns form values or registration. Your input still supplies its
+value, read-only state and change handler. Importing only editor types does not import this UI.
+
+## Checks and further reading
+
+Run your plugin's TypeScript/Svelte checks, then the application's `ridu check` and production
+`ridu build`. Ridu checks actual registrations against the resolved Go schema, including field
+selection, decoder settings, duplicate registrations and Go/admin compatibility. These checks
+compile with the application's production Vite configuration without starting a browser or dev
+server. They do not prove every future field value or arbitrary callback is correct: test those
+interactions as well.
+
+For custom UI, use the documented editor contracts and run the checks above in the consuming
+application so its Svelte and TypeScript configuration checks the complete integration.
+
+- [Plugin fields and editors](https://riducms.com/docs/fields/plugin/)
+- [Building plugins](https://riducms.com/docs/plugins/)
+- [Application-local field components](https://riducms.com/docs/custom-components/field-components/)

package/package.json

@@ -3,12 +3,17 @@
 		"url": "https://github.com/riducms/ridu/issues"
 	},
 	"dependencies": {
-		"@riducms/protocol": "0.1.5",
-		"@riducms/translations": "0.1.5"
+		"@riducms/protocol": "0.2.0",
+		"@riducms/translations": "0.2.0",
+		"@riducms/ui": "0.2.0"
 	},
 	"description": "Public TypeScript contracts for statically registered Ridu admin plugins.",
 	"exports": {
-		".": "./src/index.ts"
+		".": "./src/index.ts",
+		"./admin": "./src/admin.ts",
+		"./authoring/v1": "./src/authoring/v1.ts",
+		"./editor": "./src/editor/index.ts",
+		"./editor/field": "./src/editor/field.ts"
 	},
 	"files": [
 		"src",
@@ -34,5 +39,5 @@
 		"test": "bun test"
 	},
 	"type": "module",
-	"version": "0.1.5"
+	"version": "0.2.0"
 }

package/src/admin.ts

@@ -0,0 +1,171 @@
+import { bindSchemaManifest } from "@riducms/protocol";
+import { resolveBlockTypes } from "@riducms/protocol";
+import { validatePluginManifest, validatePluginRegistrations } from "./plugin-registry";
+import { isRegisteredRowLabel, type RegisteredRowLabel } from "./local-row-label";
+import { localEditorReference } from "./editor/registry";
+import type { SchemaField } from "@riducms/protocol";
+import type { SchemaManifest } from "@riducms/protocol";
+import type { TranslationLanguage } from "@riducms/translations";
+import type { PluginMessageCatalog } from "./i18n";
+import { resolveAdminExtensions, type AdminContributions, type AdminPlugin } from "./plugin";
+import {
+	validateAdminEditors,
+	validateFieldEditorRegistrations,
+	type FieldEditorConfig,
+} from "./editor/registry";
+
+/**
+ * Settings for your application's admin, exported from `admin/src/admin.config.ts`.
+ * Register your custom components here. Keep `generatedAdminPlugins` in `plugins`
+ * to load installed plugins such as rich text. Use `fields` to replace inputs for
+ * text, textarea, email, date, code, number and checkbox fields.
+ */
+export interface AdminConfig extends AdminContributions, FieldEditorConfig {
+	/** Custom array or block row headings selected by Go `field.Admin{RowLabel: field.Component("app:name")}`. */
+	rowLabels?: Readonly<Record<`app:${string}`, RegisteredRowLabel>>;
+	/** Installed admin plugins, normally `generatedAdminPlugins` from Ridu's generated file. */
+	plugins?: readonly AdminPlugin[];
+	/** Interface messages made with `defineAdminMessages`; refer to them as `app:messageName`. */
+	messages?: PluginMessageCatalog;
+	/** Bundled admin UI language catalogs. These are separate from document content locales. */
+	languages?: readonly TranslationLanguage[];
+}
+
+/**
+ * Configure your application's admin components and installed plugins.
+ *
+ * Export the result as the default export of `admin/src/admin.config.ts`. Keep
+ * `plugins: generatedAdminPlugins` to load installed packages such as rich text.
+ * Add `fields` for inputs made with `defineFieldEditor`, `rowLabels` for headings
+ * made with `defineRowLabel`, or options such as `dashboard`, `routes`, and
+ * `documentActions` for other parts of the admin. All options are optional.
+ *
+ * Application field and row-label keys use `app:name`; select the same key in Go
+ * with `field.Component`. A plugin's new field types instead belong inside its
+ * `defineAdminPlugin({ fields: ... })` registration.
+ *
+ * Installed plugins load first, then your application components. Entries need
+ * unique keys, and only one component may replace a given screen or location.
+ * Run `ridu check` to also check selections, field types, and settings from Go.
+ * These checks also run when building and starting the admin.
+ *
+ * @param config The installed plugins, custom components, and interface translations.
+ * @returns The same configuration object after registration checks. The admin
+ * reads it when starting; calling this function does not mount any components.
+ * @throws If registrations, keys, or replacement locations conflict.
+ * @example
+ * ```ts
+ * import { defineAdmin } from '@riducms/plugin/admin';
+ * import { generatedAdminPlugins } from './ridu.plugins.generated';
+ * import WelcomePanel from './components/welcome-panel.svelte';
+ *
+ * export default defineAdmin({
+ *   plugins: generatedAdminPlugins,
+ *   dashboard: [{ key: 'welcome', component: WelcomePanel, position: 'before' }]
+ * });
+ * ```
+ */
+export function defineAdmin(config: AdminConfig): AdminConfig {
+	if ("fieldPlugins" in config)
+		throw new Error(
+			"Application fieldPlugins are not supported; use a field-owned Editor component or a paired advanced field plugin."
+		);
+	validatePluginRegistrations(config.plugins ?? []);
+	validateFieldEditorRegistrations(config);
+	for (const [reference, label] of Object.entries(config.rowLabels ?? {})) {
+		if (!localEditorReference.test(reference) || !isRegisteredRowLabel(label))
+			throw new Error(`Row label ${reference} must use an app:name reference and defineRowLabel.`);
+	}
+	resolveAdminExtensions(config.plugins ?? [], config);
+	return config;
+}
+
+/**
+ * Check admin registrations against Ridu's resolved Go schema. Used by Ridu's build
+ * tooling and admin startup; application authors normally run `ridu check` instead.
+ * Set `completeManifest` only with the full schema from Go: runtime schemas can omit
+ * resources the current user cannot access, so absence there does not prove a typo.
+ * Throws with the affected registration or field when a selection/config is invalid.
+ */
+export function validateAdminConfig(
+	config: AdminConfig,
+	manifest: Pick<SchemaManifest, "collections" | "globals" | "blocks"> &
+		Partial<Pick<SchemaManifest, "plugins">>,
+	options: { completeManifest?: boolean } = {}
+): void {
+	defineAdmin(config);
+	validateAdminEditors(config, manifest);
+	validatePluginManifest(config.plugins ?? [], manifest, options.completeManifest === true);
+	bindSchemaManifest(manifest);
+	const inspect = (fields: readonly SchemaField[], owner: string) => {
+		for (const field of fields) {
+			const selection = field.nested?.rowLabelComponent;
+			if (selection?.reference !== undefined) {
+				const reference = selection.reference;
+				if (
+					!localEditorReference.test(reference) ||
+					selection.plugin !== undefined ||
+					selection.component !== undefined ||
+					(field.type !== "array" && field.type !== "blocks")
+				)
+					throw new Error(`${owner}.${field.path}: invalid local row label selection.`);
+				const label = config.rowLabels?.[reference as `app:${string}`];
+				if (label === undefined)
+					throw new Error(
+						`${owner}.${field.path}: row label ${reference} is not registered in admin/src/admin.config.ts.`
+					);
+				try {
+					label.decode(field);
+				} catch (error) {
+					throw new Error(
+						`${owner}.${field.path}: ${error instanceof Error ? error.message : String(error)}`
+					);
+				}
+			}
+			for (const tree of field.plugin?.embeddedTrees ?? [])
+				for (const item of tree.cases)
+					for (const variant of resolveBlockTypes(item)) inspect(variant.fields, owner);
+			if (field.nested !== undefined) inspect(field.nested.fields, owner);
+			for (const block of resolveBlockTypes(field.blocks) ?? []) inspect(block.fields, owner);
+		}
+	};
+	for (const collection of manifest.collections) inspect(collection.fields, collection.slug);
+	for (const global of manifest.globals ?? []) inspect(global.fields, global.slug);
+	// Runtime manifests are permission-filtered; only build checks can prove target absence.
+	if (!options.completeManifest) return;
+	const collections = new Map(manifest.collections.map((item) => [item.slug, item]));
+	const globals = new Set((manifest.globals ?? []).map((item) => item.slug));
+	const extensions = resolveAdminExtensions(config.plugins ?? [], config);
+	for (const cell of extensions.listCells) {
+		const collection = collections.get(cell.collection);
+		if (!collection?.fields.some((field) => field.name === cell.field || field.path === cell.field))
+			throw new Error(
+				`Admin list cell ${cell.key} selects unknown field ${cell.collection}.${cell.field}.`
+			);
+	}
+	for (const view of extensions.views) {
+		if ("collection" in view && view.collection !== undefined && !collections.has(view.collection))
+			throw new Error(`Admin core view ${view.key} selects unknown collection ${view.collection}.`);
+		if ("global" in view && view.global !== undefined && !globals.has(view.global))
+			throw new Error(`Admin core view ${view.key} selects unknown global ${view.global}.`);
+	}
+	for (const action of extensions.documentActions) {
+		if (action.collection !== undefined && !collections.has(action.collection))
+			throw new Error(
+				`Admin document action ${action.key} selects unknown collection ${action.collection}.`
+			);
+	}
+	for (const view of extensions.documentViews) {
+		if (
+			view.collection !== undefined &&
+			!collections.has(view.collection) &&
+			!globals.has(view.collection)
+		)
+			throw new Error(
+				`Admin document view ${view.key} selects unknown resource ${view.collection}.`
+			);
+	}
+}
+
+export { defineRowLabel } from "./local-row-label";
+export type { RowLabelProps, RowLabelDefinition, RegisteredRowLabel } from "./local-row-label";

package/src/authoring/v1.ts

@@ -0,0 +1,71 @@
+import type { AdminPlugin } from "../plugin";
+import { validatePluginRegistrations } from "../plugin-registry";
+
+export { definePluginField, defineFieldComponent } from "../field";
+export type {
+	PluginFieldBinding,
+	PluginFieldProps,
+	PluginForm,
+	PluginFieldRegistration,
+} from "../field";
+
+/** This literal belongs to this versioned entry point, never to the consuming runtime. */
+const authoringAPIVersion = 1;
+
+/**
+ * Define the fields, pages, and other admin components supplied by a Go plugin.
+ *
+ * Export the result from the plugin's JavaScript package. The Go descriptor's
+ * `Admin.Package` and `Admin.Export` identify that package and export. Applications
+ * install both packages and load the generated plugins with `defineAdmin`.
+ *
+ * Required options are `key`, matching the Go plugin's key, and `pairingVersion`,
+ * a positive integer matching its `Admin.PairingVersion`. Increase the latter when
+ * an older Go or admin package would no longer work with the other. This import
+ * supplies `apiVersion: 1`; do not pass or overwrite that property.
+ *
+ * Use `fields` for the default editors of new Go field types. Each map key matches
+ * a Go `PluginFieldType.Key`, and each value is returned by `definePluginField`.
+ * Use `components` for alternative editors made with `defineFieldComponent`,
+ * selected explicitly in Go with `field.PluginComponent`. The other options add
+ * pages, dashboard panels, navigation, and the UI described by `AdminContributions`.
+ *
+ * @param plugin The plugin key, compatibility version, and components to register.
+ * @returns A frozen copy with `apiVersion: 1`, preserving inferred field value and
+ * input types. Export it; do not call its components yourself or edit its maps.
+ * @throws If required metadata, field registrations, or component keys are invalid.
+ * Run `ridu check` in an application to also check the Go descriptor and selections.
+ * @example
+ * ```ts
+ * import { defineAdminPlugin, definePluginField } from '@riducms/plugin/authoring/v1';
+ * import ColorField from './color-field.svelte';
+ * import { decodeColor } from './value';
+ *
+ * export const colorAdminPlugin = defineAdminPlugin({
+ *   key: 'color',
+ *   pairingVersion: 1,
+ *   fields: {
+ *     color: definePluginField({ component: ColorField, decodeValue: decodeColor })
+ *   }
+ * });
+ * ```
+ */
+export function defineAdminPlugin<const Plugin extends Omit<AdminPlugin, "apiVersion">>(
+	plugin: Plugin & { apiVersion?: never }
+): Plugin & { readonly apiVersion: 1 } {
+	if ("apiVersion" in plugin)
+		throw new Error(
+			"The authoring import owns apiVersion; do not restamp another plugin definition."
+		);
+	const result = Object.freeze({
+		...plugin,
+		...(plugin.fields === undefined ? {} : { fields: Object.freeze({ ...plugin.fields }) }),
+		...(plugin.components === undefined
+			? {}
+			: { components: Object.freeze({ ...plugin.components }) }),
+		apiVersion: authoringAPIVersion,
+	});
+	const definition: Omit<AdminPlugin, "apiVersion"> = plugin;
+	validatePluginRegistrations([{ ...definition, apiVersion: authoringAPIVersion }]);
+	return result;
+}