@tony01/astroneum 0.4.1-beta.2

package/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to **astroneum** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+once it reaches v1.0. Until then, minor releases may include breaking changes
+— always check this file before upgrading.
+
+## [Unreleased]
+
+### Added — Full Indicator Parity (50 total, +23 new)
+
+Astroneum now ships **50 technical indicators** — up from 27 — achieving full
+parity with the comparison table against TradingView Pro. Every indicator in the
+original roadmap (Phases 1–4) is implemented.
+
+**Phase 1 — Critical (MVP)**
+- **ATR** (Average True Range) — `averageTrueRange.ts` — market volatility
+  measure used for position sizing and stop-loss placement.
+- **ADX** (Average Directional Index) — `averageDirectionalIndex.ts` —
+  standalone trend-strength indicator (0–25 weak, 25–50 strong, 50+ very
+  strong).
+- **A/D** (Accumulation/Distribution) — `accumulationDistribution.ts` —
+  cumulative volume + CLV money flow, divergence signals for reversals.
+
+**Phase 2 — Important (Competitive Feature)**
+- **CMF** (Chaikin Money Flow) — `chaikinMoneyFlow.ts` — money flow over N
+  periods using close-location-within-range (default 20).
+- **MFI** (Money Flow Index) — `moneyFlowIndex.ts` — volume-weighted RSI
+  using typical price, overbought >80 / oversold <20.
+- **VWAP** (Volume Weighted Average Price) — `volumeWeightedAveragePrice.ts`
+  — cumulative volume-weighted typical price overlay.
+- **Ichimoku Cloud** — `ichimokuCloud.ts` — 5-line comprehensive trend
+  system (Tenkan/Kijun/Senkou A/B/Chikou), default periods 9/26/52.
+
+**Phase 3 — Polish (Market Completeness)**
+- **DEMA / TEMA / WMA / VWMA** — double/triple/weighted/volume-weighted
+  moving averages (`doubleExponentialMovingAverage.ts`,
+  `tripleExponentialMovingAverage.ts`, `weightedMovingAverage.ts`,
+  `volumeWeightedMovingAverage.ts`).
+- **HV** (Historical Volatility) — `historicalVolatility.ts` — annualized
+  volatility from log returns × √252.
+- **DC** (Donchian Channels) — `donchianChannels.ts` — highest-high /
+  lowest-low channels with midline.
+- **KC** (Keltner Channels) — `keltnerChannels.ts` — EMA middle line with
+  ATR-based upper/lower bands.
+- **SuperTrend** — `superTrend.ts` — trend-following volatility stop with
+  direction tracking.
+
+**Phase 4 — Advanced (Niche Features)**
+- **STDDEV** (Standard Deviation) — `standardDeviation.ts` — population
+  standard deviation of close over N periods.
+- **VROC** (Volume Rate of Change) — `volumeRateOfChange.ts` — percentage
+  change in volume over N periods.
+- **PP** (Pivot Points) — `pivotPoints.ts` — classic pivot points with
+  R1–R3 resistance and S1–S3 support levels.
+- **CORR** (Correlation Coefficient) — `correlationCoefficient.ts` —
+  Pearson's R between close and linear sequence 1..N.
+- **LinReg** (Linear Regression) — `linearRegression.ts` — least-squares
+  regression line on close prices.
+- **AMA** (Adaptive Moving Average / KAMA) — `adaptiveMovingAverage.ts` —
+  Kaufman's adaptive MA with efficiency-ratio smoothing.
+- **HMA** (Hull Moving Average) — `hullMovingAverage.ts` — WMA-based
+  lag-reduced moving average.
+- **ZZ** (ZigZag) — `zigzag.ts` — pivot-based trend-reversal detection
+  with configurable deviation percentage.
+
+### Changed
+
+- **Demo page expanded** — category-organised indicator picker displaying all
+  50 indicators with tooltips, overlay vs. sub-pane visual distinction
+  (amber/green), and active-indicator status bar with counts.
+- **`INDICATOR_COMPARISON.md`** fully rewritten to track all indicators,
+  coverage percentages per category, and completed roadmap.
+
+### Fixed
+
+- **SuperTrend state tracking** — replaced fragile float comparison
+  `prevSuperTrend === upperBand` with `direction` variable for correct
+  trend-state transitions.
+- **HMA performance** — reduced from O(n³) to O(n²) by pre-computing
+  `2*WMA(n/2) - WMA(n)` values before the final WMA pass.
+- **ZigZag pivot detection** — replaced adjacent-bar comparison with
+  running extreme tracking to reliably capture peaks/troughs during
+  consolidation phases.
+
+---
+
+### Added — TradingView Competitive Parity
+
+- **Heikin-Ashi candle type** — `barStyle="heikin_ashi"` prop. `heikinAshi(data)` exported.
+- **Crosshair sync** in `MultiChartLayout` — `onCrosshairMove()` / `setCrosshair()` on handle.
+- **Measure tool** — 18th drawing tool in extension. Pixel distance label + risk/reward line.
+- **Magnet/Snap helpers** — `snapToOhlc()` and `snapAngle()` in `DrawingSnapper`.
+- **Undo/Redo manager** — `UndoManager` class using `serializeState()`/`loadState()`.
+- **Extended keyboard shortcuts** — arrow keys pan, Page/Home/End, mouse wheel zoom at cursor.
+- **Copy/paste drawings** — Ctrl+C copies overlays as JSON, Ctrl+V pastes.
+- **Session Visualizer** — `SessionVisualizer` renders session high/low/open/close lines.
+- **Volume Profile** — `volumeProfilePlugin` horizontal histogram with POC + Value Area.
+- **Position Visualizer** — `PositionVisualizer` entry/stop/target lines on chart.
+- **Compare Overlay** — `createCompareIndicator()` overlays second symbol normalized to %.
+- **Lock all drawings** — `lockAllDrawings(locked)` on `AstroneumHandle`.
+- **Drawing live preview** — `DrawingTemplates.preview()` + `applyColor()` per-overlay.
+- **Price axis scaling** — `priceScale='linear'|'log'|'percent'|'indexed'` prop + `PriceScaleTransform`.
+- **Chart templates** — `ChartTemplateManager` singleton saves/loads named configs to localStorage.
+- **Multi-timeframe resampling** — `resampleBars()`, `forwardFill()`, `mtfIndicator()`.
+- **Non-time-based bars** — `generateRenko()`, `generateKagi()`, `generateTickBars()`, `generateRangeBars()`.
+- **Point & Figure** — `generatePointAndFigure()`, `computePFColumns()`, `pfColumnsToBars()`.
+- **Multi-period layout** — `MultiPeriodLayout` stacked same-symbol different periods.
+- **Auto pattern detection** — `zigzag()`, `detectSupportResistance()`, `zigzagPlugin`.
+- **DOM visualization** — `domPlugin` bid/ask volume ladder.
+
+### Fixed — Bug, Perf & Security Hardening
+
+- **Bug: `rafMergeTick` low-merge inverted** — comparison operator fixed (was `<`, now `>`).
+- **Bug: `ScriptEngine` figures mutation** — shared `this.figures` now uses `[...result.figures]`.
+- **Bug: Plugin `figureKeys` closure leak** — moved to per-instance `extendData`.
+- **Bug: `Math.max(...arr)` stack overflow risk** — replaced with iterative loops in `DrawingSnapper`/`GlyphAtlas`.
+- **Bug: LTTB decimation NaN** — empty bucket guard added in `PerformanceMode.decimate()`.
+- **Bug: `virtualizeWindow` overlap** — startIdx/endIdx clamp added.
+- **Bug: `useKeyboardShortcuts` stale ref** — fixed stable wrapper pattern.
+- **Perf: Tooltip style objects pre-computed** at module scope (no per-render allocation).
+- **Perf: `adjustFromTo()` integer math** for week/month/year (eliminates `new Date()` allocations).
+- **Perf: `serializeState()` uses `structuredClone`** instead of recursive `deepClone`.
+- **Perf: 6 `useEffect` hooks batched** into one for engine prop sync.
+- **Perf: `sortBarsAsc()` O(n) validation** before sort (99% of API responses are pre-sorted).
+- **Perf: Shared color helpers** extracted to `candleShaders.ts` (~160 lines duplicated code removed).
+- **Perf: `TaskScheduler` priority queue** — data > indicator > overlay priority ordering.
+- **Perf: `IndicatorWorkerPool` SAB transfer** when `crossOriginIsolated`.
+- **Perf: `packBars()` optional columns** bitmap for skipping unused columns.
+- **Perf: `SharedIndicatorGLCanvas` FinalizationRegistry** for auto-cleanup.
+- **Perf: aria-live string buffer reuse** instead of template-string allocation per move.
+- **Security: ScriptEngine sandbox hardened** — `Object.freeze(Object/Array.prototype)` + `eval` blocked.
+- **Security: AlertManager webhook URL validated** — https-only, block private IPs/localhost.
+- **Security: localStorage writes debounced** — `AlertManager.check()` saves at most 1/s.
+- **Security: localStorage schema validation** on load — corrupted data rejected.
+- **Security: WebSocket URL scheme validation** — `wss://`/`ws://` required.
+- **Security: Polygon API key** moved from URL query param to `Authorization: Bearer` header.
+- **Security: `#apiKey` private class field** — non-enumerable, safe from `JSON.stringify`.
+- **Security: Locale strings stripped of HTML tags** — XSS prevention.
+- **Security: `BarsCodec.decode()` capped** at 500k bars to prevent OOM.
+- **Security: `pnpm audit` in all CI workflows.**
+- **Security: TA surface gating + OPFS path safety** documented.
+
+## [0.3.0] — 2026-06-15
+
+### Added — v0.5 Polish (partial)
+
+- **Lazy locale loading** ([src/i18n/index.ts](src/i18n/index.ts)) —
+  only `en-US` is bundled eagerly; the other 18 locales are loaded on
+  demand via dynamic `import()`. New public exports:
+  - `loadLocale(key)` — async loader for built-in locales
+  - `BUILTIN_LOCALES` — the canonical list
+  - Existing `loadLocales(key, dictionary)` continues to work for custom
+    translations.
+- **Drawing & layout persistence** — `serializeState()` and `loadState(state)`
+  on `AstroneumHandle` capture / restore theme, locale, timezone, symbol,
+  period, styles, indicators, and overlays as JSON.
+  See [docs/api.md](docs/api.md#serializestate--loadstate).
+- **Accessibility pass** — opt-in via the new `accessible` prop on
+  `<AstroneumChart>`. When enabled, the chart container gets `tabindex=0`,
+  `role="img"`, and an `aria-label`; a visually-hidden `aria-live="polite"`
+  region announces OHLCV on crosshair changes (throttled to ~10/s).
+- **High-contrast theme** — set `theme="high-contrast"` for a
+  WCAG-conscious black/white/yellow palette with strong focus rings.
+- **Benchmark CI workflow**
+  ([.github/workflows/benchmark.yml](.github/workflows/benchmark.yml)) —
+  runs `pnpm size` and the perf tests on every PR and posts the perf
+  output as a sticky comment.
+
+### Changed
+
+- `WasmIndicators.ts` renamed to **`TypedArrayIndicators.ts`** to match
+  what it actually is (a column-store TS implementation). A back-compat
+  shim is kept at the old path with `@deprecated` JSDoc and will be
+  removed in v1.0.
+
+### Deferred
+
+Still tracked for v0.6 – v1.0; not in this release:
+
+- WebGPU renderer / real Rust + WASM SIMD indicators
+- `OrderManager` + broker package
+- Heatmap / footprint / options-chain panes
+- Full mobile audit & Storybook site
+- React component tests (jsdom + RTL) + Playwright visual regression
+- Compare overlay UI
+
+---
+
+## [0.2.0] — 2026-05-30
+
+### Added — v0.3 Hardening
+
+- **Subpath exports** for tree-shakeable, opt-in feature modules
+  ([#roadmap-4](README.md#v04--modularization)):
+  - `astroneum/replay` — `BarReplay`
+  - `astroneum/multichart` — `MultiChartLayout`
+  - `astroneum/watchlist` — `WatchlistManager`
+  - `astroneum/portfolio` — `PortfolioTracker`
+  - `astroneum/alerts` — `AlertManager`
+  - `astroneum/script` — `ScriptEngine`
+  - `astroneum/datafeeds/polygon` — `DefaultDatafeed` + `WebSocketDatafeed`
+  - `astroneum/datafeeds/crypto` — `createStandardCryptoDatafeed` + adapters
+- **`size-limit` budget** ([.size-limit.json](.size-limit.json)) with one
+  budget per entry. Run `pnpm size` after `pnpm build`.
+- **Datafeed contract tests** ([src/__tests__/datafeed-contract.test.ts](src/__tests__/datafeed-contract.test.ts))
+  — type-level + behavioural checks for any `Datafeed` implementation.
+- **SSR smoke tests** ([src/__tests__/ssr-smoke.test.ts](src/__tests__/ssr-smoke.test.ts))
+  — verifies the root entry and all subpath entries import cleanly with no
+  DOM globals defined, and that the root entry's public API surface is stable.
+- **`CONTRIBUTING.md`**, **`SECURITY.md`**, **`CODE_OF_CONDUCT.md`**,
+  and this `CHANGELOG.md`.
+- **Browser support matrix** documented in [README](README.md#browser-support).
+
+### Changed
+
+- `pnpm verify` order is now `lint → typecheck → build → test` so SSR and
+  bundle tests can assert against fresh `dist/` output.
+- `tsup.config.ts` now bundles every subpath entry and injects `'use client'`
+  into every emitted JS file (not just `dist/index.js`).
+- `package.json#files` widened from `dist/*.{js,css,d.ts}` to
+  `dist/**/*.{js,css,d.ts}` so nested subpath artifacts ship.
+
+### Fixed
+
+- `src/index.ts` no longer side-imports the non-existent
+  `./styles/index.less` (was a leftover from a SCSS migration and caused the
+  build to fail outright on a clean install).
+
+---
+
+## [0.2.0-baseline] — 2026-05-30
+
+Initial public roadmap baseline. See git history for details prior to this
+changelog being introduced.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kowit Charoenratchatabhan
+
+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,198 @@
+# Astroneum
+
+Professional financial charting library for React applications — now with
+TradingView-class features, zero licensing fees, and MIT license.
+
+[![npm version](https://img.shields.io/npm/v/astroneum?label=npm)](https://www.npmjs.com/package/astroneum)
+[![npm downloads](https://img.shields.io/npm/dm/astroneum)](https://www.npmjs.com/package/astroneum)
+[![React 18-19](https://img.shields.io/badge/react-18%20%7C%2019-149eca)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/typescript-ready-3178c6)](https://www.typescriptlang.org/)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-339933)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+
+![Astroneum chart — dark theme with EMA, MACD, RSI and volume indicators](screenshort-1.png)
+
+![Astroneum chart — dark theme with multi-pane indicators](screenshort-2.png)
+
+## Features
+
+### Chart Types
+- **Candlestick, OHLC, bar, area, line, Heikin-Ashi** — rendered via Canvas2D / WebGL2 with GPU acceleration
+- **Non-time-based bars** — Renko, Kagi, Tick, Range, and Point & Figure generators
+- **Multi-chart grid** (2/4/8/16 panes) and **multi-period stacked layout** (e.g. 4H + 1H + 15m)
+
+### Indicators & Analysis
+- **28 built-in indicators** — SMA, EMA, MACD, RSI, KDJ, Bollinger Bands, TRIX, SAR, and more
+- **Volume Profile** — horizontal histogram with POC, Value Area, and price-level bucketing
+- **ZigZag + auto pattern detection** — swing highs/lows, support/resistance clustering
+- **Depth of Market** — bid/ask volume ladder visualization
+- **Compare/Overlay** — second symbol normalized to percentage on same pane
+- **Multi-timeframe indicators** — resample any TF, forward-fill to lower TF bars
+- **Custom indicator plugins** via `registerIndicatorPlugin()` with Canvas2D or WebGL2 render path
+- **Script editor** — sandboxed Pine-Script–inspired JS environment for custom indicators
+
+### Drawing Tools
+- **18 drawing tools** — trend lines, Fibonacci (circle, spiral, extension, segment, fan), Gann boxes, pitchforks, Elliott waves, harmonic patterns (ABCD, XABCD), and **measure/ruler tool**
+- **Magnet/Snap** — snap to bar OHLC within 8px, angle snap to 0°/30°/45°/60°/90°
+- **Drawing style presets** (7 built-in + custom) with live preview and per-drawing color
+- **Undo/Redo** — `UndoManager` with 50-entry depth via Ctrl+Z / Ctrl+Y
+- **Copy/Paste drawings** — Ctrl+C/V across charts via clipboard
+- **Lock all drawings** toggle
+- **Session visualizer** — auto session high/low/open/close lines
+
+### Navigation & UX
+- **Keyboard shortcuts** — arrows pan, Page/Home/End scroll/jump, mouse wheel zoom at cursor
+- **Crosshair sync** across multi-chart and multi-period layouts
+- **Price axis scaling** — linear, log, percentage, indexed-to-100
+- **Chart templates** — save/load named configurations to localStorage
+- **Accessibility** — `accessible` prop with aria-live OHLCV announcement
+- **State serialization** — full chart state persistence & recovery via `serializeState()`/`loadState()`
+
+### Data & Performance
+- **Off-main-thread indicator pool** — Web Workers + TypedArray column store
+- **OPFS historical cache** — binary bar data persisted to Origin Private File System
+- **FlatBuffers binary codec** (`BarsCodec`) — 40 bytes per bar, efficient storage & transfer
+- **TickAnimator** — smooth close/high/low interpolation at 60fps
+- **TaskScheduler** with priority queue (data > indicator > overlay)
+- **SharedArrayBuffer** ring buffer when `crossOriginIsolated`
+
+### Datafeeds
+- **StandardCryptoDatafeed** — 100+ symbols, Binance/Bitget/OKX futures, real-time WebSocket
+- **DefaultDatafeed & WebSocketDatafeed** — Polygon.io REST + WebSocket
+- **WebTransportDatafeed** — experimental HTTP/3 QUIC support
+- **BYO datafeed** — 4-method interface (`searchSymbols`, `getHistoryData`, `subscribe`, `unsubscribe`)
+
+### Developer Experience
+- **Fully typed TypeScript** — branded financial types (`Price`, `Volume`, `Timestamp`)
+- **8 tree-shakeable subpath exports** — import only what you need
+- **19 locales** — lazy-loaded on demand, dark/light/high-contrast themes
+- **SSR-safe** — `'use client'` on every entry, Next.js App Router compatible
+- **MIT license** — no usage limits, no watermark, no "Powered by" branding
+
+---
+
+## Install
+
+```bash
+npm install astroneum
+```
+
+`react` and `react-dom` ≥ 18 are peer dependencies.
+
+## Quick Start
+
+```tsx
+import { useMemo, useRef, useState } from 'react'
+import {
+  AstroneumChart,
+  createStandardCryptoDatafeed,
+  STANDARD_CRYPTO_SYMBOLS,
+  type AstroneumHandle,
+  type Period,
+  type SymbolInfo,
+} from '@tony01/astroneum'
+import 'astroneum/style.css'
+
+export default function App() {
+  const chartRef = useRef<AstroneumHandle>(null)
+  const datafeed = useMemo(() => createStandardCryptoDatafeed(), [])
+  const [symbol] = useState<SymbolInfo>(STANDARD_CRYPTO_SYMBOLS[0])
+  const [period] = useState<Period>({ multiplier: 1, timespan: 'hour', text: '1H' })
+
+  return (
+    <AstroneumChart
+      ref={chartRef}
+      symbol={symbol}
+      period={period}
+      datafeed={datafeed}
+      theme="dark"
+      subIndicators={['VOL']}
+      style={{ width: '100%', height: 560 }}
+    />
+  )
+}
+```
+
+## Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `symbol` | `SymbolInfo` | Symbol to display |
+| `period` | `Period` | Timeframe (1m, 5m, 1H, 4H, D, etc.) |
+| `datafeed` | `Datafeed` | Data source (crypto, Polygon, or custom) |
+| `theme` | `string` | `'dark'`, `'light'`, or `'high-contrast'` |
+| `barStyle` | `'candle' \| 'heikin_ashi'` | Candle rendering style |
+| `priceScale` | `'linear' \| 'log' \| 'percent' \| 'indexed'` | Price axis scale |
+| `locale` | `string` | BCP-47 locale (e.g. `'ja-JP'`) |
+| `drawingBarVisible` | `boolean` | Show drawing toolbar |
+| `mainIndicators` | `IndicatorDef[]` | Main pane indicators |
+| `subIndicators` | `string[]` | Sub-pane indicators (`['VOL', 'MACD', 'RSI']`) |
+| `plugins` | `ChartPlugin[]` | Custom plugins with lifecycle hooks |
+| `accessible` | `boolean` | Screen-reader support |
+| `style` / `className` | | Container styling |
+
+## Subpath Exports
+
+```tsx
+// Main entry
+import { AstroneumChart, DefaultDatafeed } from '@tony01/astroneum'
+
+// Tree-shakeable subpaths
+import { BarReplay }            from '@tony01/astroneum/replay'
+import { MultiChartLayout }     from '@tony01/astroneum/multichart'
+import { MultiPeriodLayout }    from '@tony01/astroneum'              // same symbol, stacked periods
+import { WatchlistManager }     from '@tony01/astroneum/watchlist'
+import { PortfolioTracker }     from '@tony01/astroneum/portfolio'
+import { AlertManager }         from '@tony01/astroneum/alerts'
+import { ScriptEngine }         from '@tony01/astroneum/script'
+import { UndoManager }          from '@tony01/astroneum'
+import { ChartTemplateManager } from '@tony01/astroneum'
+import { SessionVisualizer }    from '@tony01/astroneum'
+
+// Datafeeds
+import { createStandardCryptoDatafeed, STANDARD_CRYPTO_SYMBOLS } from '@tony01/astroneum/datafeeds/crypto'
+import { DefaultDatafeed, WebSocketDatafeed }                     from '@tony01/astroneum/datafeeds/polygon'
+
+// Utilities
+import { heikinAshi }                     from '@tony01/astroneum'  // OHLC → Heikin-Ashi transform
+import { zigzag, detectSupportResistance } from '@tony01/astroneum' // pattern detection
+import { resampleBars, forwardFill }      from '@tony01/astroneum'  // multi-TF resampling
+import { generateRenko, generateKagi,
+         generateTickBars, generateRangeBars,
+         generatePointAndFigure }         from '@tony01/astroneum'  // non-time-based bars
+import { transformCandles, untransformPrice } from '@tony01/astroneum' // price scale transforms
+
+// Plugins
+import { volumeProfilePlugin, domPlugin, zigzagPlugin,
+         pointAndFigurePlugin }           from '@tony01/astroneum'  // registerIndicatorPlugin(...)
+import { createCompareIndicator }         from '@tony01/astroneum'  // compare symbols overlay
+```
+
+## Browser Support
+
+| Browser | Minimum | Notes |
+|---------|---------|-------|
+| Chrome / Edge | 110+ | Full WebGL2 + OPFS |
+| Firefox | 115+ | Full WebGL2 |
+| Safari | 16.4+ | Full WebGL2, OPFS on 17+ |
+| iOS Safari | 16.4+ | Touch + pinch |
+
+Graceful fallback: no WebGL2 → Canvas2D, no OPFS → in-memory cache, no OffscreenCanvas → main-thread calc.
+
+## Next.js Usage
+
+```ts
+// next.config.ts
+const nextConfig = { transpilePackages: ['astroneum'] }
+```
+
+```tsx
+// app/layout.tsx
+import 'astroneum/style.css'
+```
+
+The library ships with `'use client'` built in — no extra directive needed.
+
+## License
+
+MIT — use it anywhere, no fees, no limits, no branding requirement.