@trendr/core 0.1.0 → 0.2.1

package/README.md

@@ -1,27 +1,31 @@
-<p align="center">
-  <img src=".github/trend.png" alt="trend" width="400" />
-</p>
+<pre align="center">
+▗        ▌
+▜▘▛▘█▌▛▌▛▌
+▐▖▌ ▙▖▌▌▙▌
 
-<p align="center">4-16x faster than ink and neo-blessed - <a href="bench/README.md">benchmarks</a></p>
+</pre>
 
-Direct-mode TUI renderer with JSX, signals, and per-cell diffing.
 
-ESM only. Requires esbuild (or similar) for JSX transformation.
+JSX components, signals, per-cell diffing and flexbox without React and [Yoga](https://github.com/facebook/yoga/issues/1859). Terminals are character grids, not DOM trees. Why reconcile a virtual DOM to write escape sequences?
 
-```json
-{ "jsx": "automatic", "jsxImportSource": "trend" }
-```
+4-16x faster frame times and 580x less I/O per render than popular TUI frameworks. No dependencies. [benchmarks](bench/README.md)
 
-https://github.com/user-attachments/assets/d307ba1e-2b21-4f7d-8b1b-56252820db6c
+https://github.com/user-attachments/assets/6e84bb4b-a99e-46f2-a235-1ee4be62c0ae
 
-https://github.com/user-attachments/assets/a5984747-f365-4fe3-a161-93101682ca42
+## Usage
 
-https://github.com/user-attachments/assets/9c357c93-0299-4480-a969-61a54b49ec33
+```bash
+npm i @trendr/core
+```
 
-## Usage
+Requires esbuild (or similar) for JSX transformation.
+
+```json
+{ "jsx": "automatic", "jsxImportSource": "trend" }
+```
 
 ```jsx
-import { mount, createSignal, useInput } from 'trend'
+import { mount, createSignal, useInput } from '@trendr/core'
 
 function App() {
   const [count, setCount] = createSignal(0)
@@ -42,20 +46,31 @@ function App() {
 mount(App)
 ```
 
-`mount(Component, { stream?, stdin?, theme? })` enters alt screen, starts a 60fps render loop, and returns `{ unmount }`. Components are plain functions that return JSX. State is managed with signals - call the getter to read, the setter to write. The framework re-renders automatically when signals change.
+`mount(Component, { stream?, stdin?, title?, theme? })` enters alt screen and returns `{ unmount, repaint }`. Renders on demand when signals change, capped at 60fps.
 
 ### Theming
 
-All built-in components use `accent` as the focus/highlight color (default: `'cyan'`). Override it globally via mount:
+Pass a theme object to `mount` to configure global defaults:
 
 ```jsx
-mount(App, { theme: { accent: 'green' } })
+mount(App, {
+  theme: {
+    accent: 'green',        // focus/highlight color, default 'cyan'
+    cursor: {
+      blink: true,          // default false
+      rate: 530,            // blink interval ms, default 530
+      style: 'block',       // default 'block'
+      bg: 'cyan',           // cursor background color
+      color: 'black',       // cursor text color
+    },
+  },
+})
 ```
 
-Components read the accent with `useTheme()`. Use this in your own components to stay consistent:
+Components read the theme with `useTheme()`:
 
 ```jsx
-import { useTheme } from 'trend'
+import { useTheme } from '@trendr/core'
 
 const { accent } = useTheme()
 ```
@@ -65,7 +80,7 @@ Individual components still accept explicit color props (e.g. `<Spinner color="m
 ## Signals
 
 ```js
-import { createSignal, createEffect, createMemo, batch, untrack, onCleanup } from 'trend'
+import { createSignal, createEffect, createMemo, batch, untrack, onCleanup } from '@trendr/core'
 
 const [value, setValue] = createSignal(0)
 value()         // read (tracks dependency)
@@ -109,26 +124,58 @@ Two element types: `box` (container) and `text` (leaf).
   margin: 1,                // same variants as padding
   border: 'round',          // 'single' | 'double' | 'round' | 'bold'
   borderColor: 'cyan',
+  borderEdges: { bottom: true, left: true }, // render only specific sides
   bg: 'blue',               // background color
+  texture: 'dots',          // background texture (see below)
+  textureColor: '#333',     // color for texture characters
+  position: 'absolute',     // remove from flow, position with top/left/right/bottom
+  top: 0, left: 0, right: 0, bottom: 0,
+  overflow: 'scroll',       // scrollable container (see ScrollBox)
+  scrollOffset: 0,          // scroll position (rows from top)
 }}>
+```
 
+```jsx
 <text style={{
   color: 'cyan',            // named, hex (#ff0000), or 256-color index
   bg: 'black',
-  bold: true,
-  dim: true,
-  italic: true,
-  underline: true,
-  inverse: true,
-  strikethrough: true,
+  bold: true, dim: true, italic: true,
+  underline: true, inverse: true, strikethrough: true,
   overflow: 'wrap',         // 'wrap' (default) | 'truncate' | 'nowrap'
 }}>
 ```
 
+### Background Textures
+
+Repeating character fill for box backgrounds. Works with or without `bg`.
+
+```jsx
+<box style={{ bg: '#1a1a2e', texture: 'dots', textureColor: '#2a2a4e' }}>
+```
+
+Presets: `'shade-light'` (░), `'shade-medium'` (▒), `'shade-heavy'` (▓), `'dots'` (·), `'cross'` (╳), `'grid'` (┼), `'dash'` (╌). Or pass any single character: `texture: '~'`.
+
+Texture characters show through spaces in text rendered on top (unless the text has an explicit `bg`, which claims the cell).
+
+### Absolute Positioning
+
+Position relative to parent, removed from flex flow.
+
+```jsx
+<box style={{ border: 'round', height: 5, flexDirection: 'column' }}>
+  <text>content here</text>
+  <box style={{ position: 'absolute', top: 0, right: 1 }}>
+    <text style={{ color: 'green', bold: true }}>ONLINE</text>
+  </box>
+</box>
+```
+
+If both `left` and `right` are set, width is derived (same for `top`/`bottom`).
+
 `Box`, `Text`, and `Spacer` are convenience wrappers:
 
 ```jsx
-import { Box, Text, Spacer } from 'trend'
+import { Box, Text, Spacer } from '@trendr/core'
 <Box style={{ flexDirection: 'row' }}><Text>hello</Text><Spacer /><Text>right</Text></Box>
 ```
 
@@ -157,7 +204,7 @@ Handlers fire in reverse registration order (innermost component first). Call `s
 Declarative key binding. Parses `'ctrl+s'`, `'alt+enter'`, etc.
 
 ```jsx
-import { useHotkey } from 'trend'
+import { useHotkey } from '@trendr/core'
 
 useHotkey('ctrl+s', () => save())
 useHotkey('alt+enter', () => submit(), { when: () => isFocused })
@@ -165,10 +212,11 @@ useHotkey('alt+enter', () => submit(), { when: () => isFocused })
 
 ### useLayout
 
-Returns the component's computed layout rectangle.
+Returns a live reference to the component's computed layout rectangle. Values update in-place each frame, including after terminal resize.
 
 ```jsx
-const { x, y, width, height } = useLayout()
+const layout = useLayout()
+// layout.x, layout.y, layout.width, layout.height, layout.contentHeight
 ```
 
 ### useResize
@@ -185,12 +233,75 @@ Used in [dashboard](examples/dashboard.jsx)
 useInterval(() => tick(), 1000) // auto-cleaned on unmount
 ```
 
+### useTimeout
+
+Used in [timeout](examples/timeout.jsx)
+
+Single-shot timer. Auto-cleaned on unmount.
+
+```jsx
+useTimeout(() => hide(), 3000)
+```
+
+### useAsync
+
+Used in [async](examples/async.jsx)
+
+Async function to reactive signals.
+
+```jsx
+import { useAsync } from '@trendr/core'
+
+const { status, data, error, run } = useAsync(fetchUsers)
+
+// status(): 'idle' | 'loading' | 'success' | 'error'
+// data():   resolved value (null until success)
+// error():  rejected error (null until error)
+// run():    trigger the async function. forwards args: run(userId)
+```
+
+Stale calls are discarded. Use `{ immediate: true }` to fire on mount:
+
+```jsx
+const { status, data } = useAsync(fetchUsers, { immediate: true })
+```
+
+### useMouse
+
+```jsx
+useMouse((event) => {
+  // event.action: 'press' | 'release' | 'drag' | 'scroll'
+  // event.button: 'left' | 'middle' | 'right' (press/release only)
+  // event.direction: 'up' | 'down' (scroll only)
+  // event.x, event.y: 0-based terminal coordinates
+  // event.stopPropagation(): prevent other handlers from receiving this event
+})
+```
+
+Mouse is enabled automatically. Built-in components support click, scroll wheel, and scrollbar dragging.
+
 ### useStdout
 
 ```jsx
 const stream = useStdout() // the output stream (process.stdout or custom)
 ```
 
+### useRepaint
+
+Forces a full repaint. Useful after spawning an external process (e.g. `$EDITOR`).
+
+```jsx
+import { useRepaint, useStdout, exitAltScreen, showCursor, altScreen, hideCursor } from '@trendr/core'
+
+const repaint = useRepaint()
+const stdout = useStdout()
+
+stdout.write(exitAltScreen + showCursor)
+execSync(`${process.env.EDITOR} ${file}`, { stdio: 'inherit' })
+stdout.write(altScreen + hideCursor)
+repaint()
+```
+
 ### useTheme
 
 Returns the current theme object. See [Theming](#theming).
@@ -203,10 +314,10 @@ const { accent } = useTheme()
 
 Used in [explorer](examples/explorer.jsx), [chat](examples/chat.jsx), [modal-form](examples/modal-form.jsx), [components](examples/components.jsx), [focus-demo](examples/focus-demo.jsx), [layout](examples/layout.jsx)
 
-Manages focus across multiple interactive regions. You register named items in the order you want tab to cycle through them. The focus manager tracks which name is currently active - it doesn't know anything about your components or layout.
+Register named items in tab order. The focus manager tracks which is active.
 
 ```jsx
-import { useFocus } from 'trend'
+import { useFocus } from '@trendr/core'
 
 const fm = useFocus({ initial: 'input' })
 
@@ -216,30 +327,29 @@ fm.item('list')      // tab stop 1
 fm.item('sidebar')   // tab stop 2
 ```
 
-Then wire each component's `focused` prop to `fm.is()`, which returns true when that name is the active one:
+Wire `fm.is()` to each component's `focused` prop. Tab/shift-tab cycles through items.
 
 ```jsx
 <TextInput focused={fm.is('input')} />
 <List focused={fm.is('list')} />
 <Select focused={fm.is('sidebar')} />
-```
-
-Tab and shift-tab cycle through the registered names. The focus manager handles the index - you just query it.
 
-```jsx
-fm.is('input')   // boolean - is 'input' the active name?
-fm.focus('list')  // jump to 'list' programmatically
-fm.current()      // the currently active name
+fm.focus('list')  // jump programmatically
+fm.current()      // the active name
 ```
 
-Groups let you nest multiple items under one tab stop, navigable with j/k or up/down within the group:
+Groups nest multiple items under one tab stop:
 
 ```jsx
-fm.group('settings', { items: ['theme', 'autosave', 'format'], navigate: 'updown', wrap: true })
+fm.group('settings', { items: ['theme', 'autosave', 'format'] })
 // fm.is('theme'), fm.is('autosave'), etc. work within the group
 ```
 
-Stack-based focus for modals and drills - push saves the current focus and switches, pop restores it:
+Options:
+- `navigate` - which keys move between group items: `'both'` (default, j/k and up/down), `'jk'`, or `'updown'`
+- `wrap` - wrap around at ends (default `false`)
+
+Stack-based focus for modals - push saves current focus, pop restores it:
 
 ```jsx
 fm.push('modal')  // save current focus, switch to 'modal'
@@ -251,12 +361,17 @@ fm.pop()          // restore previous focus
 Used in [chat](examples/chat.jsx), [modal-form](examples/modal-form.jsx), [components](examples/components.jsx)
 
 ```jsx
-import { useToast } from 'trend'
+import { useToast } from '@trendr/core'
 
 const toast = useToast({
   duration: 2000,           // ms, default 2000
   position: 'bottom-right', // see positions below
   margin: 1,                // padding from screen edge, default 1
+  render: (message) => (    // optional custom render
+    <box style={{ bg: '#1E1E1E', paddingX: 1 }}>
+      <text style={{ color: '#9A9EA3' }}>{message}</text>
+    </box>
+  ),
 })
 
 toast('saved')
@@ -268,7 +383,7 @@ toast('saved')
 
 ## Components
 
-All interactive components accept a `focused` prop that controls whether they respond to keyboard input. When multiple components are on screen, only the focused one should capture keys - otherwise a keypress meant for a text input would also scroll a list. In practice you wire this to a focus manager:
+All interactive components accept a `focused` prop. Wire it to a focus manager so only one component captures keys at a time:
 
 ```jsx
 const fm = useFocus({ initial: 'search' })
@@ -328,19 +443,79 @@ Scrollable list with keyboard navigation.
   selected={selectedIndex}  // controlled, or omit for internal state
   onSelect={setIndex}
   focused={fm.is('list')}
-  height={10}               // defaults to layout height
+  scrollbar={true}          // default false
+  scrolloff={2}             // items of margin from edges when scrolling (default 2)
+  interactive={true}        // handle keyboard input (default: same as focused)
   header={<text>title</text>}
+  headerHeight={1}          // default 1, rows the header occupies
   renderItem={(item, { selected, index, focused }) => (
     <text style={{ bg: selected ? (focused ? accent : 'gray') : null }}>{item.name}</text>
   )}
 />
 ```
 
+`itemHeight` enables multi-row items (tells scroll math how many rows each item occupies):
+
+```jsx
+<List
+  items={data}
+  itemHeight={3}
+  renderItem={(item, { selected, focused }) => (
+    <box style={{ flexDirection: 'column', bg: selected ? accent : null }}>
+      <text style={{ bold: true }}>{item.name}</text>
+      <text style={{ color: 'gray' }}>{item.description}</text>
+      <text style={{ color: 'green' }}>{item.status}</text>
+    </box>
+  )}
+/>
+```
+
 Keys: j/k or up/down, g/G for top/bottom, ctrl-d/u half page, ctrl-f/b full page, pageup/pagedown.
 
+### PickList
+
+Used in [pick-list](examples/pick-list.jsx)
+
+Filterable list with live search. Text input at the top filters a scrollable list below. Navigate the list with up/down or ctrl-n/ctrl-p while typing.
+
+```jsx
+<PickList
+  items={data}
+  focused={fm.is('search')}
+  placeholder="search..."
+  onSelect={item => {}}       // Enter on highlighted item
+  onCancel={() => {}}          // Escape
+  onChange={query => {}}       // every keystroke in the filter
+  clearOnSelect={false}        // reset filter on select (default false)
+  scrollbar={true}             // default false
+  scrolloff={2}                // items of margin from edges (default 2, inherited from List)
+  gap={1}                      // space between input and list (default 0)
+  filter={(query, item) => {}} // custom filter (default: case-insensitive includes)
+/>
+```
+
+Multi-row items with `renderItem`, `itemHeight`, and `itemGap`:
+
+```jsx
+<PickList
+  items={packages}
+  itemHeight={3}
+  itemGap={1}
+  renderItem={(pkg, { selected, focused }) => (
+    <box style={{ flexDirection: 'column', bg: selected ? accent : null, paddingX: 1 }}>
+      <text style={{ bold: true }}>{pkg.name}</text>
+      <text style={{ color: 'gray' }}>{pkg.desc}</text>
+      <text style={{ color: 'yellow' }}>{pkg.downloads}</text>
+    </box>
+  )}
+/>
+```
+
+Keys: type to filter, up/down or ctrl-n/ctrl-p to navigate, enter to select, escape to cancel. All bash-style editing keys work (ctrl-a/e/u/k/w).
+
 ### Table
 
-Used in [components](examples/components.jsx)
+Used in [components](examples/components.jsx), [custom-table](examples/custom-table.jsx)
 
 Column-based data table. Uses List internally.
 
@@ -355,6 +530,25 @@ Column-based data table. Uses List internally.
   selected={selectedRow}
   onSelect={setRow}
   focused={fm.is('table')}
+  separator={true}              // horizontal rule below header
+  separatorChars={{ left: '', fill: '─', right: '' }}  // customizable
+/>
+```
+
+`renderItem` gives full control over row rendering while keeping column-aligned headers:
+
+```jsx
+<Table
+  columns={columns}
+  data={rows}
+  selected={idx()}
+  onSelect={setIdx}
+  renderItem={(row, { selected, focused }) => (
+    <box style={{ flexDirection: 'row', bg: selected ? accent : null, paddingX: 1 }}>
+      <text style={{ color: selected ? 'black' : null, flexGrow: 1 }}>{row.name}</text>
+      <text style={{ color: selected ? 'black' : row.stale ? 'yellow' : 'gray' }}>{row.age}</text>
+    </box>
+  )}
 />
 ```
 
@@ -387,6 +581,8 @@ Dropdown selector. Can render inline or as overlay.
   focused={fm.is('color')}
   overlay={false}          // true renders as floating overlay
   placeholder="pick one..."
+  openIcon="▲"             // default ▲
+  closedIcon="▼"           // default ▼
   renderItem={(item, { selected, index }) => <text>{item}</text>}
   style={{
     border: 'single', borderColor: 'green', bg: 'black',
@@ -408,10 +604,12 @@ Used in [modal-form](examples/modal-form.jsx), [components](examples/components.
   label="Enable feature"
   onChange={setChecked}  // (newState: boolean) => void
   focused={fm.is('feature')}
+  checkedIcon="[✓]"     // default '[x]'
+  uncheckedIcon="[ ]"   // default '[ ]'
 />
 ```
 
-Keys: space or enter to toggle. Renders `[x]` / `[ ]`.
+Keys: space or enter to toggle.
 
 ### Radio
 
@@ -426,21 +624,34 @@ Used in [modal-form](examples/modal-form.jsx), [components](examples/components.
 />
 ```
 
-Keys: j/k or up/down, enter/space to select. Renders circle symbols.
+Keys: j/k or up/down, enter/space to select. Renders `●` / `○`.
 
 ### ProgressBar
 
-Used in [dashboard](examples/dashboard.jsx), [components](examples/components.jsx)
+Used in [progress](examples/progress.jsx), [components](examples/components.jsx)
 
 ```jsx
 <ProgressBar
-  value={0.65}      // 0 to 1
-  width={20}        // characters, default 20
-  color="red"       // overrides theme accent
-  label="65%"       // optional text after bar
+  value={0.65}              // 0 to 1
+  variant="thin"            // 'thin' (default), 'block', 'ascii', 'braille'
+  color="red"               // overrides theme accent
+  label="Installing"        // optional label before bar
+  count="8/12"              // optional count after percentage
+  percentage={true}         // show percentage (default true)
+  width={30}                // override bar width (default: fills available space)
 />
 ```
 
+Variants:
+- `thin` - clean `━` bar (default)
+- `block` - thick `█░` blocks
+- `ascii` - plain `[###---]`, works in any terminal
+- `braille` - smooth `⣿` fill
+
+```
+Installing  ━━━━━━━━━━━━━━━━━━━━━━━━ 67% (8/12)
+```
+
 ### Spinner
 
 Used in [components](examples/components.jsx)
@@ -448,11 +659,59 @@ Used in [components](examples/components.jsx)
 ```jsx
 <Spinner
   label="loading..."
+  variant="dots"     // 'dots' (default), 'line', 'circle', 'bounce', 'arrow', 'square', 'star'
   color="magenta"    // overrides theme accent
   interval={80}      // ms, default 80
+  frames={['a','b']} // custom frames (overrides variant)
+/>
+```
+
+### Task
+
+Used in [task](examples/task.jsx)
+
+Spinner while loading, checkmark on success, x on error. Built on `useAsync`.
+
+```jsx
+<Task
+  run={() => fetchData()}   // async function
+  label="Fetching data..."  // shown while loading
+  successLabel="Done"       // optional, shown on success (defaults to label)
+  errorLabel="Failed"       // optional, shown on error (defaults to error message)
+  immediate={true}          // fire on mount (default true)
+  icon={{ success: '+' }}   // override icons per status
+  color="cyan"              // override color (defaults vary by status)
 />
 ```
 
+Multiple tasks render as a step list:
+
+```jsx
+<Task run={() => install()} label="Installing..." successLabel="Installed" />
+<Task run={() => build()} label="Building..." successLabel="Built" />
+<Task run={() => test()} label="Testing..." successLabel="Tests passed" />
+```
+
+### Shimmer
+
+Used in [shimmer](examples/shimmer.jsx)
+
+Sliding highlight effect with gradient falloff.
+
+```jsx
+<Shimmer
+  color="gray"         // base text color (default 'gray')
+  highlight="cyan"     // shimmer color (default: theme accent)
+  size={3}             // width of bright center in chars (default 3)
+  gradient={3}         // gradient tail length each side (default 3, 0 for hard edge)
+  duration={1000}      // ms for one pass across the text (default 1000)
+  delay={500}          // ms pause between passes (default 500)
+  reverse={false}      // slide right to left (default false)
+>
+  Loading resources...
+</Shimmer>
+```
+
 ### Button
 
 Used in [modal-form](examples/modal-form.jsx)
@@ -492,7 +751,7 @@ Keys: escape to close.
 
 Used in [explorer](examples/explorer.jsx), [reader](examples/reader.jsx), [highlight](examples/highlight.jsx)
 
-Scrollable text viewer with optional scrollbar. Content can include ANSI escape sequences (SGR) - colors, bold, dim, etc. are parsed and rendered correctly. This means you can pipe output from any syntax highlighter (shiki, cli-highlight, etc.) directly into `content`.
+Scrollable text viewer. ANSI escape sequences are parsed and rendered, so syntax highlighter output (shiki, cli-highlight, etc.) works directly.
 
 ```jsx
 <ScrollableText
@@ -501,12 +760,117 @@ Scrollable text viewer with optional scrollbar. Content can include ANSI escape
   scrollOffset={offset}    // controlled, or omit for internal state
   onScroll={setOffset}
   scrollbar={true}         // default false
-  wrap={false}             // default true, set false for horizontal scroll
+  wrap={false}             // default true, false truncates long lines
+  thumbChar="█"            // default █
+  trackChar="│"            // default │
 />
 ```
 
 Keys: same as List (j/k, g/G, ctrl-d/u, ctrl-f/b, pageup/pagedown).
 
+### ScrollBox
+
+Scrollable container for JSX children (vs ScrollableText which takes a string).
+
+```jsx
+<ScrollBox
+  focused={fm.is('list')}
+  scrollbar={true}          // default false
+  scrollOffset={offset}     // controlled, or omit for internal state
+  onScroll={setOffset}
+  thumbChar="█"             // default █
+  trackChar="│"             // default │
+  style={{ flexGrow: 1 }}   // pass-through style for the scroll container
+>
+  {items.map(item => (
+    <text key={item.id}>{item.name}</text>
+  ))}
+</ScrollBox>
+```
+
+Keys: same as List and ScrollableText.
+
+### SplitPane
+
+Paneled layout with shared borders and junction characters. Sizes use `fr` units or fixed values.
+
+```jsx
+import { SplitPane } from '@trendr/core'
+
+<SplitPane direction="row" sizes={[20, '2fr', '1fr']} border="round" borderColor="gray">
+  <box style={{ paddingX: 1 }}>
+    <text>sidebar</text>
+  </box>
+  <box style={{ paddingX: 1 }}>
+    <text>main content</text>
+  </box>
+  <box style={{ paddingX: 1 }}>
+    <text>detail</text>
+  </box>
+</SplitPane>
+```
+
+Props:
+- `direction` - `'row'` (vertical dividers) or `'column'` (horizontal dividers)
+- `sizes` - array of fixed numbers or `'Nfr'` strings. `[20, '1fr']` = 20 cols fixed + rest. `['1fr', '1fr']` = even split. Defaults to equal fractions.
+- `border` - `'single'` | `'double'` | `'round'` | `'bold'`
+- `borderColor` - color for border and dividers
+- `borderEdges` - object with `top`, `right`, `bottom`, `left` booleans to render only specific sides. Omitted keys default to false.
+
+Nesting works:
+
+```jsx
+<SplitPane direction="column" sizes={['1fr', 8]} border="round">
+  <SplitPane direction="row" sizes={[20, '1fr']} border="round">
+    <box>nav</box>
+    <box>main</box>
+  </SplitPane>
+  <box>status</box>
+</SplitPane>
+```
+
+## Animation
+
+Physics-based animation. Animated values are signals that trigger re-renders.
+
+```jsx
+import { useAnimated, spring, ease, decay } from '@trendr/core'
+
+const x = useAnimated(0, spring())    // spring physics
+x.set(100)                            // animate to 100
+x()                                   // read current value (tracks as signal)
+x.snap(50)                            // jump instantly, no animation
+```
+
+`useAnimated` is the hook version (auto-cleanup on unmount). `animated` is the standalone version for use outside components.
+
+### Interpolators
+
+```js
+spring({ frequency: 2, damping: 0.3 })   // underdamped spring (bouncy)
+spring({ damping: 1 })                    // critically damped (no bounce)
+ease(300)                                 // 300ms ease-out-cubic
+ease(500, linear)                         // 500ms linear
+decay({ deceleration: 0.998 })            // momentum-based decay
+```
+
+Switch interpolator mid-animation:
+
+```js
+x.setInterpolator(ease(200))
+x.set(newTarget)
+```
+
+### Easing functions
+
+`linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutElastic()`, `easeOutBounce()`
+
+### Tick callback
+
+```js
+x.onTick((value) => { /* called each frame while animating */ })
+```
+
 ## Build
 
 Uses esbuild. JSX configured with `jsxImportSource: 'trend'`.