@stigmer/react 3.0.7 → 3.0.8-dev.20260612073024

package/src/access/__tests__/ManageAccessDialog.test.tsx

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ManageAccessDialog } from "../ManageAccessDialog";
+
+// The dialog's job is composition + conditional section rendering — not the
+// behavior of the lower-level controls, which own their own tests. Stub the
+// two heavy children to assert *which* sections mount, and pin the
+// proto-generated capability so the People gate is deterministic.
+const hasGrantableRolesMock = vi.fn<(kind: ApiResourceKind) => boolean>(() => true);
+vi.mock("@stigmer/sdk", async (importActual) => {
+  const actual = await importActual<typeof import("@stigmer/sdk")>();
+  return { ...actual, hasGrantableRoles: (kind: ApiResourceKind) => hasGrantableRolesMock(kind) };
+});
+
+vi.mock("../../iam-policy/PeopleWithAccess", () => ({
+  PeopleWithAccess: () => <div data-testid="people-with-access" />,
+}));
+
+vi.mock("../../library/ResourceVisibilityControl", () => ({
+  ResourceVisibilityControl: () => <div data-testid="visibility-control" />,
+}));
+
+// happy-dom does not implement the native dialog show/close methods.
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  hasGrantableRolesMock.mockReset();
+  hasGrantableRolesMock.mockReturnValue(true);
+});
+
+const RESOURCE = {
+  kind: ApiResourceKind.agent,
+  kindString: "agent",
+  id: "agt_123",
+  org: "acme",
+  name: "Release Bot",
+} as const;
+
+describe("ManageAccessDialog", () => {
+  it("mounts no body while closed (the access-list fetch stays lazy)", () => {
+    render(
+      <ManageAccessDialog
+        open={false}
+        onOpenChange={() => {}}
+        resource={RESOURCE}
+      />,
+    );
+
+    expect(screen.queryByText("Manage access")).toBeNull();
+    expect(screen.queryByTestId("people-with-access")).toBeNull();
+  });
+
+  it("renders the header with the resource name when open", () => {
+    render(
+      <ManageAccessDialog open onOpenChange={() => {}} resource={RESOURCE} />,
+    );
+
+    expect(screen.getByText("Manage access")).toBeTruthy();
+    expect(screen.getByText("Release Bot")).toBeTruthy();
+  });
+
+  it("renders General access only when a visibility descriptor is provided", () => {
+    const { rerender } = render(
+      <ManageAccessDialog open onOpenChange={() => {}} resource={RESOURCE} />,
+    );
+    expect(screen.queryByTestId("visibility-control")).toBeNull();
+
+    rerender(
+      <ManageAccessDialog
+        open
+        onOpenChange={() => {}}
+        resource={RESOURCE}
+        visibility={{
+          kind: "agent",
+          current: ApiResourceVisibility.visibility_private,
+          org: "acme",
+        }}
+      />,
+    );
+    expect(screen.getByTestId("visibility-control")).toBeTruthy();
+    expect(screen.getByText("General access")).toBeTruthy();
+  });
+
+  it("renders People only when the kind has grantable roles", () => {
+    hasGrantableRolesMock.mockReturnValue(false);
+    const { rerender } = render(
+      <ManageAccessDialog open onOpenChange={() => {}} resource={RESOURCE} />,
+    );
+    expect(screen.queryByTestId("people-with-access")).toBeNull();
+
+    hasGrantableRolesMock.mockReturnValue(true);
+    rerender(
+      <ManageAccessDialog
+        open
+        onOpenChange={() => {}}
+        resource={{ ...RESOURCE, id: "agt_456" }}
+      />,
+    );
+    expect(screen.getByTestId("people-with-access")).toBeTruthy();
+    expect(screen.getByText("People with access")).toBeTruthy();
+  });
+
+  it("renders the extra section only when provided", () => {
+    render(
+      <ManageAccessDialog
+        open
+        onOpenChange={() => {}}
+        resource={RESOURCE}
+        extraSection={{
+          title: "Run visibility",
+          description: "Who can observe runs.",
+          content: <div data-testid="run-visibility" />,
+        }}
+      />,
+    );
+
+    expect(screen.getByText("Run visibility")).toBeTruthy();
+    expect(screen.getByTestId("run-visibility")).toBeTruthy();
+  });
+
+  it("requests close via Done and the close affordance", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <ManageAccessDialog open onOpenChange={onOpenChange} resource={RESOURCE} />,
+    );
+
+    // Query by text/label rather than role: a native <dialog> that has not yet
+    // run showModal() hides its descendants from the accessibility tree.
+    screen.getByText("Done").click();
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+
+    onOpenChange.mockClear();
+    screen.getByLabelText("Close").click();
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/access/index.ts

@@ -0,0 +1,21 @@
+// Access — the unified "Manage access" experience composing visibility
+// (library) and explicit grants (iam-policy) into one dialog, with a kebab
+// hook and a visible-button trigger for the surfaces that mount it.
+export {
+  ManageAccessDialog,
+  type ManageAccessDialogProps,
+} from "./ManageAccessDialog";
+export {
+  ManageAccessButton,
+  type ManageAccessButtonProps,
+} from "./ManageAccessButton";
+export {
+  useManageAccess,
+  type UseManageAccessArgs,
+  type UseManageAccessReturn,
+} from "./useManageAccess";
+export type {
+  AccessResource,
+  AccessVisibility,
+  AccessExtraSection,
+} from "./types";

package/src/access/types.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { VisibilityResourceKind } from "../library/useUpdateVisibility";
+
+/**
+ * The resource whose access is being managed. Carries everything the People
+ * section needs: the enum {@link ApiResourceKind} (for grantable-role lookup),
+ * the FGA/API kind string (for IAM refs and permission checks), the id, and
+ * the owning org (drives the org-member typeahead).
+ */
+export interface AccessResource {
+  /** ApiResourceKind enum — drives grantable-role lookup and capability. */
+  readonly kind: ApiResourceKind;
+  /** FGA/API kind string (e.g. "mcp_server", "session", "workflow_execution"). */
+  readonly kindString: string;
+  /** Resource id. */
+  readonly id: string;
+  /** Slug of the owning organization (`metadata.org`). */
+  readonly org: string;
+  /** Optional display name, shown as the dialog subtitle for context. */
+  readonly name?: string;
+}
+
+/**
+ * Describes the "General access" (visibility) axis for the Manage access
+ * dialog. Optional because not every resource has visibility (e.g. sessions
+ * and workflow executions do not). When present, the dialog renders the
+ * shared `ResourceVisibilityControl`, which owns level selection and
+ * the `can_edit` gate.
+ */
+export interface AccessVisibility {
+  /** Resource kind, selecting both the updateVisibility RPC and FGA type. */
+  readonly kind: VisibilityResourceKind;
+  /** Current visibility of the resource. */
+  readonly current: ApiResourceVisibility;
+  /**
+   * Slug of the owning org (`metadata.org`); gates the Platform option for
+   * blueprints. Omit for instances and where Platform should not be offered.
+   */
+  readonly org?: string;
+  /** Called after a successful visibility change so the host can refetch. */
+  readonly onChanged?: () => void;
+}
+
+/**
+ * A generic, resource-specific access section appended below People — the
+ * escape hatch for the rare per-kind axis (today: workflow-instance run
+ * observability) without baking that knowledge into a generic dialog.
+ */
+export interface AccessExtraSection {
+  /** Section heading. */
+  readonly title: string;
+  /** Optional one-line explanation under the heading. */
+  readonly description?: string;
+  /** The section body (e.g. a `<RunVisibilityControl />`). */
+  readonly content: ReactNode;
+}

package/src/access/useManageAccess.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { useCallback, useState, type ReactNode } from "react";
+import { useCheckPermission } from "../iam-policy/useCheckPermission";
+import type { DetailAction } from "../resource-detail/types";
+import { ManageAccessDialog } from "./ManageAccessDialog";
+import type {
+  AccessResource,
+  AccessVisibility,
+  AccessExtraSection,
+} from "./types";
+
+/** Arguments for {@link useManageAccess}. */
+export interface UseManageAccessArgs {
+  /**
+   * The resource whose access is managed, or `null` while it is still
+   * loading. When `null`, {@link UseManageAccessReturn.action} is `null` and
+   * the dialog renders nothing — safe to call before the resource is ready.
+   */
+  readonly resource: AccessResource | null;
+  /** General access (visibility) axis; omit for resources without visibility. */
+  readonly visibility?: AccessVisibility;
+  /** Optional resource-specific section (e.g. run observability). */
+  readonly extraSection?: AccessExtraSection;
+  /** Menu-item label. @default "Manage access" */
+  readonly label?: string;
+}
+
+/** Return value of {@link useManageAccess}. */
+export interface UseManageAccessReturn {
+  /**
+   * A ready-to-spread {@link DetailAction} for a kebab/overflow menu, or
+   * `null` when the resource is unavailable or the user lacks
+   * `can_view_access`. Lives in the `"sharing"` group.
+   */
+  readonly action: DetailAction | null;
+  /** The {@link ManageAccessDialog} node — render it once in the host tree. */
+  readonly dialog: ReactNode;
+  /** Imperatively open the dialog. */
+  readonly open: () => void;
+  /** Whether the dialog is currently open. */
+  readonly isOpen: boolean;
+}
+
+/**
+ * Wires the unified Manage access dialog to a kebab/overflow menu — the
+ * trigger shape used by static resource detail views (agent, skill,
+ * mcp_server, workflow), whose actions live in {@link ResourceActionBar}'s
+ * menu rather than as a standalone button.
+ *
+ * Owns the open-state and the `can_view_access` gate (a viewer may open the
+ * dialog to read general access and the people list; the dialog's own sections
+ * gate editing). Returns a `null` action when the resource is still loading or
+ * the user cannot view access — so the host can unconditionally fold
+ * `action` into its actions array.
+ *
+ * Surfaces that want a *visible* trigger instead use {@link ManageAccessButton}.
+ *
+ * @example
+ * ```tsx
+ * const access = useManageAccess({
+ *   resource: meta ? { kind: ApiResourceKind.agent, kindString: "agent", id: meta.id, org: meta.org } : null,
+ *   visibility: meta ? { kind: "agent", current: meta.visibility, org: meta.org, onChanged: refetch } : undefined,
+ * });
+ * // ...
+ * <ResourceDetailShell actions={access.action ? [...actions, access.action] : actions} ... />
+ * {access.dialog}
+ * ```
+ */
+export function useManageAccess({
+  resource,
+  visibility,
+  extraSection,
+  label = "Manage access",
+}: UseManageAccessArgs): UseManageAccessReturn {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const { allowed: canView } = useCheckPermission(
+    resource ? { kind: resource.kindString, id: resource.id } : null,
+    "can_view_access",
+  );
+
+  const open = useCallback(() => setIsOpen(true), []);
+
+  const action: DetailAction | null =
+    resource && canView
+      ? { id: "manage-access", label, group: "sharing", onAction: open }
+      : null;
+
+  const dialog = resource ? (
+    <ManageAccessDialog
+      open={isOpen}
+      onOpenChange={setIsOpen}
+      resource={resource}
+      visibility={visibility}
+      extraSection={extraSection}
+    />
+  ) : null;
+
+  return { action, dialog, open, isOpen };
+}

package/src/agent/AgentDetailView.tsx

@@ -10,11 +10,13 @@ import type {
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { useAgent } from "./useAgent";
 import { useUpdateAgent } from "./useUpdateAgent";
 import { agentToInput } from "./internal/agentToInput";
 import { ErrorMessage } from "../error/ErrorMessage";
-import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl";
+import { VisibilityBadge } from "../library/VisibilitySelector";
+import { useManageAccess } from "../access/useManageAccess";
 import { ResourceDetailShell } from "../resource-detail/ResourceDetailShell";
 import { Section } from "../resource-detail/Section";
 import { useDetailTabs } from "../resource-detail/useDetailTabs";
@@ -280,6 +282,30 @@ export function AgentDetailView({
     }
   }, [agent]);
 
+  // Unified Manage access — visibility (General access) over explicit grants
+  // (People), opened from the kebab. Derived from the loaded metadata, so the
+  // action stays null until the resource is ready (and folds harmlessly into
+  // the actions array meanwhile).
+  const access = useManageAccess({
+    resource: agent?.metadata
+      ? {
+          kind: ApiResourceKind.agent,
+          kindString: "agent",
+          id: agent.metadata.id,
+          org: agent.metadata.org,
+          name: agent.metadata.name,
+        }
+      : null,
+    visibility: agent?.metadata
+      ? {
+          kind: "agent",
+          current: agent.metadata.visibility,
+          org: agent.metadata.org,
+          onChanged: refetch,
+        }
+      : undefined,
+  });
+
   if (isLoading) return <LoadingSkeleton className={className} />;
   if (error)
     return <ErrorMessage error={error} retry={refetch} className={className} />;
@@ -312,16 +338,16 @@ export function AgentDetailView({
     updatedAt: specAudit?.updatedAt ? timestampDate(specAudit.updatedAt) : null,
   };
 
+  // Inline visibility is read-only (at-a-glance); editing lives in the
+  // Manage access dialog, the single writer for both access axes.
   const visibilityControl = meta ? (
-    <ResourceVisibilityControl
-      kind="agent"
-      resourceId={meta.id}
-      visibility={meta.visibility}
-      org={meta.org || org}
-      onChanged={refetch}
-    />
+    <VisibilityBadge visibility={meta.visibility} />
   ) : undefined;
 
+  const mergedActions = access.action
+    ? [...(actions ?? []), access.action]
+    : actions;
+
   let tabContent: React.ReactNode;
   if (activeAdditionalTab) {
     tabContent = activeAdditionalTab.content;
@@ -361,19 +387,22 @@ export function AgentDetailView({
   }
 
   return (
-    <ResourceDetailShell
-      header={headerMeta}
-      visibilityControl={visibilityControl}
-      primaryAction={primaryAction}
-      actions={actions}
-      tabs={effectiveTabs}
-      activeTab={effectiveTabs ? effectiveActiveTab : undefined}
-      onTabChange={effectiveTabs ? effectiveOnTabChange : undefined}
-      tabsAriaLabel="Agent detail sections"
-      className={className}
-    >
-      {tabContent}
-    </ResourceDetailShell>
+    <>
+      <ResourceDetailShell
+        header={headerMeta}
+        visibilityControl={visibilityControl}
+        primaryAction={primaryAction}
+        actions={mergedActions}
+        tabs={effectiveTabs}
+        activeTab={effectiveTabs ? effectiveActiveTab : undefined}
+        onTabChange={effectiveTabs ? effectiveOnTabChange : undefined}
+        tabsAriaLabel="Agent detail sections"
+        className={className}
+      >
+        {tabContent}
+      </ResourceDetailShell>
+      {access.dialog}
+    </>
   );
 }
 

package/src/agent-instance/AgentInstanceDetailPanel.tsx

@@ -10,9 +10,9 @@ import type { ResourceRef } from "@stigmer/sdk";
 import { getUserMessage } from "@stigmer/sdk";
 import { useUpdateAgentInstance } from "./useUpdateAgentInstance";
 import { useDeleteAgentInstance } from "./useDeleteAgentInstance";
-import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl";
+import { VisibilityBadge } from "../library/VisibilitySelector";
 import { PermissionGate } from "../iam-policy/PermissionGate";
-import { SharePanel } from "../iam-policy/SharePanel";
+import { ManageAccessButton } from "../access/ManageAccessButton";
 import { EnvironmentPicker } from "../environment/EnvironmentPicker";
 import { useEnvironmentList } from "../environment/useEnvironmentList";
 
@@ -58,10 +58,11 @@ export function AgentInstanceDetailPanel({
 
   const [isEditingEnvs, setIsEditingEnvs] = useState(false);
   const [editEnvRefs, setEditEnvRefs] = useState<ResourceRef[]>([]);
-  const [showSharePanel, setShowSharePanel] = useState(false);
   const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
   const [deleteError, setDeleteError] = useState<Error | null>(null);
 
+  const visibility = meta?.visibility ?? ApiResourceVisibility.visibility_private;
+
   const handleStartEditEnvs = useCallback(() => {
     const currentRefs: ResourceRef[] = (spec?.environmentRefs ?? []).map((ref) => ({
       org: ref.org || org,
@@ -115,9 +116,12 @@ export function AgentInstanceDetailPanel({
       {/* Header */}
       <div className="flex items-center justify-between border-b border-border px-4 py-3">
         <div>
-          <h3 className="text-sm font-semibold text-foreground">
-            {meta?.name || meta?.slug || "Instance"}
-          </h3>
+          <div className="flex items-center gap-2">
+            <h3 className="text-sm font-semibold text-foreground">
+              {meta?.name || meta?.slug || "Instance"}
+            </h3>
+            <VisibilityBadge visibility={visibility} />
+          </div>
           <p className="text-[0.65rem] text-muted-foreground">
             {createdAt && `Created ${createdAt.toLocaleDateString()}`}
             {updatedAt && ` \u00B7 Updated ${updatedAt.toLocaleDateString()}`}
@@ -137,19 +141,20 @@ export function AgentInstanceDetailPanel({
               Start session
             </button>
           )}
-          <PermissionGate resource={{ kind: "agent_instance", id }} relation="can_grant_access">
-            <button
-              type="button"
-              onClick={() => setShowSharePanel((v) => !v)}
-              className={cn(
-                "rounded-md px-2.5 py-1 text-xs font-medium",
-                "border border-border text-foreground hover:bg-accent-hover",
-                "focus:outline-none focus:ring-2 focus:ring-ring",
-              )}
-            >
-              Share
-            </button>
-          </PermissionGate>
+          <ManageAccessButton
+            resource={{
+              kind: ApiResourceKind.agent_instance,
+              kindString: "agent_instance",
+              id,
+              org: meta?.org ?? "",
+              name: meta?.name,
+            }}
+            visibility={{
+              kind: "agentInstance",
+              current: visibility,
+              onChanged: onUpdated,
+            }}
+          />
           <button
             type="button"
             onClick={onClose}
@@ -241,29 +246,6 @@ export function AgentInstanceDetailPanel({
           )}
         </div>
 
-        {/* Visibility */}
-        <div className="px-4 py-3">
-          <h4 className="text-xs font-medium text-muted-foreground mb-2">Visibility</h4>
-          <ResourceVisibilityControl
-            kind="agentInstance"
-            resourceId={id}
-            visibility={meta?.visibility ?? ApiResourceVisibility.visibility_private}
-            onChanged={onUpdated}
-          />
-        </div>
-
-        {/* Share Panel */}
-        {showSharePanel && (
-          <div className="px-4 py-3">
-            <SharePanel
-              resource={{ kind: "agent_instance", id, resourceKind: ApiResourceKind.agent_instance }}
-              resourceKindString="agent_instance"
-              resourceKind={ApiResourceKind.agent_instance}
-              onClose={() => setShowSharePanel(false)}
-            />
-          </div>
-        )}
-
         {/* Delete */}
         <PermissionGate resource={{ kind: "agent_instance", id }} relation="can_delete">
           <div className="px-4 py-3">

package/src/iam-policy/GrantAccessForm.tsx

@@ -11,6 +11,7 @@ import { cn } from "@stigmer/theme";
 import { getUserMessage, iamRoleToString } from "@stigmer/sdk";
 import { useCreateIamPolicy } from "./useCreateIamPolicy";
 import { RoleSelector } from "./RoleSelector";
+import { PrincipalPicker, type SelectedPrincipal } from "./PrincipalPicker";
 
 /** Props for {@link GrantAccessForm}. */
 export interface GrantAccessFormProps {
@@ -20,6 +21,13 @@ export interface GrantAccessFormProps {
   readonly resourceKindString: string;
   /** ID of the resource being granted access to. */
   readonly resourceId: string;
+  /**
+   * Organization whose members can be granted access. Drives the
+   * {@link PrincipalPicker} typeahead.
+   */
+  readonly orgId: string;
+  /** Principal IDs that already have access (shown disabled in the picker). */
+  readonly excludePrincipalIds?: readonly string[];
   /** Fired after a policy is successfully created. */
   readonly onGranted?: (policy: IamPolicy) => void;
   /** Fired when the user cancels. */
@@ -29,11 +37,13 @@ export interface GrantAccessFormProps {
 }
 
 /**
- * Form for granting a principal access to a resource.
+ * Form for granting an organization member access to a resource.
  *
- * Collects a **principal ID** (identity account), lets the user pick
- * a **role** from the resource's grantable roles, and creates the IAM
- * policy binding.
+ * Lets the user pick a **person** from the org's member list (by name or
+ * email, disambiguating identity sources) via {@link PrincipalPicker}, choose
+ * a **role** from the resource's grantable roles, and creates the IAM policy
+ * binding. The resolved `identity_account` ID is carried internally — the user
+ * never types or sees raw account IDs.
  *
  * All visual properties flow through `--stgm-*` design tokens.
  *
@@ -43,6 +53,7 @@ export interface GrantAccessFormProps {
  *   resourceKind={ApiResourceKind.organization}
  *   resourceKindString="organization"
  *   resourceId="org-abc123"
+ *   orgId="org-abc123"
  *   onGranted={(policy) => refetchAccessList()}
  *   onCancel={() => setShowForm(false)}
  * />
@@ -52,6 +63,8 @@ export function GrantAccessForm({
   resourceKind,
   resourceKindString,
   resourceId,
+  orgId,
+  excludePrincipalIds,
   onGranted,
   onCancel,
   className,
@@ -59,24 +72,23 @@ export function GrantAccessForm({
   const { create: createPolicy, isCreating, error, clearError } =
     useCreateIamPolicy();
 
-  const [principalId, setPrincipalId] = useState("");
+  const [principal, setPrincipal] = useState<SelectedPrincipal | null>(null);
   const [selectedRole, setSelectedRole] = useState<IamRole | null>(null);
 
-  const trimmedPrincipalId = principalId.trim();
   const canSubmit =
-    trimmedPrincipalId !== "" && selectedRole !== null && !isCreating;
+    principal !== null && selectedRole !== null && !isCreating;
 
   const handleSubmit = useCallback(
     async (e: FormEvent) => {
       e.preventDefault();
-      if (!canSubmit || selectedRole === null) return;
+      if (!canSubmit || selectedRole === null || principal === null) return;
 
       clearError();
       try {
         const spec = create(IamPolicySpecSchema, {
           principal: create(ApiResourceRefSchema, {
             kind: "identity_account",
-            id: trimmedPrincipalId,
+            id: principal.id,
           }),
           resource: create(ApiResourceRefSchema, {
             kind: resourceKindString,
@@ -93,7 +105,7 @@ export function GrantAccessForm({
     [
       canSubmit,
       selectedRole,
-      trimmedPrincipalId,
+      principal,
       resourceKindString,
       resourceId,
       createPolicy,
@@ -105,31 +117,14 @@ export function GrantAccessForm({
   return (
     <form onSubmit={handleSubmit} className={cn("space-y-3", className)}>
       <div className="space-y-3">
-        {/* Principal */}
-        <div className="space-y-1">
-          <label
-            htmlFor="stgm-grant-principal"
-            className="text-xs font-medium text-foreground"
-          >
-            Account ID
-          </label>
-          <input
-            id="stgm-grant-principal"
-            type="text"
-            value={principalId}
-            onChange={(e) => setPrincipalId(e.target.value)}
-            placeholder="e.g. ia-01HQUSER123"
-            disabled={isCreating}
-            autoFocus
-            required
-            className={cn(
-              "w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground",
-              "placeholder:text-muted-foreground",
-              "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
-              "disabled:pointer-events-none disabled:opacity-50",
-            )}
-          />
-        </div>
+        {/* Principal picker (org-member typeahead) */}
+        <PrincipalPicker
+          orgId={orgId}
+          value={principal}
+          onChange={setPrincipal}
+          excludePrincipalIds={excludePrincipalIds}
+          disabled={isCreating}
+        />
 
         {/* Role selector */}
         <RoleSelector