@plumix/core 0.1.0

package/dist/plugin/manifest.d.ts

@@ -0,0 +1,1539 @@
+import type { BlockNode, BlockPattern, BlockSpec, BlockVariation, MarkSpec, PatternInsertMode, PatternPreview, PatternTarget, ShortcodeSpec, ThemeBreakpoints, ThemeTokens } from "@plumix/blocks";
+import type { EntryTypeCapabilityOverrides, TermTaxonomyCapabilityOverrides } from "../auth/rbac.js";
+import type { AppContext } from "../context/app.js";
+import type { UserRole } from "../db/schema/users.js";
+import type { Label } from "../i18n/label.js";
+import type { ResolvedI18n, ResolvedLocale } from "../i18n/locale-registry.js";
+import type { McpTool } from "../mcp/tool.js";
+import type { RouteIntent } from "../route/intent.js";
+import type { RegisteredTemplateDep } from "../template-deps.js";
+import type { PluginI18nSlot } from "./define.js";
+import type { RegisteredLookupAdapter } from "./lookup.js";
+/**
+ * WP-style per-type chrome labels shared between `EntryTypeOptions.labels`
+ * and `EntryTypeManifestEntry.labels`. Every field is optional on the
+ * options side; `buildManifest` resolves the cascade server-side so the
+ * projection (`ResolvedEntryTypeLabels`) ships every key fully populated.
+ * Consumers read `entry.labels.editItem` directly — no per-call-site
+ * fallback boilerplate.
+ *
+ * Key set mirrors WP's `register_post_type()` labels table where the
+ * mental model carries (`searchItems`, `notFound`, `addNewItem`, etc.)
+ * plus plumix-specific SPA chrome (`loadingItems`, `loadErrorItems`,
+ * `untitledItem`, `noMatch`) that PHP-WP doesn't need. Deliberately
+ * excludes `menu_name` (already covered by `label`/`plural`),
+ * `name_admin_bar` (plumix has no admin bar), media-specific keys
+ * (`featured_image`, `insert_into_item`, …) that belong on the media
+ * plugin, and tag-cloud affordances (`popular_items`, `most_used`)
+ * that plumix's picker UX doesn't surface.
+ */
+export interface EntryTypeLabels {
+    readonly singular?: Label;
+    readonly plural?: Label;
+    /** "Add New" — short-form CTA for the admin bar quick-create overflow. */
+    readonly addNew?: Label;
+    /** "Add Post" — primary create CTA on list pages and slash menu. */
+    readonly addNewItem?: Label;
+    /** "Edit Post" — list-table row action and editor heading. */
+    readonly editItem?: Label;
+    /** "New Post" — quick-create affordance distinct from `addNewItem`. */
+    readonly newItem?: Label;
+    /** "View Post" — list-table row action and post-save toast link. */
+    readonly viewItem?: Label;
+    /** "View Posts" — plural archive-link variant of `viewItem`. */
+    readonly viewItems?: Label;
+    /** "Search Posts…" — list-page search input placeholder. */
+    readonly searchItems?: Label;
+    /** "No posts yet" — list-page empty state title (no rows registered). */
+    readonly notFound?: Label;
+    /** "No posts found in Trash" — trash view empty state. */
+    readonly notFoundInTrash?: Label;
+    /** "Loading posts" — aria-busy state during list fetch. */
+    readonly loadingItems?: Label;
+    /** "Couldn't load posts. Try again." — list-page fetch-failure banner. */
+    readonly loadErrorItems?: Label;
+    /** "All posts" — "all-types" filter chip label. */
+    readonly allItems?: Label;
+    /** "No posts match" — empty state after a search returns zero rows. */
+    readonly noMatch?: Label;
+    /** "Parent Post" — hierarchical parent picker option label. */
+    readonly parentItem?: Label;
+    /** "Parent Post:" — colon-suffixed variant for form labels. */
+    readonly parentItemColon?: Label;
+    /** "Untitled Post" — reference-picker label when an entry has no title. */
+    readonly untitledItem?: Label;
+    /** "Move post to trash?" — confirmation prompt on trash action. */
+    readonly moveToTrash?: Label;
+    /** "Post updated" — toast after autosave or explicit save. */
+    readonly itemUpdated?: Label;
+    /** "Post published" — toast after first publish. */
+    readonly itemPublished?: Label;
+    /** "Post published privately" — toast for private visibility. */
+    readonly itemPublishedPrivately?: Label;
+    /** "Post scheduled" — toast after scheduling a future publish. */
+    readonly itemScheduled?: Label;
+    /** "Post moved to trash" — toast after trash action completes. */
+    readonly itemTrashed?: Label;
+    /** "Post reverted to draft" — toast after unpublish. */
+    readonly itemRevertedToDraft?: Label;
+    /** "Posts list" — SR-only region label for the data table. */
+    readonly itemsList?: Label;
+    /** "Posts list navigation" — SR-only region label for pagination. */
+    readonly itemsListNavigation?: Label;
+    /** "Filter posts list" — SR-only label for the filter row. */
+    readonly filterItemsList?: Label;
+}
+export interface EntryTypeOptions {
+    readonly label: Label;
+    /**
+     * Human-readable label variants. `plural` also drives the admin URL slug
+     * (`/entries/<slugified-plural>`) unless overridden; omit it and the slug
+     * falls back to `${name}s`, which is acceptable for English-named types
+     * but surfaces an "anglos" for `name: "angle"` etc. — plugins with
+     * irregular plurals should set `labels.plural` explicitly.
+     *
+     * The other keys mirror WordPress's `register_post_type()` labels table:
+     * per-type chrome strings the admin would otherwise produce by
+     * lowercase-noun substitution. Substitution breaks in languages with
+     * gender/case agreement (DE, RU, PL, UK, AR), and lowercasing translated
+     * nouns is wrong in DE (Beiträge → beiträge is a typo). Each label is
+     * optional and the admin falls back to a generic noun-less catalog
+     * string when missing.
+     */
+    readonly labels?: EntryTypeLabels;
+    readonly description?: string;
+    readonly supports?: readonly string[];
+    readonly termTaxonomies?: readonly string[];
+    readonly isHierarchical?: boolean;
+    /** Master visibility switch; defaults to `true`. Cascades to `showUI`/`showInSidebar`/`excludeFromGenericRpc`/`excludeFromSearch` when those are unset. */
+    readonly isPublic?: boolean;
+    readonly showUI?: boolean;
+    readonly showInSidebar?: boolean;
+    readonly excludeFromGenericRpc?: boolean;
+    readonly excludeFromSearch?: boolean;
+    readonly hasArchive?: boolean | string;
+    readonly rewrite?: {
+        readonly slug?: string;
+        readonly isHierarchical?: boolean;
+    };
+    readonly capabilityType?: string;
+    readonly capabilities?: EntryTypeCapabilityOverrides;
+    readonly priority?: number;
+    readonly menuIcon?: string;
+    /** Synonyms the command palette matches in addition to the sidebar label. */
+    readonly keywords?: readonly Label[];
+    /**
+     * Per-type versioning policy. Only honored when `supports` includes
+     * `"revisions"`. `maxRevisions` caps how many revision rows are
+     * retained per live entry (default 25); `autosaveIntervalSeconds`
+     * shapes the editor's autosave cadence (default 60).
+     */
+    readonly versioning?: {
+        readonly maxRevisions?: number;
+        readonly autosaveIntervalSeconds?: number;
+    };
+    /** Page size for this type's archive route. Default 20. */
+    readonly archivePerPage?: number;
+}
+/**
+ * WP-style per-type chrome labels for term taxonomies. Same cascade
+ * semantics as `EntryTypeLabels` — `buildManifest` resolves into
+ * `ResolvedTermTaxonomyLabels` server-side. Terms always have a
+ * server-supplied `name` so `untitledItem` doesn't apply here.
+ */
+export interface TermTaxonomyLabels {
+    readonly singular?: Label;
+    /** "Categories" — plural form (symmetric with `EntryTypeLabels.plural`). */
+    readonly plural?: Label;
+    /** "Add New" — short-form CTA paired with `addNewItem`. */
+    readonly addNew?: Label;
+    /** "Add Category" — primary create CTA. */
+    readonly addNewItem?: Label;
+    /** "Edit Category" — term-edit form heading. */
+    readonly editItem?: Label;
+    /** "View Category" — list-table row action linking to the public archive. */
+    readonly viewItem?: Label;
+    /** "Update Category" — save-button text on the term edit form. */
+    readonly updateItem?: Label;
+    /** "New Category Name" — placeholder for the create-form name input. */
+    readonly newItemName?: Label;
+    /** "Search categories…" — list-page search input placeholder. */
+    readonly searchItems?: Label;
+    /** "No categories yet" — list-page empty state title. */
+    readonly notFound?: Label;
+    /** "Loading categories" — aria-busy state during fetch. */
+    readonly loadingItems?: Label;
+    /** "Couldn't load categories. Try again." — fetch-failure banner. */
+    readonly loadErrorItems?: Label;
+    /** "All categories" — filter chip label. */
+    readonly allItems?: Label;
+    /** "No categories match" — empty state after zero-match search. */
+    readonly noMatch?: Label;
+    /** "Parent Category" — hierarchical parent picker option label. */
+    readonly parentItem?: Label;
+    /** "Parent Category:" — colon-suffixed variant for form labels. */
+    readonly parentItemColon?: Label;
+    /** "No categories" — entry-list cell empty placeholder. */
+    readonly noTerms?: Label;
+    /** "Filter by category" — SR-only label on filter dropdown. */
+    readonly filterByItem?: Label;
+    /** "← Go to Categories" — back-link from term edit to list. */
+    readonly backToItems?: Label;
+    /** "Categories list" — SR-only region label for the data table. */
+    readonly itemsList?: Label;
+    /** "Categories list navigation" — SR-only region label for pagination. */
+    readonly itemsListNavigation?: Label;
+    /** "Separate tags with commas" — help text for chip-style multi-input
+     *  pickers (non-hierarchical only; categories don't use it). */
+    readonly separateItemsWithCommas?: Label;
+    /** "Add or remove tags" — help text for chip-style picker controls. */
+    readonly addOrRemoveItems?: Label;
+}
+export interface TermTaxonomyOptions {
+    readonly label: Label;
+    readonly labels?: TermTaxonomyLabels;
+    readonly description?: string;
+    readonly isHierarchical?: boolean;
+    readonly entryTypes?: readonly string[];
+    readonly isPublic?: boolean;
+    readonly showUI?: boolean;
+    readonly showInSidebar?: boolean;
+    readonly excludeFromGenericRpc?: boolean;
+    readonly isInQuickEdit?: boolean;
+    readonly hasAdminColumn?: boolean;
+    readonly rewrite?: {
+        readonly slug?: string;
+        readonly isHierarchical?: boolean;
+    };
+    readonly capabilities?: TermTaxonomyCapabilityOverrides;
+    readonly menuIcon?: string;
+    /** Synonyms the command palette matches in addition to the sidebar label. */
+    readonly keywords?: readonly Label[];
+    /** Page size for this taxonomy's term archives. Default 20. */
+    readonly archivePerPage?: number;
+}
+export declare function resolveEntryTypeVisibility(options: EntryTypeOptions): {
+    readonly isPublic: boolean;
+    readonly showUI: boolean;
+    readonly showInSidebar: boolean;
+    readonly excludeFromGenericRpc: boolean;
+    readonly excludeFromSearch: boolean;
+};
+export declare function resolveTermTaxonomyVisibility(options: TermTaxonomyOptions): {
+    readonly isPublic: boolean;
+    readonly showUI: boolean;
+    readonly showInSidebar: boolean;
+    readonly excludeFromGenericRpc: boolean;
+};
+export declare function manifestEntryVisibility(entry: Pick<EntryTypeManifestEntry, "isPublic" | "showUI" | "showInSidebar"> | Pick<TermTaxonomyManifestEntry, "isPublic" | "showUI" | "showInSidebar">): {
+    readonly isPublic: boolean;
+    readonly showUI: boolean;
+    readonly showInSidebar: boolean;
+};
+export type MetaScalarType = "string" | "number" | "boolean" | "json";
+export interface MetaBoxFieldOption {
+    readonly value: string;
+    readonly label: Label;
+}
+/**
+ * Column span for a field within its meta box's 12-column grid. A plain
+ * number applies from the smallest breakpoint up. The object form is
+ * mobile-first: `base` is the default, `sm` / `md` / `lg` override upward.
+ * Breakpoints key off the card's own width (Tailwind container queries,
+ * `@sm` / `@md` / `@lg`) so the same `span` renders consistently whether
+ * the box lands in a full-width route or a narrow sidebar. Values outside
+ * 1..12 are clamped at render time. Omitted span means full width (12).
+ */
+export type MetaBoxFieldSpan = number | {
+    readonly base?: number;
+    readonly sm?: number;
+    readonly md?: number;
+    readonly lg?: number;
+};
+/**
+ * Shared shape for every meta-box field variant — properties carried
+ * regardless of `inputType`. Each narrowed variant of `MetaBoxField`
+ * extends this with input-specific options.
+ */
+export interface MetaBoxFieldBase {
+    readonly key: string;
+    readonly label: Label;
+    /**
+     * Storage type. Drives server-side sanitization on write and
+     * coercion on read (`entry.meta` / `term.meta` columns store JSON,
+     * but the type informs the expected shape). `json` accepts any
+     * JSON-serialisable value.
+     */
+    readonly type: MetaScalarType;
+    /**
+     * Applied after type coercion, before persistence. Returning a
+     * sanitized value replaces the caller's input — ideal for trimming,
+     * whitelisting, or normalising shape.
+     */
+    readonly sanitize?: (value: unknown) => unknown;
+    /** Default surfaced in the admin form when the key has no saved value. */
+    readonly default?: unknown;
+    /** Optional help text rendered under the label on every input type. */
+    readonly description?: Label;
+    /** Renders `required` on the native input; server validation is separate. */
+    readonly required?: boolean;
+    /**
+     * Column span within the meta box's 12-column grid. Defaults to full
+     * width. See `MetaBoxFieldSpan` for the responsive object form.
+     */
+    readonly span?: MetaBoxFieldSpan;
+    /**
+     * Capability gate for the individual field. When set, the admin hides
+     * the field from viewers whose capability set lacks it. The server
+     * rejects entry/term/user writes that include the field's key — both
+     * upserts and deletes count, so a viewer can't blank a value they
+     * can't see. Gating applies at the top-level field only; capabilities
+     * on repeater subfields are ignored (a row's gate is the parent
+     * repeater field's gate). Defaults to no gating.
+     */
+    readonly capability?: string;
+    /**
+     * Expose this field's value on the public REST API. Default-deny: meta is
+     * hidden from REST responses unless a field opts in with `showInApi: true`,
+     * so internal fields never leak by default. Has no effect on the admin RPC.
+     */
+    readonly showInApi?: boolean;
+}
+/**
+ * The narrowed `text` field variant produced by the `text()` builder
+ * helper exported from `plumix/fields`. The builder rejects options
+ * that don't apply to a text input (e.g. `min`, `step`, `options`) at
+ * the type level; downstream consumers can rely on the narrowed shape
+ * via the `inputType` discriminator.
+ */
+export interface TextMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "text";
+    readonly type: "string";
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+}
+/** Multi-line text input. Storage shape mirrors `text`. */
+export interface TextareaMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "textarea";
+    readonly type: "string";
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+}
+/** Numeric input with optional `min` / `max` / `step` bounds. */
+export interface NumberMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "number";
+    readonly type: "number";
+    readonly placeholder?: Label;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+/** RFC-5322-shaped email input. */
+export interface EmailMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "email";
+    readonly type: "string";
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+}
+/** URL input. */
+export interface UrlMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "url";
+    readonly type: "string";
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+}
+/**
+ * Masked-input password field. Visually hides characters in the admin
+ * so values aren't shoulder-surfable in shared sessions; storage
+ * shape mirrors `text`.
+ */
+export interface PasswordMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "password";
+    readonly type: "string";
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+}
+/**
+ * Date-only field. Stored as `YYYY-MM-DD` (ISO 8601 calendar date,
+ * no time, no timezone). Optional `min` / `max` bounds use the same
+ * format and are enforced as registration-time validation only —
+ * server-side bound enforcement is deferred to a later release.
+ */
+export interface DateMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "date";
+    readonly type: "string";
+    readonly min?: string;
+    readonly max?: string;
+}
+/**
+ * Date + time field. Stored as a partial ISO 8601 string
+ * (`YYYY-MM-DDTHH:MM` with optional `:SS`) reflecting whatever the
+ * author's browser produced via `<input type="datetime-local">`. A
+ * future iteration may bake in the browser's timezone offset so the
+ * wall-clock semantics survive cross-region reads; today's storage is
+ * naive local time and consumers anchor to a timezone explicitly via
+ * `parseMetaDate` + their own `Temporal.ZonedDateTime` shaping if
+ * needed.
+ */
+export interface DateTimeMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "datetime";
+    readonly type: "string";
+    readonly min?: string;
+    readonly max?: string;
+}
+/**
+ * Time-only field. Stored as `HH:MM` (with optional `:SS`). No date
+ * anchor, no timezone — useful for "open at 09:00" style values where
+ * the calendar date is supplied separately.
+ */
+export interface TimeMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "time";
+    readonly type: "string";
+    readonly min?: string;
+    readonly max?: string;
+}
+/**
+ * Hex color picker. Stored as a `#xxxxxx` string (the format the
+ * native `<input type="color">` produces). The builder injects a
+ * default sanitizer that rejects values that don't match the hex
+ * shape on write.
+ */
+export interface ColorMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "color";
+    readonly type: "string";
+}
+/**
+ * Bounded numeric slider. Renders as `<input type="range">`. `min` /
+ * `max` are required so the slider has a concrete range; `step`
+ * defaults to `1`. The builder injects a default sanitizer that
+ * enforces the bounds on write.
+ */
+export interface RangeMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "range";
+    readonly type: "number";
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+}
+/**
+ * Multi-value picker over a fixed option list. Storage is a JSON
+ * array of option `value` strings. Renders as a toggle group in the
+ * admin so authors see all options at once. The builder ships a
+ * default sanitizer that rejects values outside the declared
+ * options.
+ */
+export interface MultiselectMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "multiselect";
+    readonly type: "json";
+    readonly options: readonly MetaBoxFieldOption[];
+}
+/**
+ * Free-form JSON value. Storage round-trips through the JSON
+ * serializer so any structure that survives `JSON.stringify`
+ * survives the wire.
+ */
+export interface JsonMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "json";
+    readonly type: "json";
+}
+/**
+ * Reference target descriptor carried on every reference field
+ * variant (`user`, `entry`, `term`, `media`, plugin-registered
+ * custom kinds). The `kind` matches a registered `LookupAdapter`;
+ * the adapter interprets `scope` according to its own contract.
+ *
+ * Reading the manifest, the admin dispatches to a generic picker
+ * that calls the lookup RPC with `{ kind, scope }` — picker UI is
+ * one component, target-specific knowledge lives in the adapter.
+ */
+export interface ReferenceTarget<TScope = unknown> {
+    readonly kind: string;
+    readonly scope?: TScope;
+    /**
+     * Storage cardinality. `false`/absent → single value (string or
+     * cached object). `true` → array (of strings or cached objects).
+     * The server-side write validator and read-side orphan filter
+     * dispatch on this flag to handle both shapes uniformly.
+     */
+    readonly multiple?: boolean;
+    /**
+     * Storage shape per item. `"id"` (default) → bare id string —
+     * every read needs a join/resolve to get a label. `"object"` →
+     * `{ id, ...cachedFields, ...userFields }` — the meta pipeline
+     * normalizes cached fields from the adapter on every write so
+     * reads can render without a join. Used by `media` (where the
+     * thumbnail/mime/filename are needed on every render and a
+     * resolve per render is wasteful on the edge).
+     *
+     * The cached fields come from `LookupResult.cached` returned by
+     * the adapter; user-supplied keys (e.g. per-usage `alt`) survive
+     * the merge so editors can override per-usage metadata.
+     */
+    readonly valueShape?: "id" | "object";
+}
+/**
+ * Single user reference. Storage is the bare user id as a string
+ * (`"42"` → `users.id = 42`); reads return `null` when the user is
+ * gone or no longer matches scope. The `referenceTarget.scope`
+ * accepts the user adapter's scope shape (roles + disabled-state).
+ */
+export interface UserMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "user";
+    readonly type: "string";
+    readonly referenceTarget: ReferenceTarget;
+}
+/**
+ * Multi user reference. Storage is a JSON array of bare user ids
+ * (`["42", "43"]`); reads filter out orphans (the bag's array stays
+ * dense — missing IDs are dropped, not nulled, so consumers iterate
+ * without branching). `referenceTarget.multiple` is `true`; `max`
+ * caps the array length at write time.
+ */
+export interface UserListMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "userList";
+    readonly type: "json";
+    readonly referenceTarget: ReferenceTarget;
+    /** Max items allowed in the array. Omitted = unbounded. */
+    readonly max?: number;
+}
+/**
+ * Single entry reference. Storage is the bare entry id as a string;
+ * reads return `null` when the entry is gone, scope-mismatched, or
+ * trashed. `referenceTarget.scope` carries `entryTypes` (the only
+ * entry-type names this field accepts).
+ *
+ * Naming note: the `Reference` infix avoids the collision with
+ * `EntryMetaBoxField` further down — the latter is the per-variant
+ * Omit-distributive union for fields inside an entry meta box.
+ */
+export interface EntryReferenceMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "entry";
+    readonly type: "string";
+    readonly referenceTarget: ReferenceTarget;
+}
+/**
+ * Multi entry reference. Storage is a JSON array of bare entry ids;
+ * reads filter out orphans (the array stays dense — missing IDs are
+ * dropped, not nulled). `referenceTarget.multiple` is `true`; `max`
+ * caps the array length at write time. Scope rules match
+ * `EntryReferenceMetaBoxField` — `entryTypes` is required.
+ */
+export interface EntryListMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "entryList";
+    readonly type: "json";
+    readonly referenceTarget: ReferenceTarget;
+    /** Max items allowed in the array. Omitted = unbounded. */
+    readonly max?: number;
+}
+/**
+ * Single term reference. Storage is the bare term id as a string;
+ * reads return `null` for orphans / scope mismatches.
+ * `referenceTarget.scope` carries `termTaxonomies` (the taxonomy
+ * names this field accepts).
+ */
+export interface TermReferenceMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "term";
+    readonly type: "string";
+    readonly referenceTarget: ReferenceTarget;
+}
+/**
+ * Multi term reference. Storage is a JSON array of bare term ids;
+ * reads filter out orphans the same way `EntryListMetaBoxField`
+ * does. `referenceTarget.multiple` is `true`; `max` caps array
+ * length. Scope rules match `TermReferenceMetaBoxField` —
+ * `termTaxonomies` is required.
+ */
+export interface TermListMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "termList";
+    readonly type: "json";
+    readonly referenceTarget: ReferenceTarget;
+    /** Max items allowed in the array. Omitted = unbounded. */
+    readonly max?: number;
+}
+/**
+ * Single media reference with cached metadata. Storage is the
+ * `MediaValue` object — `{ id, mime?, filename?, alt? }` — not a
+ * bare id, so admin renders show a thumbnail + filename without an
+ * extra resolve round-trip per render. `referenceTarget.valueShape`
+ * is `"object"`; the meta pipeline overwrites the cached fields
+ * (mime/filename) from the lookup adapter on every write but lets
+ * user-supplied keys (e.g. per-usage `alt`) survive the merge.
+ *
+ * Lives in core so the typed builder narrows correctly at call
+ * sites — same convention as `entry` / `term`. The actual builder
+ * + adapter are in `@plumix/plugin-media`.
+ */
+export interface MediaMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "media";
+    readonly type: "json";
+    readonly referenceTarget: ReferenceTarget;
+}
+/**
+ * Multi media reference. Storage is a JSON array of `MediaValue`
+ * objects — `[{ id, mime?, filename? }, ...]` — extending the cached-
+ * object pattern from `MediaMetaBoxField` to the array shape. The
+ * meta pipeline rewrites each entry's cached fields on every write,
+ * so admin renders thumbnails for every item without a per-item
+ * resolve. `referenceTarget.multiple` is `true`, `valueShape` is
+ * `"object"`; `max` caps the array length at write time.
+ */
+export interface MediaListMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "mediaList";
+    readonly type: "json";
+    readonly referenceTarget: ReferenceTarget;
+    /** Max items allowed in the array. Omitted = unbounded. */
+    readonly max?: number;
+}
+/**
+ * Richtext field — Tiptap ProseMirror JSON storage. `marks`, `nodes`,
+ * and `blocks` are strict allowlists: omitted entries are denied even
+ * if they're standard Tiptap extensions. `doc`/`paragraph`/`text` are
+ * always included implicitly because ProseMirror requires them for
+ * any document to parse.
+ *
+ * `marks` are inline formatters (`bold`, `italic`, `link`, …).
+ * `nodes` are block-level Tiptap nodes (`heading`, `bulletList`,
+ * `codeBlock`, …). `blocks` is a forward-compatible allowlist of
+ * custom node names — the validator accepts documents containing them,
+ * leaving the theme-side block render registry (planned) responsible
+ * for actually drawing them.
+ *
+ * Server-side validator (`walkRichtextDoc`) walks the saved doc and
+ * rejects any node/mark/block name outside the allowlist. The admin
+ * toolbar surfaces only the buttons that match the allowlist.
+ *
+ * Replaces the dropped `markdown` and `code` standalone field types —
+ * `richtext({ nodes: ["codeBlock"] })` covers code-in-meta;
+ * `richtext({ marks: ["bold","italic","link"], nodes: ["bulletList","orderedList"] })`
+ * covers markdown-shaped formatting.
+ */
+export interface RichtextMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "richtext";
+    readonly type: "json";
+    readonly marks?: readonly string[];
+    readonly nodes?: readonly string[];
+    readonly blocks?: readonly string[];
+}
+/**
+ * Flat list of structured rows. Each row carries the same fixed schema
+ * declared via `subFields`; mixed-row "flexible content" is explicitly
+ * out of scope. Subfields may be any registered field type *except*
+ * another repeater — nesting is rejected at registration time so v0.1
+ * doesn't ship recursive UX (lift later non-breakingly if a real use
+ * case appears).
+ *
+ * Storage rides on the `json` primitive so any JSON-serialisable row
+ * shape survives the wire. The auto-injected sanitizer drops rows
+ * where every subfield value is empty (`null` / `undefined` / `""`),
+ * then enforces optional `min` / `max` row counts. "Empty" is strictly
+ * those three: a row whose only populated subfield is `0` (number) or
+ * `false` (checkbox) survives — those are real values.
+ */
+export interface RepeaterMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "repeater";
+    readonly type: "json";
+    readonly subFields: readonly MetaBoxField[];
+    readonly min?: number;
+    readonly max?: number;
+}
+/** Single-value dropdown picker; `options` is required. */
+export interface SelectMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "select";
+    readonly type: "string";
+    readonly options: readonly MetaBoxFieldOption[];
+}
+/** Single-value radio group; `options` is required. */
+export interface RadioMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "radio";
+    readonly type: "string";
+    readonly options: readonly MetaBoxFieldOption[];
+}
+/** Boolean checkbox — storage type pinned to `boolean`. */
+export interface CheckboxMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: "checkbox";
+    readonly type: "boolean";
+}
+/**
+ * Catch-all variant for any `inputType` not narrowed into a dedicated
+ * variant above — primarily plugin-registered custom types arriving via
+ * `registerFieldType`. Object-literal registrations using built-in
+ * input-type strings (e.g. `inputType: "text"`) still type-check
+ * against the narrowed variant when their option shape matches; this
+ * variant exists so authoring patterns and plugin extensions don't
+ * regress.
+ */
+export interface LegacyMetaBoxField extends MetaBoxFieldBase {
+    readonly inputType: string;
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly options?: readonly MetaBoxFieldOption[];
+}
+/**
+ * A field inside a meta box — the single source of truth for both the
+ * admin UI renderer and the server-side storage contract. Declaring a
+ * meta box is the only way to register a meta key; there is no separate
+ * `registerMeta` step.
+ *
+ * Modelled as a discriminated union keyed on `inputType`. Each built-in
+ * input type has its own narrowed variant produced by a builder helper
+ * exported from `plumix/fields`; `LegacyMetaBoxField` keeps custom
+ * `registerFieldType` registrations and broad object-literal authoring
+ * compiling unchanged.
+ */
+export type MetaBoxField = TextMetaBoxField | TextareaMetaBoxField | NumberMetaBoxField | EmailMetaBoxField | UrlMetaBoxField | PasswordMetaBoxField | DateMetaBoxField | DateTimeMetaBoxField | TimeMetaBoxField | ColorMetaBoxField | RangeMetaBoxField | MultiselectMetaBoxField | JsonMetaBoxField | UserMetaBoxField | UserListMetaBoxField | EntryReferenceMetaBoxField | EntryListMetaBoxField | TermReferenceMetaBoxField | TermListMetaBoxField | MediaMetaBoxField | MediaListMetaBoxField | RichtextMetaBoxField | RepeaterMetaBoxField | SelectMetaBoxField | RadioMetaBoxField | CheckboxMetaBoxField | LegacyMetaBoxField;
+/**
+ * Shared base for every "card of fields" registration surface — entry
+ * meta boxes, term meta boxes, user meta boxes, and settings groups.
+ * Each concrete surface extends this with its scope specifier (if any)
+ * and any surface-specific layout hints (`location` on entry boxes).
+ *
+ * Semantics shared across every extender:
+ * - `priority` orders cards within their region; lower first,
+ *   unspecified sorts last, ties break by `id` / `name` alphabetical.
+ * - `capability` is a UI-only filter — the admin hides cards the
+ *   viewer lacks the capability for. The server enforces only the
+ *   entity-level write gate (`<entryType>:edit*`, `<termTaxonomy>:edit`,
+ *   `user:edit`, `settings:manage`). Do NOT use `capability` for
+ *   secrets; any user with the entity write gate can write any
+ *   registered field via the raw RPC.
+ * - `fields` carry `MetaBoxField.sanitize` which runs server-side only
+ *   — the manifest wire contract strips callbacks before shipping.
+ */
+export interface MetaBoxBaseOptions {
+    readonly label: Label;
+    readonly description?: Label;
+    readonly priority?: number;
+    readonly capability?: string;
+    readonly fields: readonly MetaBoxField[];
+}
+/**
+ * Field shape for entry meta boxes. Drops `span` from the shared
+ * `MetaBoxField` — the editor's document rail is a fixed 256px column,
+ * so side-by-side layouts can't fit legibly. Compile-time signal to
+ * plugin authors that spans are a page-width affordance only (term,
+ * user, settings).
+ *
+ * `Omit<MetaBoxField, "span">` would normally distribute over the
+ * union, but TS's excess-property check across a many-variant
+ * distributed `Omit` gets pessimistic and starts rejecting options
+ * that exist only on a subset of variants. The explicit per-variant
+ * union below preserves the same shape with stable inference.
+ */
+export type EntryMetaBoxField = Omit<TextMetaBoxField, "span"> | Omit<TextareaMetaBoxField, "span"> | Omit<NumberMetaBoxField, "span"> | Omit<EmailMetaBoxField, "span"> | Omit<UrlMetaBoxField, "span"> | Omit<PasswordMetaBoxField, "span"> | Omit<DateMetaBoxField, "span"> | Omit<DateTimeMetaBoxField, "span"> | Omit<TimeMetaBoxField, "span"> | Omit<ColorMetaBoxField, "span"> | Omit<RangeMetaBoxField, "span"> | Omit<MultiselectMetaBoxField, "span"> | Omit<JsonMetaBoxField, "span"> | Omit<UserMetaBoxField, "span"> | Omit<UserListMetaBoxField, "span"> | Omit<EntryReferenceMetaBoxField, "span"> | Omit<EntryListMetaBoxField, "span"> | Omit<TermReferenceMetaBoxField, "span"> | Omit<TermListMetaBoxField, "span"> | Omit<MediaMetaBoxField, "span"> | Omit<MediaListMetaBoxField, "span"> | Omit<RichtextMetaBoxField, "span"> | Omit<RepeaterMetaBoxField, "span"> | Omit<SelectMetaBoxField, "span"> | Omit<RadioMetaBoxField, "span"> | Omit<CheckboxMetaBoxField, "span"> | Omit<LegacyMetaBoxField, "span">;
+/**
+ * Meta box shown on the entry editor. Scoped by `entryTypes`. Renders
+ * as a collapsible section in the editor's document rail, which is
+ * fixed at 256px — fields always occupy the full row.
+ */
+export interface EntryMetaBoxOptions extends Omit<MetaBoxBaseOptions, "fields"> {
+    /**
+     * @deprecated The entry editor no longer partitions meta boxes by
+     * location — every registered box renders as a collapsible section in
+     * the right rail regardless of this flag. Declared for backward
+     * compatibility with plugins that still set it; safe to remove from
+     * new code.
+     */
+    readonly location?: "bottom" | "sidebar";
+    readonly entryTypes: readonly string[];
+    readonly fields: readonly EntryMetaBoxField[];
+}
+/** Meta box shown on the termTaxonomy term edit form. Scoped by `termTaxonomies`. */
+export interface TermMetaBoxOptions extends MetaBoxBaseOptions {
+    readonly termTaxonomies: readonly string[];
+}
+/**
+ * Meta box shown on the user edit form. User meta is a flat keyspace
+ * (no scope analogue to entry types or termTaxonomies), so the base shape
+ * is everything an author needs.
+ */
+export type UserMetaBoxOptions = MetaBoxBaseOptions;
+/**
+ * A self-contained group of fields on a settings page — storage unit
+ * AND visual unit. Each group gets its own Save button (independent
+ * storage, unlike entity meta which rides the entity's single Save).
+ * Surfaced via `registerSettingsPage.groups: string[]`.
+ */
+export type SettingsGroupOptions = MetaBoxBaseOptions;
+/**
+ * A UI-level composition of groups rendered at `/settings/<page>` in the
+ * admin. Pages are not stored — they're pure registration metadata. A
+ * page lists the groups it wants to surface by name (each group can be
+ * referenced from multiple pages if useful).
+ */
+export interface SettingsPageOptions {
+    readonly label: Label;
+    readonly description?: Label;
+    readonly groups: readonly string[];
+    /**
+     * Admin menu ordering. Unspecified positions sort last (in
+     * registration order). Mirrors `EntryTypeOptions.priority` so
+     * sidebar composition stays predictable across plugins.
+     */
+    readonly priority?: number;
+}
+export interface RegisteredEntryType extends EntryTypeOptions {
+    readonly name: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredTermTaxonomy extends TermTaxonomyOptions {
+    readonly name: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredEntryMetaBox extends EntryMetaBoxOptions {
+    readonly id: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredTermMetaBox extends TermMetaBoxOptions {
+    readonly id: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredUserMetaBox extends UserMetaBoxOptions {
+    readonly id: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredSettingsGroup extends SettingsGroupOptions {
+    readonly name: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredSettingsPage extends SettingsPageOptions {
+    readonly name: string;
+    readonly registeredBy: string | null;
+}
+export interface RegisteredCapability {
+    readonly name: string;
+    readonly minRole: UserRole;
+    /**
+     * Additional roles explicitly granted the capability, independent of
+     * hierarchy. Complements `minRole`: a role satisfies the capability
+     * if it meets `minRole` OR appears here. Useful for non-contiguous
+     * grants ("editors and authors but not admins in between" stays
+     * impossible; "admin by hierarchy + author explicitly" becomes
+     * expressible). Sorted + deduped at registration.
+     */
+    readonly defaultGrants?: readonly UserRole[];
+    readonly registeredBy: string | null;
+}
+export interface RegisteredRewriteRule {
+    readonly pattern: string;
+    readonly intent: RouteIntent;
+    readonly priority: number;
+    readonly registeredBy: string | null;
+}
+/**
+ * Reference to a React component contributed by a plugin. The string is
+ * the export name on the plugin's `adminEntry` module — the plumix vite
+ * pipeline namespace-imports each plugin's entry and emits the matching
+ * `window.plumix.registerPlugin{Page,FieldType}` calls into the
+ * synthesised admin chunk, so plugin authors only need `export const
+ * MyComponent = ...` and a single registration call to `ctx.register*`.
+ *
+ * No `package` field is needed: the plugin id (implicit from
+ * registration context) keys the namespace import the export resolves
+ * against. Drop-in for the previous `{ package, export }` shape; bumped
+ * pre-release so consumers can update in one pass.
+ */
+export type PluginComponentRef = string;
+/**
+ * How an admin page slots into the sidebar. `group` is either a bare
+ * id (string) or an object that declares group metadata inline — first
+ * page using a given id sets the label/priority for that group; later
+ * pages can use the bare-string form to attach to it. Core group ids
+ * (`overview` / `content` / `term-taxonomies` / `management`) carry
+ * their own label/priority and ignore inline metadata.
+ */
+export type AdminNavGroupRef = string | {
+    readonly id: string;
+    readonly label?: Label;
+    readonly priority?: number;
+};
+export interface AdminPageOptions {
+    readonly path: string;
+    readonly title: Label;
+    readonly nav?: {
+        readonly group: AdminNavGroupRef;
+        readonly label: Label;
+        readonly icon?: PluginComponentRef;
+        readonly order?: number;
+        /** Synonyms the command palette matches in addition to `label`. */
+        readonly keywords?: readonly Label[];
+    };
+    readonly capability?: string;
+    readonly component: PluginComponentRef;
+}
+export interface RegisteredAdminPage extends AdminPageOptions {
+    readonly registeredBy: string | null;
+}
+export interface DashboardWidgetOptions {
+    /** Unique widget id, conventionally `<pluginId>:<name>`. */
+    readonly id: string;
+    readonly title: Label;
+    /** Hidden unless the viewer holds this capability (when set). */
+    readonly capability?: string;
+    /** Export name in the plugin's admin chunk, resolved at render. */
+    readonly component: PluginComponentRef;
+    /** Lower sorts first on the dashboard; unset sorts last. */
+    readonly priority?: number;
+}
+export interface RegisteredDashboardWidget extends DashboardWidgetOptions {
+    readonly registeredBy: string | null;
+}
+export interface DashboardWidgetManifestEntry {
+    readonly id: string;
+    readonly title: Label;
+    readonly capability?: string;
+    readonly component: PluginComponentRef;
+    readonly priority?: number;
+}
+/**
+ * Built-in nav-icon names that core nav items reference. The admin maps
+ * each value to a lucide component at render time — keeps the wire
+ * payload free of package identifiers and makes the union exhaustive at
+ * the type level.
+ */
+export type CoreIconName = "dashboard" | "content" | "file-text" | "layout" | "image" | "calendar" | "tag" | "folder" | "users" | "settings" | "puzzle" | "mail" | "key";
+/**
+ * Built-in nav groups core ships. Plugins target their items at these
+ * ids via `nav.group`, and can interleave their own groups by picking
+ * priorities between or around these defaults. Labels are
+ * `MessageDescriptor`s so the sidebar localizes at render time via
+ * the admin's `useLabel` hook.
+ *
+ * Convention: plugin-declared groups keep their label descriptor id
+ * under the same `core.adminNav.<groupId>` namespace (see
+ * `@plumix/plugin-menu` → `appearance`, `@plumix/plugin-media` →
+ * `library`, `@plumix/plugin-audit-log` → `tools`). The id space is
+ * the concept, not the owner — translators see one "Appearance"
+ * entry rather than one per plugin sharing the group.
+ */
+export declare const CORE_NAV_GROUPS: readonly {
+    readonly id: string;
+    readonly label: Label;
+    readonly priority: number;
+}[];
+/**
+ * Plugin-contributed form field renderer. The admin's form dispatcher
+ * falls through to a plain text input on unknown `inputType` values
+ * (with a dev-mode warning); registering a type here swaps in a
+ * plugin React component that renders the custom UI.
+ *
+ * The `type` string must match a field's `inputType` — registering
+ * `type: "media_picker"` means any field (entry meta, term meta,
+ * user meta, settings group) with `inputType: "media_picker"`
+ * renders through the plugin's component.
+ */
+export interface FieldTypeOptions {
+    readonly type: string;
+    readonly component: PluginComponentRef;
+}
+export interface RegisteredFieldType extends FieldTypeOptions {
+    readonly registeredBy: string | null;
+}
+export type PluginRouteMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "*";
+export type PluginRouteAuth = "public" | "authenticated" | {
+    readonly capability: string;
+};
+export interface RegisteredRawRoute {
+    readonly pluginId: string;
+    readonly method: PluginRouteMethod;
+    readonly path: string;
+    readonly auth: PluginRouteAuth;
+    readonly handler: (request: Request, ctx: AppContext) => Response | Promise<Response>;
+}
+export type RestResourceMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * A REST resource a plugin contributes into the shared `/_plumix/api/v1/`
+ * namespace. `path` is relative to that prefix (e.g. `/{type}/{id}/comments`)
+ * and uses `{param}` segments. `auth` reuses the declarative route model; core
+ * enforces it before the handler runs. `input`/`output` are valibot schemas —
+ * the `output` schema is the public allowlist and feeds the generated spec.
+ */
+export interface RestResourceOptions {
+    readonly method?: RestResourceMethod;
+    readonly path: string;
+    readonly auth: PluginRouteAuth;
+    readonly input?: any;
+    readonly output: any;
+    readonly handler: (args: {
+        input: any;
+        context: AppContext;
+    }) => any;
+}
+export interface RegisteredRestResource extends RestResourceOptions {
+    readonly pluginId: string;
+    readonly method: RestResourceMethod;
+}
+/**
+ * Tiny `{ key, label, href }` blob a plugin attaches so the standard
+ * login screen can render a button for the sign-in flow it ships. The
+ * actual flow (start route, callback route, identity resolution) is
+ * registered separately via `registerRoute` + `resolveExternalIdentity`;
+ * this is purely the UI affordance that points the user at it.
+ */
+export interface LoginLinkOptions {
+    /**
+     * Stable key, scoped per-plugin. The wire id surfaced to the admin
+     * (and used as its React key) is `${pluginId}:${key}`, so the bare
+     * `key` you pass only needs to be unique within your own plugin —
+     * two different plugins can both register a `key: "default"`.
+     *
+     * Lowercase alphanum + dash/underscore, must start with a letter,
+     * 1–32 chars total. Same shape as `OAUTH_PROVIDER_KEY_PATTERN`.
+     */
+    readonly key: string;
+    /**
+     * Button text shown on the login screen ("Sign in with Microsoft",
+     * "Continue with Okta"). No CR/LF — see `siteName` for rationale.
+     */
+    readonly label: string;
+    /**
+     * URL the button points at — typically the plugin's own start route,
+     * e.g. `/_plumix/saml-microsoft/start`. Must be a relative path
+     * starting with `/` or an `https://` absolute URL; arbitrary schemes
+     * are rejected so a malicious or misconfigured plugin can't surface
+     * a `javascript:` link.
+     */
+    readonly href: string;
+}
+export interface RegisteredLoginLink extends LoginLinkOptions {
+    readonly registeredBy: string;
+}
+/**
+ * Plugin-registered work that fires on the runtime's scheduled trigger
+ * (Cloudflare cron, future Node/Bun timers). The handler receives a
+ * synthetic-request `AppContext` — same `db` / `hooks` / `logger` /
+ * `defer` as a normal request, but `user` is `null` and `request` is
+ * an internal marker.
+ *
+ * A task with a `cron` runs only on the invocation whose fired schedule
+ * (`event.cron`) byte-matches it; a task without one runs on every
+ * invocation. The operator must declare a matching `wrangler` `triggers.crons`
+ * entry for a `cron`-tagged task to ever fire — the strings must be identical.
+ */
+export interface ScheduledTask {
+    readonly id: string;
+    /** Cron expression; must byte-match a `wrangler` `triggers.crons` entry. */
+    readonly cron?: string;
+    readonly handler: (ctx: AppContext) => void | Promise<void>;
+}
+export interface RegisteredScheduledTask extends ScheduledTask {
+    readonly registeredBy: string;
+}
+export type PluginRpcRouter = Record<string, any>;
+export interface RegisteredMcpTool {
+    readonly tool: McpTool;
+    readonly registeredBy: string;
+}
+export interface RegisteredBlock {
+    readonly spec: BlockSpec;
+    readonly registeredBy: string;
+}
+export interface RegisteredMark {
+    readonly spec: MarkSpec;
+    readonly registeredBy: string;
+}
+export interface RegisteredPattern {
+    readonly spec: BlockPattern;
+    readonly registeredBy: string;
+}
+export interface RegisteredShortcode {
+    readonly spec: ShortcodeSpec;
+    readonly registeredBy: string;
+}
+export interface PluginRegistry {
+    readonly entryTypes: ReadonlyMap<string, RegisteredEntryType>;
+    readonly termTaxonomies: ReadonlyMap<string, RegisteredTermTaxonomy>;
+    readonly entryMetaBoxes: ReadonlyMap<string, RegisteredEntryMetaBox>;
+    readonly termMetaBoxes: ReadonlyMap<string, RegisteredTermMetaBox>;
+    readonly userMetaBoxes: ReadonlyMap<string, RegisteredUserMetaBox>;
+    readonly capabilities: ReadonlyMap<string, RegisteredCapability>;
+    readonly settingsGroups: ReadonlyMap<string, RegisteredSettingsGroup>;
+    readonly settingsPages: ReadonlyMap<string, RegisteredSettingsPage>;
+    readonly rewriteRules: readonly RegisteredRewriteRule[];
+    readonly rpcRouters: ReadonlyMap<string, PluginRpcRouter>;
+    readonly mcpTools: ReadonlyMap<string, RegisteredMcpTool>;
+    readonly rawRoutes: readonly RegisteredRawRoute[];
+    readonly restResources: readonly RegisteredRestResource[];
+    readonly loginLinks: readonly RegisteredLoginLink[];
+    readonly adminPages: ReadonlyMap<string, RegisteredAdminPage>;
+    readonly dashboardWidgets: ReadonlyMap<string, RegisteredDashboardWidget>;
+    readonly fieldTypes: ReadonlyMap<string, RegisteredFieldType>;
+    readonly blockSpecs: ReadonlyMap<string, RegisteredBlock>;
+    readonly markSpecs: ReadonlyMap<string, RegisteredMark>;
+    readonly patternSpecs: ReadonlyMap<string, RegisteredPattern>;
+    readonly shortcodeSpecs: ReadonlyMap<string, RegisteredShortcode>;
+    readonly lookupAdapters: ReadonlyMap<string, RegisteredLookupAdapter>;
+    readonly scheduledTasks: readonly RegisteredScheduledTask[];
+    readonly templateDeps: ReadonlyMap<string, RegisteredTemplateDep>;
+}
+export interface MutablePluginRegistry extends PluginRegistry {
+    readonly entryTypes: Map<string, RegisteredEntryType>;
+    readonly termTaxonomies: Map<string, RegisteredTermTaxonomy>;
+    readonly entryMetaBoxes: Map<string, RegisteredEntryMetaBox>;
+    readonly termMetaBoxes: Map<string, RegisteredTermMetaBox>;
+    readonly userMetaBoxes: Map<string, RegisteredUserMetaBox>;
+    readonly capabilities: Map<string, RegisteredCapability>;
+    readonly settingsGroups: Map<string, RegisteredSettingsGroup>;
+    readonly settingsPages: Map<string, RegisteredSettingsPage>;
+    readonly rewriteRules: RegisteredRewriteRule[];
+    readonly rpcRouters: Map<string, PluginRpcRouter>;
+    readonly mcpTools: Map<string, RegisteredMcpTool>;
+    readonly rawRoutes: RegisteredRawRoute[];
+    readonly restResources: RegisteredRestResource[];
+    readonly loginLinks: RegisteredLoginLink[];
+    readonly adminPages: Map<string, RegisteredAdminPage>;
+    readonly dashboardWidgets: Map<string, RegisteredDashboardWidget>;
+    readonly fieldTypes: Map<string, RegisteredFieldType>;
+    readonly blockSpecs: Map<string, RegisteredBlock>;
+    readonly markSpecs: Map<string, RegisteredMark>;
+    readonly patternSpecs: Map<string, RegisteredPattern>;
+    readonly shortcodeSpecs: Map<string, RegisteredShortcode>;
+    readonly lookupAdapters: Map<string, RegisteredLookupAdapter>;
+    readonly scheduledTasks: RegisteredScheduledTask[];
+    readonly templateDeps: Map<string, RegisteredTemplateDep>;
+}
+export declare function createPluginRegistry(): MutablePluginRegistry;
+/**
+ * Look up the `MetaBoxField` declaration for a meta key within the
+ * entry meta surface, scoped to a given entry type. Returns the first
+ * matching field across all registered entry meta boxes — key
+ * uniqueness per (entryType, key) is enforced at registration time,
+ * so "first match" is the only match.
+ */
+export declare function findEntryMetaField(registry: PluginRegistry, entryType: string, key: string): MetaBoxField | undefined;
+/**
+ * Like `findEntryMetaField`, but for term meta. Scoped by termTaxonomy.
+ */
+export declare function findTermMetaField(registry: PluginRegistry, termTaxonomy: string, key: string): MetaBoxField | undefined;
+/**
+ * Like `findEntryMetaField`, but for user meta. Users have a flat
+ * keyspace (no entry-type / termTaxonomy analogue), so no scope argument —
+ * key uniqueness across all user meta boxes is enforced at manifest-
+ * build time.
+ */
+export declare function findUserMetaField(registry: PluginRegistry, key: string): MetaBoxField | undefined;
+/**
+ * Shape serialised into the admin's `<script id="plumix-manifest">` payload.
+ * Intentionally a strict subset of `RegisteredEntryType`: drops
+ * `registeredBy` (plugin attribution is server-only debug metadata) and
+ * `rewrite` (URL mapping is evaluated server-side). Add fields only when the
+ * admin UI needs them.
+ *
+ * `adminSlug` is derived at build time (see `buildManifest`) and is what the
+ * admin router uses for `/entries/$slug`. Keeping it in the manifest rather
+ * than re-deriving client-side lets the collision check run once on the
+ * server and ships the final routing key as authoritative.
+ */
+export interface EntryTypeManifestEntry {
+    readonly name: string;
+    readonly adminSlug: string;
+    readonly label: Label;
+    /** Plugin-author-declared per-type labels. Admin consumers resolve
+     *  the cascade via `entryTypeLabel(entry, key)` which falls back to
+     *  `GENERIC_ENTRY_TYPE_LABELS[key]` when a key is unset — keeping
+     *  the wire shape narrow (only author-declared keys serialize). */
+    readonly labels?: EntryTypeLabels;
+    readonly description?: string;
+    readonly supports?: readonly string[];
+    readonly termTaxonomies?: readonly string[];
+    readonly isHierarchical?: boolean;
+    /**
+     * Resolved visibility. `buildManifest` always emits these — consumers
+     * should read them via `manifestEntryVisibility(entry)` which applies
+     * the same cascade rules as `resolveEntryTypeVisibility` when they
+     * happen to be missing (lets admin test fixtures stay terse without
+     * the client ever branching on undefined).
+     */
+    readonly isPublic?: boolean;
+    readonly showUI?: boolean;
+    readonly showInSidebar?: boolean;
+    readonly hasArchive?: boolean | string;
+    readonly capabilityType?: string;
+    readonly priority?: number;
+    readonly menuIcon?: string;
+    /** Synonyms the command palette matches in addition to the sidebar label. */
+    readonly keywords?: readonly Label[];
+    /**
+     * Per-type versioning policy. Populated when the entry type opts
+     * into `supports: ['revisions']`. `maxRevisions` caps how many
+     * revision rows are retained per live entry — oldest pruned past
+     * the cap on each successful update. `autosaveIntervalSeconds`
+     * shapes the editor's autosave cadence in a later slice; defaults
+     * to 60 here so themes can read it without nil-checking.
+     */
+    readonly versioning?: {
+        readonly maxRevisions: number;
+        readonly autosaveIntervalSeconds: number;
+    };
+}
+/**
+ * Client-safe field descriptor inside a meta box. Mirrors `MetaBoxField`
+ * minus the server-only `sanitize` callback and `default` value (the
+ * admin receives the default server-side and injects it into the form).
+ */
+export interface MetaBoxFieldManifestEntry {
+    readonly key: string;
+    readonly label: Label;
+    readonly type: MetaScalarType;
+    readonly inputType: string;
+    readonly description?: Label;
+    readonly required?: boolean;
+    readonly placeholder?: Label;
+    readonly maxLength?: number;
+    /**
+     * Lower bound. `number` carries it as a number; `date` / `datetime`
+     * / `time` carry it as the matching ISO string. Renderers branch on
+     * `inputType` to pick the right interpretation.
+     */
+    readonly min?: number | string;
+    /** Upper bound — see `min`. */
+    readonly max?: number | string;
+    readonly step?: number;
+    readonly options?: readonly MetaBoxFieldOption[];
+    readonly default?: unknown;
+    readonly span?: MetaBoxFieldSpan;
+    /**
+     * Carried for reference field variants (`user`, `entry`, `term`,
+     * `media`, plugin-registered kinds). The admin's generic picker
+     * dispatches on `referenceTarget.kind` to call the matching
+     * lookup RPC; `scope` rides along untouched.
+     */
+    readonly referenceTarget?: ReferenceTarget;
+    /**
+     * Richtext field allowlists — wire projection of
+     * `RichtextMetaBoxField`'s `marks` / `nodes` / `blocks`. See that
+     * type for semantics.
+     */
+    readonly marks?: readonly string[];
+    readonly nodes?: readonly string[];
+    readonly blocks?: readonly string[];
+    /**
+     * Repeater subfield manifest, keyed positionally — same shape as a
+     * top-level field minus `span` (rows are full-width). Sanitize
+     * callbacks are stripped from the wire shape; the admin recurses
+     * through this list when rendering each row.
+     */
+    readonly subFields?: readonly EntryMetaBoxFieldManifestEntry[];
+    /**
+     * Capability gate for the individual field. See `MetaBoxFieldBase.capability`.
+     */
+    readonly capability?: string;
+}
+/**
+ * Shared base for every "card of fields" serialised entry. Each
+ * concrete projection extends with its identifier + any surface-
+ * specific layout + scope fields.
+ */
+export interface MetaBoxBaseManifestEntry {
+    readonly label: Label;
+    readonly description?: Label;
+    readonly priority?: number;
+    readonly capability?: string;
+    readonly fields: readonly MetaBoxFieldManifestEntry[];
+}
+/**
+ * Wire-side mirror of `EntryMetaBoxField` — drops `span` from the
+ * shared `MetaBoxFieldManifestEntry`. See `EntryMetaBoxField` for why.
+ */
+export type EntryMetaBoxFieldManifestEntry = Omit<MetaBoxFieldManifestEntry, "span">;
+export interface EntryMetaBoxManifestEntry extends Omit<MetaBoxBaseManifestEntry, "fields"> {
+    readonly id: string;
+    /**
+     * @deprecated Ignored by the admin editor — all entry meta boxes
+     * render in the document rail as collapsible sections. Kept on the
+     * wire so older plugins that set it don't fail manifest validation.
+     */
+    readonly location?: "bottom" | "sidebar";
+    readonly entryTypes: readonly string[];
+    readonly fields: readonly EntryMetaBoxFieldManifestEntry[];
+}
+export interface TermMetaBoxManifestEntry extends MetaBoxBaseManifestEntry {
+    readonly id: string;
+    readonly termTaxonomies: readonly string[];
+}
+export interface UserMetaBoxManifestEntry extends MetaBoxBaseManifestEntry {
+    readonly id: string;
+}
+/**
+ * Shape serialised for termTaxonomies in the manifest. Strict allowlist
+ * projection of `RegisteredTermTaxonomy` — drops `registeredBy` (server-only
+ * debug metadata) and server-only operational flags (`isInQuickEdit`,
+ * `hasAdminColumn`, `rewrite`) that don't affect the admin UI today.
+ * `entryTypes` is kept so future admin surfaces (term-picker on post
+ * editor) can filter by post type without a second round-trip.
+ */
+export interface TermTaxonomyManifestEntry {
+    readonly name: string;
+    readonly label: Label;
+    /** Plugin-author-declared per-type labels — see
+     *  `EntryTypeManifestEntry.labels` for the cascade contract. */
+    readonly labels?: TermTaxonomyLabels;
+    readonly description?: string;
+    readonly isHierarchical?: boolean;
+    readonly entryTypes?: readonly string[];
+    /** Resolved visibility — see `EntryTypeManifestEntry`. */
+    readonly isPublic?: boolean;
+    readonly showUI?: boolean;
+    readonly showInSidebar?: boolean;
+    readonly menuIcon?: string;
+    /** Synonyms the command palette matches in addition to the sidebar label. */
+    readonly keywords?: readonly Label[];
+}
+/**
+ * Shape serialised for settings groups in the manifest. Same shared
+ * shape as every other meta surface; the storage key `name` replaces
+ * the meta-box `id`. Fields use the same `MetaBoxFieldManifestEntry`
+ * type — one field contract for plugin authors.
+ */
+export interface SettingsGroupManifestEntry extends MetaBoxBaseManifestEntry {
+    readonly name: string;
+}
+/**
+ * Shape serialised for settings pages in the manifest. Pages are pure
+ * admin-UI composition: `groups` names registered groups in render
+ * order, one shadcn `<Card>` per group in the admin route.
+ */
+export interface SettingsPageManifestEntry {
+    readonly name: string;
+    readonly label: Label;
+    readonly description?: Label;
+    readonly groups: readonly string[];
+    readonly priority?: number;
+}
+/**
+ * One row in the assembled admin sidebar tree. Sources contributing
+ * items: core (Dashboard, Users, Settings), entry types (auto-projected
+ * to the `content` group), term taxonomies (auto-projected to the
+ * `term-taxonomies` group), and plugin-registered admin pages with
+ * `nav` set.
+ *
+ * Exactly one of `icon` (plugin-supplied React component ref) or
+ * `coreIcon` (built-in lucide name) is set per item; admin picks a
+ * generic fallback when neither is provided.
+ *
+ * `component` is set only for plugin-rendered routes — the admin's
+ * `/p/$` catch-all looks up this ref to render the page. Items that
+ * point at core admin routes (`/`, `/users`, `/settings`,
+ * `/entries/<slug>`, etc.) leave it undefined.
+ */
+export interface AdminNavItem {
+    readonly to: string;
+    readonly label: Label;
+    readonly order?: number;
+    readonly capability?: string;
+    readonly icon?: PluginComponentRef;
+    readonly coreIcon?: CoreIconName;
+    readonly component?: PluginComponentRef;
+    readonly exact?: boolean;
+    /** Synonyms the command palette matches in addition to `label`. */
+    readonly keywords?: readonly Label[];
+}
+export interface AdminNavGroup {
+    readonly id: string;
+    readonly label: Label;
+    readonly priority?: number;
+    readonly icon?: PluginComponentRef;
+    readonly coreIcon?: CoreIconName;
+    readonly items: readonly AdminNavItem[];
+}
+export interface FieldTypeManifestEntry {
+    readonly type: string;
+    readonly component: PluginComponentRef;
+}
+export interface BlockManifestEntry {
+    readonly name: string;
+    readonly title: Label;
+    readonly category?: string;
+    readonly icon?: string;
+    readonly description?: Label;
+    readonly keywords?: readonly Label[];
+    readonly inserter?: boolean;
+    readonly variations?: readonly BlockVariation[];
+}
+export interface MarkManifestEntry {
+    readonly name: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly keyboardShortcut?: string;
+    readonly bubbleMenuLabel?: string;
+    readonly bubbleMenuIcon?: string;
+    /** Export name on the plugin's `adminEntry` module — see `MarkSpec.adminSchema`. */
+    readonly adminSchema?: string;
+}
+export interface PatternManifestEntry {
+    readonly name: string;
+    readonly title: Label;
+    readonly category?: string;
+    readonly keywords?: readonly Label[];
+    readonly insert?: PatternInsertMode;
+    readonly preview?: PatternPreview;
+    readonly target?: PatternTarget;
+    readonly entryTypes?: readonly string[];
+    readonly priority?: number;
+    readonly content: readonly BlockNode[];
+}
+/**
+ * Wire-shipped manifest payload. Every field is optional on the type
+ * so test fixtures can declare just the slice they exercise; the
+ * server's `buildManifest` always populates all of them and consumers
+ * coerce missing fields to `[]` at the read site.
+ */
+export interface PlumixManifest {
+    readonly entryTypes?: readonly EntryTypeManifestEntry[];
+    readonly termTaxonomies?: readonly TermTaxonomyManifestEntry[];
+    readonly entryMetaBoxes?: readonly EntryMetaBoxManifestEntry[];
+    readonly termMetaBoxes?: readonly TermMetaBoxManifestEntry[];
+    readonly userMetaBoxes?: readonly UserMetaBoxManifestEntry[];
+    readonly settingsGroups?: readonly SettingsGroupManifestEntry[];
+    readonly settingsPages?: readonly SettingsPageManifestEntry[];
+    readonly adminNav?: readonly AdminNavGroup[];
+    readonly dashboardWidgets?: readonly DashboardWidgetManifestEntry[];
+    readonly fieldTypes?: readonly FieldTypeManifestEntry[];
+    readonly blocks?: readonly BlockManifestEntry[];
+    readonly marks?: readonly MarkManifestEntry[];
+    readonly patterns?: readonly PatternManifestEntry[];
+    /**
+     * Theme tokens from `defineTheme({ tokens })`. Routed through the
+     * manifest channel because the precompiled admin shell can't import
+     * `plumix.config.ts` at build time.
+     */
+    readonly tokens?: ThemeTokens;
+    /**
+     * Theme responsive breakpoints from `defineTheme({ breakpoints })`. Same
+     * manifest-channel reason as `tokens`: the precompiled admin shell can't
+     * import the user's config, but the editor needs them for device widths.
+     */
+    readonly breakpoints?: ThemeBreakpoints;
+    /**
+     * Site i18n config — populates the locale-switcher dropdown and gives
+     * admin components access to the active default. Same channel reason as
+     * `tokens`: the precompiled admin shell can't import the user's config.
+     */
+    readonly i18n?: I18nManifest;
+    /**
+     * Per-plugin catalog URL maps for the i18n runtime registry (#697).
+     * Admin fetches `pluginI18n[id].catalogs[locale]` at boot, merges the
+     * loaded `messages` into the active Lingui instance. The source
+     * locale never has an entry (Lingui returns `descriptor.message`
+     * when active === source). Locales are intersected with the site's
+     * enabled list before emission. Plugins without an `i18n` slot
+     * don't appear here.
+     */
+    readonly pluginI18n?: PluginI18nManifest;
+}
+/** Per-plugin catalog URL maps. Flat record keyed by plugin id so
+ *  `manifest.pluginI18n[id]` is direct lookup; admin reads this
+ *  shape verbatim. */
+export type PluginI18nManifest = Readonly<Record<string, {
+    readonly catalogs: Readonly<Record<string, string>>;
+}>>;
+/** URL the admin runtime fetches to load a plugin's compiled catalog
+ *  for a given locale. Same-origin under `/_plumix/admin/...` so the
+ *  default CSP `script-src 'self'` covers the dynamic import. Widening
+ *  to absolute URLs (CDN-hosted catalogs) would need a CSP review.
+ *
+ *  Paired with `pluginCatalogStagedPath` — the plumix Vite plugin stages
+ *  each plugin's `.mjs` at that filesystem path so the URL resolves. */
+export declare function pluginCatalogUrl(pluginId: string, locale: string): string;
+/** Filesystem path (relative to the admin asset root) where the plumix
+ *  Vite plugin must stage `<plugin.i18n.catalogPath>/<locale>.mjs`.
+ *  Mirrors `pluginCatalogUrl` so a single edit retargets both ends of
+ *  the runtime fetch. */
+export declare function pluginCatalogStagedPath(pluginId: string, locale: string): string;
+export interface I18nManifest {
+    readonly defaultLocale: string;
+    readonly locales: readonly ResolvedLocale[];
+}
+/**
+ * Strict manifest shape — every slice is populated. `buildManifest`
+ * returns this; tests reading from it don't need `?.` everywhere. The
+ * wider `PlumixManifest` (all-optional) is what flows over the wire
+ * and what test fixtures construct.
+ */
+export type BuiltManifest = {
+    readonly [K in keyof PlumixManifest]-?: NonNullable<PlumixManifest[K]>;
+};
+/** Script tag id that carries the JSON-encoded manifest in the admin HTML. */
+export declare const MANIFEST_SCRIPT_ID = "plumix-manifest";
+export declare function emptyManifest(): PlumixManifest;
+/**
+ * Project a registry snapshot into its manifest form — the subset that ships
+ * to the admin bundle. Every surface with a `priority?: number` field —
+ * entry types, entry/term/user meta boxes, settings pages, settings groups —
+ * is sorted by `priority` ascending; ties break by `name` / `id`
+ * alphabetical so the shipped order is deterministic regardless of
+ * plugin install order.
+ *
+ * Throws `DuplicateAdminSlugError` if two post types resolve to the same
+ * admin slug — the admin router can't disambiguate `/entries/$slug` in that
+ * case, and catching it at build time is cheaper than a 404 at runtime.
+ */
+export declare function buildManifest(registry: PluginRegistry, options?: {
+    readonly tokens?: ThemeTokens;
+    readonly breakpoints?: ThemeBreakpoints;
+    readonly i18n?: ResolvedI18n;
+    readonly plugins?: readonly {
+        readonly id: string;
+        readonly i18n?: PluginI18nSlot;
+    }[];
+    /** Plugin ids whose catalogs admin already bakes into its bundle
+     *  via `import.meta.glob("../../../plugins/*"/locales/*.mjs")` —
+     *  emitting URLs for them double-loads at runtime. The plumix
+     *  vite plugin computes this set by inspecting which plugins
+     *  resolve through the `@plumix/plugin-<id>` convention against
+     *  the consumer's `node_modules`. Empty / omitted means every
+     *  i18n-slot plugin gets a URL. Only consulted alongside
+     *  `plugins`; passing this set without `plugins` is a no-op. */
+    readonly adminBundledPluginIds?: ReadonlySet<string>;
+}): BuiltManifest;
+/**
+ * Shared comparator: `priority` ascending (unspecified sorts last),
+ * ties broken by a caller-supplied stable key (id / name) in
+ * alphabetical order. Used by `buildManifest` server-side AND the
+ * admin's in-memory filter helpers so the shipped manifest and the
+ * admin filter paths agree on order regardless of registration
+ * sequence.
+ */
+export declare function byPriorityThen<T extends {
+    readonly priority?: number;
+}>(getKey: (item: T) => string): (a: T, b: T) => number;
+/**
+ * Seed per-field values from a server meta bag, falling back to each
+ * field's registered `default`. Shared by every admin form that owns
+ * meta state (entry editor, term edit route, user edit route, settings
+ * group card) — one shape, one behaviour.
+ */
+export declare function seedFromMetaBoxes(boxes: readonly {
+    readonly fields: readonly {
+        readonly key: string;
+        readonly default?: unknown;
+    }[];
+}[], stored: Readonly<Record<string, unknown>> | null | undefined): Record<string, unknown>;
+/**
+ * Derive the URL-safe admin slug for a post type. Prefers `plural` when
+ * set (allows "fish" → `fish`, "children" → `children`, etc.), falls back
+ * to `${name}s` which is English-biased but matches the common case.
+ * Non-alphanumerics collapse to single dashes; leading/trailing dashes
+ * are trimmed. Empty results throw — an empty slug would shadow
+ * `/entries/` itself in TanStack Router.
+ */
+export declare function deriveAdminSlug(name: string, plural?: string): string;
+/**
+ * Serialise a manifest into the `<script>` markup injected into the admin
+ * `index.html`. The payload lives inside a `type="application/json"` block,
+ * so it isn't executed — but a stray `</script>` sequence would still end
+ * the tag and leak the remainder into the document. Escape the slash to
+ * neutralise that, which is the standard JSON-in-HTML-script hardening.
+ */
+export declare function serializeManifestScript(manifest: PlumixManifest): string;
+/**
+ * Replace the `<script id="plumix-manifest">` placeholder in the admin's
+ * `index.html` with a freshly serialised manifest. Throws if the placeholder
+ * is missing — that's an indicator that the admin bundle is out of date
+ * (was built without the placeholder), and silently appending would mask
+ * the staleness.
+ */
+export declare function injectManifestIntoHtml(html: string, manifest: PlumixManifest): string;
+//# sourceMappingURL=manifest.d.ts.map