OASIS_MOBILE/GUIA_DE_DESARROLLO.md

Guía de desarrollo de OASIS_MOBILE

Léela antes de tocar nada. Esta rama vive encima de Oasis, que desarrolla epsylon (el dev) y que saca una versión casi cada día. Todo lo que añadimos tiene que sobrevivir a la siguiente versión sin reescribirlo. Esta guía dice qué se puede tocar, qué no y cómo hacer cada tipo de cambio.

Las cifras y el razonamiento están en docs/FRONTERA_UPSTREAM.md. Aquí solo van las reglas.

---

1. La regla de oro

Oasis lo cambia el dev. Nosotros cambiamos cómo se ve en el móvil.

Lo que la rama añade va en ficheros nuestros. En un fichero del dev, como mucho, una línea que llama a un fichero nuestro, y solo en el móvil.

¿Por qué? Entre la 1.0.1 y la 1.3.3 (siete semanas) el dev publicó 39 versiones, cada una en un único commit. backend.js cambió en 34 de ellas, main_views.js en 31, las traducciones en 31. Cada línea nuestra en esos ficheros es un conflicto casi seguro en la próxima integración. Y si tocamos cómo se publica o se cuenta algo en la red, nuestro móvil deja de entenderse con los demás nodos.

---

2. El semáforo

ROJO: no se toca

Qué	Dónde	Por qué
El backend del dev	src/backend/backend.js	Cambia en 34/39 versiones. Rutas, middleware, todo.
La cadena de middleware	el array middleware al final de backend.js	Crece en cada versión (contexto por petición, idioma, CSP...).
Los modelos del dev	src/models/* salvo los nuestros (ver verde)	Definen qué se publica en el log SSB y cómo se cuenta. Cambiarlos rompe la red.
El arranque de SSB	src/server/* (SSB_server.js, ssb_config.js, package.json)	Dependencias y conexión con la red.
La política de seguridad	src/backend/request_guards.js	La CSP: sin style="" ni <script> en línea. Así se queda.
Las traducciones del dev	src/client/assets/translations/oasis_*.js	Se reescriben en 31/39 versiones.
Las hojas del dev	styles/style.css, styles/mobile.css	Cambian en 32/39 y 10/39.
Los temas del dev	themes/Dark-SNH.css, Clear-SNH.css, Purple-SNH.css, Matrix-SNH.css, OasisMobile.css	OasisMobile.css es del dev (21/39), no nuestro.

Ejemplos de lo que no se hace:

• Cambiar una regla de un modelo, aunque parezca mala. "Quien crea una votación no vota" está en votes_model.js: se explica en pantalla, no se cambia.
• Añadir una ruta o un middleware a backend.js.
• Envolver o reescribir una función del backend (checkMod, getConfig...).
• Editar oasis_es.js para cambiar un texto.
• Meter estilos en línea o <script> en una vista.

ÁMBAR: una línea de enganche y nada más

Las vistas del dev (src/views/*_view.js, main_views.js). Se reescriben a menudo (tribes_view.js en 23/39, main_views.js en 31/39), así que:

• La lógica va en src/views/mobile_ui.js (o en otro mobile_*.js nuestro).
• En la vista del dev queda una llamada, siempre detrás de la bandera:

// en tribes_view.js (del dev)
const mobileUi = require('./mobile_ui');
...
if (mobileUi.isMobile()) return mobileUi.tribeTabs(tribe, section, sections);

• Si el dev reescribe la vista, se vuelve a poner esa línea. No hay que reconstruir una función entera.
• En escritorio (sin OASIS_MOBILE) la vista del dev funciona igual que en el original.

Enganches que hay hoy: main_views.js (6), tribes_view.js (6), vote_view.js (4), settings_view.js (3), welcome_view.js (3). Para encontrarlos: grep -n mobileUi src/views/*.js.

VERDE: nuestro, se toca libremente

Para qué	Fichero
Aspecto de los dos skins de móvil (márgenes, letra, botones, piezas nuevas)	src/client/assets/styles/mobile_ux.css
Colores y formas del skin Acampada	src/client/assets/themes/Acampada.css, styles/hive_acampada.css
Estilos de Karvan	styles/karvan.css
Piezas de interfaz que se enchufan en vistas del dev	src/views/mobile_ui.js
Pantallas enteras propias	src/views/mobile_modules_view.js, karvan_view.js, identities_view.js
Lanzador, barra de abajo, barra de arriba	src/views/hive_views.js
Iconos	src/views/mobile_icons.js
Rutas propias y retoques a respuestas del dev	src/backend/karvan_routes.js (el router propio)
Workflows propios	src/models/fork_workflows.js
Modelos propios	src/models/karvan_model.js
JavaScript de cliente propio	src/client/public/js/karvan.js
Textos nuevos	src/client/assets/translations/i18n_fork.js
Imágenes propias	src/client/assets/images/ux-*.svg
La app Android	android/

---

3. Cómo se hace cada cosa

Cambiar cómo se ve algo

1. Busca la clase en el HTML (servidor local + inspector, ver sección 6).
2. Escribe la regla en mobile_ux.css. Los colores, siempre con los tokens --ux-* (--ux-bg, --ux-fg, --ux-accent, --ux-muted, --ux-line, --ux-danger...): así sale bien en Acampada y en OasisMobile.
3. Si no gana: mobile.css y Acampada.css usan !important y selectores largos. Sube la especificidad (.main-column div.x, label.x input.y[type="checkbox"]) y pon !important. Ojo: Acampada.css quita el borde a todos los div; para ponerle borde a uno, .main-column div.mi-clase.
4. Letra: Anton solo en títulos y en el botón principal negro (.create-button). Todo lo demás, en la letra del sistema en negrita.
5. Márgenes: uno solo, de 14 px a cada lado. No añadas rellenos a contenedores intermedios.

Cambiar el HTML de una pantalla del dev

1. Función nueva en mobile_ui.js, que reciba lo que necesite como parámetro.
2. Una línea en la vista del dev: mobileUi.isMobile() ? mobileUi.miPieza(...) : lo_de_antes.
3. Los textos, por i18n (ver "Textos").

Una pantalla entera nueva, o una ruta nueva

En el router propio, src/backend/karvan_routes.js. Va justo antes del router del dev en la cadena: lo que no atiende pasa al del dev con next().

.get('/modules', async (ctx, next) => {
  if (!isMobile()) return next();          // en escritorio, la del dev
  ctx.body = mobileModulesView({ ... });   // en el movil, la nuestra
})

Retocar lo que responde el dev, sin editarlo

El envoltorio wrapUpstream de karvan_routes.js deja actuar al dev y después mira la respuesta. Así se sabe a qué sección apagada se quería entrar (el dev solo redirige a /modules) o se añade ?saved=1 tras guardar. Este es el sitio para eso, nunca backend.js.

Textos

• Siempre en i18n_fork.js, en los 11 idiomas (en, es, fr, eu, de, it, pt, zh, ar, hi, ru).
• Comprueba que la clave no existe ya en oasis_en.js: si existe, se pisaría también en escritorio.
• En el código, siempre con texto de reserva en inglés: i18n.miClave || 'My text'.

Un workflow nuevo

En fork_workflows.js. Se registra empujándolo a los arrays que exporta el modelo del dev. No se edita workflows_model.js ni se redefine un workflow del dev.

Un icono

En mobile_icons.js: trazo de 2 px en rejilla de 24, currentColor. La clave es la ruta (/tribes → tribes).

Algo que solo pasa en el móvil

Siempre detrás de process.env.OASIS_MOBILE === '1' (o mobileUi.isMobile()). main.js la pone; el escritorio no la tiene.

---

4. Antes de cada commit

• git diff --stat no toca nada rojo. Si toca una vista del dev, son líneas de enganche, no funciones.
• node --check en cada .js cambiado.
• El servidor local arranca y responde 200 en /activity, /tribes, /modules, /settings, /votes, /karvan, /inbox.
• Mirado a 412 px de ancho (y a 360 si es una pieza ancha).
• Textos nuevos en los 11 idiomas.
• Nada en línea (style="", <script>): la CSP lo bloquea.
• Commit en castellano, sin rastro de herramientas ni coautorías automáticas.
• Ninguna clave, contraseña ni .ssb en el commit.

---

5. Cuando sale una versión nueva del dev

1. Coge su código tal cual para todo lo rojo.
2. En las vistas del dev, vuelve a poner los enganches (grep -n mobileUi en la versión anterior de la rama te dice dónde estaban).
3. Repite la medición de docs/FRONTERA_UPSTREAM.md: qué ficheros ha tocado y si ha desaparecido alguna clase de la que tiran nuestras hojas.
4. Revisa a 412 px las pantallas de la sección 4.
5. Compila la APK con la oficial de esa misma versión como base (android/scripts/release.sh, variable OASIS_APK_BASE).

---

6. Cómo probar

Servidor local (con una identidad de usar y tirar y la red en pausa):

HOME=/tmp/oasis-prueba OASIS_NETWORK_PAUSED=1 node main.js
# http://localhost:3000, con el inspector del navegador en modo movil, 412x915

• src/server/node_modules no está en git: hace falta uno (el de la APK base vale).
• Si al reiniciar sale "Another Oasis instance is already running", el anterior sigue vivo y estás viendo código viejo: mátalo antes.
• Al arrancar se borran src/configs/banking-eco-history.json y fediverse-accounts.json: git checkout -- src/configs/ antes de hacer commit.

En el emulador (Android Studio, Pixel_9_API_36): la APK de depuración deja inspeccionar la WebView con chrome://inspect o con adb forward tcp:9333 localabstract:webview_devtools_remote_<pid>.

---

7. Deuda que queda (por orden)

Cosas de antes de esta guía que todavía la incumplen. Ver la sección 5 de docs/FRONTERA_UPSTREAM.md.

1. OasisMobile.css difiere en 4.873 líneas de la del dev. Hay que devolverle la suya y llevar nuestra maqueta a una hoja propia.
2. 21 trozos antiguos en backend.js (14 con la bandera de móvil): exportar copia de seguridad, avatar de la barra de arriba, vídeos, filtro del lanzador... Pasan al router propio.
3. El workflow "activists" sigue redefinido en workflows_model.js: devolver el del dev (ya existe el nuestro, "acampada").
4. Selectores muertos en OasisMobile.css (61), hive_acampada.css (29) y Acampada.css (5).