What's New
==========

Recent changes — since ``v0.3.0``
---------------------------------

Custom fonts: ``Application.register_font`` / ``set_default_font``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Two new methods on ``Application`` let the Python side ship
custom font files to the browser and apply a document-wide
default font.

.. code-block:: python

   app.register_font('Roboto', '/path/to/Roboto-Regular.ttf')
   app.register_font('Roboto', '/path/to/Roboto-Bold.ttf',
                     weight='bold')
   app.set_default_font('Roboto', size=13)

* ``register_font(family, source, *, weight, style)`` -- stores
  the font bytes in an in-memory registry keyed by a monotonic
  id; the built-in HTTP server exposes them at
  ``/_pgwidgets/font/<id>`` with ``Cache-Control: immutable``.
  Accepts paths (``str`` / ``os.PathLike``) or raw ``bytes``.
* ``set_default_font(family, *, size, weight, style)`` --
  writes ``--pg-default-font-{family,size,weight,style}`` CSS
  variables on ``:root`` via a managed ``<style>`` element on
  the JS side.  The base widget stylesheet consumes them with
  safe fallbacks so apps that never opt in see no change in
  rendering.

Both methods broadcast to every connected session immediately
and replay the entire registry to every new / reconnecting
session before ``on_connect`` / ``reconstruct`` runs.  That
guarantees a widget that's reconstructed with
``set_font(family, ...)`` always finds the face already
declared on the JS side, even after a full page reload.

The JS handler normalises descriptive TTF weight names
(``thin``, ``light``, ``medium``, ``semibold``, ``extrabold``,
``black``, ``heavy``, ...) to the numeric CSS values per the
CSS Fonts spec, so a font registry that knows weights by their
metadata name (e.g. Ginga's ``font_asst``) can pass weights
straight through.

The matching sync- and async-backend API are identical; the
async variant schedules sends via
``asyncio.run_coroutine_threadsafe`` so ``register_font`` is
callable from outside the event loop.

See :doc:`sync` / :doc:`async` for the full API description.

Flask multi-process example
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``examples/flask-multi-process`` is a new end-to-end demo of
running pgwidgets-python behind Flask + gunicorn + nginx, with
one OS process per browser session.  Highlights:

* ``Application`` accepts ``ws_sock=`` and a session can be
  pre-warmed in the worker process before the browser opens
  its WebSocket -- the worker spawns, runs the user-app's
  ``build_ui`` against an empty session, and then waits for
  the WS handshake.
* Session-aware routing so a Flask front-end can hand each
  browser tab off to a dedicated worker by session ID.
* Dead-child reaping (``waitpid(WNOHANG)``) to avoid zombie
  worker processes piling up.
* The user app is a Python class (``app.build_ui(session)``),
  so worker pre-warming, multi-tab fanout, and reconstruction
  reuse the same entry point.
* The gunicorn / nginx layer serves the bundled pgwidgets-js
  static assets from the pip-installed package (no separate
  jsdelivr fetch needed).

See ``examples/flask-multi-process/README.md`` for the full
production stack walkthrough.

file_browser: ``col_key`` on row-activated
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``pgwidgets.extras.file_browser`` matches the JS-side
TreeView/TableView ``activated`` callback signature change:
``FileBrowser._on_row_activated`` now receives ``col_key`` as
the 4th argument, so handlers that double-click a file can see
which column they hit.  Existing handlers (3-arg) keep working.

``_resolve_kwargs``: skipped-positional kwargs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The kwarg resolver used by every generated widget method now
allows a caller to skip a positional argument and supply the
next one by keyword.  For example, with a method declared as
``set_color(bg=None, fg=None)``, callers may now write
``label.set_color(fg="red")`` directly instead of
``label.set_color(None, "red")``.  Previously the resolver
would reject the keyword-only form for parameters that
preceded any supplied keyword.

method_types: TreeView colour + cell-selection methods classified as ACTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Internal: the four ``set_*_color`` overrides and the new
``select_cell`` / ``select_cells`` / ``clear_cell_selection``
methods are now ACTION-typed, so the wrapper layer dispatches
each call straight through to the JS side instead of trying to
collapse them into a single ``_state`` slot.  Matters for
reconstruction-replay; rarely matters for application code.

----

Recent changes — since ``v0.2.3``
---------------------------------

Chunked binary transport (both directions)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Session`` gained ``_send_binary_chunked(wid, method, args, data,
chunk_size=512KB, shape=None, dtype=None)`` and a matching
incoming-binary path.  Large payloads automatically use the
chunked transport — :meth:`Image.set_binary_image` (and the
reconstruction replay of binary state) auto-pick chunked above a
1 MiB threshold.  ``Session._handle_file_chunk`` was rewritten as
``_handle_binary_chunk`` to consume the new binary-chunk
envelope: chunks store by ``chunk_index`` (robust to ordering)
and reassemble as ``bytes``.

**Pre-1.0 API break**: drop-end / FileDialog ``activated``
handlers now receive each file's ``data`` field as raw ``bytes``
(was a ``"data:<mime>;base64,…"`` string).  Each file dict now
also carries an ``encoding`` field (currently ``"bytes"``;
reserved for future ``"base64"``).

:class:`pgwidgets.Buffer` for typed-array delivery
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

New :class:`pgwidgets.Buffer` wraps raw bytes with ``shape`` and
``dtype`` metadata.  When passed to a binary-aware method, the
bytes ride the chunked transport and the receiver on the JS side
gets a typed array of the right shape (``Uint8Array``,
``Float32Array``, …) without the per-method casting that used to
be necessary::

   from pgwidgets import Buffer
   pixels = ...  # 2048 * 2048 * 4 bytes
   viewer.load_buffer(
       Buffer(pixels, shape=(2048, 2048, 4), dtype="uint8"),
       [2048, 2048], cache)

Supported dtypes: ``uint8`` / ``uint16`` / ``uint32`` / ``int8``
/ ``int16`` / ``int32`` / ``float32`` / ``float64``.
Construction validates that ``len(data) == prod(shape) *
itemsize``.

``Application(ws_sock=…)`` for race-free port allocation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:class:`Application` accepts an optional pre-bound TCP socket via
``ws_sock=``.  When provided, ``Application`` adopts the socket
directly (hands it to ``websockets.serve(sock=...)``) instead of
binding ``(host, ws_port)`` itself, and reads ``ws_port`` back
from the socket for logging.  The motivation is TOCTOU-free port
allocation: the caller can bind in advance, hand the socket in,
and never release the port between "find" and "use" — no other
process can grab it in the gap.  The existing ``ws_port=`` API
is unchanged.

Flask multi-process demo
~~~~~~~~~~~~~~~~~~~~~~~~

New ``examples/flask-multi-process/`` example: one pgwidgets
``Application`` per visitor, each in its own OS process with its
own WebSocket port.  Demonstrates the new ``ws_sock=`` parameter
(child binds, never releases), idle reaping via a grace timer on
``app.on_disconnect`` that handles the subtle case where
``app.on_connect`` doesn't fire on session-reconnect (the wrapper
also hooks ``session.add_connection``), and serving pgwidgets-js's
static assets from the pip-installed package rather than a CDN.

----

Recent changes — since ``v0.2.1``
---------------------------------

Reliable ``get_size()`` / ``get_position()`` on every visual widget
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The auto-sync layer that backs widget getters has been reworked so
``widget.get_size()`` (and ``get_position()`` where supported)
returns the current layout-determined value for any visual widget,
not just ones that opted into the ``resizable`` / ``moveable``
options.  The binding now installs a *passive* resize listener on
every visual widget — the value is captured into local state for
the getter, but it is **not** pushed to other connected browsers or
replayed on reconstruction.  Explicit ``widget.resize(w, h)`` calls
are still replayed, as is interactive resize on widgets that opted
into active sync.

The user-visible upshot: code that calls ``image.get_size()`` on an
``Image`` placed in a flex container now returns the real pixel
size the browser laid the widget out at, instead of ``None`` or a
stale value.  And widgets like ``Image`` with
``set_expanding(True, True)`` no longer get pinned to pixel
dimensions on reconnect (a regression in earlier auto-sync work).

The same guard now applies in both reconstruction paths
(top-level state replay AND ``_transfer_proxy`` for factory-created
widgets like ``ToolBarAction``), which fixes a "toolbar items
drift farther apart after each reconnect" bug.

``map`` callback survives reconstruction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Python side now forwards ``map`` callbacks during a reconstruct
window instead of suppressing them along with the rest of the
state-replay echoes.  ``map`` is a one-shot lifecycle event tied to
the widget first becoming visually present; missing it on the
Python side meant a user's map handler stayed un-fired until the
window happened to be resized.  Pairs with the JS-side reliability
work for the same callback.

Sensible defaults for more getters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Getters now return useful zero-value defaults before any state has
been set or reported from the browser, instead of ``None``:

- ``get_scroll_position()`` → ``(0.0, 0.0)``
- ``get_scroll_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
  ``ScrollBar``, which uses a single-axis API)
- ``get_thumb_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
  ``ScrollBar``)
- ``get_expanding()`` → ``(False, False)``
- ``get_enabled()`` → ``True``
- ``get_state()`` → ``False``
- ``get_volume()`` → ``1.0`` (HTMLMediaElement convention: 0.0
  muted, 1.0 full).

Configured in ``STATE_KEY_DEFAULTS`` / ``STATE_DEFAULTS`` in
``method_types.py``.

----

Earlier — since ``v0.1.3``
--------------------------

Major changes
~~~~~~~~~~~~~

TreeView / TableView: dict-tree model
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Mirroring the JS-side rewrite, ``TreeView`` and ``TableView`` now
work with hierarchies of dicts keyed by stable string identifiers.
Paths are arrays of those keys and stay valid no matter how the
visible tree is sorted.

.. code-block:: python

   tree = W.TreeView(columns=[
       {"label": "Name", "key": "NAME", "type": "string"},
       {"label": "Type", "key": "TYPE", "type": "string"},
       {"label": "Size", "key": "SIZE", "type": "integer"},
   ], sortable=True)

   tree.set_tree({
       "Documents": {
           "report.pdf": {"TYPE": "PDF",  "SIZE": 2400},
           "notes.txt":  {"TYPE": "Text", "SIZE": 12},
       },
       "Pictures": {
           "photo.jpg": {"TYPE": "JPEG", "SIZE": 3200},
       },
   })

Highlights:

- New column-key-based API: ``set_column_width(col_key)``,
  ``sort_by_column(col_key, ascending)``,
  ``insert_column(column, before=None)``,
  ``delete_column(col_key)``,
  ``set_cell(path, col_key, value)``,
  ``set_column_editable(col_key, tf)``.
- New column types: ``"string"`` / ``"integer"`` / ``"float"`` /
  ``"boolean"`` (renders ✓ when truthy) / ``"icon"``.
  ``halign`` field with sensible per-type defaults.
- New tree methods:

  - ``add_tree(tree, parent=None)`` -- merge a dict-tree under a
    parent path (preserves selection by path).
  - ``update_tree(tree)`` -- replace the tree, preserve selection.
  - ``get_subtree(status='all')`` -- return a connected subset
    (selected / expanded / collapsed nodes plus their descendants
    and ancestors), round-trippable through ``set_tree``.
  - ``clear_selection()`` -- explicit no-arg reset.

- Auto-spanning: a row whose value for a column is missing causes
  the previous present cell to extend across it.  Lets parent rows
  be terse: ``{"NAME": "Documents"}`` (with the rest of the columns
  omitted) renders as a single cell across the row.
- ``TableView.set_data`` accepts a list of dicts (preferred) or a
  list of arrays.

See :doc:`widgets` for the full reference.

Window controls (TopLevel) and shade (MDISubWindow)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``TopLevel`` gains the same window controls that ``MDISubWindow``
has, plus a "shade" (roll up to title bar) state on both.

New ``TopLevel`` options (default ``False`` except ``shadeable``
which defaults ``True``):

- ``minimizable`` -- show minimize button.  Minimized windows
  auto-stack along the bottom of the viewport.
- ``maximizable`` -- show maximize button.  Fills the browser
  viewport (snapshot at click time).
- ``lowerable`` -- show send-to-back button.
- ``shadeable`` -- collapse to title bar in place.  Available from
  the right-click context menu and via double-click on the title
  bar.
- ``icon`` -- title-bar icon (URL or ``data:`` URI).

New methods: ``set_icon(url)``, ``toggle_minimize()``,
``toggle_maximize()``, ``toggle_shade()``,
``set_window_state(state)``, ``get_window_state()``.

New callback ``window-state`` is auto-tracked, so the
minimize/maximize/shade state survives a browser reconnect.

``MDIWidget.add_widget`` accepts ``shadeable`` (default ``True``).

Right-click on the title bar of either widget opens a context menu
with the applicable actions (Raise, Lower, Shade, Minimize,
Maximize, Close).  The menu supports both click-release and
press-drag-release, like a menubar.

Image: binary-frame protocol
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

New method ``Image.set_binary_image(data, format='jpeg')`` sends raw
bytes (``bytes`` / ``bytearray`` / ``memoryview``) via a WebSocket
binary frame, avoiding the ~33% base64 overhead of ``set_image``.
Useful for animation/streaming.  ``format`` is one of ``"jpeg"``,
``"png"``, ``"webp"``, ``"gif"``.  The latest frame is stored in
widget state and replayed on reconnect.

Callbacks base class
^^^^^^^^^^^^^^^^^^^^

New module ``pgwidgets.callbacks`` exposes ``Callbacks``, a small
base class that provides the same callback API (``add_callback``,
``on``, ``make_callback``, ``enable_callback``, ...) as a real
``Widget`` without the widget machinery.  Use it for Python-side
composite/utility classes that need to expose handler registration.

``FileBrowser`` (in ``pgwidgets.extras``) is now a subclass and so
supports both ``add_callback("activated", ...)`` and
``on("activated", ...)`` directly.

See :ref:`callbacks-base`.

Robustness improvements
~~~~~~~~~~~~~~~~~~~~~~~

- ``Session._send`` and ``_send_binary`` no longer hang when the
  asyncio loop refuses a coroutine (loop closed mid-call,
  ``RecursionError`` from a deep callback chain, etc.).  The
  schedule failure is logged, the orphan coroutine is closed, and
  ``_send`` returns ``None`` so the caller continues.
- ``json.dumps`` errors in ``_send`` / ``_push`` are caught and
  logged instead of crashing reconstruction with a non-JSON-
  serialisable widget state.
- After every ``create``, ``Session._next_wid`` is advanced past
  the JS-side ``next_wid`` so subsequent Python allocations skip
  any auto-allocated sub-widget IDs (matching the JS-side
  collision rescue).  This fixes "callback fires on the wrong
  widget" cases where a widget like ``TreeView`` allocates
  internal ``ScrollBar`` widgets in its constructor.

Other notable changes
~~~~~~~~~~~~~~~~~~~~~

- ``ColorDialog`` now exposes ``popup``, ``set_position``,
  ``set_modal``, and the ``move`` / ``close`` callbacks (inherited
  from ``Dialog`` on the JS side).  Its ``popup`` is wired through
  the ``_dialog_popup`` custom method so visibility/position state
  is tracked for reconstruction.
- ``MenuAction`` ``activated`` callback signature simplified.  Old:
  ``handler(widget, text, checked)``.  New: ``handler(widget)`` for
  non-checkable actions; ``handler(widget, checked)`` for checkable
  ones.  *This is a breaking change for any handler that took the
  text arg.*
- ``Widget`` base class now exposes
  ``set_allow_text_selection(tf)``; browser text selection is off
  by default for most widgets (form controls and the cell editor
  in ``TreeView`` always allow selection).
- ``clear()`` on ``TreeView`` / ``TableView`` no longer resets the
  ``columns`` state (it was popping ``_state["columns"]`` even
  though the JS side preserves columns on clear).
- ``FileBrowser`` migrated to the new dict-tree ``TableView`` API
  internally and now subclasses ``Callbacks``.
- ``FixedLayout`` container added (auto-generated from the JS
  definition).  Use ``W.FixedLayout()`` and
  ``layout.add_widget(child, x, y)`` to place children at fixed
  pixel offsets; ``remove(child)`` works as on any other container.