@tangle-network/ui 11.35.0 → 11.37.0

package/src/markdown/code-block.tsx

@@ -1,151 +1,27 @@
 import {
   memo,
-  useCallback,
+  useId,
   useEffect,
   useRef,
   useState,
   type CSSProperties,
+  type ButtonHTMLAttributes,
+  type MouseEvent,
   type HTMLAttributes,
   type ReactNode,
 } from "react";
-import type { HighlighterCore, LanguageRegistration, ThemedToken } from "shiki/core";
+import type { ThemedToken } from "shiki/core";
 import { Check, Copy, FileCode2 } from "lucide-react";
 import { focusRing, focusRingInset } from "../lib/focus";
 import { cn } from "../lib/utils";
+import { SYNTAX, LANGUAGE_NAMES, PLAIN_TEXT, codeBlockGrammar, tokenize, tokenStyle, codePreStyle, codeTextStyle, codePresentation, createCopyFeedback, bindCodeTabs, apiMetadataText, type CopyFeedback, type CodeExample, type ApiMetadata } from "../lib/code-presentation";
+export { codeBlockGrammar } from "../lib/code-presentation";
 
-// Leave variables unresolved: the browser resolves them on each token span,
-// including nested themes, inline overrides and CSS/media changes. No document
-// sampling, observers, layout reads or React re-render are needed to recolor code.
-const SYNTAX = {
-  comment: "var(--syntax-comment, currentColor)",
-  keyword: "var(--syntax-keyword, currentColor)",
-  string: "var(--syntax-string, currentColor)",
-  function: "var(--syntax-function, currentColor)",
-  number: "var(--syntax-number, currentColor)",
-  variable: "var(--syntax-variable, currentColor)",
-  foreground: "var(--syntax-foreground, currentColor)",
-} as const;
-
-const SHIKI_THEME = "tangle-syntax";
-// Shiki's CSS-variables theme names token roles; each maps onto a Brand syntax token.
-const BRAND_COLOR_FOR_SHIKI: Record<string, string> = {
-  "var(--shiki-foreground)": SYNTAX.foreground,
-  "var(--shiki-token-comment)": SYNTAX.comment,
-  "var(--shiki-token-keyword)": SYNTAX.keyword,
-  "var(--shiki-token-string)": SYNTAX.string,
-  "var(--shiki-token-string-expression)": SYNTAX.string,
-  "var(--shiki-token-function)": SYNTAX.function,
-  "var(--shiki-token-constant)": SYNTAX.number,
-  "var(--shiki-token-link)": SYNTAX.number,
-  "var(--shiki-token-parameter)": SYNTAX.variable,
-  "var(--shiki-token-punctuation)": SYNTAX.foreground,
-};
-
-type GrammarModule = { default: LanguageRegistration[] };
-const GRAMMARS: Record<string, () => Promise<GrammarModule>> = {
-  typescript: () => import("shiki/langs/typescript.mjs"),
-  tsx: () => import("shiki/langs/tsx.mjs"),
-  javascript: () => import("shiki/langs/javascript.mjs"),
-  jsx: () => import("shiki/langs/jsx.mjs"),
-  json: () => import("shiki/langs/json.mjs"),
-  jsonc: () => import("shiki/langs/jsonc.mjs"),
-  bash: () => import("shiki/langs/bash.mjs"),
-  python: () => import("shiki/langs/python.mjs"),
-  html: () => import("shiki/langs/html.mjs"),
-  css: () => import("shiki/langs/css.mjs"),
-  scss: () => import("shiki/langs/scss.mjs"),
-  markdown: () => import("shiki/langs/markdown.mjs"),
-  mdx: () => import("shiki/langs/mdx.mjs"),
-  yaml: () => import("shiki/langs/yaml.mjs"),
-  toml: () => import("shiki/langs/toml.mjs"),
-  sql: () => import("shiki/langs/sql.mjs"),
-  diff: () => import("shiki/langs/diff.mjs"),
-  go: () => import("shiki/langs/go.mjs"),
-  rust: () => import("shiki/langs/rust.mjs"),
-  solidity: () => import("shiki/langs/solidity.mjs"),
-  ruby: () => import("shiki/langs/ruby.mjs"),
-  java: () => import("shiki/langs/java.mjs"),
-  kotlin: () => import("shiki/langs/kotlin.mjs"),
-  swift: () => import("shiki/langs/swift.mjs"),
-  php: () => import("shiki/langs/php.mjs"),
-  c: () => import("shiki/langs/c.mjs"),
-  cpp: () => import("shiki/langs/cpp.mjs"),
-  csharp: () => import("shiki/langs/csharp.mjs"),
-  graphql: () => import("shiki/langs/graphql.mjs"),
-  xml: () => import("shiki/langs/xml.mjs"),
-  dockerfile: () => import("shiki/langs/dockerfile.mjs"),
-};
-
-const LANGUAGE_ALIASES: Record<string, string> = {
-  ts: "typescript", mts: "typescript", cts: "typescript", js: "javascript", mjs: "javascript",
-  cjs: "javascript", node: "javascript", sh: "bash", shell: "bash", zsh: "bash", console: "bash",
-  shellscript: "bash", py: "python", python3: "python", yml: "yaml", md: "markdown", rs: "rust",
-  sol: "solidity", rb: "ruby", kt: "kotlin", cs: "csharp", "c#": "csharp", "c++": "cpp",
-  gql: "graphql", svg: "xml", docker: "dockerfile", patch: "diff", htm: "html",
-};
-
-const LANGUAGE_NAMES: Record<string, string> = {
-  typescript: "TypeScript", tsx: "TSX", javascript: "JavaScript", jsx: "JSX", json: "JSON",
-  jsonc: "JSONC", bash: "Bash", python: "Python", html: "HTML", css: "CSS", scss: "SCSS",
-  markdown: "Markdown", mdx: "MDX", yaml: "YAML", toml: "TOML", sql: "SQL", diff: "Diff",
-  go: "Go", rust: "Rust", solidity: "Solidity", ruby: "Ruby", java: "Java", kotlin: "Kotlin",
-  swift: "Swift", php: "PHP", c: "C", cpp: "C++", csharp: "C#", graphql: "GraphQL", xml: "XML",
-  dockerfile: "Dockerfile",
-};
-
-/** The Shiki grammar for a fence language, or undefined for plain text. */
-const PLAIN_TEXT = new Set(["text", "txt", "plain", "plaintext"]);
-
-export function codeBlockGrammar(language: string | undefined): string | undefined {
-  if (!language) return undefined;
-  const id = language.toLowerCase();
-  const resolved = LANGUAGE_ALIASES[id] ?? id;
-  return GRAMMARS[resolved] ? resolved : undefined;
-}
-
-let highlighterPromise: Promise<HighlighterCore> | undefined;
-const grammarLoads = new Map<string, Promise<void>>();
-
-function loadHighlighter(): Promise<HighlighterCore> {
-  // The JavaScript regex engine needs no WebAssembly, so it runs under a strict CSP.
-  return highlighterPromise ??= Promise.all([import("shiki/core"), import("shiki/engine/javascript")])
-    .then(([core, engine]) => core.createHighlighterCore({
-      themes: [core.createCssVariablesTheme({ name: SHIKI_THEME, variablePrefix: "--shiki-", fontStyle: true })],
-      langs: [],
-      engine: engine.createJavaScriptRegexEngine(),
-    }))
-    .catch((error: unknown) => {
-      highlighterPromise = undefined;
-      throw error;
-    });
-}
-
-async function tokenize(code: string, grammar: string): Promise<ThemedToken[][]> {
-  const highlighter = await loadHighlighter();
-  let load = grammarLoads.get(grammar);
-  if (!load) {
-    load = GRAMMARS[grammar]!().then((module) => highlighter.loadLanguage(module.default));
-    load.catch(() => grammarLoads.delete(grammar));
-    grammarLoads.set(grammar, load);
-  }
-  await load;
-  return highlighter.codeToTokensBase(code, { lang: grammar, theme: SHIKI_THEME });
-}
-
-function tokenStyle(token: ThemedToken): CSSProperties | undefined {
-  const color = token.color ? BRAND_COLOR_FOR_SHIKI[token.color] ?? SYNTAX.foreground : undefined;
-  const style = token.fontStyle ?? 0;
-  if (!color && !style) return undefined;
-  return {
-    ...(color ? { color } : {}),
-    ...(style & 1 ? { fontStyle: "italic" } : {}),
-    ...(style & 2 ? { fontWeight: "bold" } : {}),
-    ...(style & 4 ? { textDecoration: "underline" } : {}),
-  };
-}
 
 export interface CodeBlockProps extends HTMLAttributes<HTMLDivElement> {
   code: string;
+  examples?: readonly CodeExample[];
+  metadata?: ApiMetadata;
   language?: string;
   /**
    * Header text. Defaults to the language's name. Set this when the display
@@ -165,7 +41,13 @@ export interface CodeBlockProps extends HTMLAttributes<HTMLDivElement> {
  * plain code first (and on the server), then highlights once its grammar loads.
  */
 export const CodeBlock = memo(
-  ({ code, language, label, filename, showLineNumbers = false, light, className, children, ...props }: CodeBlockProps) => {
+  ({ code: defaultCode, language: defaultLanguage, label, filename: defaultFilename, examples, metadata, showLineNumbers = false, light, className, children, ...props }: CodeBlockProps) => {
+    const [selected,setSelected]=useState(0);
+    const tabId=useId(),tabList=useRef<HTMLDivElement>(null);
+    const selectedIndex=Math.min(selected,Math.max(0,(examples?.length??1)-1));
+    const example=examples?.[selectedIndex];
+    const code=example?.code??defaultCode,language=example?.language??defaultLanguage,filename=example?.filename??defaultFilename;
+    useEffect(()=>{if(tabList.current)return bindCodeTabs(tabList.current,setSelected);},[examples?.length]);
     const grammar = codeBlockGrammar(language);
     const [highlighted, setHighlighted] = useState<{ code: string; grammar: string; lines: ThemedToken[][] } | null>(null);
     useEffect(() => {
@@ -182,21 +64,8 @@ export const CodeBlock = memo(
     // A plain-text fence names no language worth showing; it keeps its copy control.
     const languageName = grammar ? LANGUAGE_NAMES[grammar] : PLAIN_TEXT.has(language?.toLowerCase() ?? "") ? undefined : language;
     const headerLabel = label ?? (filename ? undefined : languageName);
-    const hasHeader = Boolean(filename || headerLabel);
+    const hasHeader = Boolean(filename || headerLabel || metadata || examples?.length);
     const mode = light === undefined ? {} : { "data-theme": light ? "light" : "dark" };
-    const preStyle: CSSProperties = {
-      margin: 0,
-      padding: "var(--code-padding-y, 0.625rem) var(--code-padding-x, 0.75rem)",
-      background: "transparent",
-      color: SYNTAX.foreground,
-      fontSize: "var(--code-font-size, 0.8125rem)",
-      lineHeight: "var(--code-line-height, 1.5)",
-      overflowX: "auto",
-    };
-    const codeStyle: CSSProperties = {
-      fontFamily: "var(--font-mono, 'JetBrains Mono', ui-monospace, monospace)",
-      whiteSpace: "pre",
-    };
     const isHighlighted = Boolean(highlighted && highlighted.code === code && highlighted.grammar === grammar);
     const lines: Array<Array<{ content: string; style?: CSSProperties }>> = isHighlighted
       ? highlighted!.lines.map((line) => line.map((token) => ({ content: token.content, style: tokenStyle(token) })))
@@ -205,13 +74,14 @@ export const CodeBlock = memo(
 
     return (
       <div
-        className={cn("group relative overflow-hidden rounded-lg border font-mono", "bg-card border-border", className)}
+        className={cn(codePresentation.root, className)}
         data-highlighted={isHighlighted ? "true" : undefined}
         {...props}
         {...mode}
       >
         {hasHeader && (
-          <div className="flex items-center justify-between gap-3 border-b border-border px-3 py-1.5 bg-[var(--code-header-bg,hsl(var(--background)))]">
+          <div className={codePresentation.header}>
+            {metadata && <span className="tangle-api-meta">{apiMetadataText(metadata)}</span>}
             {filename ? (
               <span className="flex min-w-0 items-center gap-2 font-sans text-sm">
                 <FileCode2 aria-hidden className="size-4 shrink-0 text-muted-foreground" />
@@ -222,6 +92,7 @@ export const CodeBlock = memo(
               <span className="font-sans text-sm font-medium text-muted-foreground">{headerLabel}</span>
             )}
             {children}
+            {examples?.length ? <CopyButton text={code}/> : null}
           </div>
         )}
         {!hasHeader && children && (
@@ -229,6 +100,10 @@ export const CodeBlock = memo(
             {children}
           </div>
         )}
+        {examples && examples.length > 1 && <div role="tablist" aria-label="Code examples" ref={tabList} className={codePresentation.tabs}>
+          {examples.map((item,index)=><button key={index} id={`${tabId}-tab-${index}`} type="button" role="tab" className={codePresentation.tab} data-state={index===selectedIndex?"active":"inactive"} aria-selected={index===selectedIndex} tabIndex={index===selectedIndex?0:-1} aria-controls={`${tabId}-panel`}>{item.label}</button>)}
+        </div>}
+        <div id={`${tabId}-panel`} role={examples && examples.length > 1 ? "tabpanel" : undefined} aria-labelledby={examples && examples.length > 1 ? `${tabId}-tab-${selectedIndex}` : undefined}>
         {/* A long line scrolls the block sideways, which a keyboard reaches only
             if the block takes focus; a label on a bare <pre> is prohibited ARIA,
             so the block is a named region. Inset: the rounded card clips an outer ring. */}
@@ -237,9 +112,9 @@ export const CodeBlock = memo(
           role="region"
           aria-label={regionName ? `${regionName} code` : "Code"}
           className={focusRingInset}
-          style={preStyle}
+          style={codePreStyle}
         >
-          <code style={codeStyle}>
+          <code style={codeTextStyle}>
             {/* Plain code without line numbers stays one text node, as the server renders it. */}
             {!isHighlighted && !showLineNumbers ? code : lines.map((line, index) => (
               <span key={index}>
@@ -261,53 +136,46 @@ export const CodeBlock = memo(
             ))}
           </code>
         </pre>
+        </div>
       </div>
     );
   },
 );
 CodeBlock.displayName = "CodeBlock";
 
-/** Copy-to-clipboard button for use inside CodeBlock. */
-export const CopyButton = memo(({ text }: { text: string }) => {
-  const [copied, setCopied] = useState(false);
-  // Status text for the live region. Cleared before each attempt so a repeat
-  // copy or a failure is announced again.
-  const [status, setStatus] = useState("");
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  useEffect(() => {
-    return () => { if (timerRef.current) clearTimeout(timerRef.current); };
-  }, []);
-
-  const handleCopy = useCallback(async () => {
-    setStatus("");
-    if (timerRef.current) clearTimeout(timerRef.current);
-    try {
-      await navigator.clipboard.writeText(text);
-      setCopied(true);
-      setStatus("Copied to clipboard");
-    } catch (err) {
-      console.warn("Clipboard write failed:", err);
-      setCopied(false);
-      setStatus("Copy failed");
-    }
-    timerRef.current = setTimeout(() => {
-      setCopied(false);
-      setStatus("");
-    }, 2000);
-  }, [text]);
-
-  const label = copied ? "Copied" : "Copy to clipboard";
+export interface CopyButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>,"children"> {
+  text:string;
+  /** Supply for a visible action label; omitted preserves the icon-only control. */
+  label?:string;
+  copiedLabel?:string;
+  failedLabel?:string;
+}
+/** Copy-to-clipboard button for use inside CodeBlock or other exact-text actions. */
+export const CopyButton = memo(({ text, label: actionLabel, copiedLabel="Copied", failedLabel="Copy failed", className, onClick, ...props }: CopyButtonProps) => {
+  const [{copied,status,pending,loading,longRunning},setFeedback] = useState<CopyFeedback>({copied:false,status:"",pending:false});
+  const button=useRef<HTMLButtonElement>(null);
+  const feedback=useRef<ReturnType<typeof createCopyFeedback>|null>(null);
+  useEffect(()=>{const controller=createCopyFeedback(setFeedback,undefined,button.current??undefined);feedback.current=controller;return()=>controller.dispose();},[]);
+  const handleCopy=(event:MouseEvent<HTMLButtonElement>)=>{if(pending||props["aria-disabled"]===true||props["aria-disabled"]==="true")return;onClick?.(event);if(!event.defaultPrevented)void feedback.current?.copy(text);};
+
+  const label = copied ? copiedLabel : actionLabel && status === "Copy failed" ? failedLabel : actionLabel ?? "Copy to clipboard";
   return (
     <>
       <button
+        {...props}
+        ref={button}
+        data-copy-loading={!!loading}
         type="button"
         onClick={handleCopy}
         className={cn(
-          "flex items-center justify-center w-6 h-6 rounded-md bg-muted border border-border hover:border-[var(--border-strong)] transition-colors",
+          codePresentation.copy,
+          actionLabel && "gap-2 px-3",
           focusRing,
+          className,
         )}
-        aria-label={label}
+        aria-label={pending?"Copying to clipboard":label}
+        aria-busy={pending||props["aria-busy"]}
+        aria-disabled={pending||props["aria-disabled"]}
         title={label}
       >
         {copied ? (
@@ -315,9 +183,10 @@ export const CopyButton = memo(({ text }: { text: string }) => {
         ) : (
           <Copy aria-hidden="true" className="w-3.5 h-3.5 text-muted-foreground" />
         )}
+        {actionLabel && <span>{label}</span>}
       </button>
       {/* Announce the result; the icon swap alone is silent to screen readers. */}
-      <span className="sr-only" role="status" aria-live="polite">
+      <span className={codePresentation.copyStatus} data-copy-long-work={!!longRunning} role="status" aria-live="polite">
         {status}
       </span>
     </>

package/src/markdown/index.ts

@@ -5,6 +5,7 @@ export {
   type MarkdownLinkChipResolver,
   type MarkdownProps,
 } from "./markdown";
-export { CodeBlock, CopyButton, codeBlockGrammar, type CodeBlockProps } from "./code-block";
+export { CodeBlock, CopyButton, codeBlockGrammar, type CopyButtonProps, type CodeBlockProps } from "./code-block";
 export { fenceInfo } from "./code-meta";
 export { numericColumns, tableCsv } from "./markdown-table";
+export { ApiSchema, type ApiSchemaProps } from "./api-schema";

package/src/presentation.ts

@@ -0,0 +1,205 @@
+/** React-free presentation. Consumers scan this published source with Tailwind. */
+import { surfaceMotion } from "./lib/motion";
+import { cva } from "class-variance-authority";
+import { controlHeight, controlMotion, controlRadius, controlSizes, controlSquare, controlText, fieldPresentation, fieldSizes, fieldTouchText } from "./lib/control-presentation";
+import { focusRing, focusFieldInvalid } from "./lib/focus";
+import { ixControl, ixControlSoft, ixSelected, ixTabUnderline } from "./lib/interaction";
+import { cn } from "./lib/utils";
+export { controlHeight, controlMotion, controlRadius, controlSizes, controlText, fieldPresentation, fieldSizes, fieldTouchText } from "./lib/control-presentation";
+
+export const buttonVariants = cva(
+  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium ${controlMotion} ${focusRing} disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50 motion-reduce:active:scale-100 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`,
+  {
+    variants: {
+      variant: {
+        default:
+          `bg-primary text-primary-foreground hover:bg-primary/90 active:scale-[0.97] ${ixControl}`,
+        destructive:
+          `bg-destructive text-destructive-foreground hover:bg-destructive/90 active:scale-[0.97] ${ixControl}`,
+        outline:
+          `border border-border bg-card hover:bg-muted active:scale-[0.97] text-foreground ${ixControl}`,
+        secondary:
+          `bg-muted border border-border text-foreground hover:bg-muted/80 active:scale-[0.97] ${ixControl}`,
+        ghost:
+          `hover:text-foreground text-muted-foreground border border-transparent ${ixControlSoft}`,
+        link: `text-[var(--accent-text)] underline-offset-4 hover:underline ${ixControlSoft}`,
+        sandbox:
+          `bg-[var(--btn-primary-bg)] text-[var(--btn-primary-text)] border border-[var(--border-accent)] hover:bg-[var(--btn-primary-hover)] active:scale-[0.97] ${ixControl}`,
+      },
+      size: {
+        default: `${controlHeight.md} ${controlText.md} ${controlRadius.md} px-4 py-2`,
+        md: `${controlHeight.md} ${controlText.md} ${controlRadius.md} px-4 py-2`,
+        sm: `${controlHeight.sm} ${controlText.sm} ${controlRadius.sm} px-3`,
+        lg: `${controlHeight.lg} ${controlText.lg} ${controlRadius.lg} px-7`,
+        display: "tangle-control-display",
+        xl: "h-13 rounded-xl px-9 text-base",
+        icon: `${controlSquare.md} ${controlText.md} ${controlRadius.md}`,
+        "icon-sm": `${controlSquare.sm} ${controlText.sm} ${controlRadius.sm}`,
+        "icon-lg": `${controlSquare.lg} ${controlText.lg} ${controlRadius.lg}`,
+        ...controlSizes,
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+
+export const inputVariants = cva(
+  cn(
+    "flex w-full border py-1 placeholder:text-[var(--text-dim)] disabled:cursor-not-allowed disabled:opacity-50 file:border-0 file:bg-transparent file:font-medium",
+    fieldPresentation,
+    fieldTouchText,
+  ),
+  {
+    variants: {
+      // `default` and `sandbox` render the same field; both names stay valid.
+      variant: {
+        default: "",
+        sandbox: "",
+        error: focusFieldInvalid,
+      },
+      size: {
+        default: fieldSizes.md,
+        md: fieldSizes.md,
+        sm: fieldSizes.sm,
+        lg: fieldSizes.lg,
+        compact: cn(fieldSizes.md, controlSizes.compact),
+        touch: cn(fieldSizes.md, controlSizes.touch),
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+
+export const tablePresentation = {
+  root: "w-full caption-bottom text-sm",
+  wrapper: "relative w-full overflow-auto",
+  head: "[&_tr]:border-b",
+  body: "[&_tr:last-child]:border-0",
+  footer: "border-t bg-card font-medium [&>tr]:last:border-b-0",
+  row: `border-border border-b ${controlMotion} hover:bg-muted/50 data-[state=selected]:bg-muted/50`,
+  columnHeader: "h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0",
+  cell: "p-4 align-middle [&:has([role=checkbox])]:pr-0",
+  caption: "mt-4 text-muted-foreground text-sm",
+} as const;
+
+export const emptyStatePresentation = {
+  root: "flex flex-col items-center justify-center px-4 py-16 text-center",
+  icon: "mb-4 rounded-full bg-muted p-4 text-muted-foreground",
+  title: "font-semibold text-lg",
+  description: "mt-2 max-w-sm text-muted-foreground text-sm",
+  action: "mt-6",
+} as const;
+
+export const metricPresentation = {
+  strip: "grid min-w-0 rounded-[var(--radius-lg)] border border-border bg-card shadow-[var(--shadow-card)]",
+  item: "min-w-0 border-border p-4 sm:p-5",
+  value: "mt-1 whitespace-normal [overflow-wrap:anywhere] font-semibold text-xl tabular-nums tracking-tight lg:text-2xl",
+  label: "flex min-w-0 flex-wrap items-center gap-2 text-muted-foreground text-sm",
+  labelText: "min-w-0 whitespace-normal [overflow-wrap:anywhere]",
+  hint: "mt-0.5 whitespace-normal [overflow-wrap:anywhere] text-[var(--text-dim)] text-xs",
+} as const;
+
+export const metricLayouts = {
+  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",
+  6: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 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(6n+1))]:border-l",
+} as const;
+
+export const dialogPresentation = {
+  overlay: "fixed inset-0 z-50 bg-black/40",
+  transition: surfaceMotion,
+  position: "fixed top-[50%] left-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%]",
+  surface: "gap-4 rounded-lg border bg-card p-6 shadow-lg",
+  close: `absolute top-4 right-4 rounded-sm opacity-70 ${controlMotion} hover:opacity-100 focus-visible:opacity-100 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground`,
+  header: "flex flex-col space-y-1.5 text-center sm:text-left",
+  footer: "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+  title: "font-semibold text-lg leading-none tracking-tight",
+  description: "text-muted-foreground text-sm",
+} as const;
+
+/** Native-dialog adapter for Hono/static markup. Radix remains the React Dialog/Sheet owner. */
+export function bindDialog(dialog: HTMLDialogElement, trigger: HTMLElement): () => void {
+  const sync = () => trigger.setAttribute("aria-expanded", String(dialog.open));
+  const show = () => { if (!dialog.open) dialog.showModal(); sync(); };
+  const close = () => { sync(); trigger.focus(); };
+  const click = (event: MouseEvent) => {
+    const target = event.target;
+    if (target instanceof Element && target.closest("[data-dialog-close]")) dialog.close();
+  };
+  // Native modal inertness blocks page controls, but Tab can still visit browser
+  // chrome at a boundary. Keep this reading surface's keyboard cycle local.
+  const key = (event: KeyboardEvent) => {
+    if (event.key !== "Tab" || !dialog.open) return;
+    const candidates = [...dialog.querySelectorAll<HTMLElement>("*")]
+      .filter(element => (element.tabIndex >= 0 || (element.isContentEditable && !element.hasAttribute("tabindex")))
+        && !element.matches(":disabled") && !element.closest("[inert]")
+        && element.getClientRects().length > 0 && getComputedStyle(element).visibility === "visible");
+    const radio = (element: Element): element is HTMLInputElement => element instanceof HTMLInputElement && element.type === "radio" && !!element.name;
+    const sameRadioGroup = (a: Element, b: Element) => radio(a) && radio(b) && a.name === b.name && a.form === b.form && a.getRootNode() === b.getRootNode();
+    const stops = candidates.filter(element => {
+      if (!radio(element)) return true;
+      const group = candidates.filter(candidate => sameRadioGroup(element, candidate));
+      const checked = group.find(candidate => (candidate as HTMLInputElement).checked);
+      return element === (checked ?? (event.shiftKey ? group.at(-1) : group[0]));
+    }).sort((a, b) => (a.tabIndex > 0 ? a.tabIndex : Infinity) - (b.tabIndex > 0 ? b.tabIndex : Infinity));
+    const first = stops[0], last = stops.at(-1), active = document.activeElement;
+    if (!first) { event.preventDefault(); dialog.focus(); return; }
+    const atBoundary = (boundary: HTMLElement) => active === boundary || (active instanceof Element && sameRadioGroup(active, boundary));
+    if (active === dialog || (event.shiftKey ? atBoundary(first) : atBoundary(last!))) {
+      event.preventDefault(); (event.shiftKey ? last! : first).focus();
+    }
+  };
+  trigger.setAttribute("aria-haspopup", "dialog");
+  if (dialog.id) trigger.setAttribute("aria-controls", dialog.id);
+  sync();trigger.addEventListener("click",show);dialog.addEventListener("close",close);dialog.addEventListener("click",click);dialog.addEventListener("keydown",key);
+  return () => {trigger.removeEventListener("click",show);dialog.removeEventListener("close",close);dialog.removeEventListener("click",click);dialog.removeEventListener("keydown",key);};
+}
+
+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",
+);
+
+export const helpPresentation = {
+ root: "text-[length:var(--font-size-help,0.75rem)] leading-4",
+ error: "font-medium text-[var(--surface-danger-text)]",
+ hint: "text-[var(--text-dim)]",
+};
+
+export const cardPresentation = {
+ root: `rounded-[var(--radius-lg)] border text-card-foreground ${controlMotion}`,
+ padding: "p-4",
+ variants: {
+    default: "bg-card border-border shadow-[var(--edge-highlight),var(--shadow-card)]",
+    elevated: "bg-muted/50 border-border shadow-[var(--shadow-card)]",
+    glass: "bg-card/80 backdrop-blur-xl border-border shadow-[var(--shadow-card)]",
+    sandbox: "bg-muted/50 border-primary/20 shadow-[var(--shadow-accent)]",
+  },
+} as const;
+
+/** Canonical segmented, pill and underline navigation presentation. */
+export const tabsPresentation = {
+list: {
+    default:
+      "inline-flex h-10 items-center justify-center rounded-lg bg-muted p-1 text-muted-foreground",
+    pills: "inline-flex items-center gap-2",
+    underline: "inline-flex items-center gap-4 border-b border-border",
+  },
+trigger: {
+    default:
+      `inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ${controlMotion} ${focusRing} disabled:pointer-events-none disabled:opacity-50 ${ixControlSoft} ${ixSelected}`,
+    pills:
+      `inline-flex items-center justify-center whitespace-nowrap rounded-full px-4 py-2 text-sm font-medium ${controlMotion} ${focusRing} disabled:pointer-events-none disabled:opacity-50 data-[state=inactive]:text-muted-foreground ${ixControlSoft} ${ixSelected}`,
+    underline:
+      `inline-flex items-center justify-center whitespace-nowrap rounded-t-md pb-3 text-sm font-medium ${controlMotion} ${focusRing} disabled:pointer-events-none disabled:opacity-50 border-b-2 border-transparent data-[state=inactive]:text-muted-foreground ${ixTabUnderline}`,
+  }
+} as const;
+export { ixControlSoft, ixSelected, ixTabUnderline } from "./lib/interaction";

package/src/primitives/alert.tsx

@@ -1,6 +1,5 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
-import type { StatusTone } from "./status-pill";
 
 /**
  * An inline message that stays on the page: a policy note above a form, a
@@ -14,7 +13,7 @@ import type { StatusTone } from "./status-pill";
  * `danger` and `warning` announce themselves (`role="alert"`); the quieter
  * tones are `role="status"` so a screen reader is not interrupted by a note.
  */
-export type AlertTone = Exclude<StatusTone, "running">;
+export type AlertTone = "neutral" | "info" | "success" | "warning" | "danger";
 
 export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
   tone?: AlertTone;

package/src/primitives/button.tsx

@@ -1,7 +1,7 @@
 import { Slot } from "@radix-ui/react-slot";
-import { cva } from "class-variance-authority";
+import { buttonVariants } from "../presentation";
 import * as React from "react";
-import { controlHeight, controlMotion, controlRadius, controlSizes, controlSquare, controlText } from "../lib/control-presentation";
+import { controlMotion } from "../lib/motion";
 import { focusRing } from "../lib/focus";
 import { ixControl, ixControlSoft, ixSelected } from "../lib/interaction";
 import { cn } from "../lib/utils";
@@ -14,49 +14,12 @@ import { cn } from "../lib/utils";
 // `ixControl` (green edge and glow on hover, press and after a click); ghost,
 // link and bare take `ixControlSoft`, a wash that never glows. A toggle button
 // (any `aria-pressed`) adds `ixControl` + `ixSelected` whatever its variant.
-const buttonVariants = cva(
-  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium transition-[color,background-color,border-color,box-shadow,transform,scale] ${controlMotion} ${focusRing} disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50 motion-reduce:active:scale-100 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`,
-  {
-    variants: {
-      variant: {
-        default:
-          `bg-primary text-primary-foreground hover:bg-primary/90 active:scale-[0.97] ${ixControl}`,
-        destructive:
-          `bg-destructive text-destructive-foreground hover:bg-destructive/90 active:scale-[0.97] ${ixControl}`,
-        outline:
-          `border border-border bg-card hover:bg-muted active:scale-[0.97] text-foreground ${ixControl}`,
-        secondary:
-          `bg-muted border border-border text-foreground hover:bg-muted/80 active:scale-[0.97] ${ixControl}`,
-        ghost:
-          `hover:text-foreground text-muted-foreground border border-transparent ${ixControlSoft}`,
-        link: `text-[var(--accent-text)] underline-offset-4 hover:underline ${ixControlSoft}`,
-        sandbox:
-          `bg-[var(--btn-primary-bg)] text-[var(--btn-primary-text)] border border-[var(--border-accent)] hover:bg-[var(--btn-primary-hover)] active:scale-[0.97] ${ixControl}`,
-      },
-      size: {
-        default: `${controlHeight.md} ${controlText.md} ${controlRadius.md} px-4 py-2`,
-        md: `${controlHeight.md} ${controlText.md} ${controlRadius.md} px-4 py-2`,
-        sm: `${controlHeight.sm} ${controlText.sm} ${controlRadius.sm} px-3`,
-        lg: `${controlHeight.lg} ${controlText.lg} ${controlRadius.lg} px-7`,
-        xl: "h-13 rounded-xl px-9 text-base",
-        icon: `${controlSquare.md} ${controlText.md} ${controlRadius.md}`,
-        "icon-sm": `${controlSquare.sm} ${controlText.sm} ${controlRadius.sm}`,
-        "icon-lg": `${controlSquare.lg} ${controlText.lg} ${controlRadius.lg}`,
-        ...controlSizes,
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
-  },
-);
 
 // `bare` keeps the shared focus ring, disabled and loading behavior and drops
 // every surface, size and type class. It is for pressable rows, tiles and pills
 // that draw their own layout; anything that reads as a button uses a styled
 // variant and a size.
-const bareButton = `${focusRing} ${ixControlSoft} disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50`;
+const bareButton = `${focusRing} ${controlMotion} ${ixControlSoft} disabled:pointer-events-none disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50`;
 
 /** One Button render's classes: variant and size, the toggle states, then the caller's. */
 function buttonClassName(
@@ -75,7 +38,7 @@ export interface ButtonProps
   extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "sandbox" | "bare" | null;
   /** sm 32px, default/md 36px (`--control-height`), lg 44px; icon sizes are squares on the same heights. */
-  size?: "default" | "md" | "sm" | "lg" | "xl" | "icon" | "icon-sm" | "icon-lg" | "compact" | "touch" | null;
+  size?: "default" | "md" | "sm" | "lg" | "xl" | "display" | "icon" | "icon-sm" | "icon-lg" | "compact" | "touch" | null;
   asChild?: boolean;
   loading?: boolean;
   children?: React.ReactNode;
@@ -136,6 +99,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
         <Slot
           className={buttonClassName(variant, size, props["aria-pressed"], className)}
           ref={ref}
+          data-variant={size === "display" ? variant ?? "default" : undefined}
           {...props}
           {...(isDisabled ? disabledHandlers(props) : {})}
         >
@@ -161,6 +125,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       <button
         className={buttonClassName(variant, size, props["aria-pressed"], className)}
         ref={ref}
+        data-variant={size === "display" ? variant ?? "default" : undefined}
         {...props}
         disabled={disabled || loading}
         aria-busy={loading || props["aria-busy"]}