cortena-ui 1.4.2 → 1.5.0

package/dist/agent-chat/types.d.ts

@@ -0,0 +1,187 @@
+"use client";
+import { A2UIChatBlock } from "./a2ui-block.js";
+//#region src/agent-chat/types.d.ts
+/**
+ * A row of `sessions.list`.
+ *
+ * Titles fall back in a fixed order (§17.2 of the extension how-to):
+ * `label`, `autoTitle`, `derivedTitle`, `displayName`, `lastMessagePreview`,
+ * then "New conversation". `sessionTitle` below is that order, in one place.
+ */
+export interface AgentSession {
+  /** The session key, verbatim — this is also the AG-UI `threadId`. */
+  key: string;
+  label?: string | null;
+  autoTitle?: string | null;
+  derivedTitle?: string | null;
+  displayName?: string | null;
+  lastMessagePreview?: string | null;
+  updatedAt?: number | null;
+}
+/** The title to show for a session row. */
+export declare function sessionTitle(session: AgentSession): string;
+export interface AgentChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  timestamp: number;
+  attachments?: string[];
+  /** The chain of thought behind this turn, collapsed by default. */
+  thinkingText?: string;
+  isError?: boolean;
+  /** True when the wire record was a tool call or a tool result; hidden. */
+  isToolMessage?: boolean;
+  /**
+   * The run that produced this message. Absent on anything loaded from
+   * history. A `final` folds into the previous bubble only when the two share
+   * this value, so one run's answer cannot be rewritten by the next one's.
+   */
+  runId?: string;
+  /** UI the agent drew, carried outside the prose. */
+  a2ui?: A2UIChatBlock[];
+}
+/**
+ * One chat event. The same `{ state: "delta" | "final" | "error" }` shape
+ * cortenacore broadcasts, so a client for a different transport has a
+ * documented target to hit.
+ *
+ * `delta` carries a SNAPSHOT, not an increment: every delta repeats all the
+ * text, all the thinking and every A2UI block seen so far. Two transports that
+ * disagree about this leave the store in different states for the same run.
+ */
+export interface AgentChatEvent {
+  runId: string;
+  sessionKey: string;
+  seq: number;
+  state: "delta" | "final" | "error";
+  message?: {
+    role?: string;
+    content?: Array<{
+      type: string;
+      text?: string;
+      thinking?: string;
+      a2ui?: unknown;
+    }>;
+    timestamp?: number;
+  };
+  errorMessage?: string;
+}
+/** One step of the tool strip. */
+export interface AgentToolEvent {
+  event: "tool.start" | "tool.args" | "tool.progress" | "tool.complete" | "tool.error";
+  data: {
+    id?: string;
+    name?: string;
+    /** `tool.args`: the call's input, parsed when it was valid JSON. */
+    input?: unknown;
+    output?: unknown;
+    startedAt?: number;
+    completedAt?: number;
+  };
+}
+/** Decisions cortenacore accepts on `POST /agui/approval`. */
+export type AgentApprovalDecision = "allow-once" | "allow-always" | "deny";
+export interface AgentApprovalRequest {
+  id: string;
+  /** The command, or the tool, the approval is about. */
+  toolName: string;
+  args: Record<string, unknown>;
+  timestamp: number;
+  /**
+   * The run and the session this request arrived on, captured when it arrived.
+   *
+   * A decision is bound to them rather than resolved against whatever run
+   * happens to be in flight when the user presses a button. The two come
+   * apart routinely: an approval pauses a run, the user opens another session
+   * in the drawer or starts a second turn, and the client's idea of "the
+   * current thread" has moved on. Answering "allow" against the wrong thread
+   * is a command approved in a conversation nobody was asked about.
+   */
+  runId: string;
+  sessionKey: string;
+  /** Set when a decision was made and the server would not take it. */
+  error?: string;
+}
+/** Where an approval came from, and therefore where the decision must go. */
+export interface AgentApprovalContext {
+  runId: string;
+  sessionKey: string;
+}
+export type AgentApprovalEvent = {
+  type: "request";
+  request: AgentApprovalRequest;
+} |
+/** `decision: null` is an expiry. It is treated as a denial. */
+{
+  type: "resolved";
+  id: string;
+  decision: AgentApprovalDecision | null;
+};
+export interface AgentChatSendInput {
+  /** The session key to run in. `threadId` is this value verbatim. */
+  sessionKey: string;
+  /** What the user typed. Empty for an action sent by rendered UI. */
+  message: string;
+  /** The run id; also the idempotency key. */
+  runId: string;
+  attachments?: unknown[];
+  thinking?: "low" | "medium" | "high";
+  model?: {
+    provider: string;
+    model: string;
+  };
+  /** A click inside an A2UI surface. Never a sentence the user appears to type. */
+  a2uiAction?: {
+    surfaceId: string;
+    componentId: string;
+    name: string;
+    payload: Record<string, unknown>;
+  };
+  /** The same, from inside a rendered MCP App. */
+  mcpAppAction?: Record<string, unknown>;
+}
+/**
+ * Everything `AgentChat` needs from a server.
+ *
+ * `request` is deliberately a method name plus params rather than a URL: the
+ * two calls the chat makes — `sessions.list` and `chat.history` — are control
+ * plane methods, and a host that proxies them through its own gateway chooses
+ * its own paths.
+ */
+export interface AgentChatClient {
+  /** The agent this client talks to. Session keys are `agent:<agentId>:…`. */
+  readonly agentId: string;
+  /** Start a run. Resolves when the run has been accepted, not when it ends. */
+  send(input: AgentChatSendInput): Promise<void>;
+  /** Stop the run in flight. Best-effort; local state resets either way. */
+  abort(params?: {
+    runId?: string;
+    sessionKey?: string;
+  }): Promise<void>;
+  /**
+   * Answer an approval. `context` is the `{ runId, sessionKey }` the request
+   * carried, not the run in flight — see `AgentApprovalRequest`. Rejects when
+   * the server refuses the decision, so the caller can put the card back.
+   */
+  resolveApproval(id: string, decision: AgentApprovalDecision, context: AgentApprovalContext): Promise<void>;
+  /** `sessions.list` and `chat.history`. */
+  request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+  /** Chat deltas, finals and errors. Returns an unsubscribe. */
+  onChat(sink: (event: AgentChatEvent) => void): () => void;
+  /** Tool starts, arguments, progress and results. Returns an unsubscribe. */
+  onTool(sink: (event: AgentToolEvent) => void): () => void;
+  /** Approval requests and resolutions. Returns an unsubscribe. */
+  onApproval(sink: (event: AgentApprovalEvent) => void): () => void;
+}
+/** What `sessions.list` answers. */
+export interface AgentSessionsListResponse {
+  sessions?: AgentSession[];
+}
+/** What `chat.history` answers. `messages` are raw transcript records. */
+export interface AgentChatHistoryResponse {
+  messages?: unknown[];
+  hasMore?: boolean;
+  total?: number;
+}
+//#endregion
+//# sourceMappingURL=types.d.ts.map

package/dist/agent-chat/types.js

@@ -0,0 +1,17 @@
+"use client";
+//#region src/agent-chat/types.ts
+/** The title to show for a session row. */
+function sessionTitle(session) {
+	for (const candidate of [
+		session.label,
+		session.autoTitle,
+		session.derivedTitle,
+		session.displayName,
+		session.lastMessagePreview
+	]) if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+	return "New conversation";
+}
+//#endregion
+export { sessionTitle };
+
+//# sourceMappingURL=types.js.map

package/dist/agent-chat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/agent-chat/types.ts"],"sourcesContent":["/**\n * The transport contract `AgentChat` is written against.\n *\n * Everything the chat surface needs from a server is behind `AgentChatClient`,\n * and nothing in the interface names AG-UI, HTTP or React. That is what makes\n * the surface testable — `test/agent-chat.test.tsx` drives it from a fake that\n * replays scripted event sequences — and it is what keeps `@ag-ui/client` out\n * of every module except `./agui-client.ts`.\n *\n * The three sinks are subscriptions rather than constructor callbacks so one\n * client can outlive several mounts of the component, which is what a pop-up\n * that collapses and reopens mid-run does.\n */\n\nimport type { A2UIChatBlock } from \"./a2ui-block\";\n\n/* ── what a session is ───────────────────────────────────────────────────── */\n\n/**\n * A row of `sessions.list`.\n *\n * Titles fall back in a fixed order (§17.2 of the extension how-to):\n * `label`, `autoTitle`, `derivedTitle`, `displayName`, `lastMessagePreview`,\n * then \"New conversation\". `sessionTitle` below is that order, in one place.\n */\nexport interface AgentSession {\n  /** The session key, verbatim — this is also the AG-UI `threadId`. */\n  key: string;\n  label?: string | null;\n  autoTitle?: string | null;\n  derivedTitle?: string | null;\n  displayName?: string | null;\n  lastMessagePreview?: string | null;\n  updatedAt?: number | null;\n}\n\n/** The title to show for a session row. */\nexport function sessionTitle(session: AgentSession): string {\n  for (const candidate of [\n    session.label,\n    session.autoTitle,\n    session.derivedTitle,\n    session.displayName,\n    session.lastMessagePreview,\n  ]) {\n    if (typeof candidate === \"string\" && candidate.trim()) {\n      return candidate.trim();\n    }\n  }\n  return \"New conversation\";\n}\n\n/* ── what a message is ───────────────────────────────────────────────────── */\n\nexport interface AgentChatMessage {\n  id: string;\n  role: \"user\" | \"assistant\";\n  text: string;\n  timestamp: number;\n  attachments?: string[];\n  /** The chain of thought behind this turn, collapsed by default. */\n  thinkingText?: string;\n  isError?: boolean;\n  /** True when the wire record was a tool call or a tool result; hidden. */\n  isToolMessage?: boolean;\n  /**\n   * The run that produced this message. Absent on anything loaded from\n   * history. A `final` folds into the previous bubble only when the two share\n   * this value, so one run's answer cannot be rewritten by the next one's.\n   */\n  runId?: string;\n  /** UI the agent drew, carried outside the prose. */\n  a2ui?: A2UIChatBlock[];\n}\n\n/* ── the three sinks ─────────────────────────────────────────────────────── */\n\n/**\n * One chat event. The same `{ state: \"delta\" | \"final\" | \"error\" }` shape\n * cortenacore broadcasts, so a client for a different transport has a\n * documented target to hit.\n *\n * `delta` carries a SNAPSHOT, not an increment: every delta repeats all the\n * text, all the thinking and every A2UI block seen so far. Two transports that\n * disagree about this leave the store in different states for the same run.\n */\nexport interface AgentChatEvent {\n  runId: string;\n  sessionKey: string;\n  seq: number;\n  state: \"delta\" | \"final\" | \"error\";\n  message?: {\n    role?: string;\n    content?: Array<{ type: string; text?: string; thinking?: string; a2ui?: unknown }>;\n    timestamp?: number;\n  };\n  errorMessage?: string;\n}\n\n/** One step of the tool strip. */\nexport interface AgentToolEvent {\n  event: \"tool.start\" | \"tool.args\" | \"tool.progress\" | \"tool.complete\" | \"tool.error\";\n  data: {\n    id?: string;\n    name?: string;\n    /** `tool.args`: the call's input, parsed when it was valid JSON. */\n    input?: unknown;\n    output?: unknown;\n    startedAt?: number;\n    completedAt?: number;\n  };\n}\n\n/** Decisions cortenacore accepts on `POST /agui/approval`. */\nexport type AgentApprovalDecision = \"allow-once\" | \"allow-always\" | \"deny\";\n\nexport interface AgentApprovalRequest {\n  id: string;\n  /** The command, or the tool, the approval is about. */\n  toolName: string;\n  args: Record<string, unknown>;\n  timestamp: number;\n  /**\n   * The run and the session this request arrived on, captured when it arrived.\n   *\n   * A decision is bound to them rather than resolved against whatever run\n   * happens to be in flight when the user presses a button. The two come\n   * apart routinely: an approval pauses a run, the user opens another session\n   * in the drawer or starts a second turn, and the client's idea of \"the\n   * current thread\" has moved on. Answering \"allow\" against the wrong thread\n   * is a command approved in a conversation nobody was asked about.\n   */\n  runId: string;\n  sessionKey: string;\n  /** Set when a decision was made and the server would not take it. */\n  error?: string;\n}\n\n/** Where an approval came from, and therefore where the decision must go. */\nexport interface AgentApprovalContext {\n  runId: string;\n  sessionKey: string;\n}\n\nexport type AgentApprovalEvent =\n  | { type: \"request\"; request: AgentApprovalRequest }\n  /** `decision: null` is an expiry. It is treated as a denial. */\n  | { type: \"resolved\"; id: string; decision: AgentApprovalDecision | null };\n\n/* ── the client ──────────────────────────────────────────────────────────── */\n\nexport interface AgentChatSendInput {\n  /** The session key to run in. `threadId` is this value verbatim. */\n  sessionKey: string;\n  /** What the user typed. Empty for an action sent by rendered UI. */\n  message: string;\n  /** The run id; also the idempotency key. */\n  runId: string;\n  attachments?: unknown[];\n  thinking?: \"low\" | \"medium\" | \"high\";\n  model?: { provider: string; model: string };\n  /** A click inside an A2UI surface. Never a sentence the user appears to type. */\n  a2uiAction?: { surfaceId: string; componentId: string; name: string; payload: Record<string, unknown> };\n  /** The same, from inside a rendered MCP App. */\n  mcpAppAction?: Record<string, unknown>;\n}\n\n/**\n * Everything `AgentChat` needs from a server.\n *\n * `request` is deliberately a method name plus params rather than a URL: the\n * two calls the chat makes — `sessions.list` and `chat.history` — are control\n * plane methods, and a host that proxies them through its own gateway chooses\n * its own paths.\n */\nexport interface AgentChatClient {\n  /** The agent this client talks to. Session keys are `agent:<agentId>:…`. */\n  readonly agentId: string;\n  /** Start a run. Resolves when the run has been accepted, not when it ends. */\n  send(input: AgentChatSendInput): Promise<void>;\n  /** Stop the run in flight. Best-effort; local state resets either way. */\n  abort(params?: { runId?: string; sessionKey?: string }): Promise<void>;\n  /**\n   * Answer an approval. `context` is the `{ runId, sessionKey }` the request\n   * carried, not the run in flight — see `AgentApprovalRequest`. Rejects when\n   * the server refuses the decision, so the caller can put the card back.\n   */\n  resolveApproval(\n    id: string,\n    decision: AgentApprovalDecision,\n    context: AgentApprovalContext,\n  ): Promise<void>;\n  /** `sessions.list` and `chat.history`. */\n  request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;\n  /** Chat deltas, finals and errors. Returns an unsubscribe. */\n  onChat(sink: (event: AgentChatEvent) => void): () => void;\n  /** Tool starts, arguments, progress and results. Returns an unsubscribe. */\n  onTool(sink: (event: AgentToolEvent) => void): () => void;\n  /** Approval requests and resolutions. Returns an unsubscribe. */\n  onApproval(sink: (event: AgentApprovalEvent) => void): () => void;\n}\n\n/** What `sessions.list` answers. */\nexport interface AgentSessionsListResponse {\n  sessions?: AgentSession[];\n}\n\n/** What `chat.history` answers. `messages` are raw transcript records. */\nexport interface AgentChatHistoryResponse {\n  messages?: unknown[];\n  hasMore?: boolean;\n  total?: number;\n}\n"],"mappings":";;;AAqCA,SAAgB,aAAa,SAA+B;CAC1D,KAAK,MAAM,aAAa;EACtB,QAAQ;EACR,QAAQ;EACR,QAAQ;EACR,QAAQ;EACR,QAAQ;CACV,GACE,IAAI,OAAO,cAAc,YAAY,UAAU,KAAK,GAClD,OAAO,UAAU,KAAK;CAG1B,OAAO;AACT"}

package/dist/agent-chat.d.ts

@@ -0,0 +1,10 @@
+"use client";
+import { A2UIChatBlock, extractA2UIBlocks, foldA2UIBlocks, readA2UIBlock } from "./agent-chat/a2ui-block.js";
+import { AgentApprovalDecision, AgentApprovalEvent, AgentApprovalRequest, AgentChatClient, AgentChatEvent, AgentChatHistoryResponse, AgentChatMessage, AgentChatSendInput, AgentSession, AgentSessionsListResponse, AgentToolEvent, sessionTitle } from "./agent-chat/types.js";
+import { AGUI_CUSTOM_NAMES, AgentChatBridge, AgentChatBridgeOptions, AguiIncomingEvent } from "./agent-chat/bridge.js";
+import { CreateAguiAgentChatClientOptions, createAguiAgentChatClient } from "./agent-chat/agui-client.js";
+import { isHiddenMessage, isProvisionalSessionKey, isSessionOfAgent, mintSessionKey, parseHistoryMessages, readStoredSessionKey, sessionStorageKey, viewStorageKey, wouldShrinkHistory, writeStoredSessionKey } from "./agent-chat/session.js";
+import { AgentChatState, AgentToolEntry, UseAgentChatOptions, UseAgentChatResult, useAgentChat } from "./agent-chat/store.js";
+import { AgentA2UIBlocks, AgentA2UIBlocksProps, AgentApprovalCard, AgentApprovalCardProps, AgentChat, AgentChatProps, AgentMessageBubble, AgentMessageBubbleProps, AgentSessionDrawer, AgentSessionDrawerProps, AgentStreamingBubble, AgentStreamingBubbleProps, AgentThinking, AgentThinkingProps, AgentToolCard, AgentToolCardProps, AgentToolRenderContext, readMcpAppUri, shouldStickToBottom } from "./components/agent-chat.js";
+import { AgentChatPopup, AgentChatPopupExtension, AgentChatPopupProps, AgentChatPopupState } from "./components/agent-chat-popup.js";
+export { type A2UIChatBlock, AGUI_CUSTOM_NAMES, AgentA2UIBlocks, type AgentA2UIBlocksProps, AgentApprovalCard, type AgentApprovalCardProps, type AgentApprovalDecision, type AgentApprovalEvent, type AgentApprovalRequest, AgentChat, AgentChatBridge, type AgentChatBridgeOptions, type AgentChatClient, type AgentChatEvent, type AgentChatHistoryResponse, type AgentChatMessage, AgentChatPopup, type AgentChatPopupExtension, type AgentChatPopupProps, type AgentChatPopupState, type AgentChatProps, type AgentChatSendInput, type AgentChatState, AgentMessageBubble, type AgentMessageBubbleProps, type AgentSession, AgentSessionDrawer, type AgentSessionDrawerProps, type AgentSessionsListResponse, AgentStreamingBubble, type AgentStreamingBubbleProps, AgentThinking, type AgentThinkingProps, AgentToolCard, type AgentToolCardProps, type AgentToolEntry, type AgentToolEvent, type AgentToolRenderContext, type AguiIncomingEvent, type CreateAguiAgentChatClientOptions, type UseAgentChatOptions, type UseAgentChatResult, createAguiAgentChatClient, extractA2UIBlocks, foldA2UIBlocks, isHiddenMessage, isProvisionalSessionKey, isSessionOfAgent, mintSessionKey, parseHistoryMessages, readA2UIBlock, readMcpAppUri, readStoredSessionKey, sessionStorageKey, sessionTitle, shouldStickToBottom, useAgentChat, viewStorageKey, wouldShrinkHistory, writeStoredSessionKey };

package/dist/agent-chat.js

@@ -0,0 +1,10 @@
+"use client";
+import { extractA2UIBlocks, foldA2UIBlocks, readA2UIBlock } from "./agent-chat/a2ui-block.js";
+import { AGUI_CUSTOM_NAMES, AgentChatBridge } from "./agent-chat/bridge.js";
+import { createAguiAgentChatClient } from "./agent-chat/agui-client.js";
+import { isHiddenMessage, isProvisionalSessionKey, isSessionOfAgent, mintSessionKey, parseHistoryMessages, readStoredSessionKey, sessionStorageKey, viewStorageKey, wouldShrinkHistory, writeStoredSessionKey } from "./agent-chat/session.js";
+import { useAgentChat } from "./agent-chat/store.js";
+import { sessionTitle } from "./agent-chat/types.js";
+import { AgentA2UIBlocks, AgentApprovalCard, AgentChat, AgentMessageBubble, AgentSessionDrawer, AgentStreamingBubble, AgentThinking, AgentToolCard, readMcpAppUri, shouldStickToBottom } from "./components/agent-chat.js";
+import { AgentChatPopup } from "./components/agent-chat-popup.js";
+export { AGUI_CUSTOM_NAMES, AgentA2UIBlocks, AgentApprovalCard, AgentChat, AgentChatBridge, AgentChatPopup, AgentMessageBubble, AgentSessionDrawer, AgentStreamingBubble, AgentThinking, AgentToolCard, createAguiAgentChatClient, extractA2UIBlocks, foldA2UIBlocks, isHiddenMessage, isProvisionalSessionKey, isSessionOfAgent, mintSessionKey, parseHistoryMessages, readA2UIBlock, readMcpAppUri, readStoredSessionKey, sessionStorageKey, sessionTitle, shouldStickToBottom, useAgentChat, viewStorageKey, wouldShrinkHistory, writeStoredSessionKey };

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

@@ -0,0 +1,66 @@
+"use client";
+import { AdminPermissionsApi, AdminRoute } from "./types.js";
+import * as React from "react";
+//#region src/components/admin-permissions/admin-permissions.d.ts
+export interface AdminPermissionsProps extends Omit<React.ComponentProps<"div">, "children" | "title"> {
+  /** Everything the screen reads and writes. The extension's, entirely. */
+  api: AdminPermissionsApi;
+  /**
+   * The screen to show. Pass it and the host's router owns the URL; omit it
+   * and the composition keeps the current screen in its own state.
+   */
+  route?: AdminRoute;
+  /** The screen to open with when `route` is not passed. @default "members" */
+  defaultRoute?: AdminRoute;
+  /**
+   * Fired when the administrator picks another screen. Always fired, whether
+   * or not `route` is controlled, so a host can push the URL without also
+   * having to hold the state.
+   */
+  onNavigate?: (route: AdminRoute) => void;
+  /** `false` hides the title block, for a host that renders its own. */
+  header?: boolean;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+}
+/**
+ * AdminPermissions — the consistent admin screen for every Cortena extension
+ * (§13, DESIGN-D11 as amended by DESIGN-D22; audit rules P-14, P-42, P-43).
+ *
+ * Four screens behind `admin/*`: `/admin/members`, `/admin/roles`,
+ * `/admin/licence`, `/admin/permissions`. It renders whatever roles and
+ * actions the extension declares and **defines none of its own** — there is
+ * not one role name, action name or grant in this folder. That is exactly what
+ * lets a verification workflow and a work tracker have completely different
+ * role models and still look like one product.
+ *
+ * ```tsx
+ * <Route path="admin/*" element={
+ *   <AdminPermissions
+ *     api={adminApi}
+ *     route={screenFromPath(location.pathname)}
+ *     onNavigate={(next) => navigate(`/admin/${next}`)}
+ *   />
+ * } />
+ * ```
+ *
+ * **Router-agnostic, by a `route` prop plus `onNavigate`.** The component
+ * imports no router and never touches `history` or `location`. Those four
+ * paths are real URLs — deep-linkable, bookmarkable, and answerable to the
+ * back button — and only the host's router can own a URL; a component that
+ * pushed history itself would fight whichever router the extension chose.
+ * `onNavigate` reports the intent, the host turns it into a navigation, and
+ * `route` comes back as the answer.
+ *
+ * An internal fallback exists for the case with no router in it — the guide,
+ * a test, a small app: omit `route` and the composition keeps the screen in
+ * its own state. `onNavigate` still fires, so a host can start uncontrolled
+ * and add a router later without changing anything else.
+ *
+ * The navigation is a real tablist rather than a row of links, because the
+ * choice is between panels of one screen; the host is free to hide it with
+ * `header={false}` and drive `route` from its own chrome.
+ */
+export declare function AdminPermissions({ api, route, defaultRoute, onNavigate, header, title, description, className, ...props }: AdminPermissionsProps): React.JSX.Element;
+//#endregion
+//# sourceMappingURL=admin-permissions.d.ts.map

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

@@ -0,0 +1,101 @@
+"use client";
+"use client";
+import { cn } from "../../lib/cn.js";
+import { PageHeader } from "../page-header.js";
+import { Tabs, TabsList, TabsTrigger } from "../tabs.js";
+import { ADMIN_ROUTES, ADMIN_ROUTE_LABELS } from "./types.js";
+import { AdminPermissionsProvider } from "./context.js";
+import { AdminLicenceScreen } from "./licence.js";
+import { AdminMatrix } from "./matrix.js";
+import { AdminMembers } from "./members.js";
+import { AdminRoles } from "./roles.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/admin-permissions/admin-permissions.tsx
+/**
+* AdminPermissions — the consistent admin screen for every Cortena extension
+* (§13, DESIGN-D11 as amended by DESIGN-D22; audit rules P-14, P-42, P-43).
+*
+* Four screens behind `admin/*`: `/admin/members`, `/admin/roles`,
+* `/admin/licence`, `/admin/permissions`. It renders whatever roles and
+* actions the extension declares and **defines none of its own** — there is
+* not one role name, action name or grant in this folder. That is exactly what
+* lets a verification workflow and a work tracker have completely different
+* role models and still look like one product.
+*
+* ```tsx
+* <Route path="admin/*" element={
+*   <AdminPermissions
+*     api={adminApi}
+*     route={screenFromPath(location.pathname)}
+*     onNavigate={(next) => navigate(`/admin/${next}`)}
+*   />
+* } />
+* ```
+*
+* **Router-agnostic, by a `route` prop plus `onNavigate`.** The component
+* imports no router and never touches `history` or `location`. Those four
+* paths are real URLs — deep-linkable, bookmarkable, and answerable to the
+* back button — and only the host's router can own a URL; a component that
+* pushed history itself would fight whichever router the extension chose.
+* `onNavigate` reports the intent, the host turns it into a navigation, and
+* `route` comes back as the answer.
+*
+* An internal fallback exists for the case with no router in it — the guide,
+* a test, a small app: omit `route` and the composition keeps the screen in
+* its own state. `onNavigate` still fires, so a host can start uncontrolled
+* and add a router later without changing anything else.
+*
+* The navigation is a real tablist rather than a row of links, because the
+* choice is between panels of one screen; the host is free to hide it with
+* `header={false}` and drive `route` from its own chrome.
+*/
+function AdminPermissions({ api, route, defaultRoute = "members", onNavigate, header = true, title = "Administration", description = "Who is in this organisation, what your roles let them do, and the licence behind it.", className, ...props }) {
+	const [internal, setInternal] = React.useState(defaultRoute);
+	const active = route ?? internal;
+	const go = (next) => {
+		if (route === void 0) setInternal(next);
+		onNavigate?.(next);
+	};
+	return /* @__PURE__ */ jsx(AdminPermissionsProvider, {
+		api,
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-slot": "admin-permissions",
+			"data-route": active,
+			className: cn("flex flex-col gap-5", className),
+			...props,
+			children: [
+				header ? /* @__PURE__ */ jsx(PageHeader, {
+					title,
+					description
+				}) : null,
+				/* @__PURE__ */ jsx(Tabs, {
+					value: active,
+					onValueChange: (value) => go(value),
+					"data-slot": "admin-permissions-nav",
+					children: /* @__PURE__ */ jsx(TabsList, {
+						"aria-label": "Administration screens",
+						children: ADMIN_ROUTES.map((item) => /* @__PURE__ */ jsx(TabsTrigger, {
+							value: item,
+							"data-route": item,
+							children: ADMIN_ROUTE_LABELS[item]
+						}, item))
+					})
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					"data-slot": "admin-permissions-screen",
+					children: [
+						active === "members" ? /* @__PURE__ */ jsx(AdminMembers, {}) : null,
+						active === "roles" ? /* @__PURE__ */ jsx(AdminRoles, {}) : null,
+						active === "licence" ? /* @__PURE__ */ jsx(AdminLicenceScreen, {}) : null,
+						active === "permissions" ? /* @__PURE__ */ jsx(AdminMatrix, {}) : null
+					]
+				})
+			]
+		})
+	});
+}
+//#endregion
+export { AdminPermissions };
+
+//# sourceMappingURL=admin-permissions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"admin-permissions.js","names":[],"sources":["../../../src/components/admin-permissions/admin-permissions.tsx"],"sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport { PageHeader } from \"@/components/page-header\";\nimport { Tabs, TabsList, TabsTrigger } from \"@/components/tabs\";\nimport { cn } from \"@/lib/cn\";\nimport { AdminPermissionsProvider } from \"./context\";\nimport { AdminLicenceScreen } from \"./licence\";\nimport { AdminMatrix } from \"./matrix\";\nimport { AdminMembers } from \"./members\";\nimport { AdminRoles } from \"./roles\";\nimport {\n  ADMIN_ROUTES,\n  ADMIN_ROUTE_LABELS,\n  type AdminPermissionsApi,\n  type AdminRoute,\n} from \"./types\";\n\nexport interface AdminPermissionsProps\n  extends Omit<React.ComponentProps<\"div\">, \"children\" | \"title\"> {\n  /** Everything the screen reads and writes. The extension's, entirely. */\n  api: AdminPermissionsApi;\n  /**\n   * The screen to show. Pass it and the host's router owns the URL; omit it\n   * and the composition keeps the current screen in its own state.\n   */\n  route?: AdminRoute;\n  /** The screen to open with when `route` is not passed. @default \"members\" */\n  defaultRoute?: AdminRoute;\n  /**\n   * Fired when the administrator picks another screen. Always fired, whether\n   * or not `route` is controlled, so a host can push the URL without also\n   * having to hold the state.\n   */\n  onNavigate?: (route: AdminRoute) => void;\n  /** `false` hides the title block, for a host that renders its own. */\n  header?: boolean;\n  title?: React.ReactNode;\n  description?: React.ReactNode;\n}\n\n/**\n * AdminPermissions — the consistent admin screen for every Cortena extension\n * (§13, DESIGN-D11 as amended by DESIGN-D22; audit rules P-14, P-42, P-43).\n *\n * Four screens behind `admin/*`: `/admin/members`, `/admin/roles`,\n * `/admin/licence`, `/admin/permissions`. It renders whatever roles and\n * actions the extension declares and **defines none of its own** — there is\n * not one role name, action name or grant in this folder. That is exactly what\n * lets a verification workflow and a work tracker have completely different\n * role models and still look like one product.\n *\n * ```tsx\n * <Route path=\"admin/*\" element={\n *   <AdminPermissions\n *     api={adminApi}\n *     route={screenFromPath(location.pathname)}\n *     onNavigate={(next) => navigate(`/admin/${next}`)}\n *   />\n * } />\n * ```\n *\n * **Router-agnostic, by a `route` prop plus `onNavigate`.** The component\n * imports no router and never touches `history` or `location`. Those four\n * paths are real URLs — deep-linkable, bookmarkable, and answerable to the\n * back button — and only the host's router can own a URL; a component that\n * pushed history itself would fight whichever router the extension chose.\n * `onNavigate` reports the intent, the host turns it into a navigation, and\n * `route` comes back as the answer.\n *\n * An internal fallback exists for the case with no router in it — the guide,\n * a test, a small app: omit `route` and the composition keeps the screen in\n * its own state. `onNavigate` still fires, so a host can start uncontrolled\n * and add a router later without changing anything else.\n *\n * The navigation is a real tablist rather than a row of links, because the\n * choice is between panels of one screen; the host is free to hide it with\n * `header={false}` and drive `route` from its own chrome.\n */\nexport function AdminPermissions({\n  api,\n  route,\n  defaultRoute = \"members\",\n  onNavigate,\n  header = true,\n  title = \"Administration\",\n  description = \"Who is in this organisation, what your roles let them do, and the licence behind it.\",\n  className,\n  ...props\n}: AdminPermissionsProps) {\n  const [internal, setInternal] = React.useState<AdminRoute>(defaultRoute);\n  const active = route ?? internal;\n\n  const go = (next: AdminRoute) => {\n    if (route === undefined) setInternal(next);\n    onNavigate?.(next);\n  };\n\n  return (\n    <AdminPermissionsProvider api={api}>\n      <div\n        data-slot=\"admin-permissions\"\n        data-route={active}\n        className={cn(\"flex flex-col gap-5\", className)}\n        {...props}\n      >\n        {header ? <PageHeader title={title} description={description} /> : null}\n        <Tabs\n          value={active}\n          onValueChange={(value) => go(value as AdminRoute)}\n          data-slot=\"admin-permissions-nav\"\n        >\n          <TabsList aria-label=\"Administration screens\">\n            {ADMIN_ROUTES.map((item) => (\n              <TabsTrigger key={item} value={item} data-route={item}>\n                {ADMIN_ROUTE_LABELS[item]}\n              </TabsTrigger>\n            ))}\n          </TabsList>\n        </Tabs>\n        <div data-slot=\"admin-permissions-screen\">\n          {active === \"members\" ? <AdminMembers /> : null}\n          {active === \"roles\" ? <AdminRoles /> : null}\n          {active === \"licence\" ? <AdminLicenceScreen /> : null}\n          {active === \"permissions\" ? <AdminMatrix /> : null}\n        </div>\n      </div>\n    </AdminPermissionsProvider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+EA,SAAgB,iBAAiB,EAC/B,KACA,OACA,eAAe,WACf,YACA,SAAS,MACT,QAAQ,kBACR,cAAc,wFACd,WACA,GAAG,SACqB;CACxB,MAAM,CAAC,UAAU,eAAe,MAAM,SAAqB,YAAY;CACvE,MAAM,SAAS,SAAS;CAExB,MAAM,MAAM,SAAqB;EAC/B,IAAI,UAAU,KAAA,GAAW,YAAY,IAAI;EACzC,aAAa,IAAI;CACnB;CAEA,OACE,oBAAC,0BAAD;EAA+B;EAC7B,UAAA,qBAAC,OAAD;GACE,aAAU;GACV,cAAY;GACZ,WAAW,GAAG,uBAAuB,SAAS;GAC9C,GAAI;GAJN,UAAA;IAMG,SAAS,oBAAC,YAAD;KAAmB;KAAoB;IAAc,CAAA,IAAI;IACnE,oBAAC,MAAD;KACE,OAAO;KACP,gBAAgB,UAAU,GAAG,KAAmB;KAChD,aAAU;KAEV,UAAA,oBAAC,UAAD;MAAU,cAAW;MAClB,UAAA,aAAa,KAAK,SACjB,oBAAC,aAAD;OAAwB,OAAO;OAAM,cAAY;OAC9C,UAAA,mBAAmB;MACT,GAFK,IAEL,CACd;KACO,CAAA;IACN,CAAA;IACN,qBAAC,OAAD;KAAK,aAAU;KAAf,UAAA;MACG,WAAW,YAAY,oBAAC,cAAD,CAAe,CAAA,IAAI;MAC1C,WAAW,UAAU,oBAAC,YAAD,CAAa,CAAA,IAAI;MACtC,WAAW,YAAY,oBAAC,oBAAD,CAAqB,CAAA,IAAI;MAChD,WAAW,gBAAgB,oBAAC,aAAD,CAAc,CAAA,IAAI;KAC3C;;GACF;;CACmB,CAAA;AAE9B"}

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

@@ -0,0 +1,70 @@
+"use client";
+import { AdminGroupRow, AdminMemberRow, AdminPermissionMatrix, AdminPermissionsApi, AdminPrincipal } from "./types.js";
+import * as React from "react";
+//#region src/components/admin-permissions/context.d.ts
+/**
+ * One async read, with the abort a screen needs when it unmounts mid-flight.
+ * Small on purpose: the composition fetches three documents of its own (the
+ * matrix, the licence, the groups) and the members list is a DataTable on the
+ * server source, which owns its own fetching.
+ */
+export interface Resource<T> {
+  data: T | null;
+  error: Error | null;
+  loading: boolean;
+  reload: () => void;
+}
+export interface AdminPermissionsContextValue {
+  api: AdminPermissionsApi;
+  /** The declared vocabulary and matrix. `null` until it loads, or when it failed. */
+  matrix: AdminPermissionMatrix | null;
+  matrixState: Resource<AdminPermissionMatrix>;
+  /** Write the matrix. Optimistic: the grid shows the new grants before the PUT lands. */
+  saveMatrix: (next: AdminPermissionMatrix) => Promise<void>;
+  /**
+   * True when the API offers groups *and* the org actually has some. Every
+   * group affordance is hidden otherwise.
+   */
+  hasGroups: boolean;
+  /**
+   * True while the answer to `hasGroups` is not known yet — the list is in
+   * flight, or it failed.
+   *
+   * `hasGroups === false` used to mean three different things at once: this
+   * API has no groups, this org has none, and `groups.list()` blew up. The
+   * third renders identically to the second, so a member who inherits
+   * "reviewer" from Legal is shown with no roles at all and an administrator
+   * reads that as a fact about the member. A failure has to look like a
+   * failure.
+   */
+  groupsUnknown: boolean;
+  groups: AdminGroupRow[];
+  groupsState: Resource<{
+    rows: AdminGroupRow[];
+    roles: Record<string, string[]>;
+  }>;
+  /** group id → the roles it carries, including any not yet confirmed by the server. */
+  groupRoles: Readonly<Record<string, string[]>>;
+  /** Bumped after a successful assignment, so the members source refetches. */
+  revision: number;
+  /** Direct member roles written since the last refetch, by user id. */
+  memberRoles: ReadonlyMap<string, string[]>;
+  /**
+   * Assign a principal's direct roles. Optimistic: the screen shows the new
+   * roles immediately and puts the old ones back if the call rejects, then
+   * rethrows so the caller can show the envelope's message.
+   */
+  assignRoles: (principal: AdminPrincipal, roles: string[]) => Promise<void>;
+  /**
+   * Hand back rows the server has just answered with, so any optimistic entry
+   * the server now agrees with can be dropped. See `memberRoles`.
+   */
+  reconcileMembers: (rows: readonly AdminMemberRow[]) => void;
+}
+export declare function useAdminPermissions(): AdminPermissionsContextValue;
+export declare function AdminPermissionsProvider({ api, children }: {
+  api: AdminPermissionsApi;
+  children: React.ReactNode;
+}): React.JSX.Element;
+//#endregion
+//# sourceMappingURL=context.d.ts.map