Skip to content

0x0funky/agent-sprite-forge / skills/video2dsprite

video2dsprite

Verified

Turn one approved master still into a character's whole animated sprite set - one image-to-video clip per action (idle, walk, run, attack, jump, hurt, cast and so on), all from that still, generated through generate2dmedia route_media.py (the xAI API when a key is configured, else the local Grok CLI) - then gate each take, key it with a soft matte, register it to the master, pick loops or retime actions, finish (HD by default, pixel on request) and package fixed-canvas frames, alpha WebM, packed MP4 for iPhone and a PNG fallback with engine metadata and a JS runtime. Also processes a supplied clip. Use for character and creature animation, fluid motion and any video-to-sprite work. Not for FX, icon or prop sheets (generate2dsprite), maps or plate loops (generate2dmap), code-drawn animation (codeart2d, only on request) or calling a video API by itself (generate2dmedia).

scripts/register_clip.py

View on GitHub
#!/usr/bin/env python3
"""Register image-to-video clips by construction, and judge raw takes.

  apply             Map keyed frames (for example video2dsprite process frames-clean)
                    onto the master canvas with the one fixed transform recorded by
                    prepare_i2v_input.py: premultiplied resampling, action padding that
                    grows the canvas and shifts the anchor (never shrinks the body),
                    optional feet/x/hip locks in whole output pixels, and an actor or
                    fx profile (edge fade, dissolve tail, displayScale), then the alpha
                    hygiene floor (alpha <= 4 cleared: invisible resampling halo). Writes
                    frames/, registration.json and review-contact.png to a new
                    --output-dir after registration QA.
  profile           Write a character profile (video2dsprite.character_profile.v1) from
                    registered clips; later clips inherit it with apply
                    --character-profile.
  validate-profile  Check registered clips against a profile and report every clip's
                    rest-pose foot line (nativeFootBottomRange).
  qc                Judge a raw take against its job: landmark and identity NCC
                    (36 px patches, +-15 px search), camera drift and scale in the
                    calm spans, edge key purity. Appends one take.v1 line to
                    takes.jsonl (an audit log: kept and rejected takes exit 0;
                    --strict exits 1 on a rejection, the line still written).
  palette-repair    Remap off-palette flashes inside given regions to colours sampled
                    from the master. Alpha never changes; writes an audit report.

Registration is by construction, not by bounding box: every frame of a clip uses
the same scale and translation, so pose, height and contact changes survive.
"""
from __future__ import annotations

import argparse
import json
import math
import re
import sys
import tempfile
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Sequence

import numpy as np
from PIL import Image, ImageDraw

HERE = Path(__file__).resolve().parent
if str(HERE) not in sys.path:
    sys.path.insert(0, str(HERE))
import forge_core  # noqa: E402  (this skill's vendored copy)
import forge_matte  # noqa: E402
import prepare_i2v_input as prep  # noqa: E402  (sibling script: action templates, placement, key helpers)

TOOL_NAME = "register_clip"
TOOL_VERSION = forge_core.FORGE_PACKAGE_VERSION  # QA envelopes record the package version (D29)
REGISTRATION_SCHEMA = "video2dsprite.registration.v1"
PROFILE_SCHEMA = "video2dsprite.character_profile.v1"
TAKE_SCHEMA = "video2dsprite.take.v1"
PALETTE_REPAIR_SCHEMA = "video2dsprite.palette_repair.v1"
REGISTRATION_FILE = "registration.json"
PALETTE_REPAIR_FILE = "palette-repair.json"

FITS = ("auto", "stretch", "cover", "contain")
LOCKS = ("feet", "x", "hip")
PROFILES = ("actor", "fx")
THRESHOLD = forge_core.ALPHA_GEOMETRY_THRESHOLD   # subject pixels: alpha > 16 (edge and overflow checks)
CONTOUR = 127   # body measurements compared with the crisp master use the 50% alpha contour,
                # which resampling blur leaves in place (alpha > 16 grows a resampled body by ~1 px a side)

DEFAULT_MAX_ANCHOR_ERROR = 2.0    # output px between the rest frame and the master (same measurement)
DEFAULT_MAX_SCALE_ERROR = 0.03    # amber-quay measured 2.2-4.8% body-scale pumping as visible
DEFAULT_GROUND_MIN_RUN = 3        # px a row needs to count as the ground line (ignores specks)
LOCK_MARGIN = 0.06                # locked frames are registered once with this much room (share of the canvas)
FX_EDGE_FADE = 0.085              # Dusk FX: 46 px boundary falloff on a 540 px canvas
FX_FADE_IN_FRAMES = 2             # Dusk FX: transparent first frame, 50 ms appearance
FX_DISSOLVE_TAIL = 0.2            # Dusk FX: final 20% alpha dissolve, at least 4 frames
FX_DISSOLVE_MIN_FRAMES = 4

QC_PATCH = 36                     # Dusk qa-registration.py: 36 px zero-mean NCC patches
QC_SEARCH = 15                    # ... searched +-15 px
QC_SUBJECT_DISTANCE = 64.0        # RGB distance from the estimated key that counts as subject in raw frames
QC_CHANGE_LEVELS = 16             # luma change that counts as motion, above codec noise
DEFAULT_MAX_SCALE_CHANGE = 0.03
DEFAULT_MAX_DRIFT = 2.0           # source px
DEFAULT_MIN_LANDMARK_NCC = 0.6
DEFAULT_MIN_IDENTITY_NCC = 0.5
DEFAULT_MAX_EDGE_IMPURE = 0.0005  # share of the border band
HYGIENE_FLOOR = 4                 # D18: registered frames lose alpha <= 4 (forge_core.alpha_hygiene floor)
MATTE_MODES = ("soft", "dominance", "binary")


class RegistrationQAError(ValueError):
    """Registration QA failed; nothing was published."""


# --------------------------------------------------------------------------- small helpers

def _ascii(text: Any) -> str:
    return forge_core.ascii_text(str(text))


_round_half_up = forge_core.round_half_up  # floor(value + 1/2), never banker's rounding (D30)


def _natural_key(path: Path) -> list:
    return [int(part) if part.isdigit() else part.lower() for part in re.split(r"(\d+)", path.name)]


def list_frames(directory: str | Path, pattern: str = "*.png") -> list[Path]:
    folder = Path(directory)
    if not folder.is_dir():
        raise ValueError(f"Frames folder not found: {folder}")
    files = sorted((path for path in folder.glob(pattern) if path.is_file()), key=_natural_key)
    if not files:
        raise ValueError(f"No frames matching {pattern} in {folder}")
    return files


def ref_path(path: str | Path, base: str | Path) -> str:
    """Manifest-relative POSIX path, or just the file name when no relative path exists
    (another drive): manifests never hold absolute paths (forge_core.manifest_path, D30)."""
    return forge_core.manifest_path(path, base)


def _file_ref(path: Path, base: Path, digest: str | None = None) -> dict[str, Any]:
    """A common fileRef {path, sha256, bytes} (forge_core.file_ref, D30)."""
    return forge_core.file_ref(path, base, sha256=digest)


def _load_pixels(path: Path) -> tuple[np.ndarray, str]:
    image, info = forge_core.load_rgba(path)
    return np.asarray(image), info["sha256"]


def _bbox(mask: np.ndarray) -> tuple[int, int, int, int] | None:
    rows = np.flatnonzero(mask.any(axis=1))
    if rows.size == 0:
        return None
    columns = np.flatnonzero(mask.any(axis=0))
    return int(columns[0]), int(rows[0]), int(columns[-1]) + 1, int(rows[-1]) + 1


def _box_sum(values: np.ndarray, height: int, width: int) -> np.ndarray:
    """Sums of every height x width window (valid positions only), via a summed-area table."""
    table = np.zeros((values.shape[0] + 1, values.shape[1] + 1), np.float64)
    table[1:, 1:] = values.astype(np.float64).cumsum(0).cumsum(1)
    return table[height:, width:] - table[:-height, width:] - table[height:, :-width] + table[:-height, :-width]


def parse_range(text: str) -> tuple[int, int | None]:
    match = re.fullmatch(r"\s*(\d+)\s*:\s*(\d*)\s*", str(text))
    if not match:
        raise argparse.ArgumentTypeError(f"--range needs START:END (0-based, end exclusive); got {text!r}")
    start, end = int(match.group(1)), (int(match.group(2)) if match.group(2) else None)
    if end is not None and end <= start:
        raise argparse.ArgumentTypeError(f"--range end must be after start; got {text!r}")
    return start, end


def parse_frames_list(text: str) -> list[int]:
    """Comma-separated frame indices; 'none' is the empty list."""
    if str(text).strip().lower() == "none":
        return []
    try:
        values = sorted({int(part) for part in str(text).split(",") if part.strip()})
    except ValueError:
        raise argparse.ArgumentTypeError(f"--rest-frames needs none or comma-separated indices; got {text!r}") from None
    if not values or values[0] < 0:
        raise argparse.ArgumentTypeError(f"--rest-frames needs none or indices >= 0; got {text!r}")
    return values


def parse_locks(text: str) -> list[str]:
    locks = [part.strip().lower() for part in str(text).split(",") if part.strip()]
    if not locks or any(lock not in LOCKS for lock in locks):
        raise argparse.ArgumentTypeError(f"--lock takes {', '.join(LOCKS)} (comma-separated); got {text!r}")
    if "x" in locks and "hip" in locks:
        raise argparse.ArgumentTypeError("--lock x and hip both pin x; pick one")
    return sorted(set(locks), key=LOCKS.index)


def parse_hue(text: str) -> tuple[float, float]:
    low, high = prep.parse_numbers(text, 2, "a hue range H0,H1")
    if not (0 <= low <= 360 and 0 <= high <= 360):
        raise argparse.ArgumentTypeError(f"hues are degrees 0-360; got {text!r}")
    return low, high


# --------------------------------------------------------------------------- the job

@dataclass(frozen=True)
class Job:
    """registration_job.v1 plus the geometry derived from it."""

    path: Path
    sha256: str
    data: dict[str, Any]
    master_path: Path
    master_sha256: str
    master_size: tuple[int, int]
    view_box: tuple[int, int, int, int] | None
    source_size: tuple[int, int]
    source_anchor: tuple[float, float]
    canvas: tuple[int, int]
    scale: float
    offset: tuple[float, float]
    key: str
    key_rgb: tuple[int, int, int]
    padding: tuple[int, int, int, int]
    action: str
    returns_to_rest: bool
    pixel_art: bool
    anchor_mode: str
    margin: float


def _pair(value: Any, name: str, *, positive: bool = False, integer: bool = False) -> tuple:
    ok = isinstance(value, list) and len(value) == 2 and all(
        isinstance(item, (int, float)) and not isinstance(item, bool) and math.isfinite(item) for item in value)
    if ok and integer:
        ok = all(float(item).is_integer() for item in value)
    if ok and positive:
        ok = all(item > 0 for item in value)
    if not ok:
        raise ValueError(f"The job's {name} must be two {'positive ' if positive else ''}"
                         f"{'integers' if integer else 'numbers'}; got {value!r}")
    return (int(value[0]), int(value[1])) if integer else (float(value[0]), float(value[1]))


def _job_key(value: Any) -> str:
    """The job's keyColor as a key name or #rrggbb (the key actually used, never auto)."""
    if isinstance(value, list) and len(value) == 3 and all(isinstance(v, int) and 0 <= v <= 255 for v in value):
        return "#" + "".join(f"{int(v):02x}" for v in value)
    if isinstance(value, str) and value.strip().lower() != "auto":
        try:
            return prep.normalise_key(value)
        except argparse.ArgumentTypeError:
            pass
    raise ValueError(f"The job's keyColor must be the key used: magenta, green, blue, #rrggbb or [r, g, b]; "
                     f"got {value!r}")


def load_job(path: str | Path) -> Job:
    """Read a registration_job.v1 (prepare_i2v_input output or hand-written with the
    required fields only) and derive the source canvas, anchor and transform."""
    path = Path(path)
    raw = path.read_bytes()
    try:
        data = forge_core.parse_json(raw)  # UTF-8 with or without a BOM (D28)
    except ValueError:
        raise ValueError(f"{path.name} is not valid JSON") from None
    if not isinstance(data, dict) or data.get("schema") != prep.JOB_SCHEMA:
        raise ValueError(f"{path.name} is not a {prep.JOB_SCHEMA} document")
    master = data.get("master")
    if not (isinstance(master, dict) and isinstance(master.get("path"), str)
            and isinstance(master.get("sha256"), str)):
        raise ValueError("The job needs master.path and master.sha256")
    master_size = _pair(master.get("size"), "master.size", positive=True, integer=True)
    master_anchor = _pair(master.get("anchor"), "master.anchor")
    view_box = None
    origin = (0.0, 0.0)
    source_size = master_size
    if master.get("viewBox") is not None:
        box = master["viewBox"]
        if not (isinstance(box, list) and len(box) == 4 and all(isinstance(v, int) for v in box)
                and 0 <= box[0] < box[2] <= master_size[0] and 0 <= box[1] < box[3] <= master_size[1]):
            raise ValueError(f"The job's master.viewBox must be an integer box inside the master; got {box!r}")
        view_box = tuple(box)
        origin = (float(box[0]), float(box[1]))
        source_size = (box[2] - box[0], box[3] - box[1])
    source_anchor = (master_anchor[0] - origin[0], master_anchor[1] - origin[1])
    if "sourceSize" in data and _pair(data["sourceSize"], "sourceSize", positive=True, integer=True) != source_size:
        raise ValueError("The job's sourceSize disagrees with master.size/viewBox")
    if "sourceAnchor" in data:
        stated = _pair(data["sourceAnchor"], "sourceAnchor")
        if max(abs(stated[0] - source_anchor[0]), abs(stated[1] - source_anchor[1])) > 1e-6:
            raise ValueError("The job's sourceAnchor disagrees with master.anchor and viewBox")
    canvas = _pair(data.get("referenceCanvas"), "referenceCanvas", positive=True, integer=True)
    scale = data.get("referenceScale")
    if not isinstance(scale, (int, float)) or isinstance(scale, bool) or not math.isfinite(scale) or scale <= 0:
        raise ValueError(f"The job's referenceScale must be a positive number; got {scale!r}")
    offset = _pair(data.get("referenceOffset"), "referenceOffset")
    padding = data.get("padding")
    if not (isinstance(padding, list) and len(padding) == 4 and all(isinstance(v, int) and v >= 0 for v in padding)):
        raise ValueError(f"The job's padding must be four integers >= 0; got {padding!r}")
    key = _job_key(data.get("keyColor"))
    action = str(data.get("action") or "")
    if not action:
        raise ValueError("The job needs an action")
    template = prep.ACTIONS.get(action)
    returns = data.get("returnsToRest")
    returns = bool(returns) if isinstance(returns, bool) else bool(template and template.returns_to_rest)
    master_path = (path.parent / master["path"]).resolve()
    margin = data.get("margin", prep.DEFAULT_MARGIN)
    return Job(path=path.resolve(), sha256=forge_core.sha256_bytes(raw), data=data, master_path=master_path,
               master_sha256=master["sha256"], master_size=master_size, view_box=view_box,
               source_size=source_size, source_anchor=source_anchor, canvas=canvas, scale=float(scale),
               offset=offset, key=key, key_rgb=prep.key_rgb(key), padding=tuple(padding), action=action,
               returns_to_rest=returns, pixel_art=bool(data.get("pixelArt", False)),
               anchor_mode=str(data.get("anchorMode") or "stance"),
               margin=float(margin) if isinstance(margin, (int, float)) else float(prep.DEFAULT_MARGIN))


def load_master_view(job: Job) -> np.ndarray:
    """The master (or its view box) as RGBA, after checking it is the file the job was made from."""
    if not job.master_path.is_file():
        raise ValueError(f"The job's master {job.data['master']['path']} is not next to {job.path.name}")
    pixels, digest = _load_pixels(job.master_path)
    if digest != job.master_sha256:
        raise ValueError(f"{job.master_path.name} changed since the job was prepared (sha256 mismatch)")
    if job.view_box:
        x0, y0, x1, y1 = job.view_box
        pixels = pixels[y0:y1, x0:x1]
    return np.ascontiguousarray(pixels)


def measure_mode(job: Job) -> str:
    """The anchor measurement used for rest checks (explicit anchors are compared in stance mode)."""
    return job.anchor_mode if job.anchor_mode in forge_core.ANCHOR_MODES else "stance"


# --------------------------------------------------------------------------- the transform

@dataclass(frozen=True)
class VideoFit:
    """How the provider canvas maps onto the returned video: video = k * reference + c."""

    requested: str
    applied: str
    size: tuple[int, int]
    k: tuple[float, float]
    c: tuple[float, float]


def video_fit(canvas: Sequence[int], size: Sequence[int], fit: str) -> VideoFit:
    """stretch: separate x/y factors (sx = W/1280, sy = H/720). cover: one factor, centred
    crop (Grok's 1264x720 from 1280x720 is a fixed centre crop). contain: one factor,
    centred letterbox. auto: one factor when the aspect ratios match (960x960 from a square
    input), otherwise cover."""
    (ref_w, ref_h), (width, height) = canvas, size
    ratio_x, ratio_y = width / ref_w, height / ref_h
    same_aspect = width * ref_h == height * ref_w
    applied = ("uniform" if same_aspect else "cover") if fit == "auto" else fit
    if applied == "stretch":
        return VideoFit(fit, applied, (width, height), (ratio_x, ratio_y), (0.0, 0.0))
    factor = ratio_x if applied == "uniform" else (max if applied == "cover" else min)(ratio_x, ratio_y)
    centre = ((width - factor * ref_w) / 2, (height - factor * ref_h) / 2)
    return VideoFit(fit, applied, (width, height), (factor, factor), centre)


def anchor_in_video(job: Job, fit: VideoFit) -> tuple[float, float]:
    """Video position of the source anchor: k * (offset + scale * anchor) + c."""
    ax, ay = job.source_anchor
    return (fit.k[0] * (job.offset[0] + job.scale * ax) + fit.c[0],
            fit.k[1] * (job.offset[1] + job.scale * ay) + fit.c[1])


def output_scale(job: Job, fit: VideoFit) -> tuple[float, float]:
    """Output px per video px on each axis."""
    return 1.0 / (fit.k[0] * job.scale), 1.0 / (fit.k[1] * job.scale)


def video_to_output(job: Job, fit: VideoFit, padding: Sequence[int], point: Sequence[float],
                    shift: Sequence[int] = (0, 0)) -> tuple[float, float]:
    sx, sy = output_scale(job, fit)
    vx, vy = anchor_in_video(job, fit)
    return (job.source_anchor[0] + padding[0] + shift[0] + (point[0] - vx) * sx,
            job.source_anchor[1] + padding[1] + shift[1] + (point[1] - vy) * sy)


def _local_unpremultiply(planes: Sequence[np.ndarray]) -> np.ndarray:
    """forge_core's unpremultiply: colour divided by the unclipped alpha, RGB zeroed under alpha 0."""
    alpha = planes[3]
    alpha8 = np.floor(np.clip(alpha, 0.0, 1.0) * 255.0 + 0.5).astype(np.uint8)
    premultiplied = np.clip(np.stack(planes[:3], axis=-1), 0.0, None)
    rgb = np.clip(np.floor(premultiplied / np.maximum(alpha, 1e-6)[..., None] + 0.5), 0, 255).astype(np.uint8)
    rgb[alpha8 == 0] = 0
    return np.dstack([rgb, alpha8])


_LOCAL_FILTERS = {"box": (Image.Resampling.BOX, 0.5), "lanczos": (Image.Resampling.LANCZOS, 3.0)}


def _local_resample_anisotropic(pixels: np.ndarray, scale_xy: Sequence[float], resampler: str,
                                anchor_src: Sequence[float], anchor_dst: Sequence[float],
                                out_size: Sequence[int]) -> np.ndarray:
    """forge_core.resample_rgba's anchor-pinned path with separate x and y scales.

    Needed only for --fit stretch with a provider that changed the aspect ratio
    (handoff section 6 asks to promote it as resample_rgba(scale=(sx, sy))). Same
    premultiplied float planes, the same box filter for reductions of 2x or more and
    the same padded canvas, so Pillow never renormalises a clipped window.
    """
    if resampler == "nearest":
        raise ValueError("nearest needs one integer scale; a stretched fit has two scales (use lanczos or box)")
    scale_x, scale_y = float(scale_xy[0]), float(scale_xy[1])
    resample_filter, support = _LOCAL_FILTERS["box" if resampler == "box" or min(scale_x, scale_y) <= 0.5
                                              else resampler]
    pad_x = math.ceil(support * max(1.0, 1.0 / scale_x)) + 2
    pad_y = math.ceil(support * max(1.0, 1.0 / scale_y)) + 2
    base_x, base_y = math.floor(anchor_src[0]), math.floor(anchor_src[1])
    left = anchor_src[0] - base_x - anchor_dst[0] / scale_x
    top = anchor_src[1] - base_y - anchor_dst[1] / scale_y
    span_x, span_y = out_size[0] / scale_x, out_size[1] / scale_y
    col0, row0 = math.floor(left) - pad_x, math.floor(top) - pad_y
    col1, row1 = math.ceil(left + span_x) + pad_x, math.ceil(top + span_y) + pad_y
    canvas = np.zeros((row1 - row0, col1 - col0, 4), np.float32)
    height, width = pixels.shape[:2]
    src_x0, src_x1 = max(0, base_x + col0), min(width, base_x + col1)
    src_y0, src_y1 = max(0, base_y + row0), min(height, base_y + row1)
    if src_x0 < src_x1 and src_y0 < src_y1:
        region = pixels[src_y0:src_y1, src_x0:src_x1].astype(np.float32)
        alpha = region[..., 3:] / 255.0
        cy, cx = src_y0 - (base_y + row0), src_x0 - (base_x + col0)
        canvas[cy:cy + region.shape[0], cx:cx + region.shape[1], :3] = region[..., :3] * alpha
        canvas[cy:cy + region.shape[0], cx:cx + region.shape[1], 3] = alpha[..., 0]
    box = (left - col0, top - row0, left - col0 + span_x, top - row0 + span_y)
    planes = [np.asarray(Image.fromarray(np.ascontiguousarray(canvas[..., channel])).resize(
        tuple(int(v) for v in out_size), resample_filter, box=box)) for channel in range(4)]
    return _local_unpremultiply(planes)


def register_frame(pixels: np.ndarray, job: Job, fit: VideoFit, padding: Sequence[int],
                   out_size: Sequence[int], resampler: str, shift: Sequence[int] = (0, 0)) -> np.ndarray:
    """One frame through the clip's single inverse transform: the job anchor lands exactly
    on (anchor + padding + shift) with the exact scale (premultiplied, grid pinned)."""
    scale_x, scale_y = output_scale(job, fit)
    source = anchor_in_video(job, fit)
    target = (job.source_anchor[0] + padding[0] + shift[0], job.source_anchor[1] + padding[1] + shift[1])
    if scale_x == scale_y:
        return np.asarray(forge_core.resample_rgba(pixels, scale_x, resampler, anchor_src=source, anchor_dst=target,
                                                   out_size=tuple(out_size)))
    return _local_resample_anisotropic(pixels, (scale_x, scale_y), resampler, source, target, out_size)


def place_in_video(view: np.ndarray, job: Job, fit: VideoFit) -> np.ndarray:
    """The master as the provider was asked to reproduce it, in video px (perfect matte)."""
    scale = (fit.k[0] * job.scale, fit.k[1] * job.scale)
    target = (fit.k[0] * job.offset[0] + fit.c[0], fit.k[1] * job.offset[1] + fit.c[1])
    if scale[0] == scale[1]:
        integral = all(float(value).is_integer() for value in (scale[0], *target))
        resampler = "nearest" if job.pixel_art and integral else "lanczos"
        return np.asarray(forge_core.resample_rgba(view, scale[0], resampler, anchor_src=(0.0, 0.0),
                                                   anchor_dst=target, out_size=fit.size))
    return _local_resample_anisotropic(view, scale, "lanczos", (0.0, 0.0), target, fit.size)


# --------------------------------------------------------------------------- silhouette measurements

@dataclass(frozen=True)
class Silhouette:
    """The body inside the 50% alpha contour."""

    mask: np.ndarray
    box: tuple[int, int, int, int]
    ground: int        # bottom edge of the lowest row with >= min_run body px
    centroid_x: float
    area: int

    @property
    def height(self) -> int:
        return self.ground - self.box[1]


def silhouette(alpha: np.ndarray, min_run: int) -> Silhouette | None:
    mask = alpha > CONTOUR
    box = _bbox(mask)
    if box is None:
        return None
    try:
        ground = forge_core.ground_row(mask, min_run=min_run)
    except ValueError:
        ground = box[3]
    columns = np.nonzero(mask)[1]
    return Silhouette(mask, box, ground, float(columns.mean()) + 0.5, int(columns.size))


def hip_x(mask: np.ndarray, ground: float, height: float) -> float | None:
    """Body root x (game-opus55 _hip): per row of the hip band (0.55 to 0.25 of the rest height
    above the ground line), the centre of the widest run; blades and scarf tips are never it."""
    first = max(0, _round_half_up(ground - 0.55 * height))
    last = min(mask.shape[0], _round_half_up(ground - 0.25 * height))
    centres = []
    for row in mask[first:last]:
        edges = np.diff(np.concatenate(([0], row.astype(np.int8), [0])))
        starts, ends = np.flatnonzero(edges == 1), np.flatnonzero(edges == -1)
        if starts.size:
            widest = int(np.argmax(ends - starts))
            centres.append((starts[widest] + ends[widest]) / 2)
    return float(np.median(centres)) if centres else None


def anchor_band(height: int) -> int:
    return max(2, _round_half_up(0.04 * height))


# --------------------------------------------------------------------------- profiles

def _identity_from_job(job: Job) -> dict[str, Any]:
    return {"masterSha256": job.master_sha256, "sourceSize": list(job.source_size),
            "sourceAnchor": list(job.source_anchor), "scale": job.scale, "anchorMode": job.anchor_mode}


def _identity_from_registration(doc: dict[str, Any]) -> dict[str, Any]:
    return {"masterSha256": doc["master"]["sha256"], "sourceSize": doc["baseSize"], "sourceAnchor": doc["baseAnchor"],
            "scale": doc["referenceScale"], "anchorMode": doc["anchorMode"]}


def _identity_from_profile(doc: dict[str, Any]) -> dict[str, Any]:
    registration = doc["registration"]
    return {"masterSha256": registration.get("masterSha256"), "sourceSize": doc["sourceSize"],
            "sourceAnchor": doc["sourceAnchor"], "scale": registration["scale"],
            "anchorMode": registration["anchorMode"]}


def identity_mismatches(expected: dict[str, Any], actual: dict[str, Any], scale_tolerance: float) -> list[str]:
    """Differences that would make two clips of one character disagree (master, canvas,
    anchor, reference scale, anchor mode)."""
    problems = []
    shas = expected.get("masterSha256"), actual.get("masterSha256")
    if all(shas) and shas[0] != shas[1]:
        problems.append("master differs (sha256 mismatch)")
    if list(expected["sourceSize"]) != list(actual["sourceSize"]):
        problems.append(f"sourceSize {list(actual['sourceSize'])} != {list(expected['sourceSize'])}")
    if max(abs(float(a) - float(b)) for a, b in zip(expected["sourceAnchor"], actual["sourceAnchor"])) > 0.01:
        problems.append(f"sourceAnchor {list(actual['sourceAnchor'])} != {list(expected['sourceAnchor'])}")
    reference = float(expected["scale"])
    if abs(float(actual["scale"]) - reference) > scale_tolerance * reference:
        problems.append(f"referenceScale {float(actual['scale']):g} != {reference:g} (tolerance "
                        f"{scale_tolerance:.1%}; a different scale changes the generated detail and motion size)")
    if expected["anchorMode"] != actual["anchorMode"]:
        problems.append(f"anchorMode {actual['anchorMode']} != {expected['anchorMode']}")
    return problems


def _load_document(path: str | Path, schema: str) -> dict[str, Any]:
    path = Path(path)
    try:
        data = forge_core.read_json(path)  # UTF-8 with or without a BOM (D28)
    except (OSError, ValueError) as error:
        raise ValueError(f"Cannot read {path.name}: {error}") from None
    if not isinstance(data, dict) or data.get("schema") != schema:
        raise ValueError(f"{path.name} is not a {schema} document")
    return data


def load_registration(path: str | Path) -> dict[str, Any]:
    data = _load_document(path, REGISTRATION_SCHEMA)
    for field in ("master", "baseSize", "baseAnchor", "referenceScale", "anchorMode", "clip", "padding",
                  "sourceSize", "sourceAnchor", "mode"):
        if field not in data:
            raise ValueError(f"{Path(path).name} lacks {field}")
    return data


def load_profile(path: str | Path) -> dict[str, Any]:
    data = _load_document(path, PROFILE_SCHEMA)
    if not isinstance(data.get("registration"), dict) or "scale" not in data["registration"]:
        raise ValueError(f"{Path(path).name} lacks registration.scale")
    for field in ("sourceSize", "sourceAnchor", "clips"):
        if field not in data:
            raise ValueError(f"{Path(path).name} lacks {field}")
    return data


# --------------------------------------------------------------------------- apply

def _fx_edge_fade(job: Job, fit: VideoFit, padding: Sequence[int], out_size: Sequence[int],
                  fade_px: float) -> tuple[np.ndarray, list[float]]:
    """Smoothstep falloff toward the edge of what the provider could draw: the output canvas
    clipped to the video footprint, so escaping energy dissipates before any hard edge."""
    x0, y0 = video_to_output(job, fit, padding, (0.0, 0.0))
    x1, y1 = video_to_output(job, fit, padding, fit.size)
    rect = [max(0.0, x0), max(0.0, y0), min(float(out_size[0]), x1), min(float(out_size[1]), y1)]
    xs = np.arange(out_size[0]) + 0.5
    ys = np.arange(out_size[1]) + 0.5
    # distance of each pixel centre from the edge, minus half a pixel: the outermost pixels are 0
    dx = np.minimum(xs - rect[0], rect[2] - xs) - 0.5
    dy = np.minimum(ys - rect[1], rect[3] - ys) - 0.5
    distance = np.minimum(dy[:, None], dx[None, :])
    ramp = np.clip(distance / max(fade_px, 1e-6), 0.0, 1.0)
    return ramp * ramp * (3.0 - 2.0 * ramp), [round(value, 4) for value in rect]


def _fx_time_fade(index: int, count: int, fade_in: int, tail: int) -> float:
    """Dusk FX alpha envelope: min(1, i / fade_in, (n - 1 - i) / tail)."""
    factor = 1.0
    if fade_in > 0:
        factor = min(factor, index / fade_in)
    if tail > 0:
        factor = min(factor, (count - 1 - index) / tail)
    return max(0.0, factor)


def _scale_alpha(pixels: np.ndarray, factor: Any) -> np.ndarray:
    out = pixels.copy()
    out[..., 3] = np.floor(pixels[..., 3].astype(np.float64) * factor + 0.5).astype(np.uint8)
    out[out[..., 3] == 0] = 0
    return out


def _contact_sheet(samples: Sequence[np.ndarray], padding: Sequence[int], base_size: Sequence[int],
                   anchor: Sequence[float], tile: int = 160, columns: int = 6) -> Image.Image:
    """Review sheet: sampled frames on slate with the base canvas and the anchor drawn."""
    height, width = samples[0].shape[:2]
    factor = min(1.0, tile / max(width, height))
    tile_w, tile_h = max(1, _round_half_up(width * factor)), max(1, _round_half_up(height * factor))
    rows = math.ceil(len(samples) / columns)
    count = min(columns, len(samples))
    sheet = Image.new("RGB", (count * (tile_w + 8) + 8, rows * (tile_h + 8) + 8), (24, 30, 38))
    for index, frame in enumerate(samples):
        small = (forge_core.resample_rgba(frame, factor, "box", out_size=(tile_w, tile_h)) if factor < 1
                 else Image.fromarray(frame))
        cell = Image.new("RGB", (tile_w, tile_h), (58, 66, 76))
        cell.paste(small, (0, 0), small)
        draw = ImageDraw.Draw(cell)
        left, top = padding[0] * factor, padding[1] * factor
        draw.rectangle([left, top, left + base_size[0] * factor - 1, top + base_size[1] * factor - 1],
                       outline=(150, 150, 150))
        ax, ay = anchor[0] * factor, anchor[1] * factor
        draw.line([ax - 5, ay, ax + 5, ay], fill=(0, 230, 255))
        draw.line([ax, ay - 5, ax, ay + 5], fill=(0, 230, 255))
        row, column = divmod(index, columns)
        sheet.paste(cell, (8 + column * (tile_w + 8), 8 + row * (tile_h + 8)))
    return sheet


def _frame_list_text(indices: Sequence[int], limit: int = 12) -> str:
    shown = ", ".join(str(index) for index in indices[:limit])
    return shown + (f" and {len(indices) - limit} more" if len(indices) > limit else "")


@dataclass(frozen=True)
class ApplyPlan:
    """Everything apply needs before it touches a frame."""

    job: Job
    view: np.ndarray
    all_files: list[Path]
    files: list[Path]
    start: int
    padding: tuple[int, int, int, int]
    out_size: tuple[int, int]
    out_anchor: tuple[float, float]
    fit: VideoFit
    resampler: str
    min_run: int
    rest_frames: list[int]
    fx: bool


def _plan_apply(args: argparse.Namespace, character: dict[str, Any] | None) -> ApplyPlan:
    job = load_job(args.job)
    if character:
        problems = identity_mismatches(_identity_from_profile(character), _identity_from_job(job), args.scale_tolerance)
        if problems:
            raise ValueError(f"Profile mismatch with {Path(args.character_profile).name} "
                             f"(id {character.get('id')}): " + "; ".join(problems))
    inherited = (character or {}).get("registration", {})
    fit_name = args.fit or inherited.get("fit") or "auto"
    resampler = args.resampler or inherited.get("resampler") or "lanczos"
    min_run = args.ground_min_run or inherited.get("groundMinRun") or DEFAULT_GROUND_MIN_RUN
    if fit_name not in FITS or resampler not in forge_core.RESAMPLERS:
        raise ValueError(f"The profile's fit {fit_name!r} or resampler {resampler!r} is unknown")
    fx = args.profile == "fx"
    if fx and args.lock:
        raise ValueError("--lock pins a body to the ground; it does not apply to --profile fx")
    view = load_master_view(job)
    all_files = list_frames(args.frames, args.pattern)
    total = len(all_files)
    start, end = args.range if args.range else (0, None)
    end = total if end is None else min(end, total)
    if start >= end:
        raise ValueError(f"--range selects no frames out of {total}")
    files = all_files[start:end]
    rest_frames = ([] if fx else [0]) if args.rest_frames is None else args.rest_frames
    if rest_frames and rest_frames[-1] >= total:
        raise ValueError(f"--rest-frames {rest_frames} exceed the {total} frames in {Path(args.frames).name}")
    padding = tuple(args.action_padding) if args.action_padding else job.padding
    if fx and not args.action_padding and not any(padding):
        padding = prep.default_padding(prep.ACTIONS["fx"], job.source_size)
    width, height = job.source_size
    out_size = (width + padding[0] + padding[2], height + padding[1] + padding[3])
    out_anchor = (job.source_anchor[0] + padding[0], job.source_anchor[1] + padding[1])
    first, _ = _load_pixels(files[0])
    if not fx and int(first[..., 3].min()) == 255:
        raise ValueError(f"{files[0].name} is opaque: register keyed RGBA frames "
                         "(video2dsprite process frames-clean), not raw video frames")
    fit = video_fit(job.canvas, (first.shape[1], first.shape[0]), fit_name)
    return ApplyPlan(job, view, all_files, files, start, padding, out_size, out_anchor, fit, resampler, int(min_run),
                     rest_frames, fx)


def _load_frame(plan: ApplyPlan, path: Path) -> tuple[np.ndarray, str]:
    pixels, digest = _load_pixels(path)
    if (pixels.shape[1], pixels.shape[0]) != plan.fit.size:
        raise ValueError(f"{path.name} is {pixels.shape[1]}x{pixels.shape[0]}; the clip's frames are "
                         f"{plan.fit.size[0]}x{plan.fit.size[1]}")
    return pixels, digest


def _rest_pass(plan: ApplyPlan, mode: str, band: int) -> list[dict[str, Any]]:
    """Register the rest frames (source indices, inside or outside --range) without locks and
    measure them (anchor, foot line, x, hip)."""
    measures = []
    for index in plan.rest_frames:
        pixels, _ = _load_frame(plan, plan.all_files[index])
        registered = register_frame(pixels, plan.job, plan.fit, plan.padding, plan.out_size, plan.resampler)
        sil = silhouette(registered[..., 3], plan.min_run)
        if sil is None:
            continue
        measures.append({"frame": index, "anchor": forge_core.anchor_from_mask(sil.mask, mode, band_rows=band),
                         "ground": sil.ground, "height": sil.height, "area": sil.area, "x": sil.centroid_x,
                         "hip": hip_x(sil.mask, sil.ground, sil.height)})
    return measures


def _lock_targets(rest: list[dict[str, Any]], master: Silhouette, master_hip: float | None,
                  padding: Sequence[int]) -> dict[str, Any]:
    """Locks pin every frame to the rest pose as registered (the same measurement, so resampling
    blur adds no bias); without rest frames, to the master."""
    if rest:
        hips = [item["hip"] for item in rest if item["hip"] is not None]
        return {"source": "rest", "ground": _round_half_up(float(np.median([item["ground"] for item in rest]))),
                "x": float(np.median([item["x"] for item in rest])),
                "hip": float(np.median(hips)) if hips else None,
                "height": float(np.median([item["height"] for item in rest]))}
    return {"source": "master", "ground": master.ground + padding[1], "x": master.centroid_x + padding[0],
            "hip": None if master_hip is None else master_hip + padding[0], "height": float(master.height)}


def _lock_shift(sil: Silhouette, locks: Sequence[str], targets: dict[str, Any],
                lock_max: int | None) -> tuple[tuple[int, int], bool]:
    """Whole-output-pixel shift that pins the foot line (feet) and x (centroid or hip band);
    whole pixels keep the sampling phase identical in every frame (game-opus55)."""
    dx = dy = 0
    if "feet" in locks:
        dy = targets["ground"] - sil.ground
    if "x" in locks:
        dx = _round_half_up(targets["x"] - sil.centroid_x)
    elif "hip" in locks:
        hip = hip_x(sil.mask, targets["ground"], targets["height"])
        dx = 0 if hip is None else _round_half_up(targets["hip"] - hip)
    clipped = lock_max is not None and max(abs(dx), abs(dy)) > lock_max
    if clipped:
        dx, dy = int(np.clip(dx, -lock_max, lock_max)), int(np.clip(dy, -lock_max, lock_max))
    return (int(dx), int(dy)), clipped


def _register_locked(pixels: np.ndarray, plan: ApplyPlan, locks: Sequence[str], targets: dict[str, Any],
                     lock_max: int | None, margin: int) -> tuple[np.ndarray, int | None, tuple[int, int], bool]:
    """Register one frame and apply the locks.

    With locks the frame is registered once onto the canvas grown by ``margin`` along the
    locked axes, measured there, and the output canvas is cropped at the whole-pixel lock
    shift (the pixels a shifted registration gives); a shift beyond the margin is registered
    again. Returns the frame, its unshifted foot line in canvas coordinates (None when
    empty), the shift and whether --lock-max clipped it.
    """
    width, height = plan.out_size
    if not locks:
        registered = register_frame(pixels, plan.job, plan.fit, plan.padding, plan.out_size, plan.resampler)
        sil = silhouette(registered[..., 3], plan.min_run)
        return registered, None if sil is None else sil.ground, (0, 0), False
    mx = margin if ("x" in locks or "hip" in locks) else 0
    my = margin if "feet" in locks else 0
    grown = (plan.padding[0] + mx, plan.padding[1] + my, plan.padding[2] + mx, plan.padding[3] + my)
    wide = register_frame(pixels, plan.job, plan.fit, grown, (width + 2 * mx, height + 2 * my), plan.resampler)
    sil = silhouette(wide[..., 3], plan.min_run)
    if sil is None:
        return wide[my:my + height, mx:mx + width].copy(), None, (0, 0), False
    moved = {"ground": targets["ground"] + my, "x": targets["x"] + mx, "height": targets["height"],
             "hip": None if targets["hip"] is None else targets["hip"] + mx}
    (dx, dy), clipped = _lock_shift(sil, locks, moved, lock_max)
    if abs(dx) <= mx and abs(dy) <= my:
        registered = wide[my - dy:my - dy + height, mx - dx:mx - dx + width].copy()
    else:
        registered = register_frame(pixels, plan.job, plan.fit, plan.padding, plan.out_size, plan.resampler, (dx, dy))
    return registered, sil.ground - my, (dx, dy), clipped


def _overflow(plan: ApplyPlan, box: Sequence[int], shift: Sequence[int]) -> list[float]:
    """How far (output px) a source subject box reaches past each side of the output canvas."""
    x0, y0 = video_to_output(plan.job, plan.fit, plan.padding, box[:2], shift)
    x1, y1 = video_to_output(plan.job, plan.fit, plan.padding, box[2:], shift)
    return [-x0, -y0, x1 - plan.out_size[0], y1 - plan.out_size[1]]


def cmd_apply(args: argparse.Namespace) -> dict[str, Any]:
    character = load_profile(args.character_profile) if args.character_profile else None
    plan = _plan_apply(args, character)
    job, padding, out_size, count = plan.job, plan.padding, plan.out_size, len(plan.files)
    master_sil = silhouette(plan.view[..., 3], plan.min_run)
    if master_sil is None:
        raise ValueError("The master has no visible pixels (alpha > 16)")
    band = anchor_band(master_sil.height)
    mode = measure_mode(job)
    master_anchor = forge_core.anchor_from_mask(master_sil.mask, mode, band_rows=band)
    master_hip = hip_x(master_sil.mask, master_sil.ground, master_sil.height)
    rest_measures = _rest_pass(plan, mode, band)
    locks = args.lock or []
    targets = _lock_targets(rest_measures, master_sil, master_hip, padding)
    if "hip" in locks and targets["hip"] is None:
        raise ValueError("The rest pose has no hip band to lock to")
    fade = None
    fade_rect: list[float] = []
    fade_px, tail = 0.0, 0
    if plan.fx:
        fade_px = args.edge_fade if args.edge_fade is not None else max(1.0, FX_EDGE_FADE * min(out_size))
        fade, fade_rect = _fx_edge_fade(job, plan.fit, padding, out_size, fade_px)
        tail = max(FX_DISSOLVE_MIN_FRAMES, _round_half_up(args.dissolve_tail * count)) if args.dissolve_tail > 0 else 0

    lock_margin = args.lock_max if args.lock_max is not None else max(8, _round_half_up(LOCK_MARGIN * max(out_size)))
    output = Path(args.output_dir)
    final = output.parent.resolve() / output.name
    contact = sorted({_round_half_up(i * (count - 1) / max(1, min(12, count) - 1)) for i in range(min(12, count))})
    samples: list[np.ndarray] = []
    records: list[dict[str, Any]] = []
    video_edge, overflow_frames, empty_frames, clipped_locks = [], [], [], []
    needed = [0.0, 0.0, 0.0, 0.0]
    hygiene = {"floor_px": 0, "max_removed_alpha": 0, "frames": []}
    with forge_core.staged_output(output) as stage:
        (stage / "frames").mkdir()
        for index, path in enumerate(plan.files):
            pixels, digest = _load_frame(plan, path)
            source_box = forge_core.subject_bbox(pixels[..., 3])
            if source_box is not None and (min(source_box[:2]) == 0 or source_box[2] == plan.fit.size[0]
                                           or source_box[3] == plan.fit.size[1]):
                video_edge.append(index)
            registered, ground_line, shift, clipped = _register_locked(pixels, plan, locks, targets, args.lock_max,
                                                                        lock_margin)
            native = None if ground_line is None else ground_line - padding[1]
            if ground_line is None:
                empty_frames.append(index)
            if clipped:
                clipped_locks.append(index)
            if source_box is not None:
                over = _overflow(plan, source_box, shift)
                if max(over) > 0.5:
                    overflow_frames.append(index)
                    needed = [max(need, value) for need, value in zip(needed, over)]
            if plan.fx:
                registered = _scale_alpha(registered, fade * _fx_time_fade(index, count, args.fade_in_frames, tail))
            # D18: lanczos resampling (forge_core.resample_rgba) rings just outside edges and unpremultiplying
            # alpha 1-4 invents saturated, often key-leaning colours; they are invisible but read as key spill.
            cleaned, floor = forge_core.alpha_hygiene(registered, mode="floor", floor=HYGIENE_FLOOR)
            if floor["floor_px"]:
                registered = np.asarray(cleaned)
                hygiene["floor_px"] += floor["floor_px"]
                hygiene["max_removed_alpha"] = max(hygiene["max_removed_alpha"], floor["max_removed_alpha"])
                hygiene["frames"].append(index)
            name = f"frames/frame_{index:06d}.png"
            forge_core.save_png(registered, stage / name)
            records.append({"file": name, "sha256": forge_core.sha256_file(stage / name),
                            "sourceIndex": plan.start + index, "sourceFile": path.name, "sourceSha256": digest,
                            "shift": list(shift), "nativeFootBottom": native})
            if index in contact:
                samples.append(registered)
        checks, failures = _apply_checks(plan.fx, args, video_edge, overflow_frames, needed, padding, empty_frames,
                                         clipped_locks, plan.rest_frames, rest_measures, master_anchor, master_sil)
        if failures:
            raise RegistrationQAError("registration QA failed, nothing was written: " + "; ".join(failures))
        forge_core.save_png(np.asarray(_contact_sheet(samples, padding, job.source_size, plan.out_anchor)),
                            stage / "review-contact.png")
        document = _registration_document(args, plan, final, records, checks, master_sil, master_hip, master_anchor,
                                          band, rest_measures, targets, contact, character)
        document["hygiene"] = {"mode": "floor", "floor": HYGIENE_FLOOR, "floor_px": hygiene["floor_px"],
                               "max_removed_alpha": hygiene["max_removed_alpha"],
                               "frames_changed": len(hygiene["frames"]),
                               "method": "forge_core.alpha_hygiene(mode='floor', floor=4) after resampling, locks and "
                                         "fx fades: pixels with 0 < alpha <= 4 become (0, 0, 0, 0) (D18)"}
        if plan.fx:
            document["fx"] = {"edgeFadePx": fade_px, "fadeRect": fade_rect, "fadeInFrames": args.fade_in_frames,
                              "dissolveTailFrames": tail}
        forge_core.write_json(stage / REGISTRATION_FILE, document)
    warnings = [f"{check['id']}: {check['value']}" for check in checks if check["status"] == "warn"]
    for warning in warnings:
        print("warning: " + _ascii(warning), file=sys.stderr)
    return {"output": str(final), "metadata": str(final / REGISTRATION_FILE), "frames": count,
            "sourceSize": list(out_size), "sourceAnchor": list(plan.out_anchor), "fitApplied": plan.fit.applied,
            "qa": "needs-visual-review", "warnings": len(warnings)}


def _registration_document(args: argparse.Namespace, plan: ApplyPlan, final: Path, records: list[dict[str, Any]],
                           checks: list[dict[str, Any]], master_sil: Silhouette, master_hip: float | None,
                           master_anchor: Sequence[float], band: int, rest_measures: list[dict[str, Any]],
                           targets: dict[str, Any], contact: list[int],
                           character: dict[str, Any] | None) -> dict[str, Any]:
    """registration.json (video2dsprite.registration.v1; schema requested in the B06 handoff)."""
    job, padding, fit = plan.job, plan.padding, plan.fit
    rest = None
    if rest_measures:
        anchor = [float(np.median([item["anchor"][axis] for item in rest_measures])) for axis in (0, 1)]
        expected = [master_anchor[0] + padding[0], master_anchor[1] + padding[1]]
        rest = {"frames": [item["frame"] for item in rest_measures],
                "nativeFootBottom": float(np.median([item["ground"] for item in rest_measures])) - padding[1],
                "anchor": anchor, "anchorExpected": expected,
                "anchorError": [round(anchor[axis] - expected[axis], 4) for axis in (0, 1)],
                "heightRatio": float(np.median([item["height"] for item in rest_measures])) / master_sil.height,
                "areaRatio": float(np.median([item["area"] for item in rest_measures])) / master_sil.area}
    feet = [record["nativeFootBottom"] for record in records if record["nativeFootBottom"] is not None]
    scale_x, scale_y = output_scale(job, fit)
    anchor_video = anchor_in_video(job, fit)
    display_scale = args.display_scale
    if display_scale is None and plan.fx:
        display_scale = max(plan.out_size) / max(job.source_size)
    master_ref = {"path": ref_path(job.master_path, final), "sha256": job.master_sha256}
    document: dict[str, Any] = {
        "schema": REGISTRATION_SCHEMA,
        "mode": "construction",
        "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
        "clip": args.clip or job.action,
        "action": job.action,
        "profile": args.profile,
        "jobSha256": job.sha256,
        "job": {"path": ref_path(job.path, final), "sha256": job.sha256},
        "master": {**master_ref, "size": list(job.master_size), "anchor": job.data["master"]["anchor"],
                   **({"viewBox": list(job.view_box)} if job.view_box else {})},
        "anchorMode": job.anchor_mode,
        "keyColor": job.key,
        "referenceCanvas": list(job.canvas),
        "referenceScale": job.scale,
        "referenceOffset": list(job.offset),
        "baseSize": list(job.source_size),
        "baseAnchor": list(job.source_anchor),
        "padding": list(padding),
        "sourceSize": list(plan.out_size),
        "sourceAnchor": list(plan.out_anchor),
        "masterGeometry": {"groundLine": master_sil.ground, "top": master_sil.box[1], "height": master_sil.height,
                           "centroidX": master_sil.centroid_x, "hipX": master_hip, "anchor": list(master_anchor),
                           "anchorBandRows": band},
        "video": {"size": list(fit.size), "frameCount": len(plan.all_files),
                  "range": [plan.start, plan.start + len(records)],
                  "frameDirectory": ref_path(Path(args.frames).resolve(), final)},
        "transform": {
            "fit": fit.requested, "fitApplied": fit.applied, "videoScale": list(fit.k), "videoOffset": list(fit.c),
            "anchorVideo": list(anchor_video), "anchorOutput": list(plan.out_anchor),
            "inverse": {"scale": [scale_x, scale_y], "offset": [plan.out_anchor[0] - anchor_video[0] * scale_x,
                                                                 plan.out_anchor[1] - anchor_video[1] * scale_y]},
            "resampler": plan.resampler,
            "note": "output = video * inverse.scale + inverse.offset + shift; one transform for every frame",
        },
        "lock": {"modes": args.lock or [], "maxShift": args.lock_max, "groundMinRun": plan.min_run,
                 "targets": targets},
        "rest": rest,
        "nativeFootBottomRange": [min(feet), max(feet)] if feet else None,
        "frames": records,
        "review": {"path": "review-contact.png", "frames": contact},
        "qa": {
            "status": "needs-visual-review",
            "method": "register_clip apply v1: one inverse transform from registration_job.v1 (registration by "
                      "construction), forge_core.resample_rgba anchor-pinned premultiplied resampling, then the "
                      "alpha hygiene floor (alpha <= 4 cleared, D18); subject = alpha > 16; edge, overflow and "
                      "rest-pose checks on the source and registered alpha",
            "notProven": ["identity, contact and pose quality (look at review-contact.png and the frames)",
                          "matte quality of the input frames", "loop seams and timing (gait_loop, retime)"],
            "checks": checks,
            "inputs": [_file_ref(job.path, final, job.sha256), master_ref,
                       *({"path": ref_path(path, final), "sha256": record["sourceSha256"]}
                         for path, record in zip(plan.files, records))],
            "outputs": [{"path": record["file"], "sha256": record["sha256"]} for record in records],
            "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
        },
    }
    if display_scale is not None:
        document["displayScale"] = display_scale
    if character:
        document["characterProfile"] = {"path": ref_path(Path(args.character_profile).resolve(), final),
                                        "sha256": forge_core.sha256_file(args.character_profile),
                                        "id": character.get("id")}
    return document


def _apply_checks(fx: bool, args: argparse.Namespace, video_edge: list[int], overflow_frames: list[int],
                  needed: list[float], padding: Sequence[int], empty_frames: list[int], clipped_locks: list[int],
                  rest_frames: list[int], rest_measures: list[dict[str, Any]], master_anchor: Sequence[float],
                  master_sil: Silhouette) -> tuple[list[dict], list[str]]:
    """Registration QA checks and the failure messages (empty when everything passes)."""
    checks: list[dict[str, Any]] = []
    failures: list[str] = []
    soft = fx or args.allow_edge_touch
    status = "warn" if soft else "fail"
    checks.append({"id": "video-edge-touch", "status": status if video_edge else "pass", "value": video_edge,
                   "threshold": 0})
    if video_edge and not soft:
        failures.append(f"video-edge-touch: the subject touches the video frame border in frames "
                        f"{_frame_list_text(video_edge)}; the generator cut it, so regenerate the take (padding cannot "
                        "restore it)")
    extra = [int(math.ceil(value)) if value > 0.5 else 0 for value in needed]
    grown = [base + more for base, more in zip(padding, extra)]
    checks.append({"id": "canvas-overflow", "status": status if overflow_frames else "pass",
                   "value": {"frames": overflow_frames, "neededPadding": extra}, "threshold": 0.5})
    if overflow_frames and not soft:
        failures.append(f"canvas-overflow: the subject leaves the {padding} padded canvas in frames "
                        f"{_frame_list_text(overflow_frames)}; grow the canvas with --action-padding "
                        f"{','.join(str(v) for v in grown)} (never shrink the body)")
    checks.append({"id": "empty-frames", "status": "warn" if empty_frames and not fx else "pass",
                   "value": empty_frames, "threshold": 0})
    if clipped_locks:
        checks.append({"id": "lock-max", "status": "warn", "value": clipped_locks, "threshold": args.lock_max})
    if not rest_frames:
        checks.append({"id": "rest-anchor-error", "status": "skipped", "value": None, "threshold": None})
        checks.append({"id": "rest-scale-error", "status": "skipped", "value": None, "threshold": None})
        return checks, failures
    if not rest_measures:
        checks.append({"id": "rest-anchor-error", "status": "fail", "value": "rest frames are empty",
                       "threshold": args.max_anchor_error})
        failures.append(f"rest-anchor-error: rest frames {rest_frames} have no subject")
        return checks, failures
    expected = (master_anchor[0] + padding[0], master_anchor[1] + padding[1])
    error = max(max(abs(item["anchor"][axis] - expected[axis]) for axis in (0, 1)) for item in rest_measures)
    ok = error <= args.max_anchor_error
    checks.append({"id": "rest-anchor-error", "status": "pass" if ok else "fail", "value": round(error, 4),
                   "threshold": args.max_anchor_error})
    if not ok:
        failures.append(f"rest-anchor-error: the rest pose sits {error:.2f} px from the master's anchor (limit "
                        f"{args.max_anchor_error:g}); the provider changed the framing: check --fit, run qc, or "
                        "regenerate")
    ratio = max(abs(item["height"] / master_sil.height - 1.0) for item in rest_measures)
    ok = ratio <= args.max_scale_error
    checks.append({"id": "rest-scale-error", "status": "pass" if ok else "fail", "value": round(ratio, 5),
                   "threshold": args.max_scale_error})
    if not ok:
        failures.append(f"rest-scale-error: the rest pose height differs from the master by {ratio:.1%} (limit "
                        f"{args.max_scale_error:.1%}); the provider rescaled the take: check --fit or regenerate")
    return checks, failures


# --------------------------------------------------------------------------- profile and validate-profile

def profile_matte(mode: str, key: str, erode: int, unmix: bool | None, despill: str) -> dict[str, Any]:
    """The ``matte`` block video2dsprite --matte-profile reads (D21): ``unmix`` defaults to the soft matte
    (the dominance alpha is a ramp and binary alpha has nothing to un-mix, so only soft may un-mix) and
    ``erode`` is a whole number of px."""
    if mode not in MATTE_MODES:
        raise ValueError(f"--matte-mode must be one of {', '.join(MATTE_MODES)}")
    if unmix and mode != "soft":
        raise ValueError(f"--unmix belongs to the soft matte; a {mode} profile pins unmix false")
    if isinstance(erode, bool) or not isinstance(erode, int) or erode < 0:
        raise ValueError(f"--erode must be a whole number of px >= 0, got {erode!r}")
    return {"mode": mode, "key": key, "erode": erode, "unmix": (mode == "soft") if unmix is None else bool(unmix),
            "despill": despill}


def cmd_profile(args: argparse.Namespace) -> dict[str, Any]:
    output = Path(args.output)
    if output.exists():
        raise FileExistsError(f"Refusing to replace existing output: {output}")
    matte = profile_matte(args.matte_mode, args.key or None, args.erode, args.unmix, args.despill_mode)
    registrations = [(Path(path), load_registration(path)) for path in args.registration]
    reference = registrations[0][1]
    expected = _identity_from_registration(reference)
    clips: dict[str, Any] = {}
    for path, doc in registrations:
        problems = identity_mismatches(expected, _identity_from_registration(doc), args.scale_tolerance)
        if problems:
            raise ValueError(f"{path.name} does not match {registrations[0][0].name}: " + "; ".join(problems))
        if doc["clip"] in clips:
            raise ValueError(f"Two registrations name clip {doc['clip']!r}; pass apply --clip to tell them apart")
        clips[doc["clip"]] = {
            "padding": doc["padding"], "sourceSize": doc["sourceSize"], "sourceAnchor": doc["sourceAnchor"],
            "registration": {"path": ref_path(path.resolve(), output.parent.resolve()),
                             "sha256": forge_core.sha256_file(path)},
            "jobSha256": doc.get("jobSha256"),
            "nativeFootBottom": (doc.get("rest") or {}).get("nativeFootBottom"),
        }
    feet = [clip["nativeFootBottom"] for clip in clips.values() if clip["nativeFootBottom"] is not None]
    geometry = reference.get("masterGeometry", {})
    profile: dict[str, Any] = {
        "schema": PROFILE_SCHEMA,
        "id": args.id,
        "sourceSize": reference["baseSize"],
        "sourceAnchor": reference["baseAnchor"],
        "registration": {
            "scale": reference["referenceScale"], "anchorMode": reference["anchorMode"],
            "masterSha256": reference["master"]["sha256"], "referenceCanvas": reference.get("referenceCanvas"),
            "fit": reference.get("transform", {}).get("fit"),
            "resampler": reference.get("transform", {}).get("resampler"),
            "groundMinRun": reference.get("lock", {}).get("groundMinRun"),
            "restFootBottom": geometry.get("groundLine"),
        },
        "matte": {**matte, "key": matte["key"] or reference.get("keyColor", "magenta")},
        "clips": clips,
        "nativeFootBottomRange": [min(feet), max(feet)] if feet else None,
        "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
    }
    if args.world_scale is not None:
        profile["worldScale"] = args.world_scale
    output.parent.mkdir(parents=True, exist_ok=True)
    forge_core.write_json(output, profile, no_clobber=True)
    final = output.resolve()
    return {"output": str(final), "metadata": str(final), "id": args.id, "clips": sorted(clips),
            "nativeFootBottomRange": profile["nativeFootBottomRange"]}


def cmd_validate_profile(args: argparse.Namespace) -> dict[str, Any]:
    profile = load_profile(args.profile)
    expected = _identity_from_profile(profile)
    rest_line = profile["registration"].get("restFootBottom")
    results = []
    failed = False
    for path in args.registration:
        doc = load_registration(path)
        issues = identity_mismatches(expected, _identity_from_registration(doc), args.scale_tolerance)
        if doc.get("mode") != "construction":
            issues.append(f"mode {doc.get('mode')} is not construction")
        known = profile["clips"].get(doc["clip"])
        if known:
            for field in ("padding", "sourceSize"):
                if list(known[field]) != list(doc[field]):
                    issues.append(f"{field} {doc[field]} != profile clip {known[field]}")
            if max(abs(float(a) - float(b)) for a, b in zip(known["sourceAnchor"], doc["sourceAnchor"])) > 0.01:
                issues.append(f"sourceAnchor {doc['sourceAnchor']} != profile clip {known['sourceAnchor']}")
        foot = (doc.get("rest") or {}).get("nativeFootBottom")
        if foot is not None and rest_line is not None and abs(foot - rest_line) > args.foot_tolerance:
            issues.append(f"rest foot line {foot:g} is {foot - rest_line:+g} px from the profile's {rest_line:g} "
                          f"(tolerance {args.foot_tolerance:g})")
        failed |= bool(issues)
        results.append({"clip": doc["clip"], "registration": Path(path).name, "nativeFootBottom": foot,
                        "clipFootBottomRange": doc.get("nativeFootBottomRange"), "issues": issues})
    feet = [item["nativeFootBottom"] for item in results if item["nativeFootBottom"] is not None]
    foot_range = [min(feet), max(feet)] if feet else None
    spread_ok = foot_range is None or foot_range[1] - foot_range[0] <= args.foot_tolerance
    summary = {"status": "pass" if not failed and spread_ok else "fail", "profile": profile.get("id"),
               "clips": len(results), "nativeFootBottomRange": foot_range,
               "restFootBottom": rest_line, "results": results}
    if summary["status"] == "fail":
        print(json.dumps(summary))
        reasons = [f"{item['clip']}: " + "; ".join(item["issues"]) for item in results if item["issues"]]
        if not spread_ok:
            reasons.append(f"nativeFootBottomRange {foot_range} spreads more than {args.foot_tolerance:g} px")
        raise ValueError("profile validation failed: " + " | ".join(reasons))
    return summary


# --------------------------------------------------------------------------- qc

def _luma(pixels: np.ndarray) -> np.ndarray:
    return pixels[..., :3].astype(np.float32) @ np.array([0.299, 0.587, 0.114], np.float32)


def ncc_search(template: np.ndarray, image: np.ndarray, x0: int, y0: int, search: int) -> dict[str, Any] | None:
    """Best zero-mean NCC of ``template`` (top-left at x0, y0) within +-search px in ``image``."""
    height, width = template.shape
    top, left = y0 - search, x0 - search
    if top < 0 or left < 0 or top + height + 2 * search > image.shape[0] or left + width + 2 * search > image.shape[1]:
        return None
    region = image[top:top + height + 2 * search, left:left + width + 2 * search].astype(np.float64)
    centred = template.astype(np.float64) - template.mean()
    norm = math.sqrt(float((centred * centred).sum()))
    if norm < 1e-6:
        return None
    windows = np.lib.stride_tricks.sliding_window_view(region, (height, width))
    numerator = np.einsum("ijkl,kl->ij", windows, centred)
    count = height * width
    sums = _box_sum(region, height, width)
    squares = _box_sum(region * region, height, width)
    spread = np.sqrt(np.maximum(squares - sums * sums / count, 0.0))
    scores = numerator / np.maximum(spread * norm, 1e-9)
    row, column = np.unravel_index(int(np.argmax(scores)), scores.shape)
    return {"ncc": float(scores[row, column]), "dx": int(column) - search, "dy": int(row) - search}


def pick_landmarks(luma: np.ndarray, subject: np.ndarray, count: int, patch: int, search: int) -> list[tuple[int, int]]:
    """Up to ``count`` well-textured patch corners (top-left) on the subject: Shi-Tomasi
    response over the patch, at least a quarter subject coverage, greedy spacing of one patch."""
    gradient_y, gradient_x = np.gradient(luma.astype(np.float64))
    sxx = _box_sum(gradient_x * gradient_x, patch, patch)
    syy = _box_sum(gradient_y * gradient_y, patch, patch)
    sxy = _box_sum(gradient_x * gradient_y, patch, patch)
    response = (sxx + syy) / 2 - np.sqrt(((sxx - syy) / 2) ** 2 + sxy ** 2)
    coverage = _box_sum(subject.astype(np.float64), patch, patch) / (patch * patch)
    score = np.where(coverage >= 0.25, response, -np.inf)
    score[:search, :] = -np.inf
    score[:, :search] = -np.inf
    score[score.shape[0] - search:, :] = -np.inf
    score[:, score.shape[1] - search:] = -np.inf
    picks: list[tuple[int, int]] = []
    for _ in range(count):
        flat = int(np.argmax(score))
        row, column = divmod(flat, score.shape[1])
        if not np.isfinite(score[row, column]) or score[row, column] <= 1e-6:
            break
        picks.append((column, row))
        score[max(0, row - patch + 1):row + patch, max(0, column - patch + 1):column + patch] = -np.inf
    return picks


def _similarity_scale(points: Sequence[tuple[float, float]], moved: Sequence[tuple[float, float]]) -> float | None:
    if len(points) < 3:
        return None
    source = np.asarray(points, np.float64)
    target = np.asarray(moved, np.float64)
    source_c, target_c = source - source.mean(0), target - target.mean(0)
    denominator = float((source_c * source_c).sum())
    return float((source_c * target_c).sum() / denominator) if denominator > 1e-9 else None


def _band_mask(height: int, width: int, band: int) -> np.ndarray:
    mask = np.zeros((height, width), bool)
    mask[:band] = mask[-band:] = True
    mask[:, :band] = mask[:, -band:] = True
    return mask


def _decimate(image: np.ndarray, target: int = 240) -> tuple[np.ndarray, int]:
    """Every n-th pixel so the short side is about ``target`` px (key estimates, motion measures)."""
    step = max(1, min(image.shape[:2]) // target)
    return image[::step, ::step], step


def _frame_key(pixels: np.ndarray, job: Job, band: int) -> np.ndarray:
    """The take's backdrop key from the border ring of a decimated frame (I2V keys drift)."""
    small, step = _decimate(pixels[..., :3])
    key, _info = forge_matte.estimate_key(small, job.key, ring=max(1, band // step))
    return key


def _subject_mask(pixels: np.ndarray, key: np.ndarray, keyed: bool) -> np.ndarray:
    """Keyed frames: alpha > 16. Raw frames: RGB distance from the key above 64."""
    if keyed:
        return pixels[..., 3] > THRESHOLD
    offset = pixels[..., :3].astype(np.float32) - key
    return np.sqrt((offset * offset).sum(-1)) > QC_SUBJECT_DISTANCE


def _subject_stats(mask: np.ndarray, band: int) -> dict[str, Any] | None:
    box = _bbox(mask)
    if box is None:
        return None
    return {"area": int(mask.sum()), "box": box,
            "anchor": forge_core.anchor_from_mask(mask, "stance", band_rows=band)}


def _take_ids(path: Path) -> set[str]:
    if not path.is_file():
        return set()
    ids = set()
    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        if line.strip():
            try:
                ids.add(str(json.loads(line).get("take")))
            except (ValueError, AttributeError):
                raise ValueError(f"{path.name} line {number} is not a JSON object") from None
    return ids


def cmd_qc(args: argparse.Namespace) -> dict[str, Any]:
    job = load_job(args.job)
    view = load_master_view(job)
    takes = Path(args.takes) if args.takes else job.path.parent / "takes.jsonl"
    take_id = args.take or (Path(args.video).stem if args.video else Path(args.frames).resolve().name)
    if take_id in _take_ids(takes):
        raise ValueError(f"Take {take_id!r} is already recorded in {takes.name}; pass a new --take id")
    with tempfile.TemporaryDirectory(prefix="register-clip-qc-") as scratch:
        if args.video:
            import forge_av  # optional: needs ffmpeg
            fps = _fps_value(forge_av.probe(args.video)["fps_rational"])
            files = forge_av.extract_frames(args.video, Path(scratch) / "frames", alpha="off")
            source = {"kind": "video", "name": Path(args.video).name, "sha256": forge_core.sha256_file(args.video)}
        else:
            files = list_frames(args.frames, args.pattern)
            fps = args.fps
            source = {"kind": "frames", "name": Path(args.frames).resolve().name}
        line = _judge_take(job, view, files, fps, take_id, source, takes, args)
    takes.parent.mkdir(parents=True, exist_ok=True)
    with open(takes, "a", encoding="utf-8", newline="\n") as stream:
        stream.write(json.dumps(line, ensure_ascii=False, allow_nan=False) + "\n")
    summary = {"take": take_id, "status": line["status"], "reasons": line["reasons"],
               "warnings": line["warnings"], "takes": str(takes.resolve()), "metadata": str(takes.resolve())}
    if line["status"] == "rejected" and args.strict:
        print(json.dumps(summary))
        raise ValueError(f"take {take_id} rejected: " + " | ".join(line["reasons"]))
    return summary


def _plain(value: Any) -> Any:
    if isinstance(value, np.generic):
        return value.item()
    raise TypeError(f"{type(value).__name__} is not JSON serializable")


def _fps_value(text: str) -> float:
    numerator, _, denominator = str(text).partition("/")
    return float(numerator) / float(denominator or 1)


@dataclass(frozen=True)
class TakeReference:
    """The master as the job placed it, seen in the take's video px."""

    fit: VideoFit
    luma: np.ndarray
    stats: dict[str, Any]
    stance_band: int
    landmarks: list[tuple[int, int]]
    identity_box: list[int] | None
    identity_step: int
    identity_template: np.ndarray | None


def _identity_box(job: Job, fit: VideoFit, mask: np.ndarray, box: Sequence[int], size: Sequence[int],
                  requested: Sequence[int] | None) -> list[int] | None:
    """--identity-box (master px) in video px, or the head: the top 35% of the subject, as wide as its
    top 20% plus a margin."""
    if requested:
        x0, y0 = (int(math.floor(v)) for v in master_to_video(job, fit, requested[:2]))
        x1, y1 = (int(math.ceil(v)) for v in master_to_video(job, fit, requested[2:]))
    else:
        bx0, by0, bx1, by1 = box
        height = by1 - by0
        crown = np.flatnonzero(mask[by0:by0 + max(1, _round_half_up(0.2 * height))].any(axis=0))
        margin = _round_half_up(0.1 * (crown[-1] + 1 - crown[0]))
        x0, x1 = max(bx0, crown[0] - margin), min(bx1, crown[-1] + 1 + margin)
        y0, y1 = by0, by0 + max(QC_PATCH // 2, _round_half_up(0.35 * height))
    x0, y0 = max(QC_SEARCH, x0), max(QC_SEARCH, y0)
    x1, y1 = min(size[0] - QC_SEARCH, x1), min(size[1] - QC_SEARCH, y1)
    return [x0, y0, x1, y1] if x1 - x0 >= 8 and y1 - y0 >= 8 else None


def _take_reference(job: Job, view: np.ndarray, first: np.ndarray, args: argparse.Namespace) -> TakeReference:
    size = (first.shape[1], first.shape[0])
    fit = video_fit(job.canvas, size, args.fit or "auto")
    placed = place_in_video(view, job, fit)
    rgb = prep.composite_on_key(placed, job.key_rgb)
    luma = _luma(rgb)
    keyed = int(first[..., 3].min()) < 255
    # the reference subject follows the same rule as the frames, so their areas compare without bias
    mask = placed[..., 3] > THRESHOLD if keyed else _subject_mask(rgb, np.asarray(job.key_rgb, np.float32), False)
    box = _bbox(mask)
    if box is None:
        raise ValueError("The master does not land inside the video frame; check the job and --fit")
    stance_band = anchor_band(box[3] - box[1])
    identity = _identity_box(job, fit, mask, box, size, args.identity_box)
    step, template = 1, None
    if identity:
        step = max(1, math.ceil(max(identity[2] - identity[0], identity[3] - identity[1]) / 96))
        template = _block_mean(luma[identity[1]:identity[3], identity[0]:identity[2]], step)
    return TakeReference(fit, luma, _subject_stats(mask, stance_band), stance_band,
                         pick_landmarks(luma, mask, args.landmarks, QC_PATCH, QC_SEARCH), identity, step, template)


def _block_mean(image: np.ndarray, step: int) -> np.ndarray:
    """Mean of step x step blocks (the trailing partial block is dropped)."""
    if step == 1:
        return image
    height, width = (image.shape[0] // step) * step, (image.shape[1] // step) * step
    return image[:height, :width].reshape(height // step, step, width // step, step).mean(axis=(1, 3))


def _sample_scores(reference: TakeReference, luma: np.ndarray, min_ncc: float) -> tuple[dict, dict | None]:
    """Landmark matches (with a similarity-fit scale) and the identity NCC of one sampled frame."""
    matches = [ncc_search(reference.luma[y:y + QC_PATCH, x:x + QC_PATCH], luma, x, y, QC_SEARCH)
               for x, y in reference.landmarks]
    good = [(point, match) for point, match in zip(reference.landmarks, matches)
            if match and match["ncc"] >= min_ncc and abs(match["dx"]) < QC_SEARCH and abs(match["dy"]) < QC_SEARCH]
    half = QC_PATCH / 2
    scale = _similarity_scale([(x + half, y + half) for (x, y), _ in good],
                              [(x + half + m["dx"], y + half + m["dy"]) for (x, y), m in good])
    values = [match["ncc"] for match in matches if match]
    landmarks = {"matched": len(good), "medianNcc": round(float(np.median(values)), 4) if values else None,
                 "scale": None if scale is None else round(scale, 5)}
    identity = None
    if reference.identity_template is not None:
        step = reference.identity_step
        x0, y0 = reference.identity_box[:2]
        search = max(1, math.ceil(QC_SEARCH / step))
        image = _block_mean(luma[y0 % step:, x0 % step:], step)
        match = ncc_search(reference.identity_template, image, x0 // step, y0 // step, search)
        identity = {"ncc": None if match is None else round(match["ncc"], 4),
                    "dx": None if match is None else match["dx"] * step,
                    "dy": None if match is None else match["dy"] * step}
    return landmarks, identity


def _judge_take(job: Job, view: np.ndarray, files: Sequence[Path], fps: float, take_id: str,
                source: dict[str, Any], takes: Path, args: argparse.Namespace) -> dict[str, Any]:
    """Score one raw take; the take.v1 line (with a QA envelope) is returned, not written."""
    first, first_digest = _load_pixels(files[0])
    size = (first.shape[1], first.shape[0])
    keyed = int(first[..., 3].min()) < 255
    reference = _take_reference(job, view, first, args)
    fit = reference.fit
    count = len(files)
    to_source = (1.0 / (fit.k[0] * job.scale), 1.0 / (fit.k[1] * job.scale))
    band = args.edge_band or max(4, int(math.floor(job.margin * min(fit.k) * 0.6)))
    band = min(band, max(1, min(size) // 4))
    band_mask = _band_mask(size[1], size[0], band)
    band_px = int(band_mask.sum())
    calm = max(1, _round_half_up(prep.CALM_SPAN_S * fps))
    start_span = list(range(min(count, calm)))
    end_span = list(range(max(0, count - calm), count)) if job.returns_to_rest and count > calm else []
    samples = sorted({_round_half_up(i * (count - 1) / max(1, min(args.samples, count) - 1))
                      for i in range(min(args.samples, count))})

    edge_frames: list[dict[str, Any]] = []
    key_drift: list[float] = []
    changes: list[float] = []
    poses: dict[int, dict[str, float]] = {}
    landmark_rows: list[dict[str, Any]] = []
    identity_rows: list[dict[str, Any]] = []
    digests: list[str] = []
    base = None
    for index, path in enumerate(files):
        pixels, digest = (first, first_digest) if index == 0 else _load_pixels(path)
        digests.append(digest)
        if (pixels.shape[1], pixels.shape[0]) != size:
            raise ValueError(f"{path.name} is {pixels.shape[1]}x{pixels.shape[0]}; the take is {size[0]}x{size[1]}")
        key = np.asarray(job.key_rgb, np.float32) if keyed else _frame_key(pixels, job, band)
        key_drift.append(float(np.sqrt(((key - np.asarray(job.key_rgb, np.float32)) ** 2).sum())))
        if keyed:
            impure = int((pixels[..., 3][band_mask] > THRESHOLD).sum())
        else:
            ring = pixels[..., :3][band_mask].astype(np.float32) - key
            impure = int(((ring * ring).sum(-1) > forge_matte.KEY_TOLERANCE ** 2).sum())
        if impure > args.max_edge_impure * band_px:
            edge_frames.append({"frame": index, "impurePx": impure, "fraction": round(impure / band_px, 6)})
        small = _luma(_decimate(pixels)[0])
        base = small if base is None else base
        changes.append(float((np.abs(small - base) > QC_CHANGE_LEVELS).mean()))
        if index == 0 or index in end_span:
            stats = _subject_stats(_subject_mask(pixels, key, keyed), reference.stance_band)
            if stats:
                poses[index] = {"scale": math.sqrt(stats["area"] / reference.stats["area"]),
                                "dx": (stats["anchor"][0] - reference.stats["anchor"][0]) * to_source[0],
                                "dy": (stats["anchor"][1] - reference.stats["anchor"][1]) * to_source[1]}
        if index in samples:
            marks, identity = _sample_scores(reference, _luma(pixels), args.min_landmark_ncc)
            landmark_rows.append({"frame": index, **marks})
            if identity:
                identity_rows.append({"frame": index, **identity})
    if source["kind"] == "video":
        inputs = [{"path": source["name"], "sha256": source["sha256"]}]
    else:
        inputs = [{"path": ref_path(path, takes.resolve().parent), "sha256": digest}
                  for path, digest in zip(files, digests)]
    return _take_line(job, reference, take_id, source, takes, args, size, fps, count, band, start_span, end_span,
                      edge_frames, key_drift, changes, poses, landmark_rows, identity_rows, inputs)


def _take_line(job: Job, reference: TakeReference, take_id: str, source: dict[str, Any], takes: Path,
               args: argparse.Namespace, size: Sequence[int], fps: float, count: int, band: int,
               start_span: list[int], end_span: list[int], edge_frames: list[dict[str, Any]], key_drift: list[float],
               changes: list[float], poses: dict[int, dict[str, float]], landmark_rows: list[dict[str, Any]],
               identity_rows: list[dict[str, Any]], inputs: list[dict[str, str]]) -> dict[str, Any]:
    """Gates, warnings and the take.v1 line; ``inputs`` are the take's video or frame file refs."""
    start = poses.get(0)
    end = [poses[index] for index in end_span if index in poses]
    end_scale = float(np.median([pose["scale"] for pose in end])) if end else None
    end_drift = None
    if end:
        end_drift = math.hypot(float(np.median([pose["dx"] for pose in end])),
                               float(np.median([pose["dy"] for pose in end])))
    start_drift = math.hypot(start["dx"], start["dy"]) if start else None
    checks: list[dict[str, Any]] = []
    reasons: list[str] = []
    warnings: list[str] = []

    def gate(check_id: str, ok: bool | None, value: Any, threshold: Any, reason: str) -> None:
        checks.append({"id": check_id, "status": "skipped" if ok is None else ("pass" if ok else "fail"),
                       "value": value, "threshold": threshold})
        if ok is False:
            reasons.append(reason)

    worst = max(edge_frames, key=lambda item: item["fraction"]) if edge_frames else {"fraction": 0.0, "frame": None}
    gate("edge-key-purity", not edge_frames, [item["frame"] for item in edge_frames], args.max_edge_impure,
         f"edge key purity: {len(edge_frames)} frame(s) have non-key pixels in the {band} px border band (worst "
         f"{worst['fraction']:.2%} at frame {worst['frame']}); the subject or an effect leaves the work region or the "
         "background is not flat: regenerate, don't pad")
    first_row = landmark_rows[0] if landmark_rows and landmark_rows[0]["frame"] == 0 else None
    landmarks_ok = None if not reference.landmarks or first_row is None else (
        first_row["matched"] >= 0.5 * len(reference.landmarks))
    gate("landmarks-first-frame", landmarks_ok,
         None if first_row is None else f"{first_row['matched']}/{len(reference.landmarks)}", 0.5,
         f"only {first_row['matched'] if first_row else 0}/{len(reference.landmarks)} landmarks match the reference in "
         f"frame 0 (NCC >= {args.min_landmark_ncc:g}): the take does not start from the supplied image")
    gate("camera-scale-start", None if start is None else abs(start["scale"] - 1) <= args.max_scale_change,
         None if start is None else round(start["scale"], 5), args.max_scale_change,
         f"camera scale {start['scale'] if start else 0:.3f} in frame 0: the take does not start at the reference "
         "scale; check --fit (provider crop or stretch) or regenerate")
    gate("camera-drift-start", None if start_drift is None else start_drift <= args.max_drift,
         None if start_drift is None else round(start_drift, 4), args.max_drift,
         f"frame 0 sits {start_drift or 0:.2f} source px from the reference position: check --fit or regenerate")
    gate("camera-scale-end", None if end_scale is None else abs(end_scale - 1) <= args.max_scale_change,
         None if end_scale is None else round(end_scale, 5), args.max_scale_change,
         f"camera scale {end_scale or 0:.3f} in the end calm span (frames {end_span[0] if end_span else 0}-"
         f"{end_span[-1] if end_span else 0}): push-in or pull-out; regenerate with 'locked camera, fixed scale'")
    calm_identity = [row["ncc"] for row in identity_rows
                     if (row["frame"] == 0 or row["frame"] in end_span) and row["ncc"] is not None]
    identity_min = min(calm_identity) if calm_identity else None
    gate("identity-calm", None if identity_min is None else identity_min >= args.min_identity_ncc,
         identity_min, args.min_identity_ncc,
         f"identity NCC {identity_min or 0:.2f} below {args.min_identity_ncc:g} in a calm frame: the head region "
         "changed or is covered")

    # calm spans: the share of pixels changed from frame 0, relative to the clip's busiest 10% of frames
    busiest = float(np.percentile(changes, 90))
    calm_motion = {}
    for name, span in (("start", start_span), ("end", end_span)):
        if span and busiest > 1e-3:
            calm_motion[name] = round(float(np.median([changes[index] for index in span])) / busiest, 4)
            moving = calm_motion[name] > 0.5
            checks.append({"id": f"calm-{name}", "status": "warn" if moving else "pass",
                           "value": calm_motion[name], "threshold": 0.5})
            if moving:
                warnings.append(f"the {name} calm span is not at the reference pose (it changes "
                                f"{calm_motion[name]:.2f}x as much as the busiest frames): "
                                + ("the take starts moving at once; frame 0 is the only rest frame" if name == "start"
                                   else "the take does not return to the reference pose"))
    if end_drift is not None and end_drift > args.max_drift:
        warnings.append(f"the end calm span sits {end_drift:.2f} source px from the reference: "
                        "consider apply --lock feet")
    all_identity = [row["ncc"] for row in identity_rows if row["ncc"] is not None]
    metrics = {
        "frames": count, "fps": fps, "size": list(size), "fitApplied": reference.fit.applied,
        "calm": {"start": [start_span[0], start_span[-1]] if start_span else None,
                 "end": [end_span[0], end_span[-1]] if end_span else None, "motionRatio": calm_motion},
        "cameraScale": {"start": None if start is None else start["scale"], "end": end_scale,
                        "landmarkFirst": first_row["scale"] if first_row else None,
                        "landmarkLast": landmark_rows[-1]["scale"] if landmark_rows else None},
        "cameraDriftSourcePx": {"start": start_drift, "end": end_drift},
        "landmarks": {"count": len(reference.landmarks), "patch": QC_PATCH, "search": QC_SEARCH,
                      "minNcc": args.min_landmark_ncc, "perFrame": landmark_rows},
        "identity": {"box": reference.identity_box, "minCalm": identity_min,
                     "minAll": min(all_identity) if all_identity else None, "perFrame": identity_rows},
        "edge": {"bandPx": band, "impureFrames": edge_frames},
        "keyDrift": {"median": float(np.median(key_drift)), "max": float(max(key_drift))},
        "changedShareFromFrame0": {"p90": busiest, "levels": QC_CHANGE_LEVELS},
    }
    metrics = json.loads(json.dumps(metrics, default=_plain))  # numpy scalars -> JSON numbers
    job_ref = {"path": ref_path(job.path, takes.resolve().parent), "sha256": job.sha256}
    return {
        "schema": TAKE_SCHEMA,
        "take": take_id,
        "status": "rejected" if reasons else "kept",
        "reasons": reasons,
        "warnings": warnings,
        "metrics": metrics,
        "job": job_ref,
        "action": job.action,
        "source": {**source, "frames": count, "size": list(size), "fps": fps},
        "qa": {
            "status": "fail" if reasons else "needs-visual-review",
            "method": "register_clip qc v1: frame 0 and the end calm span against the master as the job placed it; "
                      "36 px zero-mean NCC landmarks and head-region identity, +-15 px search; subject = RGB "
                      "distance > 64 from the take's border key (alpha > 16 for keyed frames); scale = sqrt of the "
                      "subject area ratio, drift = stance anchor shift",
            "notProven": ["mid-clip identity and anatomy (watch the take)",
                          "camera motion that returns to the reference before the end calm span",
                          "camera motion in takes that end in a new pose (victory, defeat, fx)"],
            "checks": checks,
            "inputs": [job_ref, *inputs],
            "outputs": [],
            "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
        },
    }


def master_to_video(job: Job, fit: VideoFit, point: Sequence[float]) -> tuple[float, float]:
    """A master (sheet) px point in video px."""
    origin = job.view_box[:2] if job.view_box else (0, 0)
    px, py = point[0] - origin[0], point[1] - origin[1]
    return (fit.k[0] * (job.offset[0] + job.scale * px) + fit.c[0],
            fit.k[1] * (job.offset[1] + job.scale * py) + fit.c[1])


# --------------------------------------------------------------------------- palette-repair

def hsv(rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
    """Hue in degrees [0, 360), saturation and value in [0, 1] of uint8 RGB."""
    colour = rgb.astype(np.float64)
    high, low = colour.max(-1), colour.min(-1)
    delta = high - low
    safe = np.where(delta > 0, delta, 1.0)
    red, green, blue = colour[..., 0], colour[..., 1], colour[..., 2]
    hue = np.where(high == red, ((green - blue) / safe) % 6.0,
                   np.where(high == green, (blue - red) / safe + 2.0, (red - green) / safe + 4.0)) * 60.0
    hue = np.where(delta > 0, hue, 0.0)
    saturation = np.where(high > 0, delta / np.where(high > 0, high, 1.0), 0.0)
    return hue, saturation, high / 255.0


def hue_selection(rgb: np.ndarray, hue_range: Sequence[float], min_saturation: float,
                  min_value: float) -> np.ndarray:
    hue, saturation, value = hsv(rgb)
    low, high = hue_range
    in_band = (hue >= low) & (hue <= high) if low <= high else (hue >= low) | (hue <= high)
    return in_band & (saturation >= min_saturation) & (value >= min_value)


def build_palette(master: np.ndarray, box: Sequence[int] | None, hue_range: Sequence[float],
                  min_saturation: float, min_value: float, size: int) -> np.ndarray:
    """The ``size`` most frequent opaque master colours outside the repaired hue band."""
    pixels = master if box is None else master[box[1]:box[3], box[0]:box[2]]
    opaque = pixels[..., 3] > 245
    allowed = opaque & ~hue_selection(pixels[..., :3], hue_range, min_saturation, min_value)
    colours, counts = np.unique(pixels[allowed][:, :3], axis=0, return_counts=True)
    if colours.size == 0:
        raise ValueError("The palette source has no opaque colours outside the repaired hue band")
    order = np.argsort(-counts, kind="stable")[:size]
    return colours[order]


def nearest_colours(colours: np.ndarray, palette: np.ndarray, chunk: int = 65536) -> np.ndarray:
    pal = palette.astype(np.int32)
    out = np.empty((colours.shape[0], 3), np.uint8)
    for begin in range(0, colours.shape[0], chunk):
        part = colours[begin:begin + chunk].astype(np.int32)
        distance = ((part[:, None, :] - pal[None, :, :]) ** 2).sum(-1)
        out[begin:begin + chunk] = palette[np.argmin(distance, axis=1)]
    return out


def cmd_palette_repair(args: argparse.Namespace) -> dict[str, Any]:
    files = list_frames(args.frames, args.pattern)
    if args.job:
        job = load_job(args.job)
        master = load_master_view(job)
        palette_source = job.master_path
    else:
        image, _info = forge_core.load_rgba(args.master)
        master = np.asarray(image)
        palette_source = Path(args.master)
    palette = build_palette(master, args.palette_box, args.hue, args.min_saturation, args.min_value, args.palette_size)
    output = Path(args.output_dir)
    final = output.parent.resolve() / output.name
    first, _ = _load_pixels(files[0])
    height, width = first.shape[:2]
    region = np.zeros((height, width), bool)
    for x0, y0, x1, y1 in args.region:
        region[max(0, y0):min(height, y1), max(0, x0):min(width, x1)] = True
    if not region.any():
        raise ValueError("--region lies outside the frames")
    union = np.zeros((height, width), bool)
    rows, inputs, outputs = [], [], []
    worst = 0.0
    with forge_core.staged_output(output) as stage:
        frames_dir = stage / "frames"
        frames_dir.mkdir()
        for path in files:
            pixels, digest = _load_pixels(path)
            if pixels.shape[:2] != (height, width):
                raise ValueError(f"{path.name} is {pixels.shape[1]}x{pixels.shape[0]}; the frames are {width}x{height}")
            selected = (region & (pixels[..., 3] >= args.min_alpha)
                        & hue_selection(pixels[..., :3], args.hue, args.min_saturation, args.min_value))
            visible = int((region & (pixels[..., 3] > 0)).sum())
            fraction = int(selected.sum()) / visible if visible else 0.0
            worst = max(worst, fraction)
            if fraction > args.max_changed_fraction:
                raise RegistrationQAError(
                    f"palette-repair QA failed, nothing was written: {fraction:.1%} of the visible region pixels in "
                    f"{path.name} match the rule (limit {args.max_changed_fraction:.0%}); narrow --hue or --region")
            repaired = pixels.copy()
            if selected.any():
                repaired[selected, :3] = nearest_colours(pixels[selected, :3], palette)
            if not np.array_equal(repaired[..., 3], pixels[..., 3]):
                raise RegistrationQAError("palette-repair changed alpha; nothing was written")
            union |= selected
            forge_core.save_png(repaired, frames_dir / path.name)
            after = forge_core.sha256_file(frames_dir / path.name)
            rows.append({"file": f"frames/{path.name}", "changedPx": int(selected.sum()), "regionVisiblePx": visible,
                         "beforeSha256": digest, "afterSha256": after})
            inputs.append({"path": ref_path(path, final), "sha256": digest})
            outputs.append({"path": f"frames/{path.name}", "sha256": after})
        forge_core.save_png((union * 255).astype(np.uint8), stage / "changed-mask.png")
        total = sum(row["changedPx"] for row in rows)
        report = {
            "schema": PALETTE_REPAIR_SCHEMA,
            "status": "needs-visual-review",
            "method": "register_clip palette-repair v1: inside the regions, opaque pixels (alpha >= min-alpha) whose "
                      "HSV hue is in the band (with saturation and value floors) take the nearest RGB colour of the "
                      "palette sampled from the master; alpha and every pixel outside the regions are unchanged",
            "notProven": ["that the replacement colours read correctly (compare frames before and after)",
                          "pixels of the flash outside the regions or below the alpha floor"],
            "checks": [
                {"id": "alpha-unchanged", "status": "pass", "value": True, "threshold": True},
                {"id": "changed-fraction", "status": "pass", "value": round(worst, 6),
                 "threshold": args.max_changed_fraction},
                {"id": "region-limited", "status": "pass", "value": 0, "threshold": 0},
            ],
            "inputs": inputs,
            "outputs": outputs,
            "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
            "rule": {"hueRange": list(args.hue), "minSaturation": args.min_saturation, "minValue": args.min_value,
                     "minAlpha": args.min_alpha},
            "regions": [list(box) for box in args.region],
            "paletteSource": {"path": ref_path(palette_source, final), "sha256": forge_core.sha256_file(palette_source),
                              "box": None if args.palette_box is None else list(args.palette_box)},
            "palette": ["#" + "".join(f"{int(v):02x}" for v in colour) for colour in palette],
            "frames": rows,
            "totalChangedPx": total,
            "alphaUnchanged": True,
            "changedMask": "changed-mask.png",
        }
        forge_core.write_json(stage / PALETTE_REPAIR_FILE, report)
    return {"output": str(final), "metadata": str(final / PALETTE_REPAIR_FILE), "frames": len(rows),
            "totalChangedPx": total, "palette": len(palette)}


# --------------------------------------------------------------------------- CLI

def _positive(text: str) -> float:
    value = float(text)
    if not math.isfinite(value) or value <= 0:
        raise argparse.ArgumentTypeError(f"needs a positive number; got {text!r}")
    return value


def _fraction(text: str) -> float:
    value = float(text)
    if not math.isfinite(value) or not 0 <= value <= 1:
        raise argparse.ArgumentTypeError(f"needs a number from 0 to 1; got {text!r}")
    return value


def _non_negative_int(text: str) -> int:
    value = int(text)
    if value < 0:
        raise argparse.ArgumentTypeError(f"needs an integer >= 0; got {text!r}")
    return value


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = parser.add_subparsers(dest="command", required=True)

    pa = sub.add_parser("apply", help="register keyed frames with the job's one fixed transform")
    pa.add_argument("--job", required=True, help="registration_job.json from prepare_i2v_input.py")
    pa.add_argument("--frames", required=True, help="folder of keyed RGBA frames at the video's size (natural order)")
    pa.add_argument("--pattern", default="*.png", help="frame file pattern (default *.png)")
    pa.add_argument("--output-dir", required=True, help="new folder for frames/ and registration.json")
    pa.add_argument("--range", type=parse_range, help="START:END frames to register (0-based, end exclusive)")
    pa.add_argument("--action-padding", type=prep.parse_padding,
                    help="L,T,R,B source px; grows the canvas and shifts the anchor (default: the job's padding)")
    pa.add_argument("--fit", choices=FITS, help="provider canvas to video: auto (default), stretch, cover, contain")
    pa.add_argument("--resampler", choices=forge_core.RESAMPLERS,
                    help="lanczos (default; box for 2x+ reductions), box, or nearest (exact 1/N pixel art only)")
    pa.add_argument("--lock", type=parse_locks, help="feet, x or hip (comma list): whole-pixel shifts to the master")
    pa.add_argument("--lock-max", type=_non_negative_int, help="largest lock shift in output px (default unlimited)")
    pa.add_argument("--ground-min-run", type=_non_negative_int,
                    help="px a row needs to count as the ground line (default 3)")
    pa.add_argument("--rest-frames", type=parse_frames_list,
                    help="source frames (0-based, before --range) that repeat the reference pose (default 0; "
                         "fx: none); 'none' skips the rest checks")
    pa.add_argument("--max-anchor-error", type=_positive, default=DEFAULT_MAX_ANCHOR_ERROR,
                    help="rest-pose anchor error limit in output px (default 2)")
    pa.add_argument("--max-scale-error", type=_positive, default=DEFAULT_MAX_SCALE_ERROR,
                    help="rest-pose height error limit (default 0.03)")
    pa.add_argument("--allow-edge-touch", action="store_true",
                    help="downgrade video-edge-touch and canvas-overflow to warnings (recorded)")
    pa.add_argument("--profile", choices=PROFILES, default="actor", help="actor (default) or fx")
    pa.add_argument("--edge-fade", type=_positive,
                    help="fx: boundary falloff in output px (default 8.5%% of the canvas)")
    pa.add_argument("--fade-in-frames", type=_non_negative_int, default=FX_FADE_IN_FRAMES,
                    help="fx: frames of appearance (default 2: the first frame is transparent)")
    pa.add_argument("--dissolve-tail", type=_fraction, default=FX_DISSOLVE_TAIL,
                    help="fx: share of the frames that dissolve to transparent at the end (default 0.2, >= 4 frames)")
    pa.add_argument("--display-scale", type=_positive,
                    help="runtime draw scale to record (fx default: padded canvas / base canvas, longest side)")
    pa.add_argument("--clip", help="clip name for profiles (default: the job's action)")
    pa.add_argument("--character-profile", help="character_profile.json to inherit; a mismatch fails the run")
    pa.add_argument("--scale-tolerance", type=_fraction, default=0.005,
                    help="relative referenceScale tolerance against the profile (default 0.005)")
    pa.set_defaults(func=cmd_apply)

    pr = sub.add_parser("profile", help="write a character profile from registered clips")
    pr.add_argument("--registration", action="append", required=True,
                    help="registration.json of a clip (repeat; the first one is the reference)")
    pr.add_argument("--id", required=True, help="character id")
    pr.add_argument("--output", required=True, help="new profile JSON file")
    pr.add_argument("--world-scale", type=_positive, help="world units per source px")
    pr.add_argument("--matte-mode", choices=MATTE_MODES, default="soft")
    pr.add_argument("--key", type=prep.normalise_key, help="matte key (default: the clips' key)")
    pr.add_argument("--erode", type=_non_negative_int, default=0, help="matte erosion in whole px (default 0)")
    pr.add_argument("--unmix", action=argparse.BooleanOptionalAction,
                    help="soft matte only: un-mix edge colours (default: on for soft, off for dominance and binary)")
    pr.add_argument("--despill-mode", choices=forge_matte.DESPILL_MODES, default="auto")
    pr.add_argument("--scale-tolerance", type=_fraction, default=0.005)
    pr.set_defaults(func=cmd_profile)

    pv = sub.add_parser("validate-profile", help="check registered clips against a character profile")
    pv.add_argument("--profile", required=True, help="character_profile.json")
    pv.add_argument("--registration", action="append", required=True, help="registration.json (repeat)")
    pv.add_argument("--foot-tolerance", type=float, default=2.0, help="rest foot line tolerance in px (default 2)")
    pv.add_argument("--scale-tolerance", type=_fraction, default=0.005)
    pv.set_defaults(func=cmd_validate_profile)

    pq = sub.add_parser("qc", help="judge a raw take and append a take.v1 line to takes.jsonl")
    pq.add_argument("--job", required=True, help="registration_job.json the take was generated from")
    source = pq.add_mutually_exclusive_group(required=True)
    source.add_argument("--frames", help="folder of the take's raw frames (natural order)")
    source.add_argument("--video", help="the take's video file (needs ffmpeg)")
    pq.add_argument("--pattern", default="*.png", help="frame file pattern (default *.png)")
    pq.add_argument("--take", help="take id (default: the video or folder name)")
    pq.add_argument("--takes", help="takes.jsonl to append to (default: next to the job)")
    pq.add_argument("--fps", type=_positive, default=24.0, help="frame rate of --frames (default 24)")
    pq.add_argument("--fit", choices=FITS, help="provider canvas to video (default auto)")
    pq.add_argument("--samples", type=int, default=9,
                    help="frames sampled for NCC (default 9, first and last included)")
    pq.add_argument("--landmarks", type=int, default=12, help="landmark patches (default 12)")
    pq.add_argument("--identity-box", type=prep.parse_box, help="X0,Y0,X1,Y1 identity region in master px "
                                                                "(default: the top 35%% of the subject)")
    pq.add_argument("--edge-band", type=int, help="border band in video px (default 60%% of the job margin)")
    pq.add_argument("--max-edge-impure", type=_fraction, default=DEFAULT_MAX_EDGE_IMPURE,
                    help="share of the border band allowed off-key (default 0.0005)")
    pq.add_argument("--max-scale-change", type=_positive, default=DEFAULT_MAX_SCALE_CHANGE,
                    help="calm-span camera scale limit (default 0.03)")
    pq.add_argument("--max-drift", type=_positive, default=DEFAULT_MAX_DRIFT,
                    help="start-span drift limit in source px (default 2)")
    pq.add_argument("--min-landmark-ncc", type=_fraction, default=DEFAULT_MIN_LANDMARK_NCC)
    pq.add_argument("--min-identity-ncc", type=_fraction, default=DEFAULT_MIN_IDENTITY_NCC)
    pq.add_argument("--strict", action="store_true",
                    help="exit 1 when the take is rejected (the line is still written)")
    pq.set_defaults(func=cmd_qc)

    pp = sub.add_parser("palette-repair", help="remap off-palette flashes inside regions to master colours")
    pp.add_argument("--frames", required=True, help="folder of registered RGBA frames")
    pp.add_argument("--pattern", default="*.png", help="frame file pattern (default *.png)")
    palette = pp.add_mutually_exclusive_group(required=True)
    palette.add_argument("--master", help="palette source image (RGBA)")
    palette.add_argument("--job", help="registration_job.json: use its master")
    pp.add_argument("--region", type=prep.parse_box, action="append", required=True,
                    help="X0,Y0,X1,Y1 frame px to repair (half-open; repeat for several)")
    pp.add_argument("--hue", type=parse_hue, required=True,
                    help="H0,H1 hue band in degrees to replace (wraps if H0 > H1)")
    pp.add_argument("--min-saturation", type=_fraction, default=0.3)
    pp.add_argument("--min-value", type=_fraction, default=0.1)
    pp.add_argument("--min-alpha", type=int, default=200, help="only pixels at least this opaque (default 200)")
    pp.add_argument("--palette-box", type=prep.parse_box, help="X0,Y0,X1,Y1 master px to sample (default: all)")
    pp.add_argument("--palette-size", type=int, default=128, help="most frequent master colours kept (default 128)")
    pp.add_argument("--max-changed-fraction", type=_fraction, default=0.6,
                    help="QA limit: share of a frame's visible region pixels the rule may change (default 0.6)")
    pp.add_argument("--output-dir", required=True, help="new folder for the repaired frames and the report")
    pp.set_defaults(func=cmd_palette_repair)
    return parser


def _finish_args(args: argparse.Namespace) -> None:
    if args.command == "qc" and (args.samples < 2 or args.landmarks < 1):
        raise ValueError("--samples needs at least 2 and --landmarks at least 1")
    if args.command == "palette-repair" and not (1 <= args.palette_size <= 4096 and 0 <= args.min_alpha <= 255):
        raise ValueError("--palette-size must be 1-4096 and --min-alpha 0-255")


def run(argv: Sequence[str] | None = None) -> dict[str, Any]:
    """Parse argv and run the command; returns the JSON summary (raises on errors)."""
    args = build_parser().parse_args(argv)
    _finish_args(args)
    return args.func(args)


def _run(argv: Sequence[str] | None = None) -> int:
    print(json.dumps(run(argv), ensure_ascii=True))
    return 0


def main(argv: Sequence[str] | None = None) -> int:
    """Usage errors exit 2; refused input, failed registration QA, a failed profile validation and a take
    rejected under --strict exit 1 with ``error: ...``; anything unexpected prints ``error: internal error
    (...)`` (D26, D27; forge_core.run_cli). qc is an append-only verdict log, not a verify tool: a rejected
    take is recorded and exits 0 unless --strict."""
    import forge_av  # qc --video decodes with ffmpeg: its errors are refused input, not internal errors
    return forge_core.run_cli(_run, argv, expected=forge_core.CLI_EXPECTED_ERRORS + (forge_av.ForgeAVError,))


if __name__ == "__main__":
    raise SystemExit(main())
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall