Skip to content

CLAUDE.md

Latest commit

 

History

History
126 lines (93 loc) · 5.75 KB

CLAUDE.md

File metadata and controls

126 lines (93 loc) · 5.75 KB
Raw

CLAUDE.md

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

Project Overview

qSpider is a web and desktop player for QSP (Quest Soft Player) games. It's built as a React application using NX workspace for monorepo management, with Tauri for desktop versions.

Development Commands

Starting Development Server

  • pnpm start - Start the main web player development server (http://localhost:4200)
  • pnpm start:standalone - Start standalone web player
  • pnpm start:desktop - Start desktop version with Tauri (requires Rust installed)
  • pnpm start:docs - Start documentation site

Building

  • pnpm build - Build all projects for production
  • pnpm build:standalone - Build standalone web player
  • pnpm build:desktop - Build desktop version
  • pnpm build:docs - Build documentation

Testing and Quality

  • pnpm test - unit tests in every project (nx test targets, inferred by the @nx/vitest plugin from each project's vite/vitest config); one project: pnpm nx test <project>. html-renderer, renderer and desktop run in Vitest browser mode, so they need Chromium: CHROME_BIN=/usr/bin/chromium or pnpm exec playwright install chromium
  • pnpm lint - Run ESLint on all projects
  • pnpm format - Format code with Prettier
  • pnpm format:check - Check code formatting
  • pnpm typecheck - Type-check all projects
  • pnpm check:rust - Rust fmt, clippy and tests for src-tauri
  • pnpm e2e:web - Web E2E (Playwright); needs CHROME_BIN=/usr/bin/chromium or pnpm exec playwright install chromium
  • pnpm e2e:standalone-web - Standalone web E2E (Playwright, port 4310); same browser requirement as e2e:web
  • pnpm e2e:desktop - Desktop E2E (WebdriverIO + tauri-driver); needs tauri-driver on PATH (~/.cargo/bin), WebKitWebDriver and Rust
  • pnpm e2e:standalone-desktop - Standalone desktop E2E (own Tauri debug build in target/e2e-standalone); same requirements as e2e:desktop
  • pnpm smoke:desktop - Desktop launch smoke of both desktop apps (no WebDriver; markers on stdout). On Linux it runs in the private session; on macOS/Windows it refuses unless CI is set (CI runs it on macOS and Windows); see apps/player-e2e/README.md "Launch smoke"
  • pnpm check - Fast subset: format, lint, typecheck, unit tests (every project, browser-mode ones included, so Chromium as for pnpm test), build, Rust checks, web and standalone web E2E (no desktop E2E)
  • pnpm check:full - pnpm check plus desktop and standalone desktop E2E

Before declaring work done locally, run format check, lint and typecheck plus the E2E specs the change touches, and report their results. The full gate is CI on the PR (all suites run there as parallel jobs); run pnpm check:full locally only when asked, or to reproduce a CI failure. pnpm check is the fast subset (no desktop E2E). Every check must pass; any failure is a regression to fix or report, never to hide or skip. Setup details: apps/player-e2e/README.md.

When writing or changing E2E tests, follow the Rules section of apps/player-e2e/README.md (areas, naming, locating by data-qsp/role/data-qa, seeEventually, OperatePlayer).

NX Specific Commands

  • nx build player - Build specific player app
  • nx serve player - Serve specific player app
  • nx affected - Run commands on affected projects only
  • nx dep-graph - View dependency graph

Architecture

Workspace Structure

The project uses NX monorepo with the following structure:

Applications (apps/):

  • player - Main web player application
  • player-standalone - Standalone web player
  • player-desktop - Desktop-specific player variant
  • docs - Documentation site (Docusaurus)

Libraries (libs/):

  • game-state - Core game state management and QSP API integration
  • game-shelf - Game library and storage management
  • renderer - Game content rendering
  • html-renderer - HTML content rendering
  • browser - Browser-specific utilities
  • desktop - Desktop-specific utilities
  • contracts - TypeScript interfaces and types
  • i18n - Internationalization support
  • importers - Game file import functionality
  • utils - Common utilities
  • tauri-storage - Tauri-specific storage adapters

Technology Stack

  • Frontend: React 19.3, TypeScript, Vite
  • State Management: Xoid for reactive state
  • UI Components: Radix UI primitives with custom styling
  • Desktop: Tauri (Rust backend)
  • Build System: NX workspace with Vite
  • Styling: TailwindCSS
  • Audio: Howler.js
  • Game Engine: @qsp/wasm-engine (WebAssembly QSP engine)

Key Libraries and Dependencies

  • @qsp/wasm-engine - Core QSP game engine (WebAssembly)
  • @qsp/converters - Game file format converters
  • @radix-ui/* - UI component primitives
  • @tauri-apps/api - Tauri desktop integration
  • dexie - IndexedDB wrapper for browser storage
  • i18next - Internationalization framework
  • xoid - Reactive state management

Development Notes

  • Default project is player as specified in nx.json
  • Uses ESLint for linting with TypeScript support
  • Prettier for code formatting
  • Commitizen for conventional commits
  • Husky for git hooks with lint-staged
  • The project supports both web and desktop deployment
  • Uses service workers for PWA functionality in web builds
  • Desktop version requires Rust toolchain for Tauri

Desktop Development

To set up desktop development:

  1. Install Rust: https://rustup.rs/
  2. Navigate to src-tauri directory and run cargo install
  3. Use pnpm start:desktop for development

Game Engine Integration

The application integrates with QSP games through the @qsp/wasm-engine WebAssembly module, providing:

  • Game execution and state management
  • Save/load functionality
  • Resource handling (images, audio, etc.)
  • HTML content rendering with custom themes