@cerca.red/mapa 0.2.0

package/dist/puerto.d.ts

@@ -0,0 +1,244 @@
+import type { Caja, ColeccionDeEntidades, Coordenada } from "@cerca.red/geo";
+import type { CapaDelEstilo, EspecificacionDeEstilo } from "./estilo.ts";
+/**
+ * El puerto: todo lo que este SDK le pide a un motor de mapas.
+ *
+ * ## Por qué existe
+ *
+ * Tres razones, y las tres se pagan solas.
+ *
+ * **Una.** El núcleo del SDK no importa `maplibre-gl`, así que el punto de
+ * entrada por defecto de este paquete se puede importar desde un Server
+ * Component de Next sobre Workers sin que el build reviente. Quien quiera el
+ * mapa de verdad entra por `@cerca.red/mapa/navegador`, y eso **se ve en el
+ * diff**.
+ *
+ * **Dos.** Esta interfaz es la lista escrita de lo que hay que revisar el día
+ * que salga MapLibre 7. La 6 ya rompió tres cosas —`map.transform` dejó de
+ * existir, `setData()` perdió la espera y el retorno encadenable, y el evento
+ * de datos se partió en dos tipos—, y cada una se arregla en un archivo
+ * (`navegador/maplibre.ts`) en vez de en cuarenta.
+ *
+ * **Tres.** Con el puerto, casi todo el SDK se prueba en Node contra un doble
+ * y sin GPU. Lo que no se puede probar así queda acotado a lo que de verdad
+ * necesita WebGL, que es poco y va a Playwright.
+ *
+ * ## La regla de crecimiento
+ *
+ * Se le suman métodos **cuando hacen falta**, no por si acaso. Cada método de
+ * más es una cosa más que el doble tiene que fingir bien y una cosa más que
+ * revisar en la próxima versión mayor de MapLibre.
+ */
+/**
+ * Quién movió la cámara.
+ *
+ * Es el campo que rompe el bucle lista↔mapa. Sin él, la pantalla que escucha
+ * el movimiento para recargar resultados no puede distinguir «el usuario
+ * arrastró el mapa» de «yo acabo de encuadrar el resultado que el usuario
+ * eligió en la lista», así que vuelve a consultar por su propio movimiento,
+ * lo que mueve el mapa, lo que dispara otro evento.
+ */
+export type OrigenDeMovimiento = "usuario" | "codigo";
+/** Un punto en píxeles del canvas, con el origen en la esquina superior izquierda. */
+export interface PuntoEnPantalla {
+    readonly x: number;
+    readonly y: number;
+}
+/** Dónde está mirando la cámara. */
+export interface VistaDelMapa {
+    readonly centro: Coordenada;
+    readonly zoom: number;
+    /** Grados desde el norte, en el sentido de las agujas del reloj. */
+    readonly rumbo: number;
+    /** Grados de inclinación respecto a la vertical: 0 es cenital. */
+    readonly inclinacion: number;
+    /** La caja que se ve ahora mismo. */
+    readonly caja: Caja;
+}
+/**
+ * Espacio en píxeles que la cámara deja libre en cada borde.
+ *
+ * En móvil no es un detalle estético: una hoja inferior que ocupa media
+ * pantalla hace que el centro del canvas **no** sea el centro de lo que el
+ * usuario ve, y sin márgenes cada encuadre deja los resultados debajo de la
+ * hoja.
+ */
+export interface Margenes {
+    readonly arriba: number;
+    readonly derecha: number;
+    readonly abajo: number;
+    readonly izquierda: number;
+}
+/** Adónde llevar la cámara. Todo opcional: lo que no se diga, no se toca. */
+export interface DestinoDeCamara {
+    readonly centro?: Coordenada;
+    readonly zoom?: number;
+    readonly rumbo?: number;
+    readonly inclinacion?: number;
+}
+/** Cómo llegar. */
+export interface OpcionesDeMovimiento {
+    readonly origen: OrigenDeMovimiento;
+    /**
+     * `"vuelo"` es la curva larga de MapLibre, que hace zoom hacia fuera y
+     * luego hacia dentro; `"suave"` interpola en línea recta; `"salto"` no
+     * anima.
+     *
+     * Importa cuál se elige: el vuelo a un punto muy cercano se ve como un
+     * tirón hacia atrás y hacia delante, y es la razón por la que encuadrar un
+     * solo negocio usa `"suave"`.
+     */
+    readonly modo?: "vuelo" | "suave" | "salto";
+    readonly duracionEnMs?: number;
+}
+export interface OpcionesDeEncuadre extends OpcionesDeMovimiento {
+    readonly margenes?: Margenes;
+    /** El zoom más allá del cual no se acerca aunque la caja quepa. */
+    readonly zoomMaximo?: number;
+}
+/** Una entidad que el motor tiene dibujada bajo un punto de la pantalla. */
+export interface EntidadDibujada {
+    readonly capa: string;
+    readonly id: string | number | undefined;
+    readonly propiedades: Readonly<Record<string, unknown>>;
+}
+/** Opciones de una fuente GeoJSON. Solo las que este SDK usa. */
+export interface OpcionesDeFuente {
+    /** Agrupa los puntos cercanos. La agrupación la hace el motor, no el SDK. */
+    readonly agrupar?: boolean;
+    readonly radioDeGrupoEnPx?: number;
+    /** Zoom a partir del cual se dejan de agrupar. */
+    readonly zoomMaximoDeGrupo?: number;
+    /** Necesario para poder darle estado a una entidad por su identificador. */
+    readonly promoverId?: string;
+}
+/** Una imagen registrada para usarse como símbolo. */
+export interface ImagenDeSimbolo {
+    readonly ancho: number;
+    readonly alto: number;
+    readonly datos: Uint8ClampedArray | Uint8Array;
+    /**
+     * `true` si es una imagen de campo de distancia con signo, que es lo que
+     * permite recolorearla desde el estilo en vez de generar una imagen por
+     * cada combinación de estado y color.
+     */
+    readonly sdf?: boolean;
+    readonly escalaDePixeles?: number;
+}
+/** Lo que devuelve suscribirse: llamarlo cancela la suscripción. */
+export type Desuscribir = () => void;
+/** El evento de un cambio de cámara. */
+export interface EventoDeCamara {
+    readonly origen: OrigenDeMovimiento;
+    readonly vista: VistaDelMapa;
+}
+/** El evento de un toque o un clic sobre el mapa. */
+export interface EventoDePuntero {
+    readonly coordenada: Coordenada;
+    readonly punto: PuntoEnPantalla;
+    /**
+     * `true` si vino de un dedo o de un ratón, `false` si vino del teclado.
+     *
+     * Un canvas no es accesible por sí solo: el recorrido con teclado necesita
+     * una lista real al lado, y quien la escucha tiene que poder decidir
+     * distinto —no abrir una tarjeta flotante bajo un dedo que no existe—.
+     */
+    readonly desdePuntero: boolean;
+}
+/** Lo que un motor de mapas avisa. */
+export interface EventosNativos {
+    /** El estilo terminó de cargar. Se vuelve a emitir en cada cambio de estilo. */
+    readonly "estilo:listo": undefined;
+    /** Una fuente terminó de recibir datos. Lleva el identificador de la fuente. */
+    readonly "fuente:datos": {
+        readonly fuente: string;
+    };
+    readonly movimiento: EventoDeCamara;
+    readonly "movimiento:fin": EventoDeCamara;
+    readonly zoom: EventoDeCamara;
+    readonly clic: EventoDePuntero;
+    readonly error: {
+        readonly error: Error;
+    };
+}
+/** Lo que un motor de mapas avisa sobre capas concretas. */
+export interface EventosDeCapa {
+    readonly clic: EventoDePuntero & {
+        readonly entidades: readonly EntidadDibujada[];
+    };
+    readonly encima: EventoDePuntero & {
+        readonly entidades: readonly EntidadDibujada[];
+    };
+    readonly fuera: EventoDePuntero;
+}
+/**
+ * El motor de mapas, visto desde el SDK.
+ *
+ * Lo implementan dos cosas: `navegador/maplibre.ts`, que envuelve MapLibre de
+ * verdad, y `doble/`, que finge lo justo para que las pruebas en Node midan
+ * el comportamiento del SDK y no el del motor.
+ */
+export interface MapaNativo {
+    /** `true` cuando el estilo ya cargó y se le pueden añadir capas. */
+    estaListo(): boolean;
+    /** Se resuelve cuando `estaListo()` pasa a ser cierto. Si ya lo era, de inmediato. */
+    cuandoListo(): Promise<void>;
+    /** Suelta el contexto WebGL y todos los oyentes. Después de esto no se le habla más. */
+    destruir(): void;
+    /** Vuelve a medir el contenedor. Hace falta cuando la hoja inferior cambia de alto. */
+    redimensionar(): void;
+    /**
+     * Reemplaza el estilo entero.
+     *
+     * Cambiar de tema o de idioma es esto, y por eso el SDK guarda su propio
+     * modelo: el estilo nuevo llega sin las fuentes ni las capas de Cerca, y
+     * hay que volver a ponerlas. No es un defecto que evitar — es lo que
+     * garantiza que el orden de capas quede bien por construcción.
+     */
+    ponerEstilo(estilo: EspecificacionDeEstilo): void;
+    agregarFuenteGeoJSON(id: string, datos: ColeccionDeEntidades, opciones?: OpcionesDeFuente): void;
+    /**
+     * Cambia los datos de una fuente ya añadida.
+     *
+     * En MapLibre 6 esto **no dice cuándo aterrizó el dato**: `setData()` perdió
+     * la opción de esperar y ya no devuelve el mapa. Quien necesite encuadrar
+     * después de poner datos escucha `fuente:datos`.
+     */
+    ponerDatosDeFuente(id: string, datos: ColeccionDeEntidades): void;
+    tieneFuente(id: string): boolean;
+    /** Añade una capa, opcionalmente por debajo de otra que ya exista. */
+    agregarCapa(capa: CapaDelEstilo, antesDe?: string): void;
+    quitarCapa(id: string): void;
+    tieneCapa(id: string): boolean;
+    /**
+     * Marca una entidad de una fuente con un estado que el estilo puede leer.
+     *
+     * Sirve para lo que **solo cambia color** —el resalte al pasar por encima—.
+     * Para lo que tiene que dibujarse **encima** de sus vecinos hace falta otra
+     * fuente, porque la clave de ordenación de símbolos no lee el estado de
+     * entidad. Es la razón por la que la selección vive en su propia fuente.
+     */
+    ponerEstadoDeEntidad(fuente: string, id: string | number, estado: Readonly<Record<string, unknown>>): void;
+    limpiarEstadosDeEntidad(fuente: string): void;
+    agregarImagen(id: string, imagen: ImagenDeSimbolo): void;
+    tieneImagen(id: string): boolean;
+    vista(): VistaDelMapa;
+    moverCamara(destino: DestinoDeCamara, opciones: OpcionesDeMovimiento): void;
+    encuadrarCaja(caja: Caja, opciones: OpcionesDeEncuadre): void;
+    ponerMargenes(margenes: Margenes): void;
+    /** Limita hasta dónde se puede navegar. `undefined` quita el límite. */
+    ponerCajaMaxima(caja: Caja | undefined): void;
+    /**
+     * De coordenada a píxel.
+     *
+     * Es lo que hace comprobable el objetivo táctil de 44 px sobre un canvas,
+     * donde no hay ningún elemento del DOM cuya caja medir: se calcula el punto
+     * y se toca dentro y fuera del radio esperado.
+     */
+    proyectar(coordenada: Coordenada): PuntoEnPantalla;
+    desproyectar(punto: PuntoEnPantalla): Coordenada;
+    /** Las entidades dibujadas bajo un punto, en las capas dadas. */
+    entidadesEn(punto: PuntoEnPantalla, capas: readonly string[]): readonly EntidadDibujada[];
+    al<T extends keyof EventosNativos>(tipo: T, manejador: (evento: EventosNativos[T]) => void): Desuscribir;
+    alDeCapa<T extends keyof EventosDeCapa>(tipo: T, capas: readonly string[], manejador: (evento: EventosDeCapa[T]) => void): Desuscribir;
+}

package/dist/puerto.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=puerto.js.map

package/dist/puerto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"puerto.js","sourceRoot":"","sources":["../src/puerto.ts"],"names":[],"mappings":"","sourcesContent":["import type { Caja, ColeccionDeEntidades, Coordenada } from \"@cerca.red/geo\";\n\nimport type { CapaDelEstilo, EspecificacionDeEstilo } from \"./estilo.ts\";\n\n/**\n * El puerto: todo lo que este SDK le pide a un motor de mapas.\n *\n * ## Por qué existe\n *\n * Tres razones, y las tres se pagan solas.\n *\n * **Una.** El núcleo del SDK no importa `maplibre-gl`, así que el punto de\n * entrada por defecto de este paquete se puede importar desde un Server\n * Component de Next sobre Workers sin que el build reviente. Quien quiera el\n * mapa de verdad entra por `@cerca.red/mapa/navegador`, y eso **se ve en el\n * diff**.\n *\n * **Dos.** Esta interfaz es la lista escrita de lo que hay que revisar el día\n * que salga MapLibre 7. La 6 ya rompió tres cosas —`map.transform` dejó de\n * existir, `setData()` perdió la espera y el retorno encadenable, y el evento\n * de datos se partió en dos tipos—, y cada una se arregla en un archivo\n * (`navegador/maplibre.ts`) en vez de en cuarenta.\n *\n * **Tres.** Con el puerto, casi todo el SDK se prueba en Node contra un doble\n * y sin GPU. Lo que no se puede probar así queda acotado a lo que de verdad\n * necesita WebGL, que es poco y va a Playwright.\n *\n * ## La regla de crecimiento\n *\n * Se le suman métodos **cuando hacen falta**, no por si acaso. Cada método de\n * más es una cosa más que el doble tiene que fingir bien y una cosa más que\n * revisar en la próxima versión mayor de MapLibre.\n */\n\n/**\n * Quién movió la cámara.\n *\n * Es el campo que rompe el bucle lista↔mapa. Sin él, la pantalla que escucha\n * el movimiento para recargar resultados no puede distinguir «el usuario\n * arrastró el mapa» de «yo acabo de encuadrar el resultado que el usuario\n * eligió en la lista», así que vuelve a consultar por su propio movimiento,\n * lo que mueve el mapa, lo que dispara otro evento.\n */\nexport type OrigenDeMovimiento = \"usuario\" | \"codigo\";\n\n/** Un punto en píxeles del canvas, con el origen en la esquina superior izquierda. */\nexport interface PuntoEnPantalla {\n  readonly x: number;\n  readonly y: number;\n}\n\n/** Dónde está mirando la cámara. */\nexport interface VistaDelMapa {\n  readonly centro: Coordenada;\n  readonly zoom: number;\n  /** Grados desde el norte, en el sentido de las agujas del reloj. */\n  readonly rumbo: number;\n  /** Grados de inclinación respecto a la vertical: 0 es cenital. */\n  readonly inclinacion: number;\n  /** La caja que se ve ahora mismo. */\n  readonly caja: Caja;\n}\n\n/**\n * Espacio en píxeles que la cámara deja libre en cada borde.\n *\n * En móvil no es un detalle estético: una hoja inferior que ocupa media\n * pantalla hace que el centro del canvas **no** sea el centro de lo que el\n * usuario ve, y sin márgenes cada encuadre deja los resultados debajo de la\n * hoja.\n */\nexport interface Margenes {\n  readonly arriba: number;\n  readonly derecha: number;\n  readonly abajo: number;\n  readonly izquierda: number;\n}\n\n/** Adónde llevar la cámara. Todo opcional: lo que no se diga, no se toca. */\nexport interface DestinoDeCamara {\n  readonly centro?: Coordenada;\n  readonly zoom?: number;\n  readonly rumbo?: number;\n  readonly inclinacion?: number;\n}\n\n/** Cómo llegar. */\nexport interface OpcionesDeMovimiento {\n  readonly origen: OrigenDeMovimiento;\n  /**\n   * `\"vuelo\"` es la curva larga de MapLibre, que hace zoom hacia fuera y\n   * luego hacia dentro; `\"suave\"` interpola en línea recta; `\"salto\"` no\n   * anima.\n   *\n   * Importa cuál se elige: el vuelo a un punto muy cercano se ve como un\n   * tirón hacia atrás y hacia delante, y es la razón por la que encuadrar un\n   * solo negocio usa `\"suave\"`.\n   */\n  readonly modo?: \"vuelo\" | \"suave\" | \"salto\";\n  readonly duracionEnMs?: number;\n}\n\nexport interface OpcionesDeEncuadre extends OpcionesDeMovimiento {\n  readonly margenes?: Margenes;\n  /** El zoom más allá del cual no se acerca aunque la caja quepa. */\n  readonly zoomMaximo?: number;\n}\n\n/** Una entidad que el motor tiene dibujada bajo un punto de la pantalla. */\nexport interface EntidadDibujada {\n  readonly capa: string;\n  readonly id: string | number | undefined;\n  readonly propiedades: Readonly<Record<string, unknown>>;\n}\n\n/** Opciones de una fuente GeoJSON. Solo las que este SDK usa. */\nexport interface OpcionesDeFuente {\n  /** Agrupa los puntos cercanos. La agrupación la hace el motor, no el SDK. */\n  readonly agrupar?: boolean;\n  readonly radioDeGrupoEnPx?: number;\n  /** Zoom a partir del cual se dejan de agrupar. */\n  readonly zoomMaximoDeGrupo?: number;\n  /** Necesario para poder darle estado a una entidad por su identificador. */\n  readonly promoverId?: string;\n}\n\n/** Una imagen registrada para usarse como símbolo. */\nexport interface ImagenDeSimbolo {\n  readonly ancho: number;\n  readonly alto: number;\n  readonly datos: Uint8ClampedArray | Uint8Array;\n  /**\n   * `true` si es una imagen de campo de distancia con signo, que es lo que\n   * permite recolorearla desde el estilo en vez de generar una imagen por\n   * cada combinación de estado y color.\n   */\n  readonly sdf?: boolean;\n  readonly escalaDePixeles?: number;\n}\n\n/** Lo que devuelve suscribirse: llamarlo cancela la suscripción. */\nexport type Desuscribir = () => void;\n\n/** El evento de un cambio de cámara. */\nexport interface EventoDeCamara {\n  readonly origen: OrigenDeMovimiento;\n  readonly vista: VistaDelMapa;\n}\n\n/** El evento de un toque o un clic sobre el mapa. */\nexport interface EventoDePuntero {\n  readonly coordenada: Coordenada;\n  readonly punto: PuntoEnPantalla;\n  /**\n   * `true` si vino de un dedo o de un ratón, `false` si vino del teclado.\n   *\n   * Un canvas no es accesible por sí solo: el recorrido con teclado necesita\n   * una lista real al lado, y quien la escucha tiene que poder decidir\n   * distinto —no abrir una tarjeta flotante bajo un dedo que no existe—.\n   */\n  readonly desdePuntero: boolean;\n}\n\n/** Lo que un motor de mapas avisa. */\nexport interface EventosNativos {\n  /** El estilo terminó de cargar. Se vuelve a emitir en cada cambio de estilo. */\n  readonly \"estilo:listo\": undefined;\n  /** Una fuente terminó de recibir datos. Lleva el identificador de la fuente. */\n  readonly \"fuente:datos\": { readonly fuente: string };\n  readonly movimiento: EventoDeCamara;\n  readonly \"movimiento:fin\": EventoDeCamara;\n  readonly zoom: EventoDeCamara;\n  readonly clic: EventoDePuntero;\n  readonly error: { readonly error: Error };\n}\n\n/** Lo que un motor de mapas avisa sobre capas concretas. */\nexport interface EventosDeCapa {\n  readonly clic: EventoDePuntero & {\n    readonly entidades: readonly EntidadDibujada[];\n  };\n  readonly encima: EventoDePuntero & {\n    readonly entidades: readonly EntidadDibujada[];\n  };\n  readonly fuera: EventoDePuntero;\n}\n\n/**\n * El motor de mapas, visto desde el SDK.\n *\n * Lo implementan dos cosas: `navegador/maplibre.ts`, que envuelve MapLibre de\n * verdad, y `doble/`, que finge lo justo para que las pruebas en Node midan\n * el comportamiento del SDK y no el del motor.\n */\nexport interface MapaNativo {\n  // — ciclo de vida —\n\n  /** `true` cuando el estilo ya cargó y se le pueden añadir capas. */\n  estaListo(): boolean;\n  /** Se resuelve cuando `estaListo()` pasa a ser cierto. Si ya lo era, de inmediato. */\n  cuandoListo(): Promise<void>;\n  /** Suelta el contexto WebGL y todos los oyentes. Después de esto no se le habla más. */\n  destruir(): void;\n  /** Vuelve a medir el contenedor. Hace falta cuando la hoja inferior cambia de alto. */\n  redimensionar(): void;\n\n  // — estilo —\n\n  /**\n   * Reemplaza el estilo entero.\n   *\n   * Cambiar de tema o de idioma es esto, y por eso el SDK guarda su propio\n   * modelo: el estilo nuevo llega sin las fuentes ni las capas de Cerca, y\n   * hay que volver a ponerlas. No es un defecto que evitar — es lo que\n   * garantiza que el orden de capas quede bien por construcción.\n   */\n  ponerEstilo(estilo: EspecificacionDeEstilo): void;\n\n  // — fuentes —\n\n  agregarFuenteGeoJSON(\n    id: string,\n    datos: ColeccionDeEntidades,\n    opciones?: OpcionesDeFuente,\n  ): void;\n  /**\n   * Cambia los datos de una fuente ya añadida.\n   *\n   * En MapLibre 6 esto **no dice cuándo aterrizó el dato**: `setData()` perdió\n   * la opción de esperar y ya no devuelve el mapa. Quien necesite encuadrar\n   * después de poner datos escucha `fuente:datos`.\n   */\n  ponerDatosDeFuente(id: string, datos: ColeccionDeEntidades): void;\n  tieneFuente(id: string): boolean;\n\n  // — capas —\n\n  /** Añade una capa, opcionalmente por debajo de otra que ya exista. */\n  agregarCapa(capa: CapaDelEstilo, antesDe?: string): void;\n  quitarCapa(id: string): void;\n  tieneCapa(id: string): boolean;\n\n  // — estado de entidad —\n\n  /**\n   * Marca una entidad de una fuente con un estado que el estilo puede leer.\n   *\n   * Sirve para lo que **solo cambia color** —el resalte al pasar por encima—.\n   * Para lo que tiene que dibujarse **encima** de sus vecinos hace falta otra\n   * fuente, porque la clave de ordenación de símbolos no lee el estado de\n   * entidad. Es la razón por la que la selección vive en su propia fuente.\n   */\n  ponerEstadoDeEntidad(\n    fuente: string,\n    id: string | number,\n    estado: Readonly<Record<string, unknown>>,\n  ): void;\n  limpiarEstadosDeEntidad(fuente: string): void;\n\n  // — símbolos —\n\n  agregarImagen(id: string, imagen: ImagenDeSimbolo): void;\n  tieneImagen(id: string): boolean;\n\n  // — cámara —\n\n  vista(): VistaDelMapa;\n  moverCamara(destino: DestinoDeCamara, opciones: OpcionesDeMovimiento): void;\n  encuadrarCaja(caja: Caja, opciones: OpcionesDeEncuadre): void;\n  ponerMargenes(margenes: Margenes): void;\n  /** Limita hasta dónde se puede navegar. `undefined` quita el límite. */\n  ponerCajaMaxima(caja: Caja | undefined): void;\n\n  // — consulta —\n\n  /**\n   * De coordenada a píxel.\n   *\n   * Es lo que hace comprobable el objetivo táctil de 44 px sobre un canvas,\n   * donde no hay ningún elemento del DOM cuya caja medir: se calcula el punto\n   * y se toca dentro y fuera del radio esperado.\n   */\n  proyectar(coordenada: Coordenada): PuntoEnPantalla;\n  desproyectar(punto: PuntoEnPantalla): Coordenada;\n  /** Las entidades dibujadas bajo un punto, en las capas dadas. */\n  entidadesEn(\n    punto: PuntoEnPantalla,\n    capas: readonly string[],\n  ): readonly EntidadDibujada[];\n\n  // — eventos —\n\n  al<T extends keyof EventosNativos>(\n    tipo: T,\n    manejador: (evento: EventosNativos[T]) => void,\n  ): Desuscribir;\n  alDeCapa<T extends keyof EventosDeCapa>(\n    tipo: T,\n    capas: readonly string[],\n    manejador: (evento: EventosDeCapa[T]) => void,\n  ): Desuscribir;\n}\n"]}

package/dist/sdk.d.ts

@@ -0,0 +1,111 @@
+import { type Caja, type Coordenada, coleccionVacia } from "@cerca.red/geo";
+import { type Anclas } from "./identificadores.ts";
+import { type EventosDelMapa, type TipoDeEvento } from "./eventos.ts";
+import type { FabricaDeEstilo, Tema } from "./estilo.ts";
+import { type PaletaDelMapa } from "./paleta.ts";
+import type { Desuscribir, DestinoDeCamara, EntidadDibujada, MapaNativo, Margenes, OpcionesDeEncuadre, OpcionesDeMovimiento, PuntoEnPantalla } from "./puerto.ts";
+import type { BandaDeIsocrona, NegocioEnMapa, ResultadosEnMapa, RutaEnMapa, SimboloDeMapa, UbicacionDeUsuarioEnMapa, VehiculoEnMapa, ZonaEnMapa } from "./proyecciones.ts";
+import { type CapaExtra } from "./sincronizacion.ts";
+/**
+ * El SDK del mapa de Cerca, construido sobre el puerto.
+ *
+ * Este archivo no sabe qué es MapLibre. Recibe un `MapaNativo` ya construido
+ * —el adaptador de `navegador/`, o el doble de `doble/`— y encima pone el
+ * modelo, los eventos y las decisiones que no se deben repetir en cada
+ * superficie.
+ */
+export interface OpcionesDeCrearMapa {
+    /** Quien sabe construir el estilo. Función pura: mismas opciones, mismo documento. */
+    readonly estilo: FabricaDeEstilo;
+    /**
+     * La URL del archivo de teselas, **tal como vino del manifiesto**.
+     *
+     * No se compone aquí ni en ninguna superficie: ADR-024 puso las URLs
+     * absolutas en el manifiesto precisamente para que nadie las construya, y
+     * eso es lo que hace que promover un puntero a una versión anterior revierta
+     * de verdad en todas partes.
+     */
+    readonly urlDeTeselas: string;
+    readonly tema?: Tema;
+    readonly idioma?: string;
+    /**
+     * Los identificadores de las capas vacías donde se insertan las de Cerca.
+     *
+     * El valor por defecto son los que emite hoy `@cerca.red/mapa-estilos`, y
+     * `anclas-del-estilo.test.ts` ejecuta ese paquete para comprobar que sigue
+     * emitiéndolos. Quien use otro proveedor de estilo pasa los suyos.
+     */
+    readonly anclas?: Anclas;
+    readonly colores?: Partial<PaletaDelMapa>;
+    readonly margenes?: Margenes;
+    readonly radioDeImprecisionEnMetros?: number;
+    /** Hasta dónde se deja navegar. Normalmente, la caja de la región del manifiesto. */
+    readonly cajaMaxima?: Caja;
+    readonly simbolos?: readonly SimboloDeMapa[];
+    /**
+     * `true` si el motor ya nació con el estilo que produce `estilo(...)`.
+     *
+     * Lo usa `crearMapa` de la subruta del navegador, que construye el mapa de
+     * MapLibre con el estilo ya calculado. Sin esta bandera el SDK lo pondría
+     * otra vez en el constructor: MapLibre avisa por consola —«Style is not
+     * done loading, rebuilding from scratch»— y vuelve a descargar los glifos,
+     * que son la petición más pesada de la primera pintura.
+     *
+     * No es una opción para las superficies: es el cable entre las dos mitades
+     * de la construcción.
+     */
+    readonly estiloYaAplicado?: boolean;
+}
+/** Qué encuadrar. */
+export type QueEncuadrar = Caja | readonly Coordenada[] | "todo" | "grupos" | "negocios" | "rutas" | "zonas";
+export interface OpcionesDeSeleccion {
+    /**
+     * Si seleccionar además emite `negocio:clic`. **Por defecto no**, y esa es
+     * la decisión que rompe el bucle lista↔mapa.
+     *
+     * La pantalla de resultados escucha `negocio:clic` para abrir la ficha. Si
+     * `seleccionarNegocio` lo emitiera, tocar un resultado en la lista abriría
+     * la ficha dos veces: una por el toque en la lista y otra por el eco del
+     * mapa. Quien de verdad quiera el eco lo pide.
+     */
+    readonly emitirEvento?: boolean;
+    /** Si además se lleva la cámara al negocio. Por defecto no. */
+    readonly encuadrar?: boolean;
+}
+export interface MapaDeCerca {
+    ponerResultados(resultados: ResultadosEnMapa): void;
+    ponerNegocios(negocios: readonly NegocioEnMapa[]): void;
+    seleccionarNegocio(id: string | undefined, opciones?: OpcionesDeSeleccion): void;
+    ponerUbicacionDeUsuario(ubicacion: UbicacionDeUsuarioEnMapa | undefined): void;
+    ponerVehiculos(vehiculos: readonly VehiculoEnMapa[]): void;
+    moverVehiculo(id: string, ubicacion: Coordenada, rumbo?: number): void;
+    mostrarRuta(rutas: readonly RutaEnMapa[]): void;
+    mostrarZonaDeCobertura(zonas: readonly ZonaEnMapa[]): void;
+    mostrarIsocrona(bandas: readonly BandaDeIsocrona[]): void;
+    encuadrar(que?: QueEncuadrar, opciones?: Partial<OpcionesDeEncuadre>): void;
+    volarA(destino: DestinoDeCamara, opciones?: Partial<OpcionesDeMovimiento>): void;
+    vista(): ReturnType<MapaNativo["vista"]>;
+    proyectar(coordenada: Coordenada): PuntoEnPantalla;
+    desproyectar(punto: PuntoEnPantalla): Coordenada;
+    queHayEn(punto: PuntoEnPantalla, capas?: readonly string[]): readonly EntidadDibujada[];
+    ponerTema(tema: Tema): void;
+    ponerIdioma(idioma: string): void;
+    registrarSimbolos(simbolos: readonly SimboloDeMapa[]): void;
+    ponerMargenes(margenes: Margenes): void;
+    agregarCapaExtra(extra: CapaExtra): Desuscribir;
+    cuando<T extends TipoDeEvento>(tipo: T, manejador: (evento: EventosDelMapa[T]) => void): Desuscribir;
+    unaVez<T extends TipoDeEvento>(tipo: T, manejador: (evento: EventosDelMapa[T]) => void): Desuscribir;
+    destruir(): void;
+    estaDestruido(): boolean;
+}
+/**
+ * Crea el SDK sobre un motor ya construido.
+ *
+ * Las superficies no llaman a esto: llaman a `crearMapa` de
+ * `@cerca.red/mapa/navegador`, que construye el motor de MapLibre y llama
+ * aquí. Esta puerta existe para las pruebas y para cualquier motor futuro.
+ */
+export declare function crearMapaConMotor(motor: MapaNativo, opciones: OpcionesDeCrearMapa): MapaDeCerca;
+/** Reexportado para que quien construya una capa extra vacía no invente la forma. */
+export { coleccionVacia };
+export type { CapaExtra };