@cosmicdrift/kumiko-framework 0.325.2 → 0.326.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.325.2",
+  "version": "0.326.1",
   "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>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.325.2",
-    "@cosmicdrift/kumiko-types": "0.325.2",
+    "@cosmicdrift/kumiko-http": "0.326.1",
+    "@cosmicdrift/kumiko-types": "0.326.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.325.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.326.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,395 @@
+import { describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { requiredKeysFromScreen } from "../../i18n/required-surface-keys";
+import { SETTINGS_HUB_I18N } from "../../i18n/settings-hub-keys";
+import { validateBoot } from "../boot-validator";
+import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE } from "../build-config-feature-schema";
+import { access, createSystemConfig, createTenantConfig } from "../config-helpers";
+import { defineFeature } from "../define-feature";
+import { SELECTED_EXTENSIONS_QUERY } from "../extension-selector-plugins";
+import { createRegistry } from "../registry";
+import type {
+  ConfigEditScreenDefinition,
+  FeatureDefinition,
+  ScreenDefinition,
+  SecretsEditScreenDefinition,
+} from "../types";
+
+const TENANT_ADMIN_WRITE = access.roles("TenantAdmin", "Admin");
+
+function secretsFeature() {
+  return defineFeature("secrets", (r) => {
+    r.writeHandler(
+      "set",
+      z.object({ key: z.string(), value: z.string() }),
+      async () => ({ isSuccess: true, data: null }),
+      { access: { roles: ["TenantAdmin", "Admin", "SystemAdmin"] } },
+    );
+  });
+}
+
+function mailFoundation(extra?: (r: Parameters<Parameters<typeof defineFeature>[1]>[0]) => void) {
+  return defineFeature("mail-foundation", (r) => {
+    r.translations({
+      keys: {
+        "mail-foundation.settings": { en: "Mail", de: "Mail-Versand" },
+        "mail-foundation.settings.tenant": { en: "Mail (tenant)", de: "Mail (Mandant)" },
+      },
+    });
+    r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
+    const keys = r.config({
+      keys: {
+        provider: createTenantConfig("text", {
+          default: "",
+          write: TENANT_ADMIN_WRITE,
+          mask: { title: "mail.provider", order: 1, icon: "mail" },
+        }),
+      },
+    });
+    r.extensionSelector("mailTransport", keys.provider);
+    extra?.(r);
+  });
+}
+
+const smtp = defineFeature("mail-smtp", (r) => {
+  r.requires("mail-foundation");
+  r.useExtension("mailTransport", "smtp");
+  r.config({
+    keys: {
+      host: createTenantConfig("text", {
+        default: "",
+        write: TENANT_ADMIN_WRITE,
+        mask: { title: "smtp.host" },
+      }),
+      relay: createSystemConfig("text", {
+        default: "",
+        write: access.systemAdmin,
+        mask: { title: "smtp.relay" },
+      }),
+    },
+  });
+  r.secret("password", { label: { en: "SMTP password" }, scope: "tenant", required: true });
+});
+
+const inmemory = defineFeature("mail-inmemory", (r) => {
+  r.requires("mail-foundation");
+  r.useExtension("mailTransport", "inmemory");
+  r.config({
+    keys: {
+      capture: createTenantConfig("boolean", {
+        write: TENANT_ADMIN_WRITE,
+        mask: { title: "inmemory.capture" },
+      }),
+    },
+  });
+});
+
+const stripe = defineFeature("stripe", (r) => {
+  r.secret("apiKey", { label: { en: "Stripe key" }, scope: "tenant" });
+});
+
+function build(features: FeatureDefinition[]) {
+  return buildConfigFeatureSchema(createRegistry(features));
+}
+
+function screenOf<T extends ScreenDefinition["type"]>(
+  schema: ReturnType<typeof buildConfigFeatureSchema>,
+  id: string,
+  type: T,
+): Extract<ScreenDefinition, { type: T }> {
+  const s = schema.screens.find((x) => x.id === id);
+  if (s === undefined || s.type !== type) throw new Error(`no ${type} screen "${id}"`);
+  return s as Extract<ScreenDefinition, { type: T }>; // @cast-boundary type checked on the line above
+}
+
+const gatedFeatures = () => [secretsFeature(), mailFoundation(), smtp, inmemory, stripe];
+
+describe("buildConfigFeatureSchema — extension selector", () => {
+  test("selector key renders as select of plugin ids, at every scope it shows up", () => {
+    const schema = build(gatedFeatures());
+    const selection = screenOf(schema, "mail-foundation-tenant-selection", "configEdit");
+    expect(selection.fields["provider"]).toMatchObject({
+      type: "select",
+      options: ["inmemory", "smtp"],
+    });
+  });
+
+  test("selector without any plugin stays a text field", () => {
+    const schema = build([mailFoundation()]);
+    const screen = screenOf(schema, "mail-foundation-tenant", "configEdit");
+    expect(screen.fields["provider"]?.type).toBe("text");
+  });
+
+  test("owner tenant screen is a dashboard: selection, plugin config panels, plugin secrets panel", () => {
+    const schema = build(gatedFeatures());
+    const dashboard = screenOf(schema, "mail-foundation-tenant", "dashboard");
+    expect(dashboard.description).toBe("config.settings.extensionSelectorHint");
+    expect(dashboard.panels).toEqual([
+      { kind: "screen", id: "selection", screen: "mail-foundation-tenant-selection" },
+      {
+        kind: "screen",
+        id: "mail-inmemory-config",
+        screen: "mail-inmemory-tenant",
+        visibleWhen: { query: SELECTED_EXTENSIONS_QUERY, field: "mailTransport", eq: "inmemory" },
+      },
+      {
+        kind: "screen",
+        id: "mail-smtp-config",
+        screen: "mail-smtp-tenant",
+        visibleWhen: { query: SELECTED_EXTENSIONS_QUERY, field: "mailTransport", eq: "smtp" },
+      },
+      {
+        kind: "screen",
+        id: "mail-smtp-secrets",
+        screen: "mail-smtp-tenant-secrets",
+        visibleWhen: { query: SELECTED_EXTENSIONS_QUERY, field: "mailTransport", eq: "smtp" },
+      },
+    ]);
+  });
+
+  test("embedded screens are dormant and plugin features lose their tenant nav", () => {
+    const schema = build(gatedFeatures());
+    for (const id of [
+      "mail-foundation-tenant-selection",
+      "mail-smtp-tenant",
+      "mail-inmemory-tenant",
+    ]) {
+      expect(screenOf(schema, id, "configEdit").dormant).toBe(true);
+    }
+    expect(screenOf(schema, "mail-smtp-tenant-secrets", "secretsEdit").dormant).toBe(true);
+    expect(screenOf(schema, "mail-foundation-tenant", "dashboard").dormant).toBeUndefined();
+
+    const navIds = schema.navs.map((n) => n.id);
+    expect(navIds).toContain("mail-foundation-tenant");
+    expect(navIds).not.toContain("mail-smtp-tenant");
+    expect(navIds).not.toContain("mail-inmemory-tenant");
+  });
+
+  test("owner nav keeps id/label/screen and the dashboard access is the union incl. secrets", () => {
+    const schema = build(gatedFeatures());
+    const nav = schema.navs.find((n) => n.id === "mail-foundation-tenant");
+    expect(nav).toMatchObject({
+      screen: "mail-foundation-tenant",
+      label: "mail-foundation.settings.tenant",
+      parent: "audience-tenant",
+      icon: "mail",
+    });
+    const dashboard = screenOf(schema, "mail-foundation-tenant", "dashboard");
+    expect(dashboard.access).toEqual({ roles: ["TenantAdmin", "Admin", "SystemAdmin"] });
+    expect(nav?.access).toEqual(dashboard.access);
+  });
+
+  test("plugin panel keeps title source: the plugin screen still uses its own settings section", () => {
+    const schema = build(gatedFeatures());
+    const pluginScreen: ConfigEditScreenDefinition = screenOf(
+      schema,
+      "mail-smtp-tenant",
+      "configEdit",
+    );
+    expect(pluginScreen.configKeys).toEqual({ host: "mail-smtp:config:host" });
+    expect(pluginScreen.layout.sections[0]).toMatchObject({ title: "mail-smtp.settings" });
+  });
+
+  test("plugin secrets panel reuses the global secrets access object", () => {
+    const schema = build(gatedFeatures());
+    const panelScreen: SecretsEditScreenDefinition = screenOf(
+      schema,
+      "mail-smtp-tenant-secrets",
+      "secretsEdit",
+    );
+    const globalScreen = screenOf(schema, "secrets", "secretsEdit");
+    expect(panelScreen.access).toBe(globalScreen.access);
+    expect(panelScreen.requiredFields).toEqual(["mail-smtp-password"]);
+    expect(Object.keys(panelScreen.secretKeys)).toEqual(["mail-smtp-password"]);
+  });
+
+  test("global secrets screen drops gated secrets", () => {
+    const schema = build(gatedFeatures());
+    const globalScreen = screenOf(schema, "secrets", "secretsEdit");
+    expect(Object.keys(globalScreen.secretKeys)).toEqual(["stripe-api-key"]);
+    expect(schema.translations).toMatchObject({
+      "config.secret.mail-smtp.password.label": { en: "SMTP password" },
+      "config.secret.stripe.api-key.label": { en: "Stripe key" },
+    });
+  });
+
+  test("global secrets screen and nav vanish when only gated secrets exist; audience nav keeps secrets access", () => {
+    const schema = build([secretsFeature(), mailFoundation(), smtp, inmemory]);
+    expect(schema.screens.some((s) => s.id === "secrets")).toBe(false);
+    expect(schema.navs.some((n) => n.id === "secrets")).toBe(false);
+    const audience = schema.navs.find((n) => n.id === "audience-tenant");
+    expect(audience?.access).toEqual({ roles: ["TenantAdmin", "Admin", "SystemAdmin"] });
+  });
+
+  test("selection title translation is copied from the owner's tenant label, else its settings label", () => {
+    const withTenantLabel = build(gatedFeatures());
+    expect(withTenantLabel.translations?.["screen:mail-foundation-tenant-selection.title"]).toEqual(
+      {
+        en: "Mail (tenant)",
+        de: "Mail (Mandant)",
+      },
+    );
+
+    const plainOwner = defineFeature("mail-foundation", (r) => {
+      r.translations({ keys: { "mail-foundation.settings": { en: "Mail" } } });
+      r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
+      const keys = r.config({
+        keys: {
+          provider: createTenantConfig("text", {
+            default: "",
+            write: TENANT_ADMIN_WRITE,
+            mask: { title: "mail.provider" },
+          }),
+        },
+      });
+      r.extensionSelector("mailTransport", keys.provider);
+    });
+    const schema = build([plainOwner, smtp, inmemory]);
+    expect(schema.translations?.["screen:mail-foundation-tenant-selection.title"]).toEqual({
+      en: "Mail",
+    });
+  });
+
+  test("plugin system-scope screen and nav stay ungated", () => {
+    const schema = build(gatedFeatures());
+    expect(screenOf(schema, "mail-smtp-system", "configEdit").dormant).toBeUndefined();
+    expect(schema.navs.find((n) => n.id === "mail-smtp-system")).toMatchObject({
+      parent: "audience-system",
+      screen: "mail-smtp-system",
+    });
+  });
+
+  test("plugin feature registered under two ids keeps today's behaviour", () => {
+    const twice = defineFeature("mail-smtp", (r) => {
+      r.useExtension("mailTransport", "smtp");
+      r.useExtension("mailTransport", "smtps");
+      r.config({
+        keys: {
+          host: createTenantConfig("text", {
+            default: "",
+            write: TENANT_ADMIN_WRITE,
+            mask: { title: "smtp.host" },
+          }),
+        },
+      });
+      r.secret("password", { label: { en: "SMTP password" }, scope: "tenant" });
+    });
+    const schema = build([secretsFeature(), mailFoundation(), twice, inmemory]);
+    expect(schema.navs.map((n) => n.id)).toContain("mail-smtp-tenant");
+    expect(screenOf(schema, "mail-smtp-tenant", "configEdit").dormant).toBeUndefined();
+    expect(Object.keys(screenOf(schema, "secrets", "secretsEdit").secretKeys)).toEqual([
+      "mail-smtp-password",
+    ]);
+    const dashboard = screenOf(schema, "mail-foundation-tenant", "dashboard");
+    expect(dashboard.panels.map((p) => p.id)).toEqual(["selection", "mail-inmemory-config"]);
+  });
+
+  test("plugin feature shared by two selectors keeps today's behaviour", () => {
+    const otherFoundation = defineFeature("sms-foundation", (r) => {
+      r.extendsRegistrar("smsTransport", { onRegister: () => undefined });
+      const keys = r.config({
+        keys: {
+          provider: createTenantConfig("text", {
+            default: "",
+            write: TENANT_ADMIN_WRITE,
+            mask: { title: "sms.provider" },
+          }),
+        },
+      });
+      r.extensionSelector("smsTransport", keys.provider);
+    });
+    const both = defineFeature("mail-smtp", (r) => {
+      r.useExtension("mailTransport", "smtp");
+      r.useExtension("smsTransport", "gateway");
+      r.config({
+        keys: {
+          host: createTenantConfig("text", {
+            default: "",
+            write: TENANT_ADMIN_WRITE,
+            mask: { title: "smtp.host" },
+          }),
+        },
+      });
+    });
+    const schema = build([mailFoundation(), otherFoundation, both]);
+    expect(schema.navs.map((n) => n.id)).toContain("mail-smtp-tenant");
+    expect(schema.screens.find((s) => s.id === "mail-foundation-tenant")?.type).toBe("configEdit");
+  });
+
+  test("selector key not visible at tenant scope: no dashboard, plugins untouched", () => {
+    const systemOnlyOwner = defineFeature("mail-foundation", (r) => {
+      r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
+      const keys = r.config({
+        keys: {
+          provider: createSystemConfig("text", {
+            default: "",
+            write: access.systemAdmin,
+            mask: { title: "mail.provider" },
+          }),
+        },
+      });
+      r.extensionSelector("mailTransport", keys.provider);
+    });
+    const schema = build([systemOnlyOwner, smtp, inmemory]);
+    expect(schema.screens.some((s) => s.type === "dashboard")).toBe(false);
+    expect(schema.navs.map((n) => n.id)).toContain("mail-smtp-tenant");
+    expect(screenOf(schema, "mail-foundation-system", "configEdit").fields["provider"]?.type).toBe(
+      "select",
+    );
+  });
+
+  test("app without a masked selector is unchanged", () => {
+    const unmaskedOwner = defineFeature("mail-foundation", (r) => {
+      r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
+      const keys = r.config({ keys: { provider: createTenantConfig("text", { default: "" }) } });
+      r.extensionSelector("mailTransport", keys.provider);
+    });
+    const schema = build([secretsFeature(), unmaskedOwner, smtp, inmemory, stripe]);
+    expect(schema.screens.some((s) => s.type === "dashboard")).toBe(false);
+    expect(schema.navs.map((n) => n.id)).toContain("mail-smtp-tenant");
+    expect(Object.keys(screenOf(schema, "secrets", "secretsEdit").secretKeys).sort()).toEqual([
+      "mail-smtp-password",
+      "stripe-api-key",
+    ]);
+    expect(screenOf(schema, "mail-smtp-tenant", "configEdit").dormant).toBeUndefined();
+  });
+});
+
+describe("generated selector dashboard — boot validation", () => {
+  // Re-registers the GENERATED hub screens on the config stand-in so
+  // validateBoot runs its real dashboard/screen-panel/query-ref checks on them.
+  function hubHostFeature(withQuery: boolean): FeatureDefinition {
+    const schema = build(gatedFeatures());
+    // i18n coverage of the hub is asserted in the i18n-keys boot test; here every
+    // required key is defined so only the screen/panel/query checks can fail.
+    const translationKeys = Object.fromEntries(
+      schema.screens
+        .flatMap((s) =>
+          requiredKeysFromScreen(SETTINGS_HUB_FEATURE, s, { treatDotFormAsKey: true }),
+        )
+        .map((key) => [key, { en: key }]),
+    );
+    return defineFeature("config", (r) => {
+      r.translations({ keys: { ...translationKeys, ...SETTINGS_HUB_I18N } });
+      if (withQuery) {
+        r.queryHandler({
+          name: "config-value:selected-extensions",
+          schema: z.object({}),
+          access: { openToAll: { reason: "test stand-in" } },
+          handler: async () => ({}),
+        });
+      }
+      for (const screen of schema.screens) r.screen(screen);
+    });
+  }
+
+  test("panel targets resolve to embeddable generated screens and the visibleWhen query is registered", () => {
+    expect(() => validateBoot([hubHostFeature(true), ...gatedFeatures()])).not.toThrow();
+  });
+
+  test("a visibleWhen query that is not a registered handler is rejected", () => {
+    expect(() => validateBoot([hubHostFeature(false), ...gatedFeatures()])).toThrow(
+      /visibleWhen query "config:query:config-value:selected-extensions"/,
+    );
+  });
+});

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

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { SETTINGS_HUB_I18N } from "../../../i18n/settings-hub-keys";
 import { buildConfigFeatureSchema } from "../../build-config-feature-schema";
 import { access, createTenantConfig } from "../../config-helpers";
 import { defineFeature } from "../../define-feature";
@@ -265,3 +267,74 @@ describe("validateI18nSurfaceKeys — mask.title is unconditionally required (fw
     expect(() => validateBoot([configHub, feature])).not.toThrow();
   });
 });
+
+describe("validateI18nSurfaceKeys — extension-selector settings dashboard", () => {
+  const secretsMount = defineFeature("secrets", (r) => {
+    r.writeHandler(
+      "set",
+      z.object({ key: z.string(), value: z.string() }),
+      async () => ({ isSuccess: true, data: null }),
+      { access: { roles: ["TenantAdmin"] } },
+    );
+  });
+  const hubWithHint = defineFeature("config", (r) => {
+    r.translations({ keys: SETTINGS_HUB_I18N });
+  });
+  const hubWithoutHint = defineFeature("config", (r) => {
+    const { "config.settings.extensionSelectorHint": _hint, ...withoutHint } = SETTINGS_HUB_I18N;
+    r.translations({ keys: withoutHint });
+  });
+
+  // Consumer-shaped: only the keys an app declared before the selector screen existed.
+  const owner = defineFeature("mail-foundation", (r) => {
+    r.translations({
+      keys: {
+        "mail-foundation.settings": { en: "Mail" },
+        "screen:mail-foundation-tenant.title": { en: "Mail" },
+        "mail.provider": { en: "Provider" },
+      },
+    });
+    r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
+    const keys = r.config({
+      keys: {
+        provider: createTenantConfig("text", {
+          default: "",
+          write: access.roles("TenantAdmin"),
+          mask: { title: "mail.provider" },
+        }),
+      },
+    });
+    r.extensionSelector("mailTransport", keys.provider);
+  });
+  const smtp = defineFeature("mail-smtp", (r) => {
+    r.requires("mail-foundation");
+    r.translations({
+      keys: {
+        "mail-smtp.settings": { en: "SMTP" },
+        "screen:mail-smtp-tenant.title": { en: "SMTP" },
+        "smtp.host": { en: "Host" },
+      },
+    });
+    r.useExtension("mailTransport", "smtp");
+    r.config({
+      keys: {
+        host: createTenantConfig("text", {
+          default: "",
+          write: access.roles("TenantAdmin"),
+          mask: { title: "smtp.host" },
+        }),
+      },
+    });
+    r.secret("password", { label: { en: "SMTP password" }, scope: "tenant" });
+  });
+
+  test("an app declaring only today's keys boots with the selector dashboard", () => {
+    expect(() => validateBoot([hubWithHint, secretsMount, owner, smtp])).not.toThrow();
+  });
+
+  test("the dashboard hint key is required once a selector dashboard exists", () => {
+    expect(() => validateBoot([hubWithoutHint, secretsMount, owner, smtp])).toThrow(
+      /Settings-Hub: required translation key missing: "config\.settings\.extensionSelectorHint"/,
+    );
+  });
+});

package/src/engine/boot-validator/i18n-keys.ts

@@ -5,14 +5,20 @@ import {
   requiredKeysFromNav,
   requiredKeysFromScreen,
   requiredKeysFromWorkspace,
+  screenTitleKey,
 } from "../../i18n/required-surface-keys";
 import {
   buildConfigFeatureSchema,
   type ConfigFeatureSchema,
   SETTINGS_HUB_FEATURE,
 } from "../build-config-feature-schema";
+import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins";
 import { createRegistry } from "../registry";
-import type { FeatureDefinition } from "../types";
+import type { FeatureDefinition, ScreenDefinition } from "../types";
+
+function isDormantSecretsScreen(screen: ScreenDefinition): boolean {
+  return screen.type === "secretsEdit" && screen.dormant === true;
+}
 
 function requiredKeysFromGeneratedConfigHub(schema: ConfigFeatureSchema): readonly string[] {
   if (schema.navs.length === 0) return [];
@@ -25,9 +31,12 @@ function requiredKeysFromGeneratedConfigHub(schema: ConfigFeatureSchema): readon
     for (const key of requiredKeysFromScreen(SETTINGS_HUB_FEATURE, screen, {
       treatDotFormAsKey: true,
     })) {
+      // Embedded selector-plugin secrets panels render no title of their own.
+      if (isDormantSecretsScreen(screen) && key === screenTitleKey(screen.id)) continue;
       out.add(key);
     }
   }
+  if (schema.screens.some((s) => s.type === "dashboard")) out.add(EXTENSION_SELECTOR_HINT_KEY);
   for (const nav of schema.navs) {
     for (const key of requiredKeysFromNav(nav, { treatDotFormAsKey: true })) out.add(key);
   }

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

@@ -17,14 +17,19 @@
 
 import type { WorkspaceSchema } from "../ui-types";
 import type { ConfigScope } from "./constants";
+import {
+  EXTENSION_SELECTOR_HINT_KEY,
+  SELECTED_EXTENSIONS_QUERY,
+  selectablePluginIds,
+} from "./extension-selector-plugins";
 import {
   createBooleanField,
   createNumberField,
   createSelectField,
   createTextField,
 } from "./factories";
-import { isKebabSegment } from "./qualified-name";
-import type { ConfigKeyDefinition, TranslationKeys } from "./types/config";
+import { isKebabSegment, toKebab } from "./qualified-name";
+import type { ConfigKeyDefinition, TranslationEntry, TranslationKeys } from "./types/config";
 import type { Registry, SecretKeyDefinition } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 import type { AccessRule } from "./types/handlers";
@@ -32,6 +37,8 @@ import { isOpenToAllGranted } from "./types/handlers";
 import type { NavDefinition, NavIconKey } from "./types/nav";
 import type {
   ConfigEditScreenDefinition,
+  DashboardPanelDefinition,
+  DashboardScreenDefinition,
   EditFieldsSection,
   ScreenDefinition,
   SecretsEditScreenDefinition,
@@ -117,51 +124,293 @@ type ScopeResult = {
   readonly translations?: TranslationKeys;
 };
 
+// Its tenant keys/secrets become panels of the selector owner's dashboard, not own navs.
+type GatedPlugin = {
+  readonly feature: string;
+  readonly extension: string;
+  readonly pluginId: string;
+  readonly scopedKeys: readonly ScopedKey[];
+  readonly secrets: readonly DeclaredSecret[];
+};
+
+type SelectorGating = {
+  readonly pluginsByOwnerGroup: ReadonlyMap<string, readonly GatedPlugin[]>;
+  readonly pluginFeatures: ReadonlySet<string>;
+  readonly secretQns: ReadonlySet<string>;
+};
+
+const NO_SELECTOR_GATING: SelectorGating = {
+  pluginsByOwnerGroup: new Map(),
+  pluginFeatures: new Set(),
+  secretQns: new Set(),
+};
+
+type HubContext = {
+  readonly declaredTranslationKeys: ReadonlySet<string>;
+  readonly selectorOptions: ReadonlyMap<string, readonly string[]>;
+  readonly translationsByKey: ReadonlyMap<string, TranslationEntry>;
+};
+
 // Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
 // (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
-function collectDeclaredTranslationKeys(registry: Registry): Set<string> {
-  const declaredTranslationKeys = new Set<string>();
+function collectDeclaredTranslations(registry: Registry): ReadonlyMap<string, TranslationEntry> {
+  const declared = new Map<string, TranslationEntry>();
   for (const f of registry.features.values()) {
-    for (const key of Object.keys(f.translations ?? {})) declaredTranslationKeys.add(key);
+    for (const [key, values] of Object.entries(f.translations ?? {})) {
+      if (!declared.has(key)) declared.set(key, values);
+    }
+  }
+  return declared;
+}
+
+function collectSelectorOptions(registry: Registry): Map<string, readonly string[]> {
+  const options = new Map<string, readonly string[]>();
+  for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+    const pluginIds = selectablePluginIds(registry, extensionName);
+    if (pluginIds.length > 0) options.set(selectorKey, pluginIds);
+  }
+  return options;
+}
+
+function collectVisibleSelectorOwners(
+  registry: Registry,
+  visible: readonly ScopedKey[],
+): { ownerGroupByExtension: Map<string, string>; selectorFeatures: Set<string> } {
+  const ownerGroupByExtension = new Map<string, string>();
+  const selectorFeatures = new Set<string>();
+  for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+    const selector = visible.find((v) => v.key.qn === selectorKey);
+    if (selector === undefined) continue;
+    ownerGroupByExtension.set(extensionName, selector.key.feature);
+    selectorFeatures.add(selector.key.feature);
+    selectorFeatures.add(selector.key.ownerFeature);
+  }
+  return { ownerGroupByExtension, selectorFeatures };
+}
+
+function countSelectorUsagesByFeature(registry: Registry): Map<string, number> {
+  const usageCountByFeature = new Map<string, number>();
+  for (const [extensionName] of registry.getAllExtensionSelectors()) {
+    for (const usage of registry.getExtensionUsages(extensionName)) {
+      if (usage.featureName === undefined) continue;
+      const feature = toKebab(usage.featureName);
+      usageCountByFeature.set(feature, (usageCountByFeature.get(feature) ?? 0) + 1);
+    }
+  }
+  return usageCountByFeature;
+}
+
+// A plugin feature with several selector-gated registrations can't sit under one
+// selector's panel, so it stays ungated (own nav, secrets in the global screen).
+function planSelectorGating(
+  registry: Registry,
+  visible: readonly ScopedKey[],
+  declaredSecrets: readonly DeclaredSecret[],
+  secretsEnabled: boolean,
+): SelectorGating {
+  const { ownerGroupByExtension, selectorFeatures } = collectVisibleSelectorOwners(
+    registry,
+    visible,
+  );
+  if (ownerGroupByExtension.size === 0) return NO_SELECTOR_GATING;
+  const usageCountByFeature = countSelectorUsagesByFeature(registry);
+
+  const pluginsByOwnerGroup = new Map<string, GatedPlugin[]>();
+  const pluginFeatures = new Set<string>();
+  const secretQns = new Set<string>();
+  for (const [extension, ownerGroup] of [...ownerGroupByExtension].sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    const usages = [...registry.getExtensionUsages(extension)].sort((a, b) =>
+      (a.featureName ?? "").localeCompare(b.featureName ?? ""),
+    );
+    for (const usage of usages) {
+      if (usage.featureName === undefined) continue;
+      const feature = toKebab(usage.featureName);
+      if (usageCountByFeature.get(feature) !== 1 || selectorFeatures.has(feature)) continue;
+      const scopedKeys = visible.filter((v) => v.key.ownerFeature === feature);
+      const secrets = secretsEnabled ? declaredSecrets.filter((s) => s.feature === feature) : [];
+      if (scopedKeys.length === 0 && secrets.length === 0) continue;
+      const plugins = pluginsByOwnerGroup.get(ownerGroup) ?? [];
+      plugins.push({ feature, extension, pluginId: usage.entityName, scopedKeys, secrets });
+      pluginsByOwnerGroup.set(ownerGroup, plugins);
+      pluginFeatures.add(feature);
+      for (const s of secrets) secretQns.add(s.qn);
+    }
   }
-  return declaredTranslationKeys;
+  return { pluginsByOwnerGroup, pluginFeatures, secretQns };
+}
+
+type FeatureScreens = {
+  screens: ScreenDefinition[];
+  navs: NavDefinition[];
+  translations: Record<string, TranslationEntry>;
+};
+
+// A tenant/user-home key with an elevated write role (SystemAdmin on a
+// tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
+// audience navs (cascade-default screen + home screen) — both would
+// otherwise carry the identical `${feature}.settings` label. Opt-in
+// scoped override (`${feature}.settings.${scope}`) disambiguates only
+// where a feature actually declares one; every single-scope feature
+// keeps the plain key unchanged.
+function buildFeatureNav(
+  scope: ConfigScope,
+  feature: string,
+  ordered: readonly MaskedKey[],
+  access: AccessRule,
+  declaredTranslationKeys: ReadonlySet<string>,
+): NavDefinition {
+  const shortId = `${feature}-${scope}`;
+  const scopedLabel = `${feature}.settings.${scope}`;
+  return {
+    id: shortId,
+    label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
+    parent: audienceNavShortId(scope),
+    screen: shortId,
+    icon: ordered[0]?.def.mask?.icon ?? "settings",
+    order: minMaskOrder(ordered),
+    access,
+  };
 }
 
-// Per-feature configEdit screen + child-nav, one pair per feature present in
-// `visible` at this scope.
+// One configEdit screen + child-nav per feature; a tenant-scope selector owner
+// becomes a dashboard instead and its gated plugins get no entries of their own.
 function buildFeatureScreensAndNavs(
   scope: ConfigScope,
   visible: readonly ScopedKey[],
-  declaredTranslationKeys: ReadonlySet<string>,
-): { screens: ScreenDefinition[]; navs: NavDefinition[] } {
-  const screens: ScreenDefinition[] = [];
-  const navs: NavDefinition[] = [];
-  for (const feature of featuresPresent(visible.map((v) => v.key))) {
-    const group = visible.filter((v) => v.key.feature === feature);
+  hub: HubContext,
+  gating: SelectorGating,
+  secretsAccess: AccessRule | undefined,
+): FeatureScreens {
+  const out: FeatureScreens = { screens: [], navs: [], translations: {} };
+  const ungated = visible.filter((v) => !gating.pluginFeatures.has(v.key.ownerFeature));
+  for (const feature of featuresPresent(ungated.map((v) => v.key))) {
+    const group = ungated.filter((v) => v.key.feature === feature);
     const ordered = sortByMaskOrder(group.map((v) => v.key));
     const access = rolesToAccess(group.flatMap((v) => v.roles));
     const shortId = `${feature}-${scope}`;
+    const plugins = scope === "tenant" ? gating.pluginsByOwnerGroup.get(feature) : undefined;
 
-    screens.push(buildScreen(shortId, scope, feature, ordered, access, declaredTranslationKeys));
-    // A tenant/user-home key with an elevated write role (SystemAdmin on a
-    // tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
-    // audience navs (cascade-default screen + home screen) — both would
-    // otherwise carry the identical `${feature}.settings` label. Opt-in
-    // scoped override (`${feature}.settings.${scope}`) disambiguates only
-    // where a feature actually declares one; every single-scope feature
-    // keeps the plain key unchanged.
-    const scopedLabel = `${feature}.settings.${scope}`;
-    navs.push({
-      id: shortId,
-      label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
-      parent: audienceNavShortId(scope),
-      screen: shortId,
-      icon: ordered[0]?.def.mask?.icon ?? "settings",
-      order: minMaskOrder(ordered),
+    if (plugins === undefined) {
+      out.screens.push(buildScreen(shortId, scope, feature, ordered, access, hub));
+      out.navs.push(buildFeatureNav(scope, feature, ordered, access, hub.declaredTranslationKeys));
+      continue;
+    }
+    const ownerHub = buildSelectorOwnerDashboard(
+      feature,
+      ordered,
       access,
-    });
+      plugins,
+      hub,
+      secretsAccess,
+    );
+    out.screens.push(...ownerHub.screens);
+    out.navs.push(
+      buildFeatureNav(scope, feature, ordered, ownerHub.access, hub.declaredTranslationKeys),
+    );
+    Object.assign(out.translations, ownerHub.translations);
+  }
+  return out;
+}
+
+function pluginTenantScreenId(plugin: GatedPlugin): string {
+  return `${plugin.feature}-tenant`;
+}
+
+// Plugin screens keep their `${F}-tenant` ids so consumer title keys stay valid;
+// they are dormant because only this dashboard embeds them.
+function buildSelectorOwnerDashboard(
+  ownerGroup: string,
+  ownerKeys: readonly MaskedKey[],
+  ownerAccess: AccessRule,
+  plugins: readonly GatedPlugin[],
+  hub: HubContext,
+  secretsAccess: AccessRule | undefined,
+): {
+  screens: ScreenDefinition[];
+  access: AccessRule;
+  translations: Record<string, TranslationEntry>;
+} {
+  const selectionScreenId = `${ownerGroup}-tenant-selection`;
+  const selectionScreen: ConfigEditScreenDefinition = {
+    ...buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub),
+    dormant: true,
+  };
+  const screens: ScreenDefinition[] = [selectionScreen];
+  const configPanels: DashboardPanelDefinition[] = [];
+  const secretsPanels: DashboardPanelDefinition[] = [];
+  const accessRules: (AccessRule | undefined)[] = [ownerAccess];
+  const translations: Record<string, TranslationEntry> = {};
+
+  const titleSource = [`${ownerGroup}.settings.tenant`, `${ownerGroup}.settings`].find((key) =>
+    hub.translationsByKey.has(key),
+  );
+  const titleValues =
+    titleSource === undefined ? undefined : hub.translationsByKey.get(titleSource);
+  if (titleValues !== undefined) translations[`screen:${selectionScreenId}.title`] = titleValues;
+
+  for (const plugin of plugins) {
+    const visibleWhen = {
+      query: SELECTED_EXTENSIONS_QUERY,
+      field: plugin.extension,
+      eq: plugin.pluginId,
+    };
+    if (plugin.scopedKeys.length > 0) {
+      const pluginAccess = rolesToAccess(plugin.scopedKeys.flatMap((v) => v.roles));
+      const ordered = sortByMaskOrder(plugin.scopedKeys.map((v) => v.key));
+      screens.push({
+        ...buildScreen(
+          pluginTenantScreenId(plugin),
+          "tenant",
+          plugin.feature,
+          ordered,
+          pluginAccess,
+          hub,
+        ),
+        dormant: true,
+      });
+      accessRules.push(pluginAccess);
+      configPanels.push({
+        kind: "screen",
+        id: `${plugin.feature}-config`,
+        screen: pluginTenantScreenId(plugin),
+        visibleWhen,
+      });
+    }
+    if (plugin.secrets.length > 0) {
+      const secretsScreenId = `${plugin.feature}-tenant-secrets`;
+      const generated = buildSecretsEditScreen(
+        secretsScreenId,
+        plugin.secrets,
+        secretsAccess,
+        hub.declaredTranslationKeys,
+      );
+      screens.push({ ...generated.screen, dormant: true });
+      Object.assign(translations, generated.translations);
+      accessRules.push(secretsAccess);
+      secretsPanels.push({
+        kind: "screen",
+        id: `${plugin.feature}-secrets`,
+        screen: secretsScreenId,
+        visibleWhen,
+      });
+    }
   }
-  return { screens, navs };
+
+  const access = unionAccessRules(accessRules);
+  const dashboard: DashboardScreenDefinition = {
+    id: `${ownerGroup}-tenant`,
+    type: "dashboard",
+    description: EXTENSION_SELECTOR_HINT_KEY,
+    panels: [
+      { kind: "screen", id: "selection", screen: selectionScreenId },
+      ...configPanels,
+      ...secretsPanels,
+    ],
+    access,
+  };
+  return { screens: [dashboard, ...screens], access, translations };
 }
 
 // Everything generated for one audience scope: the audience-parent nav, the
@@ -173,7 +422,8 @@ function buildScopeResult(
   secretsEnabled: boolean,
   secretsWriteHandler: ReturnType<Registry["getWriteHandler"]>,
   declaredSecrets: readonly DeclaredSecret[],
-  declaredTranslationKeys: ReadonlySet<string>,
+  hub: HubContext,
+  registry: Registry,
 ): ScopeResult | null {
   const visible = scopedKeysAt(masked, scope);
   // Secrets attach to the tenant-audience nav regardless of whether any
@@ -183,6 +433,10 @@ function buildScopeResult(
 
   const configAccess = rolesToAccess(visible.flatMap((v) => v.roles));
   const secretsAccess = secretsWriteHandler?.access;
+  const gating =
+    scope === "tenant"
+      ? planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
+      : NO_SELECTOR_GATING;
   const screens: ScreenDefinition[] = [];
   const navs: NavDefinition[] = [];
   // Audience-Parent: Gruppierungs-Knoten ohne Screen.
@@ -194,19 +448,26 @@ function buildScopeResult(
     access: includeSecrets ? unionAccessRules([configAccess, secretsAccess]) : configAccess,
   });
 
-  const perFeature = buildFeatureScreensAndNavs(scope, visible, declaredTranslationKeys);
+  const perFeature = buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess);
   screens.push(...perFeature.screens);
   navs.push(...perFeature.navs);
 
-  let translations: TranslationKeys | undefined;
-  if (includeSecrets) {
-    const generated = buildSecretsScreen(declaredSecrets, secretsAccess, declaredTranslationKeys);
+  const translations: Record<string, TranslationEntry> = {
+    ...perFeature.translations,
+  };
+  const globalSecrets = declaredSecrets.filter((s) => !gating.secretQns.has(s.qn));
+  if (includeSecrets && globalSecrets.length > 0) {
+    const generated = buildSecretsScreen(globalSecrets, secretsAccess, hub.declaredTranslationKeys);
     screens.push(generated.screen);
     navs.push(generated.nav);
-    translations = generated.translations;
+    Object.assign(translations, generated.translations);
   }
 
-  return { screens, navs, ...(translations !== undefined && { translations }) };
+  return {
+    screens,
+    navs,
+    ...(Object.keys(translations).length > 0 && { translations }),
+  };
 }
 
 export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema {
@@ -218,7 +479,12 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
   const secretsEnabled = secretsWriteHandler !== undefined && declaredSecrets.length > 0;
   if (masked.length === 0 && !secretsEnabled) return { screens: [], navs: [] };
 
-  const declaredTranslationKeys = collectDeclaredTranslationKeys(registry);
+  const translationsByKey = collectDeclaredTranslations(registry);
+  const hub: HubContext = {
+    declaredTranslationKeys: new Set(translationsByKey.keys()),
+    selectorOptions: collectSelectorOptions(registry),
+    translationsByKey,
+  };
 
   const screens: ScreenDefinition[] = [];
   const navs: NavDefinition[] = [];
@@ -231,12 +497,15 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
       secretsEnabled,
       secretsWriteHandler,
       declaredSecrets,
-      declaredTranslationKeys,
+      hub,
+      registry,
     );
     if (result === null) continue;
     screens.push(...result.screens);
     navs.push(...result.navs);
-    if (result.translations !== undefined) translations = result.translations;
+    if (result.translations !== undefined) {
+      translations = { ...translations, ...result.translations };
+    }
   }
 
   // Every masked key machine-only and no secrets → no human hub, and no
@@ -283,6 +552,30 @@ function buildSecretsScreen(
   access: AccessRule | undefined,
   declaredTranslationKeys: ReadonlySet<string>,
 ): { screen: SecretsEditScreenDefinition; nav: NavDefinition; translations: TranslationKeys } {
+  const { screen, translations } = buildSecretsEditScreen(
+    "secrets",
+    secrets,
+    access,
+    declaredTranslationKeys,
+  );
+  const nav: NavDefinition = {
+    id: "secrets",
+    label: "config.secrets.title",
+    parent: audienceNavShortId("tenant"),
+    screen: "secrets",
+    icon: "key",
+    order: 900,
+    ...(access !== undefined && { access }),
+  };
+  return { screen, nav, translations };
+}
+
+function buildSecretsEditScreen(
+  screenId: string,
+  secrets: readonly DeclaredSecret[],
+  access: AccessRule | undefined,
+  declaredTranslationKeys: ReadonlySet<string>,
+): { screen: SecretsEditScreenDefinition; translations: TranslationKeys } {
   const secretKeys: Record<string, string> = {};
   const fieldLabels: Record<string, string> = {};
   const fieldHints: Record<string, string> = {};
@@ -290,7 +583,7 @@ function buildSecretsScreen(
   // Mutable outer record — TranslationKeys' Readonly<Record<...>> index
   // signature only permits reading, so the top-level assignments below
   // need a writable local type; each entry is still a fresh, never-mutated object.
-  const translations: Record<string, Readonly<Record<string, string>>> = {};
+  const translations: Record<string, TranslationEntry> = {};
   const sections: SecretsEditSection[] = [];
 
   for (const feature of [...new Set(secrets.map((s) => s.feature))]) {
@@ -317,7 +610,7 @@ function buildSecretsScreen(
   }
 
   const screen: SecretsEditScreenDefinition = {
-    id: "secrets",
+    id: screenId,
     type: "secretsEdit",
     secretKeys,
     fieldLabels,
@@ -326,16 +619,7 @@ function buildSecretsScreen(
     sections,
     ...(access !== undefined && { access }),
   };
-  const nav: NavDefinition = {
-    id: "secrets",
-    label: "config.secrets.title",
-    parent: audienceNavShortId("tenant"),
-    screen: "secrets",
-    icon: "key",
-    order: 900,
-    ...(access !== undefined && { access }),
-  };
-  return { screen, nav, translations };
+  return { screen, translations };
 }
 
 // Keys visible at `scope`, paired with their effective write roles AT that
@@ -389,7 +673,7 @@ function buildScreen(
   feature: string,
   keys: readonly MaskedKey[],
   access: AccessRule,
-  declaredTranslationKeys: ReadonlySet<string>,
+  hub: HubContext,
 ): ConfigEditScreenDefinition {
   const configKeys: Record<string, string> = {};
   const fields: Record<string, FieldDefinition> = {};
@@ -411,7 +695,7 @@ function buildScreen(
     }
     seenFieldIds.set(id, k.qn);
     configKeys[id] = k.qn;
-    fields[id] = deriveField(k.def);
+    fields[id] = deriveField(k.def, hub.selectorOptions.get(k.qn));
     // mask is the visibility gate, so collectMaskedKeys guarantees it here.
     if (k.def.mask) fieldLabels[id] = k.def.mask.title;
   }
@@ -419,7 +703,7 @@ function buildScreen(
   const descriptionKey = `${feature}.settings.description`;
   const section: EditFieldsSection = {
     title: `${feature}.settings`,
-    ...(declaredTranslationKeys.has(descriptionKey) && { description: descriptionKey }),
+    ...(hub.declaredTranslationKeys.has(descriptionKey) && { description: descriptionKey }),
     fields: keys.map(fieldId),
   };
   return {
@@ -434,7 +718,11 @@ function buildScreen(
   };
 }
 
-function deriveField(def: ConfigKeyDefinition): FieldDefinition {
+function deriveField(
+  def: ConfigKeyDefinition,
+  selectorPluginIds: readonly string[] | undefined,
+): FieldDefinition {
+  if (selectorPluginIds !== undefined) return createSelectField({ options: selectorPluginIds });
   switch (def.type) {
     case "number":
       return createNumberField();

package/src/engine/extension-selector-plugins.ts

@@ -0,0 +1,24 @@
+import type { Registry } from "./types/feature";
+
+// Pinned QN of config's selected-extensions query — framework cannot import
+// bundled-features, so a pin test bundled-side keeps it equal to the handler.
+export const SELECTED_EXTENSIONS_QUERY = "config:query:config-value:selected-extensions";
+
+export const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHint";
+
+export function selectablePluginIds(
+  registry: Pick<Registry, "getExtensionUsages">,
+  extensionName: string,
+): string[] {
+  return [...new Set(registry.getExtensionUsages(extensionName).map((u) => u.entityName))].sort();
+}
+
+export function extensionSelectorTargets(
+  registry: Pick<Registry, "getAllExtensionSelectors">,
+): ReadonlyMap<string, string> {
+  const extensionByKey = new Map<string, string>();
+  for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+    extensionByKey.set(selectorKey, extensionName);
+  }
+  return extensionByKey;
+}

package/src/engine/index.ts

@@ -118,6 +118,12 @@ export {
   FILE_STORAGE_PROVIDER_ENV,
   TENANT_MEMBERSHIPS_QUERY,
 } from "./extension-names";
+export {
+  EXTENSION_SELECTOR_HINT_KEY,
+  extensionSelectorTargets,
+  SELECTED_EXTENSIONS_QUERY,
+  selectablePluginIds,
+} from "./extension-selector-plugins";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage";
 export type {
   StorageProviderDestroyTenantHook,

package/src/i18n/settings-hub-keys.ts

@@ -17,6 +17,9 @@ export const SETTINGS_HUB_I18N: TranslationKeys = {
   "config.settings.system": { en: "Platform" },
   "config.settings.tenant": { en: "Tenant" },
   "config.settings.user": { en: "Personal" },
+  "config.settings.extensionSelectorHint": {
+    en: "Save the provider selection to show its settings below.",
+  },
   "config.secrets.title": { en: "Secrets" },
   "config.secrets.notSet": { en: "Not set" },
   "config.secrets.set": { en: "Set" },