Clean release snapshot

plugins/highway_3d/FREECAM_BRIDGE.md

@@ -0,0 +1,86 @@
+# 3D Highway — Free-Camera Bridge
+
+> 🇬🇧 English · 🇪🇸 Español más abajo
+
+## What this modification does (EN)
+
+This change adds a small, **opt-in** hook inside `camUpdate()` in
+[`screen.js`](./screen.js) that lets an external plugin drive the 3D Highway
+camera (orbit, height, zoom, tilt, pan) **without forking the renderer**.
+
+The renderer reads a single shared object once per frame:
+
+```js
+window.__h3dCamCtl = {
+  enabled,     // master switch — when false the renderer auto-frames as usual
+  heightMul,   // camera height multiplier
+  distMul,     // dolly / zoom multiplier
+  yaw,         // orbit around the look target (radians)
+  pitch,       // tilt offset (highway K-units)
+  panX, panY   // look-target pan (highway K-units)
+};
+```
+
+**Safety / backward compatibility**
+- The bridge object is read **once** (`_freeCam`) and reused for both the
+  position and the look-at transforms.
+- Every field is coerced with `Number.isFinite` to a safe default
+  (`heightMul`/`distMul → 1`, everything else → `0`) before use, so a malformed
+  bridge object can **never** feed `NaN` into `cam.position.set` / `cam.lookAt`.
+- When `window.__h3dCamCtl` is absent or `enabled === false`, behaviour is
+  **byte-for-byte identical** to before: the `if` is skipped and `lookAt` uses
+  the existing `else` path.
+
+The shared `-FOCUS_D * 0.35` look-at Z is computed once (`_lookAtZ`) and reused.
+
+## The plugin that uses this bridge
+
+**Camera Director** — a floating, bilingual (EN/ES) control panel to author,
+save and share highway camera views:
+
+➡️ **https://github.com/nimuart/cameradirector_feedback**
+
+Camera Director creates and writes `window.__h3dCamCtl`; this renderer only
+reads it. That one-object contract is the entire integration surface — no other
+globals, no patching of the renderer's internals.
+
+---
+
+## Qué hace esta modificación (ES)
+
+Este cambio agrega un hook pequeño y **opcional** dentro de `camUpdate()` en
+[`screen.js`](./screen.js) que permite que un plugin externo maneje la cámara del
+3D Highway (órbita, altura, zoom, inclinación, paneo) **sin tener que forkear el
+renderer**.
+
+El renderer lee un único objeto compartido una vez por frame:
+
+```js
+window.__h3dCamCtl = {
+  enabled,     // interruptor maestro — si es false, el renderer encuadra solo
+  heightMul,   // multiplicador de altura
+  distMul,     // multiplicador de dolly / zoom
+  yaw,         // órbita alrededor del objetivo (radianes)
+  pitch,       // inclinación (unidades K del highway)
+  panX, panY   // paneo del objetivo (unidades K del highway)
+};
+```
+
+**Seguridad / compatibilidad**
+- El objeto se lee **una sola vez** (`_freeCam`) y se reutiliza para la posición
+  y para el look-at.
+- Cada campo se valida con `Number.isFinite` y cae a un default seguro
+  (`heightMul`/`distMul → 1`, el resto → `0`), así un objeto mal formado **nunca**
+  mete `NaN` en `cam.position.set` / `cam.lookAt`.
+- Si `window.__h3dCamCtl` no existe o `enabled === false`, el comportamiento es
+  **idéntico** al de antes.
+
+## El plugin que usa este puente
+
+**Camera Director** — panel flotante y bilingüe (EN/ES) para crear, guardar y
+compartir vistas de cámara del highway:
+
+➡️ **https://github.com/nimuart/cameradirector_feedback**
+
+Camera Director crea y escribe `window.__h3dCamCtl`; este renderer solo lo lee.
+Ese contrato de un solo objeto es toda la superficie de integración.