cortena-ui 1.4.2 → 1.6.0

package/src/entries/agent-chat.ts

@@ -0,0 +1,137 @@
+/**
+ * `cortena-ui/agent-chat` — the extension's own agent, as a chat pop-up.
+ *
+ * §17 of how-to-create-a-cortena-extension, audit rule P-25. `AgentChatPopup`
+ * mounts in `AppShell`'s `agentSlot`; `AgentChat` is the surface it wraps, and
+ * is what cortenaweb adopts so there is one chat rather than two.
+ *
+ * Its own entry, and deliberately not re-exported from the root barrel, for the
+ * reason `sortable-list` has one: `createAguiAgentChatClient` imports
+ * `@ag-ui/client`, which brings rxjs, zod 3, uuid and protobuf. An extension
+ * that draws a button should not pay for a run stream it never opens, and the
+ * only guarantee that it does not is an import it has to ask for.
+ * `test/bundle-probe.test.mjs` measures it.
+ *
+ * ## `@ag-ui/client` is an OPTIONAL PEER, not a dependency
+ *
+ * ```jsonc
+ * "peerDependencies":     { "@ag-ui/client": "^0.0.59" },
+ * "peerDependenciesMeta": { "@ag-ui/client": { "optional": true } }
+ * ```
+ *
+ * An extension that uses this entry installs `@ag-ui/client` itself, at a
+ * version its own package.json names. As a dependency of cortena-ui it was
+ * pinned to one exact build for the whole fleet, and an app that also talks
+ * AG-UI directly — which is every app with a second agent surface — resolved
+ * two copies. Two copies of an rxjs-based client is two event pipelines and
+ * two zod registries, and the symptoms are subscriptions that never fire.
+ *
+ * Optional, because it is only needed by `createAguiAgentChatClient`. Nothing
+ * else in this entry imports it: `AgentChat`, `AgentChatPopup` and
+ * `useAgentChat` are written against the `AgentChatClient` interface, so an
+ * extension on a different transport installs nothing and gets no warning.
+ *
+ * `createAguiAgentChatClient` loads it with a dynamic import, so this entry
+ * evaluates without it. It used to be a static import, which made "optional"
+ * untrue in the only way that matters: an extension that had not installed
+ * `@ag-ui/client` could not import `AgentChatPopup` either, and the error
+ * named a package it does not use. Now the peer is needed by one operation,
+ * and when it is absent the failure arrives in the chat, as a failed run,
+ * saying what to install.
+ *
+ * ```tsx
+ * import { AgentChatPopup, createAguiAgentChatClient } from "cortena-ui/agent-chat";
+ *
+ * const client = createAguiAgentChatClient({
+ *   baseUrl: "/api/agent",        // this extension's gateway, not cortenacore
+ *   getToken: () => jwt,          // the USER's JWT, never a service token
+ *   agentId: "tasks",             // = the AgentTemplate slug = the extension id
+ * });
+ *
+ * <AppShell extension={ext} user={user} agentSlot={<AgentChatPopup extension={ext} client={client} />}>
+ * ```
+ */
+
+export type { A2UIChatBlock } from "@/agent-chat/a2ui-block";
+export { extractA2UIBlocks, foldA2UIBlocks, readA2UIBlock } from "@/agent-chat/a2ui-block";
+export type { AguiIncomingEvent, AgentChatBridgeOptions } from "@/agent-chat/bridge";
+export { AGUI_CUSTOM_NAMES, AgentChatBridge } from "@/agent-chat/bridge";
+export type { CreateAguiAgentChatClientOptions } from "@/agent-chat/agui-client";
+export { createAguiAgentChatClient } from "@/agent-chat/agui-client";
+export {
+  isHiddenMessage,
+  isProvisionalSessionKey,
+  isSessionOfAgent,
+  mintSessionKey,
+  parseHistoryMessages,
+  readStoredSessionKey,
+  readStoredSteps,
+  serialiseSteps,
+  sessionStorageKey,
+  STEP_LIMIT,
+  stepsStorageKey,
+  viewStorageKey,
+  wouldShrinkHistory,
+  writeStoredSessionKey,
+  writeStoredSteps,
+} from "@/agent-chat/session";
+export type { AgentStepPhase } from "@/agent-chat/step-label";
+export {
+  confirmationRequiredLabel,
+  genericLabel,
+  humaniseId,
+  isGenericLabel,
+  stepLabel,
+  truncate,
+} from "@/agent-chat/step-label";
+export type {
+  AgentChatState,
+  AgentToolEntry,
+  UseAgentChatOptions,
+  UseAgentChatResult,
+} from "@/agent-chat/store";
+export { readResultMetadata, useAgentChat } from "@/agent-chat/store";
+export type {
+  AgentApprovalDecision,
+  AgentApprovalEvent,
+  AgentApprovalRequest,
+  AgentChatClient,
+  AgentChatEvent,
+  AgentChatHistoryResponse,
+  AgentChatMessage,
+  AgentChatSendInput,
+  AgentChatStep,
+  AgentSession,
+  AgentSessionsListResponse,
+  AgentToolEvent,
+  AgentToolResultMeta,
+  AgentToolResultMetadata,
+} from "@/agent-chat/types";
+export { sessionTitle } from "@/agent-chat/types";
+export type {
+  AgentA2UIBlocksProps,
+  AgentApprovalCardProps,
+  AgentChatProps,
+  AgentMessageBubbleProps,
+  AgentSessionDrawerProps,
+  AgentStepsProps,
+  AgentStreamingBubbleProps,
+  AgentThinkingProps,
+  AgentToolCardProps,
+  AgentToolRenderContext,
+} from "@/components/agent-chat";
+export {
+  AgentA2UIBlocks,
+  AgentApprovalCard,
+  AgentChat,
+  AgentMessageBubble,
+  AgentSessionDrawer,
+  AgentSteps,
+  AgentStreamingBubble,
+  AgentThinking,
+  AgentToolCard,
+  readMcpAppUri,
+  shouldStickToBottom,
+} from "@/components/agent-chat";
+export type { AgentChatPopupExtension, AgentChatPopupProps, AgentChatPopupState } from "@/components/agent-chat-popup";
+export { AgentChatPopup } from "@/components/agent-chat-popup";

package/src/entries/core.ts

@@ -12,6 +12,8 @@
  */
 
 export type { AlertProps } from "@/components/alert";
+export type { AppShellExtension, AppShellHelp, AppShellProps, AppShellUser, BottomRightClusterProps, BrandMarkProps, HelpButtonProps, HelpPanelSlotProps, ThemeToggleProps } from "@/components/app-shell";
+export type { AuthScreenBrand, AuthScreenProps, LoginExtension, LoginMethod, LoginScreenProps, PasswordCredentials } from "@/components/login-screen";
 export type { BadgeProps } from "@/components/badge";
 export type { BreadcrumbLinkProps } from "@/components/breadcrumb";
 export type { ButtonLinkProps } from "@/components/button-link";
@@ -21,6 +23,7 @@ export type { CheckboxProps } from "@/components/checkbox";
 export type { ChipProps } from "@/components/chip";
 export type { ComboboxChipProps, ComboboxChipsProps, ComboboxContentProps, ComboboxInputProps } from "@/components/combobox";
 export type { CommandDialogProps, CommandItemProps } from "@/components/command";
+export type { ConsentClient, ConsentScope, ConsentScreenProps, ConsentUser } from "@/components/consent-screen";
 export type { CortenaTheme, CortenaThemeMessage, ResolvedCortenaTheme, UseCortenaThemeOptions, UseCortenaThemeResult } from "@/hooks/use-cortena-theme";
 export type { DialogContentProps } from "@/components/dialog";
 export type { DropdownMenuContentProps, DropdownMenuItemProps, DropdownMenuLabelProps, DropdownMenuSubTriggerProps } from "@/components/dropdown-menu";
@@ -39,6 +42,7 @@ export type { SectionCardProps } from "@/components/section-card";
 export type { SegmentedOption, SegmentedProps } from "@/components/segmented";
 export type { SelectContentProps, SelectProps, SelectTriggerProps } from "@/components/select";
 export type { SeparatorProps } from "@/components/separator";
+export type { SessionClaims, SessionExpiryDialogProps, SessionGuardMessage, SessionGuardProps, SessionPolicy, SessionSignOutReason, SessionState, SessionTimers, SessionToken, UseSessionGuardOptions, UseSessionGuardResult } from "@/components/session-guard";
 export type { SheetContentProps, SheetProps } from "@/components/sheet";
 export type { SpinnerProps } from "@/components/spinner";
 export type { StatusDotProps, StatusDotTone } from "@/components/status-dot";
@@ -49,6 +53,8 @@ export type { ToolbarProps } from "@/components/toolbar";
 export type { TooltipContentProps } from "@/components/tooltip";
 export { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/accordion";
 export { Alert, AlertDescription, AlertIcon, AlertTitle, alertVariants } from "@/components/alert";
+export { AppShell, BottomRightCluster, BrandMark, HelpButton, ThemeToggle, documentTitle } from "@/components/app-shell";
+export { AuthScreen, GoogleMark, LoginScreen, MicrosoftMark, httpsLogoUrl } from "@/components/login-screen";
 export { Avatar, AvatarFallback, AvatarImage } from "@/components/avatar";
 export { Badge, badgeVariants } from "@/components/badge";
 export { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@/components/breadcrumb";
@@ -59,6 +65,8 @@ export { Checkbox } from "@/components/checkbox";
 export { Chip, chipVariants } from "@/components/chip";
 export { Combobox, ComboboxChip, ComboboxChips, ComboboxClear, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, useComboboxFilter } from "@/components/combobox";
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandLoading, CommandSeparator, CommandShortcut } from "@/components/command";
+export { ConsentScreen } from "@/components/consent-screen";
+export { DEFAULT_SESSION_POLICY, SESSION_CHANNEL_NAME, SessionExpiryDialog, SessionGuard, decodeSessionClaims, formatCountdown, useSessionGuard } from "@/components/session-guard";
 export { DEFAULT_THEME_STORAGE_KEY, THEME_MESSAGE_TYPE, applyStoredTheme, applyTheme, getThemeInitScript, readStoredTheme, themeFromBackground, themeFromMessage, themeInitScript, useCortenaTheme } from "@/hooks/use-cortena-theme";
 export { Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from "@/components/dialog";
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "@/components/dropdown-menu";

package/src/entries/data-table.ts

@@ -7,3 +7,44 @@
  */
 
 export * from "@/components/data-table";
+
+/**
+ * The extension's own admin area (§13, audit rule P-19): roles, the permission
+ * matrix, licence seats, and role assignment for users and groups. It lives
+ * here because its members screen is a `DataTable` on a server source, so it
+ * reaches `@tanstack/react-table` — an extension that draws a Button must not
+ * pay for a table engine to do it.
+ */
+export type {
+  AdminEffectiveRole,
+  AdminErrorEnvelope,
+  AdminGroupRef,
+  AdminGroupRow,
+  AdminLicence,
+  AdminMemberRow,
+  AdminPermissionMatrix,
+  AdminPermissionsApi,
+  AdminPermissionsContextValue,
+  AdminPermissionsProps,
+  AdminPrincipal,
+  AdminRoleSource,
+  AdminRoute,
+  RoleAssignmentDialogProps,
+} from "@/components/admin-permissions";
+export {
+  ADMIN_ROUTES,
+  ADMIN_ROUTE_LABELS,
+  AdminLicenceScreen,
+  AdminMatrix,
+  AdminMembers,
+  AdminPermissions,
+  AdminPermissionsProvider,
+  AdminRoles,
+  DirectRoles,
+  EffectiveRoles,
+  RoleAssignmentDialog,
+  adminErrorMessage,
+  effectiveRolesOf,
+  sourceGroupOf,
+  useAdminPermissions,
+} from "@/components/admin-permissions";

package/src/entries/markdown.ts

@@ -7,3 +7,28 @@
 
 export type { CodeRendererProps, MarkdownComponents, MarkdownProps } from "@/components/markdown";
 export { Markdown, markdownSanitizeSchema } from "@/components/markdown";
+
+/**
+ * The in-extension help panel (§12, audit rule P-13). It lives here because it
+ * renders the extension's functional document as markdown, and an extension
+ * that draws a Button must not pay for react-markdown to do it.
+ */
+export type {
+  HelpDocument,
+  HelpHotkeysOptions,
+  HelpHotkeysProps,
+  HelpPanelProps,
+  HelpPanelSlotConfig,
+  HelpRoute,
+  HelpSection,
+  HelpSource,
+} from "@/components/help-panel";
+export {
+  HelpHotkeys,
+  HelpPanel,
+  helpPanelSlot,
+  httpDocumentUrl,
+  parseHelpDocument,
+  resolveHelpTarget,
+  useHelpHotkeys,
+} from "@/components/help-panel";

package/src/hooks/use-cortena-theme.ts

@@ -90,6 +90,39 @@ export function applyTheme(theme: CortenaTheme, root: HTMLElement = document.doc
 
 /* ── storage ─────────────────────────────────────────────────────────────── */
 
+/**
+ * The mode already on `<html>`, if a host put one there.
+ *
+ * A Cortena extension is frequently mounted inside a shell that has ALREADY
+ * decided the theme — cortenaweb's iframe embed writes the attribute before
+ * the extension's bundle runs, and a server-rendered host writes it into the
+ * markup. "system" is this hook's word for "the user has not chosen", not for
+ * "remove whatever is there".
+ */
+function documentTheme(): ResolvedCortenaTheme | null {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const value = document.documentElement.getAttribute("data-theme");
+  return value === "dark" || value === "light" ? value : null;
+}
+
+/** Exactly what `data-theme` says, `null` when it is absent, without judging it. */
+function documentThemeAttribute(): string | null {
+  return typeof document === "undefined"
+    ? null
+    : document.documentElement.getAttribute("data-theme");
+}
+
+/** Whether a choice has actually been stored, as against defaulted to "system". */
+function hasStoredTheme(storageKey: string): boolean {
+  try {
+    return isTheme(window.localStorage.getItem(storageKey));
+  } catch {
+    return false;
+  }
+}
+
 export function readStoredTheme(storageKey: string = DEFAULT_THEME_STORAGE_KEY): CortenaTheme {
   try {
     const raw = window.localStorage.getItem(storageKey);
@@ -232,7 +265,10 @@ export function useCortenaTheme(options: UseCortenaThemeOptions = {}): UseCorten
 
   const resolvedTheme = useSyncExternalStore(
     subscribeScheme,
-    () => (theme === "system" ? systemScheme() : theme),
+    // With no choice of the user's own, what is painted is what the host set,
+    // and only then the OS scheme. Reporting `systemScheme()` while <html>
+    // said `dark` made the toggle's icon and the page disagree.
+    () => (theme === "system" ? (documentTheme() ?? systemScheme()) : theme),
     () => "light" as const,
   );
 
@@ -245,10 +281,33 @@ export function useCortenaTheme(options: UseCortenaThemeOptions = {}): UseCorten
     [storageKey],
   );
 
-  // Keep <html> in step with the store, including a change made in another tab.
+  /**
+   * Keep <html> in step with the store, including a change made in another tab.
+   *
+   * This is the whole of C4: with no stored choice, `theme` is "system", and
+   * writing that removes an attribute the host set — so an extension embedded
+   * in a dark cortenaweb flashed to light the instant its shell mounted, and
+   * stayed there. Nothing errors, nothing warns; the page is simply the wrong
+   * colour. "system" is this hook's word for "the user has not chosen", and
+   * only a stored choice licenses touching the attribute at all; `setTheme`
+   * writes storage first, so a deliberate "system" does still take it off.
+   *
+   * Decided fresh on every run, from two facts about the world rather than
+   * from a ref: whether a choice is stored, and what is on <html> right now.
+   * The ref this replaces made the first run special, and under StrictMode —
+   * or any remount — the *second* run was then no longer the first, so the
+   * host's attribute was removed a tick after mount by the very effect that
+   * exists to preserve it.
+   */
   useEffect(() => {
-    applyTheme(theme);
-  }, [theme]);
+    if (!hasStoredTheme(storageKey)) {
+      return;
+    }
+    const wanted = theme === "system" ? null : theme;
+    if (documentThemeAttribute() !== wanted) {
+      applyTheme(theme);
+    }
+  }, [storageKey, theme]);
 
   // Joined so a fresh array literal on every render does not re-subscribe.
   const originsKey = allowedOrigins?.join(" ") ?? "";

package/src/index.ts

@@ -20,6 +20,12 @@
  *   cortena-ui/a2ui           the A2UI catalogue and renderer
  *   cortena-ui/sortable-list  SortableList (dnd-kit, which cannot be shaken)
  *
+ * One entry is not part of this union and never will be: `cortena-ui/agent-chat`
+ * imports `@ag-ui/client`, and the only guarantee that an extension drawing a
+ * Button does not download a run transport it never opens is an import it has to
+ * ask for. `test/bundle-probe.test.mjs` fails if `@ag-ui/*` reaches any other
+ * entry.
+ *
  * Each component has exactly one home, so these unions never collide. Adding a
  * component means adding it to its area entry, not here.
  */