@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/managed-pages/branding.js

@@ -0,0 +1,156 @@
+import { access, createTenantConfig, } from "@cosmicdrift/kumiko-framework/engine";
+import { EMPTY_BRANDING } from "../page-render/index.js";
+// Per-tenant branding, lifted from the publicstatus-local branding-config
+// pattern into the framework so every app + studio-tenant gets tenant-editable
+// branding. Stored as `config` keys (scope: tenant), edited via the
+// configEdit screen (screens/branding-screen.ts), read at render time via the
+// branding query.
+//
+// Write-validated: accent-color must be a CSS hex, logo/site URLs must be
+// https. The configEdit screen dispatches `config:write:set` per key, which
+// runs the keyDef.pattern gate (set.write.ts → validatePattern). `read: all`
+// (scope default) so the anonymous public-render path can read them.
+//
+// `write: access.withSystem(access.admin)` — tenant admins self-service via
+// configEdit AND the system actor (ctx.systemWriteAs) may provision/migrate
+// these keys. The scope default (`access.admin`, admin-only) has no system
+// path, so a continuity migration could not set them (issue #396). Adding
+// SYSTEM_ROLE keeps the keys human-writable (checkWriteAccess collapses to
+// system-only only when system is the SOLE writer), so self-service survives.
+//
+// CONTINUITY (Phase 5 — Prod trap): these keys land under
+// `managed-pages:config:branding-*`, NOT the live `publicstatus:config:
+// branding-*`. The publicstatus consumer (Phase 5) MUST migrate the existing
+// read_config_values rows to the new QNs per tenant BEFORE switching the read
+// path, or every tenant resets to defaults on deploy. The migration is
+// deliberately NOT built here — the source QNs belong to the consumer app.
+// Anchored, allow-empty (empty = "unset, use default"; cleared via the form).
+// Linear → ReDoS-safe on untrusted tenant input. The URL char-class mirrors
+// the render-side validator (page-render/branding.ts) so a value that saves
+// also renders. text keys carry an explicit length cap too — `validateType`
+// only checks the JS type, and the configEdit `maxLength` is client-side, so a
+// direct config:write:set would otherwise be unbounded (the page body is
+// likewise capped in Phase 2).
+const HEX_PATTERN = {
+    regex: "^$|^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+};
+const HTTPS_PATTERN = { regex: "^$|^https://[^\\s\"'<>]{1,2000}$" };
+const TITLE_PATTERN = { regex: "^[\\s\\S]{0,200}$" };
+const DESCRIPTION_PATTERN = { regex: "^[\\s\\S]{0,500}$" };
+// Custom CSS is too complex for a regex allowlist — the write-time pattern only
+// caps length (ReDoS-safe, allow-empty); the real allowlist sanitization runs at
+// render (page-render/css-sanitize.ts). Keep this cap in sync with MAX_CSS_LENGTH
+// there.
+const CUSTOM_CSS_PATTERN = { regex: "^[\\s\\S]{0,8000}$" };
+export const LAYOUT_PRESETS = ["minimal", "centered", "wide"];
+// Companion toggle feature name. managed-pages reads ctx.hasFeature() against it
+// in the branding query to per-tenant-gate custom-CSS emission. Declared as a
+// `r.toggleable({default:false})` feature in css-gate.ts.
+export const MANAGED_PAGES_CSS_FEATURE = "managed-pages-css";
+// Short keys → qualified names via define-feature's `qn(feature, "config",
+// toKebab(key))`: e.g. `brandingSiteUrl` → `managed-pages:config:branding-
+// site-url`. BRANDING_QN below is the single source those QN strings are read
+// from (configEdit screen + render read); the integration test pins write-
+// target == read-source end-to-end.
+// Admin self-service + system provisioning (see write-access note above, #396).
+const BRANDING_WRITE = access.withSystem(access.admin);
+export const BRANDING_KEYS = {
+    brandingTitle: createTenantConfig("text", {
+        default: "",
+        pattern: TITLE_PATTERN,
+        write: BRANDING_WRITE,
+    }),
+    brandingDescription: createTenantConfig("text", {
+        default: "",
+        pattern: DESCRIPTION_PATTERN,
+        write: BRANDING_WRITE,
+    }),
+    brandingSiteUrl: createTenantConfig("text", {
+        default: "",
+        pattern: HTTPS_PATTERN,
+        write: BRANDING_WRITE,
+    }),
+    brandingAccentColor: createTenantConfig("text", {
+        default: "",
+        pattern: HEX_PATTERN,
+        write: BRANDING_WRITE,
+    }),
+    brandingLogoUrl: createTenantConfig("text", {
+        default: "",
+        pattern: HTTPS_PATTERN,
+        write: BRANDING_WRITE,
+    }),
+    brandingLayoutPreset: createTenantConfig("select", {
+        default: "centered",
+        options: LAYOUT_PRESETS,
+        write: BRANDING_WRITE,
+    }),
+};
+// Registered ONLY when the app passes allowCustomCss:true — kept out of
+// BRANDING_KEYS so the CSS editor field + key don't exist when the capability is
+// off (fail-closed at the app level). The render-time sanitizer is the real
+// safety boundary; this is the opt-in switch + a per-tenant toggle gate.
+export const CUSTOM_CSS_KEY = {
+    brandingCustomCss: createTenantConfig("text", { default: "", pattern: CUSTOM_CSS_PATTERN }),
+};
+export const BRANDING_QN = {
+    title: "managed-pages:config:branding-title",
+    description: "managed-pages:config:branding-description",
+    siteUrl: "managed-pages:config:branding-site-url",
+    accentColor: "managed-pages:config:branding-accent-color",
+    logoUrl: "managed-pages:config:branding-logo-url",
+    layoutPreset: "managed-pages:config:branding-layout-preset",
+    customCss: "managed-pages:config:branding-custom-css",
+};
+export const BRANDING_QUERY_QN = "managed-pages:query:branding";
+async function readText(config, qualifiedKey) {
+    const value = await config(qualifiedKey);
+    return typeof value === "string" ? value : "";
+}
+// Resolve the tenant's branding cascade into render tokens. `config` is
+// optional because ctx.config is only wired when the app composes the config
+// feature — a missing accessor degrades to defaults (same posture as
+// publicstatus' branding read), not a crash.
+export async function readBranding(config) {
+    if (!config)
+        return EMPTY_BRANDING;
+    const [title, description, siteUrl, accentColor, logoUrl, layoutPreset] = await Promise.all([
+        readText(config, BRANDING_QN.title),
+        readText(config, BRANDING_QN.description),
+        readText(config, BRANDING_QN.siteUrl),
+        readText(config, BRANDING_QN.accentColor),
+        readText(config, BRANDING_QN.logoUrl),
+        readText(config, BRANDING_QN.layoutPreset),
+    ]);
+    // customCss stays "" here — it is gated (allowCustomCss + per-tenant toggle)
+    // and read separately by the branding query via readCustomCss.
+    return { title, description, siteUrl, accentColor, logoUrl, layoutPreset, customCss: "" };
+}
+// Read the raw, untrusted custom CSS for the request's tenant. The caller (the
+// branding query) only invokes this once the gate has passed; the value is
+// sanitized at render (page-render), never trusted here.
+export async function readCustomCss(config) {
+    return readText(config, BRANDING_QN.customCss);
+}
+function stringField(source, key) {
+    const value = source[key];
+    return typeof value === "string" ? value : "";
+}
+// Coerce the branding query's wire response (`{ data: <BrandingTokens> }`)
+// into BrandingTokens at the IO boundary, without an `as` cast — any missing/
+// non-string field falls back to "" so a malformed/empty response renders the
+// unbranded default rather than throwing.
+export function coerceBranding(value) {
+    if (typeof value !== "object" || value === null)
+        return EMPTY_BRANDING;
+    const source = Object.fromEntries(Object.entries(value));
+    return {
+        title: stringField(source, "title"),
+        description: stringField(source, "description"),
+        siteUrl: stringField(source, "siteUrl"),
+        accentColor: stringField(source, "accentColor"),
+        logoUrl: stringField(source, "logoUrl"),
+        layoutPreset: stringField(source, "layoutPreset"),
+        customCss: stringField(source, "customCss"),
+    };
+}

package/dist/managed-pages/css-gate.d.ts

@@ -0,0 +1,2 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createManagedPagesCssFeature(): FeatureDefinition;

package/dist/managed-pages/css-gate.js

@@ -0,0 +1,21 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { MANAGED_PAGES_CSS_FEATURE } from "./branding.js";
+// Per-tenant toggle gate for the managed-pages custom-CSS capability. Declares
+// no handlers/entities — composing it simply registers `managed-pages-css` as a
+// `toggleable` feature (default OFF), which an operator/tier can enable per
+// tenant via feature-toggles. managed-pages' branding query reads
+// `ctx.hasFeature("managed-pages-css")` and only emits raw tenant CSS when this
+// toggle is on AND the app passed `allowCustomCss: true`.
+//
+// Without a feature-toggles/tier-engine runtime wired, ctx.hasFeature returns
+// true (apps without tier-cuts treat all features on), so `allowCustomCss`
+// alone governs. To per-tenant tier-gate CSS-inject, compose this feature AND
+// wire feature-toggles; the render-time sanitizer is the safety boundary either
+// way. Compose alongside managed-pages (it `requires` it).
+export function createManagedPagesCssFeature() {
+    return defineFeature(MANAGED_PAGES_CSS_FEATURE, (r) => {
+        r.describe('Per-tenant toggle gate for the managed-pages custom-CSS (raw tenant CSS-inject) capability. Handler-less: composing it makes `managed-pages-css` a toggleable feature defaulting OFF, so an operator/tier can grant raw CSS-inject per tenant. managed-pages reads `ctx.hasFeature("managed-pages-css")` in its branding query and emits tenant CSS only when this toggle is on AND the app passed `allowCustomCss: true`. The tenant CSS is allowlist-sanitized + scoped at render regardless; this gate is the commercial/operator control, not the safety boundary.');
+        r.requires("managed-pages");
+        r.toggleable({ default: false });
+    });
+}

package/dist/managed-pages/feature.d.ts

@@ -0,0 +1,45 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type BrandingTokens } from "../page-render/index.js";
+export type ManagedPagesWrapLayout = (opts: {
+    readonly title: string;
+    readonly bodyHtml: string;
+    readonly lang: string;
+    readonly slug: string;
+    readonly description: string | null;
+    readonly ogImage: string | null;
+    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;
+};
+export declare function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDefinition;

package/dist/managed-pages/feature.js

@@ -0,0 +1,181 @@
+import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { cachedSecurePageResponse, EMPTY_BRANDING, renderSafeMarkdown, wrapInLayout, } from "../page-render/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 };
+// 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";
+function brandingRevisionSeed(branding) {
+    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, tenantId) {
+    try {
+        return coerceBranding(await systemQuery(BRANDING_QUERY_QN, {}, tenantId));
+    }
+    catch {
+        return EMPTY_BRANDING;
+    }
+}
+// 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) {
+    const wrapLayout = 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, data: data }))
+                        .catch(() => ({ ok: false, data: null })),
+                    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",
+                };
+                // 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/dist/managed-pages/handlers/branding.query.d.ts

@@ -0,0 +1,4 @@
+import * as z from "zod";
+export declare function createBrandingQuery(opts: {
+    readonly allowCustomCss: boolean;
+}): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"branding", z.ZodObject<{}, z.core.$strip>, import("../index.js").BrandingTokens, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/managed-pages/handlers/branding.query.js

@@ -0,0 +1,33 @@
+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) {
+    return defineQueryHandler({
+        name: "branding",
+        schema: z.object({}),
+        access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+        rateLimit: { per: "ip", 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/dist/managed-pages/handlers/by-slug.query.d.ts

@@ -0,0 +1,14 @@
+import * as z from "zod";
+export declare const bySlugQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"by-slug", z.ZodObject<{
+    slug: z.ZodString;
+    lang: z.ZodString;
+}, z.core.$strip>, {
+    slug: string;
+    lang: string;
+    title: string;
+    body: string;
+    description: string | null;
+    ogImage: string | null;
+    version: number;
+    updatedAt: Date;
+} | null, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/managed-pages/handlers/by-slug.query.js

@@ -0,0 +1,39 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { 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", 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(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/dist/managed-pages/handlers/by-tenant-published.query.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+export type PublishedPageSummary = {
+    readonly slug: string;
+    readonly lang: string;
+    readonly title: string;
+    readonly updatedAt: Date;
+};
+export declare const byTenantPublishedQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"by-tenant-published", z.ZodObject<{
+    tenantIdOverride: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    pages: {
+        slug: string;
+        lang: string;
+        title: string;
+        updatedAt: Date;
+    }[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/managed-pages/handlers/by-tenant-published.query.js

@@ -0,0 +1,32 @@
+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 { pagesTable } from "../table.js";
+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", 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(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/dist/managed-pages/handlers/page-crud.d.ts

@@ -0,0 +1,2 @@
+export declare const pageCrudWrites: import("@cosmicdrift/kumiko-types/handlers").WriteHandlerDef[];
+export declare const pageCrudQueries: import("@cosmicdrift/kumiko-types/handlers").QueryHandlerDef[];

package/dist/managed-pages/handlers/page-crud.js

@@ -0,0 +1,35 @@
+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"] };
+// 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/dist/managed-pages/handlers/set.write.d.ts

@@ -0,0 +1,15 @@
+import * as z from "zod";
+export declare const setWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"set", z.ZodObject<{
+    slug: z.ZodString;
+    lang: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ogImage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    published: z.ZodOptional<z.ZodBoolean>;
+    tenantIdOverride: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    slug: string;
+    lang: string;
+    isNew: boolean;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;