feat(world): 熵可视化世界信号派生层与深海实体辉光接线（宪法P1第一批）

- worldState.ts：retention引擎数据→世界信号集纯函数派生（vitality/mist/depthNorm/firefly/warmth），宪法边界硬编码：雾上限0.4、关闭留存→纯净亮度映射、冷启动=未点亮混沌、辉光域0.6-1.15无惩罚性暗淡
- useWorldSignals.ts：细粒度selector订阅hook，帧率敏感场景防连带重渲染
- worldState.test.ts：7用例覆盖宪法§1/§5/§7关键约束
- ModuleEntity/SpatialNav：深海实体辉光=交互态基值×世界活力（珊瑚健康度），宪法第一条映射表首次落地

Author: Aparencia

client/src/features/retention/hooks/useWorldSignals.ts

@@ -0,0 +1,43 @@
+/**
+ * 世界信号订阅 Hook
+ * World signals subscription hook
+ *
+ * @ai-context: 订阅珊瑚生态/深海发现/留存设置 store，实时派生世界信号集，
+ * 供 3D 场景层（SpatialNav 实体辉光、后续混沌雾/萤火/洋流）消费。
+ * streak 尚未接入 store（StreakBubble 走 props 传递），潮汐批次接线时补真实值。
+ *
+ * @ai-context: Subscribes to retention stores and derives live world signals
+ * for the 3D scene layer. Streak wiring lands with the tide batch.
+ */
+import { useMemo } from 'react';
+import { useEcosystemStore } from '../store/useEcosystemStore';
+import { useDiscoveryStore } from '../store/useDiscoveryStore';
+import { useRetentionSettings } from '../store/useRetentionSettings';
+import {
+  deriveWorldSignals,
+  vitalityToGlowScale,
+  type WorldSignals,
+} from '../lib/worldState';
+
+/** 世界信号 + 派生的实体辉光乘数 / Signals plus derived glow multiplier */
+export type WorldSignalsWithGlow = WorldSignals & { glowScale: number };
+
+export function useWorldSignals(): WorldSignalsWithGlow {
+  // 细粒度 selector：避免整 store 订阅连带重渲染（3D 场景对帧率敏感）
+  const corals = useEcosystemStore((s) => s.corals);
+  const totalDepth = useEcosystemStore((s) => s.totalDepth);
+  const discoveriesCount = useDiscoveryStore((s) => s.totalCount);
+  const enabled = useRetentionSettings((s) => s.enabled);
+
+  return useMemo(() => {
+    const signals = deriveWorldSignals({
+      corals,
+      totalDepth,
+      discoveriesCount,
+      // TODO(潮汐批次): streak store 接线后替换为真实连击值
+      currentStreak: 0,
+      enabled,
+    });
+    return { ...signals, glowScale: vitalityToGlowScale(signals.vitality) };
+  }, [corals, totalDepth, discoveriesCount, enabled]);
+}

client/src/features/retention/lib/worldState.test.ts

@@ -0,0 +1,126 @@
+/**
+ * 世界状态派生层单元测试
+ * Unit tests for the world state derivation layer
+ *
+ * @ai-context: 覆盖《熵可视化设计宪法》关键约束：焦虑防线雾上限 0.4、
+ * 关闭留存→中性信号、冷启动非空白、无负向输出语义。
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  deriveWorldSignals,
+  vitalityToGlowScale,
+  WORLD_ANCHORS,
+} from './worldState';
+import type { CoralRecord } from '../types';
+
+function makeCoral(health: CoralRecord['health'], id = Math.random().toString(36)): CoralRecord {
+  return {
+    id,
+    type: 'branching',
+    health,
+    plantedAt: new Date(),
+    sourceSession: 'test',
+    depth: 10,
+  };
+}
+
+const base = {
+  corals: [] as CoralRecord[],
+  totalDepth: 0,
+  discoveriesCount: 0,
+  currentStreak: 0,
+  enabled: true,
+};
+
+describe('deriveWorldSignals', () => {
+  it('should return neutral signals when retention is disabled (焦虑防线 §5)', () => {
+    // Arrange：留存关闭，即使存在白化珊瑚
+    const input = { ...base, corals: [makeCoral('bleached')], enabled: false };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert：纯净亮度映射——满活力、无雾
+    expect(s.vitality).toBe(1);
+    expect(s.mist).toBe(0);
+    expect(s.enabled).toBe(false);
+  });
+
+  it('should return unlit-chaos world on cold start (宪法第七条：非空白)', () => {
+    // Arrange：无任何珊瑚
+    const input = { ...base };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert：中性活力 + 薄雾，暗示可能性而非空洞
+    expect(s.vitality).toBe(WORLD_ANCHORS.VITALITY_COLD_START);
+    expect(s.mist).toBe(WORLD_ANCHORS.MIST_COLD_START);
+    expect(s.depthNorm).toBe(0);
+  });
+
+  it('should map healthy ratio to vitality and zero mist when all healthy', () => {
+    // Arrange：全部健康
+    const input = { ...base, corals: [makeCoral('healthy'), makeCoral('healthy')] };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert
+    expect(s.vitality).toBe(1);
+    expect(s.mist).toBe(0);
+  });
+
+  it('should map bleached ratio to mist proportionally', () => {
+    // Arrange：一半白化
+    const input = { ...base, corals: [makeCoral('healthy'), makeCoral('bleached')] };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert：0.5 × 0.4
+    expect(s.vitality).toBe(0.5);
+    expect(s.mist).toBeCloseTo(0.2);
+  });
+
+  it('should never exceed mist cap 0.4 even when fully bleached (焦虑防线 §1)', () => {
+    // Arrange：全部白化
+    const input = { ...base, corals: [makeCoral('bleached'), makeCoral('bleached')] };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert：雾封顶 40%，朦胧可拨开，永不吞噬世界
+    expect(s.mist).toBeLessThanOrEqual(WORLD_ANCHORS.MIST_MAX);
+    expect(s.vitality).toBe(0);
+  });
+
+  it('should clamp depth/firefly/warmth into 0-1', () => {
+    // Arrange：远超饱和锚点的输入
+    const input = {
+      ...base,
+      corals: [makeCoral('healthy')],
+      totalDepth: WORLD_ANCHORS.DEPTH_FULL * 10,
+      discoveriesCount: WORLD_ANCHORS.FIREFLY_FULL * 5,
+      currentStreak: WORLD_ANCHORS.STREAK_FULL * 3,
+    };
+
+    // Act
+    const s = deriveWorldSignals(input);
+
+    // Assert
+    expect(s.depthNorm).toBe(1);
+    expect(s.firefly).toBe(1);
+    expect(s.warmth).toBe(1);
+  });
+});
+
+describe('vitalityToGlowScale', () => {
+  it('should stay within the 0.6-1.15 readable band (奖赏回来：无惩罚性暗淡)', () => {
+    // Act & Assert：边界内外均收敛于可读域
+    expect(vitalityToGlowScale(0)).toBeCloseTo(0.6);
+    expect(vitalityToGlowScale(1)).toBeCloseTo(1.15);
+    expect(vitalityToGlowScale(-2)).toBeCloseTo(0.6);
+    expect(vitalityToGlowScale(9)).toBeCloseTo(1.15);
+  });
+});

client/src/features/retention/lib/worldState.ts

@@ -0,0 +1,113 @@
+/**
+ * 世界状态派生层（宪法 P1 · 数据接线）
+ * World state derivation layer (constitution P1 · data wiring)
+ *
+ * @ai-context: 从留存引擎（珊瑚/发现）数据派生熵可视化单范式所需的世界信号集。
+ * 纯函数、无副作用、可单测。所有输出遵循《熵可视化设计宪法》第一条映射表
+ * 与第二条焦虑防线：vitality→发光体亮度、mist→混沌雾（上限 0.4）、
+ * depthNorm→地质层、firefly→萤火数量、warmth→洋流温度。
+ * 留存关闭时返回中性信号（第二条 §5 可关闭性：纯净亮度映射，无雾）。
+ *
+ * @ai-context: Derives world signals for the entropy-visualization paradigm
+ * from retention engine data (corals/discoveries). Pure, testable, bounded
+ * by the design constitution's mapping table and anxiety-defense limits.
+ */
+
+import type { CoralRecord } from '../types';
+
+/** 归一化锚点（世界饱和度常量） / Normalization anchors */
+export const WORLD_ANCHORS = {
+  /** 地质层满饱和的累计深度（米） / Depth where strata saturate */
+  DEPTH_FULL: 2000,
+  /** 萤火密度满饱和的发现数 / Discoveries where firefly density saturates */
+  FIREFLY_FULL: 20,
+  /** 洋流温度满饱和的连击天数 / Streak days where warmth saturates */
+  STREAK_FULL: 7,
+  /** 混沌雾最大强度（宪法第二条 §1：≤40%） / Max mist per constitution */
+  MIST_MAX: 0.4,
+  /** 冷启动基底雾（宪法第七条：未点亮的混沌，非空白） / Cold-start base mist */
+  MIST_COLD_START: 0.12,
+  /** 冷启动世界活力中性值 / Cold-start neutral vitality */
+  VITALITY_COLD_START: 0.55,
+} as const;
+
+/** 派生输入：全部来自 retention 引擎存量 / Inputs from existing retention stores */
+export interface WorldSignalInput {
+  corals: CoralRecord[];
+  totalDepth: number;
+  discoveriesCount: number;
+  currentStreak: number;
+  /** 留存总开关：关闭→中性信号（纯净亮度映射） / Master toggle off → neutral */
+  enabled: boolean;
+}
+
+/** 世界信号集：每个字段只映射一个学习变量（宪法第一条） / One signal = one variable */
+export interface WorldSignals {
+  /** 世界活力 0–1：健康珊瑚占比 → 发光体亮度 / Healthy coral ratio → glow */
+  vitality: number;
+  /** 混沌雾强度 0–0.4：白化占比 → 遗忘（熵增） / Bleached ratio → mist */
+  mist: number;
+  /** 地质层规模 0–1：累计深度归一 / Cumulative depth normalized */
+  depthNorm: number;
+  /** 萤火密度 0–1：发现数归一 / Discovery count normalized */
+  firefly: number;
+  /** 洋流温度 0–1：连击归一 / Streak normalized */
+  warmth: number;
+  /** 留存是否开启 / Retention enabled flag */
+  enabled: boolean;
+}
+
+const clamp01 = (v: number): number => Math.min(1, Math.max(0, v));
+
+/**
+ * 派生世界信号集 / Derive the world signal set
+ *
+ * @ai-context 奖赏回来原则：白化珊瑚映射为"朦胧雾"而非消亡——
+ * 雾永远可拨开，复习（新的种植）即恢复。无任何负向输出语义。
+ */
+export function deriveWorldSignals(input: WorldSignalInput): WorldSignals {
+  const { corals, totalDepth, discoveriesCount, currentStreak, enabled } = input;
+  const depthNorm = clamp01(totalDepth / WORLD_ANCHORS.DEPTH_FULL);
+  const firefly = clamp01(discoveriesCount / WORLD_ANCHORS.FIREFLY_FULL);
+  const warmth = clamp01(currentStreak / WORLD_ANCHORS.STREAK_FULL);
+
+  // 焦虑防线 §5：用户关闭留存/混沌雾渲染 → 纯净亮度映射，无雾
+  if (!enabled) {
+    return { vitality: 1, mist: 0, depthNorm, firefly: 0, warmth: 0, enabled: false };
+  }
+
+  // 冷启动：未点亮的混沌世界（宪法第七条）——中性活力 + 薄雾，暗示可能性
+  if (corals.length === 0) {
+    return {
+      vitality: WORLD_ANCHORS.VITALITY_COLD_START,
+      mist: WORLD_ANCHORS.MIST_COLD_START,
+      depthNorm: 0,
+      firefly,
+      warmth,
+      enabled: true,
+    };
+  }
+
+  const healthy = corals.filter((c) => c.health === 'healthy').length;
+  // 白化是"暂停生长"而非消亡：占比映射为雾，上限被宪法锁死
+  const bleachedRatio = 1 - healthy / corals.length;
+
+  return {
+    vitality: healthy / corals.length,
+    mist: Math.min(WORLD_ANCHORS.MIST_MAX, bleachedRatio * WORLD_ANCHORS.MIST_MAX),
+    depthNorm,
+    firefly,
+    warmth,
+    enabled: true,
+  };
+}
+
+/**
+ * 世界活力 → 发光体辉光乘数 / Vitality → entity glow multiplier
+ *
+ * @ai-context 输出域 0.6–1.15：只调节明暗程度，永不低于可读下限，
+ * 避免"暗淡=惩罚"的负向语义（奖赏回来原则）。
+ */
+export function vitalityToGlowScale(vitality: number): number {
+  return 0.6 + clamp01(vitality) * 0.55;
+}

client/src/lib/3d/navigation/SpatialNav.tsx

@@ -19,6 +19,7 @@ import { OrbitControls } from '@react-three/drei';
 import { useOrbitalStore, MODULE_POSITIONS, type ModuleId } from './OrbitalStore';
 import { useSceneTheme } from '../hooks/useSceneTheme';
 import { ModuleEntity } from '../objects/ModuleEntity';
+import { useWorldSignals } from '@/features/retention/hooks/useWorldSignals';
 import { AuroraModuleEntity } from '../objects/AuroraModuleEntity';
 import { CameraController } from '../core/CameraController';
 import { useCameraFlight } from '../hooks/useCameraFlight';
@@ -76,6 +77,8 @@ export function SpatialNav() {
   const { phase, overlayVisible, currentModule, hoveredModule, highlightAll, enterModule, setHovered } = useOrbitalStore();
   const { flyTo, update } = useCameraFlight();
   const { shouldDegrade3D } = useRuntimeEnv();
+  // 世界信号：实体辉光随学习数据（珊瑚健康度）明暗——宪法第一条接线（第一批仅深海实体）
+  const worldSignals = useWorldSignals();
 
   // 点击入口记录的行星实时世界坐标（飞行 effect 优先消费），点击后才有效
   const clickFlightPosRef = useRef<Partial<Record<ModuleId, [number, number, number]>>>({});
@@ -200,6 +203,7 @@ export function SpatialNav() {
               geometry={config.geometry}
               color={config.color}
               emissiveColor={config.emissiveColor}
+              glowScale={worldSignals.glowScale}
               isHovered={hoveredModule === module.id || highlightAll}
               // 选中态需结合相位：Esc 退出后 currentModule 保留（页面状态存活），但视觉选中必须解除
               isActive={phase !== 'overview' && currentModule === module.id}

client/src/lib/3d/objects/ModuleEntity.tsx

@@ -22,6 +22,12 @@ interface ModuleEntityProps {
   isHovered: boolean;
   isActive: boolean;
   showLabel?: boolean;
+  /**
+   * 世界活力辉光乘数（宪法第一条：掌握度=亮度）。
+   * 由 useWorldSignals 派生，域 0.6–1.15：只调明暗、永不惩罚性暗淡。
+   * World vitality glow multiplier (constitution §1: mastery = brightness).
+   */
+  glowScale?: number;
   onClick: () => void;
   onPointerOver: () => void;
   onPointerOut: () => void;
@@ -75,6 +81,7 @@ export function ModuleEntity({
   isHovered,
   isActive,
   showLabel = false,
+  glowScale = 1,
   onClick,
   onPointerOver,
   onPointerOut,
@@ -96,7 +103,8 @@ export function ModuleEntity({
 
   // Target states for lerp transitions
   const targetScale = isActive ? 1.3 : isHovered ? 1.15 : 1.0;
-  const targetEmissive = isActive ? 1.2 : isHovered ? 0.8 : 0.3;
+  // 辉光 = 交互态基值 × 世界活力（学习数据的亮度映射，宪法第一条）
+  const targetEmissive = (isActive ? 1.2 : isHovered ? 0.8 : 0.3) * glowScale;
 
   useFrame((_, delta) => {
     if (!meshRef.current) return;