tickup 1.0.34 → 1.0.37

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

@@ -1,24 +1,24 @@
 # Props & chart options
 
+For **exhaustive tables** (every host prop, `TickUpRenderEngine`, and `chartOptions` field with types, defaults, and Standard Tier notes), see **[API reference](./16-api-reference.md)**. This page is a shorter narrative companion.
+
 ## `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). |
+| `intervalsArray` | OHLCV series (`Interval[]`). Default `[]`. Clamped to **5,000** bars (Standard Tier). |
+| `initialVisibleTimeRange` | On the type for API stability; **not wired** in `TickUpHost` today — use ref pan/fit or load data first. |
+| `initialNumberOfYTicks` | Seeds `chartOptions.axes.numberOfYTicks` when that axis field is omitted in `chartOptions` (default **5**). |
+| `initialXAxisHeight` | **Not read** by the host today; layout uses internal constants. |
+| `initialYAxisWidth` | **Not read** by the host today. |
 | `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.
+Type: `DeepPartial<ChartOptions>`. Merged with library defaults (`DEFAULT_GRAPH_OPTIONS`). Pass a **stable** reference (`useMemo`) when values do not change every render, so toolbar-driven state is not overwritten by a new `{}` each time.
 
 ### Layout (only without `productId`)
 
@@ -26,55 +26,47 @@ When you **do** change options intentionally, any deep change triggers a merge i
 |------|---------|
 | `showSidebar` | Drawing tools column. |
 | `showTopBar` | Symbol + chart controls row. |
-| `showSettingsBar` | Gear and related controls in the top cluster. |
+| `showSettingsBar` | Gear and related controls. |
 
 ### 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.
+| `symbol` | Controlled symbol (top bar when shown). |
+| `defaultSymbol` | Initial symbol when `symbol` is **omitted**. |
+| `onSymbolChange` | Top-bar symbol edits (Flow, Command, Desk). |
+| `onSymbolSearch` | Search submit; return **`false`** or **reject** to revert input. |
+| `onRefreshRequest` | User chose Refresh. |
 
-`getChartContext()` still reports the same symbol metadata for introspection.
+**Top bar hidden** (e.g. Pulse): use **`symbol`** / **`defaultSymbol`** for the compact strip; see [Toolbar & interactions](./10-toolbar-and-interactions.md).
 
 ### 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. |
+| `productId` | Lock layout (`pulse` \| `flow` \| `command` \| `desk` \| `prime`). |
+| `showAttribution` | In-chart TickUp watermark (Desk forces on). |
+| `licenseKey` | For `productId: 'prime'`: evaluation vs licensed chrome (Prime product). |
+| `themeVariant` / `defaultThemeVariant` / `onThemeVariantChange` | Shell light/dark. |
 
 ### 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).
+- Shell props drive **`GlobalStyle`**, settings modal chrome, and toolbar surfaces.
+- Plot colors come from **`chartOptions`** (`base.theme`, `base.style`, …). Align shell and chart theme for readable grid and watermarks.
 
 ## `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
+    engine?,             // rendering profile key (Standard Edition defaults to Canvas 2D)
+    chartType,
     theme,
     showOverlayLine,
     showHistogram,
-    showCrosshair,       // hover cross lines
-    showCrosshairValues, // time/price labels on crosshair
-    showCandleTooltip,   // OHLC hover panel
+    showCrosshair,
+    showCrosshairValues,
+    showCandleTooltip,
     style: { candles, line, area, bar, histogram, grid, overlay, axes, drawings, showGrid, backgroundColor },
     overlays?, overlayKinds?,
   },
@@ -84,34 +76,32 @@ ChartOptions = {
 
 ### 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.
+- **`showCrosshair`** — Guide lines in navigation mode.  
+- **`showCrosshairValues`** — Time/price labels (requires crosshair).  
+- **`showCandleTooltip`** — OHLC / change / volume panel.
 
 ### 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).
+Under `base.style.axes`: locale, decimals, currency, sessions, holidays, 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.
+- **`base.showOverlayLine`** — Draw indicator lines.  
+- **`base.overlays`** — `OverlayWithCalc[]` (recommended).  
+- **`base.overlayKinds`** — Shorthand list.
 
-See [Overlays & indicators](./12-overlays-and-indicators.md).
+Standard Tier: **three** overlays maximum. See [Overlays & indicators](./12-overlays-and-indicators.md).
 
-### Drawings default style
+### Standard Tier: data volume & live cadence
 
-Under `base.style.drawings`: line color, width, line style, fill, and **selected** state styling.
+**TickUp Core** (Standard Tier) keeps at most **5,000** bars in the rendered series and throttles rapid live merges to about **1 Hz** on Standard shells so dashboards stay responsive. If you need deeper history or faster merge cadence without that throttle, evaluate **Prime** (see [Comparison showcase](./18-comparison-showcase.md)).
 
-See also existing reference: [`docs/Documentation/ChartStyleOptions.md`](../docs/Documentation/ChartStyleOptions.md) if present for extra detail; defaults live in `src/components/DefaultData.ts`.
+### Drawings default style
 
-### Pro Tip
+`base.style.drawings`: line, fill, selection styling.
 
-Keep your `chartOptions` stable in core, then layer Prime engine patches for premium rendering without changing your component contracts.
+---
 
-### Prime Showcase
+## Tier comparison: TickUp Prime
 
-[Explore the TickUp Prime Showcase](https://bardamri.github.io/tickup-charts/)
+**TickUp Prime** documents optional engine patches and commercial styling. **TickUp Core** integration does not require them. **[Prime docs](https://github.com/BARDAMRI/tickup-prime)** · **[Showcase](https://bardamri.github.io/tickup-charts/)**

package/documentation/06-imperative-api.md

@@ -1,66 +1,64 @@
 # Imperative API (ref handle)
 
-Obtain a handle with `useRef<TickUpHostHandle>()` (or `TickUpHostHandle`) and attach `ref` to `TickUpCommand`, `TickUpHost`, etc.
+Host **props** and **`chartOptions`** field tables: **[API reference](./16-api-reference.md)**.
+
+**Standard Tier:** `applyLiveData`, `addInterval`, and related paths still enforce the **5,000**-bar cap and (on Standard shells) the **~1 Hz** live merge throttle — same as the `intervalsArray` prop path. See [Data & live updates](./07-data-and-live-updates.md).
+
+Use `useRef<TickUpHostHandle>()` and attach `ref` to `TickUpCommand`, `TickUpHost`, or another supported shell.
 
 ## 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. |
+| `addShape(shape)` | Add from `DrawingSpec` or shape instance (`DrawingInput`). |
+| `updateShape(shapeId, newShape)` | Replace or apply a `DrawingPatch` (see `isDrawingPatch`). |
+| `patchShape(shapeId, patch)` | `DrawingPatch` only. |
 | `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. |
+| `deleteSelectedDrawing()` | Remove selected shape. |
+| `updateSelectedShape(patch)` | Patch selected shape. |
 | `setDrawingsFromSpecs(specs)` | Replace stack from `DrawingSpec[]`. |
 
-Helpers exported from the package: `drawingFromSpec`, `applyDrawingPatch`, `isDrawingPatch`.
+Helpers: `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). |
+| `addInterval(interval)` | Append; series sorted by `t`. |
+| `updateInterval(index, interval)` | Replace at **0-based** index. |
+| `deleteInterval(index)` | Remove at index. |
+| `applyLiveData(updates, placement)` | Streaming merges; 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`.
+Prefer **`mergeByTime`** for time-keyed upserts. Indices refer to the **trimmed** series under Standard Tier rules.
 
 ## 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. |
+| `fitVisibleRangeToData()` | Fit visible time to loaded data. |
+| `nudgeVisibleTimeRangeToLatest(options?)` | Pan so the last bar stays in view when needed. |
+| `getMainCanvasElement()` | Main OHLC canvas. |
+| `getCanvasSize()` | `{ width, height, dpr }`. |
+| `getVisibleRanges()` | `VisibleViewRanges`: visible time + price. May be **`null`** until mount — use `?.`. |
+| `clearCanvas()` | Clear buffers and drawings. |
+| `redrawCanvas()` | Redraw with current state. |
+| `reloadCanvas()` | Reload path for current intervals. |
+| `setEngine(engine)` | Merge a **`TickUpChartEngine`** patch into live **`chartOptions`** (optional profiles from **`tickup/full`**). |
+| `setInteractionMode(mode)` | Drawing / navigation mode (`Mode` enum). |
+| `selectShape(id)` / `unselectShape()` | Selection control. |
 
 ## 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. |
+| `getViewInfo()` | Intervals, drawings, ranges, canvas size. **`null`** until ready — use `?.`. |
+| `getDrawings(query?)` | `DrawingSnapshot[]`. |
+| `getDrawingById(id)` | One snapshot or null. |
+| `getSelectedDrawing()` / `getSelectedDrawingId()` | Current selection. |
+| `getDrawingInstances(query?)` | Live `IDrawingShape[]` (advanced). |
+| `getChartContext()` | Symbol, chart type, theme, layout, data window, drawing count. |
 
-## 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.
+## Example: visible ranges
 
 ```tsx
 import { useEffect, useRef } from 'react';
@@ -72,18 +70,17 @@ 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);
+      console.log('visible unix sec', v.time.start, v.time.end);
     }
   }, 1000);
   return () => clearInterval(t);
 }, []);
 ```
 
-## Example: add and patch a line
+## Example: add a line
 
 ```tsx
-import { ShapeType, type TickUpHostHandle } from 'tickup/full';
+import { ShapeType } from 'tickup/full';
 
 ref.current?.addShape({
   type: ShapeType.Line,
@@ -93,33 +90,10 @@ ref.current?.addShape({
   ],
   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();
 ```
 
-### Pro Tip
-
-Prime workflows benefit most from the imperative API when you need precise runtime control over rendering mode, overlays, and drawing orchestration.
+---
 
-### Prime Showcase
+## Tier comparison: TickUp Prime
 
-[Explore the TickUp Prime Showcase](https://bardamri.github.io/tickup-charts/)
+Commercial Prime deployments may expose additional runtime controls. **TickUp Core** APIs above are the supported baseline. **[TickUp Prime](https://github.com/BARDAMRI/tickup-prime)** · **[Showcase](https://bardamri.github.io/tickup-charts/)**

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

@@ -1,7 +1,20 @@
 # Data & live updates
 
+## Standard Tier guardrails
+
+**TickUp Core** applies the following on every ingest path (initial props, history refresh, and live merges):
+
+| Guardrail | Behavior |
+|-----------|----------|
+| **History depth** | Only the **last 5,000** candles are kept for rendering and downstream calculations. Older bars are discarded (`slice(-5000)` semantics). |
+| **Live update rate** | On Standard product shells, rapid `applyLiveData` / prop updates are **throttled to about 1 second** between applied frames so the UI stays stable. Licensed Prime-tier host configurations may opt out of this throttle. |
+
+If your feed sends more than 5,000 bars, trim server-side as well to save bandwidth; the chart will still enforce the cap client-side.
+
 ## `Interval` shape
 
+What **open / high / low / close** mean in practice, and how to debug bad data: **[Interval schema & debugging](./17-interval-schema-and-debugging.md)**.
+
 ```ts
 interface Interval {
   t: number; // unix seconds
@@ -17,54 +30,53 @@ 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.
+Supply the series from parent state. When the reference or backing data changes, the stage syncs and applies Standard Tier clamping.
 
 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[]`.  
+- **updates** — One `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). |
+| Value | Behavior |
+|-------|----------|
+| `replace` | Replace series with normalized incoming set. |
+| `append` | Append bars with `t` ≥ last bar’s `t`; same `t` replaces last. |
+| `prepend` | Prepend bars with `t` ≤ first bar’s `t`; same `t` replaces first. |
+| `mergeByTime` | Concatenate, sort by `t`, dedupe by time (last wins). |
 
-**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.
+Returns **`LiveDataApplyResult`**: `{ ok, intervals, errors, warnings }`. Check `ok` in production.
 
 ## 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.
+- **`normalizeInterval`**, **`normalizeIntervals`**  
+- **`dedupeByTimePreferLast`**  
+- **`applyLiveDataMerge`**
 
-`onRefreshRequest` fires when the user chooses Refresh. Reload your feed, set new `intervalsArray`, or call `reloadCanvas` / `fitVisibleRangeToData` as needed.
+## Timeframe changes
 
-## Timeframe / Interval changes
+Use **`onIntervalSearch(tf)`** on **`TickUpHost`** to load data for a new timeframe. See [Toolbar & interactions](./10-toolbar-and-interactions.md).
 
-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).
+## Pitfalls
 
-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.
+- Do not pass a **new** `chartOptions={{}}` every render without `useMemo`; see [Props & chart options](./05-props-and-chart-options.md).  
+- Keep `t` ordering consistent with your merge mode.
 
-## Pitfalls
+## Troubleshooting (Standard Tier)
 
-- 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.
+| Observation | Explanation |
+|---------------|-------------|
+| Bar count stuck at **5,000** | **By design** — older bars are dropped client-side. Trim server-side too to save bandwidth. |
+| Live path updates ~once per second | **By design** — **~1 Hz** throttle on Standard shells. Prime license may opt out of throttling. |
+| Indicators look “wrong” on huge CSV | Overlays only see the **last 5,000** bars; verify your window matches expectations. |
 
-### Pro Tip
+More symptoms: [Interval schema & debugging](./17-interval-schema-and-debugging.md), [API reference](./16-api-reference.md).
 
-Prime deployments pair live merge flows with high-density rendering profiles to keep interaction smooth on larger streaming datasets.
+---
 
-### Prime Showcase
+## Tier comparison: TickUp Prime
 
-[Explore the TickUp Prime Showcase](https://bardamri.github.io/tickup-charts/)
+**TickUp Prime** targets higher update rates and much larger histories than the **5,000**-candle Standard Tier baseline. Evaluate **[TickUp Prime](https://github.com/BARDAMRI/tickup-prime)** and the **[showcase](https://bardamri.github.io/tickup-charts/)**.

package/documentation/08-drawings-and-shapes.md

@@ -6,16 +6,14 @@
 |------|----------------|
 | **Line** | 2 points: start and end (time/price). |
 | **Rectangle** | 2 corners (diagonal). |
-| **Circle** | 2 points: center and rim (or bounding logic per implementation). |
-| **Triangle** | 3 vertices (polyline workflow may add progressively). |
+| **Circle** | 2 points: center and rim. |
+| **Triangle** | 3 vertices. |
 | **Angle** | Vertex + two rays (two-phase placement in UI). |
 | **Arrow** | 2 points: tail and head. |
 | **Polyline** | Multiple vertices; double-click to finish in UI. |
-| **CustomSymbol** | 1 anchor point + `symbol` string + `size`. |
+| **CustomSymbol** | 1 anchor + `symbol` string + `size`. |
 
-## Toolbar (Command / Desk / custom host with sidebar)
-
-The visible **sidebar** exposes these tools only:
+## Toolbar (Command / Desk / host with sidebar)
 
 | Tool | Mode |
 |------|------|
@@ -27,33 +25,29 @@ The visible **sidebar** exposes these tools only:
 | Select | `select` |
 | Edit | `editShape` |
 
-**Not on the toolbar** (but fully supported via **code**): **Arrow**, **Polyline**, **Custom symbol** (`ShapeType.Arrow` / `Polyline` / `CustomSymbol`). Use `addShape` / `DrawingSpec` for those.
+**Not on the default toolbar** (supported via code): **Arrow**, **Polyline**, **CustomSymbol**. Use `addShape` / `DrawingSpec`.
 
-The enum also includes **`Mode.drawText`** for future use; there is no text drawing tool in the default toolbar today.
+The enum may include **`Mode.drawText`** for future use; there is no text tool in the default toolbar today.
 
-Click the active tool again to return to default navigation (`Mode.none`).
+Click the active tool again to return to **`Mode.none`**.
 
-### Creating shapes with the mouse
+### Mouse workflow
 
 1. Choose a draw tool.  
-2. Click (and drag or multi-click per tool) on the plot.  
-3. Shapes commit when enough points are placed (tool-specific).
+2. Click (and drag or multi-click per tool).  
+3. Shapes commit when enough points are placed.
 
-**Polyline** (programmatic / custom UI only in the default product): add vertices with clicks; **double-click** finishes the path. **Angle** uses a two-step flow (first ray, then second ray) before committing.
+**Polyline**: double-click finishes. **Angle**: two-step ray placement.
 
 ### Select & edit
 
-- **Select** — Click a shape to highlight (top-most hit wins).  
-- **Edit** — Adjust handles where implemented.  
-- **Double-click** a shape (in select/navigation modes) or **right‑click** a **selected** shape to open **Shape properties** — modal fields include line color/width/style, fill, selection styling, and for custom symbols: text + size (`ShapePropertiesFormState`).
-
-The shell uses the exported **`ShapePropertiesModal`** component wired to `onRequestShapeProperties` on the canvas; you can reuse it in custom hosts.
+- **Select** — Top-most hit wins.  
+- **Edit** — Handles where implemented.  
+- **Double-click** or **right‑click** (selected) opens **Shape properties** (`ShapePropertiesModal`): line, fill, selection styling; custom symbols: text + size.
 
-  size?: number;
-};
-```
+The shell wires **`ShapePropertiesModal`** via `onRequestShapeProperties`.
 
-Minimum points per type are enforced in `drawingFromSpec` (e.g. 2 for line/rect/circle/arrow).
+Minimum points are enforced in `drawingFromSpec`.
 
 ```tsx
 chartRef.current?.addShape({
@@ -63,78 +57,38 @@ chartRef.current?.addShape({
 });
 ```
 
-## Programmatic tools & drawing by code
-
-You can trigger any drawing tool programmatically (as if the user clicked the toolbar) using **`setInteractionMode(Mode)`**:
+## Programmatic tools
 
 ```tsx
 import { Mode } from 'tickup/full';
 
-// Start the rectangle tool
 chartRef.current?.setInteractionMode(Mode.drawRectangle);
-
-// Cancel/return to navigation
 chartRef.current?.setInteractionMode(Mode.none);
 ```
 
-### Direct insertion
-Use **`addShape(DrawingSpec)`** to instantly place a shape on the chart without user interaction (e.g., loading saved annotations).
+Use **`addShape(DrawingSpec)`** to insert without UI interaction.
 
-## Programmatic selection and management
-
-In addition to UI interaction, you can fully control the selection state via the API:
-
-*   **`selectShape(id)`**: Highlights and selects a specific drawing by its ID.
-*   **`unselectShape()`**: Clears the current selection.
-*   **`getSelectedDrawing()`**: Returns the plain data snapshot of the currently active drawing (or `null`).
-*   **`getSelectedDrawingId()`**: Returns the ID of the selected drawing.
-
-```tsx
-const selected = chartRef.current?.getSelectedDrawing();
-if (selected) {
-    console.log("Editing shape of type:", selected.type);
-}
-```
+## Selection API
 
-## Programmatic updates \& deletion
+- `selectShape(id)`, `unselectShape()`  
+- `getSelectedDrawing()`, `getSelectedDrawingId()`  
+- `updateSelectedShape(patch)`, `deleteSelectedDrawing()`
 
-### Specific shape (by ID)
-*   **`updateShape(id, data)`**: Full replacement.
-*   **`patchShape(id, patch)`**: Partial property update (color, width, points).
-*   **`deleteShape(id)`**: Remove the shape.
+## Updates & deletion
 
-### Selection-centric (Convenience)
-*   **`updateSelectedShape(patch)`**: Updates the properties of whichever shape is currently selected.
-*   **`deleteSelectedDrawing()`**: Removes the current selection from the chart.
-
-```tsx
-// Force the selected shape to be red
-chartRef.current?.updateSelectedShape({
-    style: { lineColor: '#ff0000' }
-});
-```
-
-## Bulk replace
-
-`setDrawingsFromSpecs(specs: DrawingSpec[])` rebuilds the entire overlay stack from JSON-friendly specs (e.g. after loading a layout from your server).
+- `updateShape`, `patchShape`, `deleteShape` by id.  
+- `setDrawingsFromSpecs(specs)` — bulk replace.
 
 ## Query & persistence
 
-- `getDrawings(query?)` — Filter by `types`, `ids`, `idPrefix`, time/price bounds, or custom `predicate`.  
-- `shapeToSnapshot` / `queryDrawingsToSnapshots` — Export plain objects for storage.
+`getDrawings(query?)`, `shapeToSnapshot`, `queryDrawingsToSnapshots` — export plain objects for storage.
 
 ## Coordinate space
 
-`DrawingPoint` uses **time** (unix seconds) and **price** (Y value), not pixels. The canvas maps these using the current visible ranges.
-
-## Shape properties UI
-
-`ShapePropertiesModal` is exported for advanced hosts who want to embed the same form outside the default flow. The shell wires it from the chart when editing.
-
-### Pro Tip
+`DrawingPoint` uses **time** (unix seconds) and **price**, not pixels.
 
-Note: Advanced drawing tools like Fibonacci Retracements are available exclusively in TickUp Prime.
+---
 
-### Prime Showcase
+## Tier comparison: TickUp Prime
 
-[Explore the TickUp Prime Showcase](https://bardamri.github.io/tickup-charts/)
+Additional drawing and analysis tooling may ship with the commercial product. **TickUp Core** covers the shapes and APIs above. **[TickUp Prime](https://github.com/BARDAMRI/tickup-prime)** · **[Showcase](https://bardamri.github.io/tickup-charts/)**