@cosmicdrift/kumiko-samples 0.360.0 → 0.361.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.360.0",
+  "version": "0.361.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

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

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "fix",
+    "title": "Audit log works under an active subject KMS",
+    "detail": "audit list, audit details and user-data-rights my-audit-log returned event payloads as stored. With a subject KMS configured the payload carried kumiko-pii ciphertext and the API leak guard answered 500 pii_ciphertext_leak. Every PII ciphertext string in the payload is now replaced by REDACTED_PII_PLACEHOLDER (\"[[personal data]]\"); the audit log still never shows plaintext PII."
+  },
   {
     "version": "0.353.0",
     "type": "fix",

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -7,6 +7,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.js";
 import { AUDIT_SCOPE_VALUES } from "../constants.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
@@ -51,7 +52,7 @@ export const detailsQuery = defineQueryHandler({
       aggregateType: row.aggregateType,
       version: row.version,
       type: row.type,
-      payload: row.payload,
+      payload: redactPiiCiphertext(row.payload),
       metadata: row.metadata,
       createdAt: row.createdAt,
       createdBy: row.createdBy,

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -9,16 +9,15 @@
 // A SystemAdmin can pass scope "system" to read the app-instance system events
 // (e.g. app.started); no other cross-tenant read exists.
 //
-// Sensitive field-values are ciphertext inside the event payload (the log
-// carries them encrypted); stripSensitive only strips the event echo. This
-// query returns payloads as stored, so a sensitive value surfaces as ciphertext,
-// never as plaintext.
+// Event payloads hold PII as subject-KMS ciphertext; it is replaced by
+// REDACTED_PII_PLACEHOLDER before returning, since the API leak guard refuses ciphertext.
 
 import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.js";
 import { AUDIT_SCOPE_VALUES } from "../constants.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
@@ -132,7 +131,7 @@ export const listQuery = defineQueryHandler({
       aggregateType: r.aggregateType,
       version: r.version,
       type: r.type,
-      payload: r.payload,
+      payload: redactPiiCiphertext(r.payload),
       metadata: r.metadata,
       createdAt: r.createdAt,
       createdBy: r.createdBy,

package/packages/bundled-features/src/auth-email-password/web/auth-client.ts

@@ -452,6 +452,8 @@ export type CurrentUserProfile = {
   readonly email: string;
   readonly displayName: string;
   readonly locale?: string;
+  /** Effective IANA zone (user override, else tenant, else UTC). */
+  readonly effectiveTimeZone?: string;
   readonly globalRoles: readonly string[];
 };
 
@@ -477,6 +479,7 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
       email: string;
       displayName: string;
       locale?: string;
+      effectiveTimeZone?: string;
       // JSON-encoded string[] — siehe userEntity.roles. Default "[]" wenn
       // keine globalen Rollen.
       roles?: string;
@@ -488,6 +491,9 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
     email: body.data.email,
     displayName: body.data.displayName,
     ...(body.data.locale !== undefined && { locale: body.data.locale }),
+    ...(body.data.effectiveTimeZone !== undefined && {
+      effectiveTimeZone: body.data.effectiveTimeZone,
+    }),
     globalRoles: parseRoles(body.data.roles),
   };
 }

package/packages/bundled-features/src/auth-email-password/web/session.tsx

@@ -10,8 +10,20 @@
 // und die Transitions.
 
 import { readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
-import { useSessionEndedSignal } from "@cosmicdrift/kumiko-renderer";
-import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react";
+import {
+  type CurrentUser,
+  CurrentUserProvider,
+  useSessionEndedSignal,
+} from "@cosmicdrift/kumiko-renderer";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import {
   AuthRequestError,
   type CurrentUserProfile,
@@ -232,7 +244,31 @@ export function SessionProvider({
   }, []);
 
   const api: SessionApi = { ...state, login, logout, switchTenant, refresh: doRefresh };
-  return <SessionContext.Provider value={api}>{children}</SessionContext.Provider>;
+  // Keyed on the primitives, not the profile object: every refresh (tenant
+  // switch, session bootstrap retry) builds a new profile object, and a new
+  // CurrentUser reference would re-seed a create form and drop typed input.
+  const profile = state.user;
+  const userId = profile?.id;
+  const userEmail = profile?.email;
+  const userDisplayName = profile?.displayName;
+  const userTimeZone = profile?.effectiveTimeZone;
+  const currentUser = useMemo<CurrentUser | undefined>(
+    () =>
+      userId === undefined || userEmail === undefined || userDisplayName === undefined
+        ? undefined
+        : {
+            id: userId,
+            email: userEmail,
+            displayName: userDisplayName,
+            ...(userTimeZone !== undefined && { timeZone: userTimeZone }),
+          },
+    [userId, userEmail, userDisplayName, userTimeZone],
+  );
+  return (
+    <SessionContext.Provider value={api}>
+      <CurrentUserProvider user={currentUser}>{children}</CurrentUserProvider>
+    </SessionContext.Provider>
+  );
 }
 
 export function useSession(): SessionApi {

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "cap-counter exports capReservationsTable and capReservationsTableMeta",
+    "detail": "The reservation table store_cap_reservations was only reachable through internal imports, so kumiko-enterprise redeclared it in a test. The cap-counter entry now exports capReservationsTable and capReservationsTableMeta, following the feature-toggles pattern."
+  },
   {
     "version": "0.358.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-counter/index.ts

@@ -49,6 +49,7 @@ export {
   type StockCapGuard,
   type StockCapSpec,
 } from "./stock-cap-guard.js";
+export { capReservationsTable, capReservationsTableMeta } from "./tables.js";
 export {
   createValueCapGuard,
   type ValueCapGuard,

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -55,6 +55,7 @@ import {
   nullBlindIndexesForSubject,
   type TenantDb,
   type WhereObject,
+  WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
@@ -259,14 +260,14 @@ async function forgetRowAndEraseKeys(args: {
 type FileFieldPlan = {
   /** type file|image — stores the fileRef-id directly in the entity column. */
   readonly singleFields: readonly string[];
-  /** type files|images — no entity column, resolved via file_refs. */
+  /** type files|images — resolved via file_refs (bound by entityType/entityId/fieldName). */
   readonly multiFields: readonly string[];
 };
 
 const NO_FILE_FIELDS: FileFieldPlan = { singleFields: [], multiFields: [] };
 
 // file/image = single-column fields (fileRef-id lives directly in the entity
-// row); files/images = plural, no column, resolved via file_refs. Same set
+// row); files/images = plural, resolved via file_refs. Same set
 // as boot-validator/entity-handler.ts FILE_FIELD_TYPES and engine's
 // isFileField — inlined here rather than importing across the package
 // barrel since this module already needs the single/multi split, not just
@@ -285,8 +286,8 @@ function planFileFields(fields: Readonly<Record<string, unknown>>): FileFieldPla
 }
 
 // Every fileRef-id a row's file/image/files/images-fields reference: single
-// fields hold the id in their own column, plural fields have no column and
-// resolve via file_refs (tenantId, entityType, entityId, fieldName).
+// fields hold the id in their own column, plural fields resolve
+// via file_refs (tenantId, entityType, entityId, fieldName).
 async function collectFileRefIds(
   db: DbRunner,
   tenantId: TenantId,
@@ -771,7 +772,8 @@ export async function runRetentionCleanup(
           proj.table,
           { ...where, isDeleted: false },
           batchLimit,
-          (id) => executor.delete({ id }, systemUser, tdb),
+          (id) =>
+            executor.delete({ id }, systemUser, tdb, { writePurpose: WritePurposes.retention }),
         );
         break;
       }
@@ -803,7 +805,10 @@ export async function runRetentionCleanup(
           batchLimit,
           targets,
           (id, changes) =>
-            executor.update({ id, changes }, systemUser, tdb, { skipOptimisticLock: true }),
+            executor.update({ id, changes }, systemUser, tdb, {
+              skipOptimisticLock: true,
+              writePurpose: WritePurposes.retention,
+            }),
         );
         break;
       }

package/packages/bundled-features/src/folders-user-data/hooks.ts

@@ -4,7 +4,7 @@
 // Mirrors credit-user-data — standard tenant-scoped pattern, no name-stripping
 // (a folder name is tenant data, not per-user PII).
 
-import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { type EventStoreExecutor, WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   createSystemUser,
@@ -64,7 +64,9 @@ function tenantScopedDelete(
     const systemUser = createSystemUser(ctx.tenantId);
     const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
     for (const row of rows) {
-      await executor.delete({ id: row.id }, systemUser, ctx.db);
+      await executor.delete({ id: row.id }, systemUser, ctx.db, {
+        writePurpose: WritePurposes.erasure,
+      });
     }
   };
 }

package/packages/bundled-features/src/form-draft-user-data/hooks.ts

@@ -3,6 +3,7 @@
 // consumers without the user-data-rights pipeline don't pull a hard
 // dependency.
 
+import { WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type UserDataDeleteHook,
@@ -42,7 +43,9 @@ export const formDraftDeleteHook: UserDataDeleteHook = async (ctx) => {
   const systemUser = createSystemUser(ctx.tenantId);
   const failures: string[] = [];
   for (const row of rows) {
-    const result = await formDraftExecutor.delete({ id: row.id }, systemUser, ctx.db);
+    const result = await formDraftExecutor.delete({ id: row.id }, systemUser, ctx.db, {
+      writePurpose: WritePurposes.erasure,
+    });
     if (!result.isSuccess) {
       failures.push(`${row.id}: ${result.error.message}`);
     }

package/packages/bundled-features/src/shared/encrypt-for-direct-write.ts

@@ -1,6 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import {
-  collectPiiSubjectFields,
+  collectPiiEncryptedFields,
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
   KeyErasedError,
@@ -24,7 +24,7 @@ export async function encryptForDirectWrite(
     return await encryptPiiFieldValues(
       row,
       entity,
-      collectPiiSubjectFields(entity),
+      collectPiiEncryptedFields(entity),
       kms,
       { requestId: requestContext.get()?.requestId ?? fallbackRequestId },
       { entityName },

package/packages/bundled-features/src/shared/index.ts

@@ -33,6 +33,7 @@ export {
   redactErrorText,
   redactUrls,
 } from "./redact.js";
+export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";
 export { requireForTenant } from "./require-for-tenant.js";
 export {
   type RowBoundGrantResult,

package/packages/bundled-features/src/shared/redact-pii-ciphertext.ts

@@ -0,0 +1,16 @@
+import { isPiiCiphertext } from "@cosmicdrift/kumiko-framework/crypto";
+
+export const REDACTED_PII_PLACEHOLDER = "[[personal data]]" as const;
+
+// Event payloads store PII fields as subject-KMS ciphertext; the API leak guard
+// rejects any response carrying it, so payload reads swap it for a placeholder.
+export function redactPiiCiphertext(value: unknown): unknown {
+  if (isPiiCiphertext(value)) return REDACTED_PII_PLACEHOLDER;
+  if (Array.isArray(value)) return value.map(redactPiiCiphertext);
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, inner]) => [key, redactPiiCiphertext(inner)]),
+    );
+  }
+  return value;
+}

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -1,7 +1,11 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb, WhereObject } from "@cosmicdrift/kumiko-framework/db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  WritePurposes,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type EscapeHatchAuditSink,
@@ -177,7 +181,7 @@ async function markTenantDestroyFailed(db: DbRunner, tenantId: TenantId): Promis
     },
     user,
     scopedDb,
-    { skipOptimisticLock: true },
+    { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
   );
   invalidateTenantLifecycleGate(tenantId);
 }
@@ -436,6 +440,7 @@ export async function runTenantDestructionSweep(args: {
       { id: tenantId, version, changes: { status: "destroying", destroyStartedAt: now } },
       user,
       scopedDb,
+      { writePurpose: WritePurposes.erasure },
     );
     if (!result.isSuccess) continue;
     invalidateTenantLifecycleGate(tenantId);

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -8,6 +8,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbRunner,
+  WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
@@ -233,7 +234,7 @@ async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<StageRunOut
     },
     user,
     db,
-    { skipOptimisticLock: true },
+    { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
   );
   invalidateTenantLifecycleGate(ctx.tenantId);
   return STAGE_DONE;

package/packages/bundled-features/src/user/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "user:me returns effectiveTimeZone, SessionProvider provides the current user",
+    "detail": "The me query adds effectiveTimeZone (ctx.tz.user), CurrentUserProfile.effectiveTimeZone is parsed by fetchCurrentUser and SessionProvider wraps its children in CurrentUserProvider."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/user/handlers/me.query.ts

@@ -8,6 +8,7 @@ const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user
 
 // Returns the currently signed-in user's profile. Field-level read access
 // strips out the passwordHash automatically (configured on the entity).
+// `effectiveTimeZone` is the effective IANA zone of the caller.
 export const meQuery = defineQueryHandler({
   name: "user:me",
   schema: z.object({}),
@@ -33,6 +34,9 @@ export const meQuery = defineQueryHandler({
     const db = ctx.systemDb.acknowledgeCrossTenant(
       "user rows are tenant-agnostic identity records; self-lookup by id needs no tenant filter",
     );
-    return crud.detail({ id: query.user.id }, query.user, db); // @wrapper-known semantic-alias
+    const row = await crud.detail({ id: query.user.id }, query.user, db);
+    // `timezone` on the row is only the stored override (often unset); clients
+    // need the effective zone (override, else tenant, else UTC) to compute "today".
+    return row === null ? row : { ...row, effectiveTimeZone: ctx.tz.user };
   },
 });

package/packages/bundled-features/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -3,6 +3,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.js";
 
 // DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
 // WHERE createdBy = ctx.user.id ist hard-coded (kein userId-Param,
@@ -75,7 +76,7 @@ export const myAuditLogQuery = defineQueryHandler({
       aggregateType: r["aggregate_type"],
       version: r["version"],
       type: r["type"],
-      payload: r["payload"],
+      payload: redactPiiCiphertext(r["payload"]),
       createdAt: r["created_at"],
     }));
     const last = serialised[serialised.length - 1];

package/packages/bundled-features/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -1,4 +1,8 @@
-import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  type TenantDb,
+  WritePurposes,
+} from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
@@ -206,6 +210,7 @@ async function severPersonLink(
     if (typeof id !== "string") continue;
     await crud.update({ id, changes: { insertedById: null } }, systemUser, tdb, {
       skipOptimisticLock: true,
+      writePurpose: WritePurposes.erasure,
     });
   }
 }

package/packages/bundled-features/src/user-data-rights-defaults/hooks/tenant-invitation.userdata-hook.ts

@@ -1,4 +1,4 @@
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type UserDataDeleteHook,
@@ -117,7 +117,7 @@ export const tenantInvitationDeleteHook: UserDataDeleteHook = async (ctx, strate
           { id, changes: { email: `forgotten-${id}@anonymized.invalid` } },
           systemUser,
           ctx.db,
-          { skipOptimisticLock: true },
+          { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
         );
       }
     }
@@ -138,6 +138,7 @@ export const tenantInvitationDeleteHook: UserDataDeleteHook = async (ctx, strate
     if (typeof id !== "string") continue;
     await crud.update({ id, changes: { invitedBy: INVITED_BY_ANONYMIZED } }, systemUser, ctx.db, {
       skipOptimisticLock: true,
+      writePurpose: WritePurposes.erasure,
     });
   }
   throwIfErasureFailed(failures);

package/packages/bundled-features/src/user-data-rights-defaults/hooks/user.userdata-hook.ts

@@ -1,4 +1,4 @@
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type UserDataDeleteHook,
@@ -102,7 +102,7 @@ export const userDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
       },
       systemUser,
       ctx.db,
-      { skipOptimisticLock: true },
+      { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
     );
   } else {
     // anonymize: PII raus, aber Row bleibt active (damit FK-References
@@ -120,7 +120,7 @@ export const userDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
       },
       systemUser,
       ctx.db,
-      { skipOptimisticLock: true },
+      { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
     );
   }
 };

package/samples/apps/styleguide/src/features/examples/feature.ts

@@ -37,14 +37,19 @@ export const shippingEntity = createEntity({
 });
 
 // Profile — testet das Avatar-Image-Upload-Feld (createImageField) in der
-// Auto-Form: runde Preview + "Change"-Button, Upload an /api/files.
+// Auto-Form: rechteckige Preview + "Change"-Button, Upload an /api/files.
 export const profileEntity = createEntity({
   table: "read_examples_profile",
   fields: {
     avatar: createImageField({ maxSize: "5mb", accept: ["jpg", "jpeg", "png"] }),
     fullName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
     // Demo-Daten, kein echtes PII-Encryption-Setup → Plaintext bewusst erlaubt.
-    email: createTextField({ required: true, personal: false, reason: "is_business_data" }),
+    email: createTextField({
+      required: true,
+      personal: false,
+      reason: "is_business_data",
+      sortable: true,
+    }),
     bio: createTextField({ personal: { of: "id" }, find: "none", multiline: { rows: 3 } }),
   },
 });
@@ -105,7 +110,51 @@ export const examplesFeature = defineFeature("examples", (r) => {
     },
   });
 
-  r.crud("profile", profileEntity, editFormOnly);
+  r.crud("profile", profileEntity, {
+    ...editFormOnly,
+    verbs: { delete: false, restore: false },
+  });
+
+  r.screen({
+    id: "profile-list",
+    type: "entityList",
+    entity: "profile",
+    dormant: true,
+    columns: ["avatar", "fullName", "email"],
+    searchable: true,
+    defaultSort: { field: "email", dir: "asc" },
+    rowActions: [
+      {
+        kind: "navigate",
+        id: "view",
+        label: "examples:profile:view",
+        screen: "profile-view",
+        entityId: "id",
+        rowClick: true,
+      },
+    ],
+    access: { openToAll: { reason: openReason } },
+  });
+
+  r.screen({
+    id: "profile-view",
+    type: "entityEdit",
+    entity: "profile",
+    dormant: true,
+    listScreenId: "profile-list",
+    layout: {
+      sections: [
+        {
+          columns: 2,
+          fields: [
+            { field: "avatar", span: 2, readOnly: true },
+            { field: "fullName", readOnly: true },
+            { field: "email", readOnly: true },
+          ],
+        },
+      ],
+    },
+  });
 
   r.screen({
     id: "profile-edit",

package/samples/apps/styleguide/src/features/examples/i18n.ts

@@ -38,6 +38,9 @@ export const EXAMPLES_I18N: Readonly<Record<string, LocalizedString>> = {
     de: "Aktualisiere deine persönlichen Daten und wie andere dich sehen.",
     en: "Update your personal information and how others see you.",
   },
+  "screen:profile-list.title": { de: "Profile", en: "Profiles" },
+  "screen:profile-view.title": { de: "Profil ansehen", en: "View profile" },
+  "examples:profile:view": { de: "Ansehen", en: "View" },
   "examples:profile:submit": { de: "Änderungen speichern", en: "Save changes" },
   "examples:entity:profile:field:avatar": { de: "Avatar", en: "Avatar" },
   "examples:entity:profile:field:fullName": { de: "Vollständiger Name", en: "Full name" },

package/samples/apps/ui-walkthrough/src/app/seed-rental.ts

@@ -163,6 +163,7 @@ const BOARD_LEASES: readonly BoardLease[] = [
 
 const MAX_NACHMIETER_INDEX = 2;
 const GENERATED_LEASE_COUNT = 300;
+const TERMINATED_LEASE_ID = "00000000-0000-4000-8000-000000003999";
 const FIRST_NAMES = [
   "Anna",
   "Ben",
@@ -204,7 +205,7 @@ function generatedLease(index: number): BoardLease & { readonly terminated: bool
     einheit: `WE-${String(100 + index)}`,
     liegenschaft: PROPERTIES[index % PROPERTIES.length] ?? "Haus Eichenweg",
     beginn: `${year}-${month}-01`,
-    ...(terminated && { ende: "2025-12-31" }),
+    ...(terminated && { ende: "2027-03-31" }),
     miete: 500 + (index % 20) * 15,
     terminated,
   };
@@ -240,7 +241,7 @@ export const seedRental: SeedFn = async (stack) => {
   }
   for (let index = 0; index < GENERATED_LEASE_COUNT; index++) {
     const lease = generatedLease(index);
-    await createLease(lease, lease.terminated);
+    await createLease(lease, lease.terminated, lease.terminated ? TERMINATED_LEASE_ID : undefined);
   }
 
   const maxId = boardLeaseId(MAX_NACHMIETER_INDEX);

package/samples/apps/ui-walkthrough/src/features/rental/feature.ts

@@ -11,6 +11,7 @@ import {
   germanStatusLabel,
   idPayloadSchema,
   leaseExecutor,
+  noticePeriodEnd,
   parseLeaseRow,
   partyExecutor,
   positionExecutor,
@@ -22,9 +23,11 @@ import {
 } from "./lease-support";
 import {
   adjustRentScreen,
+  leaseDetailGapsScreen,
   leaseDetailScreen,
   leaseEditScreen,
   leaseHubScreen,
+  leaseListEmptyScreen,
   leaseListScreen,
   leaseListShortScreen,
   partyEditScreen,
@@ -86,7 +89,8 @@ export const rentalFeature = defineFeature("rental", (r) => {
       return {
         id: lease.id,
         mieter: lease.mieter,
-        statusLabel: germanStatusLabel(lease.status),
+        status: lease.status,
+        statusLabel: germanStatusLabel(lease.status, lease.ende),
         grundmiete: formatGermanMoney(lease.grundmiete),
         beginn: formatGermanDate(lease.beginn),
         kuendigungsfrist: lease.kuendigungsfrist ?? "",
@@ -152,7 +156,10 @@ export const rentalFeature = defineFeature("rental", (r) => {
       leaseExecutor.update(
         {
           id: event.payload.id,
-          changes: { status: "terminated", ende: ctx.tz.today(ctx.tz.tenant).toString() },
+          changes: {
+            status: "terminated",
+            ende: noticePeriodEnd(ctx.tz.today(ctx.tz.tenant).toString()),
+          },
         },
         event.user,
         ctx.db,
@@ -232,6 +239,8 @@ export const rentalFeature = defineFeature("rental", (r) => {
   r.screen(partyEditScreen);
   r.screen(leaseDetailScreen);
   r.screen(leaseHubScreen);
+  r.screen(leaseDetailGapsScreen);
+  r.screen(leaseListEmptyScreen);
   r.screen(rentalDashboardScreen);
   r.screen(adjustRentScreen);
   r.screen(recordPositionsScreen);

package/samples/apps/ui-walkthrough/src/features/rental/i18n.ts

@@ -29,15 +29,22 @@ export const rentalTranslations: TranslationsByLocale = {
     "rental.tab.notes": "Notizen",
 
     "rental.action.open": "Öffnen",
-    "rental.action.terminate": "Mietvertrag kündigen",
+    "rental.action.terminate": "Kündigung erfassen",
     "rental.action.editLease": "Vertragsdaten bearbeiten",
-    "rental.action.terminateConfirm": "Soll dieser Mietvertrag gekündigt werden?",
+    "rental.action.terminateConfirm": "Kündigung zum Ende der Kündigungsfrist erfassen?",
     "rental.action.addPosition": "Position hinzufügen",
     "rental.action.adjustRent": "Miete anpassen",
     "rental.adjustRent.hint":
       "Die alte Position endet am Vortag, die neue beginnt am Stichtag. Art, Menge und Einheit bleiben dabei unverändert, so bleibt die Mietgeschichte nachvollziehbar.",
+    "rental.leaseListEmpty.description":
+      "Gekündigte Verträge, die aktuell als aktiv geführt werden.",
+    "rental.leaseListEmpty.emptyTitle": "Alles in Ordnung",
+    "rental.leaseListEmpty.emptyDescription":
+      "Es gibt keine gekündigten Verträge, die noch als aktiv geführt werden.",
+    "screen:lease-detail-gaps.title": "Mietvertrag",
+    "screen:lease-list-empty.title": "Mietverträge (Prüfliste)",
     "rental.action.createLease": "Mietvertrag abschließen",
-    "rental:entity:lease:noun": { one: "Mietvertrag", other: "Mietverträgen" },
+    "rental:entity:lease:noun": { one: "Mietvertrag", other: "Mietverträge" },
     "rental.search.placeholder": "Mieter, Einheit oder Liegenschaft",
     "rental.positions.description": "Alle Positionen dieses Vertrags mit ihrem Verlauf.",
     "rental.positions.noun": { one: "Position", other: "Positionen" },
@@ -134,13 +141,18 @@ export const rentalTranslations: TranslationsByLocale = {
     "rental.tab.notes": "Notes",
 
     "rental.action.open": "Open",
-    "rental.action.terminate": "Terminate lease",
+    "rental.action.terminate": "Record notice",
     "rental.action.editLease": "Edit lease details",
-    "rental.action.terminateConfirm": "Terminate this lease?",
+    "rental.action.terminateConfirm": "Record notice to the end of the notice period?",
     "rental.action.addPosition": "Add position",
     "rental.action.adjustRent": "Adjust rent",
     "rental.adjustRent.hint":
       "The old position ends the day before, the new one starts on the effective date. Type, quantity and unit stay unchanged, so the rent history stays traceable.",
+    "rental.leaseListEmpty.description": "Terminated leases that are still marked active.",
+    "rental.leaseListEmpty.emptyTitle": "All clear",
+    "rental.leaseListEmpty.emptyDescription": "No terminated leases are still marked active.",
+    "screen:lease-detail-gaps.title": "Lease",
+    "screen:lease-list-empty.title": "Leases (review list)",
     "rental.action.createLease": "Sign lease",
     "rental:entity:lease:noun": { one: "lease", other: "leases" },
     "rental.search.placeholder": "Tenant, unit or property",

package/samples/apps/ui-walkthrough/src/features/rental/lease-support.ts

@@ -61,6 +61,7 @@ const leaseRowSchema = z.object({
   liegenschaft: z.string().nullish(),
   beginn: readDateSchema,
   status: z.string(),
+  ende: readDateSchema.nullish(),
   grundmiete: moneySchema,
   kuendigungsfrist: z.string().nullish(),
   zahltag: z.number().nullish(),
@@ -90,10 +91,20 @@ const GERMAN_STATUS_LABEL: Readonly<Record<string, string>> = {
   terminated: "Gekündigt",
 };
 
-export function germanStatusLabel(status: string): string {
+export function germanStatusLabel(status: string, ende?: string | null): string {
+  if (status === "terminated" && ende) return `Gekündigt zum ${formatGermanDate(ende)}`;
   return GERMAN_STATUS_LABEL[status] ?? status;
 }
 
+// Tenant notice (§ 573c BGB, simplified to the 3rd calendar day instead of the
+// 3rd working day): notice received by then ends the lease after the month after
+// next, later notice one month later.
+export function noticePeriodEnd(isoToday: string): string {
+  const today = getTemporal().PlainDate.from(isoToday);
+  const target = today.add({ months: today.day <= 3 ? 2 : 3 });
+  return target.with({ day: target.daysInMonth }).toString();
+}
+
 export function formatGermanDate(isoDate: string): string {
   const [year, month, day] = isoDate.split("-");
   return `${day}.${month}.${year}`;

package/samples/apps/ui-walkthrough/src/features/rental/screens.ts

@@ -165,7 +165,8 @@ export const leaseDetailScreen: ProjectionDetailScreenDefinition = {
       { field: "liegenschaft", navigate: { screen: "lease-list" } },
     ],
     status: "statusLabel",
-    statusTones: { Aktiv: "ok", Gekündigt: "bad" },
+    statusToneField: "status",
+    statusTones: { active: "ok", terminated: "bad" },
   },
   metrics: ["grundmiete", "beginn", "kuendigungsfrist", "zahltag", "mieter"],
   fieldLabels: {
@@ -286,6 +287,7 @@ export const leaseDetailScreen: ProjectionDetailScreenDefinition = {
       handler: RENTAL_WRITES.leaseTerminate,
       payload: { pick: ["id"] },
       confirm: "rental.action.terminateConfirm",
+      visible: { field: "status", eq: "active" },
     },
     {
       kind: "navigate",
@@ -452,3 +454,46 @@ export const recordPositionsScreen: ActionFormScreenDefinition = {
   submitLabel: "rental.action.recordPositions",
   access: OPEN_ACCESS,
 };
+
+// Fixtures for the UI-gap screenshots: a confirm-gated primary action that is
+// visible only while the lease is active (a terminated lease falls back to edit
+// as the main button), and a list that is empty because of its default filter.
+export const leaseDetailGapsScreen: ProjectionDetailScreenDefinition = {
+  ...leaseDetailScreen,
+  id: "lease-detail-gaps",
+  detailFor: "lease",
+  primaryAction: "terminate",
+  actions: [
+    {
+      kind: "writeHandler",
+      id: "terminate",
+      icon: "x",
+      label: "rental.action.terminate",
+      handler: RENTAL_WRITES.leaseTerminate,
+      payload: { pick: ["id"] },
+      confirm: "rental.action.terminateConfirm",
+      style: "primary",
+      visible: { field: "status", eq: "active" },
+    },
+  ],
+};
+
+export const leaseListEmptyScreen: EntityListScreenDefinition = {
+  id: "lease-list-empty",
+  type: "entityList",
+  entity: "lease",
+  dormant: true,
+  description: "rental.leaseListEmpty.description",
+  emptyState: {
+    title: "rental.leaseListEmpty.emptyTitle",
+    description: "rental.leaseListEmpty.emptyDescription",
+  },
+  columns: [...OPEN_FILL_COLUMNS],
+  defaultSort: { field: "beginn", dir: "desc" },
+  filter: { field: "status", op: "eq", value: "terminated" },
+  defaultFilters: { status: ["active"] },
+  createLabel: "rental.action.createLease",
+  searchPlaceholder: "rental.search.placeholder",
+  rowActions: [openLeaseDetail],
+  access: OPEN_ACCESS,
+};

package/samples/apps/ui-walkthrough/src/features/vehicles/feature.ts

@@ -13,6 +13,7 @@ import { vehiclesTranslations } from "./i18n";
 import {
   campaignEditScreen,
   campaignListScreen,
+  vehicleEditFlowScreen,
   vehicleEditScreen,
   vehicleListScreen,
   vehicleWizardScreen,
@@ -67,6 +68,7 @@ export const vehiclesFeature = defineFeature("vehicles", (r) => {
   r.screen(vehicleListScreen);
   r.screen(vehicleEditScreen);
   r.screen(vehicleWizardScreen);
+  r.screen(vehicleEditFlowScreen);
   r.screen(campaignListScreen);
   r.screen(campaignEditScreen);
 

package/samples/apps/ui-walkthrough/src/features/vehicles/i18n.ts

@@ -10,6 +10,7 @@ export const vehiclesTranslations: TranslationsByLocale = {
     "screen:vehicle-list.title": "Fahrzeuge",
     "screen:vehicle-edit.title": "Angaben bearbeiten",
     "screen:vehicle-wizard.title": "Fahrzeug bearbeiten",
+    "screen:vehicle-edit-flow.title": "Ausstattung bearbeiten",
     "screen:campaign-list.title": "Kampagnen",
 
     "vehicles.action.edit": "Bearbeiten",
@@ -17,7 +18,7 @@ export const vehiclesTranslations: TranslationsByLocale = {
     "vehicles.action.details": "Details",
     "vehicles.action.saveChanges": "Änderungen speichern",
     "vehicles.search.placeholder": "Fahrzeug suchen",
-    "vehicles:entity:vehicle:noun": { one: "Fahrzeug", other: "Fahrzeugen" },
+    "vehicles:entity:vehicle:noun": { one: "Fahrzeug", other: "Fahrzeuge" },
     "vehicles:entity:campaign:noun": { one: "Kampagne", other: "Kampagnen" },
 
     "vehicles.section.basics": "Basisdaten",
@@ -119,6 +120,7 @@ export const vehiclesTranslations: TranslationsByLocale = {
     "screen:vehicle-list.title": "Vehicles",
     "screen:vehicle-edit.title": "Edit details",
     "screen:vehicle-wizard.title": "Edit vehicle",
+    "screen:vehicle-edit-flow.title": "Edit equipment",
     "screen:campaign-list.title": "Campaigns",
 
     "vehicles.action.edit": "Edit",

package/samples/apps/ui-walkthrough/src/features/vehicles/screens.ts

@@ -92,6 +92,24 @@ export const vehicleEditScreen: EntityEditScreenDefinition = {
   access: OPEN_ACCESS,
 };
 
+export const vehicleEditFlowScreen: EntityEditScreenDefinition = {
+  id: "vehicle-edit-flow",
+  type: "entityEdit",
+  entity: "vehicle",
+  dormant: true,
+  listScreenId: "vehicle-list",
+  recordTitleField: "modell",
+  layout: {
+    sections: [
+      {
+        title: "vehicles.section.equipment",
+        fields: ["marke", "modell", { field: "ausstattung", span: 2 }],
+      },
+    ],
+  },
+  access: OPEN_ACCESS,
+};
+
 export const vehicleWizardScreen: EntityEditScreenDefinition = {
   id: "vehicle-wizard",
   type: "entityEdit",

package/samples/recipes/files-post-processing/src/feature.ts

@@ -21,6 +21,9 @@ import type { DerivativePublicPredicateArgs } from "@cosmicdrift/kumiko-bundled-
 import {
   createEntity,
   createImageField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityUpdateHandler,
   defineFeature,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -32,7 +35,7 @@ import { z } from "zod";
 // the public route's fixed presets (thumb/card/hero/full, entry point 3)
 // share the name `thumb` but are a completely separate spec — same label,
 // different whitelist, different actual pixels.
-const photoEntity = createEntity({
+export const photoEntity = createEntity({
   table: "files_post_processing_photos",
   fields: {
     original: createImageField({
@@ -59,6 +62,13 @@ export const filesPostProcessingFeature = defineFeature("files-post-processing",
   r.requires("file-derivatives");
   r.entity("photo", photoEntity);
 
+  // Uploading a file to a photo's field needs the same rights as saving the
+  // photo, so the photo must exist and the uploader needs update access.
+  const photoAccess = { access: { roles: ["Admin"] } } as const;
+  r.writeHandler(defineEntityCreateHandler("photo", photoEntity, photoAccess));
+  r.writeHandler(defineEntityUpdateHandler("photo", photoEntity, photoAccess));
+  r.queryHandler(defineEntityDetailHandler("photo", photoEntity, photoAccess));
+
   // Entry point 2 — imperative. A real app would gate this behind real
   // roles; `openToAll` keeps the recipe's HTTP wiring to one line.
   r.writeHandler(