@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/lifecycle-hooks/README.md

@@ -0,0 +1,46 @@
+# Lifecycle hooks
+
+Attach behaviour to the four entity lifecycle moments: validation
+(reject bad input), postSave (log every change), preDelete (block delete
+when an invariant says no), postDelete (log after commit). This recipe
+ships an `article` entity with hooks at each phase.
+
+Hooks are how a feature inserts cross-cutting logic without the handler
+body knowing about it. They run in the same transaction as the write
+unless explicitly opted out, so a thrown hook rolls the whole change
+back.
+
+## What it shows
+
+- **`r.hook("validation", handlerRef, fn)`** — runs before the
+  handler body executes. Returns either `null` (pass) or an array of
+  `{ field, error }` objects (fail). Used here to reject titles
+  containing the word "spam" and titles longer than 200 characters.
+- **`r.hook("postSave", { allOf: entityRef }, fn)`** — fires after every
+  successful save (create or update) in the same transaction.
+  `result.isNew` distinguishes create from update; `result.changes`
+  carries the changed fields only.
+- **`r.hook("preDelete", { allOf: entityRef }, fn)`** — fires inside the
+  delete transaction. Throws on invariant violations (here: "published
+  articles cannot be deleted") to roll the delete back. The handler
+  receives the full row snapshot — no extra load needed.
+- **`r.hook("postDelete", { allOf: entityRef }, fn)`** — fires after commit.
+  External side effects (logs, notifications) belong here because
+  failures cannot roll the delete back.
+
+## When to reach for it
+
+You want logic that runs alongside writes — auditing, notification
+emails, denormalised counter updates — without modifying the handler
+body. The split between in-transaction and after-commit phases lets you
+pick the right rollback semantics for each side effect.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). Integration
+tests exercise each of the four hook phases plus the rollback path on
+preDelete violation.
+
+```bash
+bun kumiko test integration samples/lifecycle-hooks
+```

package/samples/recipes/lifecycle-hooks/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-lifecycle-hooks",
+  "description": "preSave, postSave, and the rest. Your logic, our plumbing.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/lifecycle-hooks/src/feature.ts

@@ -0,0 +1,104 @@
+// Lifecycle Hooks Sample
+// Shows: validation hooks (reject bad data), postSave entity hooks (track changes),
+// preDelete hooks (block delete on invariant violation), postDelete hooks
+// (log deletions after commit).
+
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type SaveContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+
+export const articleEntity = createEntity({
+  table: "read_sample_articles",
+  fields: {
+    // maxLength high so zod lets long titles through — the validation hook
+    // below rejects titles > 200 so the sample can demonstrate the hook path.
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 1000,
+    }),
+    content: createTextField({ personal: false, reason: "is_business_data" }),
+    status: createTextField({ personal: false, reason: "is_business_data", default: "draft" }),
+    isPublished: createBooleanField({ default: false }),
+  },
+});
+
+// Collect hook events for testing
+export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
+
+const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
+
+export const articlesFeature = defineFeature("blog", (r) => {
+  const article = r.entity("article", articleEntity);
+
+  const articleCreate = r.writeHandler(
+    defineEntityCreateHandler("article", articleEntity, editorWrite),
+  );
+  const articleUpdate = r.writeHandler(
+    defineEntityUpdateHandler("article", articleEntity, editorWrite),
+  );
+  r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
+
+  // --- Validation hook on create: reject banned words + length ---
+  r.hook("validation", articleCreate, (data) => {
+    const title = data["title"] as string;
+    if (title.toLowerCase().includes("spam")) {
+      return [{ field: "title", error: "title_contains_banned_word" }];
+    }
+    if (title.length > 200) {
+      return [{ field: "title", error: "title_too_long" }];
+    }
+    return null;
+  });
+
+  // --- Validation hook on update: length check on title changes ---
+  r.hook("validation", articleUpdate, (data) => {
+    const changes = data["changes"] as Record<string, unknown> | undefined;
+    const title = changes?.["title"] as string | undefined;
+    if (title && title.length > 200) {
+      return [{ field: "title", error: "title_too_long" }];
+    }
+    return null;
+  });
+
+  // --- postSave entity hook: log all saves ---
+  r.hook("postSave", { allOf: article }, async (result: SaveContext) => {
+    hookLog.push({
+      type: result.isNew ? "created" : "updated",
+      data: { id: result.id, changes: result.changes },
+    });
+  });
+
+  // --- preDelete entity hook: block delete when the article is still published.
+  // preDelete runs inside the write transaction and throws on violation, so
+  // the delete rolls back before any projection or event is written. The
+  // payload.data carries the full row snapshot taken just before delete —
+  // no extra load needed.
+  r.hook("preDelete", { allOf: article }, async (payload) => {
+    if (payload.data["isPublished"] === true) {
+      throw new ConflictError({
+        message: `article ${payload.id} is still published`,
+        i18nKey: "errors.publishedArticleCannotBeDeleted",
+        details: { reason: "published_article_cannot_be_deleted", entityId: payload.id },
+      });
+    }
+  });
+
+  // --- postDelete entity hook: log deletions after the transaction commits.
+  // Default phase is afterCommit so failures here can't roll back the delete.
+  r.hook("postDelete", { allOf: article }, async (payload) => {
+    hookLog.push({
+      type: "deleted",
+      data: { id: payload.id },
+    });
+  });
+});

package/samples/recipes/managed-config/README.md

@@ -0,0 +1,136 @@
+# Recipe: Managed config
+
+**What this shows:** how one declarative config surface provisions everything a
+key needs — storage, masking, cascade, and a settings-hub entry — across two
+backings and two scopes, without a hand-written screen, nav, or env-wiring map.
+
+Two keys, deliberately different:
+
+| Key | Scope | Backing | Story |
+|---|---|---|---|
+| `payment-api-key` | `system` | `secrets` | Platform-owned secret (one Stripe key bills all tenants). Stored envelope-encrypted in the secrets store, masked in every query, revealed only for the owning feature's `ctx.config` read. |
+| `smtp-host` | `tenant` | config | Platform default that a tenant admin overrides. Cascade resolves `tenant-row → system-row → default`; one tenant's override never leaks to another. |
+
+## Pattern
+
+```ts illustration
+import { access, createSystemConfig, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+
+r.config({
+  keys: {
+    // System-only secret: storage routes to the secrets envelope (KEK rotation
+    // + audit-on-read), never config_values. backing:"secrets" is system-only —
+    // the boot-guard rejects it on tenant/user scope (secrets has no cascade).
+    "payment-api-key": createSystemConfig("text", {
+      backing: "secrets",
+      write: access.systemAdmin,
+      read: access.admin,
+      mask: { title: "integrations.payment-api-key", icon: "credit-card", order: 1 },
+    }),
+    // Tenant override with a platform default sourced from an env var at boot.
+    "smtp-host": createTenantConfig("text", {
+      env: "SMTP_HOST",
+      default: "smtp.platform.example",
+      write: access.roles("SystemAdmin", "Admin"),
+      read: access.admin,
+      mask: { title: "integrations.smtp-host", icon: "mail", order: 2 },
+    }),
+  },
+});
+```
+
+## What each option provisions
+
+- **`backing: "secrets"`** — the value lives in the secrets store (envelope
+  encryption, KEK rotation, audit-on-read) instead of `config_values`. Set/read/
+  reset dispatch through `ctx.secrets`; the query handlers mask the value while
+  the owning feature still reads the revealed plaintext via `ctx.config`. Only
+  valid for `scope: "system"` — secrets are flat per `(tenant, key)` with no
+  cascade, so a tenant override would be incoherent and is rejected at boot.
+- **`env: "SMTP_HOST"`** — at boot (`runProdApp`) the env var seeds the key's
+  default as an app-override, below any `system-row`. The env var *is* the
+  default; no manual `AppConfigOverrides` map, no re-typing in the admin UI.
+- **`mask`** — the key surfaces automatically in the self-populating settings
+  hub: `buildConfigFeatureSchema` derives a `configEdit` screen + a child nav
+  under the audience hub (Platform / Organisation / Personal) from the key's
+  scope and type. No `r.screen`, no `r.nav`. `mask.title` is the i18n label key.
+
+## Boot wiring
+
+```ts illustration
+import {
+  createConfigAccessorFactory,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { createSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+
+const masterKeyProvider = createEnvMasterKeyProvider({ env: process.env });
+const resolver = createConfigResolver();
+
+await runProdApp({
+  extraContext: ({ db, registry }) => ({
+    configResolver: resolver,
+    _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    // Required whenever a key declares backing:"secrets" — without it the set
+    // and read paths fail loud, never silently miss.
+    secrets: createSecretsContext({ db, masterKeyProvider }),
+  }),
+  // ...
+});
+```
+
+Register the `secrets` feature too so its `tenant_secrets` table is migrated;
+the config backing only needs the `ctx.secrets` context shown above.
+
+## Vs. the neighbouring recipes
+
+| Pattern | Storage | Cascade | Use case |
+|---|---|---|---|
+| **`encrypted: true` config key** (`encrypted-tenant-config`) | `config_values`, AES ciphertext | system → tenant | Per-tenant customer secret, no KEK rotation/audit. |
+| **`backing: "secrets"` config key** (this recipe) | secrets envelope, system tenant | none (system-only) | Platform-owned secret needing rotation + audit-on-read, declared as a config key. |
+| **`r.secret`** (`secrets-demo`) | secrets envelope | none | Same storage, but addressed directly — no config key, no settings-hub entry. |
+
+`backing: "secrets"` is the bridge: you get the secrets store's guarantees
+*and* the config feature's declarative surface (masking, settings hub, the same
+`config:write:set` write path).
+
+## Flow
+
+1. SystemAdmin sets `payment-api-key` (`backing: "secrets"`) → value lands in
+   the secrets envelope, masked in every query.
+2. Owning feature reads plaintext via `ctx.config` — audit-on-read from secrets.
+3. SystemAdmin sets platform `smtp-host` default (system scope).
+4. Tenant A overrides `smtp-host` → cascade resolves tenant-row for A only.
+5. Tenant B still sees the system default — no cross-tenant leak.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Proves:
+
+- `backing: "secrets"` routes to secrets store, not `config_values`
+- Owning feature reads revealed plaintext; cascade queries stay masked
+- Tenant SMTP override wins locally and never leaks to another tenant
+- Boot rejects `integrationsFeature` without the `secrets` feature mounted
+
+## What's not in this recipe
+
+- **Tenant-scoped secrets** — forbidden by declaration. `backing: "secrets"` +
+  `scope: "tenant"`/`"user"` fails at boot; use `encrypted: true` for a
+  cascading per-tenant secret.
+- **The env→default bridge at runtime** — `env:` is wired by `runProdApp`, not
+  by `setupTestStack`, so the integration test sets the platform default
+  explicitly via a `scope: "system"` write rather than through the env var.
+
+## Related samples
+
+- [encrypted-tenant-config](/en/samples/recipes-encrypted-tenant-config/) —
+  per-tenant customer secrets with `encrypted: true` on config keys.
+- [apps-cap-billing-demo](/en/samples/apps-cap-billing-demo/) — mail transport
+  selected per tenant via config.

package/samples/recipes/managed-config/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-managed-config",
+  "description": "Managed config: one declaration provisions storage + masking + settings-hub, across backings (secrets vs config) and scopes (system vs tenant).",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/managed-config/src/feature.ts

@@ -0,0 +1,88 @@
+// Managed config — one declaration provisions everything a config key needs.
+//
+// Two keys, two backings, two scopes — same declarative surface:
+//
+//   payment-api-key  scope:"system"  backing:"secrets"   platform-owned secret
+//     → stored envelope-encrypted in the secrets store (system tenant), masked
+//       in every query, revealed only for the owning feature's ctx.config read.
+//
+//   smtp-host        scope:"tenant"  (config, plain)      per-tenant override
+//     → platform default (env/system-row) that a tenant admin can override;
+//       cascade resolves tenant-row → system-row → default.
+//
+// `mask` makes each key surface in the self-populating settings hub without a
+// hand-written r.screen / r.nav. `env` wires the platform default from an
+// environment variable at boot (runProdApp) — no manual AppConfigOverrides map.
+
+import {
+  access,
+  type ConfigKeyHandle,
+  createSystemConfig,
+  createTenantConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const FEATURE = "integrations";
+
+export const paymentApiKeyHandle: ConfigKeyHandle<"text"> = {
+  name: `${FEATURE}:config:payment-api-key`,
+  type: "text",
+};
+
+export const smtpHostHandle: ConfigKeyHandle<"text"> = {
+  name: `${FEATURE}:config:smtp-host`,
+  type: "text",
+};
+
+export const integrationsFeature = defineFeature(FEATURE, (r) => {
+  r.requires("config");
+  // backing:"secrets" stores payment-api-key in the secrets envelope, which
+  // the secrets feature provisions — declare the dependency so registry-build
+  // enforces it instead of leaving a consumer to discover the missing
+  // tenant_secrets table at runtime.
+  r.requires("secrets");
+
+  r.config({
+    keys: {
+      // System-only secret: backing:"secrets" routes storage to the secrets
+      // envelope (KEK rotation + audit-on-read), never config_values. The
+      // boot-guard rejects backing:"secrets" on any non-system scope.
+      "payment-api-key": createSystemConfig("text", {
+        backing: "secrets",
+        write: access.systemAdmin,
+        read: access.admin,
+        mask: { title: "integrations.payment-api-key", icon: "credit-card", order: 1 },
+      }),
+      // Tenant override with a platform default. env seeds the default from
+      // SMTP_HOST at boot; a tenant admin overrides it per tenant.
+      "smtp-host": createTenantConfig("text", {
+        env: "SMTP_HOST",
+        default: "smtp.platform.example",
+        write: access.roles("SystemAdmin", "Admin"),
+        read: access.admin,
+        mask: { title: "integrations.smtp-host", icon: "mail", order: 2 },
+      }),
+    },
+  });
+
+  // Internal-read probe: the owning feature reads its own secrets-backed key
+  // via ctx.config and receives the revealed plaintext, never the mask.
+  r.queryHandler(
+    "peek-payment-key",
+    z.object({}),
+    async (_query, ctx) => {
+      if (!ctx.config) throw new Error("ctx.config not wired");
+      return { value: await ctx.config(paymentApiKeyHandle) };
+    },
+    { access: { roles: ["SystemAdmin"] } },
+  );
+
+  r.translations({
+    keys: {
+      "integrations.settings": { de: "Integrationen", en: "Integrations" },
+      "integrations.payment-api-key": { de: "Zahlungs-API-Schlüssel", en: "Payment API Key" },
+      "integrations.smtp-host": { de: "SMTP-Server", en: "SMTP Host" },
+    },
+  });
+});

package/samples/recipes/managed-pages/README.md

@@ -0,0 +1,158 @@
+# Recipe: managed-pages
+
+Tenant-editable, server-rendered public pages with per-tenant branding and
+opt-in, tier-gated **custom CSS** — the framework generalization of the
+`legal-pages`/`wrapLayout` render pattern, hardened for untrusted tenant input.
+
+**What the recipe demonstrates:**
+- Compose `managed-pages` (+ its `config` dependency and the `managed-pages-css`
+  companion toggle) in `runProdApp({ features: [...] })`
+- Required wirings: `anonymousAccess` + `extraContext` config plumbing
+- Single-tenant `resolveApexTenant` (multi-tenant resolves from the Host)
+- The render boundary: published-only, Markdown raw-HTML escaped, per-tenant
+  branding applied as scoped `:root` vars, custom CSS allowlist-sanitized and
+  contained in a `<style data-tenant-css>` block
+- 6 integration tests proving end-to-end behavior
+
+## Layout
+
+```
+samples/recipes/managed-pages/
+├── package.json                # workspace deps
+├── README.md                   # this file
+└── src/
+    ├── feature.ts              # the composed features re-exported for tests
+    └── __tests__/
+        └── feature.integration.test.ts  # 6 tests: render + branding + CSS
+```
+
+## Run tests
+
+```bash
+# From the repo root:
+bun kumiko test all samples/recipes/managed-pages/
+```
+
+When the tests are green:
+- A published page is reachable via `stack.app.request("/p/about")`; a draft is `404`
+- Per-tenant content is cache-isolated (`Vary: Host`)
+- Raw HTML in a Markdown body is escaped (no `<script>` execution)
+- Branding writes (`config:write:set`) roundtrip into the rendered HTML
+- Attack CSS (`position:fixed`, `@import`, `url()`) is neutralized at render
+
+## Integration into a real app
+
+### 1. Compose the features
+
+```typescript illustration
+// bin/main.ts
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import {
+  createManagedPagesFeature,
+  createManagedPagesCssFeature,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+
+await runProdApp({
+  features: [
+    createManagedPagesFeature({
+      // Host → tenantId. Single-tenant returns a constant; multi-tenant maps
+      // the subdomain / custom domain. NULL → 404 (no tenant for this host).
+      resolveApexTenant: (host) => resolveTenantForHost(host),
+      // Opt-in custom CSS (default false, fail-closed). The render-time
+      // sanitizer is the safety boundary; gate per tier with the companion.
+      allowCustomCss: true,
+    }),
+    createManagedPagesCssFeature(),
+    /* ... your other features */
+  ],
+  // routes run anonymous; multi-tenant honors the per-page X-Tenant header
+  anonymousAccess: { tenantExists: async (id) => /* validate */ true },
+});
+```
+
+`config` is auto-mounted by `runProdApp`. In `setupTestStack` it is **not**, so
+the recipe lists `createConfigFeature()` explicitly (see `src/feature.ts`).
+
+> **anonymousAccess:** a fixed `defaultTenantId` locks single-tenant and rejects
+> the per-page `X-Tenant` with `400 tenant_mismatch` unless it equals the
+> default. Multi-tenant apps wire `tenantExists` (or a `tenantResolver`) and let
+> the route's `X-Tenant` win.
+
+### 2. Create the table
+
+```bash
+bun kumiko migrate generate    # detects the `page` entity → SQL migration
+bun kumiko migrate apply
+```
+
+### 3. Authoring + branding
+
+- Pages: TenantAdmin/SystemAdmin author via the `entityList`/`entityEdit`
+  screens (`managed-pages:screen:page-list`); wire nav/workspace onto them.
+- Branding: the `configEdit` screen (`managed-pages:screen:branding-settings`)
+  or `config:write:set` against the `BRANDING_QN.*` keys
+  (`managed-pages:config:branding-{title,accent-color,...,custom-css}`).
+
+### 4. Per-tenant CSS gating
+
+`createManagedPagesCssFeature()` is `r.toggleable({ default: false })`. To gate
+custom CSS per tier, wire `feature-toggles`/`tier-engine` so the
+`managed-pages-css` toggle is on only for entitled tenants. **Without a toggle
+runtime, `ctx.hasFeature` fails open** — the capability stays on. The fail-closed
+anchor is `allowCustomCss` (app-level opt-in); the toggle is the commercial gate.
+
+## Custom wrapLayout (your own marketing chrome)
+
+A custom `wrapLayout` receives `branding` RAW and untrusted: `title`/
+`description` are length-capped at write but **not** HTML-escaped, and
+`customCss` is unsanitized. Emit every tenant value through the exported
+boundary helpers — never interpolate `branding.title` yourself (stored XSS):
+
+```typescript illustration
+import {
+  brandingHeaderHtml,
+  brandingStyleBlock,
+  tenantStyleBlock,
+  TENANT_CONTENT_ATTR,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+
+const wrapLayout = (o) => `<!doctype html>
+<html lang="${o.lang}">
+<head>
+  <title>${o.title}</title>
+  ${/* your layout CSS */ ""}
+  ${brandingStyleBlock(o.branding)}            <!-- escaped :root theme vars -->
+  ${tenantStyleBlock(o.branding.customCss)}    <!-- scoped + sanitized + contained -->
+</head>
+<body>
+  ${brandingHeaderHtml(o.branding)}            <!-- escaped logo + title header -->
+  <main ${TENANT_CONTENT_ATTR}>${o.bodyHtml}</main>
+</body>
+</html>`;
+```
+
+`brandingHeaderHtml`/`brandingStyleBlock` escape + re-validate (hex/https) the
+branding tokens; `tenantStyleBlock` bakes in the scope selector so callers can't
+mis-scope and lose containment. The default skeleton (`wrapInLayout`) uses the
+exact same helpers.
+
+## Security posture
+
+| Threat | Mitigation |
+|---|---|
+| `<script>`/raw HTML in a page body | `renderSafeMarkdown` escapes raw HTML (Markdown-only) |
+| Cross-tenant content on a shared CDN | `Vary: Host` + per-tenant `resolveApexTenant` |
+| Draft leak to anonymous visitors | published-only; drafts → 404 |
+| `@import`/`url()`/`expression()`/`</style>` in custom CSS | allowlist-by-construction sanitizer (rebuilt from validated tokens) |
+| Scope-escape / overlay onto host chrome | scope-prefix + `position`/`isolation`/`overflow` containment |
+| Untrusted tenant abusing CSS | tier-gate (`managed-pages-css`) + `allowCustomCss` opt-in |
+
+Custom-CSS sanitization for untrusted tenants is **best-effort defense-in-depth**:
+a tenant can still restyle its **own** page area within the clip. Keep it
+tier-gated.
+
+## Cross-refs
+
+- [packages/bundled-features/src/managed-pages](../../../packages/bundled-features/src/managed-pages) — the feature
+- [packages/bundled-features/src/page-render/css-sanitize.ts](../../../packages/bundled-features/src/page-render/css-sanitize.ts) — the allowlist sanitizer
+- [samples/recipes/legal-pages](../legal-pages) — the simpler, static sibling

package/samples/recipes/managed-pages/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-managed-pages",
+  "description": "Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/managed-pages/src/feature.ts

@@ -0,0 +1,25 @@
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createManagedPagesCssFeature,
+  createManagedPagesFeature,
+} from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+// managed-pages declares `r.requires("config")` for its branding keys — the
+// config feature must be in the stack (runProdApp auto-mounts it; setupTestStack
+// does not, so the recipe lists it explicitly).
+export const configFeature = createConfigFeature();
+
+// Single-tenant apex: every request maps to the one system tenant. A multi-
+// tenant app resolves the tenant from the request Host (subdomain / custom
+// domain) and returns the matching tenantId instead — see README.
+export const managedPagesFeature = createManagedPagesFeature({
+  resolveApexTenant: () => SYSTEM_TENANT_ID,
+  allowCustomCss: true,
+});
+
+// Companion per-tenant toggle for the CSS-inject capability. Compose it and wire
+// feature-toggles to gate custom CSS per tier; without a toggle runtime,
+// `ctx.hasFeature` fails open and CSS stays on (the render-time sanitizer is the
+// safety boundary regardless).
+export const managedPagesCssFeature = createManagedPagesCssFeature();