motionloom 2.0.0

package/src/core/spec.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+spec.py — Step 2 of the pipeline: Motion Spec generation & validation.
+
+A motion spec is the signed contract between the understanding step and the
+generation step. It binds the animation to the project context, picks the
+framework per the selection matrix, and validates that the requested values
+stay inside the performance budget (file size, frame count, layer count).
+
+Usage:
+    python3 src/core/spec.py generate <category> --duration 0.8 --loop \
+        --context project-context.json --output motion-spec.md
+    python3 src/core/spec.py validate motion-spec.md
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+FRAMEWORK_MATRIX = {
+    "ui-micro": ["framer-motion", "gsap"],
+    "loading": ["lottie", "framer-motion", "css"],
+    "hero-scene": ["lottie", "gsap", "threejs"],
+    "character-body": ["lottie", "spine"],
+    "icon-animation": ["lottie", "framer-motion", "css"],
+    "scroll-linked": ["gsap", "framer-motion"],
+    "data-viz": ["gsap", "framer-motion", "threejs"],
+    "3d-scene": ["threejs"],
+}
+
+EASING_CANON = {
+    "linear", "ease", "ease-in", "ease-out", "ease-in-out",
+    "ease-in-sine", "ease-out-sine", "ease-in-out-sine",
+    "ease-in-quad", "ease-out-quad", "ease-in-out-quad",
+    "ease-in-cubic", "ease-out-cubic", "ease-in-out-cubic",
+    "ease-in-expo", "ease-out-expo", "ease-in-out-expo",
+    "ease-in-back", "ease-out-back", "ease-in-out-back",
+    "spring", "anticipation", "overshoot",
+}
+
+PERF_BUDGET = {
+    "max_file_kb": 300,          # dotLottie target for UI; 1500 for hero
+    "max_layers": 80,
+    "max_duration_hero_s": 8,
+    "max_duration_ui_s": 2,
+    "default_fps": 60,
+    "rig_fps": 30,
+}
+
+
+def generate_spec(args) -> dict:
+    context = {}
+    ctx_path = Path(args.context).resolve() if args.context else None
+    if ctx_path and ctx_path.exists():
+        try:
+            context = json.loads(ctx_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"error: invalid context JSON: {ctx_path}: {exc}")
+    elif not args.allow_unbound:
+        raise SystemExit(f"error: context not found: {ctx_path}; run analyze first (or pass --allow-unbound explicitly)")
+
+    if args.category not in FRAMEWORK_MATRIX:
+        raise SystemExit(f"error: unknown category '{args.category}'; choose one of: {', '.join(FRAMEWORK_MATRIX)}")
+    duration = args.duration if args.duration is not None else _default_duration(args.category)
+    fps = args.fps or (PERF_BUDGET["rig_fps"] if args.category == "character-body" else PERF_BUDGET["default_fps"])
+    total_frames = round(duration * fps)
+
+    stack_pref = (context.get("stack") or {}).get("framework")
+    candidates = FRAMEWORK_MATRIX.get(args.category, ["lottie"])
+    framework = args.framework or (stack_pref if stack_pref in candidates else candidates[0])
+
+    easing = args.easing or context.get("motion_language", {}).get("recommendation") or "ease-in-out"
+    if easing not in EASING_CANON:
+        print(f"warning: easing '{easing}' not in canon; defaulting to ease-in-out", file=sys.stderr)
+        easing = "ease-in-out"
+
+    brand = context.get("brand", {})
+    manifest_motion = ((context.get("manifest_overrides") or {}).get("motion") or {})
+    spec = {
+        "version": "1.0",
+        "category": args.category,
+        "framework": framework,
+        "duration_s": duration,
+        "fps": fps,
+        "total_frames": total_frames,
+        "loop": _default_loop(args.category) if args.loop is None else args.loop,
+        "easing": easing,
+        "camera": args.camera or ("push-in" if args.category == "hero-scene" else None),
+        "theme": {
+            "primary": brand.get("primary"),
+            "accent": brand.get("accent"),
+        },
+        "performance": {
+            "max_file_kb": PERF_BUDGET["max_file_kb"],
+            "max_layers": PERF_BUDGET["max_layers"],
+        },
+        "source_binding": context.get("source_authority", ""),
+        "context_binding": {
+            "name": context.get("name"),
+            "project_root": context.get("project_root"),
+            "context_sha256": _sha256(ctx_path) if ctx_path and ctx_path.exists() else None,
+        },
+        "accessibility": {
+            "reduced_motion": manifest_motion.get("reduced_motion", "respect-prefers-reduced-motion"),
+        },
+    }
+    if args.interactivity:
+        spec["interactivity"] = [i.strip() for i in args.interactivity.split(",")]
+    out = Path(args.output)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(spec, indent=2) + "\n", encoding="utf-8")
+    print(f"motion-spec.json written -> {out}")
+    return spec
+
+
+def _default_duration(category: str) -> float:
+    # CLI-first import: works when run directly without PYTHONPATH
+    for extra in (".", os.path.dirname(os.path.dirname(os.path.abspath(__file__)))):
+        if extra not in sys.path:
+            sys.path.insert(0, extra)
+    return _load_categories().get(category, {}).get("default_duration_s", 1.0)
+
+
+def _default_loop(category: str) -> bool:
+    return bool(_load_categories().get(category, {}).get("loop", False))
+
+
+def _load_categories() -> dict:
+    try:
+        from core.analyzer import CATEGORIES  # noqa
+        return CATEGORIES
+    except ModuleNotFoundError:
+        return {}
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def validate_spec(path: str, context_path: str | None = None) -> list:
+    issues = []
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+        spec = json.loads(text) if text.strip().startswith("{") else _parse_md_spec(text)
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        return [f"invalid motion spec: {exc}"]
+    if not isinstance(spec, dict):
+        return ["motion spec root must be a JSON object"]
+    category = spec.get("category")
+    framework = spec.get("framework")
+    if category not in FRAMEWORK_MATRIX:
+        issues.append(f"unknown category '{category}'")
+    elif framework not in FRAMEWORK_MATRIX[category]:
+        issues.append(f"framework '{framework}' is not allowed for category '{category}'")
+    duration = spec.get("duration_s")
+    fps = spec.get("fps")
+    if not isinstance(duration, (int, float)) or isinstance(duration, bool):
+        issues.append("duration_s must be a number")
+        duration = 0
+    if not isinstance(fps, (int, float)) or isinstance(fps, bool):
+        issues.append("fps must be a number")
+        fps = 0
+    if duration <= 0:
+        issues.append("duration_s must be greater than zero")
+    if fps <= 0:
+        issues.append("fps must be greater than zero")
+    if duration > PERF_BUDGET["max_duration_ui_s"] and category not in ("hero-scene", "character-body", "3d-scene"):
+        issues.append(f"duration {duration}s exceeds {PERF_BUDGET['max_duration_ui_s']}s budget for {category}")
+    if fps not in (30, 60, 120):
+        issues.append(f"fps {fps} is non-standard; prefer 30/60/120")
+    expected_frames = round(duration * fps)
+    if spec.get("total_frames") != expected_frames:
+        issues.append(f"total_frames {spec.get('total_frames')} does not equal duration_s × fps ({expected_frames})")
+    easing = spec.get("easing")
+    if easing not in EASING_CANON:
+        issues.append(f"easing '{easing}' not in canonical list")
+    if not spec.get("theme", {}).get("primary"):
+        issues.append("no brand primary color bound — run analyzer first")
+    binding = spec.get("context_binding") or {}
+    if not binding.get("name") or not binding.get("project_root") or not binding.get("context_sha256"):
+        issues.append("missing context_binding — spec is not bound to a project context")
+    if context_path:
+        context_file = Path(context_path)
+        if not context_file.exists():
+            issues.append(f"context file not found: {context_file}")
+        elif binding.get("context_sha256") != _sha256(context_file):
+            issues.append("context hash mismatch — regenerate motion spec after project analysis changes")
+    return issues
+
+
+def _parse_md_spec(text: str) -> dict:
+    def grab(key):
+        m = re.search(rf"-\s*\*?{key}\*?\s*[:=]\s*(.+)", text)
+        return m.group(1).strip() if m else None
+    return {
+        "category": grab("category") or "ui-micro",
+        "framework": grab("framework") or "lottie",
+        "duration_s": float(grab("duration") or 1.0),
+        "fps": int(grab("fps") or 60),
+        "loop": "true" in (grab("loop") or "false"),
+        "easing": grab("easing") or "ease-in-out",
+        "theme": {"primary": grab("primary")},
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="cmd")
+    g = sub.add_parser("generate")
+    g.add_argument("category")
+    g.add_argument("--framework")
+    g.add_argument("--duration", type=float)
+    g.add_argument("--fps", type=int)
+    g.add_argument("--loop", action="store_true")
+    g.add_argument("--no-loop", dest="loop", action="store_false")
+    g.add_argument("--easing")
+    g.add_argument("--camera")
+    g.add_argument("--interactivity")
+    g.add_argument("--context", default="project-context.json")
+    g.add_argument("--allow-unbound", action="store_true", help="allow generation without project-context.json (not accepted by quality gate)")
+    g.add_argument("--output", default="motion-spec.json")
+    g.set_defaults(loop=None)
+    v = sub.add_parser("validate")
+    v.add_argument("path")
+    v.add_argument("--context")
+    args = parser.parse_args()
+    if args.cmd == "generate":
+        generate_spec(args)
+    elif args.cmd == "validate":
+        issues = validate_spec(args.path, args.context)
+        print("PASS — no issues" if not issues else "ISSUES:\n" + "\n".join(f"- {i}" for i in issues))
+        sys.exit(1 if issues else 0)
+
+
+if __name__ == "__main__":
+    main()

package/src/output/browser-review-smoke/animation.json

@@ -0,0 +1,57 @@
+{
+  "v": "5.12.0",
+  "fr": 60,
+  "ip": 0,
+  "op": 60,
+  "w": 512,
+  "h": 512,
+  "nm": "generated-scene",
+  "ddd": 0,
+  "assets": [],
+  "layers": [
+    {
+      "ddd": 0,
+      "ind": 1,
+      "ty": 4,
+      "nm": "shape-layer",
+      "sr": 1,
+      "ks": {
+        "o": { "a": 0, "k": 100 },
+        "r": { "a": 0, "k": 0 },
+        "p": { "a": 0, "k": [256, 256, 0] },
+        "a": { "a": 0, "k": [0, 0, 0] },
+        "s": {
+          "a": 1,
+          "k": [
+            { "t": 0,  "s": [80, 80, 100], "i": { "x": [0.4], "y": [1] }, "o": { "x": [0.6], "y": [0] } },
+            { "t": 30, "s": [105, 105, 100], "i": { "x": [0.4], "y": [1] }, "o": { "x": [0.6], "y": [0] } },
+            { "t": 60, "s": [100, 100, 100] }
+          ]
+        }
+      },
+      "ao": 0,
+      "shapes": [
+        {
+          "ty": "gr",
+          "it": [
+            { "ty": "el", "p": { "a": 0, "k": [0, 0] }, "s": { "a": 0, "k": [120, 120] } },
+            {
+              "ty": "fl",
+              "c": { "a": 0, "k": [0.145, 0.388, 0.922, 1] },
+              "o": { "a": 0, "k": 100 },
+              "r": 1
+            },
+            { "ty": "tr", "p": { "a": 0, "k": [0, 0] }, "a": { "a": 0, "k": [0, 0] }, "s": { "a": 0, "k": [100, 100] }, "r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 } }
+          ]
+        }
+      ],
+      "ip": 0,
+      "op": 60,
+      "st": 0
+    }
+  ],
+  "markers": [
+    { "cm": "loop-start", "tm": 0, "dr": 30 },
+    { "cm": "loop-end", "tm": 30, "dr": 30 }
+  ]
+}

package/src/output/browser-review-smoke/browser-review.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": "1.0",
+  "candidate_id": "88a2f2f18ba45a07f56e",
+  "task_id": "professional-review-e2e",
+  "scene": "browser-review-smoke",
+  "url": "https://3300-i8isn2ocahcvfq0jk51ta-68c15abe.sg1.manus.computer/?scene=browser-review-smoke&task_id=professional-review-e2e&candidate_id=88a2f2f18ba45a07f56e&artifact_base=https%3A%2F%2F3300-i8isn2ocahcvfq0jk51ta-68c15abe.sg1.manus.computer%2Fscenes%2Fbrowser-review-smoke&task_base=https%3A%2F%2F3300-i8isn2ocahcvfq0jk51ta-68c15abe.sg1.manus.computer%2Ftasks%2Fprofessional-review-e2e",
+  "status": "approved",
+  "context_sha256": "cbbd43a53a0ddd5cf5452df5f6d521f06829465bd58c6d764a59d501ed1710fa",
+  "source_sha256": "c5ab312427678b17ae903d280d89db9d202670f031f10ad6fe774fc9aaecee8a",
+  "runtime": "lottie",
+  "checkpoints": [
+    0,
+    50,
+    100
+  ],
+  "review_artifact": "review.json",
+  "requires_user_approval": true,
+  "prepared_at": "2026-08-12T17:42:31Z",
+  "expires_at": "2026-08-13T17:42:31Z",
+  "reviewed_at": "2026-08-12T17:48:54Z"
+}

package/src/output/browser-review-smoke/manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "Browser Review Smoke",
+  "description": "Runtime candidate used to verify the mandatory internal browser review handoff.",
+  "framework": "lottie",
+  "category": "loading",
+  "file": "animation.json",
+  "source_binding": {
+    "kind": "fixture",
+    "source_path": "animation.json",
+    "source_url": "https://github.com/lenhonbp/MotionLoom/tree/main/src/output/browser-review-smoke",
+    "authority": "MotionLoom browser-review smoke fixture",
+    "license": "MIT",
+    "attribution": "Generated fixture retained for deterministic runtime and browser-review tests.",
+    "sha256": "c5ab312427678b17ae903d280d89db9d202670f031f10ad6fe774fc9aaecee8a"
+  },
+  "checks": [
+    {"id": "runtime", "label": "Runtime render evidence exists", "detail": "Frames 0, 50 and 100 are produced by the Lottie runtime.", "pass": true},
+    {"id": "timing", "label": "Timing matches motion spec", "detail": "Duration and FPS are bound to motion-spec.json.", "pass": true},
+    {"id": "reduced-motion", "label": "Reduced-motion policy is documented", "detail": "The motion spec contains the accessibility policy.", "pass": true},
+    {"id": "brand", "label": "Project context is bound", "detail": "Candidate context hash matches the generated spec.", "pass": true}
+  ]
+}

package/src/output/browser-review-smoke/motion-spec.json

@@ -0,0 +1,28 @@
+{
+  "version": "1.0",
+  "category": "loading",
+  "framework": "lottie",
+  "duration_s": 1.0,
+  "fps": 60,
+  "total_frames": 60,
+  "loop": false,
+  "easing": "ease-out",
+  "camera": null,
+  "theme": {
+    "primary": "#2563EB",
+    "accent": "#F59E0B"
+  },
+  "performance": {
+    "max_file_kb": 300,
+    "max_layers": 80
+  },
+  "source_binding": "project-manifest.json then assets/library/, never invented geometry",
+  "context_binding": {
+    "name": "browser-review-fixture",
+    "project_root": "/tmp/animation-review-host",
+    "context_sha256": "cbbd43a53a0ddd5cf5452df5f6d521f06829465bd58c6d764a59d501ed1710fa"
+  },
+  "accessibility": {
+    "reduced_motion": "respect-prefers-reduced-motion"
+  }
+}

package/src/output/browser-review-smoke/snapshot/.render-meta.json

@@ -0,0 +1,10 @@
+{
+  "mode": "runtime",
+  "scene": "browser-review-smoke",
+  "framework": "lottie",
+  "progress": [
+    0,
+    50,
+    100
+  ]
+}

package/src/rig/README.md

@@ -0,0 +1,35 @@
+# Cutout Body Rigging (`src/rig/`)
+
+This module turns flat vector art into an animatable character body using the cutout rig technique: each limb is a separate layer pivoted on an explicit joint, and motion is expressed as per-bone rotation keyframes. It is the same principle used by Spine and Duik, implemented portably in pure SVG + JSON keyframes so it plays in Lottie, GSAP, Framer Motion, or CSS.
+
+## Bone hierarchy
+
+Bones rotate in strict parent-first order: `hip → spine → chest → head`, shoulders branch to upper-arm → forearm → hand, and hips to thigh → shin → foot. The engine (`cutout_rig.py`) enforces this order when building the SVG `<g>` tree — a child never appears before its parent.
+
+## Conventions
+
+Each bone group carries two markers: `data-bone="<name>"` (used by the player to target rotations) and an inline `transform="rotate(...)"` so the pose is readable directly in the file. The `DEFAULT_POSE` dictionary in `cutout_rig.py` is the T-pose baseline; every clip is additive to it.
+
+## Building a rig
+
+```
+python3 src/rig/cutout_rig.py build \
+  --input assets/library/character-flat.svg \
+  --output rigged-avatar.svg \
+  --pivot-x 0 --pivot-y 0
+```
+
+If no authoritative art is provided, the engine emits a default geometric avatar that the designer must replace — never ship the placeholder as final art.
+
+## Clips and poses
+
+```
+python3 src/rig/cutout_rig.py pose rigged-avatar.svg --pose walk \
+  --duration 1.5 --fps 30 --out idle-clip.json
+```
+
+Built-in clips: `idle`, `walk`, `wave`, `nod`, `bounce`. Custom clips are plain JSON maps of `bone → [start_deg, end_deg]`. Interpolation uses smoothstep ease-in-out; set `loop: true` on the player for seamless cycles (`idle`, `walk`).
+
+## Exporting to Lottie
+
+Feed the rigged SVG plus the clip JSON to the Lottie template in `templates/lottie/` — the template wraps the bone tree in a dotLottie with a theme slot for the body color so the brand analyzer can recolor the character at runtime without regenerating the file.

package/src/rig/cutout_rig.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+cutout_rig.py — Body rigging engine for cutout character animation.
+
+Builds a skeletal hierarchy from an authoritative flat SVG and emits
+frame-interpolated pose keyframes suitable for
+Lottie export or direct GSAP/CSS playback.
+
+Hierarchy convention (parent-first rotation order):
+    root (hip)
+      spine -> chest -> head
+      L-shoulder -> L-upper-arm -> L-forearm -> L-hand
+      R-shoulder -> R-upper-arm -> R-forearm -> R-hand
+      L-hip -> L-thigh -> L-shin -> L-foot
+      R-hip -> R-thigh -> R-shin -> R-foot
+
+Usage:
+    python3 src/rig/cutout_rig.py build --input assets/library/avatar-base.svg --output rigged-avatar.svg
+    python3 src/rig/cutout_rig.py pose rigged-avatar.svg --pose idle --duration 1.5 --fps 30 --out idle.json
+"""
+
+import argparse
+import json
+import math
+import re
+import uuid
+from pathlib import Path
+
+BONES = [
+    "hip", "spine", "chest", "head",
+    "l_shoulder", "l_upper_arm", "l_forearm", "l_hand",
+    "r_shoulder", "r_upper_arm", "r_forearm", "r_hand",
+    "l_hip", "l_thigh", "l_shin", "l_foot",
+    "r_hip", "r_thigh", "r_shin", "r_foot",
+]
+
+# Default pose: degrees relative to parent (T-pose-ish standing)
+DEFAULT_POSE = {
+    "hip": 0, "spine": 0, "chest": 0, "head": 0,
+    "l_shoulder": 10, "l_upper_arm": -8, "l_forearm": -12, "l_hand": 0,
+    "r_shoulder": -10, "r_upper_arm": 8, "r_forearm": 12, "r_hand": 0,
+    "l_hip": 0, "l_thigh": 2, "l_shin": -1, "l_foot": 0,
+    "r_hip": 0, "r_thigh": -2, "r_shin": 1, "r_foot": 0,
+}
+
+# Preset motion clips: per-bone (start, end) offsets in degrees, additive to DEFAULT_POSE
+CLIPS = {
+    "idle": {
+        "head": (-3, 3), "chest": (-1, 1), "l_upper_arm": (4, 4),
+        "r_upper_arm": (-4, -4), "spine": (-1, 1),
+    },
+    "walk": {
+        "l_thigh": (18, -18), "r_thigh": (-18, 18),
+        "l_shin": (-22, 10), "r_shin": (10, -22),
+        "l_upper_arm": (-24, 24), "r_upper_arm": (24, -24),
+        "spine": (-3, 3), "head": (2, -2),
+    },
+    "wave": {
+        "r_upper_arm": (-110, -110), "r_forearm": (10, 50),
+        "r_hand": (0, 25), "chest": (0, 4), "head": (0, -6),
+    },
+    "nod": {"head": (0, 14)},
+    "bounce": {"hip": (0, 6), "spine": (-2, 2), "l_upper_arm": (6, -6), "r_upper_arm": (-6, 6)},
+}
+
+EASE_IN_OUT = lambda t: t * t * (3 - 2 * t)  # smoothstep
+
+
+def svg_group(bone: str, children_svg: str, pivot: str, shape: str) -> str:
+    """Wrap a bone in a <g> with data-bone attribute and transform-origin pivot."""
+    return (
+        f'<g data-bone="{bone}" style="transform-origin:{pivot}" '
+        f'transform="rotate({DEFAULT_POSE[bone]:.1f} 0 0)">{shape}{children_svg}</g>'
+    )
+
+
+def build_rig(args) -> str:
+    if not args.input:
+        if not args.allow_placeholder:
+            raise SystemExit("error: --input authoritative SVG is required; use --allow-placeholder only for local prototyping")
+        flat = _default_avatar_svg()
+    elif not Path(args.input).exists():
+        raise SystemExit(f"error: SVG asset not found: {args.input}")
+    else:
+        flat = Path(args.input).read_text(encoding="utf-8")
+
+    # Prefer explicit data-part names; positional assignment is only a
+    # compatibility fallback for legacy source art without names.
+    parts = _split_svg_parts(flat)
+    assigned = {name: shape for name, shape in parts if name}
+    if not assigned:
+        assigned = dict(zip(BONES, [shape for _, shape in parts]))
+
+    def hierarchy(bone: str) -> str:
+        kids = {
+            "hip": ["spine", "l_hip", "r_hip"],
+            "spine": ["chest"],
+            "chest": ["head", "l_shoulder", "r_shoulder"],
+            "l_shoulder": ["l_upper_arm"], "l_upper_arm": ["l_forearm"], "l_forearm": ["l_hand"],
+            "r_shoulder": ["r_upper_arm"], "r_upper_arm": ["r_forearm"], "r_forearm": ["r_hand"],
+            "l_hip": ["l_thigh"], "l_thigh": ["l_shin"], "l_shin": ["l_foot"],
+            "r_hip": ["r_thigh"], "r_thigh": ["r_shin"], "r_shin": ["r_foot"],
+        }
+        children = "".join(hierarchy(c) for c in kids.get(bone, []))
+        shape = assigned.get(bone, "")
+        pivot = f"{args.pivot_x}px {args.pivot_y}px"
+        return svg_group(bone, children, pivot, shape)
+
+    inner = hierarchy("hip")
+    doc = flat if "<g data-bone=" in flat else f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {args.width} {args.height}">
+<g id="rig" data-rig="cutout-v1">{inner}</g></svg>'''
+    out = Path(args.output)
+    out.write_text(doc, encoding="utf-8")
+    print(f"rigged avatar written -> {out} ({len(BONES)} bones)")
+    return str(out)
+
+
+def _split_svg_parts(svg_text: str) -> list:
+    """Extract `(data-part, SVG fragment)` without changing the source geometry."""
+    named = []
+    # Covers self-closing primitives and named groups. It intentionally does
+    # not claim arbitrary unlabelled nested geometry as a body part.
+    pattern = re.compile(
+        r'(<g\b[^>]*data-part=["\']([^"\']+)["\'][^>]*>.*?</g>|'
+        r'<(?:path|circle|ellipse|rect|polygon)\b[^>]*data-part=["\']([^"\']+)["\'][^>]*/>)',
+        re.S,
+    )
+    for match in pattern.finditer(svg_text):
+        named.append((match.group(2) or match.group(3), match.group(1)))
+    if named:
+        return named
+    legacy = re.findall(
+        r'(<g\b[^>]*>.*?</g>|<(?:path|circle|ellipse|rect|polygon)\b[^>]*/>)',
+        svg_text,
+        re.S,
+    )
+    return [(None, fragment) for fragment in legacy]
+
+
+def _default_avatar_svg() -> str:
+    return f"""<!-- cutout avatar base — replace with authoritative art from assets/library/ -->
+<circle data-part="head" cx="250" cy="90" r="42" fill="#2d2d3a"/>
+<rect data-part="chest" x="208" y="140" width="84" height="96" rx="22" fill="#2d2d3a"/>
+<rect data-part="l_upper_arm" x="178" y="148" width="26" height="78" rx="13" fill="#45455a"/>
+<rect data-part="r_upper_arm" x="296" y="148" width="26" height="78" rx="13" fill="#45455a"/>
+<rect data-part="l_forearm" x="176" y="228" width="22" height="70" rx="11" fill="#45455a"/>
+<rect data-part="r_forearm" x="302" y="228" width="22" height="70" rx="11" fill="#45455a"/>
+<rect data-part="l_thigh" x="216" y="238" width="30" height="84" rx="15" fill="#37374a"/>
+<rect data-part="r_thigh" x="254" y="238" width="30" height="84" rx="15" fill="#37374a"/>
+<rect data-part="l_shin" x="218" y="324" width="26" height="80" rx="13" fill="#37374a"/>
+<rect data-part="r_shin" x="256" y="324" width="26" height="80" rx="13" fill="#37374a"/>
+<ellipse data-part="l_foot" cx="231" cy="408" rx="24" ry="10" fill="#1f1f2e"/>
+<ellipse data-part="r_foot" cx="269" cy="408" rx="24" ry="10" fill="#1f1f2e"/>"""
+
+
+def pose(args) -> dict:
+    rig = Path(args.rig).read_text(encoding="utf-8")
+    clip = CLIPS.get(args.pose) or _parse_clip_file(args.pose)
+    fps = args.fps or 30
+    duration = args.duration or 1.5
+    frames = max(2, round(duration * fps))
+
+    keyframes = []
+    for i in range(frames):
+        t = EASE_IN_OUT(i / (frames - 1)) if frames > 1 else 0
+        # ping-pong: forward half then back
+        tt = 1 - abs(1 - 2 * (i / max(1, frames - 1)))
+        pose_frame = dict(DEFAULT_POSE)
+        for bone, (a, b) in clip.items():
+            pose_frame[bone] = DEFAULT_POSE.get(bone, 0) + (a + (b - a) * tt)
+        keyframes.append({"frame": i, "time_s": round(i / fps, 3), "angles": pose_frame})
+
+    out = Path(args.out)
+    out.write_text(json.dumps({
+        "rig": str(args.rig), "clip": args.pose, "fps": fps,
+        "duration_s": duration, "frames": len(keyframes), "keyframes": keyframes,
+    }, indent=2) + "\n", encoding="utf-8")
+    print(f"pose clip written -> {out} ({len(keyframes)} frames)")
+    return {"file": str(out), "frames": len(keyframes)}
+
+
+def _parse_clip_file(path: str) -> dict:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="cmd")
+    b = sub.add_parser("build")
+    b.add_argument("--input")
+    b.add_argument("--output", default="rigged-avatar.svg")
+    b.add_argument("--pivot-x", default=0)
+    b.add_argument("--pivot-y", default=0)
+    b.add_argument("--width", default=500)
+    b.add_argument("--height", default=450)
+    p = sub.add_parser("pose")
+    p.add_argument("rig")
+    p.add_argument("--pose", required=True)
+    p.add_argument("--duration", type=float)
+    p.add_argument("--fps", type=int)
+    p.add_argument("--out", default="clip.json")
+    b.add_argument("--allow-placeholder", action="store_true", help="allow generated geometric avatar for local prototyping only")
+    args = parser.parse_args()
+    if args.cmd == "build":
+        build_rig(args)
+    elif args.cmd == "pose":
+        pose(args)
+
+
+if __name__ == "__main__":
+    main()