motionloom 2.0.0

package/scripts/validate-lottie.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+validate-lottie.py — Acceptance gate for generated Lottie files.
+
+Checks the Bodymovin version header, frame count against the signed spec,
+layer count against the performance budget, and (optionally) slot names
+against the brand spec. Exit 0 = accepted, exit 1 = rejected with reasons.
+
+Usage:
+    python3 scripts/validate-lottie.py <animation.json|animation.lottie> \
+        --spec motion-spec.json --max-layers 80
+"""
+
+import argparse
+import json
+import zipfile
+import sys
+from pathlib import Path
+
+
+def load_lottie(path: Path, animation_id: str | None = None) -> dict:
+    if path.suffix == ".lottie":
+        with zipfile.ZipFile(path) as zf:
+            if "manifest.json" not in zf.namelist():
+                raise ValueError("dotLottie manifest.json is required")
+            manifest = json.loads(zf.read("manifest.json"))
+            entries = manifest.get("animations")
+            if not isinstance(entries, list) or not entries:
+                raise ValueError("dotLottie manifest must declare at least one animation")
+            chosen = animation_id or ((manifest.get("initial") or {}).get("animation"))
+            entry = next((item for item in entries if item.get("id") == chosen), None) if chosen else entries[0]
+            if entry is None:
+                raise ValueError(f"animation id not found in manifest: {chosen}")
+            ident = str(entry.get("id", ""))
+            candidates = [f"a/{ident}", f"a/{ident}.json", ident, f"{ident}.json"]
+            name = next((candidate for candidate in candidates if candidate in zf.namelist()), None)
+            if not name:
+                raise ValueError(f"animation '{ident}' has no JSON payload under a/")
+            return json.loads(zf.read(name))
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def validate(path: Path, spec: dict | None, max_layers: int, animation_id: str | None = None) -> list:
+    issues = []
+    try:
+        doc = load_lottie(path, animation_id or ((spec or {}).get("animation_id")))
+    except Exception as e:
+        return [f"cannot parse file: {e}"]
+
+    if not doc.get("v"):
+        issues.append("missing Bodymovin version header (v)")
+    op = doc.get("op")
+    fr = doc.get("fr")
+    if op is None or fr is None:
+        issues.append("missing frame metadata (fr/op)")
+    elif spec and abs(op - spec.get("total_frames", op)) > 3:
+        issues.append(f"frame count {op} deviates from spec total_frames {spec.get('total_frames')}")
+
+    layers = len(doc.get("layers", []))
+    if layers > max_layers:
+        issues.append(f"layer count {layers} exceeds budget {max_layers}")
+
+    kb = path.stat().st_size / 1024
+    budget_kb = 1500 if (spec and spec.get("category") == "hero-scene") else 300
+    if kb > budget_kb:
+        issues.append(f"file size {kb:.0f}KB exceeds budget {budget_kb}KB")
+
+    if spec:
+        expected_slots = set(spec.get("slots", []))
+        found_slots = set()
+        for slot in (doc.get("themes") or {}).get("slots", []):
+            found_slots.add(slot.get("id") or slot.get("p"))
+        missing = expected_slots - found_slots
+        if missing:
+            issues.append(f"brand slots missing: {sorted(missing)}")
+
+    return issues
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("path")
+    parser.add_argument("--spec")
+    parser.add_argument("--max-layers", type=int, default=80)
+    parser.add_argument("--animation-id")
+    args = parser.parse_args()
+
+    spec = None
+    if args.spec:
+        spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
+
+    issues = validate(Path(args.path), spec, args.max_layers, args.animation_id)
+    if issues:
+        print("REJECTED:")
+        for i in issues:
+            print(f"  - {i}")
+        sys.exit(1)
+    print("ACCEPTED — lottie passes validation")
+
+
+if __name__ == "__main__":
+    main()

package/src/core/analyzer.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+analyzer.py — Step 1 of the MotionLoom pipeline: Project Understanding.
+
+Reads a project repository (package.json, tailwind config, design tokens,
+existing animation files, README) and emits `project-context.json`:
+the single source of truth that all later steps (plan, source, generate)
+must bind to. The agent is required to ground every generated animation
+in this context, never in assumptions.
+"""
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+__version__ = "1.0.0"
+
+# ---------------------------------------------------------------------------
+# Category taxonomy — maps a user request to an animation class
+# ---------------------------------------------------------------------------
+CATEGORIES = {
+    "ui-micro": {
+        "description": "Buttons, toggles, loaders, hover/focus states, feedback toasts",
+        "framework": "framer-motion",
+        "default_duration_s": 0.3,
+        "fps": 60,
+        "loop": False,
+    },
+    "loading": {
+        "description": "Spinners, skeletons, progress indicators",
+        "framework": "lottie",
+        "default_duration_s": 1.0,
+        "fps": 60,
+        "loop": True,
+    },
+    "hero-scene": {
+        "description": "Full-viewport marketing scenes with camera motion",
+        "framework": "lottie",
+        "default_duration_s": 3.5,
+        "fps": 60,
+        "loop": True,
+    },
+    "character-body": {
+        "description": "Avatar/character with skeleton rig: idle, walk, emote",
+        "framework": "lottie",
+        "default_duration_s": 1.5,
+        "fps": 30,
+        "loop": True,
+    },
+    "icon-animation": {
+        "description": "Animated icons, path-draw reveals, state glyphs",
+        "framework": "lottie",
+        "default_duration_s": 0.8,
+        "fps": 60,
+        "loop": False,
+    },
+    "scroll-linked": {
+        "description": "Parallax, progress-bound reveals, pin animations",
+        "framework": "gsap",
+        "default_duration_s": 1.0,
+        "fps": 60,
+        "loop": False,
+    },
+    "data-viz": {
+        "description": "Chart transitions, counting numbers, graph builds",
+        "framework": "gsap",
+        "default_duration_s": 1.2,
+        "fps": 60,
+        "loop": False,
+    },
+    "3d-scene": {
+        "description": "WebGL/Three.js scenes, model turntables, shaders",
+        "framework": "threejs",
+        "default_duration_s": 5.0,
+        "fps": 60,
+        "loop": True,
+    },
+}
+
+
+def read_json(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def detect_stack(project_root: Path, pkg: dict | None) -> dict:
+    stack = {"framework": None, "react": False, "vue": False, "react_native": False, "native_web": False}
+    deps = set()
+    if pkg:
+        deps.update(pkg.get("dependencies", {}).keys())
+        deps.update(pkg.get("devDependencies", {}).keys())
+    stack["react"] = bool({"react", "next", "framer-motion"} & deps)
+    stack["vue"] = bool({"vue", "nuxt"} & deps)
+    stack["react_native"] = bool({"react-native"} & deps)
+    stack["native_web"] = bool({"lottie-web", "dotlottie-web", "gsap", "animejs"} & deps)
+    if "framer-motion" in deps:
+        stack["framework"] = "framer-motion"
+    elif "gsap" in deps:
+        stack["framework"] = "gsap"
+    elif "dotlottie-web" in deps or "lottie-web" in deps or "@lottiefiles/react-lottie-player" in deps:
+        stack["framework"] = "lottie"
+    elif "three" in deps:
+        stack["framework"] = "threejs"
+    elif stack["react"]:
+        stack["framework"] = "framer-motion"
+    else:
+        stack["framework"] = "gsap"
+    return stack
+
+
+def extract_brand_tokens(project_root: Path) -> dict:
+    tokens = {"primary": None, "accent": None, "palette": [], "fonts": []}
+    # Tailwind config
+    for candidate in ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs"]:
+        p = project_root / candidate
+        if p.exists():
+            text = p.read_text(encoding="utf-8")
+            for m in re.finditer(r"primary:\s*['\"](#[0-9a-fA-F]{3,8})['\"]", text):
+                tokens["primary"] = m.group(1).upper()
+            for m in re.finditer(r"accent:\s*['\"](#[0-9a-fA-F]{3,8})['\"]", text):
+                tokens["accent"] = m.group(1).upper()
+    # package.json theme / CSS variables
+    css_vars = {}
+    css_files = list(project_root.rglob("*.css")) + list(project_root.rglob("*.scss"))
+    for f in css_files[:20]:
+        text = f.read_text(encoding="utf-8", errors="ignore")
+        for m in re.finditer(r"--([a-z0-9-]+):\s*(#[0-9a-fA-F]{3,8})", text):
+            css_vars[m.group(1)] = m.group(2).upper()
+    for key in ("color-primary", "primary", "brand", "--primary"):
+        if key in css_vars:
+            tokens["primary"] = tokens["primary"] or css_vars[key]
+    return tokens
+
+
+def detect_motion_language(project_root: Path) -> dict:
+    """Gather existing easing/duration conventions from the project."""
+    easings = set()
+    durations = set()
+    for pattern in ("*.ts", "*.tsx", "*.js", "*.jsx", "*.css"):
+        for f in project_root.rglob(pattern):
+            if "node_modules" in f.parts:
+                continue
+            try:
+                text = f.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            if len(text) > 200_000:
+                continue
+            easings.update(re.findall(r"ease(in-out|in|out|linear)?", text))
+            durations.update(re.findall(r"(?:duration|time)[^;]{0,20}?:\s*['\"]?([\d.]+(?:s|ms))", text, re.I))
+    return {
+        "easings_used": sorted(easings)[:10],
+        "duration_patterns": sorted(durations)[:10],
+        "recommendation": "ease-in-out" if "in-out" in easings else "ease-out",
+    }
+
+
+def find_existing_animations(project_root: Path) -> list:
+    found = []
+    for ext in ("*.lottie", "*.json", "*.riv"):
+        for f in project_root.rglob(ext):
+            rel = str(f.relative_to(project_root))
+            if "node_modules" in rel or ".git" in rel:
+                continue
+            if ext == "*.json":
+                text = f.read_text(encoding="utf-8", errors="ignore")[:200]
+                if '"v"' not in text and "anim" not in text.lower():
+                    continue
+            found.append(rel)
+            if len(found) >= 15:
+                return found
+    return found
+
+
+def analyze(project_root: str) -> dict:
+    root = Path(project_root).resolve()
+    pkg = read_json(root / "package.json")
+    manifest = read_json(root / "project-manifest.json")
+    readme = (root / "README.md").read_text(encoding="utf-8", errors="ignore")[:3000] if (root / "README.md").exists() else ""
+
+    brand = extract_brand_tokens(root)
+    # project-manifest.json is the explicit project contract and therefore
+    # overrides inferred values from Tailwind/CSS when both are present.
+    manifest_brand = (manifest or {}).get("brand") or {}
+    for key in ("primary", "accent"):
+        if manifest_brand.get(key):
+            brand[key] = str(manifest_brand[key]).upper()
+    context = {
+        "schema_version": "1.1",
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "project_root": str(root),
+        "name": (pkg or {}).get("name") or root.name,
+        "description": (manifest or {}).get("description") or (pkg or {}).get("description") or "",
+        "stack": detect_stack(root, pkg),
+        "brand": brand,
+        "motion_language": detect_motion_language(root),
+        "existing_animations": find_existing_animations(root),
+        "manifest_overrides": manifest or {},
+        "source_authority": "project-manifest.json then assets/library/, never invented geometry",
+    }
+    return context
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Analyze a host project and emit its binding context.")
+    parser.add_argument("project_root", nargs="?", default=".")
+    parser.add_argument("--output", help="Context path; defaults to <project_root>/project-context.json")
+    args = parser.parse_args()
+    root = Path(args.project_root).resolve()
+    if not root.is_dir():
+        parser.error(f"project root is not a directory: {root}")
+    ctx = analyze(str(root))
+    out = Path(args.output).resolve() if args.output else root / "project-context.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(ctx, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(f"{out} written ({len(json.dumps(ctx))} bytes)")
+    print(json.dumps(ctx, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/src/core/snapshot.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+snapshot.py — Step 5 support: render deterministic PNG snapshots of a scene.
+
+For code-based scenes (GSAP / Framer Motion) it drives a headless Chromium
+via the Dev Lab snapshot harness; for Lottie files it renders frames with
+the dotlottie runtime in Node. Output lands in src/output/<scene>/snapshot/
+as `frame-00.png`, `frame-50.png`, `frame-100.png` so visual diffs and PR
+reviews are bit-exact reproducible.
+
+Usage:
+    python3 src/core/snapshot.py render <scene> --scene-dir src/output/<scene> --progress 0,50,100
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _fallback_placeholder_frames(scene_dir: Path, progress: list[int], framework: str) -> None:
+    """Deterministic placeholder frames when the headless harness is not installed.
+    Frames embed the scene id, progress and framework so diffs still detect change."""
+    from PIL import Image, ImageDraw
+
+    out = scene_dir / "snapshot"
+    out.mkdir(parents=True, exist_ok=True)
+    color = {"lottie": (245, 158, 11), "gsap": (59, 130, 246), "framer-motion": (34, 197, 94)}.get(
+        framework, (140, 140, 160))
+    for p in progress:
+        img = Image.new("RGB", (320, 200), (20, 18, 26))
+        d = ImageDraw.Draw(img)
+        d.rectangle([40, 60, 40 + int(2.4 * p), 100], fill=color)
+        d.text((20, 150), f"{scene_dir.name} @{p}% [{framework}] placeholder", fill=(200, 200, 210))
+        img.save(out / f"frame-{p:02d}.png")
+    (out / ".render-meta.json").write_text(json.dumps({
+        "mode": "placeholder", "scene": scene_dir.name, "framework": framework,
+        "progress": progress,
+    }, indent=2) + "\n", encoding="utf-8")
+
+
+def _write_render_meta(scene_dir: Path, scene: str, framework: str, progress: list[int], mode: str) -> None:
+    out = scene_dir / "snapshot"
+    out.mkdir(parents=True, exist_ok=True)
+    (out / ".render-meta.json").write_text(json.dumps({
+        "mode": mode, "scene": scene, "framework": framework, "progress": progress,
+    }, indent=2) + "\n", encoding="utf-8")
+
+
+def render_snapshots(scene: str, scene_dir: Path, progress: list[int], allow_placeholder: bool = False) -> dict:
+    if not scene_dir.is_dir():
+        raise SystemExit(f"error: scene directory not found: {scene_dir}")
+    if any(p < 0 or p > 100 for p in progress):
+        raise SystemExit("error: progress values must be between 0 and 100")
+    manifest_path = scene_dir / "manifest.json"
+    if not manifest_path.exists():
+        raise SystemExit(f"error: scene manifest missing: {manifest_path}")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"error: invalid scene manifest: {exc}")
+
+    framework = manifest.get("framework", "unknown")
+    src = manifest.get("file", "")
+    if not framework or framework == "unknown":
+        raise SystemExit("error: manifest.framework is required")
+    shots = []
+
+    if framework in ("lottie", "dotlottie") and src.endswith((".lottie", ".json")):
+        # Node path using @napi-rs/canvas + dotlottie (see scripts/render-node.mjs)
+        runner = Path(__file__).parent.parent.parent / "scripts" / "render-node.mjs"
+        source_path = (scene_dir / src).resolve()
+        if not source_path.is_file() or scene_dir.resolve() not in source_path.parents:
+            raise SystemExit(f"error: manifest.file must point to a file inside the scene directory: {src}")
+        (scene_dir / "snapshot").mkdir(parents=True, exist_ok=True)
+        for p in progress:
+            out_png = scene_dir / "snapshot" / f"frame-{p:02d}.png"
+            env = {**os.environ, "FRAME_PCT": str(p), "SRC": str(source_path), "OUT": str(out_png)}
+            subprocess.run(["node", str(runner)], env=env, check=True,
+                           capture_output=True)
+            shots.append(str(out_png))
+        _write_render_meta(scene_dir, scene, framework, progress, "runtime")
+    else:
+        # Headless Chromium via Dev Lab snapshot harness
+        lab = Path(__file__).parent.parent.parent / "dev-lab"
+        harness = lab / "scripts" / "snapshot.mjs"
+        try:
+            subprocess.run(
+                ["node", str(harness), "--scene", scene,
+                 "--progress", ",".join(map(str, progress)), "--out", str(scene_dir / "snapshot")],
+                cwd=lab, check=True, capture_output=True,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            if not allow_placeholder:
+                detail = getattr(exc, "stderr", b"")
+                if isinstance(detail, bytes):
+                    detail = detail.decode(errors="replace")
+                raise SystemExit(
+                    "error: runtime snapshot failed; start the Dev Lab and install its renderer "
+                    f"dependencies before accepting this scene. {detail[-500:]}"
+                )
+            print("warn: runtime harness unavailable; writing explicitly marked placeholder frames", file=sys.stderr)
+            _fallback_placeholder_frames(scene_dir, progress, framework)
+        shots = sorted(str(p) for p in (scene_dir / "snapshot").glob("frame-*.png"))
+
+    return {"scene": scene, "framework": framework, "shots": shots}
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("cmd", choices=["render"])
+    parser.add_argument("scene")
+    parser.add_argument("--scene-dir", required=True)
+    parser.add_argument("--progress", default="0,50,100")
+    parser.add_argument("--allow-placeholder", action="store_true", help="diagnostic only; quality gate rejects these frames")
+    args = parser.parse_args()
+    result = render_snapshots(args.scene, Path(args.scene_dir), [int(x) for x in args.progress.split(",")], args.allow_placeholder)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()