@tangle-network/ui 11.35.0 → 11.37.0

package/src/lib/code-presentation.ts

@@ -0,0 +1,257 @@
+import { tabsPresentation } from "../presentation";
+import type { HighlighterCore, LanguageRegistration, ThemedToken } from "shiki/core";
+// 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.
+export 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",
+};
+
+export 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. */
+export 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;
+    });
+}
+
+export 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 });
+}
+
+export function tokenStyle(token: ThemedToken): TokenStyle | 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 TokenStyle {color?: string; fontStyle?: "italic"; fontWeight?: "bold"; textDecoration?: "underline";}
+export const codePreStyle = {
+  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",
+} as const;
+export const codeTextStyle = {fontFamily: "var(--font-mono, 'JetBrains Mono', ui-monospace, monospace)",whiteSpace:"pre"} as const;
+export const codePresentation = {
+  tabs: `tangle-code-tabs ${tabsPresentation.list.underline}`,
+  tab: tabsPresentation.trigger.underline,
+  root: "group relative min-w-0 overflow-hidden rounded-lg border font-mono bg-card border-border",
+  header: "flex flex-wrap items-center justify-between gap-3 border-b border-border px-3 py-1.5 bg-[var(--code-header-bg,hsl(var(--background)))]",
+  copy: "flex items-center justify-center min-w-8 min-h-8 pointer-coarse:min-w-11 pointer-coarse:min-h-11 rounded-md bg-muted border border-border hover:border-[var(--border-strong)] transition-colors data-[copy-loading=true]:after:content-['…'] data-[copy-loading=true]:gap-1",
+  copyStatus: "sr-only data-[copy-long-work=true]:not-sr-only data-[copy-long-work=true]:text-xs data-[copy-long-work=true]:text-muted-foreground",
+};
+export interface CodeExample {label:string;code:string;language?:string;filename?:string;}
+export interface ApiMetadata {kind:"request"|"response"|"error";method?:string;status?:number;contentType?:string;}
+export const apiMetadataText = (meta:ApiMetadata) => [meta.kind,meta.method,meta.status,meta.contentType].filter(v=>v!==undefined).join(" · ");
+
+/** Same lazy grammar/token model for React, Hono SSR and static renderers. */
+export async function highlightCode(code:string,language?:string) {
+ const grammar=codeBlockGrammar(language);
+ if(!grammar)return code.split("\n").map(content=>[{content,style:undefined as TokenStyle|undefined}]);
+ return (await tokenize(code,grammar)).map(line=>line.map(token=>({content:token.content,style:tokenStyle(token)})));
+}
+/** Legacy fallback is used only when the modern clipboard API is absent. */
+export async function writeClipboard(text:string):Promise<void> {
+ if(navigator.clipboard?.writeText){await navigator.clipboard.writeText(text);return;}
+ const active=document.activeElement as HTMLElement|null,selection=document.getSelection();
+ const ranges=selection?Array.from({length:selection.rangeCount},(_,i)=>selection.getRangeAt(i).cloneRange()):[];
+ const field=document.createElement("textarea");field.value=text;field.readOnly=true;field.tabIndex=-1;
+ field.setAttribute("aria-hidden","true");field.style.position="fixed";field.style.left="-9999px";
+ document.body.append(field);
+ try {field.select();if(!document.execCommand?.("copy"))throw Error("Clipboard unavailable");}
+ finally {field.remove();active?.focus({preventScroll:true});if(selection){selection.removeAllRanges();for(const range of ranges)selection.addRange(range);}}
+}
+const COPY_FEEDBACK_MS=2000;
+export interface InteractionBudgets { feedback?:number; pending?:number; longWork?:number; mutation?:number; }
+/** Resolve scoped Brand times, including calc(), without duplicating token values. */
+export function interactionBudgets(scope:HTMLElement):InteractionBudgets {
+ const view=scope.ownerDocument.defaultView;if(!view)return {};
+ const probe=scope.ownerDocument.createElement("i");probe.hidden=true;scope.append(probe);
+ const read=(role:string)=>{
+  const name=`--interaction-${role}`;
+  if(!view.getComputedStyle(scope).getPropertyValue(name).trim())return undefined;
+  probe.style.animationDuration=`var(${name})`;
+  const time=/^(\d+(?:\.\d+)?)(ms|s)$/.exec(view.getComputedStyle(probe).animationDuration);
+  return time?Number(time[1])*(time[2]==="s"?1000:1):undefined;
+ };
+ try{return {feedback:read("feedback-budget"),pending:read("pending-delay"),longWork:read("long-work-delay"),mutation:read("mutation-budget")};}
+ finally{probe.remove();}
+}
+export interface CopyFeedback {
+ copied:boolean;status:string;pending:boolean;loading?:boolean;longRunning?:boolean;elapsedMs?:number;
+ measurement?:{elapsedMs:number;feedbackMs:number;budgets:InteractionBudgets;mutationBudgetExceeded:boolean|undefined};
+}
+/** Owns one accepted write, scoped delays and cleanup for both renderers. */
+export function createCopyFeedback(change:(state:CopyFeedback)=>void,write:(text:string)=>Promise<void>=writeClipboard,scope?:HTMLElement) {
+ let disposed=false,pending=false,timer:ReturnType<typeof setTimeout>|undefined;
+ let delays:Array<ReturnType<typeof setTimeout>>=[],elapsed:ReturnType<typeof setInterval>|undefined;
+ const clearPending=()=>{for(const delay of delays)clearTimeout(delay);delays=[];if(elapsed)clearInterval(elapsed);elapsed=undefined;};
+ return {
+  async copy(text:string) {
+   if(disposed||pending)return;
+   const started=performance.now(),budgets=scope?interactionBudgets(scope):{};
+   pending=true;if(timer)clearTimeout(timer);
+   let loading=budgets.pending===undefined,longRunning=false;
+   const announce=()=>{
+    const elapsedMs=performance.now()-started;
+    change({copied:false,pending:true,loading,longRunning,elapsedMs,status:longRunning
+     ?`Copying · ${Math.floor(elapsedMs/1000)}s elapsed. Time remaining unknown. Cannot cancel this clipboard write; waiting for confirmation.`
+     :"Copying to clipboard"});
+   };
+   announce();const feedbackMs=performance.now()-started;
+   if(budgets.pending!==undefined)delays.push(setTimeout(()=>{loading=true;announce();},budgets.pending));
+   if(budgets.longWork!==undefined)delays.push(setTimeout(()=>{longRunning=true;announce();elapsed=setInterval(announce,1000);},budgets.longWork));
+   let copied:boolean;
+   try {await write(text);copied=true;}
+   catch {copied=false;}
+   pending=false;clearPending();if(disposed)return;
+   const elapsedMs=performance.now()-started;
+   change({copied,status:copied?"Copied to clipboard":"Copy failed",pending:false,measurement:{elapsedMs,feedbackMs,budgets,
+    mutationBudgetExceeded:budgets.mutation===undefined?undefined:elapsedMs>budgets.mutation}});
+   timer=setTimeout(()=>{if(!disposed)change({copied:false,status:"",pending:false});},COPY_FEEDBACK_MS);
+  },
+  dispose(){disposed=true;clearPending();if(timer)clearTimeout(timer);},
+ };
+}
+export function bindCopyButton(button:HTMLButtonElement,status:HTMLElement,text:()=>string) {
+ const previous={label:button.getAttribute("aria-label"),status:status.textContent,disabled:button.getAttribute("aria-disabled"),busy:button.getAttribute("aria-busy"),loading:button.getAttribute("data-copy-loading"),long:status.getAttribute("data-copy-long-work")};
+ const restore=(element:HTMLElement,name:string,value:string|null)=>{if(value===null)element.removeAttribute(name);else element.setAttribute(name,value);};
+ const feedback=createCopyFeedback(state=>{
+  status.textContent=state.status;status.setAttribute("data-copy-long-work",String(!!state.longRunning));
+  button.setAttribute("data-copy-loading",String(!!state.loading));
+  button.setAttribute("aria-label",state.pending?"Copying to clipboard":state.copied?"Copied":"Copy to clipboard");
+  if(state.pending){button.setAttribute("aria-disabled","true");button.setAttribute("aria-busy","true");}
+  else {restore(button,"aria-disabled",previous.disabled);restore(button,"aria-busy",previous.busy);}
+ },writeClipboard,button);
+ const click=()=>{if(!button.disabled&&button.getAttribute("aria-disabled")!=="true")void feedback.copy(text());};button.addEventListener("click",click);
+ return ()=>{button.removeEventListener("click",click);feedback.dispose();restore(button,"aria-label",previous.label);status.textContent=previous.status;restore(button,"aria-disabled",previous.disabled);restore(button,"aria-busy",previous.busy);restore(button,"data-copy-loading",previous.loading);restore(status,"data-copy-long-work",previous.long);};
+}
+/** Native tabs adapter. The consumer owns labels, IDs and escaped panel content. */
+export function bindCodeTabs(list:HTMLElement,onSelect?:(index:number)=>void) {
+ const buttons=()=>[...list.querySelectorAll<HTMLButtonElement>('[role="tab"]')];
+ const select=(index:number,focus:boolean)=>{
+  const tabs=buttons(),tab=tabs[index];if(!tab)return;
+  for(const panel of new Set(tabs.map(t=>document.getElementById(t.getAttribute("aria-controls")??""))))if(panel)panel.hidden=true;
+  tabs.forEach((t,i)=>{t.setAttribute("aria-selected",String(i===index));t.dataset.state=i===index?"active":"inactive";t.tabIndex=i===index?0:-1;});
+  const panel=document.getElementById(tab.getAttribute("aria-controls")??"");if(panel){panel.hidden=false;panel.setAttribute("aria-labelledby",tab.id);}
+  if(focus)tab.focus();onSelect?.(index);
+ };
+ const click=(event:MouseEvent)=>{const tab=(event.target as Element).closest('[role="tab"]');const index=buttons().findIndex(t=>t===tab);if(index>=0)select(index,false);};
+ const key=(event:KeyboardEvent)=>{
+  const tabs=buttons(),current=tabs.findIndex(t=>t===document.activeElement);if(current<0)return;
+  const next=event.key==="Home"?0:event.key==="End"?tabs.length-1:event.key==="ArrowRight"?(current+1)%tabs.length:event.key==="ArrowLeft"?(current+tabs.length-1)%tabs.length:undefined;
+  if(next!==undefined){event.preventDefault();select(next,true);}
+ };
+ list.addEventListener("click",click);list.addEventListener("keydown",key);
+ return ()=>{list.removeEventListener("click",click);list.removeEventListener("keydown",key);};
+}
+export interface ApiField {name:string;type:string;description?:string;required?:boolean;children?:readonly ApiField[];}
+export function schemaRows(fields:readonly ApiField[],parent="",depth=0):Array<ApiField&{path:string;depth:number}> {
+ return fields.flatMap(field=>{const path=parent?`${parent}.${field.name}`:field.name;return [{...field,path,depth},...schemaRows(field.children??[],path,depth+1)];});
+}

package/src/lib/control-presentation.ts

@@ -2,10 +2,8 @@ import { focusField } from "./focus";
 import { ixField } from "./interaction";
 import { cn } from "./utils";
 
-// Time-valued tokens only: --transition-fast is a legacy duration + easing
-// shorthand, not a valid transition-duration. Reuse Brand's scoped vocabulary.
-export const controlMotion =
-  "duration-[var(--duration-fast)] ease-[var(--ease-standard)] motion-reduce:transition-none motion-reduce:duration-0";
+import { controlMotion } from "./motion";
+export { controlMotion } from "./motion";
 
 /**
  * The control scale. Button, Input, Textarea and SelectTrigger take the same

package/src/lib/focus.ts

@@ -1,3 +1,4 @@
+import { controlMotion } from "./motion";
 import { ixField } from "./interaction";
 
 /**
@@ -30,7 +31,7 @@ import { ixField } from "./interaction";
  * Tailwind emits `focus:` after `hover:`.
  */
 export const focusField =
-  "border-border transition-[border-color,box-shadow] duration-150 ease-out hover:border-[var(--border-strong)] focus:outline-hidden focus:border-[var(--focus-border)] focus:ring-3 focus:ring-[var(--focus-halo)]";
+  `border-border ${controlMotion} hover:border-[var(--border-strong)] focus:outline-hidden focus:border-[var(--focus-border)] focus:ring-3 focus:ring-[var(--focus-halo)]`;
 
 /**
  * The field treatment for a container that wraps a borderless field, such as a
@@ -50,7 +51,7 @@ export const focusField =
  * borderless field inside stays transparent.
  */
 export const focusFieldWithin =
-  `focus-field-within transition-[border-color,box-shadow] duration-150 ease-out ${ixField} has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:border-[var(--focus-border)] has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-3 has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-[var(--focus-halo)]`;
+  `focus-field-within ${controlMotion} ${ixField} has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:border-[var(--focus-border)] has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-3 has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-[var(--focus-halo)]`;
 
 /** Error state for a field: a danger hairline and the same focus shape in danger. Compose after `focusField`. */
 export const focusFieldInvalid =

package/src/lib/motion.ts

@@ -0,0 +1,7 @@
+/** Brand motion roles contain duration AND easing; consume complete shorthands. */
+export const controlMotion =
+  "[transition:color_var(--motion-control),background-color_var(--motion-control),border-color_var(--motion-control),box-shadow_var(--motion-control),transform_var(--motion-control),scale_var(--motion-control),opacity_var(--motion-control)] motion-reduce:transition-none";
+
+/** Radix presence markers carry the scoped role; SurfaceMotion owns interruptible geometry. */
+export const surfaceMotion =
+  "data-[state=open]:[animation:tangle-surface-present_var(--motion-surface)_both] data-[state=delayed-open]:[animation:tangle-surface-present_var(--motion-surface)_both] data-[state=instant-open]:[animation:tangle-surface-present_var(--motion-surface)_both] data-[state=closed]:[animation:tangle-surface-absent_var(--motion-dismiss)_both] motion-reduce:animate-none!";

package/src/lib/surface-motion.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { animate, motionValue, styleEffect, type MotionValue } from "motion";
+
+type Side = "top" | "right" | "bottom" | "left";
+type SurfaceProps = React.HTMLAttributes<HTMLDivElement> & {
+  kind: "dialog" | "sheet" | "overlay" | "tooltip" | "popover";
+  side?: Side;
+  asChild?: boolean;
+  "data-state"?: string;
+};
+
+/** Radix owns state, focus and presence; Motion only retargets the visible object. */
+export const SurfaceMotion = React.forwardRef<HTMLDivElement, SurfaceProps>(
+  ({ kind, side = "right", asChild, "data-state": state, ...props }, forwardedRef) => {
+    const element = React.useRef<HTMLDivElement | null>(null);
+    const values = React.useRef<Record<"opacity" | "scale" | "x" | "y", MotionValue<number>> | null>(null);
+    const controls = React.useRef<Array<ReturnType<typeof animate>>>([]);
+    const ref = React.useCallback<React.RefCallback<HTMLDivElement>>((node) => {
+      element.current = node;
+      if (typeof forwardedRef === "function") {
+        const cleanup: unknown = forwardedRef(node);
+        if (typeof cleanup === "function") return () => { element.current = null; cleanup(); };
+      } else if (forwardedRef) forwardedRef.current = node;
+    }, [forwardedRef]);
+
+    React.useLayoutEffect(() => {
+      const node = element.current;
+      if (!node) return;
+      const preference = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : undefined;
+      let cancelRender: (() => void) | undefined;
+      const run = () => {
+        const closed = state === "closed";
+        const bounds = node.getBoundingClientRect();
+        const hidden = {
+          opacity: kind === "sheet" ? 1 : 0,
+          scale: kind === "dialog" || kind === "tooltip" || kind === "popover" ? 0.98 : 1,
+          x: kind === "sheet" ? side === "left" ? -bounds.width : side === "right" ? bounds.width : 0 : 0,
+          y: kind === "sheet" ? side === "top" ? -bounds.height : side === "bottom" ? bounds.height : 0 : 0,
+        };
+        const target = closed ? hidden : { opacity: 1, scale: 1, x: 0, y: 0 };
+        const style = getComputedStyle(node);
+        // The nonvisual marker resolves the full role, including scoped calc().
+        const time = /^(\d+(?:\.\d+)?)(ms|s)$/.exec(style.animationDuration.split(",")[0]!.trim());
+        const seconds = time ? Number(time[1]) / (time[2] === "ms" ? 1000 : 1) : 0;
+        const place = (value: typeof target) => {
+          node.style.opacity = String(value.opacity);
+          node.style.transform = `translateX(${value.x}px) translateY(${value.y}px) scale(${value.scale})`;
+        };
+        // Missing styles and reduced motion settle synchronously. No semantic
+        // transition waits for a JavaScript completion callback.
+        if (preference?.matches || seconds <= 0 || style.animationName === "none") {
+          controls.current.forEach(control => control.stop());
+          if (values.current) for (const key of ["opacity", "scale", "x", "y"] as const) values.current[key].jump(target[key]);
+          place(target);
+          return;
+        }
+        if (!values.current) {
+          place(hidden);
+          values.current = { opacity: motionValue(hidden.opacity), scale: motionValue(hidden.scale), x: motionValue(hidden.x), y: motionValue(hidden.y) };
+        }
+        cancelRender ??= styleEffect(node, values.current);
+        // Critically damped response: <0.01% residual at the role's deadline.
+        // Explicit values keep every channel on the same frame clock, including
+        // opacity, without resampling a compositor animation on reversal.
+        const frequency = 12 / seconds;
+        controls.current = (["opacity", "scale", "x", "y"] as const).map(key => animate(values.current![key], target[key], {
+          type: "spring", stiffness: frequency * frequency, damping: 2 * frequency,
+          restDelta: 0.001, restSpeed: 0.01,
+        }));
+      };
+      run();
+      preference?.addEventListener("change", run);
+      return () => { preference?.removeEventListener("change", run); cancelRender?.(); };
+    // Radix Popper temporarily suppresses animation until placement resolves.
+    // Start the same retained values when that inline override clears.
+    }, [state, kind, side, props.style?.animation]);
+    React.useEffect(() => () => controls.current.forEach(control => control.stop()), []);
+    const Component = asChild ? Slot : "div";
+    return <Component {...props} data-state={state} ref={ref} />;
+  },
+);
+SurfaceMotion.displayName = "SurfaceMotion";

package/src/markdown/api-presentation.test.tsx

@@ -0,0 +1,63 @@
+import { fireEvent,render,screen } from "@testing-library/react";
+import { describe,it,expect,vi } from "vitest";
+import { CodeBlock } from "./code-block";
+import { ApiSchema } from "./api-schema";
+import { bindCopyButton,createCopyFeedback,highlightCode } from "../code-presentation";
+describe("shared API presentation",()=>{
+ it("renders field paths without turning schema text into HTML",()=>{
+  render(<ApiSchema fields={[{name:"messages",type:"array",children:[{name:"content",type:"string",description:"<script>bad()</script>"}]}]}/>);
+  expect(screen.getByText("messages.content")).toBeInTheDocument();expect(document.querySelector("script")).toBeNull();
+ });
+ it("keeps stale clipboard completions and disposed feedback silent",async()=>{
+  const updates=vi.fn();let complete!:()=>void;const feedback=createCopyFeedback(updates,()=>new Promise<void>(resolve=>{complete=resolve;}));
+  const pending=feedback.copy("bytes");feedback.dispose();complete();await pending;expect(updates).toHaveBeenCalledTimes(1);
+ });
+ it("blocks duplicate writes until the accepted operation settles",async()=>{
+  const updates=vi.fn();let complete!:()=>void;
+  const write=vi.fn(()=>new Promise<void>(resolve=>{complete=resolve;}));
+  const feedback=createCopyFeedback(updates,write);
+  const first=feedback.copy("first");await feedback.copy("duplicate");
+  expect(write.mock.calls).toEqual([["first"]]);
+  expect(updates).toHaveBeenLastCalledWith(expect.objectContaining({copied:false,status:"Copying to clipboard",pending:true}));
+  complete();await first;
+  expect(updates).toHaveBeenLastCalledWith(expect.objectContaining({copied:true,status:"Copied to clipboard",pending:false}));
+  const next=feedback.copy("next");expect(write).toHaveBeenCalledTimes(2);complete();await next;
+  feedback.dispose();await feedback.copy("disposed");expect(write).toHaveBeenCalledTimes(2);
+ });
+ it("retains exact newlines and plain binary/SSE text",async()=>{
+  const text='data: {"delta":"<x>"}\n\ndata: [DONE]\n';const lines=await highlightCode(text,"text");expect(lines.map(line=>line.map(t=>t.content).join("")).join("\n")).toBe(text);
+ });
+});
+
+describe("copy binding cleanup",()=>{
+ it.each(["pending","success","failure"])("restores retained DOM after %s",async phase=>{
+  const descriptor=Object.getOwnPropertyDescriptor(navigator,"clipboard");
+  let resolve!:()=>void,reject!:(error:Error)=>void;
+  const writeText=vi.fn(()=>new Promise<void>((yes,no)=>{resolve=yes;reject=no;}));
+  Object.defineProperty(navigator,"clipboard",{configurable:true,value:{writeText}});
+  const button=document.createElement("button"),status=document.createElement("span");
+  button.setAttribute("aria-label","Copy request");status.textContent="Ready";
+  const cleanup=bindCopyButton(button,status,()=>"exact bytes");
+  try {
+   button.click();expect(button.getAttribute("aria-label")).toBe("Copying to clipboard");
+   if(phase!=="pending"){
+    if(phase==="failure")reject(new Error("Denied"));else resolve();
+    await vi.waitFor(()=>expect(button.getAttribute("aria-label")).toBe(phase==="failure"?"Copy to clipboard":"Copied"));
+   }
+   cleanup();
+   expect(button.getAttribute("aria-label")).toBe("Copy request");expect(status.textContent).toBe("Ready");
+   resolve();await Promise.resolve();await Promise.resolve();
+   expect(button.getAttribute("aria-label")).toBe("Copy request");expect(status.textContent).toBe("Ready");
+  }finally{
+   cleanup();if(descriptor)Object.defineProperty(navigator,"clipboard",descriptor);else delete (navigator as {clipboard?:unknown}).clipboard;
+  }
+ });
+ it("restores an originally absent accessible label",()=>{
+  const button=document.createElement("button"),status=document.createElement("span");
+  const cleanup=bindCopyButton(button,status,()=>"bytes");button.setAttribute("aria-label","Copied");cleanup();expect(button.hasAttribute("aria-label")).toBe(false);
+ });
+ it("gives a single code example no orphaned tab relationship",()=>{
+  const {container,unmount}=render(<CodeBlock code="fallback" examples={[{label:"Plain",language:"text",code:"one"}]}/>);
+  try {expect(container.querySelector('[role="tab"]')).toBeNull();expect(container.querySelector('[role="tabpanel"]')).toBeNull();expect(container.querySelector('[aria-labelledby]')).toBeNull();expect(container.querySelector("pre")?.textContent).toBe("one");}finally{unmount();}
+ });
+});

package/src/markdown/api-schema.tsx

@@ -0,0 +1,9 @@
+import { schemaRows, type ApiField } from "../lib/code-presentation";
+export interface ApiSchemaProps {fields:readonly ApiField[];label?:string;}
+/** Presentation only: the consuming API owns all fields and constraints. */
+export function ApiSchema({fields,label="Schema"}:ApiSchemaProps) {
+ return <dl aria-label={label} className="tangle-api-schema">{schemaRows(fields).map((field,index)=><div key={`${field.path}-${index}`} style={{paddingInlineStart:`${field.depth}rem`}}>
+  <dt><code>{field.path}</code> <span>{field.type}{field.required?" · required":""}</span></dt>
+  {field.description&&<dd>{field.description}</dd>}
+ </div>)}</dl>;
+}