@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/engine/boot-validator/{screens-nav.ts → screens.ts}

@@ -1,16 +1,26 @@
+// Screen validation, including the dashboard-panel sub-validators.
+// Dashboard stays here (not a separate dashboard.ts) — validateScreens
+// calls validateDashboardScreen and the dashboard validators call back
+// into validateColumnRendererForm, splitting them would create a
+// same-folder require cycle.
+
 import { rowMetaFieldNames } from "../../db/table-builder";
-import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import type { FeatureDefinition } from "../types";
 import type {
+  DashboardCustomPanel,
+  DashboardFilterDefinition,
+  DashboardPanelDefinition,
+  DashboardScreenDefinition,
+  DashboardStatGroupPanel,
   FieldCondition,
   RowAction,
   RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
 } from "../types/screen";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
 //
@@ -141,6 +151,65 @@ export function validateScreens(
       continue;
     }
 
+    if (screen.type === "projectionList") {
+      // Query-getrieben, keine Entity → nur query + columns prüfen (die
+      // Column-Felder können nicht gegen eine Entity gecheckt werden; sie
+      // werden zur Render-Zeit gegen die Projection-Rows aufgelöst).
+      if (!screen.query || typeof screen.query !== "string") {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList) has empty or non-string query.`,
+        );
+      }
+      if (screen.columns.length === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList) has an empty columns list — ` +
+            `declare at least one column.`,
+        );
+      }
+      for (const col of screen.columns) {
+        validateColumnRendererForm(feature.name, screenId, normalizeListColumn(col));
+      }
+      continue;
+    }
+
+    if (screen.type === "projectionDetail") {
+      // Query-getrieben wie projectionList, aber Single-Row + Layout statt
+      // Columns. Kein Entity-Check möglich — Felder werden render-seitig
+      // gegen die Query-Response aufgelöst, nicht gegen eine Entity.
+      if (!screen.query || typeof screen.query !== "string") {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query.`,
+        );
+      }
+      if (screen.layout.sections.length === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has an empty sections list — ` +
+            `declare at least one section.`,
+        );
+      }
+      for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) extension section ` +
+              `"${section.title}" is not supported — projectionDetail has no entity for an extension ` +
+              `section to persist against.`,
+          );
+        }
+        if (section.fields.length === 0) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has a section "${section.title}" ` +
+              `with zero fields — drop the section or add fields to it.`,
+          );
+        }
+      }
+      continue;
+    }
+
+    if (screen.type === "dashboard") {
+      validateDashboardScreen(feature.name, screenId, screen);
+      continue;
+    }
+
     if (screen.type === "configEdit") {
       // configEdit: layout/fields wie actionForm validieren, plus
       // Cross-Check dass jeder qualifizierte Config-Key registriert
@@ -613,6 +682,148 @@ export function validateScreens(
   }
 }
 
+// Panel-getrieben, keine Entity — Struktur-Checks (eindeutige Panel-Ids,
+// non-empty Queries/Columns/valueField); die Query-Contracts (Stat-Record,
+// Points-Envelope, Paged-Rows) werden zur Render-Zeit aufgelöst.
+function validateDashboardScreen(
+  featureName: string,
+  screenId: string,
+  screen: DashboardScreenDefinition,
+): void {
+  if (screen.panels.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) has an empty panels list — ` +
+        `declare at least one panel.`,
+    );
+  }
+  const panelIds = new Set<string>();
+  const addPanelId = (id: string, context: string): void => {
+    if (panelIds.has(id)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${id}" (${context}).`,
+      );
+    }
+    panelIds.add(id);
+  };
+
+  for (const panel of screen.panels) {
+    addPanelId(panel.id, panel.kind);
+    if (panel.kind === "stat-group") {
+      validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelId);
+    } else if (panel.kind === "custom") {
+      validateDashboardCustomPanel(featureName, screenId, panel);
+    } else {
+      validateDashboardQueryPanel(featureName, screenId, panel);
+    }
+  }
+
+  if (screen.filter !== undefined) {
+    validateDashboardFilterDefinition(featureName, screenId, screen.filter);
+  }
+}
+
+function validateDashboardStatGroupPanel(
+  featureName: string,
+  screenId: string,
+  panel: DashboardStatGroupPanel,
+  addPanelId: (id: string, context: string) => void,
+): void {
+  if (panel.stats.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" has an empty stats list.`,
+    );
+  }
+  for (const stat of panel.stats) {
+    addPanelId(stat.id, "stat-group child");
+    if (!stat.query || typeof stat.query !== "string") {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty or non-string query.`,
+      );
+    }
+    if (stat.valueField.length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField.`,
+      );
+    }
+  }
+}
+
+function validateDashboardCustomPanel(
+  featureName: string,
+  screenId: string,
+  panel: DashboardCustomPanel,
+): void {
+  if (panel.component.react === undefined && panel.component.native === undefined) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) custom-panel "${panel.id}" has no component — ` +
+        `declare a react/native component marker.`,
+    );
+  }
+}
+
+function validateDashboardQueryPanel(
+  featureName: string,
+  screenId: string,
+  panel: Exclude<DashboardPanelDefinition, DashboardStatGroupPanel | DashboardCustomPanel>,
+): void {
+  if (!panel.query || typeof panel.query !== "string") {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query.`,
+    );
+  }
+  if (panel.kind === "stat" && panel.valueField.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`,
+    );
+  }
+  if (panel.kind === "list") {
+    if (panel.columns.length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list.`,
+      );
+    }
+    for (const col of panel.columns) {
+      validateColumnRendererForm(featureName, screenId, normalizeListColumn(col));
+    }
+  }
+}
+
+function validateDashboardFilterDefinition(
+  featureName: string,
+  screenId: string,
+  filter: DashboardFilterDefinition,
+): void {
+  if (filter.id.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty id.`,
+    );
+  }
+  if (filter.label.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty label.`,
+    );
+  }
+  const hasOptions = filter.options !== undefined;
+  const hasOptionsQuery = filter.optionsQuery !== undefined;
+  if (hasOptions === hasOptionsQuery) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter must set exactly one of ` +
+        `options/optionsQuery.`,
+    );
+  }
+  if (hasOptions && (filter.options?.length ?? 0) === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.options is empty — ` +
+        `declare at least one option or use optionsQuery instead.`,
+    );
+  }
+  if (hasOptionsQuery && filter.optionsQuery?.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty.`,
+    );
+  }
+}
+
 // Form-check für ListColumn-Renderer in der PlatformComponent-Form
 // (`{ react: { __component: "Name" } }`). Der Server kennt die client-
 // seitige columnRenderers-Map nicht — also nur prüfen ob die Struktur
@@ -678,13 +889,6 @@ export function buildUnknownFieldMessage(
   );
 }
 
-// --- Nav validation ---
-//
-// The boot-validator runs BEFORE createRegistry builds the final maps, so we
-// pre-build the qualified name sets for screens + navs here. `qualifyEntityName`
-// is the shared helper with the registry — changing the qualification rule
-// in one place flows through both ingest paths.
-
 export function collectScreenQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
   for (const f of features) {
@@ -731,184 +935,3 @@ export function collectScreensByShortId(
   }
   return map;
 }
-
-// Sammelt alle qualifizierten Write-Handler-QNs (`<feature>:write:<short>`).
-// Wird vom actionForm-Screen-Validator genutzt um zu prüfen ob der
-// im Schema deklarierte handler tatsächlich registriert ist —
-// Tippfehler/umbenannte Handler fallen sonst erst zur Laufzeit auf.
-export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
-  const set = new Set<string>();
-  for (const f of features) {
-    for (const handlerName of Object.keys(f.writeHandlers)) {
-      set.add(qualifyEntityName(f.name, "write", handlerName));
-    }
-  }
-  return set;
-}
-
-export function collectNavQns(
-  features: readonly FeatureDefinition[],
-): Map<string, NavDefinition & { readonly featureName: string }> {
-  const map = new Map<string, NavDefinition & { readonly featureName: string }>();
-  for (const f of features) {
-    for (const [navId, navDef] of Object.entries(f.navs)) {
-      const qualified = qualifyEntityName(f.name, "nav", navId);
-      map.set(qualified, { ...navDef, featureName: f.name });
-    }
-  }
-  return map;
-}
-
-// Per-feature ref validation: screen + parent refs point at real QNs. Cycle
-// detection runs once globally afterwards (it's cheaper to do a single DFS
-// over the merged graph than restart it per feature).
-export function validateNavs(
-  feature: FeatureDefinition,
-  allScreenQns: ReadonlySet<string>,
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
-): void {
-  for (const [navId, navDef] of Object.entries(feature.navs)) {
-    if (navDef.screen !== undefined && !allScreenQns.has(navDef.screen)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references screen "${navDef.screen}" ` +
-          `which is not registered. Expected a qualified name of the form ` +
-          `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
-      );
-    }
-    if (navDef.parent !== undefined && !allNavQns.has(navDef.parent)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references parent "${navDef.parent}" ` +
-          `which is not a registered nav entry. Expected a qualified name of the form ` +
-          `"<feature>:nav:<id>".`,
-      );
-    }
-    if (navDef.workspaces !== undefined) {
-      for (const wsQn of navDef.workspaces) {
-        if (!allWorkspaceQns.has(wsQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Nav entry "${navId}" self-assigns to workspace "${wsQn}" ` +
-              `which is not registered. Expected a qualified name of the form ` +
-              `"<feature>:workspace:<id>" pointing at an r.workspace() declaration.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-// Walks parent-refs across ALL nav entries (cross-feature). A cycle here
-// would crash client-side tree assembly — easier to fail loud at boot than
-// to debug a React "Maximum update depth exceeded" stack trace.
-export function validateNavCycles(
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  const visited = new Set<string>();
-  const stack = new Set<string>();
-
-  function visit(qualified: string, path: string[]): void {
-    if (stack.has(qualified)) {
-      throw new Error(
-        `[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`,
-      );
-    }
-    // skip: already visited — cycle-detection only needs to traverse each
-    // node once, and the `stack` check above catches any actual cycles
-    // reached via a different path.
-    if (visited.has(qualified)) return;
-    visited.add(qualified);
-    stack.add(qualified);
-    const navDef = allNavQns.get(qualified);
-    if (navDef?.parent) {
-      visit(navDef.parent, [...path, qualified]);
-    }
-    stack.delete(qualified);
-  }
-
-  for (const qualified of allNavQns.keys()) {
-    visit(qualified, []);
-  }
-}
-
-// Roles we recognise at boot time. The framework has no explicit
-// role-registry (r.defineRoles is a type helper only), so we synthesise
-// one from every handler-access rule plus the "all"/"system" built-ins.
-export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string> {
-  const roles = new Set<string>(["all", "system"]);
-  for (const f of features) {
-    for (const def of Object.values(f.writeHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-    for (const def of Object.values(f.queryHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-  }
-  return roles;
-}
-
-// --- Workspace validation ---
-//
-// Per-app workspace registry, built once up front. Carries `featureName`
-// alongside the definition so error messages can point at the offending
-// feature without a parallel reverse index.
-
-export function collectWorkspaceQns(
-  features: readonly FeatureDefinition[],
-): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
-  const map = new Map<string, WorkspaceDefinition & { readonly featureName: string }>();
-  for (const f of features) {
-    for (const [wsId, wsDef] of Object.entries(f.workspaces)) {
-      const qualified = qualifyEntityName(f.name, "workspace", wsId);
-      map.set(qualified, { ...wsDef, featureName: f.name });
-    }
-  }
-  return map;
-}
-
-export function validateWorkspaces(
-  feature: FeatureDefinition,
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  for (const [wsId, wsDef] of Object.entries(feature.workspaces)) {
-    if (wsDef.nav !== undefined) {
-      for (const navQn of wsDef.nav) {
-        // Settings-Hub audience navs are generated post-boot (buildAppSchema), never via r.nav() — exempt so an inline-placement reference doesn't trip the boot validator.
-        if (SETTINGS_HUB_AUDIENCE_NAV_QN_SET.has(navQn)) continue;
-        if (!allNavQns.has(navQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Workspace "${wsId}" references nav "${navQn}" ` +
-              `which is not registered. Expected a qualified name of the form ` +
-              `"<feature>:nav:<id>" pointing at an r.nav() declaration.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
-  SETTINGS_HUB_AUDIENCE_NAV_QNS,
-);
-
-// Single-default rule across the entire app. Mirrors how createApp validates
-// roles up front — a second `default: true` is a configuration error, not a
-// runtime fallback. Apps without any default fall back to "first workspace
-// the user has access to" at render time (handled by shellWorkspaces).
-export function validateDefaultWorkspaceUniqueness(
-  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
-): void {
-  const defaults: string[] = [];
-  for (const [qn, ws] of allWorkspaceQns) {
-    if (ws.default === true) defaults.push(qn);
-  }
-  if (defaults.length > 1) {
-    throw new Error(
-      `[Kumiko Workspaces] Multiple workspaces declare default: true — ` +
-        `${defaults.join(", ")}. At most one workspace per app may be the default.`,
-    );
-  }
-}

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

@@ -0,0 +1,68 @@
+// Workspace validation.
+
+import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+
+// --- Workspace validation ---
+//
+// Per-app workspace registry, built once up front. Carries `featureName`
+// alongside the definition so error messages can point at the offending
+// feature without a parallel reverse index.
+
+export function collectWorkspaceQns(
+  features: readonly FeatureDefinition[],
+): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
+  const map = new Map<string, WorkspaceDefinition & { readonly featureName: string }>();
+  for (const f of features) {
+    for (const [wsId, wsDef] of Object.entries(f.workspaces)) {
+      const qualified = qualifyEntityName(f.name, "workspace", wsId);
+      map.set(qualified, { ...wsDef, featureName: f.name });
+    }
+  }
+  return map;
+}
+
+export function validateWorkspaces(
+  feature: FeatureDefinition,
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  for (const [wsId, wsDef] of Object.entries(feature.workspaces)) {
+    if (wsDef.nav !== undefined) {
+      for (const navQn of wsDef.nav) {
+        // Settings-Hub audience navs are generated post-boot (buildAppSchema), never via r.nav() — exempt so an inline-placement reference doesn't trip the boot validator.
+        if (SETTINGS_HUB_AUDIENCE_NAV_QN_SET.has(navQn)) continue;
+        if (!allNavQns.has(navQn)) {
+          throw new Error(
+            `[Feature ${feature.name}] Workspace "${wsId}" references nav "${navQn}" ` +
+              `which is not registered. Expected a qualified name of the form ` +
+              `"<feature>:nav:<id>" pointing at an r.nav() declaration.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
+  SETTINGS_HUB_AUDIENCE_NAV_QNS,
+);
+
+// Single-default rule across the entire app. Mirrors how createApp validates
+// roles up front — a second `default: true` is a configuration error, not a
+// runtime fallback. Apps without any default fall back to "first workspace
+// the user has access to" at render time (handled by shellWorkspaces).
+export function validateDefaultWorkspaceUniqueness(
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): void {
+  const defaults: string[] = [];
+  for (const [qn, ws] of allWorkspaceQns) {
+    if (ws.default === true) defaults.push(qn);
+  }
+  if (defaults.length > 1) {
+    throw new Error(
+      `[Kumiko Workspaces] Multiple workspaces declare default: true — ` +
+        `${defaults.join(", ")}. At most one workspace per app may be the default.`,
+    );
+  }
+}

package/src/engine/build-app-schema.ts

@@ -17,6 +17,8 @@
 //              sind plain literals)
 //   Nav:       verbatim (NavDefinition ist nur strings + literals)
 //   Workspace: verbatim definition + getWorkspaceNavs() von der Registry
+//   Translations: verbatim feature.translations (raw r.translations keys,
+//                 unfiltered — see FeatureSchema.translations doc)
 //
 // Feature-Toggles: BISHER NICHT GEFILTERT. Wenn ein Feature über die
 // feature-toggles-bundled-feature global deaktiviert ist, erscheint es
@@ -49,6 +51,12 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
       entities: projectEntities(feature.entities ?? {}),
       screens: Object.values(feature.screens),
       ...(navs.length > 0 && { navs }),
+      // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
+      // doc for why this must NOT go through registry.getAllTranslations()
+      // (double-prefixes features that already qualify their own keys).
+      ...(Object.keys(feature.translations ?? {}).length > 0 && {
+        translations: feature.translations,
+      }),
     };
     features.push(featureSchema);
   }
@@ -340,9 +348,17 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   // filterable steuert die Faceted-Filter-Dropdowns im Renderer (select/
   // boolean) — muss daher ins Client-Schema.
   if (typeof def["filterable"] === "boolean") out["filterable"] = def["filterable"];
+  if (typeof def["searchable"] === "boolean") out["searchable"] = def["searchable"];
   if (isLiteral(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];
+  // Reference: entity-Target + labelField + multiple müssen zum Renderer.
+  // Der ReferenceInput baut die Options-Query aus refEntity/refFeature und
+  // resolved das Label über labelField — ohne diese Properties fällt das
+  // Dropdown leer aus (QN wird `<feature>:query::list` → 404).
+  if (typeof def["entity"] === "string") out["entity"] = def["entity"];
+  if (typeof def["labelField"] === "string") out["labelField"] = def["labelField"];
+  if (typeof def["multiple"] === "boolean") out["multiple"] = def["multiple"];
   return out as FieldDefinition; // @cast-boundary schema-walk
 }
 

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

@@ -23,6 +23,7 @@ import {
   createSelectField,
   createTextField,
 } from "./factories";
+import { isKebabSegment } from "./qualified-name";
 import type { ConfigKeyDefinition } from "./types/config";
 import type { Registry } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
@@ -56,6 +57,11 @@ export type ConfigFeatureSchema = {
 
 // Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
 const SCOPE_ORDER: Record<ConfigScope, number> = { system: 10, tenant: 20, user: 30 };
+const SCOPE_ICON: Record<ConfigScope, string> = {
+  system: "shield",
+  tenant: "building",
+  user: "user",
+};
 const SCOPES_BROAD_TO_DEEP: readonly ConfigScope[] = ["system", "tenant", "user"];
 
 const audienceNavShortId = (scope: ConfigScope): string => `audience-${scope}`;
@@ -85,7 +91,14 @@ const MACHINE_WRITE_ROLE = "system" as const;
 
 type MaskedKey = {
   readonly qn: string;
+  // Effective group this key is bucketed under for the Settings-Hub —
+  // `def.group` if set, else `ownerFeature`. This is what screen/nav
+  // generation groups by.
   readonly feature: string;
+  // The feature that actually declared this key (always derived from `qn`).
+  // Needed to disambiguate field ids when `feature !== ownerFeature` (a
+  // cross-feature `group`) and for collision error messages.
+  readonly ownerFeature: string;
   readonly shortKey: string;
   readonly def: ConfigKeyDefinition;
 };
@@ -107,6 +120,7 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
     navs.push({
       id: audienceNavShortId(scope),
       label: `config.settings.${scope}`,
+      icon: SCOPE_ICON[scope],
       order: SCOPE_ORDER[scope],
       access: rolesToAccess(visible.flatMap((v) => v.roles)),
     });
@@ -123,6 +137,7 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
         label: `${feature}.settings`,
         parent: audienceNavShortId(scope),
         screen: shortId,
+        icon: ordered[0]?.def.mask?.icon ?? "settings",
         order: minMaskOrder(ordered),
         access,
       });
@@ -190,15 +205,30 @@ function buildScreen(
   const configKeys: Record<string, string> = {};
   const fields: Record<string, FieldDefinition> = {};
   const fieldLabels: Record<string, string> = {};
+  // Field id collapses to the plain shortKey when the key stays in its own
+  // feature's group (100% of today's apps — byte-identical output). Only a
+  // cross-feature `group` (feature !== ownerFeature) needs the owner prefix,
+  // to keep two features sharing a group from clobbering the same shortKey.
+  const fieldId = (k: MaskedKey): string =>
+    k.feature === k.ownerFeature ? k.shortKey : `${k.ownerFeature}-${k.shortKey}`;
+  const seenFieldIds = new Map<string, string>();
   for (const k of keys) {
-    configKeys[k.shortKey] = k.qn;
-    fields[k.shortKey] = deriveField(k.def);
+    const id = fieldId(k);
+    const prevQn = seenFieldIds.get(id);
+    if (prevQn !== undefined) {
+      throw new Error(
+        `[Settings-Hub] group "${feature}" scope "${scope}": config keys "${prevQn}" and "${k.qn}" both resolve to field id "${id}" — rename one key or its group.`,
+      );
+    }
+    seenFieldIds.set(id, k.qn);
+    configKeys[id] = k.qn;
+    fields[id] = deriveField(k.def);
     // mask is the visibility gate, so collectMaskedKeys guarantees it here.
-    if (k.def.mask) fieldLabels[k.shortKey] = k.def.mask.title;
+    if (k.def.mask) fieldLabels[id] = k.def.mask.title;
   }
   const section: EditFieldsSection = {
     title: `${feature}.settings`,
-    fields: keys.map((k) => k.shortKey),
+    fields: keys.map(fieldId),
   };
   return {
     id: shortId,
@@ -230,14 +260,21 @@ function deriveField(def: ConfigKeyDefinition): FieldDefinition {
 function collectMaskedKeys(registry: Registry): MaskedKey[] {
   const out: MaskedKey[] = [];
   for (const [qn, def] of registry.getAllConfigKeys()) {
+    const sep = qn.indexOf(":config:");
+    if (sep === -1) continue;
+    const ownerFeature = qn.slice(0, sep);
+    if (def.group !== undefined && !isKebabSegment(def.group)) {
+      throw new Error(
+        `[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`,
+      );
+    }
     // computed keys derive their value — there is no row to set, so a
     // configEdit screen could not write them. Skip even when masked.
     if (def.mask === undefined || def.computed !== undefined) continue;
-    const sep = qn.indexOf(":config:");
-    if (sep === -1) continue;
     out.push({
       qn,
-      feature: qn.slice(0, sep),
+      feature: def.group ?? ownerFeature,
+      ownerFeature,
       shortKey: qn.slice(sep + ":config:".length),
       def,
     });