opencode-skills-collection 4.1.2 → 4.1.3

package/bundled-skills/liuguang-banlan-ui/assets/starter/shared/spectral-field.js

@@ -1,7 +1,11 @@
 (function () {
   "use strict";
 
-  const MAX_COLORS = 12;
+  // The field drifts slowly. Spacing frames so each advances field time by at most
+  // MAX_FIELD_STEP keeps the change per frame below a visible step at less GPU cost.
+  const MIN_FRAME_INTERVAL = 50;
+  const MAX_FRAME_INTERVAL = 250;
+  const MAX_FIELD_STEP = 0.003;
 
   const VERTEX_SHADER = `
     attribute vec2 aPosition;
@@ -23,12 +27,12 @@
     uniform float uWarp;
     uniform float uDither;
     uniform float uLuminanceCap;
+    uniform float uLevels;
     uniform vec3 uBase;
-    uniform vec3 uColors[12];
-    uniform float uStrengths[12];
-    uniform float uFieldScales[12];
-    uniform vec2 uPhases[12];
-    uniform float uColorCount;
+    uniform vec3 uColors[6];
+    uniform float uStrengths[6];
+    uniform float uFieldScales[6];
+    uniform vec2 uPhases[6];
 
     float hash21(vec2 p) {
       p = fract(p * vec2(123.34, 456.21));
@@ -52,8 +56,8 @@
       float amplitude = 0.52;
       mat2 rotation = mat2(0.80, 0.60, -0.60, 0.80);
       for (int i = 0; i < 5; i++) {
-        float enabled = 1.0 - step(uOctaves, float(i) + 0.5);
-        value += amplitude * noise(p) * enabled;
+        if (float(i) + 0.5 >= uOctaves) break;
+        value += amplitude * noise(p);
         p = rotation * p * 2.03 + vec2(13.1, 7.7);
         amplitude *= 0.48;
       }
@@ -77,6 +81,19 @@
       return c / (1.0 + max(c - 1.0, 0.0));
     }
 
+    vec3 linearToSrgb(vec3 c) {
+      vec3 high = 1.055 * pow(max(c, vec3(0.0031308)), vec3(1.0 / 2.4)) - 0.055;
+      return mix(c * 12.92, high, step(vec3(0.0031308), c));
+    }
+
+    // Not hash21: offsetting pixel coordinates by the seed pushes them past
+    // float precision, and the dither turns into visible stripes.
+    float ditherHash(vec2 p) {
+      vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+      p3 += dot(p3, p3.yzx + 33.33);
+      return fract((p3.x + p3.y) * p3.z);
+    }
+
     void main() {
       vec2 uv = gl_FragCoord.xy / uResolution.xy;
       vec2 p = (uv - 0.5) * vec2(uResolution.x / uResolution.y, 1.0);
@@ -104,7 +121,12 @@
         + dot(warped, vec2(0.72, -0.49))
         + uSeed * 0.000017
       );
-      for (int i = 0; i < 12; i++) {
+      for (int i = 0; i < 6; i++) {
+        float hueStop = float(i) / 6.0;
+        float hueDistance = abs(spectralFlow - hueStop);
+        hueDistance = min(hueDistance, 1.0 - hueDistance);
+        float hueBand = 1.0 - smoothstep(0.035, 0.205, hueDistance);
+        if (hueBand <= 0.0) continue;
         float field = colorField(
           warped + q * (0.21 + float(i) * 0.025),
           uPhases[i],
@@ -112,16 +134,11 @@
           uFieldScales[i]
         );
         float softBand = smoothstep(0.22, 0.78, field);
-        float active = step(float(i) + 0.5, uColorCount);
-        float hueStop = float(i) / max(uColorCount, 1.0);
-        float hueDistance = abs(spectralFlow - hueStop);
-        hueDistance = min(hueDistance, 1.0 - hueDistance);
-        float hueBand = 1.0 - smoothstep(0.035, 0.205, hueDistance);
         float shapedBand = pow(hueBand, 2.2) * (0.64 + softBand * 0.36);
-        float weight = shapedBand * sqrt(max(uStrengths[i], 0.0)) * active;
+        float weight = shapedBand * sqrt(max(uStrengths[i], 0.0));
         colorSum += uColors[i] * weight;
         weightSum += weight;
-        energySum += shapedBand * uStrengths[i] * active;
+        energySum += shapedBand * uStrengths[i];
         strongestBand = max(strongestBand, shapedBand);
       }
 
@@ -145,11 +162,13 @@
         }
       }
 
-      float dither = hash21(floor(gl_FragCoord.xy) + vec2(uSeed, -uSeed)) - 0.5;
-      color += dither * (uDither / 255.0);
-      color = toneMap(max(color, 0.0));
-      color = pow(color, vec3(1.0 / 2.2));
-      gl_FragColor = vec4(color, 1.0);
+      vec2 pixel = floor(gl_FragCoord.xy);
+      float triangle = ditherHash(pixel) + ditherHash(pixel + vec2(47.0, 113.0)) - 1.0;
+      vec3 encoded = linearToSrgb(toneMap(max(color, 0.0)));
+      // Quantize here so the result does not depend on whether the GPU rounds or
+      // truncates when it stores floats; +0.25 lands inside the chosen code either way.
+      vec3 code = clamp(floor(encoded * uLevels + 0.5 + triangle * uDither), 0.0, uLevels);
+      gl_FragColor = vec4((code + 0.25) / uLevels, 1.0);
     }
   `;
 
@@ -170,6 +189,8 @@
     ];
   }
 
+  const MAX_COLORS = 12;
+
   function clamp01(value) {
     const number = Number(value);
     return Number.isFinite(number) ? Math.min(1, Math.max(0, number)) : 0;
@@ -243,89 +264,72 @@
       this.applyFallbackConfig(config);
       this.available = false;
       this.error = null;
-      this.motionPreference = window.matchMedia("(prefers-reduced-motion: reduce)");
-      this.motionEnabled = !this.motionPreference.matches;
+      this.motionEnabled = !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
       this.visible = !document.hidden;
-      this.startTime = performance.now();
-      this.phaseTime = null;
+      this.fieldTime = config.field.staticTime;
+      this.lastTick = null;
       this.lastFrame = 0;
       this.frameHandle = 0;
       try {
-        this.gl = canvas.getContext("webgl", {
-          alpha: false,
-          antialias: false,
-          depth: false,
-          stencil: false,
-          powerPreference: "low-power",
-          preserveDrawingBuffer: true
-        });
-        if (!this.gl) throw new Error("WebGL context unavailable");
-
-        this.program = createProgram(this.gl);
-        this.gl.useProgram(this.program);
-        const buffer = this.gl.createBuffer();
-        if (!buffer) throw new Error("WebGL buffer creation failed");
-        this.gl.bindBuffer(this.gl.ARRAY_BUFFER, buffer);
-        this.gl.bufferData(
-          this.gl.ARRAY_BUFFER,
-          new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
-          this.gl.STATIC_DRAW
-        );
-        const position = this.gl.getAttribLocation(this.program, "aPosition");
-        if (position < 0) throw new Error("WebGL position attribute unavailable");
-        this.gl.enableVertexAttribArray(position);
-        this.gl.vertexAttribPointer(position, 2, this.gl.FLOAT, false, 0, 0);
-
-        this.locations = {
-          resolution: uniform(this.gl, this.program, "uResolution"),
-          time: uniform(this.gl, this.program, "uTime"),
-          seed: uniform(this.gl, this.program, "uSeed"),
-          mode: uniform(this.gl, this.program, "uMode"),
-          overall: uniform(this.gl, this.program, "uOverall"),
-          colorCount: uniform(this.gl, this.program, "uColorCount"),
-          scale: uniform(this.gl, this.program, "uScale"),
-          octaves: uniform(this.gl, this.program, "uOctaves"),
-          warp: uniform(this.gl, this.program, "uWarp"),
-          dither: uniform(this.gl, this.program, "uDither"),
-          luminanceCap: uniform(this.gl, this.program, "uLuminanceCap"),
-          base: uniform(this.gl, this.program, "uBase"),
-          colors: uniform(this.gl, this.program, "uColors[0]"),
-          strengths: uniform(this.gl, this.program, "uStrengths[0]"),
-          fieldScales: uniform(this.gl, this.program, "uFieldScales[0]"),
-          phases: uniform(this.gl, this.program, "uPhases[0]")
-        };
-
-        this.onResize = () => this.resize();
-        this.onVisibility = () => {
-          const now = performance.now();
-          if (document.hidden) {
-            this.capturePhase(now);
-            this.visible = false;
-            if (this.frameHandle) {
-              cancelAnimationFrame(this.frameHandle);
-              this.frameHandle = 0;
-            }
-            return;
-          }
-
-          this.visible = true;
-          if (this.motionEnabled) {
-            const speed = this.config.field.motionSpeed;
-            this.startTime = speed > 0 && this.phaseTime !== null
-              ? now - (this.phaseTime / speed) * 1000
-              : now;
-          }
-          this.render(now, true);
-          this.schedule();
-        };
-        this.onMotionPreference = (event) => this.setMotion(!event.matches);
-        window.addEventListener("resize", this.onResize, { passive: true });
-        document.addEventListener("visibilitychange", this.onVisibility);
-        this.motionPreference.addEventListener("change", this.onMotionPreference);
-        this.available = true;
-        this.resize();
-        this.uploadConfig();
-        this.schedule();
+      this.gl = canvas.getContext("webgl", {
+        alpha: false,
+        antialias: false,
+        depth: false,
+        stencil: false,
+        powerPreference: "low-power",
+        preserveDrawingBuffer: true
+      });
+
+      if (!this.gl) throw new Error("WebGL context unavailable");
+
+      this.available = true;
+      this.levels = Math.pow(2, this.gl.getParameter(this.gl.RED_BITS) || 8) - 1;
+      this.program = createProgram(this.gl);
+      this.gl.useProgram(this.program);
+      const buffer = this.gl.createBuffer();
+      this.gl.bindBuffer(this.gl.ARRAY_BUFFER, buffer);
+      this.gl.bufferData(
+        this.gl.ARRAY_BUFFER,
+        new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
+        this.gl.STATIC_DRAW
+      );
+      const position = this.gl.getAttribLocation(this.program, "aPosition");
+      this.gl.enableVertexAttribArray(position);
+      this.gl.vertexAttribPointer(position, 2, this.gl.FLOAT, false, 0, 0);
+
+      this.locations = {
+        resolution: uniform(this.gl, this.program, "uResolution"),
+        time: uniform(this.gl, this.program, "uTime"),
+        seed: uniform(this.gl, this.program, "uSeed"),
+        mode: uniform(this.gl, this.program, "uMode"),
+        overall: uniform(this.gl, this.program, "uOverall"),
+        scale: uniform(this.gl, this.program, "uScale"),
+        octaves: uniform(this.gl, this.program, "uOctaves"),
+        warp: uniform(this.gl, this.program, "uWarp"),
+        dither: uniform(this.gl, this.program, "uDither"),
+        luminanceCap: uniform(this.gl, this.program, "uLuminanceCap"),
+        levels: uniform(this.gl, this.program, "uLevels"),
+        base: uniform(this.gl, this.program, "uBase"),
+        colors: uniform(this.gl, this.program, "uColors[0]"),
+        strengths: uniform(this.gl, this.program, "uStrengths[0]"),
+        fieldScales: uniform(this.gl, this.program, "uFieldScales[0]"),
+        phases: uniform(this.gl, this.program, "uPhases[0]")
+      };
+
+      // Resizing clears the drawing buffer; a paused field has no next frame to repaint it.
+      this.onResize = () => {
+        if (this.resize()) this.render(performance.now(), true);
+      };
+      this.onVisibility = () => {
+        this.visible = !document.hidden;
+        this.lastTick = null;
+        if (this.visible) this.schedule();
+      };
+      window.addEventListener("resize", this.onResize, { passive: true });
+      document.addEventListener("visibilitychange", this.onVisibility);
+      this.resize();
+      this.uploadConfig();
+      this.schedule();
       } catch (error) {
         this.error = error instanceof Error ? error.message : String(error);
         this.available = false;
@@ -334,36 +338,28 @@
       }
     }
 
+    applyFallbackConfig(config) {
+      document.documentElement.style.setProperty("--field-fallback-background", fallbackBackground(config));
+    }
+
     resize() {
-      if (!this.available) return;
+      if (!this.available) return false;
       const pixelRatio = Math.min(window.devicePixelRatio || 1, 1.5);
       const width = Math.max(1, Math.round(this.canvas.clientWidth * pixelRatio));
       const height = Math.max(1, Math.round(this.canvas.clientHeight * pixelRatio));
-      if (this.canvas.width !== width || this.canvas.height !== height) {
-        this.canvas.width = width;
-        this.canvas.height = height;
-        this.gl.viewport(0, 0, width, height);
-      }
-    }
-
-    applyFallbackConfig(config) {
-      document.documentElement.style.setProperty("--field-fallback-background", fallbackBackground(config));
+      if (this.canvas.width === width && this.canvas.height === height) return false;
+      this.canvas.width = width;
+      this.canvas.height = height;
+      this.gl.viewport(0, 0, width, height);
+      return true;
     }
 
     uploadConfig() {
       if (!this.available) return;
       const gl = this.gl;
       const config = this.config;
-      const sourceColors = Array.isArray(config.colors) ? config.colors.slice(0, MAX_COLORS) : [];
-      const fallbackColor = sourceColors[0] || {
-        oklch: config.base.oklch,
-        intensity: 0,
-        peakOpacity: 0,
-        fieldScale: config.field.scale,
-        phase: [0, 0]
-      };
-      const colors = sourceColors.slice();
-      while (colors.length < MAX_COLORS) colors.push(fallbackColor);
+      const colors = config.colors.slice(0, 6);
+      while (colors.length < 6) colors.push(colors[colors.length - 1]);
       const colorValues = colors.flatMap((entry) => oklchToLinearRgb(entry.oklch));
       const strengthValues = colors.map((entry) => entry.intensity * entry.peakOpacity * 3.0);
       const fieldScaleValues = colors.map((entry) => entry.fieldScale);
@@ -372,12 +368,12 @@
       gl.uniform1f(this.locations.seed, config.seed);
       gl.uniform1f(this.locations.mode, config.mode === "obsidian" ? 1 : 0);
       gl.uniform1f(this.locations.overall, config.overallColorIntensity);
-      gl.uniform1f(this.locations.colorCount, sourceColors.length);
       gl.uniform1f(this.locations.scale, config.field.scale);
       gl.uniform1f(this.locations.octaves, config.field.octaves);
       gl.uniform1f(this.locations.warp, config.field.warpStrength);
       gl.uniform1f(this.locations.dither, config.field.ditherStrength);
-      gl.uniform1f(this.locations.luminanceCap, config.field.luminanceCap);
+      gl.uniform1f(this.locations.luminanceCap, config.field.luminanceCap ?? 1);
+      gl.uniform1f(this.locations.levels, this.levels);
       gl.uniform3fv(this.locations.base, new Float32Array(oklchToLinearRgb(config.base.oklch)));
       gl.uniform3fv(this.locations.colors, new Float32Array(colorValues));
       gl.uniform1fv(this.locations.strengths, new Float32Array(strengthValues));
@@ -385,40 +381,20 @@
       gl.uniform2fv(this.locations.phases, new Float32Array(phaseValues));
     }
 
-    capturePhase(now) {
-      if (this.motionEnabled) {
-        this.phaseTime = ((now - this.startTime) / 1000) * this.config.field.motionSpeed;
-      } else if (this.phaseTime === null) {
-        this.phaseTime = this.config.field.staticTime;
-      }
-      return this.phaseTime;
-    }
-
     updateConfig(config) {
-      const now = performance.now();
-      this.capturePhase(now);
       this.config = config;
       this.applyFallbackConfig(config);
       this.uploadConfig();
-      this.render(now, true);
+      this.render(performance.now(), true);
     }
 
     setMotion(enabled) {
-      if (enabled === this.motionEnabled) {
-        const now = performance.now();
-        if (!enabled) this.capturePhase(now);
-        this.render(now, true);
-        return;
-      }
-      const now = performance.now();
-      const phase = this.capturePhase(now);
       this.motionEnabled = enabled;
+      this.lastTick = null;
       if (enabled) {
-        const speed = this.config.field.motionSpeed;
-        this.startTime = speed > 0 ? now - (phase / speed) * 1000 : now;
         this.schedule();
       } else {
-        this.render(now, true);
+        this.render(performance.now(), true);
       }
     }
 
@@ -431,17 +407,28 @@
       });
     }
 
+    frameInterval() {
+      const speed = this.config.field.motionSpeed;
+      if (!(speed > 0)) return MAX_FRAME_INTERVAL;
+      return Math.min(MAX_FRAME_INTERVAL, Math.max(MIN_FRAME_INTERVAL, (MAX_FIELD_STEP / speed) * 1000));
+    }
+
     render(now, force) {
       if (!this.available) return;
-      if (!force && now - this.lastFrame < 50) {
+      if (!force && now - this.lastFrame < this.frameInterval()) {
         this.schedule();
         return;
       }
       this.lastFrame = now;
       this.resize();
-      const elapsed = this.capturePhase(now);
+      if (this.motionEnabled) {
+        if (this.lastTick !== null) {
+          this.fieldTime += (Math.max(0, now - this.lastTick) / 1000) * this.config.field.motionSpeed;
+        }
+        this.lastTick = now;
+      }
       this.gl.uniform2f(this.locations.resolution, this.canvas.width, this.canvas.height);
-      this.gl.uniform1f(this.locations.time, elapsed);
+      this.gl.uniform1f(this.locations.time, this.fieldTime);
       this.gl.drawArrays(this.gl.TRIANGLES, 0, 6);
     }
   }

package/bundled-skills/liuguang-banlan-ui/references/style-contract.md

@@ -2,10 +2,11 @@
 
 ## 共通原则
 
-- 把色场当作环境现象，不把它当成组件皮肤或装饰贴纸。
+- 把色场当作环境现象，不把它当成组件皮肤或装饰贴纸。logo、头像、分隔线等界面部件保持中性，不用调色板渐变上色。
 - 先建立稳定的信息层级：导航、列表/队列、详情、元数据、状态带。
 - 让颜色跨越整个场景，但保持文字、边界、按钮和选择态可读。
 - 用 OKLCH 编写颜色；为降级路径保留 sRGB 值。
+- 颜色数组按色相顺序排列。渲染器把颜色依次排在一条首尾相接的色相轴上，相邻两色在交界处混合；近互补色相邻时，交界处色度互相抵消，只剩变暗。
 - 使用连续的 fBm/domain-warp、流带或方向性流域。禁止明显的圆形光斑、中心聚光和硬彩虹条。
 - 维持静、薄、净、密、活的工作台气质：表面轻、信息密、状态清楚、背景有生命但不抢语义。
 
@@ -13,6 +14,8 @@
 
 定位：白色是第一视觉，色彩像被光照亮的珠光薄层，能看到变化但不破坏“白”。
 
+下表按 starter 工作台标定：顶栏、侧栏和工作区等面板以 66%–92% 的不透明度盖在色场上。色场直接露出时，按下一节调整。
+
 | 参数 | 建议范围 | 作用 |
 |---|---:|---|
 | `overallColorIntensity` | 0.60–0.90 | 控制全局彩色预算，默认约 0.82 |
@@ -22,9 +25,23 @@
 | 颜色 `oklch.c` | 0.030–0.065 | 足够识别，但避免糖果霓虹 |
 | `peakOpacity` | 0.055–0.110 | 决定局部峰值，先调它再调总体 |
 | `field.warpStrength` | 0.22–0.42 | 让颜色互相流动而非分块 |
-| `field.luminanceCap` | 0.94–1.00 | 白场通常不需强行压暗 |
 
-建议使用玫瑰、海玻璃青、丁香、珠杏、薄荷和远空蓝等低饱和色相。至少让三种色相在同一截图中可辨，不要让整张图退化为普通暖白、灰雾或单一冷白。
+白版不使用 `field.luminanceCap`。建议使用玫瑰、海玻璃青、丁香、珠杏、薄荷和远空蓝等低饱和色相。至少让三种色相在同一截图中可辨，不要让整张图退化为普通暖白、灰雾或单一冷白。
+
+### 色场直接露出
+
+个人主页、文章页这类页面没有面板盖住色场，按上表的强度会显得花，也会把整页压暗。下表是一个真实站点在一位用户屏幕上的判断。`tint.p50` 是 `measure_preview.py` 测得的相对底色色偏中位数（OKLab），用用户当时看到的那一版渲染器重新测得；换站点或屏幕需要重新确认。
+
+| 用户判断 | `tint.p50` | 配置 |
+|---|---:|---|
+| 看不出色场 | 约 0.004 | overall 0.30 |
+| 合适：仔细看能看出，不发灰 | 约 0.0056 | overall 0.45 |
+| 显得花且乱 | 约 0.009 | 上表默认参数，色相交错排列 |
+| 阅读页，接近全白 | 约 0.0017 | overall 0.15 |
+
+那个站点的其他参数：底色 `l` 0.988，颜色按色相排序，`field.scale` 0.8，`octaves` 3，`warpStrength` 0.26。当前渲染器下，这组参数在 overall 0.45 时测得约 0.0052，0.55 时约 0.0063。
+
+白版的颜色都比底色暗，着色的同时一定变暗。同一组颜色下，变暗和色偏按同一比例随强度变化，`shiftToTint` 基本不变，所以降低强度只会让色场更淡，不会让它更干净。要减少发灰，先按色相排序并检查 `grayRatio`。把颜色亮度调得更接近底色也能减少变暗，但越接近白色，sRGB 能容纳的色度越小；这一点还没有在当前渲染器上实测。
 
 ## 五彩斑斓黑 / `obsidian`
 
@@ -45,9 +62,11 @@
 
 ## 参数解释
 
-- `intensity`：该色相参与场的权重，必须可被滑杆实时改变。
-- `peakOpacity`：该色相的局部峰值预算；不要把它误写成整个页面透明度。
+- `intensity`：该色相参与场的权重，必须可被滑杆实时改变。渲染器把它和 `peakOpacity` 相乘，作为该色相的强度。
+- `peakOpacity`：`intensity` 为 1 时该色相的强度，是校准时定下的值；不要把它误写成整个页面透明度。
 - `fieldScale`：该色相的空间频率；不同值能避免所有颜色同相叠加。
 - `phase`：确定性相位，长度为 2 的数组；同一 seed 下保持稳定。
-- `measuredCoverage`：截图中超过基材色度阈值、并归属该色相的像素占比。
-- `effectiveShare`：可见色度能量中该色相的相对份额；这是近似归属，不是 shader 内部精确贡献。
+- `ditherStrength`：输出码值上的三角抖动幅度，以一个色阶为单位。1 能消除量化偏差；小于 1 会留下一部分偏差，强度越低越明显。
+- `luminanceCap`：只在黑版生效，限制混色后的线性亮度。
+- `measuredCoverage`：相对底色的色偏超过可见阈值、并按偏离方向归属该色相的像素块占比。
+- `effectiveShare`：可见色偏能量中该色相的相对份额；这是近似归属，不是 shader 内部精确贡献。

package/bundled-skills/liuguang-banlan-ui/references/verification.md

@@ -13,7 +13,7 @@
 
 ## 浏览器检查
 
-用真实浏览器生成至少两种视口：桌面（建议 1440×960）和窄屏（建议 390×844）。至少检查：
+用真实浏览器生成至少两种视口：桌面（建议 1440×960）和窄屏（建议 390×844）。预览用 `scripts/serve_preview.py`：`python -m http.server` 不发 `Cache-Control`，改完 manifest 后浏览器可能继续用旧文件，截图测到的就是上一版。至少检查：
 
 1. 页面初始渲染与 WebGL/CSS fallback 状态；
 2. 参数面板打开、关闭、Escape 返回焦点；
@@ -21,7 +21,8 @@
 4. 恢复预设、导出 JSON、复制失败时的可用提示；
 5. 导航、记录选择、标签切换、移动端导航收起；
 6. 控制台错误/警告和本地静态资源请求；
-7. reduced-motion 与页面隐藏时暂停/冻结行为。
+7. reduced-motion 与页面隐藏时暂停/冻结行为；
+8. 暂停后改变窗口尺寸，色场不能变黑；暂停和继续时画面不能跳。
 
 截图必须直接看过才能产生审美结论。重点检查：白版是否仍以白为主、黑版是否仍以黑为底、六色是否形成连续流域、文字是否可读，以及是否出现圆形大光斑、RGB 霓虹、灰雾、黑压死或全页玻璃。
 
@@ -30,16 +31,27 @@
 用 `scripts/measure_preview.py` 测量纯色场截图，而不是只测被面板遮挡的完整页面。脚本会：
 
 - 读取 JS manifest 中的 base 与 palette；
-- 将截图转换到 OKLab；
-- 以“高于基材色度阈值”的像素作为可见色；
-- 将可见像素分配给最近的配置色相；
-- 输出可见色像素比例、OKLab chroma、亮度均值/P95/最大值、每色覆盖率和有效色度份额。
+- 在线性光里按像素块（默认 8×8）取平均，抵消抖动，再转换到 OKLab；
+- 计算每个像素块相对 manifest 底色的偏离：亮度偏移，以及 a、b 上的色偏；
+- 把色偏超过可见阈值的像素块算作可见色，按偏离方向归属到最近的配置色相；
+- 输出可见色比例、色偏分位数、亮度偏移分位数、亮度偏移与色偏之比（`shiftToTint`）、灰块比例（`grayRatio`）、每色覆盖率和有效份额。
+
+偏离相对底色计算，底色自身的色度不影响结果。当前渲染器按 sRGB 曲线编码并在量化前抖动，overall 为 0 时截图应与 manifest 底色一致。换用别的渲染器时，先用 overall 0 的截图验证这一点，否则测到的偏离里混有渲染器自身的偏差。
 
 低色度白场的色相归属只能作为近似统计，不能替代视觉检查。黑版必须同时检查最大亮度不超过 manifest 的 `luminanceCap` 意图；不要把截图中的 sRGB 值直接当成线性亮度。
 
+## 变暗检查
+
+白版的颜色都比底色暗，着色一定伴随变暗。看两项：
+
+- `lightnessShift.mean`：整页平均比底色暗多少。
+- `grayRatio`：亮度明显改变、色偏却很小的像素块占比，只在白版计算。它应接近 0；偏高时先检查颜色是否按色相排序，`validate_manifest.py` 会对乱序给出警告。
+
+同一组颜色下，`shiftToTint` 基本不随强度变化，调低强度不会让它变小。色场直接露出的页面，按 `style-contract.md` 里“色场直接露出”一节确认强度。
+
 ## 报告结构
 
-最终报告至少输出：
+最终报告至少输出下面这些字段，另外写出 `lightnessShift.mean` 和 `grayRatio`（黑版为 `null`）：
 
 ```json
 {