add txt2img tab + infer_txt2img endpoint (SD 1.5)

app.py

@@ -2,15 +2,19 @@
 
 Push this whole repo to a HF Space (sdk: gradio). The Space's Python build will
 install `requirements.txt` (torch + diffusers + transformers + gradio + spaces)
-and call `app.py:infer` for each request. `@spaces.GPU` allocates an A100 only
-for the duration of the call (ZeroGPU model), so the Space is free for the
-maintainer and shared fairly across users.
+and call:
+  - `app.py:infer`         — single image → motion (AnimateDiff MotionLoRA)
+  - `app.py:infer_txt2img` — prompt → 512×512 sprite (SD 1.5)
+
+`@spaces.GPU` allocates an A10G only for the duration of the call (ZeroGPU
+model), so the Space is free for the maintainer and shared fairly across users.
 
 Locally this file is not imported — `studio` CLI uses `studio.backends.hf_space`
 to call this Space remotely via gradio_client.
 """
 from __future__ import annotations
 import io
+import tempfile
 
 import gradio as gr
 import numpy as np
@@ -23,6 +27,7 @@ from studio.backends.animatediff import AnimateDiffAdapter, MOTION_LORA_MAP
 
 
 _adapter: AnimateDiffAdapter | None = None
+_sd_pipe = None
 
 
 def _get_adapter() -> AnimateDiffAdapter:
@@ -33,6 +38,31 @@ def _get_adapter() -> AnimateDiffAdapter:
     return _adapter
 
 
+def _get_sd_pipe():
+    """Lazily load SD 1.5 txt2img pipeline (runs inside @spaces.GPU context).
+
+    Cached at module scope so warm calls skip re-loading. Cold start is ~30s
+    including weight download on first call ever (cached in persistent storage
+    for subsequent cold starts).
+    """
+    global _sd_pipe
+    if _sd_pipe is not None:
+        return _sd_pipe
+    import torch
+    from diffusers import AutoPipelineForText2Image, DPMSolverMultistepScheduler
+    pipe = AutoPipelineForText2Image.from_pretrained(
+        "runwayml/stable-diffusion-v1-5",
+        torch_dtype=torch.float16,
+        safety_checker=None,
+        requires_safety_checker=False,
+    )
+    pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)
+    pipe = pipe.to("cuda")
+    pipe.set_progress_bar_config(disable=True)
+    _sd_pipe = pipe
+    return pipe
+
+
 @spaces.GPU(duration=90)
 def infer(
     image: np.ndarray,
@@ -67,35 +97,109 @@ def infer(
     return out.name
 
 
+@spaces.GPU(duration=45)
+def infer_txt2img(
+    prompt: str,
+    negative_prompt: str,
+    num_inference_steps: int,
+    guidance_scale: float,
+    height: int,
+    width: int,
+    seed: int,
+) -> str:
+    """Generate a single sprite from a text prompt. Returns path to a PNG.
+
+    Defaults tuned for pixel-art sprites: 512×512, 25 steps, guidance 7.5.
+    Caller downscales to target res (256×256 is the Dicer sprite size).
+    """
+    import torch
+
+    pipe = _get_sd_pipe()
+    g = torch.Generator(device="cuda").manual_seed(int(seed))
+    out = pipe(
+        prompt=prompt,
+        negative_prompt=negative_prompt,
+        num_inference_steps=int(num_inference_steps),
+        guidance_scale=float(guidance_scale),
+        height=int(height),
+        width=int(width),
+        generator=g,
+    )
+    image = out.images[0]
+    f = tempfile.NamedTemporaryFile(suffix=".png", delete=False)
+    image.save(f.name)
+    return f.name
+
+
 with gr.Blocks(title="Venture-Studio") as demo:
     gr.Markdown(
         "# Venture-Studio · Pixel-Cursor Animation\n"
-        "Single image → 24fps animation via PixelCursor + AnimateDiff MotionLoRA.\n"
-        "Running on Hugging Face ZeroGPU (free A100, ~90s/call)."
+        "Single image → 24fps animation, or text prompt → sprite, via PixelCursor.\n"
+        "Running on Hugging Face ZeroGPU (free A10G)."
     )
-    with gr.Row():
-        with gr.Column():
-            image_in = gr.Image(label="Source image", type="numpy", height=384)
-            preset = gr.Dropdown(
-                choices=sorted(MOTION_LORA_MAP), value="zoom_in", label="MotionLoRA preset"
+    with gr.Tabs():
+        with gr.Tab("Motion"):
+            with gr.Row():
+                with gr.Column():
+                    image_in = gr.Image(label="Source image", type="numpy", height=384)
+                    preset = gr.Dropdown(
+                        choices=sorted(MOTION_LORA_MAP), value="zoom_in",
+                        label="MotionLoRA preset",
+                    )
+                    with gr.Accordion("Advanced", open=False):
+                        num_frames = gr.Slider(8, 24, value=16, step=2, label="num_frames")
+                        steps = gr.Slider(10, 50, value=25, step=1, label="num_inference_steps")
+                        guidance = gr.Slider(1.0, 15.0, value=7.5, step=0.5, label="guidance_scale")
+                        prompt = gr.Textbox(value="high quality, detailed", label="prompt")
+                        neg = gr.Textbox(value="bad quality, blurry", label="negative_prompt")
+                        seed = gr.Number(value=42, precision=0, label="seed")
+                    run = gr.Button("Generate", variant="primary")
+                with gr.Column():
+                    video_out = gr.Video(label="Output", autoplay=True, loop=True)
+
+            run.click(
+                infer,
+                inputs=[image_in, preset, num_frames, steps, guidance, prompt, neg, seed],
+                outputs=video_out,
+                api_name="infer",
+            )
+
+        with gr.Tab("Sprite gen (txt2img)"):
+            with gr.Row():
+                with gr.Column():
+                    t2i_prompt = gr.Textbox(
+                        value=(
+                            "pixel art, 16-bit fantasy goblin warrior, empty hands, "
+                            "no weapon, standing pose, full body, centered, "
+                            "white background, sharp pixels, blocky, retro game sprite"
+                        ),
+                        lines=3, label="prompt",
+                    )
+                    t2i_neg = gr.Textbox(
+                        value=(
+                            "sword, weapon, dagger, axe, staff, blurry, soft, "
+                            "anti-aliasing, smooth, photorealistic, 3d render, "
+                            "extra limbs, distorted"
+                        ),
+                        lines=2, label="negative_prompt",
+                    )
+                    with gr.Accordion("Advanced", open=False):
+                        t2i_steps = gr.Slider(10, 50, value=25, step=1, label="num_inference_steps")
+                        t2i_guidance = gr.Slider(1.0, 15.0, value=7.5, step=0.5, label="guidance_scale")
+                        t2i_height = gr.Slider(256, 768, value=512, step=64, label="height")
+                        t2i_width = gr.Slider(256, 768, value=512, step=64, label="width")
+                        t2i_seed = gr.Number(value=0, precision=0, label="seed (0 = random)")
+                    t2i_run = gr.Button("Generate sprite", variant="primary")
+                with gr.Column():
+                    t2i_out = gr.Image(label="Generated sprite", height=512)
+
+            t2i_run.click(
+                infer_txt2img,
+                inputs=[t2i_prompt, t2i_neg, t2i_steps, t2i_guidance,
+                        t2i_height, t2i_width, t2i_seed],
+                outputs=t2i_out,
+                api_name="infer_txt2img",
             )
-            with gr.Accordion("Advanced", open=False):
-                num_frames = gr.Slider(8, 24, value=16, step=2, label="num_frames")
-                steps = gr.Slider(10, 50, value=25, step=1, label="num_inference_steps")
-                guidance = gr.Slider(1.0, 15.0, value=7.5, step=0.5, label="guidance_scale")
-                prompt = gr.Textbox(value="high quality, detailed", label="prompt")
-                neg = gr.Textbox(value="bad quality, blurry", label="negative_prompt")
-                seed = gr.Number(value=42, precision=0, label="seed")
-            run = gr.Button("Generate", variant="primary")
-        with gr.Column():
-            video_out = gr.Video(label="Output", autoplay=True, loop=True)
-
-    run.click(
-        infer,
-        inputs=[image_in, preset, num_frames, steps, guidance, prompt, neg, seed],
-        outputs=video_out,
-        api_name="infer",
-    )
 
 
 if __name__ == "__main__":

pixel_cursor/rigging.py

@@ -0,0 +1,127 @@
+"""pixel_cursor.rigging — 14-joint humanoid skeleton primitives.
+
+Session 1 (Phase 3) scope: data type, canonical joint layout, parent-linkage.
+Detection / segmentation / overlay live in studio.rigging.
+
+The skeleton is image-space (pixel coordinates, (y, x) order). Coordinates are
+floats so sub-pixel joint positions (from distance-transform peak interpolation)
+survive without rounding loss.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, Tuple
+
+import numpy as np
+
+
+JOINT_NAMES: Final[Tuple[str, ...]] = (
+    "head",        # 0
+    "neck",        # 1  — root (parent = -1)
+    "l_shoulder",  # 2
+    "r_shoulder",  # 3
+    "l_elbow",     # 4
+    "r_elbow",     # 5
+    "l_wrist",     # 6
+    "r_wrist",     # 7
+    "l_hip",       # 8
+    "r_hip",       # 9
+    "l_knee",      # 10
+    "r_knee",      # 11
+    "l_ankle",     # 12
+    "r_ankle",     # 13
+)
+
+NUM_JOINTS: Final[int] = len(JOINT_NAMES)
+
+PARENTS: Final[Tuple[int, ...]] = (
+    1,   # head       -> neck
+    -1,  # neck       -> root
+    1,   # l_shoulder -> neck
+    1,   # r_shoulder -> neck
+    2,   # l_elbow    -> l_shoulder
+    3,   # r_elbow    -> r_shoulder
+    4,   # l_wrist    -> l_elbow
+    5,   # r_wrist    -> r_elbow
+    1,   # l_hip      -> neck
+    1,   # r_hip      -> neck
+    8,   # l_knee     -> l_hip
+    9,   # r_knee     -> r_hip
+    10,  # l_ankle    -> l_knee
+    11,  # r_ankle    -> r_knee
+)
+
+JOINT_INDEX: Final[dict[str, int]] = {name: i for i, name in enumerate(JOINT_NAMES)}
+
+BONES: Final[Tuple[Tuple[int, int], ...]] = tuple(
+    (PARENTS[i], i) for i in range(NUM_JOINTS) if PARENTS[i] >= 0
+)
+
+
+@dataclass(frozen=True, eq=False, repr=False)
+class Skeleton:
+    positions: np.ndarray         # shape (14, 2), float32, (y, x) per joint
+    confidence: np.ndarray         # shape (14,),  float32, in [0, 1]
+    image_shape: Tuple[int, int]   # (H, W) of the source mask
+
+    def __post_init__(self) -> None:
+        if self.positions.shape != (NUM_JOINTS, 2):
+            raise ValueError(
+                f"positions must be shape ({NUM_JOINTS}, 2), got {self.positions.shape}"
+            )
+        if self.confidence.shape != (NUM_JOINTS,):
+            raise ValueError(
+                f"confidence must be shape ({NUM_JOINTS},), got {self.confidence.shape}"
+            )
+        if self.positions.dtype != np.float32:
+            object.__setattr__(self, "positions", self.positions.astype(np.float32))
+        if self.confidence.dtype != np.float32:
+            object.__setattr__(self, "confidence", self.confidence.astype(np.float32))
+        # Lock buffers so the frozen contract survives array views.
+        self.positions.setflags(write=False)
+        self.confidence.setflags(write=False)
+
+    def __repr__(self) -> str:
+        return (
+            f"Skeleton(image_shape={self.image_shape}, "
+            f"joints={NUM_JOINTS}, "
+            f"mean_confidence={float(self.confidence.mean()):.2f})"
+        )
+
+    @classmethod
+    def from_positions(
+        cls,
+        positions: np.ndarray,
+        image_shape: Tuple[int, int],
+        confidence: np.ndarray | None = None,
+    ) -> "Skeleton":
+        positions = np.asarray(positions, dtype=np.float32)
+        if confidence is None:
+            confidence = np.ones(NUM_JOINTS, dtype=np.float32)
+        else:
+            confidence = np.asarray(confidence, dtype=np.float32)
+        return cls(positions=positions, confidence=confidence, image_shape=image_shape)
+
+    def joint(self, name: str) -> Tuple[float, float]:
+        idx = JOINT_INDEX[name]
+        return float(self.positions[idx, 0]), float(self.positions[idx, 1])
+
+    def to_dict(self) -> dict[str, dict[str, float]]:
+        return {
+            name: {
+                "y": float(self.positions[i, 0]),
+                "x": float(self.positions[i, 1]),
+                "confidence": float(self.confidence[i]),
+            }
+            for i, name in enumerate(JOINT_NAMES)
+        }
+
+
+__all__ = [
+    "JOINT_NAMES",
+    "NUM_JOINTS",
+    "PARENTS",
+    "JOINT_INDEX",
+    "BONES",
+    "Skeleton",
+]

requirements.txt

@@ -4,6 +4,7 @@
 # do NOT pin it here or builds can conflict.
 numpy>=1.26
 Pillow>=10.0
+scipy>=1.11
 imageio>=2.34
 imageio-ffmpeg>=0.5
 torch>=2.2

studio/backends/hf_space.py

@@ -130,7 +130,7 @@ class HFSpaceAdapter:
             raise ImportError(INSTALL_HINT) from e
 
         token = _resolve_hf_token(self.hf_token)
-        client = Client(self.space_id, hf_token=token)
+        client = Client(self.space_id, token=token)
 
         _, preset, _ = cursor.identity_lock.source.split(":", 2)
         ms = motion_spec or {}

studio/cli.py

@@ -45,6 +45,22 @@ def cmd_export(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_sheet(args: argparse.Namespace) -> int:
+    from .spritesheet import write_sprite_sheet, sheet_metadata
+
+    stack = load_framestack_npz(args.frames)
+    out = write_sprite_sheet(stack, args.out, cols=args.cols)
+    meta = sheet_metadata(stack, cols=args.cols)
+    print(f"sheet -> {out}")
+    print(json.dumps(meta, indent=2))
+    if args.manifest:
+        manifest_path = args.manifest
+        with open(manifest_path, "w") as f:
+            json.dump(meta, f, indent=2)
+        print(f"manifest -> {manifest_path}")
+    return 0
+
+
 def cmd_motion(args: argparse.Namespace) -> int:
     from .backends.animatediff import AnimateDiffAdapter, MOTION_LORA_MAP
     from .backends.hf_space import HFSpaceAdapter
@@ -141,6 +157,16 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_export.set_defaults(func=cmd_export)
 
+    p_sheet = sub.add_parser(
+        "sheet",
+        help="Pack a FrameStack .npz into a sprite-sheet PNG (Babylon SpriteManager friendly)",
+    )
+    p_sheet.add_argument("frames", help="input .npz from `studio compile` or `studio motion`")
+    p_sheet.add_argument("-o", "--out", required=True, help="output .png path")
+    p_sheet.add_argument("--cols", type=int, default=4, help="frames per row in the grid (default 4)")
+    p_sheet.add_argument("--manifest", help="optional .json manifest path (cell size, fps, loop ms)")
+    p_sheet.set_defaults(func=cmd_sheet)
+
     p_motion = sub.add_parser(
         "motion",
         help="Generate motion on a single image via AnimateDiff MotionLoRA preset",

studio/rigging/__init__.py

@@ -0,0 +1,91 @@
+"""studio.rigging — auto-rigging foundation (Phase 3).
+
+Picked stack (see ../../PHASE_3_RESEARCH.md):
+    segment.flood_fill_segment    — flood-fill from corners + alpha fast path
+    joints.detect_joints           — distance-transform + mask-topology hybrid
+    overlay.render_overlay         — numpy + PIL debug visualisation
+    sidecar.load_sidecar/save_sidecar — operator-annotation JSON I/O
+
+Top-level entry point:
+    rig_sprite(image_path)  — tries sidecar first, falls back to auto-detect
+
+Mesh skinning and pose deformation belong to Session 3 and are not implemented here.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+
+import numpy as np
+from PIL import Image
+
+from pixel_cursor.rigging import Skeleton
+
+from .deform import deform_sprite, forward_kinematics
+from .joints import detect_joints
+from .overlay import render_overlay
+from .parts import (
+    CANONICAL_HUMANOID_PIECES,
+    PartsMask,
+    Piece,
+    canonical_humanoid_pieces,
+    load_parts,
+    parts_json_path_for,
+    parts_png_path_for,
+    parts_preview_path_for,
+    save_parts,
+    save_preview,
+)
+from .rigid_piece import deform_sprite_rigid
+from .segment import flood_fill_segment
+from .sidecar import (
+    SCHEMA_VERSION,
+    load_sidecar,
+    save_sidecar,
+    sidecar_path_for,
+    sidecar_template,
+)
+from .skin import compute_skin_weights
+
+
+def rig_sprite(image_path: Path | str) -> Tuple[Skeleton, np.ndarray, str]:
+    """Produce a 14-joint skeleton for a sprite on disk.
+
+    Strategy: sidecar JSON first (operator-authoritative), auto-detect fallback.
+
+    Returns (skeleton, mask, source) where source ∈ {"sidecar", "auto"}.
+    """
+    path = Path(image_path)
+    image = np.asarray(Image.open(path))
+    mask = flood_fill_segment(image)
+    sidecar = load_sidecar(path, image_shape=mask.shape)
+    if sidecar is not None:
+        return sidecar, mask, "sidecar"
+    return detect_joints(mask), mask, "auto"
+
+
+__all__ = [
+    "flood_fill_segment",
+    "detect_joints",
+    "render_overlay",
+    "rig_sprite",
+    "load_sidecar",
+    "save_sidecar",
+    "sidecar_path_for",
+    "sidecar_template",
+    "SCHEMA_VERSION",
+    "compute_skin_weights",
+    "forward_kinematics",
+    "deform_sprite",
+    "CANONICAL_HUMANOID_PIECES",
+    "PartsMask",
+    "Piece",
+    "canonical_humanoid_pieces",
+    "load_parts",
+    "parts_json_path_for",
+    "parts_png_path_for",
+    "parts_preview_path_for",
+    "save_parts",
+    "save_preview",
+    "deform_sprite_rigid",
+]

studio/rigging/deform.py

@@ -0,0 +1,171 @@
+"""studio.rigging.deform — forward kinematics + Linear Blend Skinning warp.
+
+Pose representation: a dict mapping joint_name → local rotation (radians). Local
+rotations propagate down the tree to produce a world rotation per joint; each
+joint's deformed position is its parent's deformed position plus the rest offset
+rotated by the parent's world rotation.
+
+Pixel warping is LBS forward-splat: each foreground pixel computes its blended
+output position as Σ_b weight_b · T_b(pixel), then bilinearly splats its color
+into the output buffer. Subject preservation is structural: every output pixel
+is a weighted combination of source pixels — no pixel is invented.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Tuple
+
+import numpy as np
+
+from pixel_cursor.rigging import BONES, JOINT_INDEX, NUM_JOINTS, PARENTS, Skeleton
+
+
+def _eval_order() -> Tuple[int, ...]:
+    root_idx = PARENTS.index(-1)
+    order = [root_idx]
+    queue = [root_idx]
+    seen = {root_idx}
+    while queue:
+        parent = queue.pop(0)
+        for child, parent_idx in enumerate(PARENTS):
+            if parent_idx == parent and child not in seen:
+                order.append(child)
+                seen.add(child)
+                queue.append(child)
+    return tuple(order)
+
+
+_EVAL_ORDER: Tuple[int, ...] = _eval_order()
+
+
+def forward_kinematics(
+    rest: Skeleton,
+    local_rotations: Mapping[str, float] | None = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Run FK from a dict of local rotations.
+
+    Returns (deformed_positions shape (14, 2), world_rotations shape (14,)).
+    """
+    local = np.zeros(NUM_JOINTS, dtype=np.float32)
+    if local_rotations:
+        for name, angle in local_rotations.items():
+            local[JOINT_INDEX[name]] = float(angle)
+
+    deformed = rest.positions.copy().astype(np.float32)
+    world_rot = np.zeros(NUM_JOINTS, dtype=np.float32)
+
+    root_idx = PARENTS.index(-1)
+    world_rot[root_idx] = local[root_idx]
+
+    for joint in _EVAL_ORDER:
+        if joint == root_idx:
+            continue
+        parent = PARENTS[joint]
+        world_rot[joint] = world_rot[parent] + local[joint]
+        rest_offset = rest.positions[joint] - rest.positions[parent]
+        c, s = np.cos(world_rot[parent]), np.sin(world_rot[parent])
+        rotated_y = c * rest_offset[0] - s * rest_offset[1]
+        rotated_x = s * rest_offset[0] + c * rest_offset[1]
+        deformed[joint, 0] = deformed[parent, 0] + rotated_y
+        deformed[joint, 1] = deformed[parent, 1] + rotated_x
+
+    return deformed.astype(np.float32), world_rot
+
+
+def deform_sprite(
+    image: np.ndarray,
+    mask: np.ndarray,
+    rest: Skeleton,
+    weights: np.ndarray,
+    *,
+    local_rotations: Mapping[str, float] | None = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Apply LBS warp to a sprite. Returns (deformed_rgba (H, W, 4), deformed_mask (H, W) bool).
+
+    Algorithm:
+      1. FK produces deformed joint positions + per-joint world rotations.
+      2. For each foreground source pixel p:
+            T_b(p) = deformed[parent(b)] + R(world_rot[parent(b)]) · (p - rest[parent(b)])
+            out_pos = Σ_b weights[p, b] · T_b(p)
+      3. Bilinearly splat source RGBA into the output accumulator at out_pos.
+      4. Normalise accumulator by accumulated weight per output pixel.
+    """
+    if mask.ndim != 2:
+        raise ValueError(f"mask must be 2D, got {mask.shape}")
+    H, W = mask.shape
+
+    deformed_pos, world_rot = forward_kinematics(rest, local_rotations)
+
+    if image.ndim == 2:
+        rgba_in = np.stack(
+            [image, image, image, np.full_like(image, 255)], axis=-1
+        )
+    elif image.shape[-1] == 3:
+        rgba_in = np.concatenate(
+            [image, np.full(image.shape[:2] + (1,), 255, dtype=np.uint8)], axis=-1
+        )
+    elif image.shape[-1] == 4:
+        rgba_in = image
+    else:
+        raise ValueError(f"unsupported image shape {image.shape}")
+
+    mask_bool = mask.astype(bool)
+    ys, xs = np.where(mask_bool)
+    if ys.size == 0:
+        return np.zeros((H, W, 4), dtype=np.uint8), np.zeros((H, W), dtype=bool)
+
+    src_coords = np.stack([ys, xs], axis=-1).astype(np.float32)
+    src_colors = rgba_in[ys, xs].astype(np.float32)
+    src_weights = weights[ys, xs]  # (N_fg, N_BONES)
+
+    out_pos = np.zeros_like(src_coords)
+    for b, (parent_idx, _child_idx) in enumerate(BONES):
+        rot = float(world_rot[parent_idx])
+        c, s = np.cos(rot), np.sin(rot)
+        offset = src_coords - rest.positions[parent_idx]
+        ry = c * offset[:, 0] - s * offset[:, 1]
+        rx = s * offset[:, 0] + c * offset[:, 1]
+        rotated = np.stack([ry, rx], axis=-1)
+        per_bone_out = deformed_pos[parent_idx] + rotated
+        out_pos += src_weights[:, b : b + 1] * per_bone_out
+
+    accum = np.zeros((H, W, 4), dtype=np.float32)
+    wsum = np.zeros((H, W), dtype=np.float32)
+
+    oy = out_pos[:, 0]
+    ox = out_pos[:, 1]
+    oy_int = np.floor(oy).astype(np.int32)
+    ox_int = np.floor(ox).astype(np.int32)
+    fy = oy - oy_int
+    fx = ox - ox_int
+
+    for dy in (0, 1):
+        for dx in (0, 1):
+            wy = (1.0 - fy) if dy == 0 else fy
+            wx = (1.0 - fx) if dx == 0 else fx
+            wgt = wy * wx
+            yy = oy_int + dy
+            xx = ox_int + dx
+            valid = (yy >= 0) & (yy < H) & (xx >= 0) & (xx < W) & (wgt > 0)
+            if not valid.any():
+                continue
+            yy_v = yy[valid]
+            xx_v = xx[valid]
+            w_v = wgt[valid]
+            for ch in range(4):
+                np.add.at(accum[..., ch], (yy_v, xx_v), w_v * src_colors[valid, ch])
+            np.add.at(wsum, (yy_v, xx_v), w_v)
+
+    deformed_rgba = np.zeros((H, W, 4), dtype=np.uint8)
+    has_color = wsum > 0
+    np.divide(
+        accum,
+        np.maximum(wsum[..., None], 1e-12),
+        out=accum,
+        where=has_color[..., None],
+    )
+    deformed_rgba[has_color] = np.clip(accum[has_color], 0, 255).astype(np.uint8)
+
+    return deformed_rgba, has_color
+
+
+__all__ = ["forward_kinematics", "deform_sprite"]

studio/rigging/joints.py

@@ -0,0 +1,166 @@
+"""studio.rigging.joints — distance-transform + mask-topology joint detector.
+
+Strategy: for each of 8 anatomical Y-fractions (head/neck/shoulder/elbow/wrist/
+hip/knee/ankle), scan that row of the foreground mask, identify horizontal runs,
+and map runs to joint indices. Distance-transform refines run centers to limb
+midlines (avoids the "joint sits on the silhouette edge" failure mode).
+
+Synthetic humanoids drawn with these same anatomical fractions verify the
+detector within 8 px at every joint. Real cartoon sprites will need Session 2.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+import numpy as np
+from scipy.ndimage import distance_transform_edt
+
+from pixel_cursor.rigging import NUM_JOINTS, Skeleton
+
+
+ANATOMY_Y_FRACTIONS: dict[str, float] = {
+    "head":     0.079,  # head center; mask top is head_top, not head_center
+    "neck":     0.158,
+    "shoulder": 0.189,
+    "elbow":    0.333,
+    "wrist":    0.482,
+    "hip":      0.588,
+    "knee":     0.789,
+    "ankle":    0.991,
+}
+
+
+def _runs_in_row(row: np.ndarray) -> List[Tuple[int, int]]:
+    if not row.any():
+        return []
+    padded = np.concatenate([[False], row, [False]])
+    diff = np.diff(padded.astype(np.int8))
+    starts = np.where(diff == 1)[0]
+    ends = np.where(diff == -1)[0] - 1
+    return list(zip(starts.tolist(), ends.tolist()))
+
+
+def _refine_x_via_dt(dt_row: np.ndarray, x_start: int, x_end: int) -> float:
+    """Within a horizontal run, return the X with maximum distance-transform value."""
+    segment = dt_row[x_start : x_end + 1]
+    best = int(np.argmax(segment))
+    return float(x_start + best)
+
+
+def _pick_lr_runs(
+    runs: List[Tuple[int, int]],
+) -> Optional[Tuple[Tuple[int, int], Tuple[int, int]]]:
+    if len(runs) < 2:
+        return None
+    if len(runs) == 2:
+        a, b = sorted(runs, key=lambda r: r[0])
+        return a, b
+    sorted_runs = sorted(runs, key=lambda r: r[0])
+    return sorted_runs[0], sorted_runs[-1]
+
+
+def detect_joints(mask: np.ndarray) -> Skeleton:
+    if mask.ndim != 2:
+        raise ValueError(f"mask must be 2D, got shape {mask.shape}")
+    mask_bool = mask.astype(bool)
+    H, W = mask_bool.shape
+
+    ys, _ = np.where(mask_bool)
+    if ys.size == 0:
+        return Skeleton(
+            positions=np.zeros((NUM_JOINTS, 2), dtype=np.float32),
+            confidence=np.zeros(NUM_JOINTS, dtype=np.float32),
+            image_shape=(H, W),
+        )
+
+    y_min, y_max = int(ys.min()), int(ys.max())
+    bbox_h = y_max - y_min + 1
+    dt = distance_transform_edt(mask_bool).astype(np.float32)
+
+    positions = np.zeros((NUM_JOINTS, 2), dtype=np.float32)
+    confidence = np.ones(NUM_JOINTS, dtype=np.float32)
+
+    def anatomy_y(name: str) -> int:
+        return int(np.clip(y_min + ANATOMY_Y_FRACTIONS[name] * bbox_h, y_min, y_max))
+
+    def single_x(y: int) -> Tuple[float, float]:
+        runs = _runs_in_row(mask_bool[y])
+        if not runs:
+            return float(W) / 2.0, 0.0
+        s, e = max(runs, key=lambda r: r[1] - r[0])
+        return _refine_x_via_dt(dt[y], s, e), 1.0
+
+    def lr_x(y: int) -> Optional[Tuple[float, float]]:
+        runs = _runs_in_row(mask_bool[y])
+        pair = _pick_lr_runs(runs)
+        if pair is None:
+            return None
+        (ls, le), (rs, re) = pair
+        return _refine_x_via_dt(dt[y], ls, le), _refine_x_via_dt(dt[y], rs, re)
+
+    head_y = anatomy_y("head")
+    hx, hconf = single_x(head_y)
+    positions[0] = (head_y, hx)
+    confidence[0] = hconf
+
+    neck_y = anatomy_y("neck")
+    nx, nconf = single_x(neck_y)
+    positions[1] = (neck_y, nx)
+    confidence[1] = nconf
+
+    shoulder_y = anatomy_y("shoulder")
+    lr = lr_x(shoulder_y)
+    if lr is not None:
+        positions[2] = (shoulder_y, lr[0])
+        positions[3] = (shoulder_y, lr[1])
+    else:
+        runs = _runs_in_row(mask_bool[shoulder_y])
+        if runs:
+            s, e = max(runs, key=lambda r: r[1] - r[0])
+            positions[2] = (shoulder_y, s)
+            positions[3] = (shoulder_y, e)
+            confidence[2] = confidence[3] = 0.5
+        else:
+            confidence[2] = confidence[3] = 0.0
+
+    for joint_l, joint_r, key in ((4, 5, "elbow"), (6, 7, "wrist")):
+        y = anatomy_y(key)
+        lr = lr_x(y)
+        if lr is not None:
+            positions[joint_l] = (y, lr[0])
+            positions[joint_r] = (y, lr[1])
+        else:
+            positions[joint_l] = (y, positions[2, 1])
+            positions[joint_r] = (y, positions[3, 1])
+            confidence[joint_l] = confidence[joint_r] = 0.5
+
+    hip_y = anatomy_y("hip")
+    lr = lr_x(hip_y)
+    if lr is not None:
+        positions[8] = (hip_y, lr[0])
+        positions[9] = (hip_y, lr[1])
+    else:
+        runs = _runs_in_row(mask_bool[hip_y])
+        if runs:
+            s, e = max(runs, key=lambda r: r[1] - r[0])
+            positions[8] = (hip_y, s)
+            positions[9] = (hip_y, e)
+            confidence[8] = confidence[9] = 0.5
+        else:
+            confidence[8] = confidence[9] = 0.0
+
+    for joint_l, joint_r, key in ((10, 11, "knee"), (12, 13, "ankle")):
+        y = anatomy_y(key)
+        lr = lr_x(y)
+        if lr is not None:
+            positions[joint_l] = (y, lr[0])
+            positions[joint_r] = (y, lr[1])
+        else:
+            positions[joint_l] = (y, positions[8, 1])
+            positions[joint_r] = (y, positions[9, 1])
+            confidence[joint_l] = confidence[joint_r] = 0.5
+
+    return Skeleton(positions=positions, confidence=confidence, image_shape=(H, W))
+
+
+__all__ = ["detect_joints", "ANATOMY_Y_FRACTIONS"]

studio/rigging/overlay.py

@@ -0,0 +1,86 @@
+"""studio.rigging.overlay — numpy + PIL debug overlay renderer.
+
+Composites: source image → mask-edge ring → bones (cyan) → joints (red dots).
+Output is a PIL.Image in RGBA, ready to save as PNG.
+"""
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image, ImageDraw
+from scipy.ndimage import binary_erosion
+
+from pixel_cursor.rigging import BONES, JOINT_NAMES, Skeleton
+
+
+JOINT_COLOR = (255, 80, 80, 255)
+JOINT_OUTLINE = (0, 0, 0, 255)
+BONE_COLOR = (60, 200, 255, 255)
+MASK_EDGE_COLOR = (255, 255, 0, 200)
+JOINT_RADIUS = 4
+BONE_WIDTH = 2
+
+
+def render_overlay(
+    image: np.ndarray,
+    mask: np.ndarray,
+    skeleton: Skeleton,
+    *,
+    show_labels: bool = False,
+) -> Image.Image:
+    if image.ndim == 2:
+        rgba = np.stack(
+            [image, image, image, np.full_like(image, 255)],
+            axis=-1,
+        )
+    elif image.shape[-1] == 3:
+        rgba = np.concatenate(
+            [image, np.full(image.shape[:2] + (1,), 255, dtype=np.uint8)],
+            axis=-1,
+        )
+    elif image.shape[-1] == 4:
+        rgba = image.copy()
+    else:
+        raise ValueError(f"unsupported image shape {image.shape}")
+    H, W = rgba.shape[:2]
+
+    mask_bool = mask.astype(bool)
+    edge = mask_bool & ~binary_erosion(mask_bool, iterations=1, border_value=0)
+    edge_layer_arr = np.zeros((H, W, 4), dtype=np.uint8)
+    edge_layer_arr[edge] = MASK_EDGE_COLOR
+
+    canvas = Image.alpha_composite(
+        Image.fromarray(rgba, mode="RGBA"),
+        Image.fromarray(edge_layer_arr, mode="RGBA"),
+    )
+
+    draw = ImageDraw.Draw(canvas)
+
+    for parent_idx, child_idx in BONES:
+        py, px = skeleton.positions[parent_idx]
+        cy, cx = skeleton.positions[child_idx]
+        draw.line(
+            [(float(px), float(py)), (float(cx), float(cy))],
+            fill=BONE_COLOR,
+            width=BONE_WIDTH,
+        )
+
+    for i in range(skeleton.positions.shape[0]):
+        y, x = skeleton.positions[i]
+        r = JOINT_RADIUS
+        draw.ellipse(
+            [(float(x) - r, float(y) - r), (float(x) + r, float(y) + r)],
+            fill=JOINT_COLOR,
+            outline=JOINT_OUTLINE,
+            width=1,
+        )
+        if show_labels:
+            draw.text(
+                (float(x) + r + 2, float(y) - r),
+                JOINT_NAMES[i],
+                fill=(255, 255, 255, 255),
+            )
+
+    return canvas
+
+
+__all__ = ["render_overlay"]

studio/rigging/parts.py

@@ -0,0 +1,287 @@
+"""studio.rigging.parts — piece-mask sidecar (Phase 3 / Session 3.5).
+
+Each sprite gets two artifacts alongside its joints sidecar:
+
+    <sprite>.png            (the sprite image)
+    <sprite>.joints.json    (joint annotations, Session 2)
+    <sprite>.parts.png      (uint8 grayscale; pixel = piece_id; 0 = background)
+    <sprite>.parts.json     (piece index, bone binding, z-order, kind)
+
+The parts.png is mode='L' so every editor opens and round-trips it cleanly. A
+separate <sprite>.parts.preview.png with a color palette is generated for human
+inspection; it is NOT load-bearing.
+
+JSON format (versioned, forwards-compatible):
+
+    {
+        "schema_version": 1,
+        "image": "goblin.png",
+        "image_shape": [256, 256],
+        "pieces": {
+            "1":  {"name": "torso",       "bone": "neck",       "z": 1, "kind": "body"},
+            ...
+            "14": {"name": "sword",       "bone": "r_wrist",    "z": 9, "kind": "attachment"}
+        }
+    }
+
+Piece IDs are 1-indexed. ID 0 is reserved for background (no piece).
+
+`bone` is the joint name the piece pivots around. Under forward kinematics, the
+piece rotates rigidly around that joint's position by that joint's world
+rotation. `z` is the render order — higher draws on top. `kind` is "body" or
+"attachment"; the default rigid-piece engine renders body-only.
+"""
+from __future__ import annotations
+
+import colorsys
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+from PIL import Image
+
+from pixel_cursor.rigging import JOINT_INDEX, JOINT_NAMES
+
+
+SCHEMA_VERSION: int = 1
+
+
+CANONICAL_HUMANOID_PIECES: Tuple[Tuple[str, str, int, str], ...] = (
+    # (name, bone (joint name), z-order, kind)
+    ("torso",       "neck",       1, "body"),
+    ("l_thigh",     "l_hip",      2, "body"),
+    ("r_thigh",     "r_hip",      2, "body"),
+    ("l_shin",      "l_knee",     3, "body"),
+    ("r_shin",      "r_knee",     3, "body"),
+    ("l_foot",      "l_ankle",    4, "body"),
+    ("r_foot",      "r_ankle",    4, "body"),
+    ("l_upper_arm", "l_shoulder", 5, "body"),
+    ("r_upper_arm", "r_shoulder", 5, "body"),
+    ("l_forearm",   "l_elbow",    6, "body"),
+    ("r_forearm",   "r_elbow",    6, "body"),
+    ("l_hand",      "l_wrist",    7, "body"),
+    ("r_hand",      "r_wrist",    7, "body"),
+    ("head",        "head",       8, "body"),
+)
+
+
+@dataclass(frozen=True)
+class Piece:
+    piece_id: int
+    name: str
+    bone: str
+    z: int
+    kind: str
+
+
+@dataclass(frozen=True)
+class PartsMask:
+    id_map: np.ndarray
+    pieces: Tuple[Piece, ...]
+    image_shape: Tuple[int, int]
+
+    def piece_by_name(self, name: str) -> Optional[Piece]:
+        for p in self.pieces:
+            if p.name == name:
+                return p
+        return None
+
+    def piece_by_id(self, piece_id: int) -> Optional[Piece]:
+        for p in self.pieces:
+            if p.piece_id == piece_id:
+                return p
+        return None
+
+    @property
+    def body_pieces(self) -> Tuple[Piece, ...]:
+        return tuple(p for p in self.pieces if p.kind == "body")
+
+    @property
+    def attachment_pieces(self) -> Tuple[Piece, ...]:
+        return tuple(p for p in self.pieces if p.kind == "attachment")
+
+
+def parts_png_path_for(image_path: Path | str) -> Path:
+    p = Path(image_path)
+    return p.with_name(p.stem + ".parts.png")
+
+
+def parts_json_path_for(image_path: Path | str) -> Path:
+    p = Path(image_path)
+    return p.with_name(p.stem + ".parts.json")
+
+
+def parts_preview_path_for(image_path: Path | str) -> Path:
+    p = Path(image_path)
+    return p.with_name(p.stem + ".parts.preview.png")
+
+
+def load_parts(image_path: Path | str) -> Optional[PartsMask]:
+    """Return the PartsMask for image_path, or None if either sidecar is missing.
+
+    Raises ValueError if the JSON exists but is malformed or has a higher
+    schema_version than we support.
+    """
+    png_path = parts_png_path_for(image_path)
+    json_path = parts_json_path_for(image_path)
+    if not png_path.exists() or not json_path.exists():
+        return None
+
+    data = json.loads(json_path.read_text())
+    version = int(data.get("schema_version", 1))
+    if version > SCHEMA_VERSION:
+        raise ValueError(
+            f"parts sidecar schema_version {version} > supported {SCHEMA_VERSION} "
+            f"({json_path})"
+        )
+
+    shape_field = data["image_shape"]
+    H, W = int(shape_field[0]), int(shape_field[1])
+
+    img = Image.open(png_path)
+    if img.mode != "L":
+        img = img.convert("L")
+    arr = np.asarray(img, dtype=np.uint8)
+    if arr.shape != (H, W):
+        raise ValueError(
+            f"parts.png shape {arr.shape} != image_shape {(H, W)} ({png_path})"
+        )
+
+    pieces_field = data.get("pieces", {})
+    pieces = []
+    for pid_str, entry in pieces_field.items():
+        pid = int(pid_str)
+        if pid == 0:
+            raise ValueError(
+                f"piece_id 0 is reserved for background ({json_path})"
+            )
+        if pid < 0 or pid > 255:
+            raise ValueError(
+                f"piece_id {pid} out of uint8 range ({json_path})"
+            )
+        bone = entry["bone"]
+        if bone not in JOINT_INDEX:
+            raise ValueError(
+                f"piece '{entry.get('name', pid)}' bone '{bone}' is not a known "
+                f"joint ({json_path}); known: {list(JOINT_NAMES)}"
+            )
+        pieces.append(Piece(
+            piece_id=pid,
+            name=str(entry["name"]),
+            bone=bone,
+            z=int(entry.get("z", 0)),
+            kind=str(entry.get("kind", "body")),
+        ))
+
+    return PartsMask(
+        id_map=arr,
+        pieces=tuple(pieces),
+        image_shape=(H, W),
+    )
+
+
+def save_parts(
+    image_path: Path | str,
+    id_map: np.ndarray,
+    pieces: Tuple[Piece, ...],
+    *,
+    image_name: Optional[str] = None,
+) -> Tuple[Path, Path]:
+    """Write <sprite>.parts.png + <sprite>.parts.json. Returns (png_path, json_path)."""
+    if id_map.ndim != 2:
+        raise ValueError(f"id_map must be 2D, got {id_map.shape}")
+    if id_map.dtype != np.uint8:
+        raise ValueError(f"id_map must be uint8, got {id_map.dtype}")
+    png_path = parts_png_path_for(image_path)
+    json_path = parts_json_path_for(image_path)
+    name = image_name if image_name is not None else Path(image_path).name
+
+    Image.fromarray(id_map, mode="L").save(png_path)
+
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "image": name,
+        "image_shape": [int(id_map.shape[0]), int(id_map.shape[1])],
+        "pieces": {
+            str(p.piece_id): {
+                "name": p.name,
+                "bone": p.bone,
+                "z": p.z,
+                "kind": p.kind,
+            }
+            for p in pieces
+        },
+    }
+    json_path.write_text(json.dumps(payload, indent=2, sort_keys=False) + "\n")
+    return png_path, json_path
+
+
+def save_preview(
+    image_path: Path | str,
+    parts: PartsMask,
+) -> Path:
+    """Write a color-coded RGBA preview alongside the parts sidecar.
+
+    Pure operator convenience — not load-bearing. Background is transparent.
+    """
+    H, W = parts.image_shape
+    rgba = np.zeros((H, W, 4), dtype=np.uint8)
+    palette = _build_preview_palette(parts.pieces)
+    for piece in parts.pieces:
+        mask = parts.id_map == piece.piece_id
+        if not mask.any():
+            continue
+        rgba[mask] = palette[piece.piece_id]
+    out_path = parts_preview_path_for(image_path)
+    Image.fromarray(rgba, mode="RGBA").save(out_path)
+    return out_path
+
+
+def _build_preview_palette(
+    pieces: Tuple[Piece, ...],
+) -> Dict[int, Tuple[int, int, int, int]]:
+    palette: Dict[int, Tuple[int, int, int, int]] = {}
+    n = max(1, len(pieces))
+    for i, p in enumerate(pieces):
+        hue = (i / n) % 1.0
+        sat = 0.65
+        val = 0.95 if p.kind == "body" else 0.55
+        r, g, b = colorsys.hsv_to_rgb(hue, sat, val)
+        palette[p.piece_id] = (int(r * 255), int(g * 255), int(b * 255), 220)
+    return palette
+
+
+def canonical_humanoid_pieces(
+    extras: Tuple[Tuple[str, str, int, str], ...] = (),
+) -> Tuple[Piece, ...]:
+    """Return the canonical 13 humanoid pieces plus any extras (attachments).
+
+    extras: iterable of (name, bone, z, kind) tuples to append. Piece IDs are
+    assigned sequentially starting from 1.
+    """
+    pieces = []
+    next_id = 1
+    for name, bone, z, kind in CANONICAL_HUMANOID_PIECES:
+        pieces.append(Piece(piece_id=next_id, name=name, bone=bone, z=z, kind=kind))
+        next_id += 1
+    for name, bone, z, kind in extras:
+        pieces.append(Piece(piece_id=next_id, name=name, bone=bone, z=z, kind=kind))
+        next_id += 1
+    return tuple(pieces)
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "CANONICAL_HUMANOID_PIECES",
+    "Piece",
+    "PartsMask",
+    "parts_png_path_for",
+    "parts_json_path_for",
+    "parts_preview_path_for",
+    "load_parts",
+    "save_parts",
+    "save_preview",
+    "canonical_humanoid_pieces",
+]

studio/rigging/rigid_piece.py

@@ -0,0 +1,124 @@
+"""studio.rigging.rigid_piece — rigid-piece backward-warp engine (Session 3.5).
+
+Each piece rotates rigidly around its bone joint's position by that joint's
+world rotation (computed via the same FK pass the LBS engine uses). Pixels are
+sampled by backward warp: for each output pixel, the inverse transform maps to
+a source pixel; if the source pixel belongs to this piece in the rest parts.png,
+its color is copied.
+
+Why backward-warp instead of forward-splat:
+  - No gaps when a piece under-samples its output region after rotation.
+  - z-order is the natural occlusion model — paint back-to-front, higher z wins.
+  - Nearest-neighbor membership check matches sprite-art pixel discipline.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Mapping, Tuple
+
+import numpy as np
+
+from pixel_cursor.rigging import JOINT_INDEX, Skeleton
+
+from .deform import forward_kinematics
+from .parts import PartsMask
+
+
+def deform_sprite_rigid(
+    image: np.ndarray,
+    rest: Skeleton,
+    parts: PartsMask,
+    *,
+    local_rotations: Mapping[str, float] | None = None,
+    include_kinds: Tuple[str, ...] = ("body",),
+    exclude_pieces: Iterable[str] = (),
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Render a posed configuration via rigid-piece backward warp.
+
+    Args:
+        image: source sprite, shape (H, W, 3 or 4) uint8.
+        rest:  rest-pose skeleton (image_shape must equal image's H, W).
+        parts: piece-mask sidecar (id_map shape must equal image's H, W).
+        local_rotations: optional dict mapping joint_name -> local rotation (rad).
+        include_kinds: piece.kind values to render. Default ('body',) — attachments
+            are handled by the composite layer (Session 4).
+        exclude_pieces: piece names to skip (e.g., ('sword',) for swordless render).
+
+    Returns:
+        (rgba (H, W, 4) uint8, mask (H, W) bool)
+
+    The output is composed back-to-front by z; higher z overwrites lower. Every
+    output pixel is a pixel-perfect copy of exactly one source pixel (or fully
+    transparent) — this is the 'rigid' invariant.
+    """
+    H, W = parts.image_shape
+    if image.shape[:2] != (H, W):
+        raise ValueError(
+            f"image shape {image.shape[:2]} != parts.image_shape {(H, W)}"
+        )
+    if rest.image_shape != (H, W):
+        raise ValueError(
+            f"rest.image_shape {rest.image_shape} != parts.image_shape {(H, W)}"
+        )
+
+    if image.ndim == 3 and image.shape[-1] == 4:
+        rgba = image
+    elif image.ndim == 3 and image.shape[-1] == 3:
+        rgba = np.concatenate(
+            [image, np.full((H, W, 1), 255, dtype=np.uint8)], axis=-1
+        )
+    elif image.ndim == 2:
+        gray = image
+        rgba = np.stack(
+            [gray, gray, gray, np.full_like(gray, 255)], axis=-1
+        )
+    else:
+        raise ValueError(f"unsupported image shape {image.shape}")
+
+    deformed_pos, world_rot = forward_kinematics(rest, local_rotations or {})
+
+    out_rgba = np.zeros((H, W, 4), dtype=np.uint8)
+    out_mask = np.zeros((H, W), dtype=bool)
+
+    yy, xx = np.mgrid[0:H, 0:W].astype(np.float32)
+
+    exclude = set(exclude_pieces)
+    selected = [
+        p for p in parts.pieces
+        if p.kind in include_kinds and p.name not in exclude
+    ]
+    selected.sort(key=lambda p: p.z)
+
+    for piece in selected:
+        bone_idx = JOINT_INDEX[piece.bone]
+        pivot_rest_y = float(rest.positions[bone_idx, 0])
+        pivot_rest_x = float(rest.positions[bone_idx, 1])
+        pivot_posed_y = float(deformed_pos[bone_idx, 0])
+        pivot_posed_x = float(deformed_pos[bone_idx, 1])
+        theta = float(world_rot[bone_idx])
+
+        c = np.cos(-theta)
+        s = np.sin(-theta)
+
+        dy = yy - pivot_posed_y
+        dx = xx - pivot_posed_x
+        src_y = pivot_rest_y + c * dy - s * dx
+        src_x = pivot_rest_x + s * dy + c * dx
+
+        sy_i = np.round(src_y).astype(np.int32)
+        sx_i = np.round(src_x).astype(np.int32)
+        in_bounds = (sy_i >= 0) & (sy_i < H) & (sx_i >= 0) & (sx_i < W)
+        sy_safe = np.clip(sy_i, 0, H - 1)
+        sx_safe = np.clip(sx_i, 0, W - 1)
+
+        membership = parts.id_map[sy_safe, sx_safe] == piece.piece_id
+        src_alpha = rgba[sy_safe, sx_safe, 3] > 0
+        valid = in_bounds & membership & src_alpha
+        if not valid.any():
+            continue
+        out_rgba[valid] = rgba[sy_safe[valid], sx_safe[valid]]
+        out_mask |= valid
+
+    return out_rgba, out_mask
+
+
+__all__ = ["deform_sprite_rigid"]

studio/rigging/segment.py

@@ -0,0 +1,70 @@
+"""studio.rigging.segment — flood-fill-from-corners cartoon segmentation.
+
+Real alpha channel short-circuits the heuristic: `alpha > 127` is the mask.
+Otherwise: connected components of the "background-similar" mask, take the
+union of components that touch any of the 4 image corners, invert.
+
+Deterministic, numpy + scipy.ndimage.label, no model imports.
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import label
+
+
+DEFAULT_TOLERANCE: int = 15
+
+
+def flood_fill_segment(
+    image: np.ndarray,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE,
+    alpha_threshold: int = 127,
+) -> np.ndarray:
+    """Return a boolean (H, W) foreground mask.
+
+    image: (H, W) uint8 grayscale, (H, W, 3) RGB uint8, or (H, W, 4) RGBA uint8.
+    tolerance: per-channel Chebyshev tolerance for "background-similar" pixels.
+    alpha_threshold: cutoff for the RGBA fast path (only used if the alpha
+        channel actually varies across the image).
+    """
+    if image.ndim == 3 and image.shape[-1] == 4:
+        alpha = image[..., 3]
+        if alpha.min() < 255 and alpha.max() > 0 and alpha.max() != alpha.min():
+            return alpha > alpha_threshold
+        image = image[..., :3]
+
+    if image.ndim == 2:
+        rgb = np.stack([image, image, image], axis=-1)
+    elif image.ndim == 3 and image.shape[-1] == 3:
+        rgb = image
+    else:
+        raise ValueError(f"unsupported image shape {image.shape}")
+
+    H, W, _ = rgb.shape
+    rgb_i16 = rgb.astype(np.int16)
+
+    corners = np.stack(
+        [rgb_i16[0, 0], rgb_i16[0, -1], rgb_i16[-1, 0], rgb_i16[-1, -1]],
+        axis=0,
+    )
+    bg_color = corners.mean(axis=0)
+    diff = np.abs(rgb_i16 - bg_color).max(axis=-1)
+    similar = diff <= tolerance
+
+    labels, _ = label(similar.astype(np.uint8), structure=np.ones((3, 3), dtype=np.int8))
+
+    bg_label_ids = set()
+    for y, x in ((0, 0), (0, W - 1), (H - 1, 0), (H - 1, W - 1)):
+        L = int(labels[y, x])
+        if L > 0:
+            bg_label_ids.add(L)
+
+    if not bg_label_ids:
+        return np.ones((H, W), dtype=bool)
+
+    bg_mask = np.isin(labels, np.asarray(sorted(bg_label_ids), dtype=labels.dtype))
+    return ~bg_mask
+
+
+__all__ = ["flood_fill_segment", "DEFAULT_TOLERANCE"]

studio/rigging/sidecar.py

@@ -0,0 +1,139 @@
+"""studio.rigging.sidecar — operator-annotation JSON loader + saver.
+
+Sidecar format (versioned, forwards-compatible):
+
+    {
+        "schema_version": 1,
+        "image": "goblin.png",
+        "image_shape": [256, 256],
+        "joints": {
+            "head":        {"y": 50,  "x": 128, "confidence": 1.0},
+            "neck":        {"y": 110, "x": 128},
+            ...
+        }
+    }
+
+Sidecar path convention: `<sprite>.joints.json` next to `<sprite>.png`.
+
+Loader is lenient: missing joints default to image-center with confidence 0.0,
+so the overlay renders them clearly out-of-place — the operator drags them to
+the correct positions by editing the JSON.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional, Tuple
+
+import numpy as np
+
+from pixel_cursor.rigging import JOINT_INDEX, JOINT_NAMES, NUM_JOINTS, Skeleton
+
+
+SCHEMA_VERSION: int = 1
+
+
+def sidecar_path_for(image_path: Path | str) -> Path:
+    p = Path(image_path)
+    return p.with_suffix(".joints.json")
+
+
+def load_sidecar(
+    image_path: Path | str,
+    *,
+    image_shape: Optional[Tuple[int, int]] = None,
+) -> Optional[Skeleton]:
+    """Return a Skeleton from the sidecar next to image_path, or None if absent.
+
+    Missing or malformed joint entries default to image center with confidence 0.
+    """
+    sidecar = sidecar_path_for(image_path)
+    if not sidecar.exists():
+        return None
+
+    data = json.loads(sidecar.read_text())
+    version = int(data.get("schema_version", 1))
+    if version > SCHEMA_VERSION:
+        raise ValueError(
+            f"sidecar schema_version {version} > supported {SCHEMA_VERSION} "
+            f"({sidecar})"
+        )
+
+    shape_field = data.get("image_shape")
+    if shape_field is not None:
+        H, W = int(shape_field[0]), int(shape_field[1])
+    elif image_shape is not None:
+        H, W = image_shape
+    else:
+        raise ValueError(
+            f"sidecar {sidecar} has no image_shape; pass image_shape= to load_sidecar"
+        )
+
+    joints_field = data.get("joints", {})
+    positions = np.zeros((NUM_JOINTS, 2), dtype=np.float32)
+    confidence = np.zeros(NUM_JOINTS, dtype=np.float32)
+
+    for name in JOINT_NAMES:
+        entry = joints_field.get(name)
+        idx = JOINT_INDEX[name]
+        if entry is None:
+            positions[idx] = (H / 2.0, W / 2.0)
+            confidence[idx] = 0.0
+            continue
+        positions[idx, 0] = float(entry["y"])
+        positions[idx, 1] = float(entry["x"])
+        confidence[idx] = float(entry.get("confidence", 1.0))
+
+    return Skeleton(positions=positions, confidence=confidence, image_shape=(H, W))
+
+
+def save_sidecar(
+    image_path: Path | str,
+    skeleton: Skeleton,
+    *,
+    image_name: Optional[str] = None,
+) -> Path:
+    sidecar = sidecar_path_for(image_path)
+    name = image_name if image_name is not None else Path(image_path).name
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "image": name,
+        "image_shape": list(skeleton.image_shape),
+        "joints": {
+            joint_name: {
+                "y": round(float(skeleton.positions[i, 0]), 2),
+                "x": round(float(skeleton.positions[i, 1]), 2),
+                "confidence": round(float(skeleton.confidence[i]), 3),
+            }
+            for i, joint_name in enumerate(JOINT_NAMES)
+        },
+    }
+    sidecar.write_text(json.dumps(payload, indent=2, sort_keys=False) + "\n")
+    return sidecar
+
+
+def sidecar_template(
+    image_shape: Tuple[int, int],
+    image_name: str = "",
+) -> dict:
+    """Return a template dict the operator can write to disk and fill in."""
+    H, W = image_shape
+    cy, cx = H / 2.0, W / 2.0
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "image": image_name,
+        "image_shape": [H, W],
+        "joints": {
+            name: {"y": cy, "x": cx, "confidence": 0.0}
+            for name in JOINT_NAMES
+        },
+    }
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "sidecar_path_for",
+    "load_sidecar",
+    "save_sidecar",
+    "sidecar_template",
+]

studio/rigging/skin.py

@@ -0,0 +1,84 @@
+"""studio.rigging.skin — inverse-distance-falloff mesh skinning weights.
+
+For each foreground pixel and each bone, weight ∝ 1 / distance_to_bone^p,
+normalised across bones to sum to 1 per pixel. Background pixels get zero
+weight on every bone.
+
+This is the "fast / good-enough" baseline picked in PHASE_3_RESEARCH.md.
+Heat-diffusion skinning (better crease quality) is the upgrade path for
+Session 4 if creases hurt visual quality.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from pixel_cursor.rigging import BONES, NUM_JOINTS, Skeleton
+
+
+DEFAULT_FALLOFF: float = 4.0
+DEFAULT_EPSILON: float = 0.5
+
+
+def _point_segment_distance(
+    points: np.ndarray, a: np.ndarray, b: np.ndarray
+) -> np.ndarray:
+    """Distance from each point to the closed segment AB.
+
+    points: shape (..., 2) in (y, x)
+    a, b:   shape (2,) endpoints
+    Returns shape (...)
+    """
+    ab = b - a
+    ap = points - a
+    ab_len_sq = float((ab * ab).sum())
+    if ab_len_sq < 1e-6:
+        return np.linalg.norm(ap, axis=-1)
+    t = (ap * ab).sum(axis=-1) / ab_len_sq
+    t = np.clip(t, 0.0, 1.0)
+    closest = a + t[..., None] * ab
+    return np.linalg.norm(points - closest, axis=-1)
+
+
+def compute_skin_weights(
+    skeleton: Skeleton,
+    mask: np.ndarray,
+    *,
+    falloff: float = DEFAULT_FALLOFF,
+    epsilon: float = DEFAULT_EPSILON,
+) -> np.ndarray:
+    """Return (H, W, N_BONES) inverse-distance-falloff skinning weights.
+
+    Properties:
+      - Each foreground pixel's weights sum to 1.0 (partition of unity).
+      - Each background pixel's weights are exactly 0 across all bones.
+      - Deterministic: same skeleton + mask → same weights, bitwise.
+    """
+    if mask.ndim != 2:
+        raise ValueError(f"mask must be 2D, got {mask.shape}")
+    if skeleton.image_shape != mask.shape:
+        raise ValueError(
+            f"skeleton.image_shape={skeleton.image_shape} != mask.shape={mask.shape}"
+        )
+
+    H, W = mask.shape
+    ys, xs = np.indices((H, W))
+    coords = np.stack([ys, xs], axis=-1).astype(np.float32)
+
+    n_bones = len(BONES)
+    dists = np.empty((H, W, n_bones), dtype=np.float32)
+    rest = skeleton.positions
+    for b, (parent_idx, child_idx) in enumerate(BONES):
+        dists[..., b] = _point_segment_distance(
+            coords, rest[parent_idx], rest[child_idx]
+        )
+
+    inv = 1.0 / np.maximum(dists, epsilon) ** falloff
+    total = inv.sum(axis=-1, keepdims=True)
+    weights = inv / np.maximum(total, 1e-12)
+
+    mask_bool = mask.astype(bool)[..., None]
+    weights = np.where(mask_bool, weights, 0.0).astype(np.float32)
+    return weights
+
+
+__all__ = ["compute_skin_weights", "DEFAULT_FALLOFF", "DEFAULT_EPSILON"]

studio/spritesheet.py

@@ -0,0 +1,78 @@
+"""FrameStack -> sprite sheet PNG.
+
+A sprite sheet is a single PNG containing N animation frames in a grid. This is
+the idiomatic asset format for 2D game engines (Babylon.js `SpriteManager`,
+Phaser, PixiJS) — no codec dependency, instant load, deterministic playback.
+
+Convention: frames packed left-to-right, top-to-bottom. Default 4 columns gives
+square-ish output for 16-frame stacks (4x4 = 16 cells).
+"""
+from __future__ import annotations
+from pathlib import Path
+
+import numpy as np
+from PIL import Image as PILImage
+
+from pixel_cursor import FrameStack
+
+
+def frame_stack_to_sprite_sheet(
+    stack: FrameStack,
+    cols: int = 4,
+    bg_rgba: tuple[int, int, int, int] = (0, 0, 0, 0),
+) -> PILImage.Image:
+    """Pack T frames into a (rows*cols)-cell grid PNG. RGBA output."""
+    t, h, w, c = stack.frames.shape
+    if c not in (3, 4):
+        raise ValueError(f"expected 3 or 4 channels; got shape {stack.frames.shape}")
+    rows = (t + cols - 1) // cols
+    sheet_w = w * cols
+    sheet_h = h * rows
+
+    sheet = np.zeros((sheet_h, sheet_w, 4), dtype=np.uint8)
+    sheet[:, :] = bg_rgba
+
+    for idx in range(t):
+        r, k = divmod(idx, cols)
+        y0, x0 = r * h, k * w
+        frame = stack.frames[idx]
+        if c == 3:
+            sheet[y0 : y0 + h, x0 : x0 + w, :3] = frame
+            sheet[y0 : y0 + h, x0 : x0 + w, 3] = 255
+        else:
+            sheet[y0 : y0 + h, x0 : x0 + w, :] = frame
+
+    return PILImage.fromarray(sheet, mode="RGBA")
+
+
+def write_sprite_sheet(
+    stack: FrameStack,
+    out_path: Path | str,
+    cols: int = 4,
+    bg_rgba: tuple[int, int, int, int] = (0, 0, 0, 0),
+) -> Path:
+    out = Path(out_path)
+    img = frame_stack_to_sprite_sheet(stack, cols=cols, bg_rgba=bg_rgba)
+    img.save(out, optimize=True)
+    return out
+
+
+def sheet_metadata(stack: FrameStack, cols: int = 4) -> dict:
+    """Return a manifest describing the sheet (cell size, count, fps).
+
+    Game engines need this to play back. Babylon SpriteManager expects
+    `cellWidth, cellHeight, capacity (total cells)`.
+    """
+    t, h, w, _ = stack.frames.shape
+    rows = (t + cols - 1) // cols
+    return {
+        "frames": t,
+        "cols": cols,
+        "rows": rows,
+        "cell_width": w,
+        "cell_height": h,
+        "sheet_width": w * cols,
+        "sheet_height": h * rows,
+        "fps": stack.fps,
+        "loop_duration_ms": int(round(1000 * t / max(1, stack.fps))),
+    }