cortena-ui 1.4.2 → 1.5.0

package/dist/components/admin-permissions/roles.js

@@ -0,0 +1,168 @@
+"use client";
+"use client";
+import { Button } from "../button.js";
+import { Chip } from "../chip.js";
+import { EmptyState } from "../empty-state.js";
+import { ErrorBanner } from "../error-banner.js";
+import { SectionCard } from "../section-card.js";
+import { createColumnHelper } from "../data-table/features.js";
+import { DataTable } from "../data-table/data-table.js";
+import { useAdminPermissions } from "./context.js";
+import { DirectRoles, RoleAssignmentDialog } from "./role-assignment.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/admin-permissions/roles.tsx
+const helper = /* @__PURE__ */ createColumnHelper();
+/**
+* `/admin/roles` — the extension's own vocabulary, and the group principals
+* that hold it.
+*
+* Two halves. The first is what each declared role grants, read straight off
+* the matrix, so an administrator deciding whether to hand somebody "editor"
+* can see what "editor" means without leaving the screen. The second is group
+* assignment: the other kind of principal a role attaches to (DESIGN-D22,
+* P-42), on the same screen as the users because it is the same decision.
+*
+* The groups list is a **client** source, and the members list is not, for one
+* reason: an org's groups are a short, bounded list that arrives in a single
+* `groups.list()`, so paging it server-side would be a round-trip per keypress
+* for nothing. Where the groups come from — a directory sync, or somebody
+* typing them into cortena-auth — is invisible here by design.
+*
+* The whole section disappears when the api has no `groups`, and equally when
+* it has some and the org has none.
+*/
+function AdminRoles() {
+	const { matrix, hasGroups, groups, groupsState, groupRoles } = useAdminPermissions();
+	const [editing, setEditing] = React.useState(null);
+	const [editingRoles, setEditingRoles] = React.useState([]);
+	const columns = React.useMemo(() => helper.columns([
+		helper.accessor("name", {
+			header: "Group",
+			cell: ({ row }) => /* @__PURE__ */ jsx("span", {
+				className: "font-medium text-[color:var(--ds-foreground)]",
+				children: row.original.name
+			}),
+			meta: { label: "Group" }
+		}),
+		helper.accessor("memberCount", {
+			header: "Members",
+			cell: ({ row }) => row.original.memberCount ?? "—",
+			meta: {
+				align: "end",
+				label: "Members"
+			}
+		}),
+		helper.display({
+			id: "roles",
+			header: "Roles",
+			cell: ({ row }) => /* @__PURE__ */ jsx(DirectRoles, { roles: groupRoles[row.original.id] ?? [] }),
+			meta: {
+				label: "Roles",
+				exportValue: (row) => (groupRoles[row.id] ?? []).join(", ")
+			},
+			enableSorting: false
+		}),
+		helper.display({
+			id: "actions",
+			header: () => /* @__PURE__ */ jsx("span", {
+				className: "sr-only",
+				children: "Actions"
+			}),
+			cell: ({ row }) => /* @__PURE__ */ jsx("div", {
+				className: "flex justify-end",
+				children: /* @__PURE__ */ jsx(Button, {
+					variant: "outline",
+					size: "sm",
+					"aria-label": `Edit roles for ${row.original.name}`,
+					onClick: () => {
+						setEditingRoles(groupRoles[row.original.id] ?? []);
+						setEditing({
+							kind: "group",
+							id: row.original.id,
+							name: row.original.name
+						});
+					},
+					children: "Edit roles"
+				})
+			}),
+			meta: {
+				align: "end",
+				exportable: false
+			},
+			enableSorting: false,
+			enableHiding: false
+		})
+	]), [groupRoles]);
+	const roles = matrix?.roles ?? [];
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "admin-roles",
+		className: "flex flex-col gap-6",
+		children: [
+			/* @__PURE__ */ jsx(SectionCard, {
+				title: "Roles",
+				description: "Declared by this extension. Nothing on the platform reads these names, so they are the extension's to choose.",
+				children: roles.length === 0 ? /* @__PURE__ */ jsx(EmptyState, {
+					size: "compact",
+					title: "No roles declared",
+					description: "Roles come from this extension's permissions document. Until it declares some, there is nothing to assign."
+				}) : /* @__PURE__ */ jsx("ul", {
+					"data-slot": "admin-role-list",
+					className: "flex flex-col gap-2",
+					children: roles.map((role) => {
+						const granted = matrix?.grants[role] ?? [];
+						return /* @__PURE__ */ jsxs("li", {
+							"data-slot": "admin-role-summary",
+							"data-role": role,
+							className: "flex flex-col gap-1.5 rounded-[var(--ds-radius-md)] border border-[var(--ds-border-subtle)] bg-[var(--ds-muted)] px-3 py-2.5",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "text-[length:var(--ds-text-body-sm)] font-semibold text-[color:var(--ds-foreground)]",
+								children: role
+							}), granted.length === 0 ? /* @__PURE__ */ jsx("span", {
+								className: "text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]",
+								children: "Grants nothing yet"
+							}) : /* @__PURE__ */ jsx("div", {
+								className: "flex flex-wrap items-center gap-1",
+								children: granted.map((action) => /* @__PURE__ */ jsx(Chip, {
+									size: "sm",
+									variant: "outline",
+									"data-action": action,
+									children: action
+								}, action))
+							})]
+						}, role);
+					})
+				})
+			}),
+			groupsState.error ? /* @__PURE__ */ jsx(ErrorBanner, {
+				message: groupsState.error.message,
+				onRetry: groupsState.reload
+			}) : null,
+			hasGroups ? /* @__PURE__ */ jsx(SectionCard, {
+				title: "Groups",
+				description: "Groups are cortena-auth's and read-only here. Every member of a group inherits the roles assigned to it, with no assignment write of their own.",
+				flush: true,
+				children: /* @__PURE__ */ jsx(DataTable, {
+					columns,
+					dataSource: {
+						kind: "client",
+						rows: groups
+					},
+					getRowId: (row) => row.id,
+					searchPlaceholder: "Search groups…",
+					emptyMessage: "No groups",
+					exportFileName: "groups"
+				})
+			}) : null,
+			/* @__PURE__ */ jsx(RoleAssignmentDialog, {
+				principal: editing,
+				current: editingRoles,
+				onOpenChange: (open) => !open && setEditing(null)
+			})
+		]
+	});
+}
+//#endregion
+export { AdminRoles };
+
+//# sourceMappingURL=roles.js.map

package/dist/components/admin-permissions/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","names":[],"sources":["../../../src/components/admin-permissions/roles.tsx"],"sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport { Button } from \"@/components/button\";\nimport { Chip } from \"@/components/chip\";\nimport { DataTable, createColumnHelper } from \"@/components/data-table\";\nimport { EmptyState } from \"@/components/empty-state\";\nimport { ErrorBanner } from \"@/components/error-banner\";\nimport { SectionCard } from \"@/components/section-card\";\nimport { useAdminPermissions } from \"./context\";\nimport { DirectRoles, RoleAssignmentDialog } from \"./role-assignment\";\nimport type { AdminGroupRow, AdminPrincipal } from \"./types\";\n\nconst helper = /* @__PURE__ */ createColumnHelper<AdminGroupRow>();\n\n/**\n * `/admin/roles` — the extension's own vocabulary, and the group principals\n * that hold it.\n *\n * Two halves. The first is what each declared role grants, read straight off\n * the matrix, so an administrator deciding whether to hand somebody \"editor\"\n * can see what \"editor\" means without leaving the screen. The second is group\n * assignment: the other kind of principal a role attaches to (DESIGN-D22,\n * P-42), on the same screen as the users because it is the same decision.\n *\n * The groups list is a **client** source, and the members list is not, for one\n * reason: an org's groups are a short, bounded list that arrives in a single\n * `groups.list()`, so paging it server-side would be a round-trip per keypress\n * for nothing. Where the groups come from — a directory sync, or somebody\n * typing them into cortena-auth — is invisible here by design.\n *\n * The whole section disappears when the api has no `groups`, and equally when\n * it has some and the org has none.\n */\nexport function AdminRoles() {\n  const { matrix, hasGroups, groups, groupsState, groupRoles } = useAdminPermissions();\n  const [editing, setEditing] = React.useState<AdminPrincipal | null>(null);\n  const [editingRoles, setEditingRoles] = React.useState<readonly string[]>([]);\n\n  const columns = React.useMemo(\n    () =>\n      helper.columns([\n        helper.accessor(\"name\", {\n          header: \"Group\",\n          cell: ({ row }) => (\n            <span className=\"font-medium text-[color:var(--ds-foreground)]\">\n              {row.original.name}\n            </span>\n          ),\n          meta: { label: \"Group\" },\n        }),\n        helper.accessor(\"memberCount\", {\n          header: \"Members\",\n          cell: ({ row }) => row.original.memberCount ?? \"—\",\n          meta: { align: \"end\", label: \"Members\" },\n        }),\n        helper.display({\n          id: \"roles\",\n          header: \"Roles\",\n          cell: ({ row }) => <DirectRoles roles={groupRoles[row.original.id] ?? []} />,\n          meta: {\n            label: \"Roles\",\n            exportValue: (row: AdminGroupRow) => (groupRoles[row.id] ?? []).join(\", \"),\n          },\n          enableSorting: false,\n        }),\n        helper.display({\n          id: \"actions\",\n          header: () => <span className=\"sr-only\">Actions</span>,\n          cell: ({ row }) => (\n            <div className=\"flex justify-end\">\n              <Button\n                variant=\"outline\"\n                size=\"sm\"\n                aria-label={`Edit roles for ${row.original.name}`}\n                onClick={() => {\n                  setEditingRoles(groupRoles[row.original.id] ?? []);\n                  setEditing({ kind: \"group\", id: row.original.id, name: row.original.name });\n                }}\n              >\n                Edit roles\n              </Button>\n            </div>\n          ),\n          meta: { align: \"end\", exportable: false },\n          enableSorting: false,\n          enableHiding: false,\n        }),\n      ]),\n    [groupRoles],\n  );\n\n  const roles = matrix?.roles ?? [];\n\n  return (\n    <div data-slot=\"admin-roles\" className=\"flex flex-col gap-6\">\n      <SectionCard\n        title=\"Roles\"\n        description=\"Declared by this extension. Nothing on the platform reads these names, so they are the extension's to choose.\"\n      >\n        {roles.length === 0 ? (\n          <EmptyState\n            size=\"compact\"\n            title=\"No roles declared\"\n            description=\"Roles come from this extension's permissions document. Until it declares some, there is nothing to assign.\"\n          />\n        ) : (\n          <ul data-slot=\"admin-role-list\" className=\"flex flex-col gap-2\">\n            {roles.map((role) => {\n              const granted = matrix?.grants[role] ?? [];\n              return (\n                <li\n                  key={role}\n                  data-slot=\"admin-role-summary\"\n                  data-role={role}\n                  className=\"flex flex-col gap-1.5 rounded-[var(--ds-radius-md)] border border-[var(--ds-border-subtle)] bg-[var(--ds-muted)] px-3 py-2.5\"\n                >\n                  <span className=\"text-[length:var(--ds-text-body-sm)] font-semibold text-[color:var(--ds-foreground)]\">\n                    {role}\n                  </span>\n                  {granted.length === 0 ? (\n                    <span className=\"text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]\">\n                      Grants nothing yet\n                    </span>\n                  ) : (\n                    <div className=\"flex flex-wrap items-center gap-1\">\n                      {granted.map((action) => (\n                        <Chip key={action} size=\"sm\" variant=\"outline\" data-action={action}>\n                          {action}\n                        </Chip>\n                      ))}\n                    </div>\n                  )}\n                </li>\n              );\n            })}\n          </ul>\n        )}\n      </SectionCard>\n\n      {groupsState.error ? (\n        <ErrorBanner message={groupsState.error.message} onRetry={groupsState.reload} />\n      ) : null}\n\n      {hasGroups ? (\n        <SectionCard\n          title=\"Groups\"\n          description=\"Groups are cortena-auth's and read-only here. Every member of a group inherits the roles assigned to it, with no assignment write of their own.\"\n          flush\n        >\n          <DataTable\n            columns={columns}\n            dataSource={{ kind: \"client\", rows: groups }}\n            getRowId={(row) => row.id}\n            searchPlaceholder=\"Search groups…\"\n            emptyMessage=\"No groups\"\n            exportFileName=\"groups\"\n          />\n        </SectionCard>\n      ) : null}\n\n      <RoleAssignmentDialog\n        principal={editing}\n        current={editingRoles}\n        onOpenChange={(open) => !open && setEditing(null)}\n      />\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/components/admin-permissions/types.d.ts

@@ -0,0 +1,152 @@
+"use client";
+import { TableQuery, TableResult } from "../data-table/types.js";
+import "../data-table/index.js";
+//#region src/components/admin-permissions/types.d.ts
+/**
+ * A role is assigned to a principal, never to a user id (DESIGN-D22, §13.4).
+ * Both kinds are edited on the same screen and through the same dialog; only
+ * the method underneath differs.
+ */
+export interface AdminPrincipal {
+  kind: "user" | "group";
+  /** cortena-auth user id, or cortena-auth group id. */
+  id: string;
+  /** Display name, for the dialog title. */
+  name?: string;
+}
+/** A group, as a member's row refers to it. Defined and maintained in cortena-auth. */
+export interface AdminGroupRef {
+  id: string;
+  name: string;
+}
+/**
+ * Why a member holds an effective role: assigned to them directly, or carried
+ * by a group they belong to. Never dropped from the rendering — an
+ * administrator who cannot see *why* somebody has a permission removes the
+ * wrong assignment and believes the job is done (P-43).
+ */
+export type AdminRoleSource = "direct" | {
+  group: AdminGroupRef;
+};
+/** One entry of `effectiveRoles`: the role, and the assignment that granted it. */
+export interface AdminEffectiveRole {
+  role: string;
+  source: AdminRoleSource;
+}
+/**
+ * A row of `members.list`. A join: the person and their groups are
+ * cortena-auth's and read-only; `extensionRoles` is the extension's own direct
+ * assignment; `effectiveRoles` is the per-request resolution of direct +
+ * inherited that `may()` performs, rendered — never a stored table (P-43).
+ */
+export interface AdminMemberRow {
+  userId: string;
+  name: string;
+  email: string;
+  status: string;
+  /** ISO timestamp, or null when the user has never signed in. */
+  lastActiveAt: string | null;
+  groups: AdminGroupRef[];
+  extensionRoles: string[];
+  effectiveRoles: AdminEffectiveRole[];
+}
+/**
+ * A row of `groups.list` — read-only as to the group itself. The roles a group
+ * carries are the extension's and come back separately from `groups.roles()`,
+ * because the group list is identity's and the assignment map is not.
+ */
+export interface AdminGroupRow {
+  id: string;
+  name: string;
+  memberCount: number;
+}
+/** `licence.get` — a read-through display of cortena-auth's licence. */
+export interface AdminLicence {
+  plan: string;
+  seats: number | null;
+  seatsUsed: number | null;
+  features: string[];
+}
+/**
+ * `permissions.get` / `permissions.put` — the extension's own matrix, in the
+ * extension's own database. This is the source of truth that both the REST
+ * routes and the MCP tools enforce through one `may()` (§13.2, P-14).
+ */
+export interface AdminPermissionMatrix {
+  roles: string[];
+  actions: string[];
+  /** role → the actions it grants. A role absent from the map grants nothing. */
+  grants: Record<string, string[]>;
+}
+/**
+ * Everything the composition talks to, one namespace per resource in §13.3.
+ *
+ * `groups` is the only optional member, and it is optional for a reason rather
+ * than for convenience: an extension whose cortena-auth tenant has no groups
+ * omits it, and every group affordance disappears instead of rendering empty.
+ * It disappears equally when `groups.list()` comes back empty — an empty
+ * "Groups" section reads as a broken feature, and there is nothing an
+ * administrator can do about it from here.
+ */
+export interface AdminPermissionsApi {
+  members: {
+    /** `GET .../admin/members` — the DataTable server source. */
+    list: (query: TableQuery, signal?: AbortSignal) => Promise<TableResult<AdminMemberRow>>;
+    /** `PATCH .../admin/members/:userId { extensionRoles }` — direct assignment only. */
+    setRoles: (userId: string, roles: string[]) => Promise<void>;
+  };
+  groups?: {
+    /** `GET .../admin/groups` — read-only; the whole list, small enough to be a client source. */
+    list: (signal?: AbortSignal) => Promise<AdminGroupRow[]>;
+    /** The extension's assignment: group id → the roles that group carries. */
+    roles: (signal?: AbortSignal) => Promise<Record<string, string[]>>;
+    /** `PATCH .../admin/groups/:groupId { extensionRoles }` */
+    setRoles: (groupId: string, roles: string[]) => Promise<void>;
+  };
+  licence: {
+    /** `GET .../admin/licence` — read-only, always. */
+    get: (signal?: AbortSignal) => Promise<AdminLicence>;
+  };
+  permissions: {
+    /** `GET .../admin/permissions` */
+    get: (signal?: AbortSignal) => Promise<AdminPermissionMatrix>;
+    /** `PUT .../admin/permissions` */
+    put: (matrix: AdminPermissionMatrix, signal?: AbortSignal) => Promise<AdminPermissionMatrix | void>;
+  };
+}
+/** The four screens, named after their paths under `admin/`. */
+export type AdminRoute = "members" | "roles" | "licence" | "permissions";
+export declare const ADMIN_ROUTES: readonly AdminRoute[];
+export declare const ADMIN_ROUTE_LABELS: Record<AdminRoute, string>;
+/**
+ * The broker's error envelope (§15.6). A failed mutation must show what the
+ * server said — "assigneeId: Required" and "Invalid input" cost the same to
+ * produce and differ by a whole round-trip — so the rejection is unwrapped
+ * rather than replaced with a house message.
+ */
+export interface AdminErrorEnvelope {
+  ok: false;
+  status?: number;
+  code?: string;
+  message: string;
+  details?: unknown;
+}
+/**
+ * The message to show for a rejection.
+ *
+ * A fetch wrapper usually rejects with an `Error` and hangs the parsed
+ * envelope off it, so the envelope is preferred over the generic
+ * `"HTTP 403"` the Error itself carries. A rejection that *is* the envelope,
+ * and a plain `Error`, both work as well.
+ */
+export declare function adminErrorMessage(error: unknown): string;
+/**
+ * The effective roles to render. When the server sends none, the direct
+ * assignments are shown as direct — which is what they are — rather than the
+ * screen inventing an inheritance it cannot know about.
+ */
+export declare function effectiveRolesOf(row: AdminMemberRow): AdminEffectiveRole[];
+/** The group behind an effective role, or `null` for a direct assignment. */
+export declare function sourceGroupOf(source: AdminRoleSource): AdminGroupRef | null;
+//#endregion
+//# sourceMappingURL=types.d.ts.map

package/dist/components/admin-permissions/types.js

@@ -0,0 +1,63 @@
+"use client";
+//#region src/components/admin-permissions/types.ts
+const ADMIN_ROUTES = [
+	"members",
+	"roles",
+	"licence",
+	"permissions"
+];
+const ADMIN_ROUTE_LABELS = {
+	members: "Members",
+	roles: "Roles",
+	licence: "Licence",
+	permissions: "Permissions"
+};
+function envelopeMessage(value) {
+	if (!value || typeof value !== "object") return null;
+	const message = value.message;
+	return typeof message === "string" && message.length > 0 ? message : null;
+}
+/**
+* The message to show for a rejection.
+*
+* A fetch wrapper usually rejects with an `Error` and hangs the parsed
+* envelope off it, so the envelope is preferred over the generic
+* `"HTTP 403"` the Error itself carries. A rejection that *is* the envelope,
+* and a plain `Error`, both work as well.
+*/
+function adminErrorMessage(error) {
+	if (error && typeof error === "object") {
+		const carrier = error;
+		const nested = envelopeMessage(carrier.envelope) ?? envelopeMessage(carrier.body) ?? envelopeMessage(carrier.error);
+		if (nested) return nested;
+	}
+	if (error instanceof Error) return error.message || "Something went wrong";
+	const direct = envelopeMessage(error);
+	if (direct) return direct;
+	return String(error);
+}
+/** Tolerates a server that omits an array the contract says is required. */
+function groupsOf(row) {
+	return row.groups ?? [];
+}
+/**
+* The effective roles to render. When the server sends none, the direct
+* assignments are shown as direct — which is what they are — rather than the
+* screen inventing an inheritance it cannot know about.
+*/
+function effectiveRolesOf(row) {
+	if (row.effectiveRoles?.length) return row.effectiveRoles;
+	return (row.extensionRoles ?? []).map((role) => ({
+		role,
+		source: "direct"
+	}));
+}
+/** The group behind an effective role, or `null` for a direct assignment. */
+function sourceGroupOf(source) {
+	if (source === "direct" || !source) return null;
+	return source.group ?? null;
+}
+//#endregion
+export { ADMIN_ROUTES, ADMIN_ROUTE_LABELS, adminErrorMessage, effectiveRolesOf, groupsOf, sourceGroupOf };
+
+//# sourceMappingURL=types.js.map

package/dist/components/admin-permissions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/components/admin-permissions/types.ts"],"sourcesContent":["/**\n * The contract AdminPermissions renders, from §13.3 of\n * \"How to create a Cortena extension\" (DESIGN-D11, amended by DESIGN-D22).\n *\n * The composition ships **no vocabulary of its own**. Every role, every action\n * and every grant on screen arrives through the `api` prop; every principal\n * arrives through it too. That is what lets two extensions with completely\n * different role models look like one product — and it is why nothing in this\n * folder has a default role list, a default action list, or an opinion about\n * what \"admin\" means.\n *\n * The split the screen is built around:\n *\n * | cortena-auth owns | the extension owns |\n * | --- | --- |\n * | who the user is, their org membership and status | every role it recognises |\n * | the groups, their names and their membership | the roles × actions matrix |\n * | the licence | which principal holds which role |\n *\n * So the person half of the members list is read-only here, the group half is\n * read-only too, and the roles beside them are the only editable thing.\n *\n * Where the groups come from is deliberately invisible: an extension asks\n * `api.groups` for `{ id, name, memberCount }` and never learns whether that\n * is a directory sync, an SCIM push or a hand-made list in cortena-auth.\n */\n\nimport type { TableQuery, TableResult } from \"@/components/data-table\";\n\n/**\n * A role is assigned to a principal, never to a user id (DESIGN-D22, §13.4).\n * Both kinds are edited on the same screen and through the same dialog; only\n * the method underneath differs.\n */\nexport interface AdminPrincipal {\n  kind: \"user\" | \"group\";\n  /** cortena-auth user id, or cortena-auth group id. */\n  id: string;\n  /** Display name, for the dialog title. */\n  name?: string;\n}\n\n/** A group, as a member's row refers to it. Defined and maintained in cortena-auth. */\nexport interface AdminGroupRef {\n  id: string;\n  name: string;\n}\n\n/**\n * Why a member holds an effective role: assigned to them directly, or carried\n * by a group they belong to. Never dropped from the rendering — an\n * administrator who cannot see *why* somebody has a permission removes the\n * wrong assignment and believes the job is done (P-43).\n */\nexport type AdminRoleSource = \"direct\" | { group: AdminGroupRef };\n\n/** One entry of `effectiveRoles`: the role, and the assignment that granted it. */\nexport interface AdminEffectiveRole {\n  role: string;\n  source: AdminRoleSource;\n}\n\n/**\n * A row of `members.list`. A join: the person and their groups are\n * cortena-auth's and read-only; `extensionRoles` is the extension's own direct\n * assignment; `effectiveRoles` is the per-request resolution of direct +\n * inherited that `may()` performs, rendered — never a stored table (P-43).\n */\nexport interface AdminMemberRow {\n  userId: string;\n  name: string;\n  email: string;\n  status: string;\n  /** ISO timestamp, or null when the user has never signed in. */\n  lastActiveAt: string | null;\n  groups: AdminGroupRef[];\n  extensionRoles: string[];\n  effectiveRoles: AdminEffectiveRole[];\n}\n\n/**\n * A row of `groups.list` — read-only as to the group itself. The roles a group\n * carries are the extension's and come back separately from `groups.roles()`,\n * because the group list is identity's and the assignment map is not.\n */\nexport interface AdminGroupRow {\n  id: string;\n  name: string;\n  memberCount: number;\n}\n\n/** `licence.get` — a read-through display of cortena-auth's licence. */\nexport interface AdminLicence {\n  plan: string;\n  seats: number | null;\n  seatsUsed: number | null;\n  features: string[];\n}\n\n/**\n * `permissions.get` / `permissions.put` — the extension's own matrix, in the\n * extension's own database. This is the source of truth that both the REST\n * routes and the MCP tools enforce through one `may()` (§13.2, P-14).\n */\nexport interface AdminPermissionMatrix {\n  roles: string[];\n  actions: string[];\n  /** role → the actions it grants. A role absent from the map grants nothing. */\n  grants: Record<string, string[]>;\n}\n\n/**\n * Everything the composition talks to, one namespace per resource in §13.3.\n *\n * `groups` is the only optional member, and it is optional for a reason rather\n * than for convenience: an extension whose cortena-auth tenant has no groups\n * omits it, and every group affordance disappears instead of rendering empty.\n * It disappears equally when `groups.list()` comes back empty — an empty\n * \"Groups\" section reads as a broken feature, and there is nothing an\n * administrator can do about it from here.\n */\nexport interface AdminPermissionsApi {\n  members: {\n    /** `GET .../admin/members` — the DataTable server source. */\n    list: (query: TableQuery, signal?: AbortSignal) => Promise<TableResult<AdminMemberRow>>;\n    /** `PATCH .../admin/members/:userId { extensionRoles }` — direct assignment only. */\n    setRoles: (userId: string, roles: string[]) => Promise<void>;\n  };\n  groups?: {\n    /** `GET .../admin/groups` — read-only; the whole list, small enough to be a client source. */\n    list: (signal?: AbortSignal) => Promise<AdminGroupRow[]>;\n    /** The extension's assignment: group id → the roles that group carries. */\n    roles: (signal?: AbortSignal) => Promise<Record<string, string[]>>;\n    /** `PATCH .../admin/groups/:groupId { extensionRoles }` */\n    setRoles: (groupId: string, roles: string[]) => Promise<void>;\n  };\n  licence: {\n    /** `GET .../admin/licence` — read-only, always. */\n    get: (signal?: AbortSignal) => Promise<AdminLicence>;\n  };\n  permissions: {\n    /** `GET .../admin/permissions` */\n    get: (signal?: AbortSignal) => Promise<AdminPermissionMatrix>;\n    /** `PUT .../admin/permissions` */\n    put: (\n      matrix: AdminPermissionMatrix,\n      signal?: AbortSignal,\n    ) => Promise<AdminPermissionMatrix | void>;\n  };\n}\n\n/** The four screens, named after their paths under `admin/`. */\nexport type AdminRoute = \"members\" | \"roles\" | \"licence\" | \"permissions\";\n\nexport const ADMIN_ROUTES: readonly AdminRoute[] = [\n  \"members\",\n  \"roles\",\n  \"licence\",\n  \"permissions\",\n];\n\nexport const ADMIN_ROUTE_LABELS: Record<AdminRoute, string> = {\n  members: \"Members\",\n  roles: \"Roles\",\n  licence: \"Licence\",\n  permissions: \"Permissions\",\n};\n\n/**\n * The broker's error envelope (§15.6). A failed mutation must show what the\n * server said — \"assigneeId: Required\" and \"Invalid input\" cost the same to\n * produce and differ by a whole round-trip — so the rejection is unwrapped\n * rather than replaced with a house message.\n */\nexport interface AdminErrorEnvelope {\n  ok: false;\n  status?: number;\n  code?: string;\n  message: string;\n  details?: unknown;\n}\n\nfunction envelopeMessage(value: unknown): string | null {\n  if (!value || typeof value !== \"object\") return null;\n  const message = (value as { message?: unknown }).message;\n  return typeof message === \"string\" && message.length > 0 ? message : null;\n}\n\n/**\n * The message to show for a rejection.\n *\n * A fetch wrapper usually rejects with an `Error` and hangs the parsed\n * envelope off it, so the envelope is preferred over the generic\n * `\"HTTP 403\"` the Error itself carries. A rejection that *is* the envelope,\n * and a plain `Error`, both work as well.\n */\nexport function adminErrorMessage(error: unknown): string {\n  if (error && typeof error === \"object\") {\n    const carrier = error as { envelope?: unknown; body?: unknown; error?: unknown };\n    const nested =\n      envelopeMessage(carrier.envelope) ??\n      envelopeMessage(carrier.body) ??\n      envelopeMessage(carrier.error);\n    if (nested) return nested;\n  }\n  if (error instanceof Error) return error.message || \"Something went wrong\";\n  const direct = envelopeMessage(error);\n  if (direct) return direct;\n  return String(error);\n}\n\n/** Tolerates a server that omits an array the contract says is required. */\nexport function groupsOf(row: AdminMemberRow): AdminGroupRef[] {\n  return row.groups ?? [];\n}\n\n/**\n * The effective roles to render. When the server sends none, the direct\n * assignments are shown as direct — which is what they are — rather than the\n * screen inventing an inheritance it cannot know about.\n */\nexport function effectiveRolesOf(row: AdminMemberRow): AdminEffectiveRole[] {\n  if (row.effectiveRoles?.length) return row.effectiveRoles;\n  return (row.extensionRoles ?? []).map((role) => ({ role, source: \"direct\" as const }));\n}\n\n/** The group behind an effective role, or `null` for a direct assignment. */\nexport function sourceGroupOf(source: AdminRoleSource): AdminGroupRef | null {\n  if (source === \"direct\" || !source) return null;\n  return source.group ?? null;\n}\n"],"mappings":";;AA0JA,MAAa,eAAsC;CACjD;CACA;CACA;CACA;AACF;AAEA,MAAa,qBAAiD;CAC5D,SAAS;CACT,OAAO;CACP,SAAS;CACT,aAAa;AACf;AAgBA,SAAS,gBAAgB,OAA+B;CACtD,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO;CAChD,MAAM,UAAW,MAAgC;CACjD,OAAO,OAAO,YAAY,YAAY,QAAQ,SAAS,IAAI,UAAU;AACvE;;;;;;;;;AAUA,SAAgB,kBAAkB,OAAwB;CACxD,IAAI,SAAS,OAAO,UAAU,UAAU;EACtC,MAAM,UAAU;EAChB,MAAM,SACJ,gBAAgB,QAAQ,QAAQ,KAChC,gBAAgB,QAAQ,IAAI,KAC5B,gBAAgB,QAAQ,KAAK;EAC/B,IAAI,QAAQ,OAAO;CACrB;CACA,IAAI,iBAAiB,OAAO,OAAO,MAAM,WAAW;CACpD,MAAM,SAAS,gBAAgB,KAAK;CACpC,IAAI,QAAQ,OAAO;CACnB,OAAO,OAAO,KAAK;AACrB;;AAGA,SAAgB,SAAS,KAAsC;CAC7D,OAAO,IAAI,UAAU,CAAC;AACxB;;;;;;AAOA,SAAgB,iBAAiB,KAA2C;CAC1E,IAAI,IAAI,gBAAgB,QAAQ,OAAO,IAAI;CAC3C,QAAQ,IAAI,kBAAkB,CAAC,EAAA,CAAG,KAAK,UAAU;EAAE;EAAM,QAAQ;CAAkB,EAAE;AACvF;;AAGA,SAAgB,cAAc,QAA+C;CAC3E,IAAI,WAAW,YAAY,CAAC,QAAQ,OAAO;CAC3C,OAAO,OAAO,SAAS;AACzB"}

package/dist/components/agent-chat-popup.d.ts

@@ -0,0 +1,29 @@
+"use client";
+import { AgentChatClient } from "../agent-chat/types.js";
+import { AgentChatProps } from "./agent-chat.js";
+import * as React from "react";
+//#region src/components/agent-chat-popup.d.ts
+export type AgentChatPopupState = "pill" | "panel" | "full";
+export interface AgentChatPopupExtension {
+  /** Registered mark id — the same `x-cortena.icon` the shell draws. */
+  id: string;
+  /** Display name. Also the agent template slug, unless `agentId` overrides it. */
+  name: string;
+}
+export interface AgentChatPopupProps extends Omit<AgentChatProps, "agentName" | "storageScope" | "className" | "headerSlot" | "client"> {
+  extension: AgentChatPopupExtension;
+  /** The transport. Its `agentId` is the template slug the sessions belong to. */
+  client: AgentChatClient;
+  /**
+   * Names the `sessionStorage` slots. Defaults to the extension id, which is
+   * what keeps two extensions on one origin out of each other's sessions.
+   */
+  storageScope?: string;
+  /** Start here instead of collapsed; the stored state still wins on reload. */
+  defaultState?: AgentChatPopupState;
+  className?: string;
+}
+declare function AgentChatPopup({ extension, client, storageScope, defaultState, className, ...chatProps }: AgentChatPopupProps): React.JSX.Element;
+//#endregion
+export { AgentChatPopup };
+//# sourceMappingURL=agent-chat-popup.d.ts.map

package/dist/components/agent-chat-popup.js

@@ -0,0 +1,188 @@
+"use client";
+"use client";
+import { cn } from "../lib/cn.js";
+import { BrandMark } from "./app-shell.js";
+import { Button } from "./button.js";
+import { viewStorageKey, windowSessionStorage } from "../agent-chat/session.js";
+import { AgentChat } from "./agent-chat.js";
+import { Maximize2, Minimize2, X } from "lucide-react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/agent-chat-popup.tsx
+/**
+* AgentChatPopup — the extension's own agent, in the corner of every screen.
+*
+* §17 of how-to-create-a-cortena-extension, audit rule P-25. Mounted in
+* `AppShell`'s `agentSlot`, so it stacks above the theme/help cluster rather
+* than beside it and no extension positions a floating control itself.
+*
+* ```tsx
+* <AppShell
+*   extension={{ id: "tasks", name: "Tasks" }}
+*   user={user}
+*   agentSlot={
+*     <AgentChatPopup
+*       extension={{ id: "tasks", name: "Tasks" }}
+*       client={client}   // createAguiAgentChatClient({ …, agentId: "tasks" })
+*     />
+*   }
+* />
+* ```
+*
+* Three states, and the transitions between them are fixed: a collapsed pill,
+* a panel, and full screen. **Cmd/Ctrl+J** toggles between the pill and the
+* panel; **Escape** steps full screen -> panel -> pill, except while a run is
+* streaming, where the composer takes Escape to mean "stop" — the first Escape
+* during a run is nearly always about the run, not about the window.
+*
+* The chat stays mounted in every state, hidden rather than unmounted while
+* collapsed. That is not an optimisation: a run started before the user
+* collapsed the pop-up keeps streaming into it, and the unread dot on the pill
+* is what says so. Unmounting would throw the reply away halfway through.
+*
+* State is remembered per window, in `sessionStorage`, alongside the session
+* key — a second window of the same extension opens its own chat on its own
+* session rather than inheriting this one's.
+*/
+/** Cmd on a Mac, Ctrl elsewhere. Documented in README.md. */
+function isToggleShortcut(event) {
+	return (event.metaKey || event.ctrlKey) && !event.altKey && event.key.toLowerCase() === "j";
+}
+function AgentChatPopup({ extension, client, storageScope, defaultState = "pill", className, ...chatProps }) {
+	const scope = storageScope ?? extension.id;
+	const [state, setState] = React.useState(defaultState);
+	const [unread, setUnread] = React.useState(false);
+	const stateRef = React.useRef(state);
+	stateRef.current = state;
+	const pillRef = React.useRef(null);
+	const panelRef = React.useRef(null);
+	/** Whether the user has opened or closed it, as against it starting open. */
+	const moved = React.useRef(false);
+	React.useEffect(() => {
+		try {
+			const stored = windowSessionStorage()?.getItem(viewStorageKey(scope));
+			if (stored === "pill" || stored === "panel" || stored === "full") setState(stored);
+		} catch {}
+	}, [scope]);
+	const go = React.useCallback((next) => {
+		moved.current = true;
+		setState(next);
+		if (next !== "pill") setUnread(false);
+		try {
+			windowSessionStorage()?.setItem(viewStorageKey(scope), next);
+		} catch {}
+	}, [scope]);
+	React.useEffect(() => {
+		return client.onChat((event) => {
+			if (stateRef.current === "pill" && (event.state === "delta" || event.state === "final")) setUnread(true);
+		});
+	}, [client]);
+	React.useEffect(() => {
+		const onKeyDown = (event) => {
+			if (!isToggleShortcut(event)) return;
+			event.preventDefault();
+			go(stateRef.current === "pill" ? "panel" : "pill");
+		};
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, [go]);
+	/**
+	* Escape steps down one level. It is handled on the panel rather than on the
+	* window so it only fires when focus is inside the pop-up, and it arrives
+	* here only when the composer did not claim it — the composer stops
+	* propagation while a run is streaming, where Escape means "stop the run".
+	*/
+	const onKeyDown = React.useCallback((event) => {
+		if (event.key !== "Escape") return;
+		event.preventDefault();
+		go(stateRef.current === "full" ? "panel" : "pill");
+	}, [go]);
+	const open = state !== "pill";
+	/**
+	* Focus follows the pop-up.
+	*
+	* The panel is `hidden`, not unmounted, so nothing moves focus by itself.
+	* Opening left focus on the pill — which is now `hidden`, so the browser
+	* resets it to <body> and the next Tab starts at the top of the page rather
+	* than in the chat that was just opened. Closing had the mirror problem:
+	* focus was inside a subtree that had just become hidden.
+	*
+	* Only after the user moves it. A pop-up that starts on `panel`, or one
+	* restored from `sessionStorage` on load, must not steal focus from the page.
+	*/
+	React.useEffect(() => {
+		if (!moved.current) return;
+		const frame = requestAnimationFrame(() => {
+			if (open) panelRef.current?.querySelector("[data-slot=\"agent-chat-input\"]")?.focus({ preventScroll: true });
+			else pillRef.current?.focus({ preventScroll: true });
+		});
+		return () => cancelAnimationFrame(frame);
+	}, [open]);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+		ref: pillRef,
+		type: "button",
+		"data-slot": "agent-chat-pill",
+		"data-state": state,
+		"data-unread": unread ? "" : void 0,
+		"aria-expanded": open,
+		"aria-label": `Ask ${extension.name}`,
+		hidden: open,
+		onClick: () => go("panel"),
+		className: cn("relative inline-flex h-10 items-center gap-2 rounded-[var(--ds-radius-full)] px-3.5", "border border-[var(--ds-border)] bg-[var(--ds-card)] text-[color:var(--ds-foreground)]", "shadow-[var(--ds-shadow-md)] outline-none", "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]", "hover:bg-[var(--ds-hover)]", "focus-visible:ring-2 focus-visible:ring-[var(--ds-ring)] focus-visible:ring-offset-2", "focus-visible:ring-offset-[var(--ds-background)]", className),
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "flex size-5 items-center justify-center text-[color:var(--ds-primary)]",
+				children: /* @__PURE__ */ jsx(BrandMark, {
+					id: extension.id,
+					name: extension.name,
+					size: 16,
+					decorative: true
+				})
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				className: "text-[length:var(--ds-text-caption-lg)] font-medium",
+				children: ["Ask ", extension.name]
+			}),
+			unread ? /* @__PURE__ */ jsx("span", {
+				"data-slot": "agent-chat-pill-unread",
+				"aria-label": "The agent is replying",
+				className: "size-2 rounded-[var(--ds-radius-full)] bg-[var(--ds-primary)]"
+			}) : null
+		]
+	}), /* @__PURE__ */ jsx("div", {
+		ref: panelRef,
+		"data-slot": "agent-chat-panel",
+		"data-state": state,
+		role: "dialog",
+		"aria-label": `${extension.name} agent`,
+		hidden: !open,
+		onKeyDown,
+		className: cn("fixed z-50 flex flex-col overflow-hidden border border-[var(--ds-border)]", "bg-[var(--ds-card)] shadow-[var(--ds-shadow-lg)]", state === "full" ? "inset-0 rounded-none" : cn("right-6 bottom-6 rounded-[var(--ds-radius-lg)]", "h-[min(40rem,calc(100vh-3rem))] w-[min(26.25rem,calc(100vw-3rem))]")),
+		children: /* @__PURE__ */ jsx(AgentChat, {
+			client,
+			agentName: extension.name,
+			storageScope: scope,
+			className: "min-h-0 flex-1",
+			headerSlot: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Button, {
+				size: "icon-sm",
+				variant: "ghost",
+				"data-slot": "agent-chat-expand",
+				"aria-label": state === "full" ? "Restore the panel" : "Expand to full screen",
+				onClick: () => go(state === "full" ? "panel" : "full"),
+				children: state === "full" ? /* @__PURE__ */ jsx(Minimize2, { "aria-hidden": true }) : /* @__PURE__ */ jsx(Maximize2, { "aria-hidden": true })
+			}), /* @__PURE__ */ jsx(Button, {
+				size: "icon-sm",
+				variant: "ghost",
+				"data-slot": "agent-chat-collapse",
+				"aria-label": "Collapse the agent",
+				onClick: () => go("pill"),
+				children: /* @__PURE__ */ jsx(X, { "aria-hidden": true })
+			})] }),
+			...chatProps
+		})
+	})] });
+}
+//#endregion
+export { AgentChatPopup };
+
+//# sourceMappingURL=agent-chat-popup.js.map