# Wing Commander I port staging area

This directory contains the data-free Phase 2 browser foundation for **Wing
Commander I**. It uses the pinned [`wc1-re`](https://github.com/neuromancer/wc1-re)
SDL2 source reconstruction plus a small Ultimatum patch stack. Original game
data is never committed or embedded in the JavaScript/WebAssembly artifacts.

The supplied GOG DOS installation was runtime-tested from an isolated temporary
copy. The original install and its `SAVEGAME.WLD` were read-only throughout.
See [`ROADMAP.md`](ROADMAP.md), the
[Phase 0 audit](../../docs/engineering/WING_COMMANDER_I_PHASE0_AUDIT.md), and the
[Phase 1 results](../../docs/engineering/WING_COMMANDER_I_PHASE1_RESULTS.md), and
[Phase 2 results](../../docs/engineering/WING_COMMANDER_I_PHASE2_RESULTS.md).
The experimental resolution path is covered by the
[enhanced-rendering results](../../docs/engineering/WING_COMMANDER_I_ENHANCED_RENDERING_RESULTS.md).
The optional high-refresh experiment is described in the
[presentation-interpolation specification](../../docs/engineering/WING_COMMANDER_I_PRESENTATION_INTERPOLATION_SPEC.md)
and [prototype results](../../docs/engineering/WING_COMMANDER_I_INTERPOLATION_RESULTS.md).

## Current boundary

- Pinned engine and LZO dependency with archive and identifying-file hashes.
- One patch-stack representation for all engine changes.
- Reproducible data-free Emscripten build (`wingcommander1.js` and `.wasm`; no
  `.data` file).
- Shared `GameAdapter` with bounded DOS detection, staged install validation,
  explicit mount roles, capability metadata, and desktop/touch/gamepad profiles.
- Immutable `/game` data and writable `/profile/SAVEGAME.WLD`, connected to the
  legacy path by a runtime-only symlink.
- Binary `.ultsave` v1 export/import and generation recovery through the shared
  `SaveStore`.
- Semantic `EngineSession` input for flight axes, commands, pointer, and text.
- A semantic cockpit/expanded-flight-view toggle on F1, the touch command
  strip, and standard-gamepad left-stick click. Pulse commands remain pressed
  across one cooperative input turn so the recovered engine's key latches
  observe them reliably.
- Responsive desktop/mobile flight shell with a protected 4:3 viewport,
  thumb-stick, roll, combat cluster, throttle rail, system strip, portrait
  guidance, left-handed layout, adjustable controls, contextual numbered
  communications, and paced mobile text/Enter entry.
- A cooperative browser yield in modal input waits; the Vega pilot-name prompt
  accepts text and advances to the cockpit instead of freezing.
- An explicit experimental WebGL 2 flight renderer that redraws projected space
  sprites at the physical drawable resolution while preserving the original
  320x200 cockpit, HUD, palette, logic, and Original software-renderer fallback.
  Its sharp-bilinear reconstruction measures each rotated sprite's horizontal
  and vertical drawable magnification independently, including the 320x200 to
  4:3 aspect correction.
  Auto remains Original until cross-browser, physical-device, determinism, and
  performance checks pass.
- Local-only QA shell that mounts a caller-supplied isolated data directory and
  can run the Phase 2 semantic/checkpoint exercise with `?qa=1`; `?touch=1`
  keeps the touch layout visible for desktop inspection.
- Test-channel web packaging that accepts a user-selected licensed installation
  folder, stages recognized files into IndexedDB, restores managed checkpoints,
  and publishes the pinned data-free runtime plus corresponding wc1-re/LZO
  source under `/wingcommander1/`.
- Browser runtime reaches the restored OriginFX intro and Start Vega Campaign
  handoff with working keyboard and pointer input.
- The catalog record is test-channel-only. There's no wider route, cloud
  data upload, or iOS build yet.

## Data policy

Never add the GOG installation, `GAMEDAT`, `STREAMS`, executables, PDFs,
configuration files, `SAVEGAME.WLD`, `CRUSADE.WLD`, expansion data, extracted
assets, or generated data archives here. Players import their own licensed
copy. Builds stay data-free.

## Reproduce the source and build

Resolve the exact source revisions and apply the recorded patches:

```powershell
node ports/wingcommander1/scripts/resolve-upstream.mjs
```

With the repository's pinned Emscripten toolchain bootstrapped:

```powershell
node ports/wingcommander1/scripts/build-wasm.mjs
```

The build script consumes the engine and LZO checkouts under
`.cache/ports/wingcommander1/` by default. It does not accept or inspect game
data.

For isolated local QA only:

```powershell
node ports/wingcommander1/scripts/serve-qa.mjs `
  --artifacts=<wasm-build-directory> `
  --data=<isolated-game-data-copy>
```

The QA server binds to `127.0.0.1`. It isn't a general import path.

To verify a local installation through the generic import pipeline without
writing to it:

```powershell
node ports/wingcommander1/scripts/verify-local-install.mjs `
  --data="C:\Program Files\GOG Galaxy\Games\Wing Commander"
```

## Tests

```powershell
node --test `
  ports/wingcommander1/tests/wc1-install.test.cjs `
  ports/wingcommander1/tests/platform-contract.test.cjs `
  ports/wingcommander1/tests/touch-controls.test.cjs `
  ports/wingcommander1/tests/filter.test.cjs `
  ports/wingcommander1/adapter/adapter.test.cjs
node tools/engine-lock.mjs verify ports/wingcommander1/upstream.lock.json <wc1-re-checkout>
python ports/wingcommander1/scripts/qa-filters-cdp.py --data=<isolated-game-data-copy>
python ports/wingcommander1/scripts/qa-layout-cdp.py --data=<isolated-game-data-copy>
```