venuekit 0.10.0 → 0.10.1

package/README.md

@@ -1,326 +1,332 @@
 # VenueKit
 
-Editor y mapa de butacas para venta de entradas: butacas numeradas, mesas y lugares en el
-mismo plano. Se instala como **un solo paquete**, `venuekit`, con dos entradas:
-
-- `venuekit` — el núcleo: el plano (Layout v2), su validación, la expansión a unidades
-  vendibles, el candado y los tipos de lugar. **No toca el DOM ni React**: es lo que importa
-  el servidor.
-- `venuekit/react` — `<VenueDesigner />` (el editor del productor) y `<SeatMap />` (el mapa
-  del comprador). Abre con `"use client"`.
-
-Los dos comparten un único chunk con el núcleo, así que `instanceof LayoutError` y las
-constantes valen entre una entrada y otra.
-
-## Instalar
+[![npm](https://img.shields.io/npm/v/venuekit.svg)](https://www.npmjs.com/package/venuekit)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**Seating charts for ticketing apps.** A floor-plan editor for organizers and an interactive
+seat map for buyers, in one React package with a framework-free core.
+
+Draw a venue with numbered seat blocks, tables, standing-room zones and landmarks (stage,
+bar, restrooms…), assign each piece to a ticket type, and let buyers pick their exact seat.
+VenueKit handles the drawing, numbering, validation and the "don't break what's already
+sold" rules; your app keeps the money, the inventory and the database.
+
+- **Editor (`<VenueDesigner />`)** — guided by your ticket types: blocks of seats (straight or
+  curved), round and square tables, general-admission zones, landmarks, a background image to
+  trace over, resize handles, smart alignment guides, multi-select with align/distribute,
+  undo/redo, keyboard support, and a phone layout.
+- **Numbering your way** — rows with letters (optionally with Ñ, then AA, AB…) or numbers;
+  seats in sequence, odd only, even only, or from the center out; any starting point,
+  left-to-right or right-to-left, skipped numbers, and removed seats for aisles.
+- **Capacity aware** — give each ticket type its capacity and the editor sizes new blocks to
+  it, refuses to go over, and offers to trim the surplus if the capacity goes down.
+- **Sold seats are safe** — pieces with sold or held seats can be moved, rotated or resized,
+  but never deleted, renumbered or reassigned.
+- **Buyer map (`<SeatMap />`, `<VenueOverview />`)** — the whole venue at a glance, tap a zone
+  or a section to pick it, zoom into a section to choose seats, clear free / yours / sold
+  states, screen-reader and keyboard friendly, built for touch.
+- **Server-side core** — the same validation runs on your server: schema, limits, unit IDs,
+  lock checks, capacity checks. No DOM, no React.
+
+## Install
 
 ```bash
 npm install venuekit
 ```
 
-Peers: `react` y `react-dom` ≥ 18 (sólo para `venuekit/react`; el núcleo no los necesita). Dependencia: `zod` ^4.
-
-Para probar un cambio sin publicar: `npm run pack:local` deja `dist-packs/venuekit-<versión>.tgz`, que el host instala con `npm i <ruta al .tgz>` (detalle en `docs/consumo-local.md`).
-
-## `venuekit` (servidor y cliente, sin DOM)
-
-Un plano (Layout v2) es `{ meta, elements }`. `meta` lleva `id`, `name`, `version`, `width`,
-`height` y la imagen de fondo (`background`, o `null`). `elements` son bloques de butacas
-(`seatBlock`), mesas (`table`) y referencias del lugar (`landmark`: escenario, baños, barra…).
-Cada bloque o mesa puede llevar un tipo de lugar (`placeType: { ref, name }`).
-
-Hay dos formas de "sin asignar", y las dos significan lo mismo para vender: `placeType: null`
-(nunca tuvo tipo) y `{ ref: "", name: "VIP" }` (no está atada a ningún tipo, pero recuerda
-cómo se llamaba el que tenía, para re-enlazarla por nombre). No compares `placeType` a mano:
-leé `expand(layout)[i].placeTypeRef`, que vale `null` en los dos casos.
-
-El plano llega de afuera, así que el esquema tiene topes (exportados como constantes):
-`MAX_UNITS` unidades vendibles, `MAX_ELEMENTS` piezas, ids de hasta `MAX_ID_LENGTH`,
-nombres hasta `MAX_NAME_LENGTH`, `ref` hasta `MAX_REF_LENGTH`, número de mesa hasta
-`MAX_TABLE_LABEL_LENGTH`, `background.src` (una URL) hasta `MAX_SRC_LENGTH`; la primera fila
-con letras va de 1 a `MAX_LETTERS_START` letras (con números, hasta 9 dígitos) y `skip`
-tiene hasta `MAX_SKIP` entradas. Un plano fuera de esos topes no pasa `migrate`.
-
-Numeración de un bloque (`rowLabels` / `seatLabels`, campos opcionales nuevos en 0.10; un
-plano viejo sin ellos vale igual que antes): `pattern` (sólo con números) es `"sequential"`
-(1, 2, 3…, el default), `"odd"` (1, 3, 5…), `"even"` (2, 4, 6…) o `"center"` (desde el
-centro). Con impares o pares se arranca en el primero de esa clase que no sea menor que
-`start`. «Desde el centro»: la primera va en el medio y las siguientes alternan alejándose
-(la 2.ª a la izquierda, la 3.ª a la derecha…); con una fila par, la primera va en la del
-medio de la derecha y la segunda en la de la izquierda. Empezando en 1: `6 4 2 1 3 5 7`
-(fila impar) y `6 4 2 1 3 5` (par); `direction: "rtl"` lo espeja (impares a la izquierda).
-`skip` saca números o letras de la secuencia en todos los patrones. `alphabet: "es"` (sólo
-con letras) suma la Ñ después de la N; sin eso no hay Ñ, como siempre. Después de la Z sigue
-AA, AB…
-
-| Export | Para qué |
-| --- | --- |
-| `layoutSchema` | Esquema zod del plano v2. |
-| `migrate(input)` | La puerta de entrada de un plano de afuera: lo valida (esquema y topes) y lo devuelve como Layout v2. Sólo acepta v2: la v1 nunca se publicó y da `LayoutError`, igual que cualquier plano que no sirva. |
-| `CURRENT_VERSION` | Versión actual del plano (hoy `2`). |
-| `expand(layout)` | Las unidades vendibles con sus IDs: butaca `"<bloque>:<fila>:<butaca>"`, lugar de mesa `"<mesa>:<n>"`, mesa entera = id de la mesa. Mover o girar no cambia IDs. |
-| `findLockViolations(antes, despues, bloqueados)` | Qué unidades vendidas o retenidas desaparecerían, se renombrarían o cambiarían de lugar físico con el cambio (desde 0.10 también una renumeración que corre los nombres: empezar en B, saltear, invertir el sentido, cambiar el patrón). Mover, girar, escalar o curvar la pieza entera se puede. Para validar en el servidor lo mismo que el editor rechaza. |
-| `summarize(layout)` | Conteos del plano: butacas, mesas y lugares, en total y por tipo de lugar. Por tipo trae también `duplicates: { seats, tables }`: butacas (`"fila:butaca"`, p. ej. `"A:1"`) y números de mesa repetidos adentro de ese tipo. Con algo ahí, el host no debería dejar publicar. |
-| `rebindPlaceTypes(layout, opciones)` | Re-enlaza un plano guardado a los tipos de lugar del evento actual, por nombre. Lo que no encuentra queda sin asignar. |
-| `canAssign(pieza, opcion)` | Si una pieza admite ese tipo de lugar. |
-| `PlaceTypeOption` | `{ ref, label, color, accepts: "seats" \| "tableWhole" \| "tablePerPlace" \| "zone", capacitySteps? }`. `capacitySteps`: los cupos acumulados de los lotes, en orden de venta (lotes de 30, 50 y 100 → `[30, 80, 180]`); sin eso, sin tope. `"zone"`: una entrada general, que se marca como zona y no pone lugares. |
-| `placeTypeCapacity` / `nextBlockUnits` / `capacityViolations` | El tope de un tipo (el mayor cupo), cuántas butacas trae el próximo bloque (de a tramos: `[30, 80, 180]` → bloques de 30, 50 y 100) y qué tipos pasa un cambio de su cupo. Para validar en el servidor lo mismo que el editor rechaza. |
-| `landmarks` | Catálogo de referencias del lugar. |
+`react` and `react-dom` ≥ 18 are peer dependencies, needed only for `venuekit/react`. The
+core (`venuekit`) has no DOM or React dependency.
+
+The package has two entry points:
+
+| Import | What | Where |
+| --- | --- | --- |
+| `venuekit` | Core: the plan format, validation, expansion to sellable units, locking, capacity. | Server and client |
+| `venuekit/react` | `<VenueDesigner />`, `<SeatMap />`, `<VenueOverview />`, messages and themes. Starts with `"use client"`. | Client |
+
+> **Language:** the built-in UI text defaults to Spanish (Argentina). Pass the English
+> messages shown in the examples (`designerEn`, `en`) or your own overrides.
+
+## Quick start
+
+### 1. Describe your ticket types
+
+Each ticket type that can be placed on the plan is a `PlaceTypeOption`:
 
 ```ts
-import { migrate, expand, findLockViolations, rebindPlaceTypes } from "venuekit"
+import type { PlaceTypeOption } from "venuekit"
 
-const layout = rebindPlaceTypes(migrate(JSON.parse(saved)), placeTypeOptions)
-const units = expand(layout)                                   // validar ids contra el plano
-const broken = findLockViolations(current, next, soldOrHeldIds) // [] si no rompe nada vendido
+const placeTypes: PlaceTypeOption[] = [
+  { ref: "orchestra", label: "Orchestra", color: "#e5482c", accepts: "seats", capacitySteps: [120] },
+  { ref: "boxes", label: "Boxes", color: "#f2b14c", accepts: "tableWhole" },
+  { ref: "floor", label: "Floor (standing)", color: "#3fc59a", accepts: "zone" },
+]
 ```
 
-## `venuekit/react`
+- `ref` — your ID for the ticket type. VenueKit stores it on each piece.
+- `accepts` — `"seats"` (numbered seats), `"tableWhole"` (a whole table or box is one
+  unit), `"tablePerPlace"` (each chair is a unit) or `"zone"` (a standing area sold by
+  quantity; drawing its zone is optional).
+- `capacitySteps` — optional. The cumulative capacity of the type's price tiers, in sale
+  order. Tiers of 30, 50 and 100 seats are `[30, 80, 180]`: the editor offers blocks of 30,
+  50 and 100, and caps the type at 180. Leave it out for no cap.
 
-### `<VenueDesigner />`
+### 2. Let organizers draw the plan
 
 ```tsx
-import { migrate, rebindPlaceTypes } from "venuekit"
-import { VenueDesigner, designerEs } from "venuekit/react"
-
-// Un objeto nuevo en `layout` es otro plano: el editor lo carga y lo vuelve a encuadrar.
-// Si el host lo arma en cada render (aunque sea igual), memorizalo.
-const saved = useMemo(() => rebindPlaceTypes(migrate(raw), placeTypes), [raw, placeTypes])
-
-<div style={{ height: "100dvh" }}>
-  <VenueDesigner
-    layout={saved}                // Layout | null (null = plano en blanco con `name`)
-    placeTypes={placeTypes}       // PlaceTypeOption[]: las entradas numeradas del evento
-    lockedUnitIds={locked}        // ReadonlySet<string>: vendidas y retenidas por cualquiera
-    onChange={setDraft}
-    onDone={async (l) => { await save(l); close() }}   // «Listo»
-    onClose={close}               // «Volver» (opcional)
-    theme="dark"                  // "light" (por defecto) | "dark"
-    background={{ onPick: uploadImage, suggestedSrc: event.flyerUrl }}
-    messages={designerEs}         // opcional: mergeDesignerMessages / DesignerOverrides
-  />
-</div>
+"use client"
+import { useMemo, useState } from "react"
+import { migrate, rebindPlaceTypes, type Layout } from "venuekit"
+import { VenueDesigner, designerEn } from "venuekit/react"
+
+export function PlanEditor({ saved, soldOrHeld }: { saved: unknown; soldOrHeld: string[] }) {
+  // A new `layout` object means "load another plan": memoize it.
+  const initial = useMemo(() => (saved ? rebindPlaceTypes(migrate(saved), placeTypes) : null), [saved])
+  const locked = useMemo(() => new Set(soldOrHeld), [soldOrHeld])
+  const [draft, setDraft] = useState<Layout | null>(initial)
+
+  return (
+    // The editor fills its container: give the container a height.
+    <div style={{ height: "100dvh" }}>
+      <VenueDesigner
+        layout={initial}              // null = a blank plan named after `name`
+        name="Main theater"
+        placeTypes={placeTypes}
+        lockedUnitIds={locked}        // sold or held by anyone
+        onChange={setDraft}
+        onDone={async (layout) => { await savePlan(layout) }}   // the "Done" button
+        theme="dark"                  // "light" (default) or "dark"
+        background={{ onPick: uploadImageAndReturnUrl }}
+        messages={designerEn}
+      />
+    </div>
+  )
+}
 ```
 
-El editor va guiado por las entradas: a la izquierda «Tus entradas numeradas» muestra una
-tarjeta por cada `placeTypes` con lo que ya tiene en el plano («40 butacas», «3 mesas»,
-«24 lugares») o «Falta ubicar», y los botones para agregarle piezas (bloque de butacas; mesa
-redonda o cuadrada; mesa con sillas). Cada pieza nace **ya asignada** a esa entrada, en el
-centro de lo que se ve y corrida si ahí ya hay algo. La pieza elegida muestra sus datos en un
-panel junto a ella (filas, butacas por fila, forma; número y personas de una mesa) y
-«Numeración y pasillos» abre un diálogo con la vista previa del bloque: cómo se llaman las
-filas (letras, con o sin Ñ, o números), dónde empiezan y qué letras se saltean; cómo se
-numeran las butacas (seguidas, sólo impares, sólo pares o desde el centro), dónde empiezan,
-de qué lado y qué números se saltean; y qué butacas se sacan. Lo del
-diálogo se aplica todo junto al tocar «Listo» (un solo paso de deshacer, chequeado por el
-candado); «Cancelar» no toca el plano. Arriba, «+ Referencia» (escenario, baños, barra…) e
-«Imagen de fondo».
-
-- `placeTypes`: de ahí sale el color de cada pieza y qué piezas admite cada tipo. Sin
-  ninguno, el panel pide cargar entradas numeradas primero.
-- Cupo (nuevo en 0.4): con `capacitySteps`, la tarjeta dice «30 de 100 lugares», «Agregar
-  bloque» trae lo que falta para el próximo lote y, completo, se apaga con «Ya ubicaste los
-  100 lugares de Platea». Ningún cambio (filas, butacas, duplicar, numeración, lugares de
-  mesa, cambiar de tipo, un `layout` nuevo) puede pasarlo: se rechaza con «Platea tiene 100
-  lugares y ya ubicaste 100.». Deshacer siempre se puede. Si el host baja el cupo y sobran
-  lugares, la tarjeta lo dice y ofrece «Ajustar» (nuevo en 0.10): saca los que sobran
-  empezando por los últimos (última fila del último bloque hacia atrás; las últimas mesas),
-  en un paso de deshacer y sin tocar nunca lo vendido o retenido. Si los lotes del host
-  suman (30, 50 y 100 = 180), `capacitySteps` va con las sumas acumuladas: `[30, 80, 180]`.
-- Generales (nuevo en 0.4): las opciones `accepts: "zone"` aparecen en «Tus entradas
-  generales» con «+ Marcar zona de X». La zona es un rectángulo con el nombre, de ancho y
-  alto ajustables; marcarla es opcional y nunca figura como «Falta ubicar». Desde 0.8 puede
-  ser curva («Forma: Recta / Curva», como un bloque): `zone.curve` (grados, default 0) la
-  vuelve una tribuna en arco, concéntrica con un bloque de la misma curva; el ancho se mide
-  sobre el arco central y el alto es el grosor.
-- `sidePanel` (nuevo en 0.9): `(api: DesignerHostApi) => ReactNode`, el panel de entradas
-  del host en lugar de «Tus entradas numeradas» (a la izquierda; en el celular, dentro de
-  la hoja «Entradas»). `api`: `addPiece(kind, ref)` (como los botones de la librería: cupo
-  por tramos, centro de lo visible, sin encimar; devuelve el id o `null`),
-  `nextPieceUnits(ref)` (0 = cupo completo), `placed(ref)` (`{ units, zones, pieces }`),
-  `capacityText(ref)`, `capacityFullText(ref)`, `overCapacity(ref)` (cuántos sobran del
-  cupo, 0 si ninguno), `trimToCapacity(ref)` («Ajustar»: `{ removed }`, menos de lo que
-  sobraba si lo vendido no dejó; `null` si no sobra nada), `missingRefs`, `select(id)`, `reveal(id)`,
-  `selectedRef` y `summary`. `api` no cambia al arrastrar; pasá `sidePanel` estable
-  (`useCallback`) para que el panel no se redibuje en cada cuadro.
-- `placeTypes` cambiantes (nuevo en 0.9): con el editor abierto se pueden agregar, renombrar,
-  recolorear o borrar entradas. El plano y la historia las siguen sin un paso de deshacer:
-  las piezas de una entrada borrada quedan sin asignar (`ref: ""`, con el nombre) y se
-  avisa por `onChange`.
-- `lockedUnitIds`: lo vendido y lo retenido por cualquier comprador. Moverlas se puede; lo
-  que las borre, renumere o pase a otro tipo se rechaza con un aviso. Vale también para
-  Deshacer/Rehacer y para un `layout` nuevo del host: si toca algo de esto, no se carga y
-  se muestra el mismo aviso. **El host tiene que validar con `findLockViolations` antes de
-  pasar un plano nuevo**, y otra vez en el servidor al guardar.
-- `onDone` (nuevo en 0.3): el botón «Listo». Puede ser async; si falla, se avisa. Si no está,
-  el botón dice «Guardar» y llama a `onSave` como antes.
-- `onClose` (nuevo en 0.3): el botón «Volver» de arriba a la izquierda. Sin esto, no hay.
-- `theme` (nuevo en 0.3): `"dark"` pone los valores por defecto oscuros de los tokens
-  `--vk-*` (los del diseño); `"light"` es el de siempre. Los tokens del host siguen ganando.
-- Teclado: «Poner en el centro» (o Enter sobre el plano) pone la referencia armada; las
-  flechas mueven la elegida (Shift, de a más).
-- Ordenar el plano (nuevo en 0.7): al mover, la pieza se pega a bordes y centros de las
-  demás y al centro de la hoja, con una guía; también al mismo espacio que ya hay entre dos
-  vecinas, con una cota. Las manijas pegan el borde a otras piezas y el ancho/alto al de
-  otra; en bloques y mesas, la escala de otra del mismo tipo (± 5 %). Alt/Option, sin imán.
-- Varias piezas (nuevo en 0.7): Shift o ⌘/Ctrl + clic suma o saca; arrastrar en un lugar
-  vacío dibuja un recuadro que elige lo que toca (⌘/Ctrl + A, todas). Con el dedo, mantener
-  apretado en vacío y arrastrar es el recuadro; arrastrar sin esperar sigue moviendo el
-  plano. Con el mouse, el plano se mueve con espacio + arrastrar, el botón del medio o la
-  rueda (zoom). Con dos o más elegidas, el panel ofrece alinear, repartir con el mismo
-  espacio, igualar ancho/alto o tamaño, duplicar y borrar; todo es un paso de deshacer y
-  pasa por el mismo candado y cupo.
-- `onChange` se llama con cada cambio.
-- `background.onPick` lo resuelve el host (sube el archivo y devuelve la URL, o `null`);
-  `suggestedSrc` ofrece con un toque la imagen del evento.
-- En un contenedor de 768 px o menos (el celular) el lienzo ocupa todo: «Tus entradas», la
-  pieza elegida, las referencias y la imagen van en hojas desde abajo, y la numeración en una
-  hoja de todo el alto. Se mide el contenedor, no la ventana.
-
-### `<SeatMap />`
+### 3. Let buyers pick their seats
 
 ```tsx
-import { SeatMap } from "venuekit/react"
-
-const [selection, setSelection] = useState<string[]>([])
-
-<SeatMap
-  layout={layout}
-  placeTypes={[{ ref: "vip", label: "Platea VIP", color: "#7c3aed", priceLabel: "$ 25.000" }]}
-  focusRef="vip"                  // el tipo que eligió el comprador: el mapa encuadra ahí
-  takenUnitIds={soldOrHeldByOthers}
-  heldUnitIds={heldForThisBuyer}
-  selection={selection}
-  onSelectionChange={setSelection}
-  conflictUnitIds={conflicts}     // lo que el host recibió en un 409
-  holdMinutes={10}
-  totalLabel="$ 50.000"           // ya formateado: la librería no formatea plata
-  onContinue={goToCheckout}
-/>
+"use client"
+import { useState } from "react"
+import type { Layout } from "venuekit"
+import { SeatMap, en } from "venuekit/react"
+
+export function ChooseSeats({ layout, taken }: { layout: Layout; taken: string[] }) {
+  const [selection, setSelection] = useState<string[]>([])
+  return (
+    <SeatMap
+      layout={layout}
+      placeTypes={[
+        { ref: "orchestra", label: "Orchestra", color: "#e5482c", priceLabel: "$40" },
+        { ref: "boxes", label: "Boxes", color: "#f2b14c", priceLabel: "$160" },
+      ]}
+      focusRef="orchestra"            // zoom into the section the buyer picked
+      takenUnitIds={taken}            // sold + held by other buyers
+      selection={selection}
+      onSelectionChange={setSelection}
+      maxSelection={6}
+      totalLabel="$80"                // preformatted: VenueKit never formats money
+      onContinue={() => checkout(selection)}
+      messages={en}
+    />
+  )
+}
 ```
 
-- `placeTypes`: pasá **todos** los tipos que hay en el plano, no sólo el elegido. Una pieza
-  cuyo tipo no está en la lista sale neutra y atenuada, como si no se vendiera.
-- `takenUnitIds`: lo vendido **y lo retenido por otras personas**. `heldUnitIds` es sólo lo
-  retenido **para este comprador** (lo suyo, en otra pestaña o en un paso anterior).
-- Otros props: `maxSelection`, `continueLabel`, `fill` (el mapa es la página: barra abajo),
-  `messages`, `className`, `style`.
+Need the whole venue first? `<VenueOverview />` shows every section and zone and calls
+`onSelect(ref)` when the buyer taps one. See [Buyer map in a card](#buyer-map-in-a-card).
 
-### `<VenueOverview />` (nuevo en 0.4)
+### 4. Validate on the server
 
-```tsx
-<VenueOverview
-  layout={layout}
-  placeTypes={[
-    { ref: "vip", label: "Platea VIP", color: "#7c3aed", priceLabel: "$ 25.000" },
-    { ref: "general:campo", label: "Campo delantero", color: "#3fbf8f", available: false },
-  ]}
-  onSelect={(ref) => openTicket(ref)}   // tocó una zona o un lugar de ese tipo
-/>
+Plans come from the browser: always validate before saving.
+
+```ts
+import { migrate, expand, findLockViolations, summarize, LayoutError, type Layout } from "venuekit"
+
+export function checkIncomingPlan(input: unknown, current: Layout | null, soldOrHeld: Set<string>) {
+  let next: Layout
+  try {
+    next = migrate(input)                     // schema + size limits; throws LayoutError
+  } catch (e) {
+    if (e instanceof LayoutError) return { ok: false as const, reason: e.message }
+    throw e
+  }
+  if (current && findLockViolations(current, next, soldOrHeld).length > 0) {
+    return { ok: false as const, reason: "The change would remove, renumber or reassign a sold seat." }
+  }
+  const units = expand(next)                  // every sellable unit with a stable ID
+  const perType = summarize(next).byRef       // per type: units, duplicated names…
+  return { ok: true as const, next, units, perType }
+}
 ```
 
-El mapa entero para quien compra, encuadrado en todo el plano y sin atenuar nada. Tocar una
-zona o cualquier lugar de un tipo llama `onSelect(ref)`: no elige butacas (eso es
-`<SeatMap />`). Lo que no es de ningún tipo de la lista va en gris y no se toca; con
-`available: false` va atenuado, dice «Agotada» y no llama a `onSelect`. Debajo, un botón por
-tipo (nombre, `priceLabel`, «Agotada»): el camino del teclado y del lector de pantalla.
-Otros props: `messages`, `className`, `style`.
+## Core concepts
+
+**Plan (`Layout`).** A JSON document `{ meta, elements }`. `meta` holds `id`, `name`,
+`version`, `width`, `height` and an optional `background` image. `elements` are:
+
+| Element | What |
+| --- | --- |
+| `seatBlock` | Rows × seats, straight or curved, with its own row and seat numbering and removed seats. |
+| `table` | Round or rectangular, sold whole or per chair. |
+| `zone` | A standing-room area for a general-admission ticket, straight or curved. No units. |
+| `landmark` | A reference shape (stage, bar, restrooms, entrance…). Not for sale. |
+
+Each sellable piece may carry `placeType: { ref, name }` linking it to a ticket type.
+`ref: ""` means "unassigned, but remember the name", so a saved plan can be re-linked by name
+with `rebindPlaceTypes` when it is reused for another event.
 
-### Mapa entero en una tarjeta (nuevo en 0.6)
+**Units.** `expand(layout)` returns every sellable unit with a stable ID: a seat is
+`"<block>:<row>:<seat>"`, a chair is `"<table>:<n>"`, a whole table is the table's ID.
+Moving, rotating or resizing a piece never changes IDs. Store these IDs in your inventory.
 
-Desde 0.7 el mapa entero encuadra justo lo dibujado (margen de 4 % del lado corto, hasta
-16 px) y la caja toma esa proporción, no la de la hoja. Los nombres de las piezas no bajan de
-11 px: en una pieza angosta y alta van girados a lo largo y, si igual no entran, se cortan con «…».
+**Locking.** Pass the IDs of sold or held units as `lockedUnitIds` to the editor. Pieces can
+still be moved, rotated, resized or curved, but anything that would delete a locked unit,
+change its label or move a label to a different physical seat (renumbering) is refused.
+`findLockViolations(before, after, locked)` runs the same check on the server.
 
-Para mostrar el plano adentro de una tarjeta, al lado de la lista de entradas del host:
+**Capacity.** With `capacitySteps`, the editor shows "30 of 100 spots", sizes new blocks to
+the next tier, blocks any edit that would exceed the cap and, if the cap goes down, shows
+how many spots are left over with an "Adjust" action that removes them from the end
+without touching locked units.
+
+**Limits.** Plans are untrusted input, so the schema has hard limits (exported as constants):
+`MAX_UNITS`, `MAX_ELEMENTS`, `MAX_ID_LENGTH`, `MAX_NAME_LENGTH`, `MAX_REF_LENGTH`,
+`MAX_TABLE_LABEL_LENGTH`, `MAX_SRC_LENGTH`, `MAX_SKIP`, `MAX_LETTERS_START`.
+
+## API
+
+### `venuekit` (core)
+
+| Export | Purpose |
+| --- | --- |
+| `migrate(input)` | Validates an external plan (schema and limits) and returns a `Layout`. Throws `LayoutError`. |
+| `layoutSchema`, `CURRENT_VERSION` | The zod schema and the current plan version. |
+| `expand(layout)` | Sellable units with stable IDs, positions and labels. |
+| `summarize(layout)` | Counts for the plan and per type: seats, tables, places, zones, and duplicated seat or table names. |
+| `findLockViolations(before, after, locked)` | Changes that would break sold or held units. |
+| `rebindPlaceTypes(layout, options)` | Re-links a saved plan to the current event's ticket types by name. |
+| `canAssign(piece, option)` | Whether a piece accepts a ticket type. |
+| `placeTypeCapacity`, `nextBlockUnits`, `capacityViolations` | Capacity helpers used by the editor. |
+| `landmarks`, `landmarkById` | The landmark catalog. |
+| `expandLabels`, `labelSequence`, `SPANISH_ALPHABET` | Row and seat numbering. |
+
+Types: `Layout`, `Element`, `SeatBlock`, `Table`, `Zone`, `Landmark`, `PlaceTypeOption`,
+`PlaceTypeAccepts`, `SellableUnit`, `PlanSummary`, `LockViolation`, `CapacityViolation`.
+
+### `<VenueDesigner />`
+
+| Prop | Type | |
+| --- | --- | --- |
+| `layout` | `Layout \| null` | The plan to edit; `null` starts a blank plan. A new object reloads the editor (memoize it); passing back what came from `onChange` is safe. |
+| `name` | `string` | Name for a blank plan. |
+| `placeTypes` | `PlaceTypeOption[]` | Ticket types that can be placed. They may change while the editor is open. |
+| `lockedUnitIds` | `ReadonlySet<string>` | Sold or held units. |
+| `onChange` | `(layout) => void` | Called on every change. |
+| `onDone` | `(layout) => void \| Promise<void>` | The "Done" button. Without it, a "Save" button calls `onSave`. |
+| `onClose` | `() => void` | The "Back" button (hidden without it). |
+| `background` | `{ onPick: () => Promise<string \| null>; suggestedSrc?: string \| null }` | You upload the image and return its URL. |
+| `sidePanel` | `(api: DesignerHostApi) => ReactNode` | Replaces the built-in ticket-type panel with your own (for example, ticket types with their prices). `api` offers `addPiece(kind, ref)`, `placed(ref)`, `nextPieceUnits(ref)`, `overCapacity(ref)`, `trimToCapacity(ref)`, `select(id)`, `reveal(id)`, `selectedRef`, `summary`… Keep the function stable (`useCallback`). |
+| `theme` | `"light" \| "dark"` | Default token values. |
+| `messages` | `DesignerOverrides` | `designerEn`, `designerEs`, or partial overrides via `mergeDesignerMessages`. |
+
+Gestures: drag to move; corner handles to resize; Shift/⌘/Ctrl-click or drag on empty space to
+multi-select; Space + drag, middle button or wheel to pan and zoom; Alt/Option disables
+snapping. On touch: drag pans, long-press and drag selects. Arrow keys move the selection.
+Below 768 px of container width the editor switches to bottom sheets.
+
+### `<SeatMap />`
+
+| Prop | Type | |
+| --- | --- | --- |
+| `layout` | `Layout` | |
+| `placeTypes` | `{ ref, label, color, priceLabel? }[]` | Pass every type on the plan; pieces of unknown types render muted. |
+| `focusRef` | `string` | The section the buyer is choosing in: the map zooms there and dims the rest. |
+| `takenUnitIds` | `string[]` | Sold, plus held by other buyers. |
+| `heldUnitIds` | `string[]` | Held for this buyer. |
+| `selection`, `onSelectionChange` | `string[]`, `(ids) => void` | Controlled selection. |
+| `maxSelection` | `number` | |
+| `conflictUnitIds` | `string[]` | IDs lost to another buyer (for example after a 409): marked sold and announced. |
+| `totalLabel`, `continueLabel`, `onContinue`, `holdMinutes` | | The bottom bar. |
+| `embedded`, `onBack`, `onFocusChange`, `height` | | For use inside a card (see below). |
+| `fill` | `boolean` | The map is the whole page. |
+| `messages` | `MessageOverrides` | `en`, `es`, or partial overrides via `mergeMessages`. |
+
+### `<VenueOverview />`
+
+The whole venue for buyers. Tapping a zone or any unit of a type calls `onSelect(ref)`.
+Props: `layout`, `placeTypes` (`{ ref, label, color, priceLabel?, available? }`; `available:
+false` shows "Sold out"), `onSelect`, `hideList`, `showHint`, `selectedRefs`,
+`takenUnitIds`, `selectedUnitIds`, `height`, `messages`.
+
+### Buyer map in a card
 
 ```tsx
 {focus === null ? (
   <VenueOverview
     layout={layout}
-    placeTypes={types}                 // con priceLabel: va debajo del nombre de cada zona
-    onSelect={(ref) => (isZone(ref) ? addOne(ref) : setFocus(ref))}
-    hideList                           // sin la lista de abajo (sigue para teclado y lector)
-    showHint                           // «Tocá un sector para elegirlo…»
-    selectedRefs={refsWithSomething}   // zonas pintadas más fuertes
-    takenUnitIds={sold}
-    selectedUnitIds={selection}        // butacas elegidas, en miniatura
+    placeTypes={types}
+    onSelect={(ref) => (isZone(ref) ? addOneTicket(ref) : setFocus(ref))}
+    hideList
+    showHint
+    takenUnitIds={taken}
+    selectedUnitIds={selection}
+    messages={en}
   />
 ) : (
   <SeatMap
-    embedded                           // sin barra de total: la selección la muestra el host
-    onBack={() => setFocus(null)}      // «← Todo el mapa»
-    onFocusChange={setFocus}           // tocaron otro tipo en el plano atenuado
-    layout={layout} placeTypes={types} focusRef={focus}
-    takenUnitIds={sold} selection={selection} onSelectionChange={setSelection}
+    embedded
+    onBack={() => setFocus(null)}
+    onFocusChange={setFocus}
+    layout={layout}
+    placeTypes={types}
+    focusRef={focus}
+    takenUnitIds={taken}
+    selection={selection}
+    onSelectionChange={setSelection}
+    messages={en}
   />
 )}
 ```
 
-- `<VenueOverview />`: `hideList`, `showHint`, `selectedRefs`, `takenUnitIds`,
-  `selectedUnitIds`, `height` (alto fijo; sin él sigue la proporción del plano). Encuadra el
-  plano entero cada vez que cambia el tamaño de la caja.
-- `<SeatMap />`: `embedded`, `onBack`, `onFocusChange`, `height`. Encuadra `focusRef`
-  agrandado (sus zonas incluidas) con el resto del plano atenuado.
-- El mapa del comprador pinta libre = color del tipo con el número oscuro, tuya = blanca con
-  borde del tipo, vendida = gris oscuro; referencias en un bloque oscuro con el nombre en
-  mayúsculas. Tokens: `--vk-mine`, `--vk-sold`, `--vk-sold-stroke`, `--vk-sold-fg`,
-  `--vk-unit-fg`, `--vk-landmark`, `--vk-landmark-stroke`, `--vk-landmark-fg`,
-  `--vk-zone-alpha-selected`. El editor no los usa.
-
-### Textos y tema
-
-- Mensajes en es-AR por defecto: `es` / `en` (mapa) y `designerEs` / `designerEn` (editor).
-  Se pisan parcialmente con `mergeMessages(overrides)` / `mergeDesignerMessages(overrides)`
-  o pasando `messages`.
-- Tema por tokens CSS `--vk-*` (`--vk-accent`, `--vk-bg`, `--vk-fg`, `--vk-line`,
-  `--vk-muted`, `--vk-surface`, `--vk-radius`, `--vk-font`…) sobre `.vk-root`; están
-  declarados con `:where()`, así que una regla común del host los pisa.
-- El editor suma `--vk-panel`, `--vk-raised` (paneles flotantes), `--vk-field`,
-  `--vk-canvas` / `--vk-canvas-dot` (fondo del lienzo), `--vk-primary-bg` (el botón «Listo»,
-  admite un degradé), `--vk-warn`, `--vk-ok`, `--vk-link`, `--vk-seg` / `--vk-seg-on`. El
-  lienzo lee además `--vk-shape`, `--vk-shape-fill`, `--vk-unassigned`, `--vk-taken`… La
-  fuente es la de `--vk-font`: pasale la del host.
-
-## Qué es del host
-
-La librería dibuja y valida el plano; no sabe de plata ni de ventas. El host se ocupa de:
-
-- **Subir imágenes**: `background.onPick` devuelve la URL.
-- **Precios**: entran como texto ya armado (`priceLabel`, `totalLabel`).
-- **Guardar los planos por nombre** y devolverlos al editor.
-- **Saber qué está vendido o retenido**: en el mapa, `takenUnitIds` (vendido + retenido por
-  otros) y `heldUnitIds` (retenido para este comprador); en el editor, `lockedUnitIds`
-  (vendido + retenido por cualquiera). Y volver a validar en el servidor con `findLockViolations`.
-- **No publicar un plano con nombres repetidos**: `summarize(layout).byRef[ref].duplicates`.
-- **Re-enlazar un plano guardado** al evento nuevo con `rebindPlaceTypes` antes de mostrarlo.
-
-## Notas para el host
-
-- **El editor necesita alto**: ocupa el de su contenedor, así que el contenedor tiene que
-  tener uno (`height: 100dvh`, un flex que crezca…). Sin alto, no se ve.
-- **`layout` y `onChange` son seguros de devolver**: si pasás por `layout` lo que salió de
-  `onChange` (setState y de vuelta como prop) el editor lo reconoce y no lo trata como un
-  plano nuevo. Un objeto distinto sí se carga (si no toca lo vendido), y se puede deshacer:
-  por eso un `layout` armado de nuevo en cada render, aunque sea igual, recarga el editor.
-  Usá `useMemo` (ejemplo arriba).
-- **Los ids en conflicto quedan vendidos**: lo que llega en `conflictUnitIds` se trata como
-  vendido mientras el mapa siga montado, aunque el host después lo libere.
-
-## Desarrollo
-
-Requiere Node ≥ 20.
+## Theming
+
+Everything is styled with CSS custom properties on `.vk-root`, declared with `:where()` so
+any rule of yours wins: `--vk-accent`, `--vk-bg`, `--vk-fg`, `--vk-line`, `--vk-muted`,
+`--vk-surface`, `--vk-radius`, `--vk-font`… The buyer map adds `--vk-mine`, `--vk-sold`,
+`--vk-unit-fg`, `--vk-landmark`…; the editor adds `--vk-panel`, `--vk-canvas`,
+`--vk-primary-bg` and more. Set `--vk-font` to your app's font.
+
+## What your app is responsible for
+
+VenueKit draws and validates plans. It does not know about money or orders. Your app:
+
+- stores plans and ticket types, and uploads background images;
+- formats prices (`priceLabel`, `totalLabel`);
+- tracks sold and held units, passes them to the editor and the map, and re-checks
+  `findLockViolations` on the server before saving a plan;
+- holds seats during checkout and resolves conflicts between buyers;
+- refuses to publish a plan with duplicated seat names (`summarize(layout).byRef[ref].duplicates`).
+
+## Development
+
+Requires Node ≥ 20.
 
 ```bash
 npm install
-npm test            # vitest, en Node, sin navegador
+npm test                   # unit tests (Vitest)
 npm run typecheck
-npm run build       # construye el paquete venuekit (dist/)
-npm run dev -w playground   # http://localhost:5173 — `/` el mapa, `/?designer` el editor
-npx playwright install chromium webkit   # una vez
-npm run test:e2e    # proyectos mobile (WebKit) y desktop (Chromium)
+npm run build              # builds packages/venuekit/dist
+npm run dev -w playground  # http://localhost:5173 (/ buyer map, /?designer editor)
+npx playwright install chromium webkit   # once
+npm run test:e2e           # browser tests (desktop and mobile)
 ```
 
-Estructura: `packages/core`, `packages/canvas` y `packages/react` son internos (privados);
-`packages/venuekit` los empaqueta en el único paquete publicable. El playground y los tests
-corren contra el fuente, sin build. Diseño: `docs/specs/`. Planes: `docs/plans/`.
+`packages/core`, `packages/canvas` and `packages/react` are internal; `packages/venuekit`
+bundles them into the published package. A Spanish reference with every detail lives in
+[`docs/reference.es.md`](./docs/reference.es.md).
+
+## License
+
+[MIT](./LICENSE) © Juan Cruz Fernández