# Formato de datos Scene {/* #scene-data-format */}

Para flujos de registro, inicio de sesión y extensiones de Chrome, consulta [grabación manual y revisión](/docs/es/manual-recording). El grabador utiliza este mismo contrato Scene y publica imágenes solo tras la revisión administrativa.

`reconstruct.scene.v1` describe una interfaz observada independientemente del framework de origen o destino. DOM/CSS web y vistas/accesibilidad de Android son entradas de adaptadores. Un consumidor puede generar HTML, Compose u otra interfaz sin usar esas estructuras nativas como modelo de datos canónico.

El [JSON Schema](https://reconstruct.dev/docs/schemas/scene-v1.schema.json) descargable define nombres exactos de campos, miembros obligatorios, tipos anulables y enumeraciones. Esta instantánea documental incluye un [SHA-256](https://reconstruct.dev/docs/schemas/scene-v1.schema.json.sha256). Para capturas reales, usa el esquema y suma de comprobación que devuelve el servidor en ejecución con esa exportación.

El [ejemplo completo](https://reconstruct.dev/docs/examples/scene-export-v1.example.json) contiene fotogramas de diálogo cerrado/abierto y dos transiciones. Es un ejemplo ilustrativo: sus pruebas `example:` son ficticias, no una captura medida de producto.

## Entorno de extensión web {/* #web-extension-environment */}

Las capturas de extensiones de Chrome de escritorio usan el entorno `web-extension` (`WebExtension` en C# interno / Admin MCP, valor protobuf `CAPTURE_TYPE_ENVIRONMENT_WEB_EXTENSION = 6`). Móvil no admite este entorno. El contrato geométrico Scene es el mismo. La versión puede incluir metadatos tipados `browserExtension`: `id`, `name`, `version` y `packageSha256`; `displayName` procede del paquete verificado. Un trabajo administrativo graba las pantallas, que no se publican hasta revisarse. Consulta los controles y límites de privacidad en [grabación manual](/docs/es/manual-recording).

La solicitud interna de asignación del agente incluye `expected_environment` (campo 2). Si se omite, mantiene Web para trabajadores heredados. La cola lo comprueba contra el entorno del agente dentro de la transacción de asignación; cambiar ajustes administrativos del agente no puede hacer que un trabajador Web normal rastree una página de tienda de extensiones. Estos controles no son herramientas públicas Capture MCP.

## Transporte y adquisición {/* #transport-and-acquisition */}

La exportación normalizada está disponible mediante MCP [`get_interface_scene`](/docs/es/mcp-tools#platform-neutral-interface-scene). Los contratos de catálogo [REST](/docs/es/api/rest) y [gRPC](/docs/es/api/grpc) publicados no definen actualmente una operación Scene independiente. Sus respuestas de catálogo, insights y archivos almacenados son modelos distintos, incluso si se transportan como JSON.

Descubre una captura con `list_products`, `list_platforms`, `list_versions` y `list_pages`. Conserva producto, versión, entorno, página y `view` guardada exacta seleccionados. Las opciones de plataforma admitidas no prueban que exista una captura. Solicita vistas guardadas por separado e inspecciona los perfiles y fotogramas de cada exportación.

Ejemplo de parámetros MCP `tools/call`, con una selección ilustrativa:

```json
{
  "name": "get_interface_scene",
  "arguments": {
    "product": "example-product",
    "version": "1",
    "environment": "web",
    "page": "settings",
    "view": "mobile"
  }
}
```

La respuesta es un **manifiesto** compacto:

| Campo | Significado |
| --- | --- |
| `schema` | Identificador Scene: `reconstruct.scene.v1`. |
| `artifactSchema` | Identificador de envoltorio: `reconstruct.scene-export.v1`. |
| `path`, `uri`, `sha256`, `bytes` | Ubicación de exportación, SHA-256 y longitud en bytes. |
| `schemaPath`, `schemaUri`, `schemaSha256` | JSON Schema aplicable y su resumen criptográfico. |
| `entryFrameId`, `frames`, `transitionCount` | Fotograma inicial, inventario compacto de fotogramas y número de transiciones. |
| `frameCount`, `profileCount`, `assetCount` | Recuentos del inventario exportado. |
| `truncated` | Al menos un fotograma está incompleto. |
| `issueCount`, `issues`, `issuesTruncated` | Número total de incidencias y vista previa de un máximo de 30. |

Las rutas pertenecen al **sistema de archivos del servidor**. Léelas directamente solo si realmente se comparte con el cliente. Si no, resuelve los URI respecto al origen MCP y descarga con la autorización existente de la conexión. No construyas URL de transferencia a partir de ID de producto ni expongas credenciales. Verifica hashes sobre los bytes originales; reformatear JSON cambia su hash.

## Envoltorio de exportación {/* #export-envelope */}

```json
{
  "schema": "reconstruct.scene-export.v1",
  "scene": {
    "schema": "reconstruct.scene.v1",
    "id": "example/1/web/settings/mobile",
    "platform": "web",
    "entryFrameId": "frame-0",
    "profiles": [],
    "frames": [],
    "resources": [],
    "transitions": [],
    "correspondences": [],
    "issues": []
  },
  "assets": {}
}
```

Esto ilustra la estructura; el ejemplo completo contiene fotogramas poblados. Valida **`scene`**, no el envoltorio, contra el JSON Schema Scene. `assets` asigna ID de recurso Scene a bytes archivados. Cada entrada contiene `path`/`uri`, `mimeType`, `sha256` y `sizeBytes` opcionales. Puede faltar una entrada si no se archivaron los bytes del recurso. Un URI de origen, nombre de familia o contenedor multimedia vacío no demuestra que existan bytes utilizables.

## Documento e identidad {/* #document-and-identity */}

| Miembro de Scene | Significado |
| --- | --- |
| `schema`, `id`, `platform` | Formato obligatorio, identidad del documento y plataforma de origen (`unknown`, `web`, `android`). |
| `entryFrameId` | Primer fotograma observado opcional; puede mostrar consentimiento antes del contenido posterior predeterminado o con el aviso cerrado. |
| `profiles` | Ventana lógica y densidad, escala tipográfica, márgenes seguros, configuración regional y tema opcionales. |
| `frames` | Estados observados y sus inventarios de nodos. |
| `resources` | Descriptores de medios/fuentes referenciados por nodos y texto. |
| `transitions` | Acciones grabadas y sus resultados observados. |
| `correspondences` | Relaciones explícitas de nodos entre fotogramas. |
| `issues` | Pruebas ausentes, no compatibles o sin resolver. |

Los ID de perfil, fotograma, recurso y transición tienen ámbito de documento. Los ID de nodo son únicos **dentro de un fotograma**, y `parentId` referencia ese fotograma. Los ID de acción son locales al nodo. Un ID repetido o una ruta nativa igual en otro fotograma no prueban identidad. Una correspondencia registra ambos pares fotograma/nodo, procedencia y confianza opcional; síguela en vez de adivinar identidades entre perfiles.

Un fotograma tiene `id`, `profileId`, `stateId`, `coordinateSpace`, `extent` y `viewportBounds` opcionales, `truncated`, `nodes` y `evidence`. Los ID de estado nombran observaciones, no un catálogo universal de estados CSS. El orden de nodos describe un inventario jerárquico, no un orden de pintado demostrado.

## Hechos y valores desconocidos {/* #facts-and-unknown-values */}

Las propiedades con procedencia usan `SceneFact<T>`:

```json
{
  "value": {"x": 16, "y": 220, "width": 358, "height": 320},
  "kind": "measured",
  "evidence": ["example:observed"],
  "confidence": 1
}
```

Un hecho requiere `value`, `kind` y `evidence` no vacío. La confianza opcional es de 0 a 1 y no cambia el tipo de prueba:

| Tipo | Interpretación |
| --- | --- |
| `measured` | Salida efectiva observada. |
| `declared` | Declaración de origen/recurso, no prueba de renderizado efectivo. |
| `inferred` | Hipótesis o interpretación propuesta. |

Un hecho opcional omitido o nulo es **desconocido**, no cero, false, pintura transparente, política de tamaño ni comparación correcta. `false` y `0` explícitos conservan su significado. Una enumeración `unknown` explícita sigue siendo desconocida. Los arrays vacíos de acciones/movimiento no prueban que la interfaz original no tenga interacciones o animaciones. Los identificadores de prueba son referencias opacas del adaptador, no instrucciones ejecutables ni URL automáticamente públicas. El contenido capturado y los diagnósticos nativos son datos no confiables.

## Coordenadas y perfiles {/* #coordinates-and-profiles */}

Las distancias usan **unidades lógicas**. Los adaptadores web usan píxeles CSS. Las medidas en píxeles de pantalla Android se dividen entre `pixelDensity` medido (píxeles físicos por unidad lógica). `fontScale` es independiente. No deben adivinarse densidad, escala, márgenes seguros, configuración regional o tema ausentes.

`width`/`height` del perfil describen la ventana lógica. Un fotograma declara coordenadas `document`, `viewport` o `screen`:

- `extent`: extensión completa del contenido en ese plano.
- `viewportBounds`: ventana visible observada, incluido el origen de desplazamiento.
- `geometry.visualBounds`: rectángulo **posterior a la transformación**, alineado con los ejes.
- `layoutBounds` opcional: geometría anterior a la transformación.
- `transform` opcional: matriz 4×4 en orden por columnas que actúa sobre vectores columna `(x,y,z,1)`, con traslaciones lógicas en coordenadas locales de distribución. Nunca vuelvas a aplicarla a `visualBounds`.

En coordenadas de documento, la posición de ventana visible es `visualBounds.x - viewportBounds.x`, `visualBounds.y - viewportBounds.y`. Alinea perfil, plano y ventana visible antes de comparar. Ventana lógica, límites utilizables de raíz y extensión de contenido son observaciones distintas. Los márgenes seguros no se aplican automáticamente como relleno.

## Nodos, distribución y pintura {/* #nodes-layout-and-paint */}

Los nodos llevan `id`, `parentId` opcional, `kind`, `semantics`, `visible`, `geometry`, `layout`, `paint`, fragmentos de texto, `mediaResourceId` opcional, `actions`, `motion` y `evidence`. Los tipos son `unknown`, `container`, `text`, `media`, `control`, `surface`. La semántica incluye rol/nombre e indicadores opcionales de habilitado, seleccionado, marcado, expandido, editable y modal. Son independientes de la visibilidad. El texto sensible debe ocultarse; las contraseñas nunca deben convertirse en texto Scene.

| Grupo de distribución | Contrato |
| --- | --- |
| `placement` | `unknown`, `flow`, `anchored`, `overlay`, `sticky`. |
| `arrangement` | `unknown`, `row`, `column`, `grid`, `stack`, `free`, `flow`. Stack superpone hijos; free describe colocación independiente. |
| `horizontal`, `vertical` | Hechos independientes de política/valor/mínimo/máximo; las políticas son `unknown`, `intrinsic`, `fixed`, `fill`, `proportional`. |
| Espaciado/alineación | Relleno, separaciones de filas/columnas, ajuste de línea, orden inverso y alineación principal/transversal. |
| Pistas | Asignaciones numéricas de filas/columnas en un perfil, no reglas adaptables de autoría. |
| Anclajes | `referenceId` respaldado por pruebas más distancias superior/derecha/inferior/izquierda opcionales; referencia un nodo local al fotograma, `$viewport` o `$frame`. |

Tamaños fijos/mínimos/máximos y distancias de anclaje usan unidades lógicas. Los valores proporcionales son fracciones sin unidades del eje disponible referenciado; `fill` no tiene multiplicador. Un rectángulo medido no establece tamaño fijo, bloque contenedor, anclajes ni puntos de ruptura. La colocación nativa absoluta/fija puede mapearse a `overlay` sin inventar anclajes. El margen no es una separación canónica entre elementos.

La pintura usa dimensiones numéricas, canales RGBA normalizados 0–1, trazos, sombras, opacidad, desenfoque y referencias multimedia. `edges` opcional de un trazo sólido es un subconjunto único no vacío de `top`, `right`, `bottom`, `left`; al omitirlo se pinta todo el borde. Las sombras registran desplazamiento, desenfoque, extensión, interior y procedencia. `cornerRadii` utiliza actualmente cuatro campos con forma de márgenes interiores; el adaptador Web emite valores iguales para esquinas uniformes. Las esquinas web no uniformes/elípticas siguen sin admitirse, en lugar de recibir una asignación inventada.

La colocación multimedia (`content`, `background`, `surface`) es independiente del tipo de nodo. El ajuste es `unknown`, `contain`, `cover`, `stretch` u `original`. La posición `(x,y)` es un anclaje fraccionario en el espacio restante: 0 alinea el inicio, 0.5 centra y 1 alinea el final; se permiten fracciones externas. El ajuste de fondo no debe tomarse de una imagen de contenido no relacionada.

Los fragmentos contienen `text` original, límites opcionales y tipografía: familia/recurso de fuente, tamaño, peso, interlineado, espaciado, color, dirección, alineación, ajuste, decoración y uso de mayúsculas. El uso de mayúsculas (`none`, `uppercase`, `lowercase`, `capitalize`) cambia la presentación independientemente del texto original y los nombres accesibles. Pinturas, degradados y efectos de texto no compatibles siguen siendo incidencias. Las expresiones CSS nativas arbitrarias no son valores canónicos de distribución o pintura.

## Recursos y fuentes {/* #resources-and-fonts */}

Los recursos tienen `id`, `kind`, `uri`, `mimeType`, `sha256` y `bytes` opcionales y variantes tipográficas. Los tipos son `unknown`, `image`, `vector`, `font`, `video`, `audio`, `paint`. Las referencias de nodos y tipografía se resuelven dentro del documento. Las variantes registran familia, tipo/referencias de prueba, rango de peso opcional, cursiva y cobertura de puntos de código Unicode. Conserva los bytes archivados y selecciona una variante aplicable. Un nombre de familia o URL por sí solo no demuestra que la fuente deseada se cargara ni que una sustituta sea equivalente.

## Acciones y estados modales {/* #actions-and-modal-states */}

Las acciones declaran posibilidades: `unknown`, `activate`, `edit`, `scroll`, `navigate`, `focus`, `hover`, `back`, con destino opcional. Una transición tiene fotograma de origen, nodo de origen opcional y fotograma destino, acción, resultado y procedencia. Su `nodeId` siempre pertenece al **fotograma de origen**.

| Resultado | Significado |
| --- | --- |
| `unknown` | Resultado no establecido. |
| `changed` | Se observó un cambio resultante. |
| `unchanged` | No se observó ningún cambio. |
| `failed` | La acción falló. |
| `performedUnverified` | Se entregó la entrada sin demostrar el resultado esperado. |

Nuevos ID de instantánea o un cambio del cursor no demuestran que se abriera un menú. Un modal abierto debe conservar el fotograma observado completo: fondo, panel, hijos y contenido subyacente. Sigue `entryFrameId` y las transiciones para distinguir consentimiento, contenido cerrado, pestañas de diálogo, búsqueda y menús expandidos. Las mediciones de estados forzados y la entrada real de puntero/táctil conservan pruebas distintas. Las reproducciones del origen no son pruebas funcionales de una interfaz nueva generada.

## Movimiento {/* #motion */}

Los registros de movimiento de nodo/transición contienen `property`, `durationMs`, `keyframes`, `kind`, `evidence` y `delayMs`, `iterations` y `easing` Bézier cúbica opcionales (`x1`, `y1`, `x2`, `y2`). Los tiempos son milisegundos; los desplazamientos son 0–1 en orden creciente. Las coordenadas x de la curva son 0–1.

| Propiedad | Componentes de `value` del fotograma clave |
| --- | --- |
| `opacity` | `[alpha]`, 0–1. |
| `translation` | `[x, y, z]`, unidades lógicas. |
| `scale` | `[x, y, z]`, multiplicadores. |
| `rotation` | `[x, y, z]`, radianes. |
| `bounds` | `[x, y, width, height]`, unidades lógicas. |
| `color` | `[red, green, blue, alpha]`, 0–1. |

Las opciones omitidas siguen siendo desconocidas. Cero iteraciones significa que no hay reproducción. Una repetición desconocida o ilimitada no debe convertirse en un recuento finito supuesto. Las declaraciones CSS/WAAPI son `declared`; las muestras observadas pueden ser `measured`. Imágenes estáticas o dos extremos no establecen tiempos ni curvas de aceleración.

## Validación y cobertura {/* #validation-and-coverage */}

Valida la estructura con el esquema exportado y después la semántica: ID únicos en su ámbito, referencias válidas, padres sin ciclos, geometría finita, tamaños no negativos, colores normalizados, rangos de fuentes/puntos de código, ocultación y dimensiones de movimiento. El backend `SceneValidator` aplica estas invariantes adicionales. JSON Schema por sí solo no es un validador completo de grafos o privacidad.

El esquema estructural actual rechaza campos desconocidos y enumeraciones enteras. Fija su identificador y hash; usa un adaptador explícito para otra versión de formato. No reinterpretes datos desconocidos como distribución nativa. Los campos existentes conservan su significado; cambios incompatibles requieren un nuevo identificador de formato. Actualizar el servidor puede cambiar los bytes del esquema aplicable: conserva esquema/hash con cada exportación archivada.

`SceneIssue` tiene `code`, `message` y `frameId`/`nodeId` opcionales. Lee el artefacto completo, no solo la vista previa del manifiesto, y respeta los fotogramas truncados. Los límites actuales del validador son 100 perfiles, 500 fotogramas, 20 000 recursos, 100 000 nodos totales y 20 000 por fotograma. La adquisición/transporte puede tener límites menores; estas cifras no prometen cobertura de captura.

Las capturas Web nuevas emiten Scene junto con diagnósticos nativos. Los datos Web antiguos pueden convertirse con carencias explícitas. Un adaptador Android puede normalizar medidas nativas, pero el acceso API/MCP sigue requiriendo una Scene nativa publicada. El soporte del modelo no hace disponible un entorno no capturado. Estados, recursos, movimiento y observaciones adaptables ausentes siguen siendo desconocidos. Exportar correctamente o validar el esquema no demuestra fidelidad de reproducción.


## Política de envío de solicitudes {/* #request-submission-policy */}

La disponibilidad de solicitudes es independiente de la disponibilidad de capturas del catálogo. Los administradores la configuran en Requests → Job defaults → Request submissions (Solicitudes → Valores predeterminados → Envío de solicitudes). `ProductRequestJobDefaults.Submission` almacenado contiene `Enabled` y `Targets` tipados (`Type`, `Environment`). Los ajustes existentes sin ese miembro conservan los valores predeterminados: Desktop/Web, Desktop/WebExtension y Mobile/Web. Desactivar envíos conserva las selecciones y solicitudes existentes. Tanto la API de plataforma como MCP autenticado validan la política actual antes de crear una solicitud. Las opciones devuelven una lista `platforms` vacía cuando está cerrado; MCP devuelve además `enabled: false`. Los ID públicos siguen siendo `web` y `web-extension`, no nombres de enumeración. Los selectores del catálogo usan disponibilidad capturada por producto y ocultan combinaciones no disponibles.


### Destinos de solicitud agrupados {/* #grouped-request-targets */}

Los clientes nuevos envían `CreateRequestRequest.targets` como pares explícitos de plataforma/entorno. Por ejemplo:

```json
{
  "requestType": "PRODUCT_REQUEST_TYPE_ADD",
  "url": "https://metamask.io/",
  "webExtensionUrl": "https://chromewebstore.google.com/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn",
  "targets": [
    { "view": "desktop", "implementation": "web-extension" },
    { "view": "mobile", "implementation": "web" }
  ]
}
```

El servidor valida cada par contra la disponibilidad actual y los guarda en el detalle tipado de la solicitud. La aprobación crea solo los pares seleccionados: este ejemplo no crea un trabajo Desktop/Web. `views` e `implementations` siguen admitidos para clientes antiguos y representan su producto cartesiano; no los combines con `targets`. El origen web es `url`; los trabajos de extensión usan `webExtensionUrl`. Para actualizaciones, envía `catalogId` existente y destinos sin enlaces de origen. Selecciona primero el producto: la plataforma ofrece solo sus pares capturados habilitados actualmente para solicitudes. El servidor rechaza independientemente destinos ausentes del producto, resuelve el origen de cada entorno desde sus capturas publicadas e ignora enlaces sustitutivos del cliente. Los resúmenes públicos omiten el origen de extensión y los detalles privados.

## Pruebas adicionales de Scene {/* #additional-scene-evidence */}

El esquema actual incluye `themes` con tokens tipados y `layoutSamples` con mediciones dispersas de otros anchos. Las muestras referencian nodos de `frameId`; no son cuadros ni vuelven a medir texto o apariencia. Un nodo ausente no significa oculto. `nodes[].states` contiene cambios de apariencia: los campos presentes de `patch` reemplazan valores, los ausentes no cambian y las listas se reemplazan completas. Layout admite `flow`, `grow`, `shrink`, `basis`, `selfAlignment`, `order`, `gridCell`; paint incluye gradientes y estilo/posición de trazos. Son pruebas opcionales que pueden faltar en capturas antiguas. Conserva la procedencia y no deduzcas reglas adaptables de una sola medición.