eduevidence 5.2.0

package/visualization/eduevidence-report/motion/motion.css

@@ -0,0 +1,157 @@
+/* EduEvidence Motion Template
+   Motion explains hierarchy only. It never changes evidence meaning or numeric state. */
+
+.motion-ready [data-animate] {
+  opacity:0;
+  transform:translateY(10px);
+  transition:opacity .52s cubic-bezier(.22,.61,.36,1),
+             transform .52s cubic-bezier(.22,.61,.36,1);
+  transition-delay:var(--motion-delay,0ms);
+}
+.motion-ready [data-animate].is-visible { opacity:1; transform:none; }
+
+.motion-ready .quality-meter i,
+.motion-ready .balance-track i {
+  transform:scaleX(0);
+  transform-origin:left center;
+  transition:transform .72s cubic-bezier(.22,.61,.36,1) var(--motion-delay,0ms);
+}
+.motion-ready .quality-meter.is-visible i,
+.motion-ready .balance-track.is-visible i { transform:scaleX(1); }
+
+.motion-ready .flow-arrow {
+  opacity:.18;
+  transform:translateX(-4px);
+  transition:opacity .36s ease, transform .36s ease;
+  transition-delay:var(--motion-delay,0ms);
+}
+.motion-ready .flow-arrow.is-visible { opacity:1; transform:none; }
+
+.motion-ready .detail-expander[open] .detail-body {
+  animation:eduevidenceDetailReveal .24s cubic-bezier(.22,.61,.36,1) both;
+}
+@keyframes eduevidenceDetailReveal {
+  from { opacity:0; transform:translateY(-4px); }
+  to { opacity:1; transform:none; }
+}
+
+.motion-ready .report-page:not([hidden]) {
+  animation:eduevidencePageReveal .24s cubic-bezier(.22,.61,.36,1) both;
+}
+@keyframes eduevidencePageReveal {
+  from { opacity:0; transform:translateY(4px); }
+  to { opacity:1; transform:none; }
+}
+
+.motion-ready .full-report-toc a {
+  transition:color .18s ease, background-color .18s ease,
+             border-color .18s ease, box-shadow .18s ease;
+}
+
+/* ────────────────────────────────────────────────────────────────────────
+   data-lieflat gallery reveal — aligned with the Lieflat mono-tokens spec:
+     lf-pop  scale 0→1, cubic-bezier(.2,.7,.3,1.3), 500ms (quarticOut family)
+     lf-fade 900ms ease
+     lf-draw dasharray 1, 1s cubic-bezier(.4,0,.2,1)
+     --motion-delay inline variable carries the per-element stagger
+     (dot matrices 8–15ms, bars 80–130ms — set by the renderer).
+   Gated by .js-lf (added by motion.js only when JS runs and motion is not
+   reduced): without JS everything stays visible — static-first, never broken.
+   .is-live on the [data-lieflat] card starts the one-shot reveal; removing
+   and re-adding it replays (click-to-replay, timers cleared by motion.js).
+   ──────────────────────────────────────────────────────────────────────── */
+.js-lf [data-lieflat] .lf-pop,
+.js-lf [data-lieflat] .lf-fade,
+.js-lf [data-lieflat] .lf-draw { opacity:0; }
+.js-lf [data-lieflat] .lf-draw { stroke-dasharray:1; stroke-dashoffset:1; }
+
+.js-lf [data-lieflat].is-live .lf-pop {
+  opacity:1;
+  transform-box:fill-box;
+  transform-origin:center;
+  animation:eduevidenceLfPop .5s cubic-bezier(.2,.7,.3,1.3) both;
+  animation-delay:var(--motion-delay,0ms);
+}
+.js-lf [data-lieflat].is-live .lf-fade {
+  opacity:1;
+  animation:eduevidenceLfFade .9s ease both;
+  animation-delay:var(--motion-delay,0ms);
+}
+.js-lf [data-lieflat].is-live .lf-draw {
+  animation:eduevidenceLfDraw 1s cubic-bezier(.4,0,.2,1) both;
+  animation-delay:var(--motion-delay,0ms);
+}
+@keyframes eduevidenceLfPop {
+  from { transform:scale(0); opacity:0; }
+  to { transform:none; opacity:1; }
+}
+@keyframes eduevidenceLfFade {
+  from { opacity:0; }
+  to { opacity:1; }
+}
+@keyframes eduevidenceLfDraw {
+  to { stroke-dashoffset:0; }
+}
+
+.js-lf [data-lieflat] { cursor:pointer; }
+
+@media (hover:hover) {
+  .motion-ready .tribunal-card:hover,
+  .motion-ready .trace-chain-card:hover,
+  .motion-ready .outcome-group:hover,
+  .motion-ready .action-node:hover,
+  .motion-ready .method-audit-item:hover {
+    transform:translateY(-2px);
+  }
+  .motion-ready .evidence-matrix tbody tr:hover .dir {
+    transform:translateY(-1px);
+    filter:saturate(1.08);
+  }
+}
+
+@media (prefers-reduced-motion:reduce) {
+  .motion-ready [data-animate],
+  .motion-ready .quality-meter i,
+  .motion-ready .balance-track i,
+  .motion-ready .flow-arrow,
+  .motion-ready .dir,
+  .motion-ready .detail-body,
+  .motion-ready .report-page,
+  .motion-ready .full-report-toc a {
+    opacity:1 !important;
+    transform:none !important;
+    transition:none !important;
+    animation:none !important;
+  }
+  .js-lf [data-lieflat] .lf-pop,
+  .js-lf [data-lieflat] .lf-fade {
+    opacity:1 !important;
+    transform:none !important;
+    animation:none !important;
+  }
+  .js-lf [data-lieflat] .lf-draw {
+    opacity:1 !important;
+    animation:none !important;
+    stroke-dasharray:none !important;
+    stroke-dashoffset:0 !important;
+  }
+  html { scroll-behavior:auto; }
+}
+
+@media print {
+  [data-animate], .quality-meter i, .balance-track i, .flow-arrow {
+    opacity:1 !important;
+    transform:none !important;
+    transition:none !important;
+    animation:none !important;
+  }
+  [data-lieflat] .lf-pop,
+  [data-lieflat] .lf-fade,
+  [data-lieflat] .lf-draw {
+    opacity:1 !important;
+    transform:none !important;
+    animation:none !important;
+    stroke-dasharray:none !important;
+    stroke-dashoffset:0 !important;
+  }
+}

package/visualization/eduevidence-report/motion/motion.js

@@ -0,0 +1,107 @@
+/* EduEvidence Motion Template — one-shot progressive enhancement.
+   The [data-lieflat] gallery block implements the Lieflat mono-tokens
+   obsReveal contract: reveal once when scrolled into view (threshold .3),
+   click to replay (per-id timers cleared first so animations never stack),
+   prefers-reduced-motion downgrade, and static-visible without JS. */
+(function () {
+  'use strict';
+  var root = document.documentElement;
+  var reduceMotion = !!(window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches);
+  window.__EDUEVIDENCE_REDUCE_MOTION__ = reduceMotion;
+  if (reduceMotion) return;
+
+  root.classList.add('motion-ready');
+  root.classList.add('js-lf');
+  var groups = [
+    ['.decision-hero', 0], ['.hero-insight', 70], ['.brief-block', 55],
+    ['.outcome-group', 70], ['.tribunal-card', 75], ['.method-audit-item', 45],
+    ['.trace-chain-card', 70], ['.action-node', 60], ['.flow-arrow', 60],
+    ['.phase', 60], ['.full-chapter', 35], ['.brief-source', 40]
+  ];
+  groups.forEach(function (entry) {
+    document.querySelectorAll(entry[0]).forEach(function (el, index) {
+      el.setAttribute('data-animate', '');
+      el.style.setProperty('--motion-delay', Math.min(index * entry[1], 320) + 'ms');
+    });
+  });
+  document.querySelectorAll('.quality-meter,.balance-track').forEach(function (el, index) {
+    el.style.setProperty('--motion-delay', Math.min((index % 8) * 35, 210) + 'ms');
+  });
+
+  var animated = document.querySelectorAll('[data-animate],.quality-meter,.balance-track,.flow-arrow');
+  if (!('IntersectionObserver' in window)) {
+    animated.forEach(function (el) { el.classList.add('is-visible'); });
+  } else {
+    var observer = new IntersectionObserver(function (entries, obs) {
+      entries.forEach(function (entry) {
+        if (!entry.isIntersecting) return;
+        entry.target.classList.add('is-visible');
+        obs.unobserve(entry.target);
+      });
+    }, {threshold:.12, rootMargin:'0px 0px -6% 0px'});
+    animated.forEach(function (el) { observer.observe(el); });
+  }
+
+  // ---- data-lieflat gallery: reveal on scroll, click to replay ----
+  // Per-container timers (mirrors mono-tokens `keep`): every scheduled
+  // replay step is registered under the container id and cleared before the
+  // next replay so staggered animations never stack on rapid clicking.
+  var lfTimers = {};
+  var lfBoxes = Array.prototype.slice.call(document.querySelectorAll('[data-lieflat]'));
+  lfBoxes.forEach(function (box, index) {
+    var base = (box.dataset.chartId || 'figure');
+    var safe = 'lf-' + index + '-' + (window.CSS && CSS.escape ? CSS.escape(base) : base.replace(/[^a-zA-Z0-9_-]/g, '-'));
+    box.dataset.lfId = safe;
+    if (!box.hasAttribute('aria-label')) {
+      box.setAttribute('aria-label', 'Lieflat chart — click to replay the reveal animation');
+    }
+  });
+
+  function clearLfTimers(id) {
+    (lfTimers[id] || []).forEach(function (t) { if (t) clearTimeout(t); });
+    lfTimers[id] = [];
+  }
+
+  // Entrance choreography: cards revealed shortly after load (already in the
+  // viewport) get a short visual stagger so the draw-in is actually seen —
+  // without this, the load-time reveal finishes before the user looks and the
+  // charts appear static until clicked. Scrolled-in and click reveals play
+  // immediately.
+  var bootTime = Date.now();
+  function revealDelay(box, index) {
+    var fresh = Date.now() - bootTime < 1500;
+    if (!fresh) return 40;
+    return 140 + ((index % 6) * 130);
+  }
+
+  function replayLieflat(box, delay) {
+    var id = box.dataset.lfId;
+    delay = (delay === undefined ? 40 : delay);
+    clearLfTimers(id);
+    box.classList.remove('is-live');
+    // force reflow so the re-added class restarts the CSS animations
+    void box.offsetWidth;
+    var tid = setTimeout(function () {
+      box.classList.add('is-live');
+      lfTimers[id] = lfTimers[id].filter(function (t) { return t !== tid; });
+    }, delay);
+    lfTimers[id].push(tid);
+  }
+
+  if (!('IntersectionObserver' in window)) {
+    lfBoxes.forEach(function (box) { box.classList.add('is-live'); });
+  } else {
+    var lfObserver = new IntersectionObserver(function (entries, obs) {
+      entries.forEach(function (entry) {
+        if (!entry.isIntersecting) return;
+        var index = lfBoxes.indexOf(entry.target);
+        replayLieflat(entry.target, revealDelay(entry.target, index));
+        obs.unobserve(entry.target);
+      });
+    }, {threshold:.3});
+    lfBoxes.forEach(function (box) { lfObserver.observe(box); });
+  }
+  lfBoxes.forEach(function (box, index) {
+    box.addEventListener('click', function () { replayLieflat(box, 0); });
+  });
+})();

package/visualization/eduevidence-report/references/bilingual-style.md

@@ -0,0 +1,7 @@
+# Bilingual Rendering Style
+
+Chinese mode translates stable UI labels, section titles, methodology keys, flow labels and enumerations. It does not rewrite freeform research claims or evidence prose in the renderer.
+
+Allowed to remain in English in Chinese mode: AI, RCT, DOI, Evidence ID, Claim ID, Source ID, and original paper titles. Original titles should be explicitly labeled `原文标题`.
+
+If `result.zh.json` lacks a localized freeform field, preserve the source text and mark it as original text rather than silently generating a new translation.

package/visualization/eduevidence-report/references/component-catalog.md

@@ -0,0 +1,145 @@
+# HTML Component Catalog（结果层冻结组件）
+
+> LLM 可以规划章节和选择已有组件，但不能自由编写影响证据语义的 DOM / chart 逻辑。组件固定，章节组合动态。
+
+## 1. Shell / 导航
+
+| 组件 | 职责 |
+|---|---|
+| `ReportShell` | 单文件离线报告外壳 |
+| `GeneratedThemeMarker` | 显示生成时选择的五种视觉系统之一 |
+| `LanguageSwitcher` | 中文 / English 切换 |
+| `PageSwitcher` | Visual Brief / Full Report 一级分页 |
+| `FullReportReader` | 左 TOC + 右完整报告阅读器 |
+| `CollapsibleTOC` | 读取动态 5–7 章 outline；sticky / active / collapse |
+| `FullChapter` | AI 规划后的章节容器，只组合语义模块，不修改研究数据 |
+
+## 2. 决策 / 摘要
+
+| 组件 | 职责 |
+|---|---|
+| `DecisionHero` | Decision / Confidence / strongest claim / uncertainty / risk / action |
+| `ConfidenceBadge` | High / Moderate / Low / Insufficient |
+| `VisualBriefBlock` | 摘要页高价值模块容器；不是完整报告章节 |
+| `KeySourceCards` | 摘要页只显示少量关键来源 |
+
+## 3. Outcome / Visualization
+
+| 组件 | 引擎 | 职责 |
+|---|---|---|
+| `OutcomeSeparation` | HTML/CSS | Task / Learning / Retention / Transfer / Risk 构念分离 |
+| `EvidenceBalance` | SVG/ECharts | 基于 `effect_direction` 的正向/负向/零效应比较；只有 Gate 通过才渲染 |
+| `LieflatGalleryCard` | 内联 SVG（charts_data + lieflat_engine） | AI 组合的数据驱动 Lieflat 图卡：结论式标题 + 副标题（图例 `·` 分隔）+ 主题化 SVG + 全大写来源行 + 可选图注；`data-lieflat` / `data-visual` 属性供 motion 与测试定位 |
+| `LieflatSuppressed` | HTML | 数据不足时列出被抑制图型与原因（镜像 Meaningful Visualization Gate） |
+| `InteractiveChart` | ECharts | 有信息增益的交互分析图 |
+| `AcademicFigure` | Academic Figures | 出版级静态图（outcome-comparison / benchmark / forest，保持主题无关） |
+| `InfographicBlock` | SVG / AntV | 流程、干预、评价等语义图 |
+| `VisualizationSuppressed` | HTML | 数据不足时解释为什么不画图 |
+
+Lieflat 图卡只渲染 `resolve_visual_layout` 校验通过的 `visual_layout` 条目；每个条目经注册表（`references/lieflat-composition.md`）提取器出数，未注册 type 显式报错。完整性门 `lieflat_data_bound` 逐值核对数值溯源。
+
+## 4. Evidence / progressive disclosure
+
+| 组件 | 职责 |
+|---|---|
+| `EvidenceMatrix` | 6 列主视图：Evidence ID / Outcome / Effect / Quality / Claim / Source |
+| `EvidenceRow` | 单条 Evidence 摘要 |
+| `ExpandableEvidence` | 展开 study/sample/design/intervention/comparison/effect/quality/source 等完整字段 |
+| `QualityMeter` | 仅表达已有 quality_score |
+| `SafeSourceLink` | 只允许 http / https 可点击 URL |
+
+Outcome/Matrix 的主方向使用 `effect_direction`。`relation_to_claim` 只作为次级 Claim relation 显示。
+
+## 5. Adjudication / methodology / trace
+
+| 组件 | 职责 |
+|---|---|
+| `TribunalView` | Supported / Uncertain / Contradicted / Missing Evidence |
+| `ExpandableTribunalClaim` | 长裁决文本和 Evidence IDs 渐进展开 |
+| `MethodologyPanel` | compact status surface |
+| `ExpandableMethodology` | 展开每项 methodology note |
+| `ConflictCard` | 去重后的冲突/异质性解释 |
+| `ClaimTrace` | Claim → Evidence → Outcome → Effect → Quality → Source |
+
+## 6. Applicability / intervention / evaluation
+
+| 组件 | 职责 |
+|---|---|
+| `ApplicabilityCard` | Suitable / not suitable / conditions / boundary |
+| `EvidenceToAction` | Evidence → Applicability → Decision → Guardrails → Stop → Evaluation |
+| `InterventionTimeline` | 教学试点阶段 |
+| `EvaluationFlow` | Baseline → Post → Retention → Transfer |
+| `StopConditionBlock` | 失败/停止条件 |
+
+## 7. Sources / provenance
+
+| 组件 | 职责 |
+|---|---|
+| `SourceList` | Source ID / original title / year / authority / location |
+| `ExpandableSource` | canonical URL / source location / fetch metadata |
+| `ProvenancePanel` | 只显示真实存在的 fetch metadata；空 fetch 不生成空表 |
+| `Footnote` | 模式 / 版本 / integrity 状态 |
+
+## 8. Motion Template
+
+| 组件 | 职责 |
+|---|---|
+| `MotionTemplate` | 统一 section/stagger/bar/trace/flow/detail/page/toc 动画 |
+| `ChartReveal` | `data-lieflat` 图卡的 mono-tokens reveal：滚入视野（threshold .3）播一次 + 点击重播（timer 清理）+ reduced-motion 降级 + 无 JS 静态可见 |
+
+动画由 `motion/motion.css` + `motion/motion.js` 固化。五种主题不得创建不同的科学/数据动画逻辑，`chart-reveal` 为固定模板角色（见 `references/motion-system.md`）。
+
+## 9. Dynamic Report Planner
+
+AI 不创建新组件，而是把固定语义模块组合成 5–7 个章节：
+
+```text
+decision · scope · retrieval · outcomes · evidence · quality
+conflicts · trace · applicability · intervention · evaluation · sources
+```
+
+规则：
+
+1. 第一章包含 `decision`。
+2. 最后一章包含 `sources`。
+3. 全部模块覆盖且每个恰好一次。
+4. AI 可以自由命名章节和合并中间模块。
+5. Invalid outline → safe six-chapter fallback。
+
+章节之外的**图表计划**由 AI 写入 `visual_layout`（每图一个独立结论、≤6 张、形状不重复），渲染器只执行注册表校验通过的条目；数值一律由提取器从 `result.json` 出数（`references/lieflat-composition.md`）。
+
+## 10. 五种主题共用组件，不共用排版
+
+同一组件在五种主题中可以改变：
+
+- 宽度和列布局。
+- 卡片/横线/面板策略。
+- TOC 外观。
+- Brief 模块网格。
+- 表格密度。
+- 标题尺度和章节节奏。
+
+不能改变：
+
+- Evidence / Claim / Verdict / Confidence。
+- `effect_direction`。
+- 数据数量。
+- 页面功能与 Evidence 展开能力。
+- Meaningful Visualization Gate。
+
+**排版守则（硬性，见 `references/layout-constraints.md`）**：主题规则特殊性高于基座断点——
+凡 ≥2 列含 px 最小值的 `grid-template-columns`，主题必须自带 `@media (max-width:980px)` 覆写；
+轨道用 `minmax(0,1fr)` 或 `minmax(min(Npx,100%),1fr)`，禁止裸 `1fr` 与固定 px 最小值 auto-fit。
+改动后跑 `scripts/lint_report_layout.py`（静态 + 浏览器级 390/768/1280 × brief/full）。
+
+## 11. 自检
+
+- [ ] 同一 result 生成五种主题，数据与章节内容覆盖完全一致。
+- [ ] 五种主题的首屏、Brief 排版、TOC、正文宽度、章节 surface 明显不同。
+- [ ] Visual Brief / Full Report 都可切换。
+- [ ] 5–7 章 TOC 自动读取 outline。
+- [ ] 无 JS 时核心研究内容仍存在于 HTML。
+- [ ] 打印只输出完整报告并暴露 detail 内容。
+- [ ] Outcome visual 使用 `effect_direction`，不是 Claim support。
+- [ ] `lint_report_layout.py` PASS：五主题静态不变量 + 浏览器级（390/768/1280 × brief/full）无溢出、reveal 生效。
+- [ ] 手机（390px）与平板（768px）实测：无横向滚动、无裁切、图表完整、点击重播动画正常。

package/visualization/eduevidence-report/references/evidence-expansion.md

@@ -0,0 +1,65 @@
+# Evidence Expansion Contract
+
+Evidence is progressive disclosure, not a flat wall of prose.
+
+## Compact matrix
+
+Default columns:
+
+```text
+Evidence ID | Outcome | Effect | Quality | Claim | Source
+```
+
+`Effect` is derived from `evidence.effect_direction` (`positive / negative / null`). `relation_to_claim` is shown only as a secondary relationship note.
+
+## Full expansion
+
+When present, expose:
+
+```text
+study_id
+sample_id
+title
+year
+study_type
+education_level
+population
+sample_size
+intervention
+comparison
+outcome_measure
+claim
+effect
+effect_direction
+relation_to_claim
+duration
+method
+strengths
+limitations
+confounders
+quality_dimensions
+quality_score
+evidence_level
+directness
+applicability
+confidence
+status
+extensions.claim_id
+source_id
+source_location
+canonical_url
+```
+
+Missing fields are omitted. The renderer must not manufacture placeholders that could be mistaken for research data.
+
+## Long text
+
+Brief surfaces show an exact prefix excerpt. Clicking the native `<details>` control reveals the complete original string. The renderer may normalize whitespace but may not paraphrase, strengthen, weaken or translate the claim to create a shorter version.
+
+## Source safety
+
+Only `http` / `https` locations become links. Other source locations remain plain text.
+
+## Print
+
+Print mode exposes detail content and hides interactive summaries so scientific information is not lost in PDF/print export.

package/visualization/eduevidence-report/references/full-report-outline.md

@@ -0,0 +1,86 @@
+# Full Report Outline
+
+EduEvidence HTML contains two top-level views in one offline file:
+
+1. **Visual Brief** — default, scan-first, preserves the visual summary experience.
+2. **Full Report** — audit-first, desktop uses a collapsible sticky TOC and continuous report body.
+
+## Dynamic 5–7 chapter rule
+
+The Full Report is **not** a frozen 12-chapter document. An upstream AI should organize the research into **5–7 chapters** based on the actual evidence story.
+
+The renderer works with semantic modules rather than fixed chapters:
+
+```text
+decision
+scope
+retrieval
+outcomes
+evidence
+quality
+conflicts
+trace
+applicability
+intervention
+evaluation
+sources
+```
+
+The AI may merge and reorder middle modules and write research-specific chapter titles. Examples:
+
+- `retrieval + quality` → “证据从哪里来，以及它们有多可信”
+- `outcomes + evidence` → “效率提升背后的学习结果分化”
+- `conflicts + trace` → “为什么证据冲突，以及哪些主张仍可成立”
+- `applicability + intervention` → “从适用边界到有护栏试点”
+
+Constraints:
+
+- 5–7 chapters total.
+- First chapter contains `decision`.
+- Last chapter contains `sources`.
+- Every semantic module appears exactly once.
+- No evidence, contradiction, methodology audit or source provenance may be dropped by chapter merging.
+- If an AI outline is invalid, the renderer falls back to a safe six-chapter grouping.
+
+## Optional `report_outline`
+
+```json
+{
+  "report_outline": {
+    "chapters": [
+      {
+        "key": "decision",
+        "title_zh": "结论与研究边界",
+        "title_en": "Decision and Research Boundary",
+        "lead_zh": "先明确可以得出什么结论，再解释为什么。",
+        "lead_en": "State what can be concluded before explaining why.",
+        "modules": ["decision", "scope"]
+      }
+    ]
+  }
+}
+```
+
+## Visual insertion rules
+
+A chapter may include a chart or semantic visual only when it adds information beyond adjacent text/table. Sparse states such as `1 support / 0 contradict / 0 neutral` stay as badges/text. Every meaningful visual must have an interpretation caption explaining what the reader should take from it.
+
+Outcome visuals must encode `effect_direction` (`positive / negative / null`), not `relation_to_claim`. Evidence can support a claim that an intervention caused a harmful outcome; therefore `support` is not equivalent to a positive effect.
+
+**Lieflat gallery insertion** goes through the registry (`references/lieflat-composition.md`): the AI writes `visual_layout` entries (type + catalog ref + bilingual copy + source + params), and the renderer draws each entry from its extractor bundle only. Unregistered types are rejected, insufficient data suppresses the chart with a recorded reason, and a missing/invalid layout falls back to the deterministic safe combination (forest_plot + dot_cascade + bubble_almanac + tick_rows).
+
+## Progressive disclosure
+
+Evidence, methodology audit items, tribunal claims and sources default to compact summaries and expose full traceable detail through accessible native `<details>/<summary>` controls. Print mode must not lose the hidden evidence content.
+
+## Five themes, one content contract
+
+The same Visual Brief / Full Report structure, dynamic outline and evidence content are rendered through five clearly differentiated layout templates:
+
+- Claude Research [Light] — calm research reader.
+- Academic Paper [Light] — journal/paper layout.
+- DataLab [Light] — light analytical workbench.
+- DataLab [Dark] — dark analytical workbench with the same information architecture.
+- Presentation / Judge [Dark] — review/presentation layout.
+
+Theme differences may include header composition, Brief grid, TOC appearance, body width, chapter surfaces, table density and data breakout width. Themes may not change evidence semantics or chapter content coverage.

package/visualization/eduevidence-report/references/layout-constraints.md

@@ -0,0 +1,63 @@
+# Layout Constraints — 五主题报告排版守则（移动端 + 桌面）
+
+EduEvidence 的五套烘焙主题（claude / academic / datalab / datalab-dark / presentation）
+共用同一内容契约，但各自拥有排版策略。主题是实现层的自由舞台，**但不能破坏阅读**：
+任何加入/修改主题 CSS 或渲染器内联样式的人，都必须遵守以下不变量，并在改动后跑
+
+```bash
+python3 scripts/lint_report_layout.py --html-dir examples/ai-coding-assistant-50/reports-5themes
+```
+
+静态审计 + 浏览器级实测（390 / 768 / 1280 px × Visual Brief / Full Report）全部通过才能合入。
+
+## 1. 为什么会有这套守则（历史教训）
+
+- `:root[data-theme="X"] .selector` 特异性是 0,2,0，**压过**基座 `@media (max-width:980px)` 的 0,1,0 断点。
+  之前五套主题的桌面 `full-report-layout { grid-template-columns:210px minmax(0,1fr) }` 在手机上
+  把内容列挤到 ~104px（390 视口下横向裁切）；`repeat(auto-fit,minmax(240px,1fr))` 的内在尺寸
+  爆炸让 768px 平板的第二列结果直接消失在视口外（shell scrollWidth 1025 > 768）。
+- 修复范式 = 基座断点提供安全网 + **每个主题在自己的 @media ≤980 内重新声明响应式覆写**。
+
+## 2. 硬性不变量（static lint 会逐条检查）
+
+1. **移动端轨道收缩安全**
+   - 网格列一律 `minmax(0, 1fr)`（绝不允许裸 `1fr`，它按内容 min-content 定宽）。
+   - `repeat(auto-fit, minmax(Npx, 1fr))` 一律写成 `repeat(auto-fit, minmax(min(Npx,100%), 1fr))`，
+     让最小值随容器收缩，杜绝内在尺寸爆炸。
+2. **主题必须自带移动端覆写**
+   - 主题里任何 ≥2 列、含 px 最小值的 `grid-template-columns`（如 full-report-layout、
+     report-page-brief、hero-insights、tribunal-grid、brief-source-grid、outcome-groups……）
+     都必须在**同一主题文件**的 `@media (max-width:980px)` 内提供等效单列/收缩覆写——
+     基座断点压不过主题特异性。
+   - 媒体查询外出现裸 `grid-template-columns:1fr` 直接违规。
+3. **基座安全网必须存在**（build_report.py 内联样式）：`html,body` 的 `overflow-x:hidden`；
+   @media 980 的 `minmax(0,1fr)`；@media 720 的网格 item `min-width:0` 清单与
+   `.outcome-groups` / `.evidence-detail-grid,.source-detail-grid` 收缩覆写。
+4. **表格与长文本**：任何数据表外包 `.table-wrap { overflow-x:auto }`（滚动而不是撑破页面）；
+   `.source-detail-grid dd` / `.claim-cell` 等长文本位点 `overflow-wrap:anywhere`。
+
+## 3. 浏览器级门（check_mobile_layout.js）
+
+无依赖 Node 脚本（Node ≥21，CDP 驱动 headless Chrome），对每个报告在
+390 / 768 / 1280 × brief / full 检查：
+
+- `documentElement.scrollWidth > innerWidth` → 页面级横向溢出；
+- 可见 `.report-shell` 的 `scrollWidth > clientWidth` → 内容被裁切；
+- 逃逸视口且不在滚动容器/`<svg>` 内的元素 → 真溢出（表内/横向操作条内滚动是合法的）；
+- 画廊卡片：滚入后必须全部拿到 `is-live`（reveal 契约：滚入播放 + 点击重播）。
+
+无 Chrome/Node 的环境跳过浏览器级阶段（pytest 用 `skipif` 处理）。
+
+## 4. 移动端体验红线
+
+- 390px：单列全内容可读；控件（lang/视图切换）不挤压标题；图表 `width:100%` 自适应。
+- 768px（平板）：两列工作台可优雅回退单列，不出现半列被裁。
+- `prefers-reduced-motion` / 打印：图表静态完整可见（motion.css 已覆盖 `data-lieflat`）。
+- 新滚动容器（`overflow-x:auto`）只是"容器内滚动"，不得让 `.report-shell` 自身出现横向滚动条。
+
+## 5. 验收清单（改动后必跑）
+
+- [ ] `python3 scripts/lint_report_layout.py --html-dir <报告目录>` → PASS
+- [ ] `python3 scripts/rebake_all_5themes.py` 重烘焙无回归
+- [ ] `python3 -m pytest tests/test_report_layout_mobile.py -q` 全绿
+- [ ] 手机实机（或 Chrome 设备模拟）打开 15 份报告：无横向滚动、图表完整、点击可重播动画