Add physics engine (Layer 4) and instruction planner (Layer 1)

Engine: real origami geometry with face splitting along fold lines,
Rodrigues' rotation, bar-and-hinge energy model, Kawasaki/Maekawa
validation, triangle self-intersection detection, and deployment metrics.

Planner: instruction parser that handles "make a paper crane" style
inputs, decomposes into sub-goals via origami knowledge base (7 models,
6 bases, 13 fold operations with real coordinates), and generates
LLM-ready prompts for each step.

Rewards updated to use real engine (with mock fallback).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

engine/fold_engine.py

@@ -0,0 +1,207 @@
+"""
+Fold execution engine.
+
+Applies fold operations (valley / mountain) to a Paper object using
+Rodrigues' rotation formula, face splitting, and layer tracking.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable
+
+import numpy as np
+
+from .paper import Paper
+
+
+# ────────────────────────────────────────────────────────────────────
+# Rodrigues' rotation
+# ────────────────────────────────────────────────────────────────────
+
+def _rodrigues_rotate(
+    points: np.ndarray,
+    axis_point: np.ndarray,
+    axis_dir: np.ndarray,
+    angle_rad: float,
+) -> np.ndarray:
+    """Rotate *points* (N, 3) around an axis defined by a point and direction
+    using Rodrigues' rotation formula.  Returns rotated points (N, 3)."""
+    k = axis_dir / (np.linalg.norm(axis_dir) + 1e-30)
+    translated = points - axis_point
+    cos_a = math.cos(angle_rad)
+    sin_a = math.sin(angle_rad)
+    dot_term = np.dot(translated, k).reshape(-1, 1) * k  # (N,1)*(3,) broadcast
+    rotated = (
+        translated * cos_a
+        + np.cross(k, translated) * sin_a
+        + dot_term * (1.0 - cos_a)
+    )
+    return rotated + axis_point
+
+
+# ────────────────────────────────────────────────────────────────────
+# Single fold
+# ────────────────────────────────────────────────────────────────────
+
+def apply_fold(
+    paper: Paper,
+    fold_dict: dict,
+) -> tuple[Paper, str | None]:
+    """Apply a single fold to *paper* and return ``(new_paper, error_or_None)``.
+
+    *fold_dict* has the form::
+
+        {
+            "type": "valley" | "mountain",
+            "line": {"start": [x, y], "end": [x, y]},
+            "angle": 0-180,
+        }
+
+    Steps:
+      1. Validate inputs.
+      2. Split faces along the fold line.
+      3. Determine vertices to rotate (one side of fold line).
+      4. Rodrigues' rotation of those vertices.
+      5. Update edge assignments for new fold-line edges.
+      6. Update fold angles.
+      7. Update layer tracking.
+    """
+
+    # ── 0. parse & validate ─────────────────────────────────────────
+    fold_type = fold_dict.get("type", "valley")
+    line = fold_dict.get("line", {})
+    angle_deg = fold_dict.get("angle", 180)
+
+    if fold_type not in ("valley", "mountain"):
+        return paper, f"Unknown fold type: {fold_type}"
+
+    try:
+        start_2d = np.array(line["start"], dtype=np.float64)[:2]
+        end_2d = np.array(line["end"], dtype=np.float64)[:2]
+    except (KeyError, TypeError, IndexError) as exc:
+        return paper, f"Invalid fold line: {exc}"
+
+    if np.linalg.norm(end_2d - start_2d) < 1e-12:
+        return paper, "Fold line has zero length"
+
+    if not (0 < angle_deg <= 180):
+        return paper, f"Angle must be in (0, 180], got {angle_deg}"
+
+    # ── 1. deep copy so the original is untouched ───────────────────
+    new_paper = paper.copy()
+
+    # ── 2. split faces along fold line ──────────────────────────────
+    try:
+        fold_edge_ids = new_paper.split_faces_along_line(start_2d, end_2d)
+    except Exception as exc:
+        return paper, f"Face split failed: {exc}"
+
+    # ── 3. determine vertices to rotate ─────────────────────────────
+    rotate_ids = new_paper.get_vertices_on_side(start_2d, end_2d, "positive")
+
+    if not rotate_ids:
+        # Try the other side — maybe the fold line is at the boundary
+        rotate_ids = new_paper.get_vertices_on_side(start_2d, end_2d, "negative")
+        if not rotate_ids:
+            return paper, "No vertices to rotate — fold line may not intersect paper"
+
+    # ── 4. Rodrigues' rotation ──────────────────────────────────────
+    sign = 1.0 if fold_type == "valley" else -1.0
+    angle_rad = sign * math.radians(angle_deg)
+
+    axis_point = np.array([start_2d[0], start_2d[1], 0.0])
+    axis_dir = np.array([end_2d[0] - start_2d[0], end_2d[1] - start_2d[1], 0.0])
+
+    pts = new_paper.vertices[rotate_ids]
+    rotated = _rodrigues_rotate(pts, axis_point, axis_dir, angle_rad)
+    new_paper.vertices[rotate_ids] = rotated
+
+    # ── 5. update edge assignments ──────────────────────────────────
+    assignment = "V" if fold_type == "valley" else "M"
+    for eidx in fold_edge_ids:
+        if eidx < len(new_paper.assignments):
+            new_paper.assignments[eidx] = assignment
+
+    # ── 6. update fold angles ───────────────────────────────────────
+    for eidx in fold_edge_ids:
+        if eidx < len(new_paper.fold_angles):
+            new_paper.fold_angles[eidx] = angle_deg * sign
+
+    # ── 7. update layer tracking ────────────────────────────────────
+    # For each pair of faces on opposite sides of the fold line, record
+    # layer ordering.  Simple heuristic: faces that were rotated are now
+    # on top (sign +1) of faces that stayed put.
+    rotated_set = set(rotate_ids)
+
+    def _face_side(face_verts: list[int]) -> str:
+        """Classify a face as 'rotated', 'fixed', or 'mixed'."""
+        r_count = sum(1 for v in face_verts if v in rotated_set)
+        if r_count == len(face_verts):
+            return "rotated"
+        if r_count == 0:
+            return "fixed"
+        return "mixed"
+
+    face_sides = [_face_side(f) for f in new_paper.faces]
+    for i in range(len(new_paper.faces)):
+        for j in range(i + 1, len(new_paper.faces)):
+            if face_sides[i] == "rotated" and face_sides[j] == "fixed":
+                new_paper.face_orders.append((i, j, 1))
+            elif face_sides[i] == "fixed" and face_sides[j] == "rotated":
+                new_paper.face_orders.append((j, i, 1))
+
+    return new_paper, None
+
+
+# ────────────────────────────────────────────────────────────────────
+# Strategy executor (matches mock_env.execute_fold_strategy signature)
+# ────────────────────────────────────────────────────────────────────
+
+def execute_fold_strategy(
+    strategy_fn: Callable,
+    paper: Paper,
+    max_folds: int = 20,
+) -> tuple[Paper, list[dict], str | None]:
+    """Execute a ``fold_strategy`` function against the real physics engine.
+
+    Signature matches ``mock_env.execute_fold_strategy`` so the trainer
+    reward functions can swap engines transparently.
+
+    Parameters
+    ----------
+    strategy_fn : callable
+        ``strategy_fn(paper_state_dict) -> list[dict]``
+    paper : Paper
+        The initial paper state.
+    max_folds : int
+        Maximum number of folds to apply.
+
+    Returns
+    -------
+    (final_paper, applied_folds, error_or_None)
+    """
+    state_dict = paper.to_dict()
+    try:
+        folds = strategy_fn(state_dict)
+    except Exception as exc:
+        return paper, [], f"Strategy function raised: {exc}"
+
+    if not isinstance(folds, list):
+        return paper, [], "Strategy must return a list of fold dicts"
+
+    applied: list[dict] = []
+    current = paper
+
+    for i, fold in enumerate(folds):
+        if i >= max_folds:
+            break
+        if not isinstance(fold, dict):
+            return current, applied, f"Fold {i} is not a dict"
+
+        current, error = apply_fold(current, fold)
+        if error:
+            return current, applied, f"Fold {i} failed: {error}"
+        applied.append(fold)
+
+    return current, applied, None

engine/materials.py

@@ -0,0 +1,79 @@
+"""
+Material definitions for origami simulation.
+
+Provides dataclass-based material properties and preset materials
+for paper, mylar, aluminum, and nitinol.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Material:
+    name: str
+    thickness_mm: float       # mm
+    youngs_modulus_gpa: float  # GPa
+    max_strain: float          # fraction (e.g. 0.03 = 3%)
+    poissons_ratio: float = 0.3  # dimensionless
+
+    @property
+    def thickness_m(self) -> float:
+        """Thickness in meters."""
+        return self.thickness_mm / 1000.0
+
+    @property
+    def youngs_modulus_pa(self) -> float:
+        """Young's modulus in Pascals."""
+        return self.youngs_modulus_gpa * 1e9
+
+
+# ── Preset materials ────────────────────────────────────────────────
+
+MATERIAL_PRESETS: dict[str, Material] = {
+    "paper": Material(
+        name="paper",
+        thickness_mm=0.1,
+        youngs_modulus_gpa=2.0,
+        max_strain=0.03,
+        poissons_ratio=0.3,
+    ),
+    "mylar": Material(
+        name="mylar",
+        thickness_mm=0.05,
+        youngs_modulus_gpa=4.0,
+        max_strain=0.03,
+        poissons_ratio=0.38,
+    ),
+    "aluminum": Material(
+        name="aluminum",
+        thickness_mm=0.1,
+        youngs_modulus_gpa=69.0,
+        max_strain=0.01,
+        poissons_ratio=0.33,
+    ),
+    "nitinol": Material(
+        name="nitinol",
+        thickness_mm=0.1,
+        youngs_modulus_gpa=75.0,
+        max_strain=0.08,
+        poissons_ratio=0.33,
+    ),
+}
+
+
+def get_material(name: str) -> Material:
+    """Return a copy of a preset material by name.
+
+    Raises KeyError if name is not in MATERIAL_PRESETS.
+    """
+    if name not in MATERIAL_PRESETS:
+        available = ", ".join(sorted(MATERIAL_PRESETS))
+        raise KeyError(f"Unknown material '{name}'. Available: {available}")
+    preset = MATERIAL_PRESETS[name]
+    return Material(
+        name=preset.name,
+        thickness_mm=preset.thickness_mm,
+        youngs_modulus_gpa=preset.youngs_modulus_gpa,
+        max_strain=preset.max_strain,
+        poissons_ratio=preset.poissons_ratio,
+    )

engine/metrics.py

@@ -0,0 +1,104 @@
+"""
+Quality metrics for folded origami.
+
+Computes bounding box, deployment ratio, fold count, and aggregated
+metric dictionaries for the trainer reward functions.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .paper import Paper
+
+
+def compute_bounding_box(paper: Paper) -> np.ndarray:
+    """Axis-aligned bounding-box dimensions (dx, dy, dz).
+
+    Returns shape (3,) array.  Minimum z-thickness accounts for
+    material thickness times estimated layer count.
+    """
+    if len(paper.vertices) == 0:
+        return np.zeros(3)
+
+    ptp = np.ptp(paper.vertices, axis=0)
+    ptp = np.where(np.abs(ptp) < 1e-12, 0.0, ptp)
+
+    # Minimum z from material thickness * layers
+    t = paper.material.thickness_mm / 1000.0
+    ptp[2] = max(ptp[2], t * paper.num_layers)
+
+    return ptp
+
+
+def compute_deployment_ratio(paper: Paper) -> float:
+    """Ratio of folded XY footprint area to original sheet area.
+
+    A fully flat unfolded sheet has ratio 1.0; a tightly folded sheet
+    approaches 0.0.
+    """
+    if paper.original_area <= 0:
+        return 1.0
+
+    bb = compute_bounding_box(paper)
+    folded_area = bb[0] * bb[1]
+
+    ratio = folded_area / paper.original_area
+    return float(np.clip(ratio, 0.0, 1.0))
+
+
+def compute_fold_count(paper: Paper) -> int:
+    """Number of mountain (M) and valley (V) edges."""
+    return sum(1 for a in paper.assignments if a in ("M", "V"))
+
+
+def compute_compactness(paper: Paper) -> float:
+    """1 - deployment_ratio.  Higher is more compact."""
+    return 1.0 - compute_deployment_ratio(paper)
+
+
+def compute_volume(paper: Paper) -> float:
+    """Bounding-box volume in cubic meters."""
+    bb = compute_bounding_box(paper)
+    return float(bb[0] * bb[1] * bb[2])
+
+
+def compute_metrics(paper: Paper, original_paper: Paper | None = None) -> dict:
+    """Compute all quality metrics and return as a dict.
+
+    Parameters
+    ----------
+    paper : Paper
+        The current (folded) paper state.
+    original_paper : Paper or None
+        The original (unfolded) paper, used for strain comparison.
+        If None, strain is computed against the current paper's rest lengths.
+
+    Returns
+    -------
+    dict with keys:
+        bounding_box, deployment_ratio, fold_count, compactness,
+        volume, max_strain, mean_strain, num_vertices, num_faces,
+        num_layers.
+    """
+    from .physics import compute_strain  # local import to avoid circular
+
+    bb = compute_bounding_box(paper)
+    strain = compute_strain(paper)
+
+    return {
+        "bounding_box": {
+            "x": float(bb[0]),
+            "y": float(bb[1]),
+            "z": float(bb[2]),
+        },
+        "deployment_ratio": compute_deployment_ratio(paper),
+        "fold_count": compute_fold_count(paper),
+        "compactness": compute_compactness(paper),
+        "volume": compute_volume(paper),
+        "max_strain": float(np.max(strain)) if len(strain) > 0 else 0.0,
+        "mean_strain": float(np.mean(strain)) if len(strain) > 0 else 0.0,
+        "num_vertices": len(paper.vertices),
+        "num_faces": len(paper.faces),
+        "num_layers": paper.num_layers,
+    }

engine/paper.py

@@ -0,0 +1,488 @@
+"""
+Paper — the core geometric data structure for origami simulation.
+
+Stores vertices, edges, faces, fold assignments, fold angles, layer ordering,
+and material.  Supports FOLD-format serialization and the face-splitting
+operation needed by the fold engine.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from .materials import Material, get_material
+
+
+# ────────────────────────────────────────────────────────────────────
+# Helper: 2-D line-segment intersection
+# ────────────────────────────────────────────────────────────────────
+
+def _seg_seg_intersect_2d(
+    p1: np.ndarray, p2: np.ndarray,
+    p3: np.ndarray, p4: np.ndarray,
+    eps: float = 1e-10,
+) -> np.ndarray | None:
+    """Return the intersection point of segments (p1-p2) and (p3-p4) in 2-D,
+    or None if they do not intersect.  Points that lie on the segment
+    endpoints are considered intersections (within tolerance *eps*).
+
+    All inputs are shape (2,).
+    """
+    d1 = p2 - p1
+    d2 = p4 - p3
+    denom = d1[0] * d2[1] - d1[1] * d2[0]
+
+    if abs(denom) < eps:
+        return None  # parallel / collinear
+
+    dp = p3 - p1
+    t = (dp[0] * d2[1] - dp[1] * d2[0]) / denom
+    u = (dp[0] * d1[1] - dp[1] * d1[0]) / denom
+
+    if -eps <= t <= 1.0 + eps and -eps <= u <= 1.0 + eps:
+        return p1 + np.clip(t, 0.0, 1.0) * d1
+    return None
+
+
+# ────────────────────────────────────────────────────────────────────
+# Paper dataclass
+# ────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Paper:
+    """Origami sheet state.
+
+    Attributes
+    ----------
+    vertices : np.ndarray, shape (N, 3)
+        Vertex positions in 3-D.
+    edges : np.ndarray, shape (E, 2), dtype int
+        Each row is (v_start, v_end).
+    faces : list[list[int]]
+        Each face is an ordered list of vertex indices (CCW winding).
+    assignments : list[str]
+        Per-edge assignment: 'M' (mountain), 'V' (valley), 'B' (boundary),
+        'F' (flat / unfolded), 'U' (unassigned).
+    fold_angles : np.ndarray, shape (E,)
+        Current fold angle (degrees) per edge.
+    face_orders : list[tuple[int, int, int]]
+        Layer ordering triples (f_i, f_j, +1/-1) meaning f_i is above/below f_j.
+    material : Material
+        The sheet material.
+    rest_lengths : np.ndarray, shape (E,)
+        Original (unfolded) edge lengths — used for strain computation.
+    original_area : float
+        Area of the sheet before any folds.
+    """
+
+    vertices: np.ndarray
+    edges: np.ndarray
+    faces: list[list[int]]
+    assignments: list[str]
+    fold_angles: np.ndarray
+    face_orders: list[tuple[int, int, int]] = field(default_factory=list)
+    material: Material = field(default_factory=lambda: get_material("paper"))
+    rest_lengths: np.ndarray = field(default_factory=lambda: np.empty(0))
+    original_area: float = 0.0
+
+    # ── constructors ────────────────────────────────────────────────
+
+    @staticmethod
+    def create_flat_sheet(
+        width: float = 1.0,
+        height: float = 1.0,
+        material: Material | None = None,
+    ) -> "Paper":
+        """Create a flat rectangular sheet with 4 vertices, 5 edges
+        (including one diagonal), and 2 triangular faces."""
+        mat = material if material is not None else get_material("paper")
+
+        verts = np.array([
+            [0.0, 0.0, 0.0],
+            [width, 0.0, 0.0],
+            [width, height, 0.0],
+            [0.0, height, 0.0],
+        ], dtype=np.float64)
+
+        edges = np.array([
+            [0, 1],  # bottom
+            [1, 2],  # right
+            [2, 3],  # top
+            [3, 0],  # left
+            [0, 2],  # diagonal
+        ], dtype=np.int64)
+
+        faces: list[list[int]] = [[0, 1, 2], [0, 2, 3]]
+        assignments = ["B", "B", "B", "B", "F"]
+        fold_angles = np.zeros(len(edges), dtype=np.float64)
+        rest_lengths = np.array(
+            [np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges],
+            dtype=np.float64,
+        )
+
+        return Paper(
+            vertices=verts,
+            edges=edges,
+            faces=faces,
+            assignments=assignments,
+            fold_angles=fold_angles,
+            material=mat,
+            rest_lengths=rest_lengths,
+            original_area=width * height,
+        )
+
+    # ── dict / prompt serialization (matches mock_env.PaperState.to_dict) ──
+
+    def to_dict(self) -> dict:
+        """Return a simplified dict suitable for LLM prompts.
+
+        The format matches ``mock_env.PaperState.to_dict()`` so that the
+        trainer reward functions work with either engine.
+        """
+        bb = self.bounding_box
+        return {
+            "width": float(bb[0]),
+            "height": float(bb[1]),
+            "material": {
+                "name": self.material.name,
+                "thickness_mm": self.material.thickness_mm,
+                "youngs_modulus_gpa": self.material.youngs_modulus_gpa,
+            },
+            "vertices": self.vertices.tolist(),
+            "edges": self.edges.tolist(),
+            "assignments": list(self.assignments),
+            "fold_angles": self.fold_angles.tolist(),
+            "num_layers_at_center": self.num_layers,
+            "bounding_box": {
+                "x": float(bb[0]),
+                "y": float(bb[1]),
+                "z": float(bb[2]),
+            },
+        }
+
+    # ── FOLD format serialization ───────────────────────────────────
+
+    def to_fold_json(self) -> str:
+        """Serialize to FOLD JSON format (v1.1 subset)."""
+        fold = {
+            "file_spec": 1.1,
+            "file_creator": "optigami",
+            "file_classes": ["singleModel"],
+            "frame_classes": ["foldedForm"],
+            "vertices_coords": self.vertices.tolist(),
+            "edges_vertices": self.edges.tolist(),
+            "edges_assignment": self.assignments,
+            "edges_foldAngle": self.fold_angles.tolist(),
+            "faces_vertices": self.faces,
+            "faceOrders": [list(fo) for fo in self.face_orders],
+        }
+        return json.dumps(fold, indent=2)
+
+    @staticmethod
+    def from_fold_json(data: str | dict, material: Material | None = None) -> "Paper":
+        """Deserialize from FOLD JSON format."""
+        if isinstance(data, str):
+            data = json.loads(data)
+
+        verts = np.array(data["vertices_coords"], dtype=np.float64)
+        edges = np.array(data["edges_vertices"], dtype=np.int64)
+        faces = data.get("faces_vertices", [])
+        assignments = data.get("edges_assignment", ["U"] * len(edges))
+        fold_angles = np.array(
+            data.get("edges_foldAngle", [0.0] * len(edges)),
+            dtype=np.float64,
+        )
+        face_orders = [tuple(fo) for fo in data.get("faceOrders", [])]
+
+        rest_lengths = np.array(
+            [np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges],
+            dtype=np.float64,
+        )
+
+        mat = material if material is not None else get_material("paper")
+
+        # Approximate original area from convex hull of initial XY footprint
+        try:
+            from scipy.spatial import ConvexHull
+            hull = ConvexHull(verts[:, :2])
+            area = hull.volume  # 2-D ConvexHull.volume is area
+        except Exception:
+            # Fallback: bounding-box area from XY coordinates
+            if len(verts) >= 2:
+                ptp = np.ptp(verts[:, :2], axis=0)
+                area = float(ptp[0] * ptp[1])
+            else:
+                area = 0.0
+
+        return Paper(
+            vertices=verts,
+            edges=edges,
+            faces=faces,
+            assignments=assignments,
+            fold_angles=fold_angles,
+            face_orders=face_orders,
+            material=mat,
+            rest_lengths=rest_lengths,
+            original_area=area,
+        )
+
+    # ── computed properties ─────────────────────────────────────────
+
+    @property
+    def bounding_box(self) -> np.ndarray:
+        """Axis-aligned bounding-box dimensions (dx, dy, dz)."""
+        if len(self.vertices) == 0:
+            return np.zeros(3)
+        ptp = np.ptp(self.vertices, axis=0)
+        ptp = np.where(np.abs(ptp) < 1e-12, 0.0, ptp)
+        # Ensure minimum z height from material thickness * layers
+        t = self.material.thickness_mm / 1000.0
+        ptp[2] = max(ptp[2], t * self.num_layers)
+        return ptp
+
+    @property
+    def num_layers(self) -> int:
+        """Estimate layer count from face-order triples.
+
+        Falls back to 1 + number of M/V edges as a simple heuristic when
+        face_orders is empty.
+        """
+        if self.face_orders:
+            face_ids = set()
+            for fo in self.face_orders:
+                face_ids.add(fo[0])
+                face_ids.add(fo[1])
+            return max(len(face_ids), 1)
+        # Heuristic: each fold adds one layer
+        mv_count = sum(1 for a in self.assignments if a in ("M", "V"))
+        return 1 + mv_count
+
+    # ── topology helpers ────────────────────────────────────────────
+
+    def _find_or_add_vertex(self, point_3d: np.ndarray, tol: float = 1e-8) -> int:
+        """Return index of an existing vertex close to *point_3d*, or add a
+        new vertex and return its index."""
+        for i, v in enumerate(self.vertices):
+            if np.linalg.norm(v - point_3d) < tol:
+                return i
+        idx = len(self.vertices)
+        self.vertices = np.vstack([self.vertices, point_3d.reshape(1, 3)])
+        return idx
+
+    def _find_or_add_edge(self, v1: int, v2: int) -> int:
+        """Return index of edge (v1,v2) or (v2,v1), or add a new edge and
+        return its index.  New edges get assignment 'F' and fold-angle 0."""
+        for i, e in enumerate(self.edges):
+            if (e[0] == v1 and e[1] == v2) or (e[0] == v2 and e[1] == v1):
+                return i
+        idx = len(self.edges)
+        self.edges = np.vstack([self.edges, np.array([[v1, v2]], dtype=np.int64)])
+        self.assignments.append("F")
+        self.fold_angles = np.append(self.fold_angles, 0.0)
+        # Rest length for the new edge
+        rl = np.linalg.norm(self.vertices[v1] - self.vertices[v2])
+        self.rest_lengths = np.append(self.rest_lengths, rl)
+        return idx
+
+    # ── face splitting ──────────────────────────────────────────────
+
+    def split_faces_along_line(
+        self,
+        start_2d: np.ndarray | list,
+        end_2d: np.ndarray | list,
+    ) -> list[int]:
+        """Split every face that the 2-D line (start_2d -> end_2d) crosses.
+
+        The line is infinite for intersection purposes (we test each face
+        edge-segment against the full fold-line extent clipped to the paper).
+
+        Returns a list of edge indices that lie *on* the fold line (i.e. the
+        newly created edges along the fold path).
+
+        This mutates ``self`` in-place (vertices, edges, faces, assignments,
+        fold_angles, rest_lengths are updated).
+        """
+        start_2d = np.asarray(start_2d, dtype=np.float64)
+        end_2d = np.asarray(end_2d, dtype=np.float64)
+
+        fold_edge_indices: list[int] = []
+        new_faces: list[list[int]] = []
+
+        faces_to_process = list(range(len(self.faces)))
+
+        for fi in faces_to_process:
+            face = self.faces[fi]
+            n = len(face)
+
+            # Gather intersection points along the face boundary
+            hits: list[tuple[int, np.ndarray]] = []  # (local_edge_index, point_2d)
+
+            for k in range(n):
+                v_a = face[k]
+                v_b = face[(k + 1) % n]
+                pa = self.vertices[v_a][:2]
+                pb = self.vertices[v_b][:2]
+
+                pt = _seg_seg_intersect_2d(start_2d, end_2d, pa, pb)
+                if pt is not None:
+                    hits.append((k, pt))
+
+            # Deduplicate hits that are at the same location (e.g. hitting a vertex)
+            if len(hits) >= 2:
+                unique_hits: list[tuple[int, np.ndarray]] = [hits[0]]
+                for h in hits[1:]:
+                    is_dup = False
+                    for uh in unique_hits:
+                        if np.linalg.norm(h[1] - uh[1]) < 1e-8:
+                            is_dup = True
+                            break
+                    if not is_dup:
+                        unique_hits.append(h)
+                hits = unique_hits
+
+            if len(hits) < 2:
+                # Line does not fully cross this face — keep face as-is
+                new_faces.append(face)
+                continue
+
+            # We only handle the first two intersection points (one chord across face)
+            hit_a_edge_idx, hit_a_pt = hits[0]
+            hit_b_edge_idx, hit_b_pt = hits[1]
+
+            # Create / find 3-D vertices at intersection points (z=0 for flat, interpolated otherwise)
+            def _interp_z(pt2d: np.ndarray, edge_local: int) -> np.ndarray:
+                """Interpolate z from the edge endpoints."""
+                v_a = face[edge_local]
+                v_b = face[(edge_local + 1) % n]
+                pa = self.vertices[v_a]
+                pb = self.vertices[v_b]
+                seg = pb[:2] - pa[:2]
+                seg_len = np.linalg.norm(seg)
+                if seg_len < 1e-12:
+                    return np.array([pt2d[0], pt2d[1], pa[2]])
+                t = np.linalg.norm(pt2d - pa[:2]) / seg_len
+                t = np.clip(t, 0.0, 1.0)
+                z = pa[2] + t * (pb[2] - pa[2])
+                return np.array([pt2d[0], pt2d[1], z])
+
+            pt_a_3d = _interp_z(hit_a_pt, hit_a_edge_idx)
+            pt_b_3d = _interp_z(hit_b_pt, hit_b_edge_idx)
+
+            idx_a = self._find_or_add_vertex(pt_a_3d)
+            idx_b = self._find_or_add_vertex(pt_b_3d)
+
+            if idx_a == idx_b:
+                new_faces.append(face)
+                continue
+
+            # Add the fold-line edge between the two intersection points
+            fold_eidx = self._find_or_add_edge(idx_a, idx_b)
+            fold_edge_indices.append(fold_eidx)
+
+            # ── Split the face into two sub-faces ──
+            # Walk around the face vertices, inserting idx_a and idx_b at the
+            # appropriate positions, then split into two loops.
+            ordered_verts = list(face)
+
+            # Insert intersection vertices into the vertex ring if not already present
+            def _insert_after(ring: list[int], after_local: int, vid: int) -> list[int]:
+                """Insert *vid* after position *after_local* if it is not already
+                adjacent in the ring at that position."""
+                pos = after_local + 1
+                if ring[after_local % len(ring)] == vid:
+                    return ring
+                if ring[pos % len(ring)] == vid:
+                    return ring
+                return ring[:pos] + [vid] + ring[pos:]
+
+            # Determine insertion order — always insert the one with the
+            # larger local-edge index first so that the earlier index stays valid.
+            if hit_a_edge_idx <= hit_b_edge_idx:
+                ordered_verts = _insert_after(ordered_verts, hit_b_edge_idx, idx_b)
+                # Recompute hit_a_edge_idx offset if idx_b was inserted before it
+                # (it shouldn't be, since hit_b >= hit_a, but guard anyway)
+                a_pos = hit_a_edge_idx
+                ordered_verts = _insert_after(ordered_verts, a_pos, idx_a)
+            else:
+                ordered_verts = _insert_after(ordered_verts, hit_a_edge_idx, idx_a)
+                ordered_verts = _insert_after(ordered_verts, hit_b_edge_idx, idx_b)
+
+            # Now split the ring at idx_a and idx_b
+            try:
+                pos_a = ordered_verts.index(idx_a)
+                pos_b = ordered_verts.index(idx_b)
+            except ValueError:
+                new_faces.append(face)
+                continue
+
+            if pos_a > pos_b:
+                pos_a, pos_b = pos_b, pos_a
+
+            loop1 = ordered_verts[pos_a: pos_b + 1]
+            loop2 = ordered_verts[pos_b:] + ordered_verts[: pos_a + 1]
+
+            # Only keep faces with >= 3 unique vertices
+            for loop in (loop1, loop2):
+                unique = list(dict.fromkeys(loop))  # preserve order, dedupe
+                if len(unique) >= 3:
+                    new_faces.append(unique)
+                    # Ensure all edges of this new face exist
+                    for k in range(len(unique)):
+                        self._find_or_add_edge(unique[k], unique[(k + 1) % len(unique)])
+
+        self.faces = new_faces
+        return fold_edge_indices
+
+    # ── vertex side test ────────────────────────────────────────────
+
+    def get_vertices_on_side(
+        self,
+        line_start: np.ndarray | list,
+        line_end: np.ndarray | list,
+        side: str = "positive",
+    ) -> list[int]:
+        """Return indices of vertices on one side of a 2-D line.
+
+        *side* can be ``"positive"`` or ``"negative"``.  The positive side is
+        defined by the left-hand normal of (line_end - line_start).
+        """
+        ls = np.asarray(line_start, dtype=np.float64)[:2]
+        le = np.asarray(line_end, dtype=np.float64)[:2]
+        d = le - ls
+        normal = np.array([-d[1], d[0]])
+
+        indices: list[int] = []
+        for i, v in enumerate(self.vertices):
+            dot = np.dot(v[:2] - ls, normal)
+            if side == "positive" and dot > 1e-9:
+                indices.append(i)
+            elif side == "negative" and dot < -1e-9:
+                indices.append(i)
+        return indices
+
+    # ── deep copy ───────────────────────────────────────────────────
+
+    def copy(self) -> "Paper":
+        """Return an independent deep copy."""
+        return Paper(
+            vertices=self.vertices.copy(),
+            edges=self.edges.copy(),
+            faces=copy.deepcopy(self.faces),
+            assignments=list(self.assignments),
+            fold_angles=self.fold_angles.copy(),
+            face_orders=list(self.face_orders),
+            material=Material(
+                name=self.material.name,
+                thickness_mm=self.material.thickness_mm,
+                youngs_modulus_gpa=self.material.youngs_modulus_gpa,
+                max_strain=self.material.max_strain,
+                poissons_ratio=self.material.poissons_ratio,
+            ),
+            rest_lengths=self.rest_lengths.copy(),
+            original_area=self.original_area,
+        )

engine/physics.py

@@ -0,0 +1,257 @@
+"""
+Bar-and-hinge physics model.
+
+Three energy components:
+  E_total = E_bar + E_facet + E_fold
+
+Stiffness parameters are derived from the material properties.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .paper import Paper
+
+
+# ────────────────────────────────────────────────────────────────────
+# Stiffness
+# ────────────────────────────────────────────────────────────────────
+
+@dataclass
+class StiffnessParams:
+    """Stiffness values derived from material properties."""
+    k_axial: np.ndarray   # per-edge axial stiffness  (E,)
+    k_facet: float         # facet (panel bending) stiffness
+    k_fold: float          # fold (crease torsion) stiffness
+
+
+def compute_stiffness(paper: Paper) -> StiffnessParams:
+    """Derive stiffness parameters from the paper's material and geometry.
+
+    k_axial = E * t * w / L0   (per edge, w ≈ average of adjacent edge lengths)
+    k_facet = E * t^3 / (12 * (1 - nu^2))
+    k_fold  = 0.1 * k_facet    (crease torsional stiffness, empirical fraction)
+    """
+    mat = paper.material
+    E = mat.youngs_modulus_pa  # Pa
+    t = mat.thickness_m        # m
+    nu = mat.poissons_ratio
+
+    rest = paper.rest_lengths
+    # Guard against zero rest lengths
+    safe_rest = np.where(rest > 1e-15, rest, 1e-15)
+
+    # Approximate edge width as the average rest length (simple heuristic)
+    w = np.mean(safe_rest) if len(safe_rest) > 0 else 1e-3
+
+    k_axial = E * t * w / safe_rest  # (E,)
+
+    k_facet = E * t ** 3 / (12.0 * (1.0 - nu ** 2))
+
+    # Crease torsional stiffness — a fraction of facet stiffness
+    k_fold = 0.1 * k_facet
+
+    return StiffnessParams(k_axial=k_axial, k_facet=k_facet, k_fold=k_fold)
+
+
+# ────────────────────────────────────────────────────────────────────
+# Energy components
+# ────────────────────────────────────────────────────────────────────
+
+def compute_bar_energy(paper: Paper) -> float:
+    """E_bar = sum (1/2) * k_axial * (L - L0)^2
+
+    Measures stretching / compression of edges relative to rest lengths.
+    """
+    if len(paper.edges) == 0:
+        return 0.0
+
+    verts = paper.vertices
+    edges = paper.edges
+    current_lengths = np.array([
+        np.linalg.norm(verts[e[1]] - verts[e[0]]) for e in edges
+    ])
+
+    stiff = compute_stiffness(paper)
+    delta = current_lengths - paper.rest_lengths
+    energy = 0.5 * np.sum(stiff.k_axial * delta ** 2)
+    return float(energy)
+
+
+def compute_facet_energy(paper: Paper) -> float:
+    """E_facet = sum (1/2) * k_facet * l * (theta - pi)^2
+
+    Measures bending of facet panels away from flat (pi).
+    *l* is the edge length (hinge length) and *theta* is the dihedral angle
+    across the edge between two adjacent faces.  For edges that are not
+    shared by two faces we skip them.
+    """
+    if len(paper.edges) == 0 or len(paper.faces) < 2:
+        return 0.0
+
+    stiff = compute_stiffness(paper)
+    verts = paper.vertices
+    edges = paper.edges
+
+    # Build edge → face adjacency
+    edge_faces: dict[int, list[int]] = {}
+    for fi, face in enumerate(paper.faces):
+        n = len(face)
+        for k in range(n):
+            va, vb = face[k], face[(k + 1) % n]
+            for ei, e in enumerate(edges):
+                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
+                    edge_faces.setdefault(ei, []).append(fi)
+                    break
+
+    energy = 0.0
+    for ei, adj_faces in edge_faces.items():
+        if len(adj_faces) < 2:
+            continue
+        # Only consider non-fold edges (flat or boundary interior)
+        if paper.assignments[ei] in ("M", "V"):
+            continue
+
+        f1, f2 = adj_faces[0], adj_faces[1]
+        theta = _dihedral_angle(verts, paper.faces[f1], paper.faces[f2], edges[ei])
+        l = np.linalg.norm(verts[edges[ei][1]] - verts[edges[ei][0]])
+        energy += 0.5 * stiff.k_facet * l * (theta - np.pi) ** 2
+
+    return float(energy)
+
+
+def compute_fold_energy(paper: Paper) -> float:
+    """E_fold = sum (1/2) * k_fold * l * (rho - rho_target)^2
+
+    Measures deviation of fold creases from their target angles.
+    *rho* is the current dihedral angle across the fold edge and
+    *rho_target* comes from ``fold_angles``.
+    """
+    if len(paper.edges) == 0:
+        return 0.0
+
+    stiff = compute_stiffness(paper)
+    verts = paper.vertices
+    edges = paper.edges
+
+    # Build edge → face adjacency
+    edge_faces: dict[int, list[int]] = {}
+    for fi, face in enumerate(paper.faces):
+        n = len(face)
+        for k in range(n):
+            va, vb = face[k], face[(k + 1) % n]
+            for ei, e in enumerate(edges):
+                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
+                    edge_faces.setdefault(ei, []).append(fi)
+                    break
+
+    energy = 0.0
+    for ei in range(len(edges)):
+        if paper.assignments[ei] not in ("M", "V"):
+            continue
+        if ei not in edge_faces or len(edge_faces[ei]) < 2:
+            continue
+
+        f1, f2 = edge_faces[ei][0], edge_faces[ei][1]
+        rho = _dihedral_angle(verts, paper.faces[f1], paper.faces[f2], edges[ei])
+        rho_target = np.radians(paper.fold_angles[ei])  # fold_angles stored in degrees
+        l = np.linalg.norm(verts[edges[ei][1]] - verts[edges[ei][0]])
+        energy += 0.5 * stiff.k_fold * l * (rho - rho_target) ** 2
+
+    return float(energy)
+
+
+def compute_total_energy(paper: Paper) -> float:
+    """E_total = E_bar + E_facet + E_fold."""
+    return compute_bar_energy(paper) + compute_facet_energy(paper) + compute_fold_energy(paper)
+
+
+# ────────────────────────────────────────────────────────────────────
+# Strain
+# ────────────────────────────────────────────────────────────────────
+
+def compute_strain(paper: Paper) -> np.ndarray:
+    """Per-vertex Cauchy strain: average fractional edge-length deviation.
+
+    Returns shape (N,) array of non-negative strain values.
+    """
+    n_verts = len(paper.vertices)
+    if n_verts == 0:
+        return np.empty(0)
+
+    verts = paper.vertices
+    edges = paper.edges
+    rest = paper.rest_lengths
+
+    # Build vertex → edge adjacency
+    vert_edges: dict[int, list[int]] = {}
+    for ei, e in enumerate(edges):
+        vert_edges.setdefault(int(e[0]), []).append(ei)
+        vert_edges.setdefault(int(e[1]), []).append(ei)
+
+    strain = np.zeros(n_verts, dtype=np.float64)
+    for vi in range(n_verts):
+        adj = vert_edges.get(vi, [])
+        if not adj:
+            continue
+        devs = []
+        for ei in adj:
+            v1, v2 = edges[ei]
+            L = np.linalg.norm(verts[v1] - verts[v2])
+            L0 = rest[ei]
+            if L0 > 1e-15:
+                devs.append(abs(L - L0) / L0)
+        if devs:
+            strain[vi] = float(np.mean(devs))
+
+    return strain
+
+
+# ────────────────────────────────────────────────────────────────────
+# Dihedral angle helper
+# ────────────────────────────────────────────────────────────────────
+
+def _dihedral_angle(
+    verts: np.ndarray,
+    face1: list[int],
+    face2: list[int],
+    edge: np.ndarray,
+) -> float:
+    """Compute the dihedral angle (in radians) between two faces sharing *edge*.
+
+    Returns angle in [0, 2*pi).  Returns pi if normals cannot be computed.
+    """
+    n1 = _face_normal(verts, face1)
+    n2 = _face_normal(verts, face2)
+
+    if n1 is None or n2 is None:
+        return np.pi
+
+    cos_a = np.clip(np.dot(n1, n2), -1.0, 1.0)
+    angle = np.arccos(cos_a)
+
+    # Determine sign from edge direction
+    edge_dir = verts[edge[1]] - verts[edge[0]]
+    edge_dir = edge_dir / (np.linalg.norm(edge_dir) + 1e-30)
+    cross = np.cross(n1, n2)
+    if np.dot(cross, edge_dir) < 0:
+        angle = 2.0 * np.pi - angle
+
+    return float(angle)
+
+
+def _face_normal(verts: np.ndarray, face: list[int]) -> np.ndarray | None:
+    """Compute outward unit normal of a face, or None if degenerate."""
+    if len(face) < 3:
+        return None
+    v0 = verts[face[0]]
+    v1 = verts[face[1]]
+    v2 = verts[face[2]]
+    normal = np.cross(v1 - v0, v2 - v0)
+    norm = np.linalg.norm(normal)
+    if norm < 1e-15:
+        return None
+    return normal / norm

engine/validation.py

@@ -0,0 +1,256 @@
+"""
+Geometric validation for origami crease patterns.
+
+Implements Kawasaki's theorem, Maekawa's theorem, and triangle-triangle
+self-intersection detection.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .paper import Paper
+
+
+# ────────────────────────────────────────────────────────────────────
+# Result container
+# ────────────────────────────────────────────────────────────────────
+
+@dataclass
+class ValidationResult:
+    kawasaki_valid: bool
+    kawasaki_violation: float
+    maekawa_valid: bool
+    maekawa_violation: float
+    intersection_free: bool
+    self_intersection_count: int
+    is_valid: bool  # all checks pass
+
+
+# ────────────────────────────────────────────────────────────────────
+# Kawasaki's theorem
+# ────────────────────────────────────────────────────────────────────
+
+def check_kawasaki(paper: Paper) -> tuple[bool, float]:
+    """At each interior vertex, the alternating sum of sector angles equals pi.
+
+    Specifically, for a vertex with 2n incident creases, the sum of
+    odd-indexed sector angles equals the sum of even-indexed sector
+    angles equals pi.
+
+    Returns (is_valid, total_violation).  A violation of < 1e-6 is
+    considered valid.
+    """
+    verts = paper.vertices
+    edges = paper.edges
+    n_verts = len(verts)
+
+    # Build adjacency: vertex -> list of neighbor vertices (via edges)
+    adj: dict[int, list[int]] = {}
+    for e in edges:
+        adj.setdefault(int(e[0]), []).append(int(e[1]))
+        adj.setdefault(int(e[1]), []).append(int(e[0]))
+
+    # Identify boundary vertices (incident to a 'B' edge)
+    boundary_verts: set[int] = set()
+    for ei, e in enumerate(edges):
+        if paper.assignments[ei] == "B":
+            boundary_verts.add(int(e[0]))
+            boundary_verts.add(int(e[1]))
+
+    total_violation = 0.0
+
+    for vi in range(n_verts):
+        if vi in boundary_verts:
+            continue
+        neighbors = adj.get(vi, [])
+        if len(neighbors) < 2:
+            continue
+
+        # Sort neighbors by angle around vi (in the XY plane for flat-foldability)
+        center = verts[vi][:2]
+        angles = []
+        for ni in neighbors:
+            d = verts[ni][:2] - center
+            angles.append((np.arctan2(d[1], d[0]), ni))
+        angles.sort(key=lambda x: x[0])
+
+        # Sector angles
+        sector_angles = []
+        for k in range(len(angles)):
+            a1 = angles[k][0]
+            a2 = angles[(k + 1) % len(angles)][0]
+            diff = a2 - a1
+            if diff <= 0:
+                diff += 2.0 * np.pi
+            sector_angles.append(diff)
+
+        if len(sector_angles) < 2:
+            continue
+
+        # Kawasaki: alternating sums should both equal pi
+        even_sum = sum(sector_angles[i] for i in range(0, len(sector_angles), 2))
+        odd_sum = sum(sector_angles[i] for i in range(1, len(sector_angles), 2))
+
+        violation = abs(even_sum - odd_sum)
+        total_violation += violation
+
+    is_valid = total_violation < 1e-4
+    return is_valid, float(total_violation)
+
+
+# ────────────────────────────────────────────────────────────────────
+# Maekawa's theorem
+# ────────────────────────────────────────────────────────────────────
+
+def check_maekawa(paper: Paper) -> tuple[bool, float]:
+    """At each interior vertex, |M - V| = 2.
+
+    Returns (is_valid, total_violation) where violation is
+    sum of |abs(M-V) - 2| over all interior vertices.
+    """
+    edges = paper.edges
+    verts = paper.vertices
+    n_verts = len(verts)
+
+    # Boundary vertices
+    boundary_verts: set[int] = set()
+    for ei, e in enumerate(edges):
+        if paper.assignments[ei] == "B":
+            boundary_verts.add(int(e[0]))
+            boundary_verts.add(int(e[1]))
+
+    # Count M and V edges per vertex
+    m_count = [0] * n_verts
+    v_count = [0] * n_verts
+    total_mv_per_vertex = [0] * n_verts
+
+    for ei, e in enumerate(edges):
+        a = paper.assignments[ei]
+        if a == "M":
+            m_count[int(e[0])] += 1
+            m_count[int(e[1])] += 1
+        elif a == "V":
+            v_count[int(e[0])] += 1
+            v_count[int(e[1])] += 1
+        if a in ("M", "V"):
+            total_mv_per_vertex[int(e[0])] += 1
+            total_mv_per_vertex[int(e[1])] += 1
+
+    total_violation = 0.0
+    for vi in range(n_verts):
+        if vi in boundary_verts:
+            continue
+        # Only check vertices that actually have creases
+        if total_mv_per_vertex[vi] == 0:
+            continue
+        diff = abs(m_count[vi] - v_count[vi])
+        violation = abs(diff - 2)
+        total_violation += violation
+
+    is_valid = total_violation < 0.5  # integer theorem, so < 0.5 means exact
+    return is_valid, float(total_violation)
+
+
+# ────────────────────────────────────────────────────────────────────
+# Self-intersection detection (triangle-triangle)
+# ────────────────────────────────────────────────────────────────────
+
+def check_self_intersection(paper: Paper) -> tuple[bool, int]:
+    """Check for triangle-triangle intersections among the paper's faces.
+
+    Uses the separating-axis theorem (SAT) for triangle-triangle overlap
+    in 3-D.  Faces that share an edge or vertex are skipped.
+
+    Returns (is_valid, count_of_intersections).
+    """
+    verts = paper.vertices
+    faces = paper.faces
+    count = 0
+
+    for i in range(len(faces)):
+        for j in range(i + 1, len(faces)):
+            # Skip faces that share vertices (adjacent faces)
+            if set(faces[i]) & set(faces[j]):
+                continue
+            if _triangles_intersect(verts, faces[i], faces[j]):
+                count += 1
+
+    return count == 0, count
+
+
+def _triangles_intersect(
+    verts: np.ndarray,
+    face1: list[int],
+    face2: list[int],
+) -> bool:
+    """Test whether two triangular faces intersect in 3-D using
+    the separating-axis theorem (Moller's method simplified).
+
+    For non-triangular faces, only tests the first three vertices.
+    Returns True if the triangles intersect.
+    """
+    if len(face1) < 3 or len(face2) < 3:
+        return False
+
+    t1 = verts[face1[:3]]
+    t2 = verts[face2[:3]]
+
+    # 13 potential separating axes:
+    # - normals of each triangle (2)
+    # - cross products of edge pairs (3x3 = 9)
+    # - edges themselves don't need separate tests in 3D SAT
+
+    e1_edges = [t1[1] - t1[0], t1[2] - t1[1], t1[0] - t1[2]]
+    e2_edges = [t2[1] - t2[0], t2[2] - t2[1], t2[0] - t2[2]]
+
+    n1 = np.cross(e1_edges[0], e1_edges[1])
+    n2 = np.cross(e2_edges[0], e2_edges[1])
+
+    axes = [n1, n2]
+    for e1 in e1_edges:
+        for e2 in e2_edges:
+            ax = np.cross(e1, e2)
+            if np.linalg.norm(ax) > 1e-12:
+                axes.append(ax)
+
+    for axis in axes:
+        norm = np.linalg.norm(axis)
+        if norm < 1e-12:
+            continue
+        axis = axis / norm
+
+        proj1 = np.dot(t1, axis)
+        proj2 = np.dot(t2, axis)
+
+        min1, max1 = proj1.min(), proj1.max()
+        min2, max2 = proj2.min(), proj2.max()
+
+        # Check for separation (with small tolerance for shared-edge adjacency)
+        if max1 < min2 - 1e-9 or max2 < min1 - 1e-9:
+            return False  # separating axis found
+
+    return True  # no separating axis → intersection
+
+
+# ────────────────────────────────────────────────────────────────────
+# Combined validation
+# ────────────────────────────────────────────────────────────────────
+
+def validate_paper(paper: Paper) -> ValidationResult:
+    """Run all validation checks and return a combined result."""
+    k_valid, k_violation = check_kawasaki(paper)
+    m_valid, m_violation = check_maekawa(paper)
+    si_valid, si_count = check_self_intersection(paper)
+
+    return ValidationResult(
+        kawasaki_valid=k_valid,
+        kawasaki_violation=k_violation,
+        maekawa_valid=m_valid,
+        maekawa_violation=m_violation,
+        intersection_free=si_valid,
+        self_intersection_count=si_count,
+        is_valid=k_valid and m_valid and si_valid,
+    )

planner/decomposer.py

@@ -0,0 +1,284 @@
+"""
+Task decomposer: breaks a parsed instruction into sequential sub-goals
+with concrete fold operations on a unit square.
+"""
+
+from __future__ import annotations
+
+import copy
+from planner.knowledge import (
+    ORIGAMI_MODELS,
+    ORIGAMI_BASES,
+    FOLD_OPERATIONS,
+    get_model_steps,
+    get_base_steps,
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _step_to_fold_operation(step: dict) -> dict:
+    """
+    Convert a knowledge-base step dict into the engine's fold operation format:
+      {"type": ..., "line": {"start": [...], "end": [...]}, "angle": ...}
+    """
+    op = {
+        "type": step["type"],
+        "line": copy.deepcopy(step["line"]),
+        "angle": step.get("angle", 180),
+    }
+    if "layer_select" in step:
+        op["layer_select"] = step["layer_select"]
+    return op
+
+
+def _expected_state_after_fold(fold_type: str, prev_state: dict | None) -> dict:
+    """
+    Produce a lightweight expected-state dict describing what the paper
+    should look like after a fold.  This is intentionally approximate --
+    the real simulation engine computes exact geometry.
+    """
+    state = dict(prev_state or {"layers": 1, "shape": "square", "phase": "flat"})
+    if fold_type in ("valley", "mountain"):
+        state["layers"] = state.get("layers", 1) * 2
+    elif fold_type == "petal":
+        state["shape"] = "narrow_diamond"
+    elif fold_type == "squash":
+        state["shape"] = "diamond"
+    elif fold_type == "reverse_inside":
+        state["shape"] = "pointed_flap_reversed"
+    elif fold_type == "inflate":
+        state["phase"] = "3d"
+    elif fold_type == "turn_over":
+        state["flipped"] = not state.get("flipped", False)
+    elif fold_type == "unfold":
+        # Layers don't literally halve on every unfold, but this is a hint
+        state["layers"] = max(1, state.get("layers", 1) // 2)
+    return state
+
+
+def _validation_for_fold(fold_type: str) -> dict:
+    """Return a simple validation dict for a step."""
+    checks: dict = {"flat_foldable": True}
+    if fold_type in ("valley", "mountain"):
+        checks["kawasaki_check"] = True
+        checks["maekawa_check"] = True
+    if fold_type == "inflate":
+        checks["is_3d"] = True
+        checks["flat_foldable"] = False
+    return checks
+
+
+# ---------------------------------------------------------------------------
+# Known-model decomposition
+# ---------------------------------------------------------------------------
+
+def _decompose_known_model(parsed: dict) -> list[dict]:
+    """Decompose a known model into sub-goal steps."""
+    model_name: str = parsed["model_name"]
+    model_info = ORIGAMI_MODELS.get(model_name)
+    if model_info is None:
+        return _decompose_free_fold(parsed)
+
+    base_name = model_info.get("base")
+    steps = get_model_steps(model_name)
+    sub_goals: list[dict] = []
+    running_state: dict = {"layers": 1, "shape": "square", "phase": "flat"}
+
+    for i, step in enumerate(steps):
+        fold_op = _step_to_fold_operation(step)
+        running_state = _expected_state_after_fold(step["type"], running_state)
+
+        sub_goals.append({
+            "step_number": i + 1,
+            "description": step.get("description", f"Step {i + 1}"),
+            "base_required": base_name if i == 0 else None,
+            "fold_operations": [fold_op],
+            "expected_state": dict(running_state),
+            "validation": _validation_for_fold(step["type"]),
+        })
+
+    return sub_goals
+
+
+# ---------------------------------------------------------------------------
+# Packing / optimization decomposition
+# ---------------------------------------------------------------------------
+
+def _decompose_packing(parsed: dict) -> list[dict]:
+    """
+    Decompose an optimize_packing task into sub-goals.
+    Returns a Miura-ori-style fold plan on a unit square.
+    """
+    w = parsed["dimensions"]["width"]
+    h = parsed["dimensions"]["height"]
+    material = parsed["material"]
+    constraints = parsed.get("constraints", {})
+    max_folds = constraints.get("max_folds", 20)
+
+    sub_goals: list[dict] = []
+    step_num = 0
+
+    # Horizontal valley/mountain pleats (zigzag in Y)
+    n_horizontal = min(4, max_folds // 4)
+    spacing_y = 1.0 / (n_horizontal + 1)
+    for i in range(n_horizontal):
+        step_num += 1
+        y = spacing_y * (i + 1)
+        fold_type = "valley" if i % 2 == 0 else "mountain"
+        sub_goals.append({
+            "step_number": step_num,
+            "description": f"Horizontal {fold_type} fold at y={y:.3f} (pleat {i + 1}/{n_horizontal})",
+            "base_required": None,
+            "fold_operations": [{
+                "type": fold_type,
+                "line": {"start": [0.0, y], "end": [1.0, y]},
+                "angle": 180,
+                "layer_select": "all",
+            }],
+            "expected_state": {"layers": i + 2, "phase": "flat", "pattern": "miura_horizontal"},
+            "validation": {"flat_foldable": True, "kawasaki_check": True},
+        })
+
+    # Vertical zigzag valley/mountain pleats (Miura-ori angle offsets)
+    n_vertical = min(4, (max_folds - n_horizontal) // 2)
+    spacing_x = 1.0 / (n_vertical + 1)
+    for i in range(n_vertical):
+        step_num += 1
+        x = spacing_x * (i + 1)
+        fold_type = "valley" if i % 2 == 0 else "mountain"
+        # Miura-ori: alternate slight angle offset to create parallelogram cells
+        angle_offset = 0.02 * (1 if i % 2 == 0 else -1)
+        sub_goals.append({
+            "step_number": step_num,
+            "description": f"Vertical {fold_type} fold at x={x:.3f} (Miura-ori column {i + 1}/{n_vertical})",
+            "base_required": None,
+            "fold_operations": [{
+                "type": fold_type,
+                "line": {"start": [x, 0.0 + angle_offset], "end": [x, 1.0 - angle_offset]},
+                "angle": 180,
+                "layer_select": "all",
+            }],
+            "expected_state": {
+                "layers": (n_horizontal + 1) * (i + 2),
+                "phase": "flat",
+                "pattern": "miura_complete" if i == n_vertical - 1 else "miura_partial",
+            },
+            "validation": {"flat_foldable": True, "kawasaki_check": True, "maekawa_check": True},
+        })
+
+    # Final collapse
+    step_num += 1
+    sub_goals.append({
+        "step_number": step_num,
+        "description": "Collapse all creases simultaneously into compact Miura-ori stack",
+        "base_required": None,
+        "fold_operations": [{
+            "type": "valley",
+            "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+            "angle": 180,
+            "layer_select": "all",
+        }],
+        "expected_state": {
+            "layers": (n_horizontal + 1) * (n_vertical + 1),
+            "phase": "compact",
+            "pattern": "miura_ori",
+        },
+        "validation": {
+            "flat_foldable": True,
+            "check_bounding_box": constraints.get("target_box"),
+            "check_deployable": constraints.get("must_deploy", False),
+        },
+    })
+
+    return sub_goals
+
+
+# ---------------------------------------------------------------------------
+# Free-fold / unknown model decomposition
+# ---------------------------------------------------------------------------
+
+def _decompose_free_fold(parsed: dict) -> list[dict]:
+    """
+    Generic decomposition for an unknown model or free-form folding task.
+    Returns a minimal plan that an LLM can expand upon.
+    """
+    return [
+        {
+            "step_number": 1,
+            "description": "Create reference creases (diagonals and midlines)",
+            "base_required": None,
+            "fold_operations": [
+                {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180},
+                {"type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0},
+                {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
+                {"type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0},
+                {"type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180},
+                {"type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0},
+            ],
+            "expected_state": {"layers": 1, "shape": "square", "phase": "creased"},
+            "validation": {"flat_foldable": True},
+        },
+        {
+            "step_number": 2,
+            "description": "Collapse into a base form using reference creases",
+            "base_required": "preliminary_base",
+            "fold_operations": [
+                {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            ],
+            "expected_state": {"layers": 4, "shape": "diamond", "phase": "base"},
+            "validation": {"flat_foldable": True},
+        },
+        {
+            "step_number": 3,
+            "description": "Shape the model with additional folds (LLM determines specifics)",
+            "base_required": None,
+            "fold_operations": [],  # Left empty for LLM to fill
+            "expected_state": {"phase": "shaped"},
+            "validation": {"flat_foldable": True},
+        },
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Fold-pattern decomposition
+# ---------------------------------------------------------------------------
+
+def _decompose_pattern(parsed: dict) -> list[dict]:
+    """Decompose a tessellation/pattern task."""
+    # For now, delegate to packing which generates a Miura-ori pattern
+    return _decompose_packing(parsed)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def decompose_task(parsed: dict) -> list[dict]:
+    """
+    Decompose a parsed instruction into sequential sub-goals.
+
+    Args:
+        parsed: Output of parse_instruction()
+
+    Returns:
+        List of sub-goal dicts, each with:
+          - step_number: int
+          - description: str
+          - base_required: str or None
+          - fold_operations: list[dict]  (engine-format fold dicts)
+          - expected_state: dict
+          - validation: dict
+    """
+    intent = parsed.get("intent", "free_fold")
+
+    if intent == "fold_model" and parsed.get("model_name"):
+        return _decompose_known_model(parsed)
+    elif intent == "optimize_packing":
+        return _decompose_packing(parsed)
+    elif intent == "fold_pattern":
+        return _decompose_pattern(parsed)
+    else:
+        return _decompose_free_fold(parsed)

planner/knowledge.py

@@ -0,0 +1,753 @@
+"""
+Origami knowledge base: bases, models, and fold operation primitives.
+
+All fold coordinates are defined on a unit square (0,0) to (1,1).
+Fold lines use {"start": [x, y], "end": [x, y]} format matching the
+engine's FoldAction specification from architecture.md.
+"""
+
+# ---------------------------------------------------------------------------
+# Primitive fold operations — mapping from named folds to engine-level dicts
+# ---------------------------------------------------------------------------
+
+FOLD_OPERATIONS = {
+    "valley_fold": {
+        "type": "valley",
+        "angle": 180,
+        "description": "Fold paper toward you along a crease line.",
+    },
+    "mountain_fold": {
+        "type": "mountain",
+        "angle": 180,
+        "description": "Fold paper away from you along a crease line.",
+    },
+    "squash_fold": {
+        "type": "squash",
+        "angle": 180,
+        "description": "Open a flap and flatten it symmetrically.",
+        "primitives": [
+            {"type": "valley", "angle": 90, "sub_op": "open_flap"},
+            {"type": "valley", "angle": 180, "sub_op": "flatten"},
+        ],
+    },
+    "petal_fold": {
+        "type": "petal",
+        "angle": 180,
+        "description": "Lift a point while collapsing sides inward to create a narrow flap.",
+        "primitives": [
+            {"type": "valley", "angle": 180, "sub_op": "fold_left_edge_to_center"},
+            {"type": "valley", "angle": 180, "sub_op": "fold_right_edge_to_center"},
+            {"type": "valley", "angle": 180, "sub_op": "lift_bottom_point"},
+            {"type": "mountain", "angle": 180, "sub_op": "collapse_left"},
+            {"type": "mountain", "angle": 180, "sub_op": "collapse_right"},
+        ],
+    },
+    "reverse_inside_fold": {
+        "type": "reverse_inside",
+        "angle": 180,
+        "description": "Push a flap tip inward, reversing the spine crease.",
+        "primitives": [
+            {"type": "valley", "angle": 180, "sub_op": "new_crease_left"},
+            {"type": "valley", "angle": 180, "sub_op": "new_crease_right"},
+            {"type": "mountain", "angle": 180, "sub_op": "reverse_spine"},
+        ],
+    },
+    "reverse_outside_fold": {
+        "type": "reverse_outside",
+        "angle": 180,
+        "description": "Wrap a flap tip around the outside, reversing the spine crease.",
+        "primitives": [
+            {"type": "mountain", "angle": 180, "sub_op": "new_crease_left"},
+            {"type": "mountain", "angle": 180, "sub_op": "new_crease_right"},
+            {"type": "valley", "angle": 180, "sub_op": "reverse_spine"},
+        ],
+    },
+    "crimp": {
+        "type": "crimp",
+        "angle": 180,
+        "description": "Pair of reverse folds creating a zigzag step.",
+        "primitives": [
+            {"type": "valley", "angle": 180, "sub_op": "first_crease"},
+            {"type": "mountain", "angle": 180, "sub_op": "second_crease"},
+        ],
+    },
+    "pleat": {
+        "type": "pleat",
+        "angle": 180,
+        "description": "Alternating valley and mountain folds creating an accordion.",
+        "primitives": [
+            {"type": "valley", "angle": 180, "sub_op": "valley_crease"},
+            {"type": "mountain", "angle": 180, "sub_op": "mountain_crease"},
+        ],
+    },
+    "rabbit_ear": {
+        "type": "rabbit_ear",
+        "angle": 180,
+        "description": "Three creases meeting at a point, creating a triangular raised flap.",
+        "primitives": [
+            {"type": "valley", "angle": 180, "sub_op": "bisector_1"},
+            {"type": "valley", "angle": 180, "sub_op": "bisector_2"},
+            {"type": "mountain", "angle": 180, "sub_op": "ridge"},
+        ],
+    },
+    "sink_fold": {
+        "type": "sink",
+        "angle": 180,
+        "description": "Push a point into the interior of the model.",
+        "primitives": [
+            {"type": "mountain", "angle": 180, "sub_op": "reverse_creases"},
+            {"type": "valley", "angle": 180, "sub_op": "reflatten"},
+        ],
+    },
+    "turn_over": {
+        "type": "turn_over",
+        "angle": 0,
+        "description": "Flip the paper over.",
+    },
+    "unfold": {
+        "type": "unfold",
+        "angle": 0,
+        "description": "Reverse a previous fold (crease remains).",
+    },
+    "inflate": {
+        "type": "inflate",
+        "angle": 0,
+        "description": "Gently open and puff out the model to create 3D form.",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Origami bases — fundamental starting configurations
+# ---------------------------------------------------------------------------
+
+ORIGAMI_BASES = {
+    "preliminary_base": {
+        "name": "Preliminary Base (Square Base)",
+        "description": "Multi-layered diamond standing on a corner. Gateway to bird and frog bases.",
+        "total_steps": 9,
+        "steps": [
+            {
+                "description": "Fold in half diagonally (bottom-left to top-right)",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold in half on other diagonal (bottom-right to top-left)",
+                "type": "valley",
+                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold",
+                "type": "unfold",
+                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold in half horizontally",
+                "type": "valley",
+                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold in half vertically",
+                "type": "valley",
+                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold",
+                "type": "unfold",
+                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Collapse into preliminary base: push sides in using existing creases",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+                "simultaneous": [
+                    {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
+                    {"type": "mountain", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180},
+                    {"type": "mountain", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180},
+                ],
+            },
+        ],
+    },
+
+    "waterbomb_base": {
+        "name": "Waterbomb Base",
+        "description": "Flat triangle with multiple layers. Inverse of preliminary base.",
+        "total_steps": 9,
+        "steps": [
+            {
+                "description": "Fold both diagonals — first diagonal",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold first diagonal",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold second diagonal",
+                "type": "valley",
+                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold second diagonal",
+                "type": "unfold",
+                "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Mountain fold horizontally",
+                "type": "mountain",
+                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold horizontal",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Mountain fold vertically",
+                "type": "mountain",
+                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold vertical",
+                "type": "unfold",
+                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Collapse into waterbomb base: fold top edge down, push sides in",
+                "type": "mountain",
+                "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+                "simultaneous": [
+                    {"type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180},
+                    {"type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180},
+                ],
+            },
+        ],
+    },
+
+    "bird_base": {
+        "name": "Bird Base (Crane Base)",
+        "description": "Long diamond with 4 narrow flaps. Built from preliminary base + 2 petal folds.",
+        "requires_base": "preliminary_base",
+        "total_steps": 13,
+        "steps": [
+            # Steps 1-9 are the preliminary base (included by reference)
+            # Steps 10-22 from the crane sequence build the bird base
+            {
+                "description": "Fold left edge of top layer to center line",
+                "type": "valley",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Fold right edge of top layer to center line",
+                "type": "valley",
+                "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Fold top triangle down over kite flaps (crease only)",
+                "type": "valley",
+                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Unfold top triangle",
+                "type": "unfold",
+                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
+                "angle": 0,
+                "layer_select": "top",
+            },
+            {
+                "description": "Unfold kite folds",
+                "type": "unfold",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
+                "angle": 0,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold front: lift bottom point up, sides collapse inward",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Turn model over",
+                "type": "turn_over",
+                "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold left edge to center line (back)",
+                "type": "valley",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Fold right edge to center line (back)",
+                "type": "valley",
+                "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Fold top triangle down (crease only, back)",
+                "type": "valley",
+                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Unfold top triangle (back)",
+                "type": "unfold",
+                "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]},
+                "angle": 0,
+                "layer_select": "top",
+            },
+            {
+                "description": "Unfold kite folds (back)",
+                "type": "unfold",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]},
+                "angle": 0,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold back: lift bottom point up, sides collapse inward",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+        ],
+    },
+
+    "frog_base": {
+        "name": "Frog Base",
+        "description": "4 long narrow flaps radiating from center. Built from preliminary base + 4 squash + 4 petal folds.",
+        "requires_base": "preliminary_base",
+        "total_steps": 8,
+        "steps": [
+            {
+                "description": "Squash fold front-left flap",
+                "type": "squash",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Squash fold front-right flap",
+                "type": "squash",
+                "line": {"start": [0.75, 0.5], "end": [0.5, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Squash fold back-left flap",
+                "type": "squash",
+                "line": {"start": [0.25, 0.5], "end": [0.5, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Squash fold back-right flap",
+                "type": "squash",
+                "line": {"start": [0.75, 0.5], "end": [0.5, 0.75]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold first diamond",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold second diamond",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold third diamond",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+            {
+                "description": "Petal fold fourth diamond",
+                "type": "petal",
+                "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+        ],
+    },
+
+    "fish_base": {
+        "name": "Fish Base",
+        "description": "Diamond shape with 4 points. Built from kite folds + rabbit ears.",
+        "total_steps": 7,
+        "steps": [
+            {
+                "description": "Fold diagonal crease (reference line)",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold diagonal",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Kite fold: fold bottom-left edge to diagonal",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Kite fold: fold top-left edge to diagonal",
+                "type": "valley",
+                "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Rabbit ear fold on bottom-right corner",
+                "type": "rabbit_ear",
+                "line": {"start": [0.5, 0.0], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Rabbit ear fold on top-right corner",
+                "type": "rabbit_ear",
+                "line": {"start": [0.5, 1.0], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold resulting flaps down flat",
+                "type": "valley",
+                "line": {"start": [0.5, 0.5], "end": [1.0, 0.5]},
+                "angle": 180,
+                "layer_select": "top",
+            },
+        ],
+    },
+
+    "kite_base": {
+        "name": "Kite Base",
+        "description": "Simplest base: a kite shape from two folds to a diagonal.",
+        "total_steps": 3,
+        "steps": [
+            {
+                "description": "Fold diagonal (reference crease)",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+            {
+                "description": "Unfold diagonal",
+                "type": "unfold",
+                "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]},
+                "angle": 0,
+                "layer_select": "all",
+            },
+            {
+                "description": "Fold bottom-left and top-left edges to lie on diagonal",
+                "type": "valley",
+                "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]},
+                "angle": 180,
+                "layer_select": "all",
+            },
+        ],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Complete origami models — full fold sequences from flat square to finished
+# ---------------------------------------------------------------------------
+
+ORIGAMI_MODELS = {
+    "crane": {
+        "name": "Paper Crane (Tsuru)",
+        "difficulty": "intermediate",
+        "base": "bird_base",
+        "total_steps": 31,
+        "description": "The traditional Japanese crane. 31 steps from flat square.",
+        "steps": [
+            # Phase 1: Pre-crease (steps 1-8)
+            {"step": 1, "description": "Fold square in half diagonally (bottom-left to top-right)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 3, "description": "Fold in half on other diagonal", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 5, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 6, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0, "layer_select": "all"},
+            {"step": 7, "description": "Fold in half vertically", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 8, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+
+            # Phase 2: Collapse into preliminary base (step 9)
+            {"step": 9, "description": "Collapse into preliminary base: push left and right edges inward, fold top down", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+
+            # Phase 3: Front kite folds (steps 10-14)
+            {"step": 10, "description": "Fold left edge of top layer to center line", "type": "valley", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 11, "description": "Fold right edge of top layer to center line", "type": "valley", "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 12, "description": "Fold top triangle down over kite flaps", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "top"},
+            {"step": 13, "description": "Unfold step 12", "type": "unfold", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 0, "layer_select": "top"},
+            {"step": 14, "description": "Unfold steps 10-11", "type": "unfold", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "top"},
+
+            # Phase 4: Front petal fold (step 15)
+            {"step": 15, "description": "Petal fold: lift bottom point of top layer upward, sides collapse inward", "type": "petal", "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+
+            # Phase 5: Repeat on back (steps 16-22)
+            {"step": 16, "description": "Turn model over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 17, "description": "Fold left edge to center line", "type": "valley", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 18, "description": "Fold right edge to center line", "type": "valley", "line": {"start": [0.75, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 19, "description": "Fold top triangle down", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "top"},
+            {"step": 20, "description": "Unfold step 19", "type": "unfold", "line": {"start": [0.25, 0.75], "end": [0.75, 0.75]}, "angle": 0, "layer_select": "top"},
+            {"step": 21, "description": "Unfold steps 17-18", "type": "unfold", "line": {"start": [0.25, 0.5], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "top"},
+            {"step": 22, "description": "Petal fold back: lift bottom point up, collapse sides in. Bird base complete.", "type": "petal", "line": {"start": [0.5, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+
+            # Phase 6: Narrow the legs (steps 23-27)
+            {"step": 23, "description": "Fold left flap (front) edge to center", "type": "valley", "line": {"start": [0.375, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 24, "description": "Fold right flap (front) edge to center", "type": "valley", "line": {"start": [0.625, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 25, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 26, "description": "Fold left flap (back) edge to center", "type": "valley", "line": {"start": [0.375, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 27, "description": "Fold right flap (back) edge to center", "type": "valley", "line": {"start": [0.625, 0.5], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+
+            # Phase 7: Form neck and tail (steps 28-29)
+            {"step": 28, "description": "Inside reverse fold left flap upward to form neck", "type": "reverse_inside", "line": {"start": [0.35, 0.6], "end": [0.45, 0.85]}, "angle": 150, "layer_select": "all"},
+            {"step": 29, "description": "Inside reverse fold right flap upward to form tail", "type": "reverse_inside", "line": {"start": [0.55, 0.6], "end": [0.65, 0.85]}, "angle": 150, "layer_select": "all"},
+
+            # Phase 8: Head and finish (steps 30-31)
+            {"step": 30, "description": "Inside reverse fold tip of neck downward to form head/beak", "type": "reverse_inside", "line": {"start": [0.38, 0.82], "end": [0.42, 0.9]}, "angle": 150, "layer_select": "all"},
+            {"step": 31, "description": "Pull wings apart gently and press bottom to inflate body", "type": "inflate", "line": {"start": [0.5, 0.5], "end": [0.5, 0.7]}, "angle": 0, "layer_select": "all"},
+        ],
+    },
+
+    "boat": {
+        "name": "Simple Boat",
+        "difficulty": "simple",
+        "base": None,
+        "total_steps": 9,
+        "description": "A flat boat/hat from simple valley and mountain folds.",
+        "steps": [
+            {"step": 1, "description": "Fold in half horizontally (top to bottom)", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Fold in half vertically (crease only)", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 3, "description": "Unfold vertical", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
+            {"step": 4, "description": "Fold top-left corner down to center mark", "type": "valley", "line": {"start": [0.15, 0.5], "end": [0.5, 0.35]}, "angle": 180, "layer_select": "top"},
+            {"step": 5, "description": "Fold top-right corner down to center mark", "type": "valley", "line": {"start": [0.85, 0.5], "end": [0.5, 0.35]}, "angle": 180, "layer_select": "top"},
+            {"step": 6, "description": "Fold bottom strip up (front layer)", "type": "valley", "line": {"start": [0.0, 0.15], "end": [1.0, 0.15]}, "angle": 180, "layer_select": "top"},
+            {"step": 7, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
+            {"step": 8, "description": "Fold bottom strip up (back layer)", "type": "valley", "line": {"start": [0.0, 0.15], "end": [1.0, 0.15]}, "angle": 180, "layer_select": "top"},
+            {"step": 9, "description": "Open from bottom and flatten into boat shape", "type": "inflate", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
+        ],
+    },
+
+    "airplane": {
+        "name": "Paper Airplane (Dart)",
+        "difficulty": "simple",
+        "base": None,
+        "total_steps": 6,
+        "description": "Classic dart-style paper airplane using only valley folds.",
+        "steps": [
+            {"step": 1, "description": "Fold in half vertically (left to right)", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 3, "description": "Fold top-left corner to center line", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.7]}, "angle": 180, "layer_select": "all"},
+            {"step": 4, "description": "Fold top-right corner to center line", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.7]}, "angle": 180, "layer_select": "all"},
+            {"step": 5, "description": "Fold left angled edge to center line", "type": "valley", "line": {"start": [0.0, 0.7], "end": [0.5, 0.4]}, "angle": 180, "layer_select": "all"},
+            {"step": 6, "description": "Fold right angled edge to center line", "type": "valley", "line": {"start": [1.0, 0.7], "end": [0.5, 0.4]}, "angle": 180, "layer_select": "all"},
+        ],
+    },
+
+    "box": {
+        "name": "Masu Box (Open-Top Box)",
+        "difficulty": "low_intermediate",
+        "base": None,
+        "total_steps": 13,
+        "description": "An open-top box. Uses preliminary base concept with tuck folds.",
+        "steps": [
+            {"step": 1, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 0, "layer_select": "all"},
+            {"step": 3, "description": "Fold in half vertically", "type": "valley", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 5, "description": "Fold all four corners to center", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 6, "description": "Fold bottom-right corner to center", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 7, "description": "Fold top-left corner to center", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 8, "description": "Fold top-right corner to center", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 9, "description": "Fold top third down to center", "type": "valley", "line": {"start": [0.0, 0.667], "end": [1.0, 0.667]}, "angle": 180, "layer_select": "all"},
+            {"step": 10, "description": "Fold bottom third up to center", "type": "valley", "line": {"start": [0.0, 0.333], "end": [1.0, 0.333]}, "angle": 180, "layer_select": "all"},
+            {"step": 11, "description": "Unfold top and bottom, and unfold left/right corners", "type": "unfold", "line": {"start": [0.0, 0.333], "end": [1.0, 0.333]}, "angle": 0, "layer_select": "all"},
+            {"step": 12, "description": "Raise left and right walls using existing creases, tuck corners in", "type": "valley", "line": {"start": [0.25, 0.0], "end": [0.25, 1.0]}, "angle": 90, "layer_select": "all"},
+            {"step": 13, "description": "Fold flaps over into box and lock walls in place", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 90, "layer_select": "top"},
+        ],
+    },
+
+    "fortune_teller": {
+        "name": "Fortune Teller (Cootie Catcher)",
+        "difficulty": "simple",
+        "base": None,
+        "total_steps": 8,
+        "description": "Classic fortune teller: fold corners to center, flip, repeat.",
+        "steps": [
+            {"step": 1, "description": "Fold in half diagonally (crease only)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 3, "description": "Fold bottom-left corner to center", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 4, "description": "Fold bottom-right corner to center", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 5, "description": "Fold top-left corner to center", "type": "valley", "line": {"start": [0.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 6, "description": "Fold top-right corner to center", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 7, "description": "Turn over", "type": "turn_over", "line": {"start": [0.5, 0.0], "end": [0.5, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 8, "description": "Fold all four new corners to center again", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "all"},
+        ],
+    },
+
+    "waterbomb": {
+        "name": "Waterbomb (Paper Balloon)",
+        "difficulty": "simple",
+        "base": "waterbomb_base",
+        "total_steps": 12,
+        "description": "Inflatable paper balloon built on the waterbomb base.",
+        "steps": [
+            # Phase 1: Waterbomb base (steps 1-9 same as waterbomb_base)
+            {"step": 1, "description": "Fold first diagonal", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 3, "description": "Fold second diagonal", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            {"step": 4, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 0.0], "end": [0.0, 1.0]}, "angle": 0, "layer_select": "all"},
+            {"step": 5, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 6, "description": "Collapse into waterbomb base (triangle)", "type": "valley", "line": {"start": [0.0, 0.0], "end": [1.0, 1.0]}, "angle": 180, "layer_select": "all"},
+            # Phase 2: Fold flaps to top
+            {"step": 7, "description": "Fold bottom-left corner of front layer up to top", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
+            {"step": 8, "description": "Fold bottom-right corner of front layer up to top", "type": "valley", "line": {"start": [1.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
+            # Phase 3: Tuck flaps
+            {"step": 9, "description": "Fold left and right points to center", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
+            {"step": 10, "description": "Tuck small triangles into pockets", "type": "valley", "line": {"start": [0.35, 0.4], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
+            {"step": 11, "description": "Repeat steps 7-10 on back", "type": "valley", "line": {"start": [0.0, 0.0], "end": [0.5, 0.5]}, "angle": 180, "layer_select": "top"},
+            # Phase 4: Inflate
+            {"step": 12, "description": "Blow into hole at bottom to inflate into cube/sphere", "type": "inflate", "line": {"start": [0.5, 0.0], "end": [0.5, 0.5]}, "angle": 0, "layer_select": "all"},
+        ],
+    },
+
+    "jumping_frog": {
+        "name": "Jumping Frog",
+        "difficulty": "low_intermediate",
+        "base": None,
+        "total_steps": 15,
+        "description": "A frog that jumps when you press its back. Uses pleats for the spring.",
+        "steps": [
+            {"step": 1, "description": "Fold in half horizontally", "type": "valley", "line": {"start": [0.0, 0.5], "end": [1.0, 0.5]}, "angle": 180, "layer_select": "all"},
+            {"step": 2, "description": "Fold top-left corner to right edge", "type": "valley", "line": {"start": [0.0, 1.0], "end": [1.0, 0.75]}, "angle": 180, "layer_select": "all"},
+            {"step": 3, "description": "Unfold", "type": "unfold", "line": {"start": [0.0, 1.0], "end": [1.0, 0.75]}, "angle": 0, "layer_select": "all"},
+            {"step": 4, "description": "Fold top-right corner to left edge", "type": "valley", "line": {"start": [1.0, 1.0], "end": [0.0, 0.75]}, "angle": 180, "layer_select": "all"},
+            {"step": 5, "description": "Unfold", "type": "unfold", "line": {"start": [1.0, 1.0], "end": [0.0, 0.75]}, "angle": 0, "layer_select": "all"},
+            {"step": 6, "description": "Collapse top into waterbomb-like triangle", "type": "valley", "line": {"start": [0.0, 0.75], "end": [1.0, 0.75]}, "angle": 180, "layer_select": "all"},
+            {"step": 7, "description": "Fold left point of triangle up and outward for front leg", "type": "valley", "line": {"start": [0.25, 0.75], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 8, "description": "Fold right point of triangle up and outward for front leg", "type": "valley", "line": {"start": [0.75, 0.75], "end": [0.5, 1.0]}, "angle": 180, "layer_select": "top"},
+            {"step": 9, "description": "Fold bottom half up to meet triangle base", "type": "valley", "line": {"start": [0.0, 0.375], "end": [1.0, 0.375]}, "angle": 180, "layer_select": "all"},
+            {"step": 10, "description": "Fold left side to center", "type": "valley", "line": {"start": [0.25, 0.0], "end": [0.25, 0.75]}, "angle": 180, "layer_select": "all"},
+            {"step": 11, "description": "Fold right side to center", "type": "valley", "line": {"start": [0.75, 0.0], "end": [0.75, 0.75]}, "angle": 180, "layer_select": "all"},
+            {"step": 12, "description": "Fold bottom up", "type": "valley", "line": {"start": [0.25, 0.25], "end": [0.75, 0.25]}, "angle": 180, "layer_select": "all"},
+            {"step": 13, "description": "Pull back legs out to sides", "type": "valley", "line": {"start": [0.375, 0.0], "end": [0.375, 0.375]}, "angle": 180, "layer_select": "top"},
+            {"step": 14, "description": "Pleat fold for spring: fold bottom half down", "type": "mountain", "line": {"start": [0.25, 0.15], "end": [0.75, 0.15]}, "angle": 180, "layer_select": "all"},
+            {"step": 15, "description": "Valley fold bottom portion back up for spring action", "type": "valley", "line": {"start": [0.25, 0.08], "end": [0.75, 0.08]}, "angle": 180, "layer_select": "all"},
+        ],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def get_base_steps(base_name: str) -> list[dict]:
+    """Return the fold steps for a given base, or empty list if not found."""
+    base = ORIGAMI_BASES.get(base_name)
+    if base is None:
+        return []
+    return list(base["steps"])
+
+
+def get_model_steps(model_name: str) -> list[dict]:
+    """Return the full fold steps for a known model, or empty list."""
+    model = ORIGAMI_MODELS.get(model_name)
+    if model is None:
+        return []
+    return list(model["steps"])
+
+
+def list_known_models() -> list[str]:
+    """Return names of all known origami models."""
+    return list(ORIGAMI_MODELS.keys())
+
+
+def list_known_bases() -> list[str]:
+    """Return names of all known origami bases."""
+    return list(ORIGAMI_BASES.keys())
+
+
+def get_fold_operation(name: str) -> dict | None:
+    """Look up a fold operation by name."""
+    return FOLD_OPERATIONS.get(name)

planner/parser.py

@@ -0,0 +1,291 @@
+"""
+Instruction parser: converts human text into a structured origami task.
+
+Handles variations like:
+  - "make a paper crane"
+  - "fold me a crane"
+  - "i want to make a paper crane"
+  - "crane please"
+  - "can you fold a crane?"
+  - "pack a 1m x 1m mylar sheet as compact as possible"
+"""
+
+from __future__ import annotations
+
+import re
+from planner.knowledge import ORIGAMI_MODELS, list_known_models
+
+
+# ---------------------------------------------------------------------------
+# Vocabulary for matching
+# ---------------------------------------------------------------------------
+
+# Model aliases → canonical name
+_MODEL_ALIASES: dict[str, str] = {
+    # Crane
+    "crane": "crane",
+    "tsuru": "crane",
+    "bird": "crane",
+    "orizuru": "crane",
+    # Boat
+    "boat": "boat",
+    "hat": "boat",
+    "paper boat": "boat",
+    "paper hat": "boat",
+    # Airplane
+    "airplane": "airplane",
+    "aeroplane": "airplane",
+    "plane": "airplane",
+    "paper airplane": "airplane",
+    "paper plane": "airplane",
+    "dart": "airplane",
+    "paper dart": "airplane",
+    # Box
+    "box": "box",
+    "masu": "box",
+    "masu box": "box",
+    "open box": "box",
+    # Fortune teller
+    "fortune teller": "fortune_teller",
+    "fortune-teller": "fortune_teller",
+    "cootie catcher": "fortune_teller",
+    "cootie-catcher": "fortune_teller",
+    "chatterbox": "fortune_teller",
+    # Waterbomb / balloon
+    "waterbomb": "waterbomb",
+    "water bomb": "waterbomb",
+    "balloon": "waterbomb",
+    "paper balloon": "waterbomb",
+    # Jumping frog
+    "jumping frog": "jumping_frog",
+    "frog": "jumping_frog",
+    "leap frog": "jumping_frog",
+}
+
+# Sorted longest-first so multi-word aliases match before single-word ones
+_ALIAS_KEYS_SORTED = sorted(_MODEL_ALIASES.keys(), key=len, reverse=True)
+
+_MATERIALS = {
+    "paper": "paper",
+    "mylar": "mylar",
+    "aluminum": "aluminum",
+    "aluminium": "aluminum",
+    "metal": "metal",
+    "nitinol": "nitinol",
+    "foil": "aluminum",
+    "cardboard": "cardboard",
+    "cardstock": "cardstock",
+    "fabric": "fabric",
+    "cloth": "fabric",
+}
+
+# Intent keywords
+_FOLD_VERBS = {
+    "make", "fold", "create", "build", "construct", "origami",
+    "craft", "form", "shape", "assemble",
+}
+_PACK_VERBS = {
+    "pack", "compress", "compact", "minimize", "reduce", "stow",
+    "shrink", "deploy", "collapse",
+}
+_OPTIMIZE_PHRASES = [
+    "as compact as possible",
+    "minimize volume",
+    "minimize packed volume",
+    "minimize area",
+    "solar panel",
+    "stent",
+    "deployable",
+    "maximize compactness",
+    "flatten",
+]
+
+# Dimension patterns
+_DIM_PATTERNS = [
+    # "10cm x 10cm", "10 cm x 10 cm"
+    re.compile(
+        r"(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet)\s*[xX\u00d7]\s*(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet)",
+        re.IGNORECASE,
+    ),
+    # "10cm square", "1 meter square"
+    re.compile(
+        r"(\d+(?:\.\d+)?)\s*(cm|mm|m|in|inch|inches|ft|feet|meter|meters|metre|metres)\s+square",
+        re.IGNORECASE,
+    ),
+]
+
+_UNIT_TO_M = {
+    "m": 1.0,
+    "meter": 1.0,
+    "meters": 1.0,
+    "metre": 1.0,
+    "metres": 1.0,
+    "cm": 0.01,
+    "mm": 0.001,
+    "in": 0.0254,
+    "inch": 0.0254,
+    "inches": 0.0254,
+    "ft": 0.3048,
+    "feet": 0.3048,
+}
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+def _normalise(text: str) -> str:
+    """Lower-case and strip extra whitespace."""
+    return " ".join(text.lower().split())
+
+
+def _detect_model(text: str) -> str | None:
+    """Return canonical model name if one is mentioned, else None."""
+    norm = _normalise(text)
+
+    # Strip out constraint phrases that might contain model-name false positives
+    # e.g. "into a 15cm x 15cm x 5cm box" should not match "box" as a model
+    cleaned = re.sub(
+        r"(?:fit\s+)?(?:in(?:to)?|inside)\s+(?:a\s+)?\d.*?box",
+        "",
+        norm,
+    )
+
+    for alias in _ALIAS_KEYS_SORTED:
+        # Use word-boundary-aware search to avoid partial matches
+        pattern = r"(?:^|\b)" + re.escape(alias) + r"(?:\b|$)"
+        if re.search(pattern, cleaned):
+            return _MODEL_ALIASES[alias]
+    return None
+
+
+def _detect_material(text: str) -> str:
+    """Return detected material or default 'paper'."""
+    norm = _normalise(text)
+    # Check multi-word materials first (none currently, but future-proof)
+    for keyword, canonical in sorted(_MATERIALS.items(), key=lambda kv: -len(kv[0])):
+        if keyword in norm:
+            return canonical
+    return "paper"
+
+
+def _detect_dimensions(text: str) -> dict[str, float]:
+    """Parse explicit dimensions. Returns {"width": m, "height": m} or defaults."""
+    for pat in _DIM_PATTERNS:
+        m = pat.search(text)
+        if m:
+            groups = m.groups()
+            if len(groups) == 4:
+                # WxH pattern
+                w = float(groups[0]) * _UNIT_TO_M.get(groups[1].lower(), 1.0)
+                h = float(groups[2]) * _UNIT_TO_M.get(groups[3].lower(), 1.0)
+                return {"width": round(w, 6), "height": round(h, 6)}
+            elif len(groups) == 2:
+                # "N unit square"
+                side = float(groups[0]) * _UNIT_TO_M.get(groups[1].lower(), 1.0)
+                return {"width": round(side, 6), "height": round(side, 6)}
+    # Default: unit square
+    return {"width": 1.0, "height": 1.0}
+
+
+def _detect_constraints(text: str) -> dict:
+    """Detect any explicit constraints mentioned in the instruction."""
+    norm = _normalise(text)
+    constraints: dict = {}
+
+    # Target bounding box: "fit in a 15cm x 15cm x 5cm box"
+    box_pat = re.compile(
+        r"fit\s+(?:in(?:to)?|inside)\s+(?:a\s+)?(\d+(?:\.\d+)?)\s*(cm|mm|m)\s*[xX\u00d7]\s*"
+        r"(\d+(?:\.\d+)?)\s*(cm|mm|m)\s*[xX\u00d7]\s*(\d+(?:\.\d+)?)\s*(cm|mm|m)",
+        re.IGNORECASE,
+    )
+    bm = box_pat.search(norm)
+    if bm:
+        g = bm.groups()
+        constraints["target_box"] = [
+            float(g[0]) * _UNIT_TO_M.get(g[1], 1.0),
+            float(g[2]) * _UNIT_TO_M.get(g[3], 1.0),
+            float(g[4]) * _UNIT_TO_M.get(g[5], 1.0),
+        ]
+
+    # Max folds
+    folds_pat = re.compile(r"(?:max(?:imum)?|at most|no more than)\s+(\d+)\s+fold", re.IGNORECASE)
+    fm = folds_pat.search(norm)
+    if fm:
+        constraints["max_folds"] = int(fm.group(1))
+
+    # Compactness emphasis
+    for phrase in _OPTIMIZE_PHRASES:
+        if phrase in norm:
+            constraints["optimize_compactness"] = True
+            break
+
+    # Must deploy
+    if "deploy" in norm or "unfold" in norm and "clean" in norm:
+        constraints["must_deploy"] = True
+
+    return constraints
+
+
+def _detect_intent(text: str, model_name: str | None, constraints: dict) -> str:
+    """Determine the high-level intent of the instruction."""
+    norm = _normalise(text)
+    words = set(norm.split())
+
+    # If packing / optimization phrases are present, it's an optimization task
+    if constraints.get("optimize_compactness"):
+        return "optimize_packing"
+    if words & _PACK_VERBS:
+        return "optimize_packing"
+
+    # If a known model is detected, it's a fold_model task
+    if model_name is not None:
+        return "fold_model"
+
+    # If fold verbs are present but no model, it's a free fold
+    if words & _FOLD_VERBS:
+        return "free_fold"
+
+    # Fallback: if there's a pattern keyword
+    pattern_words = {"miura", "tessellation", "pattern", "waterbomb tessellation", "pleat"}
+    if words & pattern_words:
+        return "fold_pattern"
+
+    return "free_fold"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def parse_instruction(text: str) -> dict:
+    """
+    Parse a human origami instruction into a structured task.
+
+    Args:
+        text: Natural-language instruction, e.g. "make a paper crane"
+
+    Returns:
+        {
+            "intent": "fold_model" | "fold_pattern" | "optimize_packing" | "free_fold",
+            "model_name": str or None,
+            "material": str,
+            "dimensions": {"width": float, "height": float},
+            "constraints": {...},
+            "raw_instruction": str,
+        }
+    """
+    model_name = _detect_model(text)
+    material = _detect_material(text)
+    dimensions = _detect_dimensions(text)
+    constraints = _detect_constraints(text)
+    intent = _detect_intent(text, model_name, constraints)
+
+    return {
+        "intent": intent,
+        "model_name": model_name,
+        "material": material,
+        "dimensions": dimensions,
+        "constraints": constraints,
+        "raw_instruction": text,
+    }

planner/planner.py

@@ -0,0 +1,305 @@
+"""
+OrigamiPlanner: the main orchestrator that converts human instructions
+into structured fold plans with LLM-ready prompts.
+
+Usage:
+    from planner.planner import OrigamiPlanner
+
+    planner = OrigamiPlanner()
+    plan = planner.plan("make a paper crane")
+    print(plan.summary())
+    prompt = plan.get_prompt_for_step(0)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from planner.parser import parse_instruction
+from planner.decomposer import decompose_task
+from planner.knowledge import ORIGAMI_MODELS, FOLD_OPERATIONS
+
+
+# ---------------------------------------------------------------------------
+# Material defaults (mirrors trainer/prompts.py TASK_CONFIGS)
+# ---------------------------------------------------------------------------
+
+_MATERIAL_DEFAULTS = {
+    "paper":     {"thickness_mm": 0.1,  "youngs_modulus_gpa": 2.0,  "max_strain_pct": 3},
+    "mylar":     {"thickness_mm": 0.05, "youngs_modulus_gpa": 4.0,  "max_strain_pct": 3},
+    "aluminum":  {"thickness_mm": 0.02, "youngs_modulus_gpa": 69.0, "max_strain_pct": 1},
+    "metal":     {"thickness_mm": 0.05, "youngs_modulus_gpa": 200.0,"max_strain_pct": 0.5},
+    "nitinol":   {"thickness_mm": 0.1,  "youngs_modulus_gpa": 75.0, "max_strain_pct": 8},
+    "cardboard": {"thickness_mm": 1.0,  "youngs_modulus_gpa": 1.0,  "max_strain_pct": 2},
+    "cardstock": {"thickness_mm": 0.3,  "youngs_modulus_gpa": 1.5,  "max_strain_pct": 2},
+    "fabric":    {"thickness_mm": 0.2,  "youngs_modulus_gpa": 0.1,  "max_strain_pct": 15},
+}
+
+
+# ---------------------------------------------------------------------------
+# FoldPlan dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FoldPlan:
+    """
+    A complete, executable fold plan produced by OrigamiPlanner.
+
+    Attributes:
+        instruction: The original human instruction.
+        parsed: Structured parse result (intent, model, material, etc.).
+        steps: Ordered list of sub-goal dicts from the decomposer.
+        prompts: Pre-built LLM prompts, one per step.
+    """
+
+    instruction: str
+    parsed: dict
+    steps: list[dict]
+    prompts: list[str]
+
+    # ------------------------------------------------------------------
+    # Summaries
+    # ------------------------------------------------------------------
+
+    def summary(self) -> str:
+        """Human-readable summary of the plan."""
+        lines: list[str] = []
+        lines.append(f"Origami Plan: {self.instruction}")
+        lines.append(f"  Intent : {self.parsed['intent']}")
+        if self.parsed.get("model_name"):
+            model = ORIGAMI_MODELS.get(self.parsed["model_name"], {})
+            lines.append(f"  Model  : {model.get('name', self.parsed['model_name'])}")
+            lines.append(f"  Difficulty: {model.get('difficulty', 'unknown')}")
+        lines.append(f"  Material: {self.parsed['material']}")
+        dims = self.parsed["dimensions"]
+        lines.append(f"  Sheet  : {dims['width']}m x {dims['height']}m")
+        lines.append(f"  Steps  : {len(self.steps)}")
+        lines.append("")
+        lines.append("Step-by-step:")
+        for s in self.steps:
+            n = s["step_number"]
+            desc = s["description"]
+            n_ops = len(s.get("fold_operations", []))
+            lines.append(f"  {n:>3}. {desc}  ({n_ops} fold op{'s' if n_ops != 1 else ''})")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Prompt access
+    # ------------------------------------------------------------------
+
+    def get_prompt_for_step(self, step_index: int, current_state: dict | None = None) -> str:
+        """
+        Get the LLM prompt for a specific step, optionally enriched with
+        the current paper state from the simulation engine.
+
+        Args:
+            step_index: Zero-based index into self.steps.
+            current_state: Optional live paper_state dict from the engine.
+
+        Returns:
+            A fully-formatted prompt string ready for the LLM.
+        """
+        if step_index < 0 or step_index >= len(self.steps):
+            raise IndexError(f"step_index {step_index} out of range (0..{len(self.steps) - 1})")
+
+        base_prompt = self.prompts[step_index]
+
+        if current_state is None:
+            return base_prompt
+
+        # Inject live state into the prompt
+        state_block = _format_state_block(current_state)
+        return base_prompt.replace("{{CURRENT_STATE}}", state_block)
+
+    # ------------------------------------------------------------------
+    # Convenience: all fold operations flattened
+    # ------------------------------------------------------------------
+
+    def all_fold_operations(self) -> list[dict]:
+        """Return every fold operation across all steps, in order."""
+        ops: list[dict] = []
+        for step in self.steps:
+            ops.extend(step.get("fold_operations", []))
+        return ops
+
+    def total_fold_count(self) -> int:
+        """Total number of fold operations in the plan."""
+        return sum(len(s.get("fold_operations", [])) for s in self.steps)
+
+
+# ---------------------------------------------------------------------------
+# Prompt builder helpers
+# ---------------------------------------------------------------------------
+
+def _format_state_block(state: dict) -> str:
+    """Format a paper_state dict as a human-readable block for the prompt."""
+    lines = ["CURRENT STATE:"]
+    if "bounding_box" in state:
+        bb = state["bounding_box"]
+        if isinstance(bb, dict):
+            lines.append(f"  Bounding box: {bb.get('x', '?')}m x {bb.get('y', '?')}m x {bb.get('z', '?')}m")
+        elif isinstance(bb, (list, tuple)) and len(bb) >= 3:
+            lines.append(f"  Bounding box: {bb[0]}m x {bb[1]}m x {bb[2]}m")
+    if "num_layers_at_center" in state:
+        lines.append(f"  Layers at center: {state['num_layers_at_center']}")
+    if "deployment_ratio" in state:
+        lines.append(f"  Deployment ratio: {state['deployment_ratio']:.3f}")
+    if "fold_angles" in state:
+        n_folds = sum(1 for a in state["fold_angles"] if a != 0)
+        lines.append(f"  Active folds: {n_folds}")
+    return "\n".join(lines)
+
+
+def _format_fold_ops_as_code(ops: list[dict]) -> str:
+    """Format fold operations as Python list literal for inclusion in a prompt."""
+    if not ops:
+        return "    # (LLM: determine fold operations for this step)\n    return []"
+
+    lines = ["    return ["]
+    for op in ops:
+        clean = {
+            "type": op["type"],
+            "line": op.get("line", {"start": [0, 0], "end": [1, 1]}),
+            "angle": op.get("angle", 180),
+        }
+        lines.append(f"        {json.dumps(clean)},")
+    lines.append("    ]")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# OrigamiPlanner
+# ---------------------------------------------------------------------------
+
+class OrigamiPlanner:
+    """
+    Full pipeline: human instruction -> structured plan -> executable fold operations.
+
+    The planner:
+      1. Parses the instruction (parser.py)
+      2. Decomposes into sub-goals (decomposer.py)
+      3. Builds LLM-ready prompts matching trainer/prompts.py format
+    """
+
+    def plan(self, instruction: str) -> FoldPlan:
+        """
+        Plan an origami task from a human instruction.
+
+        Args:
+            instruction: e.g. "make a paper crane", "pack a 1m mylar sheet"
+
+        Returns:
+            A FoldPlan with steps and LLM prompts.
+        """
+        parsed = parse_instruction(instruction)
+        steps = decompose_task(parsed)
+        prompts = [self._build_prompt(step, i, parsed) for i, step in enumerate(steps)]
+        return FoldPlan(
+            instruction=instruction,
+            parsed=parsed,
+            steps=steps,
+            prompts=prompts,
+        )
+
+    # ------------------------------------------------------------------
+    # Prompt construction
+    # ------------------------------------------------------------------
+
+    def _build_prompt(self, step: dict, step_index: int, parsed: dict) -> str:
+        """
+        Build an LLM-ready prompt for a single sub-goal step.
+
+        The format matches trainer/prompts.py: task description at top,
+        material/constraints in the middle, and a fold_strategy() code
+        block wrapped in triple backticks at the bottom.
+        """
+        material = parsed["material"]
+        mat_info = _MATERIAL_DEFAULTS.get(material, _MATERIAL_DEFAULTS["paper"])
+        dims = parsed["dimensions"]
+        constraints = parsed.get("constraints", {})
+        total_steps = len(parsed.get("_all_steps", [])) or step.get("step_number", 1)
+
+        # ---- Header ----
+        intent = parsed["intent"]
+        if intent == "fold_model" and parsed.get("model_name"):
+            model_info = ORIGAMI_MODELS.get(parsed["model_name"], {})
+            task_line = (
+                f"TASK: Step {step['step_number']} of {total_steps} — "
+                f"{step['description']}\n"
+                f"MODEL: {model_info.get('name', parsed['model_name'])} "
+                f"(difficulty: {model_info.get('difficulty', 'unknown')})"
+            )
+        elif intent == "optimize_packing":
+            task_line = (
+                f"TASK: Step {step['step_number']} — {step['description']}\n"
+                f"GOAL: Minimize packed volume while maintaining deployability."
+            )
+        else:
+            task_line = f"TASK: Step {step['step_number']} — {step['description']}"
+
+        # ---- Material ----
+        material_block = (
+            f"MATERIAL:\n"
+            f"  - Name: {material}\n"
+            f"  - Thickness: {mat_info['thickness_mm']}mm\n"
+            f"  - Max strain: {mat_info['max_strain_pct']}%"
+        )
+
+        # ---- Constraints ----
+        constraint_lines = ["CONSTRAINTS:"]
+        if "max_folds" in constraints:
+            constraint_lines.append(f"  - Maximum {constraints['max_folds']} fold operations")
+        if "target_box" in constraints:
+            tb = constraints["target_box"]
+            constraint_lines.append(
+                f"  - Must pack into bounding box <= "
+                f"{tb[0]*100:.0f}cm x {tb[1]*100:.0f}cm x {tb[2]*100:.0f}cm"
+            )
+        if constraints.get("must_deploy"):
+            constraint_lines.append("  - Must deploy to >= 80% of original area")
+        constraint_lines.append("  - No self-intersections allowed")
+        constraints_block = "\n".join(constraint_lines)
+
+        # ---- State placeholder ----
+        state_block = (
+            f"CURRENT STATE:\n"
+            f"  Sheet: {dims['width']}m x {dims['height']}m\n"
+            f"  {{{{CURRENT_STATE}}}}"
+        )
+
+        # ---- Fold operations hint ----
+        ops = step.get("fold_operations", [])
+        ops_code = _format_fold_ops_as_code(ops)
+
+        # ---- Expected result ----
+        expected = step.get("expected_state", {})
+        expected_block = ""
+        if expected:
+            expected_block = f"\nEXPECTED RESULT: {json.dumps(expected)}"
+
+        # ---- Code block (matches trainer/prompts.py format) ----
+        code_block = (
+            f'Write a fold_strategy(paper_state) function that returns a list of fold operations.\n'
+            f'Each fold: {{"type": "valley"|"mountain", "line": {{"start": [x,y], "end": [x,y]}}, "angle": 0-180}}\n'
+            f'\n'
+            f'```python\n'
+            f'def fold_strategy(paper_state):\n'
+            f'{ops_code}\n'
+            f'```'
+        )
+
+        # ---- Assemble ----
+        sections = [
+            task_line,
+            "",
+            material_block,
+            "",
+            constraints_block,
+            "",
+            state_block,
+            expected_block,
+            "",
+            code_block,
+        ]
+        return "\n".join(sections)

trainer/rewards.py

@@ -16,9 +16,43 @@ import math
 import traceback
 from typing import Callable
 
-from trainer.mock_env import (
-    PaperState, create_flat_sheet, execute_fold_strategy, Material
-)
+# Use real engine if available, fall back to mock
+try:
+    from engine.paper import Paper
+    from engine.fold_engine import execute_fold_strategy
+    from engine.materials import Material, get_material
+    from engine.validation import validate_paper
+    from engine.metrics import compute_metrics
+
+    def _create_sheet(width, height, material):
+        return Paper.create_flat_sheet(width, height, material)
+
+    USE_REAL_ENGINE = True
+except ImportError:
+    from trainer.mock_env import (
+        PaperState as Paper, create_flat_sheet, execute_fold_strategy, Material
+    )
+
+    def _create_sheet(width, height, material):
+        return create_flat_sheet(width, height, material)
+
+    def validate_paper(p):
+        from types import SimpleNamespace
+        return SimpleNamespace(
+            is_valid=p.is_valid, kawasaki_valid=True, maekawa_valid=True,
+            kawasaki_violation=p.kawasaki_violation,
+            maekawa_violation=p.maekawa_violation,
+            self_intersection_count=p.self_intersections,
+        )
+
+    def compute_metrics(p, orig):
+        return {
+            "deployment_ratio": p.deployment_ratio,
+            "fold_count": sum(1 for a in p.assignments if a in ("M", "V")),
+            "max_strain": float(p.strain.max()) if len(p.strain) > 0 else 0.0,
+        }
+
+    USE_REAL_ENGINE = False
 
 
 # ---------------------------------------------------------------------------
@@ -102,10 +136,15 @@ def create_sandboxed_function(code: str) -> Callable:
 # ---------------------------------------------------------------------------
 
 # Current task config (set by train.py before training starts)
+if USE_REAL_ENGINE:
+    _default_material = get_material("paper")
+else:
+    _default_material = Material()
+
 _current_task = {
     "width": 1.0,
     "height": 1.0,
-    "material": Material(),
+    "material": _default_material,
     "target_ratio": 0.5,
     "max_folds": 3,
 }
@@ -200,11 +239,12 @@ def physically_valid(completions, **kwargs) -> list[float]:
             continue
 
         try:
-            paper = create_flat_sheet(
+            paper = _create_sheet(
                 _current_task["width"],
                 _current_task["height"],
                 _current_task["material"],
             )
+            original = paper
             final_state, applied, error = execute_fold_strategy(
                 strategy_fn, paper, _current_task["max_folds"]
             )
@@ -217,13 +257,16 @@ def physically_valid(completions, **kwargs) -> list[float]:
                 scores.append(0.0)
                 continue
 
-            # Score based on validity
+            # Score based on validity using engine validation
+            val = validate_paper(final_state)
+            metrics = compute_metrics(final_state, original)
+
             score = 1.0
-            score -= 2.0 * final_state.kawasaki_violation
-            score -= 2.0 * final_state.maekawa_violation
-            if final_state.self_intersections > 0:
+            score -= 2.0 * val.kawasaki_violation
+            score -= 2.0 * val.maekawa_violation
+            if val.self_intersection_count > 0:
                 score -= 5.0
-            max_strain = float(final_state.strain.max()) if len(final_state.strain) > 0 else 0.0
+            max_strain = metrics.get("max_strain", 0.0)
             if max_strain > _current_task["material"].max_strain:
                 score -= 1.0
 
@@ -283,11 +326,12 @@ def fold_quality(completions, **kwargs) -> list[float]:
             continue
 
         try:
-            paper = create_flat_sheet(
+            paper = _create_sheet(
                 _current_task["width"],
                 _current_task["height"],
                 _current_task["material"],
             )
+            original = paper
             final_state, applied, error = execute_fold_strategy(
                 strategy_fn, paper, _current_task["max_folds"]
             )
@@ -303,28 +347,32 @@ def fold_quality(completions, **kwargs) -> list[float]:
                 scores.append(0.0)
                 continue
 
+            # Use engine metrics
+            metrics = compute_metrics(final_state, original)
+            deploy_ratio = metrics.get("deployment_ratio", 1.0)
+            max_strain = metrics.get("max_strain", 0.0)
+
             # Compactness: main reward signal
-            compactness = 1.0 - final_state.deployment_ratio
+            compactness = 1.0 - deploy_ratio
             score = 20.0 * compactness
 
             # Bonus for meeting target
-            if final_state.deployment_ratio <= _current_task["target_ratio"]:
+            if deploy_ratio <= _current_task["target_ratio"]:
                 score += 10.0
 
             # Fold efficiency penalty
             score -= 0.5 * num_folds
 
             # Strain penalty
-            max_strain = float(final_state.strain.max()) if len(final_state.strain) > 0 else 0.0
             mat_limit = _current_task["material"].max_strain
             if max_strain > mat_limit:
                 score -= 3.0 * (max_strain / mat_limit)
 
             if should_print:
-                print(f"Folds: {num_folds}, Ratio: {final_state.deployment_ratio:.3f}, "
+                print(f"Folds: {num_folds}, Ratio: {deploy_ratio:.3f}, "
                       f"Compactness: {compactness:.3f}, Score: {score:.2f}")
-                bb = final_state.bounding_box
-                print(f"BBox: {bb[0]:.3f} x {bb[1]:.3f} x {bb[2]:.3f}")
+                bb = metrics.get("bounding_box", {})
+                print(f"BBox: {bb.get('x',0):.3f} x {bb.get('y',0):.3f} x {bb.get('z',0):.3f}")
 
             scores.append(score)
 

trainer/train.py

@@ -20,7 +20,14 @@ if PROJECT_ROOT not in sys.path:
 
 from trainer.prompts import build_prompt, SYSTEM_PROMPT, get_task_target_ratio, get_task_max_folds
 from trainer.rewards import code_valid, physically_valid, fold_quality, set_task_config
-from trainer.mock_env import Material
+
+try:
+    from engine.materials import get_material
+    Material = type(get_material("paper"))  # get the Material class
+except ImportError:
+    from trainer.mock_env import Material
+    def get_material(name):
+        return Material()
 
 # ============================================================================
 # Config
@@ -82,7 +89,7 @@ def main():
     set_task_config(
         width=1.0,
         height=1.0,
-        material=Material(),
+        material=get_material("paper"),
         target_ratio=target_ratio,
         max_folds=max_folds,
     )