@pramen/cms 0.0.59 → 0.0.61

package/dist/index.d.ts

@@ -43,7 +43,29 @@ export interface FieldDefinition {
      *
      * Stored as text. Uniqueness is the schema's job (`unique(t.text())`).
      */
-     | "slug" | "media" | "select" | "repeater" | "group";
+     | "slug" | "media" | "select"
+    /**
+     * A pointer to a record that is NOT this row — another pramen row, or a record in a
+     * system the CMS does not own. Stored as an OPAQUE id (a string), so the same field
+     * links a `cms_pages` row, a collection row and an external CRM record alike.
+     *
+     * `optionsFrom` on a `select` is most of this already, and stays the ergonomic case for
+     * a short closed list: it fetches `{ value, label }[]` ONCE and renders a `<select>`.
+     * What it cannot do is scale — no search term, no paging, and no way to render the
+     * label of a value whose record is not in the first (only) page. Twenty campaigns are
+     * fine; a thousand records are a dropdown nobody can use and a stored id that renders
+     * as a uuid.
+     *
+     * So a reference declares `referenceFrom`, a query handler called with BOTH shapes:
+     *
+     *   { search?: string; limit: number; offset: number }  -> browse / search
+     *   { ids: string[] }                                   -> resolve stored values
+     *
+     * and returning `{ items: ReferenceOption[]; hasMore?: boolean }` either way. The
+     * second shape is what makes an already-stored value renderable without fetching the
+     * whole set — the reason this is a field type and not a wider `select`.
+     */
+     | "reference" | "repeater" | "group";
     required?: boolean;
     default?: unknown;
     /** repeater/group only — the nested fields. */
@@ -58,6 +80,28 @@ export interface FieldDefinition {
     optionsFrom?: string;
     /** slug only — the sibling field this one is derived from (e.g. `"title"`). */
     from?: string;
+    /** reference only — the query handler that resolves this reference. See the `reference`
+     * type above for the two request shapes it must answer. */
+    referenceFrom?: string;
+    /** reference only — store a LIST of ids rather than one. A multiple reference is a
+     * `t.json()` column (an array), a single one is `t.text()`; `validateCollections`
+     * enforces the difference, because storing an array in a TEXT column is a raw driver
+     * error on the first write and nothing earlier. */
+    multiple?: boolean;
+}
+/** One option a `reference` field's `referenceFrom` handler returns. `hint` is secondary
+ * text (a date, an owner, a status) shown under the label — a picker over a thousand
+ * records usually needs more than a name to tell two rows apart. */
+export interface ReferenceOption {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** What a `reference` field's `referenceFrom` handler returns, for BOTH request shapes.
+ * `hasMore` drives the picker's "Load more"; omitting it means "this is everything". */
+export interface ReferenceResult {
+    items: ReferenceOption[];
+    hasMore?: boolean;
 }
 /** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
  * may be placed there — `null`/omitted means any. */
@@ -103,7 +147,9 @@ export interface RichTextMark {
 export type RichText = RichTextDoc;
 /** Map one FieldDefinition (as a const literal) to the TS type of its RENDERED value.
  * Media resolves to `ResolvedMedia` (the assemble-time shape a component receives). */
-export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish" | "slug" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
+export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish" | "slug" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "reference" ? (D extends {
+    multiple: true;
+} ? string[] : string) : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
 /** Infer the `fields` object type from a const `FieldDefinition[]`. Required fields are
  * present; optional ones are `| undefined`. */
 export type InferBlockFields<T extends readonly FieldDefinition[]> = {
@@ -165,6 +211,8 @@ export declare function defineContentType(slug: string, opts: {
     regions: readonly RegionDefinition[];
     defaultBlocks?: readonly DefaultBlockDefinition[];
 }): ContentTypeDef;
+/** The default `owner` — see {@link cmsBootstrap}. */
+export declare const CMS_BOOTSTRAP_OWNER = "cms";
 /** Build a pramen `bootstrap` reconciler that upserts code-defined block + content types by
  * `slug` on each boot. Idempotent: inserts a missing type, updates a drifted one, leaves an
  * identical one untouched. Register it on your app:
@@ -173,10 +221,21 @@ export declare function defineContentType(slug: string, opts: {
  *     bootstrap: [ cmsBootstrap({ blockTypes: [...], contentTypes: [...] }) ] };
  *
  * Runs with a privileged system Db, so a fresh/reprovisioned database converges to the
- * code-declared types with no manual createContentType/createBlockType call. */
+ * code-declared types with no manual createContentType/createBlockType call.
+ *
+ * Every row it writes is stamped `managedBy: owner`, which makes the editor show it
+ * read-only — convergence and an editor pointed at the same rows are otherwise a silent
+ * data-loss pair (GitHub #48). A type that drops out of the declaration is released back to
+ * the editor; a row this owner did not write is never touched, so a second reconciler (a
+ * package shipping its own block types, say) composes as long as it passes its own `owner`.
+ *
+ * The definitions are validated HERE, when the app is constructed, and every problem is
+ * reported at once — see {@link validateCmsDefinitions}. */
 export declare function cmsBootstrap(defs: {
     blockTypes?: readonly BlockTypeDef[];
     contentTypes?: readonly ContentTypeDef[];
+}, opts?: {
+    owner?: string;
 }): BootstrapFn;
 /** Emit a `.ts` module of per-slug field interfaces + a `BlockFieldsBySlug` registry from
  * DB-stored block types (`{ slug, fieldsSchema }` rows). The runtime counterpart to the
@@ -187,6 +246,104 @@ export declare function generateBlockTypes(blockTypes: Array<{
 }>): string;
 /** The block/page builder tables. All in the default partition (relations can't cross
  * partitions). Prefixed `cms_` to avoid colliding with your own entities. */
+/** What a menu item points at.
+ *
+ * `custom` is a literal href. The rest are REFERENCES resolved at read time, which is the
+ * whole reason the kind exists: a menu that stored `/about` verbatim breaks silently the
+ * day the page's slug changes, and the redirect that covers it is a second thing to
+ * remember. A `page` item follows the page. */
+export type MenuItemKind = "custom" | "page" | "term" | "collection";
+/** One entry in a menu tree. */
+export interface MenuItem {
+    /** Stable within the menu — the editor's list key and the only handle a reorder has. */
+    id: string;
+    label: string;
+    /** Defaults to `"custom"` (a literal `url`). */
+    kind?: MenuItemKind;
+    /** `page`: a `cms_pages` id · `term`: a `cms_terms` id · `collection`: a collection slug. */
+    ref?: string | null;
+    /** `custom`: the href, stored verbatim (and `isSafeHref`-checked on write). For the
+     * resolved kinds this is FILLED IN by `getMenu` and ignored on write. */
+    url?: string;
+    target?: string;
+    titleAttr?: string;
+    cssClasses?: string;
+    children?: MenuItem[];
+}
+/** A named navigation menu. Read whole with `getMenu(name)`. */
+export interface Menu {
+    id: string;
+    name: string;
+    label: string;
+    items: MenuItem[];
+}
+/** How deep a menu tree may nest. Menus are stored as one document, so without a cap a
+ * client could post a tree deep enough to blow the stack in the resolver — and no real
+ * navigation is more than three levels anyway. */
+export declare const MAX_MENU_DEPTH = 5;
+/** How many items one menu may hold, at every level combined.
+ *
+ * Depth alone is not a bound: a FLAT list of 800 `page` items is legal under
+ * `MAX_MENU_DEPTH` and turns every anonymous `getMenu` — the read on every page render of
+ * the site — into a single `WHERE id IN (?×800)`, which the read engine emits with no
+ * chunking. Every other read added alongside this one is bounded (`MAX_TERMS`,
+ * `clampLimit`); this one was not, and it is the one on the hot path. */
+export declare const MAX_MENU_ITEMS = 200;
+/** A classification vocabulary — `category`, `tag`, `region`, whatever the site sorts by. */
+export interface Taxonomy {
+    id: string;
+    slug: string;
+    label: string;
+    pluralLabel?: string | null;
+    description?: string | null;
+    /** Terms may declare a `parentId`. A flat vocabulary REJECTS one on write, rather than
+     * accepting it and rendering it nowhere. */
+    hierarchical: boolean;
+}
+/** One term in a vocabulary. `children` is present only on the tree read (`getTermTree`). */
+export interface Term {
+    id: string;
+    taxonomyId: string;
+    slug: string;
+    label: string;
+    description?: string | null;
+    parentId?: string | null;
+    position: number;
+    children?: Term[];
+}
+/** How deep a term hierarchy may nest — the same argument as {@link MAX_MENU_DEPTH}, except
+ * here the tree is rows and the risk is a parent CYCLE, which `assertTermParent` refuses. */
+export declare const MAX_TERM_DEPTH = 5;
+/** What a widget renders. `component` is the escape hatch: the CMS stores an id + props and
+ * the front end maps the id to one of its own components, exactly as `BlockRenderer` maps a
+ * block type slug — so a widget area can hold something the CMS has no idea how to draw. */
+export type WidgetType = "content" | "menu" | "component";
+/** One widget in a widget area. */
+export interface Widget {
+    id: string;
+    type: WidgetType;
+    title?: string | null;
+    /** `content`: a rich-text document (normalized on write like any other richtext value). */
+    content?: RichTextDoc;
+    /** `menu`: a `cms_menus.name`. `getWidgetArea` resolves it to `menu` alongside. */
+    menuName?: string;
+    /** `component`: the front end's own component id + its props. */
+    componentId?: string;
+    componentProps?: FieldValues;
+}
+/** A widget as READ back: a `menu` widget carries its resolved menu, so a layout renders a
+ * whole sidebar from one call rather than one call per widget. */
+export interface ResolvedWidget extends Widget {
+    menu?: Menu | null;
+}
+/** A named template region an admin fills without touching code. */
+export interface WidgetArea {
+    id: string;
+    name: string;
+    label: string;
+    description?: string | null;
+    widgets: ResolvedWidget[];
+}
 export declare const cmsSchema: {
     cms_content_types: import("@pramen/server").EntityDef<{
         id: {
@@ -221,6 +378,9 @@ export declare const cmsSchema: {
         defaultBlocks: {
             readonly type: "json";
         };
+        managedBy: {
+            readonly type: "text";
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -260,6 +420,9 @@ export declare const cmsSchema: {
         category: {
             readonly type: "text";
         };
+        managedBy: {
+            readonly type: "text";
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -428,6 +591,13 @@ export declare const cmsSchema: {
             readonly target: "cms_page_blocks";
             readonly column: string;
         };
+        terms: {
+            readonly kind: "manyToMany";
+            readonly target: "cms_terms";
+            readonly through: string;
+            readonly sourceColumn: string;
+            readonly targetColumn: string;
+        };
     }>;
     cms_page_blocks: import("@pramen/server").EntityDef<{
         id: {
@@ -600,6 +770,270 @@ export declare const cmsSchema: {
             readonly type: "text";
         };
     }, Record<string, never>>;
+    cms_menus: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        name: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        label: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        items: {
+            readonly type: "json";
+        };
+        version: {
+            readonly type: "integer";
+        } & {
+            readonly default: 1;
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+        updatedAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_redirects: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        fromPath: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        toPath: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        status: {
+            readonly type: "integer";
+        } & {
+            readonly default: 301;
+        };
+        enabled: {
+            readonly type: "boolean";
+        } & {
+            readonly default: true;
+        };
+        note: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+        updatedAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_taxonomies: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        slug: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        label: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        pluralLabel: {
+            readonly type: "text";
+        };
+        description: {
+            readonly type: "text";
+        };
+        hierarchical: {
+            readonly type: "boolean";
+        } & {
+            readonly default: false;
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
+    cms_terms: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        taxonomyId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        slug: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        label: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        description: {
+            readonly type: "text";
+        };
+        parentId: {
+            readonly type: "uuid";
+        };
+        position: {
+            readonly type: "integer";
+        } & {
+            readonly default: 0;
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, {
+        taxonomy: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_taxonomies";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+        parent: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_terms";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+        pages: {
+            readonly kind: "hasMany";
+            readonly target: "cms_page_terms";
+            readonly column: string;
+        };
+    }>;
+    cms_page_terms: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        pageId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        termId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+    }, {
+        page: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_pages";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+        term: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_terms";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+    }>;
+    cms_widget_areas: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        name: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly unique: true;
+        };
+        label: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        };
+        description: {
+            readonly type: "text";
+        };
+        widgets: {
+            readonly type: "json";
+        };
+        version: {
+            readonly type: "integer";
+        } & {
+            readonly default: 1;
+        };
+        createdAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+        updatedAt: {
+            readonly type: "text";
+        } & {
+            readonly defaultExpr: string;
+        };
+    }, Record<string, never>>;
     cms_media: import("@pramen/server").EntityDef<{
         id: {
             readonly type: "uuid";
@@ -627,6 +1061,28 @@ export declare const cmsSchema: {
         };
     }, Record<string, never>>;
 };
+/** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
+ * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
+export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+export type { AdminBlock, AdminButton, AdminElement, AdminInput, AdminInteractionType, AdminPageDef, AdminPageHandlerOpts, AdminPageInteraction, AdminPageMeta, AdminPageResponse, AdminText, } from "./blockkit";
+/**
+ * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
+ *
+ * `isoTimestampBackfill()` finds every column whose DEFAULT is `expr.now()` on its own.
+ * `cms_pages.publishedAt` has no default at all — `doPublish` stamped it from handler code,
+ * in the same space form, to stay comparable with the `updatedAt` written beside it. There
+ * is nothing on that column to find, so it is named here.
+ *
+ * Spread it into the migration if your store was ever written by a build older than this
+ * one:
+ *
+ * ```ts
+ * migrations: [isoTimestampBackfill({ extraColumns: CMS_LEGACY_TIMESTAMP_COLUMNS })]
+ * ```
+ *
+ * Costs nothing on a store that was not — the UPDATE matches no rows.
+ */
+export declare const CMS_LEGACY_TIMESTAMP_COLUMNS: Readonly<Record<string, readonly string[]>>;
 export interface ValidateOpts {
     /** Enforce `required` fields (reject when missing). Default true. Editor-facing draft
      * writes (addBlock/updateBlock/createPage) pass `false` — a DRAFT block may be incomplete;
@@ -644,6 +1100,43 @@ export interface ValidateOpts {
     legacyBaseline?: FieldValues;
 }
 export declare function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path?: string, opts?: ValidateOpts): void;
+/** Every field type the runtime knows. Exported because the editor's type-builder offers
+ * exactly this list — one definition, so a type added here appears there without a second
+ * edit, and a type removed here cannot be authored. */
+export declare const FIELD_TYPES: readonly FieldDefinition["type"][];
+/** How deep an authored field schema may nest. A schema is rendered by a recursive
+ * component and validated by a recursive function, so the cap is what keeps both bounded
+ * against a hand-posted document; nothing real nests past two or three. */
+export declare const MAX_FIELD_DEPTH = 5;
+/**
+ * Validate and canonicalize an authored `FieldDefinition[]`, throwing a 400 on the first
+ * problem. Returns the CLEANED schema — each field rebuilt from the keys its type actually
+ * uses, so a `select`'s stale `options` cannot ride along on a field someone switched to
+ * `text` and reappear if they switch back.
+ */
+export declare function validateFieldSchema(raw: unknown, path?: string, depth?: number): FieldDefinition[];
+/** Resolve `slug` cross-references inside one schema, now that every sibling is known: a
+ * `slug` field's `from` must name a field that exists AT THE SAME LEVEL (the editor reads
+ * it out of the sibling bag) and holds text. Separate pass because forward references are
+ * legitimate — a slug may precede the title it follows. */
+export declare function checkSlugSources(schema: readonly FieldDefinition[], path?: string): void;
+/** Validate + canonicalize an authored field schema end to end. */
+export declare function normalizeFieldSchema(raw: unknown, path?: string): FieldDefinition[];
+/**
+ * Validate a content type's `regions`.
+ *
+ * A region NAME is the key `addBlock({ region })` resolves and the key of the assembled
+ * `regions` object a front end reads, so it is held to the same shape as a field name. An
+ * `allowedTypes` entry is a block-type SLUG; it is not checked against the block types that
+ * exist, on purpose — a content type declaring a region for a block type that has not been
+ * created yet is an ordinary order of work, and `assertRegionAllows` is what enforces the
+ * list at placement time.
+ */
+export declare function normalizeRegions(raw: unknown): RegionDefinition[];
+/** Validate a content type's `defaultBlocks` against its own regions. A default block that
+ * names a region the type does not declare is created into nowhere — `createPage` would
+ * place it under a key no renderer reads. */
+export declare function normalizeDefaultBlocks(raw: unknown, regions: readonly RegionDefinition[]): DefaultBlockDefinition[];
 /** The node/mark vocabulary a `richtext` value may use. A node entry maps a node type to
  * the attribute names kept on it; a mark entry does the same for a mark type. */
 export interface RichTextSchema {
@@ -760,6 +1253,58 @@ export declare function imageUrl(key: string, opts?: {
     quality?: number;
     format?: "auto" | "webp" | "avif";
 }): string;
+/** Refuse an editor write to a CODE-DEFINED type.
+ *
+ * `cmsBootstrap` reconciles these rows on every boot, so a save here would return 200 and
+ * then be reverted at the next cold start, taking any content authored against the added
+ * field with it. A 409 is the honest answer: the row exists, the edit is well-formed, and
+ * the conflict is with a definition that lives somewhere this request cannot reach.
+ *
+ * The editor renders a managed type read-only, so this is the curl / stale-tab half.
+ *
+ * The caller MUST have read `managedBy` explicitly (`select`), not taken it off a wide read.
+ * Reads are column-projected against the caller's policy, so under a read policy with a
+ * `fields` list the column is simply absent — and a guard written as "absent means editable"
+ * disarms itself for exactly the deployments that restrict fields. `select` fails CLOSED
+ * instead: an unreadable column is a 403 before this runs. */
+export declare function assertNotManaged(row: Record<string, unknown>, what: string, defineFn: string): void;
+/** Where a resolved menu item points. Passed to `menuHref` so a deployment can route its
+ * own way without the CMS guessing. */
+export type MenuHrefTarget = {
+    kind: "page";
+    slug: string;
+    locale: string;
+} | {
+    kind: "term";
+    taxonomy: string;
+    slug: string;
+} | {
+    kind: "collection";
+    slug: string;
+};
+/** A URL redirect's status. 301/308 are permanent (cached by browsers, and by search
+ * engines as a canonical move); 302/307 are not. Anything else is not a redirect. */
+export declare const REDIRECT_STATUSES: readonly number[];
+/**
+ * The stored form of a redirect's `fromPath`: a rooted, query-less, fragment-less path.
+ *
+ * Canonicalized rather than merely validated, because matching is an exact string lookup
+ * against a UNIQUE column. `"/old"` and `"/old/"` are the same URL to a visitor and two
+ * rows here, so the second one is dead the moment the first exists — and which one wins is
+ * whichever the editor happened to type. Trailing slash off (except the root), fragment
+ * and query dropped, percent-encoding left exactly as written (the parser's, and the
+ * request's, canonical form).
+ */
+export declare function normalizeRedirectPath(raw: unknown): string;
+/** A redirect's editable fields, as posted. `requireEnds` is the CREATE case, where both
+ * ends must be present; an update patches whichever keys it sends. */
+interface RedirectPatch {
+    fromPath?: string;
+    toPath?: string;
+    status?: number;
+    enabled?: boolean;
+    note?: string | null;
+}
 /** What a preview link authorizes: one page, in one tenant, until `exp`. */
 export interface PreviewToken {
     /** tenant */ t: string;
@@ -821,6 +1366,14 @@ export interface CmsHandlerOpts {
      * (what the shipped editor produces). Widen it if your editor adds TipTap extensions —
      * a node type absent from the schema is DROPPED on write, not rejected. */
     richTextSchema?: RichTextSchema;
+    /** Map a resolved menu reference to a site path. The CMS is headless, so it cannot know
+     * how a deployment routes — this is the same seam `sitemapXml`'s `pageUrl` is.
+     *
+     * Defaults: a page is `/${slug}` on a monolingual deployment and `/${locale}/${slug}`
+     * once `locales` declares more than one; a term is `/${taxonomy}/${term}`; a collection
+     * is `/${slug}/`. Override it and `getMenu` follows — which is the point of storing a
+     * REFERENCE rather than the href an editor typed: change the routing, not the menu. */
+    menuHref?: (target: MenuHrefTarget) => string;
 }
 /** Build the CMS handler map. Spread into your app's handlers. Editor mutations are
  * gated both by `auth` (fast 403 before the body) and by the row ACL (cmsPolicies). */
@@ -863,6 +1416,188 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         fieldsSchema?: FieldDefinition[];
         defaultBlocks?: DefaultBlockDefinition[];
     }, Record<string, unknown> | undefined>;
+    /** One menu, references resolved to hrefs. PUBLIC — a menu is site chrome.
+     *
+     * Returns `null` for an unknown name rather than 404ing, because a layout asking for a
+     * menu it has not created yet is the normal state of a site being built, and a thrown
+     * error there takes down every page instead of rendering no nav. */
+    getMenu: import("@pramen/server").Handler<{
+        name: string;
+    }, Menu | null>;
+    /** Every menu, RAW (references unresolved) — the editor's list.
+     *
+     * Capped like every other list here. A site-furniture table is small by nature, which is
+     * an argument for the cap being generous, not for its absence: an unbounded SELECT of a
+     * wide row over RPC is the D1 failure shape from GitHub #22, and "small by nature" is
+     * not a property the query planner knows about. */
+    listMenus: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createMenu: import("@pramen/server").Handler<{
+        name: string;
+        label: string;
+        items?: MenuItem[];
+    }, Record<string, unknown>>;
+    /** Patch a menu found by `id` or `name`. `name` is the key layout code resolves and is
+     * NOT mutable — retitling is what `label` is for. */
+    updateMenu: import("@pramen/server").Handler<{
+        id?: string;
+        name?: string;
+        label?: string;
+        items?: MenuItem[];
+        expectedVersion?: number;
+    }, Record<string, unknown> | undefined>;
+    deleteMenu: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Resolve a request path to its redirect, or `null`. PUBLIC and READ-ONLY: this is
+     * what a front end calls on a 404, so it is anonymous traffic on the hot path.
+     *
+     * `enabled` is enforced by the public read POLICY, not by a `where` here, so a disabled
+     * redirect is invisible to every anonymous read (this handler, a future listing, a
+     * relation traversal) rather than to the one call that remembered to filter. */
+    resolveRedirect: import("@pramen/server").Handler<{
+        path: string;
+    }, {
+        to: string;
+        status: number;
+    } | null>;
+    listRedirects: import("@pramen/server").Handler<{
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    createRedirect: import("@pramen/server").Handler<RedirectPatch & {
+        fromPath: string;
+        toPath: string;
+    }, Record<string, unknown>>;
+    updateRedirect: import("@pramen/server").Handler<RedirectPatch & {
+        id: string;
+    }, Record<string, unknown> | undefined>;
+    deleteRedirect: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
+     * is a URL segment) and a front end routes on it. */
+    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createTaxonomy: import("@pramen/server").Handler<{
+        slug: string;
+        label: string;
+        pluralLabel?: string;
+        description?: string;
+        hierarchical?: boolean;
+    }, Record<string, unknown>>;
+    /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
+     * is not mutable — the same rule content types and block types already follow.
+     *
+     * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
+     * would leave a stored hierarchy that no reader renders and no writer can clear, and
+     * flattening the terms silently is a destructive edit behind a checkbox. */
+    updateTaxonomy: import("@pramen/server").Handler<{
+        id: string;
+        label?: string;
+        pluralLabel?: string | null;
+        description?: string | null;
+        hierarchical?: boolean;
+    }, Record<string, unknown> | undefined>;
+    /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
+     * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
+     * by a handler that threw between two writes. */
+    deleteTaxonomy: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** One vocabulary's terms, flat, ordered. PUBLIC. */
+    listTerms: import("@pramen/server").Handler<{
+        taxonomy: string;
+    }, Term[]>;
+    /** One vocabulary's terms as a TREE. PUBLIC. Assembled here rather than by the caller
+     * because a hierarchy is what the nav renders and every consumer would otherwise write
+     * the same fold. */
+    getTermTree: import("@pramen/server").Handler<{
+        taxonomy: string;
+    }, Term[]>;
+    createTerm: import("@pramen/server").Handler<{
+        taxonomy: string;
+        slug: string;
+        label: string;
+        description?: string;
+        parentId?: string | null;
+        position?: number;
+    }, Record<string, unknown>>;
+    updateTerm: import("@pramen/server").Handler<{
+        id: string;
+        slug?: string;
+        label?: string;
+        description?: string | null;
+        parentId?: string | null;
+        position?: number;
+    }, Record<string, unknown> | undefined>;
+    /** Delete a term. Children are promoted to the top level (`ON DELETE SET NULL`) and
+     * page assignments are removed (`ON DELETE CASCADE`) — see `cms_terms.parentId`. */
+    deleteTerm: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** A page's assigned terms. PUBLIC (a published page's classification is public). */
+    listPageTerms: import("@pramen/server").Handler<{
+        pageId: string;
+    }, Term[]>;
+    /** Replace a page's term assignments wholesale.
+     *
+     * Set semantics, not add/remove: the editor's panel holds the whole selection, and two
+     * calls that each patch one end of it race into a state neither asked for. Existing
+     * links that survive are LEFT ALONE rather than deleted and reinserted, so the junction
+     * rows (and any future column on them) are stable across a save that changed nothing. */
+    setPageTerms: import("@pramen/server").Handler<{
+        pageId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
+    /** Published pages carrying a term. PUBLIC.
+     *
+     * A relation traversal (`where: { terms: { id } }`), so the page read scope is
+     * AND-merged as it is anywhere else — traversal cannot widen access, and an anonymous
+     * caller sees published pages only. */
+    listPagesByTerm: import("@pramen/server").Handler<{
+        taxonomy: string;
+        term: string;
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    /** One widget area, with `menu` widgets resolved to their menus. PUBLIC.
+     *
+     * `null` for an unknown name, for the same reason `getMenu` returns null: a layout
+     * asking for a sidebar nobody has filled in yet is the normal state of a site under
+     * construction, and throwing there takes down the page. */
+    getWidgetArea: import("@pramen/server").Handler<{
+        name: string;
+    }, WidgetArea | null>;
+    listWidgetAreas: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createWidgetArea: import("@pramen/server").Handler<{
+        name: string;
+        label: string;
+        description?: string;
+        widgets?: Widget[];
+    }, Record<string, unknown>>;
+    updateWidgetArea: import("@pramen/server").Handler<{
+        id?: string;
+        name?: string;
+        label?: string;
+        description?: string | null;
+        widgets?: Widget[];
+        expectedVersion?: number;
+    }, Record<string, unknown> | undefined>;
+    deleteWidgetArea: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
     /** Mint a signed upload URL for a media blob (keyed under the tenant's `media/`
      * prefix so the public /media route can serve it). The client PUTs the bytes to
      * `url`, then calls `createMedia` with the returned `ref`. */
@@ -1050,6 +1785,9 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         defaultLocale: string;
         multilingual: boolean;
         pagesByType: true;
+        siteFurniture: true;
+        codeDefinedTypes: true;
+        canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
      * store — not configuration. `listCmsCapabilities().locales` is what the deployment
@@ -1277,6 +2015,188 @@ export declare const cmsHandlers: {
         fieldsSchema?: FieldDefinition[];
         defaultBlocks?: DefaultBlockDefinition[];
     }, Record<string, unknown> | undefined>;
+    /** One menu, references resolved to hrefs. PUBLIC — a menu is site chrome.
+     *
+     * Returns `null` for an unknown name rather than 404ing, because a layout asking for a
+     * menu it has not created yet is the normal state of a site being built, and a thrown
+     * error there takes down every page instead of rendering no nav. */
+    getMenu: import("@pramen/server").Handler<{
+        name: string;
+    }, Menu | null>;
+    /** Every menu, RAW (references unresolved) — the editor's list.
+     *
+     * Capped like every other list here. A site-furniture table is small by nature, which is
+     * an argument for the cap being generous, not for its absence: an unbounded SELECT of a
+     * wide row over RPC is the D1 failure shape from GitHub #22, and "small by nature" is
+     * not a property the query planner knows about. */
+    listMenus: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createMenu: import("@pramen/server").Handler<{
+        name: string;
+        label: string;
+        items?: MenuItem[];
+    }, Record<string, unknown>>;
+    /** Patch a menu found by `id` or `name`. `name` is the key layout code resolves and is
+     * NOT mutable — retitling is what `label` is for. */
+    updateMenu: import("@pramen/server").Handler<{
+        id?: string;
+        name?: string;
+        label?: string;
+        items?: MenuItem[];
+        expectedVersion?: number;
+    }, Record<string, unknown> | undefined>;
+    deleteMenu: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Resolve a request path to its redirect, or `null`. PUBLIC and READ-ONLY: this is
+     * what a front end calls on a 404, so it is anonymous traffic on the hot path.
+     *
+     * `enabled` is enforced by the public read POLICY, not by a `where` here, so a disabled
+     * redirect is invisible to every anonymous read (this handler, a future listing, a
+     * relation traversal) rather than to the one call that remembered to filter. */
+    resolveRedirect: import("@pramen/server").Handler<{
+        path: string;
+    }, {
+        to: string;
+        status: number;
+    } | null>;
+    listRedirects: import("@pramen/server").Handler<{
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    createRedirect: import("@pramen/server").Handler<RedirectPatch & {
+        fromPath: string;
+        toPath: string;
+    }, Record<string, unknown>>;
+    updateRedirect: import("@pramen/server").Handler<RedirectPatch & {
+        id: string;
+    }, Record<string, unknown> | undefined>;
+    deleteRedirect: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
+     * is a URL segment) and a front end routes on it. */
+    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createTaxonomy: import("@pramen/server").Handler<{
+        slug: string;
+        label: string;
+        pluralLabel?: string;
+        description?: string;
+        hierarchical?: boolean;
+    }, Record<string, unknown>>;
+    /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
+     * is not mutable — the same rule content types and block types already follow.
+     *
+     * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
+     * would leave a stored hierarchy that no reader renders and no writer can clear, and
+     * flattening the terms silently is a destructive edit behind a checkbox. */
+    updateTaxonomy: import("@pramen/server").Handler<{
+        id: string;
+        label?: string;
+        pluralLabel?: string | null;
+        description?: string | null;
+        hierarchical?: boolean;
+    }, Record<string, unknown> | undefined>;
+    /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
+     * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
+     * by a handler that threw between two writes. */
+    deleteTaxonomy: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** One vocabulary's terms, flat, ordered. PUBLIC. */
+    listTerms: import("@pramen/server").Handler<{
+        taxonomy: string;
+    }, Term[]>;
+    /** One vocabulary's terms as a TREE. PUBLIC. Assembled here rather than by the caller
+     * because a hierarchy is what the nav renders and every consumer would otherwise write
+     * the same fold. */
+    getTermTree: import("@pramen/server").Handler<{
+        taxonomy: string;
+    }, Term[]>;
+    createTerm: import("@pramen/server").Handler<{
+        taxonomy: string;
+        slug: string;
+        label: string;
+        description?: string;
+        parentId?: string | null;
+        position?: number;
+    }, Record<string, unknown>>;
+    updateTerm: import("@pramen/server").Handler<{
+        id: string;
+        slug?: string;
+        label?: string;
+        description?: string | null;
+        parentId?: string | null;
+        position?: number;
+    }, Record<string, unknown> | undefined>;
+    /** Delete a term. Children are promoted to the top level (`ON DELETE SET NULL`) and
+     * page assignments are removed (`ON DELETE CASCADE`) — see `cms_terms.parentId`. */
+    deleteTerm: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** A page's assigned terms. PUBLIC (a published page's classification is public). */
+    listPageTerms: import("@pramen/server").Handler<{
+        pageId: string;
+    }, Term[]>;
+    /** Replace a page's term assignments wholesale.
+     *
+     * Set semantics, not add/remove: the editor's panel holds the whole selection, and two
+     * calls that each patch one end of it race into a state neither asked for. Existing
+     * links that survive are LEFT ALONE rather than deleted and reinserted, so the junction
+     * rows (and any future column on them) are stable across a save that changed nothing. */
+    setPageTerms: import("@pramen/server").Handler<{
+        pageId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
+    /** Published pages carrying a term. PUBLIC.
+     *
+     * A relation traversal (`where: { terms: { id } }`), so the page read scope is
+     * AND-merged as it is anywhere else — traversal cannot widen access, and an anonymous
+     * caller sees published pages only. */
+    listPagesByTerm: import("@pramen/server").Handler<{
+        taxonomy: string;
+        term: string;
+        limit?: number;
+        offset?: number;
+    }, Record<string, unknown>[]>;
+    /** One widget area, with `menu` widgets resolved to their menus. PUBLIC.
+     *
+     * `null` for an unknown name, for the same reason `getMenu` returns null: a layout
+     * asking for a sidebar nobody has filled in yet is the normal state of a site under
+     * construction, and throwing there takes down the page. */
+    getWidgetArea: import("@pramen/server").Handler<{
+        name: string;
+    }, WidgetArea | null>;
+    listWidgetAreas: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    createWidgetArea: import("@pramen/server").Handler<{
+        name: string;
+        label: string;
+        description?: string;
+        widgets?: Widget[];
+    }, Record<string, unknown>>;
+    updateWidgetArea: import("@pramen/server").Handler<{
+        id?: string;
+        name?: string;
+        label?: string;
+        description?: string | null;
+        widgets?: Widget[];
+        expectedVersion?: number;
+    }, Record<string, unknown> | undefined>;
+    deleteWidgetArea: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
     /** Mint a signed upload URL for a media blob (keyed under the tenant's `media/`
      * prefix so the public /media route can serve it). The client PUTs the bytes to
      * `url`, then calls `createMedia` with the returned `ref`. */
@@ -1464,6 +2384,9 @@ export declare const cmsHandlers: {
         defaultLocale: string;
         multilingual: boolean;
         pagesByType: true;
+        siteFurniture: true;
+        codeDefinedTypes: true;
+        canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
      * store — not configuration. `listCmsCapabilities().locales` is what the deployment
@@ -1668,6 +2591,10 @@ export declare function cmsPolicies(opts?: CmsPolicyOpts): {
     public: Policy[];
     editor: Policy[];
 };
+/** Nav positions for the editor's built-in sections — see `./nav`. Re-exported here so a
+ * host writing `app.ts` imports it from the same place as `collection()`. It LIVES in a leaf
+ * module because `blockkit.ts` needs it too and must not depend on this one. */
+export { NAV_ORDER } from "./nav";
 /** Declares that a pramen entity is editable as a collection in the CMS editor. Both
  * halves live here: the runtime facts (entity, idField, validation via `fields`) and the
  * UI facts (labels, list columns, ordering). Mirror of {@link ContentTypeDef}. */
@@ -1699,6 +2626,16 @@ export interface CollectionDef {
         column: string;
         dir?: "asc" | "desc";
     };
+    /** Where this collection sits in the editor's primary nav. Lower comes first; ties keep
+     * declaration order. Defaults to `NAV_ORDER.collections`, which is between Pages and
+     * Media — where collections have always rendered.
+     *
+     * The point is not cosmetic. Before this the only extension seam was `extraNav`, which
+     * renders dead LAST and (by default, and for good reason) opens a new tab — so a
+     * project-specific section could only ever be a separate app bolted onto the end of the
+     * admin. A section that belongs beside Pages can now say so. See {@link NAV_ORDER} for
+     * the built-in positions to place against. */
+    readonly navOrder?: number;
     /** Workflow features this collection opts into — see {@link CollectionFeature}. Each is
      * backed by MANAGED COLUMNS on `entity` that the CMS writes and `fields` may not declare.
      * Validated against your schema at `createCollectionHandlers` time (which is why that call
@@ -1728,6 +2665,10 @@ export interface CollectionMeta {
     label: string;
     pluralLabel: string;
     icon?: string;
+    /** Nav position — see {@link CollectionDef.navOrder}. Always present in the meta (the
+     * default is filled here) so the editor sorts one list of numbers rather than deciding
+     * per entry whether a default applies. */
+    navOrder: number;
     fields: readonly FieldDefinition[];
     list: readonly string[];
     titleField: string;
@@ -1896,7 +2837,7 @@ export declare function createCollectionHandlers(collections: readonly Collectio
         revisionId: string;
     }, Record<string, unknown>>;
     /** Mint a signed link that shows ONE row's unpublished state, to whoever holds it.
-     * Mirrors `signPagePreview` — same secret, same TTL clamp, same D1 refusal, and the
+     * Mirrors `signPagePreview` — same secret, same TTL clamp, works on both stores, and the
      * same rule that the row is read through the ACL FIRST: minting a link is granting
      * access to the row, so a caller who cannot read it must not be able to mint one. */
     signCollectionPreview: import("@pramen/server").Handler<{