cortena-ui 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -3,6 +3,145 @@
 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
+
+- **`Actor` — one component for "who did this"** (DESIGN-120). The protocol
+  records the acting user and `via` on every write (§20, audit rule P-26) and
+  expects a trail to read "Name (Agent)". Seven extensions were each about to
+  format that themselves: Tasks prints the stored string raw as
+  `Amit (claude-code)`, Assure keeps a rich JSON actor and shows none of it.
+  `Actor` takes the resolved actor — `{ userId, displayName, via, avatarUrl,
+  at, surface }` — and **has no string input**: there is no `label`, `text` or
+  `children` prop, because a consumer that can pass a preformatted label is
+  how the inconsistency arrived. The rules it encodes: a direct action is the
+  name alone; an agent action is the name and a fixed ` (Agent)` in the
+  caption/muted style, never the agent's technical id or session; `system` is
+  `System`; a user with no stored display name is `Someone`, never a raw id.
+  Three sizes — `inline` for a sentence, `cell` for a list, `head` for a feed
+  row or comment with avatar and time — and a hover showing surface and time
+  wherever either is given. Times are `en-GB` by default and hand-written, the
+  same way `DateField` formats dates, so a trail does not read differently on
+  every machine; `locale` overrides it. `title` and `dangerouslySetInnerHTML`
+  are omitted from the props alongside `children`. The hover is not the only
+  way to reach what it says: the same text is in the DOM visually hidden, in
+  document order after the name, so a screen reader reads it and a `gridcell`
+  or link around the actor takes it into its own name. The avatar's initials
+  and the visible timestamp are `aria-hidden`, so neither is announced twice.
+- **`actorColumn()`** in `cortena-ui/data-table`, so a list needs no custom
+  cell. It is an accessor column over the label rather than a display column,
+  so the value the table sorts, filters, searches and exports is the string
+  the cell paints. The header defaults to `By`.
+- **`actorLabel`, `actorName`, `actorTime`** and the three wordings
+  (`ACTOR_AGENT_SUFFIX`, `ACTOR_SYSTEM_NAME`, `ACTOR_UNKNOWN_NAME`) are
+  exported for the places a React node cannot go — an `aria-label`, a CSV
+  cell, a `title`. `Actor` and its types come from `cortena-ui/core` and the
+  root barrel; `actorColumn` from `cortena-ui/data-table`.
+
 ## 1.13.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
@@ -251,6 +456,94 @@ move the theme/help cluster **and** whatever `agentSlot` renders, which is what
 the old per-extension `className="bottom-22 lg:bottom-6"` workaround could not
 do.
 
+## Attribution: who did this
+
+`Actor` is the only thing in the fleet that turns a recorded actor into words
+(DESIGN-120, protocol §20 / audit rule P-26). Every extension stores the same
+two columns on every write — the acting user and `via` — and every screen that
+shows a trail has to answer the same question: did a person do this, or did
+their agent? Seven extensions answering it themselves is seven answers, and
+the one that prints the stored string raw shows `Amit (claude-code)`, which
+names a CLI and says nothing about whether a human was in the loop.
+
+```tsx
+<p>
+  <Actor userId={row.actorUserId} displayName={row.actorName} via={row.actorVia} /> changed the status
+</p>
+```
+
+**The input is the actor, never a label.** There is no `label`, `text` or
+`children` prop and there will not be one: a consumer that can pass a
+preformatted string eventually passes a differently formatted one, which is
+exactly how the inconsistency arrived. The rules live in the component:
+
+| `via` | `displayName` | reads as |
+| --- | --- | --- |
+| `user` | "Amit Sharma" | Amit Sharma |
+| `user` | missing or blank | Someone |
+| `agent` | "Amit Sharma" | Amit Sharma **(Agent)** |
+| `agent` | missing or blank | Someone **(Agent)** |
+| `system` | anything | System |
+
+The suffix is fixed and caption-sized in `--ds-muted-foreground`. It is never
+the agent's technical id or session — which agent ran is an audit question and
+`actorAgentId` answers it; on screen the only thing that changes the reader's
+next action is *that* an agent acted. An unknown or deleted user is `Someone`
+and never the id: the server-side `actorLabel` in `packages/shared` falls back
+to the id because a log line has no other anchor, and a screen does.
+
+Three sizes. `inline` is a run of text in a sentence. `cell` is avatar-less
+and one line, and truncates on its own inline-block box, inside the `td` that
+truncates around it. `head` is avatar, name and time, for a feed row or a
+comment header — `avatar={false}` keeps the stacked shape without the picture,
+for a comment thread that has already shown it once. `at` and `surface` show on
+hover at every size.
+
+Times format as `14 Sep 2026, 19:32`: `en-GB` by default and hand-written, the
+same way `DateField` does it, so one date is not spelled two ways on two
+screens and a trail does not read differently on every machine. The zone stays
+local, and `locale` overrides the format.
+
+`title` and `dangerouslySetInnerHTML` are omitted from the props alongside
+`children`, for the same reason: every route by which a caller could put its
+own words on screen is closed.
+
+The hover is not the only way to reach what it says. The same text is also in
+the DOM, visually hidden (`sr-only`), in document order right after the name,
+so a screen reader reads it where it is relevant and any ancestor whose role
+takes its name from its contents — the `gridcell` a DataTable cell sits in, a
+link, a button — includes it in that name. The trigger stays a plain `span`:
+no tab stop, because making every actor in a 200-row grid focusable would
+wreck keyboard navigation of it, and no `aria-label`, because a `role=generic`
+element's label is dropped rather than announced. The avatar's initials and
+`head`'s visible timestamp are `aria-hidden`, so neither is read twice.
+
+A list uses the column helper rather than a custom cell:
+
+```tsx
+const helper = createColumnHelper<AuditRow>();
+const columns = helper.columns([
+  helper.accessor("action", { header: "Action", meta: { fill: true } }),
+  actorColumn(helper, {
+    actor: (row) => ({
+      userId: row.actorUserId,
+      displayName: row.actorName,
+      via: row.actorVia,
+      at: row.at,
+      surface: row.surface,
+    }),
+  }),
+]);
+```
+
+It is an accessor column over `actorLabel`, not a display column, so the value
+the table sorts, filters, searches and exports is the same string the cell
+paints — a table sorted by **By** lands where the reader expects, and a CSV of
+it reads like the screen. The header defaults to `By`.
+
+`actorLabel`, `actorName` and `actorTime` are exported for the places a React
+node cannot go: an `aria-label`, a CSV cell, a `title`.
+
 ## The agent pop-up
 
 `AgentChatPopup` is the extension's own Cortena Agent, in the corner of every

package/dist/a2ui/views.js

@@ -23,8 +23,8 @@ import { DateField, formatDateISO, parseDateISO } from "../components/date-field
 import { DataTable } from "../components/data-table/data-table.js";
 import { Chart } from "../components/chart/chart.js";
 import { Markdown } from "../components/markdown.js";
-import { AlertTriangle, CheckCircle2, Info, OctagonAlert, Terminal } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { AlertTriangle, CheckCircle2, Info, OctagonAlert, Terminal } from "lucide-react";
 import * as React from "react";
 //#region src/a2ui/views.tsx
 /**

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/accordion.js

@@ -1,9 +1,9 @@
 "use client";
 "use client";
 import { cn } from "../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { Accordion } from "@base-ui/react/accordion";
 import { ChevronDown } from "lucide-react";
-import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/accordion.tsx
 /**
 * Accordion.

package/dist/components/actor.d.ts

@@ -0,0 +1,103 @@
+"use client";
+import * as React from "react";
+//#region src/components/actor.d.ts
+/**
+ * Who acted, on one screen, in one component (DESIGN-120, protocol §20 /
+ * audit rule P-26).
+ *
+ * Every extension records the same two things on every write — the acting
+ * user and `via` — and every screen that shows a trail has to answer the same
+ * question: did a person do this, or did their agent? Seven extensions
+ * formatting that themselves is seven answers, and the one that prints the
+ * stored string raw shows `Amit (claude-code)`, which tells an operator the
+ * name of a CLI and not whether a human was in the loop.
+ *
+ * So the input is the resolved actor, never a label. There is deliberately no
+ * `label`, `text` or `children` prop: a consumer that could pass a string
+ * would eventually pass a differently formatted one, which is exactly how the
+ * inconsistency arrived. The rules below live here and nowhere else.
+ */
+/**
+ * How the principal acted. `user` and `agent` are the protocol's two values
+ * (packages/shared `ActorVia`); `system` is the display-only third for a write
+ * the platform made on nobody's behalf — a retention sweep, a migration.
+ */
+export type ActorVia = "user" | "agent" | "system";
+/**
+ * inline — text only, sits inside a sentence: "Amit (Agent) changed the status".
+ * cell   — a DataTable cell: avatar-less, one line, truncates.
+ * head   — avatar, name and time, for a feed row or a comment header.
+ */
+export type ActorSize = "inline" | "cell" | "head";
+/**
+ * The suffix, fixed, in one place, so no screen can invent its own. It is
+ * never the agent's technical id or session: which agent ran is an audit
+ * question, and the audit table has `actorAgentId` for it. On screen the only
+ * thing that changes the reader's next action is *that* an agent acted.
+ */
+export declare const ACTOR_AGENT_SUFFIX = "(Agent)";
+/** What `via: "system"` reads as, whatever name came with the row. */
+export declare const ACTOR_SYSTEM_NAME = "System";
+/**
+ * An unknown or deleted user. Never the id: `usr_9f2c…` in a feed reads as
+ * noise to everyone who is not debugging, and the ids are in the audit table
+ * for the one person who is. The server-side `actorLabel` falls back to the
+ * id because a log line has no other anchor; a screen does.
+ */
+export declare const ACTOR_UNKNOWN_NAME = "Someone";
+/** What the shared actor resolver produces and what the list APIs return. */
+export interface ActorValue {
+  /** The acting principal. Null for a system write, or a row that lost its user. */
+  userId: string | null;
+  /** The stored display name. Absent or empty means unknown or deleted. */
+  displayName?: string | null;
+  via: ActorVia;
+  avatarUrl?: string;
+  /** When it happened. Shown in `head` and in the hover for every size. */
+  at?: string | Date;
+  /** Where it happened — "Web", "MCP", "Tasks › Sprint 4". Hover only. */
+  surface?: string;
+}
+/** The name alone, before the suffix. */
+export declare function actorName(actor: Pick<ActorValue, "displayName" | "via">): string;
+/**
+ * The full label as a string: `"Amit"`, `"Amit (Agent)"`, `"System"`,
+ * `"Someone (Agent)"`.
+ *
+ * Exported for the places a React node cannot go — an `aria-label`, a CSV
+ * export, a `title` — and used by `actorColumn` as the column's sort and
+ * filter value, so a table sorts by what the reader sees.
+ */
+export declare function actorLabel(actor: Pick<ActorValue, "displayName" | "via">): string;
+/**
+ * `5 Jan 2026, 14:32` for en-GB; other locales via `Intl.DateTimeFormat`.
+ *
+ * `en-GB` by default and hand-written, exactly as `date-field.tsx` does it,
+ * for the same two reasons. The machine's own locale would render the same
+ * trail differently on every machine — the drift this component exists to
+ * remove — and `Intl`'s `dateStyle: "medium"` says "14 Sept 2026" where
+ * `DateField` says "14 Sep 2026", so two screens in one product would spell
+ * one date two ways. The zone stays local: what time it was *for the reader*
+ * is the question a feed answers.
+ */
+export declare function actorTime(at: string | Date, locale?: string): string | undefined;
+export interface ActorProps extends ActorValue, Omit<React.ComponentProps<"span">, "children" | "color" | "title" | "dangerouslySetInnerHTML"> {
+  /** @default "inline" */
+  size?: ActorSize;
+  /** Override the per-size default: off for `inline` and `cell`, on for `head`. */
+  avatar?: boolean;
+  /** Formatting locale for `at`. @default "en-GB" */
+  locale?: string;
+}
+/**
+ * Actor — "Amit", "Amit (Agent)", "System", "Someone".
+ *
+ * @example
+ * <p>
+ *   <Actor userId={r.actorUserId} displayName={r.actorName} via={r.actorVia} /> changed the status
+ * </p>
+ */
+declare function Actor({ userId, displayName, via, avatarUrl, at, surface, size, avatar, locale, className, ...props }: ActorProps): React.JSX.Element;
+//#endregion
+export { Actor };
+//# sourceMappingURL=actor.d.ts.map