motionloom 2.0.0 → 2.2.0

package/scripts/to-dotlottie.mjs

@@ -6,9 +6,8 @@
  */
 import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { strFromU8, zipSync, unzipSync } from "fflate";
 
 function arg(name, fallback = undefined) {
   const index = process.argv.indexOf(name);
@@ -43,17 +42,14 @@ if (!/^[a-zA-Z0-9._ -]+$/.test(animationId)) {
 }
 readJson(sourcePath);
 
-const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "animation-skill-dotlottie-"));
-const archiveRoot = path.join(tmp, "archive");
-fs.mkdirSync(path.join(archiveRoot, "a"), { recursive: true });
-fs.copyFileSync(sourcePath, path.join(archiveRoot, "a", `${animationId}.json`));
+const archive = {
+  [`a/${animationId}.json`]: fs.readFileSync(sourcePath),
+};
 
 const optionalDirectories = ["i", "t", "s", "f"];
 for (const directory of optionalDirectories) {
   const candidate = path.join(sceneDir, "dotlottie", directory);
-  if (fs.existsSync(candidate)) {
-    fs.cpSync(candidate, path.join(archiveRoot, directory), { recursive: true });
-  }
+  if (fs.existsSync(candidate)) addTree(candidate, directory);
 }
 
 const dotManifest = {
@@ -62,20 +58,13 @@ const dotManifest = {
   initial: { animation: animationId },
   animations: [{ id: animationId }],
 };
-fs.writeFileSync(
-  path.join(archiveRoot, "manifest.json"),
-  `${JSON.stringify(dotManifest, null, 2)}\n`,
-  "utf8",
-);
+archive["manifest.json"] = Buffer.from(`${JSON.stringify(dotManifest, null, 2)}\n`, "utf8");
 
 fs.mkdirSync(path.dirname(output), { recursive: true });
 if (fs.existsSync(output)) fs.rmSync(output, { force: true });
-execFileSync("zip", ["-X", "-q", "-r", output, "."], { cwd: archiveRoot });
+fs.writeFileSync(output, zipSync(archive, { level: 6 }));
 
-const entries = execFileSync("unzip", ["-Z1", output], { encoding: "utf8" })
-  .trim()
-  .split(/\r?\n/)
-  .filter(Boolean);
+const entries = Object.keys(unzipSync(fs.readFileSync(output))).sort();
 if (!entries.includes("manifest.json")) throw new Error("archive missing manifest.json");
 if (!entries.includes(`a/${animationId}.json`)) {
   throw new Error("archive missing initial animation payload");
@@ -95,5 +84,22 @@ console.log(JSON.stringify({
 }, null, 2));
 
 function readJsonFromZip(file, entry) {
-  return JSON.parse(execFileSync("unzip", ["-p", file, entry], { encoding: "utf8" }));
+  const payload = unzipSync(fs.readFileSync(file))[entry];
+  if (!payload) throw new Error(`archive entry is missing: ${entry}`);
+  return JSON.parse(strFromU8(payload));
+}
+
+function addTree(directory, archivePrefix) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourceEntry = path.join(directory, entry.name);
+    const archiveEntry = `${archivePrefix}/${entry.name.replaceAll("\\", "/")}`;
+    const stat = fs.lstatSync(sourceEntry);
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      addTree(sourceEntry, archiveEntry);
+    } else if (stat.isFile()) {
+      archive[archiveEntry] = fs.readFileSync(sourceEntry);
+    }
+  }
 }

package/scripts/visual-truth.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Build and validate MotionLoom's provenance-bound visual truth contract.
+
+The contract is deliberately a review aid, not an approval engine. It compares
+real rendered PNG frames, records image dimensions and SHA-256 digests, emits a
+small deterministic perceptual summary, and keeps user approval false until a
+separate browser review artifact records a human decision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import struct
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+SCHEMA_VERSION = "1.0"
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+SHA256_RE = 64
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def json_sha256(path: Path) -> str:
+    return sha256(path)
+
+
+def load_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid JSON {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"expected JSON object: {path}")
+    return value
+
+
+def png_dimensions(path: Path) -> tuple[int, int]:
+    """Read PNG dimensions without requiring Pillow or a system image tool."""
+    with path.open("rb") as handle:
+        if handle.read(8) != PNG_SIGNATURE:
+            raise ValueError(f"not a PNG file: {path}")
+        length = struct.unpack(">I", handle.read(4))[0]
+        chunk = handle.read(4)
+        if chunk != b"IHDR" or length < 8:
+            raise ValueError(f"PNG has no IHDR: {path}")
+        width, height = struct.unpack(">II", handle.read(8))
+        if width <= 0 or height <= 0:
+            raise ValueError(f"PNG dimensions are invalid: {path}")
+        return width, height
+
+
+def relpath(path: Path, root: Path) -> str:
+    resolved = path.resolve()
+    try:
+        return resolved.relative_to(root.resolve()).as_posix()
+    except ValueError:
+        raise ValueError(f"path must be inside repository root: {path}")
+
+
+def display_path(path: Path, root: Path) -> str:
+    """Render an output path without weakening repository-bound evidence paths."""
+    try:
+        return relpath(path, root)
+    except ValueError:
+        return path.resolve().as_posix()
+
+
+def frame_record(path: Path, root: Path, role: str, percent: int) -> dict:
+    if not path.is_file() or path.stat().st_size == 0:
+        raise ValueError(f"{role} frame is missing or empty: {path}")
+    width, height = png_dimensions(path)
+    return {
+        "role": role,
+        "percent": percent,
+        "path": relpath(path, root),
+        "sha256": sha256(path),
+        "bytes": path.stat().st_size,
+        "width": width,
+        "height": height,
+    }
+
+
+def perceptual_summary(baseline: dict, candidate: dict) -> dict:
+    """Return a conservative perceptual signal based on byte identity.
+
+    A byte-identical PNG is a strong deterministic equality signal. A changed
+    PNG is intentionally reported as `review_required`, not as a failed quality
+    judgment, because visual acceptability is a user/runtime review decision.
+    """
+    same_dimensions = (baseline["width"], baseline["height"]) == (candidate["width"], candidate["height"])
+    identical = baseline["sha256"] == candidate["sha256"]
+    return {
+        "metric": "sha256-image-identity",
+        "method": "PNG metadata plus byte identity; no visual approval inferred",
+        "same_dimensions": same_dimensions,
+        "byte_identical": identical,
+        "changed": not identical or not same_dimensions,
+        "distance": 0.0 if identical and same_dimensions else 1.0,
+        "threshold": 0.0,
+        "interpretation": "equal" if identical and same_dimensions else "review_required",
+    }
+
+
+def build(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    output = Path(args.output)
+    if not output.is_absolute():
+        output = (root / output).resolve()
+    scene = str(args.scene)
+    if not scene or scene in {".", ".."} or "/" in scene or "\\" in scene:
+        print("visual-truth: unsafe scene identifier", file=sys.stderr)
+        return 2
+    try:
+        baseline = Path(args.baseline)
+        candidate = Path(args.candidate)
+        if not baseline.is_absolute():
+            baseline = (root / baseline).resolve()
+        if not candidate.is_absolute():
+            candidate = (root / candidate).resolve()
+        source = Path(args.source)
+        manifest = Path(args.manifest)
+        runtime_evidence = Path(args.runtime_evidence) if args.runtime_evidence else None
+        motion_ir = Path(args.motion_ir) if args.motion_ir else None
+        for value in (source, manifest, runtime_evidence, motion_ir):
+            if value is not None and not value.is_absolute():
+                value = (root / value).resolve()
+        # Rebind optional paths after the loop because Path is immutable.
+        if args.runtime_evidence:
+            runtime_evidence = (root / args.runtime_evidence).resolve() if not Path(args.runtime_evidence).is_absolute() else Path(args.runtime_evidence).resolve()
+        if args.motion_ir:
+            motion_ir = (root / args.motion_ir).resolve() if not Path(args.motion_ir).is_absolute() else Path(args.motion_ir).resolve()
+        source = (root / args.source).resolve() if not Path(args.source).is_absolute() else Path(args.source).resolve()
+        manifest = (root / args.manifest).resolve() if not Path(args.manifest).is_absolute() else Path(args.manifest).resolve()
+        baseline_record = frame_record(baseline, root, "baseline", args.percent)
+        candidate_record = frame_record(candidate, root, "candidate", args.percent)
+        manifest_data = load_json(manifest)
+        if not source.is_file() or not manifest.is_file():
+            raise ValueError("source and manifest must exist")
+        runtime_data = load_json(runtime_evidence) if runtime_evidence else None
+        motion_data = load_json(motion_ir) if motion_ir else None
+        source_hash = sha256(source)
+        manifest_hash = sha256(manifest)
+        motion_hash = sha256(motion_ir) if motion_ir else None
+        runtime_hash = sha256(runtime_evidence) if runtime_evidence else None
+        if manifest_data.get("file") and not str(manifest_data["file"]).strip():
+            raise ValueError("manifest.file must be non-empty")
+        if runtime_data is not None:
+            if runtime_data.get("status") != "pass":
+                raise ValueError("runtime evidence status must be pass")
+            if args.task_id and runtime_data.get("task_id") not in {None, args.task_id}:
+                raise ValueError("runtime evidence task_id does not match requested task")
+            if runtime_data.get("scene") not in {None, scene}:
+                raise ValueError("runtime evidence scene does not match requested scene")
+        comparison = perceptual_summary(baseline_record, candidate_record)
+        changed_regions = []
+        if comparison["changed"]:
+            changed_regions.append({
+                "id": "full-frame",
+                "label": "Full rendered frame",
+                "reason": "Baseline and candidate PNG identities differ; inspect the exact candidate in Dev Lab.",
+                "severity": "review",
+                "evidence": [baseline_record["path"], candidate_record["path"]],
+            })
+        report = {
+            "schema_version": SCHEMA_VERSION,
+            "contract": "motionloom-visual-truth",
+            "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "status": "review_required" if comparison["changed"] else "pass",
+            "scene": scene,
+            "task_id": args.task_id or None,
+            "frames": {
+                "baseline": baseline_record,
+                "candidate": candidate_record,
+            },
+            "comparison": comparison,
+            "regions": changed_regions,
+            "provenance": {
+                "source_path": relpath(source, root),
+                "source_sha256": source_hash,
+                "manifest_path": relpath(manifest, root),
+                "manifest_sha256": manifest_hash,
+                "runtime_evidence_path": relpath(runtime_evidence, root) if runtime_evidence else None,
+                "runtime_evidence_sha256": runtime_hash,
+                "motion_ir_path": relpath(motion_ir, root) if motion_ir else None,
+                "motion_ir_sha256": motion_hash,
+                "runtime_status": runtime_data.get("status") if runtime_data else None,
+                "motion_ir_schema_version": motion_data.get("schema_version") if motion_data else None,
+            },
+            "review_boundary": {
+                "approval": False,
+                "user_review_required": True,
+                "decision": "pending",
+                "pr_side_effects": "explicit-confirmation",
+            },
+        }
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 0
+    except (OSError, ValueError) as exc:
+        print(f"visual-truth: {exc}", file=sys.stderr)
+        return 1
+
+
+def validate_report(path: Path, root: Path | None = None, expected_scene: str | None = None, expected_task_id: str | None = None, expected_source_sha256: str | None = None, expected_manifest_sha256: str | None = None, expected_motion_ir_sha256: str | None = None) -> list[str]:
+    root = (root or path.parent).resolve()
+    errors: list[str] = []
+    try:
+        data = load_json(path)
+    except ValueError as exc:
+        return [str(exc)]
+    if data.get("schema_version") != SCHEMA_VERSION:
+        errors.append("visual truth schema_version must be 1.0")
+    if data.get("contract") != "motionloom-visual-truth":
+        errors.append("visual truth contract identifier is invalid")
+    if data.get("status") not in {"pass", "review_required"}:
+        errors.append("visual truth status must be pass or review_required")
+    if expected_scene and data.get("scene") != expected_scene:
+        errors.append("visual truth scene does not match requested scene")
+    if expected_task_id and data.get("task_id") != expected_task_id:
+        errors.append("visual truth task_id does not match task bundle")
+    boundary = data.get("review_boundary")
+    if not isinstance(boundary, dict) or boundary.get("approval") is not False or boundary.get("user_review_required") is not True:
+        errors.append("visual truth must preserve approval=false and user_review_required=true")
+    frames = data.get("frames")
+    if not isinstance(frames, dict) or not isinstance(frames.get("baseline"), dict) or not isinstance(frames.get("candidate"), dict):
+        errors.append("visual truth must contain baseline and candidate frame records")
+    else:
+        for role in ("baseline", "candidate"):
+            frame = frames[role]
+            if frame.get("role") != role or not isinstance(frame.get("sha256"), str) or len(frame.get("sha256", "")) != SHA256_RE:
+                errors.append(f"visual truth {role} frame hash is invalid")
+            frame_path = root / str(frame.get("path", ""))
+            try:
+                if not frame_path.is_file() or sha256(frame_path) != frame.get("sha256"):
+                    errors.append(f"visual truth {role} frame hash/path binding is stale")
+                elif png_dimensions(frame_path) != (frame.get("width"), frame.get("height")):
+                    errors.append(f"visual truth {role} frame dimensions are stale")
+            except (OSError, ValueError):
+                errors.append(f"visual truth {role} frame is not a readable PNG")
+    provenance = data.get("provenance")
+    if not isinstance(provenance, dict):
+        errors.append("visual truth provenance is required")
+    else:
+        for label, expected in (("source_sha256", expected_source_sha256), ("manifest_sha256", expected_manifest_sha256), ("motion_ir_sha256", expected_motion_ir_sha256)):
+            if expected and provenance.get(label) != expected:
+                errors.append(f"visual truth {label} does not match current artifact")
+        for label in ("source_path", "manifest_path"):
+            path_value = provenance.get(label)
+            if not isinstance(path_value, str) or Path(path_value).is_absolute() or ".." in Path(path_value).parts:
+                errors.append(f"visual truth {label} must be a safe repository-relative path")
+    comparison = data.get("comparison")
+    if not isinstance(comparison, dict) or comparison.get("interpretation") not in {"equal", "review_required"}:
+        errors.append("visual truth comparison interpretation is invalid")
+    return errors
+
+
+def validate(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    path = Path(args.input)
+    if not path.is_absolute():
+        path = (root / path).resolve()
+    errors = validate_report(path, root, args.scene, args.task_id, args.source_sha256, args.manifest_sha256, args.motion_ir_sha256)
+    result = {"status": "pass" if not errors else "fail", "path": display_path(path, root), "errors": errors}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if not errors else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    build_parser = sub.add_parser("build")
+    build_parser.add_argument("--root", default=".")
+    build_parser.add_argument("--scene", required=True)
+    build_parser.add_argument("--baseline", required=True)
+    build_parser.add_argument("--candidate", required=True)
+    build_parser.add_argument("--percent", type=int, default=100)
+    build_parser.add_argument("--source", required=True)
+    build_parser.add_argument("--manifest", required=True)
+    build_parser.add_argument("--runtime-evidence")
+    build_parser.add_argument("--motion-ir")
+    build_parser.add_argument("--task-id")
+    build_parser.add_argument("--output", required=True)
+    build_parser.set_defaults(func=build)
+    validate_parser = sub.add_parser("validate")
+    validate_parser.add_argument("--root", default=".")
+    validate_parser.add_argument("--input", required=True)
+    validate_parser.add_argument("--scene")
+    validate_parser.add_argument("--task-id")
+    validate_parser.add_argument("--source-sha256")
+    validate_parser.add_argument("--manifest-sha256")
+    validate_parser.add_argument("--motion-ir-sha256")
+    validate_parser.set_defaults(func=validate)
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/core/analyzer.py

@@ -10,9 +10,12 @@ in this context, never in assumptions.
 """
 
 import argparse
+import fnmatch
 import json
+import os
 import re
 import sys
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -80,6 +83,112 @@ CATEGORIES = {
     },
 }
 
+DEFAULT_IGNORE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".motionloom",
+    "target",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    "coverage",
+}
+
+
+class ScanBudget:
+    """Bound repository traversal without hiding that the scan was partial."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        max_files: int | None = 2500,
+        max_bytes: int | None = 25_000_000,
+        max_seconds: float | None = 10.0,
+        ignore_dirs: set[str] | None = None,
+        ignore_globs: list[str] | None = None,
+    ) -> None:
+        self.root = root
+        self.max_files = max_files
+        self.max_bytes = max_bytes
+        self.max_seconds = max_seconds
+        self.ignore_dirs = set(DEFAULT_IGNORE_DIRS) | set(ignore_dirs or ())
+        self.ignore_globs = list(ignore_globs or [])
+        self.started = time.monotonic()
+        self.files_scanned = 0
+        self.bytes_scanned = 0
+        self.truncated = False
+        self.truncation_reasons: list[str] = []
+
+    def _mark(self, reason: str) -> None:
+        self.truncated = True
+        if reason not in self.truncation_reasons:
+            self.truncation_reasons.append(reason)
+
+    def _relative(self, path: Path) -> str:
+        return path.relative_to(self.root).as_posix()
+
+    def _ignored(self, path: Path) -> bool:
+        relative = self._relative(path)
+        if any(part in self.ignore_dirs for part in path.relative_to(self.root).parts):
+            return True
+        return any(fnmatch.fnmatch(relative, pattern) for pattern in self.ignore_globs)
+
+    def _limited(self, next_size: int = 0) -> bool:
+        if self.max_files is not None and self.files_scanned >= self.max_files:
+            self._mark("max_files")
+            return True
+        if self.max_bytes is not None and self.bytes_scanned + next_size > self.max_bytes:
+            self._mark("max_bytes")
+            return True
+        if self.max_seconds is not None and time.monotonic() - self.started >= self.max_seconds:
+            self._mark("max_seconds")
+            return True
+        return False
+
+    def files(self, suffixes: set[str] | None = None):
+        """Yield readable candidate files in stable order until a budget is hit."""
+        for directory, dirnames, filenames in os.walk(self.root, topdown=True):
+            directory_path = Path(directory)
+            dirnames[:] = sorted(
+                name for name in dirnames
+                if not self._ignored(directory_path / name)
+            )
+            for filename in sorted(filenames):
+                path = directory_path / filename
+                if self._ignored(path):
+                    continue
+                if suffixes and path.suffix.lower() not in suffixes:
+                    continue
+                try:
+                    size = path.stat().st_size
+                except OSError:
+                    continue
+                if self._limited(size):
+                    return
+                self.files_scanned += 1
+                self.bytes_scanned += size
+                yield path
+
+    def summary(self) -> dict:
+        return {
+            "max_files": self.max_files,
+            "max_bytes": self.max_bytes,
+            "max_seconds": self.max_seconds,
+            "files_scanned": self.files_scanned,
+            "bytes_scanned": self.bytes_scanned,
+            "ignored_directories": sorted(self.ignore_dirs),
+            "ignore_globs": self.ignore_globs,
+            "scan_truncated": self.truncated,
+            "truncation_reasons": self.truncation_reasons,
+        }
+
 
 def read_json(path: Path):
     try:
@@ -91,15 +200,25 @@ def read_json(path: Path):
 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()
+    package_name = ""
     if pkg:
+        package_name = str(pkg.get("name", "")).lower()
         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:
+    # Prefer the package's own identity over a transitive/dev dependency in a
+    # monorepo. This prevents Motion One from being labeled GSAP merely
+    # because its root workspace uses GSAP for tests or tooling, and lets
+    # Rive packages expose a distinct runtime signal.
+    if package_name in {"motion", "motion-one"}:
+        stack["framework"] = "motion"
+    elif package_name == "framer-motion" or "framer-motion" in deps:
         stack["framework"] = "framer-motion"
+    elif package_name.startswith("rive") or any("rive" in dependency.lower() for dependency in deps):
+        stack["framework"] = "rive"
     elif "gsap" in deps:
         stack["framework"] = "gsap"
     elif "dotlottie-web" in deps or "lottie-web" in deps or "@lottiefiles/react-lottie-player" in deps:
@@ -113,7 +232,7 @@ def detect_stack(project_root: Path, pkg: dict | None) -> dict:
     return stack
 
 
-def extract_brand_tokens(project_root: Path) -> dict:
+def extract_brand_tokens(project_root: Path, scanner: ScanBudget | None = None) -> dict:
     tokens = {"primary": None, "accent": None, "palette": [], "fonts": []}
     # Tailwind config
     for candidate in ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs"]:
@@ -126,7 +245,7 @@ def extract_brand_tokens(project_root: Path) -> dict:
                 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"))
+    css_files = list(scanner.files({".css", ".scss"})) if scanner else 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):
@@ -137,14 +256,13 @@ def extract_brand_tokens(project_root: Path) -> dict:
     return tokens
 
 
-def detect_motion_language(project_root: Path) -> dict:
+def detect_motion_language(project_root: Path, scanner: ScanBudget | None = None) -> 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
+    suffixes = {".ts", ".tsx", ".js", ".jsx", ".css"}
+    files = scanner.files(suffixes) if scanner else (f for suffix in suffixes for f in project_root.rglob(f"*{suffix}"))
+    for f in files:
             try:
                 text = f.read_text(encoding="utf-8", errors="ignore")
             except OSError:
@@ -160,30 +278,47 @@ def detect_motion_language(project_root: Path) -> dict:
     }
 
 
-def find_existing_animations(project_root: Path) -> list:
+def find_existing_animations(project_root: Path, scanner: ScanBudget | None = None) -> 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:
+    suffixes = {".lottie", ".json", ".riv"}
+    files = scanner.files(suffixes) if scanner else (
+        f for suffix in (".lottie", ".json", ".riv") for f in project_root.rglob(f"*{suffix}")
+    )
+    for f in files:
+        rel = f.relative_to(project_root).as_posix()
+        if f.suffix.lower() == ".json":
+            text = f.read_text(encoding="utf-8", errors="ignore")[:200]
+            if '"v"' not in text and "anim" not in text.lower():
                 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
+        found.append(rel)
+        if len(found) >= 15:
+            return found
     return found
 
 
-def analyze(project_root: str) -> dict:
+def analyze(
+    project_root: str,
+    *,
+    max_files: int | None = 2500,
+    max_bytes: int | None = 25_000_000,
+    max_seconds: float | None = 10.0,
+    ignore_dirs: list[str] | None = None,
+    ignore_globs: list[str] | None = None,
+) -> dict:
     root = Path(project_root).resolve()
+    scanner = ScanBudget(
+        root,
+        max_files=max_files,
+        max_bytes=max_bytes,
+        max_seconds=max_seconds,
+        ignore_dirs=ignore_dirs,
+        ignore_globs=ignore_globs,
+    )
     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)
+    brand = extract_brand_tokens(root, scanner)
     # 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 {}
@@ -198,8 +333,10 @@ def analyze(project_root: str) -> dict:
         "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),
+        "motion_language": detect_motion_language(root, scanner),
+        "existing_animations": find_existing_animations(root, scanner),
+        "scan": scanner.summary(),
+        "scan_truncated": scanner.truncated,
         "manifest_overrides": manifest or {},
         "source_authority": "project-manifest.json then assets/library/, never invented geometry",
     }
@@ -210,11 +347,23 @@ 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")
+    parser.add_argument("--max-files", type=int, default=2500)
+    parser.add_argument("--max-bytes", type=int, default=25_000_000)
+    parser.add_argument("--max-seconds", type=float, default=10.0)
+    parser.add_argument("--ignore-dir", action="append", default=[])
+    parser.add_argument("--ignore-glob", action="append", default=[])
     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))
+    ctx = analyze(
+        str(root),
+        max_files=args.max_files,
+        max_bytes=args.max_bytes,
+        max_seconds=args.max_seconds,
+        ignore_dirs=args.ignore_dir or None,
+        ignore_globs=args.ignore_glob or None,
+    )
     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")