tickup 1.0.0

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

@@ -0,0 +1,132 @@
+# Drawings & shapes
+
+## Supported shape types (`ShapeType`)
+
+| Type | Points / usage |
+|------|----------------|
+| **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). |
+| **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`. |
+
+## Toolbar (Command / Desk / custom host with sidebar)
+
+The visible **sidebar** exposes these tools only:
+
+| Tool | Mode |
+|------|------|
+| Line | `drawLine` |
+| Rectangle | `drawRectangle` |
+| Circle | `drawCircle` |
+| Triangle | `drawTriangle` |
+| Angle | `drawAngle` |
+| 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.
+
+The enum also includes **`Mode.drawText`** for future use; there is no text drawing tool in the default toolbar today.
+
+Click the active tool again to return to default navigation (`Mode.none`).
+
+### Creating shapes with the mouse
+
+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).
+
+**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.
+
+### 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.
+
+  size?: number;
+};
+```
+
+Minimum points per type are enforced in `drawingFromSpec` (e.g. 2 for line/rect/circle/arrow).
+
+```tsx
+chartRef.current?.addShape({
+  type: ShapeType.Rectangle,
+  points: [{ time: t0, price: p0 }, { time: t1, price: p1 }],
+  style: { lineColor: '#0af', fillColor: 'rgba(0,170,255,0.15)' },
+});
+```
+
+## Programmatic tools & drawing by code
+
+You can trigger any drawing tool programmatically (as if the user clicked the toolbar) using **`setInteractionMode(Mode)`**:
+
+```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).
+
+## 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);
+}
+```
+
+## Programmatic updates \& deletion
+
+### Specific shape (by ID)
+*   **`updateShape(id, data)`**: Full replacement.
+*   **`patchShape(id, patch)`**: Partial property update (color, width, points).
+*   **`deleteShape(id)`**: Remove the shape.
+
+### 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).
+
+## Query & persistence
+
+- `getDrawings(query?)` — Filter by `types`, `ids`, `idPrefix`, time/price bounds, or custom `predicate`.  
+- `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.

package/documentation/09-settings-modal.md

@@ -0,0 +1,37 @@
+# Settings modal
+
+The gear icon in the top toolbar (when enabled) opens the **Chart Settings** modal. Values apply to the current chart instance and merge into internal `chartOptions` state on **Save**.
+
+**Shell theme:** modal framing and surfaces follow **`TickUpHost`** **`themeVariant`** (controlled) or **`defaultThemeVariant`** (uncontrolled), the same as **`GlobalStyle`** — see [Props & chart options](./05-props-and-chart-options.md). Changing colors inside the modal affects **`chartOptions`**, not the outer app theme unless you also update props.
+
+## Categories
+
+| Category | What users can change |
+|----------|------------------------|
+| **Chart Style** | Histogram on/off, grid on/off, **hover**: candle tooltip, crosshair lines, crosshair time & price labels |
+| **Axes** | Y-axis side (left/right), number of Y ticks |
+| **Time** | 12-hour vs 24-hour time display |
+| **Layout** | Show side toolbar, show top bar (hidden when product chrome is **locked** by `productId`) |
+| **Colors** | Background, axis text, bull/bear (and related histogram/bar colors), line chart color |
+| **Drawing shapes** | Default line/fill/selection styles for new drawings |
+| **Regional** | Locale, language (with sensible defaults linkage) |
+| **Financial** | Currency code, use-currency toggle, currency display mode, number notation, tick size, min/max fraction & significant digits, auto precision, unit + placement |
+
+## Locked layout (product tiers)
+
+For `TickUpPulse`, `TickUpFlow`, `TickUpCommand`, and `TickUpDesk`, toolbar visibility is fixed by the product. The Layout section either hides the toggles or explains that chrome is product-controlled (`lockToolbarLayout` on the modal).
+
+## Persistence
+
+The modal does **not** persist to `localStorage` by default. The host app can:
+
+- Read merged options from `getChartContext()` / custom hooks, or  
+- Re-hydrate `chartOptions` prop on next mount from your own store.
+
+## Related options in code
+
+Several toggles map to `chartOptions.base` and `base.style`:
+
+- `showCandleTooltip`, `showCrosshair`, `showCrosshairValues`  
+- `showHistogram`, `showGrid`  
+- Axes, colors, drawings defaults as described in [Props & chart options](./05-props-and-chart-options.md).

package/documentation/10-toolbar-and-interactions.md

@@ -0,0 +1,85 @@
+# Toolbar & interactions
+
+## Compact symbol strip (no top bar)
+
+When **`showTopBar`** is **`false`**, there is no symbol text field in the toolbar. If the host passes a non-empty **`symbol`** (after trim) or, when `symbol` is omitted, a non-empty **`defaultSymbol`**, the stage renders a **single read-only row** above the plot showing that ticker. Styling follows **`chartOptions.base.style.axes`** (font, text color, line color for a bottom border) and **`base.style.backgroundColor`**.
+
+- Used automatically by **`TickUpPulse`** when you set `symbol` / `defaultSymbol`.
+- Same behavior for **`TickUpHost`** / **`TickUpStage`** with `showTopBar={false}`.
+
+If the resolved string is empty, no strip is shown (minimal embed stays plot + axes only).
+
+## Floating settings (no top bar)
+
+If the stage is configured with **`showTopBar: false`** and **`showSettingsBar: true`**, a **floating gear** appears over the plot area (position depends on Y-axis side) to open the same settings modal. **Pulse** keeps **`showSettingsBar` false**, so there is no gear unless you use a custom host layout.
+
+## Top bar (Flow, Command, Desk)
+
+Typical controls (some may hide on very narrow widths):
+
+| Control | Action |
+|---------|--------|
+| **Symbol** field | Edit ticker; Enter / search button triggers `onSymbolSearch` if provided. |
+| **Search** | Focus/select symbol or run `onSymbolSearch`. If the handler returns **`false`** or a **rejected Promise**, the field reverts to the last good symbol and `onSymbolChange` runs with that value (see [Props & chart options](./05-props-and-chart-options.md)). |
+| **Interval** selector | Searchable, categorized dropdown (Minutes, Hours, Days, etc.). Triggers `onIntervalSearch` if provided. |
+| **Chart type** | Dropdown: Candlestick, Line, Area, Bar (menu is portaled for correct hit-testing). |
+| **Settings** | Opens [settings modal](./09-settings-modal.md). |
+| **Snapshot** | Captures chart region or main canvas to PNG (implementation may use `captureChartRegionToPngDataUrl`). |
+| **Range** | `fitVisibleRangeToData`. |
+| **Export** | CSV download of series. |
+| **Refresh** | `onRefreshRequest` callback. |
+| **Theme** | Toggles **shell** light/dark (**`GlobalStyle`**, settings modal chrome). Notify the app via **`onThemeVariantChange`** on **`TickUpHost`**; keep **`themeVariant`** controlled in sync. Plot styling still follows **`chartOptions`** — align **`base.theme`** (and use **`getTickUpPrimeThemePatch`** / **`createTickUpPrimeEngine`** for Prime) so grid, axes, and watermarks match. See [Props & chart options](./05-props-and-chart-options.md) and [Prime engine](https://github.com/BARDAMRI/tickup-prime/blob/main/documentation/15-prime-engine-and-pro-roadmap.md). |
+
+## Interval selection & search flow
+
+The top bar features a searchable **Interval Selection Dropdown** that handles a large variety of timeframes categorized by duration (Short-term Intraday to Long-term Monthly).
+
+### `onIntervalSearch` (Async Data-Feed Replacement)
+
+When the user selects a new interval from the dropdown:
+
+1.  The chart enters a **searching state**.
+2.  If provided, the **`onIntervalSearch(newTf)`** handler is invoked.
+3.  The handler can perform asynchronous operations (e.g., fetching new historical data for the requested timeframe).
+4.  **Success**: If the handler returns `true` (or a Promise resolving to `true`), the UI commits to the new interval.
+5.  **Failure/Revert**: If the handler returns `false` or rejects, the UI **reverts** to the previous "committed" interval automatically, preventing the user from being stuck on an invalid data state.
+
+```tsx
+<TickUpHost
+  onIntervalSearch={async (tf) => {
+    try {
+        await myDataFeed.switchTo(tf);
+        return true; // Commit the UI change
+    } catch (e) {
+        showErrorToast(`Failed to load ${tf}`);
+        return false; // Revert the UI to the old timeframe
+    }
+  }}
+/>
+```
+
+## Pan & zoom
+
+With default mode (no draw tool active), wheel and drag behaviors follow the chart stage configuration (pan/zoom on the main plot). **Select** and **edit** modes use a **default** cursor and intentionally **do not** pan on drag so clicks hit-test shapes. Drawing modes use crosshair/drag semantics appropriate to the tool.
+
+## Crosshair & tooltip
+
+When enabled in options or settings:
+
+- **Crosshair** — Vertical and horizontal lines following the pointer.  
+- **Crosshair values** — Time label near the bottom track, price label near the Y-axis side.  
+- **Candle tooltip** — Compact OHLC / change / volume panel (grid layout on small charts; scrollable cap).
+
+Branding: low-opacity **TickUp watermark** (bundled **transparent** PNGs; strength depends on plot **`base.theme`**) is drawn inside the plot/histogram buffers (not a separate footer), unless disabled via **`showAttribution`** (**Desk** forces on).
+
+## Keyboard
+
+- **Escape** — Clears in-progress polyline points, exits active draw tools (except select/edit), and returns toward neutral navigation.
+
+## Canvas stack (conceptual)
+
+From back to front: main OHLC (and grid, session shading, watermark), optional histogram, persistent drawings layer, interaction/hover/crosshair layer. Histogram opacity and height ratio come from `chartOptions.base.style.histogram`.
+
+## Copy
+
+Selected axis or formatted numbers may normalize to clipboard-friendly representation when copying from the app (formatting service integration).

package/documentation/11-exports-and-advanced.md

@@ -0,0 +1,142 @@
+# Public exports & advanced topics
+
+Published API is split across **`tickup`** (default) and **`tickup/full`**. Symbols not listed here are **internal** (not semver-stable as public API).
+
+## `tickup` (default — basic charts)
+
+| Export | Role |
+|--------|------|
+| `TickUpStage` | Chart + axes + toolbars (when enabled via props) + optional **compact symbol strip** when `showTopBar` is false and `symbol` / `defaultSymbol` is set + imperative handle. |
+| `TickUpMark` | DOM wordmark; **`TickUpThemeVariant`**: `light` \| `dark` \| `grey` — uses bundled **transparent** PNGs per variant. |
+| `TickUpAttribution` | DOM attribution strip (wordmark + legal line); theme follows props. |
+| `GlobalStyle` | Styled global CSS fragment (optional for hosts). |
+| `ModeProvider`, `useMode` | Drawing mode context. |
+| `ChartOptions`, `DeepRequired` | Configuration typing helpers. |
+| Plus | Intervals, live-data utils, overlays builders, drawing specs/factories/query helpers, snapshot helpers, graph math (`timeToX`, …), `ShapeType` & shape arg types, `IDrawingShape`, enums (`ChartType`, `AxesPosition`, overlay keys), branding types, **`TickUpPrime`** / **`TickUpStandardEngine`** / **`createTickUpPrimeEngine`** / **`getTickUpPrimeThemePatch`** / **`TickUpChartEngine`**, Prime palette constants. |
+
+## `tickup/full` (product shells + extended)
+
+Everything in **`tickup`**, **plus**:
+
+### Components
+
+| Export | Role |
+|--------|------|
+| `TickUpHost` | Full application shell (toolbar, settings, stage). |
+| `TickUpHost` | **Alias** of `TickUpHost`. |
+| `TickUpPulse` | Minimal product (plot + axes); symbol via compact strip when provided. |
+| `TickUpFlow` | Top bar, no drawing sidebar. |
+| `TickUpCommand` | Full trader UI. |
+| `TickUpDesk` | Same as Command; watermark on. |
+| `TickUpPrimeTier` | Licensed/eval shell: same chrome as Command; `productId: 'prime'`. |
+| `TickUpPrime`, `TickUpStandardEngine` | Engine profiles for **`setEngine`** / **`chartOptions.base.engine`**. **`TickUpPrime`** = dark Prime plot. |
+| `createTickUpPrimeEngine`, `getTickUpPrimeThemePatch` | **`'light' \| 'dark'`** Prime patches so the plot (and Prime **light glass** toolbars when `base.theme === 'light'`) match the host. |
+| `TICKUP_PRIME_PRIMARY`, `TICKUP_PRIME_SECONDARY`, `TICKUP_PRIME_TEXT` | Default Prime palette strings (hex / CSS color). |
+| `TickUpChartEngine` | Type for custom engines: `{ id, getChartOptionsPatch(): DeepPartial<ChartOptions> }`. |
+| `ChartStage` | **Deprecated** — use `TickUpStage`. |
+| `ShapePropertiesModal` | Shape property editor UI. |
+
+### Component prop / handle types (full)
+
+`TickUpHostProps`, `TickUpHostHandle`, `TickUpPulseProps`, `TickUpFlowProps`, `TickUpCommandProps`, `TickUpDeskProps`, `TickUpPrimeTierProps`, `TickUpStageProps`, `TickUpStageHandle`, `ChartStageProps`, `ChartStageHandle` (deprecated), `TickUpAttributionProps`, `ShapePropertiesFormState`, `ModalThemeVariant`, `TickUpThemeVariant`, `TickUpProductId`.
+
+## Context
+
+| Export | Role |
+|--------|------|
+| `ModeProvider` | Wraps tree so drawing toolbar modes work. |
+| `useMode` | Access `{ mode, setMode }` inside provider. |
+
+The **`Mode` enum** is exported from **`tickup`** and **`tickup/full`** (used by the drawing toolbar and **`setInteractionMode`**). Hosts can still prefer **`DrawingSpec`** + ref APIs for programmatic shapes.
+
+## Core data types
+
+| Export | Role |
+|--------|------|
+| `Interval` | OHLCV bar. |
+| `TimeRange`, `VisibleViewRanges`, `ChartDimensionsData` | Time window; **visible time + price snapshot** (`getVisibleRanges()`); layout metrics. |
+| `LiveDataPlacement`, `LiveDataApplyResult` | Live merge contract. |
+| `ChartContextInfo` | `getChartContext()` snapshot. |
+| `TickUpProductId` | Product id union — **`tickup/full` only**: `pulse` \| `flow` \| `command` \| `desk` \| `prime`. |
+
+## Chart configuration types
+
+| Export | Role |
+|--------|------|
+| `ChartType`, `TimeDetailLevel` | Chart mode & axis tick density. |
+| `AxesPosition` | Y-axis left/right. |
+| `OverlayWithCalc`, `OverlaySeries`, `OverlayOptions` | Indicator configuration. |
+| `OverlayKind`, `OverlayPriceKey` | Enum keys for overlays. |
+
+## Drawings
+
+| Export | Role |
+|--------|------|
+| `ShapeType` | String enum for spec `type`. |
+| `ShapeBaseArgs`, `Drawing` | Internal drawing description types. |
+| `DrawingSpec`, `DrawingPatch`, `DrawingInput` | Spec / patch / instance union for APIs. |
+| `drawingFromSpec`, `applyDrawingPatch`, `isDrawingPatch` | Build & merge helpers. |
+| `DrawingSnapshot`, `DrawingQuery`, `DrawingWithZIndex` | Query & serialization. |
+| `shapeToSnapshot`, `queryDrawingsToSnapshots`, `filterDrawingInstances`, `filterDrawingsWithMeta` | Snapshot pipelines. |
+| `IDrawingShape` | Instance interface. |
+| `LineShapeArgs`, `RectangleShapeArgs`, … `CustomSymbolShapeArgs` | Per-shape argument types. |
+| **Shape classes** | `LineShape`, `RectangleShape`, … — advanced/tests; **`tickup/full` only**. |
+| `generateDrawingShapeId` | Id factory. |
+
+## Overlay builders
+
+| Export | Role |
+|--------|------|
+| `OverlaySpecs`, `withOverlayStyle`, `overlay` | Build `OverlayWithCalc` entries. |
+
+Details: [Overlays & indicators](./12-overlays-and-indicators.md).
+
+## Live data utilities
+
+| Export | Role |
+|--------|------|
+| `applyLiveDataMerge` | Same merge as ref `applyLiveData` (pure function). |
+| `normalizeInterval`, `normalizeIntervals` | Validate/clamp bars. |
+| `dedupeByTimePreferLast` | Collapse duplicate timestamps. |
+
+## Snapshot / export helpers
+
+| Export | Role |
+|--------|------|
+| `captureChartRegionToPngDataUrl` | Rasterize a DOM region. |
+| `buildChartSnapshotFileName`, `sanitizeChartSnapshotToken`, `contrastingFooterTextColor` | Filename & contrast helpers. |
+| `ChartSnapshotMeta` | Metadata type for snapshots. |
+
+## Graph math (coordinate helpers)
+
+`timeToX`, `xToTime`, `priceToY`, `yToPrice`, `interpolatedCloseAtTime`, `lerp`, `xFromCenter`, `xFromStart` — align custom logic with chart scales.
+
+## Not exported (internal)
+
+Examples: `FormattingService`, `deepMerge`, `deepEqual`, toolbar `Tooltip`, most styled wrappers. Do not import these from deep paths in apps if you want upgrade safety.
+
+## `TickUpStage` usage sketch
+
+Wrap with **`ModeProvider`**. Pass **all** required `TickUpStageProps` from TypeScript (intervals, `chartOptions`, tick count, `timeDetailLevel`, `timeFormat12h`, selection state, chart-type handler, settings opener, toolbar flags, etc.). Many hosts use a **product component** or **`TickUpHost`** from **`tickup/full`** instead of wiring `TickUpStage` alone.
+
+## Init process (summary)
+
+1. Mount product or `TickUpHost` / `TickUpStage`.  
+2. Merge `chartOptions` with defaults (stable prop reference recommended).  
+3. Load `intervalsArray`; derive visible time and price ranges.  
+4. Allocate canvases; draw grid, session shading, series, histogram, watermark, overlays (if enabled), drawings.  
+5. After mount, the **ref** is non-null — run imperative calls in `useEffect` or callbacks. **`getViewInfo()` / `getChartContext()`** may still return **`null`** until the inner stage is ready; use optional chaining or retry briefly (see the [`example/`](../example/) app for patterns).
+
+## Updating (summary)
+
+| Concern | Mechanism |
+|---------|-----------|
+| Series | `intervalsArray` or `applyLiveData` / `addInterval` / index update |
+| Styles | `chartOptions` (deep merge on real changes) or Settings modal |
+| Drawings | Toolbar, or `addShape` / `updateShape` / `patchShape` / `setDrawingsFromSpecs` |
+| View | Pan/zoom, `fitVisibleRangeToData`, `redrawCanvas`, `reloadCanvas` |
+| Theme | **`themeVariant` / `defaultThemeVariant` / `onThemeVariantChange`** on **`TickUpHost`** + `chartOptions.base.theme` (and Prime helpers above). |
+
+## Deprecated
+
+- `ChartStage`, `ChartStageProps`, `ChartStageHandle` → use `TickUpStage*`.

package/documentation/12-overlays-and-indicators.md

@@ -0,0 +1,65 @@
+# Overlays and indicators
+
+Technical indicator lines are drawn **on top of** the main series when overlays are enabled in chart options.
+
+## Enable drawing
+
+Set **`base.showOverlayLine`** to `true` (via `chartOptions` or defaults). Style defaults for stroke live under **`base.style.overlay`** (`lineColor`, `lineWidth`, `lineStyle`: solid | dashed | dotted).
+
+## Two configuration styles
+
+### 1. `base.overlays` — full control (`OverlayWithCalc[]`)
+
+Each entry combines:
+
+- **Style** — line color, width, style (merged with defaults).  
+- **`calc`** — an `OverlayCalcSpec` describing the math (see below).  
+- **`connectNulls`** (optional) — draw through gaps in computed values (default true in helpers).  
+- **`useCenterX`** (optional) — plot at bar center vs edge (default true in helpers).
+
+Build entries with exported helpers:
+
+```ts
+import {
+  withOverlayStyle,
+  OverlaySpecs,
+  overlay,
+  type OverlayWithCalc,
+} from 'tickup';
+
+const overlays: OverlayWithCalc[] = [
+  withOverlayStyle({ lineColor: '#ff9800', lineWidth: 2 })(OverlaySpecs.ema(12)),
+  overlay(OverlaySpecs.sma(20), { lineColor: '#2962ff' }),
+];
+```
+
+`OverlaySpecs` includes: `close`, `open`, `high`, `low`, `sma`, `ema`, `wma`, `vwap`, `bbandsMid`, `bbandsUpper`, `bbandsLower`.
+
+### 2. `base.overlayKinds` — shorthand
+
+An array of **`OverlayKind`** string keys (or calc specs in the type definition; the renderer maps kinds through the same `overlay()` factory with **default periods**, e.g. SMA/EMA/WMA period 20, Bollinger period 20 / stddev 2). Useful for quick demos; prefer **`overlays`** for explicit periods and prices.
+
+## Calculation kinds (`OverlayCalcSpec`)
+
+| Kind | Role |
+|------|------|
+| `OverlayPriceKey` (`close`, `open`, `high`, `low`) | Raw price series. |
+| `sma`, `ema`, `wma` | Moving averages; `period` + optional `price` key. |
+| `vwap` | Volume-weighted average price (uses interval volume when present). |
+| `bbands_mid`, `bbands_upper`, `bbands_lower` | Bollinger mid/upper/lower; `period`, optional `stddev`, optional `price`. |
+
+## Exported API (from `tickup`)
+
+| Export | Role |
+|--------|------|
+| `OverlaySpecs` | Factory for calc specs. |
+| `withOverlayStyle` | Curried builder: shared style → many overlays. |
+| `overlay(kindOrSpec?, style?, extras?)` | Single `OverlayWithCalc` with defaults. |
+| `OverlayKind`, `OverlayPriceKey` | Enums. |
+| Types: `OverlayWithCalc`, `OverlaySeries`, `OverlayOptions` | Typing and advanced use. |
+
+Lower-level functions such as `computeSeriesBySpec`, `drawOverlays`, `drawOverlay` exist in source for maintainers; the **supported host integration path** is configuring **`chartOptions.base.overlays`** / **`overlayKinds`** and **`showOverlayLine`**.
+
+## Chart types
+
+Overlays are wired in **candlestick**, **line**, **area**, and **bar** draw paths when `showOverlayLine` is true.

package/documentation/13-internationalization-and-axes.md

@@ -0,0 +1,56 @@
+# Internationalization, axes, and sessions
+
+## Locale and language
+
+Axis labels, dates, and many settings strings follow **`chartOptions.base.style.axes`**:
+
+| Field | Role |
+|-------|------|
+| `locale` | BCP 47 tag (e.g. `en-US`, `he-IL`). Drives date/number formatting and default direction. |
+| `language` | UI language key for built-in labels (toolbar tooltips, settings, etc.). |
+
+The in-app **Settings → Regional** category updates these fields. The library ships multiple locale presets (decimal/thousands separators, date patterns, default currency, **RTL** vs LTR) in internal locale tables.
+
+### RTL
+
+When the active locale defaults specify `direction: 'rtl'`, toolbar and settings layout flip appropriately (`dir` on toolbars/modals).
+
+## Numeric and currency display
+
+Axes support:
+
+- Fraction digits, min/max significant digits, `tickSize`, `autoPrecision`  
+- `currency`, `useCurrency`, `currencyDisplay`  
+- `numberNotation`: `standard` | `scientific` | `compact`  
+- `unit` / `unitPlacement`  
+- Optional **`displayCurrency`** / **`conversionRate`** for converted display (host-defined semantics)
+
+## Time axis
+
+- **`timezone`** — string such as `UTC` or `America/New_York` for session logic and labeling where used.  
+- **`dateFormat`** — pattern consumed by the formatting layer.  
+- Shell prop **`initialTimeFormat12h`** and settings **12-hour toggle** affect time presentation.  
+- **`TimeDetailLevel`** (`Auto` / `Low` / `Medium` / `High`) controls tick density (prop `initialTimeDetailLevel`).
+
+## Trading sessions and holidays
+
+`axes` options include:
+
+- **`tradingSessions`** — array of `{ dayOfWeek, start, end }` with `start`/`end` as `'HH:mm'` strings; used to **shade off-session** periods on the chart.  
+- **`holidays`** — ISO `YYYY-MM-DD` strings for calendar context (where integrated).  
+- **`exchange`** — display/metadata string.
+
+## Grid and background
+
+- **`base.style.showGrid`** — toggles grid lines (`grid` sub-style: colors, dash, spacing).  
+- **`base.style.backgroundColor`** — plot background.
+
+## Y axis layout
+
+- **`axes.yAxisPosition`** — `AxesPosition.left` or `.right`.  
+- **`axes.numberOfYTicks`** — count (also `initialNumberOfYTicks` on the shell).  
+- **`initialYAxisWidth`** / **`initialXAxisHeight`** — layout hints passed into the stage.
+
+## Clipboard (shell behavior)
+
+When users copy selected text, the host shell may **normalize** numbers to a canonical plain form using the same axis parsing rules (implemented inside the chart app wrapper). This is a UX nicety for spreadsheets, not a separate public API export.

package/documentation/14-legal-and-policies.md

@@ -0,0 +1,32 @@
+# Legal and policies
+
+TickUp ships as **open-source software** (see the **LICENSE** file in the repository root when present) and may also be described, demoed, or offered through **websites, accounts, or hosted services**. **Legal terms for those offerings**—including intellectual property, acceptable use, suspension or termination of access, privacy, and standard limitations of liability—are maintained as **templates** in the repository for you to customize with your lawyer.
+
+## Where to read the documents
+
+Policy templates ship **next to** this folder in the npm package (`node_modules/tickup/legal/`) and in the Git clone. All files live under **[`../legal/`](../legal/)**:
+
+| Document | File |
+|----------|------|
+| Index & disclaimer | [`../legal/README.md`](../legal/README.md) |
+| **Terms of Service** | [`../legal/TERMS_OF_SERVICE.md`](../legal/TERMS_OF_SERVICE.md) |
+| **Privacy Policy** | [`../legal/PRIVACY_POLICY.md`](../legal/PRIVACY_POLICY.md) |
+| **Acceptable Use Policy** | [`../legal/ACCEPTABLE_USE_POLICY.md`](../legal/ACCEPTABLE_USE_POLICY.md) |
+
+## What the Terms of Service cover (summary)
+
+The Terms of Service template is written so you can:
+
+- **Retain ownership** of TickUp branding, product, documentation, and proprietary parts of the Services.
+- **Suspend or terminate** user access, change or discontinue features, and refuse service where appropriate, subject to applicable law and any stricter promises you make elsewhere.
+- Use **standard protections**: disclaimers of warranty, caps on liability, indemnity where appropriate, governing law and venue placeholders, and rules for changes to the terms.
+
+**Open-source code** released under the repo **LICENSE** is called out separately so the license for that code and the Terms for hosted products can coexist without confusion.
+
+## Not legal advice
+
+These markdown files are **starting points**, not a substitute for counsel. Replace all bracketed placeholders (`[Legal Entity Name]`, `[Contact Email]`, `[Jurisdiction]`, etc.) and adapt clauses for your entity, products, and regions before publication.
+
+## Older stub
+
+A short legacy note lives in the repo under **`docs/Documentation/Terms_of_Use.md`** (that tree is **not** bundled on npm). [View on GitHub](https://github.com/BARDAMRI/TickUp/blob/main/docs/Documentation/Terms_of_Use.md) — it points here and to **`legal/`**.

package/documentation/README.md

@@ -0,0 +1,33 @@
+# TickUp Charts documentation
+
+Complete guides for integrating and operating the TickUp Charts React charting library.
+
+The **npm package** has **`tickup`** (default — `TickUpStage` and chart helpers) and **`tickup/full`** (e.g. `TickUpCommand`, `TickUpHost`, extended exports). Product-focused guides import from **`tickup/full`**.
+
+Published tarballs **include this `documentation/` folder** and the sibling **`legal/`** policy templates (see root `package.json` **`files`**) so links in **[14-legal-and-policies.md](./14-legal-and-policies.md)** resolve under `node_modules/tickup/`. Type declarations ship in **`dist/*.d.ts`**. This documentation covers the open-source core package.
+
+The **reference example app** in [`../example/`](../example/) (Vite + React) exercises all product tiers, `chartOptions`, the compact symbol strip on Pulse, host symbol callbacks, and the imperative ref API; see [`../example/README.md`](../example/README.md). The example app itself is **not** published to npm.
+
+## Contents
+
+| # | Guide | Description |
+|---|--------|-------------|
+| 1 | [Introduction](./01-introduction.md) | Overview, package scope, and Prime upgrade path |
+| 2 | [Glossary](./01-glossary.md) | Terms: intervals, ranges, products, placements, etc. |
+| 3 | [Installation](./02-installation.md) | Peer dependencies, package install, styled-components |
+| 4 | [Quick start](./03-quick-start.md) | Minimal embed, ref, controlled data |
+| 5 | [Products & layout](./04-products-and-layout.md) | Pulse, Flow, Command, Desk; toolbars (public line) |
+| 6 | [Props & chart options](./05-props-and-chart-options.md) | `TickUpHost`, `chartOptions`, shell theme + chart theme |
+| 7 | [Imperative API](./06-imperative-api.md) | Ref handle: shapes, data, **`getVisibleRanges()`**, **`getCanvasSize()`**, view, context |
+| 8 | [Data & live updates](./07-data-and-live-updates.md) | `intervalsArray`, `applyLiveData`, merge helpers |
+| 9 | [Drawings & shapes](./08-drawings-and-shapes.md) | Toolbar tools, select/edit, programmatic shapes & patches |
+| 10 | [Settings modal](./09-settings-modal.md) | In-app settings categories and persistence |
+| 11 | [Toolbar & interactions](./10-toolbar-and-interactions.md) | Chart type, snapshot, crosshair, tooltip, pan/zoom |
+| 12 | [Exports & advanced](./11-exports-and-advanced.md) | Full export list, `TickUpStage`, branding, init/update |
+| 13 | [Overlays & indicators](./12-overlays-and-indicators.md) | SMA/EMA/VWAP/Bollinger, `overlays` / `overlayKinds` |
+| 14 | [i18n & axes](./13-internationalization-and-axes.md) | Locale, RTL, currency, sessions, grid |
+| 15 | [Legal & policies](./14-legal-and-policies.md) | Terms of Service, Privacy, Acceptable Use templates (`legal/`) |
+
+## Older material
+
+Additional notes and legacy pages may still live under [`../docs/`](../docs/) (roadmap, contributing, design). The **authoritative integration reference** is this `documentation/` folder.