Origami RL environment with Three.js viewer

.dockerignore

@@ -0,0 +1,8 @@
+.venv/
+.git/
+__pycache__/
+*.pyc
+.pytest_cache/
+outputs/
+*.egg-info/
+.env

Dockerfile

@@ -0,0 +1,18 @@
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+WORKDIR /app
+
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir \
+    "openenv-core[core]>=0.2.1" \
+    "numpy>=1.24" \
+    "scipy>=1.10" \
+    "pydantic>=2.0" \
+    "fastapi>=0.115.0" \
+    "uvicorn>=0.24.0"
+
+COPY . /app
+
+EXPOSE 8000
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,39 @@
 ---
-title: Origami Env
-emoji: ⚡
-colorFrom: pink
-colorTo: red
+title: Origami Env Environment Server
+emoji: 🦢
+colorFrom: red
+colorTo: indigo
 sdk: docker
 pinned: false
+app_port: 8000
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Origami Env
+
+RL environment for origami folding — LLM generates FOLD crease patterns, physics simulates them, reward = shape similarity to target.
+
+## Usage
+
+```python
+from origami_env.client import OrigamiEnv
+from origami_env.models import OrigamiAction
+
+with OrigamiEnv(base_url="http://localhost:8000") as env:
+    result = env.reset(task_name="triangle")
+    result = env.step(OrigamiAction(fold_data={
+        "vertices_coords": [[0,0],[1,0],[1,1],[0,1]],
+        "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]
+    }))
+    print(result.observation.shape_similarity)
+```
+
+## Tasks
+
+- **triangle** — diagonal valley fold
+- **half_fold** — horizontal valley fold at y=0.5
+- **quarter_fold** — two perpendicular valley folds
+- **letter_fold** — two parallel valley folds at y=1/3 and y=2/3

__init__.py

@@ -0,0 +1 @@
+# origami_env — RL environment for origami folding

client.py

@@ -0,0 +1,37 @@
+"""Origami environment client — connects to a running origami_env server."""
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from server.models import OrigamiAction, OrigamiObservation, OrigamiState
+
+
+class OrigamiEnv(EnvClient[OrigamiAction, OrigamiObservation, OrigamiState]):
+    """
+    Client for the origami RL environment.
+
+    Example:
+        >>> with OrigamiEnv(base_url="http://localhost:8000") as env:
+        ...     result = env.reset(task_name="triangle")
+        ...     result = env.step(OrigamiAction(fold_data={...}))
+        ...     print(result.observation.shape_similarity)
+
+        >>> # From HuggingFace Spaces
+        >>> env = OrigamiEnv.from_env("username/origami_env")
+    """
+
+    def _step_payload(self, action: OrigamiAction) -> Dict[str, Any]:
+        return action.model_dump()
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[OrigamiObservation]:
+        obs_data = payload.get("observation", payload)
+        return StepResult(
+            observation=OrigamiObservation(**obs_data),
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> OrigamiState:
+        return OrigamiState(**payload)

models.py

@@ -0,0 +1,5 @@
+"""Re-export models from server.models for OpenEnv client usage."""
+
+from server.models import OrigamiAction, OrigamiObservation, OrigamiState
+
+__all__ = ["OrigamiAction", "OrigamiObservation", "OrigamiState"]

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "origami-env"
+version = "0.1.0"
+description = "RL environment for origami folding — LLM generates FOLD crease patterns"
+requires-python = ">=3.11"
+dependencies = [
+    "openenv-core[core]>=0.2.1",
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "pydantic>=2.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[project.optional-dependencies]
+training = [
+    "trl>=0.7",
+    "datasets>=2.14",
+    "unsloth",
+    "torch",
+    "transformers",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]

server/app.py

@@ -0,0 +1,72 @@
+"""FastAPI entry point — OpenEnv create_app() + custom viewer."""
+
+import os
+from pathlib import Path
+
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from openenv.core.env_server.http_server import create_app
+
+from .environment import OrigamiEnvironment
+from .models import OrigamiAction, OrigamiObservation
+
+app = create_app(
+    OrigamiEnvironment,
+    OrigamiAction,
+    OrigamiObservation,
+    env_name="origami_env",
+)
+
+from .tasks import TASKS
+
+
+@app.get("/tasks")
+def get_tasks():
+    return {
+        name: {
+            "name": task["name"],
+            "description": task["description"],
+            "difficulty": task["difficulty"],
+            "paper": task["paper"],
+            "target_fold": task["target_fold"],
+        }
+        for name, task in TASKS.items()
+    }
+
+
+@app.get("/tasks/{task_name}")
+def get_task_detail(task_name: str):
+    if task_name not in TASKS:
+        from fastapi import HTTPException
+
+        raise HTTPException(status_code=404, detail=f"Task '{task_name}' not found")
+    task = TASKS[task_name]
+    return {
+        "name": task["name"],
+        "description": task["description"],
+        "difficulty": task["difficulty"],
+        "paper": task["paper"],
+        "target_fold": task["target_fold"],
+    }
+
+
+_VIEWER_DIR = Path(__file__).resolve().parent.parent / "viewer"
+if _VIEWER_DIR.is_dir():
+    app.mount("/", StaticFiles(directory=str(_VIEWER_DIR), html=True), name="renderer")
+else:
+
+    @app.get("/", response_class=HTMLResponse)
+    def no_viewer():
+        return HTMLResponse("<h3>Viewer not found</h3><p>API docs at <a href='/docs'>/docs</a></p>")
+
+
+def main():
+    import uvicorn
+
+    port = int(os.environ.get("PORT", 8000))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

server/engine/__init__.py

@@ -0,0 +1,3 @@
+from .simulate import simulate
+from .fold_parser import parse_fold, validate_fold
+from .shape_match import compute_shape_match

server/engine/fold_parser.py

@@ -0,0 +1,180 @@
+"""FOLD JSON parsing and validation.
+
+Validates LLM-generated FOLD crease patterns before simulation.
+FOLD spec: https://github.com/edemaine/fold
+"""
+
+from typing import Any
+
+import numpy as np
+
+
+def validate_fold(fold_data: dict[str, Any]) -> tuple[bool, str]:
+    """Validate a FOLD JSON object. Returns (is_valid, error_message)."""
+
+    # Required fields
+    for key in ("vertices_coords", "edges_vertices", "edges_assignment"):
+        if key not in fold_data:
+            return False, f"Missing required field: {key}"
+
+    verts = fold_data["vertices_coords"]
+    edges = fold_data["edges_vertices"]
+    assignments = fold_data["edges_assignment"]
+
+    # Must have at least 3 vertices (a triangle)
+    if len(verts) < 3:
+        return False, f"Need at least 3 vertices, got {len(verts)}"
+
+    # Must have at least 3 edges
+    if len(edges) < 3:
+        return False, f"Need at least 3 edges, got {len(edges)}"
+
+    # Edges and assignments must match length
+    if len(edges) != len(assignments):
+        return False, (
+            f"edges_vertices ({len(edges)}) and "
+            f"edges_assignment ({len(assignments)}) must match length"
+        )
+
+    # Fold angles must match if present
+    if "edges_foldAngle" in fold_data:
+        angles = fold_data["edges_foldAngle"]
+        if len(angles) != len(edges):
+            return False, (
+                f"edges_foldAngle ({len(angles)}) must match "
+                f"edges_vertices ({len(edges)})"
+            )
+
+    # Validate vertex coordinates (2D or 3D)
+    num_verts = len(verts)
+    for i, v in enumerate(verts):
+        if not isinstance(v, (list, tuple)) or len(v) < 2:
+            return False, f"Vertex {i} must be [x, y] or [x, y, z], got {v}"
+
+    # Validate edge indices
+    for i, e in enumerate(edges):
+        if not isinstance(e, (list, tuple)) or len(e) != 2:
+            return False, f"Edge {i} must be [v1, v2], got {e}"
+        v1, v2 = e
+        if v1 < 0 or v1 >= num_verts or v2 < 0 or v2 >= num_verts:
+            return False, f"Edge {i} references invalid vertex: {e}"
+        if v1 == v2:
+            return False, f"Edge {i} is degenerate (same vertex): {e}"
+
+    # Validate assignments
+    valid_assignments = {"M", "V", "B", "F", "U", "C"}
+    for i, a in enumerate(assignments):
+        if a not in valid_assignments:
+            return False, f"Edge {i} has invalid assignment '{a}'"
+
+    # Must have at least one fold crease (M or V)
+    has_fold = any(a in ("M", "V") for a in assignments)
+    if not has_fold:
+        return False, "No fold creases (M or V) found"
+
+    # Must have boundary edges
+    has_boundary = any(a == "B" for a in assignments)
+    if not has_boundary:
+        return False, "No boundary edges (B) found"
+
+    return True, ""
+
+
+def parse_fold(fold_data: dict[str, Any]) -> dict[str, np.ndarray]:
+    """Parse validated FOLD JSON into numpy arrays for simulation.
+
+    Returns dict with:
+        vertices: (N, 3) float64 — vertex positions (z=0 for 2D input)
+        edges: (E, 2) int — edge vertex indices
+        assignments: list[str] — edge type per edge
+        fold_angles: (E,) float64 — target fold angle per edge (degrees)
+        faces: (F, 3) int — triangulated face vertex indices
+    """
+    verts = fold_data["vertices_coords"]
+
+    # Ensure 3D (add z=0 if 2D)
+    vertices = np.zeros((len(verts), 3), dtype=np.float64)
+    for i, v in enumerate(verts):
+        vertices[i, 0] = v[0]
+        vertices[i, 1] = v[1]
+        if len(v) > 2:
+            vertices[i, 2] = v[2]
+
+    edges = np.array(fold_data["edges_vertices"], dtype=np.int32)
+    assignments = list(fold_data["edges_assignment"])
+
+    # Fold angles: default based on assignment if not provided
+    if "edges_foldAngle" in fold_data:
+        fold_angles = np.array(fold_data["edges_foldAngle"], dtype=np.float64)
+    else:
+        fold_angles = np.zeros(len(edges), dtype=np.float64)
+        for i, a in enumerate(assignments):
+            if a == "V":
+                fold_angles[i] = 180.0
+            elif a == "M":
+                fold_angles[i] = -180.0
+
+    # Convert degrees to radians for simulation
+    fold_angles_rad = np.radians(fold_angles)
+
+    # Triangulate faces
+    if "faces_vertices" in fold_data:
+        raw_faces = fold_data["faces_vertices"]
+        faces = _triangulate_faces(raw_faces)
+    else:
+        faces = _compute_faces(vertices, edges)
+
+    return {
+        "vertices": vertices,
+        "edges": edges,
+        "assignments": assignments,
+        "fold_angles": fold_angles_rad,
+        "faces": faces,
+    }
+
+
+def _triangulate_faces(raw_faces: list[list[int]]) -> np.ndarray:
+    """Fan-triangulate polygon faces into triangles."""
+    triangles = []
+    for face in raw_faces:
+        if len(face) < 3:
+            continue
+        for i in range(1, len(face) - 1):
+            triangles.append([face[0], face[i], face[i + 1]])
+    if not triangles:
+        return np.zeros((0, 3), dtype=np.int32)
+    return np.array(triangles, dtype=np.int32)
+
+
+def _compute_faces(vertices: np.ndarray, edges: np.ndarray) -> np.ndarray:
+    """Compute triangulated faces from vertices and edges using adjacency.
+
+    Finds all triangles formed by the edge connectivity.
+    """
+    from collections import defaultdict
+
+    n_verts = len(vertices)
+    adj = defaultdict(set)
+    for v1, v2 in edges:
+        adj[v1].add(v2)
+        adj[v2].add(v1)
+
+    triangles = set()
+    for v1, v2 in edges:
+        common = adj[v1] & adj[v2]
+        for v3 in common:
+            tri = tuple(sorted([v1, v2, v3]))
+            triangles.add(tri)
+
+    if not triangles:
+        # Fallback: create faces using Delaunay on 2D projection
+        from scipy.spatial import Delaunay
+
+        pts_2d = vertices[:, :2]
+        try:
+            tri = Delaunay(pts_2d)
+            return tri.simplices.astype(np.int32)
+        except Exception:
+            return np.zeros((0, 3), dtype=np.int32)
+
+    return np.array(list(triangles), dtype=np.int32)

server/engine/shape_match.py

@@ -0,0 +1,101 @@
+"""Shape matching for reward computation.
+
+Computes similarity between the LLM's folded shape and the target shape.
+Like AlphaFold's RMSD but for origami vertex positions.
+"""
+
+import numpy as np
+from scipy.spatial.distance import cdist
+
+
+def compute_shape_match(
+    predicted: np.ndarray,
+    target: np.ndarray,
+) -> float:
+    """Compute shape similarity between predicted and target positions.
+
+    Uses chamfer distance normalized by bounding box diagonal.
+    Aligns shapes by centering before comparison.
+
+    Args:
+        predicted: (N, 3) predicted vertex positions.
+        target: (M, 3) target vertex positions.
+
+    Returns:
+        Similarity score in [0, 1]. 1.0 = perfect match.
+    """
+    if len(predicted) == 0 or len(target) == 0:
+        return 0.0
+
+    # Center both point clouds
+    pred_centered = predicted - predicted.mean(axis=0)
+    target_centered = target - target.mean(axis=0)
+
+    # Try multiple rotations and pick best match
+    # (the LLM's pattern might produce a rotated version of the target)
+    best_score = 0.0
+    for rotation in _get_alignment_rotations():
+        rotated = pred_centered @ rotation.T
+        score = _chamfer_similarity(rotated, target_centered)
+        best_score = max(best_score, score)
+
+    return best_score
+
+
+def _chamfer_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Chamfer distance converted to similarity score.
+
+    Chamfer = average nearest-neighbor distance (bidirectional).
+    Similarity = 1 - (chamfer / diagonal), clamped to [0, 1].
+    """
+    d = cdist(a, b)
+
+    # Forward: for each point in a, min distance to b
+    forward = d.min(axis=1).mean()
+    # Backward: for each point in b, min distance to a
+    backward = d.min(axis=0).mean()
+    chamfer = (forward + backward) / 2.0
+
+    # Normalize by bounding box diagonal of target
+    all_pts = np.vstack([a, b])
+    bbox_diag = np.linalg.norm(all_pts.max(axis=0) - all_pts.min(axis=0))
+    if bbox_diag < 1e-12:
+        return 1.0 if chamfer < 1e-12 else 0.0
+
+    similarity = max(0.0, 1.0 - chamfer / bbox_diag)
+    return similarity
+
+
+def _get_alignment_rotations() -> list[np.ndarray]:
+    """Generate rotation matrices for alignment search.
+
+    We check identity + 90° rotations around each axis (24 orientations).
+    This handles cases where the LLM's fold produces a rotated version.
+    """
+    I = np.eye(3)
+    rotations = [I]
+
+    # 90° rotations around Z axis
+    for k in range(1, 4):
+        angle = k * np.pi / 2
+        c, s = np.cos(angle), np.sin(angle)
+        rotations.append(np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]]))
+
+    # 90° rotations around X axis
+    for k in range(1, 4):
+        angle = k * np.pi / 2
+        c, s = np.cos(angle), np.sin(angle)
+        rotations.append(np.array([[1, 0, 0], [0, c, -s], [0, s, c]]))
+
+    # 90° rotations around Y axis
+    for k in range(1, 4):
+        angle = k * np.pi / 2
+        c, s = np.cos(angle), np.sin(angle)
+        rotations.append(np.array([[c, 0, s], [0, 1, 0], [-s, 0, c]]))
+
+    # Flip (mirror)
+    rotations.append(np.diag([-1, 1, 1]))
+    rotations.append(np.diag([1, -1, 1]))
+    rotations.append(np.diag([1, 1, -1]))
+
+    return rotations

server/engine/simulate.py

@@ -0,0 +1,175 @@
+"""Origami fold simulator — analytical rotation with cumulative transforms.
+
+BFS from face 0 through the face adjacency graph. Each face accumulates
+a rotation transform (R, t) such that: folded_pos = R @ flat_pos + t.
+When crossing a fold edge, the fold rotation is composed with the parent
+face's transform. Non-fold edges inherit the parent's transform directly.
+
+This correctly handles multiple intersecting folds (e.g. quarter fold)
+because each face's transform captures ALL upstream folds.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+
+from .fold_parser import parse_fold
+
+
+@dataclass
+class SimResult:
+    """Result of a fold simulation."""
+
+    positions: np.ndarray  # (N, 3) final vertex positions
+    converged: bool
+    steps_taken: int
+    max_strain: float
+    total_energy: float
+
+
+def simulate(
+    fold_data: dict,
+    crease_percent: float = 1.0,
+    max_steps: int = 500,
+    params: dict | None = None,
+) -> SimResult:
+    """Simulate a FOLD crease pattern and return final 3D positions.
+
+    Uses cumulative rotation transforms per face. BFS from face 0,
+    composing fold rotations at each crease edge.
+
+    Args:
+        fold_data: FOLD-format dict with vertices, edges, assignments, angles.
+        crease_percent: 0.0 = flat, 1.0 = fully folded.
+        max_steps: Unused (kept for API compat).
+        params: Unused (kept for API compat).
+
+    Returns:
+        SimResult with final positions, strain info.
+    """
+    parsed = parse_fold(fold_data)
+    flat_pos = parsed["vertices"].copy()
+    edges = parsed["edges"]
+    assignments = parsed["assignments"]
+    fold_angles = parsed["fold_angles"]
+    faces = parsed["faces"]
+    positions = flat_pos.copy()
+
+    if len(faces) == 0:
+        return SimResult(
+            positions=positions, converged=True,
+            steps_taken=0, max_strain=0.0, total_energy=0.0,
+        )
+
+    # Build face adjacency: edge -> [face_idx, ...]
+    face_adj = _build_face_adjacency(faces)
+
+    # Build crease map: (v_min, v_max) -> fold_angle_rad * crease_percent
+    crease_map: dict[tuple[int, int], float] = {}
+    for i, (v1, v2) in enumerate(edges):
+        key = (min(int(v1), int(v2)), max(int(v1), int(v2)))
+        if assignments[i] in ("M", "V"):
+            crease_map[key] = fold_angles[i] * crease_percent
+
+    # Per-face cumulative transform: folded = R @ flat + t
+    n_faces = len(faces)
+    face_R = [None] * n_faces
+    face_t = [None] * n_faces
+
+    # Face 0 is fixed (identity transform)
+    face_R[0] = np.eye(3)
+    face_t[0] = np.zeros(3)
+
+    visited = [False] * n_faces
+    visited[0] = True
+
+    placed: set[int] = set()
+    for vi in faces[0]:
+        placed.add(int(vi))
+
+    queue = [0]
+    while queue:
+        fi = queue.pop(0)
+        face = faces[fi]
+
+        for j in range(len(face)):
+            v1, v2 = int(face[j]), int(face[(j + 1) % len(face)])
+            edge_key = (min(v1, v2), max(v1, v2))
+
+            for fj in face_adj.get(edge_key, []):
+                if visited[fj]:
+                    continue
+                visited[fj] = True
+                queue.append(fj)
+
+                angle = crease_map.get(edge_key, 0.0)
+
+                if abs(angle) > 1e-10:
+                    # Fold rotation around the edge in folded space
+                    p1 = positions[v1].copy()
+                    axis = positions[v2] - p1
+                    axis_len = np.linalg.norm(axis)
+                    if axis_len > 1e-12:
+                        axis_unit = axis / axis_len
+                        fold_rot = Rotation.from_rotvec(
+                            angle * axis_unit,
+                        ).as_matrix()
+                    else:
+                        fold_rot = np.eye(3)
+
+                    # Compose: R_fj = fold_rot @ R_fi, t_fj adjusted for pivot
+                    face_R[fj] = fold_rot @ face_R[fi]
+                    face_t[fj] = fold_rot @ (face_t[fi] - p1) + p1
+                else:
+                    # No fold — inherit parent's transform
+                    face_R[fj] = face_R[fi].copy()
+                    face_t[fj] = face_t[fi].copy()
+
+                # Place unplaced vertices using this face's transform
+                for vi in faces[fj]:
+                    vi_int = int(vi)
+                    if vi_int not in placed:
+                        positions[vi_int] = face_R[fj] @ flat_pos[vi_int] + face_t[fj]
+                        placed.add(vi_int)
+
+    # Compute strain (deviation from rest edge lengths)
+    max_strain = _compute_strain(positions, parsed)
+
+    return SimResult(
+        positions=positions,
+        converged=True,
+        steps_taken=1,
+        max_strain=max_strain,
+        total_energy=0.0,
+    )
+
+
+def _build_face_adjacency(
+    faces: np.ndarray,
+) -> dict[tuple[int, int], list[int]]:
+    """Map each edge (sorted vertex pair) to list of face indices."""
+    adj: dict[tuple[int, int], list[int]] = {}
+    for fi, face in enumerate(faces):
+        n = len(face)
+        for j in range(n):
+            v1, v2 = int(face[j]), int(face[(j + 1) % n])
+            key = (min(v1, v2), max(v1, v2))
+            if key not in adj:
+                adj[key] = []
+            adj[key].append(fi)
+    return adj
+
+
+def _compute_strain(positions: np.ndarray, parsed: dict) -> float:
+    """Compute max axial strain across all edges."""
+    edges = parsed["edges"]
+    vertices_flat = parsed["vertices"]
+    max_strain = 0.0
+    for v1, v2 in edges:
+        rest = np.linalg.norm(vertices_flat[v2] - vertices_flat[v1])
+        curr = np.linalg.norm(positions[v2] - positions[v1])
+        if rest > 1e-12:
+            strain = abs(curr - rest) / rest
+            max_strain = max(max_strain, strain)
+    return max_strain

server/environment.py

@@ -0,0 +1,169 @@
+"""Origami RL Environment — OpenEnv Environment subclass.
+
+Single-shot episodes: LLM submits a FOLD crease pattern, physics simulates it,
+reward = shape similarity to target. Like AlphaFold for origami.
+"""
+
+import uuid
+from typing import Any, Optional
+
+import numpy as np
+from openenv.core import Environment
+
+from .engine.fold_parser import validate_fold
+from .engine.shape_match import compute_shape_match
+from .engine.simulate import SimResult, simulate
+from .models import OrigamiAction, OrigamiObservation, OrigamiState
+from .tasks import get_task
+
+
+class OrigamiEnvironment(
+    Environment[OrigamiAction, OrigamiObservation, OrigamiState]
+):
+    """Origami folding environment.
+
+    Episode flow:
+        1. reset(task_name="triangle") → returns task description + target info
+        2. step(OrigamiAction(fold_data={...})) → simulates, scores, returns done=True
+
+    Single action per episode. The action IS the complete crease pattern.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        self._state = OrigamiState()
+        self._task: dict = {}
+        self._target_positions: np.ndarray = np.zeros((0, 3))
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> OrigamiObservation:
+        """Start a new episode with a target shape task."""
+        self._state = OrigamiState(
+            episode_id=episode_id or str(uuid.uuid4()),
+            step_count=0,
+        )
+
+        # Get task
+        task_name = kwargs.get("task_name", "triangle")
+        self._task = get_task(task_name)
+        self._state.task_name = self._task["name"]
+
+        # Simulate the target FOLD to get target positions
+        target_fold = self._task["target_fold"]
+        try:
+            target_result = simulate(target_fold, crease_percent=1.0)
+            self._target_positions = target_result.positions
+        except Exception as e:
+            self._target_positions = np.zeros((0, 3))
+
+        return OrigamiObservation(
+            done=False,
+            reward=None,
+            task={
+                "name": self._task["name"],
+                "description": self._task["description"],
+                "difficulty": self._task["difficulty"],
+                "paper": self._task["paper"],
+            },
+            fold_data={},
+            final_positions=[],
+            target_positions=self._target_positions.tolist(),
+            shape_similarity=0.0,
+            max_strain=0.0,
+            is_stable=True,
+            error=None,
+        )
+
+    def step(
+        self,
+        action: OrigamiAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> OrigamiObservation:
+        """Evaluate the LLM's crease pattern.
+
+        1. Validate FOLD data
+        2. Run physics simulation (creasePercent=1.0)
+        3. Compare final shape to target
+        4. Return observation with reward = similarity × 20
+        """
+        self._state.step_count += 1
+        fold_data = action.fold_data
+
+        # Validate
+        is_valid, error_msg = validate_fold(fold_data)
+        if not is_valid:
+            self._state.is_stable = False
+            return OrigamiObservation(
+                done=True,
+                reward=-2.0,
+                task=self._task_info(),
+                fold_data=fold_data,
+                final_positions=[],
+                target_positions=self._target_positions.tolist(),
+                shape_similarity=0.0,
+                max_strain=0.0,
+                is_stable=False,
+                error=f"Invalid FOLD data: {error_msg}",
+            )
+
+        # Simulate
+        try:
+            result: SimResult = simulate(fold_data, crease_percent=1.0)
+        except Exception as e:
+            self._state.is_stable = False
+            return OrigamiObservation(
+                done=True,
+                reward=-2.0,
+                task=self._task_info(),
+                fold_data=fold_data,
+                final_positions=[],
+                target_positions=self._target_positions.tolist(),
+                shape_similarity=0.0,
+                max_strain=0.0,
+                is_stable=False,
+                error=f"Simulation error: {str(e)}",
+            )
+
+        # Shape match
+        similarity = compute_shape_match(
+            result.positions, self._target_positions
+        )
+        reward = similarity * 20.0
+
+        self._state.shape_similarity = similarity
+        self._state.is_stable = result.converged
+
+        return OrigamiObservation(
+            done=True,
+            reward=reward,
+            task=self._task_info(),
+            fold_data=fold_data,
+            final_positions=result.positions.tolist(),
+            target_positions=self._target_positions.tolist(),
+            shape_similarity=similarity,
+            max_strain=result.max_strain,
+            is_stable=result.converged,
+            error=None,
+        )
+
+    @property
+    def state(self) -> OrigamiState:
+        return self._state
+
+    def _task_info(self) -> dict:
+        """Task info dict for observations."""
+        if not self._task:
+            return {}
+        return {
+            "name": self._task.get("name", ""),
+            "description": self._task.get("description", ""),
+            "difficulty": self._task.get("difficulty", 0),
+            "paper": self._task.get("paper", {}),
+        }

server/models.py

@@ -0,0 +1,54 @@
+"""OpenEnv types for the Origami RL environment.
+
+OrigamiAction: LLM submits a FOLD crease pattern.
+OrigamiObservation: Result of simulating that pattern against a target.
+OrigamiState: Internal episode state.
+"""
+
+from typing import Any, Optional
+
+from openenv.core import Action, Observation, State
+from pydantic import Field
+
+
+class OrigamiAction(Action):
+    """LLM submits a FOLD crease pattern as its action.
+
+    The fold_data dict must contain:
+      - vertices_coords: [[x, y], ...] — 2D vertex positions on flat paper
+      - edges_vertices: [[v1, v2], ...] — edge connectivity
+      - edges_assignment: ["B"|"M"|"V", ...] — boundary/mountain/valley
+      - edges_foldAngle: [angle, ...] — target fold angles in degrees
+        (optional — defaults from assignment: M=-180, V=+180, B=0)
+    """
+
+    fold_data: dict[str, Any] = Field(
+        ..., description="FOLD-format crease pattern JSON"
+    )
+
+
+class OrigamiObservation(Observation):
+    """Result of simulating the LLM's crease pattern.
+
+    Contains everything the viewer and reward function need:
+    - The submitted fold data and simulation results
+    - Target shape for overlay comparison
+    - Shape similarity score (the reward signal)
+    """
+
+    task: dict[str, Any] = Field(default_factory=dict)
+    fold_data: dict[str, Any] = Field(default_factory=dict)
+    final_positions: list[list[float]] = Field(default_factory=list)
+    target_positions: list[list[float]] = Field(default_factory=list)
+    shape_similarity: float = 0.0
+    max_strain: float = 0.0
+    is_stable: bool = True
+    error: Optional[str] = None
+
+
+class OrigamiState(State):
+    """Internal state for an origami episode."""
+
+    task_name: str = ""
+    shape_similarity: float = 0.0
+    is_stable: bool = True

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv-core>=0.2.1
+numpy>=1.24
+scipy>=1.10
+pydantic>=2.0
+fastapi>=0.100
+uvicorn>=0.22

server/tasks.py

@@ -0,0 +1,123 @@
+"""Task definitions for origami RL training.
+
+Each task defines a target shape as a reference FOLD crease pattern.
+The LLM must discover a crease pattern that folds into the same shape.
+
+Starting simple (triangle) and progressing to harder folds.
+"""
+
+TASKS: dict[str, dict] = {
+    "triangle": {
+        "name": "triangle",
+        "description": "Fold the paper in half diagonally to make a triangle",
+        "difficulty": 1,
+        "paper": {"width": 1.0, "height": 1.0},
+        "target_fold": {
+            "vertices_coords": [[0, 0], [1, 0], [1, 1], [0, 1]],
+            "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]],
+        },
+    },
+    "half_fold": {
+        "name": "half_fold",
+        "description": "Fold the paper in half horizontally",
+        "difficulty": 1,
+        "paper": {"width": 1.0, "height": 1.0},
+        "target_fold": {
+            "vertices_coords": [
+                [0, 0], [1, 0], [1, 1], [0, 1], [0, 0.5], [1, 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]],
+        },
+    },
+    "quarter_fold": {
+        "name": "quarter_fold",
+        "description": "Fold the paper into quarters (two perpendicular folds)",
+        "difficulty": 2,
+        "paper": {"width": 1.0, "height": 1.0},
+        "target_fold": {
+            "vertices_coords": [
+                [0, 0], [0.5, 0], [1, 0],
+                [0, 0.5], [0.5, 0.5], [1, 0.5],
+                [0, 1], [0.5, 1], [1, 1],
+            ],
+            "edges_vertices": [
+                # Boundary
+                [0, 1], [1, 2], [2, 5], [5, 8], [8, 7], [7, 6], [6, 3], [3, 0],
+                # Fold lines
+                [1, 4], [4, 7],  # vertical fold
+                [3, 4], [4, 5],  # horizontal fold
+            ],
+            "edges_assignment": [
+                "B", "B", "B", "B", "B", "B", "B", "B",
+                "V", "V", "V", "V",
+            ],
+            "edges_foldAngle": [
+                0, 0, 0, 0, 0, 0, 0, 0,
+                180, 180, 180, 180,
+            ],
+            "faces_vertices": [
+                [0, 1, 4, 3],  # bottom-left
+                [1, 2, 5, 4],  # bottom-right
+                [3, 4, 7, 6],  # top-left
+                [4, 5, 8, 7],  # top-right
+            ],
+        },
+    },
+    "letter_fold": {
+        "name": "letter_fold",
+        "description": "Tri-fold the paper like a letter (two parallel folds)",
+        "difficulty": 2,
+        "paper": {"width": 1.0, "height": 1.0},
+        "target_fold": {
+            "vertices_coords": [
+                [0, 0], [1, 0],
+                [0, 1/3], [1, 1/3],
+                [0, 2/3], [1, 2/3],
+                [0, 1], [1, 1],
+            ],
+            "edges_vertices": [
+                # Boundary
+                [0, 1], [1, 3], [3, 5], [5, 7], [7, 6], [6, 4], [4, 2], [2, 0],
+                # Fold lines
+                [2, 3],  # first fold (valley)
+                [4, 5],  # second fold (mountain)
+            ],
+            "edges_assignment": [
+                "B", "B", "B", "B", "B", "B", "B", "B",
+                "V", "M",
+            ],
+            "edges_foldAngle": [
+                0, 0, 0, 0, 0, 0, 0, 0,
+                180, -180,
+            ],
+            "faces_vertices": [
+                [0, 1, 3, 2],  # bottom strip
+                [2, 3, 5, 4],  # middle strip
+                [4, 5, 7, 6],  # top strip
+            ],
+        },
+    },
+}
+
+
+def get_task(name: str | None = None) -> dict:
+    """Get a task by name. Defaults to 'triangle'."""
+    if name is None:
+        name = "triangle"
+    if name not in TASKS:
+        raise ValueError(f"Unknown task '{name}'. Available: {list(TASKS.keys())}")
+    return TASKS[name]
+
+
+def list_tasks() -> list[str]:
+    """List all available task names."""
+    return list(TASKS.keys())

tests/test_origami.py

@@ -0,0 +1,292 @@
+"""Tests for origami RL environment."""
+
+import numpy as np
+import pytest
+
+from server.engine.fold_parser import parse_fold, validate_fold
+from server.engine.shape_match import compute_shape_match
+from server.engine.simulate import simulate
+from server.environment import OrigamiEnvironment
+from server.models import OrigamiAction
+from server.tasks import TASKS, get_task, list_tasks
+from training.reward import extract_fold_json, shape_match, valid_fold
+
+# --- Fixtures ---
+
+TRIANGLE_FOLD = {
+    "vertices_coords": [[0, 0], [1, 0], [1, 1], [0, 1]],
+    "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],
+}
+
+HALF_FOLD = {
+    "vertices_coords": [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0.5], [1, 0.5]],
+    "edges_vertices": [[0, 1], [1, 5], [5, 4], [4, 0], [4, 3], [3, 2], [2, 5], [4, 5]],
+    "edges_assignment": ["B", "B", "B", "B", "B", "B", "B", "V"],
+    "edges_foldAngle": [0, 0, 0, 0, 0, 0, 0, 180],
+}
+
+
+# --- Validation ---
+
+
+class TestValidation:
+    def test_valid_fold_accepted(self):
+        valid, err = validate_fold(TRIANGLE_FOLD)
+        assert valid, err
+
+    def test_missing_field_rejected(self):
+        valid, _ = validate_fold({"vertices_coords": [[0, 0]]})
+        assert not valid
+
+    def test_no_creases_rejected(self):
+        valid, _ = validate_fold(
+            {
+                "vertices_coords": [[0, 0], [1, 0], [1, 1]],
+                "edges_vertices": [[0, 1], [1, 2], [2, 0]],
+                "edges_assignment": ["B", "B", "B"],
+            }
+        )
+        assert not valid
+
+    def test_bad_vertex_index_rejected(self):
+        valid, _ = validate_fold(
+            {
+                "vertices_coords": [[0, 0], [1, 0], [1, 1]],
+                "edges_vertices": [[0, 1], [1, 2], [2, 99]],
+                "edges_assignment": ["B", "B", "V"],
+            }
+        )
+        assert not valid
+
+    def test_degenerate_edge_rejected(self):
+        valid, _ = validate_fold(
+            {
+                "vertices_coords": [[0, 0], [1, 0], [1, 1]],
+                "edges_vertices": [[0, 1], [1, 1], [1, 2]],
+                "edges_assignment": ["B", "V", "B"],
+            }
+        )
+        assert not valid
+
+
+# --- Parsing ---
+
+
+class TestParsing:
+    def test_parse_creates_3d_vertices(self):
+        p = parse_fold(TRIANGLE_FOLD)
+        assert p["vertices"].shape == (4, 3)
+        assert np.allclose(p["vertices"][:, 2], 0)
+
+    def test_parse_computes_faces(self):
+        p = parse_fold(TRIANGLE_FOLD)
+        assert len(p["faces"]) >= 2
+
+    def test_parse_angles_in_radians(self):
+        p = parse_fold(TRIANGLE_FOLD)
+        assert abs(p["fold_angles"][4] - np.pi) < 0.01
+
+
+# --- Physics ---
+
+
+class TestPhysics:
+    def test_flat_stays_flat(self):
+        r = simulate(TRIANGLE_FOLD, crease_percent=0.0, max_steps=100)
+        assert np.max(np.abs(r.positions[:, 2])) < 0.01
+
+    def test_fold_creates_z_displacement(self):
+        # A partial fold (90°) creates z displacement; full 180° folds flat
+        r = simulate(TRIANGLE_FOLD, crease_percent=0.5, max_steps=2000)
+        z_range = r.positions[:, 2].max() - r.positions[:, 2].min()
+        assert z_range > 0.1
+
+    def test_valley_fold_brings_vertices_together(self):
+        r = simulate(TRIANGLE_FOLD, crease_percent=1.0, max_steps=2000)
+        dist = np.linalg.norm(r.positions[1] - r.positions[3])
+        assert dist < 0.1
+
+    def test_half_fold_works(self):
+        # Full fold: top vertices should overlap bottom vertices
+        r = simulate(HALF_FOLD, crease_percent=1.0, max_steps=2000)
+        # v2=[1,1] should fold onto v1=[1,0], v3=[0,1] onto v0=[0,0]
+        dist = np.linalg.norm(r.positions[2] - r.positions[1])
+        assert dist < 0.1, f"v2 didn't fold onto v1 (dist={dist})"
+
+    def test_all_tasks_fold(self):
+        for name, task in TASKS.items():
+            r = simulate(task["target_fold"], crease_percent=1.0, max_steps=2000)
+            assert r.converged, f"Task {name} did not converge"
+            assert r.max_strain < 0.01, f"Task {name} has high strain ({r.max_strain})"
+            # Partial fold should produce z displacement
+            r_half = simulate(task["target_fold"], crease_percent=0.5)
+            z_range = r_half.positions[:, 2].max() - r_half.positions[:, 2].min()
+            assert z_range > 0.01, f"Task {name} partial fold no z (z_range={z_range})"
+
+
+# --- Shape Match ---
+
+
+class TestShapeMatch:
+    def test_same_shape_perfect_match(self):
+        r = simulate(TRIANGLE_FOLD, crease_percent=1.0, max_steps=2000)
+        sim = compute_shape_match(r.positions, r.positions)
+        assert sim > 0.99
+
+    def test_different_shapes_lower_match(self):
+        target = simulate(TRIANGLE_FOLD, crease_percent=1.0, max_steps=2000)
+        wrong = simulate(HALF_FOLD, crease_percent=1.0, max_steps=2000)
+        sim = compute_shape_match(wrong.positions, target.positions)
+        assert sim < 0.95
+
+    def test_flat_vs_folded_lower_match(self):
+        target = simulate(TRIANGLE_FOLD, crease_percent=1.0, max_steps=2000)
+        flat = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]], dtype=float)
+        sim = compute_shape_match(flat, target.positions)
+        assert sim < 0.95
+
+
+# --- Environment ---
+
+
+class TestEnvironment:
+    def test_reset(self):
+        env = OrigamiEnvironment()
+        obs = env.reset(task_name="triangle")
+        assert not obs.done
+        assert obs.reward is None
+        assert len(obs.target_positions) > 0
+
+    def test_step_correct_fold(self):
+        env = OrigamiEnvironment()
+        env.reset(task_name="triangle")
+        obs = env.step(OrigamiAction(fold_data=TRIANGLE_FOLD))
+        assert obs.done
+        assert obs.reward == 20.0
+        assert obs.shape_similarity == 1.0
+
+    def test_step_invalid_fold(self):
+        env = OrigamiEnvironment()
+        env.reset(task_name="triangle")
+        obs = env.step(OrigamiAction(fold_data={"bad": True}))
+        assert obs.done
+        assert obs.reward == -2.0
+        assert obs.error is not None
+
+    def test_state(self):
+        env = OrigamiEnvironment()
+        env.reset(task_name="triangle")
+        assert env.state.task_name == "triangle"
+
+
+# --- Tasks ---
+
+
+class TestTasks:
+    def test_four_tasks(self):
+        assert len(list_tasks()) == 4
+
+    def test_get_task(self):
+        task = get_task("triangle")
+        assert task["name"] == "triangle"
+
+    def test_invalid_task_raises(self):
+        with pytest.raises(ValueError):
+            get_task("nonexistent")
+
+
+# --- Rewards ---
+
+
+class TestRewards:
+    def test_extract_json_fenced(self):
+        text = '```json\n{"vertices_coords": [[0, 0]]}\n```'
+        assert extract_fold_json(text) is not None
+
+    def test_extract_json_raw(self):
+        text = '{"vertices_coords": [[0, 0]]}'
+        assert extract_fold_json(text) is not None
+
+    def test_extract_none_garbage(self):
+        assert extract_fold_json("no json here") is None
+
+    def test_valid_fold_reward(self):
+        import json
+
+        good = [[{"content": json.dumps(TRIANGLE_FOLD)}]]
+        bad = [[{"content": "nope"}]]
+        scores = valid_fold(good + bad)
+        assert scores[0] == 1.0
+        assert scores[1] == -2.0
+
+    def test_shape_match_reward(self):
+        import json
+
+        good = [[{"content": json.dumps(TRIANGLE_FOLD)}]]
+        bad = [[{"content": "nope"}]]
+        scores = shape_match(good + bad, task_name="triangle")
+        assert scores[0] == 20.0
+        assert scores[1] == -2.0
+
+
+# --- API ---
+
+
+class TestAPI:
+    @pytest.fixture
+    def client(self):
+        from fastapi.testclient import TestClient
+
+        from server.app import app
+
+        return TestClient(app)
+
+    def test_health(self, client):
+        r = client.get("/health")
+        assert r.status_code == 200
+        assert r.json()["status"] == "healthy"
+
+    def test_tasks_endpoint(self, client):
+        r = client.get("/tasks")
+        assert r.status_code == 200
+        tasks = r.json()
+        assert "triangle" in tasks
+        assert "half_fold" in tasks
+        assert len(tasks) == 4
+
+    def test_task_detail_endpoint(self, client):
+        r = client.get("/tasks/triangle")
+        assert r.status_code == 200
+        data = r.json()
+        assert data["name"] == "triangle"
+        assert "target_fold" in data
+
+    def test_task_not_found(self, client):
+        r = client.get("/tasks/nonexistent")
+        assert r.status_code == 404
+
+    def test_websocket_reset_step(self, client):
+        with client.websocket_connect("/ws") as ws:
+            ws.send_json({"type": "reset", "data": {"task_name": "triangle"}})
+            resp = ws.receive_json()
+            assert resp["type"] == "observation"
+            assert resp["data"]["done"] is False
+
+            ws.send_json({"type": "step", "data": {"fold_data": TRIANGLE_FOLD}})
+            resp = ws.receive_json()
+            assert resp["type"] == "observation"
+            assert resp["data"]["reward"] == 20.0
+            assert resp["data"]["done"] is True
+
+    def test_websocket_all_tasks(self, client):
+        for task_name in ("triangle", "half_fold", "quarter_fold", "letter_fold"):
+            r = client.get(f"/tasks/{task_name}")
+            fold_data = r.json()["target_fold"]
+            with client.websocket_connect("/ws") as ws:
+                ws.send_json({"type": "reset", "data": {"task_name": task_name}})
+                ws.receive_json()
+                ws.send_json({"type": "step", "data": {"fold_data": fold_data}})
+                resp = ws.receive_json()
+                assert resp["data"]["reward"] == 20.0, f"{task_name} failed"

training/reward.py

@@ -0,0 +1,122 @@
+"""GRPO reward functions for origami RL training.
+
+Two reward functions (matching the 2048 pattern):
+1. valid_fold: Does the LLM output parse as valid FOLD JSON?
+2. shape_match: Simulate and compare to target shape.
+"""
+
+import json
+import re
+from typing import Any
+
+import numpy as np
+
+from server.engine.fold_parser import validate_fold
+from server.engine.shape_match import compute_shape_match
+from server.engine.simulate import simulate
+from server.tasks import get_task
+
+
+def extract_fold_json(response: str) -> dict | None:
+    """Extract FOLD JSON from LLM response text.
+
+    Looks for JSON between ```json ... ``` or raw JSON object.
+    """
+    # Try fenced code block first
+    match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", response, re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # Try raw JSON object
+    match = re.search(r"\{[^{}]*\"vertices_coords\"[^{}]*\}", response, re.DOTALL)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    # Try parsing the whole response
+    try:
+        data = json.loads(response.strip())
+        if isinstance(data, dict) and "vertices_coords" in data:
+            return data
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    return None
+
+
+def valid_fold(completions: list, **kwargs: Any) -> list[float]:
+    """Reward 1: Does the LLM output parse as valid FOLD JSON?
+
+    +1.0  valid FOLD JSON with correct structure
+    -0.5  parseable JSON but invalid FOLD structure
+    -2.0  not parseable as JSON at all
+    """
+    scores = []
+    for completion in completions:
+        response = completion[0]["content"]
+        fold_data = extract_fold_json(response)
+
+        if fold_data is None:
+            scores.append(-2.0)
+            continue
+
+        is_valid, error = validate_fold(fold_data)
+        if is_valid:
+            scores.append(1.0)
+        else:
+            scores.append(-0.5)
+
+    return scores
+
+
+def shape_match(
+    completions: list,
+    task_name: str = "triangle",
+    **kwargs: Any,
+) -> list[float]:
+    """Reward 2: Simulate the fold and compare to target shape.
+
+    Score = similarity × 20.0 (range: 0 to 20)
+    -1.0  if simulation fails/diverges
+    -2.0  if FOLD data is invalid
+
+    This is the main reward signal — AlphaFold-style shape comparison.
+    """
+    task = get_task(task_name)
+    target_fold = task["target_fold"]
+
+    # Pre-compute target positions
+    try:
+        target_result = simulate(target_fold, crease_percent=1.0)
+        target_positions = target_result.positions
+    except Exception:
+        # Target itself fails — all scores 0
+        return [0.0] * len(completions)
+
+    scores = []
+    for completion in completions:
+        response = completion[0]["content"]
+        fold_data = extract_fold_json(response)
+
+        if fold_data is None:
+            scores.append(-2.0)
+            continue
+
+        is_valid, error = validate_fold(fold_data)
+        if not is_valid:
+            scores.append(-1.0)
+            continue
+
+        try:
+            result = simulate(fold_data, crease_percent=1.0)
+            similarity = compute_shape_match(result.positions, target_positions)
+            scores.append(similarity * 20.0)
+        except Exception:
+            scores.append(-1.0)
+
+    return scores

training/train_grpo.py

@@ -0,0 +1,128 @@
+"""GRPO training script for origami RL.
+
+Follows the 2048 OpenEnv + Unsloth pattern:
+- LLM generates FOLD JSON crease patterns
+- Two reward functions: valid_fold + shape_match
+- GRPOTrainer from TRL handles the RL loop
+
+Usage (Colab):
+    python -m origami_env.training.train_grpo --task triangle --max_steps 600
+"""
+
+import argparse
+
+PROMPT_TEMPLATE = """You are an origami designer. Generate a FOLD-format crease pattern
+that, when folded, produces the target shape described below.
+
+Target: {description}
+Paper size: {width} x {height}
+
+Output a JSON object with these exact fields:
+- vertices_coords: [[x, y], ...] — 2D positions on the flat paper (0 to {width} for x, 0 to {height} for y)
+- edges_vertices: [[v1, v2], ...] — pairs of vertex indices forming edges
+- edges_assignment: ["B"|"M"|"V", ...] — B=boundary, M=mountain fold, V=valley fold
+- edges_foldAngle: [angle, ...] — fold angles in degrees (M: negative like -180, V: positive like 180, B: 0)
+
+Rules:
+- Boundary edges (B) must outline the paper rectangle
+- At least one fold crease (M or V) must exist
+- Mountain fold angles are negative (-180 to 0)
+- Valley fold angles are positive (0 to 180)
+- All vertex indices in edges must be valid (0 to N-1)
+
+Output ONLY the JSON object wrapped in ```json ... ``` markers."""
+
+
+def build_prompt(task: dict) -> str:
+    return PROMPT_TEMPLATE.format(
+        description=task["description"],
+        width=task["paper"]["width"],
+        height=task["paper"]["height"],
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="GRPO training for origami RL")
+    parser.add_argument("--task", default="triangle", help="Task name")
+    parser.add_argument("--max_steps", type=int, default=600)
+    parser.add_argument("--num_generations", type=int, default=4)
+    parser.add_argument("--model", default="unsloth/gpt-oss-20b")
+    parser.add_argument("--lr", type=float, default=2e-4)
+    args = parser.parse_args()
+
+    # --- These imports are heavy, only load when actually training ---
+    from datasets import Dataset
+    from trl import GRPOConfig, GRPOTrainer
+    from unsloth import FastLanguageModel
+
+    from server.tasks import get_task
+    from training.reward import shape_match, valid_fold
+
+    task = get_task(args.task)
+    prompt_text = build_prompt(task)
+
+    # Build dataset (1000 copies of same prompt, like 2048)
+    dataset = Dataset.from_list(
+        [
+            {
+                "prompt": [{"role": "user", "content": prompt_text}],
+                "answer": 0,
+            }
+        ]
+        * 1000
+    )
+
+    # Load model with LoRA
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=args.model,
+        load_in_4bit=True,
+        max_seq_length=2048,
+    )
+
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=8,
+        target_modules=[
+            "q_proj", "k_proj", "v_proj", "o_proj",
+            "gate_proj", "up_proj", "down_proj",
+        ],
+        lora_alpha=16,
+        use_gradient_checkpointing="unsloth",
+    )
+
+    # Wrap shape_match to inject task_name
+    def shape_match_reward(completions, **kwargs):
+        return shape_match(completions, task_name=args.task, **kwargs)
+
+    # GRPO config
+    training_args = GRPOConfig(
+        temperature=1.0,
+        learning_rate=args.lr,
+        weight_decay=0.001,
+        warmup_ratio=0.1,
+        lr_scheduler_type="linear",
+        optim="adamw_8bit",
+        logging_steps=1,
+        per_device_train_batch_size=1,
+        gradient_accumulation_steps=1,
+        num_generations=args.num_generations,
+        max_prompt_length=1024,
+        max_completion_length=1024,
+        max_steps=args.max_steps,
+        save_steps=100,
+        output_dir="outputs",
+    )
+
+    trainer = GRPOTrainer(
+        model=model,
+        processing_class=tokenizer,
+        reward_funcs=[valid_fold, shape_match_reward],
+        args=training_args,
+        train_dataset=dataset,
+    )
+
+    trainer.train()
+
+
+if __name__ == "__main__":
+    main()

viewer/index.html

@@ -0,0 +1,1047 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Origami RL</title>
+<style>
+@import url('https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;1,9..40,300&family=Instrument+Serif:ital@0;1&display=swap');
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+:root {
+  --bg: #faf9f7;
+  --surface: #ffffff;
+  --border: #e8e4df;
+  --border-hover: #c9c3ba;
+  --text: #1a1816;
+  --text-secondary: #7a756e;
+  --text-tertiary: #a9a49d;
+  --mountain: #c0392b;
+  --valley: #2471a3;
+  --boundary: #1a1816;
+  --accent: #c0392b;
+  --accent-soft: #f5eeec;
+  --success: #27ae60;
+  --shadow-sm: 0 1px 3px rgba(26,24,22,0.04);
+  --shadow-md: 0 4px 16px rgba(26,24,22,0.06);
+  --shadow-lg: 0 8px 32px rgba(26,24,22,0.08);
+  --radius: 12px;
+  --radius-sm: 8px;
+}
+
+body {
+  font-family: 'DM Sans', sans-serif;
+  background: var(--bg);
+  color: var(--text);
+  min-height: 100vh;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* --- HEADER --- */
+header {
+  padding: 32px 48px 24px;
+  display: flex;
+  align-items: baseline;
+  gap: 16px;
+}
+
+header h1 {
+  font-family: 'Instrument Serif', serif;
+  font-size: 28px;
+  font-weight: 400;
+  letter-spacing: -0.02em;
+}
+
+header span {
+  font-size: 13px;
+  color: var(--text-tertiary);
+  font-weight: 300;
+}
+
+/* --- GRID VIEW --- */
+#grid-view {
+  padding: 0 48px 64px;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 24px;
+  max-width: 1280px;
+}
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+  cursor: pointer;
+  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+  box-shadow: var(--shadow-sm);
+}
+
+.card:hover {
+  border-color: var(--border-hover);
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+.card-canvas {
+  width: 100%;
+  height: 200px;
+  background: var(--bg);
+  border-bottom: 1px solid var(--border);
+  position: relative;
+}
+
+.card-canvas canvas {
+  width: 100% !important;
+  height: 100% !important;
+}
+
+.card-info {
+  padding: 16px 20px;
+}
+
+.card-name {
+  font-family: 'Instrument Serif', serif;
+  font-size: 18px;
+  margin-bottom: 4px;
+}
+
+.card-desc {
+  font-size: 12px;
+  color: var(--text-secondary);
+  margin-bottom: 12px;
+  font-weight: 300;
+}
+
+.card-score {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.score-bar-bg {
+  flex: 1;
+  height: 4px;
+  background: var(--border);
+  border-radius: 2px;
+  overflow: hidden;
+}
+
+.score-bar-fill {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 2px;
+  transition: width 0.6s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.score-label {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  font-weight: 500;
+  min-width: 36px;
+  text-align: right;
+}
+
+/* --- DETAIL VIEW --- */
+#detail-view {
+  display: none;
+  height: 100vh;
+  flex-direction: column;
+}
+
+#detail-view.active {
+  display: flex;
+}
+
+#grid-view.hidden {
+  display: none;
+}
+
+.detail-header {
+  padding: 20px 32px;
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+}
+
+.back-btn {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  background: none;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 6px 14px;
+  font-family: inherit;
+  transition: all 0.2s;
+}
+
+.back-btn:hover {
+  border-color: var(--border-hover);
+  color: var(--text);
+}
+
+.detail-title {
+  font-family: 'Instrument Serif', serif;
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.detail-subtitle {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  font-weight: 300;
+  margin-left: auto;
+}
+
+.detail-body {
+  flex: 1;
+  display: grid;
+  grid-template-columns: 1fr 1.5fr;
+  min-height: 0;
+}
+
+/* 2D crease pattern panel */
+.panel-2d {
+  border-right: 1px solid var(--border);
+  background: var(--surface);
+  display: flex;
+  flex-direction: column;
+}
+
+.panel-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-tertiary);
+  padding: 16px 24px 8px;
+  font-weight: 500;
+}
+
+.crease-canvas {
+  flex: 1;
+  padding: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.crease-canvas svg {
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.legend {
+  padding: 12px 24px 20px;
+  display: flex;
+  gap: 20px;
+  font-size: 11px;
+  color: var(--text-secondary);
+}
+
+.legend-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.legend-swatch {
+  width: 16px;
+  height: 2px;
+  border-radius: 1px;
+}
+
+/* 3D viewer panel */
+.panel-3d {
+  background: var(--bg);
+  position: relative;
+}
+
+.panel-3d canvas {
+  width: 100% !important;
+  height: 100% !important;
+}
+
+/* Slider */
+.slider-bar {
+  padding: 16px 32px;
+  background: var(--surface);
+  border-top: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  gap: 20px;
+}
+
+.slider-label {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  font-weight: 300;
+  min-width: 40px;
+}
+
+.slider-track {
+  flex: 1;
+  position: relative;
+}
+
+input[type="range"] {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 100%;
+  height: 4px;
+  background: var(--border);
+  border-radius: 2px;
+  outline: none;
+}
+
+input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  background: var(--surface);
+  border: 2px solid var(--accent);
+  cursor: pointer;
+  box-shadow: var(--shadow-sm);
+  transition: transform 0.15s;
+}
+
+input[type="range"]::-webkit-slider-thumb:hover {
+  transform: scale(1.15);
+}
+
+.slider-value {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--text);
+  min-width: 40px;
+  text-align: right;
+}
+
+/* Metrics */
+.metrics-bar {
+  padding: 12px 32px;
+  background: var(--surface);
+  border-top: 1px solid var(--border);
+  display: flex;
+  gap: 40px;
+}
+
+.metric {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.metric-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-tertiary);
+}
+
+.metric-value {
+  font-size: 16px;
+  font-weight: 500;
+}
+
+.metric-value.high { color: var(--success); }
+.metric-value.mid { color: #e67e22; }
+.metric-value.low { color: var(--accent); }
+
+/* --- ANIMATIONS --- */
+@keyframes fadeIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.card {
+  animation: fadeIn 0.4s cubic-bezier(0.4, 0, 0.2, 1) both;
+}
+
+.card:nth-child(1) { animation-delay: 0.05s; }
+.card:nth-child(2) { animation-delay: 0.1s; }
+.card:nth-child(3) { animation-delay: 0.15s; }
+.card:nth-child(4) { animation-delay: 0.2s; }
+</style>
+</head>
+<body>
+
+<header>
+  <h1>Origami RL</h1>
+  <span>fold pattern explorer</span>
+</header>
+
+<!-- GRID VIEW -->
+<div id="grid-view">
+  <div class="grid" id="grid"></div>
+</div>
+
+<!-- DETAIL VIEW -->
+<div id="detail-view">
+  <div class="detail-header">
+    <button class="back-btn" id="back-btn">← Back</button>
+    <div class="detail-title" id="detail-title"></div>
+    <div class="detail-subtitle" id="detail-subtitle"></div>
+  </div>
+  <div class="detail-body">
+    <div class="panel-2d">
+      <div class="panel-label">Crease Pattern</div>
+      <div class="crease-canvas" id="crease-2d"></div>
+      <div class="legend">
+        <div class="legend-item">
+          <div class="legend-swatch" style="background:var(--mountain)"></div>Mountain
+        </div>
+        <div class="legend-item">
+          <div class="legend-swatch" style="background:var(--valley)"></div>Valley
+        </div>
+        <div class="legend-item">
+          <div class="legend-swatch" style="background:var(--boundary)"></div>Boundary
+        </div>
+      </div>
+    </div>
+    <div class="panel-3d" id="panel-3d"></div>
+  </div>
+  <div class="slider-bar">
+    <div class="slider-label">flat</div>
+    <div class="slider-track">
+      <input type="range" id="crease-slider" min="0" max="100" value="100">
+    </div>
+    <div class="slider-value" id="slider-val">100%</div>
+    <div class="slider-label">folded</div>
+  </div>
+  <div class="metrics-bar">
+    <div class="metric">
+      <div class="metric-label">Similarity</div>
+      <div class="metric-value high" id="m-sim">—</div>
+    </div>
+    <div class="metric">
+      <div class="metric-label">Folds</div>
+      <div class="metric-value" id="m-folds">—</div>
+    </div>
+    <div class="metric">
+      <div class="metric-label">Strain</div>
+      <div class="metric-value" id="m-strain">—</div>
+    </div>
+    <div class="metric">
+      <div class="metric-label">Vertices</div>
+      <div class="metric-value" id="m-verts">—</div>
+    </div>
+    <div class="metric">
+      <div class="metric-label">Status</div>
+      <div class="metric-value" id="m-status">—</div>
+    </div>
+  </div>
+</div>
+
+<script type="importmap">
+{
+  "imports": {
+    "three": "https://cdn.jsdelivr.net/npm/three@0.163.0/build/three.module.js",
+    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.163.0/examples/jsm/"
+  }
+}
+</script>
+
+<script type="module">
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+// ─── FOLD DATA (hardcoded demo) ───────────────────────────────
+const TASKS = {
+  triangle: {
+    name: 'Triangle',
+    description: 'Diagonal valley fold',
+    difficulty: 1,
+    similarity: 1.0,
+    fold: {
+      vertices_coords: [[0,0],[1,0],[1,1],[0,1]],
+      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]],
+    },
+    strain: 0.0,
+  },
+  half_fold: {
+    name: 'Half Fold',
+    description: 'Horizontal valley fold',
+    difficulty: 1,
+    similarity: 1.0,
+    fold: {
+      vertices_coords: [[0,0],[1,0],[1,1],[0,1],[0,0.5],[1,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]],
+    },
+    strain: 0.0,
+  },
+  quarter_fold: {
+    name: 'Quarter Fold',
+    description: 'Two perpendicular folds',
+    difficulty: 2,
+    similarity: 1.0,
+    fold: {
+      vertices_coords: [[0,0],[0.5,0],[1,0],[0,0.5],[0.5,0.5],[1,0.5],[0,1],[0.5,1],[1,1]],
+      edges_vertices: [[0,1],[1,2],[2,5],[5,8],[8,7],[7,6],[6,3],[3,0],[1,4],[4,7],[3,4],[4,5]],
+      edges_assignment: ['B','B','B','B','B','B','B','B','V','V','V','V'],
+      edges_foldAngle: [0,0,0,0,0,0,0,0,180,180,180,180],
+      faces_vertices: [[0,1,4,3],[1,2,5,4],[3,4,7,6],[4,5,8,7]],
+    },
+    strain: 0.0,
+  },
+  letter_fold: {
+    name: 'Letter Fold',
+    description: 'Two parallel folds',
+    difficulty: 2,
+    similarity: 1.0,
+    fold: {
+      vertices_coords: [[0,0],[1,0],[0,1/3],[1,1/3],[0,2/3],[1,2/3],[0,1],[1,1]],
+      edges_vertices: [[0,1],[1,3],[3,5],[5,7],[7,6],[6,4],[4,2],[2,0],[2,3],[4,5]],
+      edges_assignment: ['B','B','B','B','B','B','B','B','V','M'],
+      edges_foldAngle: [0,0,0,0,0,0,0,0,180,-180],
+      faces_vertices: [[0,1,3,2],[2,3,5,4],[4,5,7,6]],
+    },
+    strain: 0.0,
+  },
+};
+
+// ─── CLIENT-SIDE ANALYTICAL FOLD SOLVER ──────────────────────
+// Cumulative transform approach: each face stores (R, t) where
+// folded_pos = R * flat_pos + t. Correctly handles multiple folds.
+
+function analyticalFold(fold, creasePercent) {
+  const verts = fold.vertices_coords;
+  const n = verts.length;
+  const flat = new Float32Array(n * 3);
+  const pos = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) {
+    flat[i*3] = verts[i][0]; flat[i*3+1] = verts[i][1]; flat[i*3+2] = 0;
+    pos[i*3] = verts[i][0]; pos[i*3+1] = verts[i][1]; pos[i*3+2] = 0;
+  }
+
+  if (Math.abs(creasePercent) < 1e-10) return pos;
+
+  const faces = fold.faces_vertices;
+  const edges = fold.edges_vertices;
+  const assignments = fold.edges_assignment;
+  const foldAngles = fold.edges_foldAngle;
+  if (!faces || faces.length === 0) return pos;
+
+  // Build face adjacency
+  const faceAdj = {};
+  for (let fi = 0; fi < faces.length; fi++) {
+    const face = faces[fi];
+    for (let j = 0; j < face.length; j++) {
+      const v1 = face[j], v2 = face[(j+1) % face.length];
+      const key = Math.min(v1,v2) + ',' + Math.max(v1,v2);
+      if (!faceAdj[key]) faceAdj[key] = [];
+      faceAdj[key].push(fi);
+    }
+  }
+
+  // Build crease map
+  const creaseMap = {};
+  for (let i = 0; i < edges.length; i++) {
+    const [v1, v2] = edges[i];
+    const key = Math.min(v1,v2) + ',' + Math.max(v1,v2);
+    if (assignments[i] === 'M' || assignments[i] === 'V') {
+      creaseMap[key] = (foldAngles[i] * Math.PI / 180) * creasePercent;
+    }
+  }
+
+  // Per-face cumulative transform: folded = R * flat + t
+  // R is a 3x3 matrix stored as [r00,r01,r02, r10,r11,r12, r20,r21,r22]
+  const faceR = new Array(faces.length).fill(null);
+  const faceT = new Array(faces.length).fill(null);
+  // Face 0: identity
+  faceR[0] = [1,0,0, 0,1,0, 0,0,1];
+  faceT[0] = [0,0,0];
+
+  const visited = new Array(faces.length).fill(false);
+  visited[0] = true;
+  const placed = new Set();
+  for (const vi of faces[0]) placed.add(vi);
+
+  const queue = [0];
+  while (queue.length > 0) {
+    const fi = queue.shift();
+    const face = faces[fi];
+
+    for (let j = 0; j < face.length; j++) {
+      const v1 = face[j], v2 = face[(j+1) % face.length];
+      const key = Math.min(v1,v2) + ',' + Math.max(v1,v2);
+
+      for (const fj of (faceAdj[key] || [])) {
+        if (visited[fj]) continue;
+        visited[fj] = true;
+        queue.push(fj);
+
+        const angle = creaseMap[key] || 0;
+        let Rfj, tfj;
+
+        if (Math.abs(angle) > 1e-10) {
+          // Fold rotation around edge (v1->v2) in folded coords
+          const p1 = [pos[v1*3], pos[v1*3+1], pos[v1*3+2]];
+          const ax = [pos[v2*3]-p1[0], pos[v2*3+1]-p1[1], pos[v2*3+2]-p1[2]];
+          const axLen = Math.sqrt(ax[0]*ax[0]+ax[1]*ax[1]+ax[2]*ax[2]);
+
+          if (axLen < 1e-12) {
+            Rfj = faceR[fi].slice(); tfj = faceT[fi].slice();
+          } else {
+            const u = [ax[0]/axLen, ax[1]/axLen, ax[2]/axLen];
+            const foldR = rodriguesMat(u, angle);
+            Rfj = matMul(foldR, faceR[fi]);
+            // t_fj = foldR * (t_fi - p1) + p1
+            const dt = [faceT[fi][0]-p1[0], faceT[fi][1]-p1[1], faceT[fi][2]-p1[2]];
+            const rdt = matVec(foldR, dt);
+            tfj = [rdt[0]+p1[0], rdt[1]+p1[1], rdt[2]+p1[2]];
+          }
+        } else {
+          Rfj = faceR[fi].slice();
+          tfj = faceT[fi].slice();
+        }
+
+        faceR[fj] = Rfj;
+        faceT[fj] = tfj;
+
+        // Place unplaced vertices
+        for (const vi of faces[fj]) {
+          if (!placed.has(vi)) {
+            const fv = [flat[vi*3], flat[vi*3+1], flat[vi*3+2]];
+            const rv = matVec(Rfj, fv);
+            pos[vi*3]   = rv[0] + tfj[0];
+            pos[vi*3+1] = rv[1] + tfj[1];
+            pos[vi*3+2] = rv[2] + tfj[2];
+            placed.add(vi);
+          }
+        }
+      }
+    }
+  }
+
+  return pos;
+}
+
+// 3x3 rotation matrix from axis-angle (Rodrigues)
+function rodriguesMat(u, angle) {
+  const c = Math.cos(angle), s = Math.sin(angle), t = 1 - c;
+  return [
+    c + u[0]*u[0]*t,       u[0]*u[1]*t - u[2]*s,  u[0]*u[2]*t + u[1]*s,
+    u[1]*u[0]*t + u[2]*s,  c + u[1]*u[1]*t,        u[1]*u[2]*t - u[0]*s,
+    u[2]*u[0]*t - u[1]*s,  u[2]*u[1]*t + u[0]*s,   c + u[2]*u[2]*t,
+  ];
+}
+
+// 3x3 matrix multiply (row-major flat arrays)
+function matMul(a, b) {
+  return [
+    a[0]*b[0]+a[1]*b[3]+a[2]*b[6], a[0]*b[1]+a[1]*b[4]+a[2]*b[7], a[0]*b[2]+a[1]*b[5]+a[2]*b[8],
+    a[3]*b[0]+a[4]*b[3]+a[5]*b[6], a[3]*b[1]+a[4]*b[4]+a[5]*b[7], a[3]*b[2]+a[4]*b[5]+a[5]*b[8],
+    a[6]*b[0]+a[7]*b[3]+a[8]*b[6], a[6]*b[1]+a[7]*b[4]+a[8]*b[7], a[6]*b[2]+a[7]*b[5]+a[8]*b[8],
+  ];
+}
+
+// 3x3 matrix * vec3
+function matVec(m, v) {
+  return [
+    m[0]*v[0]+m[1]*v[1]+m[2]*v[2],
+    m[3]*v[0]+m[4]*v[1]+m[5]*v[2],
+    m[6]*v[0]+m[7]*v[1]+m[8]*v[2],
+  ];
+}
+
+// ─── THREE.JS HELPERS ─────────────────────────────────────────
+
+const EDGE_COLORS = { M: 0xc0392b, V: 0x2471a3, B: 0x1a1816, F: 0xddd8d0, U: 0xa9a49d };
+
+function buildMesh(task, creasePercent = 1) {
+  const fold = task.fold;
+  const n = fold.vertices_coords.length;
+  const group = new THREE.Group();
+
+  // Compute folded positions analytically
+  const positions = analyticalFold(fold, creasePercent);
+
+  // Faces
+  const faces = fold.faces_vertices;
+  const indices = [];
+  for (const face of faces) {
+    for (let i = 1; i < face.length - 1; i++) {
+      indices.push(face[0], face[i], face[i+1]);
+    }
+  }
+
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  geo.setIndex(indices);
+  geo.computeVertexNormals();
+
+  const mat = new THREE.MeshPhongMaterial({
+    color: 0xfaf9f7,
+    side: THREE.DoubleSide,
+    flatShading: false,
+    shininess: 20,
+    specular: 0x222222,
+  });
+  const mesh = new THREE.Mesh(geo, mat);
+  group.add(mesh);
+
+  // Edges
+  for (let i = 0; i < fold.edges_vertices.length; i++) {
+    const [v1, v2] = fold.edges_vertices[i];
+    const assignment = fold.edges_assignment[i];
+    const color = EDGE_COLORS[assignment] || 0xaaaaaa;
+    const lineGeo = new THREE.BufferGeometry();
+    const linePos = new Float32Array([
+      positions[v1*3], positions[v1*3+1], positions[v1*3+2],
+      positions[v2*3], positions[v2*3+1], positions[v2*3+2],
+    ]);
+    lineGeo.setAttribute('position', new THREE.BufferAttribute(linePos, 3));
+    const lineMat = new THREE.LineBasicMaterial({
+      color,
+      linewidth: assignment === 'B' ? 2 : 1,
+    });
+    group.add(new THREE.LineSegments(lineGeo, lineMat));
+  }
+
+  // Center
+  const box = new THREE.Box3().setFromObject(group);
+  const center = box.getCenter(new THREE.Vector3());
+  group.position.sub(center);
+
+  return group;
+}
+
+function setupScene(container, opts = {}) {
+  const w = container.clientWidth || 300;
+  const h = container.clientHeight || 200;
+
+  const scene = new THREE.Scene();
+  scene.background = opts.bg ? new THREE.Color(opts.bg) : new THREE.Color(0xfaf9f7);
+
+  const camera = new THREE.PerspectiveCamera(35, w / h, 0.01, 100);
+  camera.position.set(0, 0.4, 2.2);
+
+  const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+  renderer.setSize(w, h);
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  container.appendChild(renderer.domElement);
+
+  // Lights
+  const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
+  scene.add(ambientLight);
+  const dirLight1 = new THREE.DirectionalLight(0xffffff, 0.7);
+  dirLight1.position.set(1, 2, 3);
+  scene.add(dirLight1);
+  const dirLight2 = new THREE.DirectionalLight(0xffffff, 0.3);
+  dirLight2.position.set(-2, 1, -1);
+  scene.add(dirLight2);
+
+  let controls = null;
+  if (opts.orbit) {
+    controls = new OrbitControls(camera, renderer.domElement);
+    controls.enableDamping = true;
+    controls.dampingFactor = 0.08;
+    controls.enablePan = false;
+    controls.minDistance = 0.8;
+    controls.maxDistance = 5;
+    controls.autoRotate = opts.autoRotate || false;
+    controls.autoRotateSpeed = 1.5;
+  }
+
+  return { scene, camera, renderer, controls };
+}
+
+// ─── GRID VIEW ────────────────────────────────────────────────
+
+const gridEl = document.getElementById('grid');
+const cardScenes = [];
+
+for (const [key, task] of Object.entries(TASKS)) {
+  const card = document.createElement('div');
+  card.className = 'card';
+  card.innerHTML = `
+    <div class="card-canvas" id="card-${key}"></div>
+    <div class="card-info">
+      <div class="card-name">${task.name}</div>
+      <div class="card-desc">${task.description} · difficulty ${task.difficulty}</div>
+      <div class="card-score">
+        <div class="score-bar-bg"><div class="score-bar-fill" style="width:${task.similarity * 100}%"></div></div>
+        <div class="score-label">${Math.round(task.similarity * 100)}%</div>
+      </div>
+    </div>
+  `;
+  card.addEventListener('click', () => showDetail(key));
+  gridEl.appendChild(card);
+}
+
+// Init mini 3D scenes after DOM paint
+requestAnimationFrame(() => {
+  for (const [key, task] of Object.entries(TASKS)) {
+    const container = document.getElementById(`card-${key}`);
+    if (!container) continue;
+    const { scene, camera, renderer } = setupScene(container, { autoRotate: true });
+    const mesh = buildMesh(task, 1.0);
+    scene.add(mesh);
+
+    // Slow auto-rotate
+    const animate = () => {
+      requestAnimationFrame(animate);
+      mesh.rotation.y += 0.005;
+      renderer.render(scene, camera);
+    };
+    animate();
+    cardScenes.push({ key, scene, camera, renderer, mesh });
+  }
+});
+
+// ─── DETAIL VIEW ──────────────────────────────────────────────
+
+let detailScene = null;
+let detailRenderer = null;
+let detailCamera = null;
+let detailControls = null;
+let detailMeshGroup = null;
+let detailAnimId = null;
+let currentTaskKey = null;
+
+function showDetail(key) {
+  currentTaskKey = key;
+  const task = TASKS[key];
+
+  document.getElementById('grid-view').classList.add('hidden');
+  document.getElementById('detail-view').classList.add('active');
+
+  document.getElementById('detail-title').textContent = task.name;
+  document.getElementById('detail-subtitle').textContent = task.description;
+
+  // 2D crease pattern
+  draw2DCrease(task);
+
+  // Metrics
+  const foldCount = task.fold.edges_assignment.filter(a => a === 'M' || a === 'V').length;
+  document.getElementById('m-sim').textContent = Math.round(task.similarity * 100) + '%';
+  document.getElementById('m-folds').textContent = foldCount;
+  document.getElementById('m-strain').textContent = task.strain.toFixed(4);
+  document.getElementById('m-verts').textContent = task.fold.vertices_coords.length;
+  document.getElementById('m-status').textContent = task.strain < 0.05 ? 'stable' : 'settling';
+
+  const simEl = document.getElementById('m-sim');
+  simEl.className = 'metric-value ' + (task.similarity > 0.9 ? 'high' : task.similarity > 0.5 ? 'mid' : 'low');
+
+  // 3D viewer
+  const panel = document.getElementById('panel-3d');
+  // Clean up old
+  if (detailRenderer) {
+    panel.removeChild(detailRenderer.domElement);
+    detailRenderer.dispose();
+    if (detailAnimId) cancelAnimationFrame(detailAnimId);
+  }
+
+  const setup = setupScene(panel, { orbit: true, bg: 0xf5f3f0 });
+  detailScene = setup.scene;
+  detailCamera = setup.camera;
+  detailRenderer = setup.renderer;
+  detailControls = setup.controls;
+
+  // Reset slider
+  const slider = document.getElementById('crease-slider');
+  slider.value = 100;
+  document.getElementById('slider-val').textContent = '100%';
+
+  // Build mesh
+  updateDetailMesh(1.0);
+
+  // Target ghost overlay
+  addTargetGhost(task);
+
+  // Animate
+  const animateDetail = () => {
+    detailAnimId = requestAnimationFrame(animateDetail);
+    detailControls.update();
+    detailRenderer.render(detailScene, detailCamera);
+  };
+  animateDetail();
+
+  // Resize
+  const resizeObserver = new ResizeObserver(() => {
+    const w = panel.clientWidth;
+    const h = panel.clientHeight;
+    detailCamera.aspect = w / h;
+    detailCamera.updateProjectionMatrix();
+    detailRenderer.setSize(w, h);
+  });
+  resizeObserver.observe(panel);
+}
+
+function updateDetailMesh(cp) {
+  if (!currentTaskKey) return;
+  const task = TASKS[currentTaskKey];
+
+  // Remove old mesh group (keep ghost)
+  if (detailMeshGroup) {
+    detailScene.remove(detailMeshGroup);
+  }
+
+  detailMeshGroup = buildMesh(task, cp);
+  detailScene.add(detailMeshGroup);
+}
+
+function addTargetGhost(task) {
+  const fold = task.fold;
+  const n = fold.vertices_coords.length;
+
+  // Wireframe ghost of fully folded state
+  const positions = analyticalFold(fold, 1.0);
+
+  const faces = fold.faces_vertices;
+  const indices = [];
+  for (const face of faces) {
+    for (let i = 1; i < face.length - 1; i++) {
+      indices.push(face[0], face[i], face[i+1]);
+    }
+  }
+
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  geo.setIndex(indices);
+
+  const ghostMat = new THREE.MeshBasicMaterial({
+    color: 0xc0392b,
+    wireframe: true,
+    transparent: true,
+    opacity: 0.15,
+  });
+
+  const ghost = new THREE.Mesh(geo, ghostMat);
+
+  // Center same as main mesh
+  const box = new THREE.Box3().setFromBufferAttribute(geo.getAttribute('position'));
+  const center = box.getCenter(new THREE.Vector3());
+  ghost.position.sub(center);
+
+  detailScene.add(ghost);
+}
+
+function draw2DCrease(task) {
+  const container = document.getElementById('crease-2d');
+  const fold = task.fold;
+  const verts = fold.vertices_coords;
+
+  // Find bounds
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const v of verts) {
+    minX = Math.min(minX, v[0]); minY = Math.min(minY, v[1]);
+    maxX = Math.max(maxX, v[0]); maxY = Math.max(maxY, v[1]);
+  }
+
+  const pad = 0.15;
+  const vw = maxX - minX + pad * 2;
+  const vh = maxY - minY + pad * 2;
+  const size = 280;
+  const scale = size / Math.max(vw, vh);
+
+  const toX = (x) => (x - minX + pad) * scale;
+  const toY = (y) => size - (y - minY + pad) * scale; // flip Y
+
+  const STROKE = { M: '#c0392b', V: '#2471a3', B: '#1a1816', F: '#ddd8d0', U: '#a9a49d' };
+
+  let svg = `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" xmlns="http://www.w3.org/2000/svg">`;
+
+  // Background paper
+  const paperPts = [];
+  // Find boundary edges and form polygon
+  const bVerts = new Set();
+  for (let i = 0; i < fold.edges_vertices.length; i++) {
+    if (fold.edges_assignment[i] === 'B') {
+      bVerts.add(fold.edges_vertices[i][0]);
+      bVerts.add(fold.edges_vertices[i][1]);
+    }
+  }
+
+  // Draw faces as background
+  for (const face of fold.faces_vertices) {
+    const pts = face.map(vi => `${toX(verts[vi][0])},${toY(verts[vi][1])}`).join(' ');
+    svg += `<polygon points="${pts}" fill="#ffffff" stroke="none"/>`;
+  }
+
+  // Draw edges
+  for (let i = 0; i < fold.edges_vertices.length; i++) {
+    const [v1, v2] = fold.edges_vertices[i];
+    const a = fold.edges_assignment[i];
+    const color = STROKE[a] || '#aaa';
+    const width = a === 'B' ? 2 : 1.5;
+    const dash = a === 'M' ? 'stroke-dasharray="6 3"' : a === 'V' ? 'stroke-dasharray="2 2"' : '';
+
+    svg += `<line x1="${toX(verts[v1][0])}" y1="${toY(verts[v1][1])}" x2="${toX(verts[v2][0])}" y2="${toY(verts[v2][1])}" stroke="${color}" stroke-width="${width}" stroke-linecap="round" ${dash}/>`;
+  }
+
+  // Draw vertices
+  for (let i = 0; i < verts.length; i++) {
+    svg += `<circle cx="${toX(verts[i][0])}" cy="${toY(verts[i][1])}" r="3" fill="var(--text)" opacity="0.3"/>`;
+  }
+
+  svg += '</svg>';
+  container.innerHTML = svg;
+}
+
+function showGrid() {
+  document.getElementById('grid-view').classList.remove('hidden');
+  document.getElementById('detail-view').classList.remove('active');
+  if (detailAnimId) cancelAnimationFrame(detailAnimId);
+  currentTaskKey = null;
+}
+
+// ─── SLIDER ───────────────────────────────────────────────────
+
+document.getElementById('crease-slider').addEventListener('input', (e) => {
+  const val = parseInt(e.target.value);
+  document.getElementById('slider-val').textContent = val + '%';
+  updateDetailMesh(val / 100);
+});
+
+// ─── BACK BUTTON & KEYBOARD ───────────────────────────────────
+
+document.getElementById('back-btn').addEventListener('click', () => showGrid());
+
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape' && currentTaskKey) showGrid();
+});
+
+// ─── WEBSOCKET (optional live connection) ─────────────────────
+
+function connectWS() {
+  try {
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const ws = new WebSocket(`${proto}//${location.host}/ws`);
+    ws.onopen = () => console.log('[WS] Connected');
+    ws.onmessage = (e) => {
+      const data = JSON.parse(e.data);
+      if (data.type === 'observation' && data.data?.observation) {
+        const obs = data.data.observation;
+        console.log('[WS] Observation:', obs.shape_similarity);
+      }
+    };
+    ws.onerror = () => console.log('[WS] No server (using demo data)');
+  } catch (e) {
+    // Server not running, use demo data
+  }
+}
+
+connectWS();
+</script>
+
+</body>
+</html>