- \n {results.map((r) => (\n
- {r.label} \n ))}\n
`, override per surface via ``. Override the chevron with `icon=` if a different glyph fits the surface. Pass `asHeader={false}` on the trigger to suppress the `` wrapper when the accordion lives inside an existing heading hierarchy.\n\n#### `GlassInputFrame`\n\n```tsx\nimport { GlassInputFrame, ChatInput } from \"@aisquare/pretty\";\n\n// Wrap any composer in the gradient ring\n\n \n\n// Literal blue-purple-indigo from AIStudio-v3 (theme-exempt)\n\n \n\n// Or use ChatInput's built-in shorthand\n\n \n \n \n \n Useful hint \n \n \n```\n\nWrap your app once with ``, reuse Tooltip everywhere.\n\n#### `SmoothScroll`\n\n```tsx\n// Sub-entry import — SmoothScroll lives behind its own path so the main\n// barrel never references the optional `lenis` peer (#93).\nimport { SmoothScroll, useLenis } from \"@aisquare/pretty/smooth-scroll\";\n\n// Wrap once near the app root\n\n \n\n// Disable inside surfaces where smooth scroll fights inputs (e.g. editors)\n... \n\n// Read the active Lenis instance for advanced cases\nfunction ProgressBar() {\n const [progress, setProgress] = useState(0);\n useLenis((lenis) => setProgress(lenis.progress));\n return ;\n}\n```\n\nLenis-powered smooth scroll. Honors `prefers-reduced-motion` automatically (silently degrades to native scroll). Pair with `useScrollProgress` for scroll-linked motion. Opting in to this primitive is the only path that pulls `lenis` into your bundle — consumers who don't import from `@aisquare/pretty/smooth-scroll` don't need `lenis` installed at all.\n\n#### `Toaster` + `aiko`\n\n```tsx\nimport { Toaster, aiko } from \"@aisquare/pretty\";\n\n// near app root\n`. Ported from `AISquare-AIStudio-v3 AikoChat.tsx` for drop-in parity. Shares the same animation engine, reduced-motion handling, and `role=\"status\"` a11y contract. `size` prop uses Studio-v3's `sm | md` vocabulary and maps to `TypingIndicator`'s `sm | default`. For surfaces that already use `TypingIndicator`, prefer that directly; use `ThinkingDots` when migrating v3 code that referenced the local component by this name.\n\n#### `AikoLoader`\n\n```tsx\n\n \n \n\n\n {draft}
\n \n\n\n {draft}
// dim only, no glide\n \n\n\n // borderless surface override\n \n```\n\nBlock-level \"AIKO is editing this\" cue. While `loading` is true, children dim to muted ink and a skewed gradient beam glides across the wrapper at `speed` seconds per cycle (default `1.1`); when false, the wrapper is a plain pass-through. `aria-busy={loading}` is the screen-reader signal. `motion={false}` and `prefers-reduced-motion` both drop the beam — the dim + aria-busy stay so the cue persists. Pair with `` for inline chat-row \"composing\" states; reach for `EditingBeam` when AIKO is rewriting a whole field, title, or paragraph.\n\n#### `Skeleton`\n\n```tsx\n\n```\n\n### Content (images, markdown, media chrome)\n\n#### `Image`\n\n```tsx\nimport { Image } from \"@aisquare/pretty\";\n\n analytics.imageFailed(experience.id)}\n aspectRatio=\"4/3\"\n rounded=\"lg\"\n className=\"w-full\"\n/>\n\n![]()
` that owns the loading skeleton, one-shot fallback retry, error chrome, and CLS-prevention slot. Native `loading=\"lazy\"` by default; flips to `eager` + `fetchpriority=\"high\"` when `priority` is set. `aspectRatio` (`\"16/9\"`, `\"1/1\"`, etc.) forwards to CSS `aspect-ratio` on the wrapper. `rounded` cva variant: `none / sm / default / lg / full`.\n\nComposition: `errorContent` slot replaces the default error chrome; `fallbackSrc` provides one-shot retry. `onError` fires AFTER the internal retry, so consumer-side multi-step fallback chains keep working — the primitive resyncs when `src` changes.\n\nA11y: `aria-busy=\"true\"` during load, `role=\"img\" aria-label={errorLabel}` on error (suppressed for decorative `alt=\"\"` images). Honors `prefers-reduced-motion` automatically (load crossfade collapses to instant).\n\n#### `Markdown`\n\n```tsx\nimport { Markdown } from \"@aisquare/pretty\";\n\n {\n if (href?.startsWith(\"#resource:\")) return {children} ;\n return {children};\n },\n }}\n/>\n```\n\nSealed renderer for chat-aligned markdown. GFM (tables, strikethrough, task lists, autolinks), soft line breaks, sanitized HTML with `language-*` className preserved on code, syntax-highlighted fenced blocks (`react-syntax-highlighter` + Prism + `oneDark`), copy buttons, inline code in `bg-muted`, scrollable tables, and new-tab anchors. Empty / whitespace-only `content` returns `null`.\n\nComposition seam is the `components` prop — type `Partial` from `react-markdown`, shallow-merged with the primitive's defaults. Use it to intercept specific element renderers (most commonly `a` for app-specific routing); everything else stays default. There is no `asChild` — `` renders content from a string, not a child element.\n\nStreaming chat: pass `streaming` to render an inline-block blinking caret as the last child of the prose container — pulses while live tokens arrive, disappears the moment you flip the prop:\n\n```tsx\n` for the pre-first-token gap. The cursor honors `prefers-reduced-motion` (steady block instead of pulse) and is `aria-hidden` so screen readers aren't bombarded with \"blinking\" chatter — the streaming cue comes from the consumer's `aria-live` region (typically ``). Re-renders during streaming are cheap thanks to `React.memo` + `forwardRef` for direct ref access to the prose container.\n\nThe rehype-sanitize schema extension that allows `language-*` className is exported as `markdownSanitizeSchema` for consumers who need to extend it further.\n\n#### `Truncate`\n\n```tsx\nimport { Truncate } from \"@aisquare/pretty\";\n\n{customUrl} // 1-line ellipsis ()\n{description} // 2-line clamp\n // override body for icon children\n \n \n```\n\nTruncates text at N lines AND auto-renders an `` showing the full text only when overflow is actually present. Drops the need for consumers to plumb `useIsTruncated` state into a tooltip themselves. `lines={1}` (default) maps to Tailwind `truncate`; `lines={2|3|4}` maps to `line-clamp-{n}`. Polymorphic via `as` (default `\"span\"`).\n\nTooltip semantics: when `children` is a string or number, that's the default tooltip body. When children is a non-string ReactNode, pass `tooltipBody` explicitly to opt in (we don't stringify arbitrary nodes). `disableTooltip` skips the wrapper entirely. The wrapper stays mounted across resize-driven truncation flips with `open={false}` pinned when not truncated, so transient resizes don't remount the trigger child.\n\nSSR-safe: ResizeObserver gated behind `useIsomorphicLayoutEffect`, so server-rendered markup is just the bare element with truncation classes; the tooltip wrap evaluates after first client measurement.\n\nFor 1-line truncation to take effect, the parent should be a flex container with `min-w-0` (or any block parent with constrained width) — same constraint as raw `truncate`. Multi-line clamp needs no parent constraint. Requires `` at the app root (per ``).\n\n### Chat anatomy\n\n#### `ChatLog`\n\n```tsx\nimport { ChatLog, MessageRow, ScrollToBottomButton, useScrollToBottom } from \"@aisquare/pretty\";\n\nfunction ChatScroller({ messages, loadOlder, isLoadingOlder, unreadCount }) {\n const { scrollRef, sentinelRef, isAtBottom, scrollToBottom } = useScrollToBottom<\n HTMLDivElement,\n HTMLDivElement\n >();\n\n return (\n \n \n \n ))}\n \n \n scrollToBottom()}\n />\n \n );\n}\n```\n\nScroll container for a conversation of `` children. Owns the right CSS for an append-only chat surface — vertical overflow with `scrollbar-gutter: stable` so chip rows don't jiggle, and `overflow-anchor: auto` so newly-rendered messages don't yank the user's reading position. Two density variants — `comfortable` default and `compact` for tighter rails.\n\n`onLoadOlder` adds a 1px top sentinel that fires the callback once when scrolled into view (rate-limited to 250ms so layout shifts don't double-fire). `isLoadingOlder` surfaces an AIKO-voiced \"Loading earlier messages\" status row above the messages and latches the sentinel to prevent re-firing during the load. `loadingOlderLabel` overrides the copy.\n\n`empty` slot renders when `children` is null / undefined / false / an empty array — drop in an `` for the pre-first-message moment.\n\nForwards `ref` to the scroll container so you can wire `useScrollToBottom`'s `scrollRef` directly. Virtualization-friendly: a single overflow scroller with a flat children stack means `react-virtuoso` / `@tanstack/react-virtual` can wrap without structural change.\n\n#### `ScrollToBottomButton` + `useScrollToBottom()`\n\n```tsx\nimport { ScrollToBottomButton, useScrollToBottom } from \"@aisquare/pretty\";\n\nfunction ChatScroller({ messages, unreadCount }) {\n const { scrollRef, sentinelRef, isAtBottom, scrollToBottom } = useScrollToBottom<\n HTMLDivElement,\n HTMLDivElement\n >();\n\n return (\n \n {messages.map((m) => (\n scrollToBottom()}\n />\n \n );\n}\n```\n\nThe hook owns `IntersectionObserver`-based at-bottom detection plus a `scrollToBottom({ smooth })` action. The button is the visible \"Jump to latest\" affordance — absolutely positioned by default (`absolute bottom-3 left-1/2 -translate-x-1/2 z-10`), so wrap it inside a `position: relative` scroller. Override placement via `className` for sidebar / right-aligned use cases.\n\n`unreadCount` renders a small badge in the top-right corner (\"3\", \"99+\"). The label folds into `aria-label` so SR users hear \"Jump to latest, 3 unread\". Default 180ms fade+slide entrance; `motion={false}` and `prefers-reduced-motion` skip it.\n\nFor non-default content (e.g. a `Clear\n }\n/>\n```\n\n\"AIKO knows you're on X\" banner that signals which scope the agent has loaded. Three slots — `lead` (conventionally ``), `context` (the label, single-line truncated), `actions` (Clear / Edit / Exit-experience). Two variants — `default` bordered card surface, `muted` flatter pill.\n\nThe primitive renders as a regular block-level element. Sticky behavior is the consumer's call — wrap with `sticky top-0 z-10` to ride the scroller. `role=\"status\"` + `aria-live=\"polite\"` so screen readers announce scope changes; `aria-label` infers from `context` when it's a string, otherwise falls back to `\"Chat context\"` (override per surface). Default 240ms fade+slide-down entrance; `motion={false}` and `prefers-reduced-motion` skip it.\n\n#### `WizardStageIndicator`\n\n```tsx\nimport { WizardStageIndicator, ContextBar, AikoMark } from \"@aisquare/pretty\";\n\n\n\n// Composing inside :\n` (in the `actions` slot) so AIKO's loaded scope can show stage progression without bespoke per-page UI. Two variants — `compact` (default — dots + \"Step N of T · Label\" line; fits inside ContextBar) and `labels` (full breadcrumb with completed / current / pending icons + connectors; suitable for page headers).\n\nStages accept `string[]` for ergonomics or `{id, label}[]` when you need stable ids for `current` lookup. `current` accepts a 0-based index OR a stage id (string); out-of-range numbers clamp, unknown ids fall back to 0. Returns `null` on empty stages — no need to gate at the call site.\n\nA11y: `role=\"progressbar\"` with `aria-valuenow` / `aria-valuemax` / `aria-valuemin` / `aria-label`. Default `aria-label` is voice-neutral (`\"Step N of T: Label\"`) so non-AIKO consumers get a sensible SR announcement; AIKO surfaces pass an explicit override (`aria-label=\"AIKO is on Step 2 of 3, Review\"`). The `labels` variant also adds visually-hidden `(complete)` / `(current)` / `(pending)` text per stage so SR users get the full state without relying on icons.\n\nDistinct from `` (above): Stepper drives interactive multi-step flows with content panels + keyboard navigation; WizardStageIndicator is the read-only display of where the consumer state machine has the user. Pick Stepper when the user controls the step (walkthrough, recovery flow); pick WizardStageIndicator when consumer state controls the step and you want to surface \"where am I\" inline.\n\n#### `MessageRow`\n\n```tsx\nimport { MessageRow, AikoMark, Avatar } from \"@aisquare/pretty\";\n\n// User message — right-aligned bubble, soft primary tint\n \n\n// Assistant — left-aligned bare text, AIKO mark on the leading edge\n \n\n// Tool — left-aligned host for a ToolCard\n\n \n\n// System — full-width centered divider\nReturned to AIKO chat \n\n// Error — destructive surface with retry slot\n` inside `` rather than reaching for a custom surface.\n\n`senderName` renders a small label above the bubble — useful for multi-agent threads where distinguishing tool names or assistant personas matters. Supported on `assistant` and `tool` roles.\n\n#### `CollapsedMessageBody`\n\n```tsx\nimport { CollapsedMessageBody } from \"@aisquare/pretty\";\n\n// Short bodies pass through unchanged — no collapse chrome\n\n AIKO is ready. Ask me anything.\n \n\n// Long bodies collapse to a one-line headline + toggle\n\n {longAssistantMarkdown}\n \n\n// Override the auto-extracted headline\n\n {veryLongText}\n \n\n// Open by default\n\n {assistantReply}\n \n```\n\nInline collapse/expand for long chat message bodies. Bodies at or below `threshold` (default 280 chars) render children directly with no chrome — safe to drop in every `` without visible change for short replies. Above threshold, shows a one-line headline + `\"N+ more chars\"` toggle; body DOM is unmounted when collapsed so large off-screen trees stay light. Headline auto-extracted from children text content (strips markdown headers, takes first line, trims to 140 chars); override via `headline`. `aria-expanded` + `aria-controls` wire the toggle to the body region for screen readers.\n\n#### `ToolCard`\n\n```tsx\nimport { ToolCard, Markdown } from \"@aisquare/pretty\";\nimport { Search } from \"lucide-react\";\n\n// Live tool-call card — pending while running, auto-collapses on success\n{JSON.stringify({ q: \"ml\" }, null, 2)}}\n/>\n\n// Completed call — body collapsed by default, click to expand\nfile.pdf · 1.4 MB}\n result={permission denied}\n/>\n\n// Compact label-only row (no body sections — disclosure trigger disabled)\n` for the result and a `{JSON}` block for the args.\n\nDisclosure follows WAI-ARIA: trigger button has `aria-expanded` + `aria-controls`, body region has `aria-labelledby` pointing to the label cell. Body opens by default while pending or errored, collapsed once success lands so the assistant's reply stays the focus. Auto-collapses on the `pending → success` transition (uncontrolled mode); user clicks after that stick. Pass `defaultOpen` to override the heuristic, or `open` + `onOpenChange` for full control. `motion={false}` and `prefers-reduced-motion` skip the height animation and the pending pulse.\n\nComposition: drop inside `` for proper avatar-rail alignment within the chat scroller.\n\n#### `SuggestedReplies`\n\n```tsx\nimport { SuggestedReplies } from \"@aisquare/pretty\";\n\n composer.fill(text)}\n/>\n\n// Compact variant for tighter rails\n\n\n// Disable while AIKO is composing the next reply\n\n```\n\nPill-chip row that lives under the last assistant message. Two visual variants (`default` bordered pill on `bg-card`, `muted` flatter pill on `bg-muted`). `align=\"start\"` (default) or `\"end\"` for right-aligned rails. `disabled` dims every chip and blocks `onSelect`. Returns `null` for an empty `replies` array — drop in without an outer length guard. `role=\"group\"` with a default `aria-label=\"Suggested replies\"`. Default 24ms-staggered fade-in entrance; `motion={false}` and `prefers-reduced-motion` skip the stagger.\n\n#### `CitationRow`\n\n```tsx\nimport { CitationRow } from \"@aisquare/pretty\";\n\n// Inline anchor — drops between sentences with hover preview\n\n Climate science is broad\n
\n\n// Row variant — full card in a \"Sources\" list at the bottom of a message\n\n {message.referencedResources.map((r, i) => (\n openResource(r)}\n />\n ))}\n \n\n// asChild — slot through to a router Link\n\n \n \n```\n\nFootnote-style citation for resources cited in an assistant turn. Two variants for two render contexts: `anchor` (default) is an inline `[N]` chip that drops between sentences and reveals a Radix-Tooltip-anchored preview on hover/focus; `row` is the full card on its own line, used in a \"Sources\" list at the bottom of an assistant message. Both share the same content vocabulary — `index`, `title`, `summary?`, `thumbnail?` (URL or `ReactNode`), `badge?` (string or `ReactNode`).\n\nActivation: pass `onActivate` for click-to-open behavior, `href` for a real `` (so middle-click + cmd-click follow the URL natively), or both — `onActivate` wins on plain left-clicks; modifier-clicks fall through to the browser. `asChild` slots through to a custom anchor (a router ``, an analytics-instrumented wrapper). The anchor's accessible name defaults to `\"Citation N: \"`; override with `aria-label`.\n\nThe inline anchor is sized to drop into prose without breaking line height (`h-[18px]`, `text-[11px]`, `tabular-nums`). Tooltip Provider is self-contained — drop a `CitationRow` into any tree without setup.\n\n### Motion / delight\n\n#### `AnimatedCounter`\n\n```tsx\n<AnimatedCounter value={subscriberCount} />\n<AnimatedCounter value={revenue} format={(n) => `$${n.toFixed(2)}`} duration={1200} />\n```\n\nRespects `prefers-reduced-motion`.\n\n#### `Typewriter`\n\n```tsx\n<Typewriter\n phrases={[\"AI Studios.\", \"experiences.\", \"communities.\"]}\n typeSpeed={60}\n holdDuration={1800}\n/>\n```\n\nCycles through phrases with a typewriter effect. Reduced-motion shows the longest phrase statically.\n\n#### `TypewriterText`\n\n```tsx\nimport { TypewriterText } from \"@aisquare/pretty\";\n\n// Types one string to completion, then fires onDone\n<TypewriterText\n text=\"Your studio analytics are ready.\"\n speed={15} // ms per character (default 15)\n onDone={() => setStreaming(false)}\n/>\n\n// Key-remount to replay (common pattern for demos and retries)\n<TypewriterText key={replayKey} text={assistantFirstLine} />\n```\n\nOne-shot character-by-character type-out. Unlike `<Typewriter>` (phrase loop), this types a single string to completion and fires `onDone`. Designed for first-token streaming reveals in chat UIs. Blinking caret appears while typing, disappears when done. `prefers-reduced-motion` renders the full string immediately and fires `onDone` synchronously on mount. Remount via a `key` change to replay.\n\n#### `StaggeredText`\n\n```tsx\n<StaggeredText\n text=\"The platform is thinking\"\n by=\"word\" // \"char\" | \"word\"\n delay={60} // ms between staggered tokens\n shimmer // optional gradient sweep over each token\n/>;\n\n// Imperative: replay on a state change\nconst ref = useRef<StaggeredTextHandle>(null);\nref.current?.play();\nref.current?.reset();\n```\n\nAnimated text reveal — fade-in-stagger per char/word. Optional shimmer pass for AI-thinking surfaces. `aria-live` announces the full string at once for screen readers (no per-token noise). Reduced-motion renders text statically.\n\n#### `AnimatedList`\n\n```tsx\n<AnimatedList\n items={[\n { id: 1, content: \"Aiko's Studio is now live.\" },\n { id: 2, content: \"Daniel subscribed.\" },\n { id: 3, content: \"New comment on Quest #42.\" },\n ]}\n animationType=\"slide\"\n enterFrom=\"top\"\n hoverEffect=\"scale\"\n fadeEdges\n pauseOnHover\n height=\"320px\"\n/>\n\n// Bounded notification stack — older items fall off when maxItems is hit\n<AnimatedList\n items={notifications}\n autoAddDelay={4000}\n maxItems={5}\n swipeToDismiss\n onDismiss={(item) => analytics.dismiss(item.id)}\n renderItem={(item) => (\n <NotificationRow icon={item.content.icon} title={item.content.title} />\n )}\n/>\n```\n\nVertically-stacked list with motion-driven entrance / exit, optional auto-add cycling, swipe-to-dismiss, ripple/press click effects, and fade-edge masks. Adopted from React Bits Pro and adapted to pretty's anatomy — all hardcoded palette colors swapped for theme tokens (`bg-card`, `border-border`, `text-foreground`, `text-destructive`); `prefers-reduced-motion` collapses entrance / exit to instant transitions and falls back to fade for the bouncy spring animation; `forwardRef` on the wrapper for layout measurement. Use for the Studio Quick-Filter rail, Aiko notification stacks, recent-activity feeds, anywhere you want a list that _animates_ through state.\n\n#### `AnimatedContent`\n\n```tsx\n<AnimatedContent direction=\"vertical\" distance={80} delay={0.2}>\n <h2>Build experiences your audience trusts.</h2>\n</AnimatedContent>\n\n<AnimatedContent direction=\"horizontal\" reverse distance={120}>\n <FeatureBlock />\n</AnimatedContent>\n```\n\nScroll-triggered entrance — directional slide + optional scale + fade once the element crosses a viewport threshold. GSAP-powered. Adopted from React Bits OSS and adapted to pretty's anatomy: `forwardRef`, `cn` for className merge, `window` as the default scroll target (the upstream's hardcoded `snap-main-container` lookup is gone). `prefers-reduced-motion` paints the final state immediately and still fires `onComplete` so consumer state machines resolve. Optional `disappearAfter` hides the element on a timer once revealed. Requires the `gsap` peer-optional dep.\n\n#### `FadeContent`\n\n```tsx\n<FadeContent duration={0.8} delay={0.1} blur>\n <p>Numbers tell the story.</p>\n</FadeContent>\n```\n\nThe quieter sibling — pure opacity ramp (with optional blur ramp) on scroll-into-view. Same anatomy + reduced-motion handling as AnimatedContent. Use when \"this section just slid into view\" is the right read but you don't want directional movement or scale. All time props (`duration`, `delay`, `disappearAfter`) are seconds — pretty unified them since the upstream's mixed ms/s heuristic was ambiguous. Requires the `gsap` peer-optional dep.\n\n#### `FeatureTabs`\n\n```tsx\nimport { FeatureTabs, type FeatureTab } from \"@aisquare/pretty\";\nimport { Layers, Sparkles, Bot } from \"lucide-react\";\n\nconst tabs: FeatureTab[] = [\n { value: \"designers\", label: \"Designers\", icon: <Layers />, content: <DesignersPane /> },\n { value: \"builders\", label: \"Builders\", icon: <Sparkles />, content: <BuildersPane /> },\n { value: \"audience\", label: \"Audience\", icon: <Bot />, content: <AudiencePane /> },\n];\n\n<FeatureTabs tabs={tabs} defaultValue=\"designers\" />;\n```\n\nPersona-card tab selector with an animated radial-gradient indicator that slides between active triggers, plus motion-driven content fade-up on swap. Adopted from `@reactbits-pro/features-9`. Composes `@radix-ui/react-tabs` underneath for full keyboard navigation (`←` / `→` between triggers, `Home` / `End`, `Enter` / `Space` activate), `role=\"tablist\"` / `role=\"tab\"` / `role=\"tabpanel\"` semantics, and ARIA wiring out of the box. Active-card halo uses `--accent` so the indicator follows per-studio brand retinting via `<StudioBrand>`. Reduce-motion users get an instant snap. Use for marketing landing sections (hero · personas · features grid), studio dashboard \"switch the active workspace lens\" patterns, or any consumer-facing surface that needs a top-row category selector with animated content swap. The `examples/playground` itself is built on this primitive.\n\n#### `MorphingRail` / `MorphingRailStage`\n\n```tsx\nimport { MorphingRail, MorphingRailStage } from \"@aisquare/pretty\";\n\n// The dock — a stack of morphing circles (parked items / quick switcher).\n<MorphingRail\n items={items} // [{ id, icon, label, accentColor? }]\n activeId={activeKey} // optional — which one is currently in the stage\n onSelect={(id) => restore(byId[id])}\n onDismiss={(id) => dismiss(byId[id])}\n morphGroup=\"experience\"\n/>\n\n// The stage wrapper — same morphGroup, the active item's id.\n<MorphingRailStage morphGroup=\"experience\" morphId={activeKey}>\n <YourFullStageContent />\n</MorphingRailStage>\n```\n\nPaired primitive that morphs an item between a tile in a side rail and a full stage panel via Framer `layoutId`, with macOS-dock-style cursor magnification on the rail side. Designed to replace hand-rolled morphs that animate `flexGrow` / `flexBasis` on the stage container — a layout-trigger that fights Framer's FLIP and re-paints heavy children (chat / video / markdown stages) every frame. `MorphingRailStage` is transform-only on enter / exit (`opacity` and `scale`) and applies `contain: paint` so the inner content does not get re-rasterised mid-morph; `MorphingRail` mirrors the FLIP from the dock side using the same `layoutId`. Both halves share the namespace via `morphGroup`, and the rail item id must match the stage's `morphId`. Item silhouette is configurable (`shape: \"circle\" | \"rounded\" | \"square\"`, default `rounded` so it reads consistently with rounded-square dock buttons). Items pass an `accentColor` (6-digit hex) and the dock auto-tints the tile background (~15% alpha) and border (~40%); fall back to `accentClassName` when the consumer's accent is a CSS variable rather than a hex. Cursor magnification (adapted from React Bits Pro `navigation-4`) tracks `mouseY` / `mouseX` against each tile's center via `useTransform` + `useSpring` (mass 0.1, stiffness 150, damping 12) and lifts the tile under the cursor to ~1.2× — disable per-instance with `magnify={false}` when the dock should stay static. Toolbar semantics (`role=\"toolbar\"`, `aria-pressed` on the active tile), per-tile `<AikoTooltip>` on the off-axis side, optional sibling dismiss button shown on hover / focus with a 90° rotate-on-hover X. Each restore button carries `data-morph-id={item.id}` so consumers can re-focus across the morph (the rail and the stage live in different parts of the React tree, so DOM focus does not survive a swap on its own — wire a small `requestAnimationFrame` re-focus when the consumer needs it). Honors `prefers-reduced-motion` — collapses both the FLIP and the magnify to instant. Self-wraps `<TooltipProvider>`. Drop-in for AIStudio v3's `ExperienceBubble` + the `motion.div` wrapper around `CenterStage`.\n\n#### `SpotlightCard`\n\n```tsx\nimport { SpotlightCard } from \"@aisquare/pretty\";\n\n<SpotlightCard intensity=\"default\" color=\"primary\">\n <h3>Aiko's Studio</h3>\n <p className=\"text-muted-foreground\">Live now</p>\n</SpotlightCard>;\n```\n\nSurface wrapper with a cursor-following radial-glow overlay, adopted from React Bits Pro `@reactbits-starter/spotlight-card-tw`. Glow color drives from theme tokens (`--primary` / `--accent` / `--secondary`) so per-studio brand retinting via `<StudioBrand>` flows through automatically — never a hardcoded hex. `intensity` (`subtle` / `default` / `strong`) scales the gradient opacity; `radius` and `padding` variants drop the chrome into common card silhouettes; `spread` (default 400px) tunes the gradient radius. Reduce-motion users get a centered static glow on hover instead of live cursor tracking — the affordance stays, the motion stops. SSR-safe (no `window` at module scope), `forwardRef<HTMLDivElement>` for layout measurement. Use for Quest cards, studio tile grids, featured-experience cards, and Aiko nudge surfaces where the spotlight reads as \"the assistant is paying attention to where you are.\" Wrap interactive elements (Link, button) inside, not around — `asChild` is intentionally a v2 concern (the two-layer overlay structure doesn't collapse cleanly into a single Slot child).\n\n#### `BorderGlow`\n\n```tsx\nimport { BorderGlow } from \"@aisquare/pretty\";\n\n<BorderGlow color=\"primary\" intensity=\"default\">\n <StudioCard />\n</BorderGlow>;\n\n// Asymmetric color — semantic statuses\n<BorderGlow color=\"success\" intensity=\"subtle\" pulse={false}>\n <PlanCard tier=\"active\" />\n</BorderGlow>;\n\n// Slot onto a Link — outer element is the anchor\n<BorderGlow color=\"warning\" asChild>\n <a href=\"/upgrade\">Upgrade</a>\n</BorderGlow>;\n```\n\nSteady or breathing halo around a surface's perimeter — sibling to the internal `<BorderBeam>` (sweeping arc on `<Badge variant=\"premium\">`). `intensity` (`subtle` / `default` / `strong`) scales spread / blur / alpha; `color` (`primary` / `accent` / `success` / `warning`) drives the halo from `hsl(var(--token) / X)` so per-studio retinting via `<StudioBrand>` cascades through automatically. `pulse` defaults to `true` and reuses the preset's `animate-pulse-glow` keyframe by overriding `--shadow-glow` + `--shadow-glow-aurora` per instance — one keyframe drives every color × intensity combination. Reduce-motion users get a static halo (the affordance stays visible; the breathing stops). `asChild` slots the glow onto a `<Link>` / `<button>` / etc. via Radix Slot. Composes with `<BorderBeam>` on the same host element for a \"premium + active\" combination — beam sweeps the perimeter, glow is the steady backdrop. Use for active studio rail cards, subscribed-state community cards, Aiko nudge surfaces (\"I'm here, paying attention\"), and premium / upgrade prompts.\n\n#### `Stepper`\n\n```tsx\nimport { Stepper } from \"@aisquare/pretty\";\n\n// Self-rendering — pass steps + (optional) per-step content\n<Stepper\n steps={[\n { label: \"Vault\", description: \"Where uploads land\" },\n { label: \"Publish\", description: \"One click to ship\" },\n { label: \"Analytics\", description: \"See who's tuned in\" },\n ]}\n defaultValue={0}\n onComplete={() => closeWalkthrough()}\n/>;\n\n// Headless — render-prop owns the layout (content panel + footer buttons)\n<Stepper steps={steps} value={step} onValueChange={setStep}>\n {({ step, total, next, prev, complete }) => (\n <footer className=\"flex justify-between gap-3 mt-4\">\n <Button variant=\"ghost\" onClick={prev} disabled={step === 0}>\n Back\n </Button>\n <Button onClick={step === total - 1 ? complete : next}>\n {step === total - 1 ? \"Done\" : \"Next\"}\n </Button>\n </footer>\n )}\n</Stepper>;\n```\n\nMulti-step indicator with optional content panel + WAI-ARIA tablist keyboard navigation. Drives multi-step flows (first-run walkthroughs, quest authoring tutorials, paywall onboarding, Aiko-led recovery) that previously lived as ad-hoc `useState({ step: 0..3 })` per surface. Variants: `orientation` (`horizontal` / `vertical`), `size` (`sm` / `default` / `lg`), `indicator` (`numbers` / `dots` / `progress`). Controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`) modes; `interactive: false` swaps `role=\"tablist\"` for `role=\"progressbar\"` so display-only flows pick up the right ARIA shape automatically. Keyboard nav follows the WAI-ARIA tablist pattern: ← / → for horizontal, ↑ / ↓ for vertical, Home / End. Reduce-motion users get an instant step transition. The render-prop slot is the composition seam for `<AikoTip>` integration: `<AikoTip body={<Stepper steps={...}>{({ next }) => ...}</Stepper>}>` plumbs Aiko-led multi-step recovery without prop-drilling.\n\n### Aiko (brand mascot + helper surfaces)\n\nThe AISquare AI assistant lives across these primitives. They share a single visual anatomy (paper-shell silhouette, breathing AikoMark, anti-intrusion contract) and one mental model: the platform has a personality, and it shows up where it can help.\n\n#### `AikoMark`\n\n```tsx\n<AikoMark size=\"md\" />\n<AikoMark size=\"2xl\" animated={false} /> // resting frame\n<AikoMark aria-label=\"AISquare assistant\" /> // announce; otherwise decorative\n```\n\nThe brand mascot. One file, single source of truth — every Aiko surface (Tip, Sheet, Whisper, Loader, marketing) composes this. Sizes: `xs / sm / md / lg / xl / 2xl` (24 / 28 / 32 / 40 / 56 / 80 px). Honors `prefers-reduced-motion` (resting frame). To change Aiko's look across the whole platform, edit only `AikoMark.tsx`.\n\n#### `AikoTip`\n\n```tsx\n<AikoTip\n trigger=\"click\" // \"click\" | \"hover\"\n variant=\"rail\" // label | info | single | rail | pages | pages-passive\n title=\"Recall lives across chats\"\n body=\"Aiko remembers the last 50 turns to keep context tight.\"\n actions={[\n { label: \"Got it\", primary: true },\n { label: \"Snooze 30 min\", onClick: snooze },\n ]}\n>\n <Button variant=\"outline\">What's recall?</Button>\n</AikoTip>\n```\n\nThe Aiko helper bubble. Six content silhouettes share one paper shell + breathing AikoMark. Built on Radix Popover so positioning, focus, ESC, and click-outside are handled. Drop-in replacement for traditional tooltips when the helper has personality + content + (optionally) actions. `trigger=\"hover\"` makes it a label-style tooltip instead of a click-to-open popover.\n\n#### `AikoTooltip`\n\n```tsx\n<AikoTooltip body=\"Save\"> // → minimal: no mark, light shell\n <IconButton onClick={save} />\n</AikoTooltip>\n\n<AikoTooltip body=\"This will permanently delete the experience.\"> // → full: branded card with mark\n <IconButton onClick={remove} />\n</AikoTooltip>\n\n<AikoTooltip title=\"Save\" body=\"Saves and exits the editor\" side=\"right\"> // → full (header)\n <IconButton />\n</AikoTooltip>\n\n<AikoTooltip body=\"Save\" tone=\"full\"> // pin full when the heuristic guesses wrong\n <IconButton />\n</AikoTooltip>\n```\n\nThe drop-in replacement for shadcn-style `<Tooltip><TooltipTrigger><TooltipContent>` compositions. The visual treatment auto-adapts via the `tone` heuristic: short string body, no title → light label-style tooltip; longer body, JSX node, or `title` → branded paper card with the AikoMark. Brand the act, not the chrome — short button labels stay quiet so substantive AIKO comms stand out. Override with `tone=\"full\" | \"minimal\"` when you need to pin a style. Hover-only — for click-to-open helpers reach for `<AikoTip>` directly. Built on Radix Tooltip so the consumer's `<TooltipProvider>` configures cross-tooltip delay-skipping and free `aria-describedby` wiring. Default `delayDuration={400}` aligns with industry norms (Linear ≈500, GitHub ≈400) so cursor-traversal doesn't trigger noise.\n\n#### `AikoHint`\n\n```tsx\n<AikoHint title=\"Why this matters\" body=\"One sentence. Aiko keeps it brief.\" />\n\n<AikoHint\n title=\"Heads up\"\n body=\"This will overwrite the current draft.\"\n actions={[{ label: \"Got it\" }]}\n channelId=\"form.experience-name\"\n/>\n```\n\nSmall Aiko mark that teases on hover and reveals on click. Hover (120ms delay) shows a tiny label tip with the `teaser` text (default `\"Aiko has a tip\"`). Click opens a fuller info card with title + body + optional actions. Use to replace always-visible \"subtext\" / `FormDescription` patterns where the explanation should be one click away — quiet by default, informative on demand. Built on Radix Popover. Honors the [anti-intrusion contract](./docs/contracts/aiko-intrusion.md) when `channelId` is set + wrapped in `<AikoProvider>`.\n\n#### `AikoWhisper` / `AikoNudge` / `AikoIntervene`\n\n```tsx\nconst ref = useRef<HTMLButtonElement>(null);\nconst aiko = useAikoSignal(\"checkout.confused\");\n\nuseAikoDwellSignal(ref, { channelId: \"checkout.confused\", ms: 2000 });\nuseAikoRageClickSignal(ref, { channelId: \"checkout.confused\", threshold: 3 });\n\n<Button ref={ref}>Submit order</Button>;\n<AikoWhisper anchorRef={ref} open={aiko.canShow && aiko.level === \"whisper\"}\n channelId=\"checkout.confused\" onExpand={() => aiko.signal(\"rage-click\")}\n previewText=\"Aiko has a hint. Click to see it.\" />\n<AikoNudge anchorRef={ref} open={aiko.canShow && aiko.level === \"nudge\"}\n channelId=\"checkout.confused\">\n Looks confusing — try <em>refreshing your library</em>.\n</AikoNudge>\n<AikoIntervene anchorRef={ref} open={aiko.canShow && aiko.level === \"intervene\"}\n channelId=\"checkout.confused\" title=\"Need a hand?\" body=\"...\"\n primaryAction={{ label: \"Try this\", onClick: fix }} />\n```\n\nThe three escalation surfaces (Phase 3). Whisper is a tiny breathing pip; Nudge is a one-line balloon; Intervene is a full helper card. Drive `open` from `useAikoSignal(channelId).level`. All three honor the [anti-intrusion contract](./docs/contracts/aiko-intrusion.md) — closing fires `dismiss()` which snoozes 30 min, three dismisses → silent for the session, mute persists.\n\n`AikoWhisper`'s optional `previewText` opens a paper-shelled `AikoTip` (label variant) on hover/focus — progressive disclosure without committing to escalation.\n\n#### `AikoProvider` + signal hooks\n\n```tsx\nimport {\n AikoProvider,\n useAiko,\n useAikoChannel,\n useAikoSignal,\n useAikoDwellSignal,\n useAikoRageClickSignal,\n useAikoHoverLoopSignal,\n} from \"@aisquare/pretty\";\n\n// Wrap once near app root\n<AikoProvider snoozeMinutes={30} sessionDismissThreshold={3}>\n <App />\n</AikoProvider>;\n\n// Read or control any channel\nconst channel = useAikoChannel(\"library.refresh-tip\");\nchannel.canShow; // false if muted, snoozed, or session-silent\nchannel.dismiss(); // counts as one dismiss\nchannel.snoozeFor(60_000);\nchannel.mute(); // until unmute()\nchannel.reset();\n\n// Detect intent → drive the level state machine\nconst sig = useAikoSignal(\"library.refresh-tip\");\nsig.level; // \"off\" | \"whisper\" | \"nudge\" | \"intervene\"\nsig.signal(\"rage-click\"); // user-triggered escalation\nsig.resetLevel();\n\n// Auto-detectors — point at any element ref\nuseAikoDwellSignal(ref, { channelId: \"...\", ms: 2000 });\nuseAikoRageClickSignal(ref, { channelId: \"...\", threshold: 3, windowMs: 1500 });\nuseAikoHoverLoopSignal(ref, { channelId: \"...\", loopThreshold: 3 });\n```\n\nThe state machine + persistence layer behind every Aiko surface. Provider owns per-channel mute/snooze/session-dismiss-count; hooks expose typed read/write APIs. Detectors translate user behavior (long hover, rage-click, hover loops) into level escalations without you wiring it. Full anti-intrusion contract spec at [`docs/contracts/aiko-intrusion.md`](./docs/contracts/aiko-intrusion.md).\n\n### Theming\n\n#### `ThemeProvider`\n\n```tsx\nimport { ThemeProvider, useTheme } from \"@aisquare/pretty\";\n\n<ThemeProvider defaultTheme=\"system\" storageKey=\"aisquare-theme\">\n <App />\n</ThemeProvider>;\n```\n\nAdds `light` or `dark` to `<html>`, persists the choice in `localStorage`, and follows the OS `prefers-color-scheme` when set to `\"system\"`. Read or change inside the tree:\n\n```tsx\nconst { theme, resolvedTheme, setTheme } = useTheme();\n<Button onClick={() => setTheme(resolvedTheme === \"dark\" ? \"light\" : \"dark\")}>Switch</Button>;\n```\n\nFor zero-flash apps (Next.js, Remix, Astro), inline the script in `<head>`:\n\n```tsx\nimport { getThemeScript } from \"@aisquare/pretty\";\n<script dangerouslySetInnerHTML={{ __html: getThemeScript() }} />;\n```\n\n#### `StudioBrand`\n\nPer-studio brand cascade. Sets CSS vars on a wrapper so every primitive inside inherits the studio's brand, with no per-primitive code change.\n\n```tsx\n<StudioBrand\n primary=\"280 70% 50%\"\n accent=\"220 80% 60%\"\n radius=\"14px\"\n font=\"'Geist Sans', sans-serif\"\n>\n <Button>Visit studio</Button>\n</StudioBrand>\n```\n\nTwo studios side-by-side stay scoped:\n\n```tsx\n<div className=\"grid grid-cols-2\">\n <StudioBrand primary=\"280 70% 50%\">\n <App />\n </StudioBrand>\n <StudioBrand primary=\"14 90% 55%\">\n <App />\n </StudioBrand>\n</div>\n```\n\nColor values accept HSL triplets (`\"280 70% 50%\"`) or wrapped strings (`\"hsl(280 70% 50%)\"`); both work. Use `vars` to set arbitrary CSS variables (`--shadow-glow`, custom tokens). Use `asChild` to apply the brand to your own element with no extra wrapper. Composes with `ThemeProvider`: light/dark applies globally, brand vars override locally.\n\n---\n\n### Office surface primitives (iter-37-F2)\n\nSeven primitives for the AISquare Office multi-agent collaboration surface. All compose existing pretty primitives where possible.\n\n#### `RailItem`\n\nLeft-rail session navigation row. Composes `SlugTag` + `CornerMark` + `PulseDot`.\n\n```tsx\nimport { RailItem } from \"@aisquare/pretty\";\n\n<RailItem slug=\"api-stabilization\" hue=\"#1F8A5B\" status=\"open\" unread={3} summary=\"v2 contract\" />\n<RailItem slug=\"auth-refactor\" hue=\"#D97757\" status=\"stuck\" active />\n<RailItem slug=\"init\" status=\"sealed\" sealed />\n```\n\n#### `PaneHeader`\n\nCenter-pane top-section layout shell (23px/700 title + status + summary + actions slots).\n\n```tsx\nimport { PaneHeader, Tag, Pill } from \"@aisquare/pretty\";\n\n<PaneHeader\n title=\"#api-stabilization\"\n status={<Tag label=\"OPEN\" tone=\"success\" />}\n summary=\"Stabilise the v2 API contract.\"\n actions={<Pill label=\"stuck\" tone=\"destructive\" appearance=\"solid\" />}\n/>\n```\n\n#### `OfficeMsg` + sub-components\n\nOffice-specific message row. Distinct from `MessageRow` (role-based): sender identity expressed via SlugTag hue + 2px hue left-rail.\n\n```tsx\nimport { OfficeMsg, OfficeMsgTimestamp, OfficeMsgSender, OfficeMsgBody, ThreadRow } from \"@aisquare/pretty\";\n\n<OfficeMsg slug=\"founder-0\" hue=\"#D97757\" ts=\"09:55\" isOwner>\n Synthesis complete. Proposing lock.\n</OfficeMsg>\n<OfficeMsg slug=\"founder-9\" hue=\"#1F8A5B\" ts=\"09:57\" selfFlag=\"force-analysis\"\n thread={{ replyCount: 3, status: \"open\", loaded: [\"f0\"] }}>\n Tests pass.\n</OfficeMsg>\n```\n\n#### `F0Card`\n\nFounder-0 lock-proposal decision card. cardChrome(coral) surface with 4px left-bar and optional worklog row.\n\n```tsx\nimport { F0Card } from \"@aisquare/pretty\";\n\n<F0Card\n ts=\"10:01\"\n body=\"api-stabilization is locked.\"\n worklog={{ id: \"w24-032\",","readmeFilename":"README.md"}
` wrapper when the accordion lives inside an existing heading hierarchy.\n\n#### `GlassInputFrame`\n\n```tsx\nimport { GlassInputFrame, ChatInput } from \"@aisquare/pretty\";\n\n// Wrap any composer in the gradient ring\n\n \n\n// Literal blue-purple-indigo from AIStudio-v3 (theme-exempt)\n\n \n\n// Or use ChatInput's built-in shorthand\n\n \n \n \n \n Useful hint \n \n \n```\n\nWrap your app once with ``, reuse Tooltip everywhere.\n\n#### `SmoothScroll`\n\n```tsx\n// Sub-entry import — SmoothScroll lives behind its own path so the main\n// barrel never references the optional `lenis` peer (#93).\nimport { SmoothScroll, useLenis } from \"@aisquare/pretty/smooth-scroll\";\n\n// Wrap once near the app root\n\n \n\n// Disable inside surfaces where smooth scroll fights inputs (e.g. editors)\n... \n\n// Read the active Lenis instance for advanced cases\nfunction ProgressBar() {\n const [progress, setProgress] = useState(0);\n useLenis((lenis) => setProgress(lenis.progress));\n return ;\n}\n```\n\nLenis-powered smooth scroll. Honors `prefers-reduced-motion` automatically (silently degrades to native scroll). Pair with `useScrollProgress` for scroll-linked motion. Opting in to this primitive is the only path that pulls `lenis` into your bundle — consumers who don't import from `@aisquare/pretty/smooth-scroll` don't need `lenis` installed at all.\n\n#### `Toaster` + `aiko`\n\n```tsx\nimport { Toaster, aiko } from \"@aisquare/pretty\";\n\n// near app root\n`. Ported from `AISquare-AIStudio-v3 AikoChat.tsx` for drop-in parity. Shares the same animation engine, reduced-motion handling, and `role=\"status\"` a11y contract. `size` prop uses Studio-v3's `sm | md` vocabulary and maps to `TypingIndicator`'s `sm | default`. For surfaces that already use `TypingIndicator`, prefer that directly; use `ThinkingDots` when migrating v3 code that referenced the local component by this name.\n\n#### `AikoLoader`\n\n```tsx\n\n \n \n\n\n {draft}
\n \n\n\n {draft}
// dim only, no glide\n \n\n\n // borderless surface override\n \n```\n\nBlock-level \"AIKO is editing this\" cue. While `loading` is true, children dim to muted ink and a skewed gradient beam glides across the wrapper at `speed` seconds per cycle (default `1.1`); when false, the wrapper is a plain pass-through. `aria-busy={loading}` is the screen-reader signal. `motion={false}` and `prefers-reduced-motion` both drop the beam — the dim + aria-busy stay so the cue persists. Pair with `` for inline chat-row \"composing\" states; reach for `EditingBeam` when AIKO is rewriting a whole field, title, or paragraph.\n\n#### `Skeleton`\n\n```tsx\n\n```\n\n### Content (images, markdown, media chrome)\n\n#### `Image`\n\n```tsx\nimport { Image } from \"@aisquare/pretty\";\n\n analytics.imageFailed(experience.id)}\n aspectRatio=\"4/3\"\n rounded=\"lg\"\n className=\"w-full\"\n/>\n\n![]()
` that owns the loading skeleton, one-shot fallback retry, error chrome, and CLS-prevention slot. Native `loading=\"lazy\"` by default; flips to `eager` + `fetchpriority=\"high\"` when `priority` is set. `aspectRatio` (`\"16/9\"`, `\"1/1\"`, etc.) forwards to CSS `aspect-ratio` on the wrapper. `rounded` cva variant: `none / sm / default / lg / full`.\n\nComposition: `errorContent` slot replaces the default error chrome; `fallbackSrc` provides one-shot retry. `onError` fires AFTER the internal retry, so consumer-side multi-step fallback chains keep working — the primitive resyncs when `src` changes.\n\nA11y: `aria-busy=\"true\"` during load, `role=\"img\" aria-label={errorLabel}` on error (suppressed for decorative `alt=\"\"` images). Honors `prefers-reduced-motion` automatically (load crossfade collapses to instant).\n\n#### `Markdown`\n\n```tsx\nimport { Markdown } from \"@aisquare/pretty\";\n\n {\n if (href?.startsWith(\"#resource:\")) return {children} ;\n return {children};\n },\n }}\n/>\n```\n\nSealed renderer for chat-aligned markdown. GFM (tables, strikethrough, task lists, autolinks), soft line breaks, sanitized HTML with `language-*` className preserved on code, syntax-highlighted fenced blocks (`react-syntax-highlighter` + Prism + `oneDark`), copy buttons, inline code in `bg-muted`, scrollable tables, and new-tab anchors. Empty / whitespace-only `content` returns `null`.\n\nComposition seam is the `components` prop — type `Partial` from `react-markdown`, shallow-merged with the primitive's defaults. Use it to intercept specific element renderers (most commonly `a` for app-specific routing); everything else stays default. There is no `asChild` — `` renders content from a string, not a child element.\n\nStreaming chat: pass `streaming` to render an inline-block blinking caret as the last child of the prose container — pulses while live tokens arrive, disappears the moment you flip the prop:\n\n```tsx\n` for the pre-first-token gap. The cursor honors `prefers-reduced-motion` (steady block instead of pulse) and is `aria-hidden` so screen readers aren't bombarded with \"blinking\" chatter — the streaming cue comes from the consumer's `aria-live` region (typically ``). Re-renders during streaming are cheap thanks to `React.memo` + `forwardRef` for direct ref access to the prose container.\n\nThe rehype-sanitize schema extension that allows `language-*` className is exported as `markdownSanitizeSchema` for consumers who need to extend it further.\n\n#### `Truncate`\n\n```tsx\nimport { Truncate } from \"@aisquare/pretty\";\n\n{customUrl} // 1-line ellipsis ()\n{description} // 2-line clamp\n // override body for icon children\n \n \n```\n\nTruncates text at N lines AND auto-renders an `` showing the full text only when overflow is actually present. Drops the need for consumers to plumb `useIsTruncated` state into a tooltip themselves. `lines={1}` (default) maps to Tailwind `truncate`; `lines={2|3|4}` maps to `line-clamp-{n}`. Polymorphic via `as` (default `\"span\"`).\n\nTooltip semantics: when `children` is a string or number, that's the default tooltip body. When children is a non-string ReactNode, pass `tooltipBody` explicitly to opt in (we don't stringify arbitrary nodes). `disableTooltip` skips the wrapper entirely. The wrapper stays mounted across resize-driven truncation flips with `open={false}` pinned when not truncated, so transient resizes don't remount the trigger child.\n\nSSR-safe: ResizeObserver gated behind `useIsomorphicLayoutEffect`, so server-rendered markup is just the bare element with truncation classes; the tooltip wrap evaluates after first client measurement.\n\nFor 1-line truncation to take effect, the parent should be a flex container with `min-w-0` (or any block parent with constrained width) — same constraint as raw `truncate`. Multi-line clamp needs no parent constraint. Requires `` at the app root (per ``).\n\n### Chat anatomy\n\n#### `ChatLog`\n\n```tsx\nimport { ChatLog, MessageRow, ScrollToBottomButton, useScrollToBottom } from \"@aisquare/pretty\";\n\nfunction ChatScroller({ messages, loadOlder, isLoadingOlder, unreadCount }) {\n const { scrollRef, sentinelRef, isAtBottom, scrollToBottom } = useScrollToBottom<\n HTMLDivElement,\n HTMLDivElement\n >();\n\n return (\n \n \n \n ))}\n \n \n scrollToBottom()}\n />\n \n );\n}\n```\n\nScroll container for a conversation of `` children. Owns the right CSS for an append-only chat surface — vertical overflow with `scrollbar-gutter: stable` so chip rows don't jiggle, and `overflow-anchor: auto` so newly-rendered messages don't yank the user's reading position. Two density variants — `comfortable` default and `compact` for tighter rails.\n\n`onLoadOlder` adds a 1px top sentinel that fires the callback once when scrolled into view (rate-limited to 250ms so layout shifts don't double-fire). `isLoadingOlder` surfaces an AIKO-voiced \"Loading earlier messages\" status row above the messages and latches the sentinel to prevent re-firing during the load. `loadingOlderLabel` overrides the copy.\n\n`empty` slot renders when `children` is null / undefined / false / an empty array — drop in an `` for the pre-first-message moment.\n\nForwards `ref` to the scroll container so you can wire `useScrollToBottom`'s `scrollRef` directly. Virtualization-friendly: a single overflow scroller with a flat children stack means `react-virtuoso` / `@tanstack/react-virtual` can wrap without structural change.\n\n#### `ScrollToBottomButton` + `useScrollToBottom()`\n\n```tsx\nimport { ScrollToBottomButton, useScrollToBottom } from \"@aisquare/pretty\";\n\nfunction ChatScroller({ messages, unreadCount }) {\n const { scrollRef, sentinelRef, isAtBottom, scrollToBottom } = useScrollToBottom<\n HTMLDivElement,\n HTMLDivElement\n >();\n\n return (\n \n {messages.map((m) => (\n scrollToBottom()}\n />\n \n );\n}\n```\n\nThe hook owns `IntersectionObserver`-based at-bottom detection plus a `scrollToBottom({ smooth })` action. The button is the visible \"Jump to latest\" affordance — absolutely positioned by default (`absolute bottom-3 left-1/2 -translate-x-1/2 z-10`), so wrap it inside a `position: relative` scroller. Override placement via `className` for sidebar / right-aligned use cases.\n\n`unreadCount` renders a small badge in the top-right corner (\"3\", \"99+\"). The label folds into `aria-label` so SR users hear \"Jump to latest, 3 unread\". Default 180ms fade+slide entrance; `motion={false}` and `prefers-reduced-motion` skip it.\n\nFor non-default content (e.g. a `Clear\n }\n/>\n```\n\n\"AIKO knows you're on X\" banner that signals which scope the agent has loaded. Three slots — `lead` (conventionally ``), `context` (the label, single-line truncated), `actions` (Clear / Edit / Exit-experience). Two variants — `default` bordered card surface, `muted` flatter pill.\n\nThe primitive renders as a regular block-level element. Sticky behavior is the consumer's call — wrap with `sticky top-0 z-10` to ride the scroller. `role=\"status\"` + `aria-live=\"polite\"` so screen readers announce scope changes; `aria-label` infers from `context` when it's a string, otherwise falls back to `\"Chat context\"` (override per surface). Default 240ms fade+slide-down entrance; `motion={false}` and `prefers-reduced-motion` skip it.\n\n#### `WizardStageIndicator`\n\n```tsx\nimport { WizardStageIndicator, ContextBar, AikoMark } from \"@aisquare/pretty\";\n\n\n\n// Composing inside :\n` (in the `actions` slot) so AIKO's loaded scope can show stage progression without bespoke per-page UI. Two variants — `compact` (default — dots + \"Step N of T · Label\" line; fits inside ContextBar) and `labels` (full breadcrumb with completed / current / pending icons + connectors; suitable for page headers).\n\nStages accept `string[]` for ergonomics or `{id, label}[]` when you need stable ids for `current` lookup. `current` accepts a 0-based index OR a stage id (string); out-of-range numbers clamp, unknown ids fall back to 0. Returns `null` on empty stages — no need to gate at the call site.\n\nA11y: `role=\"progressbar\"` with `aria-valuenow` / `aria-valuemax` / `aria-valuemin` / `aria-label`. Default `aria-label` is voice-neutral (`\"Step N of T: Label\"`) so non-AIKO consumers get a sensible SR announcement; AIKO surfaces pass an explicit override (`aria-label=\"AIKO is on Step 2 of 3, Review\"`). The `labels` variant also adds visually-hidden `(complete)` / `(current)` / `(pending)` text per stage so SR users get the full state without relying on icons.\n\nDistinct from `` (above): Stepper drives interactive multi-step flows with content panels + keyboard navigation; WizardStageIndicator is the read-only display of where the consumer state machine has the user. Pick Stepper when the user controls the step (walkthrough, recovery flow); pick WizardStageIndicator when consumer state controls the step and you want to surface \"where am I\" inline.\n\n#### `MessageRow`\n\n```tsx\nimport { MessageRow, AikoMark, Avatar } from \"@aisquare/pretty\";\n\n// User message — right-aligned bubble, soft primary tint\n \n\n// Assistant — left-aligned bare text, AIKO mark on the leading edge\n \n\n// Tool — left-aligned host for a ToolCard\n\n \n\n// System — full-width centered divider\nReturned to AIKO chat \n\n// Error — destructive surface with retry slot\n` inside `` rather than reaching for a custom surface.\n\n`senderName` renders a small label above the bubble — useful for multi-agent threads where distinguishing tool names or assistant personas matters. Supported on `assistant` and `tool` roles.\n\n#### `CollapsedMessageBody`\n\n```tsx\nimport { CollapsedMessageBody } from \"@aisquare/pretty\";\n\n// Short bodies pass through unchanged — no collapse chrome\n\n AIKO is ready. Ask me anything.\n \n\n// Long bodies collapse to a one-line headline + toggle\n\n {longAssistantMarkdown}\n \n\n// Override the auto-extracted headline\n\n {veryLongText}\n \n\n// Open by default\n\n {assistantReply}\n \n```\n\nInline collapse/expand for long chat message bodies. Bodies at or below `threshold` (default 280 chars) render children directly with no chrome — safe to drop in every `` without visible change for short replies. Above threshold, shows a one-line headline + `\"N+ more chars\"` toggle; body DOM is unmounted when collapsed so large off-screen trees stay light. Headline auto-extracted from children text content (strips markdown headers, takes first line, trims to 140 chars); override via `headline`. `aria-expanded` + `aria-controls` wire the toggle to the body region for screen readers.\n\n#### `ToolCard`\n\n```tsx\nimport { ToolCard, Markdown } from \"@aisquare/pretty\";\nimport { Search } from \"lucide-react\";\n\n// Live tool-call card — pending while running, auto-collapses on success\n{JSON.stringify({ q: \"ml\" }, null, 2)}}\n/>\n\n// Completed call — body collapsed by default, click to expand\nfile.pdf · 1.4 MB}\n result={permission denied}\n/>\n\n// Compact label-only row (no body sections — disclosure trigger disabled)\n` for the result and a `{JSON}` block for the args.\n\nDisclosure follows WAI-ARIA: trigger button has `aria-expanded` + `aria-controls`, body region has `aria-labelledby` pointing to the label cell. Body opens by default while pending or errored, collapsed once success lands so the assistant's reply stays the focus. Auto-collapses on the `pending → success` transition (uncontrolled mode); user clicks after that stick. Pass `defaultOpen` to override the heuristic, or `open` + `onOpenChange` for full control. `motion={false}` and `prefers-reduced-motion` skip the height animation and the pending pulse.\n\nComposition: drop inside `` for proper avatar-rail alignment within the chat scroller.\n\n#### `SuggestedReplies`\n\n```tsx\nimport { SuggestedReplies } from \"@aisquare/pretty\";\n\n composer.fill(text)}\n/>\n\n// Compact variant for tighter rails\n\n\n// Disable while AIKO is composing the next reply\n\n```\n\nPill-chip row that lives under the last assistant message. Two visual variants (`default` bordered pill on `bg-card`, `muted` flatter pill on `bg-muted`). `align=\"start\"` (default) or `\"end\"` for right-aligned rails. `disabled` dims every chip and blocks `onSelect`. Returns `null` for an empty `replies` array — drop in without an outer length guard. `role=\"group\"` with a default `aria-label=\"Suggested replies\"`. Default 24ms-staggered fade-in entrance; `motion={false}` and `prefers-reduced-motion` skip the stagger.\n\n#### `CitationRow`\n\n```tsx\nimport { CitationRow } from \"@aisquare/pretty\";\n\n// Inline anchor — drops between sentences with hover preview\n\n Climate science is broad\n
\n\n// Row variant — full card in a \"Sources\" list at the bottom of a message\n\n {message.referencedResources.map((r, i) => (\n openResource(r)}\n />\n ))}\n \n\n// asChild — slot through to a router Link\n\n \n \n```\n\nFootnote-style citation for resources cited in an assistant turn. Two variants for two render contexts: `anchor` (default) is an inline `[N]` chip that drops between sentences and reveals a Radix-Tooltip-anchored preview on hover/focus; `row` is the full card on its own line, used in a \"Sources\" list at the bottom of an assistant message. Both share the same content vocabulary — `index`, `title`, `summary?`, `thumbnail?` (URL or `ReactNode`), `badge?` (string or `ReactNode`).\n\nActivation: pass `onActivate` for click-to-open behavior, `href` for a real `` (so middle-click + cmd-click follow the URL natively), or both — `onActivate` wins on plain left-clicks; modifier-clicks fall through to the browser. `asChild` slots through to a custom anchor (a router ``, an analytics-instrumented wrapper). The anchor's accessible name defaults to `\"Citation N: \"`; override with `aria-label`.\n\nThe inline anchor is sized to drop into prose without breaking line height (`h-[18px]`, `text-[11px]`, `tabular-nums`). Tooltip Provider is self-contained — drop a `CitationRow` into any tree without setup.\n\n### Motion / delight\n\n#### `AnimatedCounter`\n\n```tsx\n<AnimatedCounter value={subscriberCount} />\n<AnimatedCounter value={revenue} format={(n) => `$${n.toFixed(2)}`} duration={1200} />\n```\n\nRespects `prefers-reduced-motion`.\n\n#### `Typewriter`\n\n```tsx\n<Typewriter\n phrases={[\"AI Studios.\", \"experiences.\", \"communities.\"]}\n typeSpeed={60}\n holdDuration={1800}\n/>\n```\n\nCycles through phrases with a typewriter effect. Reduced-motion shows the longest phrase statically.\n\n#### `TypewriterText`\n\n```tsx\nimport { TypewriterText } from \"@aisquare/pretty\";\n\n// Types one string to completion, then fires onDone\n<TypewriterText\n text=\"Your studio analytics are ready.\"\n speed={15} // ms per character (default 15)\n onDone={() => setStreaming(false)}\n/>\n\n// Key-remount to replay (common pattern for demos and retries)\n<TypewriterText key={replayKey} text={assistantFirstLine} />\n```\n\nOne-shot character-by-character type-out. Unlike `<Typewriter>` (phrase loop), this types a single string to completion and fires `onDone`. Designed for first-token streaming reveals in chat UIs. Blinking caret appears while typing, disappears when done. `prefers-reduced-motion` renders the full string immediately and fires `onDone` synchronously on mount. Remount via a `key` change to replay.\n\n#### `StaggeredText`\n\n```tsx\n<StaggeredText\n text=\"The platform is thinking\"\n by=\"word\" // \"char\" | \"word\"\n delay={60} // ms between staggered tokens\n shimmer // optional gradient sweep over each token\n/>;\n\n// Imperative: replay on a state change\nconst ref = useRef<StaggeredTextHandle>(null);\nref.current?.play();\nref.current?.reset();\n```\n\nAnimated text reveal — fade-in-stagger per char/word. Optional shimmer pass for AI-thinking surfaces. `aria-live` announces the full string at once for screen readers (no per-token noise). Reduced-motion renders text statically.\n\n#### `AnimatedList`\n\n```tsx\n<AnimatedList\n items={[\n { id: 1, content: \"Aiko's Studio is now live.\" },\n { id: 2, content: \"Daniel subscribed.\" },\n { id: 3, content: \"New comment on Quest #42.\" },\n ]}\n animationType=\"slide\"\n enterFrom=\"top\"\n hoverEffect=\"scale\"\n fadeEdges\n pauseOnHover\n height=\"320px\"\n/>\n\n// Bounded notification stack — older items fall off when maxItems is hit\n<AnimatedList\n items={notifications}\n autoAddDelay={4000}\n maxItems={5}\n swipeToDismiss\n onDismiss={(item) => analytics.dismiss(item.id)}\n renderItem={(item) => (\n <NotificationRow icon={item.content.icon} title={item.content.title} />\n )}\n/>\n```\n\nVertically-stacked list with motion-driven entrance / exit, optional auto-add cycling, swipe-to-dismiss, ripple/press click effects, and fade-edge masks. Adopted from React Bits Pro and adapted to pretty's anatomy — all hardcoded palette colors swapped for theme tokens (`bg-card`, `border-border`, `text-foreground`, `text-destructive`); `prefers-reduced-motion` collapses entrance / exit to instant transitions and falls back to fade for the bouncy spring animation; `forwardRef` on the wrapper for layout measurement. Use for the Studio Quick-Filter rail, Aiko notification stacks, recent-activity feeds, anywhere you want a list that _animates_ through state.\n\n#### `AnimatedContent`\n\n```tsx\n<AnimatedContent direction=\"vertical\" distance={80} delay={0.2}>\n <h2>Build experiences your audience trusts.</h2>\n</AnimatedContent>\n\n<AnimatedContent direction=\"horizontal\" reverse distance={120}>\n <FeatureBlock />\n</AnimatedContent>\n```\n\nScroll-triggered entrance — directional slide + optional scale + fade once the element crosses a viewport threshold. GSAP-powered. Adopted from React Bits OSS and adapted to pretty's anatomy: `forwardRef`, `cn` for className merge, `window` as the default scroll target (the upstream's hardcoded `snap-main-container` lookup is gone). `prefers-reduced-motion` paints the final state immediately and still fires `onComplete` so consumer state machines resolve. Optional `disappearAfter` hides the element on a timer once revealed. Requires the `gsap` peer-optional dep.\n\n#### `FadeContent`\n\n```tsx\n<FadeContent duration={0.8} delay={0.1} blur>\n <p>Numbers tell the story.</p>\n</FadeContent>\n```\n\nThe quieter sibling — pure opacity ramp (with optional blur ramp) on scroll-into-view. Same anatomy + reduced-motion handling as AnimatedContent. Use when \"this section just slid into view\" is the right read but you don't want directional movement or scale. All time props (`duration`, `delay`, `disappearAfter`) are seconds — pretty unified them since the upstream's mixed ms/s heuristic was ambiguous. Requires the `gsap` peer-optional dep.\n\n#### `FeatureTabs`\n\n```tsx\nimport { FeatureTabs, type FeatureTab } from \"@aisquare/pretty\";\nimport { Layers, Sparkles, Bot } from \"lucide-react\";\n\nconst tabs: FeatureTab[] = [\n { value: \"designers\", label: \"Designers\", icon: <Layers />, content: <DesignersPane /> },\n { value: \"builders\", label: \"Builders\", icon: <Sparkles />, content: <BuildersPane /> },\n { value: \"audience\", label: \"Audience\", icon: <Bot />, content: <AudiencePane /> },\n];\n\n<FeatureTabs tabs={tabs} defaultValue=\"designers\" />;\n```\n\nPersona-card tab selector with an animated radial-gradient indicator that slides between active triggers, plus motion-driven content fade-up on swap. Adopted from `@reactbits-pro/features-9`. Composes `@radix-ui/react-tabs` underneath for full keyboard navigation (`←` / `→` between triggers, `Home` / `End`, `Enter` / `Space` activate), `role=\"tablist\"` / `role=\"tab\"` / `role=\"tabpanel\"` semantics, and ARIA wiring out of the box. Active-card halo uses `--accent` so the indicator follows per-studio brand retinting via `<StudioBrand>`. Reduce-motion users get an instant snap. Use for marketing landing sections (hero · personas · features grid), studio dashboard \"switch the active workspace lens\" patterns, or any consumer-facing surface that needs a top-row category selector with animated content swap. The `examples/playground` itself is built on this primitive.\n\n#### `MorphingRail` / `MorphingRailStage`\n\n```tsx\nimport { MorphingRail, MorphingRailStage } from \"@aisquare/pretty\";\n\n// The dock — a stack of morphing circles (parked items / quick switcher).\n<MorphingRail\n items={items} // [{ id, icon, label, accentColor? }]\n activeId={activeKey} // optional — which one is currently in the stage\n onSelect={(id) => restore(byId[id])}\n onDismiss={(id) => dismiss(byId[id])}\n morphGroup=\"experience\"\n/>\n\n// The stage wrapper — same morphGroup, the active item's id.\n<MorphingRailStage morphGroup=\"experience\" morphId={activeKey}>\n <YourFullStageContent />\n</MorphingRailStage>\n```\n\nPaired primitive that morphs an item between a tile in a side rail and a full stage panel via Framer `layoutId`, with macOS-dock-style cursor magnification on the rail side. Designed to replace hand-rolled morphs that animate `flexGrow` / `flexBasis` on the stage container — a layout-trigger that fights Framer's FLIP and re-paints heavy children (chat / video / markdown stages) every frame. `MorphingRailStage` is transform-only on enter / exit (`opacity` and `scale`) and applies `contain: paint` so the inner content does not get re-rasterised mid-morph; `MorphingRail` mirrors the FLIP from the dock side using the same `layoutId`. Both halves share the namespace via `morphGroup`, and the rail item id must match the stage's `morphId`. Item silhouette is configurable (`shape: \"circle\" | \"rounded\" | \"square\"`, default `rounded` so it reads consistently with rounded-square dock buttons). Items pass an `accentColor` (6-digit hex) and the dock auto-tints the tile background (~15% alpha) and border (~40%); fall back to `accentClassName` when the consumer's accent is a CSS variable rather than a hex. Cursor magnification (adapted from React Bits Pro `navigation-4`) tracks `mouseY` / `mouseX` against each tile's center via `useTransform` + `useSpring` (mass 0.1, stiffness 150, damping 12) and lifts the tile under the cursor to ~1.2× — disable per-instance with `magnify={false}` when the dock should stay static. Toolbar semantics (`role=\"toolbar\"`, `aria-pressed` on the active tile), per-tile `<AikoTooltip>` on the off-axis side, optional sibling dismiss button shown on hover / focus with a 90° rotate-on-hover X. Each restore button carries `data-morph-id={item.id}` so consumers can re-focus across the morph (the rail and the stage live in different parts of the React tree, so DOM focus does not survive a swap on its own — wire a small `requestAnimationFrame` re-focus when the consumer needs it). Honors `prefers-reduced-motion` — collapses both the FLIP and the magnify to instant. Self-wraps `<TooltipProvider>`. Drop-in for AIStudio v3's `ExperienceBubble` + the `motion.div` wrapper around `CenterStage`.\n\n#### `SpotlightCard`\n\n```tsx\nimport { SpotlightCard } from \"@aisquare/pretty\";\n\n<SpotlightCard intensity=\"default\" color=\"primary\">\n <h3>Aiko's Studio</h3>\n <p className=\"text-muted-foreground\">Live now</p>\n</SpotlightCard>;\n```\n\nSurface wrapper with a cursor-following radial-glow overlay, adopted from React Bits Pro `@reactbits-starter/spotlight-card-tw`. Glow color drives from theme tokens (`--primary` / `--accent` / `--secondary`) so per-studio brand retinting via `<StudioBrand>` flows through automatically — never a hardcoded hex. `intensity` (`subtle` / `default` / `strong`) scales the gradient opacity; `radius` and `padding` variants drop the chrome into common card silhouettes; `spread` (default 400px) tunes the gradient radius. Reduce-motion users get a centered static glow on hover instead of live cursor tracking — the affordance stays, the motion stops. SSR-safe (no `window` at module scope), `forwardRef<HTMLDivElement>` for layout measurement. Use for Quest cards, studio tile grids, featured-experience cards, and Aiko nudge surfaces where the spotlight reads as \"the assistant is paying attention to where you are.\" Wrap interactive elements (Link, button) inside, not around — `asChild` is intentionally a v2 concern (the two-layer overlay structure doesn't collapse cleanly into a single Slot child).\n\n#### `BorderGlow`\n\n```tsx\nimport { BorderGlow } from \"@aisquare/pretty\";\n\n<BorderGlow color=\"primary\" intensity=\"default\">\n <StudioCard />\n</BorderGlow>;\n\n// Asymmetric color — semantic statuses\n<BorderGlow color=\"success\" intensity=\"subtle\" pulse={false}>\n <PlanCard tier=\"active\" />\n</BorderGlow>;\n\n// Slot onto a Link — outer element is the anchor\n<BorderGlow color=\"warning\" asChild>\n <a href=\"/upgrade\">Upgrade</a>\n</BorderGlow>;\n```\n\nSteady or breathing halo around a surface's perimeter — sibling to the internal `<BorderBeam>` (sweeping arc on `<Badge variant=\"premium\">`). `intensity` (`subtle` / `default` / `strong`) scales spread / blur / alpha; `color` (`primary` / `accent` / `success` / `warning`) drives the halo from `hsl(var(--token) / X)` so per-studio retinting via `<StudioBrand>` cascades through automatically. `pulse` defaults to `true` and reuses the preset's `animate-pulse-glow` keyframe by overriding `--shadow-glow` + `--shadow-glow-aurora` per instance — one keyframe drives every color × intensity combination. Reduce-motion users get a static halo (the affordance stays visible; the breathing stops). `asChild` slots the glow onto a `<Link>` / `<button>` / etc. via Radix Slot. Composes with `<BorderBeam>` on the same host element for a \"premium + active\" combination — beam sweeps the perimeter, glow is the steady backdrop. Use for active studio rail cards, subscribed-state community cards, Aiko nudge surfaces (\"I'm here, paying attention\"), and premium / upgrade prompts.\n\n#### `Stepper`\n\n```tsx\nimport { Stepper } from \"@aisquare/pretty\";\n\n// Self-rendering — pass steps + (optional) per-step content\n<Stepper\n steps={[\n { label: \"Vault\", description: \"Where uploads land\" },\n { label: \"Publish\", description: \"One click to ship\" },\n { label: \"Analytics\", description: \"See who's tuned in\" },\n ]}\n defaultValue={0}\n onComplete={() => closeWalkthrough()}\n/>;\n\n// Headless — render-prop owns the layout (content panel + footer buttons)\n<Stepper steps={steps} value={step} onValueChange={setStep}>\n {({ step, total, next, prev, complete }) => (\n <footer className=\"flex justify-between gap-3 mt-4\">\n <Button variant=\"ghost\" onClick={prev} disabled={step === 0}>\n Back\n </Button>\n <Button onClick={step === total - 1 ? complete : next}>\n {step === total - 1 ? \"Done\" : \"Next\"}\n </Button>\n </footer>\n )}\n</Stepper>;\n```\n\nMulti-step indicator with optional content panel + WAI-ARIA tablist keyboard navigation. Drives multi-step flows (first-run walkthroughs, quest authoring tutorials, paywall onboarding, Aiko-led recovery) that previously lived as ad-hoc `useState({ step: 0..3 })` per surface. Variants: `orientation` (`horizontal` / `vertical`), `size` (`sm` / `default` / `lg`), `indicator` (`numbers` / `dots` / `progress`). Controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`) modes; `interactive: false` swaps `role=\"tablist\"` for `role=\"progressbar\"` so display-only flows pick up the right ARIA shape automatically. Keyboard nav follows the WAI-ARIA tablist pattern: ← / → for horizontal, ↑ / ↓ for vertical, Home / End. Reduce-motion users get an instant step transition. The render-prop slot is the composition seam for `<AikoTip>` integration: `<AikoTip body={<Stepper steps={...}>{({ next }) => ...}</Stepper>}>` plumbs Aiko-led multi-step recovery without prop-drilling.\n\n### Aiko (brand mascot + helper surfaces)\n\nThe AISquare AI assistant lives across these primitives. They share a single visual anatomy (paper-shell silhouette, breathing AikoMark, anti-intrusion contract) and one mental model: the platform has a personality, and it shows up where it can help.\n\n#### `AikoMark`\n\n```tsx\n<AikoMark size=\"md\" />\n<AikoMark size=\"2xl\" animated={false} /> // resting frame\n<AikoMark aria-label=\"AISquare assistant\" /> // announce; otherwise decorative\n```\n\nThe brand mascot. One file, single source of truth — every Aiko surface (Tip, Sheet, Whisper, Loader, marketing) composes this. Sizes: `xs / sm / md / lg / xl / 2xl` (24 / 28 / 32 / 40 / 56 / 80 px). Honors `prefers-reduced-motion` (resting frame). To change Aiko's look across the whole platform, edit only `AikoMark.tsx`.\n\n#### `AikoTip`\n\n```tsx\n<AikoTip\n trigger=\"click\" // \"click\" | \"hover\"\n variant=\"rail\" // label | info | single | rail | pages | pages-passive\n title=\"Recall lives across chats\"\n body=\"Aiko remembers the last 50 turns to keep context tight.\"\n actions={[\n { label: \"Got it\", primary: true },\n { label: \"Snooze 30 min\", onClick: snooze },\n ]}\n>\n <Button variant=\"outline\">What's recall?</Button>\n</AikoTip>\n```\n\nThe Aiko helper bubble. Six content silhouettes share one paper shell + breathing AikoMark. Built on Radix Popover so positioning, focus, ESC, and click-outside are handled. Drop-in replacement for traditional tooltips when the helper has personality + content + (optionally) actions. `trigger=\"hover\"` makes it a label-style tooltip instead of a click-to-open popover.\n\n#### `AikoTooltip`\n\n```tsx\n<AikoTooltip body=\"Save\"> // → minimal: no mark, light shell\n <IconButton onClick={save} />\n</AikoTooltip>\n\n<AikoTooltip body=\"This will permanently delete the experience.\"> // → full: branded card with mark\n <IconButton onClick={remove} />\n</AikoTooltip>\n\n<AikoTooltip title=\"Save\" body=\"Saves and exits the editor\" side=\"right\"> // → full (header)\n <IconButton />\n</AikoTooltip>\n\n<AikoTooltip body=\"Save\" tone=\"full\"> // pin full when the heuristic guesses wrong\n <IconButton />\n</AikoTooltip>\n```\n\nThe drop-in replacement for shadcn-style `<Tooltip><TooltipTrigger><TooltipContent>` compositions. The visual treatment auto-adapts via the `tone` heuristic: short string body, no title → light label-style tooltip; longer body, JSX node, or `title` → branded paper card with the AikoMark. Brand the act, not the chrome — short button labels stay quiet so substantive AIKO comms stand out. Override with `tone=\"full\" | \"minimal\"` when you need to pin a style. Hover-only — for click-to-open helpers reach for `<AikoTip>` directly. Built on Radix Tooltip so the consumer's `<TooltipProvider>` configures cross-tooltip delay-skipping and free `aria-describedby` wiring. Default `delayDuration={400}` aligns with industry norms (Linear ≈500, GitHub ≈400) so cursor-traversal doesn't trigger noise.\n\n#### `AikoHint`\n\n```tsx\n<AikoHint title=\"Why this matters\" body=\"One sentence. Aiko keeps it brief.\" />\n\n<AikoHint\n title=\"Heads up\"\n body=\"This will overwrite the current draft.\"\n actions={[{ label: \"Got it\" }]}\n channelId=\"form.experience-name\"\n/>\n```\n\nSmall Aiko mark that teases on hover and reveals on click. Hover (120ms delay) shows a tiny label tip with the `teaser` text (default `\"Aiko has a tip\"`). Click opens a fuller info card with title + body + optional actions. Use to replace always-visible \"subtext\" / `FormDescription` patterns where the explanation should be one click away — quiet by default, informative on demand. Built on Radix Popover. Honors the [anti-intrusion contract](./docs/contracts/aiko-intrusion.md) when `channelId` is set + wrapped in `<AikoProvider>`.\n\n#### `AikoWhisper` / `AikoNudge` / `AikoIntervene`\n\n```tsx\nconst ref = useRef<HTMLButtonElement>(null);\nconst aiko = useAikoSignal(\"checkout.confused\");\n\nuseAikoDwellSignal(ref, { channelId: \"checkout.confused\", ms: 2000 });\nuseAikoRageClickSignal(ref, { channelId: \"checkout.confused\", threshold: 3 });\n\n<Button ref={ref}>Submit order</Button>;\n<AikoWhisper anchorRef={ref} open={aiko.canShow && aiko.level === \"whisper\"}\n channelId=\"checkout.confused\" onExpand={() => aiko.signal(\"rage-click\")}\n previewText=\"Aiko has a hint. Click to see it.\" />\n<AikoNudge anchorRef={ref} open={aiko.canShow && aiko.level === \"nudge\"}\n channelId=\"checkout.confused\">\n Looks confusing — try <em>refreshing your library</em>.\n</AikoNudge>\n<AikoIntervene anchorRef={ref} open={aiko.canShow && aiko.level === \"intervene\"}\n channelId=\"checkout.confused\" title=\"Need a hand?\" body=\"...\"\n primaryAction={{ label: \"Try this\", onClick: fix }} />\n```\n\nThe three escalation surfaces (Phase 3). Whisper is a tiny breathing pip; Nudge is a one-line balloon; Intervene is a full helper card. Drive `open` from `useAikoSignal(channelId).level`. All three honor the [anti-intrusion contract](./docs/contracts/aiko-intrusion.md) — closing fires `dismiss()` which snoozes 30 min, three dismisses → silent for the session, mute persists.\n\n`AikoWhisper`'s optional `previewText` opens a paper-shelled `AikoTip` (label variant) on hover/focus — progressive disclosure without committing to escalation.\n\n#### `AikoProvider` + signal hooks\n\n```tsx\nimport {\n AikoProvider,\n useAiko,\n useAikoChannel,\n useAikoSignal,\n useAikoDwellSignal,\n useAikoRageClickSignal,\n useAikoHoverLoopSignal,\n} from \"@aisquare/pretty\";\n\n// Wrap once near app root\n<AikoProvider snoozeMinutes={30} sessionDismissThreshold={3}>\n <App />\n</AikoProvider>;\n\n// Read or control any channel\nconst channel = useAikoChannel(\"library.refresh-tip\");\nchannel.canShow; // false if muted, snoozed, or session-silent\nchannel.dismiss(); // counts as one dismiss\nchannel.snoozeFor(60_000);\nchannel.mute(); // until unmute()\nchannel.reset();\n\n// Detect intent → drive the level state machine\nconst sig = useAikoSignal(\"library.refresh-tip\");\nsig.level; // \"off\" | \"whisper\" | \"nudge\" | \"intervene\"\nsig.signal(\"rage-click\"); // user-triggered escalation\nsig.resetLevel();\n\n// Auto-detectors — point at any element ref\nuseAikoDwellSignal(ref, { channelId: \"...\", ms: 2000 });\nuseAikoRageClickSignal(ref, { channelId: \"...\", threshold: 3, windowMs: 1500 });\nuseAikoHoverLoopSignal(ref, { channelId: \"...\", loopThreshold: 3 });\n```\n\nThe state machine + persistence layer behind every Aiko surface. Provider owns per-channel mute/snooze/session-dismiss-count; hooks expose typed read/write APIs. Detectors translate user behavior (long hover, rage-click, hover loops) into level escalations without you wiring it. Full anti-intrusion contract spec at [`docs/contracts/aiko-intrusion.md`](./docs/contracts/aiko-intrusion.md).\n\n### Theming\n\n#### `ThemeProvider`\n\n```tsx\nimport { ThemeProvider, useTheme } from \"@aisquare/pretty\";\n\n<ThemeProvider defaultTheme=\"system\" storageKey=\"aisquare-theme\">\n <App />\n</ThemeProvider>;\n```\n\nAdds `light` or `dark` to `<html>`, persists the choice in `localStorage`, and follows the OS `prefers-color-scheme` when set to `\"system\"`. Read or change inside the tree:\n\n```tsx\nconst { theme, resolvedTheme, setTheme } = useTheme();\n<Button onClick={() => setTheme(resolvedTheme === \"dark\" ? \"light\" : \"dark\")}>Switch</Button>;\n```\n\nFor zero-flash apps (Next.js, Remix, Astro), inline the script in `<head>`:\n\n```tsx\nimport { getThemeScript } from \"@aisquare/pretty\";\n<script dangerouslySetInnerHTML={{ __html: getThemeScript() }} />;\n```\n\n#### `StudioBrand`\n\nPer-studio brand cascade. Sets CSS vars on a wrapper so every primitive inside inherits the studio's brand, with no per-primitive code change.\n\n```tsx\n<StudioBrand\n primary=\"280 70% 50%\"\n accent=\"220 80% 60%\"\n radius=\"14px\"\n font=\"'Geist Sans', sans-serif\"\n>\n <Button>Visit studio</Button>\n</StudioBrand>\n```\n\nTwo studios side-by-side stay scoped:\n\n```tsx\n<div className=\"grid grid-cols-2\">\n <StudioBrand primary=\"280 70% 50%\">\n <App />\n </StudioBrand>\n <StudioBrand primary=\"14 90% 55%\">\n <App />\n </StudioBrand>\n</div>\n```\n\nColor values accept HSL triplets (`\"280 70% 50%\"`) or wrapped strings (`\"hsl(280 70% 50%)\"`); both work. Use `vars` to set arbitrary CSS variables (`--shadow-glow`, custom tokens). Use `asChild` to apply the brand to your own element with no extra wrapper. Composes with `ThemeProvider`: light/dark applies globally, brand vars override locally.\n\n---\n\n### Office surface primitives (iter-37-F2)\n\nSeven primitives for the AISquare Office multi-agent collaboration surface. All compose existing pretty primitives where possible.\n\n#### `RailItem`\n\nLeft-rail session navigation row. Composes `SlugTag` + `CornerMark` + `PulseDot`.\n\n```tsx\nimport { RailItem } from \"@aisquare/pretty\";\n\n<RailItem slug=\"api-stabilization\" hue=\"#1F8A5B\" status=\"open\" unread={3} summary=\"v2 contract\" />\n<RailItem slug=\"auth-refactor\" hue=\"#D97757\" status=\"stuck\" active />\n<RailItem slug=\"init\" status=\"sealed\" sealed />\n```\n\n#### `PaneHeader`\n\nCenter-pane top-section layout shell (23px/700 title + status + summary + actions slots).\n\n```tsx\nimport { PaneHeader, Tag, Pill } from \"@aisquare/pretty\";\n\n<PaneHeader\n title=\"#api-stabilization\"\n status={<Tag label=\"OPEN\" tone=\"success\" />}\n summary=\"Stabilise the v2 API contract.\"\n actions={<Pill label=\"stuck\" tone=\"destructive\" appearance=\"solid\" />}\n/>\n```\n\n#### `OfficeMsg` + sub-components\n\nOffice-specific message row. Distinct from `MessageRow` (role-based): sender identity expressed via SlugTag hue + 2px hue left-rail.\n\n```tsx\nimport { OfficeMsg, OfficeMsgTimestamp, OfficeMsgSender, OfficeMsgBody, ThreadRow } from \"@aisquare/pretty\";\n\n<OfficeMsg slug=\"founder-0\" hue=\"#D97757\" ts=\"09:55\" isOwner>\n Synthesis complete. Proposing lock.\n</OfficeMsg>\n<OfficeMsg slug=\"founder-9\" hue=\"#1F8A5B\" ts=\"09:57\" selfFlag=\"force-analysis\"\n thread={{ replyCount: 3, status: \"open\", loaded: [\"f0\"] }}>\n Tests pass.\n</OfficeMsg>\n```\n\n#### `F0Card`\n\nFounder-0 lock-proposal decision card. cardChrome(coral) surface with 4px left-bar and optional worklog row.\n\n```tsx\nimport { F0Card } from \"@aisquare/pretty\";\n\n<F0Card\n ts=\"10:01\"\n body=\"api-stabilization is locked.\"\n worklog={{ id: \"w24-032\",","readmeFilename":"README.md"}
{draft}
\n{draft}
// dim only, no glide\n\n \n \n ))}\n \n \n scrollToBottom()}\n />\n
\n );\n}\n```\n\nScroll container for a conversation of `\n {messages.map((m) => (\n scrollToBottom()}\n />\n
\n );\n}\n```\n\nThe hook owns `IntersectionObserver`-based at-bottom detection plus a `scrollToBottom({ smooth })` action. The button is the visible \"Jump to latest\" affordance — absolutely positioned by default (`absolute bottom-3 left-1/2 -translate-x-1/2 z-10`), so wrap it inside a `position: relative` scroller. Override placement via `className` for sidebar / right-aligned use cases.\n\n`unreadCount` renders a small badge in the top-right corner (\"3\", \"99+\"). The label folds into `aria-label` so SR users hear \"Jump to latest, 3 unread\". Default 180ms fade+slide entrance; `motion={false}` and `prefers-reduced-motion` skip it.\n\nFor non-default content (e.g. a `\n
\n\n// Flatter inline variant — tucks under a chat header\n{JSON.stringify({ q: \"ml\" }, null, 2)}}\n/>\n\n// Completed call — body collapsed by default, click to expand\n{JSON}` block for the args.\n\nDisclosure follows WAI-ARIA: trigger button has `aria-expanded` + `aria-controls`, body region has `aria-labelledby` pointing to the label cell. Body opens by default while pending or errored, collapsed once success lands so the assistant's reply stays the focus. Auto-collapses on the `pending → success` transition (uncontrolled mode); user clicks after that stick. Pass `defaultOpen` to override the heuristic, or `open` + `onOpenChange` for full control. `motion={false}` and `prefers-reduced-motion` skip the height animation and the pending pulse.\n\nComposition: drop inside `\n Climate science is broad\n
\n {message.referencedResources.map((r, i) => (\n openResource(r)}\n />\n ))}\n
\n\n// asChild — slot through to a router Link\n