A Link to the Past Tracker

A web-based item and progress tracker for The Legend of Zelda: A Link to the Past randomizer speedruns and playthroughs. This application helps players track their collected items, dungeon progress, and chest locations throughout their adventure in Hyrule.

Live Site

The tracker is available at: https://kqesar.github.io/alltp-tracker/

The tracker is automatically deployed to GitHub Pages from the latest master branch.

📜 Project History

This project was originally forked from TestRunnerSRL/lttp-tracker. However, the codebase has evolved dramatically with a complete rewrite using modern technologies:

Complete React 19 + TypeScript migration from the original implementation
Modern development stack with pnpm, Vitest, and comprehensive testing
Enhanced architecture with modular components and centralized state management
Web standards compliance with W3C HTML validation and WCAG accessibility
Modern CSS Grid layout replacing legacy table-based layouts with proper spacer elements
Keyboard navigation with full arrow key and Tab sequence support for accessibility
Mobile optimization with touch gestures, responsive design, and device detection
Advanced CI/CD pipeline with automated testing, coverage reporting, and security analysis
Improved user experience with better accessibility and responsive design

Due to these extensive changes, the codebases are now fundamentally different, though the core functionality and game logic remain inspired by the original tracker.

🎮 What is it for

This tracker is designed for A Link to the Past randomizer players who need to:

Track items: Monitor collected weapons, tools, and upgrades with visual indicators
Track dungeon progress: See which dungeons are accessible, completed, or still need items
Track chest locations: Mark which overworld chests have been opened
Track boss rewards: Monitor crystal and pendant rewards for each dungeon boss
Track medallion requirements: Manage Bombos, Ether, and Quake medallion requirements for Misery Mire and Turtle Rock

🛠️ Technical Stack

Frontend: React 19 with TypeScript 5
Layout: Modern CSS Grid architecture with W3C compliance
Styling: Custom CSS with game-themed assets and semantic HTML
Accessibility: WCAG compliant with proper ARIA attributes and full keyboard navigation
Package Manager: pnpm
Code Quality: Biome for linting and formatting
Testing: Vitest with React Testing Library and comprehensive coverage reporting
Security: CodeQL static analysis for vulnerability detection
CI/CD: GitHub Actions with automated testing, coverage reporting, and security analysis

🚀 How to Launch

Prerequisites

Node.js ≥ 22.0.0
pnpm ≥ 10.0.0

Installation & Development

# Clone the repository
git clone https://github.com/kqesar/alltp-tracker
cd alltp-tracker

# Install dependencies
pnpm install

# Start development server
pnpm dev

The application will be available at http://localhost:5173 (or the next available port).

Production Build

# Build for production
pnpm build

# Preview production build
pnpm preview

Code Quality & Testing

# Run linter
pnpm lint

# Fix linting issues automatically
pnpm lint:fix

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests with coverage and display table
pnpm test:coverage:show

# Display coverage table (requires coverage data)
pnpm coverage

Coverage Reporting

The project includes comprehensive test coverage reporting:

Terminal Display: Use pnpm test:coverage:show for an immediate coverage table
CI Integration: Coverage metrics are automatically reported in PR comments
Quality Thresholds: 🟢 Excellent (≥90%), 🟡 Good (≥80%), 🟠 Fair (≥70%), 🔴 Needs Improvement (<70%)
Current Status: 84.37% lines, 85.56% functions, 78.31% branches, 289 tests passing
Comprehensive Testing: Includes unit tests, integration tests, and keyboard navigation tests

🎯 How to Use

Item Tracking

Click items in the left grid to cycle through their states (0-4 for progressive items, on/off for binary items)
Visual feedback: Items show as dimmed when not obtained, bright when obtained
Progressive items: Bow (0-4), Gloves (0-2), Sword (0-4), etc. cycle through upgrade levels

Keyboard Navigation

Full keyboard accessibility is supported for power users and accessibility:

Arrow Keys (⬅️ ➡️ ⬆️ ⬇️): Navigate through the item grid with automatic wrap-around
Tab/Shift+Tab: Sequential navigation through all interactive elements
Space/Enter: Activate items to cycle through their states
Focus Indicators: Visual focus highlights for keyboard navigation
Grid Position: Intelligent navigation that skips empty cells and maintains position

Keyboard Navigation

Full keyboard accessibility is supported for power users and accessibility:

Arrow Keys (⬅️ ➡️ ⬆️ ⬇️): Navigate through the item grid with automatic wrap-around
Tab/Shift+Tab: Sequential navigation through all interactive elements
Space/Enter: Activate items to cycle through their states
Focus Indicators: Visual focus highlights for keyboard navigation
Grid Position: Intelligent navigation that skips empty cells and maintains position

Map Interaction

Chest markers: Click to mark overworld chests as opened/unopened
Boss icons: Click to mark dungeon bosses as beaten
Hover information: Mouse over any element to see requirements and details

Mobile & Touch Experience ✨ NEW

Touch Gestures: Natural touch interactions for mobile devices
- Tap: Normal interaction (equivalent to left-click)
- Long Press: Alternative interaction for advanced features
- Touch-Optimized: 48px item sizes with 44px minimum touch targets for accessibility
Responsive Design: Mobile-first approach with adaptive layouts
- Mobile (≤480px): Optimized grid and typography
- Tablet (≤768px): Balanced layout for medium screens
- Desktop (>1024px): Full feature experience
Device Detection: Automatic capability detection for optimal experience
Orientation Support: Portrait and landscape modes with adaptive layouts
Touch Accessibility: Full compatibility with screen readers and assistive technologies

Boss Overlays

Each dungeon boss has three clickable overlays:

Top-right (Medallion): For Misery Mire and Turtle Rock, cycle through medallion requirements (Unknown/Bombos/Ether/Quake)
Bottom-left (Chest count): Track remaining chests in the dungeon
Bottom-right (Reward): Track the boss reward (Crystal/Pendant type)

Visual Indicators

Green: Location/boss is accessible with current items
Red: Not accessible with current items
Yellow: Partially accessible (some items missing)
Dimmed: Already completed/opened

🎮 Game Features

Supported Items

Weapons: Bow, Boomerang, Hookshot, various rods
Tools: Hammer, Flippers, Boots, Gloves, Bottles
Magic: Medallions (Bombos, Ether, Quake), Magic Cape, Cane of Byrna
Key items: Moon Pearl, Mirror, Book of Mudora, Magic Powder

Dungeon Logic

Accessibility checking: Real-time calculation of which dungeons can be entered/completed
Chest requirements: Track which dungeon chests can be obtained
Boss logic: Separate tracking for boss accessibility vs. dungeon completion
Medallion requirements: Special logic for Dark World medallion dungeons

Map Features

64 overworld chest locations with requirement logic
10 dungeon bosses with individual state tracking
Interactive overlays for complex dungeon information
Coordinate transformation for different map orientations

🏗️ Project Structure

src/
├── components/
│   ├── tracker/           # Item tracking components
│   │   ├── TrackerGrid.tsx        # Main item grid layout
│   │   ├── grid/                  # Grid rendering components
│   │   │   ├── GridRow.tsx        # Individual grid rows
│   │   │   └── GridItem.tsx       # Individual grid items
│   │   ├── items/                 # Item-specific components
│   │   │   ├── BossItem.tsx       # Boss-specific item handling
│   │   │   └── RegularItem.tsx    # Standard item handling
│   │   └── overlays/              # Interactive overlay components
│   │       ├── ChestOverlay.tsx   # Dungeon chest counter
│   │       ├── RewardOverlay.tsx  # Boss reward indicator
│   │       └── MedaillonOverlay.tsx # Medallion requirement selector
│   ├── map/               # Map-related components
│   │   ├── MapTracker.tsx         # Interactive map component
│   │   ├── MapChest.tsx           # Map chest markers
│   │   ├── DungeonBoss.tsx        # Dungeon boss markers
│   │   └── DungeonChest.tsx       # Dungeon chest markers
│   └── ui/                # UI utility components
│       ├── Caption.tsx            # Hover caption display
│       └── Header.tsx             # Fixed header with navigation
├── constants/             # Centralized constants
│   └── index.ts          # All hardcoded values and configuration
├── data/
│   ├── chests.ts          # Chest and dungeon definitions
│   └── items.ts           # Item definitions and layout
├── stores/
│   └── gameStore.ts       # Zustand state management
├── styles/                # Modular CSS architecture
│   ├── index.css          # Main stylesheet imports
│   ├── variables.css      # CSS custom properties and design tokens
│   ├── base.css           # Reset styles and foundational rules
│   ├── header.css         # Header component styles
│   ├── tracker.css        # Item grid and tracker components
│   ├── map.css            # Map components and location markers
│   ├── overlays.css       # Interactive overlay components
│   ├── ui.css             # Caption system and mini icons
│   ├── tooltip.css        # Tooltip system with positioning and animations
│   ├── help.css           # Help overlay styles with responsive design
│   └── mobile.css         # Mobile & touch optimizations
├── hooks/                 # Custom React hooks
│   └── useKeyboardNavigation.ts # Keyboard navigation system for tracker grid
├── App.tsx                # Main application logic
└── main.tsx              # React entry point

Component Architecture

The application follows a modular component architecture with clear separation of concerns:

tracker/: Contains all item tracking functionality
- TrackerGrid: Main container for the CSS Grid-based item layout
- grid/: Rendering components for the CSS Grid structure
- items/: Item-specific logic and display components
- overlays/: Interactive overlay components for complex dungeon interactions
map/: Map and location tracking components
- MapTracker: Main interactive map with chest and boss markers
- MapChest: Individual chest marker components
- DungeonBoss: Interactive dungeon boss markers
- DungeonChest: Dungeon-specific chest counters
ui/: Reusable UI components
- Caption: Dynamic hover information display
- Header: Fixed header with navigation and external links
styles/: Modular CSS architecture
- variables.css: CSS custom properties and design tokens
- base.css: Reset styles and foundational rules
- header.css: Header component with backdrop blur and responsive design
- tracker.css: CSS Grid layout system and tracker-specific styles
- map.css: Map components and location markers
- overlays.css: Interactive overlay components
- ui.css: Caption system and mini icons
- tooltip.css: Tooltip system with positioning and animations
- help.css: Help overlay styles with responsive design
- index.css: Master import file for all stylesheets
constants/: Centralized configuration management
- All CSS class names, magic numbers, asset paths, and configuration values
- Simple export pattern for easy maintenance and consistency

Development Standards

Import System

@ Aliases: All imports use @/ aliases instead of relative paths for better maintainability
Examples:
- import { CSS_CLASSES } from "@/constants"
- import { useGameStore } from "@/stores/gameStore"
- import { TrackerGrid } from "@/components/tracker/TrackerGrid"

Constants Management

Centralized: All hardcoded values are defined in src/constants/index.ts
Categorized: Constants are organized into logical groups (CSS_CLASSES, DUNGEON_INDICES, etc.)
Simple Exports: Uses simple export declarations (export const OBJECT = {})
Coverage: Includes CSS class names, magic numbers, asset names, and configuration values

🤝 Contributing

This project uses modern React practices and development standards:

Code Standards

Functional components with hooks
TypeScript for type safety and better development experience
Modular architecture with small, focused components
@ Alias imports: Use @/ aliases instead of relative imports for better maintainability
Centralized constants: All hardcoded values stored in @/constants for consistency
Biome for consistent code formatting and linting
Comprehensive testing: All components must have tests with high coverage standards

Testing Standards

Required: All new components must include tests
Coverage Targets: Lines ≥90%, Functions ≥90%, Branches ≥80%
Tools: Vitest with React Testing Library
Commands:
- pnpm test - Run tests
- pnpm test:coverage:show - Run tests with coverage table
- pnpm coverage - View existing coverage metrics

Import Examples

// ✅ Good - Use @ aliases
import { CSS_CLASSES } from "@/constants";
import { useGameStore } from "@/stores/gameStore";
import { TrackerGrid } from "@/components/tracker/TrackerGrid";
import { Header } from "@/components/ui/Header";

// ❌ Avoid - Relative imports
import { CSS_CLASSES } from "../constants";
import { useGameStore } from "../../stores/gameStore";

CSS Architecture

// ✅ Main App component uses modular CSS
import "@/styles/index.css";

// ✅ Individual style modules are imported via index.css
// - @/styles/variables.css (design tokens)
// - @/styles/base.css (reset and foundation)  
// - @/styles/header.css (header component)
// - @/styles/tracker.css (item grid)
// - @/styles/map.css (map components)
// - @/styles/overlays.css (interactive overlays)
// - @/styles/ui.css (caption and mini icons)

Constants Usage

// ✅ Good - Use centralized constants
### Constants Usage
```tsx
// ✅ Good - Use centralized constants
<div className={CSS_CLASSES.MAP_CONTAINER}>
  {GRID_CONSTANTS.ITEMS_PER_ROW}
</div>

🎖️ Web Standards & Accessibility

This project achieves full compliance with modern web standards:

W3C HTML Validation

✅ Valid HTML5: All generated HTML passes W3C validation
✅ Semantic markup: Proper use of semantic elements (button, section, nav, header, main)
✅ No deprecated elements: Modern alternatives used throughout

WCAG Accessibility Compliance

✅ Screen reader support: All interactive elements have proper ARIA labels
✅ Keyboard navigation: Full keyboard accessibility for all features
✅ Semantic buttons: Interactive grid items use <button> elements instead of table cells
✅ Focus management: Clear focus indicators and logical tab order

Modern CSS Architecture

✅ CSS Grid layout: Modern layout system replacing legacy table-based approaches
✅ No layout tables: CSS Grid used for all grid layouts instead of HTML tables
✅ Responsive design: Grid adapts automatically to different screen sizes
✅ Custom properties: CSS variables for consistent theming and maintainability

Visual Consistency

✅ Identical rendering: New CSS Grid implementation matches original appearance exactly
✅ Same behavior: All user interactions work identically to the original design
✅ Performance optimized: Modern CSS Grid provides better performance than table layouts

This transformation was achieved while maintaining 100% visual and functional compatibility with the original design.

// ❌ Avoid - Hardcoded values

{7}

```

Conventional Commits

This project follows the Conventional Commits specification. All commit messages should be formatted as:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests or correcting existing tests
build: Changes that affect the build system or external dependencies
ci: Changes to our CI configuration files and scripts
chore: Other changes that don't modify src or test files

Examples:

feat(tracker): add medallion overlay for boss dungeons
fix(map): correct chest coordinates transformation
docs(readme): update installation instructions

Release Process

Releases are automated using GitHub Actions:

Automatic: Push to master branch triggers automatic patch release
Manual: Use GitHub Actions workflow dispatch to create minor/major releases
Changelog: Automatically generated from conventional commits

Pull requests welcome for bug fixes, feature improvements, and code quality enhancements!

🚀 Deployment

This project is automatically deployed to GitHub Pages using GitHub Actions:

Automatic Deployment Process

Trigger: Push to master branch or manual workflow dispatch
Quality Checks:
- ✅ pnpm lint - Code quality validation
- ✅ pnpm test:coverage - Test suite execution with coverage reporting
- 🔒 CodeQL Analysis - Security vulnerability scanning
- ✅ pnpm build - Production build verification
- 📊 Coverage metrics automatically reported in PR comments
- 🛡️ Security findings available in GitHub Security tab
Deploy: Built assets are automatically pushed to gh-pages branch and deployed

GitHub Pages Configuration

The deployment uses the traditional gh-pages branch approach:

Built assets are pushed to the gh-pages branch
GitHub Pages serves content from the gh-pages branch
No environment protection rules interfere with deployment

Manual Deployment

You can manually trigger a deployment via:

GitHub Actions → Deploy to GitHub Pages → Run workflow

📈 Recent Improvements

Coverage Integration

✅ Terminal Coverage Display: New pnpm test:coverage:show command shows formatted coverage table
✅ CI Coverage Reporting: Automated coverage metrics in PR comments with color-coded status indicators
✅ Enhanced Scripts: Added pnpm coverage for quick coverage viewing
✅ Quality Thresholds: Clear coverage standards with visual feedback (🟢🟡🟠🔴)

Development Experience

✅ Modern Import System: Complete migration to @/ aliases for better maintainability
✅ Centralized Constants: All hardcoded values moved to @/constants for consistency
✅ Comprehensive Testing: High coverage standards with automated reporting
✅ Enhanced CI/CD: Integrated coverage reporting in pull request workflow

Name		Name	Last commit message	Last commit date
Latest commit History 159 Commits
.github		.github
.husky		.husky
.vscode		.vscode
public		public
scripts		scripts
src		src
.commitlintrc.json		.commitlintrc.json
.editorconfig		.editorconfig
.gitignore		.gitignore
.versionrc.json		.versionrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.d.ts		vite.config.d.ts
vite.config.js		vite.config.js
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

License

kqesar/alltp-tracker

Folders and files

Latest commit

History

Repository files navigation

A Link to the Past Tracker

Live Site

📜 Project History

🎮 What is it for

🛠️ Technical Stack

🚀 How to Launch

Prerequisites

Installation & Development

Production Build

Code Quality & Testing

Coverage Reporting

🎯 How to Use

Item Tracking

Keyboard Navigation

Keyboard Navigation

Map Interaction

Mobile & Touch Experience ✨ NEW

Boss Overlays

Visual Indicators

🎮 Game Features

Supported Items

Dungeon Logic

Map Features

🏗️ Project Structure

Component Architecture

Development Standards

Import System

Constants Management

🤝 Contributing

Code Standards

Testing Standards

Import Examples

CSS Architecture

Constants Usage

🎖️ Web Standards & Accessibility

W3C HTML Validation

WCAG Accessibility Compliance

Modern CSS Architecture

Visual Consistency

Conventional Commits

Types:

Examples:

Release Process

🚀 Deployment

Automatic Deployment Process

GitHub Pages Configuration

Manual Deployment

📈 Recent Improvements

Coverage Integration

Development Experience

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 34

Uh oh!

Contributors 4

Uh oh!

Languages