estreui 1.4.0 → 1.5.0

package/scripts/estreUi-main.js

@@ -49,6 +49,12 @@ const estreUi = {
     panelCurrentOnTop: null,
     headerCurrentOnTop: null,
 
+    // External back handler stack — host-mounted external embeds register navigation
+    // steps here so native back input flows through them before EstreUI's section
+    // stack. Roadmap #011 / push-pop API.
+    externalBackStack: [],
+    nextBackHandlerToken: 1,
+
     //static getter
     get currentTopComponent() {
         return this.blindedCurrentOnTop ?? (this.isOpenMainMenu ? this.menuCurrentOnTop : null) ?? this.mainCurrentOnTop;
@@ -109,6 +115,7 @@ const estreUi = {
     $grabArea: null,
 
     $overwatchPanel: null,
+    $topLayer: null,
     get $panelSections() { return this.$panelBlock?.find(c.c + se + uis.blockItem) ?? $(); },
     $panelHeader: null,
     $panelHost: null,
@@ -197,6 +204,43 @@ const estreUi = {
     },
     get isDarkMode() { return document.body.dataset.darkMode == t1; },
 
+    // Cover bar — desktop-class viewport with a pointing device that can hover.
+    // Static environment check; matches the media query that gates the cover
+    // bar UI surface in CSS. See roadmap entry (forthcoming) for the wider
+    // host-integration design.
+    get isWideHoverViewport() {
+        return matchMedia("(min-width: 1025px) and (min-height: 769px) and (hover: hover) and (pointer: fine)").matches;
+    },
+
+    // Cover bar — whether the rootbar is currently in its extended layout, i.e.,
+    // the non-rootbar nav siblings under fixedBottom (`customFixedSections`,
+    // `instantSections`) take flex-grow:1 per estreUiCore.css's `@media all and
+    // (min-height: 700px) and (min-width: 740px)` block, AND the cover-bar
+    // handle is initialized. Combines static media-query state with dynamic
+    // bootstrap state.
+    get rootBarExtended() {
+        if (this.coverBarHandle == null) return false;
+        const fb = this.$fixedBottom?.[0] ?? this.$fixedBottom;
+        const nav = fb?.querySelector?.("nav:not(#rootbar)");
+        if (nav == null) return false;
+        return getComputedStyle(nav).flexGrow === "1";
+    },
+
+    // Cover bar — composite readiness: the environment supports the bar (wide
+    // viewport with hover) AND the rootbar is in its extended layout with a
+    // handle already initialized. Cover entries should only be pushed when
+    // this returns true; the handle itself is idempotent against pushes that
+    // arrive while still false.
+    get isInstantBarReady() {
+        return this.isWideHoverViewport && this.rootBarExtended;
+    },
+
+    // Placeholder for the cover-bar handle introduced in Phase 1C. Held at null
+    // so rootBarExtended can short-circuit before initialization. Naming follows
+    // EstreUI's stock handle convention (EstreHandle, EstreSwipeHandler, etc.)
+    // even though the cover bar isn't DOM-attached the same way.
+    coverBarHandle: null,
+
 
 
     //links (object redirection)
@@ -225,6 +269,8 @@ const estreUi = {
 
         this.$fixedBottom = $("#fixedBottom");
 
+        this.$topLayer = $("#topLayer");
+
         this.$handlePrototypes = $("section#handlePrototypes");
 
         
@@ -239,6 +285,7 @@ const estreUi = {
             this.$tabsbar = this.$fixedBottom.find(".tabsbar");
             this.$rootbar = this.$fixedBottom.find("nav#rootbar");
             this.initRootbar();
+            this.initCoverBar();
         }
 
         const onLoadedFixedTop = subTerm => {
@@ -891,83 +938,17 @@ const estreUi = {
         }
 
         this.$rootTabs.filter(ax(eds.tabId)).click(this.rootTabOnClick);
-
-
-        // * Currently not using
-        // fetch("./structure/rootmenu" + estreStruct.structureSuffix)
-        //     .then((response) => {
-        //         if (response.ok) return response.json();
-        //         throw Error("[" + response.status + "]" + response.url);
-        //     })
-        //     .then((data) => estreUi.renderRootBar(data))
-        //     .catch((error) => console.log("fetch error: " + error));
     },
 
-// === Currently not using
-    renderRootBar(esd) {
-        this.$rootTabs.empty();
-        this.$mainArea.empty();
-        var topId = null;
-        for (var item of esd.menu) {
-            this.$rootTabs.append(this.buildRootTabItem(item));
-            this.$mainArea.append(this.buildMainSection(item));
-            if (item.type == "static" && item.home) topId = item.id;
-        }
-        this.$rootTabs = this.$rootbar.find(c.c + btn);
-
-        if (topId != null) {
-            this.$rootTabs.filter(aiv(eds.tabId, topId)).attr(eds.active, t1);
-        }
-
-        this.$rootTabs.filter(ax(eds.tabId)).click(this.rootTabOnClick);
+    // Cover bar — instantiates the handle bound to the loaded fixedBottom
+    // markup. Idempotent: subsequent calls noop, so reload paths are safe.
+    // Phase 1C-2/1C-3 add lifecycle hooks and entry rendering on top of this.
+    initCoverBar() {
+        if (this.coverBarHandle != null) return;
+        if (this.$fixedBottom == null || this.$fixedBottom.length === 0) return;
+        this.coverBarHandle = new EstreCoverBarHandle(this.$fixedBottom, this.$topLayer);
     },
 
-    buildRootTabItem(esm) {
-        const element = doc.ce(btn);
-        element.setAttribute(m.cls, "tp_tiled_btn");
-        element.setAttribute("title", esm.desc);
-        element.setAttribute(eds.tabId, esm.id);
-        element.innerHTML = esm.title;
-        return element;
-    },
-
-    buildMainSection(esm) {
-        const element = doc.ce(se);
-        element.setAttribute(m.cls, "vfv_scroll");
-        element.setAttribute("id", esm.id);
-        this.fetchContent(esm, element);
-        return element;
-    },
-
-    fetchContent(esm, target) {
-        return fetch("." + esm.direct + estreStruct.structureSuffix)
-            .then((response) => {
-                if (response.ok) return response.json();
-                throw Error("[" + response.status + "]" + response.url);
-            })
-            .then((data) => {
-                const parts = this.renderContentArea(data);
-                for (var part of parts) target.append(part);
-            })
-            .catch((error) => {
-                if (window.isLogging) console.error("fetch error: " + error);
-            });
-    },
-
-    renderContentArea(ecm) {
-        const set = [];
-        const article = doc.ce(ar);
-        if (ecm.content.display == "constraint") article.setAttribute(m.cls, "constraint");
-        set.push(article);
-        for (var handle of handles) {
-            const handler = doc.ce(div);
-            handler.setAttribute(m.cls, "handle_set " + handle.attach);
-            set.push(handler);
-        }
-        return set;
-    },
-// ===========================
-
     showExactAppbar(component, container, article) {
         const appbar = this.appbar;
         if (appbar == null) return;
@@ -1845,9 +1826,168 @@ const estreUi = {
     },
 
     async onBack() {
-        return await this.onBackOverlay() || onBackWhile() ||
-            this.isOpenMainMenu ? await this.onBackMenu() || await this.closeMainMenu() : false ||
-            await this.onBackBlinded() || await this.onBackMain();
+        // External handler stack first (LIFO). Each entry can absorb the back
+        // input by returning truthy; falsy lets the next entry (and finally the
+        // EstreUI section stack below) try. Errors are isolated and logged.
+        for (let i = this.externalBackStack.length - 1; i >= 0; i--) {
+            try {
+                if (await this.externalBackStack[i].handler()) return true;
+            } catch (e) {
+                if (window.isLogging) console.warn("[estreUi] external back handler error", e);
+            }
+        }
+        if (await this.onBackOverlay()) return true;
+        if (onBackWhile()) return true;
+        if (this.isOpenMainMenu) {
+            return await this.onBackMenu() || await this.closeMainMenu();
+        }
+        return await this.onBackBlinded() || await this.onBackMain();
+    },
+
+    /**
+     * Register a back handler from a host-mounted external embed.
+     *
+     * Handlers are consumed LIFO — the most recent push runs first on the next
+     * `back()` / popstate. Returning `true` (or a Promise resolving truthy)
+     * stops the chain and absorbs the back input; returning a falsy value lets
+     * the previous entry (or the EstreUI section stack) try.
+     *
+     * Re-entry is fine: the same `handler` may be pushed multiple times; each
+     * push gets a separate token and counts as a separate stack entry.
+     *
+     * @param {() => boolean | Promise<boolean>} handler
+     * @returns {number | null} Token for `popBackHandler`, or `null` if `handler` is invalid.
+     */
+    pushBackHandler(handler) {
+        if (typeof handler !== "function") {
+            if (window.isLogging) console.warn("[estreUi] pushBackHandler — handler must be a function");
+            return null;
+        }
+        const token = this.nextBackHandlerToken++;
+        this.externalBackStack.push({ token, handler });
+        return token;
+    },
+
+    /**
+     * Remove a previously pushed handler. Out-of-order pop is allowed —
+     * tokens identify entries independently of their stack position.
+     *
+     * @param {number} token
+     * @returns {boolean} `true` if an entry was removed, `false` if the token was unknown.
+     */
+    popBackHandler(token) {
+        const idx = this.externalBackStack.findIndex(it => it.token === token);
+        if (idx < 0) {
+            if (window.isLogging) console.warn("[estreUi] popBackHandler — token not found:", token);
+            return false;
+        }
+        this.externalBackStack.splice(idx, 1);
+        return true;
+    },
+
+    /**
+     * Drop every external back handler — fallback cleanup for embed teardown
+     * paths that cannot match tokens individually. Embeds should prefer paired
+     * push/pop and reach for this only as a safety net.
+     */
+    clearAllExternalBackHandlers() {
+        this.externalBackStack.length = 0;
+    },
+
+
+    // ─── instantSections — external embed hook (cover bar, Phase 3) ───
+    //
+    // Light-DOM-mounted embeds (mango-class talk, future docked tools…) can
+    // surface their own windows in the right-side cover bar (instantSections)
+    // using these four wrappers. Internally they delegate to the singleton
+    // EstreCoverBarHandle managed by initCoverBar(); each push returns a
+    // monotone positive integer token. The user's intent is reported back
+    // through the per-entry `onAction(action)` callback, where `action` is
+    // one of "focus" / "minimize" / "restore" / "close". The embed owns the
+    // actual window transition — the bar only routes intent.
+
+    /**
+     * Register an external cover-bar entry. Returns a token; pass it back to
+     * `updateInstantSectionEntry` / `removeInstantSectionEntry` /
+     * `setInstantSectionActiveByToken`.
+     *
+     * With `closable: true` an ✕ button is rendered on the entry; clicking
+     * it fires `onAction("close")`. The embed is responsible for the actual
+     * close (so async confirm / server roundtrip can run first) and must
+     * call `removeInstantSectionEntry` once the close completes.
+     *
+     * @param {object} data
+     * @param {string} [data.title]
+     * @param {string|null|undefined} [data.icon] — empty / undefined → sectionBound default, "none" / null → text-only, "<url>" → that URL
+     * @param {string} [data.sectionBound] — "main" | "blind" | "overlay", drives the default icon
+     * @param {(action: "focus"|"minimize"|"restore"|"close") => void} [data.onAction]
+     * @param {boolean} [data.closable] — render an ✕ that fires onAction("close")
+     * @param {number} [data.badge] — unread / notification count (0 or null → no badge, 1 → dot, 2-99 → numeric, >99 → "99+")
+     * @returns {number|null} token, or `null` if the cover bar isn't initialised
+     */
+    pushInstantSectionEntry(data) {
+        if (this.coverBarHandle == null) {
+            if (window.isLogging) console.warn("[estreUi] pushInstantSectionEntry — coverBarHandle not initialised");
+            return null;
+        }
+        return this.coverBarHandle.pushEntry({
+            title: data?.title,
+            icon: data?.icon,
+            sectionBound: data?.sectionBound,
+            onAction: data?.onAction,
+            closable: data?.closable,
+            badge: data?.badge,
+        });
+    },
+
+    /**
+     * Patch an existing external entry. `partial` may carry any of `title`,
+     * `icon`, `onAction`, `closable`. Returns false if the token is unknown
+     * or the cover bar isn't initialised.
+     *
+     * @param {number} token
+     * @param {object} partial
+     * @returns {boolean}
+     */
+    updateInstantSectionEntry(token, partial) {
+        return this.coverBarHandle?.updateEntry(token, partial) ?? false;
+    },
+
+    /**
+     * Remove an external entry. The bar detaches the DOM and forgets the
+     * state; `activeToken` is cleared if the removed entry was active.
+     *
+     * @param {number} token
+     * @returns {boolean}
+     */
+    removeInstantSectionEntry(token) {
+        return this.coverBarHandle?.removeEntry(token) ?? false;
+    },
+
+    /**
+     * Mark an external entry active (visually highlighted on the bar).
+     * Call this from the embed when its window gains focus through some
+     * other path than a bar click — e.g., the user clicked inside the
+     * embed itself.
+     *
+     * @param {number} token
+     * @returns {boolean}
+     */
+    setInstantSectionActiveByToken(token) {
+        return this.coverBarHandle?.setActiveByToken(token) ?? false;
+    },
+
+    /**
+     * Mark an external entry minimized / restored. Call this from the embed
+     * when its window's visibility changes through a path other than a bar
+     * click — e.g., the embed exposed its own minimize control.
+     *
+     * @param {number} token
+     * @param {boolean} minimized
+     * @returns {boolean}
+     */
+    setInstantSectionMinimizedByToken(token, minimized) {
+        return this.coverBarHandle?.setMinimizedByToken(token, minimized) ?? false;
     },
 
     async onCloseContainer() {
@@ -2015,3 +2155,823 @@ const estreUi = {
     eoo: eoo
 }
 
+/**
+ * Cover bar handle — owns the bottom-bar entry list that mirrors opt-in pages
+ * (instantDoc / managedOverlay sections marked with `data-cover-mount`) and,
+ * in Phase 3, external-embed windows registered via the public push API.
+ *
+ * Named with the `Handle` suffix to align with EstreUI's stock handle
+ * convention (EstreHandle, EstreSwipeHandler, etc.) even though this one
+ * isn't DOM-element-attached — it manages the bar surface as a single owner.
+ *
+ * Phase 1C-1 scope: scaffolding only — area refs cached, entry CRUD comes in
+ * 1C-2 and entry rendering in 1C-3. The handle is instantiated by
+ * estreUi.initCoverBar() during fixedBottom load (see onLoadedFixedBottom).
+ */
+class EstreCoverBarHandle {
+
+    /**
+     * Reusable 14x14 SVG glyphs for the context menu. Same stroke weight and
+     * currentColor convention as the hide-all toggle / overflow sentinel, so
+     * host code can grab the same icons when opening its own menus via
+     * openContextMenu(). New icons should follow the same 14x14 viewBox +
+     * stroke-only / currentColor pattern.
+     *
+     *   center   → 4-directional inward arrows pointing at the middle (cross
+     *              shape so users don't confuse it with the diagonal-X close)
+     *   minimize → single low bar (Windows-style _)
+     *   restore  → outlined rect (window frame)
+     *   close    → diagonal-X
+     */
+    static menuIcons = {
+        center:
+            '<svg viewBox="0 0 14 14" fill="none" aria-hidden="true" focusable="false" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">'
+            + '<path d="M7 1.5v3.5M5.5 3.5L7 5l1.5-1.5"/>'
+            + '<path d="M7 12.5V9M5.5 10.5L7 9l1.5 1.5"/>'
+            + '<path d="M1.5 7h3.5M3.5 5.5L5 7l-1.5 1.5"/>'
+            + '<path d="M12.5 7H9M10.5 5.5L9 7l1.5 1.5"/>'
+            + '</svg>',
+        minimize:
+            '<svg viewBox="0 0 14 14" fill="none" aria-hidden="true" focusable="false">'
+            + '<path d="M3 10h8" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>'
+            + '</svg>',
+        restore:
+            '<svg viewBox="0 0 14 14" fill="none" aria-hidden="true" focusable="false">'
+            + '<rect x="3" y="3" width="8" height="8" rx="1" stroke="currentColor" stroke-width="1.5"/>'
+            + '</svg>',
+        close:
+            '<svg viewBox="0 0 14 14" fill="none" aria-hidden="true" focusable="false">'
+            + '<path d="M3 3l8 8M11 3l-8 8" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>'
+            + '</svg>',
+    };
+
+    #instantSections = null;
+    #customFixedSections = null;
+    #topLayer = null;
+    #instantSentinel = null;
+    #customFixedSentinel = null;
+    #resizeObserver = null;
+    #entries = [];
+    #nextToken = 1;
+    #activeToken = null;
+    #openDropdown = null;
+    #openContextMenu = null;
+    #onDocumentPointerDown = null;
+    #onDocumentKeydown = null;
+
+    constructor($fixedBottom, $topLayer) {
+        // Accept either a jQuery wrapper or a native element; the cover bar is
+        // intentionally jQuery-agnostic internally so it stays usable under the
+        // estreU0EEOZ jQuery fallback (jsdom test environment) as well as the
+        // real jQuery in browsers.
+        const fb = $fixedBottom?.[0] ?? $fixedBottom;
+        this.#instantSections = fb?.querySelector?.("nav#instantSections") ?? null;
+        this.#customFixedSections = fb?.querySelector?.("nav#customFixedSections") ?? null;
+        // Top-layer host for overflow dropdowns (Phase 2C). Optional — falls
+        // back to null when the host hasn't mounted the slot. The bar still
+        // renders entries; overflow dropdowns simply do not appear.
+        const tl = $topLayer?.[0] ?? $topLayer;
+        this.#topLayer = tl ?? null;
+
+        // Overflow sentinels — a ⌃-caret button at the leading edge of each
+        // area. Always appended once; visibility flips via the `hidden` attr
+        // as #recomputeOverflow measures area space against entry width.
+        // instantSections is right-aligned (justify-content: flex-end) so
+        // the sentinel ends up at the left edge of the visible cluster —
+        // i.e., it points at the overflowed (clipped) side. The sentinel
+        // is prepended so newly pushed entries (appended) always render to
+        // its trailing side.
+        if (this.#instantSections != null) {
+            this.#instantSentinel = this.#createSentinel("instant");
+            this.#instantSections.appendChild(this.#instantSentinel);
+        }
+        if (this.#customFixedSections != null) {
+            this.#customFixedSentinel = this.#createSentinel("custom-fixed");
+            this.#customFixedSections.appendChild(this.#customFixedSentinel);
+        }
+
+        // ResizeObserver watches both areas so overflow recomputes when the
+        // host viewport changes or the bar's siblings adjust. Falls back to a
+        // no-op if the API isn't available (rare; jsdom recent versions ship
+        // ResizeObserver). Push/remove/update paths call #recomputeOverflow
+        // directly so the bar stays in sync even without observer events.
+        if (typeof ResizeObserver !== "undefined") {
+            this.#resizeObserver = new ResizeObserver(() => this.#recomputeOverflow());
+            if (this.#instantSections != null) this.#resizeObserver.observe(this.#instantSections);
+            if (this.#customFixedSections != null) this.#resizeObserver.observe(this.#customFixedSections);
+        }
+
+        // Global listeners — close the overflow dropdown on outside click or
+        // Escape. Capture phase so an embed cannot swallow the pointerdown
+        // before we see it (the dropdown lives in #topLayer and the user's
+        // intent in clicking anywhere else is unambiguously "dismiss").
+        const self = this;
+        this.#onDocumentPointerDown = (event) => {
+            const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+            // Dropdown close exception list: its own element, its sentinel, and
+            // any currently-open context menu (a context menu opened from a
+            // dropdown row mounts as a sibling in #topLayer, so the dropdown
+            // shouldn't treat clicks on the menu as "outside").
+            if (self.#openDropdown != null
+                && !path.includes(self.#openDropdown.element)
+                && !path.includes(self.#openDropdown.sentinel)
+                && (self.#openContextMenu == null || !path.includes(self.#openContextMenu.element))) {
+                self.#closeDropdown();
+            }
+            if (self.#openContextMenu != null
+                && !path.includes(self.#openContextMenu.element)) {
+                self.#closeContextMenu();
+            }
+        };
+        this.#onDocumentKeydown = (event) => {
+            if (event.key !== "Escape") return;
+            if (self.#openContextMenu != null) self.#closeContextMenu();
+            else if (self.#openDropdown != null) self.#closeDropdown();
+        };
+        document.addEventListener("pointerdown", this.#onDocumentPointerDown, true);
+        document.addEventListener("keydown", this.#onDocumentKeydown);
+    }
+
+    get instantSections() { return this.#instantSections; }
+    get customFixedSections() { return this.#customFixedSections; }
+    get topLayer() { return this.#topLayer; }
+    /** @deprecated jQuery-flavoured getter kept for legacy callers; prefer `instantSections`. */
+    get $instantSections() { return this.#instantSections == null ? null : $(this.#instantSections); }
+    /** @deprecated jQuery-flavoured getter kept for legacy callers; prefer `customFixedSections`. */
+    get $customFixedSections() { return this.#customFixedSections == null ? null : $(this.#customFixedSections); }
+    get entries() { return this.#entries; }
+    get activeToken() { return this.#activeToken; }
+
+    /**
+     * Register a new cover-bar entry and render its DOM into `instantSections`.
+     * @param {object} data
+     * @param {EstrePageHandle} [data.pageHandle] — page bound to this entry (null for external embeds in Phase 3)
+     * @param {string} [data.sectionBound] — main / blind / overlay etc., drives the default icon
+     * @param {string} [data.title]
+     * @param {string|null|undefined} [data.icon]
+     * @returns {number} token
+     */
+    pushEntry(data) {
+        const token = this.#nextToken++;
+        const entry = {
+            token,
+            pageHandle: data.pageHandle ?? null,
+            sectionBound: data.sectionBound ?? null,
+            title: data.title ?? null,
+            icon: data.icon,
+            // External-embed wiring (Phase 3). pageHandle and onAction are
+            // mutually exclusive at the click-routing level: when pageHandle
+            // is set, clicks call show/hide on it; otherwise onAction fires
+            // with one of "focus" / "minimize" / "restore" / "close".
+            onAction: typeof data.onAction === "function" ? data.onAction : null,
+            closable: data.closable === true,
+            badge: typeof data.badge === "number" ? data.badge : null,
+            minimized: false,
+            element: null,
+        };
+        this.#entries.push(entry);
+        this.#renderEntry(entry);
+        this.#refreshEntryBadge(entry);
+        this.#recomputeOverflow();
+        return token;
+    }
+
+    removeEntry(token) {
+        const idx = this.#entries.findIndex(e => e.token === token);
+        if (idx < 0) return false;
+        const entry = this.#entries[idx];
+        entry.element?.remove();
+        this.#entries.splice(idx, 1);
+        if (this.#activeToken === token) this.#activeToken = null;
+        this.#recomputeOverflow();
+        return true;
+    }
+
+    setActiveByToken(token) {
+        // Passing null / undefined clears the active state. Useful for
+        // cumulative-state reconcile flows where the payload may legitimately
+        // have no active entry; without this the previously-active entry
+        // would stay highlighted indefinitely.
+        if (token == null) {
+            if (this.#activeToken == null) return true;
+            const prev = this.#entries.find(e => e.token === this.#activeToken);
+            prev?.element?.setAttribute("data-active", "");
+            this.#activeToken = null;
+            return true;
+        }
+        if (this.#entries.findIndex(e => e.token === token) < 0) return false;
+        if (this.#activeToken != null && this.#activeToken !== token) {
+            const prev = this.#entries.find(e => e.token === this.#activeToken);
+            prev?.element?.setAttribute("data-active", "");
+        }
+        this.#activeToken = token;
+        const entry = this.#entries.find(e => e.token === token);
+        entry?.element?.setAttribute("data-active", "1");
+        return true;
+    }
+
+    setMinimizedByToken(token, minimized) {
+        const entry = this.#entries.find(e => e.token === token);
+        if (entry == null) return false;
+        entry.minimized = !!minimized;
+        entry.element?.setAttribute("data-minimized", entry.minimized ? "1" : "");
+        return true;
+    }
+
+    updateEntry(token, partial) {
+        const entry = this.#entries.find(e => e.token === token);
+        if (entry == null) return false;
+        if ("title" in partial) {
+            entry.title = partial.title;
+            const label = entry.element?.querySelector(":scope > label");
+            if (label != null) label.textContent = entry.title ?? "";
+            // Mirror the title attr (native tooltip) so hover stays in sync
+            // with the visible label.
+            if (entry.element != null) {
+                if (entry.title != null) entry.element.setAttribute("title", entry.title);
+                else                     entry.element.removeAttribute("title");
+            }
+        }
+        if ("icon" in partial) {
+            entry.icon = partial.icon;
+            this.#refreshEntryIcon(entry);
+        }
+        if ("onAction" in partial) {
+            entry.onAction = typeof partial.onAction === "function" ? partial.onAction : null;
+        }
+        if ("closable" in partial) {
+            entry.closable = partial.closable === true;
+            this.#refreshEntryClose(entry);
+        }
+        if ("badge" in partial) {
+            entry.badge = typeof partial.badge === "number" ? partial.badge : null;
+            this.#refreshEntryBadge(entry);
+        }
+        this.#recomputeOverflow();
+        return true;
+    }
+
+    /** Lookup entry by token. Returns the live object — callers should treat it as read-only. */
+    findEntry(token) {
+        return this.#entries.find(e => e.token === token) ?? null;
+    }
+
+    /**
+     * Resolve the icon URL for an entry per the cover-icon fallback rules:
+     *   - icon === undefined → unset → sectionBound default
+     *   - icon === ""        → explicit blank → sectionBound default
+     *   - icon === "none"    → text-only (returns null)
+     *   - icon === null      → text-only (returns null)
+     *   - icon === "<url>"   → that URL
+     */
+    #resolveIconUrl(entry) {
+        const icon = entry.icon;
+        if (icon === "none" || icon === null) return null;
+        if (icon === "" || icon === undefined) return this.#defaultIconForSection(entry.sectionBound);
+        return icon;
+    }
+
+    #defaultIconForSection(sectionBound) {
+        if (sectionBound === "main") return "./vectors/cover-icon-default-static.svg";
+        if (sectionBound === "blind") return "./vectors/cover-icon-default-instant.svg";
+        if (sectionBound === "overlay") return "./vectors/cover-icon-default-overlay.svg";
+        return null;
+    }
+
+    #renderEntry(entry) {
+        if (this.#instantSections == null) return;
+        const btn = document.createElement("button");
+        btn.type = "button";
+        btn.className = "clean cover_entry";
+        btn.setAttribute("data-cover-token", entry.token);
+        if (entry.sectionBound != null) btn.setAttribute("data-section-bound", entry.sectionBound);
+        // Full title surfaces as the native tooltip — the visible label is
+        // ellipsis-clipped on narrow tiles, but hovering reveals the rest.
+        if (entry.title != null) btn.setAttribute("title", entry.title);
+
+        const iconUrl = this.#resolveIconUrl(entry);
+        if (iconUrl != null) {
+            const span = document.createElement("span");
+            span.className = "cover_icon";
+            const img = document.createElement("img");
+            img.alt = "";
+            img.src = iconUrl;
+            span.appendChild(img);
+            btn.appendChild(span);
+        }
+
+        const label = document.createElement("label");
+        label.textContent = entry.title ?? "";
+        btn.appendChild(label);
+
+        const self = this;
+        btn.addEventListener("click", () => self.#onEntryClicked(entry.token));
+        btn.addEventListener("contextmenu", (event) => self.#onEntryContextMenu(entry.token, event));
+
+        entry.element = btn;
+        this.#instantSections.appendChild(btn);
+        if (entry.closable) this.#refreshEntryClose(entry);
+    }
+
+    /**
+     * Add / remove the close ✕ on an entry to match `entry.closable`. Idempotent
+     * so it can be called from #renderEntry (initial paint) and updateEntry
+     * (state change). The ✕ click fires onAction("close") only — the embed is
+     * responsible for the actual close (so an async confirm / server roundtrip
+     * can run first) and must call removeInstantSectionEntry afterwards.
+     */
+    #refreshEntryClose(entry) {
+        if (entry.element == null) return;
+        const existing = entry.element.querySelector(":scope > .cover_entry_close");
+        if (!entry.closable) {
+            existing?.remove();
+            return;
+        }
+        if (existing != null) return;
+        const close = document.createElement("span");
+        close.className = "cover_entry_close";
+        close.setAttribute("role", "button");
+        close.setAttribute("aria-label", "Close");
+        close.textContent = "✕";
+        close.addEventListener("click", (event) => {
+            event.stopPropagation();
+            if (typeof entry.onAction === "function") entry.onAction("close");
+        });
+        entry.element.appendChild(close);
+    }
+
+    /**
+     * Cover-bar entry click handler. Routes to one of two surfaces based on
+     * whether the entry has a page handle or an external onAction callback.
+     * The state-to-intent mapping is the same in both branches — it mirrors
+     * how task-switcher-style docks behave:
+     *
+     *   - active & visible  → hide / "minimize"
+     *   - inactive          → show + focus / "focus"
+     *   - active & minimized → show + focus / "restore"
+     *
+     * For internal page entries the handle's own show/hide is invoked. For
+     * external embed entries (Phase 3) the registered onAction callback is
+     * fired with the corresponding action token; the embed owns the actual
+     * focus/minimize/restore transition. Entries with neither route configured
+     * noop on click.
+     */
+    #onEntryClicked(token) {
+        const entry = this.#entries.find(e => e.token === token);
+        if (entry == null) return;
+        if (entry.pageHandle != null) {
+            if (this.#activeToken === token && !entry.minimized) {
+                entry.pageHandle.hide();
+            } else {
+                entry.pageHandle.show(true, true);
+            }
+            return;
+        }
+        if (typeof entry.onAction === "function") {
+            let action;
+            if (this.#activeToken === token && !entry.minimized) action = "minimize";
+            else if (this.#activeToken === token && entry.minimized) action = "restore";
+            else action = "focus";
+            entry.onAction(action);
+        }
+    }
+
+    #refreshEntryIcon(entry) {
+        if (entry.element == null) return;
+        entry.element.querySelector(":scope > .cover_icon")?.remove();
+        const iconUrl = this.#resolveIconUrl(entry);
+        if (iconUrl == null) return;
+        const span = document.createElement("span");
+        span.className = "cover_icon";
+        const img = document.createElement("img");
+        img.alt = "";
+        img.src = iconUrl;
+        span.appendChild(img);
+        entry.element.insertBefore(span, entry.element.firstChild);
+    }
+
+    /**
+     * Apply the project-wide [data-badge] attribute convention (see
+     * estreUi.css `article [data-badge]::after`) to an element. Display
+     * rules — kept consistent with `setMangoTalkBadge` / `setPushNotificationBadge`
+     * elsewhere in the host so themes can override `--badge-color` once:
+     *   - count null / 0 / negative → attribute removed
+     *   - count === 1               → data-badge="" → dot (CSS :empty variant)
+     *   - 2 ≤ count ≤ 99            → data-badge="<count>" → numeric pill
+     *   - count > 99                → data-badge="99+"
+     */
+    #setBadgeAttr(target, count) {
+        if (count == null || count <= 0) {
+            target.removeAttribute("data-badge");
+            return;
+        }
+        target.setAttribute("data-badge",
+            count === 1 ? "" :
+            count > 99  ? "99+" :
+                          String(count));
+    }
+
+    /**
+     * Sync the per-entry unread badge with `entry.badge`. The badge is
+     * surfaced as a [data-badge] attribute on the entry's .cover_icon —
+     * styled via the cover-bar-scoped ::after rule that mirrors the
+     * project-wide article [data-badge] convention. Text-only entries
+     * (icon: "none" / no .cover_icon host) silently no-op.
+     */
+    #refreshEntryBadge(entry) {
+        if (entry.element == null) return;
+        const iconHost = entry.element.querySelector(":scope > .cover_icon");
+        if (iconHost == null) return; // text-only entries can't host the badge
+        this.#setBadgeAttr(iconHost, entry.badge);
+    }
+
+    /**
+     * Create the per-area overflow sentinel button. Hidden by default; the
+     * recompute pass flips `hidden` based on whether entries fit. Clicking
+     * toggles the area's overflow dropdown (Phase 2C).
+     *
+     * The caret is rendered as an inline SVG so it can be precisely sized and
+     * positioned (top-aligned on a narrow button) regardless of the platform
+     * font. The shape mirrors the rootbar's chevron affordances — a thin
+     * upward chevron stroked in currentColor so hover / data-opened states
+     * pick up the surrounding color transitions for free.
+     */
+    #createSentinel(areaKey) {
+        const btn = document.createElement("button");
+        btn.type = "button";
+        btn.className = "clean cover_overflow_sentinel";
+        btn.setAttribute("data-area", areaKey);
+        btn.setAttribute("aria-label", "Show overflowed entries");
+        btn.innerHTML =
+            '<svg viewBox="0 0 12 8" aria-hidden="true" focusable="false">' +
+            '<polyline points="2,6 6,2 10,6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>' +
+            '</svg>';
+        btn.hidden = true;
+        const self = this;
+        btn.addEventListener("click", (event) => {
+            event.stopPropagation();
+            self.#toggleDropdown(areaKey);
+        });
+        return btn;
+    }
+
+    /**
+     * Re-evaluate overflow for both areas. Cheap: short loop guided by
+     * `area.scrollWidth > area.clientWidth`. Called from push / remove /
+     * update / ResizeObserver. Hidden entries (data-overflowed="1") drop
+     * out of layout via CSS, so subsequent measurements reflect the new
+     * width budget.
+     */
+    #recomputeOverflow() {
+        // Both areas hide from the trailing (DOM-end / most-recently-pushed)
+        // side. The sentinel sits at the trailing edge of the visible cluster
+        // (`order: 1`), so the entries that disappear are the ones closest to
+        // it — most-recently-pushed first. Users opening a fresh window see it
+        // get pushed into the dropdown as the bar fills up; older windows
+        // stay visible on the leading side where they were first placed.
+        this.#recomputeAreaOverflow(this.#instantSections, this.#instantSentinel, "trailing");
+        this.#recomputeAreaOverflow(this.#customFixedSections, this.#customFixedSentinel, "trailing");
+        if (this.#openDropdown != null) this.#refreshOpenDropdown();
+    }
+
+    /**
+     * Hide entries one at a time from the chosen end until the cluster fits.
+     *   - leading  → hide from index 0 forward  (oldest first, suited to
+     *                flex-end areas where the leading edge is clipped)
+     *   - trailing → hide from index N-1 backward (newest first, suited to
+     *                flex-start areas where the trailing edge is clipped)
+     */
+    #recomputeAreaOverflow(area, sentinel, hideFrom) {
+        if (area == null || sentinel == null) return;
+        const entries = this.#entriesForArea(area);
+        for (const e of entries) e.element?.removeAttribute("data-overflowed");
+        sentinel.hidden = true;
+        if (entries.length === 0) return;
+        if (area.scrollWidth <= area.clientWidth) return;
+
+        // Reveal the sentinel so its width counts toward the budget; then
+        // hide entries until the remaining cluster fits alongside it.
+        sentinel.hidden = false;
+        const indices = hideFrom === "leading"
+            ? entries.map((_, i) => i)
+            : entries.map((_, i) => entries.length - 1 - i);
+        for (const i of indices) {
+            if (area.scrollWidth <= area.clientWidth) return;
+            entries[i].element?.setAttribute("data-overflowed", "1");
+        }
+    }
+
+    /** Currently only `instantSections` hosts cover-bar entries. customFixedSections
+     *  is reserved for future user-pinned items (see PM/002 task ledger §Phase 4+). */
+    #entriesForArea(area) {
+        if (area === this.#instantSections) return this.#entries;
+        return [];
+    }
+
+    /**
+     * Open / close / toggle the overflow dropdown for an area. Single open
+     * dropdown at a time; opening one while another is open swaps them.
+     * No-op when the top-layer host slot is missing.
+     */
+    #toggleDropdown(areaKey) {
+        if (this.#openDropdown != null && this.#openDropdown.areaKey === areaKey) {
+            this.#closeDropdown();
+            return;
+        }
+        this.#openDropdown != null && this.#closeDropdown();
+        this.#openDropdown = this.#openDropdownFor(areaKey);
+    }
+
+    #openDropdownFor(areaKey) {
+        if (this.#topLayer == null) return null;
+        const sentinel = areaKey === "instant" ? this.#instantSentinel : this.#customFixedSentinel;
+        const area = areaKey === "instant" ? this.#instantSections : this.#customFixedSections;
+        if (sentinel == null || area == null) return null;
+
+        const dropdown = document.createElement("div");
+        dropdown.className = "cover_overflow_dropdown";
+        dropdown.setAttribute("data-area", areaKey);
+        this.#topLayer.appendChild(dropdown);
+        sentinel.setAttribute("data-opened", "1");
+
+        const state = { areaKey, sentinel, area, element: dropdown };
+        // Render and position after attaching so size can be measured.
+        this.#renderDropdownRows(state);
+        this.#positionDropdown(state);
+        return state;
+    }
+
+    #closeDropdown() {
+        if (this.#openDropdown == null) return;
+        this.#openDropdown.element.remove();
+        this.#openDropdown.sentinel?.removeAttribute("data-opened");
+        this.#openDropdown = null;
+    }
+
+    /** Re-render rows + re-position the open dropdown. Called when the set
+     *  of overflowed entries changes (e.g. resize) while it's open. */
+    #refreshOpenDropdown() {
+        if (this.#openDropdown == null) return;
+        // If the sentinel went away (everything fits again), drop the dropdown.
+        if (this.#openDropdown.sentinel?.hidden) {
+            this.#closeDropdown();
+            return;
+        }
+        this.#renderDropdownRows(this.#openDropdown);
+        this.#positionDropdown(this.#openDropdown);
+    }
+
+    #renderDropdownRows(state) {
+        const { element, area } = state;
+        element.replaceChildren();
+        // Newest hidden entries surface first — visually they sat closest to
+        // the sentinel before being pushed off, so the user reads them at
+        // the top of the dropdown. We hide from the trailing edge (most-
+        // recently-pushed first), so reversing the natural DOM order lines
+        // the dropdown rows up "newest → older" top to bottom.
+        const entries = this.#entriesForArea(area)
+            .filter(e => e.element?.getAttribute("data-overflowed") === "1")
+            .reverse();
+        for (const entry of entries) {
+            const row = document.createElement("button");
+            row.type = "button";
+            row.className = "clean cover_entry";
+            row.setAttribute("data-cover-token", entry.token);
+            if (entry.sectionBound != null) row.setAttribute("data-section-bound", entry.sectionBound);
+            if (this.#activeToken === entry.token) row.setAttribute("data-active", "1");
+            if (entry.minimized) row.setAttribute("data-minimized", "1");
+            if (entry.title != null) row.setAttribute("title", entry.title);
+
+            const iconUrl = this.#resolveIconUrl(entry);
+            if (iconUrl != null) {
+                const span = document.createElement("span");
+                span.className = "cover_icon";
+                const img = document.createElement("img");
+                img.alt = "";
+                img.src = iconUrl;
+                span.appendChild(img);
+                this.#setBadgeAttr(span, entry.badge);
+                row.appendChild(span);
+            }
+            const label = document.createElement("label");
+            label.textContent = entry.title ?? "";
+            row.appendChild(label);
+
+            const self = this;
+            row.addEventListener("click", (event) => {
+                event.stopPropagation();
+                self.#closeDropdown();
+                self.#onEntryClicked(entry.token);
+            });
+            // Right-click inside the overflow dropdown opens the entry's
+            // context menu on top of it — the dropdown stays open so the user
+            // can pick another row after dismissing the menu. The document-
+            // level pointerdown handler also exempts the open context menu
+            // from closing the dropdown (see constructor).
+            row.addEventListener("contextmenu", (event) => {
+                self.#onEntryContextMenu(entry.token, event);
+            });
+            if (entry.closable) {
+                const close = document.createElement("span");
+                close.className = "cover_entry_close";
+                close.setAttribute("role", "button");
+                close.setAttribute("aria-label", "Close");
+                close.textContent = "✕";
+                close.addEventListener("click", (event) => {
+                    event.stopPropagation();
+                    if (typeof entry.onAction === "function") entry.onAction("close");
+                });
+                row.appendChild(close);
+            }
+            element.appendChild(row);
+        }
+    }
+
+    #positionDropdown(state) {
+        const { element, sentinel, areaKey } = state;
+        const rect = sentinel.getBoundingClientRect();
+        // Anchor above the sentinel — fixedBottom sits at the screen base, so
+        // the dropdown opens upward. Use `bottom` rather than `top` so the
+        // dropdown grows up from the anchor as more rows are added.
+        const gap = 6;
+        element.style.bottom = `${Math.max(0, window.innerHeight - rect.top + gap)}px`;
+        element.style.top = "auto";
+        if (areaKey === "instant") {
+            // Right-align to the area's right edge so the dropdown stays
+            // within the host margin even when the sentinel itself sits
+            // anywhere along the bar's leading edge.
+            const areaRect = state.area.getBoundingClientRect();
+            element.style.right = `${Math.max(0, window.innerWidth - areaRect.right)}px`;
+            element.style.left = "auto";
+        } else {
+            const areaRect = state.area.getBoundingClientRect();
+            element.style.left = `${Math.max(0, areaRect.left)}px`;
+            element.style.right = "auto";
+        }
+    }
+
+    /**
+     * Right-click on a cover-bar entry opens a small context menu in #topLayer:
+     *
+     *   ── title ──────────────────
+     *   화면 가운데로 이동           (placeholder until the embed exposes the API)
+     *   최소화 / 복원                (label flips on entry.minimized)
+     *   닫기                          (fires onAction("close"))
+     *
+     * Internal page-handle entries don't get the menu — they have their own
+     * navigation surface already. External-embed entries (onAction !== null)
+     * are the target audience. The menu is single-instance: opening one closes
+     * any prior open instance, and outside pointerdown / Escape close it (see
+     * the document-level listeners in the constructor).
+     */
+    #onEntryContextMenu(token, event) {
+        const entry = this.#entries.find(e => e.token === token);
+        if (entry == null || typeof entry.onAction !== "function") return;
+        if (this.#topLayer == null) return;
+        event.preventDefault();
+        if (this.#openContextMenu != null) this.#closeContextMenu();
+        this.#openContextMenu = this.#openContextMenuFor(entry, event.clientX, event.clientY);
+    }
+
+    #openContextMenuFor(entry, x, y) {
+        // SVG glyphs picked for visual parity with the hide-all toggle and the
+        // overflow sentinel — same stroke weight (1.6 ~ 1.8) and 14x14 viewBox,
+        // all in currentColor so hover / disabled inherit the menu's text tone.
+        const SVG = EstreCoverBarHandle.menuIcons;
+        const items = [
+            { label: "화면 가운데로 이동", action: "center", svg: SVG.center },
+            entry.minimized
+                ? { label: "복원", action: "restore", svg: SVG.restore }
+                : { label: "최소화", action: "minimize", svg: SVG.minimize },
+            { label: "닫기", action: "close", svg: SVG.close },
+        ];
+        return this.openContextMenu({
+            x, y,
+            title: entry.title,
+            items,
+            onAction: (action) => this.#onContextMenuAction(entry.token, action),
+            anchorData: { "data-cover-token": entry.token },
+        });
+    }
+
+    /**
+     * Public context-menu surface — opens a menu in #topLayer at the cursor,
+     * matching the chrome the cover-bar uses internally for entry right-click.
+     * Host code (e.g. for a rootbar tab) calls this directly with its own
+     * items / onAction, instead of routing through a cover_entry.
+     *
+     * Items are `{ label, action, svg?, disabled? }`. The menu is single-
+     * instance — opening one closes any prior open menu. Outside pointerdown
+     * and Escape close it; both branches are wired in the constructor.
+     *
+     * Returns the menu state object (or null if #topLayer is missing).
+     */
+    openContextMenu({ x, y, title, items, onAction, anchorData }) {
+        if (this.#topLayer == null) return null;
+        if (this.#openContextMenu != null) this.#closeContextMenu();
+
+        const menu = document.createElement("div");
+        menu.className = "cover_entry_menu";
+        if (anchorData != null) {
+            for (const [k, v] of Object.entries(anchorData)) menu.setAttribute(k, v);
+        }
+
+        if (title != null) {
+            const titleEl = document.createElement("header");
+            titleEl.className = "cover_menu_title";
+            titleEl.textContent = title;
+            menu.appendChild(titleEl);
+        }
+
+        const self = this;
+        for (const it of items ?? []) {
+            const item = document.createElement("button");
+            item.type = "button";
+            item.className = "clean cover_menu_item";
+            item.setAttribute("data-action", it.action);
+            const iconSpan = document.createElement("span");
+            iconSpan.className = "cover_menu_item_icon";
+            if (it.svg != null) iconSpan.innerHTML = it.svg;
+            item.appendChild(iconSpan);
+            const labelSpan = document.createElement("span");
+            labelSpan.className = "cover_menu_item_label";
+            labelSpan.textContent = it.label;
+            item.appendChild(labelSpan);
+            if (it.disabled) item.disabled = true;
+            item.addEventListener("click", (ev) => {
+                ev.stopPropagation();
+                self.#closeContextMenu();
+                onAction?.(it.action);
+            });
+            menu.appendChild(item);
+        }
+
+        const state = { element: menu };
+        this.#topLayer.appendChild(menu);
+        this.#positionContextMenu(state, x, y);
+        this.#openContextMenu = state;
+        return state;
+    }
+
+    /**
+     * Anchor the context menu at the cursor and pick a quadrant so it always
+     * opens *toward* the viewport center — bottom-right click → menu pinned to
+     * its bottom-right (= grows up-and-left), top-left click → menu pinned
+     * top-left (= grows down-and-right), etc. The transform-origin custom
+     * property is set inline so the scale-grow open animation pivots at the
+     * click point.
+     */
+    #positionContextMenu(state, x, y) {
+        const { element } = state;
+        const w = window.innerWidth;
+        const h = window.innerHeight;
+        const isRight = x > w / 2;
+        const isBottom = y > h / 2;
+        element.style.left = isRight ? "auto" : `${x}px`;
+        element.style.right = isRight ? `${Math.max(0, w - x)}px` : "auto";
+        element.style.top = isBottom ? "auto" : `${y}px`;
+        element.style.bottom = isBottom ? `${Math.max(0, h - y)}px` : "auto";
+        // Origin corner = the cursor-anchored corner; CSS uses keywords (`top`
+        // / `bottom` / `left` / `right`) for transform-origin so it stays
+        // pixel-exact regardless of layout shifts during animation.
+        const vert = isBottom ? "bottom" : "top";
+        const horiz = isRight ? "right" : "left";
+        element.style.setProperty("--menu-origin", `${vert} ${horiz}`);
+    }
+
+    /**
+     * Fade the menu out (0.2s ease) before detaching, so the close looks like
+     * a deliberate dismiss rather than a pop. The element is removed on the
+     * transitionend; null-ing the state first prevents a re-entrant close from
+     * doubling up the fade.
+     */
+    #closeContextMenu() {
+        if (this.#openContextMenu == null) return;
+        const el = this.#openContextMenu.element;
+        this.#openContextMenu = null;
+        el.setAttribute("data-closing", "1");
+        const remove = () => el.remove();
+        el.addEventListener("transitionend", remove, { once: true });
+        // Safety fallback — if the animation is interrupted (e.g. element no
+        // longer in DOM), still detach after the expected duration.
+        setTimeout(remove, 260);
+    }
+
+    /** Route a context-menu click to the right action. The first three actions
+     *  delegate to the same onAction surface as bar-click intent (so embed
+     *  wirings only need one handler); "center" is a placeholder action that
+     *  the embed may wire later as a window-center transition. */
+    #onContextMenuAction(token, action) {
+        const entry = this.#entries.find(e => e.token === token);
+        if (entry == null || typeof entry.onAction !== "function") return;
+        entry.onAction(action);
+    }
+}
+
+
+// Expose estreUi on window so ES-module-realm host integrations (external embeds
+// loaded as <script type="module">) can reach the public API. Same-realm classic
+// scripts already see the lexical const; this line only adds the cross-realm
+// surface. See review #011.
+window.estreUi = estreUi;
+