dsh-background-by-model 0.4.4 → 0.4.5

package/README.md

@@ -225,6 +225,13 @@ No. Both were removed in 0.3.0; each rule uses a static image.
 
 ## Recent Optimizations
 
+### v0.4.5
+
+- **`optionalWhen` finally means what its name says** — The field is documented as "the check runs while this surface is on screen", but the probe was evaluating the exact opposite: an anchor that was *not* in the DOM produced *n/a*, and one that *was* produced the failure. Two of the three dock contracts and both conversation-view contracts were therefore testing the wrong state — which is how a healthy dock came back as `停靠空位 失效` with "no element matches `[data-dockkit-empty]`". The helper now reads the anchor as a positive predicate, and every anchor was renamed to say what it means (`dockHasTab`, `dockHasNoTab`, `chatHasMessages`, `paneFloated`, …) so an anchor named for an absence can no longer invert a check silently. Four tests pin the resulting state table in both directions.
+- **A contract about the message column stops firing on a session that has no messages** — `[data-chat-flow]` is rendered only when the session *has* messages, so its absence is the normal state of a brand-new session (the host's `data-content-phase="hero"` screen) and of the trajectory tab. The anchor was "the conversation scrollport exists", which is true in all three states, so the check reported a rename on the hero screen and on **轨迹** — the second failure the panel showed. It is now keyed on `[data-chat-turn]`, the host's own mark on every message row, which is the one thing that is present exactly when a column should exist. Measured: hero → 0 flow / 0 turn rows; after one message → 1 flow / 4 turn rows; trajectory tab → 0 flow / 0 turn rows.
+- **`visible` — presence is not the same question as "on screen"** — A selector check marked `visible: true` now also requires the element to be on screen, so an element the host parks with `visibility:hidden` cannot satisfy a contract about a surface the user is looking at. The dock's empty seat is deliberately *not* marked: the host keeps it rendered and hidden as tabs open and close, so asking whether it is visible would be asking about a state the host uses both ways.
+- **One more anchor rule, written down** — An anchor must name the state in which its attribute is **expected**, never a neighbour of it that happens to appear at the same time. All four false-red bugs in this feature have been the same mistake: a mounted surface that correctly renders nothing for the attribute to sit on.
+
 ### v0.4.4
 
 - **The dock contracts stop asking a stylesheet question about JS attributes** — `dockkit.content` and `dockkit.float` were `rule` checks ("does a host stylesheet mention this literal?"). The host sets both attributes from JavaScript — `data-dockkit-content` on a tab host that has a tab, `data-dockkit-float` on a pane the user has floated — and never writes a CSS rule for either, so that question could only ever be answered "no". Both are now **presence** checks, guarded by the host's own tab marker (`data-dockkit-tab`) and by float mode respectively, so a dock with no tab open reads as *n/a* rather than as a rename. `dockkit.empty` — the empty seat the host renders in place of a populated tab host — is a presence check too. Verified against a live host: with no tab open `data-dockkit-tab`/`data-dockkit-content` are absent; clicking the dock's `+` makes both appear (tab 0→1, content 0→1, empty 1→0), and the checks then answer instead of skipping.

package/README.zh.md

@@ -225,6 +225,13 @@ pnpm test        # 约定表、实时探测逻辑、界面样式表、版本下
 
 ## 近期优化
 
+### v0.4.5
+
+- **`optionalWhen` 终于按它名字的意思工作了** — 这个字段的文档写着「只有当这块界面在屏幕上时才检查」，但探测实现的是**反过来的**：锚点**不在** DOM 里时反而报 *未观察*，锚点**在**时才会去报失效。于是三条停靠约定里的两条、以及两条对话视图约定，全都在检查错误的状态 —— 这就是健康的停靠栏会报出「停靠空位 失效 / no element matches `[data-dockkit-empty]`」的原因。现在这个辅助函数把锚点当作**正向断言**来读，并且把所有锚点改名成它们真正的含义（`dockHasTab`、`dockHasNoTab`、`chatHasMessages`、`paneFloated` …），这样「用缺席来命名」的锚点再也不可能悄悄把检查反过来。四个测试把由此得到的状态表两个方向都钉住了。
+- **关于消息列的约定不再对着「还没有任何消息」的会话开火** — `[data-chat-flow]` 只在会话**有消息**时才渲染，所以它不在，恰恰是全新会话（宿主的 `data-content-phase="hero"` 首屏）和轨迹页的正常状态。原来的锚点是「对话滚动区存在」，而这三个状态下它都存在，于是检查在首屏和**轨迹页**都报了「属性改名」—— 也就是面板上你看到的第二个失效。现在锚点改用 `[data-chat-turn]`，宿主给每条消息行打的标记，这是唯一「恰好只在消息列该存在时存在」的东西。实测：首屏 → 消息列 0 / 消息行 0；发一条消息后 → 1 / 4；轨迹页 → 0 / 0。
+- **`visible` —— 「存在」和「在屏幕上」不是同一个问题** — 标记了 `visible: true` 的选择器检查现在要求元素真的在屏幕上，于是宿主用 `visibility:hidden` 停放在一边的元素，无法满足一条关于「用户正在看的界面」的约定。停靠空位**故意不标记**：宿主在开合 tab 时一直把它渲染着并隐藏，去问它可不可见，就是在问一个宿主两个方向都在用的状态。
+- **再写死一条锚点规则** — 锚点必须命名「这个属性**预期出现**的状态」，绝不能是恰好同时出现的邻居。这个功能里四次「误报失效」全都是同一个错误：界面明明挂着、宿主行为也对，只是**没有任何东西**能让那个属性落上去。
+
 ### v0.4.4
 
 - **停靠相关的约定不再拿「样式表问题」去问 JS 属性** — `dockkit.content` 与 `dockkit.float` 原本是 `rule` 检查（「宿主样式表里有没有提到这个字面量」）。但这两个属性都是宿主从 **JavaScript** 打上去的：`data-dockkit-content` 只在**有 tab** 的停靠页宿主上，`data-dockkit-float` 只在用户真的把面板浮动起来时；宿主从来没为它们写过任何 CSS 规则。所以那个问题无论宿主健不健康都只会回答「没有」。现在两条都改成**存在性**检查，分别用宿主自己的 tab 标记（`data-dockkit-tab`）和浮动态做守卫，于是「没开 tab 的停靠」会报成 *未观察*，而不是「属性改名」。`dockkit.empty`（宿主在「有 tab」时用来替换空位的那个座位）同样改成存在性检查。已在真实宿主上验证：没开 tab 时 `data-dockkit-tab`/`data-dockkit-content` 都不存在；点一下停靠栏的 `+`，两者同时出现（tab 0→1、content 0→1、empty 1→0），此时检查会给出结论而不是跳过。

package/lib/client.js

@@ -2673,7 +2673,8 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "div[role=\"dialog\"][aria-modal=\"true\"][aria-labelledby]",
-					optionalWhen: "settingsClosed"
+					optionalWhen: "settingsOpen",
+					visible: true
 				}],
 				sources: [{
 					path: "dsh-client-ui-primitives/lib/index.js",
@@ -2729,7 +2730,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "attr",
 					attr: "data-composer-card",
-					optionalWhen: "chatNotMounted"
+					optionalWhen: "chatHasMessages"
 				}],
 				sources: [{
 					path: "dsh-client-ui-conversation/lib/client.js",
@@ -2755,7 +2756,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "attr",
 					attr: "data-cordis-panel",
-					optionalWhen: "cordisClosed"
+					optionalWhen: "cordisMounted"
 				}],
 				sources: [{
 					path: "dsh-client-ui-cordis/lib/client.js",
@@ -2781,7 +2782,8 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "div[data-sidebar-right-panel]",
-					optionalWhen: "noRightPanel"
+					optionalWhen: "rightPanelMounted",
+					visible: true
 				}],
 				sources: [{
 					path: `${SIDEBAR_RIGHT}/lib/client.js`,
@@ -2833,7 +2835,8 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-dockkit-content]",
-					optionalWhen: "noDockTab"
+					optionalWhen: "dockHasTab",
+					visible: true
 				}],
 				sources: [{
 					path: ".",
@@ -2860,7 +2863,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-dockkit-empty]",
-					optionalWhen: "noDockTab"
+					optionalWhen: "dockHasNoTab"
 				}],
 				sources: [{
 					path: `${SIDEBAR_RIGHT}/lib/client.js`,
@@ -2886,7 +2889,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-dockkit-float]",
-					optionalWhen: "noFloatPane"
+					optionalWhen: "paneFloated"
 				}],
 				sources: [{
 					path: `${SIDEBAR_RIGHT}/lib/client.js`,
@@ -2912,7 +2915,8 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-chat-flow]",
-					optionalWhen: "chatNotMounted"
+					optionalWhen: "chatHasMessages",
+					visible: true
 				}],
 				sources: [{
 					path: "dsh-client-ui-chat/lib/client.js",
@@ -2938,7 +2942,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-conversation-scroll]",
-					optionalWhen: "chatNotMounted"
+					optionalWhen: "chatHasMessages"
 				}],
 				sources: [{
 					path: "dsh-client-ui-conversation/lib/client.js",
@@ -2964,7 +2968,7 @@ window.__ModuleLoader__.load({
 				checks: [{
 					kind: "selector",
 					selector: "[data-conversation-composer-overlay]",
-					optionalWhen: "trajectoryNotMounted"
+					optionalWhen: "trajectoryMounted"
 				}],
 				sources: [{
 					path: "dsh-client-ui-trajectory/lib/client.js",
@@ -3343,26 +3347,43 @@ window.__ModuleLoader__.load({
 					if (host === null) return "";
 					return getComputedStyle(host).getPropertyValue(token).trim();
 				},
+				visible: (el) => {
+					if (el === null || typeof getComputedStyle !== "function") return true;
+					try {
+						return getComputedStyle(el).visibility !== "hidden";
+					} catch {
+						return true;
+					}
+				},
 				styleSheets: () => typeof document === "undefined" ? [] : Array.from(document.styleSheets),
 				ctx
 			};
 		}
 		const ANCHORS = {
-			settingsClosed: "div[role=\"dialog\"][aria-modal=\"true\"][aria-labelledby]",
-			chatNotMounted: "[data-chat-flow],[data-conversation-scroll]",
-			trajectoryNotMounted: "[data-conversation-composer-overlay]",
-			noRightPanel: "div[data-sidebar-right-panel],[data-dockkit-strip],[data-dockkit-pane]",
-			cordisClosed: "[data-cordis-panel]",
-			noDockTab: "[data-dockkit-tab]",
-			noFloatPane: "[data-dockkit-float],[data-sidebar-right-mode=\"float\"]"
+			chatHasMessages: "[data-chat-turn]",
+			trajectoryMounted: "[data-conversation-composer-overlay]",
+			rightPanelMounted: "div[data-sidebar-right-panel],[data-dockkit-strip],[data-dockkit-pane]",
+			cordisMounted: "[data-cordis-panel]",
+			dockHasTab: "[data-dockkit-tab]",
+			dockHasNoTab: "[data-dockkit-empty],[data-dockkit-add-tab]",
+			paneFloated: "[data-dockkit-float],[data-sidebar-right-mode=\"float\"]",
+			settingsOpen: "div[role=\"dialog\"][aria-modal=\"true\"][aria-labelledby]"
 		};
-		function mounted(env, anchorId) {
+		/**
+		* Whether an anchor's surface is on screen.
+		*
+		* `optionalWhen: X` skips the check while this is FALSE — "the feature is not
+		* observable right now", which is what the field name promises. Every anchor is
+		* therefore written as a POSITIVE predicate (`dockHasTab`, `chatHasMessages`), and
+		* an anchor whose name reads as an absence would silently invert its check.
+		*/
+		function anchorMounted(env, anchorId) {
 			const sel = ANCHORS[anchorId];
 			if (sel === void 0) return true;
 			try {
 				return env.querySelector(sel) !== null;
 			} catch {
-				return false;
+				return true;
 			}
 		}
 		/** Walk a dotted path off a root object, tolerating a missing first hop. */
@@ -3426,7 +3447,9 @@ window.__ModuleLoader__.load({
 			}
 			return false;
 		}
-		/** Which sides of stylesheet the probe can actually read (a blind check must not fail). */
+		/**
+		* Which sides of stylesheet the probe can actually read (a blind check must not fail).
+		*/
 		function readability(env) {
 			const out = {
 				host: false,
@@ -3506,14 +3529,14 @@ window.__ModuleLoader__.load({
 					};
 				}
 				case "selector": {
-					const present = env.querySelector(check.selector) !== null;
+					const el = env.querySelector(check.selector);
 					const name = `querySelector(${JSON.stringify(check.selector)})`;
-					if (present) return {
+					if (el !== null && (check.visible !== true || env.visible(el))) return {
 						status: "pass",
 						name,
 						detail: "element found"
 					};
-					if (check.optionalWhen !== void 0 && !mounted(env, check.optionalWhen)) return {
+					if (check.optionalWhen !== void 0 && !anchorMounted(env, check.optionalWhen)) return {
 						status: "skip",
 						name,
 						detail: "not on screen right now"
@@ -3521,8 +3544,8 @@ window.__ModuleLoader__.load({
 					return {
 						status: "fail",
 						name,
-						detail: "no element matches",
-						reason: `no element matches ${check.selector} while its surface is on screen`
+						detail: el === null ? "no element matches" : "the element is hidden",
+						reason: el === null ? `no element matches ${check.selector} while its surface is on screen` : `${check.selector} is in the DOM but hidden while its surface is on screen`
 					};
 				}
 				case "attr": {
@@ -3533,7 +3556,7 @@ window.__ModuleLoader__.load({
 						name,
 						detail: "attribute found"
 					};
-					if (check.optionalWhen !== void 0 && !mounted(env, check.optionalWhen)) return {
+					if (check.optionalWhen !== void 0 && !anchorMounted(env, check.optionalWhen)) return {
 						status: "skip",
 						name,
 						detail: "not on screen right now"
@@ -3695,7 +3718,7 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region src/client/build-info.ts
 		/** This plugin's version at build time ('0.0.0' when built unbundled). */
-		const PLUGIN_VERSION = "0.4.4";
+		const PLUGIN_VERSION = "0.4.5";
 		/** The dsh floor this build declares, straight from `engines.dsh`. */
 		const DSH_FLOOR = "0.1.7-rc.2";
 		//#endregion