@cosmicdrift/kumiko-samples 0.394.0 → 0.396.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.394.0",
+  "version": "0.396.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.394.0",
+  "version": "0.396.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/inbound-provider-imap/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.395.0",
+    "type": "fix",
+    "title": "A mail the IMAP watch quarantines keeps its sender and subject",
+    "detail": "The live watch fetched new mails without the IMAP envelope, so an unparseable mail it quarantined showed no sender and no subject in the quarantine list. The watch now fetches the envelope like the poll does."
+  },
   {
     "version": "0.394.0",
     "type": "improvement",

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -32,15 +32,13 @@ import {
   type InboundMailProviderPlugin,
   type InboundMailRoleOptions,
   type MailAccountRecord,
-  type RawInboundMessage,
-  type RejectedInboundMessage,
   resolveInboundMailRoles,
   roleDedupeOptions,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { instantToLegacyDate } from "@cosmicdrift/kumiko-framework/time";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import type { ImapFlow, MailboxObject } from "imapflow";
+import type { MailboxObject } from "imapflow";
 import { createConnectMailboxHandler } from "./connect-mailbox.ts";
 import { createConnectMyMailboxHandler } from "./connect-my-mailbox.ts";
 import { FEATURE_NAME, IMAP_PROVIDER_KEY } from "./constants.ts";
@@ -58,11 +56,12 @@ import {
   mapImapError,
   parseImapCursor,
 } from "./imap-client.ts";
-import { buildProviderMessageId, coerceDate, parseOrReject } from "./parse-message.ts";
+import { buildProviderMessageId } from "./parse-message.ts";
 import { createReconnectMailboxHandler } from "./reconnect-mailbox.ts";
 import { createReconnectPrefillQuery } from "./reconnect-prefill.query.ts";
 import { createImapScreens } from "./screens.ts";
 import { sendFromImapAccount } from "./send-mail.ts";
+import { watchMailbox } from "./watch-mailbox.ts";
 
 export { IMAP_PROVIDER_KEY } from "./constants.ts";
 
@@ -151,106 +150,6 @@ async function fetchMessages(
   }
 }
 
-// =============================================================================
-// watch — IMAP IDLE (imapflow idles automatically while the mailbox is open
-// and emits 'exists' for new messages).
-// =============================================================================
-
-async function watchMailbox(
-  ctx: InboundMailContext,
-  account: MailAccountRecord,
-  handlers: {
-    readonly onMessages: (
-      msgs: readonly RawInboundMessage[],
-      rejected?: readonly RejectedInboundMessage[],
-    ) => Promise<void>;
-    readonly onError: (err: unknown) => void;
-  },
-): Promise<() => Promise<void>> {
-  const doc = await readCredentialDocument(ctx, account);
-  const client: ImapFlow = await createImapClient(doc, imapMailHostGuard());
-  let stopped = false;
-
-  try {
-    await client.connect();
-    const mailbox = (await client.mailboxOpen(IMAP_MAILBOX)) as MailboxObject;
-    const uidValidity = String(mailbox.uidValidity);
-    // uidNext is the next UID to be assigned, so everything from here is
-    // "new".
-    let nextUid = Number(mailbox.uidNext ?? 1);
-
-    const drainNew = async () => {
-      const messages: RawInboundMessage[] = [];
-      const rejected: RejectedInboundMessage[] = [];
-      let maxSeen = nextUid - 1;
-      for await (const msg of client.fetch(
-        `${nextUid}:*`,
-        { uid: true, internalDate: true, source: true },
-        { uid: true },
-      )) {
-        // `N:*` gotcha (see fetch): filter out the previous last message.
-        if (msg.uid < nextUid || !msg.source) continue;
-        const parsed = await parseOrReject({
-          source: msg.source,
-          uid: msg.uid,
-          uidValidity,
-          internalDate: coerceDate(msg.internalDate ?? undefined),
-          trustedAuthservId: account.trustedAuthservId ?? null,
-        });
-        if ("message" in parsed) messages.push(parsed.message);
-        else rejected.push(parsed.rejected);
-        if (msg.uid > maxSeen) maxSeen = msg.uid;
-      }
-      nextUid = maxSeen + 1;
-      if (messages.length > 0 || rejected.length > 0) await handlers.onMessages(messages, rejected);
-    };
-
-    client.on("exists", () => {
-      // skip: ignore delayed exists events after the watcher has stopped.
-      if (stopped) return;
-      void drainNew().catch((err) => {
-        if (!stopped) handlers.onError(mapImapError(err, doc.host));
-      });
-    });
-    const die = (err: unknown) => {
-      // skip: already stopped or terminated; fire onError only once.
-      if (stopped) return;
-      stopped = true;
-      handlers.onError(mapImapError(err, doc.host));
-    };
-    client.on("error", die);
-    client.on("close", () => die(new Error("connection closed")));
-
-    // IDLE loop: 'exists' fires ONLY while client.idle() is running
-    // (verified empirically against greenmail). Each intervening command
-    // (drainNew-fetch) ends idle(), so the loop re-enters idle() until
-    // stop() closes the connection.
-    void (async () => {
-      while (!stopped) {
-        try {
-          await client.idle();
-        } catch (err) {
-          if (!stopped) die(err);
-          // skip: the idle loop ends; die() has informed the supervisor (or stop()
-          // was the cause).
-          return;
-        }
-      }
-    })();
-
-    return async () => {
-      stopped = true;
-      client.removeAllListeners("exists");
-      client.removeAllListeners("error");
-      client.removeAllListeners("close");
-      await client.logout().catch(() => {});
-    };
-  } catch (err) {
-    await client.logout().catch(() => {});
-    throw mapImapError(err, doc.host);
-  }
-}
-
 // =============================================================================
 // Plugin + Feature-definition
 // =============================================================================

package/packages/bundled-features/src/inbound-provider-imap/watch-mailbox.ts

@@ -0,0 +1,109 @@
+import type {
+  InboundMailContext,
+  MailAccountRecord,
+  RawInboundMessage,
+  RejectedInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { ImapFlow } from "imapflow";
+import { readCredentialDocument } from "./credential-document.ts";
+import { createImapClient, IMAP_MAILBOX, imapMailHostGuard, mapImapError } from "./imap-client.ts";
+import { coerceDate, parseOrReject } from "./parse-message.ts";
+
+// IMAP IDLE (imapflow idles automatically while the mailbox is open
+// and emits 'exists' for new messages).
+
+export async function watchMailbox(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  handlers: {
+    readonly onMessages: (
+      msgs: readonly RawInboundMessage[],
+      rejected?: readonly RejectedInboundMessage[],
+    ) => Promise<void>;
+    readonly onError: (err: unknown) => void;
+  },
+): Promise<() => Promise<void>> {
+  const doc = await readCredentialDocument(ctx, account);
+  const client: ImapFlow = await createImapClient(doc, imapMailHostGuard());
+  let stopped = false;
+
+  try {
+    await client.connect();
+    const mailbox = await client.mailboxOpen(IMAP_MAILBOX);
+    const uidValidity = String(mailbox.uidValidity);
+    // uidNext is the next UID to be assigned, so everything from here is
+    // "new".
+    let nextUid = Number(mailbox.uidNext ?? 1);
+
+    const drainNew = async () => {
+      const messages: RawInboundMessage[] = [];
+      const rejected: RejectedInboundMessage[] = [];
+      let maxSeen = nextUid - 1;
+      for await (const msg of client.fetch(
+        `${nextUid}:*`,
+        { uid: true, internalDate: true, source: true, envelope: true },
+        { uid: true },
+      )) {
+        // `N:*` gotcha (see fetch): filter out the previous last message.
+        if (msg.uid < nextUid || !msg.source) continue;
+        const parsed = await parseOrReject({
+          source: msg.source,
+          envelope: msg.envelope,
+          uid: msg.uid,
+          uidValidity,
+          internalDate: coerceDate(msg.internalDate ?? undefined),
+          trustedAuthservId: account.trustedAuthservId ?? null,
+        });
+        if ("message" in parsed) messages.push(parsed.message);
+        else rejected.push(parsed.rejected);
+        if (msg.uid > maxSeen) maxSeen = msg.uid;
+      }
+      nextUid = maxSeen + 1;
+      if (messages.length > 0 || rejected.length > 0) await handlers.onMessages(messages, rejected);
+    };
+
+    client.on("exists", () => {
+      // skip: ignore delayed exists events after the watcher has stopped.
+      if (stopped) return;
+      void drainNew().catch((err) => {
+        if (!stopped) handlers.onError(mapImapError(err, doc.host));
+      });
+    });
+    const die = (err: unknown) => {
+      // skip: already stopped or terminated; fire onError only once.
+      if (stopped) return;
+      stopped = true;
+      handlers.onError(mapImapError(err, doc.host));
+    };
+    client.on("error", die);
+    client.on("close", () => die(new Error("connection closed")));
+
+    // IDLE loop: 'exists' fires ONLY while client.idle() is running
+    // (verified empirically against greenmail). Each intervening command
+    // (drainNew-fetch) ends idle(), so the loop re-enters idle() until
+    // stop() closes the connection.
+    void (async () => {
+      while (!stopped) {
+        try {
+          await client.idle();
+        } catch (err) {
+          if (!stopped) die(err);
+          // skip: the idle loop ends; die() has informed the supervisor (or stop()
+          // was the cause).
+          return;
+        }
+      }
+    })();
+
+    return async () => {
+      stopped = true;
+      client.removeAllListeners("exists");
+      client.removeAllListeners("error");
+      client.removeAllListeners("close");
+      await client.logout().catch(() => {});
+    };
+  } catch (err) {
+    await client.logout().catch(() => {});
+    throw mapImapError(err, doc.host);
+  }
+}

package/packages/bundled-features/src/managed-pages/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.395.0",
+    "type": "breaking",
+    "title": "A managed page body is Markdown or an editor document, edited in the document editor",
+    "detail": "The page entity has a new field bodyFormat (\"markdown\" or \"document\", default markdown). Pages and events from before the field read as markdown and render unchanged. A document body is HTML from the template-resolver document editor; page create, update and managed-pages:write:set check it with sanitizeDocumentHtml and store the rebuilt HTML and answer a rejected body with field errors on body (i18n key managed-pages.errors.document.rejected, new in all locale packages). The public render sanitizes a document body again and serves an empty body, with a logged warning, when a stored one fails. managed-pages:write:set takes an optional bodyFormat; omitting it sets markdown, it does not preserve the stored format. The page-edit screen no longer has a body textarea: its body section is the extension section managed-pages:page-body (PAGE_BODY_EXTENSION_NAME), which opens a Markdown body converted to HTML, shows a warning for what the conversion drops (images, block quotes, code, headings below level 3, relative links) and writes body and bodyFormat \"document\" only after the first edit. The ETag of the public page includes bodyFormat. seedPage takes an optional bodyFormat and throws on a rejected document body.",
+    "migration": "Run `kumiko-schema generate` and apply the migration; read_pages gets a bodyFormat column with default 'markdown', no rebuild is needed. Mount `managedPagesClient()` from `@cosmicdrift/kumiko-bundled-features/managed-pages/web` in createKumikoApp({ clientFeatures }); without it the body section of page-edit shows the missing-component placeholder. Apps that replaced page-edit with their own screen keep the textarea and send no bodyFormat, so their pages stay markdown."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

package/packages/bundled-features/src/managed-pages/constants.ts

@@ -1 +1,8 @@
 export const MANAGED_PAGES_FEATURE = "managed-pages" as const;
+
+export {
+  BODY_FORMATS,
+  type BodyFormat,
+  DEFAULT_BODY_FORMAT,
+  effectiveBodyFormat,
+} from "./web/constants.ts";

package/packages/bundled-features/src/managed-pages/feature.ts

@@ -5,17 +5,17 @@ import {
   type BrandingTokens,
   cachedSecurePageResponse,
   EMPTY_BRANDING,
-  renderSafeMarkdown,
   wrapInLayout,
 } from "../page-render/index.ts";
 import { rateLimitedTextResponse, type SystemQueryFn } from "../shared/index.ts";
 import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from "./branding.ts";
-import { MANAGED_PAGES_FEATURE } from "./constants.ts";
+import { type BodyFormat, MANAGED_PAGES_FEATURE } from "./constants.ts";
 import { createBrandingQuery } from "./handlers/branding.query.ts";
 import { bySlugQuery } from "./handlers/by-slug.query.ts";
 import { byTenantPublishedQuery } from "./handlers/by-tenant-published.query.ts";
 import { pageCrudQueries, pageCrudWrites } from "./handlers/page-crud.ts";
 import { setWrite } from "./handlers/set.write.ts";
+import { renderPageBody } from "./render-page-body.ts";
 import { createBrandingSettingsScreen } from "./screens/branding-screen.ts";
 import { pageEditScreen, pageListScreen } from "./screens/page-screens.ts";
 import { pageEntity } from "./table.ts";
@@ -34,6 +34,7 @@ const BY_SLUG_QN = "managed-pages:query:by-slug";
 type BySlugQueryResult = {
   title: string;
   body: string;
+  bodyFormat: BodyFormat;
   lang: string;
   description: string | null;
   ogImage: string | null;
@@ -157,7 +158,7 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
   return defineFeature(MANAGED_PAGES_FEATURE, (r) => {
     r.adoptsBundledLists();
     r.describe(
-      "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
+      "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one `page` (Markdown or editor-document HTML body, per `bodyFormat`) per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core and document bodies through the template-resolver document sanitizer, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
     );
     r.uiHints({
       displayLabel: "Managed Pages · Public CMS",
@@ -241,6 +242,7 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
           slug,
           lang,
           String(data.version),
+          data.bodyFormat,
           data.updatedAt,
           brandingRevisionSeed(branding),
         ]);
@@ -261,7 +263,7 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
 
         const html = wrapLayout({
           title: data.title,
-          bodyHtml: renderSafeMarkdown(data.body),
+          bodyHtml: renderPageBody({ slug, body: data.body, bodyFormat: data.bodyFormat }),
           lang: data.lang,
           slug,
           description: data.description,

package/packages/bundled-features/src/managed-pages/handlers/by-slug.query.ts

@@ -1,6 +1,7 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { effectiveBodyFormat } from "../constants.ts";
 import { type PageRow, pagesTable } from "../table.ts";
 
 // Public read by (tenantId, slug, lang), including anonymous access for landing and
@@ -30,6 +31,7 @@ export const bySlugQuery = defineQueryHandler({
       lang: row.lang,
       title: row.title,
       body: row.body,
+      bodyFormat: effectiveBodyFormat(row.bodyFormat),
       description: row.description,
       ogImage: row.ogImage,
       version: row.version,

package/packages/bundled-features/src/managed-pages/handlers/page-body-guard.ts

@@ -0,0 +1,61 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type FieldIssue,
+  ValidationError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { type PageRow, pagesTable } from "../table.ts";
+import { sanitizePageBody } from "./page-body-issues.ts";
+
+type PageWriteHandler = WriteHandlerDef["handler"];
+type PageWriteContext = Parameters<PageWriteHandler>[1];
+
+type Guarded =
+  | { readonly ok: true; readonly payload: unknown }
+  | { readonly ok: false; readonly issues: FieldIssue[] };
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+// preSave hooks cannot report field errors (the executor maps every throw to
+// presave_hook_failed), so the convention handlers are checked before they run.
+// An update may touch only body or only bodyFormat, so the pair is completed
+// from the stored row. A document body is handed on as the rebuilt html.
+async function guardUpdate(payload: unknown, ctx: PageWriteContext): Promise<Guarded> {
+  if (!isPlainObject(payload) || !isPlainObject(payload["changes"])) return { ok: true, payload };
+  const changes = payload["changes"];
+  if (!("body" in changes) && !("bodyFormat" in changes)) return { ok: true, payload };
+  const id = payload["id"];
+  const stored =
+    typeof id === "string" ? await fetchOne<PageRow>(ctx.db, pagesTable, { id }) : null;
+  const body = "body" in changes ? stringOrNull(changes["body"]) : (stored?.body ?? null);
+  const format = "bodyFormat" in changes ? changes["bodyFormat"] : stored?.bodyFormat;
+  const result = sanitizePageBody(body, format);
+  if (!result.ok) return result;
+  return { ok: true, payload: { ...payload, changes: { ...changes, body: result.body } } };
+}
+
+function guardCreate(payload: unknown): Guarded {
+  if (!isPlainObject(payload)) return { ok: true, payload };
+  const result = sanitizePageBody(stringOrNull(payload["body"]), payload["bodyFormat"]);
+  if (!result.ok) return result;
+  return { ok: true, payload: { ...payload, body: result.body } };
+}
+
+export function withBodyValidation(
+  def: WriteHandlerDef,
+  verb: "create" | "update",
+): WriteHandlerDef {
+  return {
+    ...def,
+    handler: async (event, ctx) => {
+      const guarded =
+        verb === "create" ? guardCreate(event.payload) : await guardUpdate(event.payload, ctx);
+      if (!guarded.ok) return writeFailure(new ValidationError({ fields: guarded.issues }));
+      return def.handler({ ...event, payload: guarded.payload }, ctx);
+    },
+  };
+}

package/packages/bundled-features/src/managed-pages/handlers/page-body-issues.ts

@@ -0,0 +1,26 @@
+import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import { sanitizeDocumentHtml } from "../../template-resolver/index.ts";
+import { effectiveBodyFormat } from "../constants.ts";
+
+export const BODY_REJECTED_I18N_KEY = "managed-pages.errors.document.rejected";
+
+export type PageBodyResult =
+  | { readonly ok: true; readonly body: string | null }
+  | { readonly ok: false; readonly issues: FieldIssue[] };
+
+// The single write-time gate for document bodies (create, update, set, seed): a
+// document body is stored as the sanitizer's rebuilt html, never as the raw input.
+export function sanitizePageBody(body: string | null | undefined, format: unknown): PageBodyResult {
+  if (effectiveBodyFormat(format) !== "document" || !body) return { ok: true, body: body ?? null };
+  const result = sanitizeDocumentHtml(body);
+  if (result.ok) return { ok: true, body: result.html };
+  return {
+    ok: false,
+    issues: result.violations.map((violation) => ({
+      path: "body",
+      code: violation.code,
+      i18nKey: BODY_REJECTED_I18N_KEY,
+      params: { detail: violation.detail },
+    })),
+  };
+}

package/packages/bundled-features/src/managed-pages/handlers/page-crud.ts

@@ -6,6 +6,7 @@ import {
   defineEntityUpdateHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { pageEntity } from "../table.ts";
+import { withBodyValidation } from "./page-body-guard.ts";
 
 // Admin authoring runs as TenantAdmin (self-service) or SystemAdmin (app-wide
 // pages). Mirrors set.write's ACL — an app with its own role alias
@@ -17,16 +18,22 @@ const ADMIN_ACCESS = { roles: ["TenantAdmin", "SystemAdmin"] } as const;
 // `managed-pages:query:page:{list,detail}` by convention. The `set` write
 // handler in feature.ts is NOT used by them and stays the provisioning API.
 export const pageCrudWrites = [
-  defineEntityCreateHandler("page", pageEntity, {
-    access: ADMIN_ACCESS,
-    description:
-      "Creates a managed page from the admin form's field values, failing if that slug and language already exist; use it from the page catalog screen, whereas managed-pages:write:set upserts a page addressed by slug and language.",
-  }),
-  defineEntityUpdateHandler("page", pageEntity, {
-    access: ADMIN_ACCESS,
-    description:
-      "Updates one managed page addressed by row id from the admin form's `{ id, version, changes }` envelope; use it from the page edit screen, whereas managed-pages:write:set addresses a page by slug and language instead.",
-  }),
+  withBodyValidation(
+    defineEntityCreateHandler("page", pageEntity, {
+      access: ADMIN_ACCESS,
+      description:
+        "Creates a managed page from the admin form's field values, failing if that slug and language already exist; use it from the page catalog screen, whereas managed-pages:write:set upserts a page addressed by slug and language.",
+    }),
+    "create",
+  ),
+  withBodyValidation(
+    defineEntityUpdateHandler("page", pageEntity, {
+      access: ADMIN_ACCESS,
+      description:
+        "Updates one managed page addressed by row id from the admin form's `{ id, version, changes }` envelope; use it from the page edit screen, whereas managed-pages:write:set addresses a page by slug and language instead.",
+    }),
+    "update",
+  ),
   defineEntityDeleteHandler("page", pageEntity, {
     access: ADMIN_ACCESS,
     description:

package/packages/bundled-features/src/managed-pages/handlers/set.write.ts

@@ -1,8 +1,11 @@
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.ts";
+import { BODY_FORMATS, DEFAULT_BODY_FORMAT } from "../constants.ts";
 import { type PageRow, pageEntity, pagesTable } from "../table.ts";
+import { sanitizePageBody } from "./page-body-issues.ts";
 
 const slugSchema = z
   .string()
@@ -21,7 +24,8 @@ const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName:
 // Upserts one page per (tenantId, slug, lang). The tenant scope defaults to event.user;
 // SystemAdmin can write to another tenant via `tenantIdOverride` (typically SYSTEM_TENANT_ID
 // for app-wide pages). On update, omitted published/description/ogImage values are preserved
-// so a publish toggle does not overwrite the body, and vice versa.
+// so a publish toggle does not overwrite the body, and vice versa. bodyFormat is the
+// exception: omitted means markdown, so provisioning callers that only know markdown stay valid.
 export const setWrite = defineWriteHandler({
   name: "set",
   schema: z.object({
@@ -29,6 +33,7 @@ export const setWrite = defineWriteHandler({
     lang: langSchema,
     title: z.string().min(1).max(200),
     body: z.string().max(100_000).nullable(),
+    bodyFormat: z.enum(BODY_FORMATS).optional(),
     description: z.string().max(500).nullable().optional(),
     ogImage: z.string().max(2000).nullable().optional(),
     published: z.boolean().optional(),
@@ -37,10 +42,14 @@ export const setWrite = defineWriteHandler({
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
+    "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them and resetting bodyFormat to markdown (the default) when it is omitted; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
   handler: async (event, ctx) => {
     const override = event.payload.tenantIdOverride;
     const tenantId = (override ?? event.user.tenantId) as TenantId; // @cast-boundary engine-bridge
+    const bodyFormat = event.payload.bodyFormat ?? DEFAULT_BODY_FORMAT;
+    const sanitized = sanitizePageBody(event.payload.body, bodyFormat);
+    if (!sanitized.ok) return writeFailure(new ValidationError({ fields: sanitized.issues }));
+    const { body } = sanitized;
     // ctx.db is scoped to the executing user's tenant, wrong for a cross-tenant override
     // on both the existing-check and the executor's stream reads; re-scope to the target.
     const { db: scopedDb, streamTenantId } = requireForTenant(ctx, tenantId);
@@ -57,7 +66,8 @@ export const setWrite = defineWriteHandler({
           version: existing.version,
           changes: {
             title: event.payload.title,
-            body: event.payload.body,
+            body,
+            bodyFormat,
             description:
               event.payload.description !== undefined
                 ? event.payload.description
@@ -83,7 +93,8 @@ export const setWrite = defineWriteHandler({
         slug: event.payload.slug,
         lang: event.payload.lang,
         title: event.payload.title,
-        body: event.payload.body,
+        body,
+        bodyFormat,
         description: event.payload.description ?? null,
         ogImage: event.payload.ogImage ?? null,
         published: event.payload.published ?? false,

package/packages/bundled-features/src/managed-pages/render-page-body.ts

@@ -0,0 +1,28 @@
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { renderSafeMarkdown } from "../page-render/index.ts";
+import { sanitizeDocumentHtml } from "../template-resolver/index.ts";
+import type { BodyFormat } from "./constants.ts";
+
+type WarnLogger = Pick<Logger, "warn">;
+
+const defaultLog = createFallbackLogger("managed-pages");
+
+export type RenderablePageBody = {
+  readonly slug: string;
+  readonly body: string;
+  readonly bodyFormat: BodyFormat;
+};
+
+// A document body is re-sanitized at render time even though writes validate it:
+// rows can predate the validation or arrive through other writers. A rejected
+// document renders as an empty body (never the raw HTML) and is logged.
+export function renderPageBody(page: RenderablePageBody, log: WarnLogger = defaultLog): string {
+  if (page.bodyFormat === "markdown") return renderSafeMarkdown(page.body);
+  const result = sanitizeDocumentHtml(page.body);
+  if (result.ok) return result.html;
+  log.warn("managed page document body rejected at render, serving an empty body", {
+    slug: page.slug,
+    violations: result.violations.map((violation) => violation.code),
+  });
+  return "";
+}

package/packages/bundled-features/src/managed-pages/screens/page-screens.ts

@@ -2,6 +2,7 @@ import type {
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { PAGE_BODY_EXTENSION_NAME } from "../web/constants.ts";
 
 // Admin authoring screens for the `page` entity. These are JSON-safe data only —
 // the generic DataTable/form renderer mounts them, so no React component is
@@ -78,10 +79,13 @@ export const pageEditScreen: EntityEditScreenDefinition = {
           { field: "published", span: 1 },
         ],
       },
+      // Not a plain field: the body is edited as a document and a Markdown
+      // body is converted on open, so the section also patches `bodyFormat`.
       {
+        kind: "extension",
         title: "managed-pages:section.body",
-        columns: 1,
-        fields: [{ field: "body", span: 1 }],
+        component: { react: { __component: PAGE_BODY_EXTENSION_NAME } },
+        entityName: "page",
       },
     ],
   },