feat(validate): strengthen manim layout checks and enforce single font lint

Co-authored-by: John Menke <jmjava@gmail.com>

Author: cursoragent

README.md

@@ -77,16 +77,30 @@ manim:
 vhs:
   vhs_path: ""              # optional explicit binary path (relative to docgen.yaml or absolute)
   sync_from_timing: false   # opt-in: allow tape Sleep rewrites from timing.json
-  typing_ms_per_char: 55    # typing estimate used by sync-vhs
+  typing_ms_per_char: 35    # typing estimate used by sync-vhs
   max_typing_sec: 3.0       # per block cap for typing estimate
-  min_sleep_sec: 0.05       # floor for rewritten Sleep values
+  min_sleep_sec: 0.2        # floor for rewritten Sleep values
 
 pipeline:
   sync_vhs_after_timestamps: false  # opt-in: run sync-vhs automatically in generate-all/rebuild-after-audio
 
 compose:
   ffmpeg_timeout_sec: 300   # can also be overridden with: docgen compose --ffmpeg-timeout N
   warn_stale_vhs: true      # warns if terminal/*.tape is newer than terminal/rendered/*.mp4
+
+validation:
+  layout:
+    sample_interval_sec: 2.0
+    edge_margin_px: 15
+    min_spacing_px: 10
+    check_overlap: true
+    check_contrast: true
+    min_contrast_ratio: 3.5
+    check_font_size: true
+    min_text_height_px: 10
+    max_text_regions: 45
+    check_single_font: true
+    default_font_family: "Liberation Sans"
 ```
 
 If you edit a `.tape` file, run `docgen vhs` before `docgen compose` so compose does not use stale rendered terminal video.
@@ -100,6 +114,14 @@ docgen sync-vhs
 docgen vhs
 docgen compose
 ```
+
+Font consistency guardrails for Manim scenes:
+
+- `docgen validate` checks Manim recordings for layout safety: off-screen clipping, spacing, overlap, contrast, and minimum text size.
+- `docgen validate` also lints scene source for single-font consistency:
+  - requires one default `Text.set_default(font="...")` family (defaults to `Liberation Sans`)
+  - flags `weight=BOLD`
+  - flags mixed explicit `font=` families and `Text("...", COLOR_CONST)` positional color mistakes
 ## System dependencies
 
 - **ffmpeg** — composition and probing

docs/demos/animations/scenes.py

@@ -15,6 +15,8 @@
 
 from manim import *
 
+Text.set_default(font="Liberation Sans")
+
 # ── Palette ──────────────────────────────────────────────────────────
 C_BG = "#1e1e2e"
 C_ACCENT = "#667eea"
@@ -105,9 +107,9 @@ def seg_end(i: int) -> float:
             return self._clock + 2
 
         # ── Beat 0-1: Title card ──────────────────────────────────────
-        title = Text("docgen", font_size=52, color=C_ACCENT, weight=BOLD)
+        title = Text("docgen", font_size=56, color=C_ACCENT)
         subtitle = Text(
-            "Markdown  →  polished demo videos",
+            "Markdown -> polished demo videos",
             font_size=22, color=C_WHITE,
         )
         subtitle.next_to(title, DOWN, buff=0.3)
@@ -117,7 +119,7 @@ def seg_end(i: int) -> float:
         self.timed_play(FadeIn(subtitle, shift=UP * 0.2), run_time=0.8)
 
         tagline = Text(
-            "Reproducible · version-controlled · fully automated",
+            "Reproducible - version-controlled - fully automated",
             font_size=16, color=GREY_B,
         )
         tagline.next_to(subtitle, DOWN, buff=0.4)
@@ -250,7 +252,7 @@ def seg_end(i: int) -> float:
         # ── Beat 11: Single command highlight ─────────────────────────
         cmd = Text(
             "docgen generate-all",
-            font_size=24, color=C_ACCENT, weight=BOLD,
+            font_size=28, color=C_ACCENT,
         )
         cmd_bg = RoundedRectangle(
             corner_radius=0.12, width=cmd.width + 0.6, height=cmd.height + 0.4,
@@ -274,7 +276,7 @@ def seg_end(i: int) -> float:
             ct.move_to(RIGHT * 4.0 + DOWN * (1.8 + ci * 0.3))
             config_items.add(ct)
 
-        cfg_label = Text("docgen.yaml", font_size=14, color=C_ORANGE, weight=BOLD)
+        cfg_label = Text("docgen.yaml", font_size=16, color=C_ORANGE)
         cfg_label.move_to(RIGHT * 4.0 + DOWN * 1.4)
         self.timed_play(FadeIn(cfg_label), run_time=0.3)
 
@@ -330,7 +332,7 @@ def seg_end(i: int) -> float:
             return self._clock + 2
 
         # ── Beat 0: Title ─────────────────────────────────────────────
-        title = Text("docgen wizard", font_size=44, color=C_ACCENT, weight=BOLD)
+        title = Text("docgen wizard", font_size=48, color=C_ACCENT)
         subtitle = Text(
             "Local web GUI for narration authoring",
             font_size=20, color=C_WHITE,
@@ -573,7 +575,7 @@ def seg_end(i: int) -> float:
 
     @staticmethod
     def _tab(label, color, active=False):
-        t = Text(label, font_size=15, color=color, weight=BOLD if active else NORMAL)
+        t = Text(label, font_size=16 if active else 15, color=color)
         underline = Line(
             t.get_left() + DOWN * 0.15,
             t.get_right() + DOWN * 0.15,

docs/demos/docgen.yaml

@@ -66,6 +66,7 @@ visual_map:
 manim:
   quality: 720p30
   manim_path: ""
+  font: "Liberation Sans"
   scenes:
     - DocgenOverviewScene
     - WizardGUIScene

src/docgen/config.py

@@ -94,6 +94,16 @@ def manim_path(self) -> str | None:
         value = self.raw.get("manim", {}).get("manim_path")
         return str(value) if value else None
 
+    @property
+    def manim_font(self) -> str:
+        """Preferred single font family for Manim Text()."""
+        return str(self.raw.get("manim", {}).get("font", "Liberation Sans"))
+
+    @property
+    def manim_font_family(self) -> str:
+        """Backward-compatible alias for configured single Manim font."""
+        return self.manim_font
+
     @property
     def vhs_config(self) -> dict[str, Any]:
         defaults: dict[str, Any] = {
@@ -188,10 +198,28 @@ def layout_config(self) -> dict[str, Any]:
             "min_spacing_px": 10,
             "edge_margin_px": 15,
             "check_overlap": True,
+            "sample_interval_sec": 2.0,
+            "check_contrast": True,
+            "min_contrast_ratio": 3.5,
+            "check_font_size": True,
+            "min_text_height_px": 10,
+            "max_text_regions": 45,
         }
         defaults.update(self.raw.get("validation", {}).get("layout", {}))
         return defaults
 
+    @property
+    def manim_lint_config(self) -> dict[str, Any]:
+        defaults: dict[str, Any] = {
+            "enabled": True,
+            "enforce_single_font": True,
+            "deny_weight_bold": True,
+            "deny_positional_text_color": True,
+            "expected_font": self.manim_font,
+        }
+        defaults.update(self.raw.get("validation", {}).get("manim_lint", {}))
+        return defaults
+
     @property
     def av_sync_config(self) -> dict[str, Any]:
         defaults: dict[str, Any] = {

src/docgen/init.py

@@ -254,6 +254,7 @@ def _write_config(plan: InitPlan) -> str:
             "quality": "720p30",
             "scenes": [f"Scene{s['id']}" for s in plan.segments],
             "manim_path": "",
+            "font": "Liberation Sans",
         },
         "vhs": {
             "vhs_path": "",
@@ -279,6 +280,13 @@ def _write_config(plan: InitPlan) -> str:
         },
         "validation": {
             "max_drift_sec": 2.75,
+            "manim_lint": {
+                "enabled": True,
+                "enforce_single_font_family": True,
+                "allowed_font_family": "Liberation Sans",
+                "ban_weight_bold": True,
+                "ban_text_positional_color": True,
+            },
             "narration_lint": {
                 "pre_tts_deny_patterns": [
                     "target duration",