eye: Instructions file for Codex

AGENTS.md — AI Agent Reference for EYE

This document helps AI coding agents understand the EYE 3D viewer codebase for modification, debugging, and extension.

---

Overview

EYE is a zero-build, single-page 3D object viewer served as static files via Nginx. It uses Three.js (r170) loaded via ES module import maps — there is no bundler, no transpiler, and no node_modules.

Architecture

┌─────────────────────────────────────────────────────┐
│  index.html (single page, all UI structure)         │
│  ┌───────────────────────────────────────────────┐  │
│  │  app.js — Main orchestrator                   │  │
│  │  ├── SceneManager (scene-manager.js)          │  │
│  │  ├── FileLoader (file-loader.js)              │  │
│  │  ├── ComparisonMode (comparison-mode.js)      │  │
│  │  ├── MaterialPanel (material-panel.js)        │  │
│  │  ├── LightingPanel (lighting-panel.js)        │  │
│  │  ├── AnimationPanel (animation-panel.js)      │  │
│  │  └── HistoryPanel (history-panel.js)          │  │
│  │       └── HistoryStore (history-store.js)     │  │
│  └───────────────────────────────────────────────┘  │
│  style.css (complete design system)                  │
└─────────────────────────────────────────────────────┘

Key Files

src/js/app.js

• Entry point. Instantiates all modules.
• _handleFiles(files) — Central file routing. When comparison mode is active, routes to ComparisonMode.loadToSlot(). Otherwise loads into the main SceneManager.
• _bindSidebarToggles() — Responsive sidebar drawer logic.
• All UI event bindings: file upload, drag-and-drop, keyboard shortcuts, panel toggles.

src/js/scene-manager.js

• Manages a single Three.js scene: renderer, camera, controls, lights, grid/axes helpers.
• setModel(object, clips) — Replaces current model, auto-fits camera.
• _resize() — Called every frame in _animate(), accounts for pixel ratio and 0-dimension guards.
• _fitCameraToModel(object) — Centers camera on model bounding box.
• Constructor takes a <canvas> element and sets up the full rendering pipeline.