@cosmicdrift/kumiko-framework 0.208.1 → 0.208.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.208.1",
+  "version": "0.208.3",
   "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.1",
+    "@cosmicdrift/kumiko-types": "0.208.3",
     "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.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.208.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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/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/define-handler.ts

@@ -1,3 +1,4 @@
+import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
 import type { ZodType, z } from "zod";
 import type { ContainsSecret } from "../secrets/types";
 import { runPipeline } from "./run-pipeline";
@@ -116,3 +117,68 @@ export function defineQueryHandler<
 ): QueryHandlerDefinition<TName, TSchema, TResult, TMap> {
   return def;
 }
+
+// Runtime marker set only by definePagedQueryHandler. A plain
+// defineQueryHandler-built object never carries it. Kept as a type-level
+// signal (fw#2216) even though no validator gates on it — QueryHandlerDef
+// has no output schema, so a boot check can't distinguish "returns
+// PagedRows" from "doesn't" without running the handler; the actual
+// enforcement is a runtime shape guard in the renderer (kumiko-screen.tsx).
+//
+// A string key, not a Symbol: bundled-features imports this module through
+// the package's "@cosmicdrift/kumiko-framework/engine" subpath (symlinked
+// node_modules entry) via a different resolution route than a same-package
+// relative import — two routes to the same file that can end up as two
+// separate module instances under bundler symlink handling. A Symbol()
+// evaluated twice would produce two unequal brands; a string literal doesn't
+// have that failure mode.
+// Exported (not just the predicate) so feature-entity-handlers.ts's
+// queryHandler() registrar — which rebuilds a fresh QueryHandlerDef from an
+// explicit field whitelist rather than spreading `def` — can carry the
+// brand through into the stored registry entry.
+export const PAGED_QUERY_HANDLER_BRAND = "__kumikoPagedQueryHandler";
+
+export function isPagedQueryHandler(def: object): boolean {
+  // @cast-boundary brand-probe — reading an internal marker key off an
+  // otherwise-typed handler definition; the property may legitimately be
+  // absent, which is exactly the case this function distinguishes.
+  return (def as Record<string, unknown>)[PAGED_QUERY_HANDLER_BRAND] === true;
+}
+
+export type PagedQueryHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TRow = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap> & {
+  readonly [PAGED_QUERY_HANDLER_BRAND]: true;
+};
+
+// A projectionList screen's query must resolve to { rows, nextCursor, total? }
+// (CursorResult<T>) — the renderer used to read rowsQuery.data?.rows and
+// silently show an empty list otherwise (fw#2216: session-list); the
+// renderer now guards against a malformed shape at runtime instead. Use this
+// instead of defineQueryHandler for any query wired to a projectionList
+// screen's `query` so the contract is documented at the definition site.
+//
+// Deliberately does NOT merge cursor/limit/sort/search into the input
+// schema — that would change sortable/paginated derivation for existing
+// screens (a behavior change, not a wrapper change). Callers that want
+// those params add them to `schema` themselves.
+export function definePagedQueryHandler<
+  const TName extends string,
+  TSchema extends ZodType,
+  TRow = unknown,
+  TMap extends object = KumikoEventTypeMap,
+>(
+  def: QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap>,
+  // R6: phantom rest-param — see defineWriteHandler. CursorResult<TRow> wraps
+  // TRow in `rows`, so ContainsSecret recurses through the array element.
+  ..._noSecretInResponse: true extends ContainsSecret<CursorResult<TRow>>
+    ? [
+        secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field.",
+      ]
+    : []
+): PagedQueryHandlerDefinition<TName, TSchema, TRow, TMap> {
+  return { ...def, [PAGED_QUERY_HANDLER_BRAND]: true };
+}

package/src/engine/entity-handlers.ts

@@ -9,6 +9,7 @@ import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-s
 import { buildEntityTable, type EntityTable } from "../db/table-builder";
 import { createTenantDb, type TenantDb } from "../db/tenant-db";
 import { assertUnreachable } from "../utils";
+import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type {
   AccessRule,
@@ -366,6 +367,12 @@ export function defineEntityQueryHandler(
     schema,
     handler,
     ...(options?.access && { access: options.access }),
+    // The "list" verb's executor.list() always returns { rows, nextCursor,
+    // total? } (see the handler body above) — brand it so the definition
+    // site documents the PagedRows contract without needing
+    // definePagedQueryHandler on top. The "detail" verb returns a single
+    // row/null, never this shape.
+    ...(verb === "list" && { [PAGED_QUERY_HANDLER_BRAND]: true }),
   };
 }
 

package/src/engine/feature-entity-handlers.ts

@@ -1,9 +1,11 @@
 import type { ZodType, z } from "zod";
 import { toTableName } from "../db/table-builder";
-import type {
-  QueryHandlerDefinition,
-  StreamHandlerDefinition,
-  WriteHandlerDefinition,
+import {
+  isPagedQueryHandler,
+  PAGED_QUERY_HANDLER_BRAND,
+  type QueryHandlerDefinition,
+  type StreamHandlerDefinition,
+  type WriteHandlerDefinition,
 } from "./define-handler";
 import type { RegisterEntityCrudOptions } from "./entity-handlers";
 import { registerEntityCrud } from "./entity-handlers";
@@ -153,6 +155,9 @@ export function buildEntityHandlerMethods<TName extends string>(
           handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
           ...(def.access && { access: def.access }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          // Carry the definePagedQueryHandler brand through — this rebuild
+          // drops any field not explicitly listed.
+          ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
         };
         tryMapEntity(state, name, def.name);
         return { name: def.name };

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

@@ -41,12 +41,18 @@ export { createApp } from "./create-app";
 export { crossTenantOverrideDenied } from "./cross-tenant";
 export { defineFeature } from "./define-feature";
 export type {
+  PagedQueryHandlerDefinition,
   QueryHandlerDefinition,
   StreamHandlerDefinition,
   WriteHandlerDefinition,
   WriteHandlerInput,
 } from "./define-handler";
-export { defineQueryHandler, defineWriteHandler } from "./define-handler";
+export {
+  definePagedQueryHandler,
+  defineQueryHandler,
+  defineWriteHandler,
+  isPagedQueryHandler,
+} from "./define-handler";
 export { defineRoles } from "./define-roles";
 export { defineStep, getStep, listStepKinds } from "./define-step";
 export type { WorkflowDefinition, WorkflowInput, WorkflowTrigger } from "./define-workflow";
@@ -418,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

@@ -299,7 +299,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 {