@tangle-network/ui 11.48.0 → 11.50.1

package/src/primitives/settings.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { CircleAlert, Ellipsis, Lock } from "lucide-react";
+import { CircleAlert, Ellipsis, Lock, TriangleAlert, type LucideIcon } from "lucide-react";
 import * as React from "react";
 import { cn } from "../lib/utils";
 import { Button } from "./button";
@@ -9,6 +9,7 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigge
 import { fieldMessageId } from "./field";
 import { InfoTip } from "./info-tip";
 import { Label } from "./label";
+import { StatusGlyph, type StatusTone } from "./status-pill";
 
 /*
  * Settings rows and lists answer to their section card's width, not the
@@ -21,25 +22,46 @@ import { Label } from "./label";
  */
 
 const SCROLL_OFFSET = "scroll-mt-[calc(var(--shell-header-height)_+_1rem)]";
+const GUTTER = "px-5 py-4 @max-[34rem]/settings-section:px-4";
 const DIVIDED = "not-first:border-t not-first:border-[color:var(--border-subtle)]";
 const ERROR_TEXT = "text-[color:var(--surface-danger-text)]";
 
-function ErrorLine({ id, className, children }: { id?: string; className?: string; children: React.ReactNode }) {
+interface LineProps { id?: string; role?: "status" | "alert"; className?: string; children: React.ReactNode }
+
+function GlyphLine({ icon: Icon, className, children, ...props }: LineProps & { icon: LucideIcon }) {
   return (
-    <div id={id} role="alert" className={cn("flex items-start gap-1.5 text-sm leading-5 [overflow-wrap:anywhere]", ERROR_TEXT, className)}>
-      <CircleAlert aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
+    <div {...props} className={cn("flex items-start gap-1.5 text-sm leading-5 [overflow-wrap:anywhere]", className)}>
+      <Icon aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
       <div className="min-w-0">{children}</div>
     </div>
   );
 }
 
-function LockLine({ id, className, children }: { id?: string; className?: string; children: React.ReactNode }) {
-  return (
-    <div id={id} className={cn("flex items-start gap-1.5 text-sm leading-5 text-muted-foreground [overflow-wrap:anywhere]", className)}>
-      <Lock aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
-      <div className="min-w-0">{children}</div>
-    </div>
-  );
+const ErrorLine = ({ className, ...props }: LineProps) => <GlyphLine icon={CircleAlert} role="alert" className={cn(ERROR_TEXT, className)} {...props} />;
+const LockLine = ({ className, ...props }: LineProps) => <GlyphLine icon={Lock} className={cn("text-muted-foreground", className)} {...props} />;
+
+// A long identifier (a URL, an address, an event name) is one unit: it moves to the next line
+// whole, and only one wider than its column breaks, at its own punctuation, where a style guide
+// breaks a URL: after a slash run or `@`, before `. - _ ? # & =`. A mid-word break is the last resort.
+const TOKEN_BREAK = /(?<=[/@])(?=[^/])|(?<=[\p{L}\p{N}])(?=[.\-_?#&=][\p{L}\p{N}])/u;
+
+function breakTokens(node: React.ReactNode): React.ReactNode {
+  if (typeof node === "string") {
+    if (!TOKEN_BREAK.test(node)) return node;
+    return node.split(/(\s+)/).map((word, index) => {
+      const parts = word.split(TOKEN_BREAK);
+      return parts.length < 2 ? word : (
+        <span key={index} className="inline-block max-w-full [text-decoration:inherit]">
+          {parts.map((part, at) => <React.Fragment key={at}>{at > 0 && <wbr />}{part}</React.Fragment>)}
+        </span>
+      );
+    });
+  }
+  if (Array.isArray(node)) return React.Children.map(node, breakTokens);
+  if (React.isValidElement<{ children?: React.ReactNode }>(node) && node.props.children != null && typeof node.props.children !== "function") {
+    return React.cloneElement(node, undefined, breakTokens(node.props.children));
+  }
+  return node;
 }
 
 export type SettingsRowLayout = "inline" | "compact" | "stacked";
@@ -123,7 +145,8 @@ export function SettingsRow(props: SettingsRowProps) {
       id={id}
       data-layout={layout}
       className={cn(
-        "grid min-w-0 items-center gap-x-8 gap-y-3 px-5 py-4 @max-[34rem]/settings-section:px-4",
+        "grid min-w-0 items-center gap-x-8 gap-y-3",
+        GUTTER,
         SCROLL_OFFSET,
         DIVIDED,
         ROW_COLUMNS[hasValue && layout === "compact" ? "inline" : layout],
@@ -150,7 +173,7 @@ export function SettingsRow(props: SettingsRowProps) {
       </div>
       {(hasValue || (control != null && control !== false)) && (
         <div className={cn("flex min-w-0 items-center gap-2", ROW_CONTROL[hasValue && layout === "compact" ? "inline" : layout])}>
-          {hasValue && <span data-slot="settings-value" className={cn("min-w-0 text-foreground text-sm [overflow-wrap:anywhere] @min-[34rem]/settings-section:text-right", mono && "font-mono")}>{value}</span>}
+          {hasValue && <span data-slot="settings-value" className={cn("min-w-0 text-foreground text-sm [overflow-wrap:anywhere] @min-[34rem]/settings-section:text-right", mono && "font-mono")}>{breakTokens(value)}</span>}
           {control}
         </div>
       )}
@@ -194,7 +217,7 @@ export function SettingsSection({
       data-tone={tone}
       className={cn("@container/settings-section min-w-0", SCROLL_OFFSET, danger && "border-[color:var(--surface-danger-border)]")}
     >
-      <div className="flex items-start justify-between gap-4 px-5 py-4 @max-[34rem]/settings-section:flex-wrap @max-[34rem]/settings-section:px-4">
+      <div className={cn("flex items-start justify-between gap-4 @max-[34rem]/settings-section:flex-wrap", GUTTER)}>
         <div className="min-w-0">
           <div className="flex items-center gap-1.5">
             <CardTitle as="h2" id={titleId} className={cn("leading-6 [overflow-wrap:anywhere]", danger && ERROR_TEXT)}>{title}</CardTitle>
@@ -216,6 +239,40 @@ export function SettingsSection({
   );
 }
 
+const NOTE_TONE = {
+  default: "text-foreground",
+  muted: "text-muted-foreground",
+  warning: "text-[color:var(--surface-warning-text)]",
+  danger: ERROR_TEXT,
+} as const;
+
+const NOTE_GLYPH: Partial<Record<keyof typeof NOTE_TONE, LucideIcon>> = { warning: TriangleAlert, danger: CircleAlert };
+
+export interface SettingsNoteProps {
+  /**
+   * `default` keeps the body ink, for a figure such as a MetricStrip or an inline form.
+   * `muted` is an empty list or a loading line. `warning` (a notice) and `danger` (a refusal)
+   * lead with a glyph, so the tone is not carried by colour alone.
+   */
+  tone?: keyof typeof NOTE_TONE;
+  /** `status` announces a change politely; `alert` announces a refusal at once. */
+  role?: "status" | "alert";
+  children?: React.ReactNode;
+}
+
+/**
+ * A line or block of a {@link SettingsSection} that is not a row: an empty list, a loading line,
+ * a notice, a refusal or a figure. It takes the rows' gutters and divider, so it lines up with
+ * the rows and lists around it.
+ */
+export function SettingsNote({ tone = "default", role, children }: SettingsNoteProps) {
+  const className = cn("min-w-0", GUTTER, DIVIDED, NOTE_TONE[tone]);
+  const glyph = NOTE_GLYPH[tone];
+  return glyph
+    ? <GlyphLine icon={glyph} role={role} className={className}>{children}</GlyphLine>
+    : <div role={role} className={cn("text-sm leading-5 [overflow-wrap:anywhere]", className)}>{children}</div>;
+}
+
 /** Track widths for a {@link SettingsList}. Every slot its items use needs a column, except status and menu, which have fallbacks. */
 export interface SettingsListColumns {
   /** A logo or avatar column, such as `"36px"`. */
@@ -310,6 +367,8 @@ export interface SettingsListItemProps {
   meta?: React.ReactNode;
   /** The item's state as plain text, or a control that sets it (a role select). */
   status?: React.ReactNode;
+  /** The state's tone, drawn as a glyph before it in the tone's ink; the state's text keeps its colour. */
+  tone?: StatusTone;
   /** Shown under the meta in danger text and announced. */
   error?: React.ReactNode;
   /** The one verb the item needs at rest. It is drawn as an outline button, so it never reads as the state beside it. */
@@ -359,7 +418,7 @@ const NARROW_STATUS = "@max-[34rem]/settings-section:col-start-[main] @max-[34re
  * that name. Without a status column the state follows the meta, and without
  * a menu column the ⋯ menu ends the action cell.
  */
-export function SettingsListItem({ leading, title, meta, status, error, action, menu }: SettingsListItemProps) {
+export function SettingsListItem({ leading, title, meta, status, tone, error, action, menu }: SettingsListItemProps) {
   const columns = React.useContext(SettingsListContext);
   const titleId = React.useId();
   const reasonId = `${titleId}-reason`;
@@ -376,6 +435,8 @@ export function SettingsListItem({ leading, title, meta, status, error, action,
       {action.label}
     </Button>
   );
+  const state = tone && status != null ? <><StatusGlyph tone={tone} /><span className="min-w-0">{status}</span></> : status;
+  const toned = tone && "flex items-center gap-1.5";
   const actionCell = (actionButton || (menuNode && !columns.menu)) && (
     <>{actionButton}{!columns.menu && menuNode}</>
   );
@@ -392,17 +453,17 @@ export function SettingsListItem({ leading, title, meta, status, error, action,
           id={titleId}
           className="font-medium text-sm leading-5 text-foreground [overflow-wrap:anywhere] [&_a]:rounded-sm [&_a]:text-foreground [&_a]:underline-offset-4 [&_a:hover]:underline [&_a:focus-visible]:outline-2 [&_a:focus-visible]:outline-offset-2 [&_a:focus-visible]:outline-[var(--focus-border)]"
         >
-          {title}
+          {breakTokens(title)}
         </div>
-        {meta != null && <div className="text-sm leading-5 text-muted-foreground [overflow-wrap:anywhere]">{meta}</div>}
-        {status != null && !columns.status && <div className="mt-1 text-sm leading-5 text-muted-foreground">{status}</div>}
+        {meta != null && <div className="text-sm leading-5 text-muted-foreground [overflow-wrap:anywhere]">{breakTokens(meta)}</div>}
+        {status != null && !columns.status && <div className={cn("mt-1 text-sm leading-5 text-muted-foreground", toned)}>{state}</div>}
         {locked && <LockLine id={reasonId} className="mt-1">{action?.disabledReason}</LockLine>}
       </div>
       {error != null && (
         <ErrorLine className="col-start-[main] row-start-2 mt-1 @max-[34rem]/settings-section:col-end-[-1] @max-[34rem]/settings-section:row-start-3">{error}</ErrorLine>
       )}
       {status != null && columns.status && (
-        <div className={cn("col-start-[status] row-start-1 min-w-0 text-sm leading-5 text-muted-foreground", NARROW_STATUS)}>{status}</div>
+        <div className={cn("col-start-[status] row-start-1 min-w-0 text-sm leading-5 text-muted-foreground", toned, NARROW_STATUS)}>{state}</div>
       )}
       {actionCell && (
         <div className="col-start-[action] row-start-1 flex min-w-0 items-center justify-end gap-1">{actionCell}</div>

package/src/primitives/status-pill.tsx

@@ -170,6 +170,13 @@ function ToneGlyph({ tone }: { tone: StatusTone }) {
   }
 }
 
+const GLYPH = "inline-flex [&>svg]:size-3 [&>svg]:shrink-0";
+
+/** The tone's glyph in the tone's ink, before a label that keeps its own colour, as `bare` draws it. */
+export function StatusGlyph({ tone }: { tone: StatusTone }) {
+  return <span aria-hidden="true" className={cn(GLYPH, TONE_TEXT[tone])}><ToneGlyph tone={tone} /></span>;
+}
+
 const StatusPill = React.forwardRef<HTMLSpanElement, StatusPillProps>(
   ({ className, tone, children, icon, bare = false, size = "sm", ...props }, ref) => (
     <span
@@ -186,7 +193,7 @@ const StatusPill = React.forwardRef<HTMLSpanElement, StatusPillProps>(
     >
       {/* 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 aria-hidden="true" className={cn("inline-flex [&>svg]:size-3 [&>svg]:shrink-0", bare && TONE_TEXT[tone])}>
+      <span aria-hidden="true" className={cn(GLYPH, bare && TONE_TEXT[tone])}>
         {icon ?? <ToneGlyph tone={tone} />}
       </span>
       {children}

package/src/run/expanded-tool-detail.tsx

@@ -1,11 +1,5 @@
 import { memo } from "react";
-import {
-  ArrowRight,
-  ArrowLeft,
-  AlertCircle,
-  Loader2,
-  FileText,
-} from "lucide-react";
+import { ArrowRight, ArrowLeft, FileText } from "lucide-react";
 import type { ToolPart } from "../types/parts";
 import { getToolDisplayMetadata } from "../utils/tool-display";
 import { CommandPreview } from "../tool-previews/command-preview";
@@ -16,8 +10,8 @@ import { GlobResultsPreview } from "../tool-previews/glob-results-preview";
 import { WebSearchPreview } from "../tool-previews/web-search-preview";
 import { QuestionPreview } from "../tool-previews/question-preview";
 import { DiffPreview } from "../tool-previews/diff-preview";
-import { cn } from "../lib/utils";
 import { ExpandableContent } from "./expandable-content";
+import { RunStatusIcon } from "./status-meta";
 
 export interface ExpandedToolDetailProps {
   part: ToolPart;
@@ -169,7 +163,7 @@ export const ExpandedToolDetail = memo(({ part }: ExpandedToolDetailProps) => {
       {error && (
         <div className="overflow-hidden rounded-[var(--radius-lg)] border border-[var(--surface-danger-border)]">
           <div className="flex items-center gap-2 border-b border-[var(--surface-danger-border)] bg-[var(--surface-danger-bg)] px-3 py-2">
-            <AlertCircle className="h-3 w-3 text-[var(--surface-danger-text)]" />
+            <RunStatusIcon status="failed" aria-hidden className="size-3" />
             <span className="text-xs font-medium uppercase tracking-[0.08em] text-[var(--surface-danger-text)]">
               Error
             </span>
@@ -185,7 +179,7 @@ export const ExpandedToolDetail = memo(({ part }: ExpandedToolDetailProps) => {
       {/* Running state */}
       {(status === "pending" || status === "running") && (
         <div className="flex items-center gap-2 rounded-[var(--radius-md)] border border-border bg-muted px-3 py-3 text-xs text-muted-foreground">
-          <Loader2 className={cn("h-3 w-3 animate-spin text-primary")} />
+          <RunStatusIcon status="running" aria-hidden className="size-3" />
           Running…
         </div>
       )}

package/src/run/index.ts

@@ -37,3 +37,11 @@ export {
   type ApprovalPlanStep,
 } from "./approval-card";
 export { RunPhaseList, type RunPhase } from "./run-phase-list";
+export {
+  RunStatusIcon,
+  runStatus,
+  statusMeta,
+  type RunStatus,
+  type RunStatusIconProps,
+  type StatusMeta,
+} from "./status-meta";

package/src/run/run-group.tsx

@@ -2,7 +2,6 @@ import { memo, useMemo, type ComponentType, type ReactNode } from "react";
 import * as Collapsible from "@radix-ui/react-collapsible";
 import {
   Bot,
-  Loader2,
   ChevronDown,
   ChevronRight,
   Terminal,
@@ -13,7 +12,6 @@ import {
   Globe,
   ClipboardList,
   Settings,
-  Sparkles,
   type LucideProps,
 } from "lucide-react";
 import { cn } from "../lib/utils";
@@ -24,6 +22,7 @@ import type { AgentBranding } from "../types/branding";
 import type { CustomToolRenderer } from "../types/tool-display";
 import { InlineToolItem } from "./inline-tool-item";
 import { InlineThinkingItem } from "./inline-thinking-item";
+import { RunStatusIcon, statusMeta } from "./status-meta";
 import { Markdown } from "../markdown/markdown";
 import { SyntheticText } from "../chat/synthetic-text";
 
@@ -98,7 +97,7 @@ function AssistantShell({
         <span>{branding.label}</span>
         {isStreaming ? (
           <span className="inline-flex items-center gap-1.5">
-            <Loader2 className="h-3 w-3 animate-spin" />
+            <RunStatusIcon status="running" aria-hidden className="size-3" />
             Thinking
           </span>
         ) : null}
@@ -418,7 +417,7 @@ export const RunGroup = memo(
                         key={key}
                         className="flex items-center gap-2 rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--md3-surface-container)] px-4 py-3 text-sm text-muted-foreground"
                       >
-                        <Loader2 className="h-4 w-4 animate-spin text-primary" />
+                        <RunStatusIcon status="running" aria-hidden />
                         Building view…
                       </div>
                     );
@@ -484,17 +483,10 @@ export const RunGroup = memo(
                 ) : null}
                 <span className="ml-auto flex shrink-0 items-center gap-1.5">
                   <CategoryBadges categories={stats.toolCategories} />
-                  {isStreaming ? (
-                    <span className="inline-flex items-center gap-1 rounded-full border border-[var(--border-accent)] bg-[var(--accent-surface-soft)] px-2 py-px text-[10px] font-semibold uppercase text-[var(--accent-text)]">
-                      <Loader2 className="h-2.5 w-2.5 animate-spin" />
-                      Running
-                    </span>
-                  ) : (
-                    <span className="inline-flex items-center gap-1 rounded-full border border-border px-2 py-px text-[10px] font-semibold uppercase text-muted-foreground">
-                      <Sparkles className="h-2.5 w-2.5" />
-                      Done
-                    </span>
-                  )}
+                  <span className="inline-flex items-center gap-1 rounded-full border border-border px-2 py-px text-[10px] font-semibold uppercase text-muted-foreground">
+                    <RunStatusIcon status={isStreaming ? "running" : "done"} aria-hidden className="size-3" />
+                    {statusMeta(isStreaming ? "running" : "done").label}
+                  </span>
                 </span>
               </button>
             </Collapsible.Trigger>
@@ -542,7 +534,7 @@ export const RunGroup = memo(
                     } else if (toolPart.state.status === "running") {
                       node = (
                         <div className="flex items-center gap-3 rounded-[var(--radius-lg)] border border-[var(--border-subtle)] bg-[var(--md3-surface-container)] px-4 py-3 text-sm text-muted-foreground">
-                          <Loader2 className="h-4 w-4 animate-spin text-primary" />
+                          <RunStatusIcon status="running" aria-hidden />
                           Building view…
                         </div>
                       );

package/src/run/run-phase-list.stories.tsx

@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { RunPhaseList } from "./run-phase-list";
+
+const meta: Meta<typeof RunPhaseList> = {
+  title: "Run/RunPhaseList",
+  component: RunPhaseList,
+  parameters: { layout: "padded" },
+};
+export default meta;
+
+export const Phases: StoryObj<typeof RunPhaseList> = {
+  args: {
+    phases: [
+      { id: "find", title: "Find the hero source", summary: "Read 12 files · searched 3 times", status: "done", content: <p>12 reads</p> },
+      { id: "patch", title: "Patch the layout", summary: "2 edits", status: "error", content: <p>An edit failed</p> },
+      { id: "prove", title: "Prove it on a phone", summary: "Running the browser", status: "running", content: <p>Chromium at 390</p> },
+    ],
+  },
+};

package/src/run/run-phase-list.test.tsx

@@ -20,6 +20,14 @@ describe("RunPhaseList", () => {
     expect(screen.queryByText("step detail")).toBeNull();
     fireEvent.click(first);
     expect(screen.getByText("step detail")).toBeInTheDocument();
-    expect(screen.getByLabelText("Had an error")).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Failed" }).getAttribute("class")).toMatch(/circle-x/);
+  });
+
+  it("marks a running phase with the breathing status glyph, not a spinner", () => {
+    const { container } = render(
+      <RunPhaseList phases={[{ id: "a", title: "Prove it", status: "running", content: null }]} />,
+    );
+    expect(screen.getByRole("img", { name: "Running" }).getAttribute("data-motion")).toBe("essential");
+    expect(container.querySelector(".animate-spin")).toBeNull();
   });
 });

package/src/run/run-phase-list.tsx

@@ -1,7 +1,8 @@
 import { useState, type ReactNode } from "react";
-import { ChevronRight, CircleAlert, Loader2 } from "lucide-react";
+import { ChevronRight } from "lucide-react";
 import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
+import { RunStatusIcon } from "./status-meta";
 
 export interface RunPhase {
   id: string;
@@ -37,8 +38,7 @@ function PhaseRow({ phase }: { phase: RunPhase }) {
           <span className="font-medium text-foreground">{phase.title}</span>
           {phase.summary && <span className="text-muted-foreground"> · {phase.summary}</span>}
         </span>
-        {phase.status === "running" && <Loader2 aria-label="Running" className="mt-1 size-4 shrink-0 animate-spin text-muted-foreground" />}
-        {phase.status === "error" && <CircleAlert aria-label="Had an error" className="mt-1 size-4 shrink-0 text-[var(--surface-danger-text)]" />}
+        {phase.status && phase.status !== "done" && <RunStatusIcon status={phase.status} className="mt-1" />}
       </button>
       {open && <div id={id} className="mb-2 ml-6 mt-1">{phase.content}</div>}
     </li>

package/src/run/status-meta.tsx

@@ -0,0 +1,92 @@
+import {
+  CircleCheck,
+  CircleDashed,
+  CircleDot,
+  CircleQuestionMark,
+  CircleStop,
+  CircleX,
+  Hand,
+  Hourglass,
+  type LucideIcon,
+  type LucideProps,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+
+/** The states an agent or a run reports. Every surface names them with `statusMeta`. */
+export type RunStatus = "running" | "waiting" | "needs-you" | "done" | "failed" | "stopped" | "idle" | "unknown";
+
+export interface StatusMeta {
+  /** The one word for the state. A qualifier such as "Shipped" follows Done; it never replaces it. */
+  label: string;
+  /** The lucide glyph, drawn on the 16px grid at stroke 1.75 (`RunStatusIcon` does both). */
+  icon: LucideIcon;
+  /** The Brand colour token for the glyph and any bare status text: `color: var(<token>)`. */
+  token: `--${string}`;
+}
+
+// Amber is attention, and only Needs you is attention: waiting on a peer, a
+// stop and an idle agent are neutral. Running takes the info ink that
+// StatusPill's running tone and the run-mix in-flight slice already use, not
+// the accent, so a per-user accent can never make Running read as Done or
+// Failed. Failed is always CircleX; the warning triangle is for warnings.
+const META: Record<RunStatus, StatusMeta> = {
+  running: { label: "Running", icon: CircleDot, token: "--surface-info-text" },
+  waiting: { label: "Waiting", icon: Hourglass, token: "--surface-neutral-text" },
+  "needs-you": { label: "Needs you", icon: Hand, token: "--surface-warning-text" },
+  done: { label: "Done", icon: CircleCheck, token: "--surface-success-text" },
+  failed: { label: "Failed", icon: CircleX, token: "--surface-danger-text" },
+  stopped: { label: "Stopped", icon: CircleStop, token: "--surface-neutral-text" },
+  idle: { label: "Idle", icon: CircleDashed, token: "--surface-neutral-text" },
+  unknown: { label: "Unknown", icon: CircleQuestionMark, token: "--surface-neutral-text" },
+};
+
+// The vocabularies ui and its products already speak, so each maps here once.
+const ALIASES: Record<string, RunStatus> = {
+  active: "running", in_progress: "running", "in-progress": "running", streaming: "running",
+  pending: "waiting", queued: "waiting", blocked: "waiting",
+  "attention-needed": "needs-you", needs_you: "needs-you", needs_input: "needs-you", awaiting_input: "needs-you",
+  completed: "done", complete: "done", success: "done", succeeded: "done", shipped: "done",
+  error: "failed", errored: "failed",
+  cancelled: "stopped", canceled: "stopped", aborted: "stopped",
+};
+
+/** Any status string as a `RunStatus`; a value nothing names reads as Unknown, never as a guess. */
+export function runStatus(status: string): RunStatus {
+  const key = status.trim().toLowerCase();
+  if (Object.hasOwn(META, key)) return key as RunStatus;
+  return Object.hasOwn(ALIASES, key) ? ALIASES[key] : "unknown";
+}
+
+/** The label, glyph and colour token for a status, in every surface. */
+export function statusMeta(status: RunStatus | (string & {})): StatusMeta {
+  return META[runStatus(status)];
+}
+
+export interface RunStatusIconProps extends Omit<LucideProps, "ref"> {
+  status: RunStatus | (string & {});
+}
+
+/**
+ * A status glyph on the icon grid, in its token colour and labelled with its
+ * word. Pass `aria-hidden` where the label is already printed beside it.
+ * Running breathes on `--motion-ambient`, the page's one loop period; the
+ * breathe is opacity only, so it is the essential motion reduced motion keeps.
+ */
+export function RunStatusIcon({ status, className, style, ...props }: RunStatusIconProps) {
+  const key = runStatus(status);
+  const { label, icon: Icon, token } = META[key];
+  const running = key === "running";
+  return (
+    <Icon
+      role="img"
+      aria-label={label}
+      size={16}
+      strokeWidth={1.75}
+      data-run-status={key}
+      data-motion={running ? "essential" : undefined}
+      className={cn("shrink-0", running && "animate-[tangle-breathe_var(--motion-ambient)_infinite]", className)}
+      style={{ color: `var(${token})`, ...style }}
+      {...props}
+    />
+  );
+}

package/src/styles/presentation.css

@@ -28,7 +28,7 @@
 .tangle-reading-header { grid-column: 1 / -1; min-width: 0; }
 /* PageShell measure="settings". The frame is the query container, so the layout follows the content area's width, not the viewport's.
    Below 60rem the navigation is a sticky tab strip whose track is the divider; from 60rem it is a sticky 13rem column beside a 48rem article.
-   Without a nav the page is the 48rem column alone. */
+   Without a nav the page is the 48rem column alone. A host whose page scrolls under its own sticky header sets --tangle-settings-sticky-top. */
 .tangle-settings-frame { container: tangle-settings / inline-size; width: 100%; min-width: 0; }
 .tangle-reading-shell[data-measure="settings"] { --tangle-settings-gutter: 1.5rem; grid-template-columns: minmax(0,1fr); gap: 0; max-width: calc(13rem + 2.5rem + 48rem + 4rem); padding: 1.5rem var(--tangle-settings-gutter) 3rem; }
 /* Without a nav the shell is the column and its gutters, so the centred shell centres the column and its header. */
@@ -37,7 +37,7 @@
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-header > * { margin-bottom: 0; }
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-outline { display: none; }
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-article { max-width: 48rem; display: flex; flex-direction: column; gap: 1.5rem; }
-.tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav { position: sticky; top: 0; z-index: 3; display: flex; align-items: flex-end; gap: 0.25rem; height: var(--shell-header-height); max-height: none; margin: 0 calc(-1 * var(--tangle-settings-gutter)) 1.25rem; padding: 0 var(--tangle-settings-gutter); overflow-x: auto; overflow-y: hidden; overscroll-behavior-x: contain; scrollbar-width: none; background: hsl(var(--background)); box-shadow: inset 0 -1px 0 hsl(var(--border)); }
+.tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav { position: sticky; top: var(--tangle-settings-sticky-top, 0px); z-index: 3; display: flex; align-items: flex-end; gap: 0.25rem; height: var(--shell-header-height); max-height: none; margin: 0 calc(-1 * var(--tangle-settings-gutter)) 1.25rem; padding: 0 var(--tangle-settings-gutter); overflow-x: auto; overflow-y: hidden; overscroll-behavior-x: contain; scrollbar-width: none; background: hsl(var(--background)); box-shadow: inset 0 -1px 0 hsl(var(--border)); }
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav::-webkit-scrollbar { display: none; }
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav > :is(ul, ol) { display: flex; flex: none; align-items: flex-end; gap: 0.25rem; margin: 0; padding: 0; list-style: none; }
 .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav a { flex: none; display: flex; align-items: center; gap: 0.5rem; min-height: var(--control-height-lg, 2.75rem); padding: 0 0.75rem; color: hsl(var(--muted-foreground)); font-size: var(--font-size-label, 0.875rem); font-weight: 500; line-height: 1.25rem; white-space: nowrap; text-decoration: none; transition: color var(--motion-control), background-color var(--motion-control), box-shadow var(--motion-control); }
@@ -55,7 +55,7 @@
   .tangle-reading-shell[data-measure="settings"] { --tangle-settings-gutter: 2rem; grid-template-columns: minmax(0,48rem); column-gap: 2.5rem; align-items: start; padding: 2rem; }
   .tangle-reading-shell[data-measure="settings"]:has(> .tangle-reading-nav) { grid-template-columns: 13rem minmax(0,48rem); }
   .tangle-reading-shell[data-measure="settings"] > .tangle-reading-header { margin-bottom: 1.75rem; }
-  .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav { top: 2rem; flex-direction: column; align-items: stretch; gap: 2px; height: auto; margin: 0; padding: 0; overflow: visible; background: none; box-shadow: none; }
+  .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav { top: calc(var(--tangle-settings-sticky-top, 0px) + 2rem); flex-direction: column; align-items: stretch; gap: 2px; height: auto; margin: 0; padding: 0; overflow: visible; background: none; box-shadow: none; }
   .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav > :is(ul, ol) { flex-direction: column; align-items: stretch; gap: 2px; }
   .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav a { min-height: var(--control-height, 2.25rem); gap: 0.625rem; padding: 0 0.625rem; border-radius: var(--radius-md); }
   .tangle-reading-shell[data-measure="settings"] > .tangle-reading-nav a > svg { display: block; flex: none; width: 1rem; height: 1rem; }