@tangle-network/ui 11.2.4 → 11.4.0

package/src/primitives/page-header.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { PageHeader } from "./page-header";
+
+describe("PageHeader", () => {
+  it("renders the title as the page's only h1", () => {
+    render(<PageHeader title="Workflows" />);
+    const headings = screen.getAllByRole("heading", { level: 1 });
+    expect(headings).toHaveLength(1);
+    expect(headings[0]).toHaveTextContent("Workflows");
+  });
+
+  it("steps the title down to h2 for a nested surface", () => {
+    render(<PageHeader level={2} title="Skills" />);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+    expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+      "Skills",
+    );
+  });
+
+  it("puts the id on the heading so a region can point aria-labelledby at it", () => {
+    render(<PageHeader titleId="keys-title" title="API keys" />);
+    expect(screen.getByRole("heading", { level: 1 })).toHaveAttribute(
+      "id",
+      "keys-title",
+    );
+  });
+
+  // The description is prose ABOUT the page, so it must not land in the
+  // heading — a paragraph rendered where a heading goes reads as body copy to a
+  // sighted reader and as the page's accessible name to a screen reader.
+  it("keeps the description out of the heading", () => {
+    render(<PageHeader title="Billing" description="Spend and invoices." />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading).toHaveTextContent("Billing");
+    expect(heading).not.toHaveTextContent("Spend and invoices.");
+    expect(screen.getByText("Spend and invoices.")).toBeInTheDocument();
+  });
+
+  it("renders the actions and meta slots when given", () => {
+    render(
+      <PageHeader
+        title="Teams"
+        actions={<button type="button">Invite</button>}
+        meta={<span>4 members</span>}
+      />,
+    );
+    expect(screen.getByRole("button", { name: "Invite" })).toBeInTheDocument();
+    expect(screen.getByText("4 members")).toBeInTheDocument();
+  });
+
+  it("omits the optional slots entirely when not given", () => {
+    const { container } = render(<PageHeader title="Alerts" />);
+    expect(container.querySelector("p")).toBeNull();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+});

package/src/primitives/page-header.tsx

@@ -0,0 +1,86 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * The one masthead every console page opens with.
+ *
+ * A page identifies itself in three separate registers, and each gets its own
+ * slot here so they cannot compete for the same one:
+ *
+ *   - `title` — what the page IS. The `<h1>`, and the only `<h1>`.
+ *   - `description` — one line on what it is for. Prose belongs here, never in
+ *     the title slot: a paragraph rendered where a heading goes reads as body
+ *     copy to a sighted reader and as nothing at all to a screen reader, which
+ *     is how a page ends up with no accessible name.
+ *   - `actions` — what the reader can DO from here, right-aligned and wrapping
+ *     under the title on a narrow viewport rather than squeezing it.
+ *
+ * `meta` is the fourth register and the one most often missing: the small facts
+ * that qualify everything below (a count, a scope, a window). They sit on their
+ * own line under the title so a reader can tell the difference between "this
+ * page has nothing in it" and "this filter matches nothing".
+ *
+ * `titleId` is exposed so a page can point `aria-labelledby` at the heading
+ * from a region further down without minting a second copy of the string.
+ */
+export interface PageHeaderProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  actions?: React.ReactNode;
+  meta?: React.ReactNode;
+  titleId?: string;
+  /** Renders the title one step down for a nested/tab surface. */
+  level?: 1 | 2;
+}
+
+const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
+  (
+    {
+      className,
+      title,
+      description,
+      actions,
+      meta,
+      titleId,
+      level = 1,
+      ...props
+    },
+    ref,
+  ) => {
+    const Heading = level === 1 ? "h1" : "h2";
+    return (
+      <header ref={ref} className={cn("mb-6", className)} {...props}>
+        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-3">
+          <div className="min-w-0">
+            <Heading
+              id={titleId}
+              className={cn(
+                "text-balance font-semibold tracking-tight",
+                level === 1 ? "text-2xl" : "text-lg",
+              )}
+            >
+              {title}
+            </Heading>
+            {description && (
+              <p className="mt-1 max-w-prose text-muted-foreground text-sm">
+                {description}
+              </p>
+            )}
+          </div>
+          {actions && (
+            <div className="flex flex-wrap items-center gap-2">{actions}</div>
+          )}
+        </div>
+        {meta && (
+          <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs">
+            {meta}
+          </div>
+        )}
+      </header>
+    );
+  },
+);
+PageHeader.displayName = "PageHeader";
+
+export { PageHeader };

package/src/primitives/status-pill.test.tsx

@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { StatusPill, type StatusTone } from "./status-pill";
+
+const TONES: StatusTone[] = [
+  "success",
+  "warning",
+  "danger",
+  "info",
+  "running",
+  "neutral",
+];
+
+describe("StatusPill", () => {
+  it("states the status as text, not colour alone", () => {
+    render(<StatusPill tone="danger">Failed</StatusPill>);
+    expect(screen.getByText("Failed")).toBeInTheDocument();
+  });
+
+  // The glyph is the channel that survives greyscale and colour blindness, so
+  // every tone must carry one and it must be hidden from the accessibility tree
+  // — the label beside it already says the same thing.
+  it.each(TONES)("gives %s a decorative glyph", (tone) => {
+    const { container } = render(<StatusPill tone={tone}>Status</StatusPill>);
+    const glyph = container.querySelector("svg");
+    expect(glyph).not.toBeNull();
+    expect(glyph).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it.each(TONES)("brings %s's own paired background", (tone) => {
+    const { container } = render(<StatusPill tone={tone}>Status</StatusPill>);
+    const pill = container.firstElementChild as HTMLElement;
+    expect(pill.className).toContain(`bg-[var(--surface-`);
+    expect(pill.className).toContain("border");
+  });
+
+  // A tone colour is solved against its own background. `bare` drops that
+  // background, so the tone may ride on the glyph only — lifting it onto the
+  // label would put it on whatever plane the caller happens to be on.
+  it.each(TONES)("keeps %s's tone off the label in bare mode", (tone) => {
+    const { container } = render(
+      <StatusPill bare tone={tone}>
+        Status
+      </StatusPill>,
+    );
+    const pill = container.firstElementChild as HTMLElement;
+    expect(pill.className).toContain("bg-transparent");
+    expect(pill.className).not.toContain("bg-[var(--surface-");
+
+    const glyphWrapper = container.querySelector("svg")
+      ?.parentElement as HTMLElement;
+    expect(glyphWrapper.className).toContain("text-[var(--surface-");
+  });
+
+  // Guards the reason TONE_TEXT is declared rather than recovered by searching
+  // TONE_SURFACE for a `text-` class: a miss there yields undefined and removes
+  // the tone from the only channel bare mode has left.
+  it.each(TONES)("resolves a real text class for %s in bare mode", (tone) => {
+    const { container } = render(
+      <StatusPill bare tone={tone}>
+        Status
+      </StatusPill>,
+    );
+    const glyphWrapper = container.querySelector("svg")
+      ?.parentElement as HTMLElement;
+    expect(glyphWrapper.className).not.toContain("undefined");
+    expect(glyphWrapper.className).toMatch(/text-\[var\(--surface-[a-z]+-text\)\]/);
+  });
+
+  // `px-2` from the size and `px-0` from bare are the same utility group, so
+  // which one lands is decided by the class merge rather than by reading order.
+  // Asserting the resolved class list keeps that a guarantee: a bare pill has to
+  // sit flush against the text beside it, and silently keeping the size padding
+  // would space it like a chip that lost only its background.
+  it.each(["sm", "md"] as const)("drops the %s size padding in bare mode", (size) => {
+    const { container } = render(
+      <StatusPill bare size={size} tone="info">
+        Queued
+      </StatusPill>,
+    );
+    const cls = (container.firstElementChild as HTMLElement).className;
+    expect(cls).toContain("px-0");
+    expect(cls).not.toMatch(/(^| )px-2(\.5)?( |$)/);
+  });
+
+  it("gives no two tones the same silhouette", () => {
+    const shapes = TONES.map((tone) => {
+      const { container } = render(<StatusPill tone={tone}>S</StatusPill>);
+      return container.querySelector("svg")?.innerHTML ?? "";
+    });
+    expect(new Set(shapes).size).toBe(shapes.length);
+  });
+
+  it("takes a larger size", () => {
+    const { container } = render(
+      <StatusPill size="md" tone="info">
+        Queued
+      </StatusPill>,
+    );
+    expect((container.firstElementChild as HTMLElement).className).toContain(
+      "text-sm",
+    );
+  });
+});

package/src/primitives/status-pill.tsx

@@ -0,0 +1,193 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * A run/resource state, told three ways at once.
+ *
+ * Status is the one place a console cannot afford to speak in colour alone: a
+ * red dot and a green dot are the same dot to roughly one man in twelve, and
+ * identical in a greyscale print or a screenshot pasted into a ticket. So every
+ * pill carries all three channels — a GLYPH whose silhouette differs per tone,
+ * the tone's COLOUR, and the state's own LABEL as text.
+ *
+ * The glyphs are chosen to survive at 8px and to differ in outline rather than
+ * in fill: a ring reads as "still open", a solid disc as "settled", a slashed
+ * disc as "stopped". Two states never share one silhouette.
+ *
+ * Each tone draws its fill, border and text from ONE matched token triple.
+ * That pairing is the whole point: a status colour is solved against its own
+ * background, and nothing guarantees it against an arbitrary one. A component
+ * that always brings its own background cannot be placed onto a plane that
+ * breaks it.
+ */
+export type StatusTone =
+  | "success"
+  | "warning"
+  | "danger"
+  | "info"
+  | "neutral"
+  | "running";
+
+export interface StatusPillProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  tone: StatusTone;
+  children: React.ReactNode;
+  /**
+   * Drops the fill and border, leaving a toned GLYPH beside a label in the
+   * inherited body colour.
+   *
+   * The label deliberately does not keep the tone. Every status text token
+   * clears the 4.5:1 body floor on the page canvas — a gate holds them there —
+   * but in light the margin is thin (4.51:1 for warning, 4.54:1 for success),
+   * and the canvas is only one of the planes a caller can put a pill on. The
+   * glyph keeps the tone instead because a glyph is non-text content against a
+   * 3:1 floor, so the tone still reads with room to spare on any plane.
+   *
+   * For a control that supplies its own surface (a chip, a selected row).
+   */
+  bare?: boolean;
+  size?: "sm" | "md";
+}
+
+const TONE_SURFACE: Record<StatusTone, string> = {
+  success:
+    "bg-[var(--surface-success-bg)] text-[var(--surface-success-text)] border-[var(--surface-success-border)]",
+  warning:
+    "bg-[var(--surface-warning-bg)] text-[var(--surface-warning-text)] border-[var(--surface-warning-border)]",
+  danger:
+    "bg-[var(--surface-danger-bg)] text-[var(--surface-danger-text)] border-[var(--surface-danger-border)]",
+  info: "bg-[var(--surface-info-bg)] text-[var(--surface-info-text)] border-[var(--surface-info-border)]",
+  // `running` shares the info triple on purpose. `--status-running` exists but
+  // is the green dot on a sandbox — a machine's power state, not a run's
+  // outcome — and it ships as one colour with no paired background or text
+  // tier, which is the pairing this component is built to guarantee. Green also
+  // already means SUCCEEDED here, so a green "running" pill would say a run had
+  // finished well while it was still going.
+  running:
+    "bg-[var(--surface-info-bg)] text-[var(--surface-info-text)] border-[var(--surface-info-border)]",
+  neutral:
+    "bg-[var(--surface-neutral-bg)] text-[var(--surface-neutral-text)] border-[var(--surface-neutral-border)]",
+};
+
+/**
+ * The text tier alone, for `bare`. Declared rather than recovered from
+ * `TONE_SURFACE` by string search: picking the `text-` class out of that string
+ * silently yields `undefined` the moment the triple gains a second `text-`
+ * utility, and an undefined class removes the tone from the one channel `bare`
+ * has left — the glyph — with nothing to signal that it happened.
+ */
+const TONE_TEXT: Record<StatusTone, string> = {
+  success: "text-[var(--surface-success-text)]",
+  warning: "text-[var(--surface-warning-text)]",
+  danger: "text-[var(--surface-danger-text)]",
+  info: "text-[var(--surface-info-text)]",
+  running: "text-[var(--surface-info-text)]",
+  neutral: "text-[var(--surface-neutral-text)]",
+};
+
+/**
+ * One glyph per silhouette. `currentColor` throughout so the mark inherits the
+ * tone's text colour and can never drift from the label beside it.
+ */
+function ToneGlyph({ tone }: { tone: StatusTone }) {
+  // `aria-hidden` is written on every `<svg>` rather than carried in this
+  // spread: the label beside the glyph already names the state, so a title here
+  // would announce it twice — and a lint rule that reads JSX statically cannot
+  // see the attribute through a spread, so it reports each mark as an unlabelled
+  // image.
+  const common = {
+    viewBox: "0 0 8 8",
+    className: "size-2 shrink-0",
+  };
+  switch (tone) {
+    // Settled and good: a solid disc.
+    case "success":
+      return (
+        <svg {...common} aria-hidden="true" fill="currentColor">
+          <circle cx="4" cy="4" r="3.25" />
+        </svg>
+      );
+    // Settled and bad: a disc with a bar through it, so it differs from
+    // success in OUTLINE and not only in hue.
+    case "danger":
+      return (
+        <svg
+          {...common}
+          aria-hidden="true"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+        >
+          <circle cx="4" cy="4" r="3.1" fill="currentColor" opacity="0.35" />
+          <path d="M1.9 6.1 6.1 1.9" strokeLinecap="round" />
+        </svg>
+      );
+    // Needs a person: a triangle.
+    case "warning":
+      return (
+        <svg {...common} aria-hidden="true" fill="currentColor">
+          <path d="M4 0.6 7.7 7.1H0.3z" />
+        </svg>
+      );
+    // Still moving: an open ring, visibly hollow at 8px.
+    case "running":
+      return (
+        <svg
+          {...common}
+          aria-hidden="true"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.75"
+        >
+          <circle cx="4" cy="4" r="2.9" />
+        </svg>
+      );
+    // Informational: a square, the only right-angled mark in the set.
+    case "info":
+      return (
+        <svg {...common} aria-hidden="true" fill="currentColor">
+          <rect x="0.9" y="0.9" width="6.2" height="6.2" rx="1.2" />
+        </svg>
+      );
+    // Nothing has happened: a dash. No enclosed area at all.
+    default:
+      return (
+        <svg
+          {...common}
+          aria-hidden="true"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.75"
+        >
+          <path d="M1 4h6" strokeLinecap="round" />
+        </svg>
+      );
+  }
+}
+
+const StatusPill = React.forwardRef<HTMLSpanElement, StatusPillProps>(
+  ({ className, tone, children, bare = false, size = "sm", ...props }, ref) => (
+    <span
+      ref={ref}
+      className={cn(
+        "inline-flex items-center gap-1.5 whitespace-nowrap rounded-full font-medium",
+        size === "sm" ? "px-2 py-0.5 text-xs" : "px-2.5 py-1 text-sm",
+        bare
+          ? "border border-transparent bg-transparent px-0"
+          : cn("border", TONE_SURFACE[tone]),
+        className,
+      )}
+      {...props}
+    >
+      {/* In `bare` mode the tone rides on the glyph alone, so it is scoped to
+          the wrapper the glyph sits in rather than applied to the whole pill. */}
+      <span className={cn("inline-flex", bare && TONE_TEXT[tone])}>
+        <ToneGlyph tone={tone} />
+      </span>
+      {children}
+    </span>
+  ),
+);
+StatusPill.displayName = "StatusPill";
+
+export { StatusPill };

package/src/primitives/toolbar.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { FilterField, Toolbar } from "./toolbar";
+
+describe("Toolbar", () => {
+  it("renders each slot it is given", () => {
+    render(
+      <Toolbar
+        actions={<button type="button">Export</button>}
+        filters={<span>Product</span>}
+        search={<input aria-label="Search" type="search" />}
+      />,
+    );
+    expect(screen.getByLabelText("Search")).toBeInTheDocument();
+    expect(screen.getByText("Product")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Export" })).toBeInTheDocument();
+  });
+
+  it("omits a slot's wrapper entirely when it is not given", () => {
+    const { container } = render(
+      <Toolbar search={<input aria-label="Search" type="search" />} />,
+    );
+    const row = container.firstElementChild as HTMLElement;
+    expect(row.children).toHaveLength(1);
+  });
+
+  // Search and filters both flex, on purpose: giving the filter row its content
+  // width starves search — a 537px filter row in an 832px toolbar collapses the
+  // search field to 89px. Sharing bounds the filter row so it scrolls within its
+  // half and search stays usable. Only `actions` sits at content width.
+  it("lets search and filters share the row, holding actions at content width", () => {
+    const { container } = render(
+      <Toolbar
+        actions={<button type="button">Export</button>}
+        filters={<span>Product</span>}
+        search={<input aria-label="Search" type="search" />}
+      />,
+    );
+    const [searchSlot, filterSlot, actionsSlot] = Array.from(
+      (container.firstElementChild as HTMLElement).children,
+    ) as HTMLElement[];
+    expect(searchSlot.className).toContain("lg:flex-1");
+    expect(searchSlot.className).toContain("min-w-0");
+    // Both flex, so neither can starve the other.
+    expect(filterSlot.className).toContain("lg:flex-1");
+    expect(filterSlot.className).toContain("min-w-0");
+    expect(actionsSlot.className).toContain("shrink-0");
+    expect(actionsSlot.className).not.toContain("flex-1");
+  });
+
+  it("scrolls the filter row instead of wrapping it", () => {
+    const { container } = render(<Toolbar filters={<span>Product</span>} />);
+    const filterSlot = (container.firstElementChild as HTMLElement)
+      .children[0] as HTMLElement;
+    expect(filterSlot.className).toContain("overflow-x-auto");
+    expect(filterSlot.className).toContain("min-w-0");
+  });
+
+  // A free child would render as a bare flex item with none of the slots'
+  // guards, so it would size off its content and push the row into overflow.
+  it("renders nothing for a stray child", () => {
+    const { container } = render(
+      // @ts-expect-error children is deliberately not part of the API
+      <Toolbar>
+        <span>stray</span>
+      </Toolbar>,
+    );
+    expect(screen.queryByText("stray")).toBeNull();
+    expect((container.firstElementChild as HTMLElement).children).toHaveLength(
+      0,
+    );
+  });
+});
+
+describe("FilterField", () => {
+  it("labels the control visibly rather than by placeholder", () => {
+    render(
+      <FilterField htmlFor="product" label="Product">
+        <select id="product">
+          <option>All products</option>
+        </select>
+      </FilterField>,
+    );
+    expect(screen.getByText("Product")).toBeInTheDocument();
+    expect(screen.getByLabelText("Product")).toBe(
+      screen.getByRole("combobox"),
+    );
+  });
+});

package/src/primitives/toolbar.tsx

@@ -0,0 +1,105 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * The control row above a table or list: search, filters, then the view switch.
+ *
+ * It exists because the alternative keeps producing the same two failures. A
+ * bare flex row gives every control its natural width, so a search field sits
+ * at 1120px on one line and three selects stack full-width beneath it — three
+ * enormous empty bars where a compact bar belongs. And each control brought its
+ * own visual language, so one row carried a native `<select>`, a custom input
+ * and a segmented control side by side.
+ *
+ * So search and filters SHARE the free space and `actions` stays at its content
+ * width, and the row is the one place those controls are composed, which is what
+ * keeps them looking like one set.
+ *
+ * Sharing is deliberate, and the alternative is worse. Giving the filter row its
+ * content width starves search: measured with a 537px filter row in an 832px
+ * toolbar, the search field collapses to 89px. Letting both flex bounds the
+ * filter row instead, so it scrolls within its half — 313px each in that same
+ * case — and search stays usable however many filters a page adds. `max-w-sm`
+ * then stops search claiming more than it can use when there are few filters.
+ *
+ * On a narrow viewport the row becomes a column and the filters scroll
+ * horizontally as a group rather than wrapping into a tall stack that pushes
+ * the table itself below the fold.
+ */
+/**
+ * Slots only — `children` is omitted deliberately. A free child would render as
+ * a bare flex item with none of the `min-w-0` / `shrink-0` guards the named
+ * slots carry, so it would size itself off its content and push the row into
+ * the overflow this layout exists to prevent.
+ */
+export interface ToolbarProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** The one control that expands to fill the row. */
+  search?: React.ReactNode;
+  /** Filters, in reading order. Kept on one scrollable line when space runs out. */
+  filters?: React.ReactNode;
+  /** View switches and exports, pinned to the end. */
+  actions?: React.ReactNode;
+}
+
+const Toolbar = React.forwardRef<HTMLDivElement, ToolbarProps>(
+  ({ className, search, filters, actions, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        "mb-4 flex flex-col gap-3 lg:flex-row lg:items-center",
+        className,
+      )}
+      {...props}
+    >
+      {search && <div className="min-w-0 lg:max-w-sm lg:flex-1">{search}</div>}
+      {filters && (
+        // `py-1` leaves room for a focus ring above and below; horizontally the
+        // scroll container clips it, which is the trade a single-line filter row
+        // makes. No negative margin — pulling the row wider than its parent is
+        // what made every page report 4px of horizontal overflow.
+        <div className="flex min-w-0 items-center gap-2 overflow-x-auto py-1 lg:flex-1">
+          {filters}
+        </div>
+      )}
+      {actions && (
+        <div className="flex shrink-0 items-center gap-2 lg:ml-auto">
+          {actions}
+        </div>
+      )}
+    </div>
+  ),
+);
+Toolbar.displayName = "Toolbar";
+
+/**
+ * A labelled filter control. The label is visible, not a placeholder: a select
+ * whose current value IS its label ("All products") tells the reader what is
+ * selected but never what the control governs, so a row of three reads as three
+ * unrelated words.
+ */
+export interface FilterFieldProps extends React.HTMLAttributes<HTMLDivElement> {
+  label: string;
+  htmlFor?: string;
+}
+
+const FilterField = React.forwardRef<HTMLDivElement, FilterFieldProps>(
+  ({ className, label, htmlFor, children, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn("flex shrink-0 items-center gap-2", className)}
+      {...props}
+    >
+      <label
+        htmlFor={htmlFor}
+        className="whitespace-nowrap text-muted-foreground text-xs"
+      >
+        {label}
+      </label>
+      {children}
+    </div>
+  ),
+);
+FilterField.displayName = "FilterField";
+
+export { FilterField, Toolbar };

package/src/redaction/index.ts

@@ -1,3 +1,15 @@
+/**
+ * The client half of agent-app's reversible redaction.
+ *
+ * `agent-app/redact` builds a document of masked spans with each original kept
+ * encrypted, and reveals one span at a time through `revealSpan`, where the
+ * authorization and the audit record happen. This module renders that document
+ * and calls back for a reveal.
+ *
+ * The two segment types are deliberately not identical: agent-app's carries the
+ * `cipher` for a masked span, and this one does not. The ciphertext stays on the
+ * server, so the type a browser holds cannot name it.
+ */
 export {
   RedactedDocument,
   type RedactedDocumentProps,

package/src/run/run-row-shell.tsx

@@ -32,7 +32,10 @@ export function RunRowStatusDot({ status }: { status: RunRowStatus }) {
 export interface RunRowShellProps {
   /** Semantic lead glyph — always visible; never replaced by status. */
   icon: ReactNode;
-  title: string;
+  /** Row title. A string in the common case; a node when the title carries its
+   *  own treatment (e.g. an active-state shimmer sweep) — it renders inline in
+   *  the shell's title slot either way. */
+  title: ReactNode;
   /** Secondary inline text (tool path/command, or a reasoning preview). */
   description?: string;
   /** Render the description in mono (tools) vs prose (reasoning). */