emberwick 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emberwick contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,530 @@
+# Emberwick
+
+A smooth-flowing candlestick chart for the web. Canvas-rendered, framework-free,
+and driven by a pluggable data feed — drop it into any financial frontend and
+point it at your own market data.
+
+- **Zero dependencies.** The core imports nothing but DOM and Canvas APIs.
+- **Framework-agnostic.** Works in React, Vue, Svelte, or a plain `<script type="module">`.
+- **Actually smooth.** Ticks ease into the forming candle, the price axis glides
+  to new bounds, zoom is cursor-anchored and eased, panning has inertia.
+- **Fast on big data.** One `requestAnimationFrame` loop, dirty-flag driven,
+  with visible-range culling — 500k bars loaded costs only the ~200 on screen.
+
+---
+
+## Installing
+
+### From npm
+
+```bash
+npm install emberwick
+```
+
+```js
+import { createChart, RandomFeed } from 'emberwick'
+```
+
+> **Not published yet.** The package builds and packs (`npm run release`), but
+> it has not been pushed to the registry, and the name has not been confirmed
+> available — run `npm view emberwick` before relying on it.
+
+### From a CDN, no build step
+
+```html
+<div id="chart" style="height: 480px"></div>
+<script src="https://unpkg.com/emberwick/umd/emberwick.umd.js"></script>
+<script>
+  const chart = Emberwick.createChart(document.getElementById('chart'))
+  chart.setFeed(new Emberwick.RandomFeed({ timeframe: 60000, speed: 60 }))
+</script>
+```
+
+The UMD build is core-only and exposes the global `Emberwick`.
+
+### By vendoring the source
+
+Nothing stops you copying the core in directly:
+
+```bash
+cp -r src/chart /path/to/your-project/src/emberwick
+```
+
+```js
+import { createChart, RandomFeed } from './emberwick/index.js'
+```
+
+The folder is self-contained — `src/chart/` has no imports that point outside
+itself, and no framework dependency. Anything that can bundle ES modules
+(Vite, webpack, Rollup, esbuild, or a browser with native ESM) can consume it
+as-is.
+
+### Entry points
+
+| Import | Contents |
+|---|---|
+| `emberwick` | The core: `createChart`, `Chart`, feeds, themes, motion primitives |
+| `emberwick/react` | `<EmberwickChart />` React component |
+| `emberwick/webcomponent` | Registers `<emberwick-chart>` (side-effecting import) |
+| `emberwick/umd` | Single-file UMD build for `<script>` tags |
+
+TypeScript declarations ship for all three entries.
+
+---
+
+## Quick start
+
+```js
+import { createChart, RandomFeed } from 'emberwick'
+
+const chart = createChart(document.getElementById('chart'))
+await chart.setFeed(new RandomFeed({ timeframe: 60_000 }))
+```
+
+The container needs a real size — the chart fills it and follows resizes:
+
+```html
+<div id="chart" style="width: 100%; height: 480px"></div>
+```
+
+> The container's `position` is set to `relative` automatically if it is
+> `static`, because the canvas layers are absolutely positioned inside it.
+
+Without a feed, push bars in directly:
+
+```js
+const chart = createChart(el)
+chart.setData(bars)          // Bar[], ascending by time
+chart.update(formingBar)     // merge a tick into the last candle (animates)
+chart.append(newBar)         // open a new candle
+```
+
+---
+
+## The bar shape
+
+One contract, used everywhere:
+
+```js
+{
+  time: 1737024000000,  // ms epoch, start of the bar
+  open: 100.2,
+  high: 101.4,
+  low:  99.8,
+  close: 100.9,
+  volume: 1420,
+}
+```
+
+Bars must be **ascending by time** and **de-duplicated**. The chart infers the
+timeframe from the gap between the first two bars (or from `feed.timeframe`).
+
+---
+
+## Plugging in your own data — the `DataFeed` interface
+
+This is the seam the whole library is built around. The core never knows where
+bars come from: implement two methods and it works.
+
+```js
+import { DataFeed } from 'emberwick'
+
+class MyApiFeed extends DataFeed {
+  constructor() {
+    super({ symbol: 'AAPL', timeframe: 60_000 })
+  }
+
+  // Historical bars ENDING at `to` (exclusive). Return [] when exhausted.
+  async getBars({ symbol, timeframe, to, limit }) {
+    const qs = new URLSearchParams({ symbol, tf: timeframe, limit })
+    if (to) qs.set('to', to)
+    const res = await fetch(`/api/candles?${qs}`)
+    return res.json()   // Bar[], ascending by time
+  }
+
+  // Live updates. Return an unsubscribe function.
+  subscribe(handler) {
+    const ws = new WebSocket('wss://example.com/stream')
+    ws.onmessage = (e) => {
+      const { bar, closed } = JSON.parse(e.data)
+      handler({ type: closed ? 'append' : 'update', bar })
+    }
+    return () => ws.close()
+  }
+}
+
+await chart.setFeed(new MyApiFeed())
+```
+
+### Feed contract
+
+| Member | Required | Purpose |
+|---|---|---|
+| `symbol` | yes | Passed back to you in `getBars` |
+| `timeframe` | yes | Bar duration in ms; sets the chart's time axis |
+| `getBars({ symbol, timeframe, to, limit })` | yes | `Promise<Bar[]>`. `to: null` means "most recent". Return `[]` to signal no more history |
+| `subscribe(handler)` | for live data | Returns an unsubscribe function |
+| `prime(lastBar)` | optional | Called once after history loads, so the feed can seed its forming candle |
+| `destroy()` | optional | Your own cleanup |
+
+### Update messages
+
+```js
+handler({ type: 'update', bar })  // forming candle changed → animates
+handler({ type: 'append', bar })  // a new candle opened
+```
+
+`update` is the one that produces the flowing motion. Send it as often as your
+feed ticks — 500 messages between two frames still cost exactly one repaint,
+because rendering is decoupled from data arrival.
+
+### Lazy history
+
+When the user pans to within **80 bars** of the left edge, the chart calls
+`getBars({ to: oldestLoadedTime })` and prepends the result, holding the view
+on the same bars. Return an empty array and it stops asking permanently.
+
+---
+
+## API
+
+### `createChart(container, options?)`
+
+Returns a `Chart`. (`new Chart(container, options)` is equivalent.)
+
+```js
+const chart = createChart(el, {
+  theme: { background: '#000', up: '#00d68f' },
+  volumeRatio: 0.18,     // fraction of height for the volume strip
+  magnet: true,          // crosshair snaps to nearest OHLC
+  animate: true,         // live-candle easing
+  initialBars: 1500,     // first getBars() page size
+  timeScale: { spacing: 9, minSpacing: 0.8, maxSpacing: 160, rightOffset: 12 },
+  priceScale: { mode: 'linear', tau: 120, marginTop: 0.12, marginBottom: 0.12 },
+})
+```
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `setData(bars)` | Replace all bars and snap to the right edge |
+| `update(bar)` | Merge a tick into the forming candle (animated) |
+| `append(bar)` | Open a new candle |
+| `setFeed(feed)` | `async` — loads history, then subscribes. Detaches any previous feed |
+| `detachFeed()` | Unsubscribe, keep the bars on screen |
+| `subscribe('crosshair', fn)` | Returns an unsubscribe fn. See events below |
+| `setTheme(partial)` | Merge theme keys and repaint |
+| `setPriceMode(mode)` | `'linear'` or `'log'` |
+| `setAnimate(bool)` | Toggle live-candle easing |
+| `setMagnet(bool)` | Toggle crosshair OHLC snapping |
+| `snapToRealtime()` | Jump back to the newest bar and re-enable autoscale |
+| `toImage()` | PNG data URL of the composited layers |
+| `destroy()` | Remove listeners, stop the loop, drop canvases |
+| `chart.fps` | Getter — measured frames per second |
+
+### Events
+
+```js
+const off = chart.subscribe('crosshair', (payload) => {
+  if (!payload) return           // pointer left the plot
+  const { index, bar, price } = payload
+  legend.textContent = `O ${bar.open} H ${bar.high} L ${bar.low} C ${bar.close}`
+})
+off()  // unsubscribe
+```
+
+`'crosshair'` is the only event that currently fires. See *Known gaps* below.
+
+---
+
+## Interaction
+
+| Input | Action |
+|---|---|
+| Drag in plot | Pan (with inertia on release) |
+| Wheel | Zoom, anchored on the cursor |
+| Two-finger pinch | Zoom |
+| Drag price axis | Stretch the price scale |
+| Drag time axis | Zoom the time scale |
+| Double-click | Snap back to realtime |
+| `←` / `→` | Pan (hold `Shift` for a bigger step) |
+| `+` / `-` | Zoom |
+
+The container gets `tabindex="0"` if it has none, so keyboard nav works
+without extra markup.
+
+---
+
+## Theming
+
+Pass any subset of the theme keys; the rest fall back to `defaultTheme`.
+
+```js
+import { defaultTheme, lightTheme } from 'emberwick'
+
+chart.setTheme(lightTheme)
+chart.setTheme({ up: '#00d68f', down: '#ff5c5c', background: '#0b0e14' })
+```
+
+Available keys: `background`, `grid`, `axisLine`, `text`, `textStrong`, `up`,
+`down`, `upFill`, `downFill`, `wickUp`, `wickDown`, `volumeUp`, `volumeDown`,
+`crosshair`, `labelBg`, `labelText`, `tagText`, `font`, `priceAxisWidth`,
+`timeAxisHeight`.
+
+---
+
+## Framework integration
+
+### React — the bundled adapter
+
+```jsx
+import { EmberwickChart } from 'emberwick/react'
+import { RandomFeed } from 'emberwick'
+import { useMemo, useRef } from 'react'
+
+export function Chart() {
+  // Memoise the feed — a new instance re-loads history.
+  const feed = useMemo(() => new RandomFeed({ timeframe: 60_000, speed: 60 }), [])
+  const ref = useRef(null)
+
+  return (
+    <div style={{ height: 480 }}>
+      <EmberwickChart
+        ref={ref}
+        feed={feed}
+        priceMode="linear"
+        theme={{ up: '#00d68f' }}
+        onCrosshair={(p) => p && console.log(p.bar)}
+      />
+      <button onClick={() => ref.current.chart.snapToRealtime()}>Realtime</button>
+    </div>
+  )
+}
+```
+
+Props: `data`, `feed`, `options`, `theme`, `priceMode`, `animate`, `magnet`,
+`onCrosshair`, `className`, `style`. Any other prop is spread onto the host
+`<div>`. The ref exposes `{ chart }` for imperative calls.
+
+The component creates the chart **once** and drives it through its methods on
+prop changes — it never rebuilds the canvas, so pan/zoom position and animation
+state survive re-renders. `destroy()` runs on unmount, so React 18 StrictMode
+double-mounting is safe.
+
+### React — by hand
+
+The adapter is ~100 lines of `useEffect`; doing it yourself is fine:
+
+```jsx
+import { useEffect, useRef } from 'react'
+import { createChart, RandomFeed } from 'emberwick'
+
+export function Chart() {
+  const hostRef = useRef(null)
+
+  useEffect(() => {
+    const chart = createChart(hostRef.current)
+    const feed = new RandomFeed({ timeframe: 60_000 })
+    chart.setFeed(feed)
+    return () => { feed.destroy(); chart.destroy() }
+  }, [])
+
+  return <div ref={hostRef} style={{ width: '100%', height: 480 }} />
+}
+```
+
+### Web Component — works in any framework
+
+```html
+<script type="module">
+  import 'emberwick/webcomponent'
+  import { RandomFeed } from 'emberwick'
+
+  const el = document.querySelector('emberwick-chart')
+  el.feed = new RandomFeed({ timeframe: 60000, speed: 60 })
+  el.addEventListener('crosshair', (e) => console.log(e.detail))
+</script>
+
+<emberwick-chart theme="dark" style="height: 480px"></emberwick-chart>
+```
+
+| | |
+|---|---|
+| Attributes | `theme="dark\|light"`, `animate="false"`, `magnet="false"` |
+| Properties | `feed`, `data`, `chart` (read-only) |
+| Events | `crosshair` — `event.detail` is the payload or `null` |
+
+The element renders into a shadow root, so host-page CSS can't reposition the
+stacked canvases. Assigning `feed`/`data` before the element upgrades is safe.
+This is the path for Vue, Svelte, Angular or server-rendered templates without
+a framework-specific wrapper.
+
+### Vue 3
+
+```vue
+<script setup>
+import { onMounted, onBeforeUnmount, ref } from 'vue'
+import { createChart, RandomFeed } from 'emberwick'
+
+const host = ref(null)
+let chart, feed
+
+onMounted(() => {
+  chart = createChart(host.value)
+  feed = new RandomFeed({ timeframe: 60_000 })
+  chart.setFeed(feed)
+})
+onBeforeUnmount(() => { feed?.destroy(); chart?.destroy() })
+</script>
+
+<template><div ref="host" style="width: 100%; height: 480px" /></template>
+```
+
+### Plain HTML
+
+```html
+<div id="chart" style="height: 480px"></div>
+<script type="module">
+  import { createChart, RandomFeed } from 'emberwick'
+  const chart = createChart(document.getElementById('chart'))
+  chart.setFeed(new RandomFeed({ timeframe: 60_000 }))
+</script>
+```
+
+---
+
+## `RandomFeed` — synthetic data for development
+
+Bundled so you can build UI before your backend exists. It's an ordinary
+`DataFeed` implementation with no special privileges.
+
+```js
+new RandomFeed({
+  symbol: 'EMBR',
+  timeframe: 60_000,
+  seed: 7,              // deterministic: same seed → same chart
+  start: 100,           // starting price
+  volatility: 0.0022,
+  drift: 0.00002,
+  ticksPerSecond: 8,    // live update rate
+  speed: 1,             // time multiplier; 60 = one candle per second
+})
+```
+
+Runtime controls: `setSpeed(n)`, `setTicksPerSecond(n)`, `setPaused(bool)`,
+`paused` (getter), `stop()`, `destroy()`.
+
+Set `speed: 60` to see the flowing motion immediately instead of waiting a
+minute per candle.
+
+---
+
+## Exports
+
+```js
+import {
+  createChart, Chart,           // entry point
+  DataFeed, RandomFeed,         // data layer
+  defaultTheme, lightTheme,     // themes
+  TimeScale, PriceScale,        // scales (advanced)
+  Smoothed, Tween, Inertia,     // motion primitives
+  LiveCandle,
+  easeOutCubic, easeInOutCubic,
+  mulberry32,                   // seeded PRNG
+  version,
+} from 'emberwick'
+```
+
+---
+
+## How the motion works
+
+Three independent mechanisms, which is why it reads as smooth rather than
+merely animated:
+
+1. **Live candle** — each of O/H/L/C eases toward the incoming tick over
+   ~55ms, with the wick clamped so it can't invert mid-chase. A brand new
+   candle plays a short grow-from-centre animation as it scrolls in.
+2. **Price axis** — autoscale bounds are smoothed, so a spike glides the axis
+   instead of jolting it and losing the reader's place.
+3. **Time axis** — `spacing` (zoom) and `right` (edge position) are smoothed,
+   so wheel zoom eases and new bars slide in. **Dragging deliberately does
+   not ease** — easing a drag feels like lag, not polish.
+
+All of it runs through `Smoothed`, a frame-rate-independent exponential
+smoother: the same visual speed at 30fps and 144fps. The render loop returns
+whether anything is still animating, so a static chart idles at zero CPU.
+
+Rendering is split across three stacked canvases — `base` (grid + axes),
+`main` (candles + volume), `overlay` (crosshair) — so moving the pointer
+repaints only the crosshair, never the candles underneath. All contexts are
+pre-scaled by `devicePixelRatio`, so drawing code works in CSS pixels and
+output stays crisp on retina.
+
+---
+
+## Building the package
+
+The repo is both the library and its playground. The playground is an ordinary
+Vite app (`npm run dev` / `npm run build`); the library has its own builds.
+
+```bash
+npm run build:lib    # ESM, multi-entry  -> dist-lib/{index,react,webcomponent}.js
+npm run build:umd    # minified UMD      -> dist-lib/umd/emberwick.umd.js
+npm run pack:lib     # manifest + README + .d.ts into dist-lib/
+npm run size         # gzipped size budget check
+npm run release      # all four, in order
+npm publish dist-lib # publish the assembled directory
+```
+
+Publishing from `dist-lib/` keeps the playground, the build configs and the
+app's private `package.json` out of the artifact. `package.lib.json` is the
+manifest that becomes the published `package.json`.
+
+React is an **optional peer dependency**, external in every build — importing
+`emberwick` never pulls React in.
+
+Source layout:
+
+```
+src/chart/                  the library core (zero deps, no framework)
+  core/      Chart, Layers, Loop, TimeScale, PriceScale, palette, formatters
+  render/    grid, candles, crosshair
+  motion/    Tween (Smoothed), Inertia, LiveCandle
+  data/      DataFeed (the seam), RandomFeed
+  index.js   public API surface   index.d.ts  types
+src/adapters/react/         <EmberwickChart />
+src/adapters/webcomponent/  <emberwick-chart>
+src/App.jsx, src/styles.css  the playground (not published)
+```
+
+---
+
+## Known gaps
+
+Honest list of what isn't there yet:
+
+- **`subscribe('visibleRange', fn)` never fires.** The event is accepted and
+  the handler is stored, but nothing emits it. Use `'crosshair'` for now.
+- **Not published to npm.** The package builds and packs, but it has not been
+  pushed, and the name is unverified — check `npm view emberwick` first.
+- **The library builds are unverified.** `npm run build:lib` / `build:umd`
+  have not been executed here; this environment only runs the app build. Run
+  `npm run release` locally before publishing.
+- **No indicators or drawing tools.** SMA/EMA/RSI/MACD, multi-pane layout and
+  trendlines are planned but not implemented.
+- **Candlesticks only.** No Heikin-Ashi, line, area or baseline series yet.
+- **No session-gap collapsing.** Weekends and market closes render as ordinary
+  bar-index steps, not gaps.
+- **`RandomFeed` deep history is per-page coherent, not one continuous walk** —
+  it regenerates backwards from a seed offset, so paging far left can show a
+  visible seam. Real feeds don't have this artifact.
+- **Types are hand-written**, not generated from source, so they can drift
+  from the implementation.
+
+---
+
+## License
+
+MIT