motionloom 2.5.0 → 2.6.0

package/scripts/package-consumer-smoke.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const expectedVersion = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "motionloom-consumer-"));
+const consumer = path.join(temporary, "consumer");
+fs.mkdirSync(consumer);
+fs.writeFileSync(
+  path.join(consumer, "package.json"),
+  `${JSON.stringify({ name: "motionloom-package-smoke", private: true }, null, 2)}\n`,
+);
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || root,
+    encoding: "utf8",
+    env: process.env,
+    ...options,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed (${result.status})\n${result.stdout || ""}\n${result.stderr || ""}`,
+    );
+  }
+  return result.stdout.trim();
+}
+
+try {
+  const packOutput = JSON.parse(run("npm", ["pack", "--json", "--pack-destination", temporary]));
+  const tarball = path.join(temporary, packOutput[0].filename);
+  run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", tarball], { cwd: consumer });
+
+  const bin = process.platform === "win32"
+    ? path.join(consumer, "node_modules", ".bin", "motionloom.cmd")
+    : path.join(consumer, "node_modules", ".bin", "motionloom");
+  const installedRoot = path.dirname(fs.realpathSync(path.join(consumer, "node_modules", "motionloom", "package.json")));
+  const help = run(bin, ["--help"], { cwd: consumer });
+  const init = JSON.parse(run(bin, ["init", "--dry-run", "--json"], { cwd: consumer }));
+  const doctor = JSON.parse(run(bin, ["doctor", "--json"], { cwd: consumer }));
+
+  if (!help.startsWith(`MotionLoom ${expectedVersion}`)) throw new Error(`unexpected help version: ${help.split("\n")[0]}`);
+  if (fs.realpathSync(init.project_root || ".") !== fs.realpathSync(consumer)) {
+    throw new Error(`installed CLI used the wrong project_root: ${init.project_root}`);
+  }
+  if (doctor.status !== "pass") throw new Error(`installed doctor failed: ${JSON.stringify(doctor.errors)}`);
+  for (const relative of [
+    "requirements.txt",
+    "dev-lab/public/index.html",
+    "dev-lab/public/devlab.js",
+    "tests/runtime-harness/index.html",
+  ]) {
+    if (!fs.existsSync(path.join(installedRoot, relative))) throw new Error(`tarball omitted ${relative}`);
+  }
+  const scene = "browser-review-smoke";
+  const consumerScene = path.join(consumer, "src", "output", scene);
+  fs.mkdirSync(path.dirname(consumerScene), { recursive: true });
+  fs.cpSync(path.join(installedRoot, "src", "output", scene), consumerScene, { recursive: true });
+  const candidatePath = path.join(consumerScene, "browser-review.json");
+  const candidate = JSON.parse(fs.readFileSync(candidatePath, "utf8"));
+  candidate.expires_at = "2099-01-01T00:00:00Z";
+  fs.writeFileSync(candidatePath, `${JSON.stringify(candidate, null, 2)}\n`);
+  run(bin, ["devlab", scene, "--prepare-only"], { cwd: consumer });
+  if (!fs.existsSync(path.join(installedRoot, "dev-lab", "public", "scenes", scene, "browser-review.json"))) {
+    throw new Error("installed Dev Lab did not prepare the consumer scene");
+  }
+  run(process.execPath, ["--input-type=module", "-e", "await import('playwright'); await import('vite');"], { cwd: consumer });
+  console.log(JSON.stringify({ status: "pass", project_root: init.project_root, installed_root: installedRoot }, null, 2));
+} finally {
+  fs.rmSync(temporary, { recursive: true, force: true });
+}

package/scripts/review-hook.py

@@ -16,7 +16,10 @@ from urllib.parse import urlencode, urlsplit, urlunsplit
 
 ROOT = Path(__file__).resolve().parents[1]
 SAFE_SCENE = re.compile(r"^[A-Za-z0-9._-]+$")
+SAFE_ANIMATION = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
 CANDIDATE_TTL = timedelta(hours=24)
+RUNTIME_DESCRIPTOR = "devlab-runtime.json"
+RUNTIME_MODES = {"sprite-sequence", "iframe"}
 
 
 def now() -> str:
@@ -37,18 +40,24 @@ def parse_time(value: str) -> datetime:
     return datetime.fromisoformat(value.replace("Z", "+00:00"))
 
 
-def candidate_id(task_id: str, scene: str, context_hash: str, source_hash: str, render_hash: str) -> str:
-    raw = f"{task_id}:{scene}:{context_hash}:{source_hash}:{render_hash}".encode()
-    return hashlib.sha256(raw).hexdigest()[:20]
+def candidate_id(
+    task_id: str,
+    scene: str,
+    context_hash: str,
+    source_hash: str,
+    render_hash: str,
+    runtime_bundle_hash: str | None = None,
+) -> str:
+    # Keep the legacy identity formula byte-for-byte when a scene has no live
+    # runtime descriptor so already-prepared snapshot candidates remain valid.
+    raw = f"{task_id}:{scene}:{context_hash}:{source_hash}:{render_hash}"
+    if runtime_bundle_hash:
+        raw += f":devlab-runtime:{runtime_bundle_hash}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:20]
 
 
 def review_urls(lab_url: str, scene: str, task_id: str, candidate: str) -> tuple[str, str, str]:
-    """Build an exact review route while anchoring artifact paths at its origin.
-
-    `--lab-url` is the actual browser route, e.g. `https://host/lab` for the
-    React Dev Lab or `http://127.0.0.1:3300/` for the bundled static lab.
-    Artifact and task paths intentionally remain same-origin root paths.
-    """
+    """Build an exact review route while anchoring artifact paths at its origin."""
     parsed = urlsplit(lab_url.strip())
     if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.query or parsed.fragment:
         raise ValueError("lab-url must be an absolute http(s) Dev Lab route without query or fragment")
@@ -62,7 +71,11 @@ def review_urls(lab_url: str, scene: str, task_id: str, candidate: str) -> tuple
         "artifact_base": f"{origin}/scenes/{scene}",
         "task_base": f"{origin}/tasks/{task_id}",
     })
-    return f"{review_base}/?{query}" if review_path != "/" else f"{origin}/?{query}", f"{origin}/scenes/{scene}", f"{origin}/tasks/{task_id}"
+    return (
+        f"{review_base}/?{query}" if review_path != "/" else f"{origin}/?{query}",
+        f"{origin}/scenes/{scene}",
+        f"{origin}/tasks/{task_id}",
+    )
 
 
 def paths(task_dir: Path, task: dict) -> tuple[Path, Path, Path, Path]:
@@ -84,6 +97,137 @@ def paths(task_dir: Path, task: dict) -> tuple[Path, Path, Path, Path]:
     return scene_dir, source_path, render_meta, context_path
 
 
+def safe_relative_file(scene_dir: Path, value: object, label: str) -> tuple[str, Path]:
+    if not isinstance(value, str) or not value or value.startswith(("/", "\\")) or "\\" in value:
+        raise ValueError(f"{label} must be a scene-relative path")
+    parts = Path(value).parts
+    if not parts or any(part in {"", ".", ".."} for part in parts):
+        raise ValueError(f"{label} contains unsafe path segments: {value!r}")
+    scene_root = scene_dir.resolve()
+    current = scene_root
+    for part in parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError(f"{label} must not traverse symlinks: {value}")
+    resolved = (scene_root / value).resolve()
+    if not resolved.is_file() or scene_root not in resolved.parents:
+        raise ValueError(f"{label} must resolve to an existing file inside the scene: {value}")
+    return value, resolved
+
+
+def runtime_bundle(scene_dir: Path) -> dict | None:
+    descriptor_path = scene_dir / RUNTIME_DESCRIPTOR
+    if not descriptor_path.exists():
+        return None
+    if descriptor_path.is_symlink() or not descriptor_path.is_file():
+        raise ValueError("devlab-runtime.json must be a regular scene-local file")
+    descriptor = read_json(descriptor_path)
+    if descriptor.get("schema_version") != "1.0":
+        raise ValueError("devlab-runtime.json schema_version must be 1.0")
+    mode = descriptor.get("mode")
+    if mode not in RUNTIME_MODES:
+        raise ValueError(f"devlab-runtime.json mode is unsupported: {mode!r}")
+    files = descriptor.get("files")
+    if not isinstance(files, list) or not files:
+        raise ValueError("devlab-runtime.json requires a non-empty files array")
+    resolved_files: dict[str, Path] = {}
+    reserved_runtime_files = {RUNTIME_DESCRIPTOR, "browser-review.json", "review.json"}
+    for raw in files:
+        relative, resolved = safe_relative_file(scene_dir, raw, "runtime file")
+        if relative in reserved_runtime_files:
+            raise ValueError(f"devlab-runtime.json must not hash mutable review metadata as runtime bytes: {relative}")
+        if relative in resolved_files:
+            raise ValueError(f"devlab-runtime.json repeats runtime file: {relative}")
+        resolved_files[relative] = resolved
+
+    animations = descriptor.get("animations")
+    if not isinstance(animations, list) or not animations:
+        raise ValueError("devlab-runtime.json requires at least one animation")
+    animation_ids: list[str] = []
+    for animation in animations:
+        if not isinstance(animation, dict):
+            raise ValueError("devlab-runtime.json animations must be objects")
+        action_id = animation.get("id")
+        if not isinstance(action_id, str) or not SAFE_ANIMATION.fullmatch(action_id):
+            raise ValueError(f"devlab-runtime.json animation id is invalid: {action_id!r}")
+        if action_id in animation_ids:
+            raise ValueError(f"devlab-runtime.json repeats animation id: {action_id}")
+        animation_ids.append(action_id)
+        if mode == "sprite-sequence":
+            fps = animation.get("fps")
+            frames = animation.get("frames")
+            if not isinstance(fps, (int, float)) or isinstance(fps, bool) or fps <= 0:
+                raise ValueError(f"sprite animation {action_id} requires a positive fps")
+            if not isinstance(frames, list) or not frames:
+                raise ValueError(f"sprite animation {action_id} requires frames")
+            for frame in frames:
+                relative, _ = safe_relative_file(scene_dir, frame, f"frame for {action_id}")
+                if relative not in resolved_files:
+                    raise ValueError(f"frame for {action_id} is not declared in runtime files: {relative}")
+
+    default_animation = descriptor.get("default_animation")
+    if default_animation not in animation_ids:
+        raise ValueError("devlab-runtime.json default_animation must reference a declared animation")
+    if mode == "iframe":
+        entrypoint, _ = safe_relative_file(scene_dir, descriptor.get("entrypoint"), "runtime entrypoint")
+        if entrypoint not in resolved_files:
+            raise ValueError("runtime entrypoint must be declared in runtime files")
+
+    controls = descriptor.get("controls")
+    if not isinstance(controls, dict):
+        raise ValueError("devlab-runtime.json controls object is required")
+    for control in ("play", "pause", "restart", "seek", "step", "speed", "loop"):
+        if not isinstance(controls.get(control), bool):
+            raise ValueError(f"devlab-runtime.json controls.{control} must be boolean")
+    review_policy = descriptor.get("review_policy")
+    if not isinstance(review_policy, dict) or not isinstance(review_policy.get("require_all_animations"), bool):
+        raise ValueError("devlab-runtime.json review_policy.require_all_animations must be boolean")
+
+    digest = hashlib.sha256()
+    digest.update(b"motionloom-devlab-runtime-v1\0")
+    digest.update(descriptor_path.read_bytes())
+    for relative in sorted(resolved_files):
+        digest.update(b"\0path\0")
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0bytes\0")
+        digest.update(resolved_files[relative].read_bytes())
+    return {
+        "descriptor": descriptor,
+        "bundle_sha256": digest.hexdigest(),
+        "animations": animation_ids,
+        "mode": mode,
+        "files": sorted(resolved_files),
+        "review_policy": {"require_all_animations": review_policy["require_all_animations"]},
+    }
+
+
+def runtime_review_payload(bundle: dict | None) -> dict:
+    if not bundle:
+        return {
+            "live": False,
+            "mode": "captured-evidence",
+            "checkpoints": [0, 50, 100],
+        }
+    return {
+        "live": True,
+        "mode": bundle["mode"],
+        "descriptor": RUNTIME_DESCRIPTOR,
+        "bundle_sha256": bundle["bundle_sha256"],
+        "animations": bundle["animations"],
+        "review_policy": bundle["review_policy"],
+    }
+
+
+def review_instruction(bundle: dict | None) -> str:
+    if bundle:
+        actions = ", ".join(bundle["animations"])
+        return (
+            "Open this exact URL in the internal browser; exercise the live runtime controls, "
+            f"inspect the declared animations ({actions}), scrub/step the candidate, and ask the user to approve or request changes."
+        )
+    return "Open this exact URL in the internal browser; inspect frames 0/50/100 and ask the user to approve or request changes."
+
+
 def prepare(args: argparse.Namespace) -> int:
     task_dir = Path(args.task_dir).resolve()
     task_path = task_dir / "task.json"
@@ -92,6 +236,7 @@ def prepare(args: argparse.Namespace) -> int:
     if not scene:
         raise ValueError("task.json requires scene")
     scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
+    bundle = runtime_bundle(scene_dir)
     memory_path = ROOT / ".motionloom" / "project-memory.json"
     memory = read_json(memory_path, {}) if memory_path.is_file() else {}
     memory_status = (memory.get("freshness") or {}).get("status")
@@ -101,7 +246,7 @@ def prepare(args: argparse.Namespace) -> int:
     context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
     source_hash = sha256(source_path)
     render_hash = sha256(render_meta)
-    cid = candidate_id(task["task_id"], scene, context_hash, source_hash, render_hash)
+    cid = candidate_id(task["task_id"], scene, context_hash, source_hash, render_hash, bundle["bundle_sha256"] if bundle else None)
     task_id = task["task_id"]
     url, artifact_base, task_base = review_urls(args.lab_url, scene, task_id, cid)
     candidate = {
@@ -115,6 +260,7 @@ def prepare(args: argparse.Namespace) -> int:
         "source_sha256": source_hash,
         "runtime": spec.get("framework", "unknown"),
         "checkpoints": [0, 50, 100],
+        "runtime_review": runtime_review_payload(bundle),
         "review_artifact": "review.json",
         "requires_user_approval": True,
         "prepared_at": now(),
@@ -126,27 +272,81 @@ def prepare(args: argparse.Namespace) -> int:
     (scene_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
     task["state"] = "review_required"
     task["updated_at"] = now()
-    task["browser_review"] = {"required": True, "status": "prepared", "candidate_id": cid, "candidate_path": "browser-review.json", "review_artifact": "review.json"}
+    task["browser_review"] = {
+        "required": True,
+        "status": "prepared",
+        "candidate_id": cid,
+        "candidate_path": "browser-review.json",
+        "review_artifact": "review.json",
+        "runtime_review": candidate["runtime_review"],
+    }
     (task_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
     (task_dir / "task.json").write_text(json.dumps(task, indent=2) + "\n", encoding="utf-8")
     report_path = task_dir / "execution-report.json"
     report = read_json(report_path)
     report["status"] = "review_required"
     report["browser_review"] = [item for item in report.get("browser_review", []) if item.get("candidate_id") != cid]
-    report["browser_review"].append({"candidate_id": cid, "decision": "pending", "evidence": ["browser-review.json"], "next_action": "Open the internal Dev Lab URL and ask the user to review."})
+    report["browser_review"].append({
+        "candidate_id": cid,
+        "decision": "pending",
+        "evidence": ["browser-review.json"] + ([RUNTIME_DESCRIPTOR] if bundle else []),
+        "next_action": review_instruction(bundle),
+    })
     report["next_agent"] = [item for item in report.get("next_agent", []) if item.get("id") != "browser-review"]
-    report["next_agent"].append({"id": "browser-review", "summary": "Open the exact candidate in the internal Dev Lab browser.", "status": "pending", "agent": "browser-review-agent", "skill": "browser-review", "evidence_needed": ["review.json"], "next_action": "Ask user to approve or request changes."})
+    report["next_agent"].append({
+        "id": "browser-review",
+        "summary": "Open the exact candidate in the internal Dev Lab browser.",
+        "status": "pending",
+        "agent": "browser-review-agent",
+        "skill": "browser-review",
+        "evidence_needed": ["review.json"],
+        "next_action": review_instruction(bundle),
+    })
     report["generated_at"] = now()
     report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     handoff_path = task_dir / "handoff.json"
     handoff = read_json(handoff_path)
     if memory_path.is_file():
         shutil.copy2(memory_path, task_dir / "project-memory.json")
-    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "artifact_base": artifact_base, "task_base": task_base, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"] + (["project-memory.json"] if memory_path.is_file() else [])))})
+    handoff.update({
+        "state": "review_required",
+        "to_agent": "browser-review-agent",
+        "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.",
+        "next_actions": [{
+            "action": "Open internal Dev Lab candidate",
+            "kind": "browser_review",
+            "agent": "browser-review-agent",
+            "skill": "browser-review",
+            "url": url,
+            "artifact_base": artifact_base,
+            "task_base": task_base,
+            "candidate_id": cid,
+            "runtime_review": candidate["runtime_review"],
+            "requires_user_approval": True,
+            "evidence_needed": ["review.json"],
+            "output_artifacts": ["review.json"],
+        }],
+        "required_artifacts": sorted(set(
+            handoff.get("required_artifacts", [])
+            + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"]
+            + ([RUNTIME_DESCRIPTOR] if bundle else [])
+            + (["project-memory.json"] if memory_path.is_file() else [])
+        )),
+    })
     handoff_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     subprocess.run([sys.executable, str(ROOT / "scripts/devlab.py"), scene, "--prepare-only", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
     subprocess.run([sys.executable, str(ROOT / "scripts/report.py"), "collect", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
-    print(json.dumps({"status": "review_required", "task_id": task["task_id"], "candidate_id": cid, "url": url, "agent": "browser-review-agent", "action": "Open this exact URL in the internal browser; ask the user to inspect frames 0/50/100 and approve or request changes.", "requires_user_approval": True, "output_artifacts": ["review.json"]}, ensure_ascii=False))
+    print(json.dumps({
+        "status": "review_required",
+        "task_id": task["task_id"],
+        "candidate_id": cid,
+        "url": url,
+        "agent": "browser-review-agent",
+        "action": review_instruction(bundle),
+        "runtime_review": candidate["runtime_review"],
+        "requires_user_approval": True,
+        "output_artifacts": ["review.json"],
+    }, ensure_ascii=False))
     return 0
 
 
@@ -156,8 +356,12 @@ def validate(args: argparse.Namespace) -> int:
     candidate = read_json(task_dir / "browser-review.json")
     scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
     spec = read_json(scene_dir / "motion-spec.json")
+    bundle = runtime_bundle(scene_dir)
     context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
-    expected = candidate_id(task["task_id"], task["scene"], context_hash, sha256(source_path), sha256(render_meta))
+    expected = candidate_id(
+        task["task_id"], task["scene"], context_hash, sha256(source_path), sha256(render_meta),
+        bundle["bundle_sha256"] if bundle else None,
+    )
     errors = []
     if not candidate.get("expires_at"):
         errors.append("browser-review candidate has no expiry")
@@ -168,7 +372,7 @@ def validate(args: argparse.Namespace) -> int:
         except (TypeError, ValueError):
             errors.append("browser-review candidate expiry is invalid")
     if candidate.get("candidate_id") != expected:
-        errors.append("candidate_id does not match task, context, source and runtime metadata")
+        errors.append("candidate_id does not match task, context, source, runtime metadata and live runtime bundle")
     if candidate.get("task_id") != task.get("task_id"):
         errors.append("candidate task_id does not match task.json")
     task_review = task.get("browser_review") or {}
@@ -184,6 +388,22 @@ def validate(args: argparse.Namespace) -> int:
         errors.append("candidate context_sha256 is stale")
     if candidate.get("status") not in {"prepared", "opened", "reviewed", "approved", "changes_requested", "expired"}:
         errors.append(f"browser-review candidate status is invalid: {candidate.get('status')}")
+
+    runtime_review = candidate.get("runtime_review") or {}
+    if bundle:
+        if runtime_review.get("live") is not True:
+            errors.append("candidate does not declare the available live runtime")
+        if runtime_review.get("descriptor") != RUNTIME_DESCRIPTOR:
+            errors.append("candidate live runtime descriptor binding is missing")
+        if runtime_review.get("mode") != bundle["mode"]:
+            errors.append("candidate live runtime mode is stale")
+        if runtime_review.get("bundle_sha256") != bundle["bundle_sha256"]:
+            errors.append("candidate live runtime bundle hash is stale")
+        if runtime_review.get("animations") != bundle["animations"]:
+            errors.append("candidate live runtime animation set is stale")
+    elif runtime_review.get("live") is True:
+        errors.append("candidate claims live runtime but devlab-runtime.json is missing")
+
     review = read_json(task_dir / "review.json", {})
     if review and review.get("candidate_id") != candidate.get("candidate_id"):
         errors.append("review.json approves a different candidate")
@@ -199,13 +419,29 @@ def validate(args: argparse.Namespace) -> int:
                     errors.append("review.json was recorded after candidate expiry")
             except (TypeError, ValueError, KeyError):
                 errors.append("review.json reviewed_at or candidate expiry is invalid")
+        if review.get("decision") == "approved" and bundle and bundle["review_policy"]["require_all_animations"]:
+            inspected = set(review.get("animations_inspected") or [])
+            required = {
+                animation["id"] for animation in bundle["descriptor"]["animations"]
+                if animation.get("review_required", True)
+            }
+            missing = sorted(required - inspected)
+            if missing:
+                errors.append(f"approved review did not inspect required animations: {', '.join(missing)}")
     if args.require_approved:
         if candidate.get("status") != "approved":
             errors.append("browser-review candidate is not approved")
         if not review or review.get("decision") != "approved":
             errors.append("review.json decision must be approved")
     status = "pass" if not errors else "fail"
-    print(json.dumps({"status": status, "task_id": task.get("task_id"), "candidate_id": candidate.get("candidate_id"), "candidate_status": candidate.get("status"), "errors": errors}, ensure_ascii=False))
+    print(json.dumps({
+        "status": status,
+        "task_id": task.get("task_id"),
+        "candidate_id": candidate.get("candidate_id"),
+        "candidate_status": candidate.get("status"),
+        "runtime_review": runtime_review,
+        "errors": errors,
+    }, ensure_ascii=False))
     return 0 if not errors else 1
 
 

package/scripts/runtime-adapters.mjs

@@ -6,9 +6,11 @@ import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { chromium } from "playwright";
 import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
 
-const ROOT = path.resolve(new URL("..", import.meta.url).pathname);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const outputRoot = path.resolve(process.env.RUNTIME_EVIDENCE_DIR || path.join(ROOT, "artifacts/runtime-adapters"));
+const outputPolicyRoot = path.resolve(process.env.MOTIONLOOM_RUNTIME_OUTPUT_ROOT || ROOT);
 const port = Number(process.env.RUNTIME_HARNESS_PORT || 4179);
 const supportedFrameworks = new Set(["rive", "gsap", "framer-motion"]);
 const frameworks = (process.env.RUNTIME_FRAMEWORKS || "rive,gsap,framer-motion")
@@ -17,8 +19,31 @@ const unsupported = frameworks.filter((name) => !supportedFrameworks.has(name));
 if (unsupported.length) {
   throw new Error(`unsupported runtime framework(s): ${unsupported.join(", ")}`);
 }
-if (outputRoot === ROOT || outputRoot === path.parse(outputRoot).root) {
-  throw new Error("RUNTIME_EVIDENCE_DIR must be a dedicated child output directory");
+function canonicalPath(target) {
+  let existing = target;
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  const base = fs.existsSync(existing) ? fs.realpathSync(existing) : path.resolve(existing);
+  return path.resolve(base, ...missing);
+}
+
+function isStrictChild(target, parent) {
+  const relative = path.relative(parent, target);
+  return Boolean(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+const canonicalOutputRoot = canonicalPath(outputRoot);
+const canonicalPolicyRoot = canonicalPath(outputPolicyRoot);
+if (!isStrictChild(canonicalOutputRoot, canonicalPolicyRoot)) {
+  throw new Error(
+    `RUNTIME_EVIDENCE_DIR must be a dedicated child of ${outputPolicyRoot}; ` +
+    "set MOTIONLOOM_RUNTIME_OUTPUT_ROOT explicitly to authorize another parent",
+  );
 }
 const baseUrl = `http://127.0.0.1:${port}`;
 const runId = `${Date.now()}-${process.pid}`;

package/scripts/skill-doctor.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import re
 import sys
@@ -11,7 +12,15 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
-REQUIRED_FILES = ["SKILL.md", "agent-card.json", "package.json"]
+REQUIRED_FILES = [
+    "SKILL.md",
+    "agent-card.json",
+    "package.json",
+    "requirements.txt",
+    "dev-lab/public/index.html",
+    "dev-lab/public/devlab.js",
+    "tests/runtime-harness/index.html",
+]
 REQUIRED_DIRS = ["scripts", "templates", "references", "schemas"]
 REQUIRED_SCRIPT_FILES = [
     "scripts/report-contract.py",
@@ -135,9 +144,26 @@ def run() -> int:
         for script in ("test", "validate", "doctor", "setup", "setup:dry", "status", "repair", "report", "report:check", "review", "memory:bootstrap", "memory:recover", "memory:validate", "devlab", "pack:dotlottie"):
             if script not in package.get("scripts", {}):
                 warnings.append({"code": "missing_package_script", "message": f"package.json has no {script} script."})
+        runtime_dependencies = {
+            **package.get("dependencies", {}),
+            **package.get("optionalDependencies", {}),
+        }
+        for dependency in ("playwright", "vite"):
+            present = dependency in runtime_dependencies
+            checks.append({"id": f"runtime-dependency:{dependency}", "status": "pass" if present else "fail"})
+            if not present:
+                errors.append({"code": "missing_runtime_dependency", "message": f"package.json runtime dependencies omit {dependency}."})
     except (FileNotFoundError, json.JSONDecodeError) as exc:
         errors.append({"code": "invalid_package_json", "message": str(exc)})
 
+    cryptography_available = importlib.util.find_spec("cryptography") is not None
+    checks.append({"id": "python-dependency:cryptography", "status": "pass" if cryptography_available else "fail"})
+    if not cryptography_available:
+        errors.append({
+            "code": "missing_python_dependency",
+            "message": "Python package cryptography is required; install dependencies from requirements.txt.",
+        })
+
     result = {
         "doctor_version": "1.0",
         "skill_root": str(ROOT),

package/tests/runtime-harness/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Animation Skill Runtime Harness</title>
+    <style>
+      html, body { margin: 0; min-height: 100%; background: #111827; color: #f8fafc; font-family: system-ui, sans-serif; }
+      body { display: grid; place-items: center; }
+      #root { width: 512px; height: 512px; display: grid; place-items: center; }
+      .stage { position: relative; width: 420px; height: 420px; overflow: hidden; background: #f8fafc; border-radius: 12px; }
+      .stage::after { content: ""; position: absolute; inset: 0; pointer-events: none; border: 1px solid rgba(15,23,42,.2); border-radius: inherit; }
+      .gsap-box, .motion-box { width: 96px; height: 96px; position: absolute; left: 40px; top: 160px; border-radius: 18px; background: #2563eb; transform-origin: center; }
+      .gsap-box::after, .motion-box::after { content: ""; position: absolute; width: 16px; height: 16px; border-radius: 50%; right: 14px; top: 14px; background: #f59e0b; }
+      canvas { width: 420px; height: 420px; display: block; }
+      #status { position: fixed; left: 12px; bottom: 12px; font: 12px ui-monospace, monospace; color: #fbbf24; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <div id="status">loading</div>
+    <script type="module" src="/tests/runtime-harness/main.jsx"></script>
+  </body>
+</html>