@cosmicdrift/kumiko-framework 0.208.2 → 0.209.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.208.2",
+  "version": "0.209.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -190,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.208.2",
+    "@cosmicdrift/kumiko-types": "0.209.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.208.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.209.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/boot-validator-projection-list.test.ts

@@ -238,4 +238,208 @@ describe("validateBoot — projectionList screens", () => {
       );
     });
   });
+
+  // fw#2224: filter/facets are new on ProjectionListScreenDefinition — no
+  // entity to check field-existence against, so validation is either
+  // structural (filter) or checked against the declared columns (facets),
+  // plus the same "does the bound query's schema actually accept this
+  // param" check fw#2165 already does for search/sort.
+  describe("projectionList filter + facets (fw#2224)", () => {
+    test('filter.op "in" requires an array value', () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filter: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["description"],
+          filter: { field: "status", op: "in", value: "not-an-array" },
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/filter\.op "in" requires/);
+    });
+
+    test('filter declared but the query schema has no "filter" parameter', () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({}),
+          async () => ({ rows: [], nextCursor: null }),
+          {
+            access: { openToAll: true },
+          },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["description"],
+          filter: { field: "status", op: "eq", value: "active" },
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/no "filter" parameter/);
+    });
+
+    test("a facet referencing a field that isn't a declared column is rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["description"],
+          facets: [
+            {
+              field: "status",
+              type: "select",
+              label: "Status",
+              options: [{ value: "active", label: "Active" }],
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/not a declared column/);
+    });
+
+    test("duplicate facet fields are rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["status"],
+          facets: [
+            {
+              field: "status",
+              type: "boolean",
+              label: "Status",
+              trueLabel: "On",
+              falseLabel: "Off",
+            },
+            {
+              field: "status",
+              type: "boolean",
+              label: "Status",
+              trueLabel: "On",
+              falseLabel: "Off",
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/more than once/);
+    });
+
+    test("a select facet with an empty options list is rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["status"],
+          facets: [{ field: "status", type: "select", label: "Status", options: [] }],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/empty options list/);
+    });
+
+    test('facets declared but the query schema has no "filters" parameter', () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({}),
+          async () => ({ rows: [], nextCursor: null }),
+          {
+            access: { openToAll: true },
+          },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["status"],
+          facets: [
+            {
+              field: "status",
+              type: "boolean",
+              label: "Status",
+              trueLabel: "On",
+              falseLabel: "Off",
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/no "filters" parameter/);
+    });
+
+    test("a valid filter + facets declaration on a schema that accepts both passes boot", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filter: z.unknown().optional(), filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["status"],
+          filter: { field: "tier", op: "eq", value: "gold" },
+          facets: [
+            {
+              field: "status",
+              type: "boolean",
+              label: "Status",
+              trueLabel: "On",
+              falseLabel: "Off",
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+  });
 });

package/src/engine/__tests__/boot-validator.test.ts

@@ -3511,6 +3511,103 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- toolbarAction drawer (fw#2225) ---
+  describe("entityList toolbarAction drawer (fw#2225)", () => {
+    function makeFeature(opts: {
+      readonly targetId?: string;
+      readonly targetType?: "actionForm" | "entityList";
+    }) {
+      const targetId = opts.targetId ?? "restock-form";
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          toolbarActions: [
+            { kind: "drawer", id: "open-drawer", label: "actions.restock", screen: targetId },
+          ],
+        });
+        if (opts.targetType === "entityList") {
+          r.screen({
+            id: targetId,
+            type: "entityList",
+            entity: "product",
+            columns: ["name"],
+          });
+          return;
+        }
+        if (opts.targetType === "actionForm") {
+          r.writeHandler(
+            "restock",
+            z.object({ qty: z.number() }),
+            async () => ({ isSuccess: true as const, data: null }),
+            { access: { roles: ["Admin"] } },
+          );
+          r.screen({
+            id: targetId,
+            type: "actionForm",
+            handler: "shop:write:restock",
+            fields: { qty: { type: "number" } } as never,
+            layout: { sections: [{ fields: ["qty"] }] },
+          });
+        }
+      });
+    }
+
+    test("drawer-target → registered actionForm → no throw", () => {
+      expect(() => validateBoot([makeFeature({ targetType: "actionForm" })])).not.toThrow();
+    });
+
+    test("drawer-target → unknown → throw with a clear message", () => {
+      expect(() => validateBoot([makeFeature({ targetId: "ghost-form" })])).toThrow(
+        /toolbarAction "open-drawer" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+
+    test("drawer-target → screen exists but is not an actionForm → throw with a clear message", () => {
+      expect(() =>
+        validateBoot([makeFeature({ targetId: "product-list-2", targetType: "entityList" })]),
+      ).toThrow(
+        /toolbarAction "open-drawer" drawer-target "product-list-2" is a "entityList" screen, not an actionForm/,
+      );
+    });
+
+    test("drawer-target → actionForm in ANOTHER feature → throw (drawer resolves same-feature only)", () => {
+      const list = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          toolbarActions: [
+            { kind: "drawer", id: "open-drawer", label: "actions.restock", screen: "restock-form" },
+          ],
+        });
+      });
+      const consumer = defineFeature("app", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({ qty: z.number() }),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock-form",
+          type: "actionForm",
+          handler: "app:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: { sections: [{ fields: ["qty"] }] },
+        });
+      });
+      expect(() => validateBoot([list, consumer])).toThrow(
+        /toolbarAction "open-drawer" drawer-target "restock-form" does not resolve to a registered screen in this feature/,
+      );
+    });
+  });
+
   // --- defaultSort funktioniert für ALLE Field-Types die sortable
   //     unterstützen (Tier 2.6b Field-Erweiterung) ---
   // Vor Tier 2.6b war `sortable` nur auf TextFieldDef. Erweitert auf

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -137,6 +137,34 @@ describe("buildConfigFeatureSchema — structure", () => {
     ]);
   });
 
+  test("screen layout renders full-width", () => {
+    expect(configScreen("billing-tenant").layout.width).toBe("full");
+  });
+
+  test("section has no description when the feature never declares the '<feature>.settings.description' key", () => {
+    // billing declares no translations at all — the section must NOT carry a
+    // description prop (not just undefined), else the renderer would try to
+    // subtitle-render translate()'s undeclared-key fallback (the raw key).
+    const section = configScreen("billing-tenant").layout.sections[0];
+    expect(section && "description" in section).toBe(false);
+  });
+
+  test("section carries description when the feature declares '<feature>.settings.description'", () => {
+    const described = defineFeature("described", (r) => {
+      r.translations({ keys: { "described.settings.description": { en: "Manage settings." } } });
+      r.config({
+        keys: { flag: createTenantConfig("boolean", { mask: { title: "described.flag" } }) },
+      });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([described]));
+    const screen = out.screens.find((s) => s.id === "described-tenant");
+    if (screen?.type !== "configEdit") throw new Error("expected configEdit screen");
+    const section = screen.layout.sections[0];
+    expect(section && "description" in section ? section.description : undefined).toBe(
+      "described.settings.description",
+    );
+  });
+
   test("excludes unmasked keys and computed keys", () => {
     const s = configScreen("billing-tenant");
     // internal-flag has no mask, derived is computed → neither appears anywhere

package/src/engine/__tests__/projection-list-filter.integration.test.ts

@@ -0,0 +1,110 @@
+// fw#2224: a projectionList screen can now declare `filter`/`facets`, but
+// the wire contract that actually matters is the payload the query handler
+// receives — `screen.filter`/facet-toggles reach the server as
+// payload.filter/payload.filters (see kumiko-screen.tsx's ProjectionListBody
+// queryPayload). This proves the server side of that contract over real
+// HTTP: a query handler whose Zod schema accepts filter/filters (here the
+// entity-list auto-CRUD handler, entityListSchema) genuinely narrows the
+// returned rows — not just "the field is present in the payload".
+//
+// The bound query is a real entity-list handler (r.crud), the same one a
+// projectionList screen would point `query` at to reuse another feature's
+// list — see the registered "member-list" projectionList screen below,
+// which pins that this is a realistic, boot-valid setup, not just a
+// hand-rolled test handler.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+const memberEntity = createEntity({
+  table: "pl_filter_members",
+  fields: {
+    name: createTextField({ required: true }),
+    status: createTextField({ required: true, filterable: true }),
+  },
+});
+
+const LIST_QN = "roster:query:member:list";
+
+const rosterFeature = defineFeature("roster", (r) => {
+  r.crud("member", memberEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { openToAll: true } },
+  });
+  r.screen({
+    id: "member-list",
+    type: "projectionList",
+    query: LIST_QN,
+    columns: ["name", "status"],
+    filter: { field: "status", op: "eq", value: "active" },
+  });
+  r.translations({
+    keys: { "screen:member-list.title": { de: "Mitglieder", en: "Members" } },
+  });
+});
+
+describe("projectionList filter — real query narrows real rows (fw#2224)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [rosterFeature] });
+    await unsafeCreateEntityTable(stack.db, memberEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "pl_filter_members"');
+  });
+
+  async function seed(): Promise<void> {
+    const CREATE = "roster:write:member:create";
+    await stack.http.write(CREATE, { name: "Ada", status: "active" }, TestUsers.admin);
+    await stack.http.write(CREATE, { name: "Grace", status: "active" }, TestUsers.admin);
+    await stack.http.write(CREATE, { name: "Bob", status: "inactive" }, TestUsers.admin);
+  }
+
+  test("screen.filter's shape (payload.filter, op:eq) returns only matching rows", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string; readonly status: string }[];
+    }>(
+      LIST_QN,
+      { limit: 50, filter: { field: "status", op: "eq", value: "active" } },
+      TestUsers.admin,
+    );
+
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows.map((r) => r.name).sort()).toEqual(["Ada", "Grace"]);
+    expect(result.rows.every((r) => r.status === "active")).toBe(true);
+  });
+
+  test("a facet's shape (payload.filters, op:in) returns only matching rows", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string; readonly status: string }[];
+    }>(
+      LIST_QN,
+      { limit: 50, filters: [{ field: "status", op: "in", value: ["inactive"] }] },
+      TestUsers.admin,
+    );
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]?.name).toBe("Bob");
+  });
+
+  test("no filter — all rows return (control: proves the filter tests above actually narrow something)", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string; readonly status: string }[];
+    }>(LIST_QN, { limit: 50 }, TestUsers.admin);
+
+    expect(result.rows).toHaveLength(3);
+  });
+});

package/src/engine/boot-validator/projection-list-screens.ts

@@ -71,6 +71,45 @@ function validateOneProjectionListScreen(
   if ((searchActive || sortActive) && screen.defaultSort === undefined) {
     throw new Error(`${prefix}: defaultSort required when search or sort is active`);
   }
+
+  validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
+  validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+}
+
+// filter (fw#2224) sends `payload.filter` — same 422 footgun as facets below
+// if the handler's schema doesn't accept it.
+function validateProjectionListFilterSchemaAcceptance(
+  prefix: string,
+  screen: ProjectionListScreenDefinition,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  // skip: no filter declared, or the schema already accepts it — nothing to reject.
+  if (screen.filter === undefined || schemaAccepts(schema, "filter")) return;
+  throw new Error(
+    `${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
+      `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+      `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
+  );
+}
+
+// facets (fw#2224) send `payload.filters` — same failure mode as search/sort
+// (fw#2165): definePagedQueryHandler doesn't auto-merge params into the
+// handler's own Zod schema, so a declared facet would 422 on every query
+// unless the author added `filters` themselves.
+function validateProjectionListFacetsSchemaAcceptance(
+  prefix: string,
+  screen: ProjectionListScreenDefinition,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  // skip: no facets declared — nothing to reject.
+  if (screen.facets === undefined || screen.facets.length === 0) return;
+  // skip: the schema already accepts filters — nothing to reject.
+  if (schemaAccepts(schema, "filters")) return;
+  throw new Error(
+    `${prefix}: declares facets but query "${screen.query}" has no "filters" parameter in its ` +
+      `Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), ` +
+      `value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
+  );
 }
 
 export function validateProjectionListScreens(features: readonly FeatureDefinition[]): void {

package/src/engine/boot-validator/screens.ts

@@ -303,6 +303,39 @@ function validateScreenNavTarget(
   }
 }
 
+// kind:"drawer" resolves same-feature only — unlike navigate/redirect,
+// which the runtime router resolves app-wide (see the comment on
+// validateScreens below), the drawer mounts the target inline using this
+// feature's schema, so a cross-feature reference could never actually
+// render. Two distinct failure messages: dangling reference vs. wrong
+// screen type (fw#2225).
+function validateToolbarDrawerAction(
+  featureName: string,
+  screenId: string,
+  screenKind: string,
+  action: Extract<ToolbarAction, { kind: "drawer" }>,
+  screens: FeatureDefinition["screens"],
+): void {
+  const target = screens[action.screen];
+  if (target === undefined) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) toolbarAction "${action.id}" ` +
+        `drawer-target "${action.screen}" does not resolve to a registered screen in this feature. ` +
+        `kind:"drawer" only resolves same-feature screens (unlike kind:"navigate", which can target ` +
+        `screens in any feature) — the drawer mounts the target inline using this feature's schema. ` +
+        `Known screens in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`,
+    );
+  }
+  if (target.type !== "actionForm") {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) toolbarAction "${action.id}" ` +
+        `drawer-target "${action.screen}" is a "${target.type}" screen, not an actionForm. ` +
+        `kind:"drawer" mounts an actionForm inside a Drawer widget — point "screen" at an ` +
+        `actionForm screen, or use kind:"navigate" for a full-page target.`,
+    );
+  }
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -351,6 +384,52 @@ export function validateScreens(
       for (const col of screen.columns) {
         validateColumnRendererForm(feature.name, screenId, normalizeListColumn(col));
       }
+      // Screen filter (fw#2224) — field existence can't be checked without
+      // an entity (columns aren't a complete field inventory of the
+      // underlying query), so only pin the structure: "in" requires an
+      // array. Field validity is documented in the PR body.
+      if (
+        screen.filter !== undefined &&
+        screen.filter.op === "in" &&
+        !Array.isArray(screen.filter.value)
+      ) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList) filter.op "in" requires ` +
+            `filter.value to be a readonly array.`,
+        );
+      }
+      // Facets (fw#2224) — unlike filter, a field inventory IS available
+      // here: the declared columns. A facet on a field with no column is
+      // almost always a typo (the user never sees the field anywhere), so
+      // this is hard-checked rather than just documented.
+      if (screen.facets !== undefined) {
+        const columnFieldNames = new Set(
+          screen.columns.map((col) => normalizeListColumn(col).field),
+        );
+        const seenFacetFields = new Set<string>();
+        for (const facet of screen.facets) {
+          if (seenFacetFields.has(facet.field)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) declares facet ` +
+                `"${facet.field}" more than once.`,
+            );
+          }
+          seenFacetFields.add(facet.field);
+          if (!columnFieldNames.has(facet.field)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet references field ` +
+                `"${facet.field}" which is not a declared column. Known columns: ` +
+                `${[...columnFieldNames].sort().join(", ")}`,
+            );
+          }
+          if (facet.type === "select" && facet.options.length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet "${facet.field}" ` +
+                `(type "select") has an empty options list — declare at least one option.`,
+            );
+          }
+        }
+      }
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
           if (action.kind === "navigate") {
@@ -374,6 +453,22 @@ export function validateScreens(
         }
         validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
       }
+      // Only drawer-kind is validated here — navigate/writeHandler toolbarActions
+      // on projectionList have no boot check yet (pre-existing gap, out of
+      // scope for fw#2225).
+      if (screen.toolbarActions !== undefined) {
+        for (const action of screen.toolbarActions) {
+          if (action.kind === "drawer") {
+            validateToolbarDrawerAction(
+              feature.name,
+              screenId,
+              "projectionList",
+              action,
+              feature.screens,
+            );
+          }
+        }
+      }
       continue;
     }
 
@@ -923,6 +1018,14 @@ export function validateScreens(
                   `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
               );
             }
+          } else if (action.kind === "drawer") {
+            validateToolbarDrawerAction(
+              feature.name,
+              screenId,
+              "entityList",
+              action,
+              feature.screens,
+            );
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(

package/src/engine/build-config-feature-schema.ts

@@ -109,6 +109,13 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
   const masked = collectMaskedKeys(registry);
   if (masked.length === 0) return { screens: [], navs: [] };
 
+  // Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
+  // (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+  const declaredTranslationKeys = new Set<string>();
+  for (const f of registry.features.values()) {
+    for (const key of Object.keys(f.translations ?? {})) declaredTranslationKeys.add(key);
+  }
+
   const screens: ScreenDefinition[] = [];
   const navs: NavDefinition[] = [];
 
@@ -131,7 +138,7 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
       const access = rolesToAccess(group.flatMap((v) => v.roles));
       const shortId = `${feature}-${scope}`;
 
-      screens.push(buildScreen(shortId, scope, feature, ordered, access));
+      screens.push(buildScreen(shortId, scope, feature, ordered, access, declaredTranslationKeys));
       navs.push({
         id: shortId,
         label: `${feature}.settings`,
@@ -201,6 +208,7 @@ function buildScreen(
   feature: string,
   keys: readonly MaskedKey[],
   access: AccessRule,
+  declaredTranslationKeys: ReadonlySet<string>,
 ): ConfigEditScreenDefinition {
   const configKeys: Record<string, string> = {};
   const fields: Record<string, FieldDefinition> = {};
@@ -226,8 +234,11 @@ function buildScreen(
     // mask is the visibility gate, so collectMaskedKeys guarantees it here.
     if (k.def.mask) fieldLabels[id] = k.def.mask.title;
   }
+  // translate() echoes an undeclared key, so an ungated description would render raw.
+  const descriptionKey = `${feature}.settings.description`;
   const section: EditFieldsSection = {
     title: `${feature}.settings`,
+    ...(declaredTranslationKeys.has(descriptionKey) && { description: descriptionKey }),
     fields: keys.map(fieldId),
   };
   return {
@@ -237,7 +248,7 @@ function buildScreen(
     configKeys,
     fields,
     fieldLabels,
-    layout: { sections: [section] },
+    layout: { sections: [section], width: "full" },
     access,
   };
 }

package/src/engine/field-helpers.ts

@@ -20,6 +20,10 @@ export const DEFAULT_CURRENCIES = [
   "INR",
 ] as const;
 
+// --- Locale ---
+
+export const DEFAULT_LOCALES = ["de", "en"] as const;
+
 export function isFileField(field: FieldDefinition | undefined): field is AnyFileFieldDef {
   if (!field) return false;
   return (

package/src/engine/index.ts

@@ -424,7 +424,7 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "./types";
-export { DEFAULT_CURRENCIES, HookPhases } from "./types";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases } from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
   PipelineBuildCtx,

package/src/engine/types/index.ts

@@ -269,6 +269,7 @@ export type {
   FieldRenderer,
   FormatSpec,
   ListColumnSpec,
+  ListFacetSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
@@ -299,7 +300,7 @@ export type {
   LifecycleHookType,
   OnDeleteStrategy,
 } from "../constants";
-export { DEFAULT_CURRENCIES, isFileField } from "../field-helpers";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers";
 export { resolveName, withResponseData } from "../handler-helpers";
 export { HookPhases } from "../hook-helpers";
 export {

package/src/i18n/required-surface-keys.ts

@@ -106,6 +106,9 @@ function pushToolbarActionKeys(out: Set<string>, action: ToolbarAction): void {
     pushKey(out, action.confirm);
     pushKey(out, action.confirmLabel);
   }
+  // drawer-kind carries no confirm/confirmLabel — action.label (the
+  // toolbar button AND the Drawer title, see ToolbarDrawerHost) is
+  // already pushed above.
 }
 
 export function requiredKeysFromScreen(

package/src/ui-types/index.ts

@@ -80,6 +80,7 @@ export type {
   FieldRenderer,
   FormWidth,
   ListColumnSpec,
+  ListFacetSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,