@liquidcars/atlas 0.1.51 → 0.1.53

package/README.md

@@ -2,6 +2,12 @@
 
 Componente web reutilizable para explorar modelos conceptuales en 3D. El componente lee una isla de datos con `palette`, `entities` y `relations`, resuelve coordenadas relativas mediante `parent` y permite explorar geometrías, contenedores, relaciones animadas y selección contextual.
 
+Core recibe modelos planos con posiciones `p` relativas al padre y dimensiones `s`.
+La [guía de modelos declarativos y nativos](../../apps/atlas-studio/docs/model-representations.md)
+explica cómo compilar una declaración con `atlas-layout`, cómo conservar coordenadas
+nativas y qué validaciones aplica el formato portable. La tolerancia de la API directa
+de core no sustituye esas validaciones de Studio y Platform.
+
 ## Prueba local
 
 Desde la carpeta del paquete:
@@ -189,6 +195,7 @@ generar el archivo.
 ## Contrato de datos
 
 - `palette`: mapa de nombres de color a valores CSS/hex.
+- `libraries` (opcional): librerías de geometrías de autor publicadas en npm y vinculadas por el modelo, no por Studio. Cada entrada declara `package`, una `version` semántica exacta y, opcionalmente, el `namespace` esperado. Studio limita inicialmente esta carga dinámica a paquetes `@liquidcars/atlas-geometry-*`.
 - `theme` (opcional): configuración de `background`, `lighting`, `panel`, `toolbar`, `breadcrumbs`, `hint` y `ui`. `ui` permite mostrar u ocultar `panel`, `toolbar`, `breadcrumbs` y `hint`.
 - `render.camera` (opcional): vista inicial con `position`, `target` y `zoom`. Las coordenadas pertenecen al espacio del modelo; `zoom` conserva el encuadre relativo entre tamaños de visor.
 - `render.initialMode`: `2d` o `3d`. `render.views."2d".theme` admite `auto` (hereda el fondo del documento), `light` o `dark`; `render.views."2d".grid` activa o desactiva los puntos (por defecto, `true`). `render.views."2d".background` permite un color CSS concreto. `render.ui.toolbar` acepta `true`, `false` o una lista como `[mode, zoom, fit]` para mostrar solo esos controles.
@@ -292,7 +299,31 @@ terceros una sola vez y cada recurso puede sobrescribir `authors` o `license`.
 Las piezas declarativas admiten primitivas, posición, rotación, escala,
 materiales e imágenes por URL/data URI; los SVG también pueden proporcionarse
 inline. Para planos con imagen, `imageFit` admite `cover`, `contain` y
-`stretch`. Desde `0.1.40`, `shape: "svg-extrude"` convierte rutas SVG en una
+`stretch`. `imageBackground` admite `auto`, `light`, `dark`, `transparent` o
+un color CSS. En imágenes transparentes, `auto` escoge blanco o negro a partir
+de la luminancia de los píxeles visibles; en imágenes opacas estima el color de
+fondo a partir del perímetro. Con `contain`, el fondo cubre el plano completo y
+la imagen conserva su proporción. `imagePadding` admite `auto`, `none`,
+`compact`, `roomy` o una fracción numérica entre `0` y `0.24`; el modo
+automático detecta los límites del contenido y reserva una zona segura. La
+pieza `shape: "rounded-frame"` crea un marco con hueco real mediante `size`,
+`innerSize`, `radius` e `innerRadius`. Las URL remotas necesitan CORS para
+convertirse en texturas WebGL.
+Un host que pueda recuperar recursos públicos de forma segura puede evitar esa
+dependencia configurando un resolvedor; este puede devolver `Response`, `Blob`,
+una URL `data:`/`blob:` o una URL alternativa:
+
+```js
+atlas.setImageResolver(async ({ source, signal, geometry, entityId }) =>
+  fetch(`/api/image?url=${encodeURIComponent(source)}`, { signal }));
+
+// También disponible como valor por defecto para todas las instancias del host.
+LiquidCarsAtlas.setDefaultImageResolver(resolver);
+```
+
+Si el resolvedor falla, Atlas conserva el intento CORS directo y emite
+`IMAGE_LOAD_FAILED` cuando tampoco puede decodificar el recurso. Desde
+`0.1.40`, `shape: "svg-extrude"` convierte rutas SVG en una
 malla con profundidad real, por lo que una marca puede formar parte del volumen
 sin convertirse en texto ni en una textura plana:
 
@@ -396,6 +427,9 @@ npm install ./liquidcars-atlas-0.1.40.tgz
 
 ## Estado
 
+`0.1.52` añade resolución delegable de imágenes remotas, fondos adaptativos,
+padding sensible al contenido y marcos redondeados con hueco real para
+geometrías de medios.
 `0.1.40` añade SVG extruido nativo para que los geometry packs puedan construir
 marcas volumétricas a partir de recursos vectoriales sin recurrir a campos de
 texto. `0.1.39` incorpora metadatos normalizados de autoría, licencia,
@@ -504,3 +538,7 @@ the origin active. History retains 2D/3D mode, camera, diagram zoom and scroll,
 selection, open containers and filters. Hosts that rebuild the component can use
 `restoreNavigationState(state, { restorePresentation: true })` to restore its
 presentation as well as its history.
+
+## Public model contract
+
+`@liquidcars/atlas/model` exports `validateRuntimeModel`, `runtimeModel`, `runtimeSnapshot`, relation normalization and presentation capture without DOM, Three or layout. It validates supplied vectors and hierarchy before core applies defaults. See the [model/document contract](../atlas-layout/spec/ATLAS-MODEL-CONTRACT-v1.md).