@tony01/astroneum 0.4.1-beta.24 → 0.4.1-beta.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +2 -1
  2. package/package.json +1 -2
  3. package/docs/MIRROR-PLAN-SYMBOL-SEARCH-WATCHLIST.md +0 -255
  4. package/docs/STRUCTURE.md +0 -245
  5. package/docs/TODO-DESIGN.md +0 -335
  6. package/docs/TODO.md +0 -232
  7. package/docs/WORKSTREAMS.md +0 -55
  8. package/docs/api.md +0 -655
  9. package/docs/datafeed-guide.md +0 -329
  10. package/docs/design-astroneum.md +0 -618
  11. package/docs/plugin-development.md +0 -569
  12. package/docs/tv-functions-skill.md +0 -730
package/CHANGELOG.md CHANGED
@@ -7,9 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  once it reaches v1.0. Until then, minor releases may include breaking changes
8
8
  — always check this file before upgrading.
9
9
 
10
- ## [0.4.1-beta.24] - 2026-08-31
10
+ ## [0.4.1-beta.25] - 2026-08-31
11
11
 
12
12
  The `0.4.1-beta.22` and `0.4.1-beta.23` tags failed their package-content gates before npm publication and are not consumable releases.
13
+ The published `0.4.1-beta.24` artifact included internal/reference documentation and is not accepted for Barwise consumption. `0.4.1-beta.25` restricts the package to license, public release documentation, package metadata, and built distribution files.
13
14
 
14
15
  ### Added — Headless engine package
15
16
  - Added `@tony01/astroneum/headless` with a React-free declaration/runtime graph, no native UI, stylesheet, datafeed, keyboard-shortcut, or implicit-network dependency.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tony01/astroneum",
3
- "version": "0.4.1-beta.24",
3
+ "version": "0.4.1-beta.25",
4
4
  "packageManager": "pnpm@10.33.0",
5
5
  "description": "Astroneum - Professional financial charting library, ready out of the box.",
6
6
  "type": "module",
@@ -73,7 +73,6 @@
73
73
  "LICENSE",
74
74
  "README.md",
75
75
  "CHANGELOG.md",
76
- "docs",
77
76
  "dist/**/*.js",
78
77
  "dist/**/*.css",
79
78
  "dist/**/*.d.ts"
package/docs/MIRROR-PLAN-SYMBOL-SEARCH-WATCHLIST.md DELETED
@@ -1,255 +0,0 @@
1
- # Mirror Plan: Symbol Search + Watchlist Parity
2
-
3
- > **Status:** Phases 2–5 executed 2026-07-13 (commit `c14a88c` local / `4bfe8fd` server). **Phase 1 (dedicated capture scripts) was not executed** — see note below.
4
- > **Date:** 2026-07-13
5
- > **CDP source:** Chrome port 9223, chart `8Wh6yRIo`, BTC.D active
6
- > **Scope:** Capture live TV DOM for Symbol Search + Watchlist; implement functional parity in Astroneum
7
- >
8
- > **Execution note:** Phase 1's `cdp-symbol-search.js` / `cdp-watchlist.js` / `ref-symbol-search.html` / `ref-watchlist.html` were never created. The geometry and DOM structure used for Phases 2–5 came from ad hoc CDP `Runtime.evaluate` calls during the working session, recorded inline in `tv-mirror-reference/structure.md` §4.1 and `watchlist.md` §2.4/§3/§8. This is an honest gap, not a silent one: the values are real (captured live), but the capture is not re-runnable from a checked-in script. See `tv-mirror-reference/README.md` for the current, corrected evidence-files table. A follow-up should build the two capture scripts before the next visual refresh.
9
- >
10
- > **What actually shipped (Phases 2–3):** rewrote `SymbolSearchModal` (840px, 11 asset tabs, 4-cell rows, debounce, token-driven styling) and fixed the `Modal`/`Input` primitives it depends on (initial-focus targeting, native attribute forwarding, removed a hardcoded TradingView-blue focus glow). Rebuilt the Watchlist header to TV's actual 4-control anatomy (list selector / Add symbol / Advanced view / Settings) instead of the previous 5-tab layout, added collapsible group headers, widened the sidebar, and wired a working resize handle. Full detail in `docs/TODO-DESIGN.md` changelog, entry "2026-07-13 (c)".
11
- >
12
- > **What did not ship:** the automated visual-regression gate (Phase 5 in spirit, never formally scoped here) that the accompanying UX audit called for. Verification for this pass was `pnpm verify` + demo build + CDP computed-style comparison, not a screenshot-diff CI gate.
13
-
14
- ---
15
-
16
- ## Context
17
-
18
- Both surfaces were inspected live via CDP on 2026-07-13.
19
-
20
- ### Symbol Search is a shared library component
21
-
22
- `src/widget/symbol-search-modal/index.tsx` is consumed by two entry points:
23
- - `AstroneumChart.tsx:656` — chart symbol change (`chart.setSymbol()`)
24
- - `WatchlistPanel.tsx:219` — add to watchlist (`manager.addSymbolFromInfo()`)
25
-
26
- Rewriting it improves both entry points simultaneously.
27
-
28
- ### Current state
29
-
30
- | Surface | File | Lines | Gap |
31
- |---|---|---|---|
32
- | Symbol Search (library) | `src/widget/symbol-search-modal/index.tsx` | 100 | Large — 460px, no tabs, no row structure, no debounce |
33
- | Symbol Search SCSS | `src/widget/symbol-search-modal/index.scss` | 42 | Layout for 460px modal |
34
- | Watchlist (demo) | `demo/src/app/components/panels/WatchlistPanel.tsx` | 514 | Small — missing section group headers |
35
- | Watchlist CSS | `demo/src/app/components/panels/panels.css` L1-286 | 286 | Mature |
36
- | WatchlistManager (library) | `src/chart/WatchlistManager.ts` | 244 | Stable — add `group` field |
37
-
38
- ### Live TV DOM (observed via CDP 2026-07-13)
39
-
40
- **Symbol Search dialog** — `[data-name="symbol-search-items-dialog"]` role=dialog, 840x680px:
41
- ```
42
- Title "Symbol search" + Close [data-qa-id="close"]
43
- Input [data-qa-id="symbol-search-input"] role=searchbox, placeholder="Symbol, ISIN, or CUSIP"
44
- Tabs [role=tablist]: All(active) / Stocks / Funds / Futures / Forex / Crypto / Indices / Bonds / Economy / Options / More
45
- Results: [data-name="symbol-search-dialog-content-item"] rows, 4 cells:
46
- 1. ticker (bold, e.g. "BTCUSD")
47
- 2. description (muted, e.g. "Bitcoin / U.S. dollar")
48
- 3. exchange (smaller, e.g. "spot crypto defiBitstamp")
49
- 4. actions (empty, hover-revealed)
50
- 51 rows in listContainer, active row has indigo tint
51
- Footer: "Search using ISIN and CUSIP codes"
52
- ```
53
-
54
- **Watchlist panel** — rail `[data-name="base"]` 44x44px aria-pressed=true:
55
- ```
56
- Header:
57
- [data-name="watchlists-button"] "Red list" 102x34px
58
- [data-name="add-symbol-button"] aria-label="Add symbol" 38x38px
59
- [data-name="advanced-view-button"] aria-label="Advanced view" 38x38px
60
- [data-name="settings-button"] aria-label="Settings" 38x38px
61
- Columns: Symbol / Last / Chg / Chg% (sortable buttons, class="sortable-PYr1BHmD", NO aria-sort on TV)
62
- Rows: [data-name="symbol-list-wrap"] 319x775px
63
- Each row: ticker + "Market open" status + last + chg + chg% + volume
64
- Section dividers: plain text group headers (e.g. "US STOCK")
65
- Details: details-add-note / details-settings / details-more-technicals
66
- ```
67
-
68
- ---
69
-
70
- ## Phase 1: CDP Capture
71
-
72
- ### 1A. Create two targeted capture scripts
73
-
74
- | Script | Output | Target |
75
- |---|---|---|
76
- | `cdp-symbol-search.js` | `ref-symbol-search.html` + `symbol-search.png` | `[data-name="symbol-search-items-dialog"]` outerHTML + screenshot |
77
- | `cdp-watchlist.js` | `ref-watchlist.html` + `watchlist.png` | Watchlist panel (header + columns + rows) outerHTML + screenshot |
78
-
79
- Both reuse the existing CDP pattern (port 9223, WebSocket, `Runtime.evaluate` + `Page.captureScreenshot`). Output only to `tv-mirror-reference/`.
80
-
81
- ### 1B. Update reference docs
82
-
83
- | File | Section | Change |
84
- |---|---|---|
85
- | `tv-mirror-reference/watchlist.md` | 2.4, 3, 8 | Fill `not captured` items: row DOM (4 cells per row), section group headers ("US STOCK"), "Market open" status, details buttons |
86
- | `tv-mirror-reference/structure.md` | 4.1 | Update Symbol Search: 840px width, 11 tabs, 4-cell rows, footer text, selectors |
87
- | `tv-mirror-reference/README.md` | Evidence files table | Add `ref-symbol-search.html`, `ref-watchlist.html` rows |
88
-
89
- ---
90
-
91
- ## Phase 2: Symbol Search Rewrite (library-level)
92
-
93
- ### 2A. Component rewrite — `src/widget/symbol-search-modal/index.tsx`
94
-
95
- | # | Change | Why |
96
- |---|---|---|
97
- | S1 | Width 460px to 840px | Fit 4-cell rows |
98
- | S2 | Asset-class tabs: All / Stocks / Funds / Futures / Forex / Crypto / Indices / Bonds / Economy / Options / More | Core TV function — filter results by `symbol.type` |
99
- | S3 | 4-cell result rows: ticker / description / exchange / actions | TV row structure |
100
- | S4 | Keyboard up/down navigation through results | Functional — can't use dialog without it |
101
- | S5 | 200ms debounce on input | Prevents API hammering (Polygon) |
102
- | S6 | Footer "Search using ISIN and CUSIP codes" | Part of the dialog |
103
-
104
- `SymbolInfo.type` is `string` (not union) — tab filter maps common values client-side: `stock/equity` to Stocks, `crypto` to Crypto, `forex/fx` to Forex, etc. Undefined `type` shows in "All" only.
105
-
106
- ### 2B. Props interface — no breaking change
107
-
108
- ```ts
109
- export interface SymbolSearchModalProps {
110
- locale: string
111
- searchSymbols: (query?: string) => Promise<SymbolInfo[]>
112
- onSymbolSelected: (symbol: SymbolInfo) => void
113
- onClose: () => void
114
- }
115
- ```
116
-
117
- No change to `Datafeed.searchSymbols` signature — filtering by `type` happens client-side on returned results.
118
-
119
- ### 2C. SCSS rewrite — `src/widget/symbol-search-modal/index.scss`
120
-
121
- - 840px width, max-height with internal scroll on results
122
- - Tab bar: horizontal scroll, 28px buttons, active underline
123
- - Result rows: 4-cell grid layout (ticker | description | exchange | actions)
124
- - Active row: `--astroneum-accent-tint` background
125
- - Footer: muted, 12px, centered
126
-
127
- ### 2D. i18n — `src/i18n/en-US.json`
128
-
129
- New keys (en-US first, 17 other locales fall back):
130
- ```json
131
- "symbol_search_all": "All",
132
- "symbol_search_stocks": "Stocks",
133
- "symbol_search_funds": "Funds",
134
- "symbol_search_futures": "Futures",
135
- "symbol_search_forex": "Forex",
136
- "symbol_search_crypto": "Crypto",
137
- "symbol_search_indices": "Indices",
138
- "symbol_search_bonds": "Bonds",
139
- "symbol_search_economy": "Economy",
140
- "symbol_search_options": "Options",
141
- "symbol_search_more": "More",
142
- "symbol_search_footer": "Search using ISIN and CUSIP codes"
143
- ```
144
-
145
- ### 2E. No subpath export needed
146
-
147
- `SymbolSearchModal` rides the root barrel (`src/index.ts:82`). No `src/entries/` or `package.json` change.
148
-
149
- ### 2F. Demo consumer fix — `WatchlistPanel.tsx:219`
150
-
151
- Pass `locale` prop instead of hardcoded `"en-US"`.
152
-
153
- ---
154
-
155
- ## Phase 3: Watchlist — section group headers
156
-
157
- ### 3A. `WatchlistManager.ts` — add `group` field
158
-
159
- ```ts
160
- export interface WatchSymbol {
161
- ticker: string
162
- // ... existing fields ...
163
- group?: string // section header label (e.g. "US STOCK")
164
- }
165
- ```
166
-
167
- `group` persists (not stripped by `_storedSymbol` — it's user-organized, not injected like quotes). Add to the whitelist in `_storedSymbol` (L196-206).
168
-
169
- ### 3B. Render section dividers — `WatchlistPanel.tsx`
170
-
171
- When iterating sorted symbols, detect `group` changes and insert a non-interactive divider row with the group label text.
172
-
173
- ### 3C. Divider row style — `panels.css`
174
-
175
- ```css
176
- .term-wl-group-header {
177
- padding: 8px 12px;
178
- font-size: 11px;
179
- font-weight: 600;
180
- color: var(--term-text-2);
181
- text-transform: uppercase;
182
- letter-spacing: 0.04em;
183
- background: var(--term-panel-bg);
184
- position: sticky;
185
- top: 0;
186
- z-index: 1;
187
- }
188
- ```
189
-
190
- ---
191
-
192
- ## Phase 4: Docs Sync
193
-
194
- | File | Section | Change |
195
- |---|---|---|
196
- | `docs/TODO-DESIGN.md` | 7.6 | Symbol Search: update spec (840px, tabs, 4-cell rows) |
197
- | `docs/TODO-DESIGN.md` | 3b | Add section group header row |
198
- | `docs/TODO-DESIGN.md` | 11.10 | Symbol search result-state parity: mark progress |
199
- | `docs/design-astroneum.md` | Symbol Search Pill | Update width 640 to 840px, add tab + 4-cell row spec |
200
- | `docs/design-astroneum.md` | Watchlist Panel | Add section group headers |
201
- | `tv-mirror-reference/watchlist.md` | 2.4, 3, 8 | Fill `not captured` items from CDP |
202
- | `tv-mirror-reference/structure.md` | 4.1 | Update Symbol Search DOM |
203
- | `tv-mirror-reference/README.md` | Evidence table | Add new capture files |
204
-
205
- ---
206
-
207
- ## Phase 5: Verification
208
-
209
- ```
210
- pnpm verify (= pnpm lint && pnpm typecheck && pnpm build && pnpm test)
211
- ```
212
-
213
- Must pass before any deploy. No deploy in this plan — implementation only.
214
-
215
- ---
216
-
217
- ## Execution Order
218
-
219
- 1. Phase 1A — CDP capture scripts (2 new files in `tv-mirror-reference/`)
220
- 2. Phase 2A-2F — Symbol Search rewrite (library: tsx + scss + i18n; demo: locale fix)
221
- 3. Phase 3A-3C — Watchlist section group headers (library: `group` field; demo: divider rows + CSS)
222
- 4. Phase 4 — Docs sync
223
- 5. Phase 5 — `pnpm verify`
224
-
225
- ---
226
-
227
- ## Files Touched
228
-
229
- | File | Phase | Change |
230
- |---|---|---|
231
- | `tv-mirror-reference/cdp-symbol-search.js` | 1A | New — CDP capture script |
232
- | `tv-mirror-reference/cdp-watchlist.js` | 1A | New — CDP capture script |
233
- | `tv-mirror-reference/ref-symbol-search.html` | 1A | New — capture output |
234
- | `tv-mirror-reference/ref-watchlist.html` | 1A | New — capture output |
235
- | `tv-mirror-reference/structure.md` | 1B | Update 4.1 |
236
- | `tv-mirror-reference/watchlist.md` | 1B | Update 2.4, 3, 8 |
237
- | `tv-mirror-reference/README.md` | 1B | Update evidence table |
238
- | `src/widget/symbol-search-modal/index.tsx` | 2A | Rewrite — tabs, 4-cell rows, debounce, keyboard nav |
239
- | `src/widget/symbol-search-modal/index.scss` | 2C | Rewrite — 840px layout |
240
- | `src/i18n/en-US.json` | 2D | 12 new keys |
241
- | `demo/src/app/components/panels/WatchlistPanel.tsx` | 2F, 3B | Locale fix + section dividers |
242
- | `demo/src/app/components/panels/panels.css` | 3C | Group header style |
243
- | `src/chart/WatchlistManager.ts` | 3A | Add `group` field |
244
- | `docs/TODO-DESIGN.md` | 4 | Update 7.6, 3b, 11.10 |
245
- | `docs/design-astroneum.md` | 4 | Update Symbol Search + Watchlist sections |
246
-
247
- ---
248
-
249
- ## Risks
250
-
251
- | Risk | Mitigation |
252
- |---|---|
253
- | `SymbolInfo.type` is `string` not union — tab filter may miss non-standard values | Client-side filter: if `type` undefined, show in "All" only; map common values |
254
- | No debounce currently — Polygon API rate limits | 200ms debounce + cancel in-flight on new keystroke |
255
- | `group` field on `WatchSymbol` needs migration for existing localStorage | `_load()` already validates; add `group` with fallback `undefined` |
package/docs/STRUCTURE.md DELETED
@@ -1,245 +0,0 @@
1
- # Astroneum — Structure Map
2
-
3
- > Living reference for the Astroneum project deployed at **https://72.62.73.180/astroneum/**.
4
- > Documents *what lives where*. For design rationale see `docs/design-astroneum.md`.
5
- > Last updated: **2026-08-29**. Keep this file in sync on every structural change (see §11).
6
-
7
- ## 1. Overview
8
-
9
- | | |
10
- |---|---|
11
- | Name | `astroneum` |
12
- | Version | `0.4.1-beta.24` |
13
- | Description | Professional financial charting library, ready out of the box |
14
- | License | MIT (author `kowito`, repo `github.com/kowito/astroneum`) |
15
- | Stack | TypeScript · React 18/19 peer · ESM-only · Canvas + WebGL/WebGPU · tsup · pnpm |
16
- | Server path | `/opt/astroneum` (owned by `deploy:deploy`) |
17
- | Git on server | Clone of `Tony1185/Astroneum` (fork). `origin` → fork, `upstream` → `kowito/astroneum`. Deploy via `git pull` → build → PM2 restart. |
18
- | Served at | `https://72.62.73.180/astroneum/` (nginx → `127.0.0.1:3002`) |
19
- | Coexistence | Shares host with `trading-bot-v2` (`/opt/trading-bot-v2`, ports 3000/3001). No shared code or DB. |
20
-
21
- ## 2. Repository layout (`/opt/astroneum`)
22
-
23
- ```
24
- /opt/astroneum/
25
- ├── src/ # library source (see §3)
26
- ├── dist/ # compiled output: ESM js + astroneum.css + .d.ts + locale chunks (gitignored, build artifact)
27
- ├── demo/ # Next.js showcase app "astroneum-demo-next" (see §5)
28
- ├── docs/ # developer docs (see §9; WORKSTREAMS owns delivery claims)
29
- ├── .opencode/ # AI OS config (fork-only, never PR to upstream)
30
- │ ├── opencode.json # references (11 docs), permissions, skills path
31
- │ ├── agents/ # 6 subagents: builder, demo-builder, deployer, doc-syncer, parity-checker, auditor
32
- │ ├── commands/ # 5 commands: /deploy, /refresh-structure, /refresh-todo, /verify, /parity-check
33
- │ └── skills/ # 3 skills: conventions, deploy, doc-sync
34
- ├── AGENTS.md # project kernel — auto-loaded by opencode as system prompt
35
- ├── .github/workflows/ # CI: auto-version-bump, benchmark, npm-publish
36
- ├── ecosystem.config.cjs # PM2 config for astroneum-demo (see §7)
37
- ├── pnpm-workspace.yaml # workspace: packages=[demo]; allowBuilds: @parcel/watcher, esbuild, sharp
38
- ├── package.json # public package manifest + exports map (see §4)
39
- ├── pnpm-lock.yaml
40
- ├── tsup.config.ts # library bundler config (see §6)
41
- ├── tsconfig.json
42
- ├── eslint.config.js
43
- ├── .size-limit.json # per-entry bundle budgets (see §6)
44
- ├── .gitignore
45
- ├── check_dist.mjs # smoke: import dist, check exports
46
- ├── check_datafeed.mjs # smoke: exercise createStandardCryptoDatafeed
47
- ├── README.md CHANGELOG.md CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md LICENSE INDICATOR_COMPARISON.md
48
- └── screenshort-1.png screenshort-2.png # (sic: "screenshort")
49
- ```
50
-
51
- ## 3. Library source (`src/`)
52
-
53
- Root files: `index.ts` (public barrel), `types.ts`, `utils.ts`, `constants.ts`, `react-shared.tsx`, `assets.d.ts`.
54
-
55
- ### 3.1 `chart/` — high-level chart features (26 modules)
56
- `AstroneumChart.tsx` (main React component), `index.ts`, `hooks.ts`, plus feature modules:
57
- `AlertManager`, `BarReplay`, `ChartTemplateManager`, `CompareOverlay`, `DOMPane`, `DrawingSnapper`, `DrawingTemplates`, `EventBus`, `MultiChartLayout`, `MultiPeriodLayout`, `MultiTimeframe`, `NonTimeBars`, `PatternRecognition`, `PerformanceMode`, `PointAndFigure`, `PortfolioTracker`, `PositionVisualizer`, `PriceScaleTransform`, `SessionVisualizer`, `UndoManager`, `VolumeProfilePlugin`, `WatchlistManager`, `ZigzagPattern`.
58
-
59
- ### 3.2 `component/` — primitive UI (10 atoms)
60
- Each is a `index.tsx` + `index.scss` pair: `button`, `checkbox`, `dropdown`, `empty`, `input`, `list`, `loading`, `modal`, `select`, `switch`. Root `index.tsx` + `index.scss` barrel.
61
-
62
- ### 3.3 `engine/` — rendering core
63
- Root: `Chart.ts`, `ChartRegistry.ts`, `Event.ts`, `Options.ts`, `Store.ts`, `index.ts`.
64
- - `common/` (~45 modules) — renderers & primitives: `Canvas`, `WebGLCanvas`, `SharedIndicatorGLCanvas`, `CandleWebGLRenderer`, `CandleWebGPURenderer`, `CandleWorkerRenderer`, `IndicatorLineWebGLRenderer`, `IndicatorPluginWebGLRenderer`, `IndicatorRectWebGLRenderer`, `TextWebGLRenderer`, `GlyphAtlas`, `candleShaders.ts`; data/coord: `Data`, `DataLoader`, `SymbolInfo`, `Period`, `VisibleRange`, `BarSpace`, `Bounding`, `Coordinate`, `Point`; interaction: `Crosshair`, `EventHandler`, `Eventful`, `Action`, `Animation`, `TickAnimator`, `TaskScheduler`, `Updater`; buffers: `RingBuffer`, `SabRingBuffer`; styling/types: `Styles`, `Nullable`, `DeepPartial`, `DeepRequired`, `PickPartial`, `PickRequired`, `ExcludePickPartial`; `utils/`.
65
- - `component/` — engine-level components: `Axis`, `XAxis`, `YAxis`, `Figure`, `Indicator`, `Overlay`.
66
- - `pane/` — `Pane`, `CandlePane`, `IndicatorPane`, `DrawPane`, `SeparatorPane`, `XAxisPane`, `types.ts`.
67
- - `view/` (22) — render views: `View`, `AxisView`, `XAxisView`, `YAxisView`, `GridView`, `CandleAreaView`, `CandleBarView`, `CandleHighLowPriceView`, `CandleLastPriceLineView`, `CandleLastPriceLabelView`, `CandleTooltipView`, `ChildrenView`, `CrosshairFeatureView`, `CrosshairLineView`, `CrosshairHorizontalLabelView`, `CrosshairVerticalLabelView`, `IndicatorView`, `IndicatorTooltipView`, `IndicatorLastValueView`, `OverlayView`, `OverlayXAxisView`, `OverlayYAxisView`.
68
- - `widget/` — `Widget`, `CandleWidget`, `IndicatorWidget`, `DrawWidget`, `SeparatorWidget`, `XAxisWidget`, `YAxisWidget`, `types.ts`.
69
- - `workers/` — `IndicatorWorkerPool`, `TypedArrayIndicators`, `WasmIndicators`.
70
- - `extension/` — extension registries: `figure`, `i18n`, `indicator`, `overlay`, `styles`, `x-axis`, `y-axis`.
71
-
72
- ### 3.4 `widget/` - UI modals & bars (11)
73
- Each `index.tsx` + `index.scss` (some with `data.ts`/`types.ts`/`icons/`): `alert-modal`, `drawing-bar` (+`icons/`; sole left rail after dead demo `term-rail` removal; cursor submenu, measure, zoom, keep-drawing toggle, hide-all, forecasting group with 12 tools in 3 sections), `indicator-modal`, `indicator-setting-modal` (+`data.ts`,`types.ts`), `period-bar`, `screenshot-modal`, `script-editor-modal`, `setting-modal` (+`data.ts`), `symbol-search-modal`, `timezone-modal` (+`data.ts`), `watchlist`. `WatchlistManager` now ships `moveSymbol`/`setSort`/`setColumns`/`setColor`/`updateQuotes`/`addSymbolFromInfo`; `Datafeed.getQuotes?` supplies optional live snapshots. Root `index.tsx` + `index.scss`.
74
-
75
- ### 3.5 `datafeed/` — data transport
76
- `DefaultDatafeed.ts`, `StandardCryptoDatafeed.ts` (Binance/Bitget/OKX USDT history, streams, and batched quote snapshots), `WebSocketDatafeed.ts`, `WebTransportDatafeed.ts`, `OPFSCache.ts` (off-thread cache), `codec/BarsCodec.ts`, `index.ts`.
77
-
78
- ### 3.6 `entries/` — subpath entry bundles
79
- `headless.ts`, `replay.ts`, `multichart.ts`, `watchlist.ts`, `workspace.ts`, `portfolio.ts`, `alerts.ts`, `script.ts`, `datafeeds/polygon.ts`, `datafeeds/crypto.ts`. (Mirror the `exports` map in §4.)
80
-
81
- ### 3.7 `extension/` — drawing tools (32 + utils + index)
82
- `abcd`, `xabcd`, `arrow`, `circle`, `rect`, `triangle`, `parallelogram`, `pitchfork`, `measure`, `waves`, `gannBox`, `gannFan`, `fibonacciCircle`, `fibonacciExtension`, `fibonacciSegment`, `fibonacciSpeedResistanceFan`, `fibonacciSpiral`, `longPosition`, `shortPosition`, `positionForecast`, `barsPattern`, `ghostFeed`, `sector`, `anchoredVwap`, `fixedRangeVolumeProfile`, `anchoredVolumeProfile`, `priceRange`, `dateRange`, `dateAndPriceRange`; `utils.ts`, `index.ts`.
83
-
84
- ### 3.8 `scripting/` — `ScriptEngine.ts` (Pine-like indicator runtime plus bounded `strategySignals()` compilation).
85
-
86
- ### 3.9 `strategy/` — deterministic backtest core
87
- `BacktestEngine.ts` runs bar-close fills, commission, slippage, trade accounting, equity, and drawdown without browser/network state. `types.ts` owns the report contract shared by demo UI and future worker execution.
88
-
89
- ### 3.10 `store/` — state: `chartStore.ts`, `indicatorStore.ts`, `uiStore.ts`, `index.ts`.
90
-
91
- ### 3.11 `i18n/` - 18 locale JSON files + `format.ts` + `index.ts`
92
- `ar-SA, de-DE, en-US, es-ES, fr-FR, hi-IN, id-ID, it-IT, ja-JP, ko-KR, nl-NL, pl-PL, pt-BR, ru-RU, th-TH, tr-TR, vi-VN, zh-CN`.
93
-
94
- ### 3.12 Misc
95
- - `plugin/index.ts` — plugin API surface; `plugin/types.ts` keeps study-plugin contracts independent of React declarations.
96
- - `jsx/` — `jsx-runtime.ts`, `jsx-dev-runtime.ts` (custom JSX runtime; tsconfig `jsxImportSource: @/jsx`).
97
- - `styles/` — `base.scss`, `index.scss` (built to `dist/astroneum.css`).
98
- - `assets/` — `logo.svg`, `iconfonts/{fonts, style.css}`.
99
- - `__tests__/` — `adjustFromTo`, `datafeed-contract`, `headless-bars`, `headless-lifecycle`, `headless-package`, `persistence`, `plugin`, `script-engine`, `ssr-smoke`, `strategy`, `utils`, `watchlist` (`.test.ts`), + `perf/`.
100
-
101
- ## 4. Public API surface (`package.json` `exports`)
102
-
103
- | Subpath | Dist target |
104
- |---|---|
105
- | `@tony01/astroneum` (`.`) | `dist/index.js` |
106
- | `@tony01/astroneum/headless` | `dist/entries/headless.js` |
107
- | `@tony01/astroneum/replay` | `dist/entries/replay.js` |
108
- | `@tony01/astroneum/multichart` | `dist/entries/multichart.js` |
109
- | `@tony01/astroneum/watchlist` | `dist/entries/watchlist.js` |
110
- | `@tony01/astroneum/portfolio` | `dist/entries/portfolio.js` |
111
- | `@tony01/astroneum/alerts` | `dist/entries/alerts.js` |
112
- | `@tony01/astroneum/script` | `dist/entries/script.js` |
113
- | `@tony01/astroneum/datafeeds/polygon` | `dist/entries/datafeeds/polygon.js` |
114
- | `@tony01/astroneum/datafeeds/crypto` | `dist/entries/datafeeds/crypto.js` |
115
- | `@tony01/astroneum/style.css` | `dist/astroneum.css` |
116
- | `@tony01/astroneum/package.json` | `./package.json` |
117
-
118
- tsup entries (single source of truth for the above): `src/index.ts` + the 10 `src/entries/**` files. All entries ship with `.d.ts`. esbuild strips `'use client'`; `tsup.onSuccess` re-injects it into every emitted `.js` so Next.js App Router treats each entry as a Client Module. The headless entry is SSR-import safe, has no React/native-UI/datafeed dependency, requires no stylesheet, installs optional indicator/drawing built-ins only through an explicit call, and exposes React-independent typed study plus bounded viewport-recovery contracts.
119
-
120
- `peerDependencies`: `react` / `react-dom` `^18 || ^19`. `engines.node`: `>=18`.
121
-
122
- ## 5. Demo app (`demo/` — `astroneum-demo-next`)
123
-
124
- Next.js 15 + React 19 showcase. Private workspace package, depends on `@tony01/astroneum: workspace:*`.
125
-
126
- - `package.json` — scripts: `dev`, `build`, `start` (= `next start -p 3002`). Deps: `next ^15.3.1`, `react ^19.2`, `@tony01/astroneum workspace:*`.
127
- - `next.config.ts` — `transpilePackages: ['@tony01/astroneum']`, `basePath: NEXT_PUBLIC_BASE_PATH` (=`/astroneum` in prod), `trailingSlash: true`, `outputFileTracingRoot: ../`.
128
- - `src/app/` routes (App Router):
129
- - `layout.tsx`, `page.tsx`, `globals.css`
130
- - `_components/alerts/` — `AlertDialog`, `ErrorBoundary`, `NotificationsDialog`, `Popover` + `alert-dialog.css`
131
- - `alerts/page.tsx`
132
- - `api/alerts/email/route.ts`, `api/alerts/webhook/route.ts`
133
- - `components/` — `ChartDemo`, `ChartTerminal`, `ChartTypeDropdown`, `CommandPalette`, `DateRangeNavigator`, `ErrorBoundary`, `MultiChartView`, `PatternDialog`, `ReplayToolbar`, `SaveLoadMenu`, `TerminalShell` + `enhancements.css`, `terminal.css`; `SidebarContent` renders panel body first and the persistent 52px rail last so it stays on the outer-right edge
134
- - `components/panels/` — `PineEditorPanel`, `WatchlistPanel` (Watchlist/Details/News; live quotes, list tabs, sorting/settings/context actions), `DetailsPanel`, `AlertsPanel` + `panels.css`
135
- - `support/` — `layout.tsx`, `support.css`, `_components/{ArticleBody, Breadcrumb}`, `_lib/{articles/, articles-data.json, data.ts}`, `categories/alerts/page.tsx`, `folders/[folder]/page.tsx`, `solutions/[slug]/page.tsx`
136
- - `mockDatafeed.ts`, `types/css-imports.d.ts`
137
- - Other: `.env`, `.gitignore`, `.impeccable/`, `.next/` (build out), `DESIGN.md`, `PRODUCT.md`, `README.md`, `next-env.d.ts`, `tsconfig.json`, `package.json.bak.`.
138
-
139
- ## 6. Build & tooling
140
-
141
- - **pnpm workspace** (`pnpm-workspace.yaml`): `packages: [demo]`; `allowBuilds: @parcel/watcher, esbuild, sharp`.
142
- - **package.json scripts**: `clean`, `build:js` (tsup), `build:css` (sass → esbuild bundle/minify, inlines eot/ttf/woff/svg), `build` (clean + js + css), `typecheck` (`tsc --noEmit`), `test` (`tsx --test src/__tests__/*.test.ts`), `test:watch`, `lint` (`eslint src`), `size` (`size-limit`), `verify` (lint+typecheck+build+test), `prepublishOnly` (verify).
143
- - **tsup.config.ts** — `format: ['esm']`, `dts: true`, `splitting: true`, `treeshake: true`, `target: 'esnext'`, `outDir: dist`, `external: ['react','react-dom','react-dom/client','react/jsx-runtime']`; esbuild `jsx: 'automatic'`, alias `@ → ./src`, loaders `.less → empty`, `.svg → text`; `onSuccess` walks `dist/` and prepends `'use client';` to every `.js`.
144
- - **tsconfig.json** — `target/module: ESNext`, `moduleResolution: Bundler`, `jsx: preserve`, `jsxImportSource: @/jsx`, `paths: @/* → ./src/*`, `include: src`, `exclude: src/__tests__`, `noEmit: true` (typecheck only).
145
- - **.size-limit.json** — 10 budgets (ignore react/react-dom): root `200 KB`; `headless` `80 KB` with all exports imported; `replay`/`multichart`/`script` `15 KB`; `watchlist`/`portfolio`/`alerts` `10 KB`; `datafeeds/polygon`/`datafeeds/crypto` `30 KB`.
146
- - **eslint.config.js** — flat config.
147
- - **Smoke scripts**: `check_dist.mjs` (imports `dist`, asserts `AstroneumChart`, `createStandardCryptoDatafeed`, `STANDARD_CRYPTO_SYMBOLS`); `check_datafeed.mjs` (searchSymbols + bounded history fetch).
148
-
149
- ## 7. Deployment topology
150
-
151
- ### nginx (TLS termination, 443/80)
152
- - `:80` → `301` to `https://$host$request_uri`.
153
- - `:443` ssl — cert `/etc/nginx/ssl/server.{crt,key}`, TLS 1.2/1.3.
154
- - Routes:
155
- - `/astroneum/_next/static/` → `127.0.0.1:3002` — immutable (`max-age=31536000, immutable`)
156
- - `/astroneum/` → `127.0.0.1:3002` — `no-cache, must-revalidate`
157
- - `/` → `127.0.0.1:3000` (trading-bot-web, WebSocket upgrade)
158
- - `/socket.io/` → `127.0.0.1:3001` (trading-bot-ws, WebSocket upgrade)
159
- - Security headers on all blocks: `X-Frame-Options DENY`, `X-Content-Type-Options nosniff`, `Referrer-Policy strict-origin-when-cross-origin`, HSTS preload.
160
- - **Caveat:** `sites-enabled/` currently contains **3 overlapping server blocks** for `72.62.73.180` (only the first match wins). Worth consolidating — flag for cleanup.
161
-
162
- ### PM2 — `astroneum-demo` (`ecosystem.config.cjs`)
163
- | Field | Value |
164
- |---|---|
165
- | name | `astroneum-demo` |
166
- | script | `pnpm` · args `--filter astroneum-demo-next start` |
167
- | cwd | `/opt/astroneum` |
168
- | env | `NODE_ENV=production`, `NEXT_PUBLIC_BASE_PATH=/astroneum`, `NODE_OPTIONS=--max-old-space-size=256`, `TZ=Asia/Bangkok` |
169
- | max_memory_restart | `512M` |
170
- | autorestart / watch | true / false |
171
- | logs | `/home/deploy/.pm2/logs/astroneum-demo-{out,error}.log` |
172
-
173
- ### Ports
174
- | Port | Bind | Process |
175
- |---|---|---|
176
- | 80 | 0.0.0.0 | nginx (→ 443) |
177
- | 443 | 0.0.0.0 | nginx (TLS) |
178
- | 3000 | 127.0.0.1 | trading-bot-web (Next.js) |
179
- | 3001 | 127.0.0.1 | trading-bot-ws (Socket.io) |
180
- | 3002 | 127.0.0.1 | **astroneum-demo** (Next.js) |
181
-
182
- ## 8. Build & deploy flow
183
-
184
- Library change → demo rebuild → restart (demo only; trading-bot unaffected):
185
-
186
- ```bash
187
- ssh 72.62.73.180 "cd /opt/astroneum && pnpm build" # 1. lib → dist/ (tsup + css)
188
- ssh 72.62.73.180 "cd /opt/astroneum && pnpm --filter astroneum-demo-next build" # 2. demo → demo/.next/ (transpilePackages picks up new dist)
189
- ssh 72.62.73.180 "pm2 restart astroneum-demo" # 3. serve
190
- ```
191
-
192
- - Demo-only change (no lib touch): skip step 1.
193
- - Docs-only change (e.g. this file): no build, no restart.
194
- - Lib `build` runs `pnpm clean` first — wipes `dist/`.
195
-
196
- ## 9. Docs & meta
197
-
198
- | Doc | Role | NOT for |
199
- |---|---|---|
200
- | `STRUCTURE.md` (this file) | Where things live (file tree, deploy, build) | How to use → `api.md` · How to build plugins → `plugin-development.md` |
201
- | `tv-functions-skill.md` | TV→Astroneum function catalog + **authoritative status** | Actionable gaps → `TODO.md` · Design → `TODO-DESIGN.md` |
202
- | `design-astroneum.md` | Library UX spec (colors, typography, layout, motion) | Demo app design → `demo/DESIGN.md` · Status → `TODO-DESIGN.md` |
203
- | `api.md` | API reference (signatures) | How to author plugins → `plugin-development.md` |
204
- | `datafeed-guide.md` | Datafeed how-to | Plugin authoring → `plugin-development.md` |
205
- | `plugin-development.md` | Plugin authoring guide | API signatures → `api.md` |
206
- | `TODO.md` | Actionable function-gap backlog | Status authority → `tv-functions-skill.md` · Design → `TODO-DESIGN.md` |
207
- | `TODO-DESIGN.md` | Design/layout gap backlog | Function gaps → `TODO.md` · Status authority → `tv-functions-skill.md` |
208
- | `WORKSTREAMS.md` | Ownership, sequencing, dependencies, and handoffs | Feature status or detailed gap tables |
209
- | `INDICATOR_COMPARISON.md` | Indicator parity table (50/50) | Other features → `tv-functions-skill.md` §3 |
210
- | `demo/DESIGN.md` | Demo app design system | Library UX spec → `design-astroneum.md` |
211
- | `demo/PRODUCT.md` | Product framing | Design system → `demo/DESIGN.md` |
212
-
213
- - **Root**: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `LICENSE` (MIT), `INDICATOR_COMPARISON.md`.
214
- - **`.github/workflows/`**: `auto-version-bump.yml`, `benchmark.yml`, `npm-publish.yml`.
215
-
216
- ## 10. Maintenance policy
217
-
218
- This file is the source of truth for *where things live* in the deployed Astroneum project. Update it whenever any of the following change:
219
-
220
- - file/dir added / removed / renamed under `src/`, `demo/src/`, `docs/`, `.github/`
221
- - new / renamed export in `package.json` `exports`, or entry in `tsup.config.ts`
222
- - new / changed PM2 process, port, or nginx route
223
- - version bump in `package.json`
224
- - new dependency that changes the public surface
225
- - new locale / widget / component / engine module / extension tool
226
- - build/tooling config edit (`tsup.config.ts`, `tsconfig.json`, `next.config.ts`, `ecosystem.config.cjs`, `.size-limit.json`, `eslint.config.js`)
227
- - docs / meta file added or removed
228
-
229
- **Detection model**: the assistant is not always running, so updates happen on invocation — when you ping with a change (or "refresh structure"), re-scan the live tree and patch this file, then append a dated entry to the changelog below. A consistency check (ports, PM2 status, exports vs. entries vs. `dist/` files) runs each refresh.
230
-
231
- **Apply**: docs-only edit, no `pnpm build` / `pm2 restart` needed (`docs/*.md` is not served by the demo app).
232
-
233
- ## 12. Change log
234
-
235
- - **2026-08-29** — Added the supported `@tony01/astroneum/headless` package entry, explicit optional built-in registration, validated host-owned bar replacement/update APIs, idempotent multi-instance lifecycle registry, SSR/package isolation tests, Chromium lifecycle smoke, and a dedicated size budget. Engine-level keyboard shortcuts moved out of the rendering core; the React host hook remains their owner.
236
- - **2026-08-29** — Hardened the headless consumer boundary with React-independent typed study plugins, 16-output study/overlay browser coverage, bounded viewport capture/restore, loader and animation teardown guards, and GPU-inclusive screenshot compositing with browser pixel coverage.
237
- - **2026-07-13** — Watchlist implementation and right-rail placement sync. Documented shipped `WatchlistManager` configuration/live-quote APIs, `Datafeed.getQuotes?`, Binance/Bitget/OKX snapshots, `watchlist.test.ts`, the 3-sub-tab watchlist panel, and the persistent 52px strip on the viewport's outer-right edge.
238
- - **2026-07-12** — Watchlist parity spec. `WatchlistPanel` documented as 3-sub-tab container (Watchlist/Details/News) — Details+News folded from sidebar rail tabs into the panel. `watchlist` widget entry updated with spec'd `WatchlistManager` extensions (`moveSymbol`/`setSort`/`setColumns`/`setColor`/`updateQuotes`/`addSymbolFromInfo`) and `Datafeed.getQuotes?` optional polling method. `components/panels/` description updated. No structural change yet — spec only.
239
- - **2026-07-11 (b)** — Synced DrawingBar Batch A and shell rail cleanup docs. `DrawingBar` is now the sole left rail; dead demo `term-rail`/`RailContent` removed. Added cursor submenu, measure, zoom, keep-drawing toggle, Ctrl+Alt+H hide-all, icon sizing fixes, and new draw i18n keys.
240
- - **2026-07-12 (b)** ??? Forecasting group + popup clipping fix. 12 new drawing overlays in `src/extension/`. New `forecasting` group in `drawing-bar` with 3 section headers. 13 new SVG icons, 15 new i18n keys. Fixed popup clipping: `demo/terminal.css` overflow moved to `@media(max-height:620px)`. Extension count 20 to 32.
241
- - **2026-07-12** — Dock/rail geometry pass. `TerminalShell` uses explicit chart/dock CSS Grid rows; the real library `DrawingBar` extends through the dock height while the dock is inset 52px to its right. The rail scrolls internally when its tools exceed a short viewport. Dock maximize is a fixed overlay and leaves chart/rail geometry unchanged.
242
- - **2026-07-11** — Added TV-mirror workstream ledger, deterministic `src/strategy/` backtest core, bounded strategy script contract, terminal curtain/split-view layer, and sample Strategy Tester report.
243
- - **2026-07-12** — Wired `PineEditorPanel` bounded strategy compilation through `ChartTerminal` and `AstroneumHandle.getDataList()` to `StrategyTesterPanel`. `DockContent` now owns persistent report tabs, report actions, overflow, resize, and maximize behavior.
244
- - **2026-07-07** — Initial map generated from live `/opt/astroneum` snapshot: src/ (12 subdirs), demo/ Next.js app, build/tooling, nginx+PM2 topology, docs/meta. Noted: no `.git` on server; 3 overlapping nginx server blocks in `sites-enabled/`.
245
- - **2026-07-07 (b)** — `src/widget/alert-modal` rewritten: now ships full Notifications UX (Webhook URL with SSRF guard + status writeback, in-app, toast, email, plain-text email, sound title/duration, notification schedule, message template, expiration, trigger frequency) using library `Modal`/`Input`/`Checkbox` primitives + `--astroneum-*` tokens. New i18n keys in `en-US.json` + `zh-CN.json` (other 16 locales fall back to en-US). Engine (`AlertManager`) + server relay (`demo/src/app/api/alerts/{webhook,email}/route.ts`) were already capable — this change exposes them in the chart-mounted widget. Also fixed `.alert-section-label` No-Eyebrow Rule violation (was `text-transform: uppercase`). design-astroneum.md section 12 updated.