Example display views (boot seed)
=================================

Fresh boot seeds display **templates** from
``agency-django/src/agency/fixtures/example_display_views.json``. They are
iframe HTML/CSS/JS Views (not Agency UI schema windows). Boot is **create-only
by name** — existing rows are not overwritten.

Catalog
-------

.. list-table::
   :header-rows: 1
   :widths: 22 34 44

   * - Name (DB)
     - Namespace
     - Demonstrates
   * - Counter demo
     - ``display.example.counter``
     - Shared numeric property; increment from the kiosk
   * - YouTube video
     - ``display.example.youtube``
     - Embed driven by ``video_id``
   * - Media image
     - ``display.example.media_image``
     - Full-bleed ``/media`` image from scope ``image_url`` (kiosk)
   * - Media picker
     - ``display.example.media_picker``
     - Photo library explorer; click a thumb to ``set`` ``image_url``
   * - Clock
     - ``display.example.clock``
     - Analog + digital kiosk clock; ``timezone`` (IANA, default Europe/Madrid)
   * - Clock + photo
     - ``display.example.clock_photo``
     - Composite: ``<agency-include>`` wraps Media image + Clock

Media image + Media picker (nabla-link)
---------------------------------------

Both templates share **Example · Media image scope** and the string property
``image_url`` (``writable_by_display``). Assign them to **different Displays**
on that **same scope**:

1. Open **Displays**. Create two screens if needed (kiosk + control).
2. Kiosk: **View** tab → **Media image** (check), **Properties** →
   **Example · Media image scope**, **Save**.
3. Control: **View** → **Media picker**, same scope, **Save**.
4. Put at least one file in **Photos** (upload or generate).
5. On the picker, click a thumb. Every kiosk showing **Media image** on that
   scope updates without reload.

The picker calls ``GET /api/photo/`` from the iframe (same origin, session
cookie). A dedicated TV with only a display token cannot list the user library
— open the picker as a logged-in preview, or on a control tablet signed into
Agency. The billboard kiosk can stay token-only; it only **reads**
``image_url``.

Empty ``image_url`` shows a placeholder on the billboard. Values are stored as
a path (``/media/uploads/…``) so they resolve on the same host.

Agent tools
-----------

Veronica (and any Agent given ``tools.display.*``) operates the same catalog
without talking to Channels:

* ``inspect_displays`` — screens, views, scopes (``protected`` + ``includes``)
* ``commission_display_view`` — secretary: name + prompt → ``display.view.*``, waits for Viewwright
* ``assign_display`` / ``set_display_property`` — launch a View on **one named** screen; change the slide
* ``assign_displays`` — same View + **named** scope on several named screens.
  Refuses ``*``, ``all``, empty lists, and any protected display. Scope is required.
* ``wait_for_display_action`` — persist a Mission wait until that kiosk
  ``sendAction``s (Counter ``+`` emits ``counter.increment``). No worker sleep.
* ``create_display_view`` / ``update_display_view`` / ``create_display_scope`` — specialists write HTML
* ``import_display_image`` / ``show_image_on_display`` — download or Photos → **one named** kiosk.
  Wikimedia ``File:`` / ``Archivo:`` article URLs are rewritten to the real file;
  HTML is never saved as ``.jpg``.

Prefer shipped templates. New HTML: Veronica commissions, she does not write markup
and she does not patch every kiosk. If the operator did not name a screen, ask or
commission a new view. Padlock (**Protect**) on a Display or View blocks agent
assign / ``show_image_on_display`` / template edits until you unlock it.

Nested templates: put ``<agency-include namespace="display.example.clock"></agency-include>``
in a parent View. The runtime expands it to a nested iframe (Clock + photo is the
shipped example). Changing the picture is a property write on the shared scope, not a new View.
``open_window`` accepts ``displays`` and ``views``.

Kiosk and preview runtimes reconnect after an ASGI/nginx bounce: exponential
backoff on ``/channel/display/``, HTTP snapshot rehydrate, and a 25s heartbeat.
Leave the kiosk tab open — it does not need a full page reload once the stack is up.

Adding examples
---------------

Append to the fixture with a unique **name**, ``display.example.<slug>``
namespace, and a stable ``pk``. Shared scopes reuse the same scope ``name`` so
``_ensure_scope`` stays idempotent. String properties must set
``value_type: "string"`` (the loader defaults to number).