@simple-auth-kit/cli 1.0.0

package/registry/admin-apps/react/variants/base/src/App.tsx

@@ -0,0 +1,103 @@
+import { useEffect } from "react";
+import { observer } from "mobx-react-lite";
+import { Navigate, Route, Routes } from "react-router-dom";
+import { AbilityContext, abilityFor, PERMISSIONS } from "@/lib/ability";
+import { useAuthStore } from "@/stores/store-context";
+import { AppShell } from "@/components/layout/AppShell";
+import { RequireAuth, RequirePermission } from "@/components/layout/RequireAuth";
+import { LoginPage } from "@/pages/LoginPage";
+import { DashboardPage } from "@/pages/DashboardPage";
+import { UsersPage } from "@/pages/UsersPage";
+import { AddUserPage } from "@/pages/AddUserPage";
+import { UserDetailPage } from "@/pages/UserDetailPage";
+import { RolesPage } from "@/pages/RolesPage";
+import { RoleDetailPage } from "@/pages/RoleDetailPage";
+import { PermissionsPage } from "@/pages/PermissionsPage";
+import { PermissionDetailPage } from "@/pages/PermissionDetailPage";
+import { AuditLogPage } from "@/pages/AuditLogPage";
+import { AccountPage } from "@/pages/AccountPage";
+import { CustomersPage } from "@/pages/CustomersPage";
+import { AddCustomerPage } from "@/pages/AddCustomerPage";
+import { CustomerDetailPage } from "@/pages/CustomerDetailPage";
+import { EditCustomerPage } from "@/pages/EditCustomerPage";
+import { CountriesPage } from "@/pages/CountriesPage";
+import { AddCountryPage } from "@/pages/AddCountryPage";
+import { CountryDetailPage } from "@/pages/CountryDetailPage";
+import { EditCountryPage } from "@/pages/EditCountryPage";
+import { LanguagesPage } from "@/pages/LanguagesPage";
+import { AddLanguagePage } from "@/pages/AddLanguagePage";
+import { LanguageDetailPage } from "@/pages/LanguageDetailPage";
+import { EditLanguagePage } from "@/pages/EditLanguagePage";
+
+export const App = observer(function App() {
+  const store = useAuthStore();
+
+  useEffect(() => {
+    void store.initialize();
+  }, [store]);
+
+  const ability = abilityFor(store.currentUser);
+
+  return (
+    <AbilityContext.Provider value={ability}>
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+
+        <Route element={<RequireAuth />}>
+          <Route element={<AppShell />}>
+            <Route path="/dashboard" element={<DashboardPage />} />
+            <Route path="/account" element={<AccountPage />} />
+
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.usersRead]} />}>
+              <Route path="/users" element={<UsersPage />} />
+              <Route path="/users/:id" element={<UserDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.usersManage]} />}>
+              <Route path="/users/new" element={<AddUserPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.rolesManage, PERMISSIONS.rolesAssign, PERMISSIONS.permissionsGrant]} />}>
+              <Route path="/roles" element={<RolesPage />} />
+              <Route path="/roles/:id" element={<RoleDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.permissionsRead]} />}>
+              <Route path="/permissions" element={<PermissionsPage />} />
+              <Route path="/permissions/:id" element={<PermissionDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.auditLogRead]} />}>
+              <Route path="/audit-log" element={<AuditLogPage />} />
+            </Route>
+
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.customersRead]} />}>
+              <Route path="/customers" element={<CustomersPage />} />
+              <Route path="/customers/:id" element={<CustomerDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.customersManage]} />}>
+              <Route path="/customers/new" element={<AddCustomerPage />} />
+              <Route path="/customers/:id/edit" element={<EditCustomerPage />} />
+            </Route>
+
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.countriesRead]} />}>
+              <Route path="/countries" element={<CountriesPage />} />
+              <Route path="/countries/:id" element={<CountryDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.countriesManage]} />}>
+              <Route path="/countries/new" element={<AddCountryPage />} />
+              <Route path="/countries/:id/edit" element={<EditCountryPage />} />
+            </Route>
+
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.languagesRead]} />}>
+              <Route path="/languages" element={<LanguagesPage />} />
+              <Route path="/languages/:id" element={<LanguageDetailPage />} />
+            </Route>
+            <Route element={<RequirePermission anyOf={[PERMISSIONS.languagesManage]} />}>
+              <Route path="/languages/new" element={<AddLanguagePage />} />
+              <Route path="/languages/:id/edit" element={<EditLanguagePage />} />
+            </Route>
+          </Route>
+        </Route>
+
+        <Route path="*" element={<Navigate to="/dashboard" replace />} />
+      </Routes>
+    </AbilityContext.Provider>
+  );
+});

package/registry/admin-apps/react/variants/base/src/components/app-sidebar.tsx

@@ -0,0 +1,181 @@
+import { Link, NavLink, useLocation } from "react-router-dom";
+import {
+  ChevronRightIcon,
+  ContactIcon,
+  GlobeIcon,
+  LanguagesIcon,
+  LayoutDashboardIcon,
+  ScrollTextIcon,
+  ShieldCheckIcon,
+  UserPlusIcon,
+  UsersIcon,
+} from "lucide-react";
+import { canAny, PERMISSIONS, useAbility, type PermissionKey } from "@/lib/ability";
+import { NavUser } from "@/components/nav-user";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarRail,
+} from "@/components/ui/sidebar";
+
+/**
+ * `requires: undefined` means "always shown" (Dashboard — every authenticated user can land
+ * there, its cards are individually gated). Everything else is hidden when the caller lacks the
+ * permission its page needs — the same keys AppShell's old flat nav used and App.tsx's
+ * `RequirePermission` route guards check, so the sidebar never offers a page that would answer
+ * 403. "My account" isn't listed here; it's reachable from the NavUser "Profile" menu item instead.
+ */
+type NavItem = {
+  to: string;
+  label: string;
+  icon: typeof UsersIcon;
+  requires?: readonly PermissionKey[];
+  children?: Array<{ to: string; label: string; requires?: readonly PermissionKey[] }>;
+};
+
+const NAV_ITEMS: NavItem[] = [
+  { to: "/dashboard", label: "Dashboard", icon: LayoutDashboardIcon },
+  {
+    to: "/users",
+    label: "Users",
+    icon: UsersIcon,
+    requires: [PERMISSIONS.usersRead],
+    children: [
+      { to: "/users", label: "All users", requires: [PERMISSIONS.usersRead] },
+      { to: "/users/new", label: "Add user", requires: [PERMISSIONS.usersManage] },
+    ],
+  },
+  {
+    to: "/roles",
+    label: "Roles & permissions",
+    icon: ShieldCheckIcon,
+    requires: [PERMISSIONS.rolesManage, PERMISSIONS.rolesAssign, PERMISSIONS.permissionsGrant],
+  },
+  { to: "/permissions", label: "Permissions", icon: ShieldCheckIcon, requires: [PERMISSIONS.permissionsRead] },
+  { to: "/audit-log", label: "Audit log", icon: ScrollTextIcon, requires: [PERMISSIONS.auditLogRead] },
+  {
+    to: "/customers",
+    label: "Customers",
+    icon: ContactIcon,
+    requires: [PERMISSIONS.customersRead],
+    children: [
+      { to: "/customers", label: "All customers", requires: [PERMISSIONS.customersRead] },
+      { to: "/customers/new", label: "Add customer", requires: [PERMISSIONS.customersManage] },
+    ],
+  },
+  {
+    to: "/countries",
+    label: "Countries",
+    icon: GlobeIcon,
+    requires: [PERMISSIONS.countriesRead],
+    children: [
+      { to: "/countries", label: "All countries", requires: [PERMISSIONS.countriesRead] },
+      { to: "/countries/new", label: "Add country", requires: [PERMISSIONS.countriesManage] },
+    ],
+  },
+  {
+    to: "/languages",
+    label: "Languages",
+    icon: LanguagesIcon,
+    requires: [PERMISSIONS.languagesRead],
+    children: [
+      { to: "/languages", label: "All languages", requires: [PERMISSIONS.languagesRead] },
+      { to: "/languages/new", label: "Add language", requires: [PERMISSIONS.languagesManage] },
+    ],
+  },
+];
+
+export function AppSidebar() {
+  const ability = useAbility();
+  const location = useLocation();
+
+  const items = NAV_ITEMS.filter((item) => !item.requires || canAny(ability, item.requires))
+    .map((item) => ({ ...item, children: item.children?.filter((child) => !child.requires || canAny(ability, child.requires)) }))
+    // A parent with every child hidden by permissions collapses to a plain link.
+    .map((item) => (item.children && item.children.length <= 1 ? { ...item, children: undefined } : item));
+
+  return (
+    <Sidebar collapsible="icon">
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" asChild>
+              <Link to="/dashboard">
+                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                  <ShieldCheckIcon className="size-4" />
+                </div>
+                <div className="grid flex-1 text-left text-sm leading-tight">
+                  <span className="truncate font-medium">simple-auth-kit</span>
+                  <span className="truncate text-xs text-muted-foreground">admin console</span>
+                </div>
+              </Link>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>Console</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {items.map((item) =>
+                item.children ? (
+                  <Collapsible key={item.to} asChild defaultOpen={location.pathname.startsWith(item.to)} className="group/collapsible">
+                    <SidebarMenuItem>
+                      <CollapsibleTrigger asChild>
+                        <SidebarMenuButton tooltip={item.label} isActive={location.pathname === item.to}>
+                          <item.icon />
+                          <span>{item.label}</span>
+                          <ChevronRightIcon className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+                        </SidebarMenuButton>
+                      </CollapsibleTrigger>
+                      <CollapsibleContent>
+                        <SidebarMenuSub>
+                          {item.children.map((child) => (
+                            <SidebarMenuSubItem key={child.to}>
+                              <SidebarMenuSubButton asChild isActive={location.pathname === child.to}>
+                                <Link to={child.to}>
+                                  {child.to === "/users/new" ? <UserPlusIcon /> : null}
+                                  <span>{child.label}</span>
+                                </Link>
+                              </SidebarMenuSubButton>
+                            </SidebarMenuSubItem>
+                          ))}
+                        </SidebarMenuSub>
+                      </CollapsibleContent>
+                    </SidebarMenuItem>
+                  </Collapsible>
+                ) : (
+                  <SidebarMenuItem key={item.to}>
+                    <SidebarMenuButton asChild isActive={location.pathname === item.to} tooltip={item.label}>
+                      <NavLink to={item.to}>
+                        <item.icon />
+                        <span>{item.label}</span>
+                      </NavLink>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ),
+              )}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter>
+        <NavUser />
+      </SidebarFooter>
+      <SidebarRail />
+    </Sidebar>
+  );
+}

package/registry/admin-apps/react/variants/base/src/components/breadcrumb.tsx

@@ -0,0 +1,47 @@
+import { Fragment } from "react";
+import { Link } from "react-router-dom";
+import { ChevronRightIcon } from "lucide-react";
+
+export type BreadcrumbTrailItem = { title: string; href: string };
+
+/**
+ * Fixed "Dashboard" root plus a per-page trail, last item non-clickable — used at the top of every
+ * console page, mirroring admin-nextjs's `Breadcrumb` but built on react-router links.
+ */
+export function Breadcrumb({ items = [] }: { items?: BreadcrumbTrailItem[] }) {
+  return (
+    <nav aria-label="breadcrumb" className="mb-4">
+      <ol className="flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground sm:gap-2.5">
+        <li>
+          {items.length === 0 ? (
+            <span aria-current="page" className="font-normal text-foreground">
+              Dashboard
+            </span>
+          ) : (
+            <Link to="/dashboard" className="transition-colors hover:text-foreground">
+              Dashboard
+            </Link>
+          )}
+        </li>
+        {items.map((item, index) => (
+          <Fragment key={item.href}>
+            <li role="presentation" aria-hidden="true">
+              <ChevronRightIcon className="size-3.5" />
+            </li>
+            <li>
+              {index === items.length - 1 ? (
+                <span aria-current="page" className="font-normal text-foreground">
+                  {item.title}
+                </span>
+              ) : (
+                <Link to={item.href} className="transition-colors hover:text-foreground">
+                  {item.title}
+                </Link>
+              )}
+            </li>
+          </Fragment>
+        ))}
+      </ol>
+    </nav>
+  );
+}

package/registry/admin-apps/react/variants/base/src/components/change-password-dialog.tsx

@@ -0,0 +1,102 @@
+import { useState, type FormEvent } from "react";
+import { EyeIcon, EyeOffIcon } from "lucide-react";
+import { AuthApiError } from "@simple-auth-kit/auth-client";
+import { Button } from "@/components/ui/button";
+import { Modal } from "@/components/ui/modal";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { authClient } from "@/lib/auth-client";
+
+function PasswordField({
+  id,
+  label,
+  value,
+  onChange,
+}: {
+  id: string;
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const [visible, setVisible] = useState(false);
+  return (
+    <div className="flex flex-col gap-1.5">
+      <Label htmlFor={id}>{label}</Label>
+      <div className="relative">
+        <Input id={id} type={visible ? "text" : "password"} required value={value} onChange={(e) => onChange(e.target.value)} className="pr-9" />
+        <button
+          type="button"
+          onClick={() => setVisible((v) => !v)}
+          className="absolute inset-y-0 right-2 flex items-center text-muted-foreground hover:text-foreground"
+          tabIndex={-1}
+        >
+          {visible ? <EyeOffIcon className="size-4" /> : <EyeIcon className="size-4" />}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function ChangePasswordDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  function reset() {
+    setCurrentPassword("");
+    setNewPassword("");
+    setConfirmPassword("");
+    setError(null);
+    setNotice(null);
+  }
+
+  function handleClose() {
+    reset();
+    onClose();
+  }
+
+  async function handleSubmit(event: FormEvent) {
+    event.preventDefault();
+    setError(null);
+    setNotice(null);
+    if (newPassword !== confirmPassword) {
+      setError("The new password and confirmation don't match.");
+      return;
+    }
+    setSubmitting(true);
+    try {
+      await authClient.changePassword({ currentPassword, newPassword });
+      setNotice("Password changed. Every other session was signed out.");
+      setCurrentPassword("");
+      setNewPassword("");
+      setConfirmPassword("");
+    } catch (err) {
+      setError(err instanceof AuthApiError ? err.message : "Couldn't change the password. Check your current password and try again.");
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Modal isOpen={open} onClose={handleClose} title="Change password" description="Every other session gets signed out — this one doesn't.">
+      <form onSubmit={handleSubmit} className="flex flex-col gap-4">
+        {error ? <p className="text-sm text-destructive">{error}</p> : null}
+        {notice ? <p className="text-sm text-emerald-600">{notice}</p> : null}
+        <PasswordField id="currentPassword" label="Current password" value={currentPassword} onChange={setCurrentPassword} />
+        <PasswordField id="newPassword" label="New password" value={newPassword} onChange={setNewPassword} />
+        <PasswordField id="confirmPassword" label="Confirm new password" value={confirmPassword} onChange={setConfirmPassword} />
+        <div className="flex justify-end gap-2">
+          <Button type="button" variant="outline" onClick={handleClose}>
+            Close
+          </Button>
+          <Button type="submit" disabled={submitting}>
+            {submitting ? "Changing…" : "Change password"}
+          </Button>
+        </div>
+      </form>
+    </Modal>
+  );
+}

package/registry/admin-apps/react/variants/base/src/components/form-error-alert.tsx

@@ -0,0 +1,23 @@
+import { AlertCircleIcon } from "lucide-react";
+
+/** The destructive block every form shows above itself on submit error — one bullet per message. */
+export function FormErrorAlert({ messages }: { messages: string[] | null }) {
+  if (!messages || messages.length === 0) return null;
+  return (
+    <div role="alert" className="mb-4 flex items-start gap-3 rounded-lg border border-destructive/50 bg-destructive/10 p-4 text-sm text-destructive">
+      <AlertCircleIcon className="mt-0.5 size-4 shrink-0" />
+      <div className="flex flex-col gap-1">
+        <p className="font-medium">{messages.length === 1 ? "Something went wrong" : "Please fix the following"}</p>
+        {messages.length === 1 ? (
+          <p>{messages[0]}</p>
+        ) : (
+          <ul className="list-disc pl-4">
+            {messages.map((message) => (
+              <li key={message}>{message}</li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}

package/registry/admin-apps/react/variants/base/src/components/layout/AppShell.tsx

@@ -0,0 +1,36 @@
+import { Outlet } from "react-router-dom";
+import { AppSidebar } from "@/components/app-sidebar";
+import { ThemeToggle } from "@/components/theme-toggle";
+import { UserMenu } from "@/components/user-menu";
+import { Separator } from "@/components/ui/separator";
+import { SidebarInset, SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar";
+
+/**
+ * The console shell: a collapsible sidebar (nav + account menu, gated the same way the old flat
+ * top-nav was) wrapping every authenticated route's content. Sign-out and account access live in
+ * `NavUser`'s dropdown in the sidebar footer, and also in `UserMenu` in the top-right of the header,
+ * alongside the light/dark/system `ThemeToggle`.
+ */
+export function AppShell() {
+  return (
+    <SidebarProvider>
+      <AppSidebar />
+      <SidebarInset>
+        <header className="flex h-14 shrink-0 items-center justify-between gap-2 border-b border-border px-4">
+          <div className="flex items-center gap-2">
+            <SidebarTrigger />
+            <Separator orientation="vertical" className="mr-2 h-4" />
+            <span className="text-sm font-medium text-muted-foreground">simple-auth-kit admin</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <ThemeToggle />
+            <UserMenu />
+          </div>
+        </header>
+        <main className="flex-1 px-4 py-6 md:px-6">
+          <Outlet />
+        </main>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}

package/registry/admin-apps/react/variants/base/src/components/layout/RequireAuth.tsx

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from "react";
+import { observer } from "mobx-react-lite";
+import { Navigate, Outlet, useLocation, useNavigate } from "react-router-dom";
+import { canAny, useAbility } from "@/lib/ability";
+import { useAuthStore } from "@/stores/store-context";
+
+/** Route guard: redirects to /login (preserving the intended destination) when there's no session. */
+export const RequireAuth = observer(function RequireAuth() {
+  const store = useAuthStore();
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  // A Vite SPA has no server to run middleware on, so there's no equivalent to the base
+  // admin-nextjs app's `proxy.ts`. Re-verify against the backend on every navigation instead of
+  // only trusting in-memory state, so a logout-all/block/deactivate takes effect at the next
+  // click rather than staying invisible until some unrelated API call happens to 401.
+  const pathnameRef = useRef(location.pathname);
+  pathnameRef.current = location.pathname;
+  useEffect(() => {
+    if (store.initializing || !store.isAuthenticated) return;
+    const pathnameAtCheckStart = pathnameRef.current;
+    void store.verifySession().then((stillValid) => {
+      if (!stillValid && pathnameRef.current === pathnameAtCheckStart) {
+        navigate("/login", { replace: true, state: { from: location } });
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location.pathname]);
+
+  if (store.initializing) {
+    return (
+      <div className="flex min-h-screen items-center justify-center text-sm text-muted-foreground">Loading…</div>
+    );
+  }
+
+  if (!store.isAuthenticated) {
+    return <Navigate to="/login" replace state={{ from: location }} />;
+  }
+
+  return <Outlet />;
+});
+
+/**
+ * Gate for a page whose routes the backend requires a permission for. `anyOf` is satisfied by
+ * holding any one of the listed permissions, which is how a page made of several independently
+ * gated cards (Roles & Permissions) opens for someone who can use only part of it.
+ *
+ * The backend's `AbilityGuard` is the real boundary — this exists so a page that would answer
+ * 403 isn't offered in the first place, and it reads the same permission keys the guard does.
+ */
+export function RequirePermission({ anyOf }: { anyOf: readonly string[] }) {
+  const ability = useAbility();
+
+  if (!canAny(ability, anyOf)) {
+    return (
+      <div className="rounded-lg border border-border bg-card p-6">
+        <p className="text-sm font-medium">You don't have access to this page</p>
+        <p className="mt-1 text-sm text-muted-foreground">
+          It needs the {anyOf.map((permission) => `"${permission}"`).join(" or ")} permission. Ask an administrator to grant it, then sign in again.
+        </p>
+      </div>
+    );
+  }
+
+  return <Outlet />;
+}

package/registry/admin-apps/react/variants/base/src/components/permission-group-select.tsx

@@ -0,0 +1,99 @@
+import type { PermissionSummary } from "@simple-auth-kit/auth-client";
+import { Card } from "@/components/ui/card";
+import { Checkbox } from "@/components/ui/checkbox";
+
+interface PermissionGroup {
+  name: string;
+  permissions: PermissionSummary[];
+}
+
+function groupPermissions(permissions: PermissionSummary[]): PermissionGroup[] {
+  const byGroup = new Map<string, PermissionSummary[]>();
+  for (const permission of permissions) {
+    const list = byGroup.get(permission.group) ?? [];
+    list.push(permission);
+    byGroup.set(permission.group, list);
+  }
+  return Array.from(byGroup.entries())
+    .map(([name, perms]) => ({ name, permissions: perms.sort((a, b) => a.order - b.order) }))
+    .sort((a, b) => (a.permissions[0]?.groupOrder ?? 0) - (b.permissions[0]?.groupOrder ?? 0));
+}
+
+// Indeterminate isn't in the base checkbox's own stylesheet (only `data-[state=checked]` is), so
+// the tri-state coloring is layered on here rather than touching the shared primitive for what
+// is otherwise a generic shadcn component used unmodified everywhere else.
+const INDETERMINATE_STYLE = "data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground data-[state=indeterminate]:border-primary";
+
+/** A checkbox grid grouped by `permission.group`, with a tri-state select-all and one per group — how the reference app lets you build a role's permission set. */
+export function PermissionGroupSelect({
+  permissions,
+  selected,
+  onChange,
+  disabled,
+}: {
+  permissions: PermissionSummary[];
+  selected: string[];
+  onChange: (next: string[]) => void;
+  disabled?: boolean;
+}) {
+  function toggle(slug: string) {
+    onChange(selected.includes(slug) ? selected.filter((s) => s !== slug) : [...selected, slug]);
+  }
+
+  const groups = groupPermissions(permissions);
+  const allSlugs = permissions.map((p) => p.slug);
+  const selectedCount = allSlugs.filter((slug) => selected.includes(slug)).length;
+  const allSelected = allSlugs.length > 0 && selectedCount === allSlugs.length;
+  const allState: boolean | "indeterminate" = allSelected ? true : selectedCount > 0 ? "indeterminate" : false;
+
+  function toggleAll() {
+    onChange(allSelected ? [] : allSlugs);
+  }
+
+  function toggleGroup(group: PermissionGroup) {
+    const groupSlugs = group.permissions.map((p) => p.slug);
+    const groupAllSelected = groupSlugs.every((slug) => selected.includes(slug));
+    onChange(groupAllSelected ? selected.filter((slug) => !groupSlugs.includes(slug)) : [...new Set([...selected, ...groupSlugs])]);
+  }
+
+  if (groups.length === 0) return <p className="text-sm text-muted-foreground">No permissions defined yet.</p>;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center justify-between">
+        <label className="flex items-center gap-2 text-sm font-medium">
+          <Checkbox checked={allState} onCheckedChange={toggleAll} disabled={disabled || allSlugs.length === 0} className={INDETERMINATE_STYLE} />
+          Select all
+        </label>
+        <span className="text-xs text-muted-foreground">
+          {selectedCount} of {allSlugs.length} selected
+        </span>
+      </div>
+      {groups.map((group) => {
+        const groupSlugs = group.permissions.map((p) => p.slug);
+        const groupSelectedCount = groupSlugs.filter((slug) => selected.includes(slug)).length;
+        const groupAllSelected = groupSlugs.length > 0 && groupSelectedCount === groupSlugs.length;
+        const groupState: boolean | "indeterminate" = groupAllSelected ? true : groupSelectedCount > 0 ? "indeterminate" : false;
+        return (
+          <Card key={group.name} className="p-4">
+            <label className="mb-2 flex items-center gap-2 text-sm font-semibold capitalize">
+              <Checkbox checked={groupState} onCheckedChange={() => toggleGroup(group)} disabled={disabled} className={INDETERMINATE_STYLE} />
+              {group.name}
+            </label>
+            <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+              {group.permissions.map((permission) => (
+                <label key={permission.id} className="flex items-center gap-2 text-sm">
+                  <Checkbox checked={selected.includes(permission.slug)} onCheckedChange={() => toggle(permission.slug)} disabled={disabled} />
+                  <span className={!permission.isActive ? "text-muted-foreground" : undefined}>
+                    {permission.displayName}
+                    {!permission.isActive && " (inactive)"}
+                  </span>
+                </label>
+              ))}
+            </div>
+          </Card>
+        );
+      })}
+    </div>
+  );
+}