@liquidcars/atlas 0.1.50 → 0.1.52

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:
@@ -292,7 +298,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 +426,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,
@@ -472,3 +505,39 @@ In that fallback, Save opens a picker or downloads a copy because the selected
 files cannot be written in place.
 See `examples/hyperlinks` for two linked documents and an external Markdown
 information file.
+
+### Named models and cloud destinations
+
+The optional `model` selector identifies a technical model key within the
+destination document. Titles may change without changing the reference:
+
+| Destination | Reference |
+| --- | --- |
+| Current document | `atlas:?model=process` |
+| Local collection | `atlas:actors/dealer.atlas.md?model=inventory` |
+| Current cloud publication | `atlas://cloud/DOCUMENT_ID@published?model=process` |
+| Fixed cloud revision | `atlas://cloud/DOCUMENT_ID@r3?model=process` |
+| Authorized cloud Draft | `atlas://cloud/DOCUMENT_ID@draft?model=process` |
+
+Append `#entityId` to select an entity. URI-encode model keys and fragments.
+Omitting `model` uses the destination document's `defaultModel`. A cloud origin
+cannot resolve local document or content paths; a local origin may open cloud
+documents through its host resolver.
+
+The exported `atlasReferenceTarget(reference, from)` parses the document kind,
+version and model selector. The resolver may return `context` alongside `uri`
+and `model`; the runtime carries that context in history and navigation events.
+Return a canonical revision URI when resolving `@published` to pin the visit.
+Cloud history visits invoke the resolver again so the host can recheck access.
+The runtime does not grant authorization or contact a cloud deployment itself.
+
+Use `setNavigationGuard(async () => { ... })` to finish pending saves before
+navigation. Resolution errors, missing models and missing entity fragments leave
+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).