preview sidecar: serve bundles through the preview server itself (single origin, sidecar as implementation detail)

[dalkia]

(Filed here because js-sdk-toolchain has issues disabled; the primary change is in sdk-commands, with a small unity-explorer follow-up.)

Context

decentraland/js-sdk-toolchain#1498 runs the abgen sidecar on its own port and hands clients its URL via the optimized-assets-url deeplink param. That two-origin model works (verified end-to-end with decentraland/unity-explorer#9459 and decentraland/creator-hub#1396), but it leaks the sidecar's existence into every consumer:

• The port must be discovered: launched clients get it from the deeplink, but the Unity Editor has no deeplink — it relies on a default (127.0.0.1:5147) matching the sidecar's preferred port (js-sdk-toolchain 3eb79143), and needs manual configuration whenever the port differs.
• Two origins to reason about in every client, doc, and test.
• Concurrent previews each expose another ad-hoc port.

Proposal

Mount the sidecar behind the preview server as a thin streaming reverse proxy:

GET  {realm}/optimized-assets/manifest/{id}_{platform}.json  →  sidecar
GET  {realm}/optimized-assets/v49/{id}/{bundle}              →  sidecar

The client then only ever knows one origin — the realm it already has. With local-ab=true set, the explorer can derive the assets base from the realm URL ({realm}/optimized-assets), making optimized-assets-url redundant for the preview flow (it stays as a generic override). The sidecar port becomes fully private to sdk-commands.

What it buys

• Zero configuration structurally, not by port convention: editor, launched clients, and Creator Hub all just work off the realm.
• The getPort(5147) preference and the deeplink param both become unnecessary (graceful migration: keep emitting the param until the explorer derives the base).
• Concurrent previews naturally scoped — each preview server proxies to its own sidecar.

What it needs

• sdk-commands: a streaming proxy route (/optimized-assets/* → sidecar) in the preview server router; sidecar port moves back to getPort(0).
• unity-explorer (follow-up to feat: load local asset bundles in local scene development (local-ab) unity-explorer#9459): when local-ab is set and no explicit optimized-assets-url is given, derive the assets base from the realm instead of defaulting to 127.0.0.1:5147. One thing to verify: the asset-bundle base URL has historically been a bare host, so the URL-building code must handle a base carrying a path prefix.
• Bundle bytes take a second localhost hop (client → preview server → sidecar) — negligible.
• abgen: nothing — it already binds 127.0.0.1 and is env-configured; this only changes who fronts it.

Migration path

1. Ship the proxy route; keep optimized-assets-url pointing at the proxied path — no client change required.
2. Explorer learns to derive the base from the realm under local-ab.
3. The deeplink param and the preferred-port convention quietly retire.

Follow-up to js-sdk-toolchain#1498 — not a blocker for it.

🤖 Generated with Claude Code

[dalkia]

Done at decentraland/js-sdk-toolchain#1504