cortena-ui 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -3,6 +3,109 @@
 Notable changes per release. Versions before 1.6.0 are recorded in the git log
 and in `../../CONSUMING.md`; this file starts where the changelog does.
 
+## 1.15.0
+
+### Added
+
+- **`cortena-ui/app` — `CortenaApp`, the whole frame** (DESIGN-119). Everything
+  around an extension's content, mounted once instead of assembled eight ways:
+  the launch, `LoginScreen` with the methods the org advertises, the signed-out
+  state with a `returnTo`, exactly one session guard, `AppShell`,
+  `AgentChatPopup` in `agentSlot`, the tab title, and the standard Profile /
+  Settings / Permissions pages. The 2026-09-14 re-audit is what it replaces:
+  seven local login pages across eight extensions, three of them with dummy
+  users; a guard mounted with a different subset of its behaviour in each; a
+  pop-up mounted without the user's token or the agent slug; a Settings item
+  greyed out in every one of the six shell swaps.
+- **A `host` role.** `role="host"` leaves the agent slot empty, because
+  CortenaWeb *is* the chat and its own guard is the one that renews and pushes
+  tokens into framed extensions. Host-only navigation is `nav` and `headerSlot`
+  configuration, not a special case inside the composition. cortena-auth's
+  hosted pages are the third consumer.
+- **`readCortenaLaunch({ hostOrigins })`**, and with it the rule that a framed
+  extension trusts the host's guard **only when the host declares it**. The
+  declaration — a `cortenaGuard=host` parameter beside the token, or the first
+  bridge message — is origin-checked against an allow-list the app supplies
+  from its own configuration, never from the request. Declared: no guard here,
+  and renewed tokens arrive through `session.onTokenRenewed`. Absent: a
+  countdown from the access token's own `exp`, the standard warning with no
+  Continue, then the signed-out state. Not framed: the full `SessionGuard`. One
+  of the three, ever — never two countdowns for one session, and never the old
+  behaviour of inferring "the host is guarding me" from the absence of a
+  refresh token.
+- **The standard pages**, at `/me`, `/settings` and `/settings/permissions`:
+  Profile, then Permissions from `AdminPermissions` against the §14.3 admin
+  routes when the caller may administer, then the extension's own settings from
+  a declared zod schema — or one plain line, "Nothing to configure for <name>
+  yet." The avatar menu's Settings item is never disabled again. Exported
+  individually as `CortenaSettingsPage`, `CortenaProfilePage` and
+  `ProfileSection`, with `matchCortenaStandardRoute` for an app that would
+  rather place them under its own router.
+- **`session.hostOrigins`**, and with it the bridge path for the declaration:
+  the composition listens for the host's first
+  `{ type: "cortena-session", guarded, accessToken }` and takes the declaration
+  and any renewal from it. Prefer this over the launch parameter —
+  `event.origin` is the browser's and cannot be forged from inside the sending
+  page, where the parameter's check falls back to `document.referrer` on a
+  browser with no `ancestorOrigins`. The gap is downgrade-only (a forged
+  declaration mounts *no* guard, never a second one) and is written down in
+  `launch.ts`.
+- **`session.expiresAt`**, for a token whose `exp` cannot be read — an opaque
+  token, or one the decoder failed on. Exactly `SessionToken`'s own escape
+  hatch, and the way to keep such a session guarded rather than landing on the
+  signed-out screen.
+- **A development warning** where a non-framed launch omits `session.refresh`.
+  Without it the guard reaches the proactive refresh at about 75% of the access
+  token's life, is rejected, and signs the user out — §10.4.1's half-dead
+  screen arriving from the inside, with nothing on screen to explain it.
+- **`CortenaApp` is router- and environment-agnostic**: `pathname` in,
+  `onNavigate` out, real `href`s, configuration and tokens as props, no browser
+  API touched during a first render, and `documentTitle={false}` for a surface
+  that does not own the tab. That is what lets CortenaWeb adopt it inside a
+  Next.js root layout instead of keeping a second shell.
+
+### Fixed
+
+- **A signed-out screen you could not leave.** The state was cleared only where
+  a *host* pushed a token, and that path exists only in a host-guarded frame.
+  On a standalone launch or an undeclared frame the signed-out screen
+  short-circuits the whole render, so a successful sign-in set the token and
+  the user stayed on "You were signed out" for ever with nothing on screen to
+  explain it. A new token now clears it wherever it comes from — the launch,
+  the app's own store, `session.onTokenRenewed`, or the bridge.
+- **A frame with an unreadable token was silently unguarded.** A token with no
+  readable `exp` took the countdown branch and then counted nothing: no
+  warning, no expiry, no signed-out state — the exact state decision (b)
+  removed, arriving through the back door. It is now reported as already over,
+  which lands on the signed-out screen with a `returnTo`, and says why in a
+  development warning. Warning rather than expiring was considered and
+  rejected: a warning's entire content is a number there is none of, and its
+  only way out is Log out, which lands on the same screen anyway.
+- **A rejected sign-out** left an unhandled rejection and the user on a shell
+  whose session was over. It is caught, and the screen stops pretending either
+  way — `SessionGuard` makes the same call.
+- **`settings.load()` is no longer called** for a declaration with no readable
+  fields. The card renders one sentence; a GET behind it is a request nothing
+  on screen is waiting for.
+
+### Notes
+
+- **The frame is light and stays light.** `cortena-ui/app` measures **285.6 kB
+  eager** against a 340 kB ceiling — the shell probe's 212.8 kB plus the
+  standard pages — with **no heavy package eager at all**. `AdminPermissions`
+  (TanStack Table, and exceljs behind `DataTable`'s export) and the agent mount
+  (`AgentChat`, react-markdown, the A2UI renderer) are both `React.lazy`, and
+  `test/bundle-probe.test.mjs` measures that rather than assuming it.
+- **`@ag-ui/client` is still reachable from `cortena-ui/agent-chat` alone.** The
+  transport factory is passed in as `agent.createClient` rather than imported,
+  so an extension writes one named import and the composition still owns every
+  argument the pop-up is built with.
+- **This package imports no zod.** A settings schema is typed structurally and
+  only ever called — `safeParse` to validate, `.shape` to derive fields — so it
+  works across zod 3 and 4 and costs the frame nothing.
+- The favicon and the `<title>` no longer need hand-copied files: the generator
+  ships as a Vite plugin from `cortena-design/vite` (cortena-design 3.6.0).
+
 ## 1.14.0
 
 ### Added

package/README.md

@@ -36,6 +36,7 @@ consumer's bundler getting tree-shaking right:
 | `cortena-ui/a2ui` | the A2UI catalogue and renderer | most of the package, by design |
 | `cortena-ui/sortable-list` | `SortableList`, `SortableHandle`, `arrayMove` | dnd-kit |
 | `cortena-ui/agent-chat` | `AgentChatPopup`, `AgentChat`, `createAguiAgentChatClient` | the A2UI catalogue, plus `@ag-ui/client` (rxjs, zod 3, uuid, protobuf) |
+| `cortena-ui/app` | `CortenaApp` — the whole frame, and `readCortenaLaunch` | 285.6 kB eagerly; the standard pages that are heavy arrive in chunks of their own |
 | `cortena-ui/rich-text-editor` | `RichTextEditor`, `parseMarkdown`, `serializeMarkdown` | TipTap on ProseMirror, 619 kB — the heaviest entry in the package |
 
 Each component has exactly one home, so the barrel re-exports every entry
@@ -129,6 +130,210 @@ regression; `test/chart-bundle.test.tsx` says which line caused it.
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
 
+## The frame
+
+`AppShell` owns what renders after sign-in. Everything around it — the sign-in
+screen, the signed-out state, the session guard, the agent pop-up, the tab
+title and the Profile / Settings / Permissions pages — used to be each
+extension's to assemble, and a 2026-09-14 re-audit of eight of them found eight
+answers: seven local login pages, three still with dummy users; a guard mounted
+with a different subset of its behaviour in each; a pop-up mounted without the
+user's token or the agent slug; a Settings item greyed out in every shell.
+
+`cortena-ui/app` is the assembly (DESIGN-119):
+
+```tsx
+// main.tsx — synchronously, before createRoot (§7.3)
+import { readCortenaLaunch } from "cortena-ui/app";
+const launch = readCortenaLaunch({ hostOrigins: [config.cortenaWebOrigin] });
+
+// App.tsx
+import { CortenaApp } from "cortena-ui/app";
+import { createAguiAgentChatClient } from "cortena-ui/agent-chat";
+
+<CortenaApp
+  extension={{ id: "tasks", name: "Tasks" }}
+  user={user}
+  auth={{ publicAuthUrl, orgId, methods, onPassword, onProvider }}
+  session={{ launch, getToken, refresh, signOut, onTokenRenewed }}
+  nav={{ groups, pathname, onNavigate: (item, e) => { e.preventDefault(); navigate(item.href); } }}
+  agent={{ slug: "tasks", gatewayUrl: "/api/agent", createClient: createAguiAgentChatClient, relay, tokensCss }}
+  permissions={{ api: adminApi, canAdminister: isAdmin }}
+  settings={{ schema, load, save }}
+  help={{ source: HELP_DOCUMENT_URL }}
+  pathname={pathname}
+  onNavigate={(href) => navigate(href)}
+  documentTitle={pageTitle}
+>
+  <Outlet />
+</CortenaApp>
+```
+
+It does things in this order, and the order is the contract:
+
+1. the launch, from `session.launch`;
+2. no token → `LoginScreen` with the methods the org advertises;
+3. the session ended → `LoginScreen` with `signedOut` and a `returnTo`;
+4. exactly one session guard, at the top, above the shell and the pop-up alike;
+5. `AppShell`, with Profile / Settings / Log out in the avatar menu;
+6. `AgentChatPopup` in `agentSlot`, in the `extension` role only;
+7. the standard pages when `pathname` names one, your `children` otherwise.
+
+### It is a client component, and router-agnostic
+
+Navigation is `pathname` in and `onNavigate` out, over real `href`s, exactly as
+`AppShell` already does. Configuration and tokens are props: the composition
+fetches nothing, reads no browser API during a first render, and does not
+assume it owns the document — `documentTitle={false}` turns off even the tab
+title. That is not style. The third consumer is CortenaWeb, in a `host` role,
+inside its own Next.js root layout; without every one of those the fleet keeps
+two shells.
+
+`role="host"` leaves the agent slot empty, because the host *is* the chat, and
+its own guard is the one that renews and pushes tokens into framed extensions.
+Host-only navigation — an Apps list, an org switcher, platform admin — is `nav`
+and `headerSlot` configuration, not a special case in here.
+
+### Reading the launch, and who guards the session
+
+A framed extension cannot refresh: CortenaWeb holds the refresh token and hands
+down access tokens (`refreshToken=none`). Inferring "the host is guarding me"
+from that absence is trust by assumption — a frame opened by anything at all
+got no warning and no signed-out state, and nothing said so. So:
+
+| the launch | what mounts |
+| --- | --- |
+| framed, and the host **declared** it guards the session | no guard here; renewed tokens arrive through `session.onTokenRenewed` |
+| framed, and it did not | a countdown from the access token's own `exp`, the standard warning with no Continue, then the signed-out state with a `returnTo` |
+| not framed | the full `SessionGuard`: idle clock, proactive refresh, cross-tab `BroadcastChannel` |
+
+One of the three, ever. Never two countdowns for one session.
+
+There are two ways the declaration can arrive, and they are not equally strong.
+
+```tsx
+// The launch parameter: ?token=…&cortenaGuard=host
+const launch = readCortenaLaunch({ hostOrigins: [config.cortenaWebOrigin] });
+
+// The first bridge message. Give the same allow-list to the composition and it
+// listens for `{ type: "cortena-session", guarded: true, accessToken? }` itself.
+<CortenaApp session={{ launch, hostOrigins: [config.cortenaWebOrigin], … }} />
+```
+
+Both are checked against an allow-list **your app supplies from its own
+configuration**, never against anything in the request. With no `hostOrigins`
+nothing is ever trusted, which is the safe direction: the frame then runs its
+own countdown rather than trusting a parent it cannot name.
+
+**Prefer the bridge.** `readCortenaSessionMessage` checks `event.origin`, which
+the browser sets from the sending document and which cannot be forged from
+inside the page that sent it. The launch parameter is checked against
+`ancestorOrigins`, which is WebKit/Blink only; everywhere else the input is
+`document.referrer`, and an open redirect on the CortenaWeb origin can produce
+one that reads as CortenaWeb's. The failure is downgrade-only — a forged
+declaration mounts *no* guard, it cannot mount a second one or obtain a token —
+but "no guard" is the state decision (b) exists to remove, so pass
+`hostOrigins` and let the host say it on the bridge. `launch.ts` carries the
+whole note.
+
+Token renewals arrive the same way: over the bridge where `hostOrigins` is set,
+or through `session.onTokenRenewed` for an app that would rather own the
+listener. Either one, and a token the app itself signs in with, clears the
+signed-out state.
+
+Call it in your store's initialiser, synchronously, before `createRoot`. §7.3
+is the single most common embedding failure: a token read in an effect is read
+after a `ProtectedRoute` has already redirected and stripped the query string,
+and the user sees a login page inside CortenaWeb with nothing to explain it.
+
+`session.signOut` is optional, and omitting it is meaningful: in a framed launch
+with no host sign-out message to send, the avatar menu's Log out is disabled
+rather than silently doing nothing.
+
+### The standard pages
+
+`/me`, `/settings` and `/settings/permissions` are the composition's, reachable
+from the avatar menu, and the Settings item is **never** disabled:
+
+- **Profile** — the person's own name, avatar and account link. cortena-auth
+  owns the user record, so the page shows it and links to it rather than
+  pretending an extension can edit it.
+- **Permissions** — `AdminPermissions` against the §14.3 admin routes, rendered
+  only when `permissions.canAdminister`. Absent otherwise, not disabled: "you
+  may not" is not a screen. The admin tabs push
+  `/settings/permissions/<screen>`, so they are deep-linkable.
+
+  **`canAdminister` comes from your own permissions client, against the §14.3
+  routes — never from an `orgRole` claim on the JWT.** Whether somebody may
+  administer *your extension* is your `may()`'s answer over your own matrix
+  (§14.2, §14.4); cortena-auth's org role says who owns the organisation, which
+  is a different question and one the bootstrap already answered once. Reading
+  the claim looks equivalent, hides the screen from an administrator your
+  matrix granted, shows it to an org owner your matrix did not, and neither is
+  visible until somebody complains. This flag only decides whether the section
+  renders; the routes behind it enforce the real thing either way.
+- **The extension's own settings** — whatever it declares, or one plain line:
+  "Nothing to configure for <name> yet." An extension that later gains settings
+  declares a schema rather than building a page.
+
+The routing is your router's. The composition compares `pathname` to the three
+paths and renders its own page instead of `children` when one matches, so it
+works under any router at all — mount it as a layout and give the router a
+route for those paths that renders nothing of its own:
+
+```tsx
+// react-router
+<Route element={<Frame />}>
+  <Route path="/me" element={null} />
+  <Route path="/settings/*" element={null} />
+  …
+</Route>
+
+// Next.js: app/me/page.tsx and app/settings/[[...rest]]/page.tsx, each
+// rendering null. The frame is in the layout, and it is "use client".
+```
+
+`matchCortenaStandardRoute(pathname)` is exported for an app that would rather
+place `CortenaSettingsPage` and `CortenaProfilePage` itself: it is the same
+rule, not a second copy of it.
+
+### The settings declaration
+
+```tsx
+const settings = z.object({
+  alertThreshold: z.number().describe("Raise an alert when a stream falls this far behind."),
+  pauseOnFailure: z.boolean(),
+  alertChannel: z.enum(["email", "channels", "none"]),
+});
+
+<CortenaApp settings={{ schema: settings, load, save }} … />
+```
+
+The fields are derived from the object's shape, and `safeParse` validates a
+save. This package imports no zod: the schema is typed structurally and only
+ever called, so it works across zod 3 and 4, whose internals differ, and costs
+the frame nothing. Reading the shape is deliberately tolerant — a schema it
+cannot read gives no fields, which draws the "nothing to configure" line rather
+than throwing on a settings page.
+
+Pass `fields` where the schema alone does not say enough — a select's options,
+a longer description, a textarea. `load` and `save` are the extension's own
+`/settings` route; the composition never stores anything.
+
+### What it does not do
+
+There is **no consent route**. cortena-auth is the authorisation server and
+renders consent; the content comes from the `scopes` section of the extension's
+own `x-cortena` identity block, which cortena-auth reads from the registered
+in-cluster address. An extension ships no consent screen.
+
+And `@ag-ui/client` is reachable from `cortena-ui/agent-chat` and nowhere else,
+including here. The transport factory is a prop — `agent.createClient` — rather
+than an import, which is one named import for the extension and leaves the
+composition owning every argument the pop-up is built with: the user's token,
+read fresh on every request, and the agent slug. Those are the two an extension
+shipped without.
+
 ## Shell chrome
 
 `AppShell` is the chrome every extension wears (§9 of

package/dist/app.d.ts

@@ -0,0 +1,6 @@
+"use client";
+import { CORTENA_GUARD_HOST, CORTENA_GUARD_PARAM, CORTENA_SESSION_MESSAGE, CortenaLaunch, CortenaSessionMessage, ReadCortenaLaunchOptions, isHostGuardDeclared, readCortenaLaunch, readCortenaSessionMessage } from "./components/app/launch.js";
+import { CortenaAppAgent } from "./components/app/agent-mount.js";
+import { CortenaAppPermissions, CortenaAppUser, CortenaProfilePage, CortenaSettingsControl, CortenaSettingsDeclaration, CortenaSettingsField, CortenaSettingsPage, CortenaSettingsPageProps, CortenaSettingsSchema, ProfileSection, ProfileSectionProps, settingsFields } from "./components/app/settings.js";
+import { CORTENA_STANDARD_ROUTES, CortenaApp, CortenaAppAuth, CortenaAppExtension, CortenaAppProps, CortenaAppRoutes, CortenaSessionAdapter, CortenaStandardRoute, matchCortenaStandardRoute } from "./components/app/cortena-app.js";
+export { CORTENA_GUARD_HOST, CORTENA_GUARD_PARAM, CORTENA_SESSION_MESSAGE, CORTENA_STANDARD_ROUTES, CortenaApp, type CortenaAppAgent, type CortenaAppAuth, type CortenaAppExtension, type CortenaAppPermissions, type CortenaAppProps, type CortenaAppRoutes, type CortenaAppUser, type CortenaLaunch, CortenaProfilePage, type CortenaSessionAdapter, type CortenaSessionMessage, type CortenaSettingsControl, type CortenaSettingsDeclaration, type CortenaSettingsField, CortenaSettingsPage, type CortenaSettingsPageProps, type CortenaSettingsSchema, type CortenaStandardRoute, ProfileSection, type ProfileSectionProps, type ReadCortenaLaunchOptions, isHostGuardDeclared, matchCortenaStandardRoute, readCortenaLaunch, readCortenaSessionMessage, settingsFields };

package/dist/app.js

@@ -0,0 +1,5 @@
+"use client";
+import { CORTENA_GUARD_HOST, CORTENA_GUARD_PARAM, CORTENA_SESSION_MESSAGE, isHostGuardDeclared, readCortenaLaunch, readCortenaSessionMessage } from "./components/app/launch.js";
+import { CortenaProfilePage, CortenaSettingsPage, ProfileSection, settingsFields } from "./components/app/settings.js";
+import { CORTENA_STANDARD_ROUTES, CortenaApp, matchCortenaStandardRoute } from "./components/app/cortena-app.js";
+export { CORTENA_GUARD_HOST, CORTENA_GUARD_PARAM, CORTENA_SESSION_MESSAGE, CORTENA_STANDARD_ROUTES, CortenaApp, CortenaProfilePage, CortenaSettingsPage, ProfileSection, isHostGuardDeclared, matchCortenaStandardRoute, readCortenaLaunch, readCortenaSessionMessage, settingsFields };

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

@@ -0,0 +1,11 @@
+"use client";
+"use client";
+import { ADMIN_ROUTES, ADMIN_ROUTE_LABELS, adminErrorMessage, effectiveRolesOf, sourceGroupOf } from "./types.js";
+import { AdminPermissionsProvider, useAdminPermissions } from "./context.js";
+import { AdminLicenceScreen } from "./licence.js";
+import { AdminMatrix } from "./matrix.js";
+import { DirectRoles, EffectiveRoles, RoleAssignmentDialog } from "./role-assignment.js";
+import { AdminMembers } from "./members.js";
+import { AdminRoles } from "./roles.js";
+import { AdminPermissions } from "./admin-permissions.js";
+export { ADMIN_ROUTES, ADMIN_ROUTE_LABELS, AdminLicenceScreen, AdminMatrix, AdminMembers, AdminPermissions, AdminPermissionsProvider, AdminRoles, DirectRoles, EffectiveRoles, RoleAssignmentDialog, adminErrorMessage, effectiveRolesOf, sourceGroupOf, useAdminPermissions };

package/dist/components/app/agent-mount.d.ts

@@ -0,0 +1,53 @@
+"use client";
+import { AgentChatClient } from "../../agent-chat/types.js";
+import { McpAppToolCaller } from "../../agent-chat/mcp-app/bridge.js";
+import "react";
+//#region src/components/app/agent-mount.d.ts
+/**
+ * The agent pop-up, wired the way §19 says and not the way each extension
+ * remembered it.
+ *
+ * This module is loaded lazily by `CortenaApp`, and that is the whole reason
+ * it is a module at all: `AgentChatPopup` reaches `AgentChat`, which reaches
+ * `Markdown` and the A2UI renderer. An extension's first screen must not carry
+ * a markdown pipeline for a chat the user has not opened, so the frame imports
+ * this by `import()` and a bundler splits it off.
+ *
+ * `createClient` is passed in rather than imported for a different reason.
+ * `createAguiAgentChatClient` reaches `@ag-ui/client` — rxjs, zod 3, uuid,
+ * protobuf — and `test/bundle-probe.test.mjs` fails if `@ag-ui/*` is reachable
+ * from any entry but `cortena-ui/agent-chat`. Keeping the factory a prop keeps
+ * that guarantee exactly as it is, and still leaves the composition owning
+ * every argument the pop-up is built with: the user's token, read fresh on
+ * every request, and the agent slug. Both were the ones an extension shipped
+ * without.
+ */
+export interface CortenaAppAgent {
+  /** The AgentTemplate slug. Usually the extension id; §19.1. */
+  slug: string;
+  /** This extension's own gateway, never cortenacore. Default `/api/agent`. */
+  gatewayUrl?: string;
+  /**
+   * `createAguiAgentChatClient` from `cortena-ui/agent-chat`, passed through.
+   * One named import, and the composition supplies every argument.
+   */
+  createClient: (options: {
+    baseUrl: string;
+    agentId: string;
+    getToken: () => string;
+  }) => AgentChatClient;
+  /**
+   * How a screen drawn inside the pop-up reaches this extension's own MCP
+   * server, with the user's credential (§19.2, step 4). Omitted, tool results
+   * stay ordinary cards.
+   */
+  relay?: McpAppToolCaller;
+  /**
+   * `cortena-design/tokens.css?raw`. The sandboxed document has an opaque
+   * origin and `default-src 'none'`, so it can fetch nothing: the tokens go in
+   * as text or the screen renders unstyled.
+   */
+  tokensCss?: string;
+}
+//#endregion
+//# sourceMappingURL=agent-mount.d.ts.map

package/dist/components/app/agent-mount.js

@@ -0,0 +1,40 @@
+"use client";
+"use client";
+import { AgentChatPopup } from "../agent-chat-popup.js";
+import { renderMcpAppToolCall } from "../../agent-chat/mcp-app/render-tool-call.js";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/app/agent-mount.tsx
+function AgentMount({ extension, agent, getToken }) {
+	const identity = React.useRef({
+		agent,
+		getToken
+	});
+	identity.current = {
+		agent,
+		getToken
+	};
+	const client = React.useMemo(() => identity.current.agent.createClient({
+		baseUrl: identity.current.agent.gatewayUrl ?? "/api/agent",
+		agentId: identity.current.agent.slug,
+		getToken: () => identity.current.getToken()
+	}), []);
+	const renderToolCall = React.useMemo(() => {
+		const relay = identity.current.agent.relay;
+		if (!relay) return;
+		return renderMcpAppToolCall({
+			extensionId: extension.id,
+			callTool: relay,
+			tokensCss: identity.current.agent.tokensCss
+		});
+	}, [extension.id]);
+	return /* @__PURE__ */ jsx(AgentChatPopup, {
+		extension,
+		client,
+		renderToolCall
+	});
+}
+//#endregion
+export { AgentMount as default };
+
+//# sourceMappingURL=agent-mount.js.map

package/dist/components/app/agent-mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mount.js","names":[],"sources":["../../../src/components/app/agent-mount.tsx"],"sourcesContent":["\"use client\";\n\nimport * as React from \"react\";\nimport { AgentChatPopup } from \"@/components/agent-chat-popup\";\nimport { renderMcpAppToolCall } from \"@/agent-chat/mcp-app/render-tool-call\";\nimport type { McpAppToolCaller } from \"@/agent-chat/mcp-app/bridge\";\nimport type { AgentChatClient } from \"@/agent-chat/types\";\n\n/**\n * The agent pop-up, wired the way §19 says and not the way each extension\n * remembered it.\n *\n * This module is loaded lazily by `CortenaApp`, and that is the whole reason\n * it is a module at all: `AgentChatPopup` reaches `AgentChat`, which reaches\n * `Markdown` and the A2UI renderer. An extension's first screen must not carry\n * a markdown pipeline for a chat the user has not opened, so the frame imports\n * this by `import()` and a bundler splits it off.\n *\n * `createClient` is passed in rather than imported for a different reason.\n * `createAguiAgentChatClient` reaches `@ag-ui/client` — rxjs, zod 3, uuid,\n * protobuf — and `test/bundle-probe.test.mjs` fails if `@ag-ui/*` is reachable\n * from any entry but `cortena-ui/agent-chat`. Keeping the factory a prop keeps\n * that guarantee exactly as it is, and still leaves the composition owning\n * every argument the pop-up is built with: the user's token, read fresh on\n * every request, and the agent slug. Both were the ones an extension shipped\n * without.\n */\n\nexport interface CortenaAppAgent {\n  /** The AgentTemplate slug. Usually the extension id; §19.1. */\n  slug: string;\n  /** This extension's own gateway, never cortenacore. Default `/api/agent`. */\n  gatewayUrl?: string;\n  /**\n   * `createAguiAgentChatClient` from `cortena-ui/agent-chat`, passed through.\n   * One named import, and the composition supplies every argument.\n   */\n  createClient: (options: {\n    baseUrl: string;\n    agentId: string;\n    getToken: () => string;\n  }) => AgentChatClient;\n  /**\n   * How a screen drawn inside the pop-up reaches this extension's own MCP\n   * server, with the user's credential (§19.2, step 4). Omitted, tool results\n   * stay ordinary cards.\n   */\n  relay?: McpAppToolCaller;\n  /**\n   * `cortena-design/tokens.css?raw`. The sandboxed document has an opaque\n   * origin and `default-src 'none'`, so it can fetch nothing: the tokens go in\n   * as text or the screen renders unstyled.\n   */\n  tokensCss?: string;\n}\n\nexport interface AgentMountProps {\n  extension: { id: string; name: string };\n  agent: CortenaAppAgent;\n  /** Read on every request rather than captured, so a renewal is picked up. */\n  getToken: () => string;\n}\n\nfunction AgentMount({ extension, agent, getToken }: AgentMountProps) {\n  // Built once for the life of the mount. The chat re-subscribes to the run\n  // stream and refetches its session list whenever the client's identity\n  // changes, so a client rebuilt per render is a session list refetched per\n  // render. The identity is constant by construction: the slug is a string and\n  // the token is read through a function rather than captured as a value.\n  const identity = React.useRef({ agent, getToken });\n  identity.current = { agent, getToken };\n\n  const client = React.useMemo(\n    () =>\n      identity.current.agent.createClient({\n        baseUrl: identity.current.agent.gatewayUrl ?? \"/api/agent\",\n        agentId: identity.current.agent.slug,\n        getToken: () => identity.current.getToken(),\n      }),\n    [],\n  );\n\n  const renderToolCall = React.useMemo(() => {\n    const relay = identity.current.agent.relay;\n    if (!relay) {\n      return undefined;\n    }\n    return renderMcpAppToolCall({\n      extensionId: extension.id,\n      callTool: relay,\n      tokensCss: identity.current.agent.tokensCss,\n      // `onMessage` is left unset on purpose: the surface's own `send` takes\n      // it, so a click inside a screen starts the next turn as the screen\n      // rather than as a user who typed nothing (DESIGN-80).\n    });\n    // The extension id is fixed for the life of the app; rebuilding this would\n    // reload a screen that is already running.\n  }, [extension.id]);\n\n  return <AgentChatPopup extension={extension} client={client} renderToolCall={renderToolCall} />;\n}\n\nexport default AgentMount;\n"],"mappings":";;;;;;;AA+DA,SAAS,WAAW,EAAE,WAAW,OAAO,YAA6B;CAMnE,MAAM,WAAW,MAAM,OAAO;EAAE;EAAO;CAAS,CAAC;CACjD,SAAS,UAAU;EAAE;EAAO;CAAS;CAErC,MAAM,SAAS,MAAM,cAEjB,SAAS,QAAQ,MAAM,aAAa;EAClC,SAAS,SAAS,QAAQ,MAAM,cAAc;EAC9C,SAAS,SAAS,QAAQ,MAAM;EAChC,gBAAgB,SAAS,QAAQ,SAAS;CAC5C,CAAC,GACH,CAAC,CACH;CAEA,MAAM,iBAAiB,MAAM,cAAc;EACzC,MAAM,QAAQ,SAAS,QAAQ,MAAM;EACrC,IAAI,CAAC,OACH;EAEF,OAAO,qBAAqB;GAC1B,aAAa,UAAU;GACvB,UAAU;GACV,WAAW,SAAS,QAAQ,MAAM;EAIpC,CAAC;CAGH,GAAG,CAAC,UAAU,EAAE,CAAC;CAEjB,OAAO,oBAAC,gBAAD;EAA2B;EAAmB;EAAwB;CAAiB,CAAA;AAChG"}

package/dist/components/app/cortena-app.d.ts

@@ -0,0 +1,184 @@
+"use client";
+import { AppShellHelp, AppShellMenuItem, AppShellNav, HelpPanelSlotProps } from "../app-shell.js";
+import { LoginMethod, PasswordCredentials } from "../login-screen.js";
+import { DialogContentProps } from "../dialog.js";
+import { SessionPolicy, SessionSignOutReason, SessionTimers } from "../session-guard.js";
+import { AdminRoute } from "../admin-permissions/types.js";
+import { CortenaLaunch } from "./launch.js";
+import { CortenaAppAgent } from "./agent-mount.js";
+import { CortenaAppPermissions, CortenaAppUser, CortenaSettingsDeclaration } from "./settings.js";
+import * as React from "react";
+//#region src/components/app/cortena-app.d.ts
+export interface CortenaAppExtension {
+  /** Registered mark id, from `x-cortena.icon` in the OpenAPI document (§10.1). */
+  id: string;
+  /** Display name. The shell's title, the tab's title and the login heading. */
+  name: string;
+  /** Override the mark when it is not the extension id. Rarely needed. */
+  icon?: string;
+}
+export interface CortenaAppAuth {
+  /** cortena-auth, in-cluster. From `config.json`; this component never calls it. */
+  authServiceUrl?: string;
+  /** cortena-auth's public origin — the account link on the Profile page. */
+  publicAuthUrl?: string;
+  orgId?: string;
+  /**
+   * What the org advertises, from `GET /api/orgs/:orgId/auth-info`. The fetch
+   * stays in the app: cortena-ui cannot depend on firebase, and a component
+   * that fetches cannot be rendered in the guide or in a test (§8.4).
+   *
+   * An empty or omitted list falls back to password rather than to a screen
+   * with no way in.
+   */
+  methods?: readonly LoginMethod[];
+  onPassword?: (credentials: PasswordCredentials) => void;
+  onProvider?: (provider: Exclude<LoginMethod, "password">) => void;
+  /** A failed sign-in, in the user's words. */
+  error?: string;
+  loading?: boolean;
+}
+export interface CortenaSessionAdapter {
+  /**
+   * The launch, as the app read it synchronously before the first render —
+   * `readCortenaLaunch()`. A value rather than a callback, so this component
+   * touches no browser API while rendering (§7.3).
+   */
+  launch: CortenaLaunch;
+  /** The current access token. Read on every use, never captured. */
+  getToken: () => string;
+  /**
+   * When the access token expires, for a token whose `exp` cannot be read — an
+   * opaque token, or one the decoder failed on. Epoch **milliseconds**; a value
+   * below `1e11` is read as epoch seconds instead. Exactly `SessionToken`'s
+   * own escape hatch, and the way to keep an unreadable credential guarded
+   * rather than landing on the signed-out screen (see the note on the guard
+   * below).
+   */
+  expiresAt?: number;
+  /**
+   * The origins a host declaration and a host-pushed token are accepted from —
+   * CortenaWeb's, from this extension's own configuration, never from the
+   * request.
+   *
+   * Given, the composition listens for the host's first bridge message and
+   * takes the declaration from it; `event.origin` is the browser's, not the
+   * sender's, and is the only part of a `postMessage` that cannot be forged
+   * from inside the page that sent it, which makes this the safer of the two
+   * declaration paths (see `launch.ts` on what `ancestorOrigins` cannot
+   * promise). With none given nothing is ever trusted.
+   */
+  hostOrigins?: readonly string[];
+  /** `POST /api/auth/refresh`. Only called when this app can refresh. */
+  refresh?: () => Promise<{
+    accessToken: string;
+  }>;
+  /**
+   * `POST /api/auth/logout`, or the message that asks the host to sign out.
+   *
+   * Omit it in a framed launch where there is no host sign-out message to
+   * send: the avatar menu's Log out is then disabled, which is what every
+   * shell swap does today and is honest — a menu item that silently does
+   * nothing is worse than one that is visibly unavailable.
+   */
+  signOut?: () => Promise<void>;
+  /**
+   * Renewed tokens, from wherever the app gets them — the bridge, its own
+   * store, a rotation it ran itself. An alternative to `hostOrigins` for an
+   * app that would rather own the `message` listener; both end up in the same
+   * place, and a token identical to the one in force costs a comparison.
+   */
+  onTokenRenewed?: (listener: (accessToken: string) => void) => () => void;
+  /** Org policy from `GET /api/orgs/:orgId/session-policy` (§10.4.2). */
+  policy?: Partial<SessionPolicy>;
+  /** The `BroadcastChannel` name. One per origin unless two apps must not share. */
+  channelName?: string;
+  /** The clock and the timers. Injected by tests and by the guide. */
+  now?: () => number;
+  timers?: SessionTimers;
+}
+/** Where the standard pages live. Overridable; the defaults are the fleet's. */
+export interface CortenaAppRoutes {
+  /** @default "/me" */
+  profile?: string;
+  /** @default "/settings" */
+  settings?: string;
+  /** @default "/settings/permissions" */
+  permissions?: string;
+}
+export declare const CORTENA_STANDARD_ROUTES: Required<CortenaAppRoutes>;
+export interface CortenaAppProps {
+  extension: CortenaAppExtension;
+  user: CortenaAppUser;
+  auth?: CortenaAppAuth;
+  session: CortenaSessionAdapter;
+  /**
+   * `extension` mounts the agent pop-up and is the default. `host` is
+   * CortenaWeb: the pop-up slot stays empty because the host *is* the chat,
+   * and its own guard is the one that renews and pushes tokens into frames.
+   */
+  role?: "extension" | "host";
+  nav?: AppShellNav | null;
+  agent?: CortenaAppAgent;
+  settings?: CortenaSettingsDeclaration;
+  permissions?: CortenaAppPermissions;
+  help?: AppShellHelp;
+  helpPanel?: React.ReactNode | ((props: HelpPanelSlotProps) => React.ReactNode);
+  headerSlot?: React.ReactNode;
+  /** Extra avatar-menu items, between Settings and Log out. */
+  menuItems?: AppShellMenuItem[];
+  bottomInset?: string | number;
+  themeStorageKey?: string;
+  /** The current path. The composition compares it to the standard routes. */
+  pathname: string;
+  /** Take over a navigation. The composition never touches `history`. */
+  onNavigate: (href: string) => void;
+  /**
+   * The page half of the tab title for a route: `documentTitle(name, page)`
+   * gives "<page> · <name> · Cortena" (§10.5, P-38). Set after mount, never
+   * during a render.
+   *
+   * `false` leaves the title alone entirely, for a surface that is not the
+   * whole tab — the guide, which mounts four of these on one page, and a host
+   * that already sets its own. The composition does not assume it owns the
+   * document; it assumes it usually does.
+   */
+  documentTitle?: ((pathname: string) => string | undefined) | false;
+  routes?: CortenaAppRoutes;
+  /**
+   * Non-modal, and portalled somewhere other than the body. For the guide,
+   * where three theme frames must not fight over focus. The product leaves
+   * this alone, exactly as it leaves `SessionGuard`'s own pair alone.
+   */
+  sessionDialog?: {
+    modal?: boolean;
+    container?: DialogContentProps["container"];
+  };
+  /** Told when the session ends, so the app can clear its own stores. */
+  onSignedOut?: (reason: SessionSignOutReason) => void;
+  /**
+   * On the frame's own root — the shell, or the sign-in screen when there is
+   * no session. `min-h-0 h-full` is how the guide boxes it.
+   */
+  className?: string;
+  /** The routed content. Replaced by a standard page when `pathname` names one. */
+  children?: React.ReactNode;
+}
+export type CortenaStandardRoute = {
+  kind: "profile";
+} | {
+  kind: "settings";
+  adminRoute?: AdminRoute;
+};
+/**
+ * Which standard page a path names, or `undefined` for the app's own content.
+ *
+ * Exported because an app that would rather place these pages itself — a Next
+ * route segment, a react-router `<Route>` — needs the same answer this
+ * composition uses, rather than a second copy of the rule.
+ */
+export declare function matchCortenaStandardRoute(pathname: string, routes?: CortenaAppRoutes): CortenaStandardRoute | undefined;
+declare function CortenaApp({ extension, user, auth, session, role, nav, agent, settings, permissions, help, helpPanel, headerSlot, menuItems, bottomInset, themeStorageKey, pathname, onNavigate, documentTitle: pageTitle, routes, sessionDialog, onSignedOut, className, children }: CortenaAppProps): React.JSX.Element;
+//#endregion
+export { CortenaApp };
+//# sourceMappingURL=cortena-app.d.ts.map