better-rtplot 0.5.0__tar.gz → 0.6.0__tar.gz

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-rtplot
-Version: 0.5.0
+Version: 0.6.0
 Summary: 
 License: MIT
 License-File: LICENSE
@@ -132,6 +132,7 @@ A rising line now draws itself in the browser tab.
 - **Remote-friendly.** Sender or plot host can bind. Live Bind /
   Connect buttons retarget without restart.
 - **Config lives with the data.** The sender declares plot layout.
+- **Responsive presentation.** Native phone sizing, essential actions, compact navigation, and explicit semantic styles. See the [presentation guide](docs/presentation.md) and [before/after screenshots](docs/presentation-screenshots/README.md).
 - **Sections and runtime state.** Optional collapsible sections, persistent status controls, and presentation updates that preserve streaming history. See the [section API](docs/sections.md) and [workflow example](examples/06_sections/README.md).
 - **Interactive controls.** Buttons, sliders, dials, displays — polled
   from your loop, no threads, no callbacks.

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/README.md

@@ -107,6 +107,7 @@ A rising line now draws itself in the browser tab.
 - **Remote-friendly.** Sender or plot host can bind. Live Bind /
   Connect buttons retarget without restart.
 - **Config lives with the data.** The sender declares plot layout.
+- **Responsive presentation.** Native phone sizing, essential actions, compact navigation, and explicit semantic styles. See the [presentation guide](docs/presentation.md) and [before/after screenshots](docs/presentation-screenshots/README.md).
 - **Sections and runtime state.** Optional collapsible sections, persistent status controls, and presentation updates that preserve streaming history. See the [section API](docs/sections.md) and [workflow example](examples/06_sections/README.md).
 - **Interactive controls.** Buttons, sliders, dials, displays — polled
   from your loop, no threads, no callbacks.

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "better-rtplot"
-version = "0.5.0"
+version = "0.6.0"
 description = ""
 authors = ["jmontp <jmontp@umich.edu>"]
 license = "MIT"

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/rtplot/client.py

@@ -3,7 +3,7 @@ import numpy as np
 import time
 import uuid
 import warnings
-from .ui_state import META_KEY, declarations, merge_state
+from .ui_state import META_KEY, declarations, merge_state, presentation_requested
 from collections import OrderedDict, namedtuple
 from dataclasses import dataclass, field
 from typing import List, Optional, Tuple, Union
@@ -162,6 +162,7 @@ class Plot:
     xrange: Optional[int] = None
     height: Optional[float] = None
     section: Optional[str] = None
+    min_height: Optional[int] = None
 
     def to_dict(self):
         return _drop_none({
@@ -176,7 +177,7 @@ class Plot:
             "yrange": _range_to_list(self.yrange),
             "xrange": self.xrange,
             "height": self.height,
-            "section": self.section,
+            "section": self.section, "min_height": self.min_height,
         })
 
 
@@ -209,11 +210,12 @@ class Button:
     label: str
     color: Optional[str] = None
     height: Optional[float] = None
+    appearance: Optional[str] = None
 
     def to_dict(self):
         return _drop_none({
             "type": "button", "id": self.id, "label": self.label,
-            "color": self.color, "height": self.height,
+            "color": self.color, "height": self.height, "appearance": self.appearance,
         })
 
 
@@ -267,11 +269,12 @@ class Display:
     label: str
     format: Optional[str] = None
     height: Optional[float] = None
+    appearance: Optional[str] = None
 
     def to_dict(self):
         return _drop_none({
             "type": "display", "id": self.id, "label": self.label,
-            "format": self.format, "height": self.height,
+            "format": self.format, "height": self.height, "appearance": self.appearance,
         })
 
 
@@ -281,11 +284,12 @@ class Text:
     label: str
     value: str = ""
     height: Optional[float] = None
+    appearance: Optional[str] = None
 
     def to_dict(self):
         return _drop_none({
             "type": "text", "id": self.id, "label": self.label,
-            "value": self.value, "height": self.height,
+            "value": self.value, "height": self.height, "appearance": self.appearance,
         })
 
 
@@ -312,12 +316,14 @@ class ControlsRow:
     controls: List[Union[Button, Slider, Dial, Display, Text, TextInput, dict]] = field(default_factory=list)
 
     section: Optional[str] = None
+    title: Optional[str] = None
+    exclusive: Optional[bool] = None
 
     def to_dict(self):
         return _drop_none({"controls": [
             c.to_dict() if hasattr(c, "to_dict") else c
             for c in self.controls
-        ], "section": self.section})
+        ], "section": self.section, "title": self.title, "exclusive": self.exclusive})
 
 
 @dataclass
@@ -328,6 +334,9 @@ class Section:
     collapsible: bool = False
     collapsed: bool = False
     visible: bool = True
+    navigation: str = "primary"
+    density: str = "normal"
+    show_heading: bool = True
 
     def to_dict(self):
         return dict(vars(self))
@@ -337,11 +346,12 @@ class Section:
 class View:
     sections: List[Union[Section, dict]]
     persistent_section: Optional[str] = None
+    essential_controls: Optional[List[str]] = None
 
     def to_dict(self):
         return _drop_none({"sections": [s.to_dict() if hasattr(s, "to_dict") else s
                                         for s in self.sections],
-                           "persistent_section": self.persistent_section})
+                           "persistent_section": self.persistent_section, "essential_controls": self.essential_controls})
 
 
 def local_plot():
@@ -600,6 +610,11 @@ def initialize_plots(plot_descriptions=1, handshake_timeout=2.0, *, view=None, u
                       "confirm support: layout may be flat and disabled states are NOT enforced.",
                       RuntimeWarning, stacklevel=2)
 
+    if presentation_requested(plot_desc_dict, _view) and "presentation_v1" not in _server_capabilities:
+        warnings.warn("Presentation options require rtplot browser server >= 0.6.0. This server did not "
+                      "confirm support; essential placement, groups, and styling may be ignored.",
+                      RuntimeWarning, stacklevel=2)
+
 
 def _send_initialize_with_handshake(cfg, timeout):
     """Publish ``cfg`` and block until the server acks it.

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/rtplot/server_browser.py

@@ -622,6 +622,8 @@ def control_allowed(tab, payload, kind):
     state = {**CONTROL_DEFAULTS, **tab.ui_state.get("controls", {}).get(cid, {})}
     if not state["enabled"] or not state["visible"]:
         return False
+    if cid in tab.view.get("essential_controls", []):
+        return True
     sid = info.get("section")
     section = next((s for s in tab.view.get("sections", []) if s["id"] == sid), {})
     return tab.ui_state.get("sections", {}).get(sid, {}).get("visible", section.get("visible", True))
@@ -649,7 +651,8 @@ def _expand_config(config):
                 plots.append((f"{key}/{i}", child))
             layout.append({"kind": "row", "columns": columns, "plots": indices, "section": entry.get("section")})
         elif "controls" in entry:
-            layout.append({"kind": "controls", "index": len(controls), "section": entry.get("section")})
+            layout.append({"kind": "controls", "index": len(controls), "section": entry.get("section"),
+                           "title": entry.get("title"), "exclusive": entry.get("exclusive", False)})
             controls.append(entry["controls"])
         else:
             layout.append({"kind": "plot", "index": len(plots), "section": entry.get("section")})
@@ -1574,6 +1577,7 @@ _INDEX_HTML = _read_static_asset("index.html")
 for _asset in (
     "ui-view.js",
     "ui-view.css",
+    "presentation.css",
     "uPlot.min.css",
     "uPlot.iife.min.js",
     "katex/katex.min.css",

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/rtplot/static/index.html

@@ -2,6 +2,7 @@
 <html lang="en">
 <head>
 <meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>rtplot</title>
 <link rel="stylesheet" href="/static/uPlot.min.css" />
 <link rel="stylesheet" href="/static/ui-view.css" />
@@ -143,6 +144,7 @@
   .res-stats .rs-tab .rs-hz { color: #2a5db0; font-weight: 500; }
   .res-unavail { font-size: calc(11px * var(--ui-scale)); color: #999; font-style: italic; }
 </style>
+<link rel="stylesheet" href="/static/presentation.css" />
 </head>
 <body>
   <div id="tabbar"></div>
@@ -154,12 +156,13 @@
   </div>
   <div id="header">
     <h1>rtplot</h1>
-    <div id="status" class="green">Rate: -- Hz</div>
-    <div id="zmq-mode">ZMQ: --</div>
     <div id="ws-status">connecting...</div>
     <button id="menu-btn" class="btn" title="Settings" aria-label="Settings">&#9776;</button>
   </div>
   <div id="menu-panel" aria-hidden="true">
+    <h2>Connection and performance</h2>
+    <div id="status" class="green">Rate: -- Hz</div>
+    <div id="zmq-mode">ZMQ: --</div>
     <h2>Settings</h2>
     <div class="menu-row">
       <label for="menu-font">UI font scale</label>
@@ -391,12 +394,25 @@
       }
       menuBtn.addEventListener('click', (e) => {
         e.stopPropagation();
-        menuPanel.classList.toggle('open');
+        const open = menuPanel.classList.toggle('open');
+        const top = Math.max(document.getElementById('header').getBoundingClientRect().bottom,
+                             viewManager?.sticky.getBoundingClientRect().bottom || 0) + 8;
+        menuPanel.style.top = `${top}px`;
+        menuPanel.style.maxHeight = `calc(100dvh - ${top + 8}px)`;
+        menuPanel.setAttribute('aria-hidden', String(!open));
+        menuBtn.setAttribute('aria-expanded', String(open));
+      });
+      document.addEventListener('keydown', e => {
+        if (e.key === 'Escape' && menuPanel.classList.contains('open')) {
+          menuPanel.classList.remove('open'); menuPanel.setAttribute('aria-hidden', 'true');
+          menuBtn.setAttribute('aria-expanded', 'false'); menuBtn.focus();
+        }
       });
       document.addEventListener('click', (e) => {
         if (!menuPanel.classList.contains('open')) return;
         if (menuPanel.contains(e.target) || menuBtn.contains(e.target)) return;
         menuPanel.classList.remove('open');
+        menuPanel.setAttribute('aria-hidden', 'true'); menuBtn.setAttribute('aria-expanded', 'false');
       });
       menuFontInput.addEventListener('input', () => {
         settings.fontScale = Number(menuFontInput.value);
@@ -445,14 +461,22 @@
       let activeLayout = null;
       const controlElements = { displays: {}, displayFormats: {}, displayKinds: {}, sliders: {}, textInputs: {} };
 
+      const presentationTargets = '.section-nav,.section-header,#header,#menu-panel,#tabbar,.uplot';
+      let presentationPointer = false;
+      document.addEventListener('pointerdown', e => {
+        presentationPointer = Boolean(e.target.closest(presentationTargets));
+        setTimeout(() => { presentationPointer = false; }, 0);
+      }, true);
       function sendCtrl(msg) {
         if (msg.type.startsWith('control_')) {
-          if (!viewManager || !viewManager.canInteract(msg.id)) return;
+          if (!viewManager || !viewManager.canInteract(msg.id)) return false;
           msg = {...msg, session: activeLayout?.session, generation: activeLayout?.generation};
         }
         if (socket && socket.readyState === WebSocket.OPEN) {
           socket.send(JSON.stringify(msg));
+          return true;
         }
+        return false;
       }
 
       function parseDisplayFormat(fmt) {
@@ -678,7 +702,7 @@
           const b = document.createElement('button');
           b.className = 'ctrl-btn';
           b.textContent = el.label || el.id;
-          if (el.color != null) {
+          if (el.color != null && (!el.appearance || el.appearance === 'default')) {
             const c = resolveColor(el.color);
             b.style.backgroundColor = c;
             b.style.borderColor = c;
@@ -735,9 +759,16 @@
           if (el.max_length !== undefined && Number.isFinite(Number(el.max_length))) {
             input.maxLength = Number(el.max_length);
           }
-          const commit = () => sendCtrl({ type: 'control_text', id: el.id, value: input.value });
-          input.addEventListener('change', commit);
-          input.addEventListener('blur', commit);
+          let committed = input.value;
+          const commit = () => {
+            if (input.value === committed) return;
+            if (sendCtrl({ type: 'control_text', id: el.id, value: input.value })) committed = input.value;
+          };
+          input.addEventListener('blur', e => {
+            // Moving into presentation UI must preserve a draft without sending it.
+            if (presentationPointer || e.relatedTarget?.closest(presentationTargets)) return;
+            commit();
+          });
           input.addEventListener('keydown', (e) => {
             if (e.key === 'Enter') {
               e.preventDefault();
@@ -765,12 +796,20 @@
         }
       }
 
-      function buildControlRow(row, section) {
+      function buildControlRow(row, section, options={}) {
         const div = document.createElement('div');
         div.className = 'ctrl-row';
+        if (options.title) {
+          const title = document.createElement('h3'); title.className = 'control-group-title'; title.textContent = options.title;
+          div.appendChild(title); div.setAttribute('role', 'group'); div.setAttribute('aria-label', options.title);
+        }
+        if (options.exclusive) div.classList.add('exclusive-group');
         row.forEach(el => {
           const item = buildControlElement(el);
           applyElementSize(item, el);
+          item.dataset.appearance = el.appearance || 'default';
+          if (el.appearance === 'state') item.setAttribute('role', 'status');
+          item.querySelectorAll('input,svg.ctrl-dial').forEach(input => input.setAttribute('aria-label', el.label || el.id));
           div.appendChild(item);
           viewManager.register(el.id, item, section);
         });
@@ -850,11 +889,11 @@
 
         const series = [{}];
         for (let t = 0; t < traceCount; t++) {
-          const dash = (styles[t] === '-') ? [10, 5] : null;
+          const dash = ({'-': [10, 5], dashed: [10, 5], dotted: [2, 4], dashdot: [10, 4, 2, 4]})[styles[t]] || null;
           series.push({
             label: pcfg.names[t],
-            stroke: resolveColor(colors[t]),
-            width: widths[t] || 1,
+            stroke: resolveColor(colors[t] || DEFAULT_COLORS[t % DEFAULT_COLORS.length]),
+            width: (Array.isArray(widths) ? widths[t] : widths) || 1,
             dash: dash || undefined,
             points: { show: false },
             spanGaps: true,
@@ -864,16 +903,15 @@
 
         const baseHeight = rowLayout ? 260 : 320;
         const heightMul = Number(pcfg.height);
-        const plotHeight = (Number.isFinite(heightMul) && heightMul > 0)
-          ? Math.round(baseHeight * heightMul)
-          : baseHeight;
+        const plotHeight = Math.max(pcfg.min_height || 160, (Number.isFinite(heightMul) && heightMul > 0)
+          ? Math.round(baseHeight * heightMul) : baseHeight);
         const wrap = document.createElement('div');
         wrap.className = 'plot-wrap';
         parent.appendChild(wrap);
 
         let plotState = null;
         const opts = {
-          width: Math.max(240, wrap.clientWidth - 16),
+          width: Math.max(120, wrap.clientWidth - 16),
           height: plotHeight,
           title: pcfg.title || '',
           scales: {
@@ -886,6 +924,14 @@
           ],
           series: series,
           legend: { show: true },
+          hooks: { ready: [u => u.root.querySelectorAll('.u-legend .u-series').forEach((tr, i) => {
+            if (!i) return;
+            if (traceCount === 1 && pcfg.title === pcfg.names[0]) tr.querySelector('.u-label').classList.add('sr-only');
+            tr.tabIndex = 0; tr.setAttribute('role', 'button'); tr.setAttribute('aria-pressed', String(u.series[i].show)); tr.setAttribute('aria-label', `Toggle ${pcfg.names[i-1]}`);
+            tr.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); tr.querySelector('.u-label').click(); } });
+          })], setSeries: [u => u.root.querySelectorAll('.u-legend .u-series').forEach((tr, i) => {
+            if (i) tr.setAttribute('aria-pressed', String(u.series[i].show));
+          })] },
           cursor: { drag: { x: false, y: false } },
         };
 
@@ -929,7 +975,7 @@
           plots.forEach(p => {
             const visible = p.wrap.getClientRects().length > 0;
             if (visible) {
-              const width = Math.max(240, p.wrap.clientWidth - 16);
+              const width = Math.max(120, p.wrap.clientWidth - 16);
               if (!p.visible || Math.abs(p.uplot.width - width) > 1) {
                 p.uplot.setSize({width, height: p.height});
                 p.dataDirty = true; p.forceKeepScales = true;
@@ -956,6 +1002,7 @@
         function newRow(count, parent) {
           const row = document.createElement('div'); row.className = 'plot-row';
           row.style.setProperty('--plot-columns', Math.max(1, Math.floor(count)));
+          row.style.setProperty('--compact-columns', Math.max(1, Math.min(2, Math.floor(count))));
           parent.appendChild(row); return row;
         }
         // Trace offsets come ONLY from wire declaration order, never section/DOM order.
@@ -976,9 +1023,10 @@
             entry.plots.forEach(index => buildOnePlot(cfg.plots[index], entry.columns === 1, offsets[index], row));
           } else if (entry.kind === 'controls') {
             implicitRows.delete(parent);
-            parent.appendChild(buildControlRow(controls[entry.index], entry.section));
+            parent.appendChild(buildControlRow(controls[entry.index], entry.section, entry));
           }
         });
+        viewManager.finish();
         applySliderValues(cfg.slider_values); applyTextValues(cfg.text_values); applyDisplayValues(cfg.display_values);
         viewManager.apply(cfg.ui_state || {}, cfg.ui_revision ?? 0);
         renderLatexIn(plotsDiv); applyVisibleSamples(); refreshPresentation(); scheduleRender();
@@ -1140,8 +1188,10 @@
 
           // Stacked labels: name on top, endpoint on a muted subline so
           // users can see at a glance which tab is wired to which device.
-          const labels = document.createElement('div');
-          labels.className = 'tab-labels';
+          const labels = document.createElement('button');
+          labels.className = 'tab-labels tab-select';
+          labels.setAttribute('aria-label', `View ${t.name || id}`);
+          labels.addEventListener('click', e => { e.stopPropagation(); if (id !== activeTab) switchTab(id); });
           const name = document.createElement('span');
           name.className = 'tab-name';
           name.textContent = t.name || id;
@@ -1154,10 +1204,10 @@
           labels.appendChild(ep);
           el.appendChild(labels);
 
-          const reconnect = document.createElement('span');
+          const reconnect = document.createElement('button');
           reconnect.className = 'tab-reconnect';
           reconnect.textContent = '\u21BB';
-          reconnect.title = 'Reconnect';
+          reconnect.title = 'Reconnect'; reconnect.setAttribute('aria-label', `Reconnect ${t.name || id}`);
           reconnect.addEventListener('click', (e) => {
             e.stopPropagation();
             sendCtrl({ type: 'tab_reconnect', id: id });
@@ -1171,17 +1221,17 @@
           el.appendChild(reconnect);
 
           if (id !== 'bind_me') {
-            const ren = document.createElement('span');
+            const ren = document.createElement('button');
             ren.className = 'tab-rename';
             ren.textContent = '\u270E';
-            ren.title = 'Rename';
+            ren.title = 'Rename'; ren.setAttribute('aria-label', `Rename ${t.name || id}`);
             ren.addEventListener('click', (e) => { e.stopPropagation(); beginRename(el, id, t.name); });
             el.appendChild(ren);
 
-            const close = document.createElement('span');
+            const close = document.createElement('button');
             close.className = 'tab-close';
             close.textContent = '\u00D7';
-            close.title = 'Close tab';
+            close.title = 'Close tab'; close.setAttribute('aria-label', `Close ${t.name || id}`);
             close.addEventListener('click', (e) => {
               e.stopPropagation();
               if (confirm(`Close tab "${t.name || id}"?`)) {
@@ -1216,6 +1266,7 @@
         add.className = 'tab-add';
         add.textContent = '+ new device';
         add.title = 'Add a tab that connects to a remote device';
+        add.setAttribute('aria-label', 'Add data source');
         add.addEventListener('click', openCreateForm);
         tabbar.appendChild(add);
 
@@ -1231,10 +1282,15 @@
         input.type = 'text';
         input.className = 'tab-name-input';
         input.value = currentName || '';
-        nameSpan.replaceWith(input);
+        const selector = nameSpan.closest('.tab-select');
+        const original = selector || nameSpan;
+        original.replaceWith(input);
         input.focus();
         input.select();
+        let finished = false;
         const commit = () => {
+          if (finished) return;
+          finished = true;
           const newName = input.value.trim();
           if (newName && newName !== currentName) {
             sendCtrl({ type: 'tab_rename', id: id, name: newName });
@@ -1243,14 +1299,16 @@
             const span = document.createElement('span');
             span.className = 'tab-name';
             span.textContent = currentName || '';
-            input.replaceWith(span);
+            if (selector) { nameSpan.textContent = currentName || ''; input.replaceWith(selector); } else input.replaceWith(span);
           }
         };
         const cancel = () => {
+          if (finished) return;
+          finished = true;
           const span = document.createElement('span');
           span.className = 'tab-name';
           span.textContent = currentName || '';
-          input.replaceWith(span);
+          if (selector) { nameSpan.textContent = currentName || ''; input.replaceWith(selector); } else input.replaceWith(span);
         };
         input.addEventListener('keydown', (e) => {
           if (e.key === 'Enter') { e.preventDefault(); commit(); }
@@ -1339,13 +1397,13 @@
         const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
         socket = new WebSocket(proto + '//' + location.host + '/ws');
         socket.binaryType = 'arraybuffer';
-        socket.onopen = () => { wsStatus.textContent = 'connected'; };
+        socket.onopen = () => { wsStatus.textContent = 'Server connected'; wsStatus.dataset.health = 'connected'; };
         socket.onclose = () => {
-          wsStatus.textContent = 'disconnected, retrying...';
+          wsStatus.textContent = 'Reconnecting…'; wsStatus.dataset.health = 'disconnected';
           if (viewManager) viewManager.connection(false);
           setTimeout(connect, 1000);
         };
-        socket.onerror = () => { wsStatus.textContent = 'error'; };
+        socket.onerror = () => { wsStatus.textContent = 'Connection error'; wsStatus.dataset.health = 'disconnected'; };
         socket.onmessage = (ev) => {
           if (typeof ev.data === 'string') {
             let msg;

better_rtplot-0.6.0/rtplot/static/presentation.css

@@ -0,0 +1,168 @@
+/* Responsive presentation. No element is duplicated across breakpoints. */
+:root { --ctrl-unit-h: 44px; --persistent-budget: 144px; --presentation-offset: 120px; }
+* { box-sizing: border-box; }
+html { scroll-padding-top: var(--presentation-offset); }
+body { min-width: 0; }
+button, input, select, summary, [role=button], .section-nav a { min-width: 44px; min-height: 44px; }
+button, input, select, textarea { font: inherit; }
+:where(button,input,select,textarea,summary,a,[tabindex]):focus-visible { outline: 3px solid #185f9f; outline-offset: 2px; }
+:where(button,input,select,textarea,summary,a,[tabindex]) { scroll-margin-top: var(--presentation-offset); scroll-margin-bottom: 12px; }
+#header { min-height: 48px; gap: 8px; padding: 2px 12px; }
+#header h1 { font-size: 17px; }
+#ws-status { font-size: 13px; color: #35485a; overflow-wrap: anywhere; }
+#menu-btn { width: 44px; height: 44px; margin: 0; flex: 0 0 44px; }
+#menu-panel { max-width: calc(100vw - 16px); min-width: 0; width: 340px; max-height: calc(100dvh - 64px); overflow-y: auto; top: 52px; right: 8px; padding: 12px; }
+#menu-panel #status, #menu-panel #zmq-mode { margin-bottom: 8px; overflow-wrap: anywhere; }
+#menu-panel .menu-ctrl { min-width: 0; }
+#menu-panel input[type=range] { min-width: 44px; width: 100%; }
+#menu-panel input[type=number] { font-size: 16px; }
+#menu-panel .menu-hint, #menu-panel label, #menu-panel .menu-reset { color: #465767; font-size: 13px; }
+#tabbar { max-width: 100%; padding-top: 0; }
+.tab { min-height: 44px; padding: 0 8px; gap: 4px; }
+.tab .tab-endpoint { display: none; }
+.tab .tab-reconnect, .tab .tab-rename, .tab .tab-close { opacity: 1; border: 0; background: transparent; font-size: 16px; color: #405569; padding: 0; flex: 0 0 44px; }
+.tab .tab-name { max-width: min(260px, 55vw); }
+#tab-create.open { flex-wrap: wrap; max-width: 100%; }
+#tab-create input { max-width: 100%; min-width: 0; font-size: 16px; }
+#plots { padding: 8px 12px 24px; min-width: 0; }
+.plot-row { grid-template-columns: repeat(var(--plot-columns, 1), minmax(0, 1fr)); overflow: visible; }
+.plot-wrap { box-sizing: content-box; }
+.uplot { max-width: 100%; }
+.uplot .u-title { white-space: normal; overflow-wrap: anywhere; font-size: 17px; }
+.uplot .u-legend { display: block; white-space: normal; padding: 4px 0; font-size: 13px; }
+.uplot .u-legend tbody { display: flex; justify-content: center; flex-wrap: wrap; gap: 2px 8px; }
+.uplot .u-legend .u-series { display: inline-flex; align-items: center; min-height: 44px; max-width: 100%; margin: 0; }
+.uplot .u-legend .u-label { white-space: normal; overflow-wrap: anywhere; max-width: 180px; }
+.uplot .u-legend .u-value { overflow-wrap: anywhere; }
+.ui-sticky { overflow: visible; max-height: none; background: #fafafa; }
+.essential-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 12px; padding: 4px 0; min-width: 0; border-bottom: 1px solid #ccd5de; }
+.essential-controls .ctrl-item { flex: 0 1 auto; min-width: 0; margin: 0; }
+.essential-controls .ctrl-text { flex: 1 1 150px; }
+.essential-controls .ctrl-text label { font-size: 12px; }
+.essential-controls .ctrl-textval { padding: 0; min-width: 0; }
+.persistent-overflow { max-height: max(44px, calc(var(--persistent-budget) - 52px - var(--essential-height, 0px) - var(--source-height, 0px))); overflow-y: auto; overscroll-behavior: contain; }
+.ui-source-status { padding: 4px 8px; font-size: 13px; color: #78260e; }
+.section-nav { gap: 4px; padding: 0; align-items: flex-start; }
+.section-nav a, .section-more summary { display: inline-flex; align-items: center; gap: 6px; font-size: 14px; line-height: 1.2; padding: 6px 10px; color: #174f80; border: 0; border-radius: 4px; background: #eaf0f6; }
+.section-nav a:hover, .section-more summary:hover { background: #dce8f3; }
+.section-more summary { cursor: pointer; }
+.section-more summary::after { content: ' ▾'; }
+.section-more[open] summary::after { content: ' ▴'; }
+.secondary-links { display: flex; flex-wrap: wrap; gap: 4px; padding-top: 4px; }
+.nav-status { color: #435b6e; font-size: 12px; }
+.section-nav [data-status=warning] .nav-status, .section-nav [data-status=error] .nav-status { color: #923616; }
+.section-header h2 { font-size: 17px; line-height: 1.4; }
+.heading-optional { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+.heading-optional:focus-within { position: static; width: auto; height: auto; clip-path: none; }
+.section-description, .section-message { color: #435363; line-height: 1.5; overflow-wrap: anywhere; }
+.view-section[data-density=compact] .ctrl-row { padding: 4px 8px; gap: 6px 10px; }
+.view-section[data-density=compact] .section-body { gap: 6px; }
+.ctrl-row { gap: 10px 12px; padding: 10px; min-width: 0; }
+.control-group-title { flex: 0 0 100%; margin: 0; font-size: 14px; font-weight: 600; color: #35485a; }
+.ctrl-item { min-width: 0; max-width: 100%; flex-wrap: wrap; line-height: 1.4; }
+.ctrl-item.flex { min-width: 0; }
+.ctrl-item label { font-size: 14px; color: #35485a; }
+.ctrl-item input { font-size: 16px; }
+.ctrl-textinput { min-width: 0; max-width: 100%; width: 100%; flex: 1 1 180px; }
+.ctrl-numinput { width: 76px; flex: 0 0 76px; }
+.ctrl-nudgebtn { width: 44px; height: 44px; flex: 0 0 44px; }
+.ctrl-slider { flex-wrap: wrap; }
+.ctrl-slider label { flex-basis: 100%; }
+.ctrl-slider .ctrl-rangeinput { min-width: 80px; flex: 1 1 100px; max-width: 100%; }
+.ctrl-btn { min-height: 44px; font-size: 15px; padding: 8px 14px; white-space: normal; overflow-wrap: anywhere; }
+.ctrl-btn:disabled, .ctrl-nudgebtn:disabled { color: #616b75; background: #eff1f3; border-color: #b6c0c9; cursor: default; }
+.ctrl-val, .ctrl-textval { min-width: 0; max-width: 100%; white-space: normal; overflow-wrap: anywhere; }
+.ctrl-textval { font-size: 15px; }
+.ctrl-reason { color: #7d3217; line-height: 1.4; }
+.ctrl-busy, .ctrl-selected { color: #245779; }
+.ctrl-item[data-appearance=help] { flex: 1 1 100%; }
+.ctrl-item[data-appearance=help] .ctrl-textval { background: transparent; color: #465767; border: 0; padding: 0; font-size: 14px; }
+.ctrl-item[data-appearance=state] .ctrl-textval { background: #e9f4ef; color: #175a3d; border: 0; font-weight: 600; }
+.ctrl-item[data-appearance=primary] .ctrl-btn:not(:disabled) { background: #175f9d; border-color: #175f9d; color: white; }
+.ctrl-item[data-appearance=warning] .ctrl-btn:not(:disabled) { background: #fff1c9; border-color: #9d6d00; color: #654200; }
+.ctrl-item[data-appearance=danger] .ctrl-btn:not(:disabled) { background: #a32624; border-color: #a32624; color: white; font-weight: 650; }
+.ctrl-item[data-appearance=choice] .ctrl-btn { border-color: #8195a8; background: #f3f6fa; color: #284862; }
+.exclusive-group { gap: 4px; }
+.exclusive-group .ctrl-item { flex: 0 1 auto; }
+.exclusive-group .ui-selected, .ctrl-item[data-appearance=choice].ui-selected { outline: 0; }
+.exclusive-group .ui-selected .ctrl-btn, .ctrl-item[data-appearance=choice].ui-selected .ctrl-btn { background: #d5e8f8; color: #123e64; border: 2px solid #235d8a; }
+.exclusive-group .ctrl-selected, .ctrl-item[data-appearance=choice] .ctrl-selected { display: none; }
+.exclusive-group .ui-selected .ctrl-btn::before, .ctrl-item[data-appearance=choice].ui-selected .ctrl-btn::before { content: '✓ '; margin-right: 4px; }
+@media (min-width: 640px) and (max-width: 1023px) {
+  .plot-row { grid-template-columns: repeat(var(--compact-columns, 2), minmax(0, 1fr)); }
+  .ctrl-item.flex { flex-basis: 240px; }
+}
+@media (max-width: 639px) {
+  :root { --persistent-budget: 180px; }
+  #plots { padding: 6px 8px 24px; gap: 8px; }
+  #header { padding-inline: 8px; }
+  .plot-row { grid-template-columns: minmax(0, 1fr); }
+  .ctrl-row > .ctrl-item { flex: 1 1 100%; }
+  .exclusive-group > .ctrl-item { flex: 0 1 auto; }
+  .ctrl-slider .ctrl-rangeinput { flex-basis: 100%; }
+  .section-nav a, .section-more summary { font-size: 13px; padding: 6px; }
+  .nav-status { font-size: 11px; }
+  .section-nav a { flex-direction: column; gap: 1px; justify-content: center; }
+  .section-header { gap: 6px; }
+}
+@media (max-height: 480px) and (min-width: 640px) {
+  :root { --persistent-budget: 120px; }
+  #header { min-height: 44px; padding-block: 0; }
+  .essential-controls { padding-block: 2px; }
+}
+/* A quiet, consistent surface keeps live data and intentional actions prominent. */
+:root { color-scheme: light; }
+body { background: #f4f6f8; color: #223348; font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; line-height: 1.45; }
+#header { background: #fff; border-color: #dde4ec; box-shadow: 0 2px 8px #263b5110; }
+#header h1 { color: #123f64; font-weight: 750; letter-spacing: -.5px; }
+#menu-btn { border-color: transparent; border-radius: 8px; color: #36536d; }
+#ws-status { display: flex; align-items: center; gap: 6px; }
+#ws-status::before { content: ''; width: 7px; height: 7px; flex: 0 0 7px; border-radius: 50%; background: #a36b14; }
+#ws-status[data-health=connected]::before { background: #22764e; }
+#ws-status[data-health=disconnected]::before { background: #a32624; }
+#tabbar { background: #e9eef3; border-color: #d6e0e9; }
+.tab, .tab.bind-me { background: transparent; border-color: transparent; border-radius: 0; top: 0; }
+.tab.active, .tab.bind-me.active { background: #fff; color: #174b75; box-shadow: inset 0 -3px #296a9e; border-color: transparent; }
+.tab-add { border: 0; border-radius: 0; color: #40586f; }
+.ui-sticky { background: #f4f6f8; }
+.essential-controls { padding-inline: 8px; background: #fff; border: 1px solid #d9e3ec; border-radius: 9px; box-shadow: 0 2px 8px #253d5510; }
+.essential-controls .ctrl-textval { background: transparent; }
+.section-nav a { background: transparent; }
+.section-more summary { background: #e8eef4; border-radius: 7px; }
+.section-header h2 { color: #263f56; letter-spacing: -.2px; font-weight: 650; }
+.section-header button { background: transparent; border-color: transparent; padding-left: 0; }
+.section-status { color: #426078; }
+.ctrl-row, .plot-wrap { border-color: #dce4ed; border-radius: 10px; box-shadow: 0 1px 3px #1d39530a; }
+.ctrl-btn, .ctrl-textinput, .ctrl-numinput, .ctrl-nudgebtn { border-radius: 7px; }
+.ctrl-textinput, .ctrl-numinput { border-color: #a9bacb; }
+.ctrl-btn { transition: background-color .12s ease, border-color .12s ease; }
+.ctrl-btn:not(:disabled):hover { box-shadow: 0 2px 5px #15395320; }
+.ctrl-item[data-appearance=primary] .ctrl-btn:not(:disabled):hover { background: #124b7d; }
+.ctrl-item[data-appearance=danger] .ctrl-btn:not(:disabled):hover { background: #851e1d; }
+.ctrl-item[data-appearance=warning] .ctrl-btn:not(:disabled):hover { background: #ffe7a3; }
+.ctrl-item[data-appearance=help] .ctrl-textval { line-height: 1.55; }
+.uplot .u-title { color: #2c445b; font-weight: 600; }
+#menu-panel { border-color: #d2dce7; border-radius: 10px; box-shadow: 0 8px 24px #15395322; }
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important; } }
+#menu-panel { top: max(52px, var(--presentation-offset)); max-height: calc(100dvh - max(52px, var(--presentation-offset)) - 8px); }
+.sr-only { position: absolute !important; width: 1px !important; height: 1px !important; padding: 0 !important; margin: -1px !important; overflow: hidden !important; clip-path: inset(50%); white-space: nowrap !important; border: 0 !important; }
+.uplot .u-legend .u-series:first-child { display: none; }
+.ctrl-item label, .control-group-title, .section-header h2 { overflow-wrap: anywhere; max-width: 100%; }
+.ctrl-btn { font-size: max(15px, calc(15px * var(--ui-scale))); }
+.ctrl-item input { font-size: max(16px, calc(16px * var(--ui-scale))); }
+#tabbar { flex-wrap: wrap; overflow: visible; }
+.tab { max-width: 100%; flex-wrap: wrap; }
+.ctrl-item[data-appearance=state] .ctrl-val { background: #e9f4ef; color: #175a3d; border: 0; font-weight: 600; }
+.tab .tab-select { border: 0; background: transparent; padding: 2px 4px; color: inherit; font: inherit; text-align: left; justify-content: center; }
+@media (max-width: 639px) {
+  .tab-add { flex: 0 0 44px; width: 44px; padding: 0; font-size: 0; }
+  .tab-add::after { content: '+'; font-size: 22px; }
+}
+/* The page, not a viewport-height body box, contains the sticky header. */
+body { height: auto; min-height: 100%; }
+.ctrl-item[data-appearance=state] .ctrl-val { background: #eaf2fa; color: #244f74; }
+.uplot .u-series:has(.sr-only) th::after { content: ''; }
+#empty-state, .res-unavail { color: #586979; }
+.ctrl-textinput, .ctrl-numinput, .ctrl-nudgebtn { border-color: #738799; }
+
+@media (max-height: 480px) and (min-width: 640px) { .ui-source-status { padding-block: 2px; font-size: 12px; line-height: 1.2; } }

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/rtplot/static/ui-view.js

@@ -9,28 +9,41 @@
       this.state = {controls: {}, sections: {}}; this.revision = -1;
       this.available = cfg.source_available !== false; this.connected = true;
       this.reason = cfg.source_reason || '';
+      this.essentialIds = new Set(cfg.view?.essential_controls || []);
       this.key = `rtplotSections.v1:${cfg.tab}`;
       try { this.prefs = JSON.parse(sessionStorage.getItem(this.key) || '{}'); } catch (_) { this.prefs = {}; }
       this.sticky = document.createElement('div'); this.sticky.className = 'ui-sticky'; root.appendChild(this.sticky);
       this.banner = document.createElement('div'); this.banner.className = 'ui-source-status';
       this.banner.setAttribute('role', 'status'); this.sticky.appendChild(this.banner);
-      this.nav = document.createElement('nav'); this.nav.className = 'section-nav'; this.nav.setAttribute('aria-label', 'Sections'); this.sticky.appendChild(this.nav);
+      this.nav = document.createElement('nav'); this.nav.className = 'section-nav'; this.nav.setAttribute('aria-label', 'Sections'); root.appendChild(this.nav);
+      this.more = document.createElement('details'); this.more.className = 'section-more';
+      const summary = document.createElement('summary'); summary.textContent = 'More'; this.more.appendChild(summary);
+      this.secondary = document.createElement('div'); this.secondary.className = 'secondary-links'; this.more.appendChild(this.secondary);
+      this.essentials = document.createElement('div'); this.essentials.className = 'essential-controls';
+      this.essentials.setAttribute('role', 'group'); this.essentials.setAttribute('aria-label', 'Essential actions and state');
+      this.sticky.appendChild(this.essentials);
+      this.overflow = document.createElement('div'); this.overflow.className = 'persistent-overflow'; this.sticky.appendChild(this.overflow);
       const view = cfg.view || {};
       (view.sections || []).forEach((s, index) => {
         const node = document.createElement('section'); node.className = 'view-section'; node.dataset.section = s.id;
         node.id = `rtplot-section-${index}`;
+        node.dataset.density = s.density || 'normal';
+        node.setAttribute('aria-label', s.title);
         const header = document.createElement('div'); header.className = 'section-header';
-        const heading = document.createElement('h2');
+        const heading = document.createElement('h2'); heading.tabIndex = -1;
         const toggle = document.createElement(s.collapsible && s.id !== view.persistent_section ? 'button' : 'span');
         toggle.textContent = s.title; heading.appendChild(toggle); header.appendChild(heading); node.appendChild(header);
+        if (s.show_heading === false) header.classList.add('heading-optional');
         if (s.description) { const d = document.createElement('p'); d.className = 'section-description'; d.textContent = s.description; node.appendChild(d); }
         const status = document.createElement('span'); status.className = 'section-status'; header.appendChild(status);
         const message = document.createElement('p'); message.className = 'section-message'; message.setAttribute('role', 'status'); node.appendChild(message);
         const body = document.createElement('div'); body.className = 'section-body'; body.id = `${node.id}-body`; node.appendChild(body);
-        const link = document.createElement('a'); link.textContent = s.title; link.href = `#${node.id}`; this.nav.appendChild(link);
-        const section = {declaration: s, node, body, toggle, link, status, message, collapsed: false};
+        const link = document.createElement('a'); link.textContent = s.title; link.href = `#${node.id}`;
+        const navStatus = document.createElement('span'); navStatus.className = 'nav-status'; link.appendChild(navStatus);
+        (s.navigation === 'secondary' ? this.secondary : this.nav).appendChild(link);
+        const section = {declaration: s, node, body, toggle, link, navStatus, heading, status, message, collapsed: false};
         this.sections.set(s.id, section);
-        if (s.id === view.persistent_section) { node.classList.add('persistent-section'); this.sticky.appendChild(node); }
+        if (s.id === view.persistent_section) { node.classList.add('persistent-section'); this.overflow.appendChild(node); }
         else root.appendChild(node);
         const canCollapse = toggle.tagName === 'BUTTON';
         if (canCollapse) {
@@ -41,19 +54,45 @@
         link.addEventListener('click', e => {
           e.preventDefault(); this.collapse(s.id, false, true);
           // A declaration/runtime-hidden section has no navigation link.
-          this.changed(); requestAnimationFrame(() => node.scrollIntoView({block: 'start'}));
+          this.more.open = false;
+          this.changed(); requestAnimationFrame(() => {
+            if (s.id === view.persistent_section && this.overflow.hidden) {
+              this.essentials.tabIndex = -1; this.essentials.focus({preventScroll: true});
+            } else {
+              heading.focus({preventScroll: true}); node.scrollIntoView({block: 'start'});
+            }
+          });
         });
       });
+      this.nav.appendChild(this.more); this.more.hidden = !this.secondary.children.length;
       this.nav.hidden = !this.sections.size;
       this.refreshAvailability();
       this.observer = new ResizeObserver(() => this.offsets());
       this.observer.observe(this.sticky); this.observer.observe(document.getElementById('header'));
+      this.onFocus = e => {
+        if (!root.contains(e.target) || this.sticky.contains(e.target)) return;
+        const top = document.getElementById('header').getBoundingClientRect().bottom + this.sticky.getBoundingClientRect().height;
+        if (e.target.getBoundingClientRect().top < top) e.target.scrollIntoView({block: 'center'});
+      };
+      root.addEventListener('focusin', this.onFocus);
       this.offsets();
     }
+    finish() {
+      // Move the existing elements once, preserving declared control order.
+      // Resizing and state updates never reparent, clone, or replace them.
+      this.controls.forEach((c, id) => { if (this.essentialIds.has(id)) this.essentials.appendChild(c.item); });
+      this.essentials.hidden = !this.essentials.children.length;
+      this.overflow.querySelectorAll('.ctrl-row').forEach(row => { if (!row.querySelector('.ctrl-item')) row.hidden = true; });
+      this.overflow.hidden = !this.overflow.querySelector('.ctrl-row:not([hidden])');
+      this.refreshAvailability(); this.offsets();
+    }
     offsets() {
       const header = document.getElementById('header').getBoundingClientRect().height;
       this.sticky.style.top = `${header}px`;
       const margin = header + this.sticky.getBoundingClientRect().height + 12;
+      document.documentElement.style.setProperty('--presentation-offset', `${margin}px`);
+      this.sticky.style.setProperty('--source-height', `${this.banner.getBoundingClientRect().height}px`);
+      this.sticky.style.setProperty('--essential-height', `${this.essentials.getBoundingClientRect().height}px`);
       this.sections.forEach(s => { s.node.style.scrollMarginTop = `${margin}px`; });
     }
     parent(section) { return this.sections.get(section)?.body || this.root; }
@@ -78,7 +117,7 @@
       const c = this.controls.get(id); if (!c) return false;
       const v = {...defaults, ...this.state.controls?.[id]};
       const s = this.sections.get(c.section);
-      return this.connected && this.available && v.enabled && v.visible && (!s || (!s.node.hidden && !s.collapsed));
+      return this.connected && this.available && v.enabled && v.visible && (this.essentialIds.has(id) || !s || (!s.node.hidden && !s.collapsed));
     }
     applyControl(id) {
       const c = this.controls.get(id); if (!c) return;
@@ -100,7 +139,10 @@
       const s = this.sections.get(id); if (!s) return;
       const v = {visible: s.declaration.visible, status: 'idle', message: '', ...this.state.sections?.[id]};
       s.node.hidden = !v.visible; s.link.hidden = !v.visible;
+      this.more.hidden = !Array.from(this.secondary.children).some(link => !link.hidden);
       s.status.textContent = statusLabels[v.status] || v.status;
+      s.navStatus.textContent = statusLabels[v.status] || v.status;
+      s.link.dataset.status = v.status;
       s.status.dataset.status = v.status; s.message.textContent = v.message; s.message.hidden = !v.message;
     }
     apply(snapshot, revision) {
@@ -124,7 +166,7 @@
       this.banner.hidden = this.connected && this.available;
       this.banner.textContent = !this.connected ? 'Disconnected from server — application controls unavailable' :
         this.reason || 'Source unavailable — application controls disabled';
-      this.sticky.hidden = !this.sections.size && this.connected && this.available;
+      this.sticky.hidden = !this.sections.size && !this.essentialIds.size && this.connected && this.available;
       this.controls.forEach((_, id) => this.applyControl(id)); this.offsets();
     }
     source(available, reason) {
@@ -132,7 +174,7 @@
       this.available = available; this.reason = reason; this.refreshAvailability();
     }
     connection(connected) { this.connected = connected; this.refreshAvailability(); }
-    destroy() { this.observer.disconnect(); }
+    destroy() { this.observer.disconnect(); this.root.removeEventListener('focusin', this.onFocus); }
   }
   window.RtplotView = RtplotView;
 })();

{better_rtplot-0.5.0 → better_rtplot-0.6.0}/rtplot/ui_state.py

@@ -2,7 +2,7 @@
 from copy import deepcopy
 
 META_KEY = "__rtplot_view__"
-CAPABILITIES = ["sections", "ui_state_v1"]
+CAPABILITIES = ["sections", "ui_state_v1", "presentation_v1"]
 CONTROL_DEFAULTS = {"enabled": True, "visible": True, "busy": False, "selected": False, "reason": ""}
 SECTION_DEFAULTS = {"visible": True, "status": "idle", "message": ""}
 STATUSES = {"idle", "ready", "busy", "complete", "warning", "error"}
@@ -29,13 +29,20 @@ def declarations(config, view=None):
             raise ValueError("Section IDs must be unique non-empty strings")
         ids.add(sid)
         s = {"id": sid, "title": sid, "description": "", "collapsible": False,
-             "collapsed": False, "visible": True, **section}
+             "collapsed": False, "visible": True, "navigation": "primary", "density": "normal",
+             "show_heading": True, **section}
         for key in ("title", "description"):
             if not isinstance(s[key], str):
                 raise ValueError(f"Section {key} must be a string")
         for key in ("collapsible", "collapsed", "visible"):
             if not isinstance(s[key], bool):
                 raise ValueError(f"Section {key} must be boolean")
+        for key, default, allowed in (("navigation", "primary", {"primary", "secondary"}),
+                                      ("density", "normal", {"normal", "compact"})):
+            if s.get(key, default) not in allowed:
+                raise ValueError(f"Invalid section {key}")
+        if type(s.get("show_heading", True)) is not bool:
+            raise ValueError("show_heading must be boolean")
         if not s["collapsible"]:
             s["collapsed"] = False
         normalized.append(s)
@@ -53,14 +60,35 @@ def declarations(config, view=None):
             raise ValueError("The persistent section can contain only control rows")
         if "plots" in row and any(p.get("section") is not None for p in row["plots"]):
             raise ValueError("Assign section on the PlotRow, not its child plots")
+        if row.get("title") is not None and not isinstance(row["title"], str):
+            raise ValueError("Control group title must be a string")
+        if type(row.get("exclusive", False)) is not bool:
+            raise ValueError("Control group exclusive must be boolean")
+        for plot in row.get("plots", [row]):
+            if "min_height" in plot and (type(plot["min_height"]) is not int or plot["min_height"] < 160):
+                raise ValueError("Plot min_height must be an integer >= 160 CSS pixels")
         for control in row.get("controls", []):
             cid = control.get("id")
             if not isinstance(cid, str) or not cid:
                 raise ValueError("Control IDs must be non-empty strings")
             if cid in controls:
                 raise ValueError(f"Duplicate control ID: {cid}")
+            if control.get("appearance", "default") not in {"default", "help", "state", "primary", "choice", "warning", "danger"}:
+                raise ValueError("Unknown control appearance")
+            if row.get("exclusive") and control.get("type") != "button":
+                raise ValueError("Exclusive groups may contain only buttons")
             controls[cid] = {"type": control.get("type"), "section": sid}
-    return ({"sections": normalized, "persistent_section": persistent} if view else {}), controls
+            if row.get("exclusive"):
+                controls[cid]["exclusive_group"] = key
+    essentials = view.get("essential_controls", [])
+    if not isinstance(essentials, list) or any(not isinstance(cid, str) or cid not in controls for cid in essentials):
+        raise ValueError("essential_controls must list existing control IDs")
+    if len(set(essentials)) != len(essentials):
+        raise ValueError("essential_controls must not contain duplicate IDs")
+    result = {"sections": normalized, "persistent_section": persistent} if view else {}
+    if essentials:
+        result["essential_controls"] = essentials
+    return result, controls
 
 
 def merge_state(current, patch, controls, view):
@@ -68,6 +96,19 @@ def merge_state(current, patch, controls, view):
     if not isinstance(patch, dict) or set(patch) - {"controls", "sections"}:
         raise ValueError("UI state must contain only controls and sections maps")
     result = deepcopy(current)
+    selected_groups = {}
+    for cid, values in patch.get("controls", {}).items() if isinstance(patch.get("controls", {}), dict) else []:
+        group = controls.get(cid, {}).get("exclusive_group")
+        if group and isinstance(values, dict) and values.get("selected") is True:
+            if group in selected_groups:
+                raise ValueError("An exclusive group may have only one selected choice")
+            selected_groups[group] = cid
+    for group, selected in selected_groups.items():
+        for cid, info in controls.items():
+            if cid != selected and info.get("exclusive_group") == group:
+                result.setdefault("controls", {}).get(cid, {}).pop("selected", None)
+                if not result["controls"].get(cid):
+                    result["controls"].pop(cid, None)
     section_ids = {s["id"] for s in view.get("sections", [])}
     for group, changes in patch.items():
         if not isinstance(changes, dict):
@@ -100,3 +141,23 @@ def merge_state(current, patch, controls, view):
             else:
                 target.pop(ident, None)
     return result
+
+
+def presentation_requested(config, view):
+    """Whether a layout relies on options introduced in presentation_v1."""
+    if view.get("essential_controls"):
+        return True
+    if any(s.get("navigation", "primary") != "primary" or s.get("density", "normal") != "normal"
+           or not s.get("show_heading", True) for s in view.get("sections", [])):
+        return True
+    for key, row in config.items():
+        if key == META_KEY:
+            continue
+        if row.get("title") and "controls" in row or row.get("exclusive"):
+            return True
+        if any(c.get("appearance", "default") != "default" for c in row.get("controls", [])):
+            return True
+        for plot in row.get("plots", [row]):
+            if plot.get("min_height") or any(style in ("dashed", "dotted", "dashdot") for style in (plot.get("line_style") or [])):
+                return True
+    return False