@k2b/cloud 0.6.0 → 0.8.0

package/src/_internal/postgres-application-name.ts

@@ -0,0 +1,30 @@
+/** Name Bun's default pool before its first use without changing connection ownership. */
+export const configurePostgresApplicationName = (
+  applicationId: string,
+  environment: Record<string, string | undefined> = process.env,
+): void => {
+  // Match Bun's precedence and preserve TLS_* variables, which imply required TLS.
+  const variable = ["DATABASE_URL", "DATABASEURL", "TLS_DATABASE_URL", "POSTGRES_URL", "PGURL", "PG_URL", "TLS_POSTGRES_DATABASE_URL"].find(
+    (key) => environment[key],
+  );
+  if (!variable) return;
+
+  let url: URL;
+  try {
+    url = new URL(environment[variable]!);
+  } catch {
+    // Diagnostics must not change how Bun handles an existing connection configuration.
+    return;
+  }
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") return;
+
+  let operatorConfigured = false;
+  url.searchParams.forEach((_value, key) => {
+    // options can contain an operator-owned `-c application_name=...` setting.
+    if (key.toLowerCase() === "application_name" || key.toLowerCase() === "options") operatorConfigured = true;
+  });
+  if (operatorConfigured) return;
+
+  url.searchParams.set("application_name", `cloud:${applicationId}`);
+  environment[variable] = url.toString();
+};

package/src/_internal/process-identity.ts

@@ -0,0 +1,15 @@
+/** Identity of the application started in this process, derived from its declaration. */
+let applicationId: string | undefined;
+
+export const getProcessApplicationId = (): string | undefined => applicationId;
+
+export const bindProcessApplicationId = (id: string): void => {
+  if (applicationId !== undefined && applicationId !== id) {
+    throw new Error(`This process already hosts application "${applicationId}"`);
+  }
+  applicationId = id;
+};
+
+export const clearProcessApplicationId = (): void => {
+  applicationId = undefined;
+};

package/src/_internal/process-sync.ts

@@ -82,7 +82,7 @@ export const startProcessSync = async ({ application }: { application: string })
         connection,
         namespace: env.SYNC_NAMESPACE,
         application,
-        defaults: { replicas: 3 },
+        defaults: { replicas: env.SYNC_REPLICAS },
         observe: (event) => observeSyncEvent(event, application),
       });
       bindProcessSync(sync);

package/src/_internal/readiness.ts

@@ -1,3 +1,6 @@
+import { buildMetadata } from "./build-metadata";
+
 export const APP_READINESS_PATH = "/_cloud/ready";
 
-export const appReadinessResponse = (appId: string): Response => Response.json({ status: "ready", appId });
+export const appReadinessResponse = (appId: string): Response =>
+  Response.json({ status: "ready", appId, version: buildMetadata.version, release: buildMetadata.release });

package/src/_internal/registry-validation.ts

@@ -39,11 +39,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     }
     for (const [locale, translation] of Object.entries(value.presentation.translations)) {
       if (!isRecord(translation)) return invalid(`presentation.translations.${locale}`, "an object");
-      if (translation.name !== undefined && !isString(translation.name)) return invalid(`presentation.translations.${locale}.name`, "a string");
+      if (translation.name !== undefined && !isString(translation.name))
+        return invalid(`presentation.translations.${locale}.name`, "a string");
       if (translation.description !== undefined && !isString(translation.description)) {
         return invalid(`presentation.translations.${locale}.description`, "a string");
       }
-      for (const field of ["adminGroups", "adminLinks", "legalLinks"] as const) {
+      for (const field of ["adminGroups", "adminLinks", "legalLinks", "searchLinks", "searchLinkDescriptions"] as const) {
         if (translation[field] !== undefined && !isStringRecord(translation[field])) {
           return invalid(`presentation.translations.${locale}.${field}`, "a string map");
         }
@@ -66,6 +67,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
         (group) =>
           !isRecord(group) ||
           (group.id !== undefined && !isString(group.id)) ||
+          (group.section !== undefined && group.section !== "ai") ||
           !isString(group.label) ||
           !Array.isArray(group.links) ||
           group.links.some((link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || !isString(link.icon)),
@@ -84,6 +86,23 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("legalLinks", "an array of valid links");
     }
   }
+  if (value.searchLinks !== undefined) {
+    if (
+      !Array.isArray(value.searchLinks) ||
+      value.searchLinks.some(
+        (link) =>
+          !isRecord(link) ||
+          !isString(link.label) ||
+          !link.label.trim() ||
+          (link.description !== undefined && !isString(link.description)) ||
+          !isString(link.href) ||
+          !/^\/(?![\/\\])[^\\\s]*$/.test(link.href) ||
+          (link.icon !== undefined && !isString(link.icon)) ||
+          (link.keywords !== undefined && !isStringArray(link.keywords)),
+      )
+    )
+      return invalid("searchLinks", "an array of same-origin navigation links");
+  }
   if (value.widgets !== undefined) {
     if (
       !Array.isArray(value.widgets) ||
@@ -102,32 +121,17 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("capabilities", "a valid capability summary");
     }
   }
-  if (value.help !== undefined) {
-    if (
-      !isRecord(value.help) ||
+  if (
+    value.help !== undefined &&
+    (!isRecord(value.help) ||
       !isString(value.help.manifestHash) ||
+      !isString(value.help.baseLocale) ||
       !isString(value.help.pageBase) ||
-      !Array.isArray(value.help.documents)
-    ) {
-      return invalid("help", "a valid Help summary");
-    }
-    if (
-      !value.help.pageBase.startsWith("/") ||
-      value.help.documents.some(
-        (document) =>
-          !isRecord(document) ||
-          !isString(document.id) ||
-          !isString(document.title) ||
-          typeof document.order !== "number" ||
-          !isString(document.searchUrl) ||
-          !document.searchUrl.startsWith("/") ||
-          !isString(document.url) ||
-          !document.url.startsWith("/"),
-      )
-    ) {
-      return invalid("help", "a valid Help summary");
-    }
+      !value.help.pageBase.startsWith("/"))
+  ) {
+    return invalid("help", "a valid Help reference");
   }
+
   if (value.openapi !== undefined && !isString(value.openapi)) return invalid("openapi", "a string");
   return null;
 };

package/src/_internal/registry.ts

@@ -1,7 +1,7 @@
 import type { EphemeralConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
-import type { AppRegistryEntry, CapabilityRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import type { DashboardWidgetPresentation } from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
@@ -10,7 +10,7 @@ import { validateAppRegistryEntry } from "./registry-validation";
 import { watchRegistryChanges } from "./registry-watch";
 
 /**
- * Shared app registry: three @k2b/sync ephemerals on the process Sync
+ * Shared app registry: two @k2b/sync ephemerals on the process Sync
  * instance. Apps, the gateway, and gateway-ops all declare them through the
  * functions below, so id, owner, TTL, and value bound stay identical across
  * the fleet (a differing declaration fails with ResourceDriftError).
@@ -34,20 +34,12 @@ export const CAPABILITY_REGISTRY_CONFIG = {
   maxValueBytes: 512 * 1024,
 } as const satisfies EphemeralConfig;
 
-export const HELP_REGISTRY_CONFIG = {
-  id: "cloud-help",
-  owner: REGISTRY_OWNER,
-  ttlMs: APP_REGISTRY_TTL_MS,
-  maxValueBytes: 512 * 1024,
-} as const satisfies EphemeralConfig;
-
 export const APP_REGISTRY_PREFIX = "apps/";
 
 export type CapabilityRegistryRecord = { appId: string; manifest: CapabilityManifest; presentation?: CapabilityPresentationCatalog };
 
 export const appRegistry = lazySync((sync) => sync.ephemeral<AppRegistryEntry>(APP_REGISTRY_CONFIG));
 export const capabilityRegistry = lazySync((sync) => sync.ephemeral<CapabilityRegistryRecord>(CAPABILITY_REGISTRY_CONFIG));
-export const helpRegistry = lazySync((sync) => sync.ephemeral<HelpRegistryEntry>(HELP_REGISTRY_CONFIG));
 
 /**
  * Follow the app registry until `signal` aborts. The watch first replays the
@@ -232,49 +224,6 @@ export const getCapability = async (appId: string): Promise<CapabilityRegistryEn
   return entry ? resolveLiveCapabilityRegistryEntry(entry.key, entry.value, app ?? undefined) : null;
 };
 
-const isHelpRegistryEntry = (value: unknown): value is HelpRegistryEntry => {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const entry = value as Partial<HelpRegistryEntry>;
-  const validDocument = (document: unknown) =>
-    !!document &&
-    typeof document === "object" &&
-    typeof (document as { id?: unknown }).id === "string" &&
-    typeof (document as { title?: unknown }).title === "string" &&
-    typeof (document as { order?: unknown }).order === "number" &&
-    typeof (document as { markdown?: unknown }).markdown === "string" &&
-    ((document as { searchText?: unknown }).searchText === undefined ||
-      typeof (document as { searchText?: unknown }).searchText === "string") &&
-    ((document as { icon?: unknown }).icon === undefined || typeof (document as { icon?: unknown }).icon === "string") &&
-    ((document as { description?: unknown }).description === undefined ||
-      typeof (document as { description?: unknown }).description === "string");
-  return (
-    typeof entry.appId === "string" &&
-    typeof entry.appName === "string" &&
-    typeof entry.appIcon === "string" &&
-    typeof entry.manifestHash === "string" &&
-    (entry.baseLocale === undefined || typeof entry.baseLocale === "string") &&
-    Array.isArray(entry.documents) &&
-    entry.documents.every(validDocument) &&
-    (entry.documentsByLocale === undefined ||
-      (!!entry.documentsByLocale &&
-        typeof entry.documentsByLocale === "object" &&
-        !Array.isArray(entry.documentsByLocale) &&
-        Object.values(entry.documentsByLocale).every((documents) => Array.isArray(documents) && documents.every(validDocument))))
-  );
-};
-
-export const listHelp = async (): Promise<HelpRegistryEntry[]> => {
-  const snap = await helpRegistry().snapshot({ prefix: "help/" });
-  return snap.entries.map((entry) => entry.value).filter(isHelpRegistryEntry);
-};
-
-export const getHelp = async (appId: string): Promise<HelpRegistryEntry | null> => {
-  const key = `help/${appId}`;
-  const snap = await helpRegistry().snapshot({ prefix: key });
-  const value = snap.entries.find((entry) => entry.key === key)?.value;
-  return isHelpRegistryEntry(value) ? value : null;
-};
-
 /**
  * Same as `listApps` but returns registry metadata for admin observability.
  */

package/src/_internal/runtime-context.ts

@@ -29,6 +29,8 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
                   adminGroups: translation.adminGroups ? { ...translation.adminGroups } : undefined,
                   adminLinks: translation.adminLinks ? { ...translation.adminLinks } : undefined,
                   legalLinks: translation.legalLinks ? { ...translation.legalLinks } : undefined,
+                  searchLinks: translation.searchLinks ? { ...translation.searchLinks } : undefined,
+                  searchLinkDescriptions: translation.searchLinkDescriptions ? { ...translation.searchLinkDescriptions } : undefined,
                 },
               ]),
             ),
@@ -37,6 +39,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       appearance: e.appearance,
       adminHref: e.nav?.adminHref,
       adminNav: e.adminNav?.map((group) => ({
+        ...(group.section ? { section: group.section } : {}),
         id: group.id,
         label: group.label,
         links: group.links.map((link) => ({ ...link })),
@@ -53,22 +56,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
             requiresRoles: e.nav.requiresRoles as Role[] | undefined,
           }
         : undefined,
-      help: e.help
-        ? {
-            manifestHash: e.help.manifestHash,
-            pageBase: e.help.pageBase,
-            baseLocale: e.help.baseLocale,
-            documentsByLocale: e.help.documentsByLocale
-              ? Object.fromEntries(
-                  Object.entries(e.help.documentsByLocale).map(([locale, documents]) => [
-                    locale,
-                    documents.map((document) => ({ ...document })),
-                  ]),
-                )
-              : undefined,
-            documents: e.help.documents.map((document) => ({ ...document })),
-          }
-        : undefined,
+      help: e.help ? { ...e.help } : undefined,
       searchTags,
       searchHelp: searchQueries?.map((query) => query.description).join(" "),
       searchTagHelp: searchQueries?.flatMap((query) =>
@@ -78,6 +66,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
         ]),
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+      searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
       openapi: e.openapi,
     };
   }),

package/src/_internal/server-timing.ts

@@ -0,0 +1,13 @@
+import type { Context } from "hono";
+
+type Phase = "auth" | "settings" | "runtime" | "ssr_data" | "ssr_finalize" | "ssr_render";
+
+/** Measure the owning operation, not downstream middleware or another request. */
+export async function measureServerPhase<T>(c: Context, phase: Phase, operation: () => T | Promise<T>): Promise<T> {
+  const start = performance.now();
+  try {
+    return await operation();
+  } finally {
+    c.header("Server-Timing", `${phase};dur=${(performance.now() - start).toFixed(2)}`, { append: true });
+  }
+}

package/src/_internal/status-preserving-ssr.ts

@@ -2,10 +2,20 @@ import type { HtmlFn, RenderFn } from "@k2b/ssr";
 import { createSSRHandler } from "@k2b/ssr/hono";
 import type { Context, Env, MiddlewareHandler, TypedResponse } from "hono";
 import type { StatusCode } from "hono/utils/http-status";
-import type { RailPreferences } from "../contracts/rail-preferences";
+import type { RailSnapshot } from "../contracts/rail-preferences";
+import type { SettingsFlat, Unflatten } from "../contracts/settings-types";
 import type { User } from "../contracts/shared";
+import type { CORE_SETTINGS } from "../services/settings/core-settings";
+import { measureServerPhase } from "./server-timing";
 
-type PageEnv<T extends object> = { Variables: { page: Partial<T>; user?: User; railPreferences?: RailPreferences } };
+type PageEnv<T extends object> = {
+  Variables: {
+    page: Partial<T>;
+    user?: User;
+    railPreferences?: RailSnapshot;
+    settings?: Unflatten<SettingsFlat<typeof CORE_SETTINGS>>;
+  };
+};
 type SsrHandlerResult = RenderFn | Response | TypedResponse;
 type SsrHandler<E extends Env, T extends object> = (context: Context<E & PageEnv<T>>) => SsrHandlerResult | Promise<SsrHandlerResult>;
 
@@ -30,15 +40,17 @@ export const createStatusPreservingSsrHandler = <T extends object>(
     const handler = args[args.length - 1] as SsrHandler<E, T>;
 
     return createHandler<E>(...middlewares, async (context) => {
-      const result = await handler(context as Context<E & PageEnv<T>>);
+      const result = await measureServerPhase(context, "ssr_data", () => handler(context as Context<E & PageEnv<T>>));
       if (result instanceof Response) return result;
-      await finalizePage?.(context as unknown as Context<PageEnv<T>>);
+      await measureServerPhase(context, "ssr_finalize", () => finalizePage?.(context as unknown as Context<PageEnv<T>>));
       if (typeof result !== "function") return result;
 
       const status = context.newResponse(null).status;
-      if (status === 200) return result;
+      if (result.constructor.name === "AsyncFunction") {
+        throw new Error("[ssr] ssr() render functions must be synchronous: return () => <Page />");
+      }
 
-      const response = await html(result, context.get("page") as T);
+      const response = await measureServerPhase(context, "ssr_render", () => html(result, context.get("page") as T));
       const headers: Record<string, string> = {};
       response.headers.forEach((value, key) => {
         headers[key] = value;

package/src/_internal/web-vitals-asset.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+import { dependencies } from "../../package.json";
+import * as collectorModule from "../browser/web-vitals.ts" with { type: "text" };
+
+// All apps using the same collector share one Core asset and browser cache key.
+// Both inputs are bundled, so production servers need no source files on disk.
+if (!("default" in collectorModule) || typeof collectorModule.default !== "string") throw new Error("Expected collector source text");
+const version = createHash("sha256").update(collectorModule.default).update(dependencies["web-vitals"]).digest("hex").slice(0, 16);
+export const WEB_VITALS_ASSET_NAME = `web-vitals-${version}.js`;
+export const WEB_VITALS_ASSET_HREF = `/public/${WEB_VITALS_ASSET_NAME}`;

package/src/access/PermissionEditor.tsx

@@ -1,9 +1,10 @@
 import { mutation } from "@k2b/stdlib/solid";
-import { Button, Combobox, type ComboboxOption, IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
+import { IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
 import { createSignal, For, Show } from "solid-js";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal } from "../contracts/shared";
 import { accessMessages } from "./messages";
+import PrincipalPicker from "./PrincipalPicker";
 
 // ─────────────────────────────────────────────────────────────────────────
 // Public API
@@ -56,8 +57,8 @@ type PermissionEditorProps = {
    *  write "Use", views call read "View"). When undefined, all three
    *  are offered with default labels. New entries are granted
    *  `allowedLevels[0]` on pick — the user upgrades via the row pill
-   *  afterwards. */
-  allowedLevels?: AllowedLevel[];
+   *  afterwards. A function may restrict levels by principal (for example public read-only). */
+  allowedLevels?: AllowedLevel[] | ((principal: Principal) => AllowedLevel[]);
 };
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -135,22 +136,6 @@ const getPrincipalIcon = (principal: Principal): string => {
   }
 };
 
-// Backend `/api/accounts/entities` shape (the subset we consume).
-type ApiEntity =
-  | { kind: "user"; user: { id: string; uid: string; displayName: string; mail: string | null } }
-  | { kind: "group"; group: { id: string; name: string; description: string | null } }
-  | {
-      kind: "service_account";
-      serviceAccount: {
-        id: string;
-        name: string;
-        kind: "user_delegated" | "resource_bound";
-        appId: string | null;
-        resourceType: string | null;
-        resourceId: string | null;
-      };
-    };
-
 // ─────────────────────────────────────────────────────────────────────────
 // PermissionEditor
 // ─────────────────────────────────────────────────────────────────────────
@@ -162,12 +147,12 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   const canEdit = () => props.canEdit !== false;
   const allowPublic = () => props.allowPublic === true;
   const allowAuthenticated = () => props.allowAuthenticated !== false;
-  const allowed = () => resolveAllowedLevels(props.allowedLevels, t());
-  const isSinglePicker = () => allowed().length === 1;
+  const allowed = (principal: Principal) =>
+    resolveAllowedLevels(typeof props.allowedLevels === "function" ? props.allowedLevels(principal) : props.allowedLevels, t());
 
   // Defensive dev-warning: an empty allowedLevels array makes the editor
   // unable to grant anything.
-  if (props.allowedLevels && props.allowedLevels.length === 0) {
+  if (Array.isArray(props.allowedLevels) && props.allowedLevels.length === 0) {
     if (typeof console !== "undefined") {
       console.warn(
         "[PermissionEditor] `allowedLevels=[]` — the editor cannot grant any permission. Pass at least one level or omit the prop for the default View / Edit / Manage set.",
@@ -175,21 +160,6 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     }
   }
 
-  const existingUserIds = () =>
-    entries()
-      .filter((e) => e.principal.type === "user")
-      .map((e) => (e.principal as { type: "user"; userId: string }).userId);
-  const existingGroupIds = () =>
-    entries()
-      .filter((e) => e.principal.type === "group")
-      .map((e) => (e.principal as { type: "group"; groupId: string }).groupId);
-  const existingServiceAccountIds = () =>
-    entries()
-      .filter((e) => e.principal.type === "service_account")
-      .map((e) => (e.principal as { type: "service_account"; serviceAccountId: string }).serviceAccountId);
-  const hasAuthenticatedEntry = () => entries().some((entry) => entry.principal.type === "authenticated");
-  const hasPublicEntry = () => entries().some((entry) => entry.principal.type === "public");
-
   const grantMut = mutation.create({
     mutation: async (data: { principal: Principal; permission: GrantableLevel; display: { displayName: string } }) =>
       props.grantAccess(data.principal, data.permission, data.display),
@@ -230,106 +200,6 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   });
   const busy = () => grantMut.loading() || updateMut.loading() || revokeMut.loading();
 
-  // ── Combobox add-flow ─────────────────────────────────────────────────
-  // The Combobox is a fire-and-forget input: type → pick → granted at the
-  // lowest allowed level. The `principalsByOptId` map carries the original
-  // discriminated principal across the ComboboxOption boundary so onSelect
-  // can route it to grantAccess without re-parsing prefixed ids.
-  let principalsByOptId = new Map<string, Principal>();
-
-  const fetchPrincipals = async (q: string, signal: AbortSignal): Promise<ComboboxOption[]> => {
-    const map = new Map<string, Principal>();
-    const opts: ComboboxOption[] = [];
-
-    // Synthetic principals — only when allowed AND not already granted.
-    // Placed first so they're visible immediately on focus, before any
-    // typing kicks off a backend request.
-    if (allowAuthenticated() && !hasAuthenticatedEntry()) {
-      map.set("auth", { type: "authenticated" });
-      opts.push({
-        id: "auth",
-        label: t().allUsers,
-        description: t().signedInDescription,
-        icon: "ti-lock-open-2",
-      });
-    }
-    if (allowPublic() && !hasPublicEntry()) {
-      map.set("public", { type: "public" });
-      opts.push({
-        id: "public",
-        label: t().public,
-        description: t().publicDescription,
-        icon: "ti-world",
-      });
-    }
-
-    // Real entities require a query — avoid a wide listing on every focus.
-    if (q.length >= 2) {
-      const url = new URL("/api/accounts/entities", window.location.origin);
-      url.searchParams.set("search", q);
-      url.searchParams.set("kinds", props.allowServiceAccounts ? "user,group,service_account" : "user,group");
-      url.searchParams.set("per_page", "10");
-      const userIds = existingUserIds();
-      if (userIds.length) url.searchParams.set("exclude_user_ids", userIds.join(","));
-      const groupIds = existingGroupIds();
-      if (groupIds.length) url.searchParams.set("exclude_group_ids", groupIds.join(","));
-      const serviceAccountIds = existingServiceAccountIds();
-      if (serviceAccountIds.length) url.searchParams.set("exclude_service_account_ids", serviceAccountIds.join(","));
-
-      const res = await fetch(url.toString(), { credentials: "same-origin", signal });
-      if (res.ok) {
-        const data = (await res.json()) as { items?: ApiEntity[] };
-        for (const item of data.items ?? []) {
-          if (item.kind === "user") {
-            const id = `u:${item.user.id}`;
-            map.set(id, { type: "user", userId: item.user.id });
-            opts.push({
-              id,
-              label: item.user.displayName,
-              description: item.user.mail ?? item.user.uid,
-              icon: "ti ti-user",
-            });
-          } else if (item.kind === "group") {
-            const id = `g:${item.group.id}`;
-            map.set(id, { type: "group", groupId: item.group.id });
-            opts.push({
-              id,
-              label: item.group.name,
-              description: item.group.description ?? undefined,
-              icon: "ti ti-users-group",
-            });
-          } else if (item.kind === "service_account") {
-            const id = `sa:${item.serviceAccount.id}`;
-            map.set(id, { type: "service_account", serviceAccountId: item.serviceAccount.id });
-            opts.push({
-              id,
-              label: item.serviceAccount.name,
-              description:
-                item.serviceAccount.kind === "user_delegated"
-                  ? t().userBoundServiceAccount
-                  : [item.serviceAccount.appId, item.serviceAccount.resourceType, item.serviceAccount.resourceId]
-                      .filter(Boolean)
-                      .join(" · "),
-              icon: "ti ti-key",
-            });
-          }
-        }
-      }
-    }
-
-    principalsByOptId = map;
-    return opts;
-  };
-
-  const handleSelect = (option: ComboboxOption) => {
-    if (busy()) return;
-    const principal = principalsByOptId.get(option.id);
-    if (!principal) return;
-    const firstLevel = allowed()[0]?.level;
-    if (!firstLevel) return; // dev-warned above; bail silently
-    grantMut.mutate({ principal, permission: firstLevel, display: { displayName: option.label } });
-  };
-
   return (
     <div class="flex flex-col gap-3">
       {/* Existing entries */}
@@ -340,8 +210,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
               entry={entry}
               canEdit={canEdit()}
               disabled={busy()}
-              allowed={allowed()}
-              singlePicker={isSinglePicker()}
+              allowed={allowed(entry.principal)}
+              singlePicker={allowed(entry.principal).length === 1}
               onUpdatePermission={(permission) => {
                 if (!busy()) void updateMut.mutate({ accessId: entry.id, permission });
               }}
@@ -360,19 +230,16 @@ export default function PermissionEditor(props: PermissionEditorProps) {
           level on pick. The user upgrades via the row pill if they want
           a higher level. KISS: one decision per step. */}
       <Show when={canEdit()}>
-        <Combobox
-          placeholder={
-            props.allowServiceAccounts
-              ? allowAuthenticated()
-                ? t().addAll
-                : t().addService
-              : allowAuthenticated()
-                ? t().addAudience
-                : t().addBasic
-          }
-          fetchData={fetchPrincipals}
-          onSelect={handleSelect}
+        <PrincipalPicker
+          existing={entries().map((e) => e.principal)}
+          allowPublic={allowPublic()}
+          allowAuthenticated={allowAuthenticated()}
+          allowServiceAccounts={props.allowServiceAccounts}
           disabled={busy()}
+          onSelect={(principal, display) => {
+            const permission = allowed(principal)[0]?.level;
+            if (permission && !busy()) grantMut.mutate({ principal, permission, display });
+          }}
         />
       </Show>
     </div>