# GEX Levels for Bookmap — 0.1.2 beta

Released 20 October 2026. Fixes a hover exception when Bookmap enters empty
heatmap space: event scores now stay in the API's 0–10000 range, with zero for
unclaimed events. Missing or disposed maps do not claim mouse input.

Native Java add-on. Built against the installed Bookmap API; Java 17 bytecode,
tested on Bookmap's bundled Java 21. It is not a Chrome extension and does not
contain Bookmap libraries, vendor credentials, a market-data feed or trading code.

## Install

1. In Bookmap, open **Settings → Configure add-ons**, choose **Add**, and select
   `gex-levels-bookmap-0.1.2.jar`. Menu wording may vary by Bookmap version.
2. Enable **GEX Levels — Map & Context 0.1.2** on a supported instrument.
3. In **Connection & map**, enter your existing personal **GEX Indicator** key.
   The key is kept in memory only; enter it again after restarting Bookmap.
4. Choose map/source/expirations, click **Apply all settings**, then connect.
   A live Bookmap chart is required. Do not share the key or a screenshot of it.
5. Compare the symbol, options source, basis, expirations and capture timestamp
   with the GEX website. A different selection can legitimately draw different levels.

Bookmap must allow custom Java add-ons, and your own provider must supply the chart.
GEX does not enable SPX/NDX charts where your Bookmap data provider lacks them.

## Included

- Overlay on the heatmap: walls, gamma/DEX zero levels, flip, max pain, OI walls,
  Focus and cluster/battle zones where supplied by the server.
- The six IV zones use the same served-premium formula as Chrome, with expected
  move and IV walls. Missing inputs stay absent.
- Optional vanna/charm/vega, session references, server VWAP bands and converted
  NDX companion levels when supplied.
- Compact context panel and nearby per-strike GEX table; layer toggles, font,
  opacity, line width and strike-count settings per instrument.
- Live or confirmed opening capture, ES SPY/SPX source, basis selection,
  default/0DTE/specific/multiple expiration settings. Explicit scoped books do
  not promise all legacy families. No live map is relabelled as a missing open.
- Local proximity sound from live Bookmap trades, tick distance and per-level
  cooldown. No orders, account access, position changes or external messages.
- Fixed HTTPS backend, personal licensed session, conditional snapshot reads,
  stale/wrong-symbol guards, response-size limit and background polling.

Symbol catalog is generated from the backend list at build time; supported futures
aliases include NQ/MNQ, ES/MES, GC/MGC and SI/SIL. Levels arrive in chart price
units, with no second ETF conversion. Support in the catalog is not a guarantee
of current provider coverage or of a tradable Bookmap symbol.

## Deliberate limits / release gate

Version 0.1.1 added independent daily/overnight/VWAP switches, sigma and direction filters,
line/label switches, width, patterns and opacity. Previous workspaces keep their defaults.
Display-only edits rebuild the verified snapshot without resetting its capture timestamp.
Selection changes still invalidate it. Version 0.1.2 retains these settings and fixes hover scoring.

This is a beta base integration, **not full Chrome feature parity**. Research A–E,
interactive chain analysis, level history/replay, native MBO/iceberg detection,
liquidity heatmap analytics, trading and account/position health are not implemented.
The overlay is a current map, begins at its capture time, and is withheld during
historical backfill or when the chart clock is not live. It does not backtest.

Compilation, synthetic API contracts, settings persistence and offscreen rendering
are tested. **Activation in the real Bookmap host, licensed live HTTPS data and
rendering over a real heatmap still require manual validation before stable release.**
Tests do not use customers' credentials or claim to reproduce live order flow.

## Build and verify

From the repository root, with a JDK available:

`node indicators/bookmap-gex-levels/build.mjs`

Optional `BOOKMAP_HOME` overrides the default Windows installation directory.
Outputs: `dist/gex-levels-bookmap-0.1.2.jar`, `.sha256`, and fixture screenshots
under `build/`. Shared native JSON/expiry/decoder sources are relocated at build
time; do not edit other platform clients to change this add-on.

API references: https://github.com/BookmapAPI/DemoStrategies
