tickup 1.0.0

package/documentation/01-glossary.md

@@ -0,0 +1,61 @@
+# Glossary
+
+## Data
+
+- **Interval** — One bar or tick row: open, high, low, close, time (`t` in **Unix seconds**), optional volume (`v`). See `Interval` type.
+- **Series** — Ordered array of intervals, usually sorted by `t`.
+- **Time range** — Visible window on the X axis: `start` and `end` (Unix seconds). Indices `startIndex` / `endIndex` refer to positions in the loaded series.
+- **Price range** — Visible Y window: min/max prices and derived `range` span.
+
+## Chart presentation
+
+- **Chart type** — `ChartType`: Candlestick, Line, Area, Bar (OHLCV rendering mode).
+- **Theme** — `base.theme` on the chart (`light`, `dark`, `grey`) plus **`TickUpHost`** shell theme: **`themeVariant`** (controlled), **`defaultThemeVariant`**, **`onThemeVariantChange`** (**`GlobalStyle`** / modal chrome). Align chart and shell for readable grid and watermarks.
+- **Axes** — Time (X) and price (Y) scales, tick formatting, locale, timezone options under `chartOptions.base.style.axes` and `chartOptions.axes`.
+- **Histogram** — Volume bars below (or proportionally to) the main plot when `showHistogram` is true.
+- **Overlay** — Additional computed or static series drawn on top of price (see overlay types in code).
+
+## Products (tiers)
+
+TickUp ships **named product components** that fix toolbar layout:
+
+| Product   | Typical use |
+|-----------|-------------|
+| **Pulse** | Minimal embed: plot + axes only; optional **compact symbol strip** if `symbol` / `defaultSymbol` is non-empty |
+| **Flow**  | Top bar (symbol, settings, chart type); no drawing sidebar |
+| **Command** | Full UI: side drawing bar + top bar |
+| **Desk**  | Same as Command; in-chart branding watermark required |
+
+Use **`TickUpHost`** **without** `productId` to control `showSidebar` / `showTopBar` / `showSettingsBar` yourself.
+
+**Prime** may refer to **`productId: 'prime'`** (**`TickUpPrimeTier`**) or the **`prime`** render engine (**`chartOptions.base.engine`** / **`TickUpPrime`**). See [Prime engine & Pro roadmap](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md).
+
+## Live data
+
+- **Placement** — How new bars are merged: `replace`, `append`, `prepend`, `mergeByTime` (`LiveDataPlacement`).
+- **Apply result** — `LiveDataApplyResult`: success flag, resulting intervals, `errors`, `warnings`.
+
+## Drawings
+
+- **Shape** — User or API-created overlay: line, rectangle, circle, triangle, angle, arrow, polyline, custom symbol (`ShapeType`).
+- **Drawing spec** — Plain object `{ type, points, style?, id?, symbol?, size? }` for creation (`DrawingSpec`).
+- **Patch** — Partial update `{ style?, points?, symbol?, size? }` (`DrawingPatch`).
+- **Z-index** — Stack order: later shapes draw above earlier ones; hit-testing uses top-most first.
+
+## Interaction modes
+
+Internal drawing **mode** (toolbar) toggles between none, draw tools, select, and edit. Pan/zoom applies when mode is default navigation.
+
+## Snapshot / export
+
+- **Main canvas** — OHLC layer only (no histogram/drawings) via `getMainCanvasElement`.
+- **Chart region snapshot** — PNG of the composed view (plot + axes) via `captureChartRegionToPngDataUrl` and toolbar integration.
+
+## Indicators
+
+- **Overlay** — A computed line series (e.g. SMA) drawn over price; configured via `base.showOverlayLine` and `base.overlays` or `base.overlayKinds`. See [Overlays & indicators](./12-overlays-and-indicators.md).
+
+## Market calendar (axes)
+
+- **Trading session** — Recurring weekday window (`dayOfWeek` + `HH:mm` start/end) used to dim time outside regular hours.
+- **Holiday** — ISO date string list for calendar-aware behavior where applied.

package/documentation/01-introduction.md

@@ -0,0 +1,7 @@
+# Introduction
+
+TickUp is a high-performance React charting library for financial OHLCV workflows, built on Canvas 2D with product-grade UI tiers and an imperative API for real-time updates.
+
+You can start with the open-source core package for charting, drawing tools, overlays, and streaming data, then move to the **Prime Engine** as the professional upgrade path when you need premium visual rendering profiles and advanced Pro capabilities.
+
+For onboarding, continue to [Installation](./02-installation.md) and [Quick start](./03-quick-start.md).

package/documentation/02-installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+## Requirements
+
+- **React** 18 or 19  
+- **react-dom** 18 or 19  
+- **styled-components** 6.x  
+
+These are **peer dependencies**; your app must install them.
+
+## npm
+
+```bash
+npm install tickup
+```
+
+With peer dependencies in a single command:
+
+```bash
+npm install tickup react react-dom styled-components
+```
+
+## TypeScript
+
+Types ship with the package (`dist/index.d.ts`). Enable `strict` as usual; import types from `tickup`.
+
+## Bundler notes
+
+- **ESM** entry: `tickup` → `dist/index.es.js`  
+- **CJS** entry: `dist/index.cjs.js`  
+
+Vite, Webpack, and Next.js typically resolve the correct format automatically.
+
+## Styled-components
+
+TickUp uses styled-components for layout and themed UI. Ensure your app wraps the tree appropriately (e.g. single `ThemeProvider` if you use one globally; TickUp does not require a specific theme object for its internal styled components).
+
+## Verify
+
+```tsx
+import { TickUpCommand } from 'tickup/full';
+
+export function SmokeTest() {
+  return <TickUpCommand style={{ height: 400 }} />;
+}
+```
+
+You still need to pass `intervalsArray` (can be `[]` for an empty chart). See [Quick start](./03-quick-start.md).

package/documentation/03-quick-start.md

@@ -0,0 +1,86 @@
+# Quick start
+
+### Prime Preview
+![The "Hero" Prime Neon](../assets/showcase/hero-prime-neon.png)
+*Luxury rendering and neon effects enabled via `@tickup/prime`.*
+
+TickUp Charts is **React-first**: embed **`TickUpHost`**, **`TickUpStage`**, or product components (`TickUpCommand`, …). There is **no** imperative `TickUpCore(container)` class — use props + refs (e.g. **`ref.setEngine(TickUpPrime)`** for **dark** Prime, or **`createTickUpPrimeEngine('light')`** when the shell is light). See [Prime engine & Pro roadmap](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md).
+
+## 1. Render a product component
+
+```tsx
+import { useRef } from 'react';
+import { TickUpCommand, type TickUpHostHandle } from 'tickup/full';
+
+const sample = [
+  { t: 1700000000, o: 100, h: 102, l: 99, c: 101, v: 1200 },
+  { t: 1700000060, o: 101, h: 103, l: 100, c: 102, v: 900 },
+];
+
+export function App() {
+  const chartRef = useRef<TickUpHostHandle>(null);
+
+  return (
+    <div style={{ height: 480, width: '100%' }}>
+      <TickUpCommand
+        ref={chartRef}
+        intervalsArray={sample}
+        defaultSymbol="DEMO"
+      />
+    </div>
+  );
+}
+```
+
+`TickUpCommand` is the full-trader layout. For a minimal plot only, use **`TickUpPulse`** (same props, different chrome). Pass **`symbol`** or **`defaultSymbol`** so the ticker appears in a **compact strip** above the chart (Pulse has no top-bar symbol field). See [Products & layout](./04-products-and-layout.md) and [Toolbar & interactions](./10-toolbar-and-interactions.md).
+
+## 2. Give the chart a sized parent
+
+The chart fills its container. Use explicit `height` (and usually `width` or flex) on a wrapper `div`.
+
+## 3. Updating data from React state
+
+Control the series with props:
+
+```tsx
+const [bars, setBars] = useState<Interval[]>(initial);
+
+<TickUpCommand ref={chartRef} intervalsArray={bars} />;
+```
+
+When `intervalsArray` changes reference or content, the stage syncs. For streaming updates without replacing the whole array, prefer the **imperative** API below.
+
+## 4. Imperative live updates
+
+```tsx
+const r = chartRef.current?.applyLiveData(
+  { t: 1700000120, o: 102, h: 104, l: 101, c: 103, v: 1100 },
+  'append'
+);
+if (r && !r.ok) console.warn(r.errors);
+```
+
+See [Data & live updates](./07-data-and-live-updates.md).
+
+## 5. Optional: `chartOptions`
+
+Pass a **stable** object (e.g. `useMemo`) so you do not reset internal UI state on every render:
+
+```tsx
+const options = useMemo(
+  () => ({
+    base: { showHistogram: true },
+    axes: { yAxisPosition: AxesPosition.left, numberOfYTicks: 5 },
+  }),
+  []
+);
+
+<TickUpCommand chartOptions={options} intervalsArray={bars} />;
+```
+
+See [Props & chart options](./05-props-and-chart-options.md).
+
+## Next
+
+- [Products & layout](./04-products-and-layout.md) — choose the right tier  
+- [Imperative API](./06-imperative-api.md) — full ref surface  

package/documentation/04-products-and-layout.md

@@ -0,0 +1,51 @@
+# Products & layout
+
+## Product components
+
+Import from **`tickup/full`**:
+
+| Export | `productId` | Side drawing bar | Top bar | Settings entry |
+|--------|-------------|------------------|---------|----------------|
+| `TickUpPulse` | `pulse` | No | No | No |
+| `TickUpFlow` | `flow` | No | Yes | Yes |
+| `TickUpCommand` | `command` | Yes | Yes | Yes |
+| `TickUpDesk` | `desk` | Yes | Yes | Yes (branding on) |
+| `TickUpPrimeTier` | `prime` | Yes | Yes | Yes |
+
+Props types: `TickUpPulseProps`, `TickUpFlowProps`, etc. Product components **omit** `showSidebar`, `showTopBar`, and `showSettingsBar` from their public props; those are fixed per tier.
+
+### Prime tier vs Prime engine
+
+- **`TickUpPrimeTier`** — Same chrome as **Command**; shows an **evaluation strip** when **`licenseKey`** is unset.  
+- **`TickUpPrime`** (engine) — Visual profile: **`chartOptions.base.engine: 'prime'`** or **`ref.setEngine(TickUpPrime)`** (dark plot). For a **light** Prime plot, use **`getTickUpPrimeThemePatch('light')`** / **`createTickUpPrimeEngine('light')`**. Usable on **any** tier. See [Prime engine & Pro roadmap](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md).
+
+### Symbol on Pulse (no top bar)
+
+**Pulse** has no symbol field in the toolbar. If you pass a non-empty **`symbol`** (controlled) or **`defaultSymbol`** (fallback when `symbol` is omitted), the stage shows a **compact read-only symbol strip** above the plot (same typography/colors as axis styling). If both resolve to empty after trim, the strip is hidden. See [Toolbar & interactions](./10-toolbar-and-interactions.md).
+
+The same strip appears for **`TickUpHost`** / **`TickUpStage`** whenever **`showTopBar`** is `false` and a symbol string is available — not only for Pulse.
+
+## Custom layout: `TickUpHost`
+
+Use **`TickUpHost`** **without** `productId`:
+
+```tsx
+import { TickUpHost } from 'tickup/full';
+
+<TickUpHost
+  showSidebar
+  showTopBar
+  showSettingsBar
+  intervalsArray={data}
+/>;
+```
+
+Then you control which chrome appears. Settings saved in the modal still respect **locked** layout when `productId` is set on other variants.
+
+## Desk specifics
+
+- **Desk** — `showAttribution` (in-chart watermark) is forced **on**.
+
+## Mode provider
+
+The shell wraps children in **`ModeProvider`** internally. If you use **`TickUpStage`** alone (advanced), wrap with `ModeProvider` yourself. See [Exports & advanced](./11-exports-and-advanced.md).

package/documentation/05-props-and-chart-options.md

@@ -0,0 +1,109 @@
+# Props & chart options
+
+## `TickUpHostProps` / `TickUpHostHandle`
+
+### Data & view
+
+| Prop | Purpose |
+|------|---------|
+| `intervalsArray` | OHLCV series (`Interval[]`). Default `[]`. |
+| `initialVisibleTimeRange` | Optional `TimeRange` (`start`/`end` unix seconds). |
+| `initialNumberOfYTicks` | Default Y tick count (default 5). |
+| `initialXAxisHeight` | X axis height hint (pixels). |
+| `initialYAxisWidth` | Y axis width hint (pixels). |
+| `initialTimeDetailLevel` | `TimeDetailLevel` for axis time density. |
+| `initialTimeFormat12h` | 12h vs 24h time formatting. |
+
+### `chartOptions` (deep partial merge)
+
+Type: `DeepPartial<ChartOptions>`. Merged with library defaults (`DEFAULT_GRAPH_OPTIONS`). **Important:** pass a **stable reference** (`useMemo`) when the object does not meaningfully change, so internal state (e.g. chart type from the toolbar) is not overwritten by a new empty `{}` every render.
+
+When you **do** change options intentionally, any deep change triggers a merge into current state.
+
+### Layout (only without `productId`)
+
+| Prop | Purpose |
+|------|---------|
+| `showSidebar` | Drawing tools column. |
+| `showTopBar` | Symbol + chart controls row. |
+| `showSettingsBar` | Gear and related controls in the top cluster. |
+
+### Toolbar / host hooks
+
+| Prop | Purpose |
+|------|---------|
+| `symbol` | Controlled symbol string (toolbar input when the top bar is shown). |
+| `defaultSymbol` | Initial symbol when `symbol` is **omitted** (uncontrolled). Ignored for display once `symbol` is passed. |
+| `onSymbolChange` | Fired when the user edits the symbol in the **top bar** (Flow, Command, Desk). |
+| `onSymbolSearch` | Search submit (button or Enter) when the top bar is present. Return **`false`** or **reject** the returned `Promise` if loading the symbol failed — the input reverts to the last successfully displayed ticker and **`onSymbolChange`** is invoked with that previous value so controlled state stays consistent. Return **`true`** or **`undefined`** on success. |
+| `onRefreshRequest` | User hit Refresh in toolbar. |
+
+**When the top bar is hidden** (e.g. **Pulse**, or `showTopBar: false` on `TickUpHost`):
+
+- There is no editable symbol control; use React state and pass **`symbol`** (or **`defaultSymbol`** only) from the host.
+- If the resolved text is non-empty (trimmed controlled value, else trimmed `defaultSymbol`), a **read-only symbol strip** is rendered above the chart. Empty string hides it.
+
+`getChartContext()` still reports the same symbol metadata for introspection.
+
+### Other
+
+| Prop | Purpose |
+|------|---------|
+| `productId` | Lock layout to a tier (`pulse` \| `flow` \| `command` \| `desk` \| `prime`). |
+| `showAttribution` | In-chart TickUp watermark (default true; forced on for Desk). Uses transparent bundled marks. |
+| `licenseKey` | For **`productId: 'prime'`**: non-empty value hides the eval strip. |
+| `themeVariant` | Shell **light** \| **dark** — when set, the host is **controlled**; keep it in sync with your app state and update from **`onThemeVariantChange`** when the user toggles theme in the toolbar. |
+| `defaultThemeVariant` | Initial shell theme when **`themeVariant`** is omitted (uncontrolled). Default **`light`**. |
+| `onThemeVariantChange` | Called when the user toggles light/dark from the settings toolbar; use with **`themeVariant`** for controlled mode or alone to observe toggles in uncontrolled mode. |
+
+### Shell vs chart theme
+
+- **`themeVariant` / `defaultThemeVariant` / `onThemeVariantChange`** drive **`GlobalStyle`** (page background), settings-modal chrome, and related shell UI — not the plot alone.
+- Plot colors still come from **`chartOptions`** (`base.theme`, `base.style`, …). Keep them **consistent** with the shell (e.g. light shell + `base.theme: 'light'`) so axes, grid, and watermarks stay readable.
+- For the **Prime** renderer (`base.engine: 'prime'`), use **`getTickUpPrimeThemePatch('light' | 'dark')`** or **`createTickUpPrimeEngine(theme)`** with **`ref.setEngine`** so the merged patch matches your host theme. **`TickUpPrime`** alone applies the **dark** Prime plot; see [Prime engine & Pro roadmap](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md).
+
+## `ChartOptions` structure (high level)
+
+```ts
+ChartOptions = {
+  base: {
+    engine?,             // 'standard' | 'prime' — canvas profile; prime + base.theme 'light' uses light Prime palette & toolbars (see doc 15)
+    chartType,           // Candlestick | Line | Area | Bar
+    theme,
+    showOverlayLine,
+    showHistogram,
+    showCrosshair,       // hover cross lines
+    showCrosshairValues, // time/price labels on crosshair
+    showCandleTooltip,   // OHLC hover panel
+    style: { candles, line, area, bar, histogram, grid, overlay, axes, drawings, showGrid, backgroundColor },
+    overlays?, overlayKinds?,
+  },
+  axes: { yAxisPosition, currency, numberOfYTicks },
+};
+```
+
+### Interaction flags (`base`)
+
+- **`showCrosshair`** — Vertical + horizontal guide lines in default navigation mode.  
+- **`showCrosshairValues`** — Labels for cursor time (along bottom) and price (along Y-axis side). Requires crosshair enabled.  
+- **`showCandleTooltip`** — Corner panel with date, O/H/L/C, change, volume.
+
+These can be toggled from the **Settings** modal (Chart Style → Hover) when using the full shell.
+
+### Axes & formatting
+
+Under `base.style.axes`: locale, language, decimals, currency, date format, timezone, **trading sessions**, **holidays**, exchange, notation, tick size, conversion/display currency fields, etc. See [i18n & axes](./13-internationalization-and-axes.md).
+
+### Overlays / indicators
+
+- **`base.showOverlayLine`** — Master switch for drawing indicator lines on the plot.  
+- **`base.overlays`** — `OverlayWithCalc[]` (recommended for explicit periods).  
+- **`base.overlayKinds`** — Shorthand list of kinds with library default parameters.
+
+See [Overlays & indicators](./12-overlays-and-indicators.md).
+
+### Drawings default style
+
+Under `base.style.drawings`: line color, width, line style, fill, and **selected** state styling.
+
+See also existing reference: [`docs/Documentation/ChartStyleOptions.md`](../docs/Documentation/ChartStyleOptions.md) if present for extra detail; defaults live in `src/components/DefaultData.ts`.

package/documentation/06-imperative-api.md

@@ -0,0 +1,117 @@
+# Imperative API (ref handle)
+
+Obtain a handle with `useRef<TickUpHostHandle>()` (or `TickUpHostHandle`) and attach `ref` to `TickUpCommand`, `TickUpHost`, etc.
+
+## Drawings
+
+| Method | Description |
+|--------|-------------|
+| `addShape(shape)` | Add from `DrawingSpec` or a shape instance (`DrawingInput`). |
+| `updateShape(shapeId, newShape)` | Replace with full spec/instance or apply a `DrawingPatch` (see `isDrawingPatch`). |
+| `patchShape(shapeId, patch)` | `DrawingPatch` only: style, points, symbol/size for custom symbols. |
+| `deleteShape(shapeId)` | Remove by id. |
+| `deleteSelectedDrawing()` | Removes the currently selected shape from the stage. |
+| `updateSelectedShape(patch)` | Update properties (color, points, etc.) of the currently selected shape. |
+| `setDrawingsFromSpecs(specs)` | Replace stack from `DrawingSpec[]`. |
+
+Helpers exported from the package: `drawingFromSpec`, `applyDrawingPatch`, `isDrawingPatch`.
+
+## Intervals (series)
+
+| Method | Description |
+|--------|-------------|
+| `addInterval(interval)` | Append a bar; series is kept sorted by `t`. |
+| `updateInterval(index, interval)` | Replace bar at **0-based index** in the current sorted series. |
+| `deleteInterval(index)` | Remove bar at **0-based index**. |
+| `applyLiveData(updates, placement)` | Preferred for streaming and time-keyed upserts; see [Data & live updates](./07-data-and-live-updates.md). |
+
+Resolve an index with `getViewInfo()?.intervals.findIndex(...)`. For time-based edits, prefer **`mergeByTime`** in `applyLiveData`.
+
+## View & canvas
+
+| Method | Description |
+|--------|-------------|
+| `fitVisibleRangeToData()` | Fit visible time range to loaded data. |
+| `nudgeVisibleTimeRangeToLatest(options?)` | If the last bar is past the right edge, pans the window by the minimum amount so it stays visible (keeps the same time span when possible). Optional `trailingPaddingSec`. No-op if the latest bar is already in view — useful for live streams without calling `fitVisibleRangeToData` every tick. |
+| `getMainCanvasElement()` | Main OHLC `HTMLCanvasElement` (snapshots). |
+| `getCanvasSize()` | `{ width, height, dpr }` (backing store pixels + DPR). |
+| `getVisibleRanges()` | **`VisibleViewRanges`**: current **time** window (`time.start` / `time.end` in **unix seconds**, `time.startIndex` / `time.endIndex` into the sorted series) and **price** band (`price.min`, `price.max`, `price.range`) used for Y-axis scaling. Same values as `getViewInfo().visibleRange` / `.visiblePriceRange`. On **`TickUpHost`** / product refs, returns **`null`** until the inner stage is mounted — use `?.`. Type **`VisibleViewRanges`** is exported from **`tickup`** / **`tickup/full`**. |
+| `clearCanvas()` | Clear off-screen buffers **and** clear the drawings list (shapes removed). |
+| `redrawCanvas()` | Re-run the draw pipeline with current state (no data reload). |
+| `reloadCanvas()` | Stage **reload** hook (rebinds view to current intervals / internal reload path). |
+| `setEngine(engine)` | Merge a **`TickUpChartEngine`** patch into live **`chartOptions`**. Use **`TickUpPrime`** (dark Prime plot), **`createTickUpPrimeEngine('light' \| 'dark')`** (Prime plot aligned to host theme), **`TickUpStandardEngine`**, or a custom **`{ id, getChartOptionsPatch }`**. Imports: **`tickup`** or **`tickup/full`**. Prefer **`getTickUpPrimeThemePatch`** in **`chartOptions`** when applying Prime so props and **`setEngine`** stay in sync — see [Prime engine & Pro roadmap](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md). |
+| `setInteractionMode(mode)` | Forwarded to the stage: same drawing modes as the package toolbar (`Mode` enum from **`tickup/full`**). |
+| `deleteSelectedDrawing()` | Removes the currently selected shape on the stage (no-op if nothing selected). |
+| `selectShape(id)` | Programmatically select a drawing by its ID. |
+| `unselectShape()` | Clear the current selection. |
+| `updateSelectedShape(patch)` | Modify the active selection properties. |
+
+## Introspection
+
+| Method | Description |
+|--------|-------------|
+| `getViewInfo()` | Intervals, drawings instances, visible time/price ranges, canvas size. On **`TickUpHost` / product refs**, this may be **`null`** until the inner stage is mounted — use optional chaining (`?.`) in `useEffect` or after layout. Prefer **`getVisibleRanges()`** when you only need the visible time/price snapshot (no intervals or drawings). |
+| `getDrawings(query?)` | `DrawingSnapshot[]` with optional `DrawingQuery` filter. |
+| `getDrawingById(id)` | Single snapshot or null. |
+| `getSelectedDrawing()` | Get the snapshot of the currently selected drawing. |
+| `getSelectedDrawingId()` | Get the unique ID of the selected drawing. |
+| `getDrawingInstances(query?)` | Live `IDrawingShape[]` for advanced use. |
+| `getChartContext()` | `ChartContextInfo`: symbol, chart type, theme, layout metrics, data window (`data.visibleTimeStart` / `visibleTimeEnd` / indices / price fields mirror **`getVisibleRanges()`**), drawing count, selection index, tick settings. May be `null` from the shell until the stage is ready. |
+
+## Example: read visible ranges after zoom/pan
+
+`time.start` / `time.end` track the plotted X domain (unix seconds). `price.min` / `price.max` include padding around the highs/lows of the bars in view.
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { TickUpCommand, type TickUpHostHandle } from 'tickup/full';
+
+const ref = useRef<TickUpHostHandle>(null);
+
+useEffect(() => {
+  const t = window.setInterval(() => {
+    const v = ref.current?.getVisibleRanges();
+    if (v) {
+      console.log('visible unix sec', v.time.start, v.time.end, 'bars', v.time.startIndex, v.time.endIndex);
+      console.log('visible price', v.price.min, v.price.max);
+    }
+  }, 1000);
+  return () => clearInterval(t);
+}, []);
+```
+
+## Example: add and patch a line
+
+```tsx
+import { ShapeType, type TickUpHostHandle } from 'tickup/full';
+
+ref.current?.addShape({
+  type: ShapeType.Line,
+  points: [
+    { time: t0, price: p0 },
+    { time: t1, price: p1 },
+  ],
+  style: { lineColor: '#ff00aa', lineWidth: 2 },
+});
+
+ref.current?.patchShape('some-id', {
+  style: { lineWidth: 3 },
+});
+```
+
+After `addShape`, read the new id via `getDrawings()` (last / highest `zIndex`) or pass an explicit `id` in `DrawingSpec`.
+
+## Example: programmatic selection and update
+
+```tsx
+// 1. Select a specific shape
+chartRef.current?.selectShape("trend-line-1");
+
+// 2. Modify whichever shape is currently selected (convenience)
+chartRef.current?.updateSelectedShape({
+    style: { lineColor: "#00ff00" }
+});
+
+// 3. Clear focus
+chartRef.current?.unselectShape();
+```

package/documentation/07-data-and-live-updates.md

@@ -0,0 +1,62 @@
+# Data & live updates
+
+## `Interval` shape
+
+```ts
+interface Interval {
+  t: number; // unix seconds
+  o: number;
+  c: number;
+  l: number;
+  h: number;
+  v?: number;
+}
+```
+
+Times are **seconds**, not milliseconds.
+
+## React prop: `intervalsArray`
+
+Supply the full series from parent state. When the array reference or backing data changes, the chart updates.
+
+For high-frequency streaming, prefer **`applyLiveData`** on the ref to avoid reallocating huge arrays on every tick.
+
+## `applyLiveData(updates, placement)`
+
+- **updates** — Single `Interval` or `Interval[]`.  
+- **placement** — `LiveDataPlacement`:
+
+| Value | Behavior (conceptual) |
+|-------|------------------------|
+| `replace` | Replace series with normalized incoming set. Fails `ok` if incoming is empty after validation. |
+| `append` | Append only bars with `t` ≥ last bar’s `t`; same `t` replaces the last bar; earlier times produce **warnings** and are skipped. |
+| `prepend` | Prepend only bars with `t` ≤ first bar’s `t`; same `t` replaces the first bar; later times produce **warnings** and are skipped. |
+| `mergeByTime` | Concatenate, sort by `t`, then **dedupe by time** (last row wins per timestamp). |
+
+**Existing** series is normalized on merge; invalid base rows add to `errors`. Incoming rows go through **`normalizeIntervals`** (OHLC clamping, bad volume dropped, low/high swap notes in `warnings`).
+
+Returns **`LiveDataApplyResult`**: `{ ok, intervals, errors, warnings }`. Always check `ok` and surface `errors` in production; inspect `warnings` for skipped bars or clamping.
+
+## Normalization utilities (exported)
+
+From `tickup`:
+
+- **`normalizeInterval`** — Validate/clamp one partial row; returns `{ value, notes }`.  
+- **`normalizeIntervals`** — Batch version; `errors` / `warnings` arrays.  
+- **`dedupeByTimePreferLast`** — Collapse duplicate `t`.  
+- **`applyLiveDataMerge`** — Lower-level merge helper used by the stage.
+
+Use these server-side or before calling `applyLiveData` if you need consistent cleaning.
+
+`onRefreshRequest` fires when the user chooses Refresh. Reload your feed, set new `intervalsArray`, or call `reloadCanvas` / `fitVisibleRangeToData` as needed.
+
+## Timeframe / Interval changes
+
+While `intervalsArray` provides the chart with data, the user often initiates a change in the required data set by picking a new interval (e.g. from 1m to 1h).
+
+Use **`onIntervalSearch(tf)`** on the `TickUpHost` to intercept these changes. This is the ideal place to swap your data source or fetch a new historical block for the new timeframe. See [Toolbar & Interactions](./10-toolbar-and-interactions.md) for details on the search and revert flow.
+
+## Pitfalls
+
+- Do not pass a **new literal** `chartOptions={{}}` every render without `useMemo`; see [Props & chart options](./05-props-and-chart-options.md).  
+- Ensure `t` is monotonic where your feed requires it; merge modes handle ordering differently.