@riducms/plugin 0.2.3 → 0.3.0

package/README.md

@@ -7,14 +7,22 @@ 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 |
+Collection cards can use `listResultsRenderers` without replacing Ridu's list controller. Custom dashboards
+can use `withAdminLoader` with a generated Go loader reference and `AdminLoaderProps<Data>`.
+The same helper pairs loaders with literal custom routes and collection/global/not-found replacement
+views. Results renderers own their links through `list.documentHref(document)` and `Link` from
+`@riducms/admin/routing`.
+See [custom admin views and data](https://riducms.com/docs/custom-components/custom-views/) for the complete
+Go-to-Svelte contract and its deliberate limits.
+
+| 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 `fieldEditors` 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({ fieldEditors })`; 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.
@@ -54,27 +62,39 @@ unknown data, returns the shape your component expects, or throws a useful error
 
 ```ts
 export interface NoteValue {
-  text: string;
+	text: string;
 }
 export interface NoteConfig {
-  copyTo: string;
+	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 };
+	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 };
+	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 };
 }
 ```
 
@@ -82,35 +102,34 @@ Then write `note-field.svelte`:
 
 ```svelte
 <script lang="ts">
-  import type { PluginFieldProps } from "@riducms/plugin/authoring/v1";
-  import type { NoteValue, NoteConfig } from "./value";
+	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);
+	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>
+	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}
+	{#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)}
+	type="button"
+	disabled={field.readOnly || title.readOnly || !field.value?.text}
+	onclick={() => title.set(field.value?.text ?? null)}
 >
-  Use note as title
+	Use note as title
 </button>
 ```
 
@@ -122,15 +141,15 @@ 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,
-    }),
-  },
+	key: "editorial-tools",
+	pairingVersion: 1,
+	fields: {
+		"review-note": definePluginField({
+			component: NoteField,
+			decodeValue: decodeNote,
+			decodeConfig: decodeNoteConfig,
+		}),
+	},
 });
 ```
 
@@ -185,14 +204,14 @@ expects. This is different from your own `field`, which has your registered deco
 
 ## 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. |
+| 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. |
+| `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
@@ -226,11 +245,17 @@ final checks on saving; UI customization does not change storage, filtering or o
 - `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.
+- `canCreateDocument(collection)`: a live presentation hint for showing collection create controls.
+  The reference browser and operation engine still authorize the actual create operation.
 - `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.
+  `onCommit(ids, collectionSlug)`. Supply `collections` to offer a collection selector; switching
+  clears the list query and uncommitted selection. The admin offers only collections the current
+  session can read and does not browse or commit when none are available. A static `optionFilter`
+  applies to every offered collection; pass a collection-aware resolver when their filter fields
+  differ. 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.
@@ -250,7 +275,7 @@ 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 })}
+	{@render authoring.schemaForm({ treeKey: "widgets", identity: selectedIdentity })}
 {/if}
 ```
 
@@ -264,11 +289,11 @@ name input and its feedback:
 
 ```svelte
 {#if authoring.schemaHeader !== undefined}
-  {@render authoring.schemaHeader({
-    treeKey: "widgets",
-    identity: selectedIdentity,
-    onChange: ({ field, value }) => updateWidgetField(selectedIdentity, field, value),
-  })}
+	{@render authoring.schemaHeader({
+		treeKey: "widgets",
+		identity: selectedIdentity,
+		onChange: ({ field, value }) => updateWidgetField(selectedIdentity, field, value),
+	})}
 {/if}
 ```
 
@@ -305,15 +330,20 @@ embedded-form example and the [rich-text package](../plugin-richtext/) for an ed
 
 ## Other admin UI
 
-Both paired plugins and `defineAdmin` can register `routes`, `dashboard`, `login`, `account`,
-`navigation`, `logoutButton`, `views`, `branding`, `shell`, `providers`, `listCells`,
-`documentActions` and `documentViews`.
+Both paired plugins and `defineAdmin` can register `routes`, `dashboardPanels`, `login`, `account`,
+`navigation`, `logoutButton`, `coreViews`, `branding`, `shellSlots`, `providers`,
+`listCellRenderers`, `listResultsRenderers`, `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.
 
+`logoutButton` replaces the sign-out control in the navigation footer and receives `host.logout()`.
+The Payload-style shell places this control there rather than in the account menu. A full navigation
+replacement should render its `defaultView` when it wants to retain the framework navigation and
+logout control.
+
 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.
@@ -367,6 +397,9 @@ 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.
 
+The [custom components guide](https://riducms.com/docs/custom-components/) explains when a
+component is a routed view, form-bound editor, read-only renderer, shell slot, or reusable primitive.
+
 - [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,9 +3,10 @@
 		"url": "https://github.com/riducms/ridu/issues"
 	},
 	"dependencies": {
-		"@riducms/protocol": "0.2.3",
-		"@riducms/translations": "0.2.3",
-		"@riducms/ui": "0.2.3"
+		"@riducms/protocol": "0.3.0",
+		"@riducms/sdk": "0.3.0",
+		"@riducms/translations": "0.3.0",
+		"@riducms/ui": "0.3.0"
 	},
 	"description": "Public TypeScript contracts for statically registered Ridu admin plugins.",
 	"exports": {
@@ -39,5 +40,5 @@
 		"test": "bun test"
 	},
 	"type": "module",
-	"version": "0.2.3"
+	"version": "0.3.0"
 }

package/src/admin-extensions/documents.ts

@@ -0,0 +1,42 @@
+import type { OperationCapabilities, SchemaCollection } from "@riducms/protocol";
+import type { Component } from "svelte";
+
+import type { FieldDocument } from "../authoring";
+import type { AdminI18n, ExtensionTranslationKey } from "../i18n";
+import type { AdminExtensionNotificationTone } from "./shared";
+
+/** Tools for a document action or extra document view 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/views; use the generated SDK for application-specific operations. */
+export interface AdminDocumentExtensionProps {
+	collection: SchemaCollection;
+	document: FieldDocument;
+	host: AdminDocumentExtensionHost;
+	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 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?: ExtensionTranslationKey;
+	/** Collection or global slug; omit to show for every collection and global. */
+	collection?: string;
+	component: Component<AdminDocumentExtensionProps>;
+}

package/src/admin-extensions/index.ts

@@ -0,0 +1,81 @@
+import type { PluginMessageCatalog } from "../i18n";
+import type { RowLabelPlugin } from "../row-label";
+import type { AdminDocumentAction, AdminDocumentView } from "./documents";
+import type { AdminListCellRenderer, AdminListResultsRenderer } from "./lists";
+import type {
+	AdminBrandComponent,
+	AdminLogoutButton,
+	AdminNavigationComponent,
+	AdminProvider,
+	AdminShellSlot,
+} from "./shell";
+import type {
+	AdminAccountComponent,
+	AdminCoreView,
+	AdminDashboardPanel,
+	AdminLoginComponent,
+	AdminRoute,
+} from "./views";
+
+export * from "./documents";
+export * from "./lists";
+export * from "./shared";
+export * from "./shell";
+export * from "./views";
+
+/**
+ * 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 AdminRoute[];
+	/** Panels composed into or replacing the authenticated dashboard. */
+	dashboardPanels?: 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 navigation footer. */
+	logoutButton?: AdminLogoutButton;
+	/** Wraps or replaces framework collection, global, and not-found views. */
+	coreViews?: readonly AdminCoreView[];
+	/** Replaces framework-owned brand graphics at exact shell surfaces. */
+	branding?: readonly AdminBrandComponent[];
+	/** Adds components to explicit global shell slots. */
+	shellSlots?: readonly AdminShellSlot[];
+	/** Wraps the admin in statically ordered Svelte context providers. */
+	providers?: readonly AdminProvider[];
+	/** Collection list cells rendered for exact collection/field pairs. */
+	listCellRenderers?: readonly AdminListCellRenderer[];
+	/** Replace only the results layout; Ridu retains list loading, controls and pagination. */
+	listResultsRenderers?: readonly AdminListResultsRenderer[];
+	/** Actions rendered alongside framework-owned document actions. */
+	documentActions?: readonly AdminDocumentAction[];
+	/** Read-only or operational views rendered beside Edit and API. */
+	documentViews?: readonly AdminDocumentView[];
+}
+
+/** Checked registrations collected for Ridu's admin runtime. Normally consumed by generated code. */
+export interface ResolvedAdminExtensions {
+	rowLabels: readonly RowLabelPlugin[];
+	routes: readonly AdminRoute[];
+	dashboardPanels: readonly AdminDashboardPanel[];
+	login: readonly AdminLoginComponent[];
+	account: readonly AdminAccountComponent[];
+	navigation: readonly AdminNavigationComponent[];
+	logoutButton: AdminLogoutButton | undefined;
+	coreViews: readonly AdminCoreView[];
+	branding: readonly AdminBrandComponent[];
+	shellSlots: readonly AdminShellSlot[];
+	providers: readonly AdminProvider[];
+	listCellRenderers: readonly AdminListCellRenderer[];
+	listResultsRenderers: readonly AdminListResultsRenderer[];
+	documentActions: readonly AdminDocumentAction[];
+	documentViews: readonly AdminDocumentView[];
+	messages: Readonly<Record<string, PluginMessageCatalog>>;
+	applicationMessages: PluginMessageCatalog | undefined;
+}

package/src/admin-extensions/lists.ts

@@ -0,0 +1,56 @@
+import type { SchemaCollection, SchemaField } from "@riducms/protocol";
+import type { Component } from "svelte";
+
+import type { FieldDocument } from "../authoring";
+import type { AdminI18n, ExtensionTranslationKey } from "../i18n";
+
+/** Live, read-only projections and selection commands from Ridu's list controller. */
+export interface AdminCollectionList {
+	readonly documents: readonly FieldDocument[];
+	readonly selectedIDs: ReadonlySet<string>;
+	readonly selectionEnabled: boolean;
+	readonly allOnPageSelected: boolean;
+	readonly pageSelectionIndeterminate: boolean;
+	toggleDocument(id: string, selected: boolean): void;
+	togglePage(selected: boolean): void;
+	title(document: FieldDocument): string;
+	/** Router-root destination with an encoded ID and the current content locale. */
+	documentHref(document: FieldDocument): string;
+}
+
+export interface AdminListResultsRendererProps {
+	collection: SchemaCollection;
+	list: AdminCollectionList;
+	i18n: AdminI18n;
+}
+
+/** Collection-specific results layout. Trash retains its framework restore/delete controls. */
+export interface AdminListResultsRenderer {
+	key: string;
+	collection: string;
+	component: Component<AdminListResultsRendererProps>;
+}
+
+/** Data for displaying a collection table cell. This is not an editable document-form binding. */
+export interface AdminListCellRendererProps {
+	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 AdminListCellRenderer {
+	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;
+	/** Optional translation key from this plugin's messages, or app:... for application entries. */
+	labelKey?: ExtensionTranslationKey;
+	component: Component<AdminListCellRendererProps>;
+}

package/src/admin-extensions/shared.ts

@@ -0,0 +1,48 @@
+import type { SchemaManifest } from "@riducms/protocol";
+import type { AdminLoader } from "@riducms/sdk";
+import type { Component } from "svelte";
+
+import type { FieldDocument } from "../authoring";
+import type { AdminI18n } from "../i18n";
+
+/** 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;
+}
+
+export type AdminExtensionNotificationTone = "success" | "error";
+
+/** Prepared application data and the mounted view's explicit refresh operation. */
+export interface AdminLoaderProps<Data> {
+	data: Data;
+	refresh: () => Promise<void>;
+	refreshing: boolean;
+}
+
+export type AdminViewComponent<Props extends object> =
+	| { component: Component<Props> | Component; loader?: never }
+	| {
+			component: Component<Props & AdminLoaderProps<unknown>>;
+			loader: AdminLoader<never, unknown>;
+	  };
+
+/** Spread this pairing into a dashboard panel, custom route or core-view registration. */
+export function withAdminLoader<Input, Data, Props extends AdminLoaderProps<NoInfer<Data>>>(
+	loader: AdminLoader<Input, Data>,
+	component: Component<Props>
+): {
+	loader: AdminLoader<never, unknown>;
+	component: Component<Omit<Props, keyof AdminLoaderProps<unknown>> & AdminLoaderProps<unknown>>;
+} {
+	// Erase the paired generic only after checking both sides. The host decodes
+	// with this same loader before handing its output to this same component.
+	return { loader, component } as unknown as {
+		loader: AdminLoader<never, unknown>;
+		component: Component<Omit<Props, keyof AdminLoaderProps<unknown>> & AdminLoaderProps<unknown>>;
+	};
+}

package/src/admin-extensions/shell.ts

@@ -0,0 +1,72 @@
+import type { Component, Snippet } from "svelte";
+
+import type { AdminI18n } from "../i18n";
+import type { AdminExtensionProps } from "./shared";
+
+/** 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 {
+	/** 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>;
+	position: AdminNavigationPosition;
+}
+
+export interface AdminLogoutExtensionHost {
+	/** End the current session and return to sign-in. Await this instead of only changing local UI. */
+	logout: () => Promise<void>;
+}
+
+export interface AdminLogoutButtonProps extends AdminExtensionProps {
+	host: AdminLogoutExtensionHost;
+}
+
+/** Replace the navigation footer's sign-out button; call the supplied `host.logout()` on activation. */
+export interface AdminLogoutButton {
+	key: string;
+	component: Component<AdminLogoutButtonProps>;
+}
+
+export type AdminBrandSurface = "loginLogo" | "navigationLogo" | "accountAvatar";
+
+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;
+	component: Component<AdminBrandComponentProps>;
+}
+
+export type AdminShellSlotPosition = "header" | "actions" | "settingsMenu";
+
+export interface AdminShellSlotProps extends AdminExtensionProps {
+	position: AdminShellSlotPosition;
+}
+
+/** Add UI to the global header, actions area or account settings menu in registration order. */
+export interface AdminShellSlot {
+	key: string;
+	position: AdminShellSlotPosition;
+	component: Component<AdminShellSlotProps>;
+}
+
+export interface AdminProviderProps {
+	/** 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>;
+}