iana (#1)

- docs/handoff (2936d2efdffb9328f69a2e963b3ebd1de87e2449)
- plans/ (be602daa47c9f605d39659bc29515b59a433f59d)
- feat: implement origami RL environment (Phase 1) (d7f96cffadde2f76730c4871302da58301abd65f)
- feat: React observability dashboard + FastAPI server + matplotlib renderer (cecbed6224418454feaa683e9c5fcb12103b4ffd)
- feat: Python 3D origami mass-spring simulator (Ghassaei 2018) (94ab3fc15d67c0a7dcdc85153a42c9aa7bfa765a)
- Add 3D fold preview modes (e971f8f4c4e321dc962d15fd6801091d28396a6f)
- Add OpenEnv runtime adapter and server entrypoint (883cccb04ed467c34314981766ce0cb261a4fff4)
- Add OpenEnv manifest and deployment packaging (039a8a2b410b2a6511bad6d40885453da2eb3fa8)
- Add OpenEnv adapter contract tests (2f3409572f5262a20e9b67af66e8a469dfa923e4)


Co-authored-by: Iana Lin <ianalin123@users.noreply.huggingface.co>

.gitignore

@@ -28,3 +28,5 @@ __pycache__/
 
 # Reference repos (not pushed to HF)
 .reference/
+*.pyc
+__pycache__/

Dockerfile

@@ -0,0 +1,12 @@
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+WORKDIR /app
+
+COPY . /app
+
+RUN pip install --no-cache-dir -r requirements.txt \
+    && pip install --no-cache-dir "openenv-core[core]>=0.2.1"
+
+ENV ENABLE_WEB_INTERFACE=false
+
+CMD ["uvicorn", "openenv_server.app:app", "--host", "0.0.0.0", "--port", "8000"]

docs/optigami_handoff.md

@@ -0,0 +1,767 @@
+# OrigamiRL — OpenEnv Hackathon Handoff Document
+
+## TL;DR
+
+Build the **first multi-turn RL environment where an LLM learns to generate origami folding instructions**, verified by a computational origami simulator. Target the OpenEnv Hackathon (March 7-8, 2026, SF — $100K+ in prizes). Use OpenEnv spec + Unsloth GRPO for training. Dense verifiable rewards from origami geometry theorems (Kawasaki, Maekawa). No learned reward model needed.
+
+---
+
+## Hackathon Context
+
+- **Event:** OpenEnv Hackathon SF, hosted by Cerebral Valley + Shack15 + Meta/PyTorch
+- **Date:** March 7-8, 2026 (happening NOW)
+- **Prize:** $100K+ cash
+- **Teams:** Up to 4 people
+- **Format:** Build RL environments, post-train a base model
+
+### Judging Criteria
+
+| Category | Weight | What Matters |
+|----------|--------|-------------|
+| Environment Innovation | 40% | Novel, creative, challenging. Does it meaningfully test agent behavior? |
+| Storytelling | 30% | Clear problem explanation, engaging demo, easy to follow |
+| Training Script Showing Improvement | 20% | Observable reward curves, before/after behavior |
+| Reward and Training Pipeline Setup | 10% | Coherent reward logic, meaningful improvement in inference |
+
+### Key Sponsors to Impress
+
+- **Meta/PyTorch** — OpenEnv creators, want environments using their spec
+- **Unsloth AI** — GRPO training infra, ART (Agent Reinforcement Trainer). USE THEIR TOOLS.
+- **OpenPipe** — ART trainer (frontend/backend split for GRPO). Also use.
+- **Patronus AI** — Building "generative simulators" (auto-scaling RL environments). They care about curriculum difficulty scaling and verifiable rewards.
+- **Snorkel AI** — "2026 is the year of environments." They care about data quality and environment diversity.
+- **Hugging Face** — OpenEnv Hub, want environments deployed there
+- **Scale AI / Mercor** — Agent evaluation, structured task environments
+
+---
+
+## The Pitch (for judges)
+
+> "Spatial reasoning is the next frontier for LLM training — NeurIPS 2025 papers like OrigamiSpace showed that even GPT-5 fails at multi-step origami reasoning. But those are benchmarks, not training environments. We built OrigamiRL: the first multi-turn RL environment where an LLM agent learns to fold paper by outputting instructions, receiving geometric feedback, and improving through GRPO. Our reward function is fully verifiable — fold validity is checked against computational origami axioms, not an LLM judge. We built it on OpenEnv + Unsloth with a natural curriculum from single folds to full cranes."
+
+---
+
+## Prior Work (What Exists, Where the Gaps Are)
+
+### 1. OrigamiSpace (NeurIPS 2025 Spotlight)
+
+- **Paper:** https://arxiv.org/abs/2511.18450
+- **What it is:** Benchmark with 350 origami data instances (CP diagrams, folding processes, folded shapes). 4 evaluation tasks: Pattern Prediction, Multi-step Spatial Reasoning, Spatial Relationship Prediction, End-to-End CP Code Generation.
+- **Their compiler:** Outputs detailed flattened diagrams with crease locations and stacking relationships, supports interactive simulation with MLLMs, provides comprehensive error feedback. Checks: syntax validity, geometric foldability, no self-intersections, Kawasaki's theorem, Maekawa's theorem.
+- **Their reward metrics for code gen:** Hausdorff distance (shape similarity), dihedral angle distribution, bounding box aspect ratios, constraint satisfaction.
+- **Difficulty levels:** Easy (3-9 steps), Medium (10-19 steps), Hard (20-30 steps)
+- **Gap:** Single-turn only (LLM generates complete CP code in one shot). They mention RL exploration but it's not the focus. No multi-turn sequential folding.
+
+### 2. GamiBench (Dec 2025)
+
+- **Paper:** https://arxiv.org/abs/2512.22207
+- **What it is:** 186 regular + 186 impossible 2D crease patterns with 3D folded shapes from 6 viewpoints. 3 VQA tasks.
+- **Gap:** Evaluation-only, no training. Tests single-step spatial understanding.
+
+### 3. SpatialThinker (NeurIPS 2025)
+
+- **Paper:** https://arxiv.org/abs/2511.07403
+- **What it is:** 3D-aware MLLM trained with RL using dense spatial rewards. Constructs scene graphs. Multi-objective reward with lexicographic gating.
+- **Key architecture to steal:** Dense reward design with lexicographic ordering — format → count → accuracy → spatial. Nearly doubled RL training gains vs sparse rewards. Only needed 7K training samples with GRPO.
+- **Gap:** Static scene understanding (objects on a table), not sequential physical transformations.
+
+### 4. rigid-origami Gym (IJCAI 2023)
+
+- **Repo:** https://github.com/belalugaX/rigid-origami
+- **Paper:** "Automating Rigid Origami Design" (https://arxiv.org/abs/2211.13219)
+- **What it is:** Gym environment where agent constructs crease pattern graphs on a board. Sparse rewards. Foldability validated by triangle intersection tests + kinematic rigidity model. Game terminates on non-foldable states.
+- **Gap:** Classical RL agents (discrete grid actions), NOT LLMs generating text. Rigid-origami tessellations only, not traditional origami. No natural language.
+
+### 5. The Unique Gap We Fill
+
+Nobody has built a model that reasons about **sequential 2D-to-3D geometric transformations with physical constraints** through **natural language instructions** in a **multi-turn RL training loop**. Origami is uniquely hard because it requires tracking how a flat sheet's topology changes through a sequence of folds — mental rotation, spatial visualization, and perspective-taking all at once.
+
+---
+
+## Environment Design
+
+### Architecture Overview
+
+```
++---------------------------------------------------+
+|                   OpenEnv Server                   |
+|  +-----------+  +----------+  +--------------+    |
+|  |   State   |  |  Action  |  |   Reward     |    |
+|  | (FOLD JSON|  | (LLM     |  | (Dense,      |    |
+|  |  + target)|  |  output) |  |  verifiable) |    |
+|  +-----------+  +----------+  +--------------+    |
+|         |              |              |            |
+|         v              v              v            |
+|  +-----------------------------------------------+|
+|  |         Paper Geometry Engine (Python)         ||
+|  |  - Polygon state (Shapely)                    ||
+|  |  - Fold operations (reflection across line)   ||
+|  |  - Kawasaki/Maekawa constraint checks         ||
+|  |  - Layer tracking                             ||
+|  |  - FOLD format import/export                  ||
+|  +-----------------------------------------------+|
+|         |                                          |
+|         v                                          |
+|  +-----------------------------------------------+|
+|  |         Three.js Visualizer (Demo only)        ||
+|  |  - 3D fold animation                          ||
+|  |  - Strain heatmap                             ||
+|  |  - Instruction stream                         ||
+|  +-----------------------------------------------+|
++---------------------------------------------------+
+         |                    ^
+         v                    |
++---------------------------------------------------+
+|              Unsloth ART / GRPO Trainer            |
+|  - Qwen2.5-VL-7B or Qwen3-4B base model          |
+|  - LoRA/QLoRA for efficient training              |
+|  - Multi-turn rollouts                            |
++---------------------------------------------------+
+```
+
+### OpenEnv Spec Compliance
+
+Must implement these APIs:
+
+```python
+class OrigamiEnv:
+    async def reset() -> Observation     # New episode: flat paper + target
+    async def step(action) -> (Observation, reward, done, info)
+    async def state() -> State           # Current paper geometry
+    async def close()                    # Cleanup
+```
+
+OpenEnv repo: https://github.com/meta-pytorch/OpenEnv
+Install: `pip install -e .` then `openenv init origami_env`
+
+### State Space
+
+```python
+@dataclass
+class OrigamiState:
+    # Current paper geometry
+    vertices: List[Tuple[float, float]]       # 2D vertex positions
+    edges: List[Tuple[int, int]]              # Edge connectivity
+    edges_assignment: List[str]               # 'M', 'V', 'B', 'F' (mountain/valley/boundary/flat)
+    edges_foldAngle: List[float]              # -180 to 180 degrees
+    faces: List[List[int]]                    # Face vertex indices
+    layer_order: List[List[int]]              # Face stacking order
+
+    # Episode context
+    target_crease_pattern: dict               # Target FOLD JSON
+    target_shape_image: Optional[np.ndarray]  # Target folded shape (for multimodal)
+    instruction_history: List[str]            # Previous instructions
+    step_count: int
+    max_steps: int
+```
+
+This maps directly to the **FOLD format** (JSON-based, used by all origami software):
+
+```json
+{
+  "vertices_coords": [[0,0], [1,0], [1,1], [0,1]],
+  "edges_vertices": [[0,1], [1,2], [2,3], [3,0]],
+  "edges_assignment": ["B", "B", "B", "B"],
+  "edges_foldAngle": [0, 0, 0, 0],
+  "faces_vertices": [[0, 1, 2, 3]]
+}
+```
+
+FOLD spec: https://github.com/edemaine/fold
+FOLD JS library: https://edemaine.github.io/fold/
+
+### Action Space
+
+The LLM outputs a JSON action:
+
+```json
+{
+  "instruction": "Fold the top edge down to meet the bottom edge",
+  "fold_line": [[0, 0.5], [1, 0.5]],
+  "fold_angle": -180,
+  "assignment": "V"
+}
+```
+
+The `instruction` field is natural language (what we're training the model to produce well). The geometric fields are the verifiable representation. During training, the model outputs both; for the final demo, the NL instruction is the star.
+
+Alternative simpler action (for early iterations):
+
+```json
+{
+  "instruction": "Valley fold along the horizontal center line",
+  "fold_type": "valley",
+  "fold_axis": "horizontal",
+  "fold_position": 0.5
+}
+```
+
+### Reward Function — Dense, Multi-Objective, Lexicographically Gated
+
+Inspired by SpatialThinker's design. Rewards are computed in order; later rewards only apply if earlier gates pass.
+
+```python
+def compute_reward(state, action, new_state, target) -> dict:
+    rewards = {}
+
+    # LEVEL 1: Format (gate for everything else)
+    # Does the output parse into a valid fold operation?
+    rewards['format'] = 1.0 if parseable(action) else 0.0
+    if rewards['format'] == 0:
+        return rewards  # Stop here
+
+    # LEVEL 2: Local Geometric Validity
+    # Kawasaki's theorem: sector angles at each interior vertex sum to 2pi
+    kawasaki_valid = check_kawasaki(new_state)
+    # Maekawa's theorem: |M - V| = 2 at each interior vertex
+    maekawa_valid = check_maekawa(new_state)
+    # No self-intersection
+    no_intersection = check_no_self_intersection(new_state)
+    rewards['validity'] = (kawasaki_valid + maekawa_valid + no_intersection) / 3.0
+    if rewards['validity'] < 0.5:
+        return rewards  # Stop here
+
+    # LEVEL 3: Physical Feasibility
+    # Can this fold actually be performed given layer stack?
+    layer_consistent = check_layer_ordering(new_state)
+    fold_achievable = check_fold_angle_feasible(new_state)
+    rewards['feasibility'] = (layer_consistent + fold_achievable) / 2.0
+
+    # LEVEL 4: Progress Toward Target (Dense)
+    # Crease pattern graph similarity
+    cp_similarity = crease_pattern_similarity(new_state, target)
+    # Fold angle distribution match
+    angle_similarity = fold_angle_distribution_match(new_state, target)
+    # Bounding box aspect ratio match
+    bbox_similarity = bounding_box_similarity(new_state, target)
+    rewards['progress'] = 0.4 * cp_similarity + 0.4 * angle_similarity + 0.2 * bbox_similarity
+
+    # LEVEL 5: Completion Bonus
+    if shape_matches_target(new_state, target, tolerance=0.05):
+        rewards['completion'] = 10.0
+
+    # LEVEL 6: Efficiency
+    rewards['efficiency'] = -0.01  # Small step penalty to encourage fewer folds
+
+    # Total
+    rewards['total'] = (
+        0.1 * rewards['format'] +
+        0.2 * rewards['validity'] +
+        0.1 * rewards['feasibility'] +
+        0.5 * rewards['progress'] +
+        rewards.get('completion', 0) +
+        rewards['efficiency']
+    )
+    return rewards
+```
+
+### Key Origami Theorems for Verification
+
+These are the verifiable constraints — the "unit tests" of origami:
+
+1. **Kawasaki's Theorem:** At any interior vertex of a flat-foldable crease pattern, the alternating sum of sector angles equals zero (equivalently, they sum to 2pi on each side). NECESSARY condition for flat-foldability.
+
+2. **Maekawa's Theorem:** At any interior vertex, the number of mountain folds minus valley folds equals +/-2. |M - V| = 2.
+
+3. **No self-intersection:** Faces cannot penetrate each other during folding.
+
+4. **Euler's formula for planar graphs:** V - E + F = 2 (sanity check on graph structure).
+
+5. **Huzita-Hatori axioms:** The 7 axioms defining all possible single-fold operations (point-to-point, point-to-line, line-to-line, etc.). These define the VALID action space.
+
+### Curriculum Design
+
+| Level | Folds | Examples | Complexity |
+|-------|-------|----------|-----------|
+| 1 | 1 | Valley fold in half, mountain fold corner | Single fold validity |
+| 2 | 2-3 | Paper airplane nose, triangle fold | Sequential dependency |
+| 3 | 4-6 | Simple boat, fortune teller | Multi-step with symmetry |
+| 4 | 7-12 | Paper airplane (full), jumping frog | Longer horizon planning |
+| 5 | 13-20 | Crane, lily | Complex spatial tracking |
+
+For the hackathon, focus on Levels 1-3. Even showing reward improvement on Level 1-2 is a strong result.
+
+---
+
+## Core Implementation: Python Geometry Engine
+
+This is the MOST IMPORTANT piece. Pure Python, no JS dependencies.
+
+```python
+import numpy as np
+from shapely.geometry import Polygon, LineString, MultiPolygon
+from shapely.ops import split
+from typing import List, Tuple, Dict
+import json
+
+class PaperState:
+    """Represents the current state of the origami paper."""
+
+    def __init__(self, size: float = 1.0):
+        # Start with a unit square
+        self.regions = [Polygon([(0,0), (size,0), (size,size), (0,size)])]
+        self.fold_history = []
+        self.crease_lines = []
+        self.crease_assignments = []  # 'M' or 'V'
+        self.crease_angles = []
+        self.layer_order = [0]  # Stack order of regions
+
+    def apply_fold(self, fold_line: LineString, angle: float, assignment: str) -> dict:
+        """
+        Apply a fold operation. Returns dict with validity info.
+        fold_line: Shapely LineString defining the fold axis
+        angle: fold angle in degrees (-180 to 180)
+        assignment: 'M' (mountain) or 'V' (valley)
+        """
+        result = {'valid': True, 'errors': []}
+
+        # 1. Split regions by fold line
+        new_regions = []
+        for region in self.regions:
+            if fold_line.intersects(region):
+                parts = split(region, fold_line)
+                new_regions.extend(parts.geoms)
+            else:
+                new_regions.append(region)
+
+        # 2. Determine which side folds (based on assignment)
+        folding_side = []
+        staying_side = []
+        for region in new_regions:
+            centroid = region.centroid
+            side = self._point_side(centroid, fold_line)
+            if side > 0:
+                folding_side.append(region)
+            else:
+                staying_side.append(region)
+
+        # 3. Reflect folding regions across fold line
+        reflected = [self._reflect_polygon(r, fold_line) for r in folding_side]
+
+        # 4. Update state
+        self.regions = staying_side + reflected
+        self.crease_lines.append(fold_line)
+        self.crease_assignments.append(assignment)
+        self.crease_angles.append(angle)
+        self.fold_history.append({
+            'line': list(fold_line.coords),
+            'angle': angle,
+            'assignment': assignment
+        })
+
+        # 5. Update layer order
+        self._update_layer_order(staying_side, reflected)
+
+        return result
+
+    def _reflect_polygon(self, poly: Polygon, line: LineString) -> Polygon:
+        """Reflect a polygon across a line."""
+        coords = list(poly.exterior.coords)
+        reflected_coords = [self._reflect_point(p, line) for p in coords]
+        return Polygon(reflected_coords)
+
+    def _reflect_point(self, point: tuple, line: LineString) -> tuple:
+        """Reflect a point across a line."""
+        p = np.array(point[:2])
+        l1 = np.array(line.coords[0])
+        l2 = np.array(line.coords[1])
+        d = l2 - l1
+        d = d / np.linalg.norm(d)
+        # Reflection formula: p' = p - 2(p-l1).n * n where n is normal to line
+        n = np.array([-d[1], d[0]])
+        v = p - l1
+        return tuple(p - 2 * np.dot(v, n) * n)
+
+    def _point_side(self, point, line: LineString) -> float:
+        """Returns positive if point is on left side of line, negative if right."""
+        p = np.array([point.x, point.y])
+        l1 = np.array(line.coords[0])
+        l2 = np.array(line.coords[1])
+        return float(np.cross(l2 - l1, p - l1))
+
+    def _update_layer_order(self, staying, reflected):
+        """Update the layer stacking order after a fold."""
+        self.layer_order = list(range(len(staying))) + \
+                          list(range(len(staying), len(staying) + len(reflected)))
+
+    def to_fold_json(self) -> dict:
+        """Export current state as FOLD format JSON."""
+        vertices = set()
+        for line in self.crease_lines:
+            for coord in line.coords:
+                vertices.add(tuple(round(c, 10) for c in coord))
+        # Add boundary vertices
+        for region in self.regions:
+            for coord in region.exterior.coords:
+                vertices.add(tuple(round(c, 10) for c in coord[:2]))
+
+        vertices = sorted(list(vertices))
+        vertex_map = {v: i for i, v in enumerate(vertices)}
+
+        edge_set = set()
+        edges_list = []
+        assignments_list = []
+        angles_list = []
+
+        # Add crease edges
+        for i, line in enumerate(self.crease_lines):
+            c = [tuple(round(x, 10) for x in coord) for coord in line.coords]
+            edge = tuple(sorted([vertex_map[c[0]], vertex_map[c[1]]]))
+            if edge not in edge_set:
+                edge_set.add(edge)
+                edges_list.append(list(edge))
+                assignments_list.append(self.crease_assignments[i])
+                angles_list.append(self.crease_angles[i])
+
+        return {
+            'vertices_coords': [list(v) for v in vertices],
+            'edges_vertices': edges_list,
+            'edges_assignment': assignments_list,
+            'edges_foldAngle': angles_list,
+        }
+
+
+class OrigamiVerifier:
+    """Verifiable reward functions based on origami theorems."""
+
+    @staticmethod
+    def check_kawasaki(state: PaperState) -> bool:
+        """Kawasaki's theorem: alternating sum of angles at each interior vertex = 0."""
+        fold_json = state.to_fold_json()
+        vertices = fold_json['vertices_coords']
+        edges = fold_json['edges_vertices']
+
+        for v_idx in range(len(vertices)):
+            v = vertices[v_idx]
+            incident_edges = [e for e in edges if v_idx in e]
+            if len(incident_edges) < 4:
+                continue  # Need degree-4+ for Kawasaki
+
+            # Calculate sector angles
+            angles = []
+            for e in incident_edges:
+                other = e[1] if e[0] == v_idx else e[0]
+                other_v = vertices[other]
+                angle = np.arctan2(other_v[1] - v[1], other_v[0] - v[0])
+                angles.append(angle)
+
+            angles.sort()
+            sector_angles = []
+            for i in range(len(angles) - 1):
+                sector_angles.append(angles[i+1] - angles[i])
+            sector_angles.append(2*np.pi - (angles[-1] - angles[0]))
+
+            # Kawasaki: alternating sum should be ~0
+            if len(sector_angles) >= 4:
+                alt_sum = sum(sector_angles[::2]) - sum(sector_angles[1::2])
+                if abs(alt_sum) > 0.01:
+                    return False
+        return True
+
+    @staticmethod
+    def check_maekawa(state: PaperState) -> bool:
+        """Maekawa's theorem: |M - V| = 2 at each interior vertex."""
+        fold_json = state.to_fold_json()
+        vertices = fold_json['vertices_coords']
+        edges = fold_json['edges_vertices']
+        assignments = fold_json['edges_assignment']
+
+        for v_idx in range(len(vertices)):
+            incident = [(i, e) for i, e in enumerate(edges) if v_idx in e]
+            m_count = sum(1 for i, _ in incident if i < len(assignments) and assignments[i] == 'M')
+            v_count = sum(1 for i, _ in incident if i < len(assignments) and assignments[i] == 'V')
+
+            if m_count + v_count >= 4:  # Interior vertex with folds
+                if abs(m_count - v_count) != 2:
+                    return False
+        return True
+
+    @staticmethod
+    def crease_pattern_similarity(state: PaperState, target_fold_json: dict) -> float:
+        """Compare current crease pattern to target. Returns 0-1 similarity."""
+        current = state.to_fold_json()
+
+        n_current = len(current.get('edges_vertices', []))
+        n_target = len(target_fold_json.get('edges_vertices', []))
+
+        if n_target == 0:
+            return 1.0 if n_current == 0 else 0.0
+
+        edge_count_sim = 1.0 - abs(n_current - n_target) / max(n_target, 1)
+        edge_count_sim = max(0, edge_count_sim)
+
+        current_assignments = current.get('edges_assignment', [])
+        target_assignments = target_fold_json.get('edges_assignment', [])
+
+        c_m = current_assignments.count('M')
+        c_v = current_assignments.count('V')
+        t_m = target_assignments.count('M')
+        t_v = target_assignments.count('V')
+
+        total = max(t_m + t_v, 1)
+        assign_sim = 1.0 - (abs(c_m - t_m) + abs(c_v - t_v)) / (2 * total)
+        assign_sim = max(0, assign_sim)
+
+        return 0.5 * edge_count_sim + 0.5 * assign_sim
+```
+
+---
+
+## OpenEnv Environment Wrapper
+
+```python
+# origami_env/server.py
+from openenv.core import Environment
+from paper_engine import PaperState, OrigamiVerifier
+from shapely.geometry import LineString
+import json
+
+class OrigamiEnvironment(Environment):
+
+    def __init__(self, targets_dir="targets/", max_steps=20):
+        self.targets_dir = targets_dir
+        self.max_steps = max_steps
+        self.paper = None
+        self.target = None
+        self.step_count = 0
+
+    async def reset(self, target_id=None):
+        self.paper = PaperState(size=1.0)
+        self.target = self._load_target(target_id)
+        self.step_count = 0
+        return self._get_observation()
+
+    async def step(self, action):
+        self.step_count += 1
+
+        # Parse action
+        try:
+            fold_line = LineString(action['fold_line'])
+            angle = action['fold_angle']
+            assignment = action['assignment']
+        except (KeyError, Exception):
+            reward = {'format': 0, 'total': -0.1}
+            return self._get_observation(), reward, False, {'error': 'parse_failed'}
+
+        # Apply fold
+        result = self.paper.apply_fold(fold_line, angle, assignment)
+
+        # Compute rewards
+        reward = self._compute_reward(result)
+
+        # Check termination
+        done = (
+            self.step_count >= self.max_steps or
+            reward.get('completion', 0) > 0
+        )
+
+        return self._get_observation(), reward, done, {}
+
+    async def state(self):
+        return {
+            'paper': self.paper.to_fold_json(),
+            'target': self.target,
+            'step': self.step_count,
+            'fold_history': self.paper.fold_history
+        }
+
+    def _compute_reward(self, fold_result):
+        rewards = {}
+        rewards['format'] = 1.0
+
+        kawasaki = OrigamiVerifier.check_kawasaki(self.paper)
+        maekawa = OrigamiVerifier.check_maekawa(self.paper)
+        rewards['validity'] = (float(kawasaki) + float(maekawa)) / 2.0
+
+        rewards['progress'] = OrigamiVerifier.crease_pattern_similarity(
+            self.paper, self.target
+        )
+
+        if rewards['progress'] > 0.95:
+            rewards['completion'] = 10.0
+
+        rewards['efficiency'] = -0.01
+
+        rewards['total'] = (
+            0.1 * rewards['format'] +
+            0.2 * rewards['validity'] +
+            0.6 * rewards['progress'] +
+            rewards.get('completion', 0) +
+            rewards['efficiency']
+        )
+        return rewards
+
+    def _get_observation(self):
+        return {
+            'paper_state': self.paper.to_fold_json(),
+            'target': self.target,
+            'step': self.step_count,
+            'instruction_history': [str(f['line']) for f in self.paper.fold_history]
+        }
+
+    def _load_target(self, target_id):
+        if target_id:
+            with open(f"{self.targets_dir}/{target_id}.fold") as f:
+                return json.load(f)
+        # Default: simple valley fold in half
+        return {
+            'vertices_coords': [[0,0], [1,0], [1,1], [0,1], [0,0.5], [1,0.5]],
+            'edges_vertices': [[0,1], [1,2], [2,3], [3,0], [4,5]],
+            'edges_assignment': ['B', 'B', 'B', 'B', 'V'],
+            'edges_foldAngle': [0, 0, 0, 0, -180],
+        }
+```
+
+---
+
+## Training Script (Unsloth GRPO)
+
+```python
+# train.py
+from unsloth import FastLanguageModel
+from trl import GRPOConfig, GRPOTrainer
+import torch
+
+# Load model
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name="unsloth/Qwen2.5-7B-Instruct",
+    max_seq_length=4096,
+    load_in_4bit=True,
+)
+
+# Add LoRA
+model = FastLanguageModel.get_peft_model(
+    model,
+    r=32,
+    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
+                     "gate_proj", "up_proj", "down_proj"],
+    lora_alpha=32,
+    lora_dropout=0,
+    use_gradient_checkpointing="unsloth",
+)
+
+# Reward function
+def origami_reward(completions, prompts):
+    """Compute rewards for a batch of completions."""
+    rewards = []
+    for completion in completions:
+        try:
+            action = parse_fold_action(completion)
+            paper = PaperState()
+            result = paper.apply_fold(action['fold_line'], action['angle'], action['assignment'])
+            r = compute_reward(paper, target)
+            rewards.append(r['total'])
+        except Exception:
+            rewards.append(-0.1)
+    return rewards
+
+# GRPO Config
+config = GRPOConfig(
+    output_dir="origami-grpo",
+    num_train_epochs=3,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    learning_rate=5e-6,
+    max_completion_length=512,
+    num_generations=8,
+    temperature=1.0,
+    logging_steps=1,
+)
+
+dataset = load_origami_prompts()
+
+trainer = GRPOTrainer(
+    model=model,
+    config=config,
+    train_dataset=dataset,
+    reward_funcs=[origami_reward],
+    tokenizer=tokenizer,
+)
+
+trainer.train()
+```
+
+---
+
+## Visualization (Demo Only — Not in Training Loop)
+
+### Options
+
+1. **Origami Simulator** — https://github.com/amandaghassaei/OrigamiSimulator — Three.js, accepts FOLD files, shows folding animation with strain visualization
+2. **PackCAD** — https://packcad.com/ — Web-based, SVG crease patterns, rigid folding simulation
+3. **Custom Three.js** — Simpler but more control
+
+### Demo UI Layout
+
+```
++----------------------+----------------------+
+|   Instruction Stream |   3D Fold Viewer     |
+|                      |                      |
+| Step 1: Valley fold  |   [Three.js canvas]  |
+| along center [OK]    |                      |
+|                      |   Paper animating    |
+| Step 2: Fold top     |   fold by fold       |
+| corners to center    |                      |
+|                      |                      |
++----------------------+----------------------+
+|   Reward Dashboard                          |
+|   Format:   ========== 1.0                  |
+|   Validity: ========.. 0.8                  |
+|   Progress: ======.... 0.6                  |
+|   Total:    =======... 0.72                 |
+|                                              |
+|   [Reward curve over training steps]         |
++----------------------------------------------+
+```
+
+---
+
+## Key Libraries and Resources
+
+| Tool | Purpose | Link |
+|------|---------|------|
+| OpenEnv | Environment framework | https://github.com/meta-pytorch/OpenEnv |
+| Unsloth | GRPO training | https://github.com/unslothai/unsloth |
+| OpenPipe ART | Multi-turn RL trainer | https://github.com/OpenPipe/ART |
+| FOLD format | Origami data structure | https://github.com/edemaine/fold |
+| Rabbit Ear | JS origami library | https://github.com/rabbit-ear/rabbit-ear |
+| Origami Simulator | 3D visualization | https://github.com/amandaghassaei/OrigamiSimulator |
+| PackCAD | Folding simulation | https://packcad.com/ |
+| Shapely | Python geometry | pip install shapely |
+| rigid-origami gym | Reference gym env | https://github.com/belalugaX/rigid-origami |
+
+### Papers to Cite
+
+- OrigamiSpace: https://arxiv.org/abs/2511.18450
+- GamiBench: https://arxiv.org/abs/2512.22207
+- SpatialThinker: https://arxiv.org/abs/2511.07403
+- Automating Rigid Origami Design: https://arxiv.org/abs/2211.13219
+- FOLD format spec: https://github.com/edemaine/fold/blob/main/doc/spec.md
+
+---
+
+## Priority Build Order
+
+1. **Python geometry engine** — PaperState class with fold operations and FOLD export
+2. **Verifier functions** — Kawasaki, Maekawa, similarity metrics
+3. **OpenEnv wrapper** — step/reset/state API
+4. **Simple targets** — Hand-create 5-10 Level 1-2 targets as .fold files
+5. **Training script** — Wire up Unsloth GRPO with reward function
+6. **Run training** — Even on small model, get reward curves
+7. **Three.js visualizer** — For demo only, not in training loop
+8. **Before/after demo** — Show base model vs trained model outputs
+9. **Polish presentation narrative**
+
+---
+
+## Narrative for Judges
+
+**The story arc:**
+
+1. "LLMs are great at text but terrible at spatial reasoning"
+2. "Origami is the perfect testbed — it's sequential, physical, and verifiable"
+3. "NeurIPS 2025 showed even GPT-5 fails at origami benchmarks, but nobody built a TRAINING environment"
+4. "We built OrigamiRL — the first multi-turn RL environment for origami instruction generation"
+5. "Our rewards come from math theorems, not vibes — Kawasaki's theorem is our unit test"
+6. "Watch the model go from generating paper-tearing nonsense to valid fold sequences"
+7. "This generalizes to any domain where LLMs need to output structured physical instructions"

env/environment.py

@@ -0,0 +1,243 @@
+import json
+import os
+import copy
+from pathlib import Path
+from typing import Optional
+
+from .paper_state import PaperState
+from .rewards import compute_reward, compute_terminal_reward, load_target, target_crease_edges
+from .prompts import (
+    code_as_policy_prompt,
+    step_level_prompt,
+    parse_fold_list,
+    parse_single_fold,
+)
+from .verifier import check_all_vertices
+
+
+TARGETS_DIR = Path(__file__).parent / 'targets'
+
+
+class OrigamiEnvironment:
+    """
+    OpenEnv-compatible origami crease pattern environment.
+
+    Supports two modes:
+    - code_as_policy: model outputs complete fold sequence, gets terminal reward
+    - step: model outputs one fold at a time, gets per-step reward
+    """
+
+    def __init__(
+        self,
+        mode: str = 'code_as_policy',  # 'code_as_policy' or 'step'
+        max_steps: int = 8,
+        targets_dir: Optional[str] = None,
+    ):
+        assert mode in ('code_as_policy', 'step'), f"Unknown mode: {mode}"
+        self.mode = mode
+        self.max_steps = max_steps
+        self.targets_dir = Path(targets_dir) if targets_dir else TARGETS_DIR
+
+        self.paper: Optional[PaperState] = None
+        self.target: Optional[dict] = None
+        self.target_name: Optional[str] = None
+        self.step_count: int = 0
+        self.last_reward: Optional[dict] = None
+
+        # Cache all available targets
+        self._targets = self._load_all_targets()
+
+    def _load_all_targets(self) -> dict[str, dict]:
+        targets = {}
+        for fold_file in self.targets_dir.glob('*.fold'):
+            with open(fold_file) as f:
+                targets[fold_file.stem] = json.load(f)
+        return targets
+
+    def available_targets(self) -> list[str]:
+        return sorted(self._targets.keys())
+
+    def reset(self, target_name: Optional[str] = None) -> dict:
+        """
+        Reset environment to start of a new episode.
+
+        Args:
+            target_name: name of target (stem of .fold file). If None, picks level-1 randomly.
+
+        Returns:
+            observation dict with 'prompt' key containing the LLM prompt string.
+        """
+        import random
+
+        if target_name:
+            assert target_name in self._targets, f"Unknown target: {target_name}"
+            self.target_name = target_name
+        else:
+            # Default to level-1 targets
+            level1 = [k for k, v in self._targets.items() if v.get('level', 1) == 1]
+            self.target_name = random.choice(level1 if level1 else list(self._targets.keys()))
+
+        self.target = self._targets[self.target_name]
+        self.paper = PaperState()
+        self.step_count = 0
+        self.last_reward = None
+
+        return self._get_observation()
+
+    def step(self, action) -> tuple[dict, dict, bool, dict]:
+        """
+        Execute an action.
+
+        In code_as_policy mode: action is a string (model completion with <folds> tags)
+            OR a list of fold dicts already parsed.
+        In step mode: action is a string (single fold JSON) or dict.
+
+        Returns:
+            (observation, reward, done, info)
+        """
+        if self.mode == 'code_as_policy':
+            return self._step_sequence(action)
+        else:
+            return self._step_single(action)
+
+    def _step_sequence(self, action) -> tuple[dict, dict, bool, dict]:
+        """Execute a complete fold sequence (code-as-policy mode)."""
+        # Parse action if it's a string
+        if isinstance(action, str):
+            try:
+                folds = parse_fold_list(action)
+            except ValueError as e:
+                bad_reward = {'format': 0.0, 'total': -0.1, 'error': str(e)}
+                return self._get_observation(), bad_reward, True, self._info()
+        else:
+            folds = action  # already a list of dicts
+
+        # Execute each fold sequentially
+        last_result = {'valid': True, 'anchored': True, 'new_vertices': [], 'errors': []}
+        for fold in folds:
+            try:
+                p1 = fold['from']
+                p2 = fold['to']
+                assignment = fold['assignment']
+            except (KeyError, TypeError) as e:
+                last_result = {'valid': False, 'anchored': False, 'new_vertices': [], 'errors': [str(e)]}
+                break
+
+            last_result = self.paper.add_crease(p1, p2, assignment)
+            self.step_count += 1
+            if not last_result['valid']:
+                break  # stop at first invalid fold, partial credit
+
+        reward = compute_terminal_reward(self.paper, self.target)
+        self.last_reward = reward
+        return self._get_observation(), reward, True, self._info()
+
+    def _step_single(self, action) -> tuple[dict, dict, bool, dict]:
+        """Execute a single fold (step mode)."""
+        if isinstance(action, str):
+            try:
+                fold = parse_single_fold(action)
+            except ValueError as e:
+                bad_reward = {'format': 0.0, 'total': -0.1, 'error': str(e)}
+                self.last_reward = bad_reward
+                done = self.step_count >= self.max_steps
+                return self._get_observation(), bad_reward, done, self._info()
+        else:
+            fold = action
+
+        try:
+            p1 = fold['from']
+            p2 = fold['to']
+            assignment = fold['assignment']
+        except (KeyError, TypeError) as e:
+            bad_reward = {'format': 0.0, 'total': -0.1, 'error': str(e)}
+            self.last_reward = bad_reward
+            done = self.step_count >= self.max_steps
+            return self._get_observation(), bad_reward, done, self._info()
+
+        result = self.paper.add_crease(p1, p2, assignment)
+        self.step_count += 1
+
+        reward = compute_reward(self.paper, result, self.target)
+        self.last_reward = reward
+
+        done = (
+            self.step_count >= self.max_steps or
+            reward.get('completion', 0) > 0
+        )
+        return self._get_observation(), reward, done, self._info()
+
+    def _get_observation(self) -> dict:
+        """Returns observation dict with the LLM prompt and raw state."""
+        if self.mode == 'code_as_policy':
+            prompt = code_as_policy_prompt(self.target, max_folds=self.max_steps)
+        else:
+            prompt = step_level_prompt(
+                target=self.target,
+                paper_state=self.paper,
+                step=self.step_count,
+                max_steps=self.max_steps,
+                last_reward=self.last_reward,
+            )
+
+        return {
+            'prompt': prompt,
+            'target_name': self.target_name,
+            'step': self.step_count,
+            'paper_fold_json': self.paper.graph.edges if self.paper else {},
+        }
+
+    def _info(self) -> dict:
+        """Returns diagnostic info dict for logging."""
+        if self.paper is None:
+            return {}
+
+        interior = self.paper.graph.interior_vertices()
+        vertex_scores = check_all_vertices(self.paper.graph)
+
+        return {
+            'local_foldability': (
+                vertex_scores['kawasaki'] == 1.0 and
+                vertex_scores['maekawa'] == 1.0
+            ),
+            'blb_satisfied': vertex_scores['blb'] == 1.0,
+            'global_foldability': 'not_checked',  # NP-complete (Bern-Hayes 1996)
+            'n_interior_vertices': len(interior),
+            'n_creases': len(self.paper.graph.crease_edges()),
+            'target_name': self.target_name,
+        }
+
+    def state(self) -> dict:
+        """Returns current environment state for logging/inspection."""
+        return {
+            'paper': {
+                'vertices': dict(self.paper.graph.vertices),
+                'edges': {
+                    k: v for k, v in self.paper.graph.edges.items()
+                    if v[2] in ('M', 'V')
+                },
+                'fold_history': self.paper.fold_history,
+            },
+            'target': self.target_name,
+            'step': self.step_count,
+            'mode': self.mode,
+        }
+
+    def close(self):
+        """Cleanup."""
+        pass
+
+    def clone(self) -> 'OrigamiEnvironment':
+        """Return a deep copy for parallel evaluation (used in GRPO)."""
+        new_env = OrigamiEnvironment(
+            mode=self.mode,
+            max_steps=self.max_steps,
+            targets_dir=str(self.targets_dir),
+        )
+        if self.paper is not None:
+            new_env.paper = copy.deepcopy(self.paper)
+        new_env.target = self.target
+        new_env.target_name = self.target_name
+        new_env.step_count = self.step_count
+        new_env.last_reward = self.last_reward
+        return new_env

env/graph.py

@@ -0,0 +1,117 @@
+import numpy as np
+from typing import Optional
+
+BOUNDARY_TOL = 1e-9
+VERTEX_TOL = 1e-9
+
+
+class CreaseGraph:
+    """
+    Planar graph representing an origami crease pattern on a unit square.
+
+    Vertices: points in [0,1]x[0,1], deduplicated by proximity.
+    Edges: segments between vertices, labeled M (mountain), V (valley), or B (boundary).
+    """
+
+    def __init__(self):
+        self.vertices: dict[int, tuple[float, float]] = {}
+        self.edges: dict[int, tuple[int, int, str]] = {}
+        self.vertex_edges: dict[int, list[int]] = {}
+        self._next_vertex_id: int = 0
+        self._next_edge_id: int = 0
+
+        corners = [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)]
+        for x, y in corners:
+            vid = self._next_vertex_id
+            self.vertices[vid] = (x, y)
+            self.vertex_edges[vid] = []
+            self._next_vertex_id += 1
+
+        boundary_pairs = [(0, 1), (1, 2), (2, 3), (3, 0)]
+        for v1, v2 in boundary_pairs:
+            eid = self._next_edge_id
+            self.edges[eid] = (v1, v2, 'B')
+            self.vertex_edges[v1].append(eid)
+            self.vertex_edges[v2].append(eid)
+            self._next_edge_id += 1
+
+    def add_vertex(self, x: float, y: float) -> int:
+        for vid, (vx, vy) in self.vertices.items():
+            if abs(vx - x) < VERTEX_TOL and abs(vy - y) < VERTEX_TOL:
+                return vid
+        vid = self._next_vertex_id
+        self.vertices[vid] = (float(x), float(y))
+        self.vertex_edges[vid] = []
+        self._next_vertex_id += 1
+        return vid
+
+    def add_edge(self, v1_id: int, v2_id: int, assignment: str) -> int:
+        pair = frozenset((v1_id, v2_id))
+        for eid, (ev1, ev2, _) in self.edges.items():
+            if frozenset((ev1, ev2)) == pair:
+                return eid
+        eid = self._next_edge_id
+        self.edges[eid] = (v1_id, v2_id, assignment)
+        self.vertex_edges[v1_id].append(eid)
+        self.vertex_edges[v2_id].append(eid)
+        self._next_edge_id += 1
+        return eid
+
+    def get_cyclic_edges(self, vertex_id: int) -> list[int]:
+        vx, vy = self.vertices[vertex_id]
+        edge_ids = self.vertex_edges[vertex_id]
+
+        def angle_of_edge(eid: int) -> float:
+            ev1, ev2, _ = self.edges[eid]
+            other_id = ev2 if ev1 == vertex_id else ev1
+            ox, oy = self.vertices[other_id]
+            return float(np.arctan2(oy - vy, ox - vx))
+
+        return sorted(edge_ids, key=angle_of_edge)
+
+    def interior_vertices(self) -> list[int]:
+        result = []
+        for vid, (x, y) in self.vertices.items():
+            if (
+                x > BOUNDARY_TOL
+                and x < 1.0 - BOUNDARY_TOL
+                and y > BOUNDARY_TOL
+                and y < 1.0 - BOUNDARY_TOL
+            ):
+                result.append(vid)
+        return result
+
+    def split_edge(self, edge_id: int, new_vertex_id: int) -> tuple[int, int]:
+        ev1, ev2, assignment = self.edges[edge_id]
+
+        del self.edges[edge_id]
+        if edge_id in self.vertex_edges[ev1]:
+            self.vertex_edges[ev1].remove(edge_id)
+        if edge_id in self.vertex_edges[ev2]:
+            self.vertex_edges[ev2].remove(edge_id)
+
+        eid1 = self._next_edge_id
+        self.edges[eid1] = (ev1, new_vertex_id, assignment)
+        self.vertex_edges[ev1].append(eid1)
+        self.vertex_edges[new_vertex_id].append(eid1)
+        self._next_edge_id += 1
+
+        eid2 = self._next_edge_id
+        self.edges[eid2] = (new_vertex_id, ev2, assignment)
+        self.vertex_edges[new_vertex_id].append(eid2)
+        self.vertex_edges[ev2].append(eid2)
+        self._next_edge_id += 1
+
+        return (eid1, eid2)
+
+    def crease_edges(self) -> list[int]:
+        return [eid for eid, (_, _, a) in self.edges.items() if a in ('M', 'V')]
+
+    def boundary_midpoints(self) -> list[tuple[float, float]]:
+        midpoints = []
+        for eid, (v1, v2, assignment) in self.edges.items():
+            if assignment == 'B':
+                x1, y1 = self.vertices[v1]
+                x2, y2 = self.vertices[v2]
+                midpoints.append(((x1 + x2) / 2.0, (y1 + y2) / 2.0))
+        return midpoints

env/paper_state.py

@@ -0,0 +1,150 @@
+import numpy as np
+from shapely.geometry import LineString, Point, Polygon
+from shapely.ops import unary_union
+from typing import Optional
+from .graph import CreaseGraph, VERTEX_TOL
+
+UNIT_SQUARE_CORNERS = [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)]
+
+_UNIT_SQUARE = Polygon(UNIT_SQUARE_CORNERS)
+
+
+class PaperState:
+    """
+    Represents the evolving crease pattern on a unit square [0,1]x[0,1].
+    Uses CreaseGraph for the underlying data structure.
+    """
+
+    def __init__(self):
+        self.graph = CreaseGraph()
+        self.fold_history: list[dict] = []
+
+    def anchor_points(self) -> list[tuple[float, float]]:
+        points: dict[tuple[float, float], None] = {}
+        for corner in UNIT_SQUARE_CORNERS:
+            points[corner] = None
+        for vid, (x, y) in self.graph.vertices.items():
+            points[(float(x), float(y))] = None
+        return list(points.keys())
+
+    def _is_anchor(self, pt: tuple[float, float]) -> bool:
+        px, py = pt
+        for ax, ay in self.anchor_points():
+            if abs(ax - px) < VERTEX_TOL and abs(ay - py) < VERTEX_TOL:
+                return True
+        return False
+
+    def add_crease(self, p1: list, p2: list, assignment: str) -> dict:
+        errors: list[str] = []
+
+        if assignment not in ('M', 'V'):
+            return {
+                'valid': False,
+                'anchored': False,
+                'new_vertices': [],
+                'errors': ['invalid_assignment'],
+            }
+
+        p1 = (float(p1[0]), float(p1[1]))
+        p2 = (float(p2[0]), float(p2[1]))
+
+        anchored = self._is_anchor(p1) and self._is_anchor(p2)
+
+        seg_len = np.hypot(p2[0] - p1[0], p2[1] - p1[1])
+        if seg_len < VERTEX_TOL:
+            errors.append('zero_length')
+            return {'valid': False, 'anchored': anchored, 'new_vertices': [], 'errors': errors}
+
+        new_line = LineString([p1, p2])
+
+        if not _UNIT_SQUARE.contains(new_line) and not _UNIT_SQUARE.boundary.contains(new_line):
+            clipped = new_line.intersection(_UNIT_SQUARE)
+            if clipped.is_empty:
+                errors.append('outside_bounds')
+                return {'valid': False, 'anchored': anchored, 'new_vertices': [], 'errors': errors}
+
+        intersection_points: list[tuple[float, float]] = []
+
+        for eid, (ev1, ev2, _) in list(self.graph.edges.items()):
+            ex1, ey1 = self.graph.vertices[ev1]
+            ex2, ey2 = self.graph.vertices[ev2]
+            existing_line = LineString([(ex1, ey1), (ex2, ey2)])
+            inter = new_line.intersection(existing_line)
+
+            if inter.is_empty:
+                continue
+
+            if inter.geom_type == 'Point':
+                ix, iy = inter.x, inter.y
+                ep1 = (ex1, ey1)
+                ep2 = (ex2, ey2)
+                if (
+                    abs(ix - ep1[0]) < VERTEX_TOL and abs(iy - ep1[1]) < VERTEX_TOL
+                    or abs(ix - ep2[0]) < VERTEX_TOL and abs(iy - ep2[1]) < VERTEX_TOL
+                ):
+                    continue
+                intersection_points.append((ix, iy))
+            # MultiPoint or LineString intersections (collinear) are skipped
+
+        new_vertex_coords: list[tuple[float, float]] = []
+        for ix, iy in intersection_points:
+            before = set(self.graph.vertices.keys())
+            vid = self.graph.add_vertex(ix, iy)
+            if vid not in before:
+                new_vertex_coords.append((ix, iy))
+
+            for eid in list(self.graph.edges.keys()):
+                if eid not in self.graph.edges:
+                    continue
+                ev1, ev2, _ = self.graph.edges[eid]
+                ex1, ey1 = self.graph.vertices[ev1]
+                ex2, ey2 = self.graph.vertices[ev2]
+                seg = LineString([(ex1, ey1), (ex2, ey2)])
+                pt = Point(ix, iy)
+                if seg.distance(pt) < VERTEX_TOL:
+                    if ev1 != vid and ev2 != vid:
+                        self.graph.split_edge(eid, vid)
+
+        v1_id = self.graph.add_vertex(p1[0], p1[1])
+        v2_id = self.graph.add_vertex(p2[0], p2[1])
+
+        waypoints = [p1] + sorted(
+            intersection_points,
+            key=lambda pt: np.hypot(pt[0] - p1[0], pt[1] - p1[1]),
+        ) + [p2]
+
+        waypoint_ids = []
+        for wp in waypoints:
+            wid = self.graph.add_vertex(wp[0], wp[1])
+            waypoint_ids.append(wid)
+
+        for i in range(len(waypoint_ids) - 1):
+            wa = waypoint_ids[i]
+            wb = waypoint_ids[i + 1]
+            if wa != wb:
+                self.graph.add_edge(wa, wb, assignment)
+
+        record = {
+            'p1': p1,
+            'p2': p2,
+            'assignment': assignment,
+            'anchored': anchored,
+            'new_vertices': new_vertex_coords,
+        }
+        self.fold_history.append(record)
+
+        return {
+            'valid': True,
+            'anchored': anchored,
+            'new_vertices': new_vertex_coords,
+            'errors': errors,
+        }
+
+    def crease_edges(self) -> list[dict]:
+        result = []
+        for eid in self.graph.crease_edges():
+            v1, v2, assignment = self.graph.edges[eid]
+            x1, y1 = self.graph.vertices[v1]
+            x2, y2 = self.graph.vertices[v2]
+            result.append({'v1': (x1, y1), 'v2': (x2, y2), 'assignment': assignment})
+        return result

env/prompts.py

@@ -0,0 +1,235 @@
+import json
+import re
+from typing import Optional
+
+_CORNERS = {(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)}
+_BOUNDARY_X = {0.0, 1.0}
+_BOUNDARY_Y = {0.0, 1.0}
+
+
+def _is_corner(x: float, y: float) -> bool:
+    return (round(x, 4), round(y, 4)) in _CORNERS
+
+
+def _is_boundary(x: float, y: float) -> bool:
+    return x in _BOUNDARY_X or y in _BOUNDARY_Y
+
+
+def format_target_for_prompt(target: dict) -> str:
+    vertices = target["vertices_coords"]
+    edges_v = target["edges_vertices"]
+    edges_a = target["edges_assignment"]
+
+    lines = []
+    for (v1, v2), assignment in zip(edges_v, edges_a):
+        if assignment not in ("M", "V"):
+            continue
+        x1, y1 = vertices[v1]
+        x2, y2 = vertices[v2]
+        label = "Mountain" if assignment == "M" else "Valley"
+        lines.append(
+            f"{label} fold: ({round(x1, 4)}, {round(y1, 4)}) -> ({round(x2, 4)}, {round(y2, 4)})"
+        )
+    return "\n".join(lines)
+
+
+def format_anchor_points(paper_state) -> str:
+    corners = []
+    boundary_pts = []
+    intersections = []
+
+    for x, y in paper_state.anchor_points():
+        rx, ry = round(x, 4), round(y, 4)
+        if _is_corner(rx, ry):
+            corners.append((rx, ry))
+        elif _is_boundary(rx, ry):
+            boundary_pts.append((rx, ry))
+        else:
+            intersections.append((rx, ry))
+
+    def fmt_pts(pts: list[tuple[float, float]]) -> str:
+        return "  ".join(f"({x},{y})" for x, y in pts)
+
+    lines = []
+    if corners:
+        lines.append(f"  Corners:       {fmt_pts(corners)}")
+    if boundary_pts:
+        lines.append(f"  Boundary pts:  {fmt_pts(boundary_pts)}")
+    if intersections:
+        lines.append(f"  Intersections: {fmt_pts(intersections)}")
+
+    return "\n".join(lines)
+
+
+def format_crease_history(paper_state) -> str:
+    history = paper_state.fold_history
+    if not history:
+        return "none"
+
+    lines = []
+    for i, fold in enumerate(history, 1):
+        p1, p2 = fold["p1"], fold["p2"]
+        assignment = fold["assignment"]
+        label = "Mountain" if assignment == "M" else "Valley"
+        x1, y1 = round(p1[0], 4), round(p1[1], 4)
+        x2, y2 = round(p2[0], 4), round(p2[1], 4)
+        lines.append(f"  {i}. {label} fold: ({x1}, {y1}) -> ({x2}, {y2})")
+
+    return "\n".join(lines)
+
+
+def format_reward_feedback(reward: Optional[dict]) -> str:
+    if not reward:
+        return "(no feedback yet)"
+
+    keys = ["kawasaki", "maekawa", "blb", "progress", "economy", "total"]
+    parts = []
+    for k in keys:
+        if k in reward:
+            parts.append(f"{k}={reward[k]:.2f}")
+
+    for k, v in reward.items():
+        if k not in keys:
+            parts.append(f"{k}={v:.2f}")
+
+    return "  " + "  ".join(parts)
+
+
+def code_as_policy_prompt(target: dict, max_folds: int = 8) -> str:
+    formatted_target = format_target_for_prompt(target)
+    return f"""You are an origami designer. Generate a fold sequence for a unit square [0,1]x[0,1].
+
+TARGET CREASE PATTERN:
+{formatted_target}
+
+RULES (must hold at every interior vertex):
+  - Kawasaki: alternating sector angles sum equally (each half = 180 degrees)
+  - Maekawa: |mountain_count - valley_count| = 2
+  - Big-Little-Big: folds bounding the smallest sector must have opposite types (one M, one V)
+
+INITIAL ANCHOR POINTS (valid fold endpoints — new ones appear when creases intersect):
+  Corners:      (0.0,0.0)  (1.0,0.0)  (1.0,1.0)  (0.0,1.0)
+  Midpoints:    (0.0,0.5)  (0.5,0.0)  (1.0,0.5)  (0.5,1.0)
+  Note: new anchor points are created at crease intersections.
+
+Output at most {max_folds} folds. Both endpoints must be valid anchor points.
+Output ONLY the JSON list, wrapped in <folds> tags:
+
+<folds>
+[
+  {{"instruction": "Describe the fold in plain English", "from": [x1, y1], "to": [x2, y2], "assignment": "V"}},
+  {{"instruction": "...", "from": [x1, y1], "to": [x2, y2], "assignment": "M"}}
+]
+</folds>"""
+
+
+def step_level_prompt(
+    target: dict,
+    paper_state,
+    step: int,
+    max_steps: int,
+    last_reward: Optional[dict] = None,
+) -> str:
+    formatted_target = format_target_for_prompt(target)
+    formatted_history = format_crease_history(paper_state)
+    formatted_anchors = format_anchor_points(paper_state)
+    formatted_reward = format_reward_feedback(last_reward)
+
+    return f"""You are an origami designer building a crease pattern step by step.
+
+TARGET:
+{formatted_target}
+
+CURRENT STATE (step {step} of {max_steps}):
+  Creases placed:
+{formatted_history}
+
+AVAILABLE ANCHOR POINTS:
+{formatted_anchors}
+
+LAST REWARD:
+{formatted_reward}
+
+Add the NEXT crease. Both endpoints must be listed anchor points above.
+Output ONLY valid JSON (no extra text):
+{{"instruction": "...", "from": [x1, y1], "to": [x2, y2], "assignment": "M" or "V"}}"""
+
+
+def parse_fold_list(completion: str) -> list[dict]:
+    match = re.search(r"<folds>(.*?)</folds>", completion, re.IGNORECASE | re.DOTALL)
+    if not match:
+        raise ValueError("No <folds>...</folds> tags found in completion")
+
+    raw = match.group(1).strip()
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Failed to parse JSON inside <folds> tags: {e}") from e
+
+    if not isinstance(data, list):
+        raise ValueError(f"Expected a JSON list inside <folds> tags, got {type(data).__name__}")
+
+    cleaned = []
+    for i, item in enumerate(data):
+        if not isinstance(item, dict):
+            raise ValueError(f"Fold {i} is not a dict: {item!r}")
+
+        for field in ("from", "to", "assignment"):
+            if field not in item:
+                raise ValueError(f"Fold {i} missing required field '{field}'")
+
+        from_pt = item["from"]
+        to_pt = item["to"]
+
+        if (
+            not isinstance(from_pt, list)
+            or len(from_pt) != 2
+            or not all(isinstance(v, (int, float)) for v in from_pt)
+        ):
+            raise ValueError(f"Fold {i} 'from' must be a list of 2 numbers, got {from_pt!r}")
+
+        if (
+            not isinstance(to_pt, list)
+            or len(to_pt) != 2
+            or not all(isinstance(v, (int, float)) for v in to_pt)
+        ):
+            raise ValueError(f"Fold {i} 'to' must be a list of 2 numbers, got {to_pt!r}")
+
+        if not isinstance(item["assignment"], str):
+            raise ValueError(f"Fold {i} 'assignment' must be a string")
+
+        cleaned.append(
+            {
+                "from": [float(from_pt[0]), float(from_pt[1])],
+                "to": [float(to_pt[0]), float(to_pt[1])],
+                "assignment": item["assignment"],
+                "instruction": item.get("instruction", ""),
+            }
+        )
+
+    return cleaned
+
+
+def parse_single_fold(completion: str) -> dict:
+    start = completion.find("{")
+    end = completion.rfind("}")
+
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError("No JSON object found in completion")
+
+    raw = completion[start : end + 1]
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Failed to parse JSON from completion: {e}") from e
+
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected a JSON object, got {type(data).__name__}")
+
+    for field in ("from", "to", "assignment"):
+        if field not in data:
+            raise ValueError(f"Missing required field '{field}' in fold JSON")
+
+    return data

env/rewards.py

@@ -0,0 +1,93 @@
+import json
+from .verifier import check_all_vertices, geometric_crease_coverage
+from .paper_state import PaperState
+
+
+def load_target(target_path: str) -> dict:
+    """Load a .fold target file and return it as a dict."""
+    with open(target_path) as f:
+        return json.load(f)
+
+
+def target_crease_edges(target: dict) -> list[dict]:
+    """
+    Extract crease edges from a FOLD target dict as list of
+    {'v1': (x1,y1), 'v2': (x2,y2), 'assignment': 'M'|'V'} dicts.
+    """
+    verts = target['vertices_coords']
+    result = []
+    for i, (v1_idx, v2_idx) in enumerate(target['edges_vertices']):
+        assignment = target['edges_assignment'][i]
+        if assignment in ('M', 'V'):
+            result.append({
+                'v1': tuple(verts[v1_idx]),
+                'v2': tuple(verts[v2_idx]),
+                'assignment': assignment,
+            })
+    return result
+
+
+def compute_reward(
+    state: PaperState,
+    action_result: dict,
+    target: dict,
+) -> dict:
+    """
+    Compute the full reward dict for a fold action.
+
+    Args:
+        state: current PaperState AFTER the action was applied
+        action_result: {'valid': bool, 'anchored': bool, 'new_vertices': list, 'errors': list}
+        target: FOLD target dict
+
+    Returns dict with keys:
+        format, anchored, kawasaki, maekawa, blb, progress, economy, completion, efficiency, total
+    """
+    r = {}
+
+    # Gate 1: format — did the action parse and apply?
+    r['format'] = 1.0 if action_result.get('valid', False) else 0.0
+    if not r['format']:
+        r['total'] = -0.1
+        return r
+
+    # Gate 2: anchoring — were endpoints valid anchor points?
+    r['anchored'] = 1.0 if action_result.get('anchored', False) else 0.3
+
+    # Vertex-level validity checks (all interior vertices)
+    vertex_scores = check_all_vertices(state.graph)
+    r['kawasaki'] = vertex_scores['kawasaki']
+    r['maekawa'] = vertex_scores['maekawa']
+    r['blb'] = vertex_scores['blb']
+
+    # Geometric progress
+    t_edges = target_crease_edges(target)
+    coverage, economy = geometric_crease_coverage(state, t_edges)
+    r['progress'] = coverage
+    r['economy'] = economy
+
+    # Completion bonus: high coverage + all vertex conditions satisfied
+    all_valid = (r['kawasaki'] == 1.0 and r['maekawa'] == 1.0 and r['blb'] == 1.0)
+    r['completion'] = 10.0 if (r['progress'] > 0.9 and all_valid) else 0.0
+
+    # Step cost
+    r['efficiency'] = -0.01
+
+    # Weighted total
+    r['total'] = (
+        0.05 * r['anchored'] +
+        0.08 * r['kawasaki'] +
+        0.07 * r['maekawa'] +
+        0.05 * r['blb'] +
+        0.45 * r['progress'] +
+        0.10 * r['economy'] +
+        r['completion'] +
+        r['efficiency']
+    )
+    return r
+
+
+def compute_terminal_reward(state: PaperState, target: dict) -> dict:
+    """Compute reward for the final state after a complete fold sequence."""
+    fake_result = {'valid': True, 'anchored': True, 'new_vertices': [], 'errors': []}
+    return compute_reward(state, fake_result, target)

env/targets/accordion_3h.fold

@@ -0,0 +1,67 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.0, 0.25],
+    [1.0, 0.25],
+    [0.0, 0.5],
+    [1.0, 0.5],
+    [0.0, 0.75],
+    [1.0, 0.75]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 5],
+    [5, 7],
+    [7, 9],
+    [9, 2],
+    [2, 3],
+    [3, 8],
+    [8, 6],
+    [6, 4],
+    [4, 0],
+    [4, 5],
+    [6, 7],
+    [8, 9]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "V",
+    "M",
+    "V"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180,
+    -180,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 5, 4],
+    [4, 5, 7, 6],
+    [6, 7, 9, 8],
+    [8, 9, 2, 3]
+  ],
+  "level": 3,
+  "description": "Three alternating horizontal folds at y=0.25 (valley), y=0.5 (mountain), y=0.75 (valley) forming an accordion"
+}

env/targets/accordion_4h.fold

@@ -0,0 +1,79 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.0, 0.2],
+    [1.0, 0.2],
+    [0.0, 0.4],
+    [1.0, 0.4],
+    [0.0, 0.6],
+    [1.0, 0.6],
+    [0.0, 0.8],
+    [1.0, 0.8]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 5],
+    [5, 7],
+    [7, 9],
+    [9, 11],
+    [11, 2],
+    [2, 3],
+    [3, 10],
+    [10, 8],
+    [8, 6],
+    [6, 4],
+    [4, 0],
+    [4, 5],
+    [6, 7],
+    [8, 9],
+    [10, 11]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "V",
+    "M",
+    "V",
+    "M"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180,
+    -180,
+    -180,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 5, 4],
+    [4, 5, 7, 6],
+    [6, 7, 9, 8],
+    [8, 9, 11, 10],
+    [10, 11, 2, 3]
+  ],
+  "level": 3,
+  "description": "Four alternating horizontal folds at y=0.2 (valley), y=0.4 (mountain), y=0.6 (valley), y=0.8 (mountain) forming an accordion"
+}

env/targets/diagonal_anti.fold

@@ -0,0 +1,35 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 2],
+    [2, 3],
+    [3, 0],
+    [1, 3]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "M"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 3],
+    [1, 2, 3]
+  ],
+  "level": 1,
+  "description": "One mountain fold along the anti-diagonal from (1,0) to (0,1)"
+}

env/targets/diagonal_main.fold

@@ -0,0 +1,35 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 2],
+    [2, 3],
+    [3, 0],
+    [0, 2]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "V"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 2],
+    [0, 2, 3]
+  ],
+  "level": 1,
+  "description": "One valley fold along the main diagonal from (0,0) to (1,1)"
+}

env/targets/half_horizontal.fold

@@ -0,0 +1,43 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.0, 0.5],
+    [1.0, 0.5]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 5],
+    [5, 2],
+    [2, 3],
+    [3, 4],
+    [4, 0],
+    [4, 5]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "V"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 5, 4],
+    [4, 5, 2, 3]
+  ],
+  "level": 1,
+  "description": "One valley fold along y=0.5, folding the paper in half horizontally"
+}

env/targets/half_vertical.fold

@@ -0,0 +1,43 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.5, 0.0],
+    [0.5, 1.0]
+  ],
+  "edges_vertices": [
+    [0, 4],
+    [4, 1],
+    [1, 2],
+    [2, 5],
+    [5, 3],
+    [3, 0],
+    [4, 5]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "M"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 4, 5, 3],
+    [4, 1, 2, 5]
+  ],
+  "level": 1,
+  "description": "One mountain fold along x=0.5, folding the paper in half vertically"
+}

env/targets/thirds_h.fold

@@ -0,0 +1,55 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.0, 0.3333333333333333],
+    [1.0, 0.3333333333333333],
+    [0.0, 0.6666666666666666],
+    [1.0, 0.6666666666666666]
+  ],
+  "edges_vertices": [
+    [0, 1],
+    [1, 5],
+    [5, 7],
+    [7, 2],
+    [2, 3],
+    [3, 6],
+    [6, 4],
+    [4, 0],
+    [4, 5],
+    [6, 7]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "V",
+    "V"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 1, 5, 4],
+    [4, 5, 7, 6],
+    [6, 7, 2, 3]
+  ],
+  "level": 2,
+  "description": "Two parallel valley folds at y=1/3 and y=2/3, dividing the paper into horizontal thirds"
+}

env/targets/thirds_v.fold

@@ -0,0 +1,55 @@
+{
+  "vertices_coords": [
+    [0.0, 0.0],
+    [1.0, 0.0],
+    [1.0, 1.0],
+    [0.0, 1.0],
+    [0.3333333333333333, 0.0],
+    [0.6666666666666666, 0.0],
+    [0.3333333333333333, 1.0],
+    [0.6666666666666666, 1.0]
+  ],
+  "edges_vertices": [
+    [0, 4],
+    [4, 5],
+    [5, 1],
+    [1, 2],
+    [2, 7],
+    [7, 6],
+    [6, 3],
+    [3, 0],
+    [4, 6],
+    [5, 7]
+  ],
+  "edges_assignment": [
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "B",
+    "M",
+    "M"
+  ],
+  "edges_foldAngle": [
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    -180,
+    -180
+  ],
+  "faces_vertices": [
+    [0, 4, 6, 3],
+    [4, 5, 7, 6],
+    [5, 1, 2, 7]
+  ],
+  "level": 2,
+  "description": "Two parallel mountain folds at x=1/3 and x=2/3, dividing the paper into vertical thirds"
+}

env/targets/validator.py

@@ -0,0 +1,119 @@
+"""
+Validates all .fold target files against origami theorems.
+Run directly: python -m env.targets.validator
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+from ..graph import CreaseGraph
+from ..verifier import check_kawasaki_at_vertex, check_maekawa_at_vertex, check_blb_at_vertex
+
+
+def build_graph_from_fold(fold_data: dict) -> CreaseGraph:
+    """
+    Reconstruct a CreaseGraph from a FOLD JSON dict.
+    Used to validate target files.
+    """
+    graph = CreaseGraph()
+
+    verts = fold_data['vertices_coords']
+    edges = fold_data['edges_vertices']
+    assignments = fold_data['edges_assignment']
+
+    # Map file vertex indices to graph vertex IDs
+    vert_map = {}
+    for i, (x, y) in enumerate(verts):
+        vid = graph.add_vertex(float(x), float(y))
+        vert_map[i] = vid
+
+    # Add edges (boundary edges from init may already exist, add_edge handles dedup)
+    for i, (v1_idx, v2_idx) in enumerate(edges):
+        v1_id = vert_map[v1_idx]
+        v2_id = vert_map[v2_idx]
+        assignment = assignments[i]
+        graph.add_edge(v1_id, v2_id, assignment)
+
+    return graph
+
+
+def validate_target(fold_path: str) -> dict:
+    """
+    Validate a single .fold target file.
+    Returns {'file': str, 'valid': bool, 'issues': list[str], 'interior_vertices': int}
+    """
+    with open(fold_path) as f:
+        fold_data = json.load(f)
+
+    issues = []
+
+    # Basic structure checks
+    required = ['vertices_coords', 'edges_vertices', 'edges_assignment', 'edges_foldAngle']
+    for field in required:
+        if field not in fold_data:
+            issues.append(f"Missing field: {field}")
+
+    if issues:
+        return {'file': os.path.basename(fold_path), 'valid': False, 'issues': issues, 'interior_vertices': -1}
+
+    n_edges = len(fold_data['edges_vertices'])
+    if len(fold_data['edges_assignment']) != n_edges:
+        issues.append("edges_assignment length mismatch")
+    if len(fold_data['edges_foldAngle']) != n_edges:
+        issues.append("edges_foldAngle length mismatch")
+
+    # Build graph and check theorems
+    graph = build_graph_from_fold(fold_data)
+    interior = graph.interior_vertices()
+
+    for v_id in interior:
+        ok, alt_sum = check_kawasaki_at_vertex(v_id, graph)
+        if not ok:
+            issues.append(f"Kawasaki violated at vertex {v_id} (alt_sum={alt_sum:.6f})")
+
+        if not check_maekawa_at_vertex(v_id, graph):
+            issues.append(f"Maekawa violated at vertex {v_id}")
+
+        blb_violations = check_blb_at_vertex(v_id, graph)
+        if blb_violations:
+            issues.append(f"BLB violated at vertex {v_id}: {blb_violations}")
+
+    return {
+        'file': os.path.basename(fold_path),
+        'valid': len(issues) == 0,
+        'issues': issues,
+        'interior_vertices': len(interior),
+    }
+
+
+def validate_all(targets_dir: str = None) -> bool:
+    """Validate all .fold files in the targets directory. Returns True if all pass."""
+    if targets_dir is None:
+        targets_dir = Path(__file__).parent
+
+    all_pass = True
+    fold_files = sorted(Path(targets_dir).glob('*.fold'))
+
+    if not fold_files:
+        print("No .fold files found")
+        return False
+
+    for fold_path in fold_files:
+        result = validate_target(str(fold_path))
+        status = "OK" if result['valid'] else "FAIL"
+        n_interior = result['interior_vertices']
+        print(f"  [{status}] {result['file']} — {n_interior} interior vertices")
+        if result['issues']:
+            for issue in result['issues']:
+                print(f"         ! {issue}")
+        if not result['valid']:
+            all_pass = False
+
+    return all_pass
+
+
+if __name__ == '__main__':
+    print("Validating targets...")
+    ok = validate_all()
+    sys.exit(0 if ok else 1)

env/targets/validator_check.py

@@ -0,0 +1,19 @@
+import json, sys, os
+
+targets_dir = "/Users/ianalin/Desktop/optigami/env/targets"
+for fname in os.listdir(targets_dir):
+    if not fname.endswith(".fold"):
+        continue
+    with open(os.path.join(targets_dir, fname)) as f:
+        d = json.load(f)
+    n_v = len(d["vertices_coords"])
+    n_e = len(d["edges_vertices"])
+    assert len(d["edges_assignment"]) == n_e, f"{fname}: assignment length mismatch"
+    assert len(d["edges_foldAngle"]) == n_e, f"{fname}: foldAngle length mismatch"
+    for e in d["edges_vertices"]:
+        assert e[0] < n_v and e[1] < n_v, f"{fname}: edge references invalid vertex"
+    for face in d["faces_vertices"]:
+        for vi in face:
+            assert vi < n_v, f"{fname}: face references invalid vertex"
+    creases = [i for i,a in enumerate(d["edges_assignment"]) if a in ('M','V')]
+    print(f"{fname}: {n_v} vertices, {n_e} edges, {len(creases)} creases, level={d.get('level','?')} OK")

env/verifier.py

@@ -0,0 +1,221 @@
+import numpy as np
+from .graph import CreaseGraph
+from .paper_state import PaperState
+
+
+def _compute_sector_angles(vertex_id: int, graph: CreaseGraph) -> list[float]:
+    """Compute consecutive sector angles (CCW) at a vertex from its cyclic edges."""
+    cyclic_edges = graph.get_cyclic_edges(vertex_id)
+    n = len(cyclic_edges)
+    vx, vy = graph.vertices[vertex_id]
+
+    angles = []
+    for eid in cyclic_edges:
+        ev1, ev2, _ = graph.edges[eid]
+        other_id = ev2 if ev1 == vertex_id else ev1
+        ox, oy = graph.vertices[other_id]
+        angles.append(np.arctan2(oy - vy, ox - vx))
+
+    sectors = []
+    for i in range(n):
+        diff = angles[(i + 1) % n] - angles[i]
+        if diff < 0:
+            diff += 2 * np.pi
+        if diff > 2 * np.pi:
+            diff -= 2 * np.pi
+        sectors.append(diff)
+
+    return sectors
+
+
+def check_kawasaki_at_vertex(vertex_id: int, graph: CreaseGraph) -> tuple[bool, float]:
+    """
+    Checks Kawasaki-Justin theorem at a single vertex.
+
+    Kawasaki: at an interior vertex with 2n creases, the alternating sum
+    of consecutive sector angles = 0.
+    Equivalently: sum(odd-indexed sectors) == sum(even-indexed sectors) == π.
+
+    Returns (satisfied: bool, |alternating_sum|: float).
+    Returns (True, 0.0) for vertices with degree < 4 (not an interior fold vertex yet).
+    Returns (False, inf) for odd-degree vertices (impossible for flat folds).
+    """
+    cyclic_edges = graph.get_cyclic_edges(vertex_id)
+    n = len(cyclic_edges)
+
+    if n % 2 != 0:
+        return (False, float('inf'))
+
+    if n < 4:
+        return (True, 0.0)
+
+    sectors = _compute_sector_angles(vertex_id, graph)
+    alt_sum = sum(s * ((-1) ** i) for i, s in enumerate(sectors))
+    return (abs(alt_sum) < 1e-9, abs(alt_sum))
+
+
+def check_maekawa_at_vertex(vertex_id: int, graph: CreaseGraph) -> bool:
+    """
+    Checks Maekawa-Justin theorem at a single vertex.
+
+    Maekawa: |M - V| == 2 where M, V are counts of mountain/valley fold edges
+    at the vertex. BOUNDARY edges ('B') are NOT counted.
+
+    Returns True if satisfied or if vertex has fewer than 4 fold edges (not yet active).
+    """
+    edge_ids = graph.vertex_edges[vertex_id]
+    fold_edges = [
+        eid for eid in edge_ids
+        if graph.edges[eid][2] in ('M', 'V')
+    ]
+
+    if len(fold_edges) < 4:
+        return True
+
+    m_count = sum(1 for eid in fold_edges if graph.edges[eid][2] == 'M')
+    v_count = sum(1 for eid in fold_edges if graph.edges[eid][2] == 'V')
+    return abs(m_count - v_count) == 2
+
+
+def check_blb_at_vertex(vertex_id: int, graph: CreaseGraph) -> list[tuple[int, int]]:
+    """
+    Checks Big-Little-Big lemma at a single vertex.
+
+    BLB: if sector angle i is a strict local minimum (smaller than both neighbors),
+    the fold edges bounding that sector must have OPPOSITE MV assignments.
+
+    Returns list of (edge_a_id, edge_b_id) pairs where BLB is violated.
+    Empty list = no violations.
+    """
+    cyclic_edges = graph.get_cyclic_edges(vertex_id)
+    n = len(cyclic_edges)
+
+    if n < 4:
+        return []
+
+    sectors = _compute_sector_angles(vertex_id, graph)
+    violations = []
+
+    for i in range(n):
+        prev_sector = sectors[(i - 1) % n]
+        next_sector = sectors[(i + 1) % n]
+
+        if sectors[i] < prev_sector and sectors[i] < next_sector:
+            edge_a = cyclic_edges[i]
+            edge_b = cyclic_edges[(i + 1) % n]
+
+            assign_a = graph.edges[edge_a][2]
+            assign_b = graph.edges[edge_b][2]
+
+            if assign_a in ('M', 'V') and assign_b in ('M', 'V'):
+                if assign_a == assign_b:
+                    violations.append((edge_a, edge_b))
+
+    return violations
+
+
+def _angle_diff(a1: float, a2: float) -> float:
+    """Minimum angle difference between two directed lines (considering 180° symmetry)."""
+    diff = abs(a1 - a2) % np.pi
+    return min(diff, np.pi - diff)
+
+
+def geometric_crease_coverage(
+    state: PaperState,
+    target_edges: list[dict],
+    tol_pos: float = 0.05,
+    tol_angle_deg: float = 5.0,
+) -> tuple[float, float]:
+    """
+    Computes how well the current crease pattern matches the target.
+
+    Args:
+        target_edges: list of {'v1': (x1,y1), 'v2': (x2,y2), 'assignment': 'M'|'V'}
+
+    Returns:
+        (coverage, economy)
+        coverage: fraction of target creases matched [0, 1]
+        economy: penalty for excess creases [0, 1], 1.0 = no excess
+    """
+    current_edges = state.crease_edges()
+    tol_angle_rad = np.deg2rad(tol_angle_deg)
+
+    matched = 0
+    for target in target_edges:
+        tx1, ty1 = target['v1']
+        tx2, ty2 = target['v2']
+        t_mid = ((tx1 + tx2) / 2.0, (ty1 + ty2) / 2.0)
+        t_angle = np.arctan2(ty2 - ty1, tx2 - tx1)
+
+        for current in current_edges:
+            cx1, cy1 = current['v1']
+            cx2, cy2 = current['v2']
+            c_mid = ((cx1 + cx2) / 2.0, (cy1 + cy2) / 2.0)
+            c_angle = np.arctan2(cy2 - cy1, cx2 - cx1)
+
+            mid_dist = np.hypot(c_mid[0] - t_mid[0], c_mid[1] - t_mid[1])
+            angle_distance = _angle_diff(c_angle, t_angle)
+
+            if mid_dist <= tol_pos and angle_distance <= tol_angle_rad:
+                matched += 1
+                break
+
+    coverage = matched / max(len(target_edges), 1)
+    n_excess = max(0, len(current_edges) - len(target_edges))
+    economy = max(0.0, 1.0 - n_excess / max(len(target_edges), 1))
+    return (coverage, economy)
+
+
+def check_all_vertices(graph: CreaseGraph) -> dict:
+    """
+    Run all vertex-level checks on every interior vertex.
+
+    Returns dict with:
+        'kawasaki': float  # fraction of interior vertices passing Kawasaki [0,1]
+        'maekawa': float   # fraction passing Maekawa [0,1]
+        'blb': float       # fraction with no BLB violations [0,1]
+        'n_interior': int  # number of interior vertices checked
+        'per_vertex': list[dict]  # per-vertex details
+    """
+    interior = graph.interior_vertices()
+
+    if not interior:
+        return {
+            'kawasaki': 1.0,
+            'maekawa': 1.0,
+            'blb': 1.0,
+            'n_interior': 0,
+            'per_vertex': [],
+        }
+
+    per_vertex = []
+    kaw_pass = 0
+    mae_pass = 0
+    blb_pass = 0
+
+    for vid in interior:
+        kaw_ok, kaw_val = check_kawasaki_at_vertex(vid, graph)
+        mae_ok = check_maekawa_at_vertex(vid, graph)
+        blb_violations = check_blb_at_vertex(vid, graph)
+        blb_ok = len(blb_violations) == 0
+
+        kaw_pass += int(kaw_ok)
+        mae_pass += int(mae_ok)
+        blb_pass += int(blb_ok)
+
+        per_vertex.append({
+            'vertex_id': vid,
+            'kawasaki_ok': kaw_ok,
+            'kawasaki_error': kaw_val,
+            'maekawa_ok': mae_ok,
+            'blb_violations': blb_violations,
+        })
+
+    n = len(interior)
+    return {
+        'kawasaki': kaw_pass / n,
+        'maekawa': mae_pass / n,
+        'blb': blb_pass / n,
+        'n_interior': n,
+        'per_vertex': per_vertex,
+    }

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: optigami
+type: space
+runtime: fastapi
+app: openenv_server.app:app
+port: 8000

openenv_runtime/__init__.py

@@ -0,0 +1,11 @@
+"""OpenEnv integration runtime for Optigami."""
+
+from .environment import OpenEnvOrigamiEnvironment
+from .models import OrigamiAction, OrigamiObservation, OrigamiState
+
+__all__ = [
+    "OpenEnvOrigamiEnvironment",
+    "OrigamiAction",
+    "OrigamiObservation",
+    "OrigamiState",
+]

openenv_runtime/environment.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from openenv.core.env_server.interfaces import Environment
+
+from env.environment import OrigamiEnvironment
+
+from .models import OrigamiAction, OrigamiObservation, OrigamiState
+
+
+class OpenEnvOrigamiEnvironment(Environment[OrigamiAction, OrigamiObservation, OrigamiState]):
+    """OpenEnv adapter over the existing OrigamiEnvironment implementation."""
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        default_mode: str = "step",
+        max_steps: int = 8,
+        targets_dir: Optional[str] = None,
+    ):
+        super().__init__()
+        self.default_mode = default_mode
+        self.max_steps = max_steps
+        self.targets_dir = targets_dir
+        self._env: Optional[OrigamiEnvironment] = None
+        self._episode_id: Optional[str] = None
+
+    def _new_env(self, mode: Optional[str] = None) -> OrigamiEnvironment:
+        return OrigamiEnvironment(
+            mode=mode or self.default_mode,
+            max_steps=self.max_steps,
+            targets_dir=self.targets_dir,
+        )
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> OrigamiObservation:
+        del seed  # deterministic seed plumbing can be added later
+
+        mode = kwargs.get("mode", self.default_mode)
+        target_name = kwargs.get("target_name")
+
+        self._env = self._new_env(mode=mode)
+        self._episode_id = episode_id
+        obs_dict = self._env.reset(target_name=target_name)
+
+        return OrigamiObservation(
+            done=False,
+            reward=None,
+            metadata={"available_targets": self._env.available_targets()},
+            prompt=obs_dict.get("prompt", ""),
+            target_name=obs_dict.get("target_name"),
+            step=obs_dict.get("step", 0),
+            paper_state=self._paper_state_snapshot(),
+            info=self._env._info(),
+            reward_components={},
+        )
+
+    def step(
+        self,
+        action: OrigamiAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> OrigamiObservation:
+        del timeout_s, kwargs
+
+        if self._env is None:
+            self.reset(target_name=action.target_name)
+
+        assert self._env is not None
+
+        if action.target_name and action.target_name != self._env.target_name:
+            self.reset(target_name=action.target_name, mode=self._env.mode)
+
+        try:
+            if action.mode == "sequence":
+                if not action.completion:
+                    return self._error_observation("sequence mode requires completion")
+
+                seq_env = self._new_env(mode="code_as_policy")
+                seq_env.reset(target_name=self._env.target_name)
+                obs_dict, reward_dict, done, info = seq_env.step(action.completion)
+                self._env = seq_env
+            else:
+                if action.fold is not None:
+                    fold_payload = {
+                        "from": list(action.fold.from_point),
+                        "to": list(action.fold.to_point),
+                        "assignment": action.fold.assignment,
+                        "instruction": action.fold.instruction,
+                    }
+                    env_action: Any = fold_payload
+                elif action.completion:
+                    env_action = action.completion
+                else:
+                    return self._error_observation("single mode requires fold or completion")
+
+                obs_dict, reward_dict, done, info = self._env.step(env_action)
+
+            total = reward_dict.get("total") if isinstance(reward_dict, dict) else None
+            return OrigamiObservation(
+                done=bool(done),
+                reward=float(total) if isinstance(total, (int, float)) else None,
+                metadata={"target_name": self._env.target_name},
+                prompt=obs_dict.get("prompt", ""),
+                target_name=obs_dict.get("target_name", self._env.target_name),
+                step=obs_dict.get("step", self._env.step_count),
+                paper_state=self._paper_state_snapshot(),
+                info=info or {},
+                reward_components=reward_dict or {},
+            )
+        except Exception as exc:  # pragma: no cover - defensive path
+            return self._error_observation(str(exc))
+
+    @property
+    def state(self) -> OrigamiState:
+        if self._env is None:
+            tmp_env = self._new_env(mode=self.default_mode)
+            return OrigamiState(
+                episode_id=self._episode_id,
+                step_count=0,
+                mode=tmp_env.mode,
+                target_name=None,
+                paper={},
+                last_reward={},
+                available_targets=tmp_env.available_targets(),
+            )
+
+        env_state = self._env.state()
+        return OrigamiState(
+            episode_id=self._episode_id,
+            step_count=env_state.get("step", self._env.step_count),
+            mode=env_state.get("mode", self._env.mode),
+            target_name=env_state.get("target", self._env.target_name),
+            paper=env_state.get("paper", {}),
+            last_reward=self._env.last_reward or {},
+            available_targets=self._env.available_targets(),
+        )
+
+    def close(self) -> None:
+        if self._env is not None:
+            self._env.close()
+            self._env = None
+
+    def _paper_state_snapshot(self) -> dict[str, Any]:
+        if self._env is None or self._env.paper is None:
+            return {"vertices": {}, "edges": [], "anchor_points": []}
+
+        graph = self._env.paper.graph
+        return {
+            "vertices": {str(k): [float(v[0]), float(v[1])] for k, v in graph.vertices.items()},
+            "edges": [
+                {
+                    "id": int(eid),
+                    "v1": [float(graph.vertices[v1][0]), float(graph.vertices[v1][1])],
+                    "v2": [float(graph.vertices[v2][0]), float(graph.vertices[v2][1])],
+                    "assignment": assignment,
+                }
+                for eid, (v1, v2, assignment) in graph.edges.items()
+            ],
+            "anchor_points": [
+                [float(x), float(y)] for (x, y) in self._env.paper.anchor_points()
+            ],
+        }
+
+    def _error_observation(self, message: str) -> OrigamiObservation:
+        return OrigamiObservation(
+            done=False,
+            reward=-0.1,
+            metadata={"error": True},
+            prompt="",
+            target_name=self._env.target_name if self._env else None,
+            step=self._env.step_count if self._env else 0,
+            paper_state=self._paper_state_snapshot(),
+            info=self._env._info() if self._env else {},
+            reward_components={"format": 0.0, "total": -0.1, "error": message},
+            error=message,
+        )

openenv_runtime/models.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from openenv.core.env_server.types import Action, Observation, State
+
+
+class OrigamiFold(BaseModel):
+    """Single fold action payload for step-level execution."""
+
+    from_point: list[float] = Field(..., description="Fold line start [x, y]")
+    to_point: list[float] = Field(..., description="Fold line end [x, y]")
+    assignment: Literal["M", "V"] = Field(..., description="Mountain or valley")
+    instruction: str = Field(default="", description="Optional natural language instruction")
+
+    @field_validator("from_point", "to_point")
+    @classmethod
+    def _validate_point(cls, point: list[float]) -> list[float]:
+        if len(point) != 2:
+            raise ValueError("Point must contain exactly 2 coordinates")
+        return [float(point[0]), float(point[1])]
+
+
+class OrigamiAction(Action):
+    """
+    OpenEnv action for Optigami.
+
+    Modes:
+    - single: execute one fold (pass `fold` or JSON `completion` for a single-fold object)
+    - sequence: execute a full <folds>[...]</folds> completion in one step
+    """
+
+    mode: Literal["single", "sequence"] = Field(default="single")
+    fold: Optional[OrigamiFold] = Field(default=None)
+    completion: Optional[str] = Field(default=None)
+    target_name: Optional[str] = Field(
+        default=None,
+        description="Optional target override; reset to this target before stepping",
+    )
+
+
+class OrigamiObservation(Observation):
+    """OpenEnv observation payload returned by Optigami."""
+
+    prompt: str = Field(default="")
+    target_name: Optional[str] = Field(default=None)
+    step: int = Field(default=0)
+    paper_state: dict[str, Any] = Field(default_factory=dict)
+    info: dict[str, Any] = Field(default_factory=dict)
+    reward_components: dict[str, float | int | str] = Field(default_factory=dict)
+    error: Optional[str] = Field(default=None)
+
+
+class OrigamiState(State):
+    """OpenEnv state payload for Optigami."""
+
+    mode: str = Field(default="step")
+    target_name: Optional[str] = Field(default=None)
+    paper: dict[str, Any] = Field(default_factory=dict)
+    last_reward: dict[str, Any] = Field(default_factory=dict)
+    available_targets: list[str] = Field(default_factory=list)

openenv_server/__init__.py

@@ -0,0 +1 @@
+"""OpenEnv FastAPI app package."""

openenv_server/app.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from openenv.core.env_server.http_server import create_app
+
+from openenv_runtime.environment import OpenEnvOrigamiEnvironment
+from openenv_runtime.models import OrigamiAction, OrigamiObservation
+
+
+app = create_app(
+    env=lambda: OpenEnvOrigamiEnvironment(),
+    action_cls=OrigamiAction,
+    observation_cls=OrigamiObservation,
+    env_name="optigami",
+)

plans/implementation_plan.md

@@ -0,0 +1,485 @@
+# Optigami — Implementation Plan
+
+> Derived from handoff doc critique, origami math/physics research, and plan review.
+> Last updated: 2026-03-07
+
+---
+
+## Resolved Architectural Decisions
+
+### 1. Code-as-policy for training, step-level for demo
+
+GRPO samples N completions for a fixed prompt, evaluates each independently, computes group advantages. That maps cleanly to **code-as-policy**: the model outputs a complete fold sequence as a JSON list, the environment executes it sequentially, terminal reward is computed once.
+
+Step-level breaks GRPO's assumption: at step k, the prompt is conditioned on prior steps which differ across rollouts, so you're no longer comparing N completions to the same situation.
+
+**Resolution:** Training is code-as-policy (full sequence → single reward). Demo is step-by-step (one fold at a time with live feedback). Same environment, different prompt wrapper. Same model at inference — you just prompt it one fold at a time for the demo.
+
+### 2. 2D crease pattern is Phase 1, engineering metrics are Phase 2
+
+**Phase 1 (hackathon MVP):** Build the crease pattern graph, check local foldability, use geometric coverage as progress proxy. Self-contained, can show reward improvement.
+
+**Phase 2 (if time permits):** Apply fold angles to compute the 3D folded state, compute deployment ratio and bounding box. These become the primary reward, with crease coverage as scaffolding. This is where the "model discovers Miura-ori" story lives.
+
+If the deadline forces a cut, Phase 1 ships and Phase 2 is explicitly called out as the next step.
+
+### 3. Scope to local flat-foldability (NP-hardness acknowledged)
+
+Global flat-foldability (layer ordering) is NP-complete (Bern-Hayes 1996). We target **local flat-foldability** at each vertex, which is polynomial. This is a feature, not a limitation — the pitch: "our rewards check the conditions every origami designer verifies. Global layer ordering is provably NP-complete."
+
+### 4. Symmetry masking is a noted risk
+
+For Level 1-2 targets the anchor set is small (≤8 points), manageable. For Level 3+, intersection vertices accumulate to 15-20+ points, giving O(300+) candidate fold lines. The unit square has dihedral-4 symmetry (4 rotations + 4 reflections). For Level 3+, if training shows no convergence after 500 steps, add explicit symmetry-based action pruning.
+
+---
+
+## File Structure
+
+```
+optigami/
+  env/
+    __init__.py
+    graph.py            # CreaseGraph: vertices, edges, cyclic ordering
+    paper_state.py      # PaperState using CreaseGraph, add_crease
+    verifier.py         # Kawasaki, Maekawa, BLB, coverage, deployment ratio
+    rewards.py          # compute_reward (Phase 1 + Phase 2 extension)
+    environment.py      # OpenEnv wrapper, code-as-policy and step modes
+    prompts.py          # LLM observation formatting
+    fold_engine.py      # Phase 2: apply fold angles, compute 3D bounding box
+    targets/
+      validator.py      # crimp-check all .fold files before training
+      half_horizontal.fold
+      half_vertical.fold
+      diagonal.fold
+      cross_fold.fold
+      x_fold.fold
+      pinwheel_base.fold
+      preliminary_base.fold
+      fish_base.fold
+  train.py
+  requirements.txt
+  src/                  # React demo visualizer (existing)
+  plans/
+    implementation_plan.md
+```
+
+---
+
+## Phase 1: CreaseGraph (`env/graph.py`)
+
+Everything builds on this. Get it right first.
+
+**Data:**
+- `vertices`: `dict[vertex_id → (x, y)]`
+- `edges`: `dict[edge_id → (v1, v2, assignment)]` where assignment ∈ `{M, V, B}`
+- `vertex_edges`: `dict[vertex_id → [edge_ids]]`
+
+**Key operations:**
+- `add_vertex(x, y, tol=1e-9)` — deduplicated by proximity
+- `add_edge(v1, v2, assignment)` — no duplicates
+- `get_cyclic_edges(vertex_id)` — incident edge IDs sorted by angle of the other endpoint around the vertex (the cyclic order Kawasaki requires)
+- `interior_vertices()` — vertices not on the unit square boundary
+- `split_edge(edge_id, new_vertex_id)` — splits an edge at a vertex, used when a new crease intersects an existing one
+
+**`add_crease(p1, p2, assignment)` in `PaperState`:**
+1. Validate both endpoints are in the anchor set (within tolerance)
+2. Find all intersections with existing edges
+3. Add intersection vertices and split existing edges at them
+4. Add the new crease edge(s) (possibly split by intersections)
+5. Return `{valid, anchored, new_vertices, errors}`
+
+**Anchor point set** (grows as creases are added):
+- Boundary corners: `(0,0), (1,0), (1,1), (0,1)`
+- Boundary midpoints of any existing boundary edge
+- All crease-crease intersection vertices
+- Midpoints of existing crease edges
+
+---
+
+## Phase 2: Verifiers (`env/verifier.py`)
+
+### Even-degree fast-fail
+
+```python
+def has_even_degree(vertex_id, graph) -> bool:
+    return len(graph.get_cyclic_edges(vertex_id)) % 2 == 0
+```
+
+Runs before Kawasaki. Odd-degree interior vertices are impossible — short-circuit immediately.
+
+### Kawasaki-Justin
+
+Sector angles must be computed in **cyclic angular order** around each vertex — not by magnitude, not arbitrarily. The handoff's sorted-angle approach was wrong; cyclic order is recovered by sorting incident edge directions by `arctan2`.
+
+```python
+def check_kawasaki_at_vertex(vertex_id, graph) -> tuple[bool, float]:
+    cyclic_edges = graph.get_cyclic_edges(vertex_id)  # sorted by angle
+    n = len(cyclic_edges)
+    if n % 2 != 0:
+        return False, float('inf')
+    if n < 4:
+        return True, 0.0  # boundary vertex, not an interior fold vertex
+
+    v = graph.vertices[vertex_id]
+    angles = []
+    for eid in cyclic_edges:
+        v1, v2, _ = graph.edges[eid]
+        other = v2 if v1 == vertex_id else v1
+        other_pos = graph.vertices[other]
+        angles.append(np.arctan2(other_pos[1] - v[1], other_pos[0] - v[0]))
+    # angles is already in cyclic order (cyclic_edges sorted by angle)
+
+    sectors = []
+    for i in range(n):
+        diff = angles[(i+1) % n] - angles[i]
+        if diff < 0:
+            diff += 2 * np.pi
+        sectors.append(diff)
+
+    alt_sum = sum(s * ((-1)**i) for i, s in enumerate(sectors))
+    return abs(alt_sum) < 1e-9, abs(alt_sum)
+```
+
+### Maekawa-Justin
+
+Boundary edges (`B`) must not be counted — only fold edges (`M`, `V`). The handoff counted boundary edges, which breaks Maekawa for any crease touching the paper edge.
+
+```python
+def check_maekawa_at_vertex(vertex_id, graph) -> bool:
+    fold_edges = [eid for eid in graph.vertex_edges[vertex_id]
+                  if graph.edges[eid][2] in ('M', 'V')]
+    if len(fold_edges) < 4:
+        return True  # not an interior fold vertex yet
+    M = sum(1 for eid in fold_edges if graph.edges[eid][2] == 'M')
+    V = len(fold_edges) - M
+    return abs(M - V) == 2
+```
+
+### Big-Little-Big (BLB)
+
+At any interior vertex, if a sector angle is a strict local minimum, the two crease lines bounding that sector must have **opposite MV parity**. This is the key pruning rule between Maekawa and layer-ordering — a pattern can satisfy Maekawa while violating BLB, meaning no valid layer ordering exists.
+
+```python
+def check_blb_at_vertex(vertex_id, graph) -> list[tuple]:
+    """Returns list of (edge_a, edge_b) pairs where BLB is violated."""
+    cyclic_edges = graph.get_cyclic_edges(vertex_id)
+    n = len(cyclic_edges)
+    if n < 4:
+        return []
+    sectors = _compute_sectors(vertex_id, cyclic_edges, graph)
+    violations = []
+    for i in range(n):
+        prev_s = sectors[(i-1) % n]
+        next_s = sectors[(i+1) % n]
+        if sectors[i] < prev_s and sectors[i] < next_s:  # strict local min
+            left_eid = cyclic_edges[i]
+            right_eid = cyclic_edges[(i+1) % n]
+            a_left = graph.edges[left_eid][2]
+            a_right = graph.edges[right_eid][2]
+            if a_left in ('M', 'V') and a_right in ('M', 'V') and a_left == a_right:
+                violations.append((left_eid, right_eid))
+    return violations
+```
+
+### Geometric Coverage (with excess penalty)
+
+One-sided coverage alone rewards placing target creases but doesn't penalize surplus creases. Both are returned separately so the reward function can weight them independently.
+
+```python
+def geometric_coverage(state, target_edges, tol_pos=0.05, tol_angle=5.0) -> tuple[float, float]:
+    """
+    Returns (coverage, economy).
+    coverage: fraction of target creases matched by current creases [0, 1]
+    economy:  penalty for excess creases [0, 1], 1.0 = no excess
+    """
+    matched = 0
+    for t_edge in target_edges:
+        for c_edge in state.crease_edges():
+            if _edges_match(t_edge, c_edge, tol_pos, tol_angle):
+                matched += 1
+                break
+    n_target = max(len(target_edges), 1)
+    n_current = len(state.crease_edges())
+    coverage = matched / n_target
+    economy = max(0.0, 1.0 - max(0, n_current - n_target) / n_target)
+    return coverage, economy
+```
+
+---
+
+## Phase 3: Reward Function (`env/rewards.py`)
+
+### Phase 1 reward
+
+Single consistent definition. `progress` carries 45% — it's the only signal with real geometric content at every step. Validity signals split 20% total. Economy penalizes excess creases.
+
+```python
+def compute_reward_phase1(state, action_result, target) -> dict:
+    r = {}
+
+    r['format'] = 1.0 if action_result['valid'] else 0.0
+    if not r['format']:
+        return {**r, 'total': -0.1}
+
+    r['anchored'] = 1.0 if action_result['anchored'] else 0.3
+
+    interior = state.graph.interior_vertices()
+    n = max(len(interior), 1)
+
+    kaw = [check_kawasaki_at_vertex(v, state.graph) for v in interior]
+    mae = [check_maekawa_at_vertex(v, state.graph) for v in interior]
+    blb = [check_blb_at_vertex(v, state.graph) for v in interior]
+
+    r['kawasaki'] = sum(ok for ok, _ in kaw) / n
+    r['maekawa']  = sum(mae) / n
+    r['blb']      = 1.0 - sum(len(v) > 0 for v in blb) / n
+
+    coverage, economy = geometric_coverage(state, target['edges'])
+    r['progress'] = coverage
+    r['economy']  = economy
+
+    all_valid = (r['kawasaki'] == 1.0 and r['maekawa'] == 1.0 and r['blb'] == 1.0)
+    r['completion'] = 10.0 if (r['progress'] > 0.9 and all_valid) else 0.0
+    r['efficiency'] = -0.01
+
+    r['total'] = (
+        0.05 * r['anchored'] +
+        0.08 * r['kawasaki'] +
+        0.07 * r['maekawa'] +
+        0.05 * r['blb'] +
+        0.45 * r['progress'] +
+        0.10 * r['economy'] +
+        r['completion'] +
+        r['efficiency']
+    )
+    return r
+```
+
+### Phase 2 reward extension
+
+When `fold_engine.py` is available, replace `progress` and `economy` with engineering metrics. No pre-specified target pattern required — the model optimizes objectives directly and can discover that Miura-ori is optimal.
+
+```python
+def compute_reward_phase2(state, action_result, folded_state) -> dict:
+    # ... same gates as phase 1 ...
+
+    r['deployment_ratio'] = compute_deployment_ratio(folded_state)
+    # = unfolded_area / folded_bounding_box_area
+
+    r['bbox_compactness'] = 1.0 - (folded_bbox_area / unfolded_area)
+    # higher = more compact fold
+
+    r['total'] = (
+        0.05 * r['anchored'] +
+        0.08 * r['kawasaki'] +
+        0.07 * r['maekawa'] +
+        0.05 * r['blb'] +
+        0.30 * r['deployment_ratio'] +
+        0.20 * r['bbox_compactness'] +
+        0.05 * r['economy'] +
+        r['completion'] +
+        r['efficiency']
+    )
+    return r
+```
+
+---
+
+## Phase 4: Prompts (`env/prompts.py`)
+
+### Code-as-policy prompt (training mode)
+
+```
+You are an origami designer. Generate a complete fold sequence for a unit square [0,1]x[0,1].
+
+TARGET CREASE PATTERN:
+  Valley fold: (0.0, 0.5) -> (1.0, 0.5)
+  Mountain fold: (0.5, 0.0) -> (0.5, 1.0)
+
+RULES (your sequence must satisfy at every interior vertex):
+  - Kawasaki: alternating sector angles sum equally (each half = 180 degrees)
+  - Maekawa: |mountain_count - valley_count| = 2
+  - Big-Little-Big: folds bounding the smallest sector must have opposite types
+
+ANCHOR POINTS (valid fold endpoints):
+  Corners:   (0,0)  (1,0)  (1,1)  (0,1)
+  Midpoints: (0.5,0)  (1,0.5)  (0.5,1)  (0,0.5)
+  Note: the square has 4-fold dihedral symmetry — symmetric fold sequences are equivalent.
+
+Output a JSON list of fold operations in order. Both endpoints must be anchor points.
+
+<folds>
+[
+  {"instruction": "...", "from": [x1, y1], "to": [x2, y2], "assignment": "M"|"V"},
+  ...
+]
+</folds>
+```
+
+### Step-level prompt (demo mode)
+
+Same information, but shows only the current step's observation with prior fold history and last-step reward appended. Same model, different prompt wrapper.
+
+```
+... [same header] ...
+
+CURRENT STATE (step 2 of 8):
+  Creases placed:
+    1. Mountain fold: (0.5, 0.0) -> (0.5, 1.0)
+
+AVAILABLE ANCHOR POINTS:
+  Corners:       (0.0,0.0)  (1.0,0.0)  (1.0,1.0)  (0.0,1.0)
+  Edge midpoints:(0.5,0.0)  (1.0,0.5)  (0.5,1.0)  (0.0,0.5)
+  Intersections: (0.5,0.5)
+
+LAST REWARD: format=1.0  kawasaki=1.0  maekawa=1.0  blb=1.0  progress=0.32  total=0.33
+
+Add the next crease. Output JSON only:
+{"instruction": "...", "from": [x1, y1], "to": [x2, y2], "assignment": "M"|"V"}
+```
+
+---
+
+## Phase 5: Target Files + Validator (`env/targets/`)
+
+Targets are hand-authored `.fold` JSON. Before any target enters training, `validator.py` runs:
+
+1. Parse FOLD JSON, reconstruct the CreaseGraph
+2. For each interior vertex: even-degree → Kawasaki → Maekawa → BLB
+3. Enumerate at least one valid MV assignment via the crimp algorithm
+4. Fail loudly with vertex + violation details if any check fails
+
+**Target set:**
+
+| File | Creases | Level | Interior vertices |
+|------|---------|-------|-------------------|
+| `half_horizontal.fold` | 1 | 1 | 0 |
+| `half_vertical.fold` | 1 | 1 | 0 |
+| `diagonal.fold` | 1 | 1 | 0 |
+| `cross_fold.fold` | 2 | 2 | 1 (degree 4) |
+| `x_fold.fold` | 2 | 2 | 1 (degree 4) |
+| `pinwheel_base.fold` | 4 | 2 | 4 |
+| `preliminary_base.fold` | 4 | 3 | 4 |
+| `fish_base.fold` | 6 | 3 | 6 |
+
+Level 1 targets have zero interior vertices — Kawasaki/Maekawa are vacuously satisfied, the only reward signal is `progress`. The model learns to place geometrically correct folds before worrying about vertex constraints.
+
+---
+
+## Phase 6: OpenEnv Wrapper (`env/environment.py`)
+
+Both modes supported. The `info` dict explicitly labels what is and isn't checked.
+
+```python
+class OrigamiEnvironment(Environment):
+
+    async def step(self, action):
+        if isinstance(action, list):
+            return self._execute_sequence(action)  # code-as-policy
+        else:
+            return self._execute_single(action)    # step mode
+
+    def _execute_sequence(self, folds):
+        for fold in folds:
+            result = self.paper.add_crease(
+                fold['from'], fold['to'], fold['assignment']
+            )
+            if not result['valid']:
+                break  # partial credit: reward up to failure point
+        reward = compute_reward_phase1(self.paper, result, self.target)
+        return self._get_observation(), reward, True, self._info()
+
+    def _info(self):
+        interior = self.paper.graph.interior_vertices()
+        return {
+            'local_foldability': all(
+                check_kawasaki_at_vertex(v, self.paper.graph)[0] and
+                check_maekawa_at_vertex(v, self.paper.graph)
+                for v in interior
+            ),
+            'blb_satisfied': all(
+                len(check_blb_at_vertex(v, self.paper.graph)) == 0
+                for v in interior
+            ),
+            'global_foldability': 'not_checked',  # NP-complete (Bern-Hayes 1996)
+            'n_interior_vertices': len(interior),
+        }
+```
+
+---
+
+## Phase 7: Training Script (`train.py`)
+
+Code-as-policy GRPO. Each completion is a complete fold sequence. N=8 completions per prompt evaluated in parallel, each with its own fresh `PaperState`. Terminal reward only.
+
+```python
+def origami_reward_fn(completions, prompts, targets):
+    rewards = []
+    for completion, target in zip(completions, targets):
+        try:
+            folds = parse_fold_list(completion)  # extract JSON from <folds> tags
+            paper = PaperState()
+            for fold in folds:
+                paper.add_crease(fold['from'], fold['to'], fold['assignment'])
+            r = compute_reward_phase1(paper, {'valid': True, 'anchored': True}, target)
+            rewards.append(r['total'])
+        except Exception:
+            rewards.append(-0.1)
+    return rewards
+```
+
+Log all reward components separately (kawasaki, maekawa, blb, progress, economy) — the decomposed curves are the demo artifact showing the model learning to satisfy geometric constraints.
+
+---
+
+## Phase 8: Fold Engine / Phase 2 (`env/fold_engine.py`)
+
+For flat-folded patterns (all creases at 180°), the folded bounding box is computable from crease pattern + simplified layer assignment. For Level 1-3 targets the layer assignment is tractable (polynomial for single-vertex, and our simple patterns have at most a few interior vertices).
+
+Apply fold angles via reflection transforms, project to get 2D bounding box of the folded state, compute:
+
+```
+deployment_ratio = 1.0 / (folded_bbox_area / unfolded_area)
+```
+
+Higher = more compact = better engineering. With this signal the model can discover optimal fold patterns (Miura-ori, accordion folds) without a pre-specified target.
+
+---
+
+## Build Order
+
+```
+[ ] 1.  requirements.txt (shapely, numpy, pytest)
+[ ] 2.  env/graph.py — CreaseGraph with cyclic ordering, split_edge
+[ ] 3.  Unit test: two crossing creases -> 1 interior vertex of degree 4, correct cyclic order
+[ ] 4.  env/paper_state.py — PaperState.add_crease with intersection handling
+[ ] 5.  env/verifier.py — even-degree, Kawasaki, Maekawa, BLB, geometric_coverage
+[ ] 6.  Unit test: degree-4 vertex with known valid/invalid angles -> Kawasaki pass/fail
+[ ] 7.  Unit test: single crease -> zero interior vertices -> verifiers return defaults (True)
+[ ] 8.  Unit test: excess crease penalty activates correctly
+[ ] 9.  targets/validator.py — crimp-check routine
+[ ] 10. env/targets/*.fold — 4 Level 1 + 4 Level 2 targets, all passing validator
+[ ] 11. env/rewards.py — Phase 1 compute_reward
+[ ] 12. env/prompts.py — code-as-policy prompt + step-level prompt
+[ ] 13. env/environment.py — both sequence and step modes + info dict
+[ ] 14. Integration test: known valid sequence on half_horizontal, reward >= 0.9
+[ ] 15. Integration test: invalid MV assignment on cross_fold, BLB fires
+[ ] 16. train.py — GRPO with code-as-policy reward fn
+[ ] 17. First training run on Level 1 targets, log all reward components to W&B
+[ ] 18. env/fold_engine.py — Phase 2: fold angles -> 3D state -> deployment ratio
+[ ] 19. Visualizer (React): render crease graph from FOLD JSON, animate fold history
+```
+
+Steps 2-3 and 5-8 are highest risk. Get the graph data structure and cyclic Kawasaki check correct before building anything on top of them. Steps 14-15 are the checkpoint before touching the training script.
+
+---
+
+## Key Risks
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Cyclic sector angle computation incorrect | High | Explicit unit tests with known valid/invalid patterns |
+| Level 3+ action space too large to learn | Medium | Dihedral symmetry hints in prompt; hard masking if no convergence after 500 steps |
+| GRPO reward signal too sparse (no interior vertices on Level 1) | Medium | Level 1 reward is purely `progress`; works without vertex constraints |
+| fold_engine Phase 2 infeasible in hackathon time | Medium | Phase 1 ships independently; Phase 2 is an extension |
+| Layer ordering required for deployment ratio on complex patterns | Low | Level 1-3 patterns are tractable; flag NP-hardness in info dict |

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "optigami"
+version = "0.1.0"
+description = "Optigami OpenEnv origami environment"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "fastapi>=0.100.0",
+  "numpy>=1.24.0",
+  "openenv-core[core]>=0.2.1",
+  "pydantic>=2.0.0",
+  "shapely>=2.0.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

requirements.txt

@@ -0,0 +1,7 @@
+shapely>=2.0.0
+numpy>=1.24.0
+scipy>=1.10.0
+matplotlib>=3.7.0
+pytest>=7.0.0
+fastapi>=0.100.0
+uvicorn>=0.23.0

server.py

@@ -0,0 +1,172 @@
+"""
+FastAPI server for the origami RL environment.
+Serves episode data to the React frontend.
+
+Usage: uvicorn server:app --reload --port 8000
+"""
+
+try:
+    from fastapi import FastAPI
+    from fastapi.middleware.cors import CORSMiddleware
+    from pydantic import BaseModel
+except ImportError:
+    print("Run: pip install fastapi uvicorn pydantic")
+    raise
+
+from typing import Optional
+
+
+app = FastAPI(title="OrigamiRL API")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # localhost:3000 for React dev
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class FoldAction(BaseModel):
+    from_point: list[float]  # [x, y]
+    to_point: list[float]    # [x, y]
+    assignment: str          # 'M' or 'V'
+    instruction: str = ""
+
+
+class EpisodeStep(BaseModel):
+    step: int
+    fold: Optional[FoldAction]
+    paper_state: dict        # FOLD JSON of current crease graph
+    anchor_points: list[list[float]]
+    reward: dict
+    done: bool
+    info: dict
+    prompt: str              # LLM prompt at this step
+
+
+class EpisodeResult(BaseModel):
+    target_name: str
+    target: dict             # FOLD JSON of target
+    steps: list[EpisodeStep]
+    final_reward: dict
+
+
+@app.get("/")
+def health_check():
+    """Health check — returns status and available target names."""
+    from env.environment import OrigamiEnvironment
+    env = OrigamiEnvironment()
+    return {"status": "ok", "targets": env.available_targets()}
+
+
+@app.get("/targets")
+def get_targets():
+    """Return list of available target names and their metadata."""
+    from env.environment import OrigamiEnvironment
+    env = OrigamiEnvironment()
+    targets = {}
+    for name in env.available_targets():
+        t = env._targets[name]
+        targets[name] = {
+            "name": name,
+            "level": t.get("level", 1),
+            "description": t.get("description", ""),
+            "n_creases": sum(1 for a in t["edges_assignment"] if a in ("M", "V")),
+        }
+    return targets
+
+
+@app.get("/episode/run")
+def run_episode(target: str = "half_horizontal", completion: str = ""):
+    """
+    Run a code-as-policy episode with a provided completion string.
+
+    If completion is empty, returns the prompt so the caller knows what to send.
+    Returns full episode result with all steps.
+    """
+    from env.environment import OrigamiEnvironment
+    from env.prompts import parse_fold_list, code_as_policy_prompt
+    from env.rewards import compute_reward, target_crease_edges
+
+    env = OrigamiEnvironment(mode="step")
+    obs = env.reset(target_name=target)
+
+    if not completion:
+        return {"prompt": obs["prompt"], "steps": [], "target": env.target}
+
+    try:
+        folds = parse_fold_list(completion)
+    except ValueError as e:
+        return {"error": str(e), "steps": []}
+
+    steps = []
+    for i, fold in enumerate(folds):
+        result = env.paper.add_crease(fold["from"], fold["to"], fold["assignment"])
+        reward = compute_reward(env.paper, result, env.target)
+
+        paper_state = {
+            "vertices": {str(k): list(v) for k, v in env.paper.graph.vertices.items()},
+            "edges": [
+                {
+                    "id": k,
+                    "v1": list(env.paper.graph.vertices[v[0]]),
+                    "v2": list(env.paper.graph.vertices[v[1]]),
+                    "assignment": v[2],
+                }
+                for k, v in env.paper.graph.edges.items()
+            ],
+            "anchor_points": [list(p) for p in env.paper.anchor_points()],
+        }
+
+        # Build per-step prompt reflecting current state
+        from env.prompts import step_level_prompt
+        step_prompt = step_level_prompt(
+            target=env.target,
+            paper_state=env.paper,
+            step=i + 1,
+            max_steps=env.max_steps,
+            last_reward=reward,
+        )
+
+        steps.append({
+            "step": i + 1,
+            "fold": {
+                "from_point": fold["from"],
+                "to_point": fold["to"],
+                "assignment": fold["assignment"],
+                "instruction": fold.get("instruction", ""),
+            },
+            "paper_state": paper_state,
+            "anchor_points": [list(p) for p in env.paper.anchor_points()],
+            "reward": reward,
+            "done": reward.get("completion", 0) > 0,
+            "info": env._info(),
+            "prompt": step_prompt,
+        })
+
+        if reward.get("completion", 0) > 0:
+            break
+
+    return {
+        "target_name": target,
+        "target": env.target,
+        "steps": steps,
+        "final_reward": steps[-1]["reward"] if steps else {},
+    }
+
+
+@app.get("/episode/demo")
+def demo_episode(target: str = "half_horizontal"):
+    """Return a pre-solved demo episode for each target."""
+    DEMO_COMPLETIONS = {
+        "half_horizontal": '<folds>[{"instruction": "Valley fold along horizontal center line", "from": [0, 0.5], "to": [1, 0.5], "assignment": "V"}]</folds>',
+        "half_vertical": '<folds>[{"instruction": "Mountain fold along vertical center line", "from": [0.5, 0], "to": [0.5, 1], "assignment": "M"}]</folds>',
+        "diagonal_main": '<folds>[{"instruction": "Valley fold along main diagonal", "from": [0, 0], "to": [1, 1], "assignment": "V"}]</folds>',
+        "diagonal_anti": '<folds>[{"instruction": "Mountain fold along anti-diagonal", "from": [1, 0], "to": [0, 1], "assignment": "M"}]</folds>',
+        "thirds_h": '<folds>[{"instruction": "Valley fold at one-third height", "from": [0, 0.333], "to": [1, 0.333], "assignment": "V"}, {"instruction": "Valley fold at two-thirds height", "from": [0, 0.667], "to": [1, 0.667], "assignment": "V"}]</folds>',
+        "thirds_v": '<folds>[{"instruction": "Mountain fold at one-third width", "from": [0.333, 0], "to": [0.333, 1], "assignment": "M"}, {"instruction": "Mountain fold at two-thirds width", "from": [0.667, 0], "to": [0.667, 1], "assignment": "M"}]</folds>',
+        "accordion_3h": '<folds>[{"instruction": "Valley fold at quarter height", "from": [0, 0.25], "to": [1, 0.25], "assignment": "V"}, {"instruction": "Mountain fold at half height", "from": [0, 0.5], "to": [1, 0.5], "assignment": "M"}, {"instruction": "Valley fold at three-quarter height", "from": [0, 0.75], "to": [1, 0.75], "assignment": "V"}]</folds>',
+        "accordion_4h": '<folds>[{"instruction": "Valley fold at 0.2", "from": [0, 0.2], "to": [1, 0.2], "assignment": "V"}, {"instruction": "Mountain fold at 0.4", "from": [0, 0.4], "to": [1, 0.4], "assignment": "M"}, {"instruction": "Valley fold at 0.6", "from": [0, 0.6], "to": [1, 0.6], "assignment": "V"}, {"instruction": "Mountain fold at 0.8", "from": [0, 0.8], "to": [1, 0.8], "assignment": "M"}]</folds>',
+    }
+    completion = DEMO_COMPLETIONS.get(target, DEMO_COMPLETIONS["half_horizontal"])
+    return run_episode(target=target, completion=completion)

sim/animate.py

@@ -0,0 +1,149 @@
+"""
+Matplotlib 3D animation of origami folding using OrigamiSimulator.
+
+Usage:
+    python -m sim.animate [target_name]
+
+    target_name defaults to 'half_horizontal', resolved against
+    env/targets/<target_name>.fold relative to this file's parent directory.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+import numpy as np
+from mpl_toolkits.mplot3d.art3d import Poly3DCollection
+
+from .simulator import OrigamiSimulator
+
+# ── Design system colours ─────────────────────────────────────────────────────
+BG_COLOR     = '#0d0d14'
+AX_COLOR     = '#13131d'
+PAPER_FACE   = '#fafaf5'
+PAPER_EDGE   = '#2a2a3a'
+MOUNTAIN_CLR = '#f59e0b'   # amber
+VALLEY_CLR   = '#38bdf8'   # sky
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def animate_fold(fold_file: str,
+                 n_frames: int = 80,
+                 steps_per_frame: int = 40,
+                 target_name: str = 'origami') -> None:
+    """
+    Animate folding from 0% → 100% → 0% in a triangle-wave loop.
+
+    Parameters
+    ----------
+    fold_file : str
+        Path to the .fold JSON file.
+    n_frames : int
+        Total animation frames (default 80 → ~40 in, 40 out).
+    steps_per_frame : int
+        Physics steps executed per frame.
+    target_name : str
+        Display name shown in the title.
+    """
+    fold_data = json.loads(Path(fold_file).read_text())
+    sim = OrigamiSimulator(fold_data, subdivisions=2)
+
+    # Triangle-wave fold percents: 0 → 1 → 0
+    half = n_frames // 2
+    fold_percents = np.concatenate([
+        np.linspace(0.0, 1.0, half),
+        np.linspace(1.0, 0.0, n_frames - half),
+    ])
+
+    # ── Figure setup ──────────────────────────────────────────────────────────
+    fig = plt.figure(figsize=(9, 7), facecolor=BG_COLOR)
+    ax  = fig.add_subplot(111, projection='3d')
+    ax.set_facecolor(AX_COLOR)
+    ax.xaxis.pane.fill = False
+    ax.yaxis.pane.fill = False
+    ax.zaxis.pane.fill = False
+    ax.grid(False)
+    ax.set_axis_off()
+
+    def update(frame: int) -> list:
+        pct = fold_percents[frame]
+        sim.set_fold_percent(pct)
+        sim.step(steps_per_frame)
+
+        ax.clear()
+        ax.set_facecolor(AX_COLOR)
+        ax.xaxis.pane.fill = False
+        ax.yaxis.pane.fill = False
+        ax.zaxis.pane.fill = False
+        ax.grid(False)
+        ax.set_axis_off()
+
+        # ── Paper surface ─────────────────────────────────────────────────────
+        verts = [sim.pos[tri] for tri in sim.triangles]
+        poly = Poly3DCollection(
+            verts,
+            alpha=0.85,
+            facecolor=PAPER_FACE,
+            edgecolor=PAPER_EDGE,
+            linewidth=0.2,
+            zorder=1,
+        )
+        ax.add_collection3d(poly)
+
+        # ── Crease / fold edges ───────────────────────────────────────────────
+        for i in range(len(sim._crease_a)):
+            if sim._crease_assign[i] not in ('M', 'V'):
+                continue
+            a, b = sim._crease_a[i], sim._crease_b[i]
+            color = MOUNTAIN_CLR if sim._crease_assign[i] == 'M' else VALLEY_CLR
+            ax.plot(
+                [sim.pos[a, 0], sim.pos[b, 0]],
+                [sim.pos[a, 1], sim.pos[b, 1]],
+                [sim.pos[a, 2], sim.pos[b, 2]],
+                color=color,
+                linewidth=2.5,
+                zorder=2,
+            )
+
+        # ── Axis limits & style ───────────────────────────────────────────────
+        ax.set_xlim(-0.2, 1.2)
+        ax.set_ylim(-0.2, 1.2)
+        ax.set_zlim(-0.6, 0.6)
+        ax.set_box_aspect([1.4, 1.4, 1.0])
+        ax.set_title(
+            f'OPTIGAMI — {target_name}  fold: {pct * 100:.0f}%',
+            color='#e0e0f0',
+            fontsize=13,
+            pad=10,
+        )
+
+        return []
+
+    ani = animation.FuncAnimation(
+        fig,
+        update,
+        frames=n_frames,
+        interval=40,   # ms between frames (~25 fps)
+        blit=False,
+    )
+
+    plt.tight_layout()
+    plt.show()
+
+
+def main() -> None:
+    target = sys.argv[1] if len(sys.argv) > 1 else 'half_horizontal'
+    fold_file = Path(__file__).parent.parent / 'env' / 'targets' / f'{target}.fold'
+    if not fold_file.exists():
+        print(f'Error: fold file not found: {fold_file}', file=sys.stderr)
+        sys.exit(1)
+    animate_fold(str(fold_file), target_name=target)
+
+
+if __name__ == '__main__':
+    main()

sim/simulator.py

@@ -0,0 +1,406 @@
+"""
+Origami mass-spring dynamic relaxation simulator.
+
+Based on: Ghassaei et al., "Fast, Interactive Origami Simulation using GPU
+Computation", 7OSME 2018.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.spatial import Delaunay
+
+# ── Physics constants ────────────────────────────────────────────────────────
+
+AXIAL_STIFFNESS  = 20.0   # K = AXIAL_STIFFNESS / rest_length
+CREASE_STIFFNESS = 0.7    # K = CREASE_STIFFNESS * edge_length  (M/V creases)
+PANEL_STIFFNESS  = 0.7    # K = PANEL_STIFFNESS  * edge_length  (F / panel edges)
+PERCENT_DAMPING  = 0.45   # global viscous damping fraction
+DT               = 0.002  # timestep (seconds)
+
+
+# ── Geometry helpers ─────────────────────────────────────────────────────────
+
+def _normalize(v: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(v)
+    return v / n if n > 1e-12 else v
+
+
+def _triangulate_faces(faces_vertices: list[list[int]]) -> np.ndarray:
+    """Fan-triangulate polygonal faces (triangles and quads supported)."""
+    tris = []
+    for face in faces_vertices:
+        if len(face) == 3:
+            tris.append(face)
+        elif len(face) == 4:
+            a, b, c, d = face
+            tris.append([a, b, c])
+            tris.append([a, c, d])
+        else:
+            # General fan triangulation for n-gons
+            for k in range(1, len(face) - 1):
+                tris.append([face[0], face[k], face[k + 1]])
+    return np.array(tris, dtype=np.int32)
+
+
+def _point_on_segment(p: np.ndarray, p0: np.ndarray, p1: np.ndarray,
+                      tol: float = 1e-6) -> bool:
+    seg = p1 - p0
+    seg_len = np.linalg.norm(seg)
+    if seg_len < 1e-10:
+        return False
+    seg_dir = seg / seg_len
+    t = np.dot(p - p0, seg_dir)
+    perp = (p - p0) - t * seg_dir
+    return -tol <= t <= seg_len + tol and np.linalg.norm(perp) < tol
+
+
+# ── Mesh subdivision ──────────────────────────────────────────────────────────
+
+def _subdivide(pos2d: np.ndarray, triangles: np.ndarray
+               ) -> tuple[np.ndarray, np.ndarray]:
+    """Split each triangle into 4 by inserting edge midpoints."""
+    midpoint_cache: dict[tuple[int, int], int] = {}
+    new_pos = list(pos2d)
+    new_tris = []
+
+    def get_mid(i: int, j: int) -> int:
+        key = (min(i, j), max(i, j))
+        if key not in midpoint_cache:
+            mid = (np.array(new_pos[i]) + np.array(new_pos[j])) / 2.0
+            midpoint_cache[key] = len(new_pos)
+            new_pos.append(mid)
+        return midpoint_cache[key]
+
+    for tri in triangles:
+        a, b, c = tri
+        ab = get_mid(a, b)
+        bc = get_mid(b, c)
+        ca = get_mid(c, a)
+        new_tris.extend([
+            [a,  ab, ca],
+            [ab, b,  bc],
+            [ca, bc, c ],
+            [ab, bc, ca],
+        ])
+
+    return np.array(new_pos, dtype=np.float64), np.array(new_tris, dtype=np.int32)
+
+
+# ── Main simulator ────────────────────────────────────────────────────────────
+
+class OrigamiSimulator:
+    """
+    Mass-spring dynamic relaxation simulator for origami.
+
+    Parameters
+    ----------
+    fold_data : dict
+        Parsed FOLD JSON with keys: vertices_coords, edges_vertices,
+        edges_assignment.
+    subdivisions : int
+        Number of midpoint subdivision passes (default 2 → 4× mesh density).
+    """
+
+    def __init__(self, fold_data: dict, subdivisions: int = 2) -> None:
+        self._fold_percent = 0.0
+        self._build(fold_data, subdivisions)
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def set_fold_percent(self, percent: float) -> None:
+        """Update all crease spring target angles (0.0 = flat, 1.0 = fully folded)."""
+        self._fold_percent = float(percent)
+        self._crease_target = self._fold_percent * self._crease_full_theta
+
+    def step(self, n_steps: int = 50) -> None:
+        """Advance the simulation by n_steps Euler integration steps."""
+        for _ in range(n_steps):
+            self._euler_step()
+
+    def reset(self) -> None:
+        """Reset to flat state (z=0, vel=0), preserving current fold percent."""
+        self.pos = self._flat_pos.copy()
+        self.vel[:] = 0.0
+
+    @property
+    def crease_indices(self) -> list[tuple[int, int, str]]:
+        """Return list of (a, b, assignment) for all crease springs."""
+        return list(zip(
+            self._crease_a.tolist(),
+            self._crease_b.tolist(),
+            self._crease_assign,
+        ))
+
+    # ── Build ─────────────────────────────────────────────────────────────────
+
+    def _build(self, fold_data: dict, subdivisions: int) -> None:
+        coords = fold_data['vertices_coords']
+        orig_edges = fold_data['edges_vertices']
+        orig_assign = fold_data['edges_assignment']
+
+        # Original 2-D positions
+        pts2d = np.array([[x, y] for x, y in coords], dtype=np.float64)
+
+        # Build triangles from faces_vertices when available (preferred: ensures
+        # crease edges appear as actual mesh edges after subdivision).
+        # Quads [a,b,c,d] are split into [a,b,c] + [a,c,d].
+        # Fall back to Delaunay only if faces_vertices is absent.
+        if 'faces_vertices' in fold_data:
+            triangles = _triangulate_faces(fold_data['faces_vertices'])
+        else:
+            tri = Delaunay(pts2d)
+            triangles = tri.simplices.astype(np.int32)
+
+        # Build original crease segments for later classification
+        # Only M and V assignments are actual fold creases; B is boundary.
+        orig_creases: list[tuple[np.ndarray, np.ndarray, str]] = []
+        for (u, v), asgn in zip(orig_edges, orig_assign):
+            if asgn in ('M', 'V'):
+                orig_creases.append((pts2d[u], pts2d[v], asgn))
+
+        # Midpoint subdivision passes
+        pos2d = pts2d.copy()
+        for _ in range(subdivisions):
+            pos2d, triangles = _subdivide(pos2d, triangles)
+
+        n = len(pos2d)
+
+        # 3-D positions (flat, z=0)
+        pos3d = np.zeros((n, 3), dtype=np.float64)
+        pos3d[:, :2] = pos2d
+
+        self.pos        = pos3d
+        self._flat_pos  = pos3d.copy()
+        self.vel        = np.zeros((n, 3), dtype=np.float64)
+        self.triangles  = triangles
+
+        self._build_beams(triangles)
+        self._build_masses(triangles)
+        self._build_creases(triangles, pos2d, orig_creases)
+
+    def _build_beams(self, triangles: np.ndarray) -> None:
+        """Collect all unique triangle edges as structural (axial) springs."""
+        edge_set: set[tuple[int, int]] = set()
+        for tri in triangles:
+            a, b, c = tri
+            for i, j in [(a, b), (b, c), (c, a)]:
+                edge_set.add((min(i, j), max(i, j)))
+
+        edges = np.array(sorted(edge_set), dtype=np.int32)
+        i_arr = edges[:, 0]
+        j_arr = edges[:, 1]
+
+        rest = np.linalg.norm(self.pos[i_arr] - self.pos[j_arr], axis=1)
+        K    = AXIAL_STIFFNESS / np.maximum(rest, 1e-12)
+
+        self._beam_i    = i_arr
+        self._beam_j    = j_arr
+        self._beam_rest = rest
+        self._beam_K    = K
+
+    def _build_masses(self, triangles: np.ndarray) -> None:
+        """Mass per node = sum of (adjacent triangle area / 3)."""
+        n = len(self.pos)
+        mass = np.zeros(n, dtype=np.float64)
+        for tri in triangles:
+            a, b, c = tri
+            pa, pb, pc = self.pos[a], self.pos[b], self.pos[c]
+            area = 0.5 * np.linalg.norm(np.cross(pb - pa, pc - pa))
+            mass[a] += area / 3.0
+            mass[b] += area / 3.0
+            mass[c] += area / 3.0
+        # Guard against zero-mass nodes (degenerate triangles)
+        mass = np.maximum(mass, 1e-12)
+        self.mass = mass
+
+    def _build_creases(self, triangles: np.ndarray, pos2d: np.ndarray,
+                       orig_creases: list[tuple[np.ndarray, np.ndarray, str]]
+                       ) -> None:
+        """
+        Identify interior edges (shared by exactly 2 triangles) and classify
+        them as M/V fold creases or F panel springs.
+        """
+        # Map each canonical edge → list of triangle indices containing it
+        edge_to_tris: dict[tuple[int, int], list[int]] = {}
+        tri_edge_map: dict[tuple[int, int], list[tuple[int, int, int]]] = {}
+
+        for t_idx, tri in enumerate(triangles):
+            a, b, c = tri
+            for (ei, ej), opposite in [
+                ((min(a, b), max(a, b)), c),
+                ((min(b, c), max(b, c)), a),
+                ((min(c, a), max(c, a)), b),
+            ]:
+                edge_to_tris.setdefault((ei, ej), []).append(t_idx)
+                tri_edge_map.setdefault((ei, ej), []).append((ei, ej, opposite))
+
+        crease_a: list[int] = []
+        crease_b: list[int] = []
+        crease_c: list[int] = []
+        crease_d: list[int] = []
+        crease_assign: list[str] = []
+        crease_full_theta: list[float] = []
+        crease_K: list[float] = []
+
+        for edge_key, t_indices in edge_to_tris.items():
+            if len(t_indices) != 2:
+                continue  # boundary edge
+
+            ei, ej = edge_key
+            # Collect opposite nodes for each of the two triangles
+            # Find the opposite node for tri 0 and tri 1
+            opp_nodes = [None, None]
+            for t_pos, t_idx in enumerate(t_indices):
+                tri = triangles[t_idx]
+                for node in tri:
+                    if node != ei and node != ej:
+                        opp_nodes[t_pos] = node
+                        break
+
+            c_node = opp_nodes[0]
+            d_node = opp_nodes[1]
+            if c_node is None or d_node is None:
+                continue
+
+            # Classify: check if both endpoints lie on the same original crease segment
+            pi = pos2d[ei]
+            pj = pos2d[ej]
+            asgn = 'F'
+            for p0, p1, crease_type in orig_creases:
+                if _point_on_segment(pi, p0, p1) and _point_on_segment(pj, p0, p1):
+                    asgn = crease_type
+                    break
+
+            if asgn == 'M':
+                full_theta = +np.pi
+                K = CREASE_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
+            elif asgn == 'V':
+                full_theta = -np.pi
+                K = CREASE_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
+            else:  # 'F' panel
+                full_theta = 0.0
+                K = PANEL_STIFFNESS * np.linalg.norm(pos2d[ej] - pos2d[ei])
+
+            crease_a.append(ei)
+            crease_b.append(ej)
+            crease_c.append(c_node)
+            crease_d.append(d_node)
+            crease_assign.append(asgn)
+            crease_full_theta.append(full_theta)
+            crease_K.append(K)
+
+        self._crease_a          = np.array(crease_a, dtype=np.int32)
+        self._crease_b          = np.array(crease_b, dtype=np.int32)
+        self._crease_c          = np.array(crease_c, dtype=np.int32)
+        self._crease_d          = np.array(crease_d, dtype=np.int32)
+        self._crease_assign     = crease_assign
+        self._crease_full_theta = np.array(crease_full_theta, dtype=np.float64)
+        self._crease_K          = np.array(crease_K, dtype=np.float64)
+        self._crease_target     = np.zeros(len(crease_a), dtype=np.float64)
+
+    # ── Physics ───────────────────────────────────────────────────────────────
+
+    def _beam_forces(self) -> np.ndarray:
+        """Vectorized axial spring forces for all beams."""
+        n = len(self.pos)
+        forces = np.zeros((n, 3), dtype=np.float64)
+
+        pi = self.pos[self._beam_i]
+        pj = self.pos[self._beam_j]
+        diff = pj - pi
+        lengths = np.linalg.norm(diff, axis=1, keepdims=True)
+        lengths = np.maximum(lengths, 1e-12)
+        unit = diff / lengths
+
+        stretch = lengths[:, 0] - self._beam_rest
+        F_mag = self._beam_K * stretch          # scalar force magnitude
+
+        # Damping along the edge
+        vi = self.vel[self._beam_i]
+        vj = self.vel[self._beam_j]
+        rel_vel = np.sum((vj - vi) * unit, axis=1)
+        damp_mag = PERCENT_DAMPING * rel_vel
+        F_total = (F_mag + damp_mag)[:, None] * unit
+
+        np.add.at(forces, self._beam_i,  F_total)
+        np.add.at(forces, self._beam_j, -F_total)
+        return forces
+
+    def _crease_forces(self) -> np.ndarray:
+        """Torsional spring forces for all crease/panel edges (Python loop)."""
+        n = len(self.pos)
+        forces = np.zeros((n, 3), dtype=np.float64)
+
+        pos = self.pos
+        for idx in range(len(self._crease_a)):
+            a = self._crease_a[idx]
+            b = self._crease_b[idx]
+            c = self._crease_c[idx]
+            d = self._crease_d[idx]
+            K = self._crease_K[idx]
+            target = self._crease_target[idx]
+
+            pa, pb, pc, pd = pos[a], pos[b], pos[c], pos[d]
+
+            edge_vec = pb - pa
+            edge_len = np.linalg.norm(edge_vec)
+            if edge_len < 1e-12:
+                continue
+            edge_dir = edge_vec / edge_len
+
+            # Face normals
+            n1_raw = np.cross(pb - pa, pc - pa)
+            n2_raw = np.cross(pa - pb, pd - pb)
+            n1_len = np.linalg.norm(n1_raw)
+            n2_len = np.linalg.norm(n2_raw)
+            if n1_len < 1e-12 or n2_len < 1e-12:
+                continue
+            n1 = n1_raw / n1_len
+            n2 = n2_raw / n2_len
+
+            # Dihedral angle via atan2
+            cross_n = np.cross(n1, n2)
+            sin_theta = np.dot(cross_n, edge_dir)
+            cos_theta = np.dot(n1, n2)
+            theta = np.arctan2(sin_theta, cos_theta)
+
+            delta  = theta - target
+            torque = -K * delta
+
+            # Moment arms (perpendicular distance from c, d to crease line)
+            vc = pc - pa
+            vd = pd - pa
+            vc_perp = vc - np.dot(vc, edge_dir) * edge_dir
+            vd_perp = vd - np.dot(vd, edge_dir) * edge_dir
+            h_c = np.linalg.norm(vc_perp)
+            h_d = np.linalg.norm(vd_perp)
+            if h_c < 1e-12 or h_d < 1e-12:
+                continue
+
+            # Forces on opposite nodes
+            F_c =  (torque / h_c) * n1
+            F_d = -(torque / h_d) * n2
+
+            # Reaction on crease nodes (moment balance)
+            proj_c = np.dot(pc - pa, edge_dir)
+            proj_d = np.dot(pd - pa, edge_dir)
+            coef_c_a = 1.0 - proj_c / edge_len
+            coef_c_b =       proj_c / edge_len
+            coef_d_a = 1.0 - proj_d / edge_len
+            coef_d_b =       proj_d / edge_len
+
+            forces[c] += F_c
+            forces[d] += F_d
+            forces[a] -= coef_c_a * F_c + coef_d_a * F_d
+            forces[b] -= coef_c_b * F_c + coef_d_b * F_d
+
+        return forces
+
+    def _euler_step(self) -> None:
+        forces = self._beam_forces() + self._crease_forces()
+        accel  = forces / self.mass[:, None]
+        vel_new = self.vel + accel * DT
+        vel_new *= (1.0 - PERCENT_DAMPING * DT)
+        self.pos += vel_new * DT
+        self.vel  = vel_new

src/App.css

@@ -1,38 +1,548 @@
-.App {
-  text-align: center;
+:root {
+  --bg: #0d0d14;
+  --surface: #13131d;
+  --surface-2: #1a1a2e;
+  --paper-white: #fafaf5;
+  --paper-edge: #2a2a3a;
+  --mountain: #f59e0b;
+  --valley: #38bdf8;
+  --target-ghost: rgba(124, 58, 237, 0.20);
+  --target-ghost-stroke: rgba(124, 58, 237, 0.45);
+  --validity: #22d3ee;
+  --progress: #22c55e;
+  --economy: #a78bfa;
+  --text-primary: #f8fafc;
+  --text-dim: #64748b;
+  --border: #2a2a3a;
+  --border-bright: #3a3a5a;
+  --font-display: 'JetBrains Mono', monospace;
+  --font-mono: 'IBM Plex Mono', monospace;
+}
+
+.app {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  background: var(--bg);
+  overflow: hidden;
+}
+
+/* ─── HEADER ─── */
+.app-header {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  padding: 0 20px;
+  height: 48px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+  flex-shrink: 0;
+  z-index: 10;
 }
 
-.App-logo {
-  height: 40vmin;
-  pointer-events: none;
+.app-title {
+  font-family: var(--font-display);
+  font-size: 14px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  color: var(--text-primary);
+  white-space: nowrap;
 }
 
-@media (prefers-reduced-motion: no-preference) {
-  .App-logo {
-    animation: App-logo-spin infinite 20s linear;
-  }
+.app-title .title-accent {
+  color: var(--mountain);
 }
 
-.App-header {
-  background-color: #282c34;
-  min-height: 100vh;
+.header-sep {
+  width: 1px;
+  height: 24px;
+  background: var(--border);
+  flex-shrink: 0;
+}
+
+.header-right {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  margin-left: auto;
+}
+
+.api-status {
+  font-size: 11px;
+  font-family: var(--font-display);
+  letter-spacing: 0.08em;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.api-status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--text-dim);
+}
+
+.api-status-dot.ok {
+  background: var(--progress);
+  box-shadow: 0 0 6px var(--progress);
+}
+
+.api-status-dot.err {
+  background: #ef4444;
+  box-shadow: 0 0 6px #ef4444;
+}
+
+/* ─── MAIN LAYOUT ─── */
+.app-body {
+  display: grid;
+  grid-template-columns: 1fr 280px;
+  flex: 1;
+  overflow: hidden;
+}
+
+.app-left {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border-right: 1px solid var(--border);
+}
+
+.app-right {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--surface);
+}
+
+/* ─── CANVAS ROW ─── */
+.canvas-row {
+  display: flex;
+  gap: 0;
+  padding: 16px;
+  flex-shrink: 0;
+  border-bottom: 1px solid var(--border);
+  overflow-x: auto;
+}
+
+.canvas-wrap {
   display: flex;
   flex-direction: column;
+  gap: 8px;
+  flex: 1;
+  min-width: 280px;
+}
+
+.canvas-wrap + .canvas-wrap {
+  margin-left: 16px;
+}
+
+.canvas-label {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.14em;
+  color: var(--text-dim);
+  text-transform: uppercase;
+}
+
+.canvas-svg {
+  display: block;
+  background: var(--paper-white);
+}
+
+.canvas-3d {
+  display: block;
+  background: linear-gradient(180deg, #1a1a2e 0%, #0f101a 100%);
+  border: 1px solid var(--border);
+}
+
+.canvas-label-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.fold-mode-toggle {
+  display: inline-flex;
+  border: 1px solid var(--border);
+  background: var(--surface);
+}
+
+.fold-mode-btn {
+  border: none;
+  background: transparent;
+  color: var(--text-dim);
+  font-family: var(--font-display);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  padding: 3px 7px;
+  cursor: pointer;
+}
+
+.fold-mode-btn + .fold-mode-btn {
+  border-left: 1px solid var(--border);
+}
+
+.fold-mode-btn.active {
+  color: var(--text-primary);
+  background: #1f2538;
+}
+
+/* ─── STEP FEED ─── */
+.step-feed-section {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.section-header {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.14em;
+  color: var(--text-dim);
+  text-transform: uppercase;
+  padding: 8px 16px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.step-feed {
+  overflow-y: auto;
+  flex: 1;
+  padding: 4px 0;
+}
+
+.step-entry {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 8px 16px;
+  border-bottom: 1px solid var(--border);
+  cursor: default;
+  transition: background 0.1s;
+}
+
+.step-entry:hover {
+  background: var(--surface);
+}
+
+.step-entry.active {
+  background: var(--surface-2);
+  border-left: 2px solid var(--valley);
+  padding-left: 14px;
+}
+
+.step-entry-top {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.step-num {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--text-dim);
+  width: 24px;
+  flex-shrink: 0;
+}
+
+.step-instruction {
+  font-size: 12px;
+  color: var(--text-primary);
+  flex: 1;
+}
+
+.assign-badge {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 700;
+  padding: 1px 5px;
+  line-height: 1.4;
+  flex-shrink: 0;
+}
+
+.assign-badge.M {
+  background: var(--mountain);
+  color: #0d0d14;
+}
+
+.assign-badge.V {
+  background: var(--valley);
+  color: #0d0d14;
+}
+
+.assign-badge.B {
+  background: var(--border-bright);
+  color: var(--text-dim);
+}
+
+.step-reward-delta {
+  font-size: 11px;
+  color: var(--text-dim);
+  padding-left: 32px;
+}
+
+.step-reward-delta .delta-positive {
+  color: var(--progress);
+}
+
+.step-reward-delta .delta-negative {
+  color: #ef4444;
+}
+
+/* ─── REWARD PANEL ─── */
+.reward-panel {
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.reward-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 6px;
+}
+
+.reward-row:last-child {
+  margin-bottom: 0;
+}
+
+.reward-label {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.06em;
+  color: var(--text-dim);
+  width: 72px;
+  flex-shrink: 0;
+  text-transform: uppercase;
+}
+
+.reward-track {
+  flex: 1;
+  height: 8px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  overflow: hidden;
+}
+
+.reward-bar {
+  height: 100%;
+  transition: width 0.4s ease;
+}
+
+.reward-value {
+  font-family: var(--font-display);
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--text-primary);
+  width: 36px;
+  text-align: right;
+  flex-shrink: 0;
+}
+
+.reward-value.dim {
+  color: var(--text-dim);
+}
+
+.reward-divider {
+  height: 1px;
+  background: var(--border);
+  margin: 6px 0;
+}
+
+/* ─── INFO BADGES ─── */
+.info-badges {
+  padding: 12px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.info-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.info-key {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.06em;
+  color: var(--text-dim);
+  text-transform: uppercase;
+}
+
+.info-val {
+  font-family: var(--font-display);
+  font-size: 11px;
+  font-weight: 700;
+  color: var(--text-primary);
+}
+
+.info-val.bool-true {
+  color: var(--progress);
+}
+
+.info-val.bool-false {
+  color: #ef4444;
+}
+
+.info-val.dim {
+  color: var(--text-dim);
+}
+
+/* ─── TARGET SELECTOR ─── */
+.target-selector {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.target-selector-label {
+  font-family: var(--font-display);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.10em;
+  color: var(--text-dim);
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.target-select {
+  background: var(--surface-2);
+  border: 1px solid var(--border-bright);
+  color: var(--text-primary);
+  font-family: var(--font-display);
+  font-size: 11px;
+  padding: 4px 8px;
+  outline: none;
+  cursor: pointer;
+  min-width: 180px;
+}
+
+.target-select:focus {
+  border-color: var(--valley);
+}
+
+optgroup {
+  background: var(--surface);
+  color: var(--text-dim);
+  font-family: var(--font-display);
+  font-size: 10px;
+}
+
+option {
+  background: var(--surface-2);
+  color: var(--text-primary);
+  font-family: var(--font-display);
+}
+
+/* ─── PLAYER CONTROLS ─── */
+.player-controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+}
+
+.ctrl-btn {
+  background: var(--surface-2);
+  border: 1px solid var(--border-bright);
+  color: var(--text-primary);
+  font-family: var(--font-display);
+  font-size: 11px;
+  font-weight: 500;
+  padding: 4px 10px;
+  cursor: pointer;
+  white-space: nowrap;
+  line-height: 1.4;
+  letter-spacing: 0.04em;
+  transition: background 0.1s, border-color 0.1s;
+}
+
+.ctrl-btn:hover:not(:disabled) {
+  background: var(--surface);
+  border-color: var(--text-dim);
+}
+
+.ctrl-btn:disabled {
+  opacity: 0.35;
+  cursor: not-allowed;
+}
+
+.ctrl-btn.play {
+  border-color: var(--valley);
+  color: var(--valley);
+}
+
+.ctrl-btn.play:hover:not(:disabled) {
+  background: rgba(56, 189, 248, 0.1);
+}
+
+.ctrl-step-display {
+  font-family: var(--font-display);
+  font-size: 11px;
+  color: var(--text-dim);
+  padding: 4px 8px;
+  border: 1px solid var(--border);
+  background: var(--bg);
+  white-space: nowrap;
+  min-width: 72px;
+  text-align: center;
+}
+
+/* ─── LOADING / ERROR ─── */
+.app-overlay {
+  position: fixed;
+  inset: 0;
+  display: flex;
   align-items: center;
   justify-content: center;
-  font-size: calc(10px + 2vmin);
-  color: white;
+  background: var(--bg);
+  z-index: 100;
+}
+
+.overlay-message {
+  font-family: var(--font-display);
+  font-size: 13px;
+  letter-spacing: 0.1em;
+  color: var(--text-dim);
+  display: flex;
+  align-items: center;
+  gap: 12px;
 }
 
-.App-link {
-  color: #61dafb;
+.pulse-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--valley);
+  animation: pulse 1.2s ease-in-out infinite;
 }
 
-@keyframes App-logo-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
+@keyframes pulse {
+  0%, 100% { opacity: 0.2; transform: scale(0.8); }
+  50% { opacity: 1; transform: scale(1); }
+}
+
+/* ─── MISC ─── */
+.episode-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 12px 16px;
+  font-family: var(--font-display);
+  font-size: 11px;
+  color: var(--text-dim);
+  letter-spacing: 0.08em;
 }

src/App.js

@@ -1,23 +1,218 @@
-import logo from './logo.svg';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import './App.css';
+import CreaseCanvas from './components/CreaseCanvas';
+import RewardPanel from './components/RewardPanel';
+import StepFeed from './components/StepFeed';
+import InfoBadges from './components/InfoBadges';
+import TargetSelector from './components/TargetSelector';
+import PlayerControls from './components/PlayerControls';
+import Fold3DCanvas from './components/Fold3DCanvas';
+
+const API_BASE = 'http://localhost:8000';
 
 function App() {
+  const [targets, setTargets] = useState({});
+  const [selectedTarget, setSelectedTarget] = useState('half_horizontal');
+  const [episode, setEpisode] = useState(null);
+  const [currentStep, setCurrentStep] = useState(0);
+  const [playing, setPlaying] = useState(false);
+  const [foldRenderMode, setFoldRenderMode] = useState('progressive'); // 'progressive' | 'final'
+  const [apiStatus, setApiStatus] = useState('connecting'); // 'connecting' | 'ok' | 'err'
+  const [episodeLoading, setEpisodeLoading] = useState(false);
+  const intervalRef = useRef(null);
+
+  const fetchTargets = useCallback(async () => {
+    try {
+      const res = await fetch(`${API_BASE}/targets`);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      setTargets(data);
+      setApiStatus('ok');
+    } catch {
+      setApiStatus('err');
+    }
+  }, []);
+
+  const fetchDemoEpisode = useCallback(async (targetName) => {
+    setEpisodeLoading(true);
+    setPlaying(false);
+    setCurrentStep(0);
+    try {
+      const res = await fetch(`${API_BASE}/episode/demo?target=${targetName}`);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      setEpisode(data);
+      setApiStatus('ok');
+    } catch {
+      setEpisode(null);
+      setApiStatus('err');
+    } finally {
+      setEpisodeLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchTargets();
+  }, [fetchTargets]);
+
+  useEffect(() => {
+    fetchDemoEpisode(selectedTarget);
+  }, [selectedTarget, fetchDemoEpisode]);
+
+  const totalSteps = episode ? episode.steps.length : 0;
+
+  // currentStep is 1-indexed for display (0 = "empty paper before any folds")
+  // steps array is 0-indexed: steps[0] = result of fold 1
+  const activeStepData = episode && currentStep > 0 ? episode.steps[currentStep - 1] : null;
+
+  useEffect(() => {
+    if (playing) {
+      intervalRef.current = setInterval(() => {
+        setCurrentStep(prev => {
+          if (prev >= totalSteps) {
+            setPlaying(false);
+            return prev;
+          }
+          return prev + 1;
+        });
+      }, 1500);
+    }
+    return () => clearInterval(intervalRef.current);
+  }, [playing, totalSteps]);
+
+  const handlePlay = () => {
+    if (currentStep >= totalSteps) setCurrentStep(0);
+    setPlaying(true);
+  };
+  const handlePause = () => setPlaying(false);
+  const handleNext = () => {
+    setPlaying(false);
+    setCurrentStep(prev => Math.min(prev + 1, totalSteps));
+  };
+  const handlePrev = () => {
+    setPlaying(false);
+    setCurrentStep(prev => Math.max(prev - 1, 0));
+  };
+  const handleReset = () => {
+    setPlaying(false);
+    setCurrentStep(0);
+  };
+
+  const targetDef = targets[selectedTarget] || null;
+  const targetFold = episode ? episode.target : null;
+
   return (
-    <div className="App">
-      <header className="App-header">
-        <img src={logo} className="App-logo" alt="logo" />
-        <p>
-          Edit <code>src/App.js</code> and save to reload.
-        </p>
-        <a
-          className="App-link"
-          href="https://reactjs.org"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          Learn React
-        </a>
+    <div className="app">
+      <header className="app-header">
+        <span className="app-title">
+          OPTI<span className="title-accent">GAMI</span> RL
+        </span>
+        <div className="header-sep" />
+        <TargetSelector
+          targets={targets}
+          selected={selectedTarget}
+          onChange={name => setSelectedTarget(name)}
+        />
+        <div className="header-sep" />
+        <PlayerControls
+          playing={playing}
+          onPlay={handlePlay}
+          onPause={handlePause}
+          onNext={handleNext}
+          onPrev={handlePrev}
+          onReset={handleReset}
+          currentStep={currentStep}
+          totalSteps={totalSteps}
+          disabled={!episode || episodeLoading}
+        />
+        <div className="header-right">
+          <div className="api-status">
+            <span className={`api-status-dot ${apiStatus === 'ok' ? 'ok' : apiStatus === 'err' ? 'err' : ''}`} />
+            <span>{apiStatus === 'ok' ? 'API OK' : apiStatus === 'err' ? 'API ERR' : 'CONNECTING'}</span>
+          </div>
+        </div>
       </header>
+
+      <div className="app-body">
+        <div className="app-left">
+          <div className="canvas-row">
+            <div className="canvas-wrap">
+              <span className="canvas-label">
+                TARGET — {targetDef ? targetDef.name.replace(/_/g, ' ').toUpperCase() : '—'}
+              </span>
+              <CreaseCanvas
+                paperState={null}
+                target={targetFold}
+                label="TARGET"
+                dim={280}
+                ghostOnly={true}
+              />
+            </div>
+            <div className="canvas-wrap">
+              <span className="canvas-label">
+                {currentStep === 0 ? 'INITIAL STATE' : `STEP ${currentStep} / ${totalSteps}`}
+              </span>
+              <CreaseCanvas
+                paperState={activeStepData ? activeStepData.paper_state : null}
+                target={targetFold}
+                label={currentStep === 0 ? 'INITIAL' : `STEP ${currentStep}`}
+                dim={280}
+                ghostOnly={false}
+              />
+            </div>
+            <div className="canvas-wrap">
+              <div className="canvas-label-row">
+                <span className="canvas-label">3D FOLD PREVIEW</span>
+                <div className="fold-mode-toggle">
+                  <button
+                    className={`fold-mode-btn${foldRenderMode === 'progressive' ? ' active' : ''}`}
+                    onClick={() => setFoldRenderMode('progressive')}
+                    type="button"
+                  >
+                    PER CREASE
+                  </button>
+                  <button
+                    className={`fold-mode-btn${foldRenderMode === 'final' ? ' active' : ''}`}
+                    onClick={() => setFoldRenderMode('final')}
+                    type="button"
+                  >
+                    FOLD AT END
+                  </button>
+                </div>
+              </div>
+              <Fold3DCanvas
+                steps={episode ? episode.steps : []}
+                currentStep={currentStep}
+                totalSteps={totalSteps}
+                mode={foldRenderMode}
+                dim={280}
+              />
+            </div>
+          </div>
+
+          <div className="step-feed-section">
+            <div className="section-header">FOLD SEQUENCE</div>
+            {episodeLoading ? (
+              <div className="episode-loading">
+                <div className="pulse-dot" />
+                FETCHING EPISODE...
+              </div>
+            ) : (
+              <StepFeed
+                steps={episode ? episode.steps : []}
+                currentStep={currentStep}
+              />
+            )}
+          </div>
+        </div>
+
+        <div className="app-right">
+          <div className="section-header">REWARD DECOMPOSITION</div>
+          <RewardPanel reward={activeStepData ? activeStepData.reward : null} />
+          <div className="section-header">EPISODE INFO</div>
+          <InfoBadges info={activeStepData ? activeStepData.info : null} targetDef={targetDef} />
+        </div>
+      </div>
     </div>
   );
 }

src/App.test.js

@@ -1,8 +1 @@
-import { render, screen } from '@testing-library/react';
-import App from './App';
-
-test('renders learn react link', () => {
-  render(<App />);
-  const linkElement = screen.getByText(/learn react/i);
-  expect(linkElement).toBeInTheDocument();
-});
+// Tests removed — observability dashboard

src/components/CreaseCanvas.js

@@ -0,0 +1,113 @@
+const MOUNTAIN = '#f59e0b';
+const VALLEY = '#38bdf8';
+
+function toSvg(x, y, dim) {
+  return [x * dim, (1 - y) * dim];
+}
+
+function GhostEdges({ target, dim }) {
+  if (!target) return null;
+  const { vertices_coords, edges_vertices, edges_assignment } = target;
+  if (!vertices_coords || !edges_vertices || !edges_assignment) return null;
+
+  return edges_vertices.map((ev, i) => {
+    const asgn = edges_assignment[i];
+    if (asgn === 'B') return null;
+    const [v1x, v1y] = vertices_coords[ev[0]];
+    const [v2x, v2y] = vertices_coords[ev[1]];
+    const [x1, y1] = toSvg(v1x, v1y, dim);
+    const [x2, y2] = toSvg(v2x, v2y, dim);
+    const color = asgn === 'M' ? MOUNTAIN : VALLEY;
+    return (
+      <line
+        key={i}
+        x1={x1} y1={y1} x2={x2} y2={y2}
+        stroke={color}
+        strokeOpacity={0.25}
+        strokeWidth={1.5}
+        strokeDasharray="5 4"
+      />
+    );
+  });
+}
+
+function CurrentEdges({ paperState, dim }) {
+  if (!paperState || !paperState.edges) return null;
+  return paperState.edges.map((edge) => {
+    if (edge.assignment === 'B') return null;
+    const [x1, y1] = toSvg(edge.v1[0], edge.v1[1], dim);
+    const [x2, y2] = toSvg(edge.v2[0], edge.v2[1], dim);
+    const color = edge.assignment === 'M' ? MOUNTAIN : VALLEY;
+    return (
+      <line
+        key={edge.id}
+        x1={x1} y1={y1} x2={x2} y2={y2}
+        stroke={color}
+        strokeWidth={2.5}
+        strokeLinecap="square"
+      />
+    );
+  });
+}
+
+function AnchorCrosses({ paperState, dim }) {
+  if (!paperState || !paperState.anchor_points) return null;
+  const size = 4;
+  return paperState.anchor_points.map((pt, i) => {
+    const [cx, cy] = toSvg(pt[0], pt[1], dim);
+    return (
+      <g key={i}>
+        <line
+          x1={cx - size} y1={cy} x2={cx + size} y2={cy}
+          stroke="#64748b" strokeWidth={1}
+        />
+        <line
+          x1={cx} y1={cy - size} x2={cx} y2={cy + size}
+          stroke="#64748b" strokeWidth={1}
+        />
+      </g>
+    );
+  });
+}
+
+export default function CreaseCanvas({ paperState, target, dim = 280, ghostOnly = false }) {
+  const pad = 1;
+  const size = dim;
+
+  return (
+    <svg
+      className="canvas-svg"
+      width={size}
+      height={size}
+      viewBox={`0 0 ${size} ${size}`}
+      style={{ flexShrink: 0 }}
+    >
+      {/* Paper background */}
+      <rect
+        x={pad} y={pad}
+        width={size - pad * 2} height={size - pad * 2}
+        fill="#fafaf5"
+      />
+
+      {/* Ghost target overlay */}
+      <GhostEdges target={target} dim={size} />
+
+      {/* Current paper state */}
+      {!ghostOnly && (
+        <>
+          <CurrentEdges paperState={paperState} dim={size} />
+          <AnchorCrosses paperState={paperState} dim={size} />
+        </>
+      )}
+
+      {/* Paper border */}
+      <rect
+        x={pad} y={pad}
+        width={size - pad * 2} height={size - pad * 2}
+        fill="none"
+        stroke="#2a2a3a"
+        strokeWidth={1}
+      />
+    </svg>
+  );
+}

src/components/Fold3DCanvas.js

@@ -0,0 +1,327 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+const PAPER_RGB = [250, 250, 245];
+const LIGHT_DIR = normalize3([0.4, -0.45, 1.0]);
+const MAX_FOLD_RAD = Math.PI * 0.92;
+const SIDE_EPS = 1e-7;
+const MOUNTAIN_COLOR = 'rgba(245, 158, 11, 0.95)';
+const VALLEY_COLOR = 'rgba(56, 189, 248, 0.95)';
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function normalize3(v) {
+  const mag = Math.hypot(v[0], v[1], v[2]);
+  if (mag < 1e-12) return [0, 0, 0];
+  return [v[0] / mag, v[1] / mag, v[2] / mag];
+}
+
+function cross3(a, b) {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+  ];
+}
+
+function sub3(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+
+function dot3(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+function shadePaper(intensity) {
+  const lit = clamp(0.3 + 0.7 * Math.abs(intensity), 0.0, 1.0);
+  const r = Math.round(PAPER_RGB[0] * lit);
+  const g = Math.round(PAPER_RGB[1] * lit);
+  const b = Math.round(PAPER_RGB[2] * lit);
+  return `rgb(${r}, ${g}, ${b})`;
+}
+
+function buildGridMesh(resolution = 18) {
+  const vertices = [];
+  for (let y = 0; y <= resolution; y += 1) {
+    for (let x = 0; x <= resolution; x += 1) {
+      vertices.push([x / resolution, y / resolution, 0]);
+    }
+  }
+
+  const triangles = [];
+  const stride = resolution + 1;
+  for (let y = 0; y < resolution; y += 1) {
+    for (let x = 0; x < resolution; x += 1) {
+      const a = y * stride + x;
+      const b = a + 1;
+      const c = a + stride;
+      const d = c + 1;
+      triangles.push([a, b, d]);
+      triangles.push([a, d, c]);
+    }
+  }
+
+  return { vertices, triangles, resolution };
+}
+
+function rotateAroundAxis(point, axisPoint, axisDir, angleRad) {
+  const px = point[0] - axisPoint[0];
+  const py = point[1] - axisPoint[1];
+  const pz = point[2] - axisPoint[2];
+
+  const kx = axisDir[0];
+  const ky = axisDir[1];
+  const kz = axisDir[2];
+
+  const cosA = Math.cos(angleRad);
+  const sinA = Math.sin(angleRad);
+
+  const crossX = ky * pz - kz * py;
+  const crossY = kz * px - kx * pz;
+  const crossZ = kx * py - ky * px;
+
+  const dot = px * kx + py * ky + pz * kz;
+  const oneMinus = 1.0 - cosA;
+
+  return [
+    axisPoint[0] + px * cosA + crossX * sinA + kx * dot * oneMinus,
+    axisPoint[1] + py * cosA + crossY * sinA + ky * dot * oneMinus,
+    axisPoint[2] + pz * cosA + crossZ * sinA + kz * dot * oneMinus,
+  ];
+}
+
+function applyFoldToVertices(vertices, fold, progress) {
+  if (!fold || progress <= 0) return;
+  const [x1, y1] = fold.from;
+  const [x2, y2] = fold.to;
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const len = Math.hypot(dx, dy);
+  if (len < 1e-8) return;
+
+  const sideValues = [];
+  let posCount = 0;
+  let negCount = 0;
+
+  for (let i = 0; i < vertices.length; i += 1) {
+    const v = vertices[i];
+    const side = dx * (v[1] - y1) - dy * (v[0] - x1);
+    sideValues.push(side);
+    if (side > SIDE_EPS) posCount += 1;
+    else if (side < -SIDE_EPS) negCount += 1;
+  }
+
+  let rotatePositive = posCount <= negCount;
+  if (posCount === 0 && negCount > 0) rotatePositive = false;
+  if (negCount === 0 && posCount > 0) rotatePositive = true;
+  if (posCount === 0 && negCount === 0) return;
+
+  const sign = fold.assignment === 'V' ? 1 : -1;
+  const angle = sign * MAX_FOLD_RAD * progress;
+  const axisPoint = [x1, y1, 0];
+  const axisDir = [dx / len, dy / len, 0];
+
+  for (let i = 0; i < vertices.length; i += 1) {
+    const side = sideValues[i];
+    const shouldRotate = rotatePositive ? side > SIDE_EPS : side < -SIDE_EPS;
+    if (!shouldRotate) continue;
+    vertices[i] = rotateAroundAxis(vertices[i], axisPoint, axisDir, angle);
+  }
+}
+
+function projectVertex(vertex, dim) {
+  let x = vertex[0] - 0.5;
+  let y = vertex[1] - 0.5;
+  let z = vertex[2];
+
+  const pitch = 1.04;
+  const yaw = -0.78;
+
+  const cp = Math.cos(pitch);
+  const sp = Math.sin(pitch);
+  const y1 = y * cp - z * sp;
+  const z1 = y * sp + z * cp;
+
+  const cy = Math.cos(yaw);
+  const sy = Math.sin(yaw);
+  const x2 = x * cy + z1 * sy;
+  const z2 = -x * sy + z1 * cy;
+
+  const camDist = 2.8;
+  const perspective = camDist / (camDist - z2);
+
+  return {
+    x: dim * 0.5 + x2 * perspective * dim * 0.82,
+    y: dim * 0.52 - y1 * perspective * dim * 0.82,
+    z: z2,
+  };
+}
+
+function foldProgresses(stepValue, foldCount, mode, totalSteps) {
+  const values = new Array(foldCount).fill(0);
+  if (foldCount === 0) return values;
+
+  if (mode === 'final') {
+    const startCollapse = Math.max(totalSteps - 1, 0);
+    const collapse = clamp(stepValue - startCollapse, 0, 1);
+    for (let i = 0; i < foldCount; i += 1) values[i] = collapse;
+    return values;
+  }
+
+  for (let i = 0; i < foldCount; i += 1) {
+    if (stepValue >= i + 1) values[i] = 1;
+    else if (stepValue > i) values[i] = clamp(stepValue - i, 0, 1);
+  }
+  return values;
+}
+
+function stepEasing(t) {
+  return t < 0.5 ? 4 * t * t * t : 1 - ((-2 * t + 2) ** 3) / 2;
+}
+
+export default function Fold3DCanvas({
+  steps,
+  currentStep,
+  totalSteps,
+  mode = 'progressive',
+  dim = 280,
+}) {
+  const canvasRef = useRef(null);
+  const rafRef = useRef(null);
+  const animatedStepRef = useRef(currentStep);
+
+  const folds = useMemo(
+    () => (steps || [])
+      .map((s) => s.fold)
+      .filter(Boolean)
+      .map((fold) => ({
+        from: [Number(fold.from_point[0]), Number(fold.from_point[1])],
+        to: [Number(fold.to_point[0]), Number(fold.to_point[1])],
+        assignment: fold.assignment === 'M' ? 'M' : 'V',
+      })),
+    [steps],
+  );
+
+  const mesh = useMemo(() => buildGridMesh(18), []);
+
+  const draw = useCallback((stepValue) => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    ctx.clearRect(0, 0, dim, dim);
+    ctx.fillStyle = '#121220';
+    ctx.fillRect(0, 0, dim, dim);
+
+    const vertices = mesh.vertices.map((v) => [v[0], v[1], v[2]]);
+    const progress = foldProgresses(stepValue, folds.length, mode, totalSteps);
+
+    for (let i = 0; i < folds.length; i += 1) {
+      if (progress[i] <= 0) continue;
+      applyFoldToVertices(vertices, folds[i], progress[i]);
+    }
+
+    const projected = vertices.map((v) => projectVertex(v, dim));
+
+    const tris = mesh.triangles.map((tri) => {
+      const p0 = projected[tri[0]];
+      const p1 = projected[tri[1]];
+      const p2 = projected[tri[2]];
+      const avgZ = (p0.z + p1.z + p2.z) / 3;
+
+      const v0 = vertices[tri[0]];
+      const v1 = vertices[tri[1]];
+      const v2 = vertices[tri[2]];
+      const normal = normalize3(cross3(sub3(v1, v0), sub3(v2, v0)));
+      const intensity = dot3(normal, LIGHT_DIR);
+
+      return {
+        tri,
+        avgZ,
+        shade: shadePaper(intensity),
+      };
+    });
+
+    tris.sort((a, b) => a.avgZ - b.avgZ);
+
+    for (const triInfo of tris) {
+      const [a, b, c] = triInfo.tri;
+      const p0 = projected[a];
+      const p1 = projected[b];
+      const p2 = projected[c];
+
+      ctx.beginPath();
+      ctx.moveTo(p0.x, p0.y);
+      ctx.lineTo(p1.x, p1.y);
+      ctx.lineTo(p2.x, p2.y);
+      ctx.closePath();
+      ctx.fillStyle = triInfo.shade;
+      ctx.fill();
+      ctx.strokeStyle = 'rgba(42, 42, 58, 0.22)';
+      ctx.lineWidth = 0.55;
+      ctx.stroke();
+    }
+
+    const res = mesh.resolution;
+    const stride = res + 1;
+    const pointToIndex = (pt) => {
+      const ix = clamp(Math.round(pt[0] * res), 0, res);
+      const iy = clamp(Math.round(pt[1] * res), 0, res);
+      return iy * stride + ix;
+    };
+
+    for (let i = 0; i < folds.length; i += 1) {
+      if (progress[i] <= 0.02) continue;
+      const fold = folds[i];
+      const aIdx = pointToIndex(fold.from);
+      const bIdx = pointToIndex(fold.to);
+      const pa = projected[aIdx];
+      const pb = projected[bIdx];
+
+      ctx.beginPath();
+      ctx.moveTo(pa.x, pa.y);
+      ctx.lineTo(pb.x, pb.y);
+      ctx.strokeStyle = fold.assignment === 'M' ? MOUNTAIN_COLOR : VALLEY_COLOR;
+      ctx.globalAlpha = clamp(0.35 + 0.65 * progress[i], 0, 1);
+      ctx.lineWidth = 2.15;
+      ctx.stroke();
+      ctx.globalAlpha = 1;
+    }
+  }, [dim, folds, mesh, mode, totalSteps]);
+
+  useEffect(() => {
+    draw(animatedStepRef.current);
+  }, [draw]);
+
+  useEffect(() => {
+    cancelAnimationFrame(rafRef.current);
+    const startValue = animatedStepRef.current;
+    const endValue = currentStep;
+    const durationMs = 420;
+    const startAt = performance.now();
+
+    const tick = (now) => {
+      const t = clamp((now - startAt) / durationMs, 0, 1);
+      const eased = stepEasing(t);
+      const value = startValue + (endValue - startValue) * eased;
+      animatedStepRef.current = value;
+      draw(value);
+      if (t < 1) rafRef.current = requestAnimationFrame(tick);
+    };
+
+    rafRef.current = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(rafRef.current);
+  }, [currentStep, draw]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      width={dim}
+      height={dim}
+      className="canvas-3d"
+      aria-label="3D fold preview"
+    />
+  );
+}

src/components/InfoBadges.js

@@ -0,0 +1,72 @@
+function BoolVal({ value }) {
+  if (value === null || value === undefined) {
+    return <span className="info-val dim">—</span>;
+  }
+  return (
+    <span className={`info-val ${value ? 'bool-true' : 'bool-false'}`}>
+      {value ? 'TRUE' : 'FALSE'}
+    </span>
+  );
+}
+
+function TextVal({ value, dim = false }) {
+  if (value === null || value === undefined) {
+    return <span className="info-val dim">—</span>;
+  }
+  return (
+    <span className={`info-val${dim ? ' dim' : ''}`}>
+      {String(value).toUpperCase()}
+    </span>
+  );
+}
+
+function NumVal({ value }) {
+  if (value === null || value === undefined) {
+    return <span className="info-val dim">—</span>;
+  }
+  return <span className="info-val">{value}</span>;
+}
+
+export default function InfoBadges({ info, targetDef }) {
+  return (
+    <div className="info-badges">
+      <div className="info-row">
+        <span className="info-key">n_creases</span>
+        <NumVal value={info ? info.n_creases : (targetDef ? targetDef.n_creases : null)} />
+      </div>
+      <div className="info-row">
+        <span className="info-key">interior_verts</span>
+        <NumVal value={info ? info.n_interior_vertices : null} />
+      </div>
+      <div className="info-row">
+        <span className="info-key">local_fold</span>
+        <BoolVal value={info ? info.local_foldability : null} />
+      </div>
+      <div className="info-row">
+        <span className="info-key">blb_sat</span>
+        <BoolVal value={info ? info.blb_satisfied : null} />
+      </div>
+      <div className="info-row">
+        <span className="info-key">global_fold</span>
+        <TextVal
+          value={info ? info.global_foldability : null}
+          dim={true}
+        />
+      </div>
+      {targetDef && (
+        <>
+          <div className="info-row">
+            <span className="info-key">level</span>
+            <span className="info-val">LVL {targetDef.level}</span>
+          </div>
+          <div className="info-row">
+            <span className="info-key">target</span>
+            <span className="info-val" style={{ fontSize: '10px', textAlign: 'right', maxWidth: '140px', wordBreak: 'break-word' }}>
+              {targetDef.name.replace(/_/g, ' ').toUpperCase()}
+            </span>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

src/components/PlayerControls.js

@@ -0,0 +1,54 @@
+export default function PlayerControls({
+  playing,
+  onPlay,
+  onPause,
+  onNext,
+  onPrev,
+  onReset,
+  currentStep,
+  totalSteps,
+  disabled,
+}) {
+  const atStart = currentStep === 0;
+  const atEnd = currentStep >= totalSteps;
+
+  return (
+    <div className="player-controls">
+      <button
+        className="ctrl-btn"
+        onClick={onReset}
+        disabled={disabled || atStart}
+        title="Reset to start"
+      >
+        ⏮ RST
+      </button>
+      <button
+        className="ctrl-btn"
+        onClick={onPrev}
+        disabled={disabled || atStart}
+        title="Previous step"
+      >
+        ◀ PREV
+      </button>
+      <span className="ctrl-step-display">
+        {disabled ? '—/—' : `${currentStep} / ${totalSteps}`}
+      </span>
+      <button
+        className="ctrl-btn"
+        onClick={onNext}
+        disabled={disabled || atEnd}
+        title="Next step"
+      >
+        NEXT ▶
+      </button>
+      <button
+        className={`ctrl-btn play`}
+        onClick={playing ? onPause : onPlay}
+        disabled={disabled || (!playing && atEnd)}
+        title={playing ? 'Pause' : 'Play'}
+      >
+        {playing ? '⏸ PAUSE' : '▶▶ PLAY'}
+      </button>
+    </div>
+  );
+}

src/components/RewardPanel.js

@@ -0,0 +1,50 @@
+const REWARD_FIELDS = [
+  { key: 'kawasaki',   label: 'kawasaki',  color: 'var(--validity)' },
+  { key: 'maekawa',   label: 'maekawa',   color: 'var(--validity)' },
+  { key: 'blb',       label: 'blb',       color: 'var(--validity)' },
+  { key: 'progress',  label: 'progress',  color: 'var(--progress)' },
+  { key: 'economy',   label: 'economy',   color: 'var(--economy)' },
+];
+
+const TOTAL_FIELD = { key: 'total', label: 'total', color: 'var(--text-primary)' };
+
+function RewardRow({ label, color, value }) {
+  const isDash = value === null || value === undefined;
+  const pct = isDash ? 0 : Math.min(Math.max(value, 0), 1) * 100;
+
+  return (
+    <div className="reward-row">
+      <span className="reward-label">{label}</span>
+      <div className="reward-track">
+        <div
+          className="reward-bar"
+          style={{ width: `${pct}%`, background: color }}
+        />
+      </div>
+      <span className={`reward-value${isDash ? ' dim' : ''}`}>
+        {isDash ? '—' : value.toFixed(2)}
+      </span>
+    </div>
+  );
+}
+
+export default function RewardPanel({ reward }) {
+  return (
+    <div className="reward-panel">
+      {REWARD_FIELDS.map(({ key, label, color }) => (
+        <RewardRow
+          key={key}
+          label={label}
+          color={color}
+          value={reward ? reward[key] : null}
+        />
+      ))}
+      <div className="reward-divider" />
+      <RewardRow
+        label={TOTAL_FIELD.label}
+        color={TOTAL_FIELD.color}
+        value={reward ? reward[TOTAL_FIELD.key] : null}
+      />
+    </div>
+  );
+}

src/components/StepFeed.js

@@ -0,0 +1,73 @@
+import { useEffect, useRef } from 'react';
+
+function rewardDelta(step, prevStep) {
+  if (!step || !step.reward) return null;
+  const curr = step.reward.total;
+  if (prevStep && prevStep.reward) {
+    return curr - prevStep.reward.total;
+  }
+  return curr;
+}
+
+export default function StepFeed({ steps, currentStep }) {
+  const feedRef = useRef(null);
+  const activeRef = useRef(null);
+
+  useEffect(() => {
+    if (activeRef.current) {
+      activeRef.current.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    }
+  }, [currentStep]);
+
+  if (!steps || steps.length === 0) {
+    return (
+      <div className="step-feed">
+        <div style={{ padding: '16px', color: 'var(--text-dim)', fontFamily: 'var(--font-display)', fontSize: '11px' }}>
+          NO STEPS LOADED
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="step-feed" ref={feedRef}>
+      {steps.map((step, idx) => {
+        const stepNum = idx + 1;
+        const isActive = currentStep === stepNum;
+        const delta = rewardDelta(step, idx > 0 ? steps[idx - 1] : null);
+        const asgn = step.fold ? step.fold.assignment : null;
+        const instruction = step.fold ? step.fold.instruction : (step.prompt || '');
+
+        return (
+          <div
+            key={stepNum}
+            className={`step-entry${isActive ? ' active' : ''}`}
+            ref={isActive ? activeRef : null}
+          >
+            <div className="step-entry-top">
+              <span className="step-num">#{stepNum}</span>
+              <span className="step-instruction">{instruction}</span>
+              {asgn && (
+                <span className={`assign-badge ${asgn}`}>{asgn}</span>
+              )}
+            </div>
+            {delta !== null && (
+              <div className="step-reward-delta">
+                {'\u0394'} total:{' '}
+                <span className={delta >= 0 ? 'delta-positive' : 'delta-negative'}>
+                  {delta >= 0 ? '+' : ''}{delta.toFixed(3)}
+                </span>
+                {step.reward && (
+                  <span style={{ color: 'var(--text-dim)' }}>
+                    {' '}| progress: {step.reward.progress.toFixed(2)}
+                    {' '}| economy: {step.reward.economy.toFixed(2)}
+                  </span>
+                )}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

src/components/TargetSelector.js

@@ -0,0 +1,38 @@
+function groupByLevel(targets) {
+  const levels = {};
+  Object.values(targets).forEach(t => {
+    if (!levels[t.level]) levels[t.level] = [];
+    levels[t.level].push(t);
+  });
+  return levels;
+}
+
+export default function TargetSelector({ targets, selected, onChange }) {
+  const levels = groupByLevel(targets);
+  const sortedLevels = Object.keys(levels).sort((a, b) => Number(a) - Number(b));
+
+  return (
+    <div className="target-selector">
+      <span className="target-selector-label">TARGET</span>
+      <select
+        className="target-select"
+        value={selected}
+        onChange={e => onChange(e.target.value)}
+      >
+        {sortedLevels.length === 0 ? (
+          <option value="">LOADING...</option>
+        ) : (
+          sortedLevels.map(level => (
+            <optgroup key={level} label={`── LEVEL ${level}`}>
+              {levels[level].map(t => (
+                <option key={t.name} value={t.name}>
+                  {t.name.replace(/_/g, ' ').toUpperCase()}
+                </option>
+              ))}
+            </optgroup>
+          ))
+        )}
+      </select>
+    </div>
+  );
+}

src/index.css

@@ -1,13 +1,34 @@
-body {
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&family=IBM+Plex+Mono:wght@300;400;500&display=swap');
+
+*, *::before, *::after {
+  box-sizing: border-box;
   margin: 0;
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
-    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
-    sans-serif;
+  padding: 0;
+}
+
+body {
+  background: #0d0d14;
+  color: #f8fafc;
+  font-family: 'IBM Plex Mono', monospace;
+  font-size: 13px;
+  line-height: 1.5;
   -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
+  overflow-x: hidden;
+}
+
+::-webkit-scrollbar {
+  width: 4px;
+  height: 4px;
+}
+
+::-webkit-scrollbar-track {
+  background: #0d0d14;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #2a2a3a;
 }
 
-code {
-  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
-    monospace;
+::-webkit-scrollbar-thumb:hover {
+  background: #3a3a5a;
 }

src/reportWebVitals.js

@@ -1,13 +1 @@
-const reportWebVitals = onPerfEntry => {
-  if (onPerfEntry && onPerfEntry instanceof Function) {
-    import('web-vitals').then(({ getCLS, getFID, getFCP, getLCP, getTTFB }) => {
-      getCLS(onPerfEntry);
-      getFID(onPerfEntry);
-      getFCP(onPerfEntry);
-      getLCP(onPerfEntry);
-      getTTFB(onPerfEntry);
-    });
-  }
-};
-
-export default reportWebVitals;
+export default function reportWebVitals() {}

tests/test_graph.py

@@ -0,0 +1,115 @@
+import numpy as np
+import pytest
+from env.graph import CreaseGraph, VERTEX_TOL
+
+
+def test_init_boundary():
+    g = CreaseGraph()
+    assert len(g.vertices) == 4
+    assert len(g.edges) == 4
+    for eid, (v1, v2, assignment) in g.edges.items():
+        assert assignment == 'B'
+    assert g.interior_vertices() == []
+
+
+def test_add_vertex_dedup():
+    g = CreaseGraph()
+    id1 = g.add_vertex(0.5, 0.5)
+    id2 = g.add_vertex(0.5, 0.5)
+    assert id1 == id2
+
+
+def test_add_vertex_dedup_near():
+    g = CreaseGraph()
+    id1 = g.add_vertex(0.5, 0.5)
+    id2 = g.add_vertex(0.5 + VERTEX_TOL * 0.5, 0.5)
+    assert id1 == id2
+
+
+def test_cyclic_order():
+    g = CreaseGraph()
+    center_id = g.add_vertex(0.5, 0.5)
+
+    right_id = g.add_vertex(0.8, 0.5)   # 0 degrees
+    top_id = g.add_vertex(0.5, 0.8)     # 90 degrees
+    left_id = g.add_vertex(0.2, 0.5)    # 180 degrees
+    bottom_id = g.add_vertex(0.5, 0.2)  # 270 degrees / -90 degrees
+
+    e_right = g.add_edge(center_id, right_id, 'M')
+    e_top = g.add_edge(center_id, top_id, 'M')
+    e_left = g.add_edge(center_id, left_id, 'M')
+    e_bottom = g.add_edge(center_id, bottom_id, 'M')
+
+    cyclic = g.get_cyclic_edges(center_id)
+    # Sorted by angle ascending: right(0), top(90), left(180), bottom(-90 → 270)
+    # arctan2 for bottom gives -pi/2 which sorts before 0 in ascending order
+    # So actual ascending order: bottom(-pi/2), right(0), top(pi/2), left(pi)
+    assert len(cyclic) == 4
+
+    def edge_angle(eid):
+        ev1, ev2, _ = g.edges[eid]
+        other_id = ev2 if ev1 == center_id else ev1
+        ox, oy = g.vertices[other_id]
+        cx, cy = g.vertices[center_id]
+        return float(np.arctan2(oy - cy, ox - cx))
+
+    angles = [edge_angle(eid) for eid in cyclic]
+    assert angles == sorted(angles), "Edges should be sorted by ascending angle"
+
+    assert e_right in cyclic
+    assert e_top in cyclic
+    assert e_left in cyclic
+    assert e_bottom in cyclic
+
+    # Verify specific order: bottom < right < top < left in angle space
+    pos = {eid: i for i, eid in enumerate(cyclic)}
+    assert pos[e_bottom] < pos[e_right] < pos[e_top] < pos[e_left]
+
+
+def test_interior_vertices_empty():
+    g = CreaseGraph()
+    assert g.interior_vertices() == []
+
+
+def test_interior_vertices_with_crease_intersection():
+    g = CreaseGraph()
+    center_id = g.add_vertex(0.5, 0.5)
+    assert center_id in g.interior_vertices()
+
+
+def test_split_edge():
+    g = CreaseGraph()
+    # Find the bottom boundary edge (0,0)-(1,0) which is edge 0: v0-v1
+    original_edge_id = None
+    for eid, (v1, v2, assignment) in g.edges.items():
+        x1, y1 = g.vertices[v1]
+        x2, y2 = g.vertices[v2]
+        if {(x1, y1), (x2, y2)} == {(0.0, 0.0), (1.0, 0.0)}:
+            original_edge_id = eid
+            original_v1 = v1
+            original_v2 = v2
+            break
+
+    assert original_edge_id is not None
+
+    mid_id = g.add_vertex(0.5, 0.0)
+    eid1, eid2 = g.split_edge(original_edge_id, mid_id)
+
+    assert original_edge_id not in g.edges
+
+    assert eid1 in g.edges
+    assert eid2 in g.edges
+
+    _, _, a1 = g.edges[eid1]
+    _, _, a2 = g.edges[eid2]
+    assert a1 == 'B'
+    assert a2 == 'B'
+
+    def edge_vertex_set(eid):
+        v1, v2, _ = g.edges[eid]
+        return {v1, v2}
+
+    assert mid_id in edge_vertex_set(eid1)
+    assert mid_id in edge_vertex_set(eid2)
+    assert original_v1 in edge_vertex_set(eid1) or original_v1 in edge_vertex_set(eid2)
+    assert original_v2 in edge_vertex_set(eid1) or original_v2 in edge_vertex_set(eid2)

tests/test_openenv_adapter.py

@@ -0,0 +1,60 @@
+from openenv_runtime.environment import OpenEnvOrigamiEnvironment
+from openenv_runtime.models import OrigamiAction, OrigamiFold, OrigamiObservation
+
+
+def test_openenv_reset_returns_observation():
+    env = OpenEnvOrigamiEnvironment(default_mode="step", max_steps=8)
+    obs = env.reset(target_name="half_horizontal", episode_id="ep-1")
+
+    assert isinstance(obs, OrigamiObservation)
+    assert obs.done is False
+    assert obs.target_name == "half_horizontal"
+    assert "prompt" in obs.model_fields_set
+
+
+def test_openenv_step_single_fold_completes_simple_target():
+    env = OpenEnvOrigamiEnvironment(default_mode="step", max_steps=8)
+    env.reset(target_name="half_horizontal")
+
+    action = OrigamiAction(
+        mode="single",
+        fold=OrigamiFold(
+            from_point=[0.0, 0.5],
+            to_point=[1.0, 0.5],
+            assignment="V",
+            instruction="Valley fold along horizontal center line",
+        ),
+    )
+    obs = env.step(action)
+
+    assert obs.reward is not None
+    assert obs.reward > 1.0
+    assert obs.done is True
+    assert obs.reward_components.get("completion", 0.0) >= 10.0
+
+
+def test_openenv_step_sequence_mode_executes_completion():
+    env = OpenEnvOrigamiEnvironment(default_mode="step", max_steps=8)
+    env.reset(target_name="half_vertical")
+
+    completion = (
+        '<folds>[{"instruction": "Mountain fold vertical center", '
+        '"from": [0.5, 0.0], "to": [0.5, 1.0], "assignment": "M"}]</folds>'
+    )
+
+    obs = env.step(OrigamiAction(mode="sequence", completion=completion))
+
+    assert obs.done is True
+    assert obs.reward is not None
+    assert obs.reward > 1.0
+
+
+def test_openenv_state_contains_targets_and_step_count():
+    env = OpenEnvOrigamiEnvironment(default_mode="step", max_steps=8)
+    env.reset(target_name="half_horizontal", episode_id="ep-state")
+
+    state = env.state
+
+    assert state.episode_id == "ep-state"
+    assert state.step_count == 0
+    assert "half_horizontal" in state.available_targets

tests/test_paper_state.py

@@ -0,0 +1,77 @@
+import pytest
+from env.paper_state import PaperState, UNIT_SQUARE_CORNERS
+from env.graph import VERTEX_TOL
+
+
+def test_single_crease_no_interior_vertices():
+    paper = PaperState()
+    result = paper.add_crease([0.0, 0.5], [1.0, 0.5], 'V')
+    assert result['valid'] is True
+    interior = paper.graph.interior_vertices()
+    assert interior == [], f"Expected no interior vertices, got {interior}"
+
+
+def test_anchor_points_initial():
+    paper = PaperState()
+    anchors = paper.anchor_points()
+    for corner in UNIT_SQUARE_CORNERS:
+        assert any(
+            abs(ax - corner[0]) < VERTEX_TOL and abs(ay - corner[1]) < VERTEX_TOL
+            for ax, ay in anchors
+        ), f"Corner {corner} not found in anchor_points"
+
+
+def test_anchor_points_grow():
+    paper = PaperState()
+    result = paper.add_crease([0.0, 0.5], [1.0, 0.5], 'V')
+    assert result['valid'] is True
+
+    anchors = paper.anchor_points()
+
+    def has_point(px, py):
+        return any(abs(ax - px) < VERTEX_TOL and abs(ay - py) < VERTEX_TOL for ax, ay in anchors)
+
+    assert has_point(0.0, 0.5), "(0, 0.5) should be in anchor_points after crease"
+    assert has_point(1.0, 0.5), "(1, 0.5) should be in anchor_points after crease"
+
+
+def test_invalid_assignment():
+    paper = PaperState()
+    result = paper.add_crease([0.0, 0.5], [1.0, 0.5], 'X')
+    assert result['valid'] is False
+    assert 'invalid_assignment' in result['errors']
+
+
+def test_fold_history():
+    paper = PaperState()
+    paper.add_crease([0.0, 0.5], [1.0, 0.5], 'M')
+    assert len(paper.fold_history) == 1
+
+
+def test_unanchored_returns_false_anchored():
+    paper = PaperState()
+    result = paper.add_crease([0.3, 0.3], [0.7, 0.7], 'M')
+    assert result['anchored'] is False
+
+
+def test_crease_edges_returned():
+    paper = PaperState()
+    paper.add_crease([0.0, 0.5], [1.0, 0.5], 'M')
+    edges = paper.crease_edges()
+    assert len(edges) >= 1
+    for e in edges:
+        assert e['assignment'] in ('M', 'V')
+        assert 'v1' in e
+        assert 'v2' in e
+
+
+def test_two_intersecting_creases():
+    paper = PaperState()
+    r1 = paper.add_crease([0.0, 0.5], [1.0, 0.5], 'M')
+    r2 = paper.add_crease([0.5, 0.0], [0.5, 1.0], 'V')
+    assert r1['valid'] is True
+    assert r2['valid'] is True
+    interior = paper.graph.interior_vertices()
+    assert len(interior) >= 1
+    coords = [paper.graph.vertices[vid] for vid in interior]
+    assert any(abs(x - 0.5) < VERTEX_TOL and abs(y - 0.5) < VERTEX_TOL for x, y in coords)