npm - @qualified-salesforce/web - Versions diffs - 0.0.1-oidc-bootstrap - Mend

@qualified-salesforce/web 0.0.1-oidc-bootstrap

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (560) hide show

package/packs/widget/api/docking/shared.js ADDED Viewed

@@ -0,0 +1,164 @@
+import { __webpack_require__ } from "../../../../js/runtime.js";
+import "../../../../widget/utils/native_globals.js";
+/* provided dependency */ var requestAnimationFrame = __webpack_require__(68034).gj;
+/* eslint-disable rulesdir/css-units */ // ============================================================================
+// Concern Interface
+// ============================================================================
+/**
+ * Common interface every docking concern (viewport_resize, viewport_lock, ...)
+ * implements. The orchestrator drives concerns uniformly through these three
+ * methods, so adding a new concern only requires implementing the same shape.
+ *
+ * Concerns must be self-contained: their CSS must not reference variables
+ * defined by another concern, and their JS must not import another concern's
+ * exports. This way each can be enabled / disabled / unit-tested in isolation.
+ *
+ * - `init` runs exactly once during {@link DockingAPI.init}. Use it for one-
+ *   shot setup like installing prototype proxies, registering CSS custom
+ *   properties, or measuring the host page.
+ * - `reEvaluate` runs at the end of `init` and on every subsequent
+ *   {@link DockingAPI.reEvaluate} call. Must be idempotent — typical work is
+ *   rescanning newly added DOM and re-stamping marker attributes.
+ * - `getStyles` returns the concern-specific CSS that the orchestrator
+ *   concatenates into the base stylesheet. Called from the first
+ *   `reEvaluate`, so any values measured in `init` (e.g. scrollbar width)
+ *   are already available.
+ */ // ============================================================================
+// Shared Constants
+// ============================================================================
+/**
+ * Attribute set on `<html>` to signal docked mode. Owned by the orchestrator
+ * (which adds/removes it) and read by viewport_resize's CSS to switch the
+ * docked-width variable between 0 and the panel width.
+ */ const DOCKED_DOCUMENT_ATTRIBUTE = "q-docked";
+// Value of the `q-docked` attribute, describing which docking layout is active.
+// `regular` is the default right-side dock; `under-header` parks the panel flush
+// below a full-width host header (hairline left border instead of a drop shadow).
+// The (shadow-DOM) widget can't select the host page's `<html>` across the shadow
+// boundary, so multimodal mirrors this value onto its own host for `:host()` CSS.
+const DOCKED_MODE = {
+    regular: "regular",
+    underHeader: "under-header"
+};
+// Stamped on the element(s) that shrink to make room for the docked panel:
+// `<html>` in default docking, the host's `<main>`/`<footer>` under-header.
+const DOCKED_TARGET_ATTRIBUTE = "q-docked-target";
+// Breakpoint at/below which docking collapses to full width. 767px keeps 768px
+// (iPad mini portrait) on desktop while treating phones as mobile.
+const MOBILE_BREAKPOINT = "max-width: 767px";
+// Top offset (px) the docked widget starts below in `dockUnderHeader` mode,
+// tracking the sticky header's bottom edge. Defaults to `0px` when consumed.
+const DOCKED_TOP_OFFSET_CSS_VARIABLE = "--q-docked-top-offset";
+/**
+ * Custom property holding the inline-size of the visible content area
+ * (`100dvw - docked offset`). Declared by viewport_resize's stylesheet, which
+ * also uses it as the target for `vw → calc(... * var(--qdvw))` rewrites; it
+ * lives here because the `<q-docking>` host sizes its probe iframe from it.
+ */ const DOCKED_VIEWPORT_WIDTH_CSS_VARIABLE = "--qdvw";
+/**
+ * Prefix for `applyOnce` markers stamped on DOM nodes / prototypes by the
+ * various proxy installers. Each installer adds a `_<name>` suffix so the
+ * markers are globally unique even when the proxies live in different files.
+ */ const DOCKING_PROXY_MARKER = "__q_docking_proxy";
+/**
+ * Tag name of the singleton custom element hosting every docking-owned DOM node.
+ * The element is in `docking_host.ts`; the name stays here because importing it
+ * back for `isQualifiedOwnedShadowRoot` would be circular.
+ */ const Q_DOCKING_TAG_NAME = "q-docking";
+/**
+ * Shadow roots owned by Qualified (widget root or `<q-docking>` host).
+ * The transformer must not walk these — their stylesheets are either
+ * ours to manage directly or in-flight CORS clones.
+ */ function isQualifiedOwnedShadowRoot(root) {
+    if (!(root instanceof ShadowRoot)) return false;
+    if (root.host.id === "qualified-multimodal-host") return true;
+    if (root.host.tagName === Q_DOCKING_TAG_NAME.toUpperCase()) return true;
+    return false;
+}
+// ============================================================================
+// Shared DOM Helpers
+// ============================================================================
+/**
+ * Measures the host page's vertical scrollbar width using a hidden element
+ * with `overflow:scroll`. Returns 0 in browsers/environments that don't
+ * paint a scrollbar (overlay scrollbars, jsdom). Each concern that needs
+ * the value calls this in its own `init` so concerns stay independent.
+ */ function measureScrollbarWidth() {
+    const d = document.createElement("div");
+    d.style.cssText = "overflow:scroll;visibility:hidden;position:absolute;width:99px";
+    document.documentElement.append(d);
+    const w = d.offsetWidth - d.clientWidth;
+    d.remove();
+    return w;
+}
+/**
+ * Executes a callback on an element exactly once per key.
+ * Subsequent calls with the same element+key combination are no-ops.
+ */ function applyOnce(el, key, fn) {
+    if (key in el) return;
+    Reflect.set(el, key, 1);
+    fn(el);
+}
+/**
+ * Invokes the callback with document.body once available.
+ * Fires synchronously if the body already exists, otherwise defers
+ * via MutationObserver on documentElement.
+ */ function whenBodyAvailable(callback) {
+    if (document.body) {
+        callback(document.body);
+        return;
+    }
+    const observer = new MutationObserver(()=>{
+        if (document.body) {
+            observer.disconnect();
+            callback(document.body);
+        }
+    });
+    observer.observe(document.documentElement, {
+        childList: true
+    });
+}
+/**
+ * Runs `fn` with `transition: none !important` on `element` so any synchronous
+ * style changes are not animated, then restores the original transition value
+ * on the next animation frame. The restore is scheduled even if `fn` throws,
+ * so the host page's transitions are never permanently overridden.
+ */ function withTransitionsDisabled(element, fn) {
+    const hadInlineTransition = element.style.getPropertyValue("transition");
+    const hadPriority = element.style.getPropertyPriority("transition");
+    element.style.setProperty("transition", "none", "important");
+    try {
+        fn();
+    } finally{
+        // Always schedule the restore, even if fn() throws — otherwise `transition: none !important`
+        // would be left on the host page and could break any later CSS transitions on the element.
+        requestAnimationFrame(()=>{
+            if (hadInlineTransition) {
+                element.style.setProperty("transition", hadInlineTransition, hadPriority);
+            } else {
+                element.style.removeProperty("transition");
+            }
+        });
+    }
+}
+function tryGet(fn, fallback) {
+    try {
+        return fn();
+    } catch (unused) {
+        return fallback;
+    }
+}
+/**
+ * Dispatches a resize event on the given target.
+ * @param target - The target to dispatch the resize event on. Defaults to window.
+ */ function dispatchResizeEvent(target) {
+    if (target === void 0) target = window;
+    target.dispatchEvent(new CustomEvent("resize", {
+        detail: {
+            source: "q-docking"
+        }
+    }));
+}
+export { DOCKED_DOCUMENT_ATTRIBUTE, DOCKED_MODE, DOCKED_TARGET_ATTRIBUTE, DOCKED_TOP_OFFSET_CSS_VARIABLE, DOCKED_VIEWPORT_WIDTH_CSS_VARIABLE, DOCKING_PROXY_MARKER, MOBILE_BREAKPOINT, Q_DOCKING_TAG_NAME, applyOnce, dispatchResizeEvent, isQualifiedOwnedShadowRoot, measureScrollbarWidth, tryGet, whenBodyAvailable, withTransitionsDisabled };

package/packs/widget/api/docking/viewport_lock.js ADDED Viewed

@@ -0,0 +1,488 @@
+import { __webpack_require__ } from "../../../../js/runtime.js";
+import { measureScrollbarWidth, whenBodyAvailable, DOCKING_PROXY_MARKER, DOCKED_DOCUMENT_ATTRIBUTE, applyOnce } from "./shared.js";
+import "../../../../widget/utils/native_globals.js";
+import { applyProxy } from "../../../../src/proxy.js";
+/* provided dependency */ var requestAnimationFrame = __webpack_require__(68034).gj;
+/* provided dependency */ var viewport_lock_setTimeout = __webpack_require__(68034).pS;
+/* provided dependency */ var __nativeWindowAddEventListener = __webpack_require__(68034).zh;
+/* eslint-disable rulesdir/css-units */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Activates the calc-based padding override on `<body>` and the
+ * `padding: 0` override on `<html>` (see `getStyles()`). Stamped on both
+ * so body content starts at the same vertical position the host page
+ * rendered at: html.padding-top + body.margin-top + body.padding-top are
+ * absorbed into body.padding-top.
+ */ const MARGIN_SWAP_ATTRIBUTE = "data-q-margin-swapped";
+/** Activates `overflow: clip !important` on a detected scroll trap. */ const OVERFLOW_TRAP_ATTRIBUTE = "data-q-overflow-trap";
+/** Activates `background: transparent !important` when body computes to plain white. */ const BACKGROUND_OVERRIDE_ATTRIBUTE = "data-q-bg-override";
+function createViewportLock() {
+    const state = {
+        scrollbarWidth: 0,
+        pendingScroll: null,
+        scrollReplayScheduled: false
+    };
+    return {
+        init () {
+            state.scrollbarWidth = measureScrollbarWidth();
+            state.pendingScroll = capturePreDockingScroll();
+            installScrollProxy();
+        },
+        reEvaluate () {
+            initMarginSwap();
+            initOverflowTrap();
+            initBackgroundOverride();
+            if (state.pendingScroll) {
+                restoreScroll(state.pendingScroll);
+                state.pendingScroll = null;
+            }
+            // Docking makes <body> the scroll container and forwards its scroll to
+            // window/document (see installScrollProxy), but nothing fires that first
+            // event — so host code that only positions itself on scroll (sticky /
+            // hide-on-scroll bars, scroll-anchored ad slots) stays in its pre-scroll
+            // default. Replay an initial scroll so it settles for the current docked
+            // scroll position.
+            if (!state.scrollReplayScheduled) {
+                state.scrollReplayScheduled = true;
+                replayInitialScroll();
+            }
+        },
+        getStyles () {
+            return /* css */ "\n        html {\n          display: block !important;\n          position: relative !important;\n          contain: layout inline-size !important;\n          height: 100dvh !important;\n          overflow: hidden !important;\n          margin-top: 0 !important;\n        }\n        body {\n          display: block !important;\n          position: relative !important;\n          overflow-x: hidden !important;\n          overflow-y: auto !important;\n          height: 100% !important;\n          width: calc(100% + " + state.scrollbarWidth + "px) !important;\n          max-width: calc(100% + " + state.scrollbarWidth + "px) !important;\n          /* The overflow rules above make body the scroll container; inherit\n             <html>'s scroll-behavior so anchor nav / scrollIntoView() keep the\n             host's smooth scroll instead of body's UA-default 'auto'. */\n          scroll-behavior: inherit !important;\n        }\n        [" + OVERFLOW_TRAP_ATTRIBUTE + "] {\n          /* clip: not a scroll container (wheel passes through to body)\n             while preserving the host's intentional clipping. */\n          overflow: clip !important;\n          /* clip does NOT establish a block formatting context, so a host\n             that relied on its own 'overflow: hidden'/'auto' to contain a\n             floated child (e.g. a 'float: left' main) loses that containment\n             once we override to clip — the child escapes and the trap\n             collapses to near-zero height, clipping the page blank.\n             'contain: layout' re-establishes an independent formatting context\n             that contains the float without turning the element into a scroll\n             container. */\n          contain: layout !important;\n        }\n        html[" + MARGIN_SWAP_ATTRIBUTE + "] {\n          padding: 0 !important;\n        }\n        body[" + MARGIN_SWAP_ATTRIBUTE + "] {\n          margin-top: 0px !important;\n          padding-top: calc(\n            var(--q-orig-padding-top, 0px) +\n            var(--q-orig-margin-top, 0px) +\n            var(--q-html-orig-padding-top, 0px)\n          ) !important;\n        }\n        [" + BACKGROUND_OVERRIDE_ATTRIBUTE + "] {\n          background: transparent !important;\n        }\n      ";
+        }
+    };
+}
+// ============================================================================
+// Scroll Capture / Restore
+// ============================================================================
+/**
+ * Falls through window → documentElement → body to tolerate environments
+ * where an earlier integration already hoisted the scroll onto body.
+ */ function capturePreDockingScroll() {
+    var _document_body, _document_body1;
+    const scrollTop = window.scrollY || document.documentElement.scrollTop || ((_document_body = document.body) == null ? void 0 : _document_body.scrollTop) || 0;
+    const scrollLeft = window.scrollX || document.documentElement.scrollLeft || ((_document_body1 = document.body) == null ? void 0 : _document_body1.scrollLeft) || 0;
+    return {
+        scrollTop,
+        scrollLeft
+    };
+}
+function restoreScroll(pos) {
+    const { body } = document;
+    if (!body) return;
+    // "instant" overrides body's inherited (possibly smooth) scroll-behavior so
+    // the restore jumps to the captured pre-dock offset rather than animating.
+    if (typeof body.scrollTo === "function") {
+        body.scrollTo({
+            top: pos.scrollTop,
+            left: pos.scrollLeft,
+            behavior: "instant"
+        });
+    } else {
+        // Environments without Element.scrollTo (e.g. jsdom): set offsets directly.
+        body.scrollTop = pos.scrollTop;
+        body.scrollLeft = pos.scrollLeft;
+    }
+}
+/**
+ * Dispatches `scroll` on `document` + `window` (the same targets the scroll
+ * proxy forwards body scrolls to) so scroll-driven host code recomputes its
+ * position against the docked scroll container. This mirrors the synthetic
+ * `resize` viewport_resize fires at init.
+ *
+ * Fired immediately, next frame, and on a short ramp: ad / widget scripts
+ * routinely attach their scroll listeners well after `load`, so a single
+ * dispatch at init would miss them and leave the widget parked in its
+ * pre-scroll default. Each dispatch is a bare event with no `scrollTo`, so
+ * handlers read the current scroll offset — re-firing later is harmless even
+ * if the user has since scrolled.
+ *
+ * The ramped re-fires are gated on docking still being active: if the widget
+ * is torn down (avatar-join-timeout failover, disable) before a timer elapses,
+ * we skip it rather than dispatch stray `scroll` events on the host page after
+ * we're gone. The immediate + next-frame fires run synchronously here, before
+ * any teardown, so they are unconditional.
+ */ function replayInitialScroll() {
+    const fire = ()=>{
+        document.dispatchEvent(new Event("scroll"));
+        window.dispatchEvent(new Event("scroll"));
+    };
+    const fireIfDocked = ()=>{
+        if (!document.documentElement.hasAttribute(DOCKED_DOCUMENT_ATTRIBUTE)) return;
+        fire();
+    };
+    fire();
+    requestAnimationFrame(fire);
+    for (const delay of [
+        150,
+        400,
+        900,
+        1600
+    ]){
+        viewport_lock_setTimeout(fireIfDocked, delay);
+    }
+}
+// ============================================================================
+// DOM Write Helpers
+// ============================================================================
+/**
+ * Treats unset / `0px` as zero. getComputedStyle canonicalises zero lengths
+ * to `"0px"`; the empty-string branch covers jsdom / detached-element cases.
+ */ function isZeroLength(cssValue) {
+    return cssValue === "" || cssValue === "0px";
+}
+// ============================================================================
+// Margin Swap
+// ============================================================================
+/**
+ * Captures the host's original top spacing (html.padding-top + body.margin-top
+ * + body.padding-top) into CSS vars on body for the calc-based swap in
+ * getStyles(). Runs immediately when body is available, then re-runs whenever
+ * host code mutates body's class or style so customer themes / runtime
+ * stylesheet changes flow through.
+ */ function initMarginSwap() {
+    whenBodyAvailable((body)=>{
+        swapMarginWithPadding(body);
+        observeBodyAttributes(body, "" + DOCKING_PROXY_MARKER + "_margin_swap_observer", ()=>swapMarginWithPadding(body));
+        // An early pass (body parsed before the host's render-blocking / async
+        // stylesheets have loaded) reads the UA-default body margin (e.g. 8px)
+        // instead of the host's real reset, baking that phantom spacing into
+        // padding-top. Stylesheet loads don't mutate body's class/style, so the
+        // observer above never fires the correction. Re-run once the document is
+        // fully loaded and styles have settled: swapMarginWithPadding is
+        // idempotent and self-clears when the settled margin is zero.
+        if (document.readyState !== "complete") {
+            __nativeWindowAddEventListener("load", ()=>swapMarginWithPadding(body), {
+                once: true
+            });
+        }
+    });
+}
+function swapMarginWithPadding(body) {
+    // Late observer callbacks can fire after the document is gone (in-flight
+    // microtasks during teardown). Bail rather than blow up.
+    if (typeof document === "undefined" || !document.documentElement) return;
+    const html = document.documentElement;
+    // Remove the gated attribute so getComputedStyle returns the host's true
+    // values rather than our zeroed override.
+    body.removeAttribute(MARGIN_SWAP_ATTRIBUTE);
+    html.removeAttribute(MARGIN_SWAP_ATTRIBUTE);
+    // Read phase — snapshot everything before any writes so a single layout
+    // flush (triggered by the first getComputedStyle) covers all three reads.
+    const bodyComputed = getComputedStyle(body);
+    const htmlComputed = getComputedStyle(html);
+    const bodyMarginTop = bodyComputed.getPropertyValue("margin-top");
+    const bodyPaddingTop = bodyComputed.getPropertyValue("padding-top");
+    const htmlPaddingTop = htmlComputed.getPropertyValue("padding-top");
+    // Nothing to absorb: the gated body calc would resolve to body's existing
+    // padding-top and the html `padding: 0` override is a no-op. Skip the
+    // attribute stamp and clear any vars left over from a prior non-zero pass.
+    if (isZeroLength(bodyMarginTop) && isZeroLength(htmlPaddingTop)) {
+        body.style.removeProperty("--q-orig-margin-top");
+        body.style.removeProperty("--q-orig-padding-top");
+        body.style.removeProperty("--q-html-orig-padding-top");
+        return;
+    }
+    body.style.setProperty("--q-orig-margin-top", bodyMarginTop);
+    body.style.setProperty("--q-orig-padding-top", bodyPaddingTop);
+    body.style.setProperty("--q-html-orig-padding-top", htmlPaddingTop);
+    body.setAttribute(MARGIN_SWAP_ATTRIBUTE, "");
+    html.setAttribute(MARGIN_SWAP_ATTRIBUTE, "");
+}
+// ============================================================================
+// Overflow Trap
+// ============================================================================
+/**
+ * Detects full-page-shell scroll traps so the lock stylesheet can override
+ * their overflow to visible — in docked mode body is the scroll container
+ * and would see no scrollable content because the trap clips its tall
+ * descendants. Idempotent: each pass clears existing marks and re-scans.
+ */ function initOverflowTrap() {
+    whenBodyAvailable((body)=>{
+        markOverflowTraps(body);
+        observeBodyChildList(body);
+    });
+}
+/** Bounds the MutationObserver's lifetime so long-lived pages don't keep re-scanning. */ const OVERFLOW_TRAP_OBSERVER_LIFETIME_MS = 5000;
+/**
+ * Re-runs {@link markOverflowTraps} when an SPA root mounts as a body child.
+ * `childList: true` without subtree keeps the observer narrow — SPA roots
+ * mount at body level, while deeper churn (carousels, focus rings) doesn't
+ * fire. Skipped after `load`: re-entry via reEvaluate scans synchronously.
+ */ function observeBodyChildList(body) {
+    if (document.readyState === "complete") return;
+    applyOnce(body, "" + DOCKING_PROXY_MARKER + "_overflow_trap_observer", (b)=>{
+        const observer = new MutationObserver(()=>markOverflowTraps(b));
+        observer.observe(b, {
+            childList: true
+        });
+        viewport_lock_setTimeout(()=>observer.disconnect(), OVERFLOW_TRAP_OBSERVER_LIFETIME_MS);
+    });
+}
+/**
+ * Walk depth cap. Covers SPA shells that nest their scroll trap a few
+ * levels under body (e.g. drawer containers inside a wrapper). 6 covers
+ * every shell seen in the visual-regression suite.
+ */ const OVERFLOW_TRAP_MAX_DEPTH = 6;
+/**
+ * Height (as a multiple of the viewport) above which a full-width, in-flow
+ * clipper with no overflowing content is treated as a page-shell pass-through
+ * and opened up. Sits above 1.0× so a viewport-height hero/banner that clips
+ * its art keeps its clip, but low enough to catch tall content sections
+ * (~1.4× viewport) that would otherwise trap the wheel.
+ */ const SHELL_PASS_THROUGH_VIEWPORT_RATIO = 1.25;
+/**
+ * Walks body's subtree post-order, marking each qualifying scroll trap. Post-
+ * order is load-bearing: marking an inner trap exposes its previously-clipped
+ * overflow to the ancestor (the next layout read forces the browser to flush
+ * the descendant's CSS override), so the ancestor's `scrollHeight` reflects
+ * the propagated value on the same walk. See {@link isOverflowTrap} for the
+ * qualifying criteria.
+ */ function markOverflowTraps(body) {
+    const viewportHeight = window.innerHeight;
+    const viewportWidth = window.innerWidth;
+    const dims = {
+        minH: viewportHeight * 0.95,
+        minW: viewportWidth * 0.95,
+        shellH: viewportHeight * SHELL_PASS_THROUGH_VIEWPORT_RATIO
+    };
+    // Clear stale marks so an element that no longer qualifies (e.g. its
+    // overflow changed) loses its attribute on this pass.
+    for (const el of body.querySelectorAll("[" + OVERFLOW_TRAP_ATTRIBUTE + "]")){
+        el.removeAttribute(OVERFLOW_TRAP_ATTRIBUTE);
+    }
+    const visit = (el, depth)=>{
+        if (depth < OVERFLOW_TRAP_MAX_DEPTH) {
+            for (const child of el.children){
+                if (child instanceof HTMLElement) visit(child, depth + 1);
+            }
+        }
+        if (isOverflowTrap(el, depth, dims)) {
+            el.setAttribute(OVERFLOW_TRAP_ATTRIBUTE, "");
+        }
+    };
+    for (const child of body.children){
+        if (child instanceof HTMLElement) visit(child, 1);
+    }
+}
+function isOverflowTrap(el, depth, dims) {
+    const { overflowY, position } = getComputedStyle(el);
+    // Depth=1 permissive case: opens up wrappers that are empty at init and
+    // only acquire scrolling content later (skips width/current-overflow
+    // checks since layout numbers may not be meaningful yet).
+    if (depth === 1 && /clip|hidden/.test(overflowY) && el.offsetHeight >= dims.minH) {
+        return true;
+    }
+    const isClipping = /clip|hidden|auto|scroll/.test(overflowY);
+    if (!isClipping) return false;
+    // jsdom returns "" for position where real browsers return "static" — treat
+    // both as in-flow. Explicit non-flow (absolute/fixed/sticky) excludes.
+    if (position && position !== "static" && position !== "relative") return false;
+    if (el.offsetWidth < dims.minW) return false;
+    // Active trap: full-size clipper with currently-overflowing content.
+    // 4px slack covers sub-pixel rounding and scrollbar-gutter reservation.
+    if (el.offsetHeight >= dims.minH && el.scrollHeight > el.clientHeight + 4) {
+        return true;
+    }
+    // Page-shell pass-through: tall clipper whose scrollHeight === clientHeight
+    // because its own height accommodates its content. Must still be opened up:
+    // Chromium's wheel pipeline stops at any `overflow != visible` even with no
+    // scrollable content. The viewport-ratio threshold distinguishes such a
+    // section from a viewport-height hero that clips its art (≤1.0×, kept
+    // clipped) — see SHELL_PASS_THROUGH_VIEWPORT_RATIO.
+    return el.offsetHeight >= dims.shellH;
+}
+// ============================================================================
+// Background Override
+// ============================================================================
+/**
+ * Opt-in via attribute so pages with intentional body backgrounds keep their
+ * own. Only opts in on plain white (the typical "no background set" case).
+ * Re-runs on every reEvaluate and whenever host code mutates body's class or
+ * style, so late-loaded customer styles / runtime theming flip the attribute
+ * back off without waiting for the next poll.
+ */ function initBackgroundOverride() {
+    whenBodyAvailable((body)=>{
+        applyBackgroundOverride(body);
+        observeBodyAttributes(body, "" + DOCKING_PROXY_MARKER + "_bg_override_observer", ()=>applyBackgroundOverride(body));
+    });
+}
+function applyBackgroundOverride(element) {
+    // Remove first so getComputedStyle sees the host page's real background.
+    element.removeAttribute(BACKGROUND_OVERRIDE_ATTRIBUTE);
+    const computed = getComputedStyle(element);
+    const isWhite = computed.backgroundColor === "rgb(255, 255, 255)" || computed.backgroundColor === "rgba(255, 255, 255, 1)";
+    const hasNoImage = computed.backgroundImage === "none" || computed.backgroundImage === "";
+    if (isWhite && hasNoImage) {
+        element.setAttribute(BACKGROUND_OVERRIDE_ATTRIBUTE, "");
+    }
+}
+// ============================================================================
+// Body Attribute Observer (shared)
+// ============================================================================
+/**
+ * Installs a long-lived MutationObserver on `body`'s class/style attributes
+ * so `callback` re-runs whenever the host mutates either. applyOnce keeps
+ * it one-per-marker across reEvaluate calls.
+ *
+ * Disconnects around the callback so style writes made by the callback
+ * itself (e.g. CSS-var writes) don't self-trigger an infinite loop —
+ * attributeFilter excludes our data-q-* writes but not inline-style writes.
+ *
+ * The `observe` call is in a finally so a thrown callback still leaves us
+ * watching for the next mutation. Otherwise an unexpected style shape on
+ * one cycle would permanently sideline the corrective logic for the rest
+ * of the session.
+ */ function observeBodyAttributes(body, marker, callback) {
+    applyOnce(body, marker, (b)=>{
+        const opts = {
+            attributes: true,
+            attributeFilter: [
+                "class",
+                "style"
+            ]
+        };
+        const observer = new MutationObserver(()=>{
+            observer.disconnect();
+            try {
+                callback();
+            } finally{
+                observer.observe(b, opts);
+            }
+        });
+        observer.observe(b, opts);
+    });
+}
+// ============================================================================
+// Scroll Proxy
+// ============================================================================
+/**
+ * Redirects scroll APIs on documentElement/window to document.body (the
+ * docked scroll container) and forwards body scroll events to document/window
+ * so customer listeners fire transparently. Live getters keep the proxy
+ * working when installed before `<body>` exists (snippet in `<head>`).
+ */ function installScrollProxy() {
+    const { documentElement } = document;
+    // True while a scroll started via the proxied APIs below is awaiting its
+    // `scroll` event, so the listener can tell it from genuine user input. The
+    // generation counter lets a deferred reset clear a write that fires no event
+    // without clobbering a newer write, and hoisting keeps `no-loop-func` happy.
+    let programmaticScrollPending = false;
+    let programmaticScrollGeneration = 0;
+    const markProgrammaticScroll = ()=>{
+        programmaticScrollPending = true;
+        const generation = programmaticScrollGeneration += 1;
+        requestAnimationFrame(()=>{
+            if (generation === programmaticScrollGeneration) {
+                programmaticScrollPending = false;
+            }
+        });
+    };
+    for (const prop of [
+        "scrollHeight",
+        "scrollWidth"
+    ]){
+        applyProxy(documentElement, prop, {
+            get () {
+                var _ref;
+                var _document_body;
+                return (_ref = (_document_body = document.body) == null ? void 0 : _document_body[prop]) != null ? _ref : 0;
+            }
+        });
+    }
+    for (const prop of [
+        "scrollTop",
+        "scrollLeft"
+    ]){
+        applyProxy(documentElement, prop, {
+            get () {
+                var _ref;
+                var _document_body;
+                return (_ref = (_document_body = document.body) == null ? void 0 : _document_body[prop]) != null ? _ref : 0;
+            },
+            set (val) {
+                if (document.body) {
+                    markProgrammaticScroll();
+                    document.body[prop] = val;
+                }
+            }
+        });
+    }
+    const proxyMethod = (method)=>function() {
+            for(var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++){
+                args[_key] = arguments[_key];
+            }
+            var _document_body;
+            markProgrammaticScroll();
+            return (_document_body = document.body) == null ? void 0 : _document_body[method](...args);
+        };
+    window.scrollTo = proxyMethod("scrollTo");
+    window.scrollBy = proxyMethod("scrollBy");
+    window.scroll = proxyMethod("scroll");
+    documentElement.scrollTo = proxyMethod("scrollTo");
+    documentElement.scrollBy = proxyMethod("scrollBy");
+    documentElement.scroll = proxyMethod("scroll");
+    applyProxy(window, "scrollY", {
+        get () {
+            var _ref;
+            var _document_body;
+            return (_ref = (_document_body = document.body) == null ? void 0 : _document_body.scrollTop) != null ? _ref : 0;
+        }
+    });
+    applyProxy(window, "pageYOffset", {
+        get () {
+            var _ref;
+            var _document_body;
+            return (_ref = (_document_body = document.body) == null ? void 0 : _document_body.scrollTop) != null ? _ref : 0;
+        }
+    });
+    applyProxy(window, "scrollX", {
+        get () {
+            var _ref;
+            var _document_body;
+            return (_ref = (_document_body = document.body) == null ? void 0 : _document_body.scrollLeft) != null ? _ref : 0;
+        }
+    });
+    applyProxy(window, "pageXOffset", {
+        get () {
+            var _ref;
+            var _document_body;
+            return (_ref = (_document_body = document.body) == null ? void 0 : _document_body.scrollLeft) != null ? _ref : 0;
+        }
+    });
+    applyProxy(document, "scrollingElement", {
+        get () {
+            return document.body;
+        }
+    });
+    whenBodyAvailable((body)=>{
+        applyOnce(body, "" + DOCKING_PROXY_MARKER + "_scroll", (b)=>{
+            b.addEventListener("scroll", (event)=>{
+                // Only the body container's own scroll is the docked viewport
+                // scroll; let descendant scroll containers pass through.
+                if (event.target !== b) return;
+                // Read and clear before re-dispatching so a forwarded listener that
+                // scrolls programmatically doesn't taint this decision.
+                const wasProgrammatic = programmaticScrollPending;
+                programmaticScrollPending = false;
+                // Mirror non-docked semantics: a viewport scroll fires on document
+                // and window, not on the body/html elements.
+                document.dispatchEvent(new Event("scroll"));
+                window.dispatchEvent(new Event("scroll"));
+                // Hide our own programmatic scroll from element-level handlers so a
+                // host "cancel on user scroll" guard can't abort it; real user
+                // scrolls still reach them.
+                if (wasProgrammatic) event.stopImmediatePropagation();
+            }, {
+                capture: true,
+                passive: true
+            });
+        });
+    });
+}
+export { createViewportLock };