@pramen/cms 0.0.47 → 0.0.49

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue } from "@pramen/server";
+import type { EnvBag } from "@pramen/server";
 /** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
  * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
 export interface FieldDefinition {
@@ -31,7 +32,18 @@ export interface FieldDefinition {
      * next week would be anonymously readable the moment it was saved — the scheduling
      * affordance would be a UI label over no enforcement at all.
      */
-     | "publish" | "media" | "select" | "repeater" | "group";
+     | "publish"
+    /**
+     * A URL segment, derived from another field as you type.
+     *
+     * Set `from` to the field it follows (usually the title). The editor keeps them in
+     * sync only while the slug is untouched — once it has been edited, or on a row that
+     * already has one, it stops following, because silently rewriting a slug changes a
+     * live URL and breaks every link to it.
+     *
+     * Stored as text. Uniqueness is the schema's job (`unique(t.text())`).
+     */
+     | "slug" | "media" | "select" | "repeater" | "group";
     required?: boolean;
     default?: unknown;
     /** repeater/group only — the nested fields. */
@@ -44,6 +56,8 @@ export interface FieldDefinition {
     /** select only — fetch options at edit time from a query handler of this name (returns
      * `{ value, label }[]`), e.g. a live list of campaigns. Takes precedence over `options`. */
     optionsFrom?: string;
+    /** slug only — the sibling field this one is derived from (e.g. `"title"`). */
+    from?: string;
 }
 /** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
  * may be placed there — `null`/omitted means any. */
@@ -56,7 +70,7 @@ export interface RegionDefinition {
 export interface DefaultBlockDefinition {
     region: string;
     blockTypeSlug: string;
-    fields?: Record<string, unknown>;
+    fields?: FieldValues;
 }
 /** A rich-text value — a serialized editor document (or a plain string). */
 export type RichText = string | {
@@ -65,7 +79,7 @@ export type RichText = string | {
 };
 /** 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" ? 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 "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[]> = {
@@ -535,7 +549,7 @@ export interface ValidateOpts {
 export declare function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path?: string, opts?: ValidateOpts): void;
 /** Deep-sanitize the richtext fields in a values object against a field schema (recursing
  * into group/repeater). Returns a sanitized copy; non-richtext fields pass through. */
-export declare function sanitizeFields(schema: FieldDefinition[] | undefined | null, values: Record<string, unknown>): Record<string, unknown>;
+export declare function sanitizeFields(schema: FieldDefinition[] | undefined | null, values: FieldValues): FieldValues;
 export interface RenderedBlock {
     /** The placement id (cms_page_blocks) — stable per position; used for reorder/remove. */
     id: string;
@@ -543,7 +557,7 @@ export interface RenderedBlock {
     block_id: string;
     block_type: string;
     title: string | null;
-    fields: Record<string, unknown>;
+    fields: FieldValues;
     is_shared: boolean;
 }
 export interface PageTranslation {
@@ -573,7 +587,7 @@ export interface AssembledPage {
         translationGroupId: string | null;
         /** Published sibling locales of this page (for hreflang alternates). */
         translations: PageTranslation[];
-        fields: Record<string, unknown> | null;
+        fields: FieldValues | null;
         /** Back-compat: mirrors seo.metaTitle/metaDescription. */
         metaTitle: string | null;
         metaDescription: string | null;
@@ -581,6 +595,14 @@ export interface AssembledPage {
     };
     regions: Record<string, RenderedBlock[]>;
 }
+/** One authored field value inside a block / collection / page `fields` bag. Stored
+ * as JSON; a `"media"` field is resolved from its stored id to a `ResolvedMedia` at
+ * assemble time, and `group`/`repeater` fields nest further bags. */
+export type FieldValue = JsonValue | ResolvedMedia | FieldValues | FieldValue[];
+/** A block / collection / page `fields` bag — field name -> authored value. */
+export interface FieldValues {
+    [field: string]: FieldValue;
+}
 /** A `"media"` block field, resolved from a stored media id to a servable shape at
  * assemble time. `url` is the raw (full-size) serving path; pass `key` to `imageUrl()`
  * for on-the-fly transforms. `null` when the referenced media was deleted. */
@@ -724,7 +746,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         title?: string;
         slug?: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, {
         ok: boolean;
         page: Record<string, unknown>;
@@ -735,7 +757,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         title: string;
         slug: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, Record<string, unknown>>;
     /** Create a translation of an existing page: a new page in `locale` sharing the
      * source's translationGroupId (and content type). Content starts empty — the editor
@@ -765,7 +787,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         pageId: string;
         blockTypeSlug: string;
         region: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
         position?: number;
         isReusable?: boolean;
@@ -784,7 +806,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         blockId: string;
         region: string;
         position?: number;
-        overrides?: Record<string, unknown>;
+        overrides?: FieldValues;
     }, Record<string, unknown>>;
     /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
     getBlock: import("@pramen/server").Handler<{
@@ -793,7 +815,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     /** Update a block's content (re-validated against its type's field schema). */
     updateBlock: import("@pramen/server").Handler<{
         blockId: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
     }, Record<string, unknown> | undefined>;
     /** Reorder a region: `order` is the page_block ids in their new order. It must cover
@@ -994,7 +1016,7 @@ export declare const cmsHandlers: {
         title?: string;
         slug?: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, {
         ok: boolean;
         page: Record<string, unknown>;
@@ -1005,7 +1027,7 @@ export declare const cmsHandlers: {
         title: string;
         slug: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, Record<string, unknown>>;
     /** Create a translation of an existing page: a new page in `locale` sharing the
      * source's translationGroupId (and content type). Content starts empty — the editor
@@ -1035,7 +1057,7 @@ export declare const cmsHandlers: {
         pageId: string;
         blockTypeSlug: string;
         region: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
         position?: number;
         isReusable?: boolean;
@@ -1054,7 +1076,7 @@ export declare const cmsHandlers: {
         blockId: string;
         region: string;
         position?: number;
-        overrides?: Record<string, unknown>;
+        overrides?: FieldValues;
     }, Record<string, unknown>>;
     /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
     getBlock: import("@pramen/server").Handler<{
@@ -1063,7 +1085,7 @@ export declare const cmsHandlers: {
     /** Update a block's content (re-validated against its type's field schema). */
     updateBlock: import("@pramen/server").Handler<{
         blockId: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
     }, Record<string, unknown> | undefined>;
     /** Reorder a region: `order` is the page_block ids in their new order. It must cover
@@ -1323,7 +1345,7 @@ export declare function robotsTxt(opts: {
 interface RouteCtx {
     callPrivileged: (opts: {
         name: string;
-        input?: unknown;
+        input?: JsonValue;
         tenant?: string;
         roles?: string[];
     }) => Promise<Response>;
@@ -1331,7 +1353,7 @@ interface RouteCtx {
 interface CmsRoute {
     method: string;
     path: string;
-    handler: (request: Request, env: Readonly<Record<string, unknown>>, ctx: RouteCtx) => Promise<Response>;
+    handler: (request: Request, env: EnvBag, ctx: RouteCtx) => Promise<Response>;
 }
 /** Turnkey public routes for `GET /sitemap.xml` and `GET /robots.txt`. Spread into
  * `app.routes`. The sitemap pulls published pages via `callPrivileged(listPublishedPages)`.

package/dist/index.js

@@ -119,6 +119,7 @@ function tsTypeOf(f) {
         case "date":
         case "datetime":
         case "publish":
+        case "slug":
             return "string";
         case "richtext":
             return "RichText";
@@ -275,6 +276,12 @@ export const cmsSchema = {
 function isDateString(v) {
     return /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(v));
 }
+/** A URL segment: lowercase a-z/0-9 groups joined by single hyphens, capped like the editor
+ * control caps it. Normalization lives in the editor, but the editor is not the only writer —
+ * a script or another client posting "Hello World/../x" would otherwise land it in a route. */
+function isSlugString(v) {
+    return v.length <= 80 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v);
+}
 /** A date-time: `YYYY-MM-DDTHH:MM[:SS[.sss]][Z|±HH:MM]` (ISO 8601 / datetime-local). */
 function isDateTimeString(v) {
     return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.test(v) && Number.isFinite(Date.parse(v));
@@ -305,6 +312,13 @@ export function validateFields(schema, values, path = "", opts = {}) {
                     throw new BadRequest(`field '${at}' must be one of: ${def.options.join(", ")}`);
                 }
                 break;
+            // A slug is text on the wire; only the editor control differs.
+            case "slug":
+                if (typeof v !== "string")
+                    throw new BadRequest(`field '${at}' must be a string`);
+                if (!isSlugString(v))
+                    throw new BadRequest(`field '${at}' must be a slug (lowercase letters, digits and single hyphens)`);
+                break;
             case "richtext":
                 if (typeof v !== "string" && typeof v !== "object")
                     throw new BadRequest(`field '${at}' must be rich text`);
@@ -490,7 +504,9 @@ async function assembleLive(db, page) {
     // fields (id → ResolvedMedia) in one batched lookup across the whole page.
     const merged = placements.map((p) => {
         const block = asObj(p.block);
-        const fields = { ...asObj(block.fields), ...(p.isShared ? asObj(p.overrides) : {}) };
+        const fields = p.isShared
+            ? { ...asObj(block.fields), ...asObj(p.overrides) }
+            : { ...asObj(block.fields) };
         return { p, block, fields, schema: typeById.get(String(block.typeId))?.fieldsSchema };
     });
     const mediaIds = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "description": "Optional block/page builder for pramen — Drupal-Paragraphs-style typed blocks in named regions, reusable blocks, scheduled publishing, built entirely from pramen primitives.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.47",
+    "@pramen/server": "0.0.49",
     "xss": "^1.0.15"
   },
   "peerDependencies": {

package/src/index.ts

@@ -42,8 +42,9 @@ import {
   Forbidden,
   PramenError,
 } from "@pramen/server";
-import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue } from "@pramen/server";
 import { filterXSS } from "xss";
+import type { EnvBag } from "@pramen/server";
 
 // --- field schema DSL (the block-editor field language) ---------------------
 
@@ -88,6 +89,17 @@ export interface FieldDefinition {
      * affordance would be a UI label over no enforcement at all.
      */
     | "publish"
+    /**
+     * A URL segment, derived from another field as you type.
+     *
+     * Set `from` to the field it follows (usually the title). The editor keeps them in
+     * sync only while the slug is untouched — once it has been edited, or on a row that
+     * already has one, it stops following, because silently rewriting a slug changes a
+     * live URL and breaks every link to it.
+     *
+     * Stored as text. Uniqueness is the schema's job (`unique(t.text())`).
+     */
+    | "slug"
     | "media"
     | "select"
     | "repeater"
@@ -104,6 +116,8 @@ export interface FieldDefinition {
   /** select only — fetch options at edit time from a query handler of this name (returns
    * `{ value, label }[]`), e.g. a live list of campaigns. Takes precedence over `options`. */
   optionsFrom?: string;
+  /** slug only — the sibling field this one is derived from (e.g. `"title"`). */
+  from?: string;
 }
 
 /** A named region on a content type; `allowedTypes` (block-type slugs) restricts what
@@ -118,7 +132,7 @@ export interface RegionDefinition {
 export interface DefaultBlockDefinition {
   region: string;
   blockTypeSlug: string;
-  fields?: Record<string, unknown>;
+  fields?: FieldValues;
 }
 
 // --- hybrid typed blocks: compile-time inference over a const FieldDefinition[] --------
@@ -134,7 +148,7 @@ export type RichText = string | { type: string; content?: unknown[] };
 
 /** 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"
+export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish" | "slug"
   ? string
   : D["type"] extends "richtext"
     ? RichText
@@ -310,6 +324,7 @@ function tsTypeOf(f: FieldDefinition): string {
     case "date":
     case "datetime":
     case "publish":
+    case "slug":
       return "string";
     case "richtext":
       return "RichText";
@@ -501,6 +516,12 @@ export interface ValidateOpts {
 function isDateString(v: string): boolean {
   return /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(v));
 }
+/** A URL segment: lowercase a-z/0-9 groups joined by single hyphens, capped like the editor
+ * control caps it. Normalization lives in the editor, but the editor is not the only writer —
+ * a script or another client posting "Hello World/../x" would otherwise land it in a route. */
+function isSlugString(v: string): boolean {
+  return v.length <= 80 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v);
+}
 /** A date-time: `YYYY-MM-DDTHH:MM[:SS[.sss]][Z|±HH:MM]` (ISO 8601 / datetime-local). */
 function isDateTimeString(v: string): boolean {
   return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/.test(v) && Number.isFinite(Date.parse(v));
@@ -509,7 +530,7 @@ function isDateTimeString(v: string): boolean {
 export function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path = "", opts: ValidateOpts = {}): void {
   const requireRequired = opts.requireRequired !== false;
   const defs = Array.isArray(schema) ? schema : [];
-  const obj = (values ?? {}) as Record<string, unknown>;
+  const obj = (values ?? {}) as FieldValues;
   if (typeof obj !== "object" || Array.isArray(obj)) throw new BadRequest(`${path || "fields"} must be an object`);
   for (const def of defs) {
     const at = path ? `${path}.${def.name}` : def.name;
@@ -529,6 +550,11 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
           throw new BadRequest(`field '${at}' must be one of: ${def.options.join(", ")}`);
         }
         break;
+      // A slug is text on the wire; only the editor control differs.
+      case "slug":
+        if (typeof v !== "string") throw new BadRequest(`field '${at}' must be a string`);
+        if (!isSlugString(v)) throw new BadRequest(`field '${at}' must be a slug (lowercase letters, digits and single hyphens)`);
+        break;
       case "richtext":
         if (typeof v !== "string" && typeof v !== "object") throw new BadRequest(`field '${at}' must be rich text`);
         break;
@@ -591,15 +617,15 @@ function sanitizeRichText(html: string): string {
 
 /** Deep-sanitize the richtext fields in a values object against a field schema (recursing
  * into group/repeater). Returns a sanitized copy; non-richtext fields pass through. */
-export function sanitizeFields(schema: FieldDefinition[] | undefined | null, values: Record<string, unknown>): Record<string, unknown> {
+export function sanitizeFields(schema: FieldDefinition[] | undefined | null, values: FieldValues): FieldValues {
   const defs = Array.isArray(schema) ? schema : [];
-  const out: Record<string, unknown> = { ...values };
+  const out: FieldValues = { ...values };
   for (const def of defs) {
     const v = out[def.name];
     if (v == null) continue;
     if (def.type === "richtext" && typeof v === "string") out[def.name] = sanitizeRichText(v);
-    else if (def.type === "group" && typeof v === "object" && !Array.isArray(v)) out[def.name] = sanitizeFields(def.fields, v as Record<string, unknown>);
-    else if (def.type === "repeater" && Array.isArray(v)) out[def.name] = v.map((it) => (it && typeof it === "object" ? sanitizeFields(def.fields, it as Record<string, unknown>) : it));
+    else if (def.type === "group" && typeof v === "object" && !Array.isArray(v)) out[def.name] = sanitizeFields(def.fields, v as FieldValues);
+    else if (def.type === "repeater" && Array.isArray(v)) out[def.name] = v.map((it) => (it && typeof it === "object" ? sanitizeFields(def.fields, it as FieldValues) : it));
   }
   return out;
 }
@@ -613,7 +639,7 @@ export interface RenderedBlock {
   block_id: string;
   block_type: string;
   title: string | null;
-  fields: Record<string, unknown>;
+  fields: FieldValues;
   is_shared: boolean;
 }
 
@@ -646,7 +672,7 @@ export interface AssembledPage {
     translationGroupId: string | null;
     /** Published sibling locales of this page (for hreflang alternates). */
     translations: PageTranslation[];
-    fields: Record<string, unknown> | null;
+    fields: FieldValues | null;
     /** Back-compat: mirrors seo.metaTitle/metaDescription. */
     metaTitle: string | null;
     metaDescription: string | null;
@@ -657,6 +683,16 @@ export interface AssembledPage {
 
 // --- media -------------------------------------------------------------------
 
+/** One authored field value inside a block / collection / page `fields` bag. Stored
+ * as JSON; a `"media"` field is resolved from its stored id to a `ResolvedMedia` at
+ * assemble time, and `group`/`repeater` fields nest further bags. */
+export type FieldValue = JsonValue | ResolvedMedia | FieldValues | FieldValue[];
+
+/** A block / collection / page `fields` bag — field name -> authored value. */
+export interface FieldValues {
+  [field: string]: FieldValue;
+}
+
 /** A `"media"` block field, resolved from a stored media id to a servable shape at
  * assemble time. `url` is the raw (full-size) serving path; pass `key` to `imageUrl()`
  * for on-the-fly transforms. `null` when the referenced media was deleted. */
@@ -695,7 +731,7 @@ export function imageUrl(
 }
 
 /** Collect the media ids referenced by a fields payload, walking group/repeater nesting. */
-function collectMediaIds(fields: Record<string, unknown>, schema: FieldDefinition[] | undefined, acc: Set<string>): void {
+function collectMediaIds(fields: FieldValues, schema: FieldDefinition[] | undefined, acc: Set<string>): void {
   if (!Array.isArray(schema)) return;
   for (const def of schema) {
     const v = fields[def.name];
@@ -713,12 +749,12 @@ function collectMediaIds(fields: Record<string, unknown>, schema: FieldDefinitio
 /** Return a copy of `fields` with every `"media"` field resolved from its id to a
  * `ResolvedMedia` (or null), recursing into group/repeater nesting. */
 function resolveMediaFields(
-  fields: Record<string, unknown>,
+  fields: FieldValues,
   schema: FieldDefinition[] | undefined,
   mediaById: Map<string, ResolvedMedia>,
-): Record<string, unknown> {
+): FieldValues {
   if (!Array.isArray(schema)) return fields;
-  const out: Record<string, unknown> = { ...fields };
+  const out: FieldValues = { ...fields };
   for (const def of schema) {
     const v = out[def.name];
     if (v == null) continue;
@@ -757,7 +793,7 @@ interface CmsDb {
 const cdb = (ctx: HandlerContext): CmsDb => ctx.db as unknown as CmsDb;
 
 const notFound = (what: string) => new PramenError(`${what} not found`, 404, "not_found");
-const asObj = (v: unknown): Record<string, unknown> => (v && typeof v === "object" ? (v as Record<string, unknown>) : {});
+const asObj = (v: unknown): FieldValues => (v && typeof v === "object" ? (v as FieldValues) : {});
 // Timestamps in the SAME shape as the `expr.now()` column default (`datetime('now')`:
 // "YYYY-MM-DD HH:MM:SS", UTC, second precision) so a column's insert-default and its
 // handler-written updates stay lexically comparable (an ISO `T`/`Z` string sorts wrong).
@@ -791,7 +827,9 @@ async function assembleLive(db: CmsDb, page: Record<string, unknown>): Promise<A
   // fields (id → ResolvedMedia) in one batched lookup across the whole page.
   const merged = placements.map((p) => {
     const block = asObj(p.block);
-    const fields = { ...asObj(block.fields), ...(p.isShared ? asObj(p.overrides) : {}) };
+    const fields = p.isShared
+      ? { ...asObj(block.fields), ...asObj(p.overrides) }
+      : { ...asObj(block.fields) };
     return { p, block, fields, schema: typeById.get(String(block.typeId))?.fieldsSchema };
   });
   const mediaIds = new Set<string>();
@@ -883,7 +921,7 @@ function pageMeta(page: Record<string, unknown>, translations: PageTranslation[]
     contentType,
     translationGroupId: (page.translationGroupId as string | null) ?? null,
     translations,
-    fields: (page.fields as Record<string, unknown> | null) ?? null,
+    fields: (page.fields as FieldValues | null) ?? null,
     metaTitle,
     metaDescription,
     seo: {
@@ -1212,7 +1250,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
      * page record itself, which was previously only settable at createPage. A slug/locale
      * change re-checks (slug, locale) uniqueness (excluding this page); `fields` is validated
      * + sanitized against the content type's fieldsSchema, exactly like createPage. */
-    updatePage: mutation(async (ctx, input: { pageId: string; title?: string; slug?: string; locale?: string; fields?: Record<string, unknown> }) => {
+    updatePage: mutation(async (ctx, input: { pageId: string; title?: string; slug?: string; locale?: string; fields?: FieldValues }) => {
       const db = cdb(ctx);
       const rows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
       const page = rows[0];
@@ -1237,7 +1275,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return { ok: true, page: updated };
     }, {
       ...editor,
-      input: (raw): { pageId: string; title?: string; slug?: string; locale?: string; fields?: Record<string, unknown> } => {
+      input: (raw): { pageId: string; title?: string; slug?: string; locale?: string; fields?: FieldValues } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string") throw new BadRequest("pageId is required");
         for (const k of ["title", "slug", "locale"] as const) {
@@ -1248,7 +1286,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     }),
 
     /** Create a page and auto-scaffold its content type's default blocks. */
-    createPage: mutation(async (ctx, input: { typeId: string; title: string; slug: string; locale?: string; fields?: Record<string, unknown> }) => {
+    createPage: mutation(async (ctx, input: { typeId: string; title: string; slug: string; locale?: string; fields?: FieldValues }) => {
       const db = cdb(ctx);
       const ctRows = await db.find({ from: "cms_content_types", where: { id: input.typeId }, limit: 1 });
       const ct = ctRows[0];
@@ -1289,7 +1327,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return page;
     }, {
       ...editor,
-      input: (raw): { typeId: string; title: string; slug: string; locale?: string; fields?: Record<string, unknown> } => {
+      input: (raw): { typeId: string; title: string; slug: string; locale?: string; fields?: FieldValues } => {
         const o = asObj(raw);
         if (typeof o.typeId !== "string" || typeof o.title !== "string" || typeof o.slug !== "string") {
           throw new BadRequest("typeId, title and slug are required");
@@ -1368,7 +1406,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region
      * against the content type's allow-list. */
-    addBlock: mutation(async (ctx, input: { pageId: string; blockTypeSlug: string; region: string; fields?: Record<string, unknown>; title?: string; position?: number; isReusable?: boolean }) => {
+    addBlock: mutation(async (ctx, input: { pageId: string; blockTypeSlug: string; region: string; fields?: FieldValues; title?: string; position?: number; isReusable?: boolean }) => {
       const db = cdb(ctx);
       const pages = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
       const page = pages[0];
@@ -1395,7 +1433,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return { block, placement };
     }, {
       ...editor,
-      input: (raw): { pageId: string; blockTypeSlug: string; region: string; fields?: Record<string, unknown>; title?: string; position?: number; isReusable?: boolean } => {
+      input: (raw): { pageId: string; blockTypeSlug: string; region: string; fields?: FieldValues; title?: string; position?: number; isReusable?: boolean } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string" || typeof o.blockTypeSlug !== "string" || typeof o.region !== "string") {
           throw new BadRequest("pageId, blockTypeSlug and region are required");
@@ -1410,7 +1448,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
      * can be placed on several pages; editing it updates them all, while `overrides` let one
      * placement diverge. The merged (base + overrides) result is validated against the
      * block type's field schema. */
-    placeBlock: mutation(async (ctx, input: { pageId: string; blockId: string; region: string; position?: number; overrides?: Record<string, unknown> }) => {
+    placeBlock: mutation(async (ctx, input: { pageId: string; blockId: string; region: string; position?: number; overrides?: FieldValues }) => {
       const db = cdb(ctx);
       const pages = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
       const page = pages[0];
@@ -1437,7 +1475,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       });
     }, {
       ...editor,
-      input: (raw): { pageId: string; blockId: string; region: string; position?: number; overrides?: Record<string, unknown> } => {
+      input: (raw): { pageId: string; blockId: string; region: string; position?: number; overrides?: FieldValues } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string" || typeof o.blockId !== "string" || typeof o.region !== "string") {
           throw new BadRequest("pageId, blockId and region are required");
@@ -1460,7 +1498,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     }),
 
     /** Update a block's content (re-validated against its type's field schema). */
-    updateBlock: mutation(async (ctx, input: { blockId: string; fields?: Record<string, unknown>; title?: string }) => {
+    updateBlock: mutation(async (ctx, input: { blockId: string; fields?: FieldValues; title?: string }) => {
       const db = cdb(ctx);
       const rows = await db.find({ from: "cms_blocks", where: { id: input.blockId }, limit: 1 });
       const block = rows[0];
@@ -1477,7 +1515,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return db.update("cms_blocks", input.blockId, patch);
     }, {
       ...editor,
-      input: (raw): { blockId: string; fields?: Record<string, unknown>; title?: string } => {
+      input: (raw): { blockId: string; fields?: FieldValues; title?: string } => {
         const o = asObj(raw);
         if (typeof o.blockId !== "string") throw new BadRequest("blockId is required");
         return o as never;
@@ -2064,12 +2102,12 @@ export function robotsTxt(opts: { origin: string; disallow?: string[] }): string
 
 // Minimal shape of a pramen public route (see @pramen/server/worker app.routes).
 interface RouteCtx {
-  callPrivileged: (opts: { name: string; input?: unknown; tenant?: string; roles?: string[] }) => Promise<Response>;
+  callPrivileged: (opts: { name: string; input?: JsonValue; tenant?: string; roles?: string[] }) => Promise<Response>;
 }
 interface CmsRoute {
   method: string;
   path: string;
-  handler: (request: Request, env: Readonly<Record<string, unknown>>, ctx: RouteCtx) => Promise<Response>;
+  handler: (request: Request, env: EnvBag, ctx: RouteCtx) => Promise<Response>;
 }
 
 /** Turnkey public routes for `GET /sitemap.xml` and `GET /robots.txt`. Spread into