Qt chart guide
==============

The Qt chart is Piker's keyboard-first realtime market view.  Follow the
`project README <../../README.rst>`_, include the UI group, then launch an FQME::

    uv sync --group uis
    uv run piker -l info chart btcusdt.spot.binance

Use a market supported by your provider; a name without its provider suffix is
rejected.  This is not an offline demo: launch may contact provider services
and needs a Qt display.  Put root options before ``chart``; see
`piker/cli/README.rst <../cli/README.rst>`_.

Daemon lifetime
---------------

The chart looks for ``pikerd`` and starts a supervisor for its session if none
is available.  To retain service state across chart restarts, run
``uv run pikerd`` separately first.  That daemon has its own lifetime; stop it
in its terminal.

Keyboard journeys
-----------------

Keep focus on the chart or search pane whose action you want:

* Search: press ``Ctrl-L`` (``L`` for "list" symbols), type, move with
  ``Ctrl-J``/``Ctrl-K`` (or ``Ctrl-Down``/``Ctrl-Up``), then ``Enter``.
  ``Ctrl-C`` or ``Ctrl-Space`` returns focus to the chart.
* Chart: use the wheel to zoom and press ``R`` to restore the default view.
  ``Ctrl-I`` and ``Ctrl-O`` provide keyboard zoom in and out.
* Gaps: press ``Ctrl-G`` on the focused realtime or history chart to toggle
  chart-local OHLC gap markers for that pane and timeframe.
* Orders: hold ``F`` ("fill") for buy, ``D`` ("dump") for sell or ``A`` for
  an alert to stage at the cursor.  Buy/sell default to dark; add ``S`` or
  ``Ctrl`` for live.  A left-click submits.  ``C`` or ``Delete`` cancels under
  the cursor; quick ``cc`` ("complete clear") asks to cancel all orders.

These are real controls.  Confirm the mode label, account and paper/live setup;
a live account can send a real order.

Closing safely
--------------

Closing the main window saves geometry and sends ``SIGINT`` to the chart process
so its async runtime can unwind.  Do not use ``MainWindow.close()`` as generic
cleanup inside another app or test runner: the signal targets the whole process.
The full in-process test tier therefore needs a dedicated shutdown seam.

Testing contract
----------------

The intended default automated gate is layered and deterministic:

* Drive real PyQt6/PyQtGraph objects with real Qt key and mouse events through
  production event filters.
* Use synthetic market data and deterministic feed, search, EMS and service
  boundaries; assert visible state, scene ownership and clean teardown.
* Keep screenshots as failure artifacts, not pixel or visual goldens.
* Keep live brokers, credentials, network feeds and compositor qualification
  out of the default gate.

Current `gap tests <../../tests/test_gap_overlays.py>`_ send a real ``QKeyEvent``
through ``Ctrl-G`` and use real graphics scenes.  The actor case stubs rendering,
so this is integration evidence, not full chart E2E.  Intended tiers and close
work live in the `pytest-qt chart plan
<../../plans/opencode/pytest-qt-chart-ui-e2e.md>`_.
