cortena-ui 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -3,6 +3,127 @@
 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.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
+
+- **`AppShell` has a navigation contract** (DESIGN-88). `nav` takes groups of
+  items — id, label, lucide icon or registered mark, href, badge, `exact` —
+  with an optional section label per group and a `footer` for the one thing in
+  a sidebar that is not navigation. Active state comes from `activeId`,
+  `isActive(href, item)` or `pathname`, in that order; cortena-ui still has no
+  router dependency, and `onNavigate` is where react-router takes over without
+  the `href` stopping being real. Below 1024px the sidebar becomes a menu
+  button and a drawer. `nav={null}` renders no sidebar, which is a legal state.
+  The five extensions in the shared-shell mockup would otherwise have shipped
+  five sidebars: five widths, five active treatments, five answers to badges
+  and groups.
+- **`headerSlot`**, between the extension name and the avatar, for a live
+  status pill, the org the screen is scoped to, or one secondary action —
+  and for nothing else. README, "The header slot and the avatar menu", has the
+  list of what may not go there.
+- **`menuItems`**, inserted between Settings and Log out in the avatar menu.
+  Log out stays last and stays behind its separator.
+- **`bottomInset`**, and `data-bottom-bar` detection when it is not given. The
+  theme/help cluster and anything in `agentSlot` lift clear of a mobile bottom
+  tab bar instead of covering two of its tabs. The shell publishes
+  `--ds-shell-bottom-inset` and `--ds-shell-header-height` on its own element
+  and on `<html>`, so a pop-up that portals out of the shell can read them.
+- **`HELP_PANEL_ID` and `NAV_DRAWER_ID`** are exported from `cortena-ui/core`
+  and the root barrel — the ids the shell gives the help region and the mobile
+  drawer, for a consumer that wires its own control's `aria-controls` to one
+  of them. They were exported from the module and reachable from neither entry.
+
+### Changed
+
+- **The help panel starts below the header.** It was `fixed top-6 right-6`,
+  which put it over the 64px header and over the avatar trigger it sits next
+  to. It now starts 12px below the header and still stops 12px above the
+  cluster (DESIGN-88).
+- **`BottomRightCluster` sets its own `bottom`.** It is now
+  `calc(24px + var(--ds-shell-bottom-inset, 0px))` as an inline style rather
+  than the `bottom-6` class, because the value is `calc()` over a variable the
+  consumer may not have set. **Migration:** an existing
+  `className="bottom-22 lg:bottom-6"` on the cluster no longer wins — an
+  inline style beats a utility class — and is now wrong twice over, since it
+  never moved the agent pop-up in `agentSlot`. Delete the override and give
+  the bottom bar `data-bottom-bar`, or pass `bottomInset`; both lift the
+  cluster and the pop-up together (DESIGN-88).
+- **The mobile drawer is a real modal.** It was `role="dialog"
+  aria-modal="true"` with no focus trap: focus stayed on the menu button,
+  Tab walked straight out into the shell under the scrim, and the page
+  scrolled behind it. Focus now starts on its close button, Tab and Shift+Tab
+  cycle inside it, the rest of the shell is `inert` while it is open, body
+  scroll is locked and restored, and focus returns to the menu button
+  (DESIGN-88 review).
+- **A modified click belongs to the browser.** `onNavigate` no longer fires —
+  and the drawer no longer closes — for a middle-click or a
+  cmd/ctrl/shift/alt-click, so "open in a new tab" works without every
+  consumer repeating the same guard before its `preventDefault()`. A router's
+  `onNavigate` written to the old contract keeps working; its own guard is
+  now redundant rather than required (DESIGN-88 review).
+- **`--ds-shell-header-height` is measured**, not restated. The constant is
+  declared once and the header takes it as its height; what lands on `<html>`
+  and on the shell element is the height the browser laid out.
+
+### Fixed
+
+- **More than one shell on a page no longer fights over `<html>`.** Every
+  shell wrote `--ds-shell-bottom-inset` and `--ds-shell-header-height` there
+  and every unmount removed them, so the values were whichever shell committed
+  last and the first to leave took them from the rest — visible in the token
+  guide, which mounts three. The first shell to mount owns the pair; the last
+  to unmount clears it (DESIGN-88 review).
+- **`aria-controls` no longer dangles.** The menu button and the help button
+  named an id that was on the page only while the drawer, or the panel, was
+  mounted; the attribute is now set only while it is (DESIGN-88 review).
+- **The shell's ResizeObservers survive a re-render.** The cluster's and the
+  bottom bar's effects listed `agentSlot`, `helpOpen` and `children` as
+  dependencies — fresh element objects every render — so both observers were
+  torn down and rebuilt on every render of the page underneath. They are keyed
+  on the DOM node now (DESIGN-88 review).
+- **`BrandMark` no longer logs three React errors per page.**
+  `safeRootAttributes` spread a mark's root attributes into JSX in their SVG
+  spelling — `stroke-width`, `stroke-linecap`, `stroke-linejoin` — and React
+  19 warned about each on every screen of every extension. They are camelCased
+  on the way in; the values still reach the DOM unchanged (DESIGN-88).
+
 ## 1.12.0
 
 ### Changed

package/README.md

@@ -124,7 +124,7 @@ regression; `test/chart-bundle.test.tsx` says which line caused it.
 - **Tested in a real browser.** Tests assert computed pixels against the
   token the browser resolved. A dangling `var()` paints transparent, which the
   tests catch and jsdom cannot. Most tests pin a theme and run once; see
-  "Which tests run in both themes".
+  "Which tests run where".
 - **Every component appears in the guide.** `guide/sections.tsx` is the visual
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
@@ -136,7 +136,10 @@ how-to-create-a-cortena-extension, audit rule P-10): the registered brand mark
 and the extension name top left, the avatar menu — the only settings entry
 point — top right, and one fixed bottom-right cluster holding the theme toggle
 then the help button. `BrandMark`, `BottomRightCluster`, `ThemeToggle`,
-`HelpButton` and `documentTitle` are exported alongside it.
+`HelpButton` and `documentTitle` are exported alongside it, and so are
+`HELP_PANEL_ID` and `NAV_DRAWER_ID` — the ids the shell gives the help region
+and the mobile drawer, for a consumer wiring its own `aria-controls` to one of
+them.
 
 The mark comes from `cortena-design/marks` by `extension.id`, which is the same
 file the Apps tile, the MCP app card, the agent pop-up pill and the favicon
@@ -147,6 +150,195 @@ favicon".
 `helpPanel` is a slot until `HelpPanel` lands (EXTBP-24); `help.source` is the
 functional document the panel will read.
 
+### Navigation
+
+`nav` is the left sidebar, and it is the shell's so that five extensions do not
+invent five of them (DESIGN-88):
+
+```tsx
+<AppShell
+  extension={{ id: "tasks", name: "Tasks" }}
+  user={user}
+  nav={{
+    pathname,                       // from the router; see below
+    groups: [
+      { items: [{ id: "dashboard", label: "Dashboard", icon: LayoutDashboard, href: "/", exact: true }] },
+      {
+        label: "Projects",          // a labelled section
+        items: [
+          { id: "all", label: "All Projects", icon: FolderKanban, href: "/projects", exact: true },
+          { id: "alerts", label: "Alerts", icon: Bell, href: "/alerts", badge: 9 },
+        ],
+      },
+    ],
+    footer: <StorageMeter />,       // the one thing that is not navigation
+  }}
+/>
+```
+
+- **`icon`** is a lucide component or the id of a mark registered in
+  `cortena-design/marks`.
+- **`badge`** is a count or a short string, painted from tokens. `0` and `""`
+  draw nothing — an empty chip is worse than no chip.
+- **Active state** comes from one of three, in this order: `activeId` (the
+  item's id), `isActive(href, item)` (a callback), or `pathname` (compared to
+  each `href` as a prefix, or exactly for an item marked `exact`). Give none
+  and nothing is active: cortena-ui has no router dependency, and reading
+  `window.location` here would be right on first paint and stale after every
+  navigation.
+- **react-router** passes `pathname: useLocation().pathname` and keeps
+  navigation client-side with `onNavigate`, which is called before the browser
+  follows the real `href`:
+
+  ```tsx
+  onNavigate: (item, event) => {
+    event.preventDefault();
+    navigate(item.href);
+  },
+  ```
+
+  The `href` stays real either way, so middle-click, "open in new tab" and
+  copy-link all still work: the shell does not call `onNavigate` at all for a
+  middle-click or a cmd/ctrl/shift/alt-click, so that guard does not belong in
+  every consumer.
+- **`href` is compared as a plain path.** A value carrying a query or a hash
+  (`/reports?tab=open`, `/docs#intro`) does not prefix-match the pathname and
+  will never light up. Give the item its base path and resolve `activeId`
+  yourself.
+- **Below 1024px** the sidebar becomes a menu button in the header and a
+  drawer, closed by Escape, by the scrim, or by following an item. It is a
+  real modal: focus moves to its close button, Tab cycles inside it, the rest
+  of the shell is `inert` while it is open, the page under it does not scroll,
+  and focus returns to the menu button on close.
+- **`nav={null}`** renders no sidebar and no menu button. That is a legal
+  state, and the right one for an extension whose whole navigation lives
+  inside one page.
+
+### The header slot and the avatar menu
+
+`headerSlot` sits between the extension name and the avatar; `menuItems` are
+inserted between Settings and Log out. Both exist because the top bar was
+closed and three extensions had something real to put in it — and both stay
+narrow on purpose (§10):
+
+| May go in `headerSlot` | May not |
+| --- | --- |
+| Live status about what is on screen — Assure's "Claude executing" pill | Navigation of any kind. That is `nav`, or it is in the page |
+| The org, workspace or tenant the screen is scoped to — Tasks' "Cortena Labs" | The theme control. It is in the bottom-right cluster, once |
+| **One** secondary action, text or icon, that belongs to the whole extension rather than to the page — Report an issue | Help. It is the help button, and its panel |
+| | Settings, or anything that opens settings. The avatar menu is the only entry point |
+| | A page-level action. Those are `PageHeader`'s `actions` |
+
+`menuItems` takes destinations that are the user's rather than the screen's —
+Assure's Permissions, a Report-issue dialog. Log out stays last and stays
+behind its separator: an extension item cannot push itself under the
+destructive action.
+
+### The bottom inset, and the two variables the shell publishes
+
+`AppShell` sets `--ds-shell-header-height` and `--ds-shell-bottom-inset`, on
+its own element and on `<html>`, so anything that portals out of the shell can
+still tell where the chrome is. `<html>` has one pair of them and a page may
+hold more than one shell — the token guide holds three — so the first shell to
+mount owns the pair and the last to unmount clears it; every shell publishes
+its own values on its own element regardless.
+
+An extension with a bottom tab bar gives that bar `data-bottom-bar` and the
+shell measures it — the measurement is 0 while the bar is hidden, so a
+`lg:hidden` tab bar lifts the cluster on a phone and nowhere else. `bottomInset`
+(a number of pixels, or any CSS length) sets the same distance by hand. Both
+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
@@ -697,11 +889,12 @@ action is shaped like A2UI's client-to-server `action`, and the catalogue is a
 schema-per-component registry. Swapping the engine later is mechanical. Nothing
 from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
 
-## Which tests run in both themes
+## Which tests run where
 
-`vitest.config.ts` has two projects. **`light`** runs every file once in a
-Chromium whose OS colour scheme is light; **`dark`** runs a second time, in a
-dark Chromium, only the files whose name ends `.theme.test.tsx`. Tag a test with
+`vitest.config.ts` has four projects. **`light-1`, `light-2` and `light-3`**
+between them run every file once, in a Chromium whose OS colour scheme is
+light; **`dark`** runs a second time, in a dark Chromium, only the files whose
+name ends `.theme.test.tsx`. Tag a test with
 that suffix when its result depends on the browser's own colour scheme — that
 is, when it asserts a theme-dependent value while no `data-theme` attribute is
 set, the `@media (prefers-color-scheme: dark)` branch of `tokens.css`. Nothing
@@ -713,6 +906,38 @@ test in a file needs the tag, move that test to a sibling `*.theme.test.tsx`
 rather than paying for the whole file twice — six such files exist today, and
 `pnpm test:dark` runs exactly them.
 
+The three `light` projects are a wall-clock split, not a behaviour split
+(DESIGN-86). Files run one at a time inside a project — parallel files made
+overlay tests time out and let one file's pointer position leak into the next —
+so 72 light files in one project meant 72 browser-page setups end to end, and
+that, not the test work, was the suite's wall time. Vitest runs *projects* side
+by side, so splitting the light files three ways makes the wall time the slowest
+shard rather than the sum. Nothing about isolation changes: each shard is still
+serial inside itself, and three light shards plus `dark` is four Chromium
+contexts at once, the same kind of concurrency the suite has always had and as
+many as an 8 GB laptop takes without swapping.
+
+Measured on the machine this was written on: the full suite went from
+**78.3 s** to **54.3 s** wall for the same 78 file runs and 812 tests, while
+CPU time rose from 73 s to 95 s. It is a third off, not the two-thirds the file
+counts suggest, and the gap is the fixed cost each project pays for itself — a
+Vite server, the `optimizeDeps` pre-bundle above, and a browser launch, worth
+roughly ten seconds before the first file runs — plus what four of those
+contending for 8 GB costs the ones already running. Splitting further buys less
+each time and costs memory sooner; measure before raising `LIGHT_SHARDS`.
+
+A file's shard is `hash(path) % 3`, an FNV-1a of its path — deliberately not an
+alphabetical split. Alphabetically, adding one file shifts every file after it
+across a boundary, so shard membership churns on every new test; hashing the
+path leaves every existing file where it was and puts only the new file
+somewhere, and a file moves only when it is renamed. The spread stays close to
+even on its own (21/27/24 over today's 72 files). You never choose a shard, and
+nothing you write needs to know which one it is in: `pnpm test` selects changed
+files across all of them, and a shard with nothing changed in it simply runs
+nothing. If the shards ever drift badly out of balance, raise `LIGHT_SHARDS` in
+`vitest.config.ts` — but keep the light shards plus `dark` at four contexts or
+fewer unless the machine has more memory.
+
 ## Commands
 
 ```bash
@@ -743,6 +968,7 @@ src/styles/index.css  what consumers import after the tokens: animation
                       utilities and the Base UI data-attribute variants
 scripts/bundle-probe.mjs  builds a consumer app per entry and weighs it
 test/                 browser tests; setup.css is the consumer recipe verbatim
+                      split by path hash across three concurrent light projects
                       *.theme.test.tsx also run in a dark Chromium
                       *.test.mjs are the Node-side bundle budgets
 guide/                Vite app: ?theme=light|dark|system frames, or all three

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/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