Skip to content

feat(trading-signals-vocs): add Vocs documentation site with interactive demos and backtesting - #1318

Open
bennycode wants to merge 2 commits into
mainfrom
vocs-docs-site
Open

feat(trading-signals-vocs): add Vocs documentation site with interactive demos and backtesting#1318
bennycode wants to merge 2 commits into
mainfrom
vocs-docs-site

Conversation

@bennycode

Copy link
Copy Markdown
Owner

Part of #1288.

This adds a new trading-signals-vocs package: a documentation site built on Vocs 2 (the framework behind the XMTP docs referenced in the ticket), with full feature parity to the current Next.js site plus docs-native extras. It runs alongside trading-signals-docs for now — swapping the deployment is a follow-up.

What's in the site

  • 127 indicator pages across trend, momentum, volatility, and volume — generated from the existing demo registry (npm run generate). Each page has a live Highcharts demo (dataset pills incl. custom candle JSON upload, price chart, collapsible sample values) and a Twoslash-checked usage snippet: class name and constructor args are extracted from each demo's createIndicator, and a wrong snippet fails the build.
  • Utility function playgrounds and the full in-browser backtester (all strategies, protection modal, config reference, buy-and-hold baseline) on a full-width page.
  • Welcome page with a mermaid architecture diagram and package overview cards.
  • Hand-written indicator intros live in src/intros/<category>/<id>.md and survive regeneration (RMI has one as an example).
  • Free extras from Vocs: full-text search, dark mode, hover type popups from the local trading-signals build, llms.txt/llms-full.txt, per-page "Copy for AI".

Engineering notes

  • @typedtrader/exchange/schemas subpath (first commit): CandleSchema/CandleBaseSchema moved to a zod-only module so browser bundles can validate uploaded candles without dragging broker code (Node built-ins) into the client graph. The barrel re-exports everything, so existing consumers are unaffected — exchange tests, dependent typechecks, and knip are green.
  • Node built-in shims: the Vocs CLI passes configFile: false, so scripts/site.ts wraps the same Vite invocation with a small plugin that shims node:events/node:crypto/node:assert/node:util in the client environment only. That is what lets trading-strategies and AlpacaBrokerMock run the backtester in the browser.
  • Twoslash vs TypeScript 7: the repo's TS 7 has no JS compiler API and ships no lib.*.d.ts, so the package pins a local typescript@^5.9 and points Twoslash at its lib directory in vocs.config.ts.
  • waku pinned to 1.0.0-beta.6 via a root override: beta.9 satisfies vocs' peer range but breaks its router at runtime (blank pages).

Verification

Built statically (267 files) and clicked through in Chrome in both themes: indicator demos incl. custom renders (MACD, QQE, Ichimoku), candle JSON upload, and a full backtest run (buy-and-hold on Synthetic Uptrend, +32.49% ROI with baseline comparison). oxlint, tsc, and knip are green across the repo.

Not ported yet (intentionally): Playwright e2e specs and deployment wiring — those belong to the actual site swap.

CandleSchema and CandleBaseSchema move from Broker.ts into src/schemas.ts,
which only imports zod. The new @typedtrader/exchange/schemas subpath lets
browser bundles validate candles without pulling in broker code that relies
on Node.js built-ins. Broker.ts re-exports everything, so the package barrel
stays unchanged for existing consumers.
…ive demos and backtesting

New docs site (part of #1288) built on Vocs 2 with interactive MDX:

- 127 generated indicator pages across trend, momentum, volatility, and
  volume, each with a live Highcharts demo (dataset pills incl. candle JSON
  upload, price chart, collapsible sample values) and a Twoslash-checked
  usage snippet derived from the demo registry
- utility function playgrounds, a full in-browser backtester (strategies,
  protection modal, buy-and-hold baseline), and a welcome page with a
  mermaid architecture diagram and package overview cards
- pages and sidebar are generated via npm run generate; hand-written intros
  in src/intros/<category>/<id>.md survive regeneration
- scripts/site.ts wraps vite with the vocs plugin to shim Node.js built-ins
  (events, crypto, assert, util) for the client bundle, which lets
  trading-strategies and the exchange broker mocks run in the browser
- Twoslash needs a package-local TypeScript 5 (the repo's TS 7 has no JS
  compiler API); waku is pinned to 1.0.0-beta.6 because beta.9 breaks the
  vocs router
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant