@seatsyoo/vue 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tikyoo, S.L.
+
+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

@@ -1,3 +1,366 @@
-# Temporary Holding Version
+# @seatsyoo/vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+El visor de mapas de asientos de **Seatsyoo** como componente de Vue 3: el comprador ve el plano del recinto,
+elige sus butacas (quedan retenidas a su nombre mientras paga) y ve en tiempo real lo que otros compran. Usa el
+visor de [`@seatsyoo/visor`](https://www.npmjs.com/package/@seatsyoo/visor) y trae sus tipos de TypeScript.
+
+Funciona con **Vue 3.3 o posterior** y con renderizado en el servidor (Nuxt, Vite SSR…). No necesita compilar
+plantillas: está escrito con `defineComponent` y una función `render`.
+
+*(English summary below.)*
+
+## Instalación
+
+```sh
+npm install @seatsyoo/vue
+# o: pnpm add @seatsyoo/vue · yarn add @seatsyoo/vue
+```
+
+`vue` lo pones tú (es una dependencia «peer»); `@seatsyoo/visor` se instala solo.
+
+## Uso
+
+```vue
+<script setup lang="ts">
+import { SeatsyooChart, type SelectedObject } from "@seatsyoo/vue";
+import { ref } from "vue";
+
+const plano = ref<InstanceType<typeof SeatsyooChart> | null>(null);
+const seleccion = ref<SelectedObject[]>([]);
+
+async function comprar() {
+  // A tu servidor, solo el evento y el token de retención, nunca la lista de lo elegido: pregunta a Seatsyoo qué
+  // retiene ese token, cobra eso y, con el pago confirmado, lo reserva (ver «Vender»).
+  await fetch("/caja", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ evento: "hamlet-2026-11-20", holdToken: plano.value?.chart?.holdToken }),
+  });
+}
+
+function tiempoAgotado() {
+  alert("Se ha acabado el tiempo: vuelve a elegir.");
+}
+</script>
+
+<template>
+  <!-- El visor ocupa todo el <div>: dale altura. -->
+  <SeatsyooChart
+    ref="plano"
+    server="https://seatsyoo.example"
+    public-key="pk_tu_clave_publica"
+    event="hamlet-2026-11-20"
+    :pricing="{ platea: 30, anfiteatro: 22 }"
+    style="height: 600px"
+    @change="(elegidas: SelectedObject[]) => (seleccion = elegidas)"
+    @hold-expired="tiempoAgotado"
+  />
+  <button :disabled="seleccion.length === 0" @click="comprar">Comprar</button>
+</template>
+```
+
+Para tenerlo en todas las plantillas sin importarlo, registra el plugin:
+
+```ts
+import { SeatsyooPlugin } from "@seatsyoo/vue";
+
+createApp(App).use(SeatsyooPlugin).mount("#app");
+```
+
+Para probarlo en un proyecto nuevo de Vite:
+
+```sh
+npm create vite@latest entradas -- --template vue-ts
+cd entradas
+npm install @seatsyoo/vue
+# pon el ejemplo de arriba en src/App.vue y arranca con:
+npm run dev
+```
+
+### Props
+
+Todas las opciones del visor que no son avisos (`server`, `public-key`, `event`, `season`, `link`, `document`,
+`language`, `theme`, `max-selected`, `pricing`, `channels`, `hold-token`, `mode`, `status-styles`, `marks`, `view3d`…), con los mismos
+nombres y tipos que en `@seatsyoo/visor` (en las plantillas, en camelCase o en kebab-case), salvo `container`, que
+es el propio componente. `class`, `style`, `id` y el resto de atributos pasan al `<div>` que lo contiene. Los números
+y booleanos, con `:` (`:max-selected="6"`, `:view3d="false"`).
+
+Cómo reacciona a los cambios de props:
+
+| Qué cambia | Qué pasa |
+| --- | --- |
+| `server`, `publicKey`, `event`, `link`, `document`, `season`, `seasonEvents`, `channels`, `pricing`, `currency`, `locale`, `language`, `maxSelected`, `session`, `holdToken`, `mode`, `showLegend`, `showSelectionBar`, `floor`, `sectors`, `view3d`, `entrance`, `texts` | Se desmonta el visor y se monta otro con lo nuevo. Los arrays y objetos se comparan **por su valor**: `:channels="['web']"` no lo vuelve a montar en cada render, y cambiar un array reactivo en el sitio (`canales.push("taquilla")`) sí. |
+| `theme`, `colorBy` | Se aplica al visor montado (`setTheme`, `setColorBy`), sin volver a montarlo. |
+| `statusStyles`, `marks` | Solo con `mode="manager"` (un panel de gestión): cómo se ve cada estado y las marcas sobre plazas libres (ver «Estados propios y marcas»). Se aplican al visor montado (`setStatusStyles`, `setMarks`), sin volver a montarlo, solo si cambia su valor: se comparan como datos (da igual el prototipo, y una clave que vale `undefined` es como si no estuviera), así que un objeto nuevo con lo mismo no hace nada, y cambiar uno reactivo en el sitio (`marcas["Platea-A-1"] = "reducida"`) sí cuenta. Quitarlas es dejar el visor sin estilos ni marcas. |
+| `load3d` | Se usa la última función; ponerlo o quitarlo vuelve a montar. |
+
+El plano (`document`) no se copia, porque puede ser muy grande: un plano nuevo con lo mismo no vuelve a montar el
+visor, pero si cambias el que ya pasaste (en el sitio), no se nota, ni aunque después pases una copia. Pasa un plano
+nuevo sin tocar el anterior.
+
+**Lo que el comprador tiene retenido al volver a montar.** Si es en el mismo evento y con `session: "continue"` (por
+defecto), el visor nuevo lo recupera. Si el nuevo no puede recuperarlo (has cambiado de evento o de temporada, de
+`server` o de `publicKey`, usas `session: "start"`, le pasas un `holdToken` o el modo `"manager"`), el componente lo
+suelta antes, como `clearSelection()`: se emiten `deselect` y `change` con la selección vacía, y esas butacas quedan
+libres para los demás en lugar de bloqueadas hasta que caduque la retención. Así, para cambiar de función basta con
+cambiar `event`.
+
+Lo retenido con un `holdToken` tuyo (creado por tu servidor) no se suelta nunca: es de tu token, y tu servidor lo
+reserva o lo suelta. Es la forma de llevar un carrito con varias funciones. Al desmontar el componente (por ejemplo,
+al pasar a la página de pago) tampoco se suelta nada: tu servidor lo reserva con el token, o el comprador lo
+recupera al volver.
+
+### Vender
+
+A tu servidor la página le manda el evento y el `holdToken`, nada más: nunca la lista de lo elegido. En la caja, tu
+servidor pregunta a Seatsyoo qué retiene ese token (`GET /api/v1/events/{evento}/statuses?holdToken=…`: lo suyo lleva
+`mine: true` y, en una zona de pie, `mq` con las plazas del token; `mq` solo viene si en la zona hay más de una plaza
+ocupada, contando las de otros compradores, y si no viene es 1), calcula el importe con sus precios (precio × plazas:
+una mesa entera cuenta todas sus sillas, como el total del visor) y guarda esa lista con el pedido, cada objeto con su
+cantidad (`{ key, quantity: mq ?? 1 }`). Con el pago confirmado, reserva exactamente lo guardado
+(`POST /api/v1/events/{evento}/actions/book` con `holdToken` y tu número de pedido, `orderId`), sin volver a preguntar.
+
+No reserves una lista que mande la página: `book` reserva también objetos libres, así que cualquiera podría añadirle
+butacas que no ha retenido, y saltarse los topes de retención. Es lo que hace la tienda de ejemplo de `@seatsyoo/node`
+(`ejemplo/tienda.ts`: `POST /caja` con `{ evento, holdToken }` y `POST /pagar` con `{ holdToken }`) y lo que cuenta la
+guía de integración de la documentación (**/docs/integracion**).
+
+### Precios
+
+Seatsyoo no guarda precios: los pone tu web. Pásalos con `pricing`, por clave de categoría (`{ platea: 30 }`), con
+`currency` y `locale` para escribirlos: el visor los enseña en la ficha de cada butaca, en la leyenda y en el total,
+y salen en `price` de cada objeto de `change`, `select`… (sin `pricing`, `price` es `null`). `price` es lo que cuesta
+cada unidad de `quantity` (por plaza; una mesa entera, con todas sus sillas), así que `price × quantity` es lo que suma
+el total del visor. Cambiar `pricing` vuelve a montar el visor (en el mismo evento, el comprador no pierde lo elegido).
+Lo que se cobra lo calcula tu servidor con sus precios, no con lo que diga la página.
+
+### Eventos
+
+| Evento | Con qué | Cuándo |
+| --- | --- | --- |
+| `ready` | el visor (`SeatingChart`) | Ha cargado el plano y los estados. |
+| `change` | la selección (`SelectedObject[]`) | La selección ha cambiado. |
+| `select`, `deselect` | el objeto (`SelectedObject`) | Se ha elegido o soltado un objeto. |
+| `hold-expired` | — | Se acabó el tiempo de la retención. |
+| `hold-token-change` | `{ token, expiresAt }` o `null` | El token de retención ha cambiado. |
+| `floor-change` | `{ id, name }` | Se muestra otra planta. |
+| `error` | `{ code, message }` | Algo ha fallado, o se ha llegado a un tope de retención (ver «Topes de retención»). Sin oyente de `@error`, se escribe en la consola. |
+
+Los eventos llegan siempre a los oyentes de ese momento: cambiarlos no vuelve a montar el visor. En TypeScript (y
+en las funciones `render`), los oyentes son `onReady`, `onChange`, `onHoldExpired`, `onHoldTokenChange`…
+
+### Lo que expone
+
+Con una ref de plantilla, `chart` es el visor montado (un `SeatingChart`): `getSelection()`, `holdToken`,
+`holdExpiresAt`, `clearSelection()`, `selectBestAvailable(n)`, `setFloor(id)`, `show3d()`, `zoomToFit()`,
+`refresh()`… Vale `null` mientras no hay visor: en el servidor, antes de montarlo y después de desmontarlo. Si
+cambia una opción que lo vuelve a montar, `chart` pasa a ser el visor nuevo.
+
+### Errores
+
+Lo que falla al cargar o al retener llega a `@error` como `{ code, message }`. Si faltan opciones para montarlo
+(qué enseñar, la clave pública…), el componente no lanza: emite `error` con `code: "invalid-options"` (sin oyente,
+lo escribe en la consola) y lo monta en cuanto las opciones valen.
+
+### Topes de retención
+
+Lo que el comprador retiene desde el visor tiene topes en el servidor. Al pasar uno, la butaca no se retiene y llega
+el error a `@error`:
+
+| Código | Qué tope |
+| --- | --- |
+| `hold-limit` (409) | Las «Plazas por comprador» de tu espacio (`maxHoldPerToken`, 10 si no se cambia; lo da `GET /workspace`), por token y evento. Una mesa o un palco que se venden enteros cuentan todas sus plazas. |
+| `hold-limit-ip` (409) | Lo retenido a la vez desde una misma conexión (IP) en un evento, sumando todas sus compras en curso: el 10 % del aforo, hasta 200, y nunca menos que `maxHoldPerToken`. |
+| `hold-rate-limited` (429) | Lo que retiene una misma IP en poco tiempo: como mucho 600 plazas cada 10 minutos (soltar no cuenta). |
+
+- `max-selected` cuenta una mesa o un palco enteros como 1, y el servidor, con todas sus plazas: con
+  `max-selected` y `maxHoldPerToken` en 10, dos mesas de 8 dan `hold-limit`. No pongas `max-selected` por encima de
+  `maxHoldPerToken` y, si vendes mesas o palcos enteros, cuenta con ese error o sube el ajuste.
+- `selectBestAvailable(n)` pide de 1 a 100 plazas, y nunca más que `maxHoldPerToken` (si no, `hold-limit` antes de
+  buscar).
+- Un `holdToken` que crea tu servidor con la clave secreta (`POST /api/v1/hold-tokens`) no lleva IP: no cuenta para
+  `hold-limit-ip`. Lo que el comprador retiene con él desde el visor sí cuenta para `hold-limit` y `hold-rate-limited`.
+- Lo que hace tu servidor con la clave secreta (retener, reservar) no tiene ninguno de estos topes.
+
+### Estados propios y marcas (modo «manager»)
+
+En un panel de gestión (modo `"manager"`), `statusStyles` dice cómo se ve cada estado y `marks`, qué plazas libres
+llevan una marca. Se sacan de la API con la clave secreta, así que los pide tu servidor y se los da a la página:
+
+- `marks` es tal cual el `marks` de `GET /api/v1/events/{evento}/marks` (`{ "marks": { "Platea-A-1":
+  "visibilidad-reducida" } }`): objeto → clave del estado.
+- `statusStyles` sale del catálogo de `GET /api/v1/statuses` (`{ statuses, system }`; con `?event={evento}`, solo los
+  que valen para ese evento), pero no es el mismo formato: por la clave de cada estado, `{ name, color, icon }`, y el
+  icono cambia de forma. `{ type: "text", text }` pasa a `{ text }` y `{ type: "image", src }`, a `{ image: src }`;
+  `{ type: "preset", name }` es de la colección del panel, que no se publica: sin icono, o con un trazado tuyo de 24×24
+  (`{ path }`). De `system` (los estados de base que tu espacio ha cambiado), solo los que traen `color`, y nunca
+  `free`. Un estado de base con `color: null` no pasa, así que el visor lo pinta como siempre y también pierde el
+  nombre y el icono propios que le hayas puesto, aunque el panel sí los enseñe (en el modo «manager», «Reservado» en
+  vez de tu «Vendida»). Si los quieres, ponle color propio en el panel. Pasar el catálogo tal cual no compila en
+  TypeScript y, en JavaScript, rompe el pintado.
+
+```ts
+import type { StatusStyle } from "@seatsyoo/vue";
+
+/** Un icono del catálogo de estados (GET /api/v1/statuses). */
+type IconoDeEstado = { type: "preset"; name: string } | { type: "text"; text: string } | { type: "image"; src: string };
+/** Lo que responde GET /api/v1/statuses (lo que hace falta aquí). */
+interface Catalogo {
+  statuses: { key: string; name: string; color: string; icon: IconoDeEstado | null }[];
+  system: { key: string; name: string | null; color: string | null; icon: IconoDeEstado | null }[];
+}
+
+function estilo(name: string | null, color: string, icon: IconoDeEstado | null): StatusStyle {
+  // «preset»: sin icono (o tu trazado de 24×24, { path: "M4 12h16" }).
+  const forma = icon?.type === "text" ? { text: icon.text } : icon?.type === "image" ? { image: icon.src } : null;
+  return { ...(name ? { name } : {}), color, ...(forma ? { icon: forma } : {}) };
+}
+
+/** De GET /api/v1/statuses a la opción statusStyles. */
+export function estilosDeEstados({ statuses, system }: Catalogo): Record<string, StatusStyle> {
+  const estilos: Record<string, StatusStyle> = {};
+  for (const s of statuses) estilos[s.key] = estilo(s.name, s.color, s.icon);
+  // De los de base, solo los que tienen color propio: sin él se quedan como los pinta el visor, también con su nombre
+  // y su icono de siempre (los tuyos se pierden). «free» no se pinta con estilo.
+  for (const s of system) if (s.key !== "free" && s.color) estilos[s.key] = estilo(s.name, s.color, s.icon);
+  return estilos;
+}
+```
+
+Después, `<SeatsyooChart mode="manager" … :status-styles="estilos" :marks="marcas" />`, con `estilos =
+estilosDeEstados(catalogo)` y las marcas tal cual (también reactivas, cambiadas en el sitio).
+
+### Renderizado en el servidor
+
+El visor se monta en `onMounted`: en el servidor el componente pinta solo un `<div>` vacío y en el navegador se
+hidrata y monta el visor. En Nuxt funciona tal cual (también dentro de `<ClientOnly>`, si lo prefieres).
+
+### La vista 3D
+
+No va en el paquete: el visor la descarga de `${server}/sdk/butacas-3d.js` cuando alguien la abre. Si tu web
+tiene una política de seguridad de contenidos (CSP), añade esa dirección a `script-src`, o pasa `:view3d="false"`.
+
+## El diseñador de planos
+
+`<SeatsyooDesigner>` abre en tu web el diseñador de planos de Seatsyoo, para que tus clientes dibujen sus recintos.
+Tu servidor abre una sesión para un plano con su clave secreta (`POST /api/v1/charts/{plano}/designer-sessions`, o
+`charts.designerSession` de `@seatsyoo/node`) y le da el token a tu web:
+
+```vue
+<script setup lang="ts">
+import { SeatsyooDesigner } from "@seatsyoo/vue";
+
+defineProps<{ token: string }>();
+const emit = defineEmits<{ cerrar: [] }>();
+// Tu servidor abre otra sesión del mismo plano y te da el token (aquí, una ruta tuya).
+const pedirToken = (): Promise<string> =>
+  fetch("/mi-api/disenador/teatro", { method: "POST" }).then((r) => r.json()).then((s: { token: string }) => s.token);
+</script>
+
+<template>
+  <SeatsyooDesigner
+    server="https://seatsyoo.example"
+    :token="token"
+    :refresh-token="pedirToken"
+    style="height: 80vh"
+    @publish="({ version }) => console.log('Publicada la versión', version)"
+    @close="emit('cerrar')"
+  />
+</template>
+```
+
+Props: `server`, `token`, `language` y `refreshToken` (pide a tu servidor otro token del mismo plano antes de que
+caduque: sin ella, al caducar deja de guardar). Eventos: `ready`, `save`, `publish`, `close` («←» sale si hay quien
+escuche `@close` al montarse) y `error`. `class`, `style` e `id` van al `<div>`, que necesita alto. Un `token` nuevo se le
+manda sin volver a montarlo; cambiar `server` o `language`, o pasar o quitar `refreshToken`, lo vuelve a montar. Con
+una ref de plantilla, `disenador.value.designer` es el diseñador (`setToken()`, `iframe`). `app.use(SeatsyooPlugin)`
+también lo registra. En el servidor (SSR) pinta solo el `<div>`.
+
+La referencia completa de opciones, avisos y métodos está en la documentación de Seatsyoo (**/docs/visor**, **/docs/disenador** y
+**/docs/frameworks**).
+
+## Licencia
+
+MIT (archivo `LICENSE`). El visor del que depende, `@seatsyoo/visor`, tiene su propia licencia: se usa gratis para
+integrar Seatsyoo.
+
+---
+
+## English summary
+
+`@seatsyoo/vue` is the **Seatsyoo** seating chart viewer as a Vue 3 component (Vue 3.3+, SSR-safe, no template
+compiler needed). It wraps `@seatsyoo/visor` and ships TypeScript types.
+
+```sh
+npm install @seatsyoo/vue
+```
+
+```vue
+<SeatsyooChart
+  ref="chart"
+  server="https://seatsyoo.example"
+  public-key="pk_your_public_key"
+  event="hamlet-2026-11-20"
+  language="en"
+  style="height: 600px"
+  @change="(selection: SelectedObject[]) => (selected = selection)"
+/>
+<!-- chart.value.chart is the mounted SeatingChart: at checkout, send only the event and its holdToken to your server
+     (never the selected keys). -->
+```
+
+- **Embedded designer**: `<SeatsyooDesigner server :token :refresh-token @publish @close style="height: 80vh" />` opens
+  the Seatsyoo chart designer in your website, with a session token your server opens with its secret key
+  (`POST /api/v1/charts/{chart}/designer-sessions`).
+- **Props**: every viewer option except `container` and the callbacks; `class`, `style`, `id` and other attributes
+  go to the wrapping `<div>`. `app.use(SeatsyooPlugin)` registers `<SeatsyooChart>` globally.
+- **Events**: `ready`, `change`, `select`, `deselect`, `error`, `hold-expired`, `hold-token-change`,
+  `floor-change`. They always reach the current listeners; without an `@error` listener, errors go to the console.
+- **Re-mounting**: changing `server`, `publicKey`, `event`, `link`, `document`, `season`, `seasonEvents`,
+  `channels`, `pricing`, `currency`, `locale`, `language`, `maxSelected`, `session`, `holdToken`, `mode`,
+  `showLegend`, `showSelectionBar`, `floor`, `sectors`, `view3d`, `entrance` or `texts` destroys the viewer and mounts a new one (arrays
+  and objects are compared by value). `theme` and `colorBy` are applied live (`setTheme`, `setColorBy`), and so
+  are `statusStyles` and `marks` (`"manager"` mode: `setStatusStyles`, `setMarks`), only when their value changes
+  (compared as data: the prototype doesn't matter and a key set to `undefined` counts as missing; a reactive object
+  changed in place counts too).
+- **Prices**: Seatsyoo does not store prices. Pass yours with `pricing` (per category key, with `currency` and
+  `locale`): the viewer shows them and they come in `price` of each selected object (`null` without `pricing`).
+  `price` is what each unit of `quantity` costs (per place; a whole table, all its chairs), so `price × quantity` adds
+  up to the viewer's total.
+- **Selling**: the page sends your server the event and the `holdToken`, nothing else. At checkout your server asks
+  Seatsyoo what that token holds (`GET /api/v1/events/{event}/statuses?holdToken=…`: `mine: true`, plus `mq` in a
+  standing area with the token's places, which only comes when more than one place is taken there, counting other
+  buyers'; when it is missing, it is 1), prices it (price × places: a whole table counts all its chairs, as in the
+  viewer's total) and stores that list with the order, each object with an explicit quantity
+  (`{ key, quantity: mq ?? 1 }`). Once paid, it books exactly that list (`POST …/actions/book` with
+  `holdToken` and your `orderId`). Never book a list sent by the page: `book` also books free objects, so anyone could
+  add seats they never held. The `@seatsyoo/node` example store (`ejemplo/tienda.ts`) does this; see
+  **/en/docs/integration**.
+- **Hold limits** (errors in the `error` event): `hold-limit` (409, the workspace's "places per buyer",
+  `maxHoldPerToken`, 10 by default, per token and event; a whole table or box counts all its places), `hold-limit-ip` (409, per connection
+  and event: 10% of the capacity, up to 200, never below `maxHoldPerToken`) and `hold-rate-limited` (429, 600 places
+  held per IP every 10 minutes). `max-selected` counts a whole table or box as 1, so keep it at or below
+  `maxHoldPerToken` and expect `hold-limit` with whole tables. `selectBestAvailable(n)` takes 1 to 100 and never more
+  than `maxHoldPerToken`. A `holdToken` your server creates with the secret key has no IP, so it does not count for
+  `hold-limit-ip`, but what the buyer holds with it from the viewer still counts for `hold-limit` and
+  `hold-rate-limited`. Your server's own calls with the secret key have none of these limits.
+- **Custom statuses and marks** (`"manager"` mode): `marks` is the `marks` of `GET /api/v1/events/{event}/marks` as
+  is. `statusStyles` is not the shape of `GET /api/v1/statuses`: per status key, `{ name, color, icon }` with the icon
+  converted (`text` → `{ text }`, `image` → `{ image: src }`, `preset` → no icon or your own 24×24 `{ path }`); from
+  `system`, only entries with a `color`, never `free` (one with `color: null` stays exactly as the viewer draws it:
+  its own name and icon are lost too, even if the panel shows them; give it its own colour if you want them). Both
+  need the secret key: your server fetches them. The `estilosDeEstados` function above does the conversion.
+- **Holds on re-mount**: same event with `session: "continue"` (default) → the new viewer recovers the buyer's
+  held seats. If it can't (another event or season, `server`, `publicKey`, `session: "start"`, a `holdToken`,
+  `"manager"` mode), the component releases them first, like `clearSelection()` (`deselect` and an empty `change`
+  are emitted): switching shows is just changing `event`. Seats held with your own `holdToken` are never released
+  (your server books or releases them, e.g. a multi-show cart), and nothing is released on unmount.
+- **`document`** is not copied: changing it in place goes unnoticed; pass a new object without mutating the old one.
+- **Exposed**: `chart`, the mounted `SeatingChart` (or `null` on the server, before mounting and after unmounting).
+- **Invalid options** don't throw: the `error` event gets `{ code: "invalid-options", message }`.
+- **SSR**: renders an empty `<div>` on the server and mounts the viewer in `onMounted`.
+- **3D view**: downloaded from `${server}/sdk/butacas-3d.js` when opened (allow it in your CSP `script-src`, or
+  pass `:view3d="false"`).
+- Full reference: the Seatsyoo docs at **/en/docs/seat-map** and **/en/docs/frameworks**.
+
+License: MIT. The viewer it depends on, `@seatsyoo/visor`, has its own license (free to use to integrate Seatsyoo).

package/dist/SeatsyooChart.d.ts

@@ -0,0 +1,153 @@
+import { type ChartDocument, type Language, type SeatingChart, type SelectedObject, type StatusStyle, type View3DModule } from "@seatsyoo/visor";
+import { type ComponentOptionsMixin, type DefineComponent, type ExtractPublicPropTypes, type Plugin, type PropType } from "vue";
+import { SeatsyooDesigner } from "./SeatsyooDesigner.js";
+declare const props: {
+    /** URL base del servidor de Seatsyoo, p. ej. https://seatsyoo.example */
+    server: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** Clave pública del espacio (obligatoria salvo con `link` o `document`). */
+    publicKey: StringConstructor;
+    /** Clave del evento. */
+    event: StringConstructor;
+    /** O la clave de un enlace público del plano: solo para ver. */
+    link: StringConstructor;
+    /** O el plano ya cargado: solo para ver. */
+    document: PropType<ChartDocument>;
+    /** O la clave de una temporada (abono). */
+    season: StringConstructor;
+    /** Abono parcial: los eventos de la temporada elegidos. */
+    seasonEvents: PropType<string[]>;
+    /** Canales de venta desde los que se compra. */
+    channels: PropType<string[]>;
+    /**
+     * Los precios que pone tu web, por clave de categoría (`{ platea: 30 }`): el visor los enseña en la ficha, la leyenda
+     * y el total, y salen en `price` de lo elegido. Seatsyoo no guarda precios.
+     */
+    pricing: PropType<Record<string, number>>;
+    /** Moneda de `pricing` (código ISO; si no, euros). */
+    currency: StringConstructor;
+    locale: StringConstructor;
+    language: PropType<Language>;
+    /** Máximo de plazas seleccionables (por defecto 10). */
+    maxSelected: NumberConstructor;
+    /** «continue» (por defecto) recupera la selección al recargar; «start» empieza de cero. */
+    session: PropType<"continue" | "start">;
+    /** Token de retención creado por tu servidor. */
+    holdToken: StringConstructor;
+    /** «buyer» (por defecto) o «manager». */
+    mode: PropType<"buyer" | "manager">;
+    /** Color base de los objetos (se aplica sin volver a montar). */
+    colorBy: PropType<"category" | "channel">;
+    /** Tema (se aplica sin volver a montar). */
+    theme: PropType<"light" | "dark" | "auto">;
+    /**
+     * Solo en el modo «manager»: nombre, color e icono de los estados, por su clave (los propios y los de base que se
+     * quieran cambiar). Se aplica sin volver a montar (setStatusStyles).
+     */
+    statusStyles: PropType<Record<string, StatusStyle>>;
+    /**
+     * Solo en el modo «manager»: marcas sobre plazas que siguen libres, objeto → estado (su aspecto, en `statusStyles`).
+     * Se aplica sin volver a montar (setMarks).
+     */
+    marks: PropType<Record<string, string>>;
+    showLegend: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    showSelectionBar: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /** Planta que se muestra al abrir (id). */
+    floor: StringConstructor;
+    sectors: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /** Botón de vista 3D (por defecto sí). */
+    view3d: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /** Entrada animada al abrirse: el plano se descubre desde el escenario (por defecto, no). */
+    entrance: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /**
+     * Textos del plano que se enseñan cambiados (por ejemplo, traducidos), por el texto tal como está en el plano:
+     * `{ Platea: "Stalls" }`. Solo cambia lo que se ve: claves, selección y eventos siguen siendo los del plano.
+     */
+    texts: PropType<Record<string, string>>;
+    /** Cómo cargar el módulo 3D (por defecto se pide al servidor). */
+    load3d: PropType<() => Promise<View3DModule>>;
+};
+declare const emits: {
+    /** El visor ha cargado el plano y los estados. */
+    ready: (chart: SeatingChart) => boolean;
+    /** La selección ha cambiado. */
+    change: (selection: SelectedObject[]) => boolean;
+    select: (object: SelectedObject) => boolean;
+    deselect: (object: SelectedObject) => boolean;
+    /** Algo ha fallado: `{ code, message }`. Sin oyente, se escribe en la consola. */
+    error: (error: {
+        code: string;
+        message: string;
+    }) => boolean;
+    /** Se acabó el tiempo de la retención (`@hold-expired`). */
+    holdExpired: () => boolean;
+    /** El token de retención ha cambiado (`@hold-token-change`). */
+    holdTokenChange: (token: {
+        token: string;
+        expiresAt: Date;
+    } | null) => boolean;
+    /** Se muestra otra planta (`@floor-change`). */
+    floorChange: (floor: {
+        id: string;
+        name: string;
+    }) => boolean;
+};
+/** Props de SeatsyooChart: las opciones del visor, sin `container` ni los avisos (que son eventos). */
+export type SeatsyooChartProps = ExtractPublicPropTypes<typeof props>;
+/** Lo que expone el componente a una ref de plantilla. */
+export interface SeatsyooChartExposed {
+    /** El visor montado (`getSelection()`, `holdToken`…), o null mientras no hay ninguno. */
+    chart: SeatingChart | null;
+}
+/**
+ * El tipo público del componente, escrito a mano con los parámetros de DefineComponent que no han cambiado desde
+ * Vue 3.3: el que deduce TypeScript lleva los de la versión con que se compila (ShallowRef<T, S>, más
+ * parámetros…), que no existen en las anteriores.
+ */
+export type SeatsyooChartComponent = DefineComponent<typeof props, SeatsyooChartExposed, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, typeof emits>;
+/**
+ * El visor de mapas de asientos de Seatsyoo.
+ *
+ * ```vue
+ * <SeatsyooChart
+ *   ref="plano"
+ *   server="https://seatsyoo.example"
+ *   public-key="pk_tu_clave_publica"
+ *   event="hamlet-2026-11-20"
+ *   style="height: 600px"
+ *   @change="(seleccion) => (elegidas = seleccion)"
+ * />
+ * ```
+ *
+ * Con una ref de plantilla, `plano.value.chart` es el visor montado (`getSelection()`, `holdToken`…), o `null`
+ * mientras no hay ninguno.
+ */
+export declare const SeatsyooChart: SeatsyooChartComponent;
+/** Plugin que registra <SeatsyooChart> y <SeatsyooDesigner> en toda la aplicación: `app.use(SeatsyooPlugin)`. */
+export declare const SeatsyooPlugin: Plugin;
+declare module "vue" {
+    interface GlobalComponents {
+        /** El visor de Seatsyoo (registrado con `app.use(SeatsyooPlugin)`). */
+        SeatsyooChart: typeof SeatsyooChart;
+        /** El diseñador de planos de Seatsyoo (registrado con `app.use(SeatsyooPlugin)`). */
+        SeatsyooDesigner: typeof SeatsyooDesigner;
+    }
+}
+export {};