wiki: dos paginas nuevas y portada al dia

Estructura del codigo, con la tabla de ficheros propios y por que cada uno
esta donde esta.

Si algo va mal: iconos sin fuente, dependencias en src/server, levantar una
segunda instancia para probar llamadas, Karvan apagado en modulos, el CSS con
comentarios sin cerrar, el tema claro, la llamada que no conecta y el aviso de
no publicar desde dos sitios con la misma clave.

Estructura.md

@@ -0,0 +1,103 @@
+# Cómo está organizado el código
+
+> ⚠ Rama experimental, no oficial. El Oasis oficial es
+> https://github.com/epsylon/oasis · [Volver a la portada](Home)
+
+Esta rama tiene que hacer dos cosas a la vez: añadir funciones y **seguir el ritmo de
+epsylon**, que publica una versión cada pocos días. Lo segundo solo sale bien si el
+código propio se distingue del suyo y no le estorba.
+
+---
+
+## La regla
+
+**Upstream no usa ni un solo subdirectorio** en `src/views`, `src/backend`,
+`src/models`, `src/client/assets/styles` ni `src/client/assets/translations`: 66 vistas
+y 67 modelos, todos planos. La rama sigue esa misma forma, y los mismos nombres:
+`*_model.js` para modelos, `*_view.js` para vistas, `*_views.js` cuando son varias.
+
+## Los ficheros propios
+
+| Fichero | Qué es | A qué se parece en upstream |
+|---|---|---|
+| `src/models/karvan_model.js` | Las salas efímeras y su ciclo de vida | `polls_model.js` |
+| `src/views/karvan_view.js` | La lista de salas y la sala | `chats_view.js` |
+| `src/backend/karvan_routes.js` | Las rutas del módulo | — (ver abajo) |
+| `src/client/public/js/karvan.js` | El cliente WebRTC del navegador | `pdf-viewer.js` |
+| `src/client/assets/styles/karvan.css` | Los estilos del módulo | `highlight.css` |
+| `src/views/identities_view.js` | El selector de identidades | cualquier `*_view.js` |
+| `src/backend/accounts.js` | Encontrar y elegir identidades | `nameCache.js` |
+| `src/backend/turnCredentials.js` | Credenciales efímeras para TURN | `wallet_addresses.js` |
+| `src/client/assets/translations/i18n_fork.js` | Los textos de la rama | junto a `i18n.js` |
+| `src/views/hive_views.js` | La interfaz de móvil | `main_views.js` |
+
+Ese último está aquí **sin dibujar nada**: sus funciones empiezan con
+`if (process.env.OASIS_MOBILE !== '1') return "";`. Vive en los dos repositorios para
+que `main_views.js` sea idéntico y las actualizaciones de upstream se apliquen una sola
+vez. Ver [Diferencias con la versión de móvil](Diferencias).
+
+## Y lo que se toca de lo suyo
+
+**Enganches de una línea**, casi siempre:
+
+```js
+// main_views.js
+renderKarvanLink()          // calcado de renderPollsLink()
+```
+
+## Las tres decisiones que no son obvias
+
+### Por qué las rutas van aparte
+
+Upstream mete **625 rutas** en `backend.js`, en una sola cadena. Ese fichero se
+reescribe en cada versión: `+833/-286` líneas en la 0.9.2, `+266/-31` en la 0.9.1. Una
+ruta añadida en medio entra en conflicto **cada vez**.
+
+Las del módulo viven en `karvan_routes.js`, montadas en un router propio que se inserta
+antes del de upstream: lo que no casa cae a `next()` y sigue su curso. Es la única
+pieza que no imita a una existente, y por un motivo medible.
+
+### Por qué las traducciones son un overlay
+
+Upstream tiene once ficheros `oasis_XX.js` y **los reescribe enteros** en cada versión.
+`i18n_fork.js` lleva las claves de la rama aparte, y `i18n.js` las mezcla con tres
+líneas. Dentro va solo lo propio: los nombres de las categorías no están, porque son
+los de epsylon.
+
+### Por qué Karvan trae su propia hoja de estilos
+
+Igual que `highlight.css` en upstream: define la forma —las burbujas, los botones
+redondos de llamada, la rejilla de vídeo— y no los colores de la interfaz, que los pone
+el tema. Ver [Temas](Temas).
+
+---
+
+## Lo que se ha quitado por sobrar
+
+| Qué | Por qué sobraba |
+|---|---|
+| `views/fork/` y `translations/fork/` | Subdirectorios propios; upstream no tiene ninguno |
+| Una segunda ruta `/legacy/export` | Copia exacta de la del dev, en otro fichero |
+| `media-favorites.js` y su JSON | De una versión anterior; nadie lo requería |
+| El campo `subtopic` en el foro | Resto de unos subtemas propios que se descartaron |
+
+---
+
+## Cómo comprobarlo
+
+Contra un clon de upstream de la misma versión:
+
+```sh
+# ficheros propios de la rama
+for d in src/backend src/models src/views; do
+  diff <(ls ../oasis/$d) <(ls $d) | grep '^>'
+done
+
+# subdirectorios que upstream no tiene (no debería salir ninguno)
+find src/views src/backend src/models -maxdepth 1 -type d | tail -n +2
+
+# líneas añadidas sobre cada fichero suyo
+for f in $(git ls-files 'src/**/*.js'); do
+  [ -f ../oasis/$f ] && n=$(diff ../oasis/$f $f | grep -c '^>') && [ $n -gt 0 ] && echo "$n $f"
+done | sort -rn
+```

Home.md

@@ -27,7 +27,7 @@ Dos cosas, y ninguna cambia la interfaz que ya conoces:
 El resto es Oasis 0.9.5 tal cual: el menú lateral por grupos del proyecto original, no
 la rejilla de hexágonos, que es de la versión para móvil.
 
-![Oasis de escritorio](img/08-portada.png)
+![Oasis de escritorio](img/11-portada.png)
 
 | Página | De qué va |
 |---|---|
@@ -37,6 +37,8 @@ la rejilla de hexágonos, que es de la versión para móvil.
 | **[Chats](Chats)** | Los chats cifrados, con respuesta citada |
 | **[Temas](Temas)** | Cómo se ve el módulo con los cuatro temas |
 | **[Diferencias con la versión de móvil](Diferencias)** | Qué cambia y por qué |
+| **[Estructura del código](Estructura)** | Dónde vive cada fichero y por qué ahí |
+| **[Si algo va mal](Problemas)** | Los fallos que han pasado de verdad, y su arreglo |
 | **[Estado](Roadmap)** | Qué funciona y qué no |
 
 Todas las capturas de esta wiki están tomadas de esta rama funcionando en un navegador

Problemas.md

@@ -0,0 +1,109 @@
+# Si algo va mal
+
+> ⚠ Rama experimental, no oficial. El Oasis oficial es
+> https://github.com/epsylon/oasis · [Volver a la portada](Home)
+
+Todo lo de esta página ha pasado de verdad durante el desarrollo.
+
+---
+
+## Los iconos se ven como cuadros vacíos (□)
+
+![Iconos sin fuente](img/03-menu-lateral.png)
+
+**No es un fallo de Oasis.** Usa caracteres Unicode poco comunes para los iconos del
+menú y a tu sistema le falta una fuente que los cubra. En la captura se ven así los del
+menú lateral, menos el reloj de arena de Karvan.
+
+```sh
+sudo apt install fonts-noto-core     # Debian, Ubuntu y derivadas
+```
+
+No afecta a nada más que a cómo se ve.
+
+## No arranca: falta hyperaxe o algún módulo
+
+```
+Cannot find module '../../server/node_modules/hyperaxe'
+```
+
+Faltan las dependencias. Se instalan **dentro de `src/server`**, no en la raíz:
+
+```sh
+cd src/server && npm install
+```
+
+## Arranca pero el puerto está ocupado
+
+Si ya tienes un Oasis corriendo, el segundo no puede coger el mismo puerto web ni el de
+SSB. Para levantar una segunda instancia —útil para probar llamadas entre dos
+identidades—:
+
+```sh
+OASIS_ACCOUNT=pruebas ./oasis.sh gui --host=127.0.0.1 --port=3011 --no-open -- --port=8009
+```
+
+Lo que va detrás de `--` se le pasa a la configuración de SSB; ahí es donde se cambia
+el puerto del protocolo.
+
+## Karvan no aparece en el menú
+
+Míralo en `/modules`: está entre **Jobs** y **L.A.R.P.**. Si su casilla está
+desmarcada, el módulo está apagado y su ruta devuelve un error.
+
+![Karvan en la pantalla de módulos](img/07-modules.png)
+
+## El panel de llamada se ve descuadrado
+
+Ya no debería. Hubo un fallo real: un comentario sin cerrar en `karvan.css` anulaba
+todo el bloque de la videollamada, y el resultado eran dos cajas vacías enormes y unos
+botones cuadrados. Está arreglado.
+
+Si te pasa algo parecido tras tocar el CSS, comprueba que no has dejado un comentario
+abierto:
+
+```sh
+python3 -c "
+import re;s=open('src/client/assets/styles/karvan.css').read()
+st=re.sub(r'/\*.*?\*/','',s,flags=re.S)
+assert '/*' not in st, 'comentario sin cerrar'
+assert st.count('{')==st.count('}'), 'llaves descuadradas'
+print('ok')"
+```
+
+## Con el tema claro, las burbujas se ven raras
+
+**Clear-SNH** usa `!important` en casi todas sus reglas, así que gana sobre cualquier
+hoja posterior. Por eso ese tema trae su propio bloque para Karvan, que lo traduce a la
+paleta clara. Si añades un tema con `!important`, tendrás que hacer lo mismo. La lista
+de clases a cubrir está en [Temas](Temas).
+
+## La llamada no conecta
+
+Comprueba, por este orden:
+
+1. **Que el indicador está en verde.** Si dice *server relay* con el punto gris, los
+   dos navegadores todavía no se han encontrado.
+2. **Que hay otro participante de verdad.** Con uno solo, se enciende tu cámara y poco
+   más.
+3. **Si estáis en redes distintas**, hace falta un TURN. De fábrica no hay ninguno —a
+   propósito, para no filtrar la IP a un tercero—. Ver [Llamadas](Llamadas).
+
+En la misma red local debería conectar sin nada más.
+
+## Cambié de identidad y sigo viendo la anterior
+
+El cambio **se aplica al reiniciar**. Cierra Oasis y vuelve a arrancarlo. La variable
+`OASIS_ACCOUNT` manda sobre lo que diga el selector, así que si arrancas con ella,
+ignorará tu elección. Ver [Instalar](Instalar).
+
+## Aviso serio: no publiques desde dos sitios con la misma identidad
+
+Si el selector marca en rojo **"Comparte clave con otra identidad"**, esas dos carpetas
+tienen el mismo `secret`.
+
+Un registro de SSB es una cadena firmada y numerada. Si dos sitios publican el número
+500 con contenidos distintos, la red ve una bifurcación, deja de replicar el feed y
+**eso no se arregla**: se pierde la identidad.
+
+Tener la copia no hace daño. Publicar desde las dos, sí.

_Sidebar.md

@@ -15,6 +15,8 @@
 ---
 
 - [Diferencias con móvil](Diferencias)
+- [Estructura del código](Estructura)
+- [Si algo va mal](Problemas)
 - [Estado](Roadmap)
 
 ---