Create app.py

app.py

@@ -0,0 +1,905 @@
+import json
+import math
+import time
+from dataclasses import dataclass, asdict
+from typing import Dict, List, Tuple, Optional
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+import gradio as gr
+
+# ============================================================
+# ChronoSandbox — Agent Timeline Lab (Deterministic, Inspectable)
+# - Multi-agent gridworld
+# - First-person pseudo-3D raycast view for selected agent
+# - Global truth map + per-agent belief maps (fog-of-war memory)
+# - AutoRun animation, time dilation, rewind scrubber
+# - Branching timelines (fork from any previous step)
+# - Click-to-edit map tiles
+#
+# Minimal philosophy: explicit rules, no hidden weights, replayable.
+# ============================================================
+
+# -----------------------------
+# World / render config
+# -----------------------------
+GRID_W, GRID_H = 21, 15
+TILE = 22  # top-down pixels per tile
+
+VIEW_W, VIEW_H = 640, 360
+RAY_W = 320
+FOV_DEG = 78
+MAX_DEPTH = 20
+
+# 0=E,1=S,2=W,3=N
+DIRS = [(1, 0), (0, 1), (-1, 0), (0, -1)]
+ORI_DEG = [0, 90, 180, 270]
+
+# Tile types
+EMPTY = 0
+WALL = 1
+FOOD = 2
+NOISE = 3
+DOOR = 4
+TELE = 5
+
+TILE_NAMES = {
+    EMPTY: "Empty",
+    WALL: "Wall",
+    FOOD: "Food",
+    NOISE: "Noise",
+    DOOR: "Door",
+    TELE: "Teleporter",
+}
+
+# Palette (kept simple; inspectable)
+SKY = np.array([14, 16, 26], dtype=np.uint8)
+FLOOR_NEAR = np.array([24, 26, 40], dtype=np.uint8)
+FLOOR_FAR = np.array([10, 11, 18], dtype=np.uint8)
+WALL_BASE = np.array([210, 210, 225], dtype=np.uint8)
+WALL_SIDE = np.array([150, 150, 170], dtype=np.uint8)
+
+AGENT_COLORS = {
+    "Predator": (255, 120, 90),
+    "Prey": (120, 255, 160),
+    "Scout": (120, 190, 255),
+}
+
+# -----------------------------
+# Deterministic RNG helper
+# -----------------------------
+def rng_for(seed: int, step: int, stream: int = 0) -> np.random.Generator:
+    # Stable stream keyed by (seed, step, stream)
+    # Using PCG64 bitgen for reproducibility.
+    mix = (seed * 1_000_003) ^ (step * 9_999_937) ^ (stream * 97_531)
+    return np.random.default_rng(mix & 0xFFFFFFFFFFFFFFFF)
+
+# -----------------------------
+# State definitions
+# -----------------------------
+@dataclass
+class Agent:
+    name: str
+    x: int
+    y: int
+    ori: int  # 0..3
+    energy: int = 100  # mainly for prey, food, etc.
+
+@dataclass
+class WorldState:
+    seed: int
+    step: int
+    grid: List[List[int]]  # ints
+    agents: Dict[str, Agent]
+    controlled: str  # which agent receives manual control
+    pov: str         # which agent camera is showing
+    autorun: bool
+    speed_hz: float
+    overlay: bool
+    event_log: List[str]
+    caught: bool
+    branches: Dict[str, int]  # branch_name -> step_index in history
+
+@dataclass
+class Snapshot:
+    step: int
+    agents: Dict[str, Dict]
+    grid: List[List[int]]
+    event_log_tail: List[str]
+    caught: bool
+
+def default_grid() -> List[List[int]]:
+    g = [[EMPTY for _ in range(GRID_W)] for _ in range(GRID_H)]
+    # Border walls
+    for x in range(GRID_W):
+        g[0][x] = WALL
+        g[GRID_H - 1][x] = WALL
+    for y in range(GRID_H):
+        g[y][0] = WALL
+        g[y][GRID_W - 1] = WALL
+
+    # Some interior structure
+    for x in range(4, 17):
+        g[7][x] = WALL
+    g[7][10] = DOOR  # a door gap
+
+    # Toys
+    g[3][4] = FOOD
+    g[11][15] = FOOD
+    g[4][14] = NOISE
+    g[12][5] = NOISE
+    g[2][18] = TELE
+    g[13][2] = TELE
+    return g
+
+def init_state(seed: int) -> WorldState:
+    agents = {
+        "Predator": Agent("Predator", 2, 2, 0, 100),
+        "Prey":     Agent("Prey", 18, 12, 2, 100),
+        "Scout":    Agent("Scout", 10, 3, 1, 100),
+    }
+    return WorldState(
+        seed=seed,
+        step=0,
+        grid=default_grid(),
+        agents=agents,
+        controlled="Predator",
+        pov="Predator",
+        autorun=False,
+        speed_hz=8.0,
+        overlay=False,
+        event_log=["Initialized world."],
+        caught=False,
+        branches={"main": 0},
+    )
+
+# -----------------------------
+# Per-agent belief memory
+# -----------------------------
+def init_belief() -> Dict[str, np.ndarray]:
+    # -1 unknown, else tile id
+    b = {}
+    for name in ["Predator", "Prey", "Scout"]:
+        b[name] = -1 * np.ones((GRID_H, GRID_W), dtype=np.int16)
+    return b
+
+# -----------------------------
+# Utility: movement + collision
+# -----------------------------
+def in_bounds(x: int, y: int) -> bool:
+    return 0 <= x < GRID_W and 0 <= y < GRID_H
+
+def is_blocking(tile: int) -> bool:
+    # door is passable (for drama); wall blocks; tele is passable
+    return tile == WALL
+
+def move_forward(state: WorldState, a: Agent) -> None:
+    dx, dy = DIRS[a.ori]
+    nx, ny = a.x + dx, a.y + dy
+    if not in_bounds(nx, ny):
+        return
+    if is_blocking(state.grid[ny][nx]):
+        return
+    # Door toggle mechanic: if you step onto a door, it becomes empty (door opens)
+    if state.grid[ny][nx] == DOOR:
+        state.grid[ny][nx] = EMPTY
+        state.event_log.append(f"t={state.step}: {a.name} opened a door.")
+    a.x, a.y = nx, ny
+
+    # Teleporter: stepping onto TELE sends you to the other TELE (deterministically)
+    if state.grid[ny][nx] == TELE:
+        teles = [(x, y) for y in range(GRID_H) for x in range(GRID_W) if state.grid[y][x] == TELE]
+        if len(teles) >= 2:
+            # choose destination as "the other tele" based on sorted list
+            teles_sorted = sorted(teles)
+            idx = teles_sorted.index((nx, ny))
+            dest = teles_sorted[(idx + 1) % len(teles_sorted)]
+            a.x, a.y = dest
+            state.event_log.append(f"t={state.step}: {a.name} teleported.")
+
+def turn_left(a: Agent) -> None:
+    a.ori = (a.ori - 1) % 4
+
+def turn_right(a: Agent) -> None:
+    a.ori = (a.ori + 1) % 4
+
+# -----------------------------
+# Perception: LOS + FOV on grid
+# -----------------------------
+def los_clear(grid: List[List[int]], x0: int, y0: int, x1: int, y1: int) -> bool:
+    # Bresenham line-of-sight; walls block
+    dx = abs(x1 - x0)
+    dy = abs(y1 - y0)
+    sx = 1 if x0 < x1 else -1
+    sy = 1 if y0 < y1 else -1
+    err = dx - dy
+    x, y = x0, y0
+    while True:
+        if (x, y) != (x0, y0) and (x, y) != (x1, y1):
+            if grid[y][x] == WALL:
+                return False
+        if x == x1 and y == y1:
+            return True
+        e2 = 2 * err
+        if e2 > -dy:
+            err -= dy
+            x += sx
+        if e2 < dx:
+            err += dx
+            y += sy
+
+def within_fov(observer: Agent, tx: int, ty: int, fov_deg: float = 78.0) -> bool:
+    # vector from observer to target in observer's local frame
+    dx = tx - observer.x
+    dy = ty - observer.y
+    if dx == 0 and dy == 0:
+        return True
+    # absolute angle of target
+    angle = math.degrees(math.atan2(dy, dx)) % 360
+    facing = ORI_DEG[observer.ori]
+    # smallest signed difference
+    diff = (angle - facing + 540) % 360 - 180
+    return abs(diff) <= (fov_deg / 2)
+
+def visible(observer: Agent, target: Agent, grid: List[List[int]]) -> bool:
+    return within_fov(observer, target.x, target.y, FOV_DEG) and los_clear(grid, observer.x, observer.y, target.x, target.y)
+
+# -----------------------------
+# Raycast pseudo-3D render
+# -----------------------------
+def raycast_view(state: WorldState, observer: Agent, belief: Optional[np.ndarray] = None) -> np.ndarray:
+    # Returns RGB uint8 image
+    img = np.zeros((VIEW_H, VIEW_W, 3), dtype=np.uint8)
+    img[:, :] = SKY
+
+    # floor gradient
+    for y in range(VIEW_H // 2, VIEW_H):
+        t = (y - VIEW_H // 2) / (VIEW_H // 2 + 1e-6)
+        col = (1 - t) * FLOOR_NEAR + t * FLOOR_FAR
+        img[y, :] = col.astype(np.uint8)
+
+    # ray setup
+    fov = math.radians(FOV_DEG)
+    half_fov = fov / 2
+    for rx in range(RAY_W):
+        # camera plane: [-1, 1]
+        cam_x = (2 * rx / (RAY_W - 1)) - 1
+        ray_ang = math.radians(ORI_DEG[observer.ori]) + cam_x * half_fov
+
+        # DDA-like stepping
+        ox, oy = observer.x + 0.5, observer.y + 0.5
+        sin_a = math.sin(ray_ang)
+        cos_a = math.cos(ray_ang)
+        depth = 0.0
+        hit_side = 0
+
+        while depth < MAX_DEPTH:
+            depth += 0.05
+            tx = int(ox + cos_a * depth)
+            ty = int(oy + sin_a * depth)
+            if not in_bounds(tx, ty):
+                break
+
+            tile = state.grid[ty][tx]
+            if tile == WALL:
+                # side shading based on ray direction
+                # crude: if abs(cos)>abs(sin) consider "vertical" else "horizontal"
+                hit_side = 1 if abs(cos_a) > abs(sin_a) else 0
+                break
+            if tile == DOOR:
+                # door is semi-visible in world; render thinner by treating as a hit but less dark
+                hit_side = 2
+                break
+
+        # project wall slice
+        if depth >= MAX_DEPTH:
+            continue
+        # fish-eye correction
+        depth *= math.cos(ray_ang - math.radians(ORI_DEG[observer.ori]))
+        depth = max(depth, 0.001)
+
+        proj_h = int((VIEW_H * 0.9) / depth)
+        y0 = max(0, VIEW_H // 2 - proj_h // 2)
+        y1 = min(VIEW_H - 1, VIEW_H // 2 + proj_h // 2)
+
+        if hit_side == 0:
+            col = WALL_BASE.copy()
+        elif hit_side == 1:
+            col = WALL_SIDE.copy()
+        else:
+            # door slice
+            col = np.array([180, 210, 255], dtype=np.uint8)
+
+        # slight depth dim
+        dim = max(0.25, 1.0 - (depth / MAX_DEPTH))
+        col = (col * dim).astype(np.uint8)
+
+        # draw slice (scaled to full VIEW_W)
+        x0 = int(rx * (VIEW_W / RAY_W))
+        x1 = int((rx + 1) * (VIEW_W / RAY_W))
+        img[y0:y1, x0:x1] = col
+
+    # overlay: draw "billboards" for visible agents
+    for other_name, other in state.agents.items():
+        if other_name == observer.name:
+            continue
+        if visible(observer, other, state.grid):
+            # place billboard at its relative angle
+            dx = other.x - observer.x
+            dy = other.y - observer.y
+            ang = (math.degrees(math.atan2(dy, dx)) % 360)
+            facing = ORI_DEG[observer.ori]
+            diff = (ang - facing + 540) % 360 - 180
+            # map diff to screen x
+            sx = int((diff / (FOV_DEG / 2)) * (VIEW_W / 2) + (VIEW_W / 2))
+            dist = math.sqrt(dx * dx + dy * dy)
+            h = int((VIEW_H * 0.65) / max(dist, 0.75))
+            w = max(10, h // 3)
+            y_mid = VIEW_H // 2
+            y0 = max(0, y_mid - h // 2)
+            y1 = min(VIEW_H - 1, y_mid + h // 2)
+            x0 = max(0, sx - w // 2)
+            x1 = min(VIEW_W - 1, sx + w // 2)
+            col = AGENT_COLORS.get(other_name, (255, 200, 120))
+            img[y0:y1, x0:x1] = np.array(col, dtype=np.uint8)
+
+    if state.overlay:
+        # reticle
+        cx, cy = VIEW_W // 2, VIEW_H // 2
+        img[cy - 1:cy + 2, cx - 10:cx + 10] = np.array([120, 190, 255], dtype=np.uint8)
+        img[cy - 10:cy + 10, cx - 1:cx + 2] = np.array([120, 190, 255], dtype=np.uint8)
+
+    return img
+
+# -----------------------------
+# Top-down map render (truth or belief)
+# -----------------------------
+def render_topdown(grid: np.ndarray, agents: Dict[str, Agent], title: str, show_agents: bool = True) -> Image.Image:
+    w = grid.shape[1] * TILE
+    h = grid.shape[0] * TILE
+    im = Image.new("RGB", (w, h + 28), (10, 12, 18))
+    draw = ImageDraw.Draw(im)
+
+    # tiles
+    for y in range(grid.shape[0]):
+        for x in range(grid.shape[1]):
+            t = int(grid[y, x])
+            if t == -1:
+                col = (18, 20, 32)  # unknown
+            elif t == EMPTY:
+                col = (26, 30, 44)
+            elif t == WALL:
+                col = (190, 190, 210)
+            elif t == FOOD:
+                col = (255, 210, 120)
+            elif t == NOISE:
+                col = (255, 120, 220)
+            elif t == DOOR:
+                col = (140, 210, 255)
+            elif t == TELE:
+                col = (120, 190, 255)
+            else:
+                col = (80, 80, 90)
+
+            x0, y0 = x * TILE, y * TILE + 28
+            draw.rectangle([x0, y0, x0 + TILE - 1, y0 + TILE - 1], fill=col)
+
+    # grid lines
+    for x in range(grid.shape[1] + 1):
+        xx = x * TILE
+        draw.line([xx, 28, xx, h + 28], fill=(12, 14, 22))
+    for y in range(grid.shape[0] + 1):
+        yy = y * TILE + 28
+        draw.line([0, yy, w, yy], fill=(12, 14, 22))
+
+    # agents
+    if show_agents:
+        for name, a in agents.items():
+            cx = a.x * TILE + TILE // 2
+            cy = a.y * TILE + 28 + TILE // 2
+            col = AGENT_COLORS.get(name, (220, 220, 220))
+            r = TILE // 3
+            draw.ellipse([cx - r, cy - r, cx + r, cy + r], fill=col)
+            # heading tick
+            dx, dy = DIRS[a.ori]
+            draw.line([cx, cy, cx + dx * r, cy + dy * r], fill=(10, 10, 10), width=3)
+
+    # title bar
+    draw.rectangle([0, 0, w, 28], fill=(14, 16, 26))
+    draw.text((8, 6), title, fill=(230, 230, 240))
+
+    return im
+
+# -----------------------------
+# Autonomy policies (explicit rules)
+# -----------------------------
+def predator_policy(state: WorldState, step: int) -> str:
+    pred = state.agents["Predator"]
+    prey = state.agents["Prey"]
+    # If prey visible, chase: turn toward prey then forward
+    if visible(pred, prey, state.grid):
+        dx = prey.x - pred.x
+        dy = prey.y - pred.y
+        ang = (math.degrees(math.atan2(dy, dx)) % 360)
+        facing = ORI_DEG[pred.ori]
+        diff = (ang - facing + 540) % 360 - 180
+        if diff < -10:
+            return "L"
+        if diff > 10:
+            return "R"
+        return "F"
+    # else wander deterministically
+    r = rng_for(state.seed, step, stream=1)
+    return r.choice(["F", "L", "R", "F", "F"])
+
+def prey_policy(state: WorldState, step: int) -> str:
+    prey = state.agents["Prey"]
+    pred = state.agents["Predator"]
+    # If predator visible, flee: turn away then forward
+    if visible(prey, pred, state.grid):
+        dx = pred.x - prey.x
+        dy = pred.y - prey.y
+        ang = (math.degrees(math.atan2(dy, dx)) % 360)
+        facing = ORI_DEG[prey.ori]
+        diff = (ang - facing + 540) % 360 - 180
+        # want to face opposite direction: add 180
+        diff_away = ((diff + 180) + 540) % 360 - 180
+        if diff_away < -10:
+            return "L"
+        if diff_away > 10:
+            return "R"
+        return "F"
+    # else seek food if adjacent, else wander
+    for turn in [0, -1, 1, 2]:
+        ori = (prey.ori + turn) % 4
+        dx, dy = DIRS[ori]
+        nx, ny = prey.x + dx, prey.y + dy
+        if in_bounds(nx, ny) and state.grid[ny][nx] == FOOD:
+            if turn == 0:
+                return "F"
+            if turn == -1:
+                return "L"
+            if turn == 1:
+                return "R"
+            return "R"  # 180 via two rights across ticks; keep simple
+    r = rng_for(state.seed, step, stream=2)
+    return r.choice(["F", "L", "R", "F"])
+
+def scout_policy(state: WorldState, step: int) -> str:
+    # Scout tries to keep line-of-sight on predator without colliding
+    scout = state.agents["Scout"]
+    pred = state.agents["Predator"]
+    if los_clear(state.grid, scout.x, scout.y, pred.x, pred.y):
+        # orbit-ish: if too close, turn away; else meander
+        dist = abs(scout.x - pred.x) + abs(scout.y - pred.y)
+        if dist <= 3:
+            return "R"
+        r = rng_for(state.seed, step, stream=3)
+        return r.choice(["F", "L", "R", "F"])
+    else:
+        # seek predator direction
+        dx = pred.x - scout.x
+        dy = pred.y - scout.y
+        ang = (math.degrees(math.atan2(dy, dx)) % 360)
+        facing = ORI_DEG[scout.ori]
+        diff = (ang - facing + 540) % 360 - 180
+        if diff < -10:
+            return "L"
+        if diff > 10:
+            return "R"
+        return "F"
+
+# -----------------------------
+# Step simulation
+# -----------------------------
+def apply_action(state: WorldState, agent_name: str, action: str) -> None:
+    a = state.agents[agent_name]
+    if action == "L":
+        turn_left(a)
+    elif action == "R":
+        turn_right(a)
+    elif action == "F":
+        move_forward(state, a)
+
+def consume_tiles(state: WorldState) -> None:
+    prey = state.agents["Prey"]
+    tile = state.grid[prey.y][prey.x]
+    if tile == FOOD:
+        prey.energy = min(200, prey.energy + 35)
+        state.grid[prey.y][prey.x] = EMPTY
+        state.event_log.append(f"t={state.step}: Prey ate food (+energy).")
+
+def check_catch(state: WorldState) -> None:
+    pred = state.agents["Predator"]
+    prey = state.agents["Prey"]
+    if pred.x == prey.x and pred.y == prey.y:
+        state.caught = True
+        state.event_log.append(f"t={state.step}: CAUGHT.")
+
+def tick(state: WorldState, manual_action: Optional[str] = None) -> None:
+    if state.caught:
+        return
+
+    # Manual action applies to controlled agent first (if provided)
+    if manual_action:
+        apply_action(state, state.controlled, manual_action)
+
+    # Autonomy for the others (and for controlled if autorun)
+    step = state.step
+    # Controlled agent: if autorun and no manual action this tick, autopilot it
+    if state.autorun and not manual_action:
+        if state.controlled == "Predator":
+            act = predator_policy(state, step)
+        elif state.controlled == "Prey":
+            act = prey_policy(state, step)
+        else:
+            act = scout_policy(state, step)
+        apply_action(state, state.controlled, act)
+
+    # Non-controlled always run their policy each tick
+    for name in ["Predator", "Prey", "Scout"]:
+        if name == state.controlled:
+            continue
+        if name == "Predator":
+            act = predator_policy(state, step)
+        elif name == "Prey":
+            act = prey_policy(state, step)
+        else:
+            act = scout_policy(state, step)
+        apply_action(state, name, act)
+
+    consume_tiles(state)
+    check_catch(state)
+    state.step += 1
+
+# -----------------------------
+# History + branching
+# -----------------------------
+MAX_HISTORY = 3000  # keeps rewind practical on Spaces
+
+def snapshot_of(state: WorldState) -> Snapshot:
+    return Snapshot(
+        step=state.step,
+        agents={k: asdict(v) for k, v in state.agents.items()},
+        grid=[row[:] for row in state.grid],
+        event_log_tail=state.event_log[-12:],
+        caught=state.caught,
+    )
+
+def restore_into(state: WorldState, snap: Snapshot) -> None:
+    state.step = snap.step
+    state.grid = [row[:] for row in snap.grid]
+    for k, d in snap.agents.items():
+        state.agents[k] = Agent(**d)
+    state.caught = snap.caught
+    # preserve full log, but annotate jump
+    state.event_log.append(f"Jumped to t={snap.step} (rewind).")
+
+# -----------------------------
+# Belief updates
+# -----------------------------
+def update_belief_for_agent(state: WorldState, belief: np.ndarray, agent: Agent) -> None:
+    # Reveal tiles in a cone up to MAX_DEPTH using simple ray sampling
+    # plus always reveal own tile
+    belief[agent.y, agent.x] = state.grid[agent.y][agent.x]
+
+    base = math.radians(ORI_DEG[agent.ori])
+    half = math.radians(FOV_DEG / 2)
+    rays = 33 if agent.name != "Scout" else 45
+
+    for i in range(rays):
+        t = i / (rays - 1)
+        ang = base + (t * 2 - 1) * half
+        sin_a, cos_a = math.sin(ang), math.cos(ang)
+        ox, oy = agent.x + 0.5, agent.y + 0.5
+        depth = 0.0
+        while depth < MAX_DEPTH:
+            depth += 0.2
+            tx = int(ox + cos_a * depth)
+            ty = int(oy + sin_a * depth)
+            if not in_bounds(tx, ty):
+                break
+            belief[ty, tx] = state.grid[ty][tx]
+            if state.grid[ty][tx] == WALL:
+                break
+
+# -----------------------------
+# UI orchestration
+# -----------------------------
+def build_views(state: WorldState, beliefs: Dict[str, np.ndarray]) -> Tuple[np.ndarray, Image.Image, Image.Image, Image.Image, str, str]:
+    pov_agent = state.agents[state.pov]
+
+    # Update beliefs each frame (deterministic, based on current truth)
+    for name, a in state.agents.items():
+        update_belief_for_agent(state, beliefs[name], a)
+
+    # POV raycast
+    pov_img = raycast_view(state, pov_agent)
+
+    # Truth map
+    truth_np = np.array(state.grid, dtype=np.int16)
+    truth_img = render_topdown(truth_np, state.agents, f"Truth Map — t={state.step}  seed={state.seed}", show_agents=True)
+
+    # Belief maps (two most interesting: controlled + other)
+    ctrl = state.controlled
+    other = "Prey" if ctrl == "Predator" else "Predator"
+    ctrl_img = render_topdown(beliefs[ctrl], state.agents, f"{ctrl} Belief (Fog-of-War)", show_agents=True)
+    other_img = render_topdown(beliefs[other], state.agents, f"{other} Belief (Fog-of-War)", show_agents=True)
+
+    # Status + log
+    pred = state.agents["Predator"]
+    prey = state.agents["Prey"]
+    scout = state.agents["Scout"]
+
+    status = (
+        f"Controlled: {state.controlled} | POV: {state.pov} | "
+        f"AutoRun: {state.autorun} @ {state.speed_hz:.2f} Hz | "
+        f"Caught: {state.caught}\n"
+        f"Pred({pred.x},{pred.y}) ori={pred.ori} | "
+        f"Prey({prey.x},{prey.y}) ori={prey.ori} energy={prey.energy} | "
+        f"Scout({scout.x},{scout.y}) ori={scout.ori}"
+    )
+    log = "\n".join(state.event_log[-14:])
+    return pov_img, truth_img, ctrl_img, other_img, status, log
+
+def grid_click_to_tile(evt: gr.SelectData, selected_tile: int, state: WorldState) -> WorldState:
+    # evt.index is pixel coords (x,y) on truth image; our truth image has 28px title bar
+    x_px, y_px = evt.index
+    y_px = y_px - 28
+    if y_px < 0:
+        return state
+    gx = int(x_px // TILE)
+    gy = int(y_px // TILE)
+    if not in_bounds(gx, gy):
+        return state
+
+    # Protect borders from accidental deletion (optional)
+    if gx == 0 or gy == 0 or gx == GRID_W - 1 or gy == GRID_H - 1:
+        return state
+
+    state.grid[gy][gx] = selected_tile
+    state.event_log.append(f"t={state.step}: Edited tile ({gx},{gy}) -> {TILE_NAMES.get(selected_tile, selected_tile)}.")
+    return state
+
+def export_run(state: WorldState, history: List[Snapshot]) -> str:
+    payload = {
+        "seed": state.seed,
+        "current_step": state.step,
+        "controlled": state.controlled,
+        "pov": state.pov,
+        "autorun": state.autorun,
+        "speed_hz": state.speed_hz,
+        "overlay": state.overlay,
+        "branches": state.branches,
+        "history": [asdict(s) for s in history],
+    }
+    return json.dumps(payload, indent=2)
+
+def import_run(txt: str) -> Tuple[WorldState, List[Snapshot], Dict[str, np.ndarray], int]:
+    data = json.loads(txt)
+    st = init_state(int(data["seed"]))
+    st.controlled = data.get("controlled", "Predator")
+    st.pov = data.get("pov", st.controlled)
+    st.autorun = bool(data.get("autorun", False))
+    st.speed_hz = float(data.get("speed_hz", 8.0))
+    st.overlay = bool(data.get("overlay", False))
+    st.branches = dict(data.get("branches", {"main": 0}))
+
+    history = []
+    for s in data.get("history", []):
+        history.append(Snapshot(**s))
+
+    beliefs = init_belief()
+    rewind_idx = min(len(history) - 1, len(history) - 1 if history else 0)
+
+    if history:
+        restore_into(st, history[-1])
+
+    st.event_log.append("Imported run.")
+    return st, history, beliefs, rewind_idx
+
+# -----------------------------
+# Gradio app
+# -----------------------------
+with gr.Blocks(title="ChronoSandbox — Agent Timeline Lab") as demo:
+    gr.Markdown(
+        "## ChronoSandbox — Agent Timeline Lab\n"
+        "Deterministic multi-agent POV sandbox with **time dilation, rewind, and branching timelines**.\n"
+        "Everything is explicit: no hidden weights, no magic state."
+    )
+
+    # Persistent state
+    st = gr.State(init_state(seed=1337))
+    history = gr.State([snapshot_of(init_state(seed=1337))])  # start with step 0
+    beliefs = gr.State(init_belief())
+    rewind_index = gr.State(0)
+
+    with gr.Row():
+        pov_img = gr.Image(label="First-Person POV (Pseudo-3D)", type="numpy", width=VIEW_W, height=VIEW_H)
+        with gr.Column():
+            status = gr.Textbox(label="Status", lines=3)
+            log = gr.Textbox(label="Event Log", lines=14)
+
+    with gr.Row():
+        truth = gr.Image(label="Truth Map (click to edit tiles)", type="pil")
+        belief_a = gr.Image(label="Belief A", type="pil")
+        belief_b = gr.Image(label="Belief B", type="pil")
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.Markdown("### Controls")
+            with gr.Row():
+                btn_L = gr.Button("Turn Left (L)")
+                btn_F = gr.Button("Forward (F)")
+                btn_R = gr.Button("Turn Right (R)")
+            with gr.Row():
+                toggle_control = gr.Button("Toggle Controlled Agent")
+                toggle_pov = gr.Button("Toggle POV Camera")
+                btn_step = gr.Button("Tick (Single Step)")
+            with gr.Row():
+                autorun = gr.Checkbox(False, label="AutoRun")
+                overlay = gr.Checkbox(False, label="Overlay (reticle)")
+            speed = gr.Slider(0.25, 32.0, value=8.0, step=0.25, label="Speed (Hz) — time dilation")
+            tile_pick = gr.Radio(
+                choices=[(TILE_NAMES[k], k) for k in [EMPTY, WALL, FOOD, NOISE, DOOR, TELE]],
+                value=WALL,
+                label="Click-edit tile type"
+            )
+        with gr.Column(scale=2):
+            gr.Markdown("### Time Travel")
+            rewind = gr.Slider(0, 0, value=0, step=1, label="Rewind Scrubber (history index)")
+            btn_jump = gr.Button("Jump to Rewind Index")
+            btn_branch = gr.Button("Branch From Current (fork timeline)")
+            branch_name = gr.Textbox(value="branch_1", label="Branch name")
+            gr.Markdown("### Import / Export")
+            export_box = gr.Textbox(label="Export JSON", lines=10)
+            btn_export = gr.Button("Export Run")
+            import_box = gr.Textbox(label="Import JSON", lines=10)
+            btn_import = gr.Button("Import Run")
+
+    timer = gr.Timer(0.12)  # base UI refresh; actual tick rate controlled by speed_hz + autorun gating
+
+    def refresh(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int):
+        # clamp rewind slider max
+        r_max = max(0, len(hist) - 1)
+        r_idx = max(0, min(r_idx, r_max))
+        pov_np, truth_im, a_im, b_im, stxt, ltxt = build_views(state, bel)
+        return (
+            pov_np,
+            truth_im,
+            a_im,
+            b_im,
+            stxt,
+            ltxt,
+            gr.update(maximum=r_max, value=r_idx),
+            r_idx
+        )
+
+    def do_action(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int, act: str):
+        tick(state, manual_action=act)
+        hist.append(snapshot_of(state))
+        if len(hist) > MAX_HISTORY:
+            hist.pop(0)
+        r_idx = len(hist) - 1
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def do_tick(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int):
+        tick(state, manual_action=None)
+        hist.append(snapshot_of(state))
+        if len(hist) > MAX_HISTORY:
+            hist.pop(0)
+        r_idx = len(hist) - 1
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def set_toggles(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int, ar: bool, sp: float, ov: bool):
+        state.autorun = bool(ar)
+        state.speed_hz = float(sp)
+        state.overlay = bool(ov)
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def toggle_control_fn(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int):
+        order = ["Predator", "Prey", "Scout"]
+        i = order.index(state.controlled)
+        state.controlled = order[(i + 1) % len(order)]
+        state.event_log.append(f"t={state.step}: Controlled -> {state.controlled}.")
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def toggle_pov_fn(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int):
+        order = ["Predator", "Prey", "Scout"]
+        i = order.index(state.pov)
+        state.pov = order[(i + 1) % len(order)]
+        state.event_log.append(f"t={state.step}: POV -> {state.pov}.")
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def jump_fn(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int, idx: int):
+        if not hist:
+            return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+        idx = int(idx)
+        idx = max(0, min(idx, len(hist) - 1))
+        restore_into(state, hist[idx])
+        r_idx = idx
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def branch_fn(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int, name: str):
+        nm = (name or "").strip() or f"branch_{len(state.branches)+1}"
+        state.branches[nm] = r_idx
+        state.event_log.append(f"t={state.step}: Branched timeline '{nm}' at history idx={r_idx}.")
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def truth_click(evt: gr.SelectData, tile: int, state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int):
+        # apply edit, snapshot after edit
+        state = grid_click_to_tile(evt, int(tile), state)
+        hist.append(snapshot_of(state))
+        if len(hist) > MAX_HISTORY:
+            hist.pop(0)
+        r_idx = len(hist) - 1
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    def export_fn(state: WorldState, hist: List[Snapshot]):
+        return export_run(state, hist)
+
+    def import_fn(txt: str):
+        state, hist, bel, r_idx = import_run(txt)
+        # refresh outputs + return states
+        pov_np, truth_im, a_im, b_im, stxt, ltxt = build_views(state, bel)
+        r_max = max(0, len(hist) - 1)
+        return (
+            pov_np, truth_im, a_im, b_im, stxt, ltxt,
+            gr.update(maximum=r_max, value=r_idx),
+            state, hist, bel, r_idx
+        )
+
+    # Buttons
+    btn_L.click(do_action, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], api_name=False, queue=True, fn_kwargs={"act": "L"})
+    btn_F.click(do_action, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], api_name=False, queue=True, fn_kwargs={"act": "F"})
+    btn_R.click(do_action, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], api_name=False, queue=True, fn_kwargs={"act": "R"})
+
+    btn_step.click(do_tick, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+
+    toggle_control.click(toggle_control_fn, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+    toggle_pov.click(toggle_pov_fn, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+
+    autorun.change(set_toggles, inputs=[st, history, beliefs, rewind_index, autorun, speed, overlay], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+    speed.change(set_toggles, inputs=[st, history, beliefs, rewind_index, autorun, speed, overlay], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+    overlay.change(set_toggles, inputs=[st, history, beliefs, rewind_index, autorun, speed, overlay], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+
+    btn_jump.click(jump_fn, inputs=[st, history, beliefs, rewind_index, rewind], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+    btn_branch.click(branch_fn, inputs=[st, history, beliefs, rewind_index, branch_name], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+
+    truth.select(truth_click, inputs=[tile_pick, st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index], queue=True)
+
+    btn_export.click(export_fn, inputs=[st, history], outputs=[export_box], queue=True)
+    btn_import.click(import_fn, inputs=[import_box], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, st, history, beliefs, rewind_index], queue=True)
+
+    # Timer-driven autorun
+    def timer_fn(state: WorldState, hist: List[Snapshot], bel: Dict[str, np.ndarray], r_idx: int, ar: bool, sp: float):
+        state.autorun = bool(ar)
+        state.speed_hz = float(sp)
+
+        if not state.autorun or state.caught:
+            return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+        # How many sim ticks per UI frame?
+        # timer runs ~8.33 Hz (0.12s). We convert desired Hz to ticks per frame.
+        ticks_per_frame = max(1, int(round(state.speed_hz * 0.12)))
+        for _ in range(ticks_per_frame):
+            tick(state, manual_action=None)
+            hist.append(snapshot_of(state))
+            if len(hist) > MAX_HISTORY:
+                hist.pop(0)
+
+        r_idx = len(hist) - 1
+        return refresh(state, hist, bel, r_idx) + (state, hist, bel, r_idx)
+
+    timer.tick(
+        timer_fn,
+        inputs=[st, history, beliefs, rewind_index, autorun, speed],
+        outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index, st, history, beliefs, rewind_index],
+        queue=True
+    )
+
+    # Initial paint
+    demo.load(refresh, inputs=[st, history, beliefs, rewind_index], outputs=[pov_img, truth, belief_a, belief_b, status, log, rewind, rewind_index], queue=True)
+
+demo.queue().launch()