# Session Summary

## Current State

The project is a Three.js/Vite space simulation with:

- autonomous ships
- orbital travel
- docking and undocking
- mining and refinery delivery
- refining / fabrication
- faction growth through ship and outpost production
- observer-focused debugging tools

The active runtime model now follows the intended layered architecture more closely:

- `order`
- `defaultBehavior`
- `assignment`
- `controllerTask`
- `state`

The previous `captainGoal` layer has been removed.

## Ship Runtime Model

Ships now carry:

- `order`
  - direct one-shot instruction such as `move-to`, `mine-this`, `dock-at`
- `defaultBehavior`
  - standing automation such as `auto-mine`, `patrol`, `escort-assigned`, `idle`
- `assignment`
  - contextual ownership / doctrine such as `unassigned`, `commander-subordinate`, `station-based`, `mining-group`
- `controllerTask`
  - immediate executable task such as `travel`, `dock`, `extract`, `unload`, `follow`, `undock`
- `state`
  - physical ship state such as `spooling-warp`, `warping`, `arriving`, `docking`, `docked`, `undocking`, `transferring`

Current precedence is:

1. `order`
2. `defaultBehavior`
3. assignment-derived fallback behavior
4. idle fallback

The main loop in [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts) is now:

- `refreshControlLayers()`
- `planControllerTask()`
- `updateControllerTask()`
- `advanceControlState()`

## Travel Model

Travel is destination-driven and orbital-centric.

- same-system travel:
  - `spooling-warp -> warping -> arriving`
- inter-system travel:
  - `spooling-ftl -> ftl -> arriving`
- arrival anchors the ship to the destination orbital when appropriate

Destination ownership lives in the `controllerTask`.

Examples:

- `travel(destination)`
- `dock(host, bay)`
- `extract(node)`
- `unload(station)`
- `undock(host)`

## Mining / Delivery / Refining

Current industrial loop:

1. miner travels to node
2. miner extracts ore
3. miner travels to refinery
4. miner docks
5. miner unloads over time
6. miner undocks
7. loop repeats

Important details:

- `mine-this` is a one-shot order and currently completes when cargo is full
- `auto-mine` is persistent behavior and includes its own internal phase state
- unloading is time-based through `transferRate` in [src/game/data/balance.json](/home/jbourdon/repos/space-game/src/game/data/balance.json)
- unload state is now `transferring`
- unload completion emits `<unloaded>`

Refineries and fabricators feed faction production.

The faction economy now uses fabricated goods to:

- build new ships
- build defense outposts in valuable systems

Current production behavior lives in:

- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts)
  - `tryBuildShipForFaction()`
  - `tryBuildOutpostForFaction()`

## Faction Growth Loop

The active empire growth loop is:

1. mine ore
2. refine / fabricate goods
3. spend goods on ships
4. spend goods on military outposts
5. project power into central / contested systems

This means the simulation is no longer missing a use for refined goods.

What is still missing is stronger strategic prioritization, for example:

- when to build more miners vs escorts vs warships
- how to react to throughput shortages
- how to react to pirate pressure

## Pirates / Threats

Pirates already exist as an active faction and can raid / fight.

Current pirate support includes:

- pirate faction command logic
- hostile target selection
- ship combat and destruction

What is still underdeveloped:

- explicit preference for miners, haulers, and refinery traffic
- clearer harassment behavior around resource chains

## Debug History

The debug window is focused on the selected ship and includes:

- `order`
- `defaultBehavior`
- `assignment`
- `controllerTask`
- `state`
- task target
- anchor

History is event-oriented plus explicit state lines.

Current notation includes:

- controller commands:
  - `[travel]`, `[dock]`, `[unload]`, `[undock]`
- state snapshots:
  - `state=move-to:.../travel-to-node    [travel]/(warping)`
- events:
  - `<arrived ...>`
  - `<docked>`
  - `<unloaded>`
  - `<undocked>`
  - `<cargo-full>`
  - `<cargo-empty>`
  - `<order ...>`
  - `<default-behavior ...>`
  - `<assignment ...>`
  - `<docking-clearance ...>`
  - `<docking-bay ...>`
  - `<anchor ...>`

History remains HTML-escaped before rendering and same-tick changes are still batched.

Copy-to-clipboard includes:

- current live summary block
- event history

## Selection / HUD

The HUD currently supports selecting:

- ships
- stations
- systems
- planets
- asteroid field nodes

Notable UI status:

- ship cards show cargo and current layered control summary
- station cards show ore stored and refined stock
- Fleet and Debug window toggle buttons exist
- debug history is scrollable and copyable

## Important Recent Changes

- removed the old `captainGoal` layer
- planner now derives `controllerTask` directly from `order` and `defaultBehavior`
- moved mining / patrol progress state into `order` and `defaultBehavior`
- updated debug / selection UI to show the active layered model
- removed confirmed dead code found by strict TypeScript unused checks

## Current Known Limitations

- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts) is still too large and owns too much simulation responsibility
- order types are still narrow
  - currently focused on `move-to`, `mine-this`, `dock-at`
- default behavior set is still narrow
  - currently focused on `idle`, `auto-mine`, `patrol`, `escort-assigned`
- pirate harassment exists but is not yet economically targeted enough
- faction production logic is timer-driven and only lightly reactive
- no persistence for saves, seeds, or layouts

## Important Files

- [src/game/GameApp.ts](/home/jbourdon/repos/space-game/src/game/GameApp.ts)
  - main simulation loop
  - layered planning
  - travel, docking, mining, unloading, faction growth, combat, debug history
- [src/game/types.ts](/home/jbourdon/repos/space-game/src/game/types.ts)
  - `order` / `defaultBehavior` / `assignment` / `controllerTask` / `state` model
- [src/game/world/worldFactory.ts](/home/jbourdon/repos/space-game/src/game/world/worldFactory.ts)
  - ship and station instancing
- [src/game/ui/presenters.ts](/home/jbourdon/repos/space-game/src/game/ui/presenters.ts)
  - selection cards
  - station cards
  - debug history markup
- [src/game/data/balance.json](/home/jbourdon/repos/space-game/src/game/data/balance.json)
  - travel, docking, transfer rates

## Validation

Validation passing at the end of this session:

- `npx tsc --noEmit --noUnusedLocals --noUnusedParameters`
- `npm run build`