@cosmicdrift/kumiko-bundled-features 0.220.0 → 0.220.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.220.0",
+  "version": "0.220.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.220.0",
-    "@cosmicdrift/kumiko-framework": "0.220.0",
-    "@cosmicdrift/kumiko-headless": "0.220.0",
-    "@cosmicdrift/kumiko-renderer": "0.220.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.220.0",
-    "@cosmicdrift/kumiko-types": "0.220.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.220.1",
+    "@cosmicdrift/kumiko-framework": "0.220.1",
+    "@cosmicdrift/kumiko-headless": "0.220.1",
+    "@cosmicdrift/kumiko-renderer": "0.220.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.220.1",
+    "@cosmicdrift/kumiko-types": "0.220.1",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,7 +160,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.220.0",
-    "@cosmicdrift/kumiko-locale-es": "0.220.0"
+    "@cosmicdrift/kumiko-locale-de": "0.220.1",
+    "@cosmicdrift/kumiko-locale-es": "0.220.1"
   }
 }

package/src/auth-email-password/web/auth-client.ts

@@ -411,12 +411,6 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
     email: body.data.email,
     displayName: body.data.displayName,
     ...(body.data.locale !== undefined && { locale: body.data.locale }),
-    globalRoles: parseGlobalRoles(body.data.roles),
+    globalRoles: parseRoles(body.data.roles),
   };
 }
-
-// Defensive parse — roles may be jsonb string[] (0.217+) or a legacy
-// JSON-encoded string; malformed → [] so SessionProvider mount never throws.
-function parseGlobalRoles(raw: unknown): readonly string[] {
-  return parseRoles(raw);
-}

package/src/feature-toggles/__tests__/feature-toggles.integration.test.ts

@@ -568,7 +568,7 @@ describe("feature-toggles queries + audit automation", () => {
   test("registered query reports metadata + override + effective for every feature", async () => {
     runtime.apply("widget", false);
     const data = await stack.http.queryOk<{
-      items: Array<{
+      rows: Array<{
         name: string;
         toggleable: boolean;
         default: boolean | null;
@@ -577,7 +577,7 @@ describe("feature-toggles queries + audit automation", () => {
         effective: boolean | null;
       }>;
     }>("feature-toggles:query:registered", {}, admin);
-    const byName = new Map(data.items.map((i) => [i.name, i]));
+    const byName = new Map(data.rows.map((i) => [i.name, i]));
 
     expect(byName.get("widget")).toMatchObject({
       toggleable: true,

package/src/feature-toggles/__tests__/toggle-admin.boot.test.ts

@@ -11,11 +11,19 @@ describe("feature-toggles screen + handler access alignment", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
-  test("toggle-admin screen is SystemAdmin-gated", () => {
+  test("toggle-admin screen is projectionList and SystemAdmin-gated", () => {
     const toggles = createFeatureTogglesFeature();
     const screen = toggles.screens[TOGGLE_ADMIN_SCREEN_ID];
-    expect(screen?.type).toBe("custom");
-    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+    expect(screen?.type).toBe("projectionList");
+    if (screen?.type !== "projectionList") throw new Error("expected projectionList");
+    expect(screen.query).toBe(FeatureToggleQueries.registered);
+    const toggleAction = screen.rowActions?.find((a) => a.id === "toggle");
+    if (toggleAction?.kind !== "writeHandler") throw new Error("expected a writeHandler rowAction");
+    expect(toggleAction.handler).toBe(FeatureToggleHandlers.set);
+    expect(toggleAction.payload).toEqual({
+      map: { featureName: "name", enabled: "nextEnabled" },
+    });
+    if ("access" in screen && screen.access && "roles" in screen.access) {
       expect(screen.access.roles).toEqual(["SystemAdmin"]);
     }
   });

package/src/feature-toggles/__tests__/toggle-admin.security.integration.test.ts

@@ -36,6 +36,7 @@ describe("feature-toggles access matrix", () => {
     ]);
     const feature = createFeatureTogglesFeature();
     const screen = feature.screens[TOGGLE_ADMIN_SCREEN_ID];
+    expect(screen?.type).toBe("projectionList");
     if (screen && "access" in screen && screen.access && "roles" in screen.access) {
       expect(screen.access.roles).toEqual(["SystemAdmin"]);
     }
@@ -49,12 +50,12 @@ describe("feature-toggles HTTP access", () => {
       { items?: readonly unknown[] } | { rows?: readonly unknown[] }
     >(FeatureToggleQueries.list, {}, admin);
     expect(typeof list).toBe("object");
-    const registered = await stack.http.queryOk<{ items: readonly unknown[] }>(
+    const registered = await stack.http.queryOk<{ rows: readonly unknown[] }>(
       FeatureToggleQueries.registered,
       {},
       admin,
     );
-    expect(Array.isArray(registered.items)).toBe(true);
+    expect(Array.isArray(registered.rows)).toBe(true);
   });
 
   test("TenantAdmin gets 403 on list, registered, and set", async () => {

package/src/feature-toggles/feature.ts

@@ -1,5 +1,10 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { FEATURE_TOGGLE_SET_EVENT_NAME, TOGGLE_ADMIN_SCREEN_ID } from "./constants";
+import {
+  FEATURE_TOGGLE_SET_EVENT_NAME,
+  FeatureToggleHandlers,
+  FeatureToggleQueries,
+  TOGGLE_ADMIN_SCREEN_ID,
+} from "./constants";
 import { featureToggleSetSchema } from "./events";
 import { globalFeatureStateTableMeta } from "./global-feature-state-table";
 import { listQuery } from "./handlers/list.query";
@@ -67,11 +72,26 @@ export function createFeatureTogglesFeature(
       registered: r.queryHandler(registeredQuery),
     };
 
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: TOGGLE_ADMIN_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "ToggleAdminScreen" } },
+      type: "projectionList",
+      query: FeatureToggleQueries.registered,
+      columns: [
+        { field: "name", label: "feature-toggles.admin.col.feature" },
+        { field: "defaultLabel", label: "feature-toggles.admin.col.default" },
+        { field: "overrideLabel", label: "feature-toggles.admin.col.override" },
+        { field: "effectiveLabel", label: "feature-toggles.admin.col.effective" },
+      ],
+      rowActions: [
+        {
+          kind: "writeHandler",
+          id: "toggle",
+          label: "feature-toggles.admin.toggle",
+          handler: FeatureToggleHandlers.set,
+          payload: { map: { featureName: "name", enabled: "nextEnabled" } },
+          visible: { field: "toggleable", eq: true },
+        },
+      ],
       access: { roles: ["SystemAdmin"] },
     });
     r.nav({

package/src/feature-toggles/handlers/registered.query.ts

@@ -12,6 +12,12 @@ import { globalFeatureStateTable } from "../global-feature-state-table";
 // Design: registry introspection (toggleable/default/requires) + a single
 // DB read of overrides. No per-feature DB calls. Scales to however many
 // features an app registers — currently tens, never thousands.
+
+function formatFlag(value: boolean | null): string {
+  if (value === null) return "inherit";
+  return value ? "on" : "off";
+}
+
 export const registeredQuery = defineQueryHandler({
   name: "registered",
   schema: z.object({}),
@@ -38,38 +44,43 @@ export const registeredQuery = defineQueryHandler({
     // dokumentiert in DispatcherOptions.effectiveFeatures.
     const effective = ctx.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
-    const items: Array<{
+    const rows: Array<{
+      id: string;
       name: string;
       toggleable: boolean;
       default: boolean | null;
       override: boolean | null;
       requires: readonly string[];
       effective: boolean | null;
+      defaultLabel: string;
+      overrideLabel: string;
+      effectiveLabel: string;
+      nextEnabled: boolean;
     }> = [];
+
     for (const feature of ctx.registry.features.values()) {
       const toggleable = feature.toggleableDefault !== undefined;
       const override = overrides.get(feature.name);
-      items.push({
+      const defaultValue = feature.toggleableDefault ?? null;
+      const effectiveValue = effective ? effective.has(feature.name) : null;
+      const effectiveBool = effectiveValue ?? defaultValue ?? false;
+
+      rows.push({
+        id: feature.name,
         name: feature.name,
         toggleable,
-        // `default` is null when non-toggleable; the UI must render
-        // non-toggleable features as "always on" without an enable/disable
-        // control (flipping them would be rejected by the set-handler).
-        default: feature.toggleableDefault ?? null,
-        // `override` is null when no explicit row exists. That's distinct
-        // from "override says on" or "override says off" so the UI can show
-        // an "inherits default" indicator.
+        // Raw booleans for API consumers; label fields for projectionList columns.
+        default: defaultValue,
         override: override ?? null,
         requires: feature.requires,
-        // Effective = what the dispatcher-gate actually uses right now,
-        // after cascade. When the feature-toggles runtime isn't wired
-        // (dev setup without the feature loaded), we surface null so the
-        // UI knows the runtime isn't available rather than defaulting
-        // to "everything on".
-        effective: effective ? effective.has(feature.name) : null,
+        effective: effectiveValue,
+        defaultLabel: formatFlag(defaultValue),
+        overrideLabel: formatFlag(override ?? null),
+        effectiveLabel: formatFlag(effectiveValue),
+        nextEnabled: !effectiveBool,
       });
     }
 
-    return { items };
+    return { rows, nextCursor: null };
   },
 });

package/src/feature-toggles/i18n.ts

@@ -3,4 +3,9 @@ type LocalizedString = { readonly en: string };
 export const FEATURE_TOGGLES_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:toggle-admin.title": { en: "Feature toggles" },
   "feature-toggles:nav.toggleAdmin": { en: "Feature toggles" },
+  "feature-toggles.admin.col.feature": { en: "Feature" },
+  "feature-toggles.admin.col.default": { en: "Default" },
+  "feature-toggles.admin.col.override": { en: "Override" },
+  "feature-toggles.admin.col.effective": { en: "Effective" },
+  "feature-toggles.admin.toggle": { en: "Toggle" },
 };

package/src/feature-toggles/web/client-plugin.tsx

@@ -1,9 +1,8 @@
 // @runtime client
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import { FEATURE_TOGGLES_FEATURE, TOGGLE_ADMIN_SCREEN_ID } from "../constants";
+import { FEATURE_TOGGLES_FEATURE } from "../constants";
 import { defaultTranslations } from "./i18n";
-import { ToggleAdminScreen } from "./toggle-admin-screen";
 
 export type FeatureTogglesClientOptions = {
   readonly translations?: TranslationsByLocale;
@@ -15,8 +14,5 @@ export function featureTogglesClient(
   return {
     name: FEATURE_TOGGLES_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
-    components: {
-      [TOGGLE_ADMIN_SCREEN_ID]: ToggleAdminScreen,
-    },
   };
 }

package/src/feature-toggles/web/index.ts

@@ -3,4 +3,3 @@ export {
   type FeatureTogglesClientOptions,
   featureTogglesClient,
 } from "./client-plugin";
-export { ToggleAdminScreen } from "./toggle-admin-screen";

package/src/file-derivatives/feature.ts

@@ -112,12 +112,10 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     // dispatch even when the httpRoute below isn't mounted, bypassing the
     // "tenantId comes from the host, never the payload" invariant that only
     // `resolveApexTenant` enforces.
-    const queries: { publicVariant?: ReturnType<typeof r.queryHandler> } = {};
-
     if (opts.resolveApexTenant) {
       const resolveApexTenant = opts.resolveApexTenant;
 
-      queries.publicVariant = r.queryHandler(publicVariantQuery);
+      r.queryHandler(publicVariantQuery);
 
       r.httpRoute({
         method: "GET",
@@ -180,8 +178,6 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
         },
       });
     }
-
-    return { queries };
   });
 }
 

package/src/secrets/handlers/delete.write.ts

@@ -21,7 +21,3 @@ export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS)
     },
   });
 }
-
-// Backwards-compat: existing imports of `deleteWrite` keep working —
-// identical to createDeleteHandler() with the default access.
-export const deleteWrite = createDeleteHandler();

package/src/secrets/handlers/list.query.ts

@@ -38,7 +38,3 @@ export function createListHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
     },
   });
 }
-
-// Backwards-compat: existing imports of `listQuery` keep working — identical
-// to createListHandler() with the default access.
-export const listQuery = createListHandler();

package/src/secrets/handlers/set.write.ts

@@ -44,10 +44,6 @@ export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   });
 }
 
-// Backwards-compat: existing imports of `setWrite` keep working — identical
-// to createSetHandler() with the default access.
-export const setWrite = createSetHandler();
-
 // Fallback redaction: show at most the first 3 chars + trailing bullets.
 // Deliberately conservative — a too-generous preview defeats the point.
 function defaultRedact(value: string): string {

package/src/secrets/index.ts

@@ -13,11 +13,11 @@ export {
   TENANT_SECRET_READ_EVENT,
   tenantSecretsTable,
 } from "./feature";
-export { createDeleteHandler, deleteWrite } from "./handlers/delete.write";
-export { createListHandler, listQuery } from "./handlers/list.query";
+export { createDeleteHandler } from "./handlers/delete.write";
+export { createListHandler } from "./handlers/list.query";
 export {
   type RotateJobPayload,
   type RotateJobResult,
   rotateJob,
 } from "./handlers/rotate.job";
-export { createSetHandler, setWrite } from "./handlers/set.write";
+export { createSetHandler } from "./handlers/set.write";

package/src/tags/__tests__/feature.test.ts

@@ -48,7 +48,7 @@ function rawQueryAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch
 }
 
 describe("createTagsFeature shape", () => {
-  test("registers tag + tag-assignment entities, 5 write-handlers, 2 query-handlers", () => {
+  test("registers tag + tag-assignment entities, legacy + convention CRUD handlers", () => {
     const feature = createTagsFeature();
 
     expect(Object.keys(feature.entities ?? {})).toEqual(
@@ -62,17 +62,21 @@ describe("createTagsFeature shape", () => {
         expect.stringMatching(/delete-tag/),
         expect.stringMatching(/assign-tag/),
         expect.stringMatching(/remove-tag/),
+        "tag:create",
+        "tag:update",
+        "tag:delete",
       ]),
     );
-    expect(Object.keys(feature.writeHandlers)).toHaveLength(5);
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(8);
 
     expect(Object.keys(feature.queryHandlers)).toEqual(
       expect.arrayContaining([
         expect.stringMatching(/tag:list/),
         expect.stringMatching(/tag-assignment:list/),
+        "tag:detail",
       ]),
     );
-    expect(Object.keys(feature.queryHandlers)).toHaveLength(2);
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(3);
   });
 });
 
@@ -102,10 +106,19 @@ describe("createTagsFeature access-options", () => {
 
   test("access:{openToAll} applies to every write- and query-path", () => {
     const feature = createTagsFeature({ access: { openToAll: true } });
-    for (const path of ["create-tag", "update-tag", "delete-tag", "assign-tag", "remove-tag"]) {
+    for (const path of [
+      "create-tag",
+      "update-tag",
+      "delete-tag",
+      "tag:create",
+      "tag:update",
+      "tag:delete",
+      "assign-tag",
+      "remove-tag",
+    ]) {
       expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
     }
-    for (const query of ["tag:list", "tag-assignment:list"]) {
+    for (const query of ["tag:list", "tag:detail", "tag-assignment:list"]) {
       expect(rawQueryAccess(feature, query)).toEqual({ openToAll: true });
     }
   });

package/src/tags/__tests__/tag-screens.boot.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { TAGS_EDIT_SCREEN_ID, TAGS_SCREEN_ID } from "../constants";
+import { createTagsFeature } from "../feature";
+
+// QN convention: entityList loads tags:query:tag:list; entityEdit loads
+// tags:query:tag:detail and saves via tags:write:tag:{create,update,delete}.
+// Legacy create-tag/update-tag/delete-tag stay registered for TagManager.
+
+describe("tags catalog screens (entityList + entityEdit)", () => {
+  const feature = createTagsFeature();
+
+  test("boot-validates with declarative tag-list + tag-edit", () => {
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("tag-list is entityList gated by default tag roles", () => {
+    const list = feature.screens[TAGS_SCREEN_ID];
+    expect(list?.type).toBe("entityList");
+    expect(list?.access).toEqual({ roles: ["TenantAdmin", "TenantMember"] });
+  });
+
+  test("tag-edit is entityEdit with matching access", () => {
+    const edit = feature.screens[TAGS_EDIT_SCREEN_ID];
+    expect(edit?.type).toBe("entityEdit");
+    expect(edit?.access).toEqual({ roles: ["TenantAdmin", "TenantMember"] });
+  });
+
+  test("convention handlers sit beside legacy create-tag/update-tag/delete-tag", () => {
+    expect(Object.keys(feature.writeHandlers)).toEqual(
+      expect.arrayContaining([
+        "create-tag",
+        "update-tag",
+        "delete-tag",
+        "tag:create",
+        "tag:update",
+        "tag:delete",
+      ]),
+    );
+    expect(Object.keys(feature.queryHandlers)).toEqual(
+      expect.arrayContaining(["tag:list", "tag:detail", "tag-assignment:list"]),
+    );
+  });
+
+  test("createTagsFeature({ roles }) threads access onto both screens", () => {
+    const custom = createTagsFeature({ roles: ["Admin"] });
+    expect(custom.screens[TAGS_SCREEN_ID]?.access).toEqual({ roles: ["Admin"] });
+    expect(custom.screens[TAGS_EDIT_SCREEN_ID]?.access).toEqual({ roles: ["Admin"] });
+    expect(custom.writeHandlers["tag:delete"]?.access).toEqual({ roles: ["Admin"] });
+  });
+});

package/src/tags/constants.ts

@@ -25,9 +25,10 @@ export const TAGS_FILTER_EXTENSION_NAME = "TagFilter";
 // after mounting tagsClient() (which registers it under clientFeatures.columnRenderers).
 export const TAGS_COLUMN_RENDERER_NAME = "TagsCell";
 
-// Screen-id of the standalone Tags management screen (custom screen rendering
-// TagManager). Qualified = "tags:screen:tag-list"; the app places it via r.nav.
+// Screen-ids for the declarative tag catalog (entityList + entityEdit).
+// Qualified list = "tags:screen:tag-list"; the app places it via r.nav.
 export const TAGS_SCREEN_ID = "tag-list";
+export const TAGS_EDIT_SCREEN_ID = "tag-edit";
 
 // Qualified handler names (QN format: scope:type:name). Clients reference the
 // object instead of magic strings (mirror custom-fields' Handlers/Queries).

package/src/tags/entity.ts

@@ -15,6 +15,8 @@ export const tagEntity = createEntity({
     name: createTextField({
       required: true,
       maxLength: 64,
+      sortable: true,
+      searchable: true,
       personal: false,
       reason: "catalog_label",
     }),

package/src/tags/feature.ts

@@ -14,15 +14,18 @@
 //
 // Handlers: create-tag, update-tag (rename/recolor/re-scope), delete-tag
 // (cascades over assignments), assign-tag, remove-tag, list tags, list assignments.
+// Convention aliases tag:{create,update,delete} + tag:detail back the
+// entityList/entityEdit catalog screens (legacy QNs stay for TagManager).
 // Deferred: optional host-projection decoration (`wireTagsFor`), search indexing.
 
 import {
   type AccessRule,
+  defineEntityDetailHandler,
   defineEntityListHandler,
   defineFeature,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME, TAGS_SCREEN_ID } from "./constants";
+import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants";
 import { tagAssignmentEntity, tagEntity } from "./entity";
 import { createAssignTagHandler } from "./handlers/assign-tag.write";
 import { createCreateTagHandler } from "./handlers/create-tag.write";
@@ -30,6 +33,7 @@ import { createDeleteTagHandler } from "./handlers/delete-tag.write";
 import { createRemoveTagHandler } from "./handlers/remove-tag.write";
 import { createUpdateTagHandler } from "./handlers/update-tag.write";
 import { TAGS_FEATURE_I18N } from "./i18n";
+import { createTagEditScreen, createTagListScreen } from "./screens";
 
 // Opt-in tier-gating: when set, the feature declares itself r.toggleable so the
 // dispatcher gate + feature-toggles + tier-engine can switch the WHOLE feature
@@ -66,18 +70,20 @@ function registerTags(
   r.writeHandler(createAssignTagHandler(access));
   r.writeHandler(createRemoveTagHandler(access));
 
+  // Convention aliases for entityList/entityEdit — same bodies as the legacy
+  // create-tag/update-tag/delete-tag QNs (TagManager/TagPicker keep those).
+  r.writeHandler(createCreateTagHandler(access, "tag:create"));
+  r.writeHandler(createUpdateTagHandler(access, "tag:update"));
+  r.writeHandler(createDeleteTagHandler(access, "tag:delete"));
+
   r.queryHandler(defineEntityListHandler("tag", tagEntity, { access }));
   r.queryHandler(defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access }));
+  r.queryHandler(defineEntityDetailHandler("tag", tagEntity, { access }));
 
-  // Standalone Tags management screen (custom React: TagManager). The app places
-  // it in nav via r.nav("tags:screen:tag-list"); tagsClient() maps the component.
-  // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
-  r.screen({
-    id: TAGS_SCREEN_ID,
-    type: "custom",
-    renderer: { react: { __component: "TagsScreen" } },
-    access,
-  });
+  // Standalone catalog: entityList + entityEdit. App navs via
+  // r.nav("tags:screen:tag-list"). TagManager stays for picker/section only.
+  r.screen(createTagListScreen(access));
+  r.screen(createTagEditScreen(access));
   r.translations({ keys: TAGS_FEATURE_I18N });
 }
 

package/src/tags/handlers/create-tag.write.ts

@@ -7,9 +7,12 @@ import { type CreateTagPayload, createTagPayloadSchema } from "../schemas";
 // UUIDv7 id (no explicit id passed). Tag names are not unique by design: the
 // catalog is a free list and dedup is a UI concern (autocomplete from existing
 // tags). Editing is update-tag.write.ts; delete (with cascade) is delete-tag.write.ts.
-export function createCreateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+export function createCreateTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  name = "create-tag",
+): WriteHandlerDef {
   return {
-    name: "create-tag",
+    name,
     schema: createTagPayloadSchema,
     access,
     handler: async (event, ctx) => {

package/src/tags/handlers/delete-tag.write.ts

@@ -16,9 +16,12 @@ const CASCADE_PAGE = 200;
 // hides isDeleted rows, so a keyset cursor over the shrinking result set would
 // silently skip rows. Re-reading the head always returns the remaining live
 // rows and terminates when none are left.
-export function createDeleteTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+export function createDeleteTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  name = "delete-tag",
+): WriteHandlerDef {
   return {
-    name: "delete-tag",
+    name,
     schema: deleteTagPayloadSchema,
     access,
     handler: async (event, ctx) => {

package/src/tags/handlers/update-tag.write.ts

@@ -8,9 +8,12 @@ import { type UpdateTagPayload, updateTagPayloadSchema } from "../schemas";
 // the fields present in the payload go into `changes`, and the executor merges
 // shallowly, so any omitted field is preserved (color/scope accept "" to clear).
 // A stale version returns version_conflict; the UI refetches and retries.
-export function createUpdateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+export function createUpdateTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  name = "update-tag",
+): WriteHandlerDef {
   return {
-    name: "update-tag",
+    name,
     schema: updateTagPayloadSchema,
     access,
     handler: async (event, ctx) => {

package/src/tags/i18n.ts

@@ -2,4 +2,8 @@ type LocalizedString = { readonly en: string };
 
 export const TAGS_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:tag-list.title": { en: "Tags" },
+  "screen:tag-edit.title": { en: "Tag" },
+  "tags:entity:tag:field:name": { en: "Name" },
+  "tags:entity:tag:field:color": { en: "Color" },
+  "tags:entity:tag:field:scope": { en: "Scope" },
 };

package/src/tags/index.ts

@@ -3,6 +3,7 @@ export {
   DEFAULT_TAG_ACCESS,
   DEFAULT_TAG_ROLES,
   TAGS_COLUMN_RENDERER_NAME,
+  TAGS_EDIT_SCREEN_ID,
   TAGS_FEATURE_NAME,
   TAGS_FILTER_EXTENSION_NAME,
   TAGS_SCREEN_ID,
@@ -44,3 +45,4 @@ export {
   type UpdateTagPayload,
   updateTagPayloadSchema,
 } from "./schemas";
+export { createTagEditScreen, createTagListScreen } from "./screens";

package/src/tags/screens.ts

@@ -0,0 +1,66 @@
+import type {
+  AccessRule,
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS, TAGS_EDIT_SCREEN_ID, TAGS_SCREEN_ID } from "./constants";
+
+// Declarative catalog screens (Phase-3 / #2312). Access matches create/update/
+// delete so createTagsFeature({ access|roles }) stays consistent. TagManager
+// remains for TagPicker/TagSection — only the standalone admin screen moved.
+
+export function createTagListScreen(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+): EntityListScreenDefinition {
+  return {
+    id: TAGS_SCREEN_ID,
+    type: "entityList",
+    entity: "tag",
+    columns: ["name", "color", "scope"],
+    defaultSort: { field: "name", dir: "asc" },
+    searchable: true,
+    rowActions: [
+      {
+        kind: "navigate",
+        id: "edit",
+        label: "kumiko.actions.edit",
+        screen: TAGS_EDIT_SCREEN_ID,
+        entityId: "id",
+      },
+      {
+        kind: "writeHandler",
+        id: "delete",
+        label: "kumiko.actions.delete",
+        // Convention QN — same cascade body as legacy tags:write:delete-tag.
+        handler: "tags:write:tag:delete",
+        payload: { pick: ["id"] },
+        confirm: "kumiko.actions.delete-confirm",
+        style: "danger",
+      },
+    ],
+    access,
+  };
+}
+
+export function createTagEditScreen(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+): EntityEditScreenDefinition {
+  return {
+    id: TAGS_EDIT_SCREEN_ID,
+    type: "entityEdit",
+    entity: "tag",
+    layout: {
+      sections: [
+        {
+          columns: 2,
+          fields: [
+            { field: "name", span: 2 },
+            { field: "color", span: 1 },
+            { field: "scope", span: 1 },
+          ],
+        },
+      ],
+    },
+    access,
+  };
+}

package/src/tags/web/client-plugin.tsx

@@ -5,12 +5,10 @@ import {
   TAGS_COLUMN_RENDERER_NAME,
   TAGS_FEATURE_NAME,
   TAGS_FILTER_EXTENSION_NAME,
-  TAGS_SCREEN_ID,
   TAGS_SECTION_EXTENSION_NAME,
 } from "../constants";
 import { defaultTranslations } from "./i18n";
 import { TagFilter } from "./tag-filter";
-import { TagManager } from "./tag-manager";
 import { TagSection } from "./tag-section";
 import { TagsCell } from "./tags-cell";
 
@@ -26,10 +24,7 @@ export function tagsClient(): ClientFeatureDefinition {
     columnRenderers: {
       [TAGS_COLUMN_RENDERER_NAME]: TagsCell,
     },
-    // Standalone Tags management screen (custom screen → TagManager).
-    components: {
-      [TAGS_SCREEN_ID]: TagManager,
-    },
+    // Catalog screen is declarative entityList — no custom TagsScreen mount.
     translations: defaultTranslations,
   };
 }

package/src/tags/web/index.ts

@@ -1,6 +1,7 @@
 // @runtime client
 export {
   TAGS_COLUMN_RENDERER_NAME,
+  TAGS_EDIT_SCREEN_ID,
   TAGS_FILTER_EXTENSION_NAME,
   TAGS_SCREEN_ID,
   TAGS_SECTION_EXTENSION_NAME,

package/src/tenant/__tests__/members-screens.boot.test.ts

@@ -74,7 +74,7 @@ describe("tenant members screen + handler access alignment", () => {
     const rowAction = screen.rowActions?.find((a) => a.id === "edit-roles");
     if (rowAction?.kind !== "navigate") throw new Error("expected a navigate row action");
     expect(rowAction.screen).toBe(MEMBER_ROLES_EDIT_SCREEN_ID);
-    expect(rowAction.params).toEqual({ map: { userId: "userId" } });
+    expect(rowAction.params).toEqual({ map: { userId: "userId", roles: "roles" } });
     expect(rowAction.visible).toEqual({ field: "status", eq: "active" });
   });
 
@@ -85,6 +85,11 @@ describe("tenant members screen + handler access alignment", () => {
       throw new Error("expected member-roles-edit screen to be actionForm");
     expect(screen.handler).toBe(TenantHandlers.updateMemberRoles);
     expect(screen.fields["userId"]).toEqual({ type: "text", required: true });
+    const section = screen.layout.sections[0];
+    if (section === undefined || !("fields" in section)) {
+      throw new Error("expected member-roles-edit layout fields section");
+    }
+    expect(section.fields).toEqual([{ field: "userId", readOnly: true }, "roles"]);
     expect(screen.fields["roles"]).toEqual({
       type: "multiSelect",
       options: DEFAULT_INVITE_ROLE_OPTIONS,

package/src/tenant/__tests__/tenant-security.integration.test.ts

@@ -859,6 +859,40 @@ describe("updateMemberRoles — TenantAdmin session-scoped path and safety gates
     expect(JSON.parse(rows[0]?.["roles"] as string)).toEqual(["Admin"]);
   });
 
+  test("SystemAdmin omits payload.tenantId — uses session tenant (actionForm UI shape)", async () => {
+    const { id: memberUserId } = await seedUser(stack.db, {
+      email: "sysadmin-session-tenant@example.com",
+      displayName: "SysAdmin Session Tenant",
+      passwordHash: await hashPassword("pw-sys-sess-1234"),
+      emailVerified: true,
+    });
+    await seedTenantMembership(stack.db, {
+      userId: memberUserId,
+      tenantId: TENANT_A_ID,
+      roles: ["User"],
+    });
+
+    // Mirrors prod: SystemAdmin with an active tenant opens Edit roles; the
+    // actionForm only posts userId+roles (no tenantId field).
+    const sysAdminInTenant: SessionUser = {
+      id: TestUsers.systemAdmin.id,
+      tenantId: TENANT_A_ID,
+      roles: ["SystemAdmin", "TenantAdmin"],
+    };
+    const res = await stack.http.writeOk(
+      TenantHandlers.updateMemberRoles,
+      { userId: memberUserId, roles: ["Admin"] },
+      sysAdminInTenant,
+    );
+    expect(res).toMatchObject({ userId: memberUserId, tenantId: TENANT_A_ID, roles: ["Admin"] });
+
+    const rows = await selectMany(stack.db, tenantMembershipsTable, {
+      userId: memberUserId,
+      tenantId: TENANT_A_ID,
+    });
+    expect(JSON.parse(rows[0]?.["roles"] as string)).toEqual(["Admin"]);
+  });
+
   test("updateMemberRoles appends audit event and invalidates active sessions for target user", async () => {
     const { id: memberUserId } = await seedUser(stack.db, {
       email: "session-target@example.com",

package/src/tenant/handlers/team-list.query.ts

@@ -223,7 +223,9 @@ export const teamListQuery = definePagedQueryHandler({
     // the order of a few thousand members per tenant; past that the fix is
     // a real combined read-projection (a materialized view/table kept in
     // sync by both tenant-membership and tenant-invitation events), not a
-    // cursor bolted onto this merge.
+    // cursor bolted onto this merge. Upgrade path: r.multiStreamProjection({
+    // name, apply }) — see custom-fields/wire-for-entity.ts:174,
+    // feature-toggles/feature.ts:109, step-dispatcher/feature.ts:41.
     const search = query.payload.search?.trim().toLowerCase();
     const merged = [...memberRows, ...invitationRows].filter((row) => {
       if (search === undefined || search === "") return true;

package/src/tenant/handlers/update-member-roles.write.ts

@@ -41,6 +41,16 @@ const REVOKE_ALL_SESSIONS_QN = "sessions:write:user-session:revoke-all-for-user"
 // (dispatcher batch wraps handlers in transaction — xact lock holds through update).
 const LAST_TENANT_ADMIN_LOCK_NAMESPACE = 0x7461646d; // 'tadm'
 
+/** SystemAdmin may pass payload.tenantId (cross-tenant); the members actionForm
+ *  only sends userId+roles, so fall back to the active session tenant. */
+function resolveTargetTenantId(
+  isSystem: boolean,
+  payloadTenantId: string | undefined,
+  sessionTenantId: string | undefined,
+): string | undefined {
+  return isSystem ? (payloadTenantId ?? sessionTenantId) : sessionTenantId;
+}
+
 export const updateMemberRolesWrite = defineWriteHandler({
   name: "updateMemberRoles",
   schema: z.object({
@@ -63,7 +73,11 @@ export const updateMemberRolesWrite = defineWriteHandler({
 
     const isSystem =
       event.user.roles.includes("SystemAdmin") || event.user.roles.includes("system");
-    const targetTenantId = isSystem ? event.payload.tenantId : event.user.tenantId;
+    const targetTenantId = resolveTargetTenantId(
+      isSystem,
+      event.payload.tenantId,
+      event.user.tenantId,
+    );
     if (!targetTenantId) {
       return writeFailure(
         new ValidationError({

package/src/tenant/i18n.ts

@@ -22,7 +22,6 @@ export const TENANT_I18N: Readonly<Record<string, LocalizedString>> = {
   },
   "tenant.members.invite.title": { en: "New invitation" },
   "tenant.members.invite.submit": { en: "Send invitation" },
-  "tenant.members.roles.edit.title": { en: "Edit roles" },
   "tenant.members.roles.edit.submit": { en: "Save roles" },
   "tenant:entity:__action-form__:field:email": { en: "Email" },
   "tenant:entity:__action-form__:field:role": { en: "Role" },

package/src/tenant/screens.ts

@@ -113,7 +113,7 @@ export function createMembersScreen(options?: {
         id: "edit-roles",
         label: "tenant.members.actions.editRoles",
         screen: MEMBER_ROLES_EDIT_SCREEN_ID,
-        params: { map: { userId: "userId" } },
+        params: { map: { userId: "userId", roles: "roles" } },
         visible: { field: "status", eq: "active" },
       },
       {
@@ -172,7 +172,8 @@ export const memberRolesEditScreen = {
     roles: { type: "multiSelect", options: DEFAULT_INVITE_ROLE_OPTIONS, required: true },
   },
   layout: {
-    sections: [{ fields: ["userId", "roles"] }],
+    // Prefill userId from rowAction; readOnly so the operator cannot retarget.
+    sections: [{ fields: [{ field: "userId", readOnly: true }, "roles"] }],
   },
   submitLabel: "tenant.members.roles.edit.submit",
   access: { roles: access.admin },

package/src/user/handlers/update-roles.ts

@@ -15,6 +15,7 @@ import {
 import {
   AccessDeniedError,
   ConflictError,
+  InternalError,
   NotFoundError,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
@@ -51,7 +52,10 @@ function isActiveSystemAdminRow(row: UserRolesRow): boolean {
 }
 
 async function countOtherActiveSystemAdmins(db: TenantDb, excludeUserId: string): Promise<number> {
-  const tableName = asEntityTableMeta(userTable)?.tableName ?? "read_users";
+  const tableName = asEntityTableMeta(userTable)?.tableName;
+  if (!tableName) {
+    throw new InternalError({ message: "user read table meta missing" });
+  }
   // kumiko-lint-ignore raw-sql jsonb @> prefilter for SystemAdmin roster under advisory lock
   const rows = (await asRawClient(db.raw).unsafe(
     `SELECT id, roles, status, is_deleted AS "isDeleted"

package/src/user/i18n.ts

@@ -7,12 +7,6 @@ export const USER_I18N: Readonly<Record<string, LocalizedString>> = {
   "user:entity:user:field:displayName": { en: "Display name" },
   "user:entity:user:field:roles": { en: "Platform roles" },
   "user:entity:user:field:tenants": { en: "Tenants" },
-  "user:entity:user:field:tenants:description": {
-    en: "Membership tenants with roles, e.g. Offlot Demo (TenantAdmin). Edit under Team → Members.",
-  },
-  "user:entity:user:field:roles:description": {
-    en: "Global platform roles only (SystemAdmin). TenantAdmin/Admin are membership roles under Team → Members.",
-  },
   "user:entity:user:field:roles:option:SystemAdmin": { en: "SystemAdmin" },
   "user:entity:user:field:status": { en: "Status" },
   "user:entity:user:field:emailVerified": { en: "Email verified" },

package/src/feature-toggles/web/toggle-admin-screen.tsx

@@ -1,137 +0,0 @@
-// @runtime client
-import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
-import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
-import { type ReactNode, useCallback, useEffect, useState } from "react";
-import { FeatureToggleHandlers, FeatureToggleQueries } from "../constants";
-
-type ToggleRow = {
-  readonly name: string;
-  readonly toggleable: boolean;
-  readonly default: boolean | null;
-  readonly override: boolean | null;
-  readonly effective: boolean | null;
-};
-
-type RegisteredResponse = {
-  readonly items: readonly ToggleRow[];
-};
-
-type State =
-  | { readonly kind: "loading" }
-  | { readonly kind: "error"; readonly message: string }
-  | { readonly kind: "ready"; readonly items: readonly ToggleRow[] };
-
-export function ToggleAdminScreen(): ReactNode {
-  const t = useTranslation();
-  const { Banner, Card, DataTable, Heading, Text } = usePrimitives();
-  const dispatcher = useDispatcher();
-  const [state, setState] = useState<State>({ kind: "loading" });
-  const [actionError, setActionError] = useState<string | null>(null);
-
-  const load = useCallback(async (): Promise<void> => {
-    setState({ kind: "loading" });
-    const res = await dispatcher.query<RegisteredResponse>(FeatureToggleQueries.registered, {});
-    if (!res.isSuccess) {
-      setState({ kind: "error", message: res.error.message });
-      return;
-    }
-    setState({ kind: "ready", items: res.data.items });
-  }, [dispatcher]);
-
-  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
-  useEffect(() => {
-    void load();
-  }, [load]);
-
-  const onSet = async (featureName: string, enabled: boolean): Promise<void> => {
-    setActionError(null);
-    const res = await dispatcher.write(FeatureToggleHandlers.set, { featureName, enabled });
-    if (!res.isSuccess) {
-      setActionError(res.error.message);
-      return;
-    }
-    await load();
-  };
-
-  if (state.kind === "loading") {
-    return (
-      <FormScreenShell testId="toggle-admin-screen">
-        <Text variant="small">{t("feature-toggles.admin.loading")}</Text>
-      </FormScreenShell>
-    );
-  }
-
-  if (state.kind === "error") {
-    return (
-      <FormScreenShell testId="toggle-admin-screen">
-        <Banner variant="error">{state.message}</Banner>
-      </FormScreenShell>
-    );
-  }
-
-  return (
-    <FormScreenShell testId="toggle-admin-screen" maxWidth="4xl" className="flex flex-col gap-6">
-      <Heading variant="page">{t("feature-toggles.admin.title")}</Heading>
-
-      {actionError !== null && <Banner variant="error">{actionError}</Banner>}
-
-      <Card options={{ padded: false }}>
-        <DataTable
-          testId="toggle-admin-table"
-          columns={[
-            {
-              field: "feature",
-              label: t("feature-toggles.admin.col.feature"),
-              type: "string",
-              sortable: false,
-            },
-            {
-              field: "default",
-              label: t("feature-toggles.admin.col.default"),
-              type: "string",
-              sortable: false,
-            },
-            {
-              field: "override",
-              label: t("feature-toggles.admin.col.override"),
-              type: "string",
-              sortable: false,
-            },
-            {
-              field: "effective",
-              label: t("feature-toggles.admin.col.effective"),
-              type: "string",
-              sortable: false,
-            },
-          ]}
-          rows={state.items.map((row) => ({
-            id: row.name,
-            values: {
-              feature: row.name,
-              default: formatFlag(row.default),
-              override: formatFlag(row.override),
-              effective: formatFlag(row.effective),
-              toggleable: row.toggleable,
-              effectiveBool: row.effective ?? row.default ?? false,
-            },
-          }))}
-          rowActions={[
-            {
-              id: "toggle",
-              label: t("feature-toggles.admin.toggle"),
-              style: "secondary",
-              isVisible: (row) => row.values["toggleable"] === true,
-              onTrigger: (row) => void onSet(row.id, !(row.values["effectiveBool"] as boolean)),
-            },
-          ]}
-          rowActionMode="inline"
-        />
-      </Card>
-    </FormScreenShell>
-  );
-}
-
-function formatFlag(value: boolean | null): string {
-  if (value === null) return "inherit";
-  return value ? "on" : "off";
-}