@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,267 @@
+import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type BrandingTokens,
+  cachedSecurePageResponse,
+  EMPTY_BRANDING,
+  renderSafeMarkdown,
+  wrapInLayout,
+} from "../page-render/index.js";
+import type { SystemQueryFn } from "../shared/index.js";
+import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from "./branding.js";
+import { createBrandingQuery } from "./handlers/branding.query.js";
+import { bySlugQuery } from "./handlers/by-slug.query.js";
+import { byTenantPublishedQuery } from "./handlers/by-tenant-published.query.js";
+import { pageCrudQueries, pageCrudWrites } from "./handlers/page-crud.js";
+import { setWrite } from "./handlers/set.write.js";
+import { MANAGED_PAGES_I18N } from "./i18n.js";
+import { createBrandingSettingsScreen } from "./screens/branding-screen.js";
+import { pageEditScreen, pageListScreen } from "./screens/page-screens.js";
+import { pageEntity } from "./table.js";
+
+// 60s-shared-cache saves the origin-revalidate roundtrip; CMS edits are live within 60s.
+const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
+
+// QN-Konstante als dokumentierter Public-Contract — der Render-Pfad ruft
+// die by-slug-Query via systemQuery in-process (kein Code-Import des
+// Handlers, symmetrisch zum legal-pages-Muster).
+const BY_SLUG_QN = "managed-pages:query:by-slug";
+
+// Raw Handler-Return von bySlugQuery (published-only) — systemQuery dispatcht
+// direkt gegen den Handler, keine `{data}`-Envelope wie am /api/query-Wire.
+type BySlugQueryResult = {
+  title: string;
+  body: string;
+  lang: string;
+  description: string | null;
+  ogImage: string | null;
+  version: number;
+  updatedAt: string;
+} | null;
+
+function brandingRevisionSeed(branding: BrandingTokens): string {
+  return JSON.stringify([
+    branding.title,
+    branding.description,
+    branding.siteUrl,
+    branding.accentColor,
+    branding.logoUrl,
+    branding.layoutPreset,
+    branding.customCss,
+  ]);
+}
+
+// Never throws: a query failure or malformed result degrades to the
+// unbranded default (branding is decoration, not a hard dependency of the
+// page render).
+async function readBrandingViaSystemQuery(
+  systemQuery: SystemQueryFn,
+  tenantId: string,
+): Promise<BrandingTokens> {
+  try {
+    return coerceBranding(await systemQuery(BRANDING_QUERY_QN, {}, tenantId));
+  } catch {
+    return EMPTY_BRANDING;
+  }
+}
+
+export type ManagedPagesWrapLayout = (opts: {
+  readonly title: string;
+  readonly bodyHtml: string;
+  readonly lang: string;
+  readonly slug: string;
+  readonly description: string | null;
+  readonly ogImage: string | null;
+  // Per-tenant branding tokens resolved at render time (accent color, logo,
+  // layout preset, …). A custom wrapLayout may apply them however it likes;
+  // the default skeleton emits scoped :root vars + a logo/title header.
+  readonly branding: BrandingTokens;
+}) => string;
+
+export type ManagedPagesOptions = {
+  /** Host → tenantId für anonyme per-Tenant-Auslieferung. NULL → 404 (kein
+   *  Tenant für diesen Host). Apex-/Marketing-Apps geben hier ihre Subdomain-
+   *  /Custom-Domain-Auflösung rein; single-tenant gibt konstant einen
+   *  tenantId (oder SYSTEM_TENANT_ID) zurück. Erforderlich, weil der Apex-
+   *  Host keinen ambient ctx.tenantId hat. */
+  readonly resolveApexTenant: (host: string) => Promise<string | null> | string | null;
+  /** Custom Layout-Wrapper (Branding/Chrome). Default: minimaler
+   *  page-render-Skeleton. Erhält slug + SEO-Meta zur freien Nutzung.
+   *  **`branding` ist RAW, untrusted tenant input.** `title`/`description`
+   *  sind am Write nur längen-gecappt, NICHT HTML-escaped; `customCss` ist
+   *  ungesanitet. Der Wrapper MUSS sie über die Boundary-Helper emittieren
+   *  (alle re-exported von `@cosmicdrift/kumiko-bundled-features/managed-pages`):
+   *  `brandingHeaderHtml(branding)` + `brandingStyleBlock(branding)` (escapen
+   *  Header/Theme) und — mit allowCustomCss — `tenantStyleBlock(branding.
+   *  customCss)` ins `<head>` plus `TENANT_CONTENT_ATTR` am Body-Container. Ein
+   *  Custom-Wrapper der `branding.title` selbst interpoliert ist stored XSS;
+   *  der Default-Wrapper nutzt durchweg die Helper. */
+  readonly wrapLayout?: ManagedPagesWrapLayout;
+  /** Basis-Pfad der Page-Routes. Default "/p" → GET /p/:slug. */
+  readonly basePath?: string;
+  /** Default-Sprache wenn `?lang=` fehlt. Default "en". */
+  readonly defaultLang?: string;
+  /** Aktiviert die per-Tenant Custom-CSS-Capability (raw, untrusted): ein
+   *  `branding-custom-css` Config-Key + ein CSS-Feld im Branding-Editor + die
+   *  Render-Emission als scoped, allowlist-sanitized `<style data-tenant-css>`.
+   *  Default **false** (fail-closed — opt-in für untrusted-Tenant-Input). Auch
+   *  wenn true, wird die Emission zusätzlich per-Tenant über das
+   *  `managed-pages-css`-Toggle (createManagedPagesCssFeature) gegated, sobald
+   *  ein feature-toggles/tier-engine-Runtime verdrahtet ist. Der Render-time-
+   *  Sanitizer (page-render/css-sanitize) ist der Safety-Boundary. */
+  readonly allowCustomCss?: boolean;
+};
+
+// managed-pages — vom Tenant editierbare, server-gerenderte Public-Pages.
+// Generalisiert das legal-pages-Render-Muster: eine dynamische Slug-Route
+// (`GET /p/:slug`), die den Tenant aus dem Host auflöst (resolveApexTenant),
+// die published Page lädt, Markdown gehärtet rendert (page-render) und über
+// einen optionalen wrapLayout in Chrome legt. Drafts → 404. Per-Tenant-
+// Content wird per `Vary: Host` cache-isoliert.
+//
+// Admin-Authoring: registriert entityList + entityEdit für `page` (TenantAdmin/
+// SystemAdmin) + die Convention-CRUD-Handler die der Renderer per Konvention
+// dispatcht. Die Screens MÜSSEN hier liegen (Boot-Validator verlangt entity-Ref
+// same-feature); Nav/Workspace bleibt App-Sache.
+//
+// Voraussetzungen am App-Bootstrap:
+//   • anonymousAccess so verdrahtet, dass der X-Tenant-Header honoriert wird
+//     — Multi-Tenant nutzt einen tenantResolver (oder keinen defaultTenantId).
+//     Ein fixer defaultTenantId lockt Single-Tenant und lehnt den per-Page
+//     gesetzten X-Tenant mit 400 tenant_mismatch ab.
+//   • Admin-UI: die App zeigt via `r.nav({ screen: "managed-pages:screen:
+//     page-list" })` + Workspace-Eintrag auf die hier deklarierten Screens
+//     (cross-feature Nav→Screen ist global-validiert) und grantet ihren Admins
+//     TenantAdmin. Ohne Nav bleiben die Screens dormant — kein Leak in
+//     flat-nav-Apps die managed-pages nur zum Public-Render nutzen.
+export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDefinition {
+  const wrapLayout: ManagedPagesWrapLayout =
+    opts.wrapLayout ??
+    ((o) =>
+      wrapInLayout({
+        title: o.title,
+        bodyHtml: o.bodyHtml,
+        lang: o.lang,
+        description: o.description,
+        branding: o.branding,
+      }));
+  const basePath = opts.basePath ?? "/p";
+  const defaultLang = opts.defaultLang ?? "en";
+  const allowCustomCss = opts.allowCustomCss ?? false;
+
+  return defineFeature("managed-pages", (r) => {
+    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.",
+    );
+    r.uiHints({
+      displayLabel: "Managed Pages · Public CMS",
+      category: "content",
+      recommended: false,
+    });
+    r.requires("config");
+    r.entity("page", pageEntity);
+
+    // Per-tenant branding config keys (scope: tenant). Write-validated via
+    // keyDef.pattern (hex / https) — see branding.ts. read:all so the
+    // anonymous render path may resolve them. The raw-CSS key is added only
+    // when allowCustomCss (fail-closed: no key/editor when the capability off).
+    r.config({ keys: allowCustomCss ? { ...BRANDING_KEYS, ...CUSTOM_CSS_KEY } : BRANDING_KEYS });
+
+    const handlers = { set: r.writeHandler(setWrite) };
+    const queries = {
+      bySlug: r.queryHandler(bySlugQuery),
+      byTenantPublished: r.queryHandler(byTenantPublishedQuery),
+      branding: r.queryHandler(createBrandingQuery({ allowCustomCss })),
+    };
+
+    for (const def of pageCrudWrites) r.writeHandler(def);
+    for (const def of pageCrudQueries) r.queryHandler(def);
+
+    r.screen(pageListScreen);
+    r.screen(pageEditScreen);
+    r.screen(createBrandingSettingsScreen({ allowCustomCss }));
+
+    r.translations({ keys: MANAGED_PAGES_I18N });
+
+    r.httpRoute({
+      method: "GET",
+      path: `${basePath}/:slug`,
+      anonymous: true,
+      handler: async (c, { systemQuery }) => {
+        // `param("slug")` ist string|undefined, weil `path` ein computed
+        // Template ist (Hono inferiert `:slug` nur aus String-Literalen).
+        const slug = c.req.param("slug");
+        if (!slug) return c.text("not found", 404);
+        const lang = c.req.query("lang") || defaultLang;
+        const url = new URL(c.req.url);
+        // Host-Header zuerst (prod hinter Proxy), URL-Host als Fallback.
+        const host = c.req.header("host") ?? url.host;
+
+        const tenantId = await opts.resolveApexTenant(host);
+        if (!tenantId) return c.text("not found", 404);
+
+        // Page + branding read in parallel, beide über systemQuery in-
+        // process gegen den host-resolved tenantId erzwungen (kein X-Tenant-
+        // Header-Trick über app.fetch — der sähe für einen host-basierten
+        // anonymousAccess-Resolver wie ein Client-Override aus und würde
+        // von resolverTrust: "authoritative" zurecht abgelehnt; siehe
+        // systemQuery's Doc in http-route.ts). Branding ist Deko → ein
+        // Fehlschlag degradiert zum unbranded Default, blockt nie die Page.
+        const [pageSettled, brandingResult] = await Promise.all([
+          systemQuery(BY_SLUG_QN, { slug, lang }, tenantId)
+            .then((data) => ({ ok: true as const, data: data as BySlugQueryResult }))
+            .catch(() => ({ ok: false as const, data: null as BySlugQueryResult })),
+          readBrandingViaSystemQuery(systemQuery, tenantId),
+        ]);
+        if (!pageSettled.ok) return c.text("page unavailable", 503);
+
+        const data = pageSettled.data;
+        if (!data) return c.text("not found", 404);
+
+        const branding = brandingResult;
+
+        const etag = computeRevisionEtag([
+          tenantId,
+          slug,
+          lang,
+          String(data.version),
+          data.updatedAt,
+          brandingRevisionSeed(branding),
+        ]);
+        const pageHeaders = {
+          "content-type": "text/html; charset=utf-8",
+          vary: "Host",
+        } as const;
+        // 304 (Revision unverändert) und HEAD überspringen beide das
+        // Markdown-Rendern — der Body wird ohnehin verworfen.
+        if (etagMatches(c.req.raw.headers.get("if-none-match"), etag) || c.req.method === "HEAD") {
+          return cachedSecurePageResponse(c.req.raw, {
+            body: null,
+            etag,
+            cache: PUBLIC_PAGE_CACHE,
+            extra: pageHeaders,
+          });
+        }
+
+        const html = wrapLayout({
+          title: data.title,
+          bodyHtml: renderSafeMarkdown(data.body),
+          lang: data.lang,
+          slug,
+          description: data.description,
+          ogImage: data.ogImage,
+          branding,
+        });
+
+        return cachedSecurePageResponse(c.req.raw, {
+          body: html,
+          etag,
+          cache: PUBLIC_PAGE_CACHE,
+          extra: pageHeaders,
+        });
+      },
+    });
+
+    return { handlers, queries };
+  });
+}

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

@@ -0,0 +1,37 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { MANAGED_PAGES_CSS_FEATURE, readBranding, readCustomCss } from "../branding.js";
+
+// Public branding read for the server-render path. Anonymous-capable: the
+// render route reaches this via internal app.fetch with X-Tenant = host-
+// resolved tenant, so `query.user.tenantId` (and thus `ctx.config`, which is
+// minted from it) carries that tenant — identical to how by-slug resolves the
+// page. Branding keys are read:all → an anonymous caller may read them (they
+// are rendered on a public page). No payload: the tenant is implicit.
+//
+// custom CSS is gated twice: the app must opt in (allowCustomCss, baked into
+// this factory) AND the per-tenant `managed-pages-css` toggle must be on
+// (ctx.hasFeature). Note ctx.hasFeature returns true when no feature-toggles/
+// tier-engine runtime is wired, so without that runtime allowCustomCss alone
+// governs. Even when emitted, the value is RAW — render re-sanitizes it.
+export function createBrandingQuery(opts: { readonly allowCustomCss: boolean }) {
+  return defineQueryHandler({
+    name: "branding",
+    schema: z.object({}),
+    access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    description:
+      "Reads the tenant's public branding values for the rendered page shell, adding the raw custom CSS only when the app opted in and the per-tenant CSS toggle is on; anonymous callers may read it because it dresses public pages.",
+    handler: async (_query, ctx) => {
+      const base = await readBranding(ctx.config);
+      if (
+        !opts.allowCustomCss ||
+        !ctx.config ||
+        !(await ctx.hasFeature(MANAGED_PAGES_CSS_FEATURE))
+      ) {
+        return base;
+      }
+      return { ...base, customCss: await readCustomCss(ctx.config) };
+    },
+  });
+}

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

@@ -0,0 +1,40 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type PageRow, pagesTable } from "../table.js";
+
+// Public-Read by (tenantId, slug, lang). Anonymous-capable (Landing-/
+// Marketing-Pages). Tenant kommt aus query.user.tenantId — am Render-Pfad
+// via X-Tenant = Host-resolved-tenant gesetzt. Liefert NUR published Pages
+// mit Body: Drafts + leere Pages sind für anonyme Besucher unsichtbar
+// (Route → 404). Admin-Editing nutzt die Entity-List/Edit-Screens, nicht
+// diese Query.
+export const bySlugQuery = defineQueryHandler({
+  name: "by-slug",
+  schema: z.object({
+    slug: z.string().min(1).max(64),
+    lang: z.string().min(2).max(8),
+  }),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+  description:
+    "Reads the body and metadata of one published managed page of the caller's tenant by slug and language, returning null for drafts and bodyless pages; use it to render a public page, not to load one for editing.",
+  handler: async (query, ctx) => {
+    const row = await fetchOne<PageRow>(ctx.db, pagesTable, {
+      tenantId: query.user.tenantId,
+      slug: query.payload.slug,
+      lang: query.payload.lang,
+    });
+    if (!row?.published || !row.body) return null;
+    return {
+      slug: row.slug,
+      lang: row.lang,
+      title: row.title,
+      body: row.body,
+      description: row.description,
+      ogImage: row.ogImage,
+      version: row.version,
+      updatedAt: row.updatedAt,
+    };
+  },
+});

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

@@ -0,0 +1,55 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
+import {
+  crossTenantOverrideDenied,
+  defineQueryHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type PageRow, pagesTable } from "../table.js";
+
+// Public-Read aller published Pages eines Tenants — Discovery-Quelle für
+// sitemap.xml/llms.txt (siehe seo-Feature). Anders als by-slug (single-row,
+// nur der angefragte Slug) listet dies alle published Slugs auf einmal, SQL-
+// seitig auf `published = true` gefiltert (Drafts nie im Ergebnis, kein
+// Body-Content — Discovery-Zweck braucht nur Slug/Title/updatedAt).
+// Anonymous: explizit in roles, symmetrisch zu text-content's by-tenant.
+export type PublishedPageSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly updatedAt: Date;
+};
+
+export const byTenantPublishedQuery = defineQueryHandler({
+  name: "by-tenant-published",
+  schema: z.object({
+    /** Optional cross-tenant read — nur für SystemAdmin. Symmetrisch zur
+     *  by-slug.query Override-Logik. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+  description:
+    "Lists every published page of a tenant with slug, language, title and last-change time but no body; use it to enumerate the public pages for sitemap.xml or llms.txt, rather than by-slug which fetches one page's content.",
+  handler: async (query, ctx) => {
+    const override = query.payload.tenantIdOverride;
+    const overrideDenied = crossTenantOverrideDenied(
+      query.user,
+      override,
+      "managedPages.errors.tenantOverrideRequiresSystemAdmin",
+    );
+    if (overrideDenied) throw overrideDenied;
+    const tenantId = override ?? query.user.tenantId;
+    const rows = castTenantRows<PageRow>(
+      await selectMany(ctx.db, pagesTable, { tenantId: tenantId, published: true }),
+    );
+    return {
+      pages: rows.map((row) => ({
+        slug: row.slug,
+        lang: row.lang,
+        title: row.title,
+        updatedAt: row.updatedAt,
+      })),
+    };
+  },
+});

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

@@ -0,0 +1,49 @@
+import {
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { pageEntity } from "../table.js";
+
+// Admin authoring runs as TenantAdmin (self-service) or SystemAdmin (app-wide
+// pages). Mirrors set.write's ACL — an app with its own role alias
+// (publicstatus = "Admin") has to grant or map TenantAdmin.
+const ADMIN_ACCESS = { roles: ["TenantAdmin", "SystemAdmin"] } as const;
+
+// Convention CRUD behind the admin screens: entityEdit/entityList dispatch
+// `managed-pages:write:page:{create,update,delete}` +
+// `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.",
+  }),
+  defineEntityDeleteHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Deletes one managed page by row id so its URL stops resolving entirely; use it to retire a page for good, not to take it offline temporarily — that is a published:false write through managed-pages:write:set.",
+    agent: { risk: "high" },
+  }),
+];
+
+export const pageCrudQueries = [
+  defineEntityListHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Lists the tenant's managed pages for the admin catalog, drafts included; use it to browse or search pages for editing, unlike by-tenant-published which only enumerates the publicly visible ones.",
+  }),
+  defineEntityDetailHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Reads one managed page by row id including its body and draft state; use it to load a page into the admin edit screen, whereas by-slug serves the public render path.",
+  }),
+];

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

@@ -0,0 +1,133 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  crossTenantOverrideDenied,
+  defineWriteHandler,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { type PageRow, pageEntity, pagesTable } from "../table.js";
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be kebab-case (lowercase, digits, dashes)");
+
+const langSchema = z
+  .string()
+  .min(2)
+  .max(8)
+  .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "lang must be ISO 639-1 (e.g. de, en, en-us)");
+
+const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName: "page" });
+
+const SET_PAGE_TENANT_OVERRIDE_REASON =
+  "SystemAdmin tenantIdOverride re-scopes the page write to the target tenant";
+
+// Upsert einer Page — eine Operation pro (tenantId, slug, lang). Tenant-
+// Scope default aus event.user; SystemAdmin kann via `tenantIdOverride`
+// für einen anderen Tenant schreiben (typisch SYSTEM_TENANT_ID für app-
+// weite Pages). published/description/ogImage werden bei Update preserved
+// wenn im Payload weggelassen (undefined) — damit ein Publish-Toggle nicht
+// den Body überschreiben muss und umgekehrt.
+export const setWrite = defineWriteHandler({
+  name: "set",
+  schema: z.object({
+    slug: slugSchema,
+    lang: langSchema,
+    title: z.string().min(1).max(200),
+    body: z.string().max(100_000).nullable(),
+    description: z.string().max(500).nullable().optional(),
+    ogImage: z.string().max(2000).nullable().optional(),
+    published: z.boolean().optional(),
+    /** Cross-tenant write — nur SystemAdmin (z.B. SYSTEM_TENANT_ID-Pages). */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  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.",
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: SET_PAGE_TENANT_OVERRIDE_REASON,
+  },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const override = event.payload.tenantIdOverride;
+    const overrideDenied = crossTenantOverrideDenied(
+      event.user,
+      override,
+      "managedPages.errors.tenantOverrideRequiresSystemAdmin",
+    );
+    if (overrideDenied) return writeFailure(overrideDenied);
+    const tenantId = override ?? event.user.tenantId;
+    // override: point the executor context at the target tenant, else getStreamVersion runs against user.tenantId → version_conflict.
+    const executorUser =
+      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user; // @cast-boundary engine-bridge
+
+    // 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.
+    // Safe: the override branch is SystemAdmin-gated above.
+    const scopedDb =
+      override !== undefined
+        ? createTenantDb(
+            db.unsafeRaw(SET_PAGE_TENANT_OVERRIDE_REASON),
+            override as TenantId, // @cast-boundary engine-bridge
+            "tenant",
+          )
+        : db;
+    const existing = await fetchOne<PageRow>(scopedDb, pagesTable, {
+      tenantId,
+      slug: event.payload.slug,
+      lang: event.payload.lang,
+    });
+
+    if (existing) {
+      const result = await executor.update(
+        {
+          id: existing.id,
+          version: existing.version,
+          changes: {
+            title: event.payload.title,
+            body: event.payload.body,
+            description:
+              event.payload.description !== undefined
+                ? event.payload.description
+                : existing.description,
+            ogImage: event.payload.ogImage !== undefined ? event.payload.ogImage : existing.ogImage,
+            published:
+              event.payload.published !== undefined ? event.payload.published : existing.published,
+          },
+        },
+        executorUser,
+        scopedDb,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { slug: event.payload.slug, lang: event.payload.lang, isNew: false },
+      };
+    }
+
+    const result = await executor.create(
+      {
+        slug: event.payload.slug,
+        lang: event.payload.lang,
+        title: event.payload.title,
+        body: event.payload.body,
+        description: event.payload.description ?? null,
+        ogImage: event.payload.ogImage ?? null,
+        published: event.payload.published ?? false,
+        tenantId,
+      },
+      executorUser,
+      scopedDb,
+    );
+    if (!result.isSuccess) return result;
+    return {
+      isSuccess: true as const,
+      data: { slug: event.payload.slug, lang: event.payload.lang, isNew: true },
+    };
+  },
+});

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

@@ -0,0 +1,62 @@
+// @runtime client
+// Pure-Data (i18n-Keys) — client-marked, damit das web/-Bundle sie in den
+// Browser-Store pivotieren darf; feature.ts (server) importiert sie ebenso
+// (server darf client-safe Pure-Data importieren, wie PAT constants.ts).
+//
+// Übersetzungs-Bundle für die managed-pages Admin-Screens. Ohne diese Keys
+// rendert die UI die Roh-i18n-Keys (screen:*.title, entity:*:field:*, Section-
+// Header). Der Boot-Validator (required-surface-keys) verlangt — sobald ein
+// Feature r.translations ruft — den KOMPLETTEN Required-Surface-Satz in de+en;
+// diese Datei deckt jeden Screen/Feld/Section-Key ab, den managed-pages
+// registriert. Die zwei customCss-Keys werden unconditional geliefert (schaden
+// bei allowCustomCss:false nicht, sind aber Pflicht für Consumer die es aktivieren).
+
+type LocalizedString = { readonly en: string };
+
+export const MANAGED_PAGES_I18N: Readonly<Record<string, LocalizedString>> = {
+  // Screen-Titel (global/unpräfixiert — screenTitleKey = screen:<id>.title)
+  "screen:page-list.title": { en: "Pages" },
+  "screen:page-edit.title": { en: "Edit page" },
+  "screen:branding-settings.title": { en: "Branding" },
+
+  // Page-Entity Feld-Labels (managed-pages:entity:page:field:*)
+  "managed-pages:entity:page:field:slug": { en: "Slug" },
+  "managed-pages:entity:page:field:lang": { en: "Language" },
+  "managed-pages:entity:page:field:title": { en: "Title" },
+  "managed-pages:entity:page:field:published": { en: "Published" },
+  "managed-pages:entity:page:field:published:option:true": {
+    en: "Published",
+  },
+  "managed-pages:entity:page:field:published:option:false": { en: "Draft" },
+  "managed-pages:entity:page:field:description": { en: "Description" },
+  "managed-pages:entity:page:field:ogImage": { en: "OG image" },
+  "managed-pages:entity:page:field:body": { en: "Content" },
+
+  // Config-Edit Feld-Labels (managed-pages:entity:__config-edit__:field:*, camelCase Form-Keys)
+  "managed-pages:entity:__config-edit__:field:title": { en: "Site title" },
+  "managed-pages:entity:__config-edit__:field:description": {
+    en: "Description",
+  },
+  "managed-pages:entity:__config-edit__:field:siteUrl": { en: "Site URL" },
+  "managed-pages:entity:__config-edit__:field:accentColor": {
+    en: "Accent color",
+  },
+  "managed-pages:entity:__config-edit__:field:logoUrl": { en: "Logo URL" },
+  "managed-pages:entity:__config-edit__:field:layoutPreset": { en: "Layout" },
+
+  // Section-Header
+  "managed-pages:section.meta": { en: "Metadata" },
+  "managed-pages:section.body": { en: "Content" },
+  "managed-pages:branding.section.identity": { en: "Identity" },
+
+  // Row-Actions + Confirm (pageListScreen)
+  "managed-pages:actions.edit": { en: "Edit" },
+  "managed-pages:actions.delete": { en: "Delete" },
+  "managed-pages:confirms.page-delete": {
+    en: "Delete this page?",
+  },
+
+  // Nur bei allowCustomCss:true im Screen — unconditional geliefert
+  "managed-pages:entity:__config-edit__:field:customCss": { en: "Custom CSS" },
+  "managed-pages:branding.section.custom-css": { en: "Custom CSS" },
+};