@dotrino/lobby 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seyacat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @dotrino/lobby
+
+**Lobby + matchmaking reciclable para cualquier juego del ecosistema Dotrino.**
+
+Resuelve, una sola vez y para todos los juegos, lo que el ajedrez, el chat y
+compañía venían reimplementando a mano: **descubrir/crear/unir salas, asientos,
+espectadores, autoridad de host (serverless), presencia, pausa/reconexión por
+identidad, sincronización autoritativa con resync, verificación del oponente,
+matchmaking filtrado por reputación y recibo de partida co-firmado.**
+
+Está construido **sobre** los pilares compartidos — no reimplementa transporte ni
+identidad:
+
+- `@dotrino/proxy-client` — transporte (canales, `identify`,
+  `send`/`sendByPubkey`, WebRTC). **Una sola conexión**, reutilizable.
+- `@dotrino/identity` — vault (firma, challenge/response,
+  **contactos**).
+- `@dotrino/reputation` — web-of-trust (gate de admisión,
+  ranking, atestaciones `txBound`). *Opcional.*
+
+Headless y framework-agnóstico (vanilla + EventEmitter). Sirve igual para Vue,
+vanilla o nativo-vía-WebView.
+
+---
+
+## Idea central
+
+El **host es uno de los jugadores** (no hay servidor central: *tu info, en tu
+máquina*). La librería separa dos cosas:
+
+1. **Lobby/Room** — toda la fontanería de salas/asientos/presencia/sync.
+2. **Motor de turnos** *(opcional)* — el juego aporta **funciones puras**
+   (`initialState`, `reducer`, `view`, `isOver`) y la lib valida en el host,
+   sincroniza y hace resync. El ajedrez queda casi trivial; las cartas funcionan
+   gracias a `view` (estado oculto por asiento) y al azar determinista sembrado.
+
+---
+
+## Instalación
+
+```bash
+npm i @dotrino/lobby \
+      @dotrino/proxy-client \
+      @dotrino/identity \
+      @dotrino/reputation
+```
+
+---
+
+## Quick start
+
+```js
+import { createLobby } from '@dotrino/lobby'
+
+// 1) Definí tu juego como funciones puras (ejemplo: "tres en raya")
+const tictactoe = {
+  initialState: { board: Array(9).fill(null), turn: 'x' },
+  reducer (state, action, ctx) {            // ctx = { seat, seats, rng, now }
+    const mark = ctx.seat === 'x' ? 'x' : 'o'
+    if (state.turn !== mark) throw new Error('no-es-tu-turno')
+    if (state.board[action.cell]) throw new Error('ocupada')
+    const board = state.board.slice()
+    board[action.cell] = mark
+    return { board, turn: mark === 'x' ? 'o' : 'x' }
+  },
+  isOver (state) {
+    const L = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]]
+    for (const [a,b,c] of L) {
+      const v = state.board[a]
+      if (v && v === state.board[b] && v === state.board[c]) return { winner: v, reason: 'line' }
+    }
+    if (state.board.every(Boolean)) return { winner: null, reason: 'draw' }
+    return null
+  }
+}
+
+// 2) Creá el lobby (conecta e identifica con el vault solo)
+const lobby = await createLobby({
+  gameId: 'tictactoe',
+  seats: ['x', 'o'],
+  engine: tictactoe,
+  start: 'ready',                 // arranca cuando ambos asientos están "listos"
+  onSeatVacated: 'pause',         // si alguien se va: pausa + reconexión por pubkey
+  matchmaking: { minReputation: 0.15, preferContacts: true }
+})
+
+// 3) Partida rápida
+const room = await lobby.quickMatch({ autoSeat: true })
+
+room.on('update', s => render(s))                 // s.seats, s.status, s.spectators
+room.on('state',  game => renderBoard(game.board))// vista del juego para MI asiento
+room.on('ended',  r => alert(`Ganó ${r.winner}`))
+
+// 4) Jugar
+boardEl.onclick = cell => room.action({ cell })
+```
+
+Crear/listar/unir manualmente:
+
+```js
+const room  = await lobby.createRoom({ name: 'Mi sala' })   // sos host
+const rooms = await lobby.listRooms()                       // [{ roomId, name, openSeats, hostScore, isContact, ... }]
+const room2 = await lobby.joinRoom(rooms[0].roomId)         // sos guest
+```
+
+---
+
+## Asientos, espectadores y ciclo de vida
+
+```js
+room.takeSeat('x')     // tomar un asiento LIBRE (sin id → el primero libre)
+room.setReady(true)    // start:'ready' arranca cuando todos los ocupados están listos
+room.leaveSeat()       // volver a espectador
+room.spectate()        // mirar sin jugar (recibe el estado, no puede actuar)
+room.mySeat            // 'x' | 'o' | null
+```
+
+- **Sólo se toman asientos libres.** Para cambiar, el ocupante deja el suyo primero.
+- **Espectadores**: reciben todos los `state`/`event`; sus `action()` se rechazan.
+  Un espectador puede `takeSeat()` si hay un asiento libre (así "otro toma el
+  lugar"). Con `onSeatVacated:'fill'`, la cola de espectadores rellena automático.
+- **Estados**: `waiting → playing → ended`, con `paused` intermedio.
+
+### ¿Qué pasa si un jugador se va / se cae?
+
+Configurable con `onSeatVacated` (y el asiento va por **pubkey del vault**, no por
+token efímero):
+
+| Política | Comportamiento |
+|---|---|
+| `'pause'` *(default)* | La partida se pausa; el mismo jugador **recupera su asiento** al reconectar (dentro de `disconnectGraceMs`). Si vence el grace, el asiento se libera. |
+| `'forfeit'` | Irse/caerse termina la partida a favor del resto (ranked). |
+| `'fill'` | El asiento se libera y el primer espectador en cola lo toma; la partida sigue (drop-in/drop-out). |
+
+---
+
+## Motor de turnos (autoritativo)
+
+El host instancia el motor; los guests sólo reflejan la **vista** que reciben.
+
+```js
+const engine = {
+  initialState,                 // valor | (rng) => estado   (rng determinista, sembrado)
+  reducer (state, action, ctx), // ctx = { seat, seats, rng, now }; throw Error(reason) para rechazar
+  view (state, seat),           // opcional: proyección por asiento (info oculta). Default: estado completo
+  isOver (state)                // opcional: { winner, reason } | null
+}
+```
+
+- **Cartas / info oculta**: usá `view(state, seat)` para devolver sólo lo que ese
+  asiento puede ver (su mano). Los espectadores reciben `view(state, null)`.
+- **Azar (barajar, dados)**: usá `ctx.rng()` (y el `rng` de `initialState`). Es
+  determinista por semilla → reproducible y registrable en el recibo.
+- **Sin motor**: si no pasás `engine`, la sala funciona en **modo relay**:
+  `room.send(data)` / `room.on('message')` y el juego sincroniza su propio estado.
+
+---
+
+## Reputación + contactos
+
+Atraviesa todo el flujo (inyectá `reputation` para activarlo):
+
+```js
+// Gate de admisión (bidireccional): el host rechaza joiners y el lobby filtra salas.
+matchmaking: { requireVouched: true, minReputation: 0.2, preferContacts: true }
+
+// Invitar a un contacto (cola offline 24 h):
+lobby.inviteContact(pubkey, { roomId: room.roomId, name: 'Revancha?' })
+lobby.on('invite', inv => console.log('te invitaron a', inv.roomId))
+
+// Verificación anti-impersonación: al sentarse se hace challenge/response.
+// (requireVerify: true por defecto)
+
+// Post-partida: calificar y agregar a contactos, con recibo co-firmado → txBound.
+await room.ratePlayer(oppPubkey, { confianza: 5, afinidad: 3 }, { notes: 'gg' })
+```
+
+### Recibo de partida co-firmado
+
+Al terminar, el host y cada co-jugador **co-firman** un recibo
+`{ a, b, ts, sigA, sigB }` (cada uno firma `{op:'receipt',a,b,ts}` con su vault).
+`ratePlayer` lo adjunta automáticamente, produciendo una atestación **`txBound`**:
+prueba verificable de que *esos dos realmente jugaron juntos* (anti-sybil).
+
+```js
+room.on('receipt', ({ pubkey, receipt }) => { /* guardado para el rating */ })
+room.matchReceipt(pubkey) // { a, b, ts, sigA, sigB } | null
+```
+
+---
+
+## Eventos de `Room`
+
+| Evento | Payload | Cuándo |
+|---|---|---|
+| `update` | `RoomState` | cambió asientos/estado/espectadores |
+| `state` | `game` | cambió la vista de juego para mi asiento |
+| `started` | `{ ts }` | arrancó la partida |
+| `ended` | `{ winner, reason }` | terminó |
+| `event` | `{ event, data }` | evento lateral genérico |
+| `chat` | `{ from, name, text, ts }` | mensaje de chat |
+| `message` | `data` | relay opaco (modo sin motor) |
+| `rejected` | `{ reason }` | tu acción fue rechazada |
+| `kicked` | `{ reason }` | el host te expulsó (verify/reputación) |
+| `closed` | `{ reason }` | el host cerró / se perdió |
+| `receipt` | `{ pubkey, receipt }` | recibo co-firmado listo |
+| `left` | — | saliste de la sala (`room.leave()`) |
+
+---
+
+## API
+
+```ts
+createLobby(opts): Promise<Lobby>
+
+Lobby.createRoom(opts?): Promise<Room>
+Lobby.joinRoom(roomId, opts?): Promise<Room>
+Lobby.listRooms(opts?): Promise<RoomSummary[]>
+Lobby.quickMatch(opts?): Promise<Room>
+Lobby.inviteContact(pubkey, { roomId, name }): void
+Lobby.listContacts(): Promise<PeerInfo[]>
+Lobby.reputationOf(pubkey): Promise<AggregateResult>
+
+Room.takeSeat(seat?) / leaveSeat() / setReady(b) / spectate()
+Room.action(a) / chat(text) / send(data) / start()
+Room.ratePlayer(pubkey, indicators, opts?) / matchReceipt(pubkey)
+Room.mySeat / status / seats / spectators / game / result / state
+Room.leave()
+```
+
+Ver tipos completos en [`src/index.d.ts`](./src/index.d.ts).
+
+---
+
+## Notas de diseño / límites de v1
+
+- `roomId === token del host` (modelo probado por el ajedrez). Si el host
+  **reconecta**, su token cambia → la sala se considera nueva y los guests caen
+  (`onHostLost: 'end'`). La **migración de host** (elección determinista del
+  jugador de menor pubkey) está prevista como `onHostLost: 'migrate'` y queda como
+  extensión futura.
+- El recibo co-firmado se genera para los pares **host ↔ cada jugador** (cubre 1v1
+  completo, p.ej. ajedrez). Recibos entre guests en mesas de N>2 quedan pendientes.
+- Sincronización por **snapshot completo personalizado** por cambio (simple y
+  correcto para juegos por turnos). Deltas/patches son una optimización futura.
+
+## Tests
+
+```bash
+npm test    # node --test
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dotrino/lobby",
+  "version": "0.1.5",
+  "description": "Lobby + matchmaking reciclable para juegos del ecosistema Dotrino: salas, asientos, espectadores, motor de turnos autoritativo, reputación y contactos sobre el proxy/identity/reputation compartidos",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "lobby",
+    "matchmaking",
+    "game",
+    "turn-based",
+    "p2p",
+    "webrtc",
+    "dotrino",
+    "web-of-trust"
+  ],
+  "peerDependencies": {
+    "@dotrino/proxy-client": ">=0.1.0",
+    "@dotrino/identity": ">=0.5.0",
+    "@dotrino/reputation": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@dotrino/reputation": { "optional": true }
+  },
+  "author": "seyacat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imdotrino/dotrino-lobby.git"
+  }
+}

package/src/engine.js

@@ -0,0 +1,96 @@
+// Motor de turnos autoritativo (lado host).
+//
+// El juego aporta funciones puras y el motor se encarga de: mantener el estado
+// autoritativo, validar/aplicar acciones, proyectar vistas por asiento (para
+// info oculta como la mano de cartas), azar determinista sembrado y detección
+// de fin de partida. Sólo se instancia en el host; los guests sólo guardan la
+// vista que reciben.
+//
+// spec = {
+//   initialState: value | (rng) => state,
+//   reducer: (state, action, ctx) => newState   // ctx = { seat, seats, rng, now }; throw para rechazar
+//   view?:   (state, seat) => stateVisibleParaEseAsiento   // default: estado completo
+//   isOver?: (state) => ({ winner, reason }) | falsy
+// }
+
+import { mulberry32, hashSeed, clone, clock } from './util.js'
+
+export function createEngine (spec = {}) {
+  if (typeof spec.reducer !== 'function') {
+    throw new Error('[lobby] engine: spec.reducer es obligatorio')
+  }
+  const viewFn = typeof spec.view === 'function' ? spec.view : null
+  const isOverFn = typeof spec.isOver === 'function' ? spec.isOver : () => null
+
+  let state = null
+  let rng = null
+  let seed = null
+  let started = false
+
+  function makeInitial () {
+    const init = spec.initialState
+    if (typeof init === 'function') return init(rng)
+    if (init === undefined) return {}
+    return clone(init)
+  }
+
+  return {
+    /** ¿Ya arrancó la partida? */
+    get started () { return started },
+    /** Semilla usada (para recibos / reproducibilidad). */
+    get seed () { return seed },
+
+    /**
+     * Arranca (o reinicia) la partida con una semilla determinista.
+     * @param {number|string} [seedValue] si se omite, se deriva del reloj.
+     */
+    start (seedValue) {
+      seed = seedValue == null ? (clock.now() >>> 0) : seedValue
+      rng = mulberry32(typeof seed === 'number' ? seed : hashSeed(seed))
+      state = makeInitial()
+      started = true
+      return state
+    },
+
+    /**
+     * Aplica una acción de un asiento. Lanza Error(reason) si el reducer rechaza.
+     * @param {string} seat  id del asiento que actúa
+     * @param {any} action
+     * @param {object} seatsSnapshot  ocupación de asientos para contexto del reducer
+     * @returns {any} el nuevo estado autoritativo
+     */
+    apply (seat, action, seatsSnapshot) {
+      if (!started) throw new Error('game-not-started')
+      const ctx = { seat, seats: seatsSnapshot || {}, rng: rng || Math.random, now: clock.now() }
+      const next = spec.reducer(state, action, ctx)
+      if (next === undefined) throw new Error('reducer-returned-undefined')
+      state = next
+      return state
+    },
+
+    /** Estado autoritativo completo (host). */
+    getState () { return state },
+
+    /** Carga un estado completo (resync/persistencia). */
+    load (s) { state = s; started = true },
+
+    /** Proyección visible para un asiento (o null = espectador / vista pública).
+     *  Una view() del juego que lanza no debe tumbar la difusión: degradamos a
+     *  vista nula (segura respecto a info oculta) y logueamos. */
+    viewFor (seat) {
+      if (state == null) return null
+      if (!viewFn) return clone(state)
+      try { return viewFn(state, seat) }
+      catch (e) { console.warn('[lobby] view() lanzó para el asiento', seat, e); return null }
+    },
+
+    /** ¿Terminó? → { winner, reason } | null */
+    checkOver () {
+      if (state == null) return null
+      const r = isOverFn(state)
+      return r || null
+    },
+
+    reset () { state = null; rng = null; seed = null; started = false }
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,232 @@
+// Tipos de @dotrino/lobby
+
+export type Role = 'host' | 'guest'
+export type RoomStatus = 'waiting' | 'playing' | 'paused' | 'ended'
+export type SeatStatus = 'open' | 'occupied' | 'disconnected'
+export type StartMode = 'ready' | 'full' | 'manual'
+export type VacancyPolicy = 'pause' | 'forfeit' | 'fill'
+export type HostLostPolicy = 'end' | 'migrate'
+
+export const STATUS: { WAITING: 'waiting'; PLAYING: 'playing'; PAUSED: 'paused'; ENDED: 'ended' }
+export const SEAT: { OPEN: 'open'; OCCUPIED: 'occupied'; DISCONNECTED: 'disconnected' }
+
+/** Spec del motor de turnos autoritativo. El juego aporta funciones puras. */
+export interface EngineSpec<S = any, A = any> {
+  /** Estado inicial (valor) o factoría que recibe el rng sembrado. */
+  initialState: S | ((rng: () => number) => S)
+  /** Aplica una acción. ctx = { seat, seats, rng, now }. Lanza Error(reason) para rechazar. */
+  reducer: (state: S, action: A, ctx: ReducerCtx) => S
+  /** Proyección visible para un asiento (o null = espectador). Default: estado completo. */
+  view?: (state: S, seat: string | null) => any
+  /** ¿Terminó? → { winner, reason } | falsy. */
+  isOver?: (state: S) => { winner: string | null; reason?: string } | null | undefined | false
+}
+
+export interface ReducerCtx {
+  seat: string
+  seats: Record<string, { pubkey: string | null; name: string | null; status: SeatStatus; occupied: boolean }>
+  rng: () => number
+  now: number
+}
+
+export interface SeatView {
+  id: string
+  pubkey: string | null
+  name: string | null
+  ready: boolean
+  status: SeatStatus
+  occupied: boolean
+}
+
+export interface SpectatorView { pubkey: string | null; name: string | null }
+
+export interface RoomState {
+  roomId: string
+  gameId: string
+  name: string | null
+  hostPubkey: string | null
+  status: RoomStatus
+  seats: Record<string, SeatView>
+  spectators: SpectatorView[]
+  result: { winner: string | null; reason?: string } | null
+  game: any
+  version: number
+}
+
+export interface RoomSummary {
+  roomId: string
+  gameId: string
+  name: string | null
+  hostPubkey: string | null
+  status: RoomStatus
+  players: number
+  openSeats: number
+  max: number
+  spectators: number
+  seats: Array<{ id: string; status: SeatStatus; name: string | null }>
+  /** Añadidos por listRooms (enrich): reputación ponderada y flag de contacto. */
+  reputation?: any
+  hostScore?: number
+  isContact?: boolean
+}
+
+export interface Receipt { a: string; b: string; ts: number; sigA: string; sigB: string }
+
+export interface MatchmakingConfig {
+  /** Sólo emparejar con avalados por tu red (trustedCount > 0). */
+  requireVouched?: boolean
+  /** Score mínimo 0..1 para admitir/emparejar. */
+  minReputation?: number
+  /** Priorizar salas de contactos al ordenar. Default true. */
+  preferContacts?: boolean
+}
+
+export interface CreateLobbyOptions {
+  /** Namespace del juego (canales). Obligatorio. */
+  gameId: string
+  /** Asientos: ['white','black'] o { min, max }. */
+  seats?: string[] | { min?: number; max?: number }
+  /** Motor de turnos opcional. Sin él, la sala funciona en modo relay. */
+  engine?: EngineSpec
+  /** Instancia de Identity ya conectada (si no, se conecta sola). */
+  identity?: any
+  /** Instancia de createVaultReputation (opcional). */
+  reputation?: any
+  /** Cliente proxy ya creado (reuso de conexión). */
+  proxy?: any
+  /** Transporte ya creado (avanzado / tests). */
+  transport?: Transport
+  /** URL del proxy. */
+  url?: string
+  start?: StartMode
+  onSeatVacated?: VacancyPolicy
+  onHostLost?: HostLostPolicy
+  allowSpectators?: boolean
+  maxSpectators?: number
+  /** Grace period (ms) para reclamar asiento tras caída. Default 45000. */
+  disconnectGraceMs?: number
+  /** Exigir challenge/response antes de sentar (anti-impersonación). Default true. */
+  requireVerify?: boolean
+  matchmaking?: MatchmakingConfig
+  /** Nombre a mostrar del jugador. */
+  playerName?: string
+  /** Semilla del motor (si se omite, la elige el host). */
+  seed?: number | string
+}
+
+export interface CreateRoomOptions { name?: string; playerName?: string; seed?: number | string }
+export interface JoinRoomOptions { playerName?: string }
+export interface QuickMatchOptions extends CreateRoomOptions, JoinRoomOptions {
+  /** Ventana (ms) para descubrir salas. */
+  timeout?: number
+  /** Asiento a tomar automáticamente. */
+  seat?: string
+  /** Auto-sentarse al unir/crear. Default true. */
+  autoSeat?: boolean
+}
+
+/** Emisor de eventos mínimo. */
+export declare class Emitter {
+  on (event: string, handler: (...args: any[]) => void): () => void
+  once (event: string, handler: (...args: any[]) => void): () => void
+  off (event: string, handler: (...args: any[]) => void): void
+  emit (event: string, ...args: any[]): void
+  removeAllListeners (): void
+}
+
+/**
+ * Una sala. Eventos: 'update'(RoomState), 'state'(game), 'event'({event,data}),
+ * 'message'(relay), 'chat', 'started', 'ended'(result), 'closed', 'kicked',
+ * 'rejected', 'receipt'({pubkey,receipt}), 'left'.
+ */
+export declare class Room extends Emitter {
+  readonly role: Role
+  readonly isHost: boolean
+  readonly roomId: string
+  readonly gameId: string
+  readonly status: RoomStatus
+  readonly result: { winner: string | null; reason?: string } | null
+  readonly seats: Record<string, SeatView>
+  readonly spectators: SpectatorView[]
+  readonly game: any
+  readonly version: number
+  readonly state: RoomState
+  readonly mySeat: string | null
+
+  takeSeat (seatId?: string): boolean
+  leaveSeat (): void
+  setReady (ready?: boolean): void
+  spectate (): void
+  action (action: any): void
+  chat (text: string): void
+  send (data: any): void
+  /** Host-only: arrancar/reiniciar manualmente. */
+  start (): boolean
+  /** Califica a un co-jugador (contacto + atestación, con recibo si existe). */
+  ratePlayer (pubkey: string, valueOrIndicators: number | Record<string, number>, opts?: { notes?: string; nickname?: string; addContact?: boolean; receipt?: Receipt }): Promise<{ ok: true; txBound: boolean }>
+  /** Recibo co-firmado con `pubkey` (o null). */
+  matchReceipt (pubkey: string): Receipt | null
+  leave (): Promise<void>
+}
+
+/**
+ * Lobby. Eventos: 'invite'({from, roomId, name, fromName}) cuando un contacto te
+ * invita; 'rooms-changed'({type:'joined'|'left', token}) cuando cambia el canal
+ * de descubrimiento (llamá listRooms para el detalle actualizado).
+ */
+export declare class Lobby extends Emitter {
+  readonly gameId: string
+  readonly rooms: Room[]
+  createRoom (opts?: CreateRoomOptions): Promise<Room>
+  joinRoom (roomId: string, opts?: JoinRoomOptions): Promise<Room>
+  listRooms (opts?: { timeout?: number; enrich?: boolean }): Promise<RoomSummary[]>
+  quickMatch (opts?: QuickMatchOptions): Promise<Room>
+  inviteContact (pubkey: string, opts?: { roomId?: string; name?: string }): void
+  listContacts (): Promise<any[]>
+  reputationOf (pubkey: string): Promise<any>
+  destroy (): Promise<void>
+}
+
+export declare class Transport {
+  constructor (opts?: { proxy?: any; identity?: any; url?: string })
+  readonly token: string | null
+  readonly isReady: boolean
+  connect (): Promise<string | null>
+  subscribe (gameId: string, fn: (from: string, env: any, meta: any) => void): () => void
+  send (to: string | string[], env: any): void
+  sendByPubkey (pubkeys: string | string[], env: any): void
+}
+
+export function createLobby (opts: CreateLobbyOptions): Promise<Lobby>
+
+export interface Engine {
+  readonly started: boolean
+  readonly seed: number | string | null
+  start (seed?: number | string): any
+  apply (seat: string, action: any, seatsSnapshot?: any): any
+  getState (): any
+  load (state: any): void
+  viewFor (seat: string | null): any
+  checkOver (): { winner: string | null; reason?: string } | null
+  reset (): void
+}
+export function createEngine (spec: EngineSpec): Engine
+
+// Helpers de reputación / contactos
+export function createRepGate (reputation: any, gate?: MatchmakingConfig): (pubkey: string) => Promise<{ ok: boolean; reason?: string; rep?: any }>
+export function rankRooms (rooms: RoomSummary[], ctx?: { reputation?: any; contacts?: Set<string>; preferContacts?: boolean }): Promise<RoomSummary[]>
+export function ratePlayer (identity: any, reputation: any, pubkey: string, valueOrIndicators: number | Record<string, number>, opts?: any): Promise<{ ok: true; txBound: boolean }>
+export function receiptPayload (a: string, b: string, ts: number): { op: 'receipt'; a: string; b: string; ts: number }
+export function signReceiptHalf (identity: any, a: string, b: string, ts: number): Promise<string>
+
+// Protocolo / utilidades
+export const K: Record<string, string>
+export function discoveryChannel (gameId: string): string
+export function roomChannel (gameId: string, roomId: string): string
+export function envelope (gameId: string, roomId: string, kind: string, data?: any, seq?: number): any
+export function parseEnvelope (payload: any): { g: string; r: string; k: string; d: any; s: number | null } | null
+export function mulberry32 (seed: number): () => number
+export function hashSeed (str: string): number
+export function shuffle<T> (array: T[], rng: () => number): T[]
+export function normalizeSeats (spec: string[] | { min?: number; max?: number }): { ids: string[]; min: number; max: number; named: boolean }
+export function samePubkey (a: string, b: string): boolean

package/src/index.js

@@ -0,0 +1,15 @@
+// @dotrino/lobby
+// Lobby + matchmaking reciclable para juegos del ecosistema Dotrino.
+// Construido sobre los pilares compartidos: proxy (transporte/canales/identify),
+// identity (vault/firma/contactos) y reputation (web-of-trust).
+
+export { createLobby, Lobby } from './lobby.js'
+export { Room, STATUS, SEAT } from './room.js'
+export { createEngine } from './engine.js'
+export { Transport } from './transport.js'
+export {
+  createRepGate, rankRooms, ratePlayer,
+  receiptPayload, signReceiptHalf
+} from './reputation.js'
+export { K, discoveryChannel, roomChannel, envelope, parseEnvelope } from './protocol.js'
+export { Emitter, mulberry32, hashSeed, shuffle, normalizeSeats, samePubkey } from './util.js'