@tangle-network/ui 11.48.0 → 11.50.1

package/src/chat/agent-timeline.tsx

@@ -2,7 +2,6 @@ import { TRANSCRIPT_TEXT } from "./transcript-text";
 import { useState, type KeyboardEvent, type ReactNode } from "react";
 import {
   AlertTriangle,
-  CheckCircle2,
   CircleDot,
   FileText,
   Info,
@@ -16,6 +15,7 @@ import { Markdown } from "../markdown/markdown";
 import { ThinkingIndicator } from "./thinking-indicator";
 import { type ToolCallData } from "../run/tool-call-feed";
 import { ToolCallGroup, ToolCallStep } from "../run/tool-call-step";
+import { statusMeta } from "../run/status-meta";
 import type { ChatAuthor } from "../types/message";
 import type { ToolPart } from "../types/parts";
 
@@ -132,7 +132,7 @@ const TONE_STYLES: Record<AgentTimelineTone, { card: string; text: string; suppo
     card: "border-[var(--surface-success-border)] bg-[var(--surface-success-bg)]",
     text: "text-[var(--surface-success-text)]",
     supportingText: "text-[var(--surface-success-text)]",
-    icon: CheckCircle2,
+    icon: statusMeta("done").icon,
   },
   warning: {
     card: "border-[var(--surface-warning-border)] bg-[var(--surface-warning-bg)]",
@@ -144,7 +144,8 @@ const TONE_STYLES: Record<AgentTimelineTone, { card: string; text: string; suppo
     card: "border-[var(--surface-danger-border)] bg-[var(--surface-danger-bg)]",
     text: "text-[var(--surface-danger-text)]",
     supportingText: "text-[var(--surface-danger-text)]",
-    icon: AlertTriangle,
+    // Failed is always the failed glyph; the triangle is for warnings.
+    icon: statusMeta("failed").icon,
   },
 };
 

package/src/chat/speaker.test.tsx

@@ -52,6 +52,7 @@ describe("SpeakerHeader", () => {
     expect(screen.getByText("@writer")).toBeInTheDocument()
     expect(screen.getByText("Answering")).toBeInTheDocument()
     expect(container.querySelector("[data-speaker-state]")?.getAttribute("data-speaker-state")).toBe("answering")
+    expect(container.querySelector("[data-run-status]")?.getAttribute("data-run-status")).toBe("running")
   })
 
   it("says nothing more once the responder has ended, even while others answer", () => {
@@ -62,8 +63,9 @@ describe("SpeakerHeader", () => {
   })
 
   it("shows a failed responder as failed while the turn still runs", () => {
-    render(<SpeakerHeader speaker={{ id: "ap_research", name: "Research Lead", state: "failed" }} live />)
+    const { container } = render(<SpeakerHeader speaker={{ id: "ap_research", name: "Research Lead", state: "failed" }} live />)
     expect(screen.getByText("Failed")).toBeInTheDocument()
+    expect(container.querySelector("[data-run-status]")?.getAttribute("data-run-status")).toBe("failed")
     expect(screen.queryByText("Answering")).not.toBeInTheDocument()
   })
 

package/src/chat/speaker.tsx

@@ -1,5 +1,5 @@
 import type { HTMLAttributes } from "react";
-import { StatusPill } from "../primitives/status-pill";
+import { RunStatusIcon } from "../run/status-meta";
 import { MessageAuthor } from "./message-author";
 
 /** Where one responder is in its answer. */
@@ -79,9 +79,9 @@ export interface SpeakerHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>,
  * gets, then the handle a person types to address the agent, then its state.
  *
  * The state comes from the speaker's own end state, else from `live`. An
- * answering responder shows the status grammar's open ring with the word, a
- * failed one its cross with the word, and a finished one nothing, as a settled
- * run row does. `data-speaker-state` carries all three.
+ * answering responder shows the running glyph with the word, a failed one the
+ * failed glyph with the word, both from `RunStatusIcon`, and a finished one
+ * nothing, as a settled run row does. `data-speaker-state` carries all three.
  */
 export function SpeakerHeader({ speaker, live = false, ...props }: SpeakerHeaderProps) {
   const state: SpeakerState = speaker.state ?? (live ? "answering" : "done");
@@ -92,19 +92,18 @@ export function SpeakerHeader({ speaker, live = false, ...props }: SpeakerHeader
       {...props}
     >
       {speaker.handle ? (
-        <span className="min-w-0 truncate text-muted-foreground text-sm" title={`@${speaker.handle}`}>
+        // A person reads the name first. The handle has no base width and grows only into the space
+        // the name and state leave, up to its own width, so it gives way before the name loses a pixel.
+        <span className="min-w-0 max-w-fit flex-1 truncate text-muted-foreground text-sm" title={`@${speaker.handle}`}>
           @{speaker.handle}
         </span>
       ) : null}
-      {state === "answering" ? (
-        <StatusPill tone="running" bare size="md" className="shrink-0 py-0">
-          Answering
-        </StatusPill>
-      ) : state === "failed" ? (
-        <StatusPill tone="danger" bare size="md" className="shrink-0 py-0">
-          Failed
-        </StatusPill>
-      ) : null}
+      {state === "done" ? null : (
+        <span className="inline-flex shrink-0 items-center gap-1.5 font-medium text-sm">
+          <RunStatusIcon status={state === "failed" ? "failed" : "running"} aria-hidden />
+          {state === "failed" ? "Failed" : "Answering"}
+        </span>
+      )}
     </MessageAuthor>
   );
 }

package/src/markdown/code-block.tsx

@@ -169,7 +169,8 @@ export const CopyButton = memo(({ text, label: actionLabel, copiedLabel="Copied"
         onClick={handleCopy}
         className={cn(
           codePresentation.copy,
-          actionLabel && "gap-2 px-3",
+          // The header's type, not the code font the block sets.
+          actionLabel && "gap-2 px-3 font-sans text-sm",
           focusRing,
           className,
         )}

package/src/markdown/markdown.stories.tsx

@@ -221,6 +221,17 @@ export const CodeBlockOnly: Story = {
   ),
 }
 
+export const CodeBlockLabelledCopy: Story = {
+  name: 'CodeBlock — labelled copy action',
+  render: () => (
+    <div className="w-full max-w-[680px] p-6 rounded-xl bg-card">
+      <CodeBlock code={`<script src="https://embed.tangle.tools/agent.js" data-agent="support"></script>`} language="html" label="HTML">
+        <CopyButton text={`<script src="https://embed.tangle.tools/agent.js" data-agent="support"></script>`} label="Copy embed code" />
+      </CodeBlock>
+    </div>
+  ),
+}
+
 export const CodeBlockNoLanguage: Story = {
   name: 'CodeBlock — no language',
   render: () => (

package/src/presentation.ts

@@ -110,6 +110,7 @@ export const metricPresentation = {
 } as const;
 
 export const metricLayouts = {
+  2: "grid-cols-1 sm:grid-cols-2 max-sm:[&>div+div]:border-t sm:[&>div:not(:nth-child(2n+1))]:border-l",
   3: "grid-cols-2 sm:grid-cols-3 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:[&>div:not(:nth-child(3n+1))]:border-l",
   4: "grid-cols-2 sm:grid-cols-4 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:[&>div:not(:nth-child(4n+1))]:border-l",
   5: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:max-lg:[&>div:not(:nth-child(3n+1))]:border-l lg:[&>div:not(:nth-child(5n+1))]:border-l",
@@ -180,6 +181,73 @@ export function bindDialog(dialog: HTMLDialogElement, trigger: HTMLElement): ()
   return () => {trigger.removeEventListener("click",show);dialog.removeEventListener("close",close);dialog.removeEventListener("click",click);dialog.removeEventListener("keydown",key);};
 }
 
+/**
+ * The settings section links of PageShell `measure="settings"`, for any host: PageShell binds its
+ * nav with it, and a server-rendered host binds the same markup. On the tab strip the current link
+ * (`aria-current="page"`) is centred by scrolling the strip only, never the page. It centres when
+ * the current link changes or first becomes reachable, never on scroll or on a change that keeps
+ * the same current link, so a user who scrolled to the first or last section stays there; resize
+ * and font swaps re-centre only until the user first scrolls the strip. A plain click on a link to
+ * another document makes it current at once, while that document loads, and a page restored from
+ * the back-forward cache shows the link it left.
+ */
+export function bindSettingsNav(nav: HTMLElement): () => void {
+  let centredKey: string | null = null;
+  let userScrolled = false;
+  let left: { from: Element | null; to: Element } | null = null;
+  const current = () => nav.querySelector<HTMLElement>('[aria-current="page"]');
+  const reveal = (layoutOnly: boolean) => {
+    const link = current();
+    if (nav.scrollWidth <= nav.clientWidth || !link) return;
+    const key = link.getAttribute("href") ?? link.textContent ?? "";
+    if (key !== centredKey) userScrolled = false;
+    else if (!layoutOnly || userScrolled) return;
+    centredKey = key;
+    const strip = nav.getBoundingClientRect(), box = link.getBoundingClientRect();
+    nav.scrollLeft += box.left + box.width / 2 - (strip.left + strip.width / 2);
+  };
+  const mark = (from: Element | null, to: Element | null) => { from?.removeAttribute("aria-current"); to?.setAttribute("aria-current", "page"); };
+  // On window, so it runs after the page's own handlers: a client router that took the click
+  // (preventDefault) sets the current link itself.
+  const click = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const link = event.target instanceof Element ? event.target.closest("a[href]") : null;
+    if (!(link instanceof HTMLAnchorElement) || !nav.contains(link) || (link.target && link.target !== "_self") || link.hasAttribute("download")) return;
+    if (link.origin !== location.origin || link.pathname + link.search === location.pathname + location.search) return;
+    const from = current();
+    if (from === link) return;
+    left = { from, to: link };
+    mark(from, link);
+  };
+  const restore = (event: PageTransitionEvent) => {
+    if (!event.persisted || !left) return;
+    mark(left.to, left.from);
+    left = null;
+  };
+  const onUser = () => { userScrolled = true; };
+  const userEvents = ["pointerdown", "touchstart", "wheel", "keydown"] as const;
+  for (const type of userEvents) nav.addEventListener(type, onUser, { passive: true });
+  window.addEventListener("click", click);
+  window.addEventListener("pageshow", restore);
+  let live = true;
+  reveal(false);
+  // A web font swap widens the tabs without resizing the strip.
+  void document.fonts?.ready.then(() => { if (live) reveal(true); });
+  const resize = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => reveal(true));
+  resize?.observe(nav);
+  // Links a host replaces (sections loaded later, a new aria-current) can change the current link.
+  const links = new MutationObserver(() => reveal(false));
+  links.observe(nav, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ["aria-current"] });
+  return () => {
+    live = false;
+    resize?.disconnect();
+    links.disconnect();
+    for (const type of userEvents) nav.removeEventListener(type, onUser);
+    window.removeEventListener("click", click);
+    window.removeEventListener("pageshow", restore);
+  };
+}
+
 export const labelVariants = cva(
   "font-medium text-[length:var(--font-size-label,0.875rem)] leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
 );

package/src/primitives/index.ts

@@ -203,13 +203,14 @@ export type { PageShellProps } from "./page-shell";
 export { Field, fieldMessageId } from "./field";
 export type { FieldProps } from "./field";
 
-export { SettingsList, SettingsListItem, SettingsRow, SettingsSection } from "./settings";
+export { SettingsList, SettingsListItem, SettingsNote, SettingsRow, SettingsSection } from "./settings";
 export type {
   SettingsListAction,
   SettingsListColumns,
   SettingsListItemProps,
   SettingsListMenuItem,
   SettingsListProps,
+  SettingsNoteProps,
   SettingsRowLayout,
   SettingsRowProps,
   SettingsSectionProps,

package/src/primitives/metric-strip.tsx

@@ -8,8 +8,8 @@ export interface MetricStripProps
   extends React.HTMLAttributes<HTMLDListElement> {
   children: React.ReactNode;
   /** Desktop columns. Default retains the existing two / sm:four layout.
-   * Five and six use three columns between sm and lg. Never inferred from data. */
-  columns?: 3 | 4 | 5 | 6;
+   * Two stack below sm; five and six use three columns between sm and lg. Never inferred from data. */
+  columns?: 2 | 3 | 4 | 5 | 6;
 }
 
 const MetricStrip = React.forwardRef<HTMLDListElement, MetricStripProps>(

package/src/primitives/page-shell.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 import type { ReactNode } from "react";
 import { cn } from "../lib/utils";
+import { bindSettingsNav } from "../presentation";
 
 export interface PageShellProps {
   children?: ReactNode;
@@ -17,9 +18,12 @@ export interface PageShellProps {
    * column. `settings` is a 48rem column of cards whose navigation is a sticky
    * 13rem column of rows when its frame is at least 60rem wide, and a sticky
    * 56px tab strip under the header below that; the current link
-   * (`aria-current="page"`) is centred by scrolling the strip only. Put
-   * links (or a list of links) in `navigation`; an `svg` in a link shows only
-   * in the column, and an element with `data-count` sits at its end.
+   * (`aria-current="page"`) is centred by scrolling the strip only
+   * ({@link bindSettingsNav}). Put links (or a list of links) in `navigation`;
+   * an `svg` in a link shows only in the column, and an element with
+   * `data-count` sits at its end. A host whose page scrolls under its own
+   * sticky header sets `--tangle-settings-sticky-top` on the frame or an
+   * ancestor, such as `var(--shell-header-height)`, and the nav sticks below it.
    */
   measure?: "reading" | "settings";
   navigationLabel?: string;
@@ -27,60 +31,6 @@ export interface PageShellProps {
   className?: string;
 }
 
-/**
- * Centre the current link of a horizontally scrolling nav, so the links on
- * both sides show that the strip scrolls. It moves the strip, never the page.
- * It centres when the current link changes (or first becomes reachable), never
- * on scroll, arrow taps or re-renders that keep the same current link, so a
- * user who scrolls to the first or last section stays there. Resize and font
- * swaps re-centre only until the user first scrolls the strip.
- */
-function useCurrentLinkInView(ref: React.RefObject<HTMLElement | null>, enabled: boolean) {
-  React.useEffect(() => {
-    const nav = ref.current;
-    if (!enabled || !nav) return;
-    let centredKey: string | null = null;
-    let userScrolled = false;
-    const reveal = (layoutOnly: boolean) => {
-      if (nav.scrollWidth <= nav.clientWidth) return;
-      const current = nav.querySelector<HTMLElement>('[aria-current="page"]');
-      if (!current) return;
-      const key = current.getAttribute("href") ?? current.textContent ?? "";
-      if (key !== centredKey) userScrolled = false;
-      else if (!layoutOnly || userScrolled) return;
-      centredKey = key;
-      const strip = nav.getBoundingClientRect();
-      const link = current.getBoundingClientRect();
-      nav.scrollLeft += link.left + link.width / 2 - (strip.left + strip.width / 2);
-    };
-    const onUser = () => { userScrolled = true; };
-    nav.addEventListener("pointerdown", onUser, { passive: true });
-    nav.addEventListener("touchstart", onUser, { passive: true });
-    nav.addEventListener("wheel", onUser, { passive: true });
-    nav.addEventListener("keydown", onUser);
-    let live = true;
-    reveal(false);
-    // A web font swap widens the tabs without resizing the strip, so the
-    // resize observer alone would leave the current tab where it was.
-    void document.fonts?.ready.then(() => { if (live) reveal(true); });
-    const resize = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => reveal(true));
-    resize?.observe(nav);
-    // Links that a caller replaces (sections loaded later, a new aria-current)
-    // can change the current link; the same current link is left where it is.
-    const links = new MutationObserver(() => reveal(false));
-    links.observe(nav, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ["aria-current"] });
-    return () => {
-      live = false;
-      resize?.disconnect();
-      links.disconnect();
-      nav.removeEventListener("pointerdown", onUser);
-      nav.removeEventListener("touchstart", onUser);
-      nav.removeEventListener("wheel", onUser);
-      nav.removeEventListener("keydown", onUser);
-    };
-  }, [ref, enabled]);
-}
-
 /**
  * Ported from sandbox-ui/src/primitives/page-shell.tsx. An optional bounded
  * width, gutter and vertical rhythm, not an application shell or a card grid.
@@ -93,7 +43,8 @@ function useCurrentLinkInView(ref: React.RefObject<HTMLElement | null>, enabled:
 export function PageShell({ children, className, navigation, article, outline, header, measure = "reading", navigationLabel = "Sections", outlineLabel = "On this page" }: PageShellProps) {
   const navRef = React.useRef<HTMLElement>(null);
   const settings = measure === "settings";
-  useCurrentLinkInView(navRef, settings && Boolean(navigation));
+  const hasNavigation = Boolean(navigation);
+  React.useEffect(() => (settings && hasNavigation && navRef.current ? bindSettingsNav(navRef.current) : undefined), [settings, hasNavigation]);
   if (navigation || article || outline || header || settings) {
     const shell = <div className={cn("tangle-reading-shell", !settings && className)} data-measure={settings ? "settings" : undefined}>
       {header && <div className="tangle-reading-header">{header}</div>}

package/src/primitives/progress.stories.tsx

@@ -38,6 +38,16 @@ export const SandboxWithValue: Story = {
   ),
 }
 
+export const Tones: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      {(['neutral', 'success', 'warning', 'danger'] as const).map((tone) => (
+        <Progress key={tone} value={tone === 'danger' ? 100 : 70} tone={tone} aria-label={`${tone} reading`} />
+      ))}
+    </div>
+  ),
+}
+
 export const Empty: Story = {
   render: () => <Progress value={0} className="w-80" />,
 }

package/src/primitives/progress.tsx

@@ -1,16 +1,27 @@
 import * as ProgressPrimitive from "@radix-ui/react-progress";
 import * as React from "react";
 import { cn } from "../lib/utils";
+import type { StatusTone } from "./status-pill";
+
+// A status ink is also its fill (Brand tokens), so a toned bar matches the state text beside it.
+const TONE_FILL = {
+  neutral: "bg-[var(--surface-neutral-text)]",
+  success: "bg-[var(--surface-success-text)]",
+  warning: "bg-[var(--surface-warning-text)]",
+  danger: "bg-[var(--surface-danger-text)]",
+} satisfies Partial<Record<StatusTone, string>>;
 
 const Progress = React.forwardRef<
   React.ElementRef<typeof ProgressPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root> & {
     variant?: "default" | "sandbox";
+    /** A state the reading is in, such as `danger` at a limit; it replaces the variant's fill. */
+    tone?: keyof typeof TONE_FILL;
     showValue?: boolean;
   }
 >(
   (
-    { className, value, variant = "default", showValue = false, ...props },
+    { className, value, variant = "default", tone, showValue = false, ...props },
     ref,
   ) => {
     const indicatorVariants = {
@@ -31,7 +42,7 @@ const Progress = React.forwardRef<
           <ProgressPrimitive.Indicator
             className={cn(
               "h-full w-full flex-1 transition-all duration-300 ease-out",
-              indicatorVariants[variant],
+              tone ? TONE_FILL[tone] : indicatorVariants[variant],
             )}
             style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
           />

package/src/primitives/settings.stories.tsx

@@ -1,17 +1,20 @@
 import { Bell, Bot, Check, CreditCard, Inbox, Loader2, Settings, Users, Workflow } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Avatar, AvatarFallback } from "./avatar";
 import { Button } from "./button";
 import { Card } from "./card";
 import { Field, fieldMessageId } from "./field";
 import { Input, Textarea } from "./input";
+import { Metric, MetricStrip } from "./metric-strip";
 import { PageHeader } from "./page-header";
 import { PageShell } from "./page-shell";
 import { SegmentedControl } from "./segmented-control";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select";
-import { SettingsList, SettingsListItem, SettingsRow, SettingsSection } from "./settings";
+import { SettingsList, SettingsListItem, SettingsNote, SettingsRow, SettingsSection } from "./settings";
+import type { StatusTone } from "./status-pill";
 import { Switch } from "./switch";
+import { bindSettingsNav } from "../presentation";
 
 /** Example data only: no routing, persistence or fetching. Every state is drawn at once so one screenshot shows them all. */
 
@@ -35,6 +38,8 @@ function Saved() {
 
 interface Automation { name: string; meta: string; state: string; verb: string; ownerOnly?: boolean; error?: string }
 
+const AUTOMATION_TONE: Record<string, StatusTone> = { Active: "success", Paused: "neutral", "Couldn't start": "danger" };
+
 const automations: Automation[] = [
   { name: "Weekly competitor scan", meta: "Mondays at 09:00", state: "Active", verb: "Pause" },
   { name: "Inbound lead triage", meta: "When a signed webhook arrives", state: "Paused", verb: "Resume", ownerOnly: true },
@@ -152,7 +157,8 @@ function SettingsPage({ sectionsLoadLater = false, withoutNavigation = false, cl
                 key={job.name}
                 title={<a href={`#${job.name}`}>{job.name}</a>}
                 meta={job.meta}
-                status={job.error ? <span className="font-medium text-[var(--surface-danger-text)]">{job.state}</span> : job.state}
+                status={job.state}
+                tone={AUTOMATION_TONE[job.state]}
                 error={job.error}
                 action={{
                   label: job.verb,
@@ -277,6 +283,85 @@ function SettingsValuesExample() {
   );
 }
 
+const webhooks: Array<{ url: string; events: string[]; state: string; tone: StatusTone }> = [
+  { url: "https://hooks.fieldnote-analytics.example/intelligence/v1/trace-events", events: ["trace.completed", "eval.regressed", "budget.exceeded"], state: "Active", tone: "success" },
+  { url: "https://ops.fieldnote.example/alerts/webhooks/intelligence_regressions", events: ["eval.regressed"], state: "Inactive", tone: "neutral" },
+  { url: "https://n8n.fieldnote.example/webhook/7f3c2a91-5d4e-4b8a-9c61-2e0f8d7a4b13", events: ["budget.exceeded", "alert.triggered"], state: "Failing", tone: "danger" },
+];
+
+const alertRules: Array<{ name: string; rule: string; severity: string; tone: StatusTone }> = [
+  { name: "Error rate", rule: "Above 5% for 10 minutes", severity: "Critical", tone: "danger" },
+  { name: "p95 latency", rule: "Above 4 s for 15 minutes", severity: "Warning", tone: "warning" },
+  { name: "Daily spend", rule: "Above $40 in a day", severity: "Notice", tone: "neutral" },
+];
+
+/** Notes (figure, empty, loading, notice, refusal), toned list states, and long URLs and event names in narrow columns. */
+function NotesAndTonesExample() {
+  return (
+    <div className="mx-auto max-w-3xl space-y-6 p-6 max-sm:p-4">
+      <SettingsSection id="webhooks" title="Webhooks" description="Signed POSTs when traces, evals or budgets change.">
+        <SettingsNote>
+          <MetricStrip columns={2} aria-label="Last 7 days">
+            <Metric label="Deliveries" value="1,284" />
+            <Metric label="Failed" value="3" />
+          </MetricStrip>
+        </SettingsNote>
+        <SettingsList aria-label="Webhook endpoints" columns={{ status: "7rem", action: "8rem", menu: "36px" }}>
+          {webhooks.map((hook) => (
+            <SettingsListItem
+              key={hook.url}
+              title={<a href={`#${hook.state}`}>{hook.url}</a>}
+              meta={hook.events.join(", ")}
+              status={hook.state}
+              tone={hook.tone}
+              action={{ label: "Send test", onSelect: () => undefined }}
+              menu={[{ label: "Delete…", tone: "danger", onSelect: () => undefined }]}
+            />
+          ))}
+        </SettingsList>
+        <SettingsNote tone="warning" role="status">One endpoint failed its last three deliveries. It pauses after five.</SettingsNote>
+      </SettingsSection>
+      <SettingsSection id="alert-rules" title="Alert rules">
+        <SettingsList aria-label="Alert rules" columns={{ status: "7rem", menu: "36px" }}>
+          {alertRules.map((rule) => (
+            <SettingsListItem key={rule.name} title={rule.name} meta={rule.rule} status={rule.severity} tone={rule.tone} menu={[{ label: "Delete…", tone: "danger", onSelect: () => undefined }]} />
+          ))}
+        </SettingsList>
+      </SettingsSection>
+      <SettingsSection id="saved-versions" title="Saved versions">
+        <SettingsNote tone="muted">No saved versions yet.</SettingsNote>
+        <SettingsNote tone="muted" role="status"><span className="inline-flex items-center gap-1.5"><Loader2 aria-hidden="true" className="size-4 animate-spin motion-reduce:animate-none" />Loading saved versions…</span></SettingsNote>
+        <SettingsNote tone="danger" role="alert">Couldn't load saved versions. The workspace didn't answer; nothing changed.</SettingsNote>
+      </SettingsSection>
+    </div>
+  );
+}
+
+const HOST_SECTIONS = [["account", "Account"], ["keys", "API keys"], ["usage", "Usage"], ["billing", "Billing"], ["webhooks", "Webhooks"], ["team", "Team"]] as const;
+
+/** What a server-rendered host such as tangle-router writes: PageShell's settings markup, with no React inside it. */
+const HOST_MARKUP = `<div class="tangle-settings-frame" style="--tangle-settings-sticky-top: var(--shell-header-height)">
+<div class="tangle-reading-shell" data-measure="settings">
+<div class="tangle-reading-header"><h1 class="tangle-heading" data-variant="section">Settings</h1></div>
+<nav aria-label="Settings sections" class="tangle-reading-nav"><ul role="list">${HOST_SECTIONS.map(([id, label]) => `<li><a href="/settings-doc/${id}"${id === "usage" ? ' aria-current="page"' : ""}>${label}</a></li>`).join("")}</ul></nav>
+<article class="tangle-reading-article">${["Usage", "Limits", "Sources"].map((name) => `<section role="region" aria-label="${name}" data-slot="card" class="rounded-[var(--radius-lg)] border border-border bg-card p-5" style="min-height: 28rem"><h2 class="font-semibold">${name}</h2></section>`).join("")}</article>
+</div></div>`;
+
+/** A host whose document scrolls under its own sticky header, with server markup bound by bindSettingsNav. */
+function ServerRenderedHostExample() {
+  const root = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const nav = root.current?.querySelector<HTMLElement>("nav");
+    return nav ? bindSettingsNav(nav) : undefined;
+  }, []);
+  return (
+    <>
+      <header className="sticky top-0 z-10 flex h-[var(--shell-header-height)] items-center border-b border-border bg-background px-6 font-medium text-sm">Host header</header>
+      <div ref={root} dangerouslySetInnerHTML={{ __html: HOST_MARKUP }} />
+    </>
+  );
+}
+
 const meta = {
   title: "Primitives/Settings",
   component: SettingsSection,
@@ -302,3 +387,9 @@ export const Fields: Story = { render: () => <FieldsExample /> };
 
 /** Values preserve ReactNode content and coexist with controls; only value rows stack in a narrow compact layout. */
 export const Values: Story = { render: () => <SettingsValuesExample /> };
+
+/** Every line that is not a row, list states in their tone, and long URLs and event names wrapping whole at 390. */
+export const NotesAndTones: Story = { render: () => <NotesAndTonesExample /> };
+
+/** tangle-router's case: server-rendered settings markup under a sticky host header, bound with bindSettingsNav. */
+export const ServerRenderedHost: Story = { render: () => <ServerRenderedHostExample /> };