feat: integrate chart storage optimization into orderbook v2.7.218

AGENTS.md

@@ -43,6 +43,7 @@
 | Trading-data, CoinMarketCap-data, auto-refresh, or cross-script validation | docs/userscript-validation.md |
 | Behavioral tests, test lint, affected selection, or source coverage | docs/test-policy.md |
 | Read-only review | skills/userscript-review/SKILL.md |
+| Chart mirror storage and IndexedDB | docs/binance-chart-storage-development.md |
 | Release or publish | skills/userscript-release/SKILL.md |
 | Codex/browser/proxy/helper/connection timeout | global timeout rule; if available, ~/.dotfiles/knowledge/shared/CODEX_TOOL_TIMEOUT_TRIAGE.md |
 

README.md

@@ -53,6 +53,7 @@ This repository is the source of truth and distribution point for the scripts. G
 
 - Infers direction from the current open/close tab.
 - Provides a quantity multiplier panel.
+- Includes chart mirror storage optimization without a separate installation.
 - Handles orderbook display precision, available quantity, current orders, and ladder order boundaries.
 - Designed for manual traders who frequently inspect the orderbook and submit limit orders.
 
@@ -108,6 +109,7 @@ npm run build:binance-userscripts
 
 ## Documentation
 
+- [Binance chart storage optimizer](docs/binance-chart-storage-development.md)
 - [Signal gateway architecture and usage (Chinese)](docs/signal-gateway-architecture.zh-CN.md)
 - [Binance orderbook trade development](docs/binance-orderbook-trade-development.md)
 - [Binance Strategy 29 Bollinger signals and migration](docs/binance-strategy29-bollinger-development.md)

README.zh-CN.md

@@ -51,6 +51,7 @@
 
 - 根据当前开仓/平仓 tab 自动识别操作方向。
 - 支持数量倍率面板，减少重复输入。
+- 内置图表镜像存储优化，无需额外安装脚本。
 - 处理订单簿价格精度、可用数量、当前委托和阶梯挂单相关边界。
 - 适合高频查看盘口、需要快速提交限价单的手动交易场景。
 

docs/binance-chart-storage-development.md

@@ -0,0 +1,99 @@
+# Orderbook Chart Storage Optimization
+
+`src/binance-orderbook-trade/chart-storage/` owns the production implementation. Build
+the existing `scripts/binance-orderbook-trade.user.js` with
+`npm run build:binance-orderbook-trade`. There is no separate install entry.
+The earlier `experiments/binance-chart-storage/` files are historical research
+and independent baselines; production imports none of them.
+
+## Behavior and scope
+
+The module installs before the orderbook business initializer at document-start
+in the page's MAIN_WORLD. It only admits
+top-level Binance perpetual trading routes accepted by the shared route parser,
+including USDT and USDC symbols. Futures home, landing and other subpages receive
+no storage hook or UI. The orderbook retains its own existing frame and SPA
+behavior. Landing-to-trading SPA navigation does not re-run the storage installer;
+only a fresh matching page starts early interception. It never places orders, changes leverage, reads credentials, changes
+the proxy, clears databases or replaces global storage methods.
+
+Only the pinned TradingView module `70940` mirror destination expression changes.
+The complete original factory must match before first execution. Late injection,
+source drift and a missing capture after a 30-second timer retire interception
+and leave native registration intact. Metadata does not guarantee early injection
+on every extension configuration; rejection remains a supported outcome.
+
+Each accepted mirror uses one IndexedDB read/write transaction and compares the
+destination values before writing. Equal JSON trees must retain signed zero,
+property order and dense array structure. Missing keys remain distinct from stored
+null. Ordinary saves, source reads, Basic chart settings and `clear()` retain
+their native implementations. No record cache persists between batches.
+
+Input admission defaults to 512 entries, 4 MiB per batch and 16 pending batches
+with 64 MiB of copied input. Unsupported values, capacity limits, initialization
+or driver/configuration rejection and synchronous transaction-creation failure
+execute the original native expression once, before any optimized transaction
+exists. Native handling may exceed the optimizer's limits; these limits bound
+optimization, not Binance's original work. Shared references, cycles and non-JSON
+input use that native path instead of silently changing their stored meaning.
+
+Within a transaction, unsupported old values and exhausted comparison budgets
+cause direct writes. They do not reject otherwise valid replacements. A genuine
+transaction failure aborts the entire batch and stops future optimization; it
+never replays the failed batch. The original caller still receives the failure
+through its Promise boundary. Subsequent calls resume native handling.
+
+## Lifecycle and diagnostics
+
+`self.__BINANCE_CHART_STORAGE__.snapshot()` returns fixed aggregate counters and
+startup status. `stop()` drains the current instance's accepted work, including
+every member of an early-rejecting native Promise array. Calls arriving during
+drain wait for that finite fence, then run their native expression. After stop,
+native arrays and errors pass through synchronously and statistics freeze.
+The public interface exposes no stored keys, values or storage methods.
+
+`acceptedBatches` counts created optimized transactions. `committedTransactions`
+counts real completion events, while `committedWrites` and `skippedWrites` count
+only committed work. `rejectedBatches` and `nativePassthroughBatches` describe
+native routing before transaction creation, not failed saves. `failedBatches`
+counts failed optimized transactions. The separate native-only experiment's
+`completed` and `dispatches` fields must not be interpreted as commit counters.
+
+Stopping does not close shared connections, undo committed data, drain other tabs
+or guarantee persistence before page destruction. Leaving a supported route
+retires optimization when a retained callback runs; pagehide also requests stop.
+
+## Compatibility limits
+
+The native per-key mirror can partially commit; an optimized destination batch
+commits or aborts as a whole. Its interleaving with native clear and other tabs
+therefore differs. Source reads remain non-atomic, and two databases cannot share
+this transaction. No newest-revision ordering, cross-tab coordination, repair of
+already queued work or universal blank-page recovery is promised. The change
+addresses repeated destination transactions and unchanged writes specifically.
+
+The retained upstream factory is generated from the exact public response and
+verified with its manifest and inverse replacement. To update that source pin,
+first inspect and regenerate the fixture provenance; never broaden the matcher
+to accept an unknown module. The generation command accepts an explicit output:
+
+```sh
+node experiments/binance-chart-storage/generate-mirror-module.js /path/to/verified/TradingView.99bc5074.js src/binance-orderbook-trade/chart-storage/mirror-module.js
+```
+
+## Validation and release
+
+- Runtime unit scenarios execute the real bootstrap and exact native factory.
+- Production writer scenarios use real IndexedDB and the captured localForage,
+  covering original-value semantics, admission, reconnect, abort and drain.
+- Multi-tab scenarios use competing different revisions, native clear, reload
+  and actual transaction events; no fixed sleep determines business completion.
+- The anonymous smoke runner executes the generated install artifact in a fresh
+  Chrome context. Tampermonkey installation requires separate exact installed
+  and loaded-source checks in the user's authorized test tab.
+
+Run the affected Node and browser tests, `npm run lint:tests`, the build/check,
+one passing full `npm test`, and `git diff --check`. Publish through a reviewed
+GitHub PR; verify the main raw artifact before synchronizing Tampermonkey. A
+successful chart and committed test batch do not establish long-running stability
+or prove that every historic white-screen incident had the same cause.