# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

IDApTIK is an asymmetric co-op stealth puzzle-platformer and adaptive game engine ecosystem. The main game (IDApixiTIK) is a browser-based hacking/network simulator built with ReScript and PixiJS. Players interact with devices (laptops, routers, servers, cameras) and use terminal/SSH mechanics to navigate networks. The project includes a pure reversible VM, multiplayer sync, an Elixir backend, and a developer portal.

## SAFETY: Staging vs Live

**This is the STAGING repository** for ReScript 13 migration testing. The live repo is `hyperpolymath/idaptik`. Do NOT push v13 changes back to the live repo.

## Development Commands

All commands use Deno (NOT npm/node). Defined in `deno.json`:

```bash
deno task dev          # Start development (ReScript watcher + Vite dev server)
deno task build        # Production build (ReScript compile + Vite build)
deno task res:build    # Compile ReScript only
deno task res:dev      # ReScript watch mode only
deno task res:clean    # Clean ReScript build artifacts
deno task lint         # Deno lint
deno task dev:vite     # Vite dev server only (without ReScript watcher)
deno task sync-server  # Start Elixir/Phoenix sync server
deno task dev:all      # Start sync server + game dev server
```

Dev server runs on port 8080. Sync server runs on port 4000.

## ReScript Status

| Property | Value |
|----------|-------|
| ReScript version | 12.2.0 (via deno.json) |
| @rescript/core | 1.6.1 |
| Module system | `esmodule` (in-source) |
| Config file | `rescript.json` (fully v13-clean) |
| Config keys | All modern (`dependencies`, `compiler-flags`, `-open RescriptCore`) |
| Deprecated Js.* APIs | **ZERO** — fully migrated 2026-03-03 |
| v13 readiness | Config ready; only blocker is rescript-legacy removal (UTF-8 crash) |
| Staging repo | `hyperpolymath/idaptik-rescript13-staging` (private, frozen baseline) |

### API Migration Rules (CRITICAL)

All deprecated `Js.*` APIs have been migrated. Do NOT reintroduce them:

| Deprecated | Replacement |
|-----------|-------------|
| `Js.Dict.*` | `Dict.*` (`Dict.make()`, `Dict.set()`, `Dict.keysToArray()`) |
| `Js.Array2.*` | `Array.*` |
| `Js.String2.*` | `String.*` |
| `Js.Math.*` | `Math.*` |
| `Js.Float.*` | `Float.*` |
| `Js.Int.*` | `Int.*` |
| `Js.Console.*` | `Console.*` |
| `Js.Json.classify()` | `JSON.Classify.classify()` (returns variant, NOT option) |
| `Js.Json.string()` | `JSON.Encode.string()` |
| `Js.Json.decodeObject()` | `JSON.Classify.classify()` with `Object(obj)` pattern match |
| `Js.log()` / `Js.log2()` | `Console.log()` / `Console.log2()` |

## Technology Stack

- **ReScript 12.2.0** — Primary language (~542 `.res` files), compiles to `.res.mjs`
- **Deno** — Runtime and package management (replaces Node/npm)
- **PixiJS 8.8.1** — 2D WebGL rendering engine
- **Vite 6.2.0** — Build tool and dev server
- **Elixir/Phoenix** — Sync server for multiplayer
- **Rust + ratatui** — Escape-hatch developer TUI
- **Gossamer** — Unified Modding Studio (idaptik-ums)
- **@pixi/sound** — Audio (BGM/SFX)
- **@pixi/ui** — UI components
- **motion** — Tweening/animation library
- **AssetPack** — Asset pipeline (raw-assets/ → public/assets/ + src/manifest.json)

## Architecture

### Component Structure

```
idaptik/
├── src/                     # Main game source (IDApixiTIK)
│   ├── Main.res             # Entry point
│   ├── manifest.json        # Generated by AssetPack (do not edit)
│   ├── app/
│   │   ├── combat/          # Combat mechanics
│   │   ├── companions/      # Companion characters (Moletaire, etc.)
│   │   ├── devices/         # Network device simulations
│   │   ├── enemies/         # Enemy AI and guards
│   │   ├── multiplayer/     # Client-side multiplayer logic
│   │   ├── narrative/       # Story and dialogue
│   │   ├── pickups/         # Collectibles
│   │   ├── player/          # Player character (physics, input, graphics)
│   │   ├── popups/          # Modal overlays
│   │   ├── proven/          # Formal verification integration
│   │   ├── screens/         # Game screens (navigation targets)
│   │   ├── tools/           # In-game tools
│   │   ├── ui/              # UI components (Button, Label, RoundedBox)
│   │   └── utils/           # Utilities (KeyboardNav, UserSettings)
│   ├── engine/              # Core game engine
│   └── bindings/            # JavaScript FFI bindings (Pixi, Sound, UI, Motion)
├── vm/                      # Pure reversible VM library
│   ├── src/                 # VM core (compiled .res.mjs output)
│   ├── lib/ocaml/           # VM source (.res files — THIS IS ACTUAL SOURCE)
│   ├── tests/               # VM instruction tests
│   └── benchmarks/          # Performance benchmarks
├── shared/                  # Cross-component types and utilities
│   ├── src/                 # Shared source
│   ├── lib/                 # Build artifacts (gitignored)
│   └── tests/               # 422/422 tests
├── sync-server/             # Elixir/Phoenix multiplayer sync
│   ├── config/              # Phoenix config
│   ├── lib/                 # Elixir source
│   └── test/                # Connectivity tests (6/6 pass)
├── dlc/                     # Downloadable content packs
├── idaptik-developers/      # Developer portal (17 ADRs, white paper)
├── idaptik-ums/             # Unified Modding Studio (Gossamer)
├── cadre-router/            # Navigation router library
├── rescript-ecosystem/      # ReScript tooling
├── scripts/                 # Build scripts (AssetPack Vite plugin)
├── raw-assets/              # Source assets (processed by AssetPack)
├── public/                  # Static assets (generated)
├── rescript.json            # ReScript compiler config (v13-clean)
└── deno.json                # Deno config, tasks, and dependency imports
```

**IMPORTANT:** `vm/lib/ocaml/*.res` files are actual VM source code, NOT build artifacts. The compiled output is in `vm/src/core/*.res.mjs`. Do not confuse the two.

### Key Patterns

**Screen Navigation**: Screens define lifecycle methods (prepare, show, hide, pause, resume, update, resize). Navigation.t manages a stack of screens/popups with asset preloading.

**Device System**: DeviceTypes.device interface with `getInfo()` and `openGUI()`. Factory pattern via DeviceFactory.res. Security levels: Open, Weak, Medium, Strong.

**Network Topology**: Star topology with central router. Features DNS resolution, traceroute, SSH between devices, zone-based layout (LAN, VLAN, External).

**State Management**: Functional with immutable records; mutable fields only where necessary. LocalStorage for persistence via engine/utils/Storage.res.

**VM Architecture**: 23 instructions (Tier 0-4), stack, memory, subroutines, I/O ports. All operations are reversible. State serialisation uses `JSON.Classify.classify` API.

**Multiplayer**: PhoenixSocket V2, terminal co-op, VMMessageBus.readPortOutput. Playwright E2E testing (5 suites).

### Entry Point Flow

1. Main.res creates Engine instance
2. Engine initializes PixiJS Application and loads assets
3. LoadScreen shown, then WorldScreen
4. Player character navigates platformer world, interacts with devices

### Asset Pipeline

Raw assets in `raw-assets/` are processed by AssetPack (via custom Vite plugin in `scripts/assetpack-vite-plugin.js`) into `public/assets/` with manifest at `src/manifest.json`. Assets are loaded by bundle name.

## ReScript Conventions

- Files compile to `.res.mjs` alongside source (in-source mode)
- Module namespaces pattern: `module ModuleName = { ... }`
- FFI bindings in `src/bindings/` wrap external JS libraries
- Use `@rescript/core` for standard library (opened globally via `-open RescriptCore`)
- Use `Dict.*`, `Array.*`, `String.*`, `Math.*`, `Console.*` — NEVER `Js.*` equivalents
- JSON parsing: `JSON.parseExn` + `JSON.Classify.classify` with pattern matching
- JSON encoding: `JSON.Encode.string`, `JSON.stringifyAny`
- Belt is fully BANNED. All Belt.* APIs (including Belt.Set.String) migrated to @rescript/core 2026-03-09. Belt.Set.String replaced with `Set.t<string>` (JS Set).

## Machine-Readable State

Project state tracked in `.machine_readable/STATE.scm` (Guile Scheme format). Update this file when completing significant work — it tracks component completion percentages, migration status, and critical next actions.
