@perspective-dev/viewer 4.5.1 → 5.0.0

package/src/rust/js/plugin.rs

@@ -10,8 +10,12 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+use std::cell::RefCell;
+use std::collections::HashMap;
+
 use perspective_js::JsViewWindow;
 use perspective_js::utils::*;
+use wasm_bindgen::JsCast;
 use wasm_bindgen::prelude::*;
 
 use crate::config::PluginStaticConfig;
@@ -25,6 +29,93 @@ extern "C" {
     #[derive(Clone)]
     pub type JsPerspectiveViewer;
 
+    /// A `<perspective-viewer>` plugin custom element.
+    ///
+    /// # Capability tiers
+    ///
+    /// Only `get_static_config`, `draw`, `save`/`restore` and `delete` are
+    /// REQUIRED. Every other method is optional — detected once per element
+    /// tag ([`PluginCapabilities`], methods live on the class prototype) —
+    /// with a defined host fallback, so a minimal plugin renders correctly
+    /// and each added method buys performance or polish, never correctness:
+    ///
+    /// | method     | host fallback when absent                              |
+    /// |------------|--------------------------------------------------------|
+    /// | `update`   | `draw` — every repaint is a full render (such plugins  |
+    /// |            | must NOT treat `draw` as a state-reset license)        |
+    /// | `resize`   | no-op — CSS reflows the box; next dispatch repaints    |
+    /// | `restyle`  | no-op — the plugin re-reads CSS at its next render     |
+    /// | `clear`    | no-op                                                  |
+    /// | `deselect` | no-op                                                  |
+    /// | `presize`  | held style-override presize (`Renderer` resize paths)  |
+    /// | `render`   | image export reports unsupported                       |
+    ///
+    /// # Call discipline
+    ///
+    /// Plugin implementations assume the host NEVER overlaps calls on the
+    /// same element: each of the rendering methods (`draw`, `update`,
+    /// `render`, `clear`, `resize`) and `delete` must run to completion
+    /// before the next begins. Every call site must therefore hold that
+    /// plugin's per-`Renderer` draw lock, witnessed by
+    /// [`crate::utils::RenderGuard`] — the guard-taking dispatch helpers
+    /// (`Renderer::draw_fresh`/`update_bound`,
+    /// `renderer::activate::activate_plugin`) and the already-locked
+    /// `render_task`/`update_lazy`/`resize`/`restyle_all`/`dispose`
+    /// entrypoints do not compile from an unlocked context. Synchronous
+    /// calls (`restore`, `restyle`, the schema queries) are exempt, though
+    /// `restyle` should ride inside a locked restyle-then-update sequence
+    /// (see `Renderer::restyle_all`).
+    ///
+    /// # Dispatch semantics (`PLUGIN_DRAW_INVARIANT_PLAN.md`, amended
+    /// 2026-07-16)
+    ///
+    /// The host invokes `draw` **iff there is a NEW `View` for this
+    /// plugin** — `bind_view` REBUILT the engine `View`, or a
+    /// freshly-selected plugin element owes its first paint of the bound
+    /// one — so implementations may treat `draw` as "new data shape"
+    /// (reset zoom/scroll/domain state). The witness enforcing this is
+    /// [`crate::session::FreshView`], which only the rebuild and
+    /// first-paint paths mint.
+    ///
+    /// `update` is a repaint of the SAME `View`, invoked iff a
+    /// plugin-visible SOURCE changed — one of exactly six: (1) data
+    /// (`View::on_update`), (2) an adopted placeholder-config delta,
+    /// (3) a genuinely CHANGED `plugin_config`/`columns_config` the host
+    /// just delivered via `restore` (so `update`-after-`restore` is the
+    /// sanctioned delivery pairing), (4) genuinely changed CSS vars just
+    /// applied via `restyle` (`Renderer::restyle_all`, or the fused
+    /// stale-capture restyle immediately preceding a dispatch inside
+    /// `draw_view` — gated by `Renderer::needs_restyle`), (5) a
+    /// render-limits change (warning dismissed), (6) an explicit PUBLIC
+    /// element-API call that reconciled as a no-op
+    /// ([`crate::tasks::RunOrigin::Public`] — the documented
+    /// `viewer.restore({})` refresh affordance). An INTERNAL run that
+    /// changed none of these dispatches nothing.
+    ///
+    /// `resize` is geometry/chrome only, from retained state (and is also
+    /// the activation-chrome nudge — implementations should no-op it
+    /// while hidden).
+    ///
+    /// `restore`/`save` are state transfer, NOT rendering: plugins must
+    /// not render internally from them, and must not call host APIs from
+    /// inside `restore` (a `restore`-triggered `restorePanel` echo is how
+    /// the initial-load double render happened — user gestures may echo,
+    /// host-delivered restores must not). (The built-in `Debug` plugin's
+    /// own `resize()` delegating to its `draw()` is plugin-INTERNAL and
+    /// exempt.)
+    ///
+    /// # Render-callable contract (invariant I5,
+    /// `SESSION_CONFIG_COHERENCE_PLAN.md`)
+    ///
+    /// From inside `draw`/`update`/`render`/`resize`, a plugin may call
+    /// back into its host `<perspective-viewer>` ONLY the per-panel
+    /// snapshot getters — `getViewConfigPanel`, `getTablePanel`,
+    /// `getClientPanel`, `getEditPortPanel` — which answer from the run's
+    /// pinned `RenderContext`, so plugin-visible state always equals the
+    /// snapshot being drawn, never a fresher in-flight commit.
+    /// Lock-acquiring host methods (`savePanel`, `restorePanel`, `flush`,
+    /// `download`/`export`/`copy`, …) DEADLOCK on the non-reentrant draw
+    /// lock if called from a render and are forbidden.
     #[derive(Clone)]
     pub type JsPerspectiveViewerPlugin;
 
@@ -51,24 +142,41 @@ extern "C" {
     #[wasm_bindgen(method, catch, js_name = plugin_config_schema)]
     pub fn _plugin_config_schema(this: &JsPerspectiveViewerPlugin, view_config: &JsValue) -> ApiResult<JsValue>;
 
+    /// STATE TRANSFER, not rendering (dispatch semantics, rule for
+    /// `restore`/`save`): deliver a `plugin_config` + `columns_config`
+    /// snapshot into the plugin. Sync and lock-exempt. The host pairs a
+    /// restore that genuinely CHANGED plugin state with exactly one
+    /// `update` in the same locked run (update source 3) — plugins must
+    /// not render from `restore()` themselves, and must not call host
+    /// APIs from inside it (the echo rule: a plugin-issued `restorePanel`
+    /// re-enters through the PUBLIC surface, indistinguishable from a
+    /// user call — the initial-load double-render bug). Prefer the typed
+    /// [`JsPerspectiveViewerPlugin::restore`] wrapper.
     #[wasm_bindgen(method, js_name=restore, catch)]
     pub fn _restore(this: &JsPerspectiveViewerPlugin, token: &JsValue, columns_config: &JsValue) -> ApiResult<()>;
 
+    /// Free the plugin's resources. Serialized like the rendering methods —
+    /// callers route through the draw lock (`Renderer::dispose`/`delete`
+    /// defer teardown through it; a sync `delete` mid-`draw` violates the
+    /// call discipline).
     #[wasm_bindgen(method)]
     pub fn delete(this: &JsPerspectiveViewerPlugin);
 
-    #[wasm_bindgen(method)]
-    pub fn restyle(
+    #[wasm_bindgen(method, js_name = restyle)]
+    fn _restyle(
         this: &JsPerspectiveViewerPlugin,
     );
 
-    #[wasm_bindgen(method, catch)]
-    pub async fn render(
+    #[wasm_bindgen(method, catch, js_name = render)]
+    async fn _render(
         this: &JsPerspectiveViewerPlugin,
         view: perspective_js::View,
         viewport: Option<JsViewWindow>,
     ) -> ApiResult<web_sys::Blob>;
 
+    /// Full render of a `View` that is NEW to this plugin — dispatched iff
+    /// `bind_view` REBUILT the engine `View`. The only REQUIRED rendering
+    /// method.
     #[wasm_bindgen(method, catch)]
     pub async fn draw(
         this: &JsPerspectiveViewerPlugin,
@@ -78,8 +186,8 @@ extern "C" {
         force: bool
     ) -> ApiResult<()>;
 
-    #[wasm_bindgen(method, catch)]
-    pub async fn update(
+    #[wasm_bindgen(method, catch, js_name = update)]
+    async fn _update(
         this: &JsPerspectiveViewerPlugin,
         view: perspective_js::View,
         column_limit: Option<usize>,
@@ -87,12 +195,17 @@ extern "C" {
         force: bool
     ) -> ApiResult<()>;
 
-    #[wasm_bindgen(method, catch)]
-    pub async fn clear(this: &JsPerspectiveViewerPlugin) -> ApiResult<JsValue>;
+    #[wasm_bindgen(method, catch, js_name = clear)]
+    async fn _clear(this: &JsPerspectiveViewerPlugin) -> ApiResult<JsValue>;
 
-    #[wasm_bindgen(method, catch)]
-    pub async fn resize(this: &JsPerspectiveViewerPlugin) -> ApiResult<JsValue>;
+    #[wasm_bindgen(method, catch, js_name = resize)]
+    async fn _resize(this: &JsPerspectiveViewerPlugin) -> ApiResult<JsValue>;
+
+    #[wasm_bindgen(method, catch, js_name = deselect)]
+    async fn _deselect(this: &JsPerspectiveViewerPlugin) -> ApiResult<()>;
 
+    #[wasm_bindgen(method, catch, js_name = presize)]
+    async fn _presize(this: &JsPerspectiveViewerPlugin, width: f64, height: f64) -> ApiResult<JsValue>;
 }
 
 impl From<JsPluginStaticConfig> for PluginStaticConfig {
@@ -101,6 +214,49 @@ impl From<JsPluginStaticConfig> for PluginStaticConfig {
     }
 }
 
+/// Which OPTIONAL plugin methods a plugin implements (see "Capability
+/// tiers" on [`JsPerspectiveViewerPlugin`]). Detected once per
+/// custom-element tag — methods live on the class prototype, so every
+/// instance of a tag answers identically — and memoized; call sites read
+/// cached flags instead of running per-call `Reflect` probes.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PluginCapabilities {
+    pub draw: bool,
+    pub update: bool,
+    pub resize: bool,
+    pub restyle: bool,
+    pub clear: bool,
+    pub deselect: bool,
+    pub presize: bool,
+    pub render: bool,
+}
+
+thread_local! {
+    static PLUGIN_CAPABILITIES: RefCell<HashMap<String, PluginCapabilities>> =
+        RefCell::new(HashMap::new());
+}
+
+impl PluginCapabilities {
+    fn detect(plugin: &JsPerspectiveViewerPlugin) -> Self {
+        let is_fn = |name: &str| {
+            js_sys::Reflect::get(plugin, &JsValue::from_str(name))
+                .map(|x| x.is_function())
+                .unwrap_or_default()
+        };
+
+        Self {
+            draw: is_fn("draw"),
+            update: is_fn("update"),
+            resize: is_fn("resize"),
+            restyle: is_fn("restyle"),
+            clear: is_fn("clear"),
+            deselect: is_fn("deselect"),
+            presize: is_fn("presize"),
+            render: is_fn("render"),
+        }
+    }
+}
+
 impl JsPerspectiveViewerPlugin {
     /// Read and deserialize the plugin's static config. Should only
     /// be called once per plugin (at registration time); cache the
@@ -118,4 +274,135 @@ impl JsPerspectiveViewerPlugin {
         let columns_config = JsValue::from_serde_ext(&columns_config).unwrap();
         self._restore(token, &columns_config)
     }
+
+    /// This plugin's memoized [`PluginCapabilities`] — the first call for a
+    /// given element tag runs the `Reflect` probes; all later calls (any
+    /// instance of the tag) read the cache.
+    pub fn capabilities(&self) -> PluginCapabilities {
+        let tag = self.unchecked_ref::<web_sys::Element>().tag_name();
+        PLUGIN_CAPABILITIES.with(|cache| {
+            *cache
+                .borrow_mut()
+                .entry(tag)
+                .or_insert_with(|| PluginCapabilities::detect(self))
+        })
+    }
+
+    /// Repaint of the SAME `View` — dispatched iff one of the six
+    /// plugin-visible sources changed (see "Dispatch semantics" on
+    /// [`JsPerspectiveViewerPlugin`]); never defensively. Reaches the
+    /// plugin via [`crate::renderer::Renderer::update_bound`] (pipeline
+    /// runs — `Adopted` deltas, changed-config delivery, public no-op
+    /// refresh) or [`crate::renderer::Renderer::update_lazy`]
+    /// (`table_updated` data refreshes, the config-apply tasks, warning
+    /// dismiss), both locked. Tier fallback: a plugin without `update`
+    /// receives `draw` — it declared no incremental path, so every repaint
+    /// is a full render.
+    pub async fn update(
+        &self,
+        view: perspective_js::View,
+        column_limit: Option<usize>,
+        row_limit: Option<usize>,
+        force: bool,
+    ) -> ApiResult<()> {
+        if self.capabilities().update {
+            self._update(view, column_limit, row_limit, force).await
+        } else {
+            self.draw(view, column_limit, row_limit, force).await
+        }
+    }
+
+    /// Repaint from retained state — dispatched iff geometry or visibility
+    /// changed: box resizes (resize observers, presize sweeps, settings
+    /// toggles) and the panel-ACTIVATION chrome nudge
+    /// ([`crate::renderer::Renderer::activation_repaint`], stamped inside
+    /// one locked dispatch). Same `View`, same data, no CSS re-read —
+    /// implementations should no-op while hidden (`offsetParent == null`).
+    /// Tier fallback: no-op — CSS reflows the box and the next dispatch
+    /// repaints the content.
+    pub async fn resize(&self) -> ApiResult<JsValue> {
+        if self.capabilities().resize {
+            self._resize().await
+        } else {
+            Ok(JsValue::UNDEFINED)
+        }
+    }
+
+    /// Re-read the `--psp-*` CSS custom properties (sync). Dispatched ONLY
+    /// when the effective theme genuinely changed, state-keyed by
+    /// [`crate::renderer::Renderer::needs_restyle`] (the effective theme
+    /// vs. the one recorded at this plugin's last capture — first paint or
+    /// last restyle), from two sites: fused immediately BEFORE a
+    /// `draw`/`update` inside the same locked dispatch
+    /// (`Renderer::draw_view`, "restyle then draw" — one render pass in
+    /// the new theme), or as `Renderer::restyle_all`'s locked
+    /// restyle-then-`update` pair when no other dispatch is coming
+    /// (theme picker, `resetThemes`, default-theme discovery, restore
+    /// tails). Exception: the public `restyleElement()` API restyles
+    /// unconditionally — it is the "my external CSS changed" affordance,
+    /// outside what captured-theme state can know. (Plus one
+    /// `mount_plugin` restyle on first light-DOM mount.) Tier fallback:
+    /// no-op — the plugin re-reads CSS at its next render.
+    pub fn restyle(&self) {
+        if self.capabilities().restyle {
+            self._restyle()
+        }
+    }
+
+    /// Blank the plugin (view deleted, table removed). Tier fallback:
+    /// no-op.
+    pub async fn clear(&self) -> ApiResult<JsValue> {
+        if self.capabilities().clear {
+            self._clear().await
+        } else {
+            Ok(JsValue::UNDEFINED)
+        }
+    }
+
+    /// Offscreen export render (`copy`/`export`) — returns an image
+    /// `Blob`; not a dispatch verb (does not touch the plugin's mounted
+    /// DOM state), but still serialized under the draw lock. Tier
+    /// fallback: errors — image export is unsupported without it.
+    pub async fn render(
+        &self,
+        view: perspective_js::View,
+        viewport: Option<JsViewWindow>,
+    ) -> ApiResult<web_sys::Blob> {
+        if self.capabilities().render {
+            self._render(view, viewport).await
+        } else {
+            Err(ApiError::from("Plugin does not support image export"))
+        }
+    }
+
+    /// Clear any visible selection state (highlighted rows, pinned
+    /// tooltips) WITHOUT emitting selection events. Invoked by the host
+    /// when an element-level global filter contributed by this panel's
+    /// selection is removed (`GlobalFilterBar` chip × / "Clear"), so the
+    /// selection visual can't outlive the filter it produced.
+    /// Implementations may redraw, so callers must hold the plugin's
+    /// per-`Renderer` draw lock (see "Call discipline"). Tier fallback:
+    /// no-op.
+    pub async fn deselect(&self) -> ApiResult<()> {
+        if self.capabilities().deselect {
+            self._deselect().await
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Staged presize: render at the TARGET element box `(width, height)`
+    /// offscreen — nothing on screen changes — resolving, once the frame
+    /// is staged, to a present closure that reveals it synchronously.
+    /// Callers run the closure in the same task as the layout commit the
+    /// presize anticipated (see `Renderer::presize_with_dimensions`), so
+    /// geometry and pixels land in one paint; the closure is lock-free (it
+    /// blits retained pixels, no plugin render entry). Only call when
+    /// [`Self::capabilities`] reports `presize` — plugins without it take
+    /// the held style-override path. Resolves `None` when the plugin
+    /// skipped (hidden), presenting nothing.
+    pub async fn presize(&self, width: f64, height: f64) -> ApiResult<Option<js_sys::Function>> {
+        let present = self._presize(width, height).await?;
+        Ok(present.dyn_into::<js_sys::Function>().ok())
+    }
 }

package/src/rust/js/regular_layout.rs

@@ -0,0 +1,258 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! A `wasm-bindgen` binding to the `<regular-layout>` custom element from
+//! [`regular-layout`](https://github.com/texodus/regular-layout), used as the
+//! layout engine for `<perspective-viewer>`'s panels.
+
+use js_sys::Promise;
+use serde::{Deserialize, Serialize};
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+extern "C" {
+    /// The `<regular-layout>` custom element.
+    #[wasm_bindgen(extends = web_sys::HtmlElement)]
+    pub type RegularLayout;
+
+    /// Place the child named `name` into the grid, optionally at `path`
+    /// (a `number[]`; pass [`JsValue::UNDEFINED`] to append) and optionally
+    /// forcing a `split` (`bool` or an `Orientation` string).
+    #[wasm_bindgen(method, js_name = "insertPanel")]
+    pub fn insert_panel(this: &RegularLayout, name: &str, path: JsValue, split: JsValue)
+    -> Promise;
+
+    /// Remove the panel named `name` from the grid (its DOM child stays
+    /// connected, but unslotted).
+    #[wasm_bindgen(method, js_name = "removePanel")]
+    pub fn remove_panel(this: &RegularLayout, name: &str) -> Promise;
+
+    /// Unslot all panels.
+    #[wasm_bindgen(method)]
+    pub fn clear(this: &RegularLayout) -> Promise;
+
+    /// Return the `number[]` index path for the panel named `name`, or `null`.
+    #[wasm_bindgen(method, js_name = "calculatePath")]
+    pub fn calculate_path(this: &RegularLayout, name: &str) -> JsValue;
+
+    /// Hit-test for the [`LayoutPath`](https://github.com/texodus/regular-layout)
+    /// under a pointer (`{clientX, clientY}`), or `null`.
+    #[wasm_bindgen(method, js_name = "calculateIntersect")]
+    pub fn calculate_intersect(this: &RegularLayout, coordinates: &JsValue) -> JsValue;
+
+    /// Show the drag-preview overlay for `target` at the pointer `coordinates`.
+    #[wasm_bindgen(method, js_name = "setOverlayState")]
+    pub fn set_overlay_state(
+        this: &RegularLayout,
+        coordinates: &JsValue,
+        target: &JsValue,
+    ) -> Promise;
+
+    /// Clear the drag-preview overlay and commit the placement for `target`.
+    #[wasm_bindgen(method, js_name = "clearOverlayState")]
+    pub fn clear_overlay_state(
+        this: &RegularLayout,
+        coordinates: &JsValue,
+        target: &JsValue,
+    ) -> Promise;
+
+    /// Euclidean pixel distance between `coordinates` and a drag `target`.
+    #[wasm_bindgen(method, js_name = "diffCoordinates")]
+    pub fn diff_coordinates(this: &RegularLayout, coordinates: &JsValue, target: &JsValue) -> f64;
+
+    /// Convert a `ViewWindow` (normalized 0–1) to a `DOMRect` in screen pixels.
+    #[wasm_bindgen(method, js_name = "realCoordinates")]
+    pub fn real_coordinates(this: &RegularLayout, window: &JsValue) -> JsValue;
+
+    /// Configure resize physics (edge tolerances, divider size).
+    #[wasm_bindgen(method, js_name = "restorePhysics")]
+    pub fn restore_physics(this: &RegularLayout, physics: &JsValue);
+
+    /// Read the current resize physics.
+    #[wasm_bindgen(method, js_name = "savePhysics")]
+    pub fn save_physics(this: &RegularLayout) -> JsValue;
+
+    /// Resume a resize previously deferred via `preventDefault()` in the
+    /// `regular-layout-before-resize` handler.
+    #[wasm_bindgen(method, js_name = "resumeResize")]
+    pub fn resume_resize(this: &RegularLayout);
+
+    /// Serialize the current [`Layout`] tree.
+    #[wasm_bindgen(method)]
+    pub fn save(this: &RegularLayout) -> JsValue;
+
+    /// Restore a [`Layout`] tree, dispatching a cancelable
+    /// `regular-layout-before-resize` event first.
+    #[wasm_bindgen(method)]
+    pub fn restore(this: &RegularLayout, layout: &JsValue) -> Promise;
+
+    /// Restore a [`Layout`] tree synchronously, without the resize event.
+    #[wasm_bindgen(method, js_name = "restoreSync")]
+    pub fn restore_sync(this: &RegularLayout, layout: &JsValue);
+
+    /// Select the panel `name`, making it the front-most tab within its
+    /// containing stack; dispatches a `regular-layout-select` event
+    /// (`detail: { name }`). Fires even when re-selecting the active tab.
+    #[wasm_bindgen(method)]
+    pub fn select(this: &RegularLayout, name: &str) -> Promise;
+
+    /// Maximize the panel `name` (full-size, others hidden). Transient — not
+    /// persisted by [`Self::save`]; a subsequent [`Self::restore`] resets it.
+    #[wasm_bindgen(method)]
+    pub fn maximize(this: &RegularLayout, name: &str);
+
+    /// Restore the normal multi-panel view after [`Self::maximize`].
+    #[wasm_bindgen(method)]
+    pub fn minimize(this: &RegularLayout);
+
+    /// The `detail` of a [`Self::BEFORE_RESIZE_EVENT`] event.
+    pub type PresizeDetail;
+
+    /// Each panel's pending-resize target as a `Record<name, LayoutPath>`; each
+    /// `LayoutPath` carries a normalized `view_window` that
+    /// [`Self::real_coordinates`] converts to a pixel box. Used to pre-size
+    /// panel contents before the layout commits.
+    #[wasm_bindgen(method, js_name = "calculatePresizePaths")]
+    pub fn calculate_presize_paths(this: &PresizeDetail) -> JsValue;
+
+    /// For a drag transition, the dragged panel's `{slot, path}` — its name
+    /// and the `LayoutPath` of its preview box (`path.view_window` is exactly
+    /// where the overlay renders it). The dragged panel is removed from the
+    /// layout tree during a drag, so it is absent from
+    /// [`Self::calculate_presize_paths`]; this getter lets consumers pre-size
+    /// it like any other panel (regular-layout >= 0.6.1). `null` when the
+    /// pointer is outside every drop target (the dragged panel is hidden),
+    /// `undefined` for non-drag transitions.
+    #[wasm_bindgen(method, getter)]
+    pub fn overlay(this: &PresizeDetail) -> JsValue;
+}
+
+impl RegularLayout {
+    /// Emitted before the layout resizes its panels, so consumers can pre-size
+    /// panel contents (`CustomEvent<PresizeDetail>`); cancelable.
+    pub const BEFORE_RESIZE_EVENT: &'static str = "regular-layout-before-resize";
+    /// Emitted before the layout tree changes (`CustomEvent<Layout>`).
+    pub const BEFORE_UPDATE_EVENT: &'static str = "regular-layout-before-update";
+    /// The `<regular-layout-frame>` chrome element tag name (titlebar + tabs).
+    pub const FRAME_TAG_NAME: &'static str = "regular-layout-frame";
+    /// Emitted when a tab is selected (`CustomEvent<{ name: string }>`). Fires
+    /// on every tab interaction — including re-selecting the active tab or
+    /// selecting the sole tab of a single-element stack — so consumers can
+    /// always map a tab interaction to an "active panel".
+    pub const SELECT_EVENT: &'static str = "regular-layout-select";
+    /// The custom element tag name.
+    pub const TAG_NAME: &'static str = "regular-layout";
+    /// Emitted after the layout tree changes (`CustomEvent<Layout>`).
+    pub const UPDATE_EVENT: &'static str = "regular-layout-update";
+
+    /// Whether `name` is currently placed in this layout's tree (a non-null
+    /// [`Self::calculate_path`]).
+    pub fn contains_panel(&self, name: &str) -> bool {
+        let path = self.calculate_path(name);
+        !path.is_null() && !path.is_undefined()
+    }
+}
+
+/// The orientation of a [`SplitLayout`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, ts_rs::TS)]
+#[serde(rename_all = "lowercase")]
+pub enum Orientation {
+    Horizontal,
+    Vertical,
+}
+
+/// A serde mirror of `regular-layout`'s serialized layout tree, as returned by
+/// [`RegularLayout::save`] and accepted by [`RegularLayout::restore`].
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ts_rs::TS)]
+#[serde(tag = "type")]
+pub enum Layout {
+    /// Space divided among children, side-by-side or stacked.
+    #[serde(rename = "split-layout")]
+    Split(SplitLayout),
+
+    /// A leaf node holding one or more named tabs (a stack).
+    #[serde(rename = "tab-layout")]
+    Tab(TabLayout),
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ts_rs::TS)]
+pub struct SplitLayout {
+    pub children: Vec<Layout>,
+    pub sizes: Vec<f64>,
+    pub orientation: Orientation,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ts_rs::TS)]
+pub struct TabLayout {
+    /// Panel ids (slot names) in this stack.
+    pub tabs: Vec<String>,
+
+    /// Index of the selected tab within `tabs`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional)]
+    pub selected: Option<usize>,
+}
+
+impl Layout {
+    /// Collect every panel id (slot name) in the tree, depth-first.
+    pub fn slot_names(&self) -> Vec<String> {
+        match self {
+            Layout::Split(split) => split.children.iter().flat_map(Layout::slot_names).collect(),
+            Layout::Tab(tab) => tab.tabs.clone(),
+        }
+    }
+
+    /// Collect every panel id that is *hidden* — i.e. in a stack (tab-layout)
+    /// at an index other than its `selected` one — in depth-first order. The
+    /// complement of the visible set: every other panel is the front of its
+    /// stack (single-tab leaves are trivially visible).
+    pub fn hidden_slot_names(&self) -> Vec<String> {
+        match self {
+            Layout::Split(split) => split
+                .children
+                .iter()
+                .flat_map(Layout::hidden_slot_names)
+                .collect(),
+            Layout::Tab(tab) => {
+                let selected = tab.selected.unwrap_or(0);
+                tab.tabs
+                    .iter()
+                    .enumerate()
+                    .filter(|(idx, _)| *idx != selected)
+                    .map(|(_, name)| name.clone())
+                    .collect()
+            },
+        }
+    }
+
+    /// Rewrite every panel id through `f`, returning the remapped tree. Ids for
+    /// which `f` returns `None` are left unchanged. Used by whole-element
+    /// `restore`, which recreates panels under fresh (collision-free) ids and
+    /// must point the saved layout tree at them.
+    pub fn remap(&self, f: &impl Fn(&str) -> Option<String>) -> Layout {
+        match self {
+            Layout::Split(split) => Layout::Split(SplitLayout {
+                children: split.children.iter().map(|c| c.remap(f)).collect(),
+                sizes: split.sizes.clone(),
+                orientation: split.orientation,
+            }),
+            Layout::Tab(tab) => Layout::Tab(TabLayout {
+                tabs: tab
+                    .tabs
+                    .iter()
+                    .map(|name| f(name).unwrap_or_else(|| name.clone()))
+                    .collect(),
+                selected: tab.selected,
+            }),
+        }
+    }
+}