# Architecture

Idlegame is split into four layers.

## Engine

`src/engine/` contains deterministic gameplay logic:

- `tickLoop.ts`: fixed-timestep accumulator. Large elapsed deltas, including
  offline catch-up, drain through the same tick path as active play.
- `game.ts`: core game state, action queue, costs/unlocks on start, completion-driven
  queue advancement (actions do not auto-repeat when the queue is empty).
- `save.ts`: versioned save schema, serialized export/import strings, and
  offline elapsed calculation.
- `story.ts`: story graph traversal, triggers (boot, actionComplete,
  minResources), choices, outcomes.
- `num.ts`: branded numeric boundary and human-readable formatting.

The engine must stay pure. It does not import React, Zustand, browser APIs,
storage, requestAnimationFrame, or Date scheduling.

## Content

`src/content/` contains authored definitions validated by Zod. M0 includes one
resource and one timed action. M1 expands this into real resources, actions,
story nodes, automation unlocks, and prestige definitions.

## State

`src/state/` owns environment coupling:

- persistence backend selection: IndexedDB via `idb-keyval`, with localStorage
  fallback
- load-on-boot and autosave orchestration
- requestAnimationFrame loop and lifecycle hooks
- mapping engine state to view models
- Zustand store updates for React
- `storyOrchestration.ts`: evaluates triggers after boot/publish/action
  completion; maps prefs to panel auto-open.
- Player prefs (`prefs.ts`) in localStorage — not in save v1.

## UI

`src/ui/` renders the view model and calls runtime commands. Components should
not implement gameplay rules. The M0 shell includes a resource readout, action
panel, progress bar, and event log.

## Verification

Run the full local gate before pushing:

```powershell
pnpm typecheck
pnpm lint
pnpm test:coverage
pnpm build
```

Rendered checks for the walking skeleton:

- app loads without framework overlay or console errors
- starting the timed action increments Gold after completion
- reload preserves saved state
- reopening after time away credits offline progress