@seatsyoo/react 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,350 @@
-# Temporary Holding Version
+# @seatsyoo/react
 
-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 React: 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 **React 18 y 19**, con renderizado en el servidor (Next.js, Remix, Astro…) y con `StrictMode`. Las
+props opcionales admiten `undefined` (como las de un `<div>`): con `exactOptionalPropertyTypes`, un componente que lo
+envuelva puede pasarle las suyas tal cual.
+
+*(English summary below.)*
+
+## Instalación
+
+```sh
+npm install @seatsyoo/react
+# o: pnpm add @seatsyoo/react · yarn add @seatsyoo/react
+```
+
+`react` lo pones tú (es una dependencia «peer»); `@seatsyoo/visor` se instala solo.
+
+## Uso
+
+```tsx
+import { SeatsyooChart, type SeatingChart, type SelectedObject } from "@seatsyoo/react";
+import { useRef, useState } from "react";
+
+export function Entradas() {
+  const plano = useRef<SeatingChart>(null);
+  const [seleccion, setSeleccion] = useState<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.current?.holdToken }),
+    });
+  }
+
+  return (
+    <>
+      <SeatsyooChart
+        ref={plano}
+        server="https://seatsyoo.example"     // la dirección de Seatsyoo de tu cuenta
+        publicKey="pk_tu_clave_publica"       // la clave pública de tu espacio
+        event="hamlet-2026-11-20"             // el evento que se vende
+        pricing={{ platea: 30, anfiteatro: 22 }} // opcional: tus precios (Seatsyoo no guarda precios)
+        style={{ height: 600 }}               // el visor ocupa todo el <div>: dale altura
+        onChange={setSeleccion}
+        onHoldExpired={() => alert("Se ha acabado el tiempo: vuelve a elegir.")}
+      />
+      <button disabled={seleccion.length === 0} onClick={comprar}>Comprar</button>
+    </>
+  );
+}
+```
+
+Para probarlo en un proyecto nuevo de Vite:
+
+```sh
+npm create vite@latest entradas -- --template react-ts
+cd entradas
+npm install @seatsyoo/react
+# pon el componente Entradas de arriba en src/App.tsx y arranca con:
+npm run dev
+```
+
+### Props
+
+Todas las opciones del visor (`server`, `publicKey`, `event`, `season`, `link`, `document`, `language`, `theme`,
+`maxSelected`, `pricing`, `channels`, `holdToken`, `mode`, `statusStyles`, `marks`, `view3d`…) y sus avisos (`onReady`, `onChange`,
+`onSelect`, `onDeselect`, `onHoldExpired`, `onHoldTokenChange`, `onFloorChange`, `onError`), con los mismos nombres
+y tipos que en `@seatsyoo/visor`, salvo `container`, que es el propio componente. Además, `className`, `style` e `id`
+del `<div>` que lo contiene.
+
+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"]}` en cada render no lo vuelve a montar. El plano (`document`), no: ver abajo. |
+| `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 en cada render no hace nada. Lo que cambies en el sitio en el objeto que ya pasaste se aplica en el siguiente render del componente, no antes (cambiar el estado y llamar a `setState` con el mismo objeto no vuelve a pintar): mejor pasa un objeto nuevo, como con el estado de React. Quitarlas es dejar el visor sin estilos ni marcas. |
+| `onChange`, `onSelect`… | Nada: el visor llama siempre a la última función que hayas pasado. No hace falta `useCallback`. |
+| `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, como harías con el estado de React.
+
+**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()`: te llegan `onDeselect` y `onChange([])`, 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 `onChange`, `onSelect`… (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.
+
+### La ref
+
+Con `ref` tienes 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. Se pone en el mismo efecto que
+monta el visor: tus efectos (`useEffect`) y `onReady` ya lo tienen. Si cambia una opción que lo vuelve a montar,
+la ref pasa a ser el visor nuevo antes de que se ejecuten tus efectos de ese cambio.
+
+### Errores
+
+Lo que falla al cargar o al retener llega a `onError` como `{ code, message }` (sin `onError`, a la consola). Si
+faltan opciones para montarlo (qué enseñar, la clave pública…), el componente no lanza: llama a `onError` con
+`code: "invalid-options"` (sin `onError`, 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 `onError`:
+
+| 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). |
+
+- `maxSelected` cuenta una mesa o un palco enteros como 1, y el servidor, con todas sus plazas: con
+  `maxSelected` y `maxHoldPerToken` en 10, dos mesas de 8 dan `hold-limit`. No pongas `maxSelected` 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/react";
+
+/** 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" … statusStyles={estilos} marks={marcas} />`, con `estilos =
+estilosDeEstados(catalogo)` y las marcas tal cual; para cambiarlos, pasa objetos nuevos.
+
+### Renderizado en el servidor y StrictMode
+
+El visor se monta en un efecto: en el servidor el componente pinta solo un `<div>` vacío (con tu `className`,
+`style` e `id`) y en el navegador se hidrata y monta el visor. Con `StrictMode`, React monta, desmonta y vuelve a
+montar: el primer visor se destruye al momento (sin avisos ni retenciones) y queda uno.
+
+En Next.js (App Router), úsalo dentro de un componente con `"use client"`.
+
+### 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:
+
+```tsx
+import { SeatsyooDesigner } from "@seatsyoo/react";
+
+// Tu servidor abre la sesión 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);
+
+function Disenador({ token, cerrar }: { token: string; cerrar: () => void }) {
+  return (
+    <SeatsyooDesigner
+      server="https://seatsyoo.example"
+      token={token}
+      refreshToken={pedirToken}
+      style={{ height: "80vh" }}
+      onPublish={({ version }) => console.log("Publicada la versión", version)}
+      onClose={cerrar}
+    />
+  );
+}
+```
+
+Props: `server`, `token`, `language`, `refreshToken` (pide a tu servidor otro token del mismo plano antes de que
+caduque: sin ella, al caducar deja de guardar), y los avisos `onReady`, `onSave`, `onPublish`, `onClose` (sin ella no
+sale «←») y `onError`; más `className`, `style` e `id` del `<div>`, que necesita alto. Un `token` nuevo se le manda sin
+volver a montarlo; cambiar `server` o `language`, o pasar o quitar `refreshToken` u `onClose`, lo vuelve a montar. Con
+`ref` (`useRef<EmbeddedDesigner>(null)`) tienes el diseñador: `setToken()`, `iframe`. 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/react` is the **Seatsyoo** seating chart viewer as a React component (React 18 and 19, SSR-safe,
+StrictMode-safe). It wraps `@seatsyoo/visor` and ships TypeScript types.
+
+```sh
+npm install @seatsyoo/react
+```
+
+```tsx
+import { SeatsyooChart, type SeatingChart } from "@seatsyoo/react";
+
+const chart = useRef<SeatingChart>(null);
+
+<SeatsyooChart
+  ref={chart}
+  server="https://seatsyoo.example"
+  publicKey="pk_your_public_key"
+  event="hamlet-2026-11-20"
+  language="en"
+  style={{ height: 600 }}
+  onChange={(selection) => console.log(selection.map((o) => o.key))}
+/>;
+// At checkout, send only the event and chart.current.holdToken to your server (never the selected keys).
+```
+
+- **Embedded designer**: `<SeatsyooDesigner server token refreshToken onPublish onClose 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`, plus `className`, `style` and `id` for the wrapping `<div>`.
+- **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 change made in
+  place is applied on the component's next render, not before: better pass a new object.
+- **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 `onError`): `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). `maxSelected` 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()` (you get `onDeselect` and
+  `onChange([])`): 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.
+- **Callbacks** (`onChange`, `onSelect`, `onReady`, `onError`…) always call the latest function you passed; no
+  `useCallback` needed.
+- **ref** gives the mounted `SeatingChart` (or `null` on the server, before mounting and after unmounting); it is
+  set in the same effect that mounts the viewer, so your effects and `onReady` already see it.
+- **Types**: optional props also accept `undefined`, so wrappers can forward their own optional props even with
+  `exactOptionalPropertyTypes`.
+- **Invalid options** don't throw: `onError` gets `{ code: "invalid-options", message }`.
+- **SSR**: renders an empty `<div>` on the server and mounts the viewer in an effect in the browser. In Next.js App
+  Router, use it from a `"use client"` component.
+- **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,36 @@
+import { type RenderOptions, type SeatingChart } from "@seatsyoo/visor";
+import { type CSSProperties, type ForwardRefExoticComponent, type RefAttributes } from "react";
+/**
+ * Las opciones opcionales admiten también `undefined` (como un <div>): con `exactOptionalPropertyTypes`, un
+ * componente que envuelve a este puede pasarle sus props opcionales tal cual (`event={props.event}`). `undefined`
+ * es lo mismo que no pasarla.
+ */
+type AdmitenUndefined<T> = {
+    [K in keyof T]: {} extends Pick<T, K> ? T[K] | undefined : T[K];
+};
+/** Props de <SeatsyooChart>: las opciones del visor (sin `container`: es el propio componente) y las del <div>. */
+export interface SeatsyooChartProps extends AdmitenUndefined<Omit<RenderOptions, "container">> {
+    /** Clase del <div> que contiene el visor. El visor ocupa todo su tamaño: dale altura. */
+    className?: string | undefined;
+    /** Estilo del <div> que contiene el visor (p. ej. `{ height: 600 }`). */
+    style?: CSSProperties | undefined;
+    id?: string | undefined;
+}
+/**
+ * El visor de mapas de asientos de Seatsyoo.
+ *
+ * ```tsx
+ * <SeatsyooChart
+ *   server="https://seatsyoo.example"
+ *   publicKey="pk_tu_clave_publica"
+ *   event="hamlet-2026-11-20"
+ *   style={{ height: 600 }}
+ *   onChange={(seleccion) => setSeleccion(seleccion)}
+ * />
+ * ```
+ *
+ * Con `ref` (`useRef<SeatingChart>(null)`) tienes el visor montado: `getSelection()`, `holdToken`,
+ * `clearSelection()`… (`null` mientras no hay ninguno).
+ */
+export declare const SeatsyooChart: ForwardRefExoticComponent<SeatsyooChartProps & RefAttributes<SeatingChart>>;
+export {};

package/dist/SeatsyooChart.js

@@ -0,0 +1,161 @@
+// <SeatsyooChart>: el visor de Seatsyoo como componente de React (18 y 19).
+//
+// - Se monta en un efecto: en el servidor (SSR) solo se pinta el <div> vacío, y con StrictMode (que monta,
+//   desmonta y vuelve a montar) el primer visor se destruye antes de hacer nada visible: queda uno.
+// - Al desmontar, destroy().
+// - Si cambia una opción de identidad (OPCIONES_DE_IDENTIDAD, por valor), se destruye y se monta otro. Si el nuevo
+//   no va a recuperar lo que el comprador tenía retenido (otro evento…), antes se suelta (sueltaAlCambiar).
+// - theme y colorBy se aplican al visor montado (setTheme, setColorBy); statusStyles y marks (modo «manager»),
+//   también, comparadas por valor (setStatusStyles, setMarks).
+// - Los avisos (onChange, onSelect…) llaman siempre a la última función recibida, sin volver a montar.
+// - La ref se pone en el mismo efecto que monta el visor (y se quita al destruirlo): el efecto del padre y onReady
+//   ya la tienen.
+import { render } from "@seatsyoo/visor";
+import { createElement, forwardRef, useEffect, useLayoutEffect, useRef, version, } from "react";
+import { aplicarEnVivo, avisarEnConsola, enVivoDe, errorDeOpciones, identidadDe, igual, opcionesEnVivo, sinIndefinidos, sueltaAlCambiar, } from "./opciones.js";
+// useLayoutEffect no hace nada en el servidor (y React 18 avisa): allí, useEffect, que tampoco se ejecuta.
+const useEfectoAntesDePintar = typeof document === "undefined" ? useEffect : useLayoutEffect;
+/**
+ * La identidad de este render, o la del último render confirmado si es igual por valor: así un array nuevo
+ * con lo mismo no cambia la dependencia del efecto que monta. Solo se lee la referencia durante el render; se
+ * escribe después de confirmar (un render descartado no cuenta).
+ */
+function useIdentidadEstable(actual) {
+    const confirmada = useRef(actual);
+    const estable = igual(confirmada.current, actual) ? confirmada.current : actual;
+    useEffect(() => {
+        confirmada.current = estable;
+    });
+    return estable;
+}
+/** React 19 llama a la limpieza que devuelve una ref de función en lugar de llamarla con null; React 18, no. */
+const REFS_CON_LIMPIEZA = Number(version.split(".")[0]) >= 19;
+/**
+ * Pone el visor en la ref de quien usa el componente (un objeto de useRef o una función) y devuelve cómo quitarlo,
+ * como lo haría React con la ref de un elemento.
+ */
+function ponerEnRef(ref, plano) {
+    if (typeof ref === "function") {
+        const limpieza = ref(plano);
+        return REFS_CON_LIMPIEZA && typeof limpieza === "function" ? limpieza : () => ref(null);
+    }
+    if (ref)
+        ref.current = plano;
+    return () => {
+        if (ref && ref.current === plano)
+            ref.current = null;
+    };
+}
+function SeatsyooChartConRef(props, ref) {
+    const { className, style, id, ...opciones } = props;
+    const contenedor = useRef(null);
+    // Las últimas opciones recibidas: los avisos y el montaje leen de aquí.
+    const ultimas = useRef(opciones);
+    // El visor montado ahora mismo y las opciones en vivo con que se montó o se dejó (para setTheme, setColorBy…).
+    const visor = useRef(null);
+    // La ref de quien usa el componente en la que está puesto el visor, y cómo quitarlo de ella.
+    const enRef = useRef(null);
+    // false desde que React quita (o esconde) el componente: el visor se destruye entonces sin soltar nada, para
+    // que lo recupere el que se monte después (o tu servidor lo reserve con el token).
+    const presente = useRef(false);
+    useEfectoAntesDePintar(() => {
+        ultimas.current = opciones;
+    });
+    useEfectoAntesDePintar(() => {
+        presente.current = true;
+        return () => {
+            presente.current = false;
+        };
+    }, []);
+    function quitarDeRef() {
+        const actual = enRef.current;
+        enRef.current = null;
+        actual?.quitar();
+    }
+    function ponerVisorEnRef(r, plano) {
+        if (enRef.current?.ref === r && enRef.current.plano === plano)
+            return;
+        quitarDeRef();
+        enRef.current = { ref: r, plano, quitar: ponerEnRef(r, plano) };
+    }
+    const identidad = useIdentidadEstable(identidadDe(opciones));
+    useEffect(() => {
+        const div = contenedor.current;
+        if (!div)
+            return;
+        const o = ultimas.current;
+        const load3d = o.load3d;
+        // Con copias de statusStyles y marks: lo que se compara después y lo que tiene el visor no es el objeto de la página.
+        const enVivo = enVivoDe(o);
+        let nuevo;
+        try {
+            nuevo = render({
+                ...sinIndefinidos(o),
+                ...opcionesEnVivo(o, enVivo),
+                container: div,
+                onReady: (c) => ultimas.current.onReady?.(c),
+                onChange: (s) => ultimas.current.onChange?.(s),
+                onSelect: (x) => ultimas.current.onSelect?.(x),
+                onDeselect: (x) => ultimas.current.onDeselect?.(x),
+                onHoldExpired: () => ultimas.current.onHoldExpired?.(),
+                onHoldTokenChange: (t) => ultimas.current.onHoldTokenChange?.(t),
+                onFloorChange: (f) => ultimas.current.onFloorChange?.(f),
+                onError: (e) => (ultimas.current.onError ?? avisarEnConsola)(e),
+                // Solo si hay load3d (si no, el visor pide la 3D al servidor); quitarlo o ponerlo cambia la identidad.
+                ...(load3d ? { load3d: () => (ultimas.current.load3d ?? load3d)() } : {}),
+            });
+        }
+        catch (err) {
+            const error = errorDeOpciones(err);
+            if (o.onError)
+                o.onError(error);
+            else
+                console.error("[seatsyoo]", error.message);
+            return;
+        }
+        visor.current = { plano: nuevo, enVivo };
+        ponerVisorEnRef(ref, nuevo);
+        return () => {
+            // Si es porque cambia una opción de identidad (el componente sigue), las opciones nuevas ya están en
+            // `ultimas` (se guardan antes de pintar, y este efecto va después).
+            if (presente.current && sueltaAlCambiar(identidad, identidadDe(ultimas.current)))
+                void nuevo.clearSelection();
+            if (enRef.current?.plano === nuevo)
+                quitarDeRef();
+            nuevo.destroy();
+            if (visor.current?.plano === nuevo)
+                visor.current = null;
+        };
+    }, [identidad]);
+    // Si cambia la ref (otra función u otro objeto), el visor pasa a la nueva y se quita de la anterior.
+    useEffect(() => {
+        if (visor.current)
+            ponerVisorEnRef(ref, visor.current.plano);
+    }, [ref]);
+    // Después del efecto que monta: si en el mismo cambio se montó otro, ya lleva lo nuevo y no se toca. En cada render
+    // (sin dependencias): statusStyles y marks se comparan por valor con lo aplicado, también si se cambian en el sitio.
+    useEffect(() => {
+        const v = visor.current;
+        if (v)
+            aplicarEnVivo(v.plano, v.enVivo, opciones);
+    });
+    return createElement("div", { ref: contenedor, className, style, id });
+}
+/**
+ * El visor de mapas de asientos de Seatsyoo.
+ *
+ * ```tsx
+ * <SeatsyooChart
+ *   server="https://seatsyoo.example"
+ *   publicKey="pk_tu_clave_publica"
+ *   event="hamlet-2026-11-20"
+ *   style={{ height: 600 }}
+ *   onChange={(seleccion) => setSeleccion(seleccion)}
+ * />
+ * ```
+ *
+ * Con `ref` (`useRef<SeatingChart>(null)`) tienes el visor montado: `getSelection()`, `holdToken`,
+ * `clearSelection()`… (`null` mientras no hay ninguno).
+ */
+export const SeatsyooChart = forwardRef(SeatsyooChartConRef);
+SeatsyooChart.displayName = "SeatsyooChart";

package/dist/SeatsyooDesigner.d.ts

@@ -0,0 +1,33 @@
+import { type EmbeddedDesigner, type EmbeddedDesignerOptions } from "@seatsyoo/visor";
+import { type CSSProperties, type ForwardRefExoticComponent, type RefAttributes } from "react";
+/** Como en <SeatsyooChart>: las opciones opcionales admiten también `undefined`, que es lo mismo que no pasarlas. */
+type AdmitenUndefined<T> = {
+    [K in keyof T]: {} extends Pick<T, K> ? T[K] | undefined : T[K];
+};
+/** Props de <SeatsyooDesigner>: las opciones del diseñador (sin `container`: es el propio componente) y las del <div>. */
+export interface SeatsyooDesignerProps extends AdmitenUndefined<Omit<EmbeddedDesignerOptions, "container">> {
+    /** Clase del <div> que contiene el diseñador. Ocupa todo su tamaño: dale altura. */
+    className?: string | undefined;
+    /** Estilo del <div> que contiene el diseñador (p. ej. `{ height: "80vh" }`). */
+    style?: CSSProperties | undefined;
+    id?: string | undefined;
+}
+/**
+ * El diseñador de planos de Seatsyoo en tu web, con el token de una sesión que abre tu servidor con su clave secreta
+ * (`POST /api/v1/charts/{plano}/designer-sessions`, o `charts.designerSession` de `@seatsyoo/node`).
+ *
+ * ```tsx
+ * <SeatsyooDesigner
+ *   server="https://seatsyoo.example"
+ *   token={token}
+ *   refreshToken={pedirToken}
+ *   style={{ height: "80vh" }}
+ *   onPublish={({ version }) => console.log("Publicada la versión", version)}
+ *   onClose={() => setAbierto(false)}
+ * />
+ * ```
+ *
+ * Con `ref` (`useRef<EmbeddedDesigner>(null)`) tienes el diseñador abierto: `setToken()`, `iframe`…
+ */
+export declare const SeatsyooDesigner: ForwardRefExoticComponent<SeatsyooDesignerProps & RefAttributes<EmbeddedDesigner>>;
+export {};

package/dist/SeatsyooDesigner.js

@@ -0,0 +1,132 @@
+// <SeatsyooDesigner>: el diseñador de planos de Seatsyoo, incrustado en tu web, como componente de React (18 y 19).
+//
+// - Se monta en un efecto: en el servidor (SSR) solo se pinta el <div> vacío, y con StrictMode (que monta, desmonta y
+//   vuelve a montar) el primero se destruye antes de abrir nada: queda uno. Al desmontar, destroy().
+// - Vuelve a montarse si cambia `server` o `language`, o si se pasa o se quita `refreshToken` u `onClose`: la página del
+//   diseñador sabe al abrirse si puede pedir tokens nuevos y si sale «←».
+// - Un `token` nuevo con el diseñador abierto no lo vuelve a montar: se le manda (setToken), como al renovarlo.
+// - Los avisos (onReady, onSave…) y refreshToken llaman siempre a la última función recibida, sin volver a montar.
+import { designer } from "@seatsyoo/visor";
+import { createElement, forwardRef, useEffect, useLayoutEffect, useRef, version, } from "react";
+import { avisarEnConsola, errorDeOpciones } from "./opciones.js";
+// useLayoutEffect no hace nada en el servidor (y React 18 avisa): allí, useEffect, que tampoco se ejecuta.
+const useEfectoAntesDePintar = typeof document === "undefined" ? useEffect : useLayoutEffect;
+/** React 19 llama a la limpieza que devuelve una ref de función en lugar de llamarla con null; React 18, no. */
+const REFS_CON_LIMPIEZA = Number(version.split(".")[0]) >= 19;
+/** Pone el diseñador en la ref de quien usa el componente y devuelve cómo quitarlo, como React con la de un elemento. */
+function ponerEnRef(ref, d) {
+    if (typeof ref === "function") {
+        const limpieza = ref(d);
+        return REFS_CON_LIMPIEZA && typeof limpieza === "function" ? limpieza : () => ref(null);
+    }
+    if (ref)
+        ref.current = d;
+    return () => {
+        if (ref && ref.current === d)
+            ref.current = null;
+    };
+}
+function SeatsyooDesignerConRef(props, ref) {
+    const { className, style, id, ...opciones } = props;
+    const contenedor = useRef(null);
+    // Las últimas opciones recibidas: los avisos y el montaje leen de aquí.
+    const ultimas = useRef(opciones);
+    // El diseñador abierto ahora mismo y el último token que se le dio.
+    const abierto = useRef(null);
+    // La ref en la que está puesto y cómo quitarlo de ella.
+    const enRef = useRef(null);
+    useEfectoAntesDePintar(() => {
+        ultimas.current = opciones;
+    });
+    function quitarDeRef() {
+        const actual = enRef.current;
+        enRef.current = null;
+        actual?.quitar();
+    }
+    function ponerDisenadorEnRef(r, d) {
+        if (enRef.current?.ref === r && enRef.current.d === d)
+            return;
+        quitarDeRef();
+        enRef.current = { ref: r, d, quitar: ponerEnRef(r, d) };
+    }
+    const renueva = !!opciones.refreshToken;
+    const cierra = !!opciones.onClose;
+    useEffect(() => {
+        const div = contenedor.current;
+        if (!div)
+            return;
+        const o = ultimas.current;
+        let d;
+        try {
+            d = designer({
+                container: div,
+                server: o.server,
+                token: o.token,
+                ...(o.language ? { language: o.language } : {}),
+                // Solo si los hay: la página del diseñador sabe al abrirse si puede pedir tokens y si sale «←».
+                ...(o.refreshToken ? { refreshToken: () => (ultimas.current.refreshToken ?? o.refreshToken)() } : {}),
+                ...(o.onClose ? { onClose: () => ultimas.current.onClose?.() } : {}),
+                onReady: (i) => ultimas.current.onReady?.(i),
+                onSave: (i) => ultimas.current.onSave?.(i),
+                onPublish: (i) => ultimas.current.onPublish?.(i),
+                onError: (e) => (ultimas.current.onError ?? avisarEnConsola)(e),
+            });
+        }
+        catch (err) {
+            // Un token que no es de una sesión del diseñador, un contenedor que falta…
+            const error = errorDeOpciones(err);
+            if (o.onError)
+                o.onError(error);
+            else
+                console.error("[seatsyoo]", error.message);
+            return;
+        }
+        abierto.current = { d, token: o.token };
+        ponerDisenadorEnRef(ref, d);
+        return () => {
+            if (enRef.current?.d === d)
+                quitarDeRef();
+            d.destroy();
+            if (abierto.current?.d === d)
+                abierto.current = null;
+        };
+    }, [opciones.server, opciones.language, renueva, cierra]);
+    // Si cambia la ref (otra función u otro objeto), el diseñador pasa a la nueva y se quita de la anterior.
+    useEffect(() => {
+        if (abierto.current)
+            ponerDisenadorEnRef(ref, abierto.current.d);
+    }, [ref]);
+    // Un token nuevo, al diseñador abierto (si se acaba de montar con él, ya lo tiene).
+    useEffect(() => {
+        const a = abierto.current;
+        if (!a || a.token === opciones.token)
+            return;
+        try {
+            a.d.setToken(opciones.token);
+            a.token = opciones.token;
+        }
+        catch (err) {
+            (ultimas.current.onError ?? avisarEnConsola)(errorDeOpciones(err));
+        }
+    }, [opciones.token]);
+    return createElement("div", { ref: contenedor, className, style, id });
+}
+/**
+ * El diseñador de planos de Seatsyoo en tu web, con el token de una sesión que abre tu servidor con su clave secreta
+ * (`POST /api/v1/charts/{plano}/designer-sessions`, o `charts.designerSession` de `@seatsyoo/node`).
+ *
+ * ```tsx
+ * <SeatsyooDesigner
+ *   server="https://seatsyoo.example"
+ *   token={token}
+ *   refreshToken={pedirToken}
+ *   style={{ height: "80vh" }}
+ *   onPublish={({ version }) => console.log("Publicada la versión", version)}
+ *   onClose={() => setAbierto(false)}
+ * />
+ * ```
+ *
+ * Con `ref` (`useRef<EmbeddedDesigner>(null)`) tienes el diseñador abierto: `setToken()`, `iframe`…
+ */
+export const SeatsyooDesigner = forwardRef(SeatsyooDesignerConRef);
+SeatsyooDesigner.displayName = "SeatsyooDesigner";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SeatsyooChart, type SeatsyooChartProps } from "./SeatsyooChart.js";
+export { SeatsyooDesigner, type SeatsyooDesignerProps } from "./SeatsyooDesigner.js";
+export type { ChartDocument, EmbeddedDesigner, EmbeddedDesignerOptions, Language, RenderOptions, SeatingChart, SelectedObject, StatusStyle, } from "@seatsyoo/visor";

package/dist/index.js

@@ -0,0 +1,3 @@
+// @seatsyoo/react: el visor de mapas de asientos de Seatsyoo y su diseñador de planos como componentes de React.
+export { SeatsyooChart } from "./SeatsyooChart.js";
+export { SeatsyooDesigner } from "./SeatsyooDesigner.js";

package/dist/opciones.d.ts

@@ -0,0 +1,99 @@
+import type { RenderOptions, SeatingChart } from "@seatsyoo/visor";
+/**
+ * Opciones que, si cambian, vuelven a montar el visor: deciden qué se carga y cómo se vende. Los arrays y los
+ * objetos se comparan por su valor, no por la referencia: `channels={["web"]}` en cada render no remonta.
+ */
+export declare const OPCIONES_DE_IDENTIDAD: readonly ["server", "publicKey", "event", "link", "document", "season", "seasonEvents", "channels", "pricing", "currency", "locale", "language", "maxSelected", "session", "holdToken", "mode", "showLegend", "showSelectionBar", "floor", "sectors", "view3d", "entrance", "texts"];
+/**
+ * Opciones que se aplican al visor ya montado, sin volver a montarlo: theme y colorBy (setTheme y setColorBy) y, para
+ * el modo «manager», los estilos de los estados y las marcas sobre plazas libres (setStatusStyles y setMarks). Se
+ * comparan por valor, como las de identidad: un objeto nuevo con lo mismo no llama a nada.
+ */
+export declare const OPCIONES_EN_VIVO: readonly ["theme", "colorBy", "statusStyles", "marks"];
+/** Avisos del visor: siempre llaman a la última función recibida, sin volver a montar. */
+export declare const AVISOS: readonly ["onReady", "onChange", "onSelect", "onDeselect", "onError", "onHoldExpired", "onHoldTokenChange", "onFloorChange"];
+type ClaveDeIdentidad = (typeof OPCIONES_DE_IDENTIDAD)[number];
+/**
+ * Cada opción del visor tiene aquí su regla (vuelve a montar, se aplica en vivo o es un aviso). Si el visor gana una
+ * opción nueva, esto deja de compilar hasta decidir qué hace el componente con ella: pasó con `entrance` y `texts`,
+ * que llegaron al visor sin que el componente las pasara, y con `statusStyles` y `marks` (en vivo: el visor tiene
+ * setStatusStyles y setMarks).
+ */
+type SinRegla = Exclude<keyof RenderOptions, ClaveDeIdentidad | (typeof OPCIONES_EN_VIVO)[number] | (typeof AVISOS)[number] | "container" | "load3d">;
+type DebeSerNever<T extends never> = T;
+export type TodasLasOpcionesTienenRegla = DebeSerNever<SinRegla>;
+/**
+ * Lo que identifica a un visor montado: las opciones de identidad (copiando arrays y objetos pequeños, para que
+ * cambiarlos en el sitio también cuente) y si hay `load3d` (la función en sí puede cambiar sin remontar: se
+ * llama siempre a la última).
+ */
+export type Identidad = {
+    [K in ClaveDeIdentidad]: RenderOptions[K];
+} & {
+    load3d: boolean;
+};
+export declare function identidadDe(opciones: Partial<RenderOptions>): Identidad;
+/** Igualdad por valor de datos tipo JSON (cadenas, números, booleanos, null, undefined, arrays y objetos). */
+export declare function igual(a: unknown, b: unknown): boolean;
+/**
+ * Copia normalizada de datos tipo JSON (listas y objetos, a cualquier profundidad): los objetos salen con
+ * Object.prototype (también un diccionario hecho con `Object.create(null)`) y sin las claves que valen `undefined`
+ * (`{ color, icon: undefined }` es lo mismo que `{ color }`: el visor no pinta icono en los dos casos).
+ *
+ * Es la regla de statusStyles y marks, la misma en React, Vue y Angular: lo aplicado en vivo se guarda así copiado, lo
+ * que llega se copia igual antes de compararlo, y el visor recibe esa copia. Así cambiarlo en el sitio también cuenta y
+ * el visor no comparte el objeto de la página (setMarks repinta lo que difiere de lo que tenía, y si fuera el mismo
+ * objeto ya cambiado no vería nada).
+ */
+export declare function copiaDeDatos<T>(valor: T): T;
+/** Con qué valor de cada opción en vivo se montó el visor o se le cambió después (sin indicar, el de por defecto). */
+export interface EnVivo {
+    theme: NonNullable<RenderOptions["theme"]>;
+    colorBy: NonNullable<RenderOptions["colorBy"]>;
+    statusStyles: NonNullable<RenderOptions["statusStyles"]>;
+    marks: NonNullable<RenderOptions["marks"]>;
+}
+/**
+ * Las opciones en vivo con que se monta un visor. Sin theme ni colorBy, los del visor por defecto; sin statusStyles ni
+ * marks, ninguno (`{}`, que para el visor es lo mismo que no pasarlas).
+ */
+export declare function enVivoDe(opciones: Partial<RenderOptions>): EnVivo;
+/** Lo que hay que añadir a las opciones de `render` para montar con estas opciones en vivo (las copias guardadas). */
+export declare function opcionesEnVivo(opciones: Partial<RenderOptions>, enVivo: EnVivo): Partial<RenderOptions>;
+/** Los métodos del visor con que se aplican las opciones en vivo. */
+export type VisorEnVivo = Pick<SeatingChart, "setTheme" | "setColorBy" | "setStatusStyles" | "setMarks">;
+/**
+ * Lleva al visor montado las opciones en vivo que han cambiado (por valor) desde `aplicadas`, y las apunta en
+ * `aplicadas`. Quitar una es volver a la de por defecto: el tema claro, el color por categoría, sin estilos ni marcas.
+ */
+export declare function aplicarEnVivo(visor: VisorEnVivo, aplicadas: EnVivo, opciones: Partial<RenderOptions>): void;
+/** Las opciones sin las que valen `undefined` (el visor usa entonces su valor por defecto). */
+export declare function sinIndefinidos<T extends object>(opciones: T): T;
+/** Lo que hace el visor con un error si nadie escucha `onError`: escribirlo en la consola. */
+export declare function avisarEnConsola(error: {
+    code: string;
+    message: string;
+}): void;
+/**
+ * `render` lanza si faltan opciones (qué enseñar, la clave pública…). En un componente no hay quien lo
+ * recoja, así que se convierte en un error con el código `invalid-options`.
+ */
+export declare function errorDeOpciones(err: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * Al volver a montar (cambia una opción de identidad), ¿hay que soltar lo que el comprador tiene retenido en el
+ * visor que se va?
+ *
+ * destroy() no suelta lo retenido: así el visor que se monte después en el mismo evento lo recupera (con
+ * `session: "continue"`, guarda su token en sessionStorage). Pero si el nuevo no lo va a recuperar (otro evento u
+ * otra temporada, otro servidor o clave pública, `session: "start"`, un `holdToken` nuevo, modo «manager»), esas
+ * plazas se quedarían bloqueadas para los demás hasta que caduque la retención, sin que la página pueda venderlas
+ * ni soltarlas: el comprador ya no las ve y el token del visor nuevo es otro. Entonces se sueltan.
+ *
+ * Lo retenido con un `holdToken` de la página no se suelta nunca: es de su token y lo lleva su servidor (por
+ * ejemplo, un carrito con varias funciones). Tampoco hay nada que soltar en el modo «manager» ni al solo ver.
+ */
+export declare function sueltaAlCambiar(antes: Identidad, despues: Identidad): boolean;
+export {};

package/dist/opciones.js

@@ -0,0 +1,210 @@
+/**
+ * Opciones que, si cambian, vuelven a montar el visor: deciden qué se carga y cómo se vende. Los arrays y los
+ * objetos se comparan por su valor, no por la referencia: `channels={["web"]}` en cada render no remonta.
+ */
+export const OPCIONES_DE_IDENTIDAD = [
+    "server",
+    "publicKey",
+    "event",
+    "link",
+    "document",
+    "season",
+    "seasonEvents",
+    "channels",
+    "pricing",
+    "currency",
+    "locale",
+    "language",
+    "maxSelected",
+    "session",
+    "holdToken",
+    "mode",
+    "showLegend",
+    "showSelectionBar",
+    "floor",
+    "sectors",
+    "view3d",
+    "entrance",
+    "texts",
+];
+/**
+ * Opciones que se aplican al visor ya montado, sin volver a montarlo: theme y colorBy (setTheme y setColorBy) y, para
+ * el modo «manager», los estilos de los estados y las marcas sobre plazas libres (setStatusStyles y setMarks). Se
+ * comparan por valor, como las de identidad: un objeto nuevo con lo mismo no llama a nada.
+ */
+export const OPCIONES_EN_VIVO = ["theme", "colorBy", "statusStyles", "marks"];
+/** Avisos del visor: siempre llaman a la última función recibida, sin volver a montar. */
+export const AVISOS = [
+    "onReady",
+    "onChange",
+    "onSelect",
+    "onDeselect",
+    "onError",
+    "onHoldExpired",
+    "onHoldTokenChange",
+    "onFloorChange",
+];
+export function identidadDe(opciones) {
+    const identidad = { load3d: typeof opciones.load3d === "function" };
+    for (const clave of OPCIONES_DE_IDENTIDAD) {
+        const valor = opciones[clave];
+        // El plano puede ser muy grande: no se copia (se compara por valor solo si llega otro objeto).
+        identidad[clave] = clave === "document" ? valor : copiaSuperficial(valor);
+    }
+    return identidad;
+}
+function copiaSuperficial(valor) {
+    if (Array.isArray(valor))
+        return [...valor];
+    if (valor !== null && typeof valor === "object")
+        return { ...valor };
+    return valor;
+}
+/** Igualdad por valor de datos tipo JSON (cadenas, números, booleanos, null, undefined, arrays y objetos). */
+export function igual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!igual(a[i], b[i]))
+                return false;
+        return true;
+    }
+    if (Array.isArray(b))
+        return false;
+    const x = a;
+    const y = b;
+    const claves = Object.keys(x);
+    if (claves.length !== Object.keys(y).length)
+        return false;
+    for (const k of claves) {
+        if (!Object.prototype.hasOwnProperty.call(y, k) || !igual(x[k], y[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Copia normalizada de datos tipo JSON (listas y objetos, a cualquier profundidad): los objetos salen con
+ * Object.prototype (también un diccionario hecho con `Object.create(null)`) y sin las claves que valen `undefined`
+ * (`{ color, icon: undefined }` es lo mismo que `{ color }`: el visor no pinta icono en los dos casos).
+ *
+ * Es la regla de statusStyles y marks, la misma en React, Vue y Angular: lo aplicado en vivo se guarda así copiado, lo
+ * que llega se copia igual antes de compararlo, y el visor recibe esa copia. Así cambiarlo en el sitio también cuenta y
+ * el visor no comparte el objeto de la página (setMarks repinta lo que difiere de lo que tenía, y si fuera el mismo
+ * objeto ya cambiado no vería nada).
+ */
+export function copiaDeDatos(valor) {
+    if (Array.isArray(valor))
+        return valor.map((v) => copiaDeDatos(v));
+    if (valor !== null && typeof valor === "object") {
+        const entradas = Object.entries(valor).filter(([, v]) => v !== undefined);
+        return Object.fromEntries(entradas.map(([k, v]) => [k, copiaDeDatos(v)]));
+    }
+    return valor;
+}
+/**
+ * Las opciones en vivo con que se monta un visor. Sin theme ni colorBy, los del visor por defecto; sin statusStyles ni
+ * marks, ninguno (`{}`, que para el visor es lo mismo que no pasarlas).
+ */
+export function enVivoDe(opciones) {
+    return {
+        theme: opciones.theme ?? "light",
+        colorBy: opciones.colorBy ?? "category",
+        statusStyles: copiaDeDatos(opciones.statusStyles ?? {}),
+        marks: copiaDeDatos(opciones.marks ?? {}),
+    };
+}
+/** Lo que hay que añadir a las opciones de `render` para montar con estas opciones en vivo (las copias guardadas). */
+export function opcionesEnVivo(opciones, enVivo) {
+    return sinIndefinidos({
+        theme: opciones.theme,
+        colorBy: opciones.colorBy,
+        statusStyles: opciones.statusStyles && enVivo.statusStyles,
+        marks: opciones.marks && enVivo.marks,
+    });
+}
+/**
+ * Lleva al visor montado las opciones en vivo que han cambiado (por valor) desde `aplicadas`, y las apunta en
+ * `aplicadas`. Quitar una es volver a la de por defecto: el tema claro, el color por categoría, sin estilos ni marcas.
+ */
+export function aplicarEnVivo(visor, aplicadas, opciones) {
+    const tema = opciones.theme ?? "light";
+    if (tema !== aplicadas.theme) {
+        visor.setTheme(tema);
+        aplicadas.theme = tema;
+    }
+    const color = opciones.colorBy ?? "category";
+    if (color !== aplicadas.colorBy) {
+        visor.setColorBy(color);
+        aplicadas.colorBy = color;
+    }
+    // statusStyles y marks: la copia normalizada de lo que llega (copiaDeDatos) contra la de lo aplicado. Un
+    // diccionario sin prototipo o con claves que valen undefined, con lo mismo, no llama a nada (como en Angular).
+    const estilos = copiaDeDatos(opciones.statusStyles ?? {});
+    if (!igual(estilos, aplicadas.statusStyles)) {
+        aplicadas.statusStyles = estilos;
+        visor.setStatusStyles(estilos);
+    }
+    const marcas = copiaDeDatos(opciones.marks ?? {});
+    if (!igual(marcas, aplicadas.marks)) {
+        aplicadas.marks = marcas;
+        visor.setMarks(marcas);
+    }
+}
+/** Las opciones sin las que valen `undefined` (el visor usa entonces su valor por defecto). */
+export function sinIndefinidos(opciones) {
+    return Object.fromEntries(Object.entries(opciones).filter(([, v]) => v !== undefined));
+}
+/** Lo que hace el visor con un error si nadie escucha `onError`: escribirlo en la consola. */
+export function avisarEnConsola(error) {
+    console.warn("[seatsyoo]", error.code, error.message);
+}
+/**
+ * `render` lanza si faltan opciones (qué enseñar, la clave pública…). En un componente no hay quien lo
+ * recoja, así que se convierte en un error con el código `invalid-options`.
+ */
+export function errorDeOpciones(err) {
+    return { code: "invalid-options", message: err instanceof Error ? err.message : String(err) };
+}
+/**
+ * Qué compra el visor montado con estas opciones: el evento, o la temporada (con los eventos del abono parcial, en
+ * cualquier orden, como los guarda el visor); `null` si solo enseña el plano (`link`, `document`: no retiene nada).
+ */
+function destino(i) {
+    // Con el mismo orden que el visor: document, link, season y event.
+    if (i.document || i.link)
+        return null;
+    if (!i.season)
+        return `evento:${i.event ?? ""}`;
+    const abono = i.seasonEvents?.length ? `@${[...i.seasonEvents].sort().join(",")}` : "";
+    return `temporada:${i.season}${abono}`;
+}
+/**
+ * Al volver a montar (cambia una opción de identidad), ¿hay que soltar lo que el comprador tiene retenido en el
+ * visor que se va?
+ *
+ * destroy() no suelta lo retenido: así el visor que se monte después en el mismo evento lo recupera (con
+ * `session: "continue"`, guarda su token en sessionStorage). Pero si el nuevo no lo va a recuperar (otro evento u
+ * otra temporada, otro servidor o clave pública, `session: "start"`, un `holdToken` nuevo, modo «manager»), esas
+ * plazas se quedarían bloqueadas para los demás hasta que caduque la retención, sin que la página pueda venderlas
+ * ni soltarlas: el comprador ya no las ve y el token del visor nuevo es otro. Entonces se sueltan.
+ *
+ * Lo retenido con un `holdToken` de la página no se suelta nunca: es de su token y lo lleva su servidor (por
+ * ejemplo, un carrito con varias funciones). Tampoco hay nada que soltar en el modo «manager» ni al solo ver.
+ */
+export function sueltaAlCambiar(antes, despues) {
+    if (antes.holdToken !== undefined || antes.mode === "manager" || destino(antes) === null)
+        return false;
+    const recupera = despues.holdToken === undefined &&
+        despues.mode !== "manager" &&
+        (antes.session ?? "continue") === "continue" &&
+        (despues.session ?? "continue") === "continue" &&
+        antes.server === despues.server &&
+        antes.publicKey === despues.publicKey &&
+        destino(antes) === destino(despues);
+    return !recupera;
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@seatsyoo/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Componente de React para el visor de mapas de asientos de Seatsyoo: elegir butacas, retenerlas y venderlas en tiempo real.",
+  "license": "MIT",
+  "keywords": [
+    "seatsyoo",
+    "react",
+    "mapa de asientos",
+    "butacas",
+    "entradas",
+    "seating chart",
+    "seat map",
+    "tickets"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "dependencies": {
+    "@seatsyoo/visor": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
 }