dsh-any-background 0.3.8 → 0.3.9

package/lib/client.js

@@ -57,6 +57,12 @@ window.__ModuleLoader__.load({
 			uiProduced: "产出物/高亮内容",
 			uiHeader: "顶栏选项",
 			uiHeaderBar: "标题栏",
+			captionInkLabel: "标题条带文字",
+			captionInkHint: "桌面端顶部那条标题带上的文字（原生「应用 / 编辑」菜单与侧栏开合按钮）由谁上色。条带是侧栏材质压在壁纸上的结果，两者可能一个深一个浅。",
+			captionInkAuto: "自动",
+			captionInkTheme: "跟随主题",
+			captionInkWhite: "始终白色",
+			captionInkBlack: "始终黑色",
 			fontPageTitle: "字体与描边",
 			fontTitle: "自定义字体",
 			fontHint: "支持 ttf/otf/woff/woff2 字体文件（上限 100MB），将应用到整个界面的文字；代码块的等宽字体保持不变。中文字体通常有几十 MB，首次上传与刷新加载需要片刻",
@@ -249,6 +255,12 @@ window.__ModuleLoader__.load({
 			uiProduced: "Produced / highlights",
 			uiHeader: "Header popovers",
 			uiHeaderBar: "Header bar",
+			captionInkLabel: "Caption strip text",
+			captionInkHint: "Who paints the text on the desktop caption strip — the native 「应用 / 编辑」 menu bar and the sidebar toggle. The strip is the sidebar material over the wallpaper, so it can end up on the opposite side of the theme.",
+			captionInkAuto: "Auto",
+			captionInkTheme: "Follow theme",
+			captionInkWhite: "Always white",
+			captionInkBlack: "Always black",
 			fontPageTitle: "Font & outline",
 			fontTitle: "Custom font",
 			fontHint: "Accepts ttf/otf/woff/woff2 files (up to 100MB) and applies them to the whole interface; code blocks keep their monospace stack. CJK fonts routinely span tens of MB, so the first upload and each reload take a moment",
@@ -518,6 +530,7 @@ window.__ModuleLoader__.load({
 			producedOpacity: .5,
 			headerOpacity: .5,
 			headerBarOpacity: .5,
+			captionInk: "auto",
 			profiles: [],
 			rotation: {
 				enabled: false,
@@ -539,6 +552,17 @@ window.__ModuleLoader__.load({
 			activeProfile: null
 		};
 		const clamp01 = (n, def) => typeof n === "number" ? Math.min(1, Math.max(0, n)) : def;
+		/** One place decides what a stored / adopted 「标题栏文字」 value means: anything the
+		*  host half or an older config file did not name is `auto`, which is 0.3.8's behaviour. */
+		const CAPTION_INK_MODES = [
+			"auto",
+			"theme",
+			"white",
+			"black"
+		];
+		function adoptCaptionInk(v) {
+			return CAPTION_INK_MODES.includes(v) ? v : DEFAULT_CONFIG.captionInk;
+		}
 		let cfg = {
 			...DEFAULT_CONFIG,
 			opacities: { ...DEFAULT_CONFIG.opacities },
@@ -732,6 +756,10 @@ window.__ModuleLoader__.load({
 		function rHeaderBarOpacity() {
 			return clamp01(cfg.headerBarOpacity, DEFAULT_CONFIG.headerBarOpacity);
 		}
+		/** Who owns the desktop caption strip's chrome ink — see `CaptionInkMode`. */
+		function rCaptionInk() {
+			return adoptCaptionInk(cfg.captionInk);
+		}
 		function rBgState() {
 			return cfg.bgState;
 		}
@@ -968,6 +996,7 @@ window.__ModuleLoader__.load({
 				producedOpacity: clamp01(c.producedOpacity, DEFAULT_CONFIG.producedOpacity),
 				headerOpacity: clamp01(c.headerOpacity, DEFAULT_CONFIG.headerOpacity),
 				headerBarOpacity: clamp01(c.headerBarOpacity, DEFAULT_CONFIG.headerBarOpacity),
+				captionInk: adoptCaptionInk(c.captionInk),
 				profiles: adoptProfiles(c.profiles),
 				rotation: adoptRotation(c.rotation),
 				schedule: adoptSchedule(c.schedule),
@@ -1304,8 +1333,9 @@ window.__ModuleLoader__.load({
 		*   painting element. A 15th file names the same token without consuming it:
 		*   `ui-theme/src/styles/gradient-shadow-text.css` DECLARES it on `body` —
 		*   `blur(40px) saturate(150%)`, no media query — which is exactly why writing the
-		*   token on a menu with a `none` fallback deletes a frost the host always had
-		*   (see `CARD_FROST_GATE` in `wallpaper.ts`). `MenuSurface.tsx` / `.module.css` are
+		*   token on a menu with a `none` fallback deletes a frost the host always had.
+		*   That is now the intended reading of a 0 on the menu blur sliders — see the note
+		*   above `popoverBlurRule` in `wallpaper.ts`. `MenuSurface.tsx` / `.module.css` are
 		*   byte-identical from rc.2 through `0.2.1-alpha.2`, and the consumer set moved only
 		*   in line numbers (the same 15 files at every tag in the table, checked per tag).
 		*
@@ -2161,16 +2191,18 @@ window.__ModuleLoader__.load({
 		* A header dropdown can only be open while its trigger reports
 		* `aria-expanded="true"`, and opening one is what mounts the popover. So a
 		* popover tag is maintained as: "there is at least one expanded header trigger,
-		* AND this popover is not owned by another group". Popovers are only ever
+		* AND this popover is a header candidate" — see `isHeaderSurface` for the two
+		* shapes that qualify (portaled to `<body>`, or mounted inside one of the
+		* header's own slot anchors) and for what stays foreign. Popovers are only ever
 		* tagged/released on a change of that combined state, which makes the tag
 		* self-consistent and idempotent.
 		*
 		* The one hazard is a popover that is open for an unrelated reason (a composer
-		* menu, a hover card) *while* a header trigger stays expanded. Such a popover
-		* is not a candidate: it is excluded by `ownsForeignSurface`, which skips any
-		* popover carrying markers of a different slider group. In practice header
-		* dropdowns are transient (opening one closes the others), so this is a guard
-		* rather than the common path.
+		* menu, a hover card) *while* a header trigger stays expanded. Such a popover is
+		* not a candidate: it is neither portaled nor a descendant of a header anchor,
+		* and the composer's in-place lists keep belonging to the card group. In practice
+		* header dropdowns are transient (opening one closes the others), so this is a
+		* guard rather than the common path.
 		*
 		* THE SURFACE MARKER IS PART OF THE CANDIDATE SET (`0.2.1-alpha.3` and up).
 		* That release moved the background-job list onto the shared `MenuSurface`, whose
@@ -2209,20 +2241,54 @@ window.__ModuleLoader__.load({
 			for (const anchor of document.querySelectorAll(headerSlotAnchors())) if (anchor.querySelector("[aria-expanded=\"true\"]") !== null) return true;
 			return false;
 		}
-		/** Surfaces that belong to a different slider group and must never be claimed.
-		*  `_denseList` without `_portal` is the in-place card-side dense menu, an
-		*  `_ioCard`/`_menu`-classed body-level list belongs elsewhere, and a modal is
-		*  its own surface. */
-		function ownsForeignSurface(el) {
-			if (el.getAttribute("aria-modal") === "true") return true;
-			return el.parentElement !== document.body;
+		/** Whether this popover can belong to the header.
+		*
+		*  Two shapes, and the second one is the reason this is not just "portaled to body":
+		*  `session-log-export/HeaderAction.tsx` renders its `Menu` WITHOUT the `portal` prop,
+		*  so the card is mounted in place, inside `[data-slot="conversation.session.header
+		*  .utilities"]` — a DOM descendant of the row, exactly where a header trigger's own
+		*  popover belongs. Keyed on `parentElement === body` alone it was never claimable, and
+		*  the only thing that styled it at all was the header group's
+		*  `[role="menu"][class*="_denseList"]:not([class*="_portal"])` arm — which dies the
+		*  moment the host drops `dense` (or adds a header popover that is not a dense menu),
+		*  and leaves the surface following the card slider while it sits in the title row.
+		*
+		*  A popover that is neither portaled nor inside a header anchor stays foreign: that is
+		*  the composer's in-place lists (permission / command / model), which the card group
+		*  owns and this group must never reach. */
+		function isHeaderSurface(el) {
+			if (el.getAttribute("aria-modal") === "true") return false;
+			return el.parentElement === document.body || el.closest(headerSlotAnchors()) !== null;
 		}
 		let observer = null;
-		let raf = null;
+		let pending = null;
+		/** False once the effect is torn down, so a pass already queued on the microtask queue
+		*  cannot re-mark a popover after the teardown cleared it. */
+		let active = false;
+		/** Coalesce the observer's batches into ONE pass, but flush it on the microtask queue
+		*  rather than a animation frame.
+		*
+		*  The frame version was the bug, not the batching: `requestAnimationFrame` callbacks
+		*  do not run while a window is not rendering — a hidden tab, an occluded or minimized
+		*  desktop window, a background Electron surface — and a queued frame never fires, so
+		*  the tag never lands and the 「顶栏选项」 pair silently keeps whatever the card group
+		*  gave the panel. Observed live: with the page not painting, an open header menu stayed
+		*  `data-dsh-any-header-popover`-less indefinitely, and the same menu was tagged the
+		*  moment rAF was made to run. A `MutationObserver` callback is already delivered once
+		*  per batch at microtask time, so a microtask flush coalesces exactly as well and has no
+		*  dependency on the compositor at all — and it lands in the SAME frame the popover
+		*  mounts, which also removes the one-frame flash of card styling on open. */
+		function schedule() {
+			if (pending !== null || !active) return;
+			pending = Promise.resolve().then(() => {
+				pending = null;
+				if (active) refreshHeaderPopovers();
+			});
+		}
 		/** Recompute tags from the current open state. */
 		function refreshHeaderPopovers() {
 			const open = headerTriggerOpen();
-			const candidates = [...document.querySelectorAll(POPOVER_SELECTOR)].filter((el) => !ownsForeignSurface(el));
+			const candidates = [...document.querySelectorAll(POPOVER_SELECTOR)].filter(isHeaderSurface);
 			if (!open) {
 				for (const el of document.querySelectorAll(`[${HEADER_POPOVER_ATTR}]`)) el.removeAttribute(HEADER_POPOVER_ATTR);
 				return;
@@ -2230,16 +2296,10 @@ window.__ModuleLoader__.load({
 			for (const el of candidates) el.setAttribute(HEADER_POPOVER_ATTR, "");
 			for (const el of document.querySelectorAll(`[${HEADER_POPOVER_ATTR}]`)) if (!candidates.includes(el)) el.removeAttribute(HEADER_POPOVER_ATTR);
 		}
-		function schedule() {
-			if (raf !== null) return;
-			raf = window.requestAnimationFrame(() => {
-				raf = null;
-				refreshHeaderPopovers();
-			});
-		}
 		/** Start tagging. Returns a teardown that stops observing and clears markings. */
 		function startHeaderPopoverTagging() {
 			if (typeof MutationObserver === "undefined" || typeof document === "undefined") return () => {};
+			active = true;
 			refreshHeaderPopovers();
 			observer = new MutationObserver(schedule);
 			observer.observe(document.body, {
@@ -2249,12 +2309,9 @@ window.__ModuleLoader__.load({
 				attributeFilter: ["aria-expanded"]
 			});
 			return () => {
+				active = false;
 				observer?.disconnect();
 				observer = null;
-				if (raf !== null) {
-					window.cancelAnimationFrame(raf);
-					raf = null;
-				}
 				for (const el of document.querySelectorAll(`[${HEADER_POPOVER_ATTR}]`)) el.removeAttribute(HEADER_POPOVER_ATTR);
 			};
 		}
@@ -3610,16 +3667,40 @@ window.__ModuleLoader__.load({
 			if (rSchemeOverride() !== "auto") return genTokens(220, .04, scheme === "dark" ? .14 : .92, scheme).tokens;
 			return null;
 		}
-		/** Surface colors the opacity sliders fade when the plugin has NO palette of
-		*  its own (no picked color, no forced scheme), read live from the host's
-		*  resolved tokens on `:root` — the same trick applyPanelOverrides uses for the
-		*  workbench panel. Without this source the per-part alpha is never emitted at
-		*  all and every opacity slider looks inert until the user drags it once.
-		*  The sliders only ever supply the alpha: the host still decides the colors,
-		*  so a custom host skin survives. Returns null when the host exposes none. */
+		/** Surface colors the opacity sliders fade when the plugin has NO palette of its own
+		*  (no picked color, no forced scheme), read live from the host's own resolved tokens —
+		*  the same trick applyPanelOverrides uses for the workbench panel. The sliders only
+		*  ever supply the alpha: the host still decides the colors, so a custom host skin
+		*  survives. Returns null when the host exposes none.
+		*
+		*  SAMPLED ON `<body>`, NOT `:root`: `design-platform.css` declares this whole token set
+		*  inside a `body { … }` block (light at :166, dark at :284), and a custom property is
+		*  inherited DOWNWARD only — read off the root element every one of them is the empty
+		*  string, this function answers null, `applyCustomTokensNow` takes its `surfaces ===
+		*  null` exit, and on an install with no picked color every interface-opacity slider does
+		*  nothing at all (the frame never gets cleared either, so the wallpaper stays hidden).
+		*  Measured against the host's own declarations: `:root` → all five tokens empty,
+		*  `body` → all five resolve.
+		*
+		*  …AND CACHED PER HOST GENERATION, with our own sheet switched off while reading: the
+		*  plugin re-scopes these same names on `body`
+		*  (`body{--dsw-specific-menu:var(--dsh-any-op-menu)!important}`), so a second read after
+		*  the first write returns the plugin's OWN substituted literal — the surfaces would
+		*  freeze at whatever color they first sampled instead of following the host. The
+		*  generation key is what can flip the host's palette without anything in this plugin
+		*  moving: its dark-mode marker, and the platform attribute (`[data-platform='darwin']`
+		*  re-declares `--dsw-specific-menu`). */
+		let hostSurfaceSample = null;
 		function readHostOpacityTokens() {
-			if (typeof getComputedStyle === "undefined") return null;
-			const cs = getComputedStyle(document.documentElement);
+			if (typeof getComputedStyle === "undefined" || typeof document === "undefined") return null;
+			const body = document.body;
+			if (body === null) return null;
+			const key = `${body.getAttribute("data-ds-dark-theme") ?? ""}|${document.documentElement.getAttribute("data-platform") ?? ""}`;
+			if (hostSurfaceSample !== null && hostSurfaceSample.key === key) return hostSurfaceSample.map;
+			const sheet = tokenStyleEl;
+			const wasDisabled = sheet === null ? false : sheet.disabled;
+			if (sheet !== null) sheet.disabled = true;
+			const cs = getComputedStyle(body);
 			const out = {};
 			let found = false;
 			for (const g of OPACITY_TOKEN_GROUPS) for (const name of g.names) {
@@ -3628,7 +3709,12 @@ window.__ModuleLoader__.load({
 				out[name] = v;
 				found = true;
 			}
-			return found ? out : null;
+			if (sheet !== null) sheet.disabled = wasDisabled;
+			hostSurfaceSample = {
+				key,
+				map: found ? out : null
+			};
+			return hostSurfaceSample.map;
 		}
 		function applyCustomTokensNow(ops) {
 			const hasColor = rHasColor();
@@ -3708,34 +3794,30 @@ window.__ModuleLoader__.load({
 		function menuFrost(blurVar) {
 			return hostAdapter().menus.frostDecl(`var(${blurVar},none)`);
 		}
-		/** The `<html>` classes that let the two menu groups write their frost token at all.
+		/** The frost token, asserted ALWAYS — and what that means for the slider's bottom end.
 		*
-		*  WHY A GATE IS NEEDED AND `:where()` IS ENOUGH: the host declares its own menu frost
-		*  on `body` (`ui-theme/src/styles/gradient-shadow-text.css` —
-		*  `--dsw-menu-backdrop-filter: blur(40px) saturate(150%)`, no media query), and every
-		*  menu frosts from that INHERITED value, whether it filters itself (the background-job
-		*  `<ul>`) or hands the value to a `MenuSurface` `.material` child. An element's own
-		*  declaration always beats what it inherits, so writing the token with a `none`
-		*  fallback does not "add no blur" at slider 0 — it DELETES the host's frost. The
-		*  result is a faded menu with nothing behind it: the page shows through it crisp and
-		*  bright, so the popup stops reading as a raised surface at all. (This is a DIFFERENT
-		*  defect from the reported "the background-job list is under the conversation" one,
-		*  which is a stacking-context injury the row takes with its own frost — see the
-		*  `z-index` note on `HEADER_BAR_RULE`. Both were live at once on `0.2.0-rc.1`.)
-		*  `none` stays correct for the exempt group: `applyExemptDefaults` pins those
-		*  surfaces at alpha 1 alongside the cleared frost, so they are opaque by design.
+		*  The host declares its own menu frost on `body` (`ui-theme/src/styles/gradient-shadow-text.css`
+		*  — `--dsw-menu-backdrop-filter: blur(40px) saturate(150%)`, no media query), and every menu
+		*  frosts from that INHERITED value, whether it filters itself (the background-job `<ul>`) or
+		*  hands the value to a `MenuSurface` `.material` child. An element's own declaration always
+		*  beats what it inherits, so writing the token with a `none` fallback does not "add no blur"
+		*  at slider 0 — it DELETES the host's frost.
 		*
-		*  `:where()` keeps the gate free: this plugin's menu cascade is ORDERED (card group →
-		*  header group → exemptions) at equal specificity, and a class prefix with real
-		*  specificity would have lifted the card group over the exemption it must lose to. */
-		const CARD_FROST_GATE = "dab-card-frost";
-		const HEADER_FROST_GATE = "dab-header-frost";
-		/** Prefix every arm of a selector list with a `:where()` gate. A joined list is one
-		*  selector per entry, so prefixing the string once would gate only the first arm and
-		*  leave the rest always on. */
-		function gated(gate, selectors) {
-			return selectors.split(",").map((sel) => `:where(.${gate}) ${sel}`).join(",");
-		}
+		*  0.3.7 answered that with a `<html>` class gate (`dab-card-frost` / `dab-header-frost`) that
+		*  only let the declaration through while the slider was non-zero, so 0 meant "leave the host
+		*  alone". That was the wrong trade and this is the report that says so: with the gate on, the
+		*  slider's LOW end is its HIGH end — 0 renders the host's 40 px frost and 1 renders 1 px — so
+		*  the control reads as dead in both directions, and 「把模糊关掉」 is simply not reachable
+		*  (measured in `dsh web` with 顶栏选项 at 0/0: the open-in-app panel still came out a soft,
+		*  opaque-looking card, because what it was showing was the host's blur, not the plugin's).
+		*  The token is therefore asserted at every value, `none` included: **0 means no frost**.
+		*  Nothing loses the host look by accident, because the part DEFAULTS are 30 px — a stock
+		*  install is frosted like the host's and only an explicit drag to 0 clears it. The same is
+		*  already true of every other blur slider in this plugin (0 = off), which is the interface
+		*  consistency the gate broke.
+		*
+		*  `none` stays correct for the exempt group as well: `applyExemptDefaults` pins those surfaces
+		*  at alpha 1 alongside the cleared frost, so they are opaque by design. */
 		/** Declare EVERY token this release's menus can paint their fill from with the same
 		*  value. One slider, one value, every layer reached — and a token the host does not
 		*  read is inert, so this is safe to emit on a line that only needs one.
@@ -3749,7 +3831,7 @@ window.__ModuleLoader__.load({
 			return hostAdapter().menus.fillTokens.map((name) => `${name}:${value}`).join(";");
 		}
 		function popoverBlurRule() {
-			return `${gated(CARD_FROST_GATE, `${POPOVER_MENU_SEL},${MENU_MATERIAL_SEL}`)}{${menuFrost(CARD_BLUR_VAR)}}${POPOVER_OTHER_SEL}{${elementFrostDecl(`var(${CARD_BLUR_VAR},none)`)}}`;
+			return `${POPOVER_MENU_SEL},${MENU_MATERIAL_SEL}{${menuFrost(CARD_BLUR_VAR)}}${POPOVER_OTHER_SEL}{${elementFrostDecl(`var(${CARD_BLUR_VAR},none)`)}}`;
 		}
 		const INPUT_FROST_CLASS = "dab-input-frost";
 		const TAKEOVER_FROST_CLASS = "dab-takeover-frost";
@@ -3802,6 +3884,8 @@ window.__ModuleLoader__.load({
 		}
 		const MOBILE_HEADER_RULE = ".dsh-mobile-app-header{background:var(--dsh-any-op-bg,transparent)!important;backdrop-filter:var(--dsh-any-part-blur-global,none);-webkit-backdrop-filter:var(--dsh-any-part-blur-global,none)}";
 		const HEADER_BAR_CLASS = "dab-header-bar";
+		/** Added to the same row only while its blur is non-zero — see `HEADER_BAR_RULE`. */
+		const HEADER_BAR_FROST_CLASS = "dab-header-bar-frost";
 		const HEADER_BAR_ANCHOR = "[data-slot^=\"conversation.session.header\"]";
 		/** The session header bar, or null where this host has no such element.
 		*
@@ -3819,13 +3903,35 @@ window.__ModuleLoader__.load({
 			if (bar.className.includes("headerBlank")) return null;
 			return bar;
 		}
-		/** Exactly one owner: the row the current conversation mounted. A row that went
-		*  blank, or one the host replaced, must not keep a class from an earlier pass. */
 		let headerBarEl = null;
-		function claimHeaderBar(bar) {
-			if (headerBarEl !== null && headerBarEl !== bar) headerBarEl.classList.remove(HEADER_BAR_CLASS);
+		/** Exactly one owner: the row the current conversation mounted. A row that went
+		*  blank, or one the host replaced, must not keep a class — or a `position` — from an
+		*  earlier pass. `frost` decides whether the row also carries the underlay arm, and the
+		*  underlay's containing block is written inline only while it is needed. */
+		function releaseHeaderBar(bar) {
+			bar.classList.remove(HEADER_BAR_CLASS, HEADER_BAR_FROST_CLASS);
+			if (bar.getAttribute(TAKEOVER_POS_ATTR) === "1") {
+				bar.style.removeProperty("position");
+				bar.removeAttribute(TAKEOVER_POS_ATTR);
+			}
+		}
+		function claimHeaderBar(bar, frost) {
+			if (headerBarEl !== null && headerBarEl !== bar) releaseHeaderBar(headerBarEl);
+			if (bar === null) {
+				headerBarEl = null;
+				return;
+			}
 			headerBarEl = bar;
-			if (bar !== null) bar.classList.add(HEADER_BAR_CLASS);
+			bar.classList.add(HEADER_BAR_CLASS);
+			if (!frost) {
+				bar.classList.remove(HEADER_BAR_FROST_CLASS);
+				return;
+			}
+			if (getComputedStyle(bar).position === "static") {
+				bar.style.position = "relative";
+				bar.setAttribute(TAKEOVER_POS_ATTR, "1");
+			}
+			bar.classList.add(HEADER_BAR_FROST_CLASS);
 		}
 		/** The bar's paint. The variables are written by `applyHeaderBar`; the class is
 		*  only ever added when they are, so a host the plugin is not theming keeps its
@@ -3865,12 +3971,27 @@ window.__ModuleLoader__.load({
 		*  filter never had to be blamed for its anchoring). 10 sits in that gap: above 9, far
 		*  below 100, so a portaled list still covers the title row exactly as the host intends.
 		*
-		*  `z-index` needs no `position` here and none is written: the row is a flex ITEM of
-		*  `ConversationRoot .root{display:flex;flex-direction:column}` on every release in range,
-		*  and z-index applies to flex items as they are. Writing `position:relative` would also
-		*  make the row a containing block — and deciding a host box's positioning is the exact
-		*  race this plugin lost once already (issue #24). */
-		const HEADER_BAR_RULE = `.${HEADER_BAR_CLASS}{background:var(--dsh-any-op-header-bar,transparent)!important;backdrop-filter:var(--dsh-any-blur-header-bar,none);-webkit-backdrop-filter:var(--dsh-any-blur-header-bar,none);z-index:10}`;
+		*  `z-index` needs no `position` here and none is written by the BASE rule: the row is
+		*  a flex ITEM of `ConversationRoot .root{display:flex;flex-direction:column}` on every
+		*  release in range, and z-index applies to flex items as they are. Writing
+		*  `position:relative` would also make the row a containing block — and deciding a host
+		*  box's positioning is the exact race this plugin lost once already (issue #24).
+		*
+		*  THE FROST DOES NOT SIT ON THE ROW. That was the first version of this rule, and it
+		*  cost the row's own children their backdrop: `backdrop-filter` makes an element a
+		*  BACKDROP ROOT as well as a stacking context, so an in-place header popover (the
+		*  session-log `…` menu, which `HeaderAction.tsx` renders without `portal`) could only
+		*  ever blur what the row itself paints — a flat tint — and the 「标题栏」 blur slider
+		*  read as dead on exactly the panel that hangs off the row. `isolation:isolate` is a
+		*  stacking context WITHOUT being a backdrop root, so the frost now rides a `::before`
+		*  underlay like it does on every other host part this plugin filters (`PART_BLUR_RULE`,
+		*  `inputBlurRule`), and the row's children sample the wallpaper again. The underlay
+		*  needs the row to be its containing block, which is why the frost arm adds
+		*  `position:relative` — INLINE, only when the host left the row `static`, and marked
+		*  `data-dab-pos-patched` so only this writer takes it back: the same guard
+		*  `setBlur` uses, for the same reason (a stylesheet `position` would cascade against
+		*  whatever the host or another plugin decides that box's position is). */
+		const HEADER_BAR_RULE = `.${HEADER_BAR_CLASS}{background:var(--dsh-any-op-header-bar,transparent)!important;z-index:10}.${HEADER_BAR_FROST_CLASS}{isolation:isolate}.${HEADER_BAR_FROST_CLASS}::before{content:"";position:absolute;inset:0;z-index:-1;pointer-events:none;border-radius:inherit;-webkit-backdrop-filter:var(--dsh-any-blur-header-bar,none);backdrop-filter:var(--dsh-any-blur-header-bar,none)}`;
 		/** The 「标题栏」card's paint: the card's material at the card's opacity, empty
 		*  where the plugin is not theming. The conversation header row, the Windows
 		*  caption band, and — through the desktop preload's probe — the native
@@ -3889,7 +4010,7 @@ window.__ModuleLoader__.load({
 			const bar = discoverHeaderBar();
 			const paint = headerBarPaint(src);
 			if (paint === "") {
-				claimHeaderBar(null);
+				claimHeaderBar(null, false);
 				root.style.removeProperty("--dsh-any-op-header-bar");
 				root.style.removeProperty("--dsh-any-blur-header-bar");
 				applyNativeCaption(surfaces);
@@ -3899,7 +4020,7 @@ window.__ModuleLoader__.load({
 			const px = rBlurs().headerBar;
 			if (px > 0) root.style.setProperty("--dsh-any-blur-header-bar", `blur(${px}px)`);
 			else root.style.removeProperty("--dsh-any-blur-header-bar");
-			claimHeaderBar(bar);
+			claimHeaderBar(bar, px > 0);
 			applyNativeCaption(surfaces);
 		}
 		const CAPTION_FRAME_CLASS = "dab-frame-caption";
@@ -3911,7 +4032,7 @@ window.__ModuleLoader__.load({
 		const CAPTION_INK_ATTR = "data-dab-caption-ink";
 		/** The strip's chrome ink, and its collapsed-state variant.
 		*
-		*  WHY THIS IS NOT THE LABEL INK: the plugin flips the label tokens against the
+		*  WHY THIS IS NOT SIMPLY THE LABEL INK: the plugin flips the label tokens against the
 		*  PICKED PALETTE (white on a dark pick), but the caption band is that palette at
 		*  the sidebar/header-bar opacity OVER the wallpaper. At a low opacity the strip
 		*  is mostly wallpaper, so white ink lands on a light band and the toggle
@@ -3920,11 +4041,31 @@ window.__ModuleLoader__.load({
 		*  painted on: past ~85% opacity the surface dominates and the palette direction
 		*  is the truth; below it the wallpaper's brightness verdict decides.
 		*
+		*  WHY THAT DERIVATION IS NOT THE WHOLE ANSWER (issue #30): the same derivation makes
+		*  the native caption menubar (「应用 / 编辑」) black on a dark theme whose sidebar is
+		*  translucent over a bright wallpaper — the strip really is light there, so the strip
+		*  is right and the rest of the window is wrong, and the two reports of this same
+		*  situation asked for opposite outcomes. So the policy is the user's: 「标题栏文字」
+		*  picks the winner, and `auto` keeps the strip-following behaviour that fixed the
+		*  invisible toggle. `theme` returns null, which removes every ink declaration this
+		*  function feeds — the menubar and the sidebar's fixed controls then read the host's
+		*  own label tokens, exactly as they did before 0.3.8.
+		*
 		*  Returned as `{ ink, collapsedInk }` because the strip's material changes with
 		*  the sidebar: expanded it is the sidebar segment, collapsed it is the 「标题栏」
-		*  card's band. `null` means "no verdict and no palette direction" — leave the
-		*  host's ink alone. */
+		*  card's band. `null` means "no override" — either no verdict and no palette
+		*  direction, or the user asked for the theme's own ink. */
 		function captionInkPair() {
+			const mode = rCaptionInk();
+			if (mode === "theme") return null;
+			if (mode === "white") return {
+				ink: "#fff",
+				collapsedInk: "#fff"
+			};
+			if (mode === "black") return {
+				ink: "#000",
+				collapsedInk: "#000"
+			};
 			const verdict = rBgDark();
 			const inkIsWhite = rSchemeOverride() === "auto" ? rHasColor() ? rColorScheme() === "dark" : verdict : rScheme() === "dark";
 			if (inkIsWhite === null || inkIsWhite === void 0) return null;
@@ -4030,7 +4171,7 @@ window.__ModuleLoader__.load({
 			const fill = captionFill(src);
 			const paint = headerBarPaint(src) || fill;
 			const width = "var(--dsh-windows-sidebar-width,0px)";
-			const css = fill === "" ? "" : `${WCO_PROBE_SEL}{--dsw-specific-sidebar-fill:transparent}[data-windows-titlebar] .${CAPTION_FRAME_CLASS}::before{background:var(--dsh-any-op-header-bar,${paint})!important;backdrop-filter:var(--dsh-any-blur-header-bar,none);-webkit-backdrop-filter:var(--dsh-any-blur-header-bar,none);clip-path:inset(0 0 0 ${width});-webkit-clip-path:inset(0 0 0 ${width})}[data-windows-titlebar] .${CAPTION_FRAME_CLASS}::after{content:"";position:absolute;top:0;left:0;pointer-events:none;z-index:-1;width:${width};height:var(--dsh-windows-titlebar-height,40px);background:var(--dsh-any-op-sidebar,${fill});backdrop-filter:var(--dsh-any-blur-sidebar-band,none);-webkit-backdrop-filter:var(--dsh-any-blur-sidebar-band,none)}[data-windows-titlebar]:has([role="dialog"][aria-modal="true"]) .${CAPTION_FRAME_CLASS}::before,[data-windows-titlebar]:has([role="dialog"][aria-modal="true"]) .${CAPTION_FRAME_CLASS}::after{box-shadow:inset 0 0 0 9999px var(--dsw-alias-bg-mask-1,rgba(0,0,0,.24))}:root:has([data-sidebar-collapsed="true"]){--dsh-any-caption-ink:var(--dsh-any-caption-ink-collapsed,#fff)!important}[data-windows-titlebar] [data-windows-menu]{--dsw-alias-label-secondary:var(--dsh-any-caption-ink,#fff);--dsw-alias-label-primary:var(--dsh-any-caption-ink,#fff)}[data-windows-titlebar] .${FLAT_CENTER_CLASS}{border-top-left-radius:0!important}`;
+			const css = fill === "" ? "" : `${WCO_PROBE_SEL}{--dsw-specific-sidebar-fill:transparent}[data-windows-titlebar] .${CAPTION_FRAME_CLASS}::before{background:var(--dsh-any-op-header-bar,${paint})!important;backdrop-filter:var(--dsh-any-blur-header-bar,none);-webkit-backdrop-filter:var(--dsh-any-blur-header-bar,none);clip-path:inset(0 0 0 ${width});-webkit-clip-path:inset(0 0 0 ${width})}[data-windows-titlebar] .${CAPTION_FRAME_CLASS}::after{content:"";position:absolute;top:0;left:0;pointer-events:none;z-index:-1;width:${width};height:var(--dsh-windows-titlebar-height,40px);background:var(--dsh-any-op-sidebar,${fill});backdrop-filter:var(--dsh-any-blur-sidebar-band,none);-webkit-backdrop-filter:var(--dsh-any-blur-sidebar-band,none)}[data-windows-titlebar]:has([role="dialog"][aria-modal="true"]) .${CAPTION_FRAME_CLASS}::before,[data-windows-titlebar]:has([role="dialog"][aria-modal="true"]) .${CAPTION_FRAME_CLASS}::after{box-shadow:inset 0 0 0 9999px var(--dsw-alias-bg-mask-1,rgba(0,0,0,.24))}` + (rCaptionInk() === "theme" ? "" : ":root:has([data-sidebar-collapsed=\"true\"]){--dsh-any-caption-ink:var(--dsh-any-caption-ink-collapsed,#fff)!important}[data-windows-titlebar] [data-windows-menu]{--dsw-alias-label-secondary:var(--dsh-any-caption-ink,#fff);--dsw-alias-label-primary:var(--dsh-any-caption-ink,#fff)}") + `[data-windows-titlebar] .${FLAT_CENTER_CLASS}{border-top-left-radius:0!important}`;
 			const el = ensureWcoStyle();
 			if (el.textContent !== css) el.textContent = css;
 			const ink = css === "" ? null : captionInkPair();
@@ -4102,7 +4243,7 @@ window.__ModuleLoader__.load({
 		*  backdrop root each of those files documents avoiding. */
 		const HEADER_BLUR_VAR = "--dsh-any-blur-header";
 		function headerPopoverRule() {
-			return `${gated(HEADER_FROST_GATE, HEADER_SURFACES_PADDED.join(","))}{${menuFrost(HEADER_BLUR_VAR)}}`;
+			return `${HEADER_SURFACES_PADDED.join(",")}{${menuFrost(HEADER_BLUR_VAR)}}`;
 		}
 		function exemptDefaultRule() {
 			return `[role="dialog"][aria-modal="true"]:not([aria-labelledby]){backdrop-filter:none;-webkit-backdrop-filter:none}[role="menu"]:has([class*="_danger"]){${hostAdapter().menus.frostDecl("none")};-webkit-text-stroke-width:0}`;
@@ -4116,13 +4257,8 @@ window.__ModuleLoader__.load({
 		function applyHeaderPopovers() {
 			const root = document.documentElement;
 			const px = rBlurs().header;
-			if (px > 0) {
-				root.style.setProperty(HEADER_BLUR_VAR, `blur(${px}px)`);
-				root.classList.add(HEADER_FROST_GATE);
-			} else {
-				root.style.removeProperty(HEADER_BLUR_VAR);
-				root.classList.remove(HEADER_FROST_GATE);
-			}
+			if (px > 0) root.style.setProperty(HEADER_BLUR_VAR, `blur(${px}px)`);
+			else root.style.removeProperty(HEADER_BLUR_VAR);
 			let opacity = rHeaderOpacity();
 			if (opacity < 0) opacity = 0;
 			if (opacity > 1) opacity = 1;
@@ -4690,17 +4826,13 @@ window.__ModuleLoader__.load({
 		/** Blur of the option panels inside the settings dialog (.dab-card), owned by
 		*  the "dialog option panel" (card) blur slider. Written as a plugin-owned
 		*  variable consumed by SETTINGS_STYLE_RULE — deliberately NOT applied to the
-		*  homepage center column, which this slider must never touch. The gate class is
-		*  what hands the menu frost token over at all (see `CARD_FROST_GATE`). */
+		*  homepage center column, which this slider must never touch. At 0 the variable is
+		*  removed and the menu rule's `none` fallback wins, which is what "no frost" means
+		*  on this slider (see the note above `popoverBlurRule`). */
 		function applyCardPanelsBlur(px) {
 			const root = document.documentElement;
-			if (px > 0) {
-				root.style.setProperty(CARD_BLUR_VAR, `blur(${px}px)`);
-				root.classList.add(CARD_FROST_GATE);
-			} else {
-				root.style.removeProperty(CARD_BLUR_VAR);
-				root.classList.remove(CARD_FROST_GATE);
-			}
+			if (px > 0) root.style.setProperty(CARD_BLUR_VAR, `blur(${px}px)`);
+			else root.style.removeProperty(CARD_BLUR_VAR);
 		}
 		/** Apply per-part interface blur to the AppFrame columns + settings panel. */
 		function applyPartBlurs(blurs) {
@@ -5431,7 +5563,7 @@ window.__ModuleLoader__.load({
 				const name = set[k];
 				if (name) document.documentElement.style.removeProperty(name);
 			}
-			document.documentElement.classList.remove(INPUT_FROST_CLASS, CARD_FROST_GATE, HEADER_FROST_GATE);
+			document.documentElement.classList.remove(INPUT_FROST_CLASS);
 			applyTakeoverFrost(0);
 			document.documentElement.style.removeProperty("--dsh-any-op-header-bar");
 			document.documentElement.style.removeProperty("--dsh-any-blur-header-bar");
@@ -5439,7 +5571,7 @@ window.__ModuleLoader__.load({
 			document.documentElement.style.removeProperty("--dsh-any-caption-ink");
 			document.documentElement.style.removeProperty("--dsh-any-caption-ink-collapsed");
 			releaseCaptionInk();
-			document.querySelectorAll(`.${HEADER_BAR_CLASS}`).forEach((el) => el.classList.remove(HEADER_BAR_CLASS));
+			document.querySelectorAll(`.${HEADER_BAR_CLASS}`).forEach((el) => releaseHeaderBar(el));
 			headerBarEl = null;
 			frameEl?.classList.remove(CAPTION_FRAME_CLASS);
 			document.querySelectorAll(`.${FLAT_CENTER_CLASS}`).forEach((el) => el.classList.remove(FLAT_CENTER_CLASS));
@@ -7464,6 +7596,47 @@ window.__ModuleLoader__.load({
 									blurs[blurKey] = v;
 									setBlurs(blurs);
 								}
+							}),
+							isHeaderBar && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: "dab-slider-block",
+								title: t("captionInkHint"),
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "dab-slider-label",
+									children: t("captionInkLabel")
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									style: {
+										display: "flex",
+										alignItems: "center",
+										gap: 10
+									},
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("select", {
+										className: "dab-select",
+										value: rCaptionInk(),
+										onChange: (e) => {
+											cfg.captionInk = e.target.value;
+											applyHeaderBar();
+											saveConfig();
+										},
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+												value: "auto",
+												children: t("captionInkAuto")
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+												value: "theme",
+												children: t("captionInkTheme")
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+												value: "white",
+												children: t("captionInkWhite")
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+												value: "black",
+												children: t("captionInkBlack")
+											})
+										]
+									})
+								})]
 							})
 						]
 					}, blurKey);