feat: playable Win3.x and Win9.x using js-dos

[bphenriques]

Closes #3143

The current EmulatorJS dosbox-pure core handles MS-DOS games but blank-screens tested Windows 3.x and Windows 9x titles. This PR adds js-dos v8.4.1 with its DOSBox-X backend as a dedicated in-browser player for the win3x and win9x platforms.

Related docs PR: rommapp/docs#110

Out of scope

To keep the integration narrow:

• MS-DOS remains on EmulatorJS, even though js-dos can also run DOS games.
• Saves remain browser-local and are not synchronized with RomM.
• Runtime readiness and bundle validation are deferred.

Changes

The integration follows the existing EmulatorJS and Ruffle patterns:

• Adds the v2 js-dos player and /rom/:rom/jsdos route.
• Adds the DISABLE_JSDOS administrator toggle.
• Bundles a pinned, checksummed js-dos release under /assets/jsdos in the full Docker image.
• Serves runtime assets same-origin with the required cross-origin isolation headers.
• Enables DOSBox-X, automatic startup, and automatic saving.
• Stores saves locally, isolated by RomM user and ROM.
• Performs a final save before leaving and handles unconfirmed save failures.
• Hides the dos.zone cloud UI with setNoCloud(true).
• Adds API types and automated coverage for routing, persistence, and player lifecycle.

Test plan

Automated tests cover player lifecycle, final-save handling, route departure, duplicate exits, and per-user save isolation. The remaining frontend, backend, build, and lint checks run in CI.

Tested titles:

• Fine Artist, which saves only after exiting the application back to Windows
• Four Magic School Bus titles
• Timon & Pumbaa's Jungle Games

Manual checks:

• Games start automatically.
• Saves persist between sessions.
• Saves are isolated between RomM users.
• Quitting returns to the game details page.
• The dos.zone cloud UI is hidden.

AI assistance disclosure

This contribution was developed with assistance from Amp and Claude. I reviewed, tested, and validated the design, implementation, and tests, and I take responsibility for the changes.

[bphenriques]

Actions to review:

• Check save mechanism. Works manually but the exit button is not working as I expected
• Assess if I need the event handler mechanism as documented in js-dos docs. E.g., custom file storage: https://js-dos.com/save-load-game-progress.html#retrieving-current-changes

Will review later this week once my weekly limits resets. Taking a look by hand in the meantime (just slower).

Done.

[bphenriques]

@gantoine, I think this is ready for an initial review when you have a chance. I tested saving plus if the launch/exit UX behave as expected. Please also take a look at the accompanying documentation PR.

As mentioned, I used AI assistance for the initial design and subsequent implementation review. The integration went through several iterations to keep the scope focused and consistent with existing players.

I am not an expert on this part of the codebase, so I would appreciate your feedback!

Thank you

[Copilot]

Pull request overview

Adds an in-browser js-dos (DOSBox-X) player path to RomM so Win3.x / Win9x ROMs can be played without the blank-screen issues seen with the existing EmulatorJS DOS core. This fits into the existing v2 player architecture alongside EmulatorJS and Ruffle, including cross-origin isolation support for SharedArrayBuffer and an admin-disable toggle surfaced via heartbeat.

Changes:

• Added a new v2 js-dos player view plus router wiring and play-action selection for win3x / win9x.
• Introduced DISABLE_JSDOS across backend config + heartbeat, and frontend support gating via useCanPlay / utils.
• Bundled a pinned js-dos release into the full Docker image and extended Nginx COOP/COEP headers for the new player route.

Reviewed changes

Copilot reviewed 35 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
frontend/src/v2/views/Player/JsDos.vue	New js-dos player view (runtime loader, lifecycle, local save scoping, quit flow).
frontend/src/v2/views/Player/JsDos.test.ts	Vitest coverage for js-dos player lifecycle, final-save flow, and save-key scoping.
frontend/src/v2/router/routes.ts	Registers the new v2 route component loader for jsdos.
frontend/src/v2/composables/useGameActions/index.ts	Routes Win3x/Win9x play actions to a hard navigation for /rom/:id/jsdos (SAB).
frontend/src/v2/composables/useGameActions/index.test.ts	Adds coverage ensuring js-dos is preferred over EmulatorJS for its platforms.
frontend/src/v2/composables/useCanPlay/index.ts	Adds canPlayJsDos and integrates it into the overall in-browser playability gate.
frontend/src/utils/index.ts	Adds isJsDosEmulationSupported() with DISABLE_JSDOS + platform slug support checks.
frontend/src/utils/index.test.ts	Unit tests for js-dos platform support logic, case-insensitivity, toggle behavior, and remap.
frontend/src/types/js-dos.d.ts	Adds TypeScript typings for the js-dos runtime factory and API surface used by the player.
frontend/src/stores/heartbeat.ts	Extends the default heartbeat shape with EMULATION.DISABLE_JSDOS.
frontend/src/plugins/router.ts	Adds the /rom/:rom/jsdos route and ROUTES.JSDOS constant.
frontend/src/locales/bg_BG/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/cs_CZ/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/de_DE/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/en_GB/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/en_US/play.json	Adds new play.* strings for js-dos save warning and quit confirmation (source locale).
frontend/src/locales/es_ES/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/fr_FR/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/hu_HU/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/it_IT/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/ja_JP/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/ko_KR/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/pl_PL/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/pt_BR/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/ro_RO/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/ru_RU/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/tr_TR/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/zh_CN/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/locales/zh_TW/play.json	Adds new play.* strings for js-dos save warning and quit confirmation.
frontend/src/generated/models/EmulationDict.ts	Updates generated OpenAPI types to include DISABLE_JSDOS.
env.template	Documents the new DISABLE_JSDOS env var.
docker/nginx/templates/default.conf.template	Adds COOP/COEP header mapping for the new /rom/*/jsdos player route.
docker/Dockerfile	Downloads and verifies js-dos release, then ships runtime assets into the full image.
backend/tests/endpoints/test_heartbeat.py	Extends heartbeat endpoint test to validate DISABLE_JSDOS is present and boolean.
backend/endpoints/responses/heartbeat.py	Extends the typed heartbeat response schema with DISABLE_JSDOS.
backend/endpoints/heartbeat.py	Includes DISABLE_JSDOS in the /heartbeat response payload.
backend/config/init.py	Adds env-var wiring for DISABLE_JSDOS.

Files not reviewed (1)

• frontend/src/generated/models/EmulationDict.ts: Generated file

Suppressed comments (1)

frontend/src/v2/views/Player/JsDos.vue:186

• The "Back to gallery" navigation depends on rom.value?.platform_id, which may be unset until the ROM request resolves. Use the seeded ROM data when available, and avoid pushing with an undefined param.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bphenriques]

There are multiple backends. I want to keep this PR minimal and adjust as needed rather than trying to replicate every possible 'knob'.

[gantoine]

@greptileai

[greptile-apps]

Greptile Summary

This PR adds a v2 js-dos/DOSBox-X browser player for Windows 3.x and Windows 9x bundles, including per-user local saves and lifecycle handling.

• Adds js-dos platform and bundle eligibility, player routing, runtime loading, and play-session integration.
• Adds the administrator disable flag through backend heartbeat and frontend capability state.
• Packages pinned js-dos assets in the full image and configures cross-origin-isolation headers.
• Adds player, routing, persistence, and lifecycle tests.

Confidence Score: 4/5

The query-sensitive isolation rule should be fixed before merging because valid js-dos URLs with query parameters cannot initialize the threaded emulator runtime.

The new player depends on COOP and COEP, but Nginx matches the full request URI with a pattern that rejects any query suffix and consequently serves affected player documents without cross-origin isolation.

Files Needing Attention: docker/nginx/templates/default.conf.template

Important Files Changed

Filename	Overview
frontend/src/v2/views/Player/JsDos.vue	Implements runtime loading, DOSBox-X startup, user-and-ROM-scoped browser saves, final-save confirmation, and player teardown.
frontend/src/v2/composables/useGameActions/index.ts	Routes eligible Windows bundles to js-dos while preserving streaming priority and hard navigation for isolation headers.
frontend/src/v2/composables/useCanPlay/index.ts	Adds file-sensitive js-dos playability alongside EmulatorJS and Ruffle.
docker/Dockerfile	Downloads, verifies, trims, and installs js-dos 8.4.1 assets into full images.
docker/nginx/templates/default.conf.template	Extends cross-origin isolation to js-dos, but query-bearing player URLs fail the end-anchored $request_uri match.
frontend/src/plugins/router.ts	Registers the shared js-dos URL and its v2 named view.
backend/endpoints/heartbeat.py	Exposes the new js-dos administrator toggle through the heartbeat capability response.

Prompt To Fix All With AI

### Issue 1
docker/nginx/templates/default.conf.template:20-29
**Query strings disable isolation**

When a js-dos player URL contains a query string, matching against `$request_uri` fails the end-anchored pattern, so Nginx omits COOP and COEP and the threaded emulator runtime cannot initialize.

```suggestion
map $uri $coep_header {
    default        "";
    ~^/rom/.*/(ejs|jsdos)$ "require-corp";
    ~^/console/rom/[0-9]+/play "require-corp";
}
map $uri $coop_header {
    default        "";
    ~^/rom/.*/(ejs|jsdos)$ "same-origin";
    ~^/console/rom/[0-9]+/play "same-origin";
}
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "refactor(jsdos): trim comments and inlin..." | Re-trigger Greptile}

[bphenriques]

Thank you for looking into this! Read the commits you added and there were some gaps in the initial implementation, was good to learn!

[bphenriques]

Just minor request to merge this one: rommapp/docs#110

Provides more insights on how to configure js-dos to co-exist with dosbox