Skip to content

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

generate2dmap

Verified

Plan and build 2D game maps and scenes - top-down and side-scrolling levels, tilemaps, prop packs, parallax backgrounds and HD-2D battle or story plates - with collision, navigation and reachability checks, environment motion, a playable HTML preview and export to Tiled, Godot 4 or LDtk. Map art (terrain, tiles, props, plates, parallax layers) is image generation by default, through generate2dmedia route_media.py (the API when a key is configured, else the local Codex or Grok CLI); map data (layout, collision, exits, spawns) is written as data. Use for any map, level, room, scene, background, terrain or prop-kit request. Not for characters, creatures, items or FX (generate2dsprite), character animation (video2dsprite), code-drawn tiles or maps (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md12.3 KB
agents/openai.yamlconfig513 B
references/background-scenes.mdmarkdown14.2 KB
references/engine-maps.mdmarkdown14.4 KB
references/hd2d-plates.mdmarkdown11.9 KB
references/hd2d-presentation.mdmarkdown9.8 KB
references/layered-map-contract.mdmarkdown21.3 KB
references/map-presets.mdmarkdown7.9 KB
references/map-strategies.mdmarkdown12.2 KB
references/parallax-backgrounds.mdmarkdown14.0 KB
references/prop-pack-contract.mdmarkdown15.0 KB
references/runtime/map-runtime.mjsscript81.1 KB
references/scene-preview.mdmarkdown14.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/map.schema.jsonconfig134.0 KB
references/side-scroll-scenes.mdmarkdown14.3 KB
scripts/build_motion_mask.pyscript46.3 KB
scripts/build_scene_preview.pyscript93.5 KB
scripts/compose_layered_preview.pyscript92.2 KB
scripts/conform_background.pyscript25.4 KB
scripts/edit_locality_check.pyscript27.1 KB
scripts/export_godot.pyscript85.6 KB
scripts/export_ldtk.pyscript51.4 KB
scripts/export_tiled.pyscript45.5 KB
scripts/extract_platform_strip.pyscript29.4 KB
scripts/extract_prop_pack.pyscript63.2 KB
scripts/extract_scene_lights.pyscript43.3 KB
scripts/extract_terrain_tiles.pyscript54.1 KB
scripts/forge_av.pyscript46.6 KB
scripts/forge_core.pyscript86.4 KB
scripts/forge_hibit.pyscript18.8 KB
scripts/forge_index.pyscript24.8 KB
scripts/forge_matte.pyscript71.6 KB
scripts/forge_nav.pyscript95.5 KB
scripts/forge_schema.pyscript26.1 KB
scripts/hibit_plate.pyscript13.5 KB
scripts/map_bundle.pyscript82.6 KB
scripts/map_nav.pyscript31.9 KB
scripts/scene_layout_guide.pyscript22.1 KB
scripts/scene_motion.pyscript54.5 KB
scripts/validate_chunks.pyscript48.8 KB
scripts/validate_layout.pyscript47.1 KB
scripts/validate_parallax.pyscript29.6 KB
scripts/validate_stage.pyscript62.3 KB

scripts/validate_layout.py

View on GitHub
#!/usr/bin/env python3
"""Validate a side-scroll level grammar (generate2dmap.layout.v1) against the controller's physics.

The level is a row of `segments` [x0, x1, kind] in world pixels (y points down).
Kinds map to three classes: ground (standable; aliases floor, solid, crest, c,
slope, s), gap (pit, void, g) and hazard (water, lava, spikes); `kinds` maps
other names, e.g. {"bridge": "ground"}. The ground surface comes from
`surface` (a polyline [[x, y], ...]; a repeated x is a vertical step) or a flat
`groundY`. Props are {id, x, y, w?}: (x, y) is the middle of the base. Props of
kind deck, platform, plank or bridge are standable surfaces {x0, x1, y, thickness}.

Checks (physics: jumpHeight, jumpDistance, maxSlopeDeg, stepUp, colliderSubstep):

  segments         contiguous, no holes or overlaps
  slope_limit      a slope steeper than maxSlopeDeg must rise no more than stepUp
                   (draw a taller one as a vertical ledge)
  step_limit       ledges taller than stepUp need a jump; taller than jumpHeight warns
  deck_thickness   decks at least minDeckThickness px (default colliderSubstep + 1,
                   else 4: a 3-row deck lets a standing body sink through)
  prop_support     every footprint column of a prop rests on ground or a deck within
                   groundTolerance (default 1 px); floating: true opts out
  spawns_grounded  spawns stand on a surface
  gaps_jumpable    the far side of every gap or hazard is reachable from the near side
                   (jump arc: apex jumpHeight, same-height range jumpDistance)
  reachability     from the first spawn: every spawn, exit and (without exits) the
                   level end; unreachable decks warn
  arena_width      each arena (default the level) is at least the viewport width plus
                   camera travel at 16:9, 19.5:9 and every listed viewport

Segment bounds are whole world pixels (columns are pixels). A gap is measured
between the centres of its edge columns, so the widest gap a jump of
jumpDistance crosses is jumpDistance - 1 px wide. Reachability searches the
directed graph of spans linked by walks, drops and jump arcs; it is a side-view
graph, not the top-down collision grid of forge_nav (whose grid_bfs serves the
4-neighbour grids of validate_chunks and the map tools).

Without --output-dir only the one-line summary is printed; with it,
layout-report.json and layout-debug.png are published into the new folder.
Exit 1 when a check fails; --strict-qc then publishes nothing.

Size limit: the level (its segments), each deck and each prop may span at most
1,000,000 px horizontally. The checks hold per-column arrays (about 90 bytes per
px of width), so a wider layout, usually a mistyped bound such as 1e9, is refused
with an error before anything is allocated. layout-debug.png is drawn at one
pixel per world px up to 4096 x 8192 px, and scaled down as a whole beyond that.
"""

from __future__ import annotations

import argparse
import json
import math
import re
import sys
from collections import deque
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Sequence

import numpy as np
from PIL import Image, ImageDraw

_HERE = str(Path(__file__).resolve().parent)
if _HERE not in sys.path:
    sys.path.insert(0, _HERE)
import forge_core  # noqa: E402  (this skill's vendored copy)


INPUT_SCHEMA = "generate2dmap.layout.v1"
REPORT_SCHEMA = "generate2dmap.layout_validation.v1"
TOOL = {"name": "validate_layout", "version": forge_core.FORGE_PACKAGE_VERSION}
KIND_CLASSES = {
    "ground": "ground", "floor": "ground", "solid": "ground", "crest": "ground", "c": "ground",
    "slope": "ground", "s": "ground",
    "gap": "gap", "pit": "gap", "void": "gap", "g": "gap",
    "hazard": "hazard", "water": "hazard", "lava": "hazard", "spikes": "hazard",
}
CLASSES = ("ground", "gap", "hazard")
DECK_KINDS = {"deck", "platform", "plank", "bridge"}
DEFAULT_ASPECTS = ("16:9", "19.5:9")
DEFAULT_DECK_THICKNESS = 4
DEFAULT_GROUND_TOLERANCE = 1.0
MAX_SAMPLES = 64
MAX_EXTENT_PX = 1_000_000  # widest level, deck or prop: the checks hold per-column arrays (review r1, finding 4)
DEBUG_WIDTH, DEBUG_HEIGHT = 4096, 8192  # layout-debug.png fits this box; a larger side view is scaled down whole
DEBUG_MAX_PIXELS = DEBUG_WIDTH * DEBUG_HEIGHT  # so the canvas never holds more than 32 Mpx
EPSILON = 1e-6
NOT_PROVEN = [
    "The actor is a point at its feet: collider width, head room under decks and ceilings are not modelled.",
    "Jumps follow one parabola (apex jumpHeight, range jumpDistance) with full air control down to zero "
    "horizontal speed; coyote time, double jumps, dashes and variable gravity are not modelled.",
    "Decks are one-way (landable from any arc that reaches their top); they never block an arc.",
    "Floating and sunk props are judged from their base line only; their art and colliders are not inspected.",
    "Camera travel is the value given (default 0); the tool does not simulate the camera.",
]
COLORS = {
    "sky": (226, 236, 246, 255), "ground": (150, 116, 82, 255), "face": (214, 70, 190, 255),
    "gap": (150, 30, 40, 255), "hazard": (60, 110, 210, 255), "deck": (176, 128, 70, 255),
    "bad": (230, 50, 50, 255), "ok": (40, 170, 80, 255), "warn": (240, 150, 30, 255),
    "prop": (90, 90, 100, 255), "spawn": (20, 150, 60, 255), "exit": (40, 90, 220, 255),
    "arc": (0, 170, 200, 255),
}


# --------------------------------------------------------------------------- input model

def _number(value: Any, name: str, *, minimum: float | None = None, exclusive: bool = False) -> float:
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
        raise ValueError(f"{name} must be a finite number.")
    if minimum is not None and (value <= minimum if exclusive else value < minimum):
        raise ValueError(f"{name} must be {'greater than' if exclusive else 'at least'} {minimum:g}.")
    return float(value)


def _px(value: float) -> str:
    """A world-px number written out in full (1,000,001, not 1e+06)."""
    return f"{value:,.6f}".rstrip("0").rstrip(".")


def _check_extent(extent: float, what: str) -> None:
    """Refuse a horizontal extent above MAX_EXTENT_PX before its per-column arrays exist (about 90 bytes per px)."""
    if extent > MAX_EXTENT_PX:
        raise ValueError(f"{what} ({_px(extent)} px); the limit is {MAX_EXTENT_PX:,} px: split the level, or check for "
                         "a mistyped number.")


def _whole(value: Any, name: str) -> int:
    number = _number(value, name)
    if number != int(number):
        raise ValueError(f"{name} must be a whole number of world pixels (got {number:g}).")
    return int(number)


@dataclass
class Physics:
    jump_height: float
    jump_distance: float
    max_slope_deg: float
    step_up: float
    collider_substep: float | None
    min_deck_thickness: float
    ground_tolerance: float

    def reach(self, rise: np.ndarray | float) -> np.ndarray:
        """Longest horizontal distance that lands `rise` px higher (negative: lower) on the falling branch."""
        rise = np.asarray(rise, dtype=float)
        return self.jump_distance / 2 * (1 + np.sqrt(np.maximum(0.0, 1 - rise / self.jump_height)))

    def height(self, t: np.ndarray) -> np.ndarray:
        """Height above the take-off point after travelling `t` px along the full-speed arc."""
        return self.jump_height * (1 - (2 * np.asarray(t, dtype=float) / self.jump_distance - 1) ** 2)


@dataclass
class Span:
    id: str
    kind: str  # "ground" or "deck"
    columns: np.ndarray  # world column indices (int)
    heights: np.ndarray  # surface y per column
    source: str | None = None  # deck prop id
    reachable: bool = False
    edges: list[int] = field(default_factory=list)

    @property
    def x0(self) -> int:
        return int(self.columns[0])

    @property
    def x1(self) -> int:
        return int(self.columns[-1]) + 1


@dataclass
class Level:
    x0: int
    x1: int
    classes: np.ndarray  # per column: 0 ground, 1 gap, 2 hazard
    heights: np.ndarray  # surface y per column (NaN where not ground)
    face: np.ndarray  # bool per column: ground too steep to stand on
    physics: Physics
    segments: list[tuple[int, int, str, str]]
    decks: list[dict[str, Any]]
    props: list[dict[str, Any]]
    spawns: list[dict[str, Any]]
    exits: list[dict[str, Any]]
    pieces: list[dict[str, Any]]

    @property
    def width(self) -> int:
        return self.x1 - self.x0


def parse_physics(data: Any) -> Physics:
    if not isinstance(data, dict):
        raise ValueError("physics must be an object with jumpHeight, jumpDistance, maxSlopeDeg and stepUp.")
    substep = data.get("colliderSubstep")
    substep = None if substep is None else _number(substep, "physics.colliderSubstep", minimum=0, exclusive=True)
    if "minDeckThickness" in data:
        deck = _number(data["minDeckThickness"], "physics.minDeckThickness", minimum=0)
    else:
        deck = math.floor(substep) + 1 if substep is not None else DEFAULT_DECK_THICKNESS
    slope = _number(data.get("maxSlopeDeg"), "physics.maxSlopeDeg", minimum=0)
    if slope > 90:
        raise ValueError("physics.maxSlopeDeg must be at most 90.")
    return Physics(_number(data.get("jumpHeight"), "physics.jumpHeight", minimum=0, exclusive=True),
                   _number(data.get("jumpDistance"), "physics.jumpDistance", minimum=0, exclusive=True),
                   slope, _number(data.get("stepUp"), "physics.stepUp", minimum=0), substep, deck,
                   _number(data.get("groundTolerance", DEFAULT_GROUND_TOLERANCE), "physics.groundTolerance",
                           minimum=0))


def _surface(document: dict[str, Any]) -> np.ndarray:
    """The ground polyline as an (n, 2) array; a flat groundY becomes two points far apart."""
    if "surface" in document and "groundY" in document:
        raise ValueError("give either surface (a polyline) or groundY (flat ground), not both.")
    if "groundY" in document:
        y = _number(document["groundY"], "groundY")
        return np.array([[-math.inf, y], [math.inf, y]])
    points = document.get("surface")
    if not isinstance(points, list) or len(points) < 2:
        raise ValueError("the layout needs surface (at least two [x, y] points) or groundY.")
    array = np.array([[_number(value, f"surface[{index}]") for value in point] if isinstance(point, list)
                      and len(point) == 2 else [math.nan, math.nan] for index, point in enumerate(points)])
    if not np.isfinite(array).all():
        raise ValueError("every surface point must be [x, y] with finite numbers.")
    if (np.diff(array[:, 0]) < 0).any():
        raise ValueError("surface x values must not decrease (repeat an x for a vertical step).")
    return array


def surface_at(polyline: np.ndarray, xs: np.ndarray) -> np.ndarray:
    """Surface y at each x; at a repeated x (a vertical step) the later point applies from that x on."""
    xs = np.asarray(xs, dtype=float)
    px, py = polyline[:, 0], polyline[:, 1]
    index = np.clip(np.searchsorted(px, xs, side="right") - 1, 0, len(px) - 2)
    x0, x1 = px[index], px[index + 1]
    y0, y1 = py[index], py[index + 1]
    span = x1 - x0
    with np.errstate(invalid="ignore", divide="ignore"):
        t = np.where(np.isfinite(span) & (span > 0), (xs - x0) / span, 0.0)
    flat = ~np.isfinite(x0) | ~np.isfinite(x1)
    return np.where(flat, y0, y0 + (y1 - y0) * np.clip(t, 0, 1))


def parse_level(document: Any) -> Level:
    if not isinstance(document, dict):
        raise ValueError("The layout must be a JSON object.")
    if document.get("schema") != INPUT_SCHEMA:
        raise ValueError(f"schema must be {INPUT_SCHEMA!r} (got {document.get('schema')!r}).")
    physics = parse_physics(document.get("physics"))
    mapping = dict(KIND_CLASSES)
    custom = document.get("kinds", {})
    if not isinstance(custom, dict):
        raise ValueError("kinds must map segment kinds to ground, gap or hazard.")
    for name, target in custom.items():
        if target not in CLASSES:
            raise ValueError(f"kinds.{name} must be one of {', '.join(CLASSES)}.")
        mapping[name] = target
    entries = document.get("segments")
    if not isinstance(entries, list) or not entries:
        raise ValueError("segments must be a non-empty list of [x0, x1, kind].")
    segments = []
    for index, entry in enumerate(entries):
        if not isinstance(entry, list) or len(entry) != 3 or not isinstance(entry[2], str):
            raise ValueError(f"segments[{index}] must be [x0, x1, kind].")
        x0, x1 = _whole(entry[0], f"segments[{index}][0]"), _whole(entry[1], f"segments[{index}][1]")
        if x1 <= x0:
            raise ValueError(f"segments[{index}] must have x1 > x0.")
        if entry[2] not in mapping:
            raise ValueError(f"segments[{index}] kind {entry[2]!r} is unknown; use one of {sorted(KIND_CLASSES)} "
                             f"or map it with kinds, e.g. \"kinds\": {{\"{entry[2]}\": \"ground\"}}.")
        segments.append((x0, x1, entry[2], mapping[entry[2]]))
    level_x0 = min(segment[0] for segment in segments)
    level_x1 = max(segment[1] for segment in segments)
    _check_extent(level_x1 - level_x0, f"the level's segments span x {_px(level_x0)} to {_px(level_x1)}")
    classes = np.full(level_x1 - level_x0, 1, np.int8)  # undefined columns count as gaps
    for x0, x1, _, cls in reversed(segments):
        classes[x0 - level_x0:x1 - level_x0] = CLASSES.index(cls)
    polyline = _surface(document)
    centers = np.arange(level_x0, level_x1) + 0.5
    ground = classes == 0
    if ground.any() and (polyline[0, 0] > centers[ground][0] or polyline[-1, 0] < centers[ground][-1]):
        raise ValueError(f"surface must cover the ground from x={level_x0} to x={level_x1}.")
    heights = np.where(ground, surface_at(polyline, centers), np.nan)
    pieces, face = _classify_pieces(polyline, centers, ground, physics)
    decks, props = [], []
    for index, prop in enumerate(document.get("props", []) or []):
        if not isinstance(prop, dict):
            raise ValueError(f"props[{index}] must be an object.")
        ident = str(prop.get("id", f"prop-{index}"))
        if str(prop.get("kind", "")).lower() in DECK_KINDS:
            if "x0" in prop or "x1" in prop:
                x0 = _number(prop.get("x0"), f"deck {ident} x0")
                x1 = _number(prop.get("x1"), f"deck {ident} x1")
            else:
                center, width = _number(prop.get("x"), f"deck {ident} x"), _number(prop.get("w"), f"deck {ident} w")
                x0, x1 = center - width / 2, center + width / 2
            if x1 <= x0:
                raise ValueError(f"deck {ident} needs x1 > x0.")
            _check_extent(x1 - x0, f"deck {ident} spans x {_px(x0)} to {_px(x1)}")
            if "thickness" not in prop:
                raise ValueError(f"deck {ident} needs thickness (rows of solid deck under its top).")
            decks.append({"id": ident, "x0": x0, "x1": x1, "y": _number(prop.get("y"), f"deck {ident} y"),
                          "thickness": _number(prop["thickness"], f"deck {ident} thickness", minimum=0)})
        else:
            width = _number(prop.get("w", prop.get("width", 0)), f"prop {ident} w", minimum=0)
            _check_extent(width, f"prop {ident} is too wide")
            props.append({"id": ident, "x": _number(prop.get("x"), f"prop {ident} x"),
                          "y": _number(prop.get("y"), f"prop {ident} y"), "w": width,
                          "floating": bool(prop.get("floating", False))})
    spawns = [_point(item, f"spawns[{index}]", needs_y=True) for index, item in enumerate(document.get("spawns", [])
                                                                                          or [])]
    exits = [_point(item, f"exits[{index}]", needs_y=False) for index, item in enumerate(document.get("exits", [])
                                                                                         or [])]
    return Level(level_x0, level_x1, classes, heights, face, physics, segments, decks, props, spawns, exits, pieces)


def _point(item: Any, name: str, *, needs_y: bool) -> dict[str, Any]:
    if not isinstance(item, dict):
        raise ValueError(f"{name} must be an object with id, x and y.")
    point = {"id": str(item.get("id", name)), "x": _number(item.get("x"), f"{name}.x")}
    if needs_y or "y" in item:
        point["y"] = _number(item.get("y"), f"{name}.y")
    return point


def _classify_pieces(polyline: np.ndarray, centers: np.ndarray, ground: np.ndarray,
                     physics: Physics) -> tuple[list[dict[str, Any]], np.ndarray]:
    """Ledges (vertical steps above stepUp) and steep faces (slopes above maxSlopeDeg rising above stepUp)."""
    pieces = []
    face = np.zeros(len(centers), bool)
    limit = math.tan(math.radians(min(physics.max_slope_deg, 89.999)))
    for (xa, ya), (xb, yb) in zip(polyline[:-1], polyline[1:]):
        if not (math.isfinite(xa) and math.isfinite(xb)):
            continue
        rise = abs(yb - ya)
        if xb == xa:
            # vertical step at xa: the columns either side must both be ground for it to matter
            left, right = np.searchsorted(centers, xa) - 1, np.searchsorted(centers, xa)
            if rise > physics.step_up + EPSILON and 0 <= left and right < len(centers) and ground[left] \
                    and ground[right]:
                pieces.append({"kind": "ledge", "x": float(xa), "height": float(rise),
                               "up": "east" if yb < ya else "west"})
            continue
        inside = (centers >= xa) & (centers <= xb) & ground
        if not inside.any():
            continue
        if rise / (xb - xa) > limit + EPSILON and rise > physics.step_up + EPSILON:
            face |= inside
            pieces.append({"kind": "steep", "x0": float(xa), "x1": float(xb), "rise": float(rise),
                           "angle_deg": round(math.degrees(math.atan2(rise, xb - xa)), 3)})
    return pieces, face


# --------------------------------------------------------------------------- spans and jumps

def _covered_columns(x0: float, x1: float) -> tuple[int, int]:
    """First and last column whose centre lies in the half-open [x0, x1) (last < first when none does)."""
    return math.ceil(x0 - 0.5), math.ceil(x1 - 0.5) - 1


def build_spans(level: Level) -> list[Span]:
    """Standable runs: ground columns linked by walkable transitions, and each deck."""
    physics = level.physics
    standable = (level.classes == 0) & ~level.face
    tolerance = physics.step_up + math.tan(math.radians(min(physics.max_slope_deg, 89.999))) + EPSILON
    steps = np.abs(np.diff(level.heights))
    linked = standable[:-1] & standable[1:] & (steps <= tolerance)
    spans: list[Span] = []
    columns = np.flatnonzero(standable)
    if columns.size:
        breaks = np.flatnonzero(~linked[columns[:-1]] | (np.diff(columns) != 1)) + 1
        for number, run in enumerate(np.split(columns, breaks)):
            spans.append(Span(f"ground-{number}", "ground", run + level.x0, level.heights[run]))
    for deck in level.decks:
        start, stop = _covered_columns(deck["x0"], deck["x1"])
        if stop < start:
            continue
        run = np.arange(start, stop + 1)
        spans.append(Span(f"deck-{deck['id']}", "deck", run, np.full(run.shape, deck["y"]), deck["id"]))
    return spans


def _samples(span: Span, lo: float, hi: float) -> np.ndarray:
    """Up to MAX_SAMPLES column positions of `span` inside [lo, hi], always keeping its ends."""
    mask = (span.columns + 0.5 >= lo) & (span.columns + 0.5 <= hi)
    chosen = np.flatnonzero(mask)
    if chosen.size > MAX_SAMPLES:
        chosen = chosen[np.unique(np.linspace(0, chosen.size - 1, MAX_SAMPLES).round().astype(int))]
    return chosen


def find_jump(level: Level, source: Span, target: Span, max_reach: float) -> dict[str, Any] | None:
    """A take-off column on `source` and a landing column on `target` the arc connects, or None."""
    physics = level.physics
    take = _samples(source, target.x0 - max_reach, target.x1 + max_reach)
    land = _samples(target, source.x0 - max_reach, source.x1 + max_reach)
    if not take.size or not land.size:
        return None
    xa, ya = source.columns[take] + 0.5, source.heights[take]
    xb, yb = target.columns[land] + 0.5, target.heights[land]
    distance = np.abs(xb[None, :] - xa[:, None])
    rise = ya[:, None] - yb[None, :]
    feasible = (rise <= physics.jump_height + EPSILON) & (distance <= physics.reach(rise) + EPSILON)
    candidates = np.argwhere(feasible)
    if not candidates.size:
        return None
    order = np.lexsort((np.abs(rise[feasible]), distance[feasible]))
    for i, j in candidates[order][:32]:
        if _clear(level, xa[i], ya[i], xb[j], yb[j]):
            return {"from": [float(xa[i]), float(ya[i])], "to": [float(xb[j]), float(yb[j])],
                    "distance": float(distance[i, j]), "rise": float(rise[i, j]),
                    "reach": float(physics.reach(rise[i, j]))}
    return None


def arc_points(physics: Physics, start: tuple[float, float], end: tuple[float, float], count: int = 33) -> np.ndarray:
    """The arc from `start` that lands at `end` with horizontal speed slowed to fit (y down)."""
    (xa, ya), (xb, yb) = start, end
    rise = ya - yb
    full = float(physics.reach(rise))
    t = np.linspace(0, full, count)
    xs = xa + np.sign(xb - xa) * t * (abs(xb - xa) / full if full > 0 else 0)
    return np.column_stack([xs, ya - physics.height(t)])


def _clear(level: Level, xa: float, ya: float, xb: float, yb: float) -> bool:
    """The arc stays above solid ground at every column strictly between take-off and landing."""
    lo, hi = sorted((xa, xb))
    columns = np.arange(math.floor(lo + 0.5), math.ceil(hi - 0.5)) - level.x0
    columns = columns[(columns >= 0) & (columns < level.width)]
    columns = columns[(columns + level.x0 + 0.5 > lo) & (columns + level.x0 + 0.5 < hi)]
    solid = columns[level.classes[columns] == 0]
    if not solid.size:
        return True
    physics = level.physics
    full = float(physics.reach(ya - yb))
    progress = np.abs(solid + level.x0 + 0.5 - xa) / max(abs(xb - xa), EPSILON)
    actor_y = ya - physics.height(progress * full)
    return bool((actor_y <= level.heights[solid] + EPSILON).all())


def link_spans(level: Level, spans: list[Span]) -> None:
    """Directed jump/drop/walk-across edges between spans (stored as indices in Span.edges)."""
    if not spans:
        return
    tops = np.concatenate([span.heights for span in spans])
    max_reach = float(level.physics.reach(tops.min() - tops.max()))
    for i, source in enumerate(spans):
        for j, target in enumerate(spans):
            if i == j or target.x0 - source.x1 > max_reach or source.x0 - target.x1 > max_reach:
                continue
            if find_jump(level, source, target, max_reach) is not None:
                source.edges.append(j)


def reach_from(spans: list[Span], starts: list[int]) -> set[int]:
    reached = set(starts)
    queue = deque(starts)
    while queue:
        for neighbour in spans[queue.popleft()].edges:
            if neighbour not in reached:
                reached.add(neighbour)
                queue.append(neighbour)
    return reached


def span_at(spans: list[Span], x: float, y: float | None, tolerance: float) -> int | None:
    """The span under (x, y): the surface within tolerance, or the first span covering x when y is None."""
    column = math.floor(x)
    best = None
    for index, span in enumerate(spans):
        if not span.x0 <= column < span.x1:
            continue
        top = span.heights[column - span.x0]
        if y is None:
            if best is None or span.kind == "ground":
                best = index
            continue
        if abs(top - y) <= tolerance + EPSILON:
            return index
    return best


# --------------------------------------------------------------------------- checks

def _check(ident: str, status: str, value: Any = None, threshold: Any = None) -> dict[str, Any]:
    return {"id": ident, "status": status, "value": value, "threshold": threshold}


def check_segments(level: Level) -> dict[str, Any]:
    problems = []
    ordered = sorted(level.segments)
    for (a0, a1, kind_a, _), (b0, b1, kind_b, _) in zip(ordered, ordered[1:]):
        if b0 > a1:
            problems.append(f"hole between x={a1} and x={b0} (no segment; counted as a gap)")
        elif b0 < a1:
            problems.append(f"segments [{a0}, {a1}, {kind_a}] and [{b0}, {b1}, {kind_b}] overlap")
    return _check("segments", "fail" if problems else "pass", problems)


def check_props(level: Level) -> tuple[dict[str, Any], list[dict[str, Any]]]:
    """Every footprint column of a prop needs ground or a deck within the tolerance under its base."""
    tolerance = level.physics.ground_tolerance
    results, floating, sunk = [], [], []
    for prop in level.props:
        if prop["w"] > 0:
            start, stop = _covered_columns(prop["x"] - prop["w"] / 2, prop["x"] + prop["w"] / 2)
            columns = np.arange(start, max(start, stop) + 1)
        else:
            columns = np.array([math.floor(prop["x"])])
        index = columns - level.x0
        inside = (index >= 0) & (index < level.width)
        ground = np.full(columns.shape, np.nan)
        ground[inside] = np.where(level.classes[index[inside]] == 0, level.heights[index[inside]], np.nan)
        supported = np.abs(ground - prop["y"]) <= tolerance + EPSILON
        for deck in level.decks:
            covered = (columns + 0.5 >= deck["x0"]) & (columns + 0.5 < deck["x1"])
            supported |= covered & (abs(deck["y"] - prop["y"]) <= tolerance + EPSILON)
        sunk_columns = ~supported & (ground < prop["y"] - tolerance - EPSILON)
        floating_columns = ~supported & ~sunk_columns
        status = "allowed" if prop["floating"] else (
            "floating" if floating_columns.any() else ("sunk" if sunk_columns.any() else "supported"))
        gaps = ground[floating_columns] - prop["y"]
        result = {"id": prop["id"], "x": prop["x"], "y": prop["y"], "w": prop["w"], "status": status,
                  "floating_columns": int(floating_columns.sum()), "sunk_columns": int(sunk_columns.sum()),
                  "max_gap_px": None if not np.isfinite(gaps).any() else float(np.nanmax(gaps))}
        results.append(result)
        if status == "floating":
            gap_text = "over a gap" if result["max_gap_px"] is None else f"up to {result['max_gap_px']:g} px above"
            floating.append(f"prop {prop['id']} at x={prop['x']:g}: {result['floating_columns']} of {columns.size} "
                            f"columns float ({gap_text} the ground)")
        elif status == "sunk":
            sunk.append(f"prop {prop['id']} at x={prop['x']:g}: {result['sunk_columns']} columns sit below the "
                        f"ground surface")
    status = "fail" if floating else ("warn" if sunk else "pass")
    return _check("prop_support", status, floating + sunk, {"ground_tolerance_px": tolerance}), results


def check_decks(level: Level) -> dict[str, Any]:
    minimum = level.physics.min_deck_thickness
    thin = [f"deck {deck['id']} is {deck['thickness']:g} px thick; a standing body sinks through decks under "
            f"{minimum:g} px" for deck in level.decks if deck["thickness"] < minimum - EPSILON]
    return _check("deck_thickness", "fail" if thin else "pass", thin, {"min_px": minimum})


def check_slopes(level: Level) -> tuple[dict[str, Any], dict[str, Any]]:
    physics = level.physics
    steep = [f"slope x={piece['x0']:g}..{piece['x1']:g} is {piece['angle_deg']:g} deg over {piece['rise']:g} px "
             f"(max {physics.max_slope_deg:g} deg, or rises up to stepUp {physics.step_up:g} px); make it a "
             f"vertical ledge or flatten it" for piece in level.pieces if piece["kind"] == "steep"]
    ledges = [piece for piece in level.pieces if piece["kind"] == "ledge"]
    tall = [f"ledge at x={piece['x']:g} is {piece['height']:g} px, above jumpHeight {physics.jump_height:g}: "
            f"impassable going {piece['up']}" for piece in ledges if piece["height"] > physics.jump_height + EPSILON]
    return (_check("slope_limit", "fail" if steep else "pass", steep,
                   {"max_slope_deg": physics.max_slope_deg, "step_up_px": physics.step_up}),
            _check("step_limit", "warn" if tall else "pass",
                   {"ledges": [{"x": piece["x"], "height": piece["height"], "up": piece["up"]} for piece in ledges],
                    "impassable": tall},
                   {"step_up_px": physics.step_up, "jump_height_px": physics.jump_height}))


def check_gaps(level: Level, spans: list[Span]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
    """The far side of each gap or hazard run is reachable from the near side (possibly over decks)."""
    physics = level.physics
    runs, results, failures = [], [], []
    blocked = level.classes != 0
    columns = np.flatnonzero(blocked)
    if columns.size:
        runs = np.split(columns, np.flatnonzero(np.diff(columns) != 1) + 1)
    ground_spans = [index for index, span in enumerate(spans) if span.kind == "ground"]
    for run in runs:
        x0, x1 = int(run[0]) + level.x0, int(run[-1]) + 1 + level.x0
        kind = CLASSES[int(level.classes[run[0]])]
        near = next((i for i in ground_spans if spans[i].x1 == x0), None)
        far = next((i for i in ground_spans if spans[i].x0 == x1), None)
        result = {"x0": x0, "x1": x1, "width": x1 - x0, "kind": kind, "near": None, "far": None,
                  "direct": None, "crossable": None}
        if near is None or far is None:
            result["note"] = "level edge or no standable ground beside it; not judged"
            results.append(result)
            continue
        result["near"], result["far"] = spans[near].id, spans[far].id
        direct = find_jump(level, spans[near], spans[far], float("inf"))
        rise = float(spans[near].heights[-1] - spans[far].heights[0])
        result["direct"] = direct or {"distance": x1 - x0 + 1.0, "rise": rise,
                                      "reach": float(physics.reach(rise)), "feasible": False}
        if direct:
            result["direct"]["feasible"] = True
        result["crossable"] = far in reach_from(spans, [near])
        if not result["crossable"]:
            failures.append(f"{kind} x={x0}..{x1} ({x1 - x0} px) cannot be crossed: best reach "
                            f"{result['direct']['reach']:.1f} px at rise {rise:g} px, jumpHeight "
                            f"{physics.jump_height:g}, jumpDistance {physics.jump_distance:g}")
        results.append(result)
    return _check("gaps_jumpable", "fail" if failures else "pass", failures,
                  {"jump_height_px": physics.jump_height, "jump_distance_px": physics.jump_distance}), results


def check_reachability(level: Level, spans: list[Span]) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    tolerance = level.physics.ground_tolerance
    ungrounded, homes = [], []
    for spawn in level.spawns:
        index = span_at(spans, spawn["x"], spawn["y"], tolerance)
        homes.append(index)
        if index is None:
            ungrounded.append(f"spawn {spawn['id']} at ({spawn['x']:g}, {spawn['y']:g}) is not on ground or a deck")
    grounded = _check("spawns_grounded", "fail" if ungrounded else ("pass" if level.spawns else "skipped"),
                      ungrounded or (None if level.spawns else "no spawns"), {"ground_tolerance_px": tolerance})
    if not level.spawns or homes[0] is None:
        reason = "no spawns" if not level.spawns else "the first spawn is not on a surface"
        return grounded, _check("reachability", "fail" if level.spawns else "skipped", reason), {}
    reached = reach_from(spans, [homes[0]])
    for index in reached:
        spans[index].reachable = True
    failures, warnings, targets = [], [], []
    for spawn, home in zip(level.spawns[1:], homes[1:]):
        if home is not None:
            targets.append(("spawn", spawn["id"], home))
    for exit_point in level.exits:
        home = span_at(spans, exit_point["x"], exit_point.get("y"), tolerance)
        if home is None:
            failures.append(f"exit {exit_point['id']} at x={exit_point['x']:g} is not on a surface")
        else:
            targets.append(("exit", exit_point["id"], home))
    if not level.exits:
        ground = [index for index, span in enumerate(spans) if span.kind == "ground"]
        if ground:
            last = max(ground, key=lambda index: spans[index].x1)
            targets.append(("level end", f"x={spans[last].x1}", last))
    for kind, ident, home in targets:
        if home not in reached:
            failures.append(f"{kind} {ident} ({spans[home].id}) cannot be reached from spawn {level.spawns[0]['id']}")
    for index, span in enumerate(spans):
        if span.kind == "deck" and index not in reached:
            warnings.append(f"deck {span.source} cannot be reached")
    status = "fail" if failures else ("warn" if warnings else "pass")
    summary = {"start": level.spawns[0]["id"], "reached_spans": sorted(spans[i].id for i in reached),
               "unreached_spans": sorted(span.id for i, span in enumerate(spans) if i not in reached)}
    return grounded, _check("reachability", status, failures + warnings), summary


def parse_viewports(document: dict[str, Any]) -> tuple[list[tuple[str, float | None, float | None]], float | None]:
    """(label, width or None, aspect or None) for every viewport plus the default 16:9 and 19.5:9."""
    entries = document.get("viewports", []) or []
    camera = document.get("camera", {}) or {}
    if not isinstance(camera, dict):
        raise ValueError("camera must be an object such as {\"viewHeight\": 270, \"travel\": 80}.")
    view_height = camera.get("viewHeight")
    view_height = None if view_height is None else _number(view_height, "camera.viewHeight", minimum=0,
                                                           exclusive=True)
    sizes, aspects = [], []
    for index, entry in enumerate(entries):
        if isinstance(entry, list) and len(entry) == 2:
            width = _number(entry[0], f"viewports[{index}][0]", minimum=0, exclusive=True)
            height = _number(entry[1], f"viewports[{index}][1]", minimum=0, exclusive=True)
            sizes.append((f"{width:g}x{height:g}", width, None))
            view_height = view_height or height
        elif isinstance(entry, str) and re.fullmatch(r"[0-9]+(\.[0-9]+)?:[0-9]+(\.[0-9]+)?", entry):
            aspects.append(entry)
        else:
            raise ValueError(f"viewports[{index}] must be [width, height] or an aspect such as 19.5:9.")
    for aspect in DEFAULT_ASPECTS:
        if aspect not in aspects:
            aspects.append(aspect)
    for aspect in aspects:
        across, down = (float(part) for part in aspect.split(":"))
        sizes.append((aspect, None, across / down))
    return sizes, view_height


def check_arenas(document: dict[str, Any], level: Level) -> tuple[dict[str, Any], list[dict[str, Any]]]:
    viewports, view_height = parse_viewports(document)
    camera = document.get("camera", {}) or {}
    default_travel = _number(camera.get("travel", 0), "camera.travel", minimum=0)
    arenas = document.get("arenas") or [{"id": "level", "x0": level.x0, "x1": level.x1}]
    results, failures, skipped = [], [], []
    for index, arena in enumerate(arenas):
        if not isinstance(arena, dict):
            raise ValueError(f"arenas[{index}] must be an object with id, x0 and x1.")
        ident = str(arena.get("id", f"arena-{index}"))
        x0, x1 = _number(arena.get("x0"), f"arena {ident} x0"), _number(arena.get("x1"), f"arena {ident} x1")
        travel = _number(arena.get("travel", default_travel), f"arena {ident} travel", minimum=0)
        for label, width, aspect in viewports:
            view = width if width is not None else (None if view_height is None else view_height * aspect)
            if view is None:
                skipped.append(f"{ident} at {label}: no camera.viewHeight or [w, h] viewport")
                continue
            need = view + travel
            ok = x1 - x0 >= need - EPSILON
            results.append({"arena": ident, "viewport": label, "arena_width": x1 - x0, "view_width": round(view, 3),
                            "travel": travel, "needed": round(need, 3), "status": "pass" if ok else "fail"})
            if not ok:
                failures.append(f"arena {ident} is {x1 - x0:g} px wide; {label} needs {need:.1f} px "
                                f"(view {view:.1f} + travel {travel:g})")
    status = "fail" if failures else ("pass" if results else "skipped")
    value = failures if failures else (results if results else skipped)
    return _check("arena_width", status, value, {"aspects": list(DEFAULT_ASPECTS), "view_height": view_height}), \
        results


# --------------------------------------------------------------------------- validation

def validate(document: Any) -> dict[str, Any]:
    level = parse_level(document)
    spans = build_spans(level)
    link_spans(level, spans)
    checks = [check_segments(level)]
    slope_check, step_check = check_slopes(level)
    checks += [slope_check, step_check, check_decks(level)]
    prop_check, prop_results = check_props(level)
    checks.append(prop_check)
    grounded, reachability, reach_summary = check_reachability(level, spans)
    gap_check, gaps = check_gaps(level, spans)
    arena_check, arenas = check_arenas(document, level)
    checks += [grounded, gap_check, reachability, arena_check]
    statuses = {check["status"] for check in checks}
    return {
        "status": "fail" if "fail" in statuses else ("warn" if "warn" in statuses else "pass"),
        "extent": {"x0": level.x0, "x1": level.x1},
        "physics": {"jumpHeight": level.physics.jump_height, "jumpDistance": level.physics.jump_distance,
                    "maxSlopeDeg": level.physics.max_slope_deg, "stepUp": level.physics.step_up,
                    "colliderSubstep": level.physics.collider_substep,
                    "minDeckThickness": level.physics.min_deck_thickness,
                    "groundTolerance": level.physics.ground_tolerance},
        "spans": [{"id": span.id, "kind": span.kind, "x0": span.x0, "x1": span.x1,
                   "top_min": float(span.heights.min()), "top_max": float(span.heights.max()),
                   "reachable": span.reachable} for span in spans],
        "pieces": level.pieces, "gaps": gaps, "props": prop_results, "arenas": arenas,
        "reachability": reach_summary, "checks": checks,
        "_level": level, "_spans": spans,
    }


def messages_of(report: dict[str, Any], status: str = "fail", limit: int = 8) -> list[str]:
    """The first messages of checks with `status` (fail or warn), for the console summary."""
    found = []
    for check in report["checks"]:
        if check["status"] != status:
            continue
        value = check["value"]
        if isinstance(value, str):
            items = [value]
        elif isinstance(value, list):
            items = [item for item in value if isinstance(item, str)]
        elif isinstance(value, dict):
            items = [item for key in ("problems", "warnings", "impassable") for item in value.get(key) or []]
            if value.get("unreached"):
                items.append(f"unreachable chunks {value['unreached']}")
        else:
            items = []
        found += [f"{check['id']}: {item}" for item in items]
    return [forge_core.ascii_text(item) for item in found[:limit]]


# --------------------------------------------------------------------------- debug image

def render_debug(report: dict[str, Any]) -> Image.Image:
    """Side view: ground, gaps, hazards, steep faces, decks, props, spawns, exits, reachable tops and gap arcs."""
    level: Level = report["_level"]
    spans: list[Span] = report["_spans"]
    physics = level.physics
    tops = [level.heights[np.isfinite(level.heights)]] + [np.array([deck["y"]]) for deck in level.decks]
    tops += [np.array([item["y"]]) for item in level.props + level.spawns]
    values = np.concatenate([array for array in tops if array.size]) if any(a.size for a in tops) else np.array([0.0])
    y_top = math.floor(values.min() - physics.jump_height - 24)
    y_bottom = math.ceil(values.max() + 40)
    width, height = level.width, max(1, y_bottom - y_top)
    # Drawn at one world px per pixel, or scaled down as a whole to fit DEBUG_WIDTH x DEBUG_HEIGHT: a full-size
    # canvas of a very wide or tall level would take gigabytes (review r1, finding 4).
    scale = min(1.0, DEBUG_WIDTH / width, DEBUG_HEIGHT / height)
    fit = (lambda size: max(1, math.floor(size * scale * (1 + 1e-12))))  # never past the box (rounding snapped)
    columns = (np.arange(width) if scale == 1.0 else
               np.minimum((np.arange(fit(width)) + 0.5) / scale, width - 1).astype(np.int64))
    canvas_h = height if scale == 1.0 else fit(height)
    classes, heights = level.classes[columns], level.heights[columns]
    canvas = np.empty((canvas_h, columns.size, 4), np.uint8)
    canvas[...] = COLORS["sky"]
    rows = np.arange(canvas_h)[:, None] / scale + y_top
    ground = (classes == 0)[None, :] & (rows >= np.nan_to_num(heights, nan=np.inf)[None, :])
    canvas[ground] = COLORS["ground"]
    face = ground & level.face[columns][None, :]
    canvas[face] = COLORS["face"]
    canvas[canvas_h - max(1, round(24 * scale)):, classes == 2] = COLORS["hazard"]
    canvas[canvas_h - max(1, round(6 * scale)):, classes == 1] = COLORS["gap"]
    image = Image.fromarray(canvas)
    draw = ImageDraw.Draw(image)
    step = max(1, math.floor(1 / scale))  # one span point per drawn pixel column is enough

    def at(x: float, y: float) -> tuple[float, float]:
        return (x - level.x0) * scale, (y - y_top) * scale

    for deck in level.decks:
        color = COLORS["bad"] if deck["thickness"] < physics.min_deck_thickness - EPSILON else COLORS["deck"]
        draw.rectangle([at(deck["x0"], deck["y"]),
                        at(max(deck["x0"], deck["x1"] - 1), deck["y"] + max(deck["thickness"], 1) - 1)], fill=color)
    for span in spans:
        color = COLORS["ok"] if span.reachable else COLORS["bad"]
        keep = np.unique(np.r_[np.arange(0, span.columns.size, step), span.columns.size - 1])
        points = [at(x + 0.5, y) for x, y in zip(span.columns[keep], span.heights[keep])]
        if len(points) == 1:
            points.append((points[0][0] + 1, points[0][1]))
        draw.line(points, fill=color, width=2)
    for gap in report["gaps"]:
        direct = gap.get("direct")
        if not direct or "from" not in direct:
            if direct and gap.get("near"):
                near = next(span for span in spans if span.id == gap["near"])
                start = (near.x1 - 0.5, float(near.heights[-1]))
                reach = float(physics.reach(0.0))
                end = (start[0] + reach, start[1])
                draw.line([at(*point) for point in arc_points(physics, start, end)], fill=COLORS["bad"], width=1)
            continue
        draw.line([at(*point) for point in arc_points(physics, tuple(direct["from"]), tuple(direct["to"]))],
                  fill=COLORS["arc"], width=1)
    for prop in report["props"]:
        color = {"floating": COLORS["bad"], "sunk": COLORS["warn"]}.get(prop["status"], COLORS["prop"])
        half = max(prop["w"] / 2, 1)
        draw.rectangle([at(prop["x"] - half, prop["y"] - 12), at(prop["x"] + half - 1, prop["y"] - 1)],
                       outline=color, width=2)
    for spawn in level.spawns:
        x, y = at(spawn["x"], spawn["y"])
        draw.polygon([(x, y - 14), (x - 6, y), (x + 6, y)], fill=COLORS["spawn"])
    for exit_point in level.exits:
        home = span_at(spans, exit_point["x"], exit_point.get("y"), physics.ground_tolerance)
        surface = (spans[home].heights[math.floor(exit_point["x"]) - spans[home].x0] if home is not None
                   else y_top + height - 30)
        x, y = at(exit_point["x"], exit_point.get("y", surface))
        draw.rectangle([x - 4, y - 16, x + 4, y], fill=COLORS["exit"])
    if scale == 1.0 and width < 512:
        factor = max(1, 512 // width)
        image = image.resize((width * factor, height * factor), Image.Resampling.NEAREST)
    return image


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

def run(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
    try:
        document = forge_core.read_json(args.layout, strict=True)  # D28
    except ValueError as error:
        raise ValueError(f"{Path(args.layout).name} is not valid JSON ({error}).") from None
    report = validate(document)
    failed = [check["id"] for check in report["checks"] if check["status"] == "fail"]
    summary: dict[str, Any] = {"status": report["status"], "spans": len(report["spans"]), "failed": failed,
                               "problems": messages_of(report), "warnings": messages_of(report, "warn")}
    if args.output_dir is None:
        return summary, 1 if failed else 0
    if args.strict_qc and failed:
        raise ValueError(f"strict QC failed ({', '.join(failed)}); nothing was written.")
    final = Path(args.output_dir)
    with forge_core.staged_output(final) as stage:
        forge_core.save_png(render_debug(report), stage / "layout-debug.png")
        public = {key: value for key, value in report.items() if not key.startswith("_") and key != "checks"}
        record = {"schema": REPORT_SCHEMA, "tool": dict(TOOL), **public,
                  "qa": {"status": report["status"],
                         "method": "validate_layout: per-column ground from segments and the surface polyline; "
                                   "standable spans linked by a parabolic jump arc (apex jumpHeight, range "
                                   "jumpDistance) checked for clearance over solid columns; breadth-first search "
                                   "from the first spawn; base-line support for props.",
                         "notProven": list(NOT_PROVEN), "checks": report["checks"],
                         "inputs": [forge_core.file_ref(Path(args.layout), final)],
                         "outputs": [forge_core.file_ref(stage / "layout-debug.png", stage)], "tool": dict(TOOL)}}
        forge_core.write_json(stage / "layout-report.json", record)
    summary.update(output_dir=str(final.resolve()), report=str((final / "layout-report.json").resolve()),
                   metadata=str((final / "layout-report.json").resolve()),
                   debug=str((final / "layout-debug.png").resolve()))
    return summary, forge_core.EXIT_PUBLISHED_FAIL if failed else 0


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--layout", type=Path, required=True, help="layout.v1 JSON (schema generate2dmap.layout.v1).")
    parser.add_argument("--output-dir", type=Path,
                        help="New folder for layout-report.json and layout-debug.png; must not exist. "
                             "Omit to print the summary only.")
    parser.add_argument("--strict-qc", action="store_true",
                        help="With --output-dir: publish nothing when a check fails.")
    return parser


def _main(argv: Sequence[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    summary, code = run(args)
    if code:
        print("error: layout validation failed: " + "; ".join(summary["problems"][:3] or summary["failed"]),
              file=sys.stderr)
    print(json.dumps(summary, ensure_ascii=True))
    return code


def main(argv: Sequence[str] | None = None) -> int:
    """Exit 0 (pass or warn), 1 (a failed check, its report published when --output-dir is given; or an error),
    2 (usage) (D26, D27)."""
    return forge_core.run_cli(_main, argv)


if __name__ == "__main__":
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall