From 882f95157120bc8df7a79f1a6291ae8e45596d67 Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 19:51:33 +0100
Subject: [PATCH 1/7] wip

---
 .gitignore                                    |  10 +
 README.md                                     |  44 ++-
 .../leaderboard/sim/SimulationMain.scala      |  88 +++++
 .../src/main/resources/common-reference.conf  |   0
 .../jvm/src/main/resources/webapp/index.html  | 149 ++++++++
 .../scala/leaderboard/LeaderboardRole.scala   |   0
 .../leaderboard/config/PostgresCfg.scala      |   0
 .../leaderboard/config/PostgresPortCfg.scala  |   0
 .../scala/leaderboard/http/HttpServer.scala   |  53 +++
 .../plugins/LeaderboardPlugin.scala           |  38 +-
 .../plugins/PostgresDockerPlugin.scala        |   0
 .../leaderboard/repo/LadderPostgres.scala     |  42 +++
 .../leaderboard/repo/ProfilesPostgres.scala   |  47 +++
 .../src/main/scala/leaderboard/sql/SQL.scala  |   0
 .../leaderboard/sql/TransactorResource.scala  |   0
 .../src/test/scala/leaderboard/Rnd.scala      |   0
 .../test/scala/leaderboard/WiringTest.scala   |   0
 .../src/test/scala/leaderboard/tests.scala    |   0
 .../src/test/scala/leaderboard/zioenv.scala   |   0
 .../main/scala/leaderboard/api/HttpApi.scala  |   0
 .../scala/leaderboard/api/LadderApi.scala     |   0
 .../scala/leaderboard/api/ProfileApi.scala    |   0
 .../dispatch/LocalDispatcher.scala            |  45 +++
 .../leaderboard/model/QueryFailure.scala      |   0
 .../leaderboard/model/RankedProfile.scala     |   0
 .../scala/leaderboard/model/UserProfile.scala |   0
 .../scala/leaderboard/model/package.scala     |   0
 .../plugins/LeaderboardCoreModule.scala       |  46 +++
 .../main/scala/leaderboard/repo/Ladder.scala  |  26 ++
 .../scala/leaderboard/repo/Profiles.scala     |  26 ++
 .../scala/leaderboard/services/Ranks.scala    |   0
 .../scala/leaderboard/http/HttpServer.scala   |  35 --
 .../main/scala/leaderboard/repo/Ladder.scala  |  60 ----
 .../scala/leaderboard/repo/Profiles.scala     |  65 ----
 build.sbt                                     | 161 +++++++--
 ...60513-1757-questions-scalajs-simulation.md | 337 ++++++++++++++++++
 launch-sim                                    |  12 +
 launcher                                      |   2 +-
 project/plugins.sbt                           |   2 +
 39 files changed, 1055 insertions(+), 233 deletions(-)
 create mode 100644 bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
 rename bifunctor-tagless/{ => jvm}/src/main/resources/common-reference.conf (100%)
 create mode 100644 bifunctor-tagless/jvm/src/main/resources/webapp/index.html
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/LeaderboardRole.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/config/PostgresCfg.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/config/PostgresPortCfg.scala (100%)
 create mode 100644 bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala (66%)
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/plugins/PostgresDockerPlugin.scala (100%)
 create mode 100644 bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/LadderPostgres.scala
 create mode 100644 bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/ProfilesPostgres.scala
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/sql/SQL.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/main/scala/leaderboard/sql/TransactorResource.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/test/scala/leaderboard/Rnd.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/test/scala/leaderboard/WiringTest.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/test/scala/leaderboard/tests.scala (100%)
 rename bifunctor-tagless/{ => jvm}/src/test/scala/leaderboard/zioenv.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/api/HttpApi.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/api/LadderApi.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/api/ProfileApi.scala (100%)
 create mode 100644 bifunctor-tagless/shared/src/main/scala/leaderboard/dispatch/LocalDispatcher.scala
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/model/QueryFailure.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/model/RankedProfile.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/model/UserProfile.scala (100%)
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/model/package.scala (100%)
 create mode 100644 bifunctor-tagless/shared/src/main/scala/leaderboard/plugins/LeaderboardCoreModule.scala
 create mode 100644 bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Ladder.scala
 create mode 100644 bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Profiles.scala
 rename bifunctor-tagless/{ => shared}/src/main/scala/leaderboard/services/Ranks.scala (100%)
 delete mode 100644 bifunctor-tagless/src/main/scala/leaderboard/http/HttpServer.scala
 delete mode 100644 bifunctor-tagless/src/main/scala/leaderboard/repo/Ladder.scala
 delete mode 100644 bifunctor-tagless/src/main/scala/leaderboard/repo/Profiles.scala
 create mode 100644 docs/drafts/20260513-1757-questions-scalajs-simulation.md
 create mode 100755 launch-sim

diff --git a/.gitignore b/.gitignore
index 7c003ed..a8b5168 100644
--- a/.gitignore
+++ b/.gitignore
@@ -126,3 +126,13 @@ hs_err_pid*
 ### Scala template
 *.class
 *.log
+
+# Project-local sbt/coursier/ivy caches used by the containerised dev loop.
+.cache/
+
+# Scala.js bundle copied here by the `copySimJs` sbt task — regenerated on
+# demand from bifunctor-tagless-js. Not checked in.
+bifunctor-tagless/jvm/src/main/resources/webapp/main.js
+bifunctor-tagless/jvm/src/main/resources/webapp/*.js.map
+bifunctor-tagless/jvm/src/main/resources/webapp/internal-*.js
+
diff --git a/README.md b/README.md
index 93fa7f2..3bc7428 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,44 @@ curl -X GET http://localhost:8080/ladder
 curl -X GET http://localhost:8080/profile/50753a00-5e2e-4a2f-94b0-e6721b0a3cc4
 ```
 
+### Perfect simulation in the browser (`bifunctor-tagless` only)
+
+The `bifunctor-tagless` variant is cross-built for the JVM and Scala.js. The
+same `LadderApi`/`ProfileApi` http4s routes that the JVM server exposes are
+also assembled in the browser into an in-process `LocalDispatcher`, which a
+`@JSExportTopLevel("LeaderboardSim")` object surfaces to JavaScript. The JS
+graph is configured with `Repo -> Dummy`, so it uses the same in-memory
+repositories that the JVM tests use — no network, no postgres, no docker.
+
+A small demo UI in `bifunctor-tagless/jvm/src/main/resources/webapp/` lets you
+call each endpoint with a radio toggle between **production** (real HTTP) and
+**simulation** (the in-page Scala.js build).
+
+To use it, run the single convenience script — it builds the Scala.js bundle,
+copies it next to the UI, and starts the server in dummy mode:
+
+```bash
+./launch-sim
+```
+
+Then open <http://localhost:8080/>. You can also open
+`bifunctor-tagless/jvm/src/main/resources/webapp/index.html` directly via
+`file://` (CORS on the server allows the `null` origin used by `file://`).
+
+If you prefer the steps separately:
+
+```bash
+sbt copySimJs                            # build + copy the Scala.js bundle
+./launcher -u repo:dummy :leaderboard    # start the server
+```
+
+The "Production" radio talks to `http://localhost:8080`; the "Simulation"
+radio calls `window.LeaderboardSim.call(method, path, body)`, which runs the
+exact same request through the in-browser http4s routes. State only persists
+within each mode — flipping back and forth is itself a useful demonstration
+that the simulation is a clean process that knows nothing about the real
+server's state.
+
 #### Note
 
 If `./launcher` command fails for you with some cryptic stack trace, there's most likely an issue with your Docker. First of all, check that you have `docker` and `contrainerd` daemons running. If you're using something else than Ubuntu, please stick to the relevant [installation page](https://docs.docker.com/engine/install/):
@@ -61,7 +99,7 @@ Both of them should have `Active: active (running)` status. If your problem isn'
 Use `sbt` to build a native Linux binary with GraalVM NativeImage under Docker:
 
 ```bash
-sbt bifunctor-tagless/GraalVMNativeImage/packageBin
+sbt bifunctor-taglessJVM/GraalVMNativeImage/packageBin
 ```
 
 If you want to build the app using local `native-image` executable (e.g. on a Mac), comment out the `graalVMNativeImageGraalVersion` key in `build.sbt` first.
@@ -69,13 +107,13 @@ If you want to build the app using local `native-image` executable (e.g. on a Ma
 To test the native app with dummy repositories run:
 
 ```bash
-./bifunctor-tagless/target/graalvm-native-image/bifunctor-tagless -u scene:managed -u repo:dummy :leaderboard
+./bifunctor-tagless/jvm/target/graalvm-native-image/bifunctor-tagless -u scene:managed -u repo:dummy :leaderboard
 ```
 
 To test the native app with production repositories in Docker run:
 
 ```bash
-./bifunctor-tagless/target/graalvm-native-image/bifunctor-tagless -u scene:managed -u repo:prod :leaderboard
+./bifunctor-tagless/jvm/target/graalvm-native-image/bifunctor-tagless -u scene:managed -u repo:prod :leaderboard
 ```
 
 Notes:
diff --git a/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
new file mode 100644
index 0000000..f37eff3
--- /dev/null
+++ b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
@@ -0,0 +1,88 @@
+package leaderboard.sim
+
+import distage.StandardAxis.Repo
+import distage.{Activation, Injector, ModuleDef, Roots}
+import izumi.distage.modules.DefaultModule2
+import izumi.logstage.distage.LogIO2Module
+import leaderboard.dispatch.LocalDispatcher
+import leaderboard.plugins.LeaderboardCoreModule
+import zio.{IO, Promise as ZPromise, Runtime, Unsafe, ZIO}
+
+import scala.concurrent.ExecutionContext
+import scala.scalajs.concurrent.JSExecutionContext
+import scala.scalajs.js
+import scala.scalajs.js.JSConverters.*
+import scala.scalajs.js.annotation.{JSExport, JSExportTopLevel}
+
+/**
+  * Entrypoint for the in-browser "perfect simulation" of the leaderboard
+  * backend. Boots the same distage object graph as the JVM application but
+  * with `Repo` axis pinned to `Dummy` (so all repository calls hit the
+  * in-memory implementations), then exposes the resulting [[LocalDispatcher]]
+  * to JavaScript as `window.LeaderboardSim.call(method, path, body)`.
+  *
+  * The dispatcher invokes the exact same `HttpRoutes` the JVM server uses,
+  * so the front-end can address it with the same method/path/body it would
+  * send via fetch() to the real backend.
+  */
+@JSExportTopLevel("LeaderboardSim")
+object SimulationMain {
+
+  private type G[A] = IO[Throwable, A]
+
+  // A zio runtime — fine on JS since the default runtime does not assume any
+  // JVM-specific scheduler.
+  private val runtime: Runtime[Any] = Runtime.default
+
+  // JS event loop — used only to materialize the cats Future returned by
+  // `runtime.unsafe.runToFuture` into a JavaScript Promise.
+  private implicit val ec: ExecutionContext = JSExecutionContext.queue
+
+  // We resolve the dispatcher asynchronously (distage produce returns a
+  // resource) and surface it through this promise. Every JS `call(...)`
+  // awaits this before dispatching, so the front-end never sees an
+  // uninitialised state.
+  private val dispatcherReady: ZPromise[Throwable, LocalDispatcher[IO]] =
+    Unsafe.unsafe(implicit u => runtime.unsafe.run(ZPromise.make[Throwable, LocalDispatcher[IO]]).getOrThrow())
+
+  locally {
+    val module = new ModuleDef {
+      include(LeaderboardCoreModule.api[IO])
+      include(LeaderboardCoreModule.repoDummy[IO])
+      // LogIO2[IO] needed by ProfileApi.
+      include(LogIO2Module[IO]())
+      // BIO typeclass instances (IO2, Async2, Primitives2, ...) used by the
+      // dummy repos and the dispatcher.
+      include(DefaultModule2[IO])
+    }
+
+    // Build the object graph and keep the resource open for the lifetime of
+    // the page. We never finalize — the in-memory dummy state should live as
+    // long as the JS module is loaded.
+    val program: G[Nothing] =
+      Injector.NoProxies[G]()
+        .produce(module, Roots.target[LocalDispatcher[IO]], Activation(Repo -> Repo.Dummy))
+        .use {
+          locator =>
+            dispatcherReady.succeed(locator.get[LocalDispatcher[IO]]) *> ZIO.never
+        }
+        .catchAll(err => dispatcherReady.fail(err) *> ZIO.never)
+
+    Unsafe.unsafe(implicit u => runtime.unsafe.fork(program))
+  }
+
+  /**
+    * Dispatch a request to the simulated backend.
+    *
+    * @return a JS promise resolving to `{ status: Int, body: String }`.
+    */
+  @JSExport
+  def call(method: String, path: String, body: String): js.Promise[js.Dynamic] = {
+    val program: G[js.Dynamic] = for {
+      dispatcher <- dispatcherReady.await
+      response   <- dispatcher.call(method, path, body)
+    } yield js.Dynamic.literal(status = response.status, body = response.body)
+
+    Unsafe.unsafe(implicit u => runtime.unsafe.runToFuture(program).toJSPromise)
+  }
+}
diff --git a/bifunctor-tagless/src/main/resources/common-reference.conf b/bifunctor-tagless/jvm/src/main/resources/common-reference.conf
similarity index 100%
rename from bifunctor-tagless/src/main/resources/common-reference.conf
rename to bifunctor-tagless/jvm/src/main/resources/common-reference.conf
diff --git a/bifunctor-tagless/jvm/src/main/resources/webapp/index.html b/bifunctor-tagless/jvm/src/main/resources/webapp/index.html
new file mode 100644
index 0000000..0e7fc7d
--- /dev/null
+++ b/bifunctor-tagless/jvm/src/main/resources/webapp/index.html
@@ -0,0 +1,149 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>distage-example leaderboard demo</title>
+  <style>
+    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+    body  { margin: 1.5rem; max-width: 60rem; }
+    h1    { margin: 0 0 0.25rem; }
+    p.lead { color: #666; margin: 0 0 1rem; }
+    fieldset { margin-bottom: 1rem; }
+    label { display: inline-block; min-width: 7rem; }
+    input[type=text], input[type=number] { width: 22rem; }
+    button { margin-top: 0.5rem; }
+    pre   { background: #f4f4f4; padding: 0.5rem 1rem; white-space: pre-wrap; word-break: break-word; }
+    .row  { display: flex; gap: 1.5rem; flex-wrap: wrap; }
+    .row > * { flex: 1 1 24rem; }
+    .mode { padding: 0.5rem 1rem; background: #fffbe6; border: 1px solid #e0d27a; border-radius: 4px; }
+    @media (prefers-color-scheme: dark) {
+      pre  { background: #1e1e1e; }
+      .mode { background: #2a2510; border-color: #6b5a1a; }
+    }
+  </style>
+</head>
+<body>
+  <h1>distage-example leaderboard</h1>
+  <p class="lead">
+    Hit the same endpoints the README's <code>curl</code> snippets call.
+    Toggle between the real HTTP backend and an in-browser
+    Scala.js simulation built from the same distage object graph with
+    <code>Repo&nbsp;→&nbsp;Dummy</code>.
+  </p>
+
+  <fieldset class="mode">
+    <legend>Backend</legend>
+    <label><input type="radio" name="mode" value="prod" checked> Production (HTTP <code>http://localhost:8080</code>)</label>
+    <label><input type="radio" name="mode" value="sim"> Simulation (Scala.js, in-page)</label>
+    <p id="sim-status" style="margin:0.5rem 0 0; color:#888;">simulation: loading…</p>
+  </fieldset>
+
+  <div class="row">
+    <fieldset>
+      <legend>Submit score — <code>POST /ladder/{user}/{score}</code></legend>
+      <div><label>user id</label><input id="ladder-user" type="text" value="50753a00-5e2e-4a2f-94b0-e6721b0a3cc4"></div>
+      <div><label>score</label><input id="ladder-score" type="number" value="100"></div>
+      <button id="btn-submit-score">Submit</button>
+    </fieldset>
+
+    <fieldset>
+      <legend>Get ladder — <code>GET /ladder</code></legend>
+      <button id="btn-get-ladder">Fetch</button>
+    </fieldset>
+
+    <fieldset>
+      <legend>Set profile — <code>POST /profile/{user}</code></legend>
+      <div><label>user id</label><input id="profile-user" type="text" value="50753a00-5e2e-4a2f-94b0-e6721b0a3cc4"></div>
+      <div><label>name</label><input id="profile-name" type="text" value="Kai"></div>
+      <div><label>description</label><input id="profile-desc" type="text" value="S C A L A"></div>
+      <button id="btn-set-profile">Save</button>
+    </fieldset>
+
+    <fieldset>
+      <legend>Get profile — <code>GET /profile/{user}</code></legend>
+      <div><label>user id</label><input id="profile-get-user" type="text" value="50753a00-5e2e-4a2f-94b0-e6721b0a3cc4"></div>
+      <button id="btn-get-profile">Fetch</button>
+    </fieldset>
+  </div>
+
+  <h2>Response</h2>
+  <pre id="output">(no calls yet)</pre>
+
+  <script type="module">
+    // `main.js` is an ES module. `@JSExportTopLevel("LeaderboardSim")` in
+    // ESModule mode emits a named export, so we import it and attach it to
+    // globalThis to keep the rest of this page's plain script simple.
+    import { LeaderboardSim } from './main.js';
+    globalThis.LeaderboardSim = LeaderboardSim;
+
+    // The prod target uses an absolute URL so the same `index.html` works
+    // whether it's served by the http4s server or opened directly from disk
+    // via file://. CORS on the server allows the file:// origin (which is
+    // "null").
+    const PROD_BASE = 'http://localhost:8080';
+
+    const out = document.getElementById('output');
+    const status = document.getElementById('sim-status');
+
+    function currentMode() {
+      return document.querySelector('input[name=mode]:checked').value;
+    }
+
+    function show(label, status, body) {
+      out.textContent = `[${label}] HTTP ${status}\n${body}`;
+    }
+
+    // Issue a request through the currently selected backend. The simulation
+    // and the production server accept exactly the same (method, path, body)
+    // triple, so the only thing that varies here is the transport.
+    async function call(method, path, body) {
+      const mode = currentMode();
+      try {
+        if (mode === 'sim') {
+          if (!globalThis.LeaderboardSim) throw new Error('simulation not ready yet');
+          const r = await globalThis.LeaderboardSim.call(method, path, body || '');
+          show('sim', r.status, r.body);
+        } else {
+          const r = await fetch(PROD_BASE + path, {
+            method,
+            body: (method === 'GET' || method === 'HEAD') ? undefined : (body || ''),
+          });
+          show('prod', r.status, await r.text());
+        }
+      } catch (e) {
+        show(mode, 'ERR', String(e));
+      }
+    }
+
+    // Poll briefly for the Scala.js module to finish initialising so we can
+    // tell the user the simulation is ready.
+    (async () => {
+      for (let i = 0; i < 50 && !globalThis.LeaderboardSim; i++) {
+        await new Promise(r => setTimeout(r, 100));
+      }
+      status.textContent = globalThis.LeaderboardSim
+        ? 'simulation: ready'
+        : 'simulation: failed to load (check /main.js)';
+    })();
+
+    document.getElementById('btn-submit-score').onclick = () => {
+      const u = document.getElementById('ladder-user').value;
+      const s = document.getElementById('ladder-score').value;
+      call('POST', `/ladder/${u}/${s}`, '');
+    };
+    document.getElementById('btn-get-ladder').onclick = () => {
+      call('GET', '/ladder', '');
+    };
+    document.getElementById('btn-set-profile').onclick = () => {
+      const u = document.getElementById('profile-user').value;
+      const name = document.getElementById('profile-name').value;
+      const desc = document.getElementById('profile-desc').value;
+      call('POST', `/profile/${u}`, JSON.stringify({ name, description: desc }));
+    };
+    document.getElementById('btn-get-profile').onclick = () => {
+      const u = document.getElementById('profile-get-user').value;
+      call('GET', `/profile/${u}`, '');
+    };
+  </script>
+</body>
+</html>
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/LeaderboardRole.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/LeaderboardRole.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/LeaderboardRole.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/LeaderboardRole.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/config/PostgresCfg.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/config/PostgresCfg.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/config/PostgresCfg.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/config/PostgresCfg.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/config/PostgresPortCfg.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/config/PostgresPortCfg.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/config/PostgresPortCfg.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/config/PostgresPortCfg.scala
diff --git a/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
new file mode 100644
index 0000000..2e1ceaa
--- /dev/null
+++ b/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
@@ -0,0 +1,53 @@
+package leaderboard.http
+
+import cats.effect.Async
+import cats.syntax.all.*
+import com.comcast.ip4s.Port
+import fs2.io.net.Network
+import izumi.distage.model.definition.Lifecycle
+import leaderboard.api.HttpApi
+import org.http4s.HttpRoutes
+import org.http4s.ember.server.EmberServerBuilder
+import org.http4s.server.Server
+import org.http4s.server.middleware.CORS
+import org.http4s.server.staticcontent.resourceServiceBuilder
+
+final case class HttpServer(
+  server: Server
+)
+
+object HttpServer {
+
+  final class Impl[F[+_, +_]](
+    allHttpApis: Set[HttpApi[F]]
+  )(implicit
+    async: Async[F[Throwable, _]]
+  ) extends Lifecycle.Of[F[Throwable, _], HttpServer](
+      Lifecycle.fromCats {
+        type G[A] = F[Throwable, A]
+
+        // The same HttpRoutes the LocalDispatcher invokes in-process.
+        val apiRoutes: HttpRoutes[G] = allHttpApis.map(_.http).toList.foldK
+
+        // Serve /webapp resources at the root, so the demo UI is available
+        // at e.g. http://localhost:8080/ alongside the API endpoints.
+        val staticRoutes: HttpRoutes[G] =
+          resourceServiceBuilder[G]("/webapp").toRoutes
+
+        // Permissive CORS so the same UI also works when opened from file://
+        // (its origin is "null" in that case). Demo-grade — do not copy
+        // verbatim into a real production service.
+        val app = CORS.policy.withAllowOriginAll(
+          (apiRoutes <+> staticRoutes).orNotFound
+        )
+
+        EmberServerBuilder
+          .default(using async, Network.forAsync)
+          .withHttpApp(app)
+          .withPort(Port.fromInt(8080).get)
+          .build
+          .map(HttpServer(_))
+      }
+    )
+
+}
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala
similarity index 66%
rename from bifunctor-tagless/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala
index 18dda71..7ff56e2 100644
--- a/bifunctor-tagless/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala
+++ b/bifunctor-tagless/jvm/src/main/scala/leaderboard/plugins/LeaderboardPlugin.scala
@@ -9,23 +9,22 @@ import izumi.distage.roles.bundled.BundledRolesModule
 import izumi.distage.roles.model.definition.RoleModuleDef
 import izumi.fundamentals.platform.integration.PortCheck
 import izumi.fundamentals.platform.versions.Version
-import leaderboard.api.{HttpApi, LadderApi, ProfileApi}
 import leaderboard.config.{PostgresCfg, PostgresPortCfg}
 import leaderboard.http.HttpServer
-import leaderboard.repo.{Ladder, Profiles}
-import leaderboard.services.Ranks
+import leaderboard.repo.{Ladder, LadderPostgres, Profiles, ProfilesPostgres}
 import leaderboard.sql.{SQL, TransactorResource}
 import leaderboard.{LadderRole, LeaderboardRole, ProfileRole}
-import org.http4s.dsl.Http4sDsl
 import zio.IO
 
 import scala.concurrent.duration.*
 
 object LeaderboardPlugin extends PluginDef {
   include(modules.roles[IO])
-  include(modules.api[IO])
-  include(modules.repoDummy[IO])
+  // Shared API + dummy repos wiring — same code that runs in the browser.
+  include(LeaderboardCoreModule.api[IO])
+  include(LeaderboardCoreModule.repoDummy[IO])
   include(modules.repoProd[IO])
+  include(modules.server[IO])
   include(modules.configs)
   include(modules.prodConfigs)
 
@@ -44,36 +43,15 @@ object LeaderboardPlugin extends PluginDef {
       include(BundledRolesModule[F[Throwable, _]](version = Version.parse("1.0.0")))
     }
 
-    def api[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
-      // The `ladder` API
-      make[LadderApi[F]]
-      // The `profile` API
-      make[ProfileApi[F]]
-
-      // A set of all APIs
-      many[HttpApi[F]]
-        .weak[LadderApi[F]] // add ladder API as a _weak reference_
-        .weak[ProfileApi[F]] // add profiles API as a _weak reference_
-
+    def server[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
       make[HttpServer].fromResource[HttpServer.Impl[F]]
-
-      make[Ranks[F]].from[Ranks.Impl[F]]
-
-      makeTrait[Http4sDsl[F[Throwable, _]]]
-    }
-
-    def repoDummy[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
-      tag(Repo.Dummy)
-
-      make[Ladder[F]].fromResource[Ladder.Dummy[F]]
-      make[Profiles[F]].fromResource[Profiles.Dummy[F]]
     }
 
     def repoProd[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
       tag(Repo.Prod)
 
-      make[Ladder[F]].fromResource[Ladder.Postgres[F]]
-      make[Profiles[F]].fromResource[Profiles.Postgres[F]]
+      make[Ladder[F]].fromResource[LadderPostgres[F]]
+      make[Profiles[F]].fromResource[ProfilesPostgres[F]]
 
       make[SQL[F]].from[SQL.Impl[F]]
 
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/plugins/PostgresDockerPlugin.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/plugins/PostgresDockerPlugin.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/plugins/PostgresDockerPlugin.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/plugins/PostgresDockerPlugin.scala
diff --git a/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/LadderPostgres.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/LadderPostgres.scala
new file mode 100644
index 0000000..e21900c
--- /dev/null
+++ b/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/LadderPostgres.scala
@@ -0,0 +1,42 @@
+package leaderboard.repo
+
+import distage.Lifecycle
+import doobie.postgres.implicits.*
+import doobie.syntax.string.*
+import izumi.functional.bio.Monad2
+import leaderboard.model.{QueryFailure, Score, UserId}
+import leaderboard.sql.SQL
+import logstage.LogIO2
+
+// Postgres-backed implementation of [[Ladder]]. Lives JVM-side because doobie
+// is not cross-built to scala.js.
+final class LadderPostgres[F[+_, +_]: Monad2](
+  sql: SQL[F],
+  log: LogIO2[F],
+) extends Lifecycle.LiftF[F[Throwable, _], Ladder[F]](for {
+    _ <- log.info(s"Creating Ladder table")
+    _ <- sql.execute("ladder-ddl") {
+      sql"""create table if not exists ladder (
+           | user_id uuid not null,
+           | score bigint not null,
+           | primary key (user_id)
+           |) without oids
+           |""".stripMargin.update.run
+    }
+    res = new Ladder[F] {
+      override def submitScore(userId: UserId, score: Score): F[QueryFailure, Unit] =
+        sql
+          .execute("submit-score") {
+            sql"""insert into ladder (user_id, score) values ($userId, $score)
+                 |on conflict (user_id) do update set
+                 |  score = excluded.score
+                 |""".stripMargin.update.run
+          }.void
+
+      override val getScores: F[QueryFailure, List[(UserId, Score)]] =
+        sql.execute("get-leaderboard") {
+          sql"""select user_id, score from ladder order by score DESC
+               |""".stripMargin.query[(UserId, Score)].to[List]
+        }
+    }
+  } yield res)
diff --git a/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/ProfilesPostgres.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/ProfilesPostgres.scala
new file mode 100644
index 0000000..23b2c1a
--- /dev/null
+++ b/bifunctor-tagless/jvm/src/main/scala/leaderboard/repo/ProfilesPostgres.scala
@@ -0,0 +1,47 @@
+package leaderboard.repo
+
+import distage.Lifecycle
+import doobie.postgres.implicits.*
+import doobie.implicits.*
+import izumi.functional.bio.Monad2
+import leaderboard.model.{QueryFailure, UserId, UserProfile}
+import leaderboard.sql.SQL
+import logstage.LogIO2
+
+// Postgres-backed implementation of [[Profiles]]. Lives JVM-side because doobie
+// is not cross-built to scala.js.
+final class ProfilesPostgres[F[+_, +_]: Monad2](
+  sql: SQL[F],
+  log: LogIO2[F],
+) extends Lifecycle.LiftF[F[Throwable, _], Profiles[F]](for {
+    _ <- log.info("Creating Profile table")
+    _ <- sql.execute("ddl-profiles") {
+      sql"""create table if not exists profiles (
+           |  user_id uuid not null,
+           |  name text not null,
+           |  description text not null,
+           |  primary key (user_id)
+           |) without oids
+           |""".stripMargin.update.run
+    }
+  } yield new Profiles[F] {
+    override def setProfile(userId: UserId, profile: UserProfile): F[QueryFailure, Unit] = {
+      sql
+        .execute("set-profile") {
+          sql"""insert into profiles (user_id, name, description)
+               |values ($userId, ${profile.name}, ${profile.description})
+               |on conflict (user_id) do update set
+               |  name = excluded.name,
+               |  description = excluded.description
+               |""".stripMargin.update.run
+        }.void
+    }
+
+    override def getProfile(userId: UserId): F[QueryFailure, Option[UserProfile]] = {
+      sql.execute("get-profile") {
+        sql"""select name, description from profiles
+             |where user_id = $userId
+             |""".stripMargin.query[UserProfile].option
+      }
+    }
+  })
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/sql/SQL.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/sql/SQL.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/sql/SQL.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/sql/SQL.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/sql/TransactorResource.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/sql/TransactorResource.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/sql/TransactorResource.scala
rename to bifunctor-tagless/jvm/src/main/scala/leaderboard/sql/TransactorResource.scala
diff --git a/bifunctor-tagless/src/test/scala/leaderboard/Rnd.scala b/bifunctor-tagless/jvm/src/test/scala/leaderboard/Rnd.scala
similarity index 100%
rename from bifunctor-tagless/src/test/scala/leaderboard/Rnd.scala
rename to bifunctor-tagless/jvm/src/test/scala/leaderboard/Rnd.scala
diff --git a/bifunctor-tagless/src/test/scala/leaderboard/WiringTest.scala b/bifunctor-tagless/jvm/src/test/scala/leaderboard/WiringTest.scala
similarity index 100%
rename from bifunctor-tagless/src/test/scala/leaderboard/WiringTest.scala
rename to bifunctor-tagless/jvm/src/test/scala/leaderboard/WiringTest.scala
diff --git a/bifunctor-tagless/src/test/scala/leaderboard/tests.scala b/bifunctor-tagless/jvm/src/test/scala/leaderboard/tests.scala
similarity index 100%
rename from bifunctor-tagless/src/test/scala/leaderboard/tests.scala
rename to bifunctor-tagless/jvm/src/test/scala/leaderboard/tests.scala
diff --git a/bifunctor-tagless/src/test/scala/leaderboard/zioenv.scala b/bifunctor-tagless/jvm/src/test/scala/leaderboard/zioenv.scala
similarity index 100%
rename from bifunctor-tagless/src/test/scala/leaderboard/zioenv.scala
rename to bifunctor-tagless/jvm/src/test/scala/leaderboard/zioenv.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/api/HttpApi.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/api/HttpApi.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/api/HttpApi.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/api/HttpApi.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/api/LadderApi.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/api/LadderApi.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/api/LadderApi.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/api/LadderApi.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/api/ProfileApi.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/api/ProfileApi.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/api/ProfileApi.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/api/ProfileApi.scala
diff --git a/bifunctor-tagless/shared/src/main/scala/leaderboard/dispatch/LocalDispatcher.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/dispatch/LocalDispatcher.scala
new file mode 100644
index 0000000..2658404
--- /dev/null
+++ b/bifunctor-tagless/shared/src/main/scala/leaderboard/dispatch/LocalDispatcher.scala
@@ -0,0 +1,45 @@
+package leaderboard.dispatch
+
+import cats.effect.Async
+import cats.syntax.all.*
+import leaderboard.api.HttpApi
+import leaderboard.dispatch.LocalDispatcher.Response
+import org.http4s.{HttpApp, Method, Request, Uri}
+
+import scala.annotation.unused
+
+/**
+  * Invokes the same `HttpRoutes` that the http4s server exposes, but without
+  * a network hop. Used by the http4s server on the JVM as the actual handler
+  * for incoming requests, and by the `@JSExportTopLevel` entrypoint in the
+  * browser so the front-end can call the simulated backend exactly like it
+  * would call the real one.
+  */
+trait LocalDispatcher[F[_, _]] {
+  def call(method: String, path: String, body: String): F[Throwable, Response]
+}
+
+object LocalDispatcher {
+  final case class Response(status: Int, body: String)
+
+  final class Impl[F[+_, +_]](
+    @unused apis: Set[HttpApi[F]]
+  )(implicit
+    async: Async[F[Throwable, _]]
+  ) extends LocalDispatcher[F] {
+    private type G[A] = F[Throwable, A]
+
+    // Pre-assembled handler matching what the http4s server runs.
+    private val httpApp: HttpApp[G] = apis.map(_.http).toList.foldK.orNotFound
+
+    override def call(method: String, path: String, body: String): F[Throwable, Response] = {
+      val req = Request[G](
+        method = Method.fromString(method).getOrElse(Method.GET),
+        uri    = Uri.unsafeFromString(path),
+      ).withEntity(body)
+      httpApp.run(req).flatMap { resp =>
+        resp.as[String].map(text => Response(resp.status.code, text))
+      }
+    }
+  }
+}
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/model/QueryFailure.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/model/QueryFailure.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/model/QueryFailure.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/model/QueryFailure.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/model/RankedProfile.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/model/RankedProfile.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/model/RankedProfile.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/model/RankedProfile.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/model/UserProfile.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/model/UserProfile.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/model/UserProfile.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/model/UserProfile.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/model/package.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/model/package.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/model/package.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/model/package.scala
diff --git a/bifunctor-tagless/shared/src/main/scala/leaderboard/plugins/LeaderboardCoreModule.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/plugins/LeaderboardCoreModule.scala
new file mode 100644
index 0000000..0981fc7
--- /dev/null
+++ b/bifunctor-tagless/shared/src/main/scala/leaderboard/plugins/LeaderboardCoreModule.scala
@@ -0,0 +1,46 @@
+package leaderboard.plugins
+
+import distage.StandardAxis.Repo
+import distage.{ModuleDef, TagKK}
+import leaderboard.api.{HttpApi, LadderApi, ProfileApi}
+import leaderboard.dispatch.LocalDispatcher
+import leaderboard.repo.{Ladder, Profiles}
+import leaderboard.services.Ranks
+import org.http4s.dsl.Http4sDsl
+
+/**
+  * Cross-compilable subset of the application wiring. Holds everything that
+  * doesn't depend on JVM-only libraries (http4s ember server, doobie, JNA,
+  * roles), so the same module can be assembled into a real http server on the
+  * JVM and into an in-browser scala.js simulation.
+  */
+object LeaderboardCoreModule {
+
+  def api[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
+    // The `ladder` API
+    make[LadderApi[F]]
+    // The `profile` API
+    make[ProfileApi[F]]
+
+    // A set of all APIs
+    many[HttpApi[F]]
+      .weak[LadderApi[F]] // add ladder API as a _weak reference_
+      .weak[ProfileApi[F]] // add profiles API as a _weak reference_
+
+    make[Ranks[F]].from[Ranks.Impl[F]]
+
+    makeTrait[Http4sDsl[F[Throwable, _]]]
+
+    // Wraps the assembled HttpRoutes for direct in-process calls. Used both by
+    // the http4s adapter on JVM and by the @JSExportTopLevel entrypoint in the
+    // browser simulation.
+    make[LocalDispatcher[F]].from[LocalDispatcher.Impl[F]]
+  }
+
+  def repoDummy[F[+_, +_]: TagKK]: ModuleDef = new ModuleDef {
+    tag(Repo.Dummy)
+
+    make[Ladder[F]].fromResource[Ladder.Dummy[F]]
+    make[Profiles[F]].fromResource[Profiles.Dummy[F]]
+  }
+}
diff --git a/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Ladder.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Ladder.scala
new file mode 100644
index 0000000..52155af
--- /dev/null
+++ b/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Ladder.scala
@@ -0,0 +1,26 @@
+package leaderboard.repo
+
+import distage.Lifecycle
+import izumi.functional.bio.{Applicative2, F, Primitives2}
+import leaderboard.model.{QueryFailure, Score, UserId}
+
+trait Ladder[F[_, _]] {
+  def submitScore(userId: UserId, score: Score): F[QueryFailure, Unit]
+  def getScores: F[QueryFailure, List[(UserId, Score)]]
+}
+
+object Ladder {
+  // In-memory dummy used by both JVM tests and the in-browser simulation.
+  final class Dummy[F[+_, +_]: Applicative2: Primitives2]
+    extends Lifecycle.LiftF[F[Nothing, _], Ladder[F]](for {
+      state <- F.mkRef(Map.empty[UserId, Score])
+    } yield {
+      new Ladder[F] {
+        override def submitScore(userId: UserId, score: Score): F[Nothing, Unit] =
+          state.update_(_ + (userId -> score))
+
+        override def getScores: F[Nothing, List[(UserId, Score)]] =
+          state.get.map(_.toList.sortBy(_._2)(Ordering[Score].reverse))
+      }
+    })
+}
diff --git a/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Profiles.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Profiles.scala
new file mode 100644
index 0000000..8cfcf8a
--- /dev/null
+++ b/bifunctor-tagless/shared/src/main/scala/leaderboard/repo/Profiles.scala
@@ -0,0 +1,26 @@
+package leaderboard.repo
+
+import distage.Lifecycle
+import izumi.functional.bio.{Applicative2, F, Primitives2}
+import leaderboard.model.{QueryFailure, UserId, UserProfile}
+
+trait Profiles[F[_, _]] {
+  def setProfile(userId: UserId, profile: UserProfile): F[QueryFailure, Unit]
+  def getProfile(userId: UserId): F[QueryFailure, Option[UserProfile]]
+}
+
+object Profiles {
+  // In-memory dummy used by both JVM tests and the in-browser simulation.
+  final class Dummy[F[+_, +_]: Applicative2: Primitives2]
+    extends Lifecycle.LiftF[F[Nothing, _], Profiles[F]](for {
+      state <- F.mkRef(Map.empty[UserId, UserProfile])
+    } yield {
+      new Profiles[F] {
+        override def setProfile(userId: UserId, profile: UserProfile): F[Nothing, Unit] =
+          state.update_(_ + (userId -> profile))
+
+        override def getProfile(userId: UserId): F[Nothing, Option[UserProfile]] =
+          state.get.map(_.get(userId))
+      }
+    })
+}
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/services/Ranks.scala b/bifunctor-tagless/shared/src/main/scala/leaderboard/services/Ranks.scala
similarity index 100%
rename from bifunctor-tagless/src/main/scala/leaderboard/services/Ranks.scala
rename to bifunctor-tagless/shared/src/main/scala/leaderboard/services/Ranks.scala
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/http/HttpServer.scala b/bifunctor-tagless/src/main/scala/leaderboard/http/HttpServer.scala
deleted file mode 100644
index 6a3cda1..0000000
--- a/bifunctor-tagless/src/main/scala/leaderboard/http/HttpServer.scala
+++ /dev/null
@@ -1,35 +0,0 @@
-package leaderboard.http
-
-import cats.effect.Async
-import cats.syntax.all.*
-import com.comcast.ip4s.Port
-import fs2.io.net.Network
-import izumi.distage.model.definition.Lifecycle
-import leaderboard.api.HttpApi
-import org.http4s.ember.server.EmberServerBuilder
-import org.http4s.server.Server
-
-final case class HttpServer(
-  server: Server
-)
-
-object HttpServer {
-
-  final class Impl[F[+_, +_]](
-    allHttpApis: Set[HttpApi[F]]
-  )(implicit
-    async: Async[F[Throwable, _]]
-  ) extends Lifecycle.Of[F[Throwable, _], HttpServer](
-      Lifecycle.fromCats {
-        val combinedApis = allHttpApis.map(_.http).toList.foldK
-
-        EmberServerBuilder
-          .default(using async, Network.forAsync)
-          .withHttpApp(combinedApis.orNotFound)
-          .withPort(Port.fromInt(8080).get)
-          .build
-          .map(HttpServer(_))
-      }
-    )
-
-}
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/repo/Ladder.scala b/bifunctor-tagless/src/main/scala/leaderboard/repo/Ladder.scala
deleted file mode 100644
index 105adaf..0000000
--- a/bifunctor-tagless/src/main/scala/leaderboard/repo/Ladder.scala
+++ /dev/null
@@ -1,60 +0,0 @@
-package leaderboard.repo
-
-import distage.Lifecycle
-import doobie.postgres.implicits.*
-import doobie.syntax.string.*
-import izumi.functional.bio.{Applicative2, F, Monad2, Primitives2}
-import leaderboard.model.{QueryFailure, Score, UserId}
-import leaderboard.sql.SQL
-import logstage.LogIO2
-
-trait Ladder[F[_, _]] {
-  def submitScore(userId: UserId, score: Score): F[QueryFailure, Unit]
-  def getScores: F[QueryFailure, List[(UserId, Score)]]
-}
-
-object Ladder {
-  final class Dummy[F[+_, +_]: Applicative2: Primitives2]
-    extends Lifecycle.LiftF[F[Nothing, _], Ladder[F]](for {
-      state <- F.mkRef(Map.empty[UserId, Score])
-    } yield {
-      new Ladder[F] {
-        override def submitScore(userId: UserId, score: Score): F[Nothing, Unit] =
-          state.update_(_ + (userId -> score))
-
-        override def getScores: F[Nothing, List[(UserId, Score)]] =
-          state.get.map(_.toList.sortBy(_._2)(Ordering[Score].reverse))
-      }
-    })
-
-  final class Postgres[F[+_, +_]: Monad2](
-    sql: SQL[F],
-    log: LogIO2[F],
-  ) extends Lifecycle.LiftF[F[Throwable, _], Ladder[F]](for {
-      _ <- log.info(s"Creating Ladder table")
-      _ <- sql.execute("ladder-ddl") {
-        sql"""create table if not exists ladder (
-             | user_id uuid not null,
-             | score bigint not null,
-             | primary key (user_id)
-             |) without oids
-             |""".stripMargin.update.run
-      }
-      res = new Ladder[F] {
-        override def submitScore(userId: UserId, score: Score): F[QueryFailure, Unit] =
-          sql
-            .execute("submit-score") {
-              sql"""insert into ladder (user_id, score) values ($userId, $score)
-                   |on conflict (user_id) do update set
-                   |  score = excluded.score
-                   |""".stripMargin.update.run
-            }.void
-
-        override val getScores: F[QueryFailure, List[(UserId, Score)]] =
-          sql.execute("get-leaderboard") {
-            sql"""select user_id, score from ladder order by score DESC
-                 |""".stripMargin.query[(UserId, Score)].to[List]
-          }
-      }
-    } yield res)
-}
diff --git a/bifunctor-tagless/src/main/scala/leaderboard/repo/Profiles.scala b/bifunctor-tagless/src/main/scala/leaderboard/repo/Profiles.scala
deleted file mode 100644
index 96b64a7..0000000
--- a/bifunctor-tagless/src/main/scala/leaderboard/repo/Profiles.scala
+++ /dev/null
@@ -1,65 +0,0 @@
-package leaderboard.repo
-
-import distage.Lifecycle
-import doobie.postgres.implicits.*
-import doobie.implicits.*
-import izumi.functional.bio.{Applicative2, F, Monad2, Primitives2}
-import leaderboard.model.{QueryFailure, UserId, UserProfile}
-import leaderboard.sql.SQL
-import logstage.LogIO2
-
-trait Profiles[F[_, _]] {
-  def setProfile(userId: UserId, profile: UserProfile): F[QueryFailure, Unit]
-  def getProfile(userId: UserId): F[QueryFailure, Option[UserProfile]]
-}
-
-object Profiles {
-  final class Dummy[F[+_, +_]: Applicative2: Primitives2]
-    extends Lifecycle.LiftF[F[Nothing, _], Profiles[F]](for {
-      state <- F.mkRef(Map.empty[UserId, UserProfile])
-    } yield {
-      new Profiles[F] {
-        override def setProfile(userId: UserId, profile: UserProfile): F[Nothing, Unit] =
-          state.update_(_ + (userId -> profile))
-
-        override def getProfile(userId: UserId): F[Nothing, Option[UserProfile]] =
-          state.get.map(_.get(userId))
-      }
-    })
-
-  final class Postgres[F[+_, +_]: Monad2](
-    sql: SQL[F],
-    log: LogIO2[F],
-  ) extends Lifecycle.LiftF[F[Throwable, _], Profiles[F]](for {
-      _ <- log.info("Creating Profile table")
-      _ <- sql.execute("ddl-profiles") {
-        sql"""create table if not exists profiles (
-             |  user_id uuid not null,
-             |  name text not null,
-             |  description text not null,
-             |  primary key (user_id)
-             |) without oids
-             |""".stripMargin.update.run
-      }
-    } yield new Profiles[F] {
-      override def setProfile(userId: UserId, profile: UserProfile): F[QueryFailure, Unit] = {
-        sql
-          .execute("set-profile") {
-            sql"""insert into profiles (user_id, name, description)
-                 |values ($userId, ${profile.name}, ${profile.description})
-                 |on conflict (user_id) do update set
-                 |  name = excluded.name,
-                 |  description = excluded.description
-                 |""".stripMargin.update.run
-          }.void
-      }
-
-      override def getProfile(userId: UserId): F[QueryFailure, Option[UserProfile]] = {
-        sql.execute("get-profile") {
-          sql"""select name, description from profiles
-               |where user_id = $userId
-               |""".stripMargin.query[UserProfile].option
-        }
-      }
-    })
-}
diff --git a/build.sbt b/build.sbt
index 1667b06..4f3a061 100644
--- a/build.sbt
+++ b/build.sbt
@@ -1,3 +1,6 @@
+import org.scalajs.linker.interface.{ModuleKind, OutputPatterns}
+import sbtcrossproject.CrossPlugin.autoImport.{CrossType, crossProject}
+
 import scala.util.chaining.scalaUtilChainingOps
 
 val V = new {
@@ -9,7 +12,7 @@ val V = new {
   val doobie        = "1.0.0-RC12"
   val catsCore      = "2.13.0"
   val zio           = "2.1.25"
-  val zioCats       = "23.0.0.8"
+  val zioCats       = "23.1.0.13"
   val kindProjector = "0.13.4"
   val circeGeneric  = "0.14.15"
   val graalMetadata = "0.11.5"
@@ -47,6 +50,8 @@ val Deps = new {
 
   val graalMetadata = "org.graalvm.buildtools" % "graalvm-reachability-metadata" % V.graalMetadata
 
+  // Standard set of deps for JVM-only sub-projects (monomorphic-cats,
+  // monofunctor-tagless, and the JVM half of bifunctor-tagless).
   val CoreDeps = Seq(
     distageCore,
     distageRoles,
@@ -79,9 +84,73 @@ inThisBuild(
   )
 )
 
-lazy val `bifunctor-tagless` = project
+// -----------------------------------------------------------------------------
+// bifunctor-tagless: a cross-built project (JVM + Scala.js)
+//
+// The shared half holds everything that compiles to both targets: the model,
+// the API classes (which return http4s `HttpRoutes`), the repository traits
+// and their in-memory dummy implementations, and the `LocalDispatcher` that
+// invokes the assembled routes in-process. The JVM half adds the postgres
+// repositories, the http4s ember server with CORS + static-file serving, and
+// the role/launcher infrastructure. The JS half adds a `@JSExportTopLevel`
+// entrypoint that boots the same distage graph with `Repo -> Dummy` and
+// surfaces the dispatcher to the browser as `window.LeaderboardSim`.
+// -----------------------------------------------------------------------------
+
+lazy val `bifunctor-tagless` = crossProject(JVMPlatform, JSPlatform)
+  .crossType(CrossType.Full)
   .in(file("bifunctor-tagless"))
-  .pipe(sharedSettings(Seq(Deps.zio, Deps.zioCats)))
+  .settings(
+    sharedScalaSettings,
+    libraryDependencies ++= Seq(
+      "io.7mind.izumi" %%% "distage-core"               % V.distage,
+      "io.7mind.izumi" %%% "distage-extension-plugins"  % V.distage,
+      "io.7mind.izumi" %%% "distage-extension-logstage" % V.distage,
+      "io.7mind.izumi" %%% "logstage-core"              % V.logstage,
+      "org.http4s"     %%% "http4s-dsl"                 % V.http4s,
+      "org.http4s"     %%% "http4s-circe"               % V.http4s,
+      "io.circe"       %%% "circe-generic"              % V.circeGeneric,
+      "org.typelevel"  %%% "cats-core"                  % V.catsCore,
+      "dev.zio"        %%% "zio"                        % V.zio,
+      // Intentionally NOT depending on zio-interop-cats here — its
+      // `ZManagedMonadError` references zio 1.x types that no longer link
+      // under scala.js. The bifunctor-tagless code uses
+      // `izumi.functional.bio.catz` for its cats-effect bridge instead. The
+      // JVM half still pulls in zio-interop-cats via distage-testkit /
+      // monofunctor-tagless transitively if needed.
+    ),
+  )
+  .jvmConfigure(_.pipe(jvmSharedSettings(Seq(Deps.zio, Deps.zioCats))))
+  .jsSettings(
+    scalaJSUseMainModuleInitializer := false,
+    // Emit ES module output so the front-end can import it via
+    // <script type="module">.
+    scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) },
+  )
+
+// sbt-scalajs-crossproject derives the per-platform project IDs from the
+// cross-project's name: `bifunctor-taglessJVM` and `bifunctor-taglessJS`.
+// These aliases give us Project handles to reference in tasks below.
+lazy val `bifunctor-taglessJVM` = `bifunctor-tagless`.jvm
+lazy val `bifunctor-taglessJS`  = `bifunctor-tagless`.js
+
+// Task: link the Scala.js bundle in `bifunctor-tagless-js` and copy the
+// resulting main.js into the JVM project's resources/webapp/ so the http4s
+// server (and a browser opening index.html directly) can find it.
+lazy val copySimJs = taskKey[Seq[File]]("Link the simulation JS and copy it into the JVM resources/webapp/ directory.")
+
+copySimJs := {
+  val _      = (`bifunctor-taglessJS` / Compile / fullLinkJS).value
+  val srcDir = (`bifunctor-taglessJS` / Compile / fullLinkJS / scalaJSLinkerOutputDirectory).value
+  val outDir = (`bifunctor-taglessJVM` / baseDirectory).value / "src" / "main" / "resources" / "webapp"
+  IO.createDirectory(outDir)
+  val srcs = (srcDir ** "*.js").get ++ (srcDir ** "*.js.map").get
+  srcs.map { f =>
+    val dst = outDir / f.getName
+    IO.copyFile(f, dst, preserveLastModified = true)
+    dst
+  }
+}
 
 lazy val `monofunctor-tagless` = project
   .in(file("monofunctor-tagless"))
@@ -98,51 +167,61 @@ lazy val `graal-resources` = project
 lazy val `distage-example` = project
   .in(file("."))
   .aggregate(
-    `bifunctor-tagless`,
+    `bifunctor-taglessJVM`,
+    `bifunctor-taglessJS`,
     `monofunctor-tagless`,
     `monomorphic-cats`,
     `graal-resources`,
   )
   .enablePlugins(GraalVMNativeImagePlugin, UniversalPlugin)
 
-def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = {
+// Scalac/source settings shared by every Scala project in this build, both
+// JVM-only ones and the cross-built bifunctor-tagless halves.
+def sharedScalaSettings: Seq[Setting[_]] = Seq(
+  libraryDependencies ++= {
+    if (scalaVersion.value.startsWith("2")) {
+      Seq(compilerPlugin(Deps.kindProjector))
+    } else {
+      Seq.empty
+    }
+  },
+  scalacOptions --= Seq("-Xfatal-warnings", "-Ykind-projector", "-Wnonunit-statement"),
+  scalacOptions ++= {
+    if (scalaVersion.value.startsWith("2")) {
+      Seq(
+        "-Xsource:3",
+        "-P:kind-projector:underscore-placeholders",
+        "-Wmacros:after",
+      )
+    } else {
+      Seq(
+        "-Ykind-projector:underscores",
+        "-Yretain-trees",
+      )
+    }
+  },
+  scalacOptions ++= Seq(
+    s"-Xmacro-settings:product-name=${name.value}",
+    s"-Xmacro-settings:product-version=${version.value}",
+    s"-Xmacro-settings:product-group=${organization.value}",
+    s"-Xmacro-settings:scala-version=${scalaVersion.value}",
+    s"-Xmacro-settings:scala-versions=${crossScalaVersions.value.mkString(":")}",
+    s"-Xmacro-settings:sbt-version=${sbtVersion.value}",
+    s"-Xmacro-settings:git-repo-clean=${git.gitUncommittedChanges.value}",
+    s"-Xmacro-settings:git-branch=${git.gitCurrentBranch.value}",
+    s"-Xmacro-settings:git-described-version=${git.gitDescribedVersion.value.getOrElse("")}",
+    s"-Xmacro-settings:git-head-commit=${git.gitHeadCommit.value.getOrElse("")}",
+  ),
+)
+
+// JVM-only project settings (the http4s ember server, doobie, GraalVM native
+// image, etc). Applied to monomorphic-cats, monofunctor-tagless, and the JVM
+// half of bifunctor-tagless.
+def jvmSharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = {
   project
     .settings(
       libraryDependencies ++= Deps.CoreDeps ++ additionalDeps,
-      libraryDependencies ++= {
-        if (scalaVersion.value.startsWith("2")) {
-          Seq(compilerPlugin(Deps.kindProjector))
-        } else {
-          Seq.empty
-        }
-      },
-      scalacOptions --= Seq("-Xfatal-warnings", "-Ykind-projector", "-Wnonunit-statement"),
-      scalacOptions ++= {
-        if (scalaVersion.value.startsWith("2")) {
-          Seq(
-            "-Xsource:3",
-            "-P:kind-projector:underscore-placeholders",
-            "-Wmacros:after",
-          )
-        } else {
-          Seq(
-            "-Ykind-projector:underscores",
-            "-Yretain-trees",
-          )
-        }
-      },
-      scalacOptions ++= Seq(
-        s"-Xmacro-settings:product-name=${name.value}",
-        s"-Xmacro-settings:product-version=${version.value}",
-        s"-Xmacro-settings:product-group=${organization.value}",
-        s"-Xmacro-settings:scala-version=${scalaVersion.value}",
-        s"-Xmacro-settings:scala-versions=${crossScalaVersions.value.mkString(":")}",
-        s"-Xmacro-settings:sbt-version=${sbtVersion.value}",
-        s"-Xmacro-settings:git-repo-clean=${git.gitUncommittedChanges.value}",
-        s"-Xmacro-settings:git-branch=${git.gitCurrentBranch.value}",
-        s"-Xmacro-settings:git-described-version=${git.gitDescribedVersion.value.getOrElse("")}",
-        s"-Xmacro-settings:git-head-commit=${git.gitHeadCommit.value.getOrElse("")}",
-      ),
+      sharedScalaSettings,
       GraalVMNativeImage / mainClass := Some("leaderboard.GenericLauncher"),
       graalVMNativeImageOptions ++= Seq(
         "--no-fallback",
@@ -159,5 +238,9 @@ def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = {
     .enablePlugins(GraalVMNativeImagePlugin, UniversalPlugin)
 }
 
+// Plain (non-cross) Scala project — used by `monomorphic-cats` and
+// `monofunctor-tagless`, which stay JVM-only.
+def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = jvmSharedSettings(additionalDeps)(project)
+
 // for quick experiments with distage snapshots
 ThisBuild / resolvers ++= Resolver.sonatypeOssRepos("snapshots")
diff --git a/docs/drafts/20260513-1757-questions-scalajs-simulation.md b/docs/drafts/20260513-1757-questions-scalajs-simulation.md
new file mode 100644
index 0000000..cfde7cd
--- /dev/null
+++ b/docs/drafts/20260513-1757-questions-scalajs-simulation.md
@@ -0,0 +1,337 @@
+# Clarifications: scala.js "perfect simulation" webapp
+
+**Context:** Extending distage-example with a small webapp that calls the same
+endpoints as the curl commands in the README, with a runtime toggle between
+"production" (real HTTP server) and "simulation" (the same backend code compiled
+to scala.js and running in the browser with the `Dummy` axis selected).
+
+The current code is not yet cross-buildable: `LadderApi`/`ProfileApi` directly
+return `HttpRoutes[IO]`, and the plugins pull in http4s-ember, doobie, and
+distage-framework-docker — none of which compile to scala.js. So the work
+involves: (a) extracting a JS-portable "core" of each API behind a
+serialized-input/serialized-output interface, (b) cross-building those modules
+for JS, (c) adding `@JSExportTopLevel` entrypoints that build a distage object
+graph with the dummy axis, and (d) shipping a tiny frontend with a backend
+switch.
+
+**How to answer:** Write your response on the `Answer:` line under each
+question. Leave blank to skip. Reference questions by ID (e.g. `Q3`) in chat if
+convenient.
+
+---
+
+## Q1: Which of the three variants should get the scala.js treatment?
+
+**Context:** `bifunctor-tagless`, `monofunctor-tagless`, and `monomorphic-cats`
+all expose the same endpoints. Cross-building all three roughly triples the
+build.sbt surface, the plugin/role duplication, and the JS bundle work, but
+they would all need to stay in sync if the example is meant to demonstrate that
+"any distage app can be simulated."
+
+**Suggestions:**
+- **`monomorphic-cats` only** (recommended) — simplest stack (no BIO, no ZIO,
+  no tagless), smallest delta, easiest to read as a demo. Other two variants
+  stay JVM-only.
+- **`bifunctor-tagless` only** — it's the "main" example per README, so
+  showcasing simulation there has the most marketing value, but it pulls in
+  zio + zio-interop-cats on JS which is heavier and adds a tagless layer to
+  the simulation story.
+- **All three** — uniform across variants, but a lot of duplicated build wiring
+  for a demo project.
+
+Answer: bifunctor-tagless only. zio etc work fine on js
+
+---
+
+## Q2: How should the project be split for cross-compilation?
+
+**Context:** Today each variant is a single sbt project mixing JVM-only pieces
+(http4s server, doobie, docker plugin, role main) with logic that could be
+JS-portable (model classes, dummy repo impls, API logic). To cross-build, we
+need to separate them.
+
+**Suggestions:**
+- **`<variant>-core` (cross JVM/JS) + `<variant>` (JVM, depends on core) +
+  `<variant>-sim` (JS only, depends on core)** (recommended) — clearest
+  layering: `core` holds model + repo traits + dummy impls + a "local API"
+  layer; `<variant>` adds http4s/doobie/docker/role; `<variant>-sim` adds the
+  `@JSExportTopLevel` adapter and scalajs-bundler config.
+- **Convert `<variant>` itself to a cross project** — fewer modules, but the
+  JVM side has to be reorganized so that all http4s/doobie code lives under a
+  `jvm/` source tree; bigger diff to the existing layout.
+- **Keep `<variant>` JVM-only, add a sibling `<variant>-sim` that
+  *source-depends* on a curated subset of files** — minimal disturbance to
+  the existing tree, but fragile (file lists drift) and harder to explain.
+
+Answer: cross-projects with subfolders
+
+---
+
+## Q3: What should the "local call" boundary look like?
+
+**Context:** The endpoints currently take typed parameters from the URL
+(`UUIDVar`, `LongVar`) and JSON bodies, and they return JSON. For the
+simulation, JS calls into the same logic, but the natural calling convention
+across the JS/JVM boundary is `String => Future[String]` (or similar) so the
+front-end doesn't have to know Scala types. The chosen shape determines what
+gets exported to JS and what the http4s layer becomes.
+
+**Suggestions:**
+- **Method-style local API** (recommended) — define a trait like
+  `LadderLocalApi { def getScores: IO[String]; def submitScore(userIdJson:
+  String, scoreJson: String): IO[String] }` where each method corresponds to
+  one endpoint; circe encodes/decodes inside. The http4s layer becomes a thin
+  router on top, and the JS adapter exports the same methods. Pros: typed
+  arguments stay typed inside Scala, JSON only at the wire boundary. Cons: one
+  method per endpoint to maintain on both sides.
+- **Single dispatch entrypoint** — one `def call(method: String, path: String,
+  body: String): IO[Response]` that mimics an HTTP request/response. Pros: one
+  export to JS, frontend code is identical for prod vs sim (just swap the
+  transport). Cons: stringly-typed routing inside Scala — defeats some of the
+  type safety the example is showcasing.
+- **HTTP-shaped over a transport interface** — abstract over `Transport` where
+  the prod impl uses fetch and the sim impl calls the in-browser app's
+  router. Most idiomatic for "perfect simulation" but the heaviest change.
+
+Answer: single dispatch entrypoint is more aligned to the purpose of the demo - to showcase how to build simulations sharing nearly all the code/approaches
+
+---
+
+## Q4: Which scala.js promise type should the JS export use?
+
+**Context:** `IO[A]` doesn't cross the JS boundary; we have to expose a JS
+`Promise` or `Thenable`. cats-effect's `IO#unsafeToPromise` exists on JS.
+
+**Suggestions:**
+- **`scala.scalajs.js.Promise[String]`** (recommended) — what JS code expects;
+  `await`-able from plain JS or TS. Simplest possible interop.
+- **`js.Thenable[String]`** — more permissive but rarely needed.
+- **Synchronous `String` return** — only viable if every dummy impl is
+  fully synchronous, which would constrain the design.
+
+Answer: use scala.js promise
+
+---
+
+## Q5: What should the frontend be written in?
+
+**Context:** The "small webapp" needs an input form per endpoint (or a free-
+form curl-like UI), a result panel, and a toggle for prod/sim backend.
+
+**Suggestions:**
+- **Plain HTML + a few lines of vanilla JS** (recommended) — zero extra
+  toolchain, served as static files; demonstrates the simulation idea without
+  introducing a UI framework as a second axis of complexity. ~100 lines.
+- **Scala.js + Laminar (or scalajs-dom only)** — keeps everything in Scala,
+  but adds Laminar as a dependency and makes the frontend a third scala.js
+  module.
+- **TypeScript + small bundler (vite/esbuild)** — most realistic for a
+  real-world setup but adds an npm toolchain to the repo just for the demo.
+
+Answer: plain html + vanilla js - we want a minimalistic example
+
+---
+
+## Q6: How should the JS artifact be produced and served?
+
+**Context:** Need to decide between sbt-scalajs `fastLinkJS`/`fullLinkJS`
+output vs `scalajs-bundler`, and how the frontend loads it.
+
+**Suggestions:**
+- **`fullLinkJS` + ES module output, loaded directly by `index.html` via
+  `<script type="module">`** (recommended) — no bundler, no npm, no
+  webpack. The dummy backend uses no JS libraries that need npm packaging, so
+  there's nothing to bundle.
+- **scalajs-bundler with webpack** — necessary only if we pull in npm
+  dependencies; overkill here.
+- **Pre-built JS committed to the repo + sbt task to refresh it** — easier for
+  someone just reading the README, but stale-artifact risk.
+
+Answer: go the recommended way
+
+---
+
+## Q7: Where do the frontend assets live and how are they served?
+
+**Context:** The webapp itself (HTML + JS bundle) needs a home. Two natural
+options:
+
+**Suggestions:**
+- **Serve the static files from the same http4s server** (recommended) —
+  add a `/` route that returns `index.html` and `/app.js` returning the
+  linked JS. Then `./launcher :leaderboard` exposes the UI at
+  `http://localhost:8080/` alongside the API. One process, no extra
+  instructions in the README.
+- **Static files in `./webapp/` opened directly from disk via `file://`** —
+  simplest, but `file://` + CORS gotchas when "production" mode tries to call
+  `http://localhost:8080`. Workable but rougher demo.
+- **Separate tiny static server module** — overkill.
+
+Answer: I think we should combine two options - we may serve the app through http4s AND let the user to open directly from file://
+
+---
+
+## Q8: How should the prod/sim toggle behave on the frontend?
+
+**Context:** The user wants a switch between "real HTTP server" and "scala.js
+simulation". The two modes need different request paths in the frontend code.
+
+**Suggestions:**
+- **Radio button / toggle in the UI; both modes available simultaneously**
+  (recommended) — in "prod" mode the JS does `fetch('/ladder', ...)`; in
+  "sim" mode it calls `window.LeaderboardSim.submitScore(...)`. The simulated
+  backend is initialised once on page load. User can flip between them and
+  see, for instance, that sim state doesn't propagate to prod and vice versa
+  — which is itself a nice demonstration of "perfect simulation."
+- **Build-time flag** — two separate HTML files, one per mode. Simpler code
+  but you can't compare them side by side.
+- **Two browser tabs, two servers** — defeats the purpose.
+
+Answer: toggle in the UI
+
+---
+
+## Q9: Should the simulated backend's state persist across page reloads?
+
+**Context:** Dummy repos are in-memory `Ref`s. By default they vanish on
+reload.
+
+**Suggestions:**
+- **Vanish on reload** (recommended) — matches the "perfect simulation" =
+  "fresh process" mental model; simpler.
+- **Persist to `localStorage`** — nicer UX, but pulls a persistence concern
+  into the dummy impls and dilutes the example.
+
+Answer: vanish on reload is fine
+
+---
+
+## Q10: Naming convention for the new modules and JS export object?
+
+**Context:** Need a name for the JS module (the cross-compiled "core") and
+the JS-only module (the JS adapter/entrypoint).
+
+**Suggestions:**
+- **`monomorphic-cats-core` (cross) + `monomorphic-cats-sim` (JS only) +
+  `monomorphic-cats` (JVM, unchanged name)**, with the JS export bound to
+  `window.LeaderboardSim` (recommended).
+- Something else — propose a naming scheme.
+
+Answer: your naming is acceptable
+
+---
+
+## Q11: Anything to leave alone?
+
+**Context:** Sanity check before I start moving files.
+
+**Suggestions:**
+- The GraalVM Native Image build configuration (`graalVMNativeImageOptions`,
+  `ni-filter.json`, `graal-resources`) should remain functional for the
+  chosen variant after the refactor.
+- The other two variants not chosen in Q1 should be left entirely untouched.
+- Existing tests in the chosen variant should keep passing without
+  modification (only build-file changes acceptable).
+
+Anything else? Constraints I should know about (e.g. scala 2 vs 3 only, no
+new top-level dependencies, must keep working with sbt 1.x, etc.)?
+
+Answer: nothing comes to my mind, you may limit this task to scala 3 only if it makes your job easier (most likely not)
+
+---
+
+## Q12: What is the exact shape of the dispatch result?
+
+**Context:** You picked the single-dispatch entrypoint (Q3): a function
+`call(method: String, path: String, body: String): IO[???]`. To make this work
+uniformly for prod (http4s converts it to an `HttpResponse`) and sim (JS
+adapter converts it to a `Promise[???]`), I need to fix the response type.
+The current endpoints can also fail (malformed UUID, decoding error, not
+found), so the result has to carry a status as well as a body.
+
+**Suggestions:**
+- **`LocalResponse(status: Int, body: String)`** (recommended) — minimal HTTP-
+  ish ADT. http4s side maps status → `Status`, body is the JSON string (or
+  empty for 204). JS side returns `js.Promise[js.Dynamic]` with
+  `{status, body}` fields so vanilla JS can branch on status. Keeps the
+  example small and uniformly HTTP-shaped.
+- **`Either[DispatchError, String]`** — leaves status mapping to each adapter
+  separately; less uniform but more "domain-typed."
+- **Plain `String`, exceptions for errors** — simplest happy path but the
+  error story leaks Scala stack traces across the JS boundary.
+
+Answer: you may use Either. Actually, if I remember correctly, the routing part of http4s can be run on scala.js. If that's true - you could just reuse existing routing - less work to do, better for the reader!
+
+---
+
+## Q13: CORS policy for the http4s server (because of file:// support in Q7).
+
+**Context:** You want the UI to also work when opened from `file://`. A page
+loaded from `file://` has origin `null`, so the http4s server has to send
+`Access-Control-Allow-Origin: null` (or `*`) for the `/ladder` and `/profile`
+endpoints in "prod" mode. Without this, the prod toggle won't work for
+file://-served pages.
+
+**Suggestions:**
+- **Permissive CORS on all API routes** (recommended for a demo) —
+  `Access-Control-Allow-Origin: *` plus the necessary methods/headers, applied
+  to API routes via http4s `CORS` middleware. Acceptable because this is an
+  example app, not a production service. README will call this out.
+- **Reflect the requesting origin** — slightly safer but adds complexity for
+  no real gain in a demo.
+- **No CORS, document that file:// only works with sim mode** — simpler code
+  but breaks half the demo when served from disk.
+
+Answer: you can add permissive cors headers
+
+---
+
+## Q14: How does the linked JS artifact get from `bifunctor-tagless-sim/target/...` to where the browser loads it?
+
+**Context:** `fullLinkJS` produces `main.js` inside the sim project's target
+dir. The http4s server needs to serve it as `/app.js`, and the file://
+workflow needs it next to `index.html`. Three plumbing options:
+
+**Suggestions:**
+- **sbt task `copySimJsToResources` that runs after `fullLinkJS` and copies
+  `main.js` (+ source map) into `bifunctor-tagless/src/main/resources/webapp/`,
+  which is also the static-files dir the http4s server reads from**
+  (recommended) — one location, one source of truth. README documents:
+  `sbt bifunctor-tagless-sim/fullLinkJS bifunctor-tagless/run`. The copied
+  artifact is gitignored.
+- **http4s reads the JS directly out of the sim target dir at runtime** —
+  works for dev but breaks the GraalVM native-image build and the file://
+  workflow.
+- **Commit the linked JS to the repo** — simplest for a casual reader, but
+  drifts. (Rejected unless you prefer it.)
+
+Answer: you may go the recommended way
+
+---
+
+## Q15: How "ceremonious" should the JS entrypoint be?
+
+**Context:** On the JVM side, the app uses `RoleAppMain.LauncherCats[IO]` with
+plugins, roles, activations — the full distage-framework stack. On JS, much
+of that machinery isn't useful (no CLI, no config files, no role lifecycle).
+We have two reasonable poles:
+
+**Suggestions:**
+- **Mini-entrypoint with plain `Injector`** (recommended) — the JS module
+  builds an `Injector[IO]` with `Activation(Repo -> Dummy, Scene -> Provided)`
+  from the shared "core" plugin (which excludes http4s/doobie/docker), grabs
+  the dispatcher out of the object graph once, and exports its methods as
+  `@JSExportTopLevel("LeaderboardSim")`. No roles, no config loader on JS.
+  Smallest JS bundle, clearest demo of "any distage graph can run in a
+  browser." Cost: a tiny bit of duplication between this and the JVM
+  `MainBase`.
+- **Full `RoleAppMain` on JS** — proves the same launcher code runs in the
+  browser, but requires `distage-extension-config` and
+  `distage-framework` to be JS-compatible. They might be (distage-core is),
+  but config relies on typesafe-config which is JVM-only — so this likely
+  forces ditching HOCON config on the JS side anyway. Bigger bundle, more
+  refactoring.
+
+Answer: recommended
+
+---
diff --git a/launch-sim b/launch-sim
new file mode 100755
index 0000000..868bfc0
--- /dev/null
+++ b/launch-sim
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+#
+# Build the Scala.js simulation bundle, drop it into the JVM project's
+# resources/webapp/, and start the leaderboard server in dummy mode (so it
+# needs neither Docker nor postgres). The UI is then reachable at
+# http://localhost:8080/ — the prod/sim toggle in that UI lets you compare
+# the real http4s backend against the in-browser simulation.
+
+set -euo pipefail
+cd "$(dirname "$0")"
+
+sbt "copySimJs; project bifunctor-taglessJVM; runMain leaderboard.GenericLauncher -u repo:dummy :leaderboard"
diff --git a/launcher b/launcher
index b2965dd..fd3f895 100755
--- a/launcher
+++ b/launcher
@@ -2,4 +2,4 @@
 
 ARGS="$@"
 
-sbt "project bifunctor-tagless; runMain leaderboard.GenericLauncher $ARGS"
+sbt "project bifunctor-taglessJVM; runMain leaderboard.GenericLauncher $ARGS"
diff --git a/project/plugins.sbt b/project/plugins.sbt
index f3d76ac..7a1151b 100644
--- a/project/plugins.sbt
+++ b/project/plugins.sbt
@@ -1,3 +1,5 @@
 addSbtPlugin("org.typelevel" % "sbt-tpolecat" % "0.5.3")
 addSbtPlugin("com.github.sbt" % "sbt-git" % "2.1.0")
 addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.13")
+addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.21.0")
+addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "1.3.2")

From dea1fdcd808324215461de50fa772d59156e76dc Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 20:07:46 +0100
Subject: [PATCH 2/7] wip

---
 .envrc     |  1 +
 .gitignore |  3 +++
 README.md  | 10 +++++++++
 flake.lock | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 flake.nix  | 49 +++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 124 insertions(+)
 create mode 100644 .envrc
 create mode 100644 flake.lock
 create mode 100644 flake.nix

diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..3550a30
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake
diff --git a/.gitignore b/.gitignore
index a8b5168..1997e8b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -130,6 +130,9 @@ hs_err_pid*
 # Project-local sbt/coursier/ivy caches used by the containerised dev loop.
 .cache/
 
+# direnv-materialised devShell
+.direnv/
+
 # Scala.js bundle copied here by the `copySimJs` sbt task — regenerated on
 # demand from bifunctor-tagless-js. Not checked in.
 bifunctor-tagless/jvm/src/main/resources/webapp/main.js
diff --git a/README.md b/README.md
index 3bc7428..7756d1b 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,16 @@ curl -X GET http://localhost:8080/ladder
 curl -X GET http://localhost:8080/profile/50753a00-5e2e-4a2f-94b0-e6721b0a3cc4
 ```
 
+### Reproducible toolchain via Nix (optional)
+
+A `flake.nix` is included. With Nix flakes enabled you can drop into a shell
+that has the exact JDK, sbt, Scala 3 and Node versions used by this project:
+
+```bash
+nix develop                  # one-off shell
+direnv allow                 # automatic — uses the bundled .envrc
+```
+
 ### Perfect simulation in the browser (`bifunctor-tagless` only)
 
 The `bifunctor-tagless` variant is cross-built for the JVM and Scala.js. The
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..cd56566
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1778443072,
+        "narHash": "sha256-zi7/fsqM/kFdNuED//4WOCUtezGtKKqRNORjMvfwjnA=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "da5ad661ba4e5ef59ba743f0d112cbc30e474f32",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..b53c573
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,49 @@
+{
+  description = "distage-example — cross-built distage app with a Scala.js in-browser simulation";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+        # Pin JDK 17 to match the GraalVM Native Image build (graalvm-ce 22.3
+        # is JDK 17-based) and the sbtscala/scala-sbt image used in CI/dev.
+        jdk = pkgs.temurin-bin-17;
+      in {
+        devShells.default = pkgs.mkShell {
+          name = "distage-example";
+
+          # Build/dev tooling. `nodejs` is here so the linked Scala.js bundle
+          # can be exercised outside the browser if needed (none of the demo
+          # paths require it — the http4s server serves the UI directly).
+          packages = with pkgs; [
+            jdk
+            sbt
+            scala_3
+            nodejs_22
+            git
+          ];
+
+          # sbt sometimes needs more heap when assembling the cross-built
+          # project + linking the Scala.js bundle.
+          SBT_OPTS = "-Xmx4G -Xss4m";
+
+          JAVA_HOME = "${jdk}/lib/openjdk";
+
+          shellHook = ''
+            echo "distage-example dev shell"
+            echo "  java     : $(java  -version 2>&1 | head -n1)"
+            echo "  sbt      : $(sbt   --script-version 2>/dev/null || sbt --version 2>&1 | tail -n1)"
+            echo "  scala 3  : $(scala -version 2>&1 | head -n1)"
+            echo
+            echo "Quick start:"
+            echo "  ./launch-sim                              # build JS, run dummy server, UI at http://localhost:8080/"
+            echo "  ./launcher -u scene:managed :leaderboard  # real backend with dockerized postgres"
+          '';
+        };
+      });
+}

From 6720bfdb94a0d4d42a5f62cf6d7dddfbd3b5bf38 Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 20:43:39 +0100
Subject: [PATCH 3/7] wip

---
 .github/workflows/build.yml                   |  18 +-
 .../leaderboard/sim/SimulationMain.scala      |  19 +-
 .../jvm/src/main/resources/webapp/index.html  |  26 +-
 .../scala/leaderboard/http/HttpServer.scala   |  21 +-
 build.sbt                                     |  22 +-
 ...60513-1757-questions-scalajs-simulation.md | 337 ------------------
 flake.nix                                     |   9 +-
 7 files changed, 78 insertions(+), 374 deletions(-)
 delete mode 100644 docs/drafts/20260513-1757-questions-scalajs-simulation.md

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 39c49bc..44a0a8f 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -17,12 +17,26 @@ jobs:
     - uses: actions/checkout@v2
     - name: Run tests
       run: sbt +test
+
+  sim-smoke:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: sbt/setup-sbt@v1
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+    - name: Link Scala.js bundle into JVM resources
+      run: sbt copySimJs
+    - name: Smoke-test the simulation bundle via node
+      run: node bifunctor-tagless/js/sim-smoke.js
+
   build-native:
     runs-on: ubuntu-latest
     steps:
       - uses: sbt/setup-sbt@v1 # setup sbt
       - uses: actions/checkout@v2
       - name: Build native app
-        run: sbt "project bifunctor-tagless; GraalVMNativeImage/packageBin"
+        run: sbt "project bifunctor-taglessJVM; GraalVMNativeImage/packageBin"
       - name: Check native app
-        run: ./bifunctor-tagless/target/graalvm-native-image/bifunctor-tagless :help
+        run: ./bifunctor-tagless/jvm/target/graalvm-native-image/bifunctor-tagless :help
diff --git a/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
index f37eff3..0b67340 100644
--- a/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
+++ b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
@@ -3,6 +3,7 @@ package leaderboard.sim
 import distage.StandardAxis.Repo
 import distage.{Activation, Injector, ModuleDef, Roots}
 import izumi.distage.modules.DefaultModule2
+import izumi.logstage.api.IzLogger
 import izumi.logstage.distage.LogIO2Module
 import leaderboard.dispatch.LocalDispatcher
 import leaderboard.plugins.LeaderboardCoreModule
@@ -49,10 +50,14 @@ object SimulationMain {
     val module = new ModuleDef {
       include(LeaderboardCoreModule.api[IO])
       include(LeaderboardCoreModule.repoDummy[IO])
-      // LogIO2[IO] needed by ProfileApi.
+      // LogIO2[IO] (needed by ProfileApi) + a default IzLogger that prints to
+      // the browser/Node console. The JVM build wires this up via the
+      // role-app machinery; here we provide it directly.
       include(LogIO2Module[IO]())
-      // BIO typeclass instances (IO2, Async2, Primitives2, ...) used by the
-      // dummy repos and the dispatcher.
+      make[IzLogger].fromValue(IzLogger())
+      // BIO + cats-effect typeclass instances for ZIO. When zio-interop-cats
+      // is on the classpath, this resolves to `DefaultModule.forZIOPlusCats`
+      // which binds `cats.effect.Async[Task]` etc. — the dispatcher needs it.
       include(DefaultModule2[IO])
     }
 
@@ -61,7 +66,13 @@ object SimulationMain {
     // long as the JS module is loaded.
     val program: G[Nothing] =
       Injector.NoProxies[G]()
-        .produce(module, Roots.target[LocalDispatcher[IO]], Activation(Repo -> Repo.Dummy))
+        // `Roots.Everything` instead of `Roots.target[LocalDispatcher]` because
+        // `LeaderboardCoreModule.api` adds `LadderApi`/`ProfileApi` to the
+        // `Set[HttpApi[F]]` as *weak* references — they only join the set if
+        // they're independently reachable through the plan. The JVM app pulls
+        // them in via roles; here we have no roles, so we ask the planner to
+        // include every binding that's not pinned out by the activation.
+        .produce(module, Roots.Everything, Activation(Repo -> Repo.Dummy))
         .use {
           locator =>
             dispatcherReady.succeed(locator.get[LocalDispatcher[IO]]) *> ZIO.never
diff --git a/bifunctor-tagless/jvm/src/main/resources/webapp/index.html b/bifunctor-tagless/jvm/src/main/resources/webapp/index.html
index 0e7fc7d..120fa6f 100644
--- a/bifunctor-tagless/jvm/src/main/resources/webapp/index.html
+++ b/bifunctor-tagless/jvm/src/main/resources/webapp/index.html
@@ -69,13 +69,17 @@ <h1>distage-example leaderboard</h1>
   <h2>Response</h2>
   <pre id="output">(no calls yet)</pre>
 
-  <script type="module">
-    // `main.js` is an ES module. `@JSExportTopLevel("LeaderboardSim")` in
-    // ESModule mode emits a named export, so we import it and attach it to
-    // globalThis to keep the rest of this page's plain script simple.
-    import { LeaderboardSim } from './main.js';
-    globalThis.LeaderboardSim = LeaderboardSim;
-
+  <!--
+    The Scala.js bundle is linked with `ModuleKind.NoModule`, so a bare
+    <script src> tag makes `@JSExportTopLevel("LeaderboardSim")` available as
+    a top-level identifier in subsequent <script> blocks. (The name is in the
+    script's lexical scope, not on `globalThis` — that's normal for
+    top-level `let` declarations.) We avoid type="module" because browsers
+    refuse to load ES modules from `file://`, and this page should work both
+    via http://localhost:8080/ and by opening the .html directly from disk.
+  -->
+  <script src="./main.js"></script>
+  <script>
     // The prod target uses an absolute URL so the same `index.html` works
     // whether it's served by the http4s server or opened directly from disk
     // via file://. CORS on the server allows the file:// origin (which is
@@ -100,8 +104,8 @@ <h2>Response</h2>
       const mode = currentMode();
       try {
         if (mode === 'sim') {
-          if (!globalThis.LeaderboardSim) throw new Error('simulation not ready yet');
-          const r = await globalThis.LeaderboardSim.call(method, path, body || '');
+          if (typeof LeaderboardSim === 'undefined') throw new Error('simulation not ready yet');
+          const r = await LeaderboardSim.call(method, path, body || '');
           show('sim', r.status, r.body);
         } else {
           const r = await fetch(PROD_BASE + path, {
@@ -118,10 +122,10 @@ <h2>Response</h2>
     // Poll briefly for the Scala.js module to finish initialising so we can
     // tell the user the simulation is ready.
     (async () => {
-      for (let i = 0; i < 50 && !globalThis.LeaderboardSim; i++) {
+      for (let i = 0; i < 50 && typeof LeaderboardSim === 'undefined'; i++) {
         await new Promise(r => setTimeout(r, 100));
       }
-      status.textContent = globalThis.LeaderboardSim
+      status.textContent = (typeof LeaderboardSim !== 'undefined')
         ? 'simulation: ready'
         : 'simulation: failed to load (check /main.js)';
     })();
diff --git a/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala b/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
index 2e1ceaa..f5f4e24 100644
--- a/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
+++ b/bifunctor-tagless/jvm/src/main/scala/leaderboard/http/HttpServer.scala
@@ -6,11 +6,13 @@ import com.comcast.ip4s.Port
 import fs2.io.net.Network
 import izumi.distage.model.definition.Lifecycle
 import leaderboard.api.HttpApi
-import org.http4s.HttpRoutes
+import org.http4s.dsl.Http4sDsl
 import org.http4s.ember.server.EmberServerBuilder
+import org.http4s.headers.Location
 import org.http4s.server.Server
 import org.http4s.server.middleware.CORS
 import org.http4s.server.staticcontent.resourceServiceBuilder
+import org.http4s.{HttpRoutes, Uri}
 
 final case class HttpServer(
   server: Server
@@ -19,26 +21,31 @@ final case class HttpServer(
 object HttpServer {
 
   final class Impl[F[+_, +_]](
-    allHttpApis: Set[HttpApi[F]]
+    allHttpApis: Set[HttpApi[F]],
+    dsl: Http4sDsl[F[Throwable, _]],
   )(implicit
     async: Async[F[Throwable, _]]
   ) extends Lifecycle.Of[F[Throwable, _], HttpServer](
       Lifecycle.fromCats {
         type G[A] = F[Throwable, A]
+        import dsl.*
 
         // The same HttpRoutes the LocalDispatcher invokes in-process.
         val apiRoutes: HttpRoutes[G] = allHttpApis.map(_.http).toList.foldK
 
-        // Serve /webapp resources at the root, so the demo UI is available
-        // at e.g. http://localhost:8080/ alongside the API endpoints.
-        val staticRoutes: HttpRoutes[G] =
-          resourceServiceBuilder[G]("/webapp").toRoutes
+        // Static demo UI in classpath under /webapp. The resource builder maps
+        // request paths verbatim (e.g. GET /main.js -> classpath /webapp/main.js),
+        // so a tiny extra route redirects GET / to /index.html.
+        val indexRedirect: HttpRoutes[G] = HttpRoutes.of[G] {
+          case GET -> Root => PermanentRedirect(Location(Uri.unsafeFromString("/index.html")))
+        }
+        val staticRoutes: HttpRoutes[G] = resourceServiceBuilder[G]("/webapp").toRoutes
 
         // Permissive CORS so the same UI also works when opened from file://
         // (its origin is "null" in that case). Demo-grade — do not copy
         // verbatim into a real production service.
         val app = CORS.policy.withAllowOriginAll(
-          (apiRoutes <+> staticRoutes).orNotFound
+          (apiRoutes <+> indexRedirect <+> staticRoutes).orNotFound
         )
 
         EmberServerBuilder
diff --git a/build.sbt b/build.sbt
index 4f3a061..c6a6d3b 100644
--- a/build.sbt
+++ b/build.sbt
@@ -112,20 +112,22 @@ lazy val `bifunctor-tagless` = crossProject(JVMPlatform, JSPlatform)
       "io.circe"       %%% "circe-generic"              % V.circeGeneric,
       "org.typelevel"  %%% "cats-core"                  % V.catsCore,
       "dev.zio"        %%% "zio"                        % V.zio,
-      // Intentionally NOT depending on zio-interop-cats here — its
-      // `ZManagedMonadError` references zio 1.x types that no longer link
-      // under scala.js. The bifunctor-tagless code uses
-      // `izumi.functional.bio.catz` for its cats-effect bridge instead. The
-      // JVM half still pulls in zio-interop-cats via distage-testkit /
-      // monofunctor-tagless transitively if needed.
+      // `zio-managed` is required transitively by `zio-interop-cats`'s
+      // ZManaged bridge classes; under scala.js the linker validates all
+      // referenced classes, so we must pull the artifact in explicitly.
+      "dev.zio"        %%% "zio-managed"                % V.zio,
+      "dev.zio"        %%% "zio-interop-cats"           % V.zioCats,
     ),
   )
   .jvmConfigure(_.pipe(jvmSharedSettings(Seq(Deps.zio, Deps.zioCats))))
   .jsSettings(
     scalaJSUseMainModuleInitializer := false,
-    // Emit ES module output so the front-end can import it via
-    // <script type="module">.
-    scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) },
+    // NoModule output: the linker emits a plain script that publishes
+    // `@JSExportTopLevel` bindings on the global scope. We deliberately do
+    // NOT use ESModule here because browsers refuse to load ES modules from
+    // `file://` (the simulation page is meant to be usable both via the
+    // http4s server and by opening index.html directly from disk).
+    scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.NoModule) },
   )
 
 // sbt-scalajs-crossproject derives the per-platform project IDs from the
@@ -243,4 +245,4 @@ def jvmSharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project
 def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = jvmSharedSettings(additionalDeps)(project)
 
 // for quick experiments with distage snapshots
-ThisBuild / resolvers ++= Resolver.sonatypeOssRepos("snapshots")
+ThisBuild / resolvers += Resolver.sonatypeCentralSnapshots
diff --git a/docs/drafts/20260513-1757-questions-scalajs-simulation.md b/docs/drafts/20260513-1757-questions-scalajs-simulation.md
deleted file mode 100644
index cfde7cd..0000000
--- a/docs/drafts/20260513-1757-questions-scalajs-simulation.md
+++ /dev/null
@@ -1,337 +0,0 @@
-# Clarifications: scala.js "perfect simulation" webapp
-
-**Context:** Extending distage-example with a small webapp that calls the same
-endpoints as the curl commands in the README, with a runtime toggle between
-"production" (real HTTP server) and "simulation" (the same backend code compiled
-to scala.js and running in the browser with the `Dummy` axis selected).
-
-The current code is not yet cross-buildable: `LadderApi`/`ProfileApi` directly
-return `HttpRoutes[IO]`, and the plugins pull in http4s-ember, doobie, and
-distage-framework-docker — none of which compile to scala.js. So the work
-involves: (a) extracting a JS-portable "core" of each API behind a
-serialized-input/serialized-output interface, (b) cross-building those modules
-for JS, (c) adding `@JSExportTopLevel` entrypoints that build a distage object
-graph with the dummy axis, and (d) shipping a tiny frontend with a backend
-switch.
-
-**How to answer:** Write your response on the `Answer:` line under each
-question. Leave blank to skip. Reference questions by ID (e.g. `Q3`) in chat if
-convenient.
-
----
-
-## Q1: Which of the three variants should get the scala.js treatment?
-
-**Context:** `bifunctor-tagless`, `monofunctor-tagless`, and `monomorphic-cats`
-all expose the same endpoints. Cross-building all three roughly triples the
-build.sbt surface, the plugin/role duplication, and the JS bundle work, but
-they would all need to stay in sync if the example is meant to demonstrate that
-"any distage app can be simulated."
-
-**Suggestions:**
-- **`monomorphic-cats` only** (recommended) — simplest stack (no BIO, no ZIO,
-  no tagless), smallest delta, easiest to read as a demo. Other two variants
-  stay JVM-only.
-- **`bifunctor-tagless` only** — it's the "main" example per README, so
-  showcasing simulation there has the most marketing value, but it pulls in
-  zio + zio-interop-cats on JS which is heavier and adds a tagless layer to
-  the simulation story.
-- **All three** — uniform across variants, but a lot of duplicated build wiring
-  for a demo project.
-
-Answer: bifunctor-tagless only. zio etc work fine on js
-
----
-
-## Q2: How should the project be split for cross-compilation?
-
-**Context:** Today each variant is a single sbt project mixing JVM-only pieces
-(http4s server, doobie, docker plugin, role main) with logic that could be
-JS-portable (model classes, dummy repo impls, API logic). To cross-build, we
-need to separate them.
-
-**Suggestions:**
-- **`<variant>-core` (cross JVM/JS) + `<variant>` (JVM, depends on core) +
-  `<variant>-sim` (JS only, depends on core)** (recommended) — clearest
-  layering: `core` holds model + repo traits + dummy impls + a "local API"
-  layer; `<variant>` adds http4s/doobie/docker/role; `<variant>-sim` adds the
-  `@JSExportTopLevel` adapter and scalajs-bundler config.
-- **Convert `<variant>` itself to a cross project** — fewer modules, but the
-  JVM side has to be reorganized so that all http4s/doobie code lives under a
-  `jvm/` source tree; bigger diff to the existing layout.
-- **Keep `<variant>` JVM-only, add a sibling `<variant>-sim` that
-  *source-depends* on a curated subset of files** — minimal disturbance to
-  the existing tree, but fragile (file lists drift) and harder to explain.
-
-Answer: cross-projects with subfolders
-
----
-
-## Q3: What should the "local call" boundary look like?
-
-**Context:** The endpoints currently take typed parameters from the URL
-(`UUIDVar`, `LongVar`) and JSON bodies, and they return JSON. For the
-simulation, JS calls into the same logic, but the natural calling convention
-across the JS/JVM boundary is `String => Future[String]` (or similar) so the
-front-end doesn't have to know Scala types. The chosen shape determines what
-gets exported to JS and what the http4s layer becomes.
-
-**Suggestions:**
-- **Method-style local API** (recommended) — define a trait like
-  `LadderLocalApi { def getScores: IO[String]; def submitScore(userIdJson:
-  String, scoreJson: String): IO[String] }` where each method corresponds to
-  one endpoint; circe encodes/decodes inside. The http4s layer becomes a thin
-  router on top, and the JS adapter exports the same methods. Pros: typed
-  arguments stay typed inside Scala, JSON only at the wire boundary. Cons: one
-  method per endpoint to maintain on both sides.
-- **Single dispatch entrypoint** — one `def call(method: String, path: String,
-  body: String): IO[Response]` that mimics an HTTP request/response. Pros: one
-  export to JS, frontend code is identical for prod vs sim (just swap the
-  transport). Cons: stringly-typed routing inside Scala — defeats some of the
-  type safety the example is showcasing.
-- **HTTP-shaped over a transport interface** — abstract over `Transport` where
-  the prod impl uses fetch and the sim impl calls the in-browser app's
-  router. Most idiomatic for "perfect simulation" but the heaviest change.
-
-Answer: single dispatch entrypoint is more aligned to the purpose of the demo - to showcase how to build simulations sharing nearly all the code/approaches
-
----
-
-## Q4: Which scala.js promise type should the JS export use?
-
-**Context:** `IO[A]` doesn't cross the JS boundary; we have to expose a JS
-`Promise` or `Thenable`. cats-effect's `IO#unsafeToPromise` exists on JS.
-
-**Suggestions:**
-- **`scala.scalajs.js.Promise[String]`** (recommended) — what JS code expects;
-  `await`-able from plain JS or TS. Simplest possible interop.
-- **`js.Thenable[String]`** — more permissive but rarely needed.
-- **Synchronous `String` return** — only viable if every dummy impl is
-  fully synchronous, which would constrain the design.
-
-Answer: use scala.js promise
-
----
-
-## Q5: What should the frontend be written in?
-
-**Context:** The "small webapp" needs an input form per endpoint (or a free-
-form curl-like UI), a result panel, and a toggle for prod/sim backend.
-
-**Suggestions:**
-- **Plain HTML + a few lines of vanilla JS** (recommended) — zero extra
-  toolchain, served as static files; demonstrates the simulation idea without
-  introducing a UI framework as a second axis of complexity. ~100 lines.
-- **Scala.js + Laminar (or scalajs-dom only)** — keeps everything in Scala,
-  but adds Laminar as a dependency and makes the frontend a third scala.js
-  module.
-- **TypeScript + small bundler (vite/esbuild)** — most realistic for a
-  real-world setup but adds an npm toolchain to the repo just for the demo.
-
-Answer: plain html + vanilla js - we want a minimalistic example
-
----
-
-## Q6: How should the JS artifact be produced and served?
-
-**Context:** Need to decide between sbt-scalajs `fastLinkJS`/`fullLinkJS`
-output vs `scalajs-bundler`, and how the frontend loads it.
-
-**Suggestions:**
-- **`fullLinkJS` + ES module output, loaded directly by `index.html` via
-  `<script type="module">`** (recommended) — no bundler, no npm, no
-  webpack. The dummy backend uses no JS libraries that need npm packaging, so
-  there's nothing to bundle.
-- **scalajs-bundler with webpack** — necessary only if we pull in npm
-  dependencies; overkill here.
-- **Pre-built JS committed to the repo + sbt task to refresh it** — easier for
-  someone just reading the README, but stale-artifact risk.
-
-Answer: go the recommended way
-
----
-
-## Q7: Where do the frontend assets live and how are they served?
-
-**Context:** The webapp itself (HTML + JS bundle) needs a home. Two natural
-options:
-
-**Suggestions:**
-- **Serve the static files from the same http4s server** (recommended) —
-  add a `/` route that returns `index.html` and `/app.js` returning the
-  linked JS. Then `./launcher :leaderboard` exposes the UI at
-  `http://localhost:8080/` alongside the API. One process, no extra
-  instructions in the README.
-- **Static files in `./webapp/` opened directly from disk via `file://`** —
-  simplest, but `file://` + CORS gotchas when "production" mode tries to call
-  `http://localhost:8080`. Workable but rougher demo.
-- **Separate tiny static server module** — overkill.
-
-Answer: I think we should combine two options - we may serve the app through http4s AND let the user to open directly from file://
-
----
-
-## Q8: How should the prod/sim toggle behave on the frontend?
-
-**Context:** The user wants a switch between "real HTTP server" and "scala.js
-simulation". The two modes need different request paths in the frontend code.
-
-**Suggestions:**
-- **Radio button / toggle in the UI; both modes available simultaneously**
-  (recommended) — in "prod" mode the JS does `fetch('/ladder', ...)`; in
-  "sim" mode it calls `window.LeaderboardSim.submitScore(...)`. The simulated
-  backend is initialised once on page load. User can flip between them and
-  see, for instance, that sim state doesn't propagate to prod and vice versa
-  — which is itself a nice demonstration of "perfect simulation."
-- **Build-time flag** — two separate HTML files, one per mode. Simpler code
-  but you can't compare them side by side.
-- **Two browser tabs, two servers** — defeats the purpose.
-
-Answer: toggle in the UI
-
----
-
-## Q9: Should the simulated backend's state persist across page reloads?
-
-**Context:** Dummy repos are in-memory `Ref`s. By default they vanish on
-reload.
-
-**Suggestions:**
-- **Vanish on reload** (recommended) — matches the "perfect simulation" =
-  "fresh process" mental model; simpler.
-- **Persist to `localStorage`** — nicer UX, but pulls a persistence concern
-  into the dummy impls and dilutes the example.
-
-Answer: vanish on reload is fine
-
----
-
-## Q10: Naming convention for the new modules and JS export object?
-
-**Context:** Need a name for the JS module (the cross-compiled "core") and
-the JS-only module (the JS adapter/entrypoint).
-
-**Suggestions:**
-- **`monomorphic-cats-core` (cross) + `monomorphic-cats-sim` (JS only) +
-  `monomorphic-cats` (JVM, unchanged name)**, with the JS export bound to
-  `window.LeaderboardSim` (recommended).
-- Something else — propose a naming scheme.
-
-Answer: your naming is acceptable
-
----
-
-## Q11: Anything to leave alone?
-
-**Context:** Sanity check before I start moving files.
-
-**Suggestions:**
-- The GraalVM Native Image build configuration (`graalVMNativeImageOptions`,
-  `ni-filter.json`, `graal-resources`) should remain functional for the
-  chosen variant after the refactor.
-- The other two variants not chosen in Q1 should be left entirely untouched.
-- Existing tests in the chosen variant should keep passing without
-  modification (only build-file changes acceptable).
-
-Anything else? Constraints I should know about (e.g. scala 2 vs 3 only, no
-new top-level dependencies, must keep working with sbt 1.x, etc.)?
-
-Answer: nothing comes to my mind, you may limit this task to scala 3 only if it makes your job easier (most likely not)
-
----
-
-## Q12: What is the exact shape of the dispatch result?
-
-**Context:** You picked the single-dispatch entrypoint (Q3): a function
-`call(method: String, path: String, body: String): IO[???]`. To make this work
-uniformly for prod (http4s converts it to an `HttpResponse`) and sim (JS
-adapter converts it to a `Promise[???]`), I need to fix the response type.
-The current endpoints can also fail (malformed UUID, decoding error, not
-found), so the result has to carry a status as well as a body.
-
-**Suggestions:**
-- **`LocalResponse(status: Int, body: String)`** (recommended) — minimal HTTP-
-  ish ADT. http4s side maps status → `Status`, body is the JSON string (or
-  empty for 204). JS side returns `js.Promise[js.Dynamic]` with
-  `{status, body}` fields so vanilla JS can branch on status. Keeps the
-  example small and uniformly HTTP-shaped.
-- **`Either[DispatchError, String]`** — leaves status mapping to each adapter
-  separately; less uniform but more "domain-typed."
-- **Plain `String`, exceptions for errors** — simplest happy path but the
-  error story leaks Scala stack traces across the JS boundary.
-
-Answer: you may use Either. Actually, if I remember correctly, the routing part of http4s can be run on scala.js. If that's true - you could just reuse existing routing - less work to do, better for the reader!
-
----
-
-## Q13: CORS policy for the http4s server (because of file:// support in Q7).
-
-**Context:** You want the UI to also work when opened from `file://`. A page
-loaded from `file://` has origin `null`, so the http4s server has to send
-`Access-Control-Allow-Origin: null` (or `*`) for the `/ladder` and `/profile`
-endpoints in "prod" mode. Without this, the prod toggle won't work for
-file://-served pages.
-
-**Suggestions:**
-- **Permissive CORS on all API routes** (recommended for a demo) —
-  `Access-Control-Allow-Origin: *` plus the necessary methods/headers, applied
-  to API routes via http4s `CORS` middleware. Acceptable because this is an
-  example app, not a production service. README will call this out.
-- **Reflect the requesting origin** — slightly safer but adds complexity for
-  no real gain in a demo.
-- **No CORS, document that file:// only works with sim mode** — simpler code
-  but breaks half the demo when served from disk.
-
-Answer: you can add permissive cors headers
-
----
-
-## Q14: How does the linked JS artifact get from `bifunctor-tagless-sim/target/...` to where the browser loads it?
-
-**Context:** `fullLinkJS` produces `main.js` inside the sim project's target
-dir. The http4s server needs to serve it as `/app.js`, and the file://
-workflow needs it next to `index.html`. Three plumbing options:
-
-**Suggestions:**
-- **sbt task `copySimJsToResources` that runs after `fullLinkJS` and copies
-  `main.js` (+ source map) into `bifunctor-tagless/src/main/resources/webapp/`,
-  which is also the static-files dir the http4s server reads from**
-  (recommended) — one location, one source of truth. README documents:
-  `sbt bifunctor-tagless-sim/fullLinkJS bifunctor-tagless/run`. The copied
-  artifact is gitignored.
-- **http4s reads the JS directly out of the sim target dir at runtime** —
-  works for dev but breaks the GraalVM native-image build and the file://
-  workflow.
-- **Commit the linked JS to the repo** — simplest for a casual reader, but
-  drifts. (Rejected unless you prefer it.)
-
-Answer: you may go the recommended way
-
----
-
-## Q15: How "ceremonious" should the JS entrypoint be?
-
-**Context:** On the JVM side, the app uses `RoleAppMain.LauncherCats[IO]` with
-plugins, roles, activations — the full distage-framework stack. On JS, much
-of that machinery isn't useful (no CLI, no config files, no role lifecycle).
-We have two reasonable poles:
-
-**Suggestions:**
-- **Mini-entrypoint with plain `Injector`** (recommended) — the JS module
-  builds an `Injector[IO]` with `Activation(Repo -> Dummy, Scene -> Provided)`
-  from the shared "core" plugin (which excludes http4s/doobie/docker), grabs
-  the dispatcher out of the object graph once, and exports its methods as
-  `@JSExportTopLevel("LeaderboardSim")`. No roles, no config loader on JS.
-  Smallest JS bundle, clearest demo of "any distage graph can run in a
-  browser." Cost: a tiny bit of duplication between this and the JVM
-  `MainBase`.
-- **Full `RoleAppMain` on JS** — proves the same launcher code runs in the
-  browser, but requires `distage-extension-config` and
-  `distage-framework` to be JS-compatible. They might be (distage-core is),
-  but config relies on typesafe-config which is JVM-only — so this likely
-  forces ditching HOCON config on the JS side anyway. Bigger bundle, more
-  refactoring.
-
-Answer: recommended
-
----
diff --git a/flake.nix b/flake.nix
index b53c573..5197893 100644
--- a/flake.nix
+++ b/flake.nix
@@ -10,9 +10,12 @@
     flake-utils.lib.eachDefaultSystem (system:
       let
         pkgs = import nixpkgs { inherit system; };
-        # Pin JDK 17 to match the GraalVM Native Image build (graalvm-ce 22.3
-        # is JDK 17-based) and the sbtscala/scala-sbt image used in CI/dev.
-        jdk = pkgs.temurin-bin-17;
+        # GraalVM CE — used as a regular JDK for `sbt compile/test/run` and
+        # additionally provides the `native-image` binary so the local
+        # native-image workflow described in the README works without Docker.
+        # (The Docker-based `graalVMNativeImageGraalVersion` path in build.sbt
+        # still pulls its own image and doesn't depend on this JDK.)
+        jdk = pkgs.graalvmPackages.graalvm-ce;
       in {
         devShells.default = pkgs.mkShell {
           name = "distage-example";

From d940b91caebb05b2d2e2782141cd2e25f26cf50b Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 20:43:45 +0100
Subject: [PATCH 4/7] wip

---
 bifunctor-tagless/js/sim-smoke.js | 111 ++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100755 bifunctor-tagless/js/sim-smoke.js

diff --git a/bifunctor-tagless/js/sim-smoke.js b/bifunctor-tagless/js/sim-smoke.js
new file mode 100755
index 0000000..c079fa8
--- /dev/null
+++ b/bifunctor-tagless/js/sim-smoke.js
@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Smoke-test the in-browser simulation bundle outside the browser.
+ *
+ * Loads the linked Scala.js bundle from the JVM project's
+ * `resources/webapp/main.js` (produced by `sbt copySimJs`) and exercises the
+ * same four endpoints the README's `curl` snippets call: submit a score, get
+ * the ladder, set a profile, get the profile. Each call should return HTTP
+ * 200; mismatches fail the run with a non-zero exit code.
+ *
+ * Run from the repo root:
+ *
+ *   sbt copySimJs
+ *   node bifunctor-tagless/js/sim-smoke.js
+ *
+ * scala.js NoModule mode emits `let LeaderboardSim` at script top level. This
+ * is intentionally script-scoped (so a browser <script src=...> exposes it as
+ * an identifier in the script's lexical scope, not on `globalThis`); to thread
+ * it out for assertions in Node we eval the bundle in a `vm` context and
+ * re-export the binding via the trailing line.
+ */
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const BUNDLE = path.resolve(
+  __dirname,
+  '..',
+  'jvm',
+  'src',
+  'main',
+  'resources',
+  'webapp',
+  'main.js',
+);
+
+if (!fs.existsSync(BUNDLE)) {
+  console.error(`Bundle not found at ${BUNDLE}. Run \`sbt copySimJs\` first.`);
+  process.exit(1);
+}
+
+const bundle = fs.readFileSync(BUNDLE, 'utf8');
+const ctx = {
+  setTimeout, setInterval, clearTimeout, clearInterval, console,
+  queueMicrotask, Promise, process,
+};
+vm.createContext(ctx);
+vm.runInContext(bundle + '\nthis.LeaderboardSim = LeaderboardSim;', ctx);
+
+const Sim = ctx.LeaderboardSim;
+if (!Sim) {
+  console.error('FAIL: LeaderboardSim binding not produced by main.js');
+  process.exit(1);
+}
+
+const USER = '50753a00-5e2e-4a2f-94b0-e6721b0a3cc4';
+
+function expect(label, response, expectedStatus, bodyPredicate) {
+  if (response.status !== expectedStatus) {
+    console.error(`FAIL: ${label} returned HTTP ${response.status}, expected ${expectedStatus}. body=${response.body}`);
+    process.exit(1);
+  }
+  if (bodyPredicate && !bodyPredicate(response.body)) {
+    console.error(`FAIL: ${label} body did not match expectation: ${response.body}`);
+    process.exit(1);
+  }
+  console.log(`ok   ${label} -> ${response.status} ${response.body || ''}`);
+}
+
+async function main() {
+  // Submit a score (empty body, score from URL).
+  expect('POST /ladder/{user}/100', await Sim.call('POST', `/ladder/${USER}/100`, ''), 200);
+
+  // Fetch the ladder — must contain our user with score 100.
+  const ladder = await Sim.call('GET', '/ladder', '');
+  expect(
+    'GET  /ladder',
+    ladder,
+    200,
+    body => {
+      const rows = JSON.parse(body);
+      return Array.isArray(rows) && rows.some(([u, s]) => u === USER && s === 100);
+    },
+  );
+
+  // Set a profile.
+  expect(
+    'POST /profile/{user}',
+    await Sim.call('POST', `/profile/${USER}`, JSON.stringify({ name: 'Kai', description: 'S C A L A' })),
+    200,
+  );
+
+  // Fetch the profile — must include rank + score from the ladder.
+  const profile = await Sim.call('GET', `/profile/${USER}`, '');
+  expect(
+    'GET  /profile/{user}',
+    profile,
+    200,
+    body => {
+      const p = JSON.parse(body);
+      return p.name === 'Kai' && p.description === 'S C A L A' && p.rank === 1 && p.score === 100;
+    },
+  );
+
+  console.log('\nsim-smoke: all assertions passed');
+}
+
+main().catch(e => {
+  console.error('FAIL:', e);
+  process.exit(1);
+});

From e105f5e72fa2f8d15efc1227a508af49681b8770 Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 20:45:47 +0100
Subject: [PATCH 5/7] wip

---
 .../main/scala/leaderboard/sim/SimulationMain.scala    | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
index 0b67340..c1362df 100644
--- a/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
+++ b/bifunctor-tagless/js/src/main/scala/leaderboard/sim/SimulationMain.scala
@@ -5,6 +5,7 @@ import distage.{Activation, Injector, ModuleDef, Roots}
 import izumi.distage.modules.DefaultModule2
 import izumi.logstage.api.IzLogger
 import izumi.logstage.distage.LogIO2Module
+import izumi.logstage.sink.ConsoleSink
 import leaderboard.dispatch.LocalDispatcher
 import leaderboard.plugins.LeaderboardCoreModule
 import zio.{IO, Promise as ZPromise, Runtime, Unsafe, ZIO}
@@ -50,11 +51,12 @@ object SimulationMain {
     val module = new ModuleDef {
       include(LeaderboardCoreModule.api[IO])
       include(LeaderboardCoreModule.repoDummy[IO])
-      // LogIO2[IO] (needed by ProfileApi) + a default IzLogger that prints to
-      // the browser/Node console. The JVM build wires this up via the
-      // role-app machinery; here we provide it directly.
+      // LogIO2[IO] (needed by ProfileApi) + a console logger. We use
+      // `SimpleConsoleSink` instead of the default `ColoredConsoleSink`
+      // because the latter probes `process.env` for terminal-color detection
+      // on init, which doesn't exist in the browser.
       include(LogIO2Module[IO]())
-      make[IzLogger].fromValue(IzLogger())
+      make[IzLogger].fromValue(IzLogger(sink = ConsoleSink.SimpleConsoleSink))
       // BIO + cats-effect typeclass instances for ZIO. When zio-interop-cats
       // is on the classpath, this resolves to `DefaultModule.forZIOPlusCats`
       // which binds `cats.effect.Async[Task]` etc. — the dispatcher needs it.

From c6ab195dbaf180fc80f3d1339df634de1ec59535 Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 21:01:36 +0100
Subject: [PATCH 6/7] wip

---
 bifunctor-tagless/js/sim-smoke.js |  5 ++++-
 build.sbt                         | 18 +++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/bifunctor-tagless/js/sim-smoke.js b/bifunctor-tagless/js/sim-smoke.js
index c079fa8..c05bba7 100755
--- a/bifunctor-tagless/js/sim-smoke.js
+++ b/bifunctor-tagless/js/sim-smoke.js
@@ -40,9 +40,12 @@ if (!fs.existsSync(BUNDLE)) {
 }
 
 const bundle = fs.readFileSync(BUNDLE, 'utf8');
+// Deliberately omit `process` from the context so this smoke test fails the
+// same way a browser would if the bundle accidentally probes Node.js APIs at
+// init. The Scala.js bundle must run without a `process` global.
 const ctx = {
   setTimeout, setInterval, clearTimeout, clearInterval, console,
-  queueMicrotask, Promise, process,
+  queueMicrotask, Promise,
 };
 vm.createContext(ctx);
 vm.runInContext(bundle + '\nthis.LeaderboardSim = LeaderboardSim;', ctx);
diff --git a/build.sbt b/build.sbt
index c6a6d3b..74d5744 100644
--- a/build.sbt
+++ b/build.sbt
@@ -217,13 +217,18 @@ def sharedScalaSettings: Seq[Setting[_]] = Seq(
 )
 
 // JVM-only project settings (the http4s ember server, doobie, GraalVM native
-// image, etc). Applied to monomorphic-cats, monofunctor-tagless, and the JVM
-// half of bifunctor-tagless.
+// image, etc). Applied to the JVM half of `bifunctor-tagless` and — via
+// `sharedSettings` below — to the plain JVM-only projects.
+//
+// Intentionally does NOT include `sharedScalaSettings`: the cross-built
+// bifunctor-tagless applies those once on the cross project so they reach
+// both halves, and applying them a second time here would set scalacOptions
+// like `-Yretain-trees` twice and trip sbt-tpolecat's "set repeatedly"
+// guard.
 def jvmSharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = {
   project
     .settings(
       libraryDependencies ++= Deps.CoreDeps ++ additionalDeps,
-      sharedScalaSettings,
       GraalVMNativeImage / mainClass := Some("leaderboard.GenericLauncher"),
       graalVMNativeImageOptions ++= Seq(
         "--no-fallback",
@@ -241,8 +246,11 @@ def jvmSharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project
 }
 
 // Plain (non-cross) Scala project — used by `monomorphic-cats` and
-// `monofunctor-tagless`, which stay JVM-only.
-def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project = jvmSharedSettings(additionalDeps)(project)
+// `monofunctor-tagless`, which stay JVM-only. These need both
+// `sharedScalaSettings` (scalac flags + macro settings) and the JVM-only
+// extras above.
+def sharedSettings(additionalDeps: Seq[ModuleID])(project: Project): Project =
+  jvmSharedSettings(additionalDeps)(project).settings(sharedScalaSettings)
 
 // for quick experiments with distage snapshots
 ThisBuild / resolvers += Resolver.sonatypeCentralSnapshots

From 99ca69f413f0cf91e61c716fe1487df60971d838 Mon Sep 17 00:00:00 2001
From: Pavel Shirshov <pshirshov@eml.cc>
Date: Wed, 13 May 2026 21:09:23 +0100
Subject: [PATCH 7/7] wip

---
 .github/workflows/build.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 44a0a8f..8aef4df 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: sbt/setup-sbt@v1 # setup sbt
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v5
     - name: Run tests
       run: sbt +test
 
@@ -22,10 +22,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: sbt/setup-sbt@v1
-    - uses: actions/checkout@v2
-    - uses: actions/setup-node@v4
+    - uses: actions/checkout@v5
+    - uses: actions/setup-node@v5
       with:
-        node-version: '22'
+        node-version: '24'
     - name: Link Scala.js bundle into JVM resources
       run: sbt copySimJs
     - name: Smoke-test the simulation bundle via node
@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: sbt/setup-sbt@v1 # setup sbt
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
       - name: Build native app
         run: sbt "project bifunctor-taglessJVM; GraalVMNativeImage/packageBin"
       - name: Check native app