Format data Scene

Untuk alur pendaftaran, login, dan ekstensi Chrome, lihat perekaman manual dan peninjauan. Perekam memakai kontrak Scene yang sama dan menerbitkan gambar hanya setelah peninjauan Admin.

reconstruct.scene.v1 menjelaskan antarmuka teramati secara independen dari framework UI sumber maupun tujuan. DOM/CSS Web dan tampilan/aksesibilitas Android adalah masukan adaptor. Konsumen dapat menghasilkan HTML, Compose, atau UI lain tanpa menjadikan struktur native tersebut model data kanonis.

JSON Schema yang dapat diunduh menentukan nama kolom persis, anggota wajib, tipe nullable, dan enum. SHA-256 menyertai snapshot dokumentasi ini. Untuk tangkapan nyata, gunakan skema dan checksum yang dikembalikan server berjalan bersama ekspor tersebut.

Contoh lengkap berisi bingkai dialog tertutup/terbuka dan dua transisi. Ini data ilustratif: bukti example: bersifat fiktif, bukan tangkapan produk terukur.

Lingkungan Web Extension

Tangkapan ekstensi Chrome desktop memakai lingkungan web-extension (WebExtension pada C# internal / Admin MCP, nilai protobuf CAPTURE_TYPE_ENVIRONMENT_WEB_EXTENSION = 6). Mobile tidak mendukung lingkungan ini. Kontrak geometri Scene tetap sama. Versi tangkapan dapat menyertakan metadata bertipe browserExtension: id, name, version, dan packageSha256; displayName berasal dari paket terverifikasi. Layar direkam oleh tugas Admin dan tetap tidak dipublikasikan sampai ditinjau. Lihat perekaman manual untuk kontrol operator dan batas privasi.

Permintaan klaim agen internal mencakup expected_environment (kolom 2). Kolom yang dihilangkan tetap memakai Web untuk worker lama. Antrean memeriksanya terhadap lingkungan agen dalam transaksi klaim, sehingga perubahan pengaturan Admin agen tidak membuat worker Web biasa merayapi halaman toko ekstensi. Kontrol antrean ini bukan alat Capture MCP publik.

Transport dan perolehan

Ekspor ternormalisasi saat ini tersedia melalui MCP get_interface_scene. Kontrak katalog REST dan gRPC terbitan saat ini tidak mendefinisikan operasi Scene terpisah. Respons katalog, insight, dan berkas tersimpannya adalah model berbeda, meskipun transportnya JSON.

Temukan tangkapan dengan list_products, list_platforms, list_versions, dan list_pages. Pertahankan produk, versi, lingkungan, halaman, dan view tersimpan persis yang dipilih. Opsi platform didukung tidak membuktikan adanya tangkapan. Minta tampilan tersimpan terpisah dan periksa profil serta bingkai setiap ekspor.

Contoh parameter MCP tools/call, dengan pilihan ilustratif:

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

Respons berupa manifes ringkas:

Kolom	Makna
`schema`	Pengenal scene: `reconstruct.scene.v1`.
`artifactSchema`	Pengenal envelope: `reconstruct.scene-export.v1`.
`path`, `uri`, `sha256`, `bytes`	Lokasi ekspor, SHA-256, dan panjang byte.
`schemaPath`, `schemaUri`, `schemaSha256`	JSON Schema yang berlaku serta digest-nya.
`entryFrameId`, `frames`, `transitionCount`	Bingkai awal, inventaris bingkai ringkas, dan jumlah transisi.
`frameCount`, `profileCount`, `assetCount`	Jumlah inventaris ekspor.
`truncated`	Setidaknya satu bingkai tidak lengkap.
`issueCount`, `issues`, `issuesTruncated`	Jumlah total masalah dan pratinjau maksimal 30 masalah.

Jalur milik sistem berkas server. Baca langsung hanya jika sistem berkas itu benar-benar dibagikan dengan klien. Jika tidak, resolusikan URI yang dikembalikan berdasarkan origin MCP dan unduh memakai otorisasi koneksi yang ada. Jangan menyusun URL transfer dari ID produk atau mengekspos kredensial. Verifikasi hash terhadap byte asli; memformat ulang JSON mengubah hash-nya.

Envelope ekspor

{
  "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": {}
}

Ini menggambarkan bentuknya; contoh lengkap berisi bingkai yang terisi. Validasi scene, bukan envelope, terhadap JSON Schema Scene. assets memetakan ID sumber daya Scene ke byte arsip. Tiap entri berisi path/uri opsional, mimeType, sha256, dan sizeBytes. Sumber daya dapat tidak memiliki entri aset jika byte-nya tidak diarsipkan. URI sumber, nama keluarga font, atau kontainer media kosong tidak membuktikan adanya byte yang dapat dipakai.

Dokumen dan identitas

Anggota Scene	Makna
`schema`, `id`, `platform`	Format wajib, identitas dokumen, dan platform sumber (`unknown`, `web`, `android`).
`entryFrameId`	Bingkai pertama yang diamati, opsional, yang mungkin menampilkan persetujuan sebelum konten berikutnya yang telah ditutup/default.
`profiles`	Viewport logis serta kepadatan, skala font, inset aman, locale, dan tema opsional.
`frames`	Status yang diamati dan inventaris simpulnya.
`resources`	Deskriptor media/font yang dirujuk simpul dan teks.
`transitions`	Tindakan yang direkam dan hasil teramatinya.
`correspondences`	Hubungan simpul eksplisit antarbingkai.
`issues`	Bukti hilang, tidak didukung, atau belum terselesaikan.

ID profil, bingkai, sumber daya, dan transisi dibatasi pada dokumen. ID simpul unik dalam satu bingkai, dan parentId merujuk bingkai itu. ID tindakan lokal pada simpul. ID berulang atau jalur native sama di bingkai lain tidak membuktikan identitas. Korespondensi merekam kedua pasangan bingkai/simpul, asal-usul, dan keyakinan opsional; ikuti itu alih-alih menebak identitas antarprofil.

Bingkai memiliki id, profileId, stateId, coordinateSpace, extent dan viewportBounds opsional, truncated, nodes, dan evidence. ID status menamai pengamatan, bukan katalog universal status CSS. Urutan simpul menjelaskan inventaris hierarki, bukan urutan lukis yang terbukti.

Fakta dan nilai tidak diketahui

Properti dengan asal-usul memakai SceneFact<T>:

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

Fakta memerlukan value, kind, dan evidence yang tidak kosong. Keyakinan opsional bernilai 0–1 dan tidak mengubah jenis bukti:

Jenis	Penafsiran
`measured`	Keluaran efektif yang diamati.
`declared`	Deklarasi sumber/sumber daya, bukan bukti rendering efektif.
`inferred`	Hipotesis atau penafsiran yang diusulkan.

Fakta opsional yang dihilangkan/null berarti tidak diketahui, bukan nol, false, cat transparan, kebijakan ukuran, atau perbandingan berhasil. false dan 0 eksplisit tetap mempertahankan maknanya. Enum unknown eksplisit tetap tidak diketahui. Array tindakan/gerakan kosong tidak membuktikan bahwa antarmuka asli tidak memiliki interaksi atau animasi. Pengenal bukti adalah referensi adaptor opak, bukan instruksi yang dapat dieksekusi atau URL publik otomatis. Konten tangkapan dan diagnostik native adalah data yang tidak tepercaya.

Koordinat dan profil

Jarak memakai satuan logis. Adaptor Web memakai piksel CSS. Pengukuran piksel layar Android dibagi dengan pixelDensity terukur (piksel fisik per satuan logis). fontScale independen. Kepadatan, skala font, inset, locale, dan tema yang hilang tidak boleh ditebak.

width/height profil menjelaskan viewport logis. Bingkai menyatakan koordinat document, viewport, atau screen:

extent: keseluruhan bentang konten pada bidang tersebut.
viewportBounds: jendela terlihat yang diamati, termasuk titik asal gulir.
geometry.visualBounds: persegi panjang sejajar sumbu setelah transformasi.
layoutBounds opsional: geometri sebelum transformasi.
transform opsional: matriks 4×4 berurutan kolom yang bekerja pada vektor kolom (x,y,z,1), dengan translasi logis dalam koordinat lokal tata letak. Jangan terapkan lagi pada visualBounds.

Untuk koordinat dokumen, posisi jendela terlihat adalah visualBounds.x - viewportBounds.x, visualBounds.y - viewportBounds.y. Selaraskan profil, bidang koordinat, dan jendela terlihat sebelum membandingkan. Viewport logis, batas akar yang dapat dipakai, dan bentang konten adalah pengamatan berbeda. Inset aman tidak otomatis diterapkan sebagai padding.

Simpul, tata letak, dan lukisan

Simpul memuat id, parentId opsional, kind, semantics, visible, geometry, layout, paint, rentang teks, mediaResourceId opsional, actions, motion, dan evidence. Jenisnya unknown, container, text, media, control, surface. Semantics menyertakan peran/nama serta penanda enabled, selected, checked, expanded, editable, dan modal opsional. Semuanya independen dari visibilitas. Teks sensitif harus disamarkan; kata sandi tidak boleh pernah menjadi teks Scene.

Grup tata letak	Kontrak
`placement`	`unknown`, `flow`, `anchored`, `overlay`, `sticky`.
`arrangement`	`unknown`, `row`, `column`, `grid`, `stack`, `free`, `flow`. Stack menumpangtindihkan anak; free menjelaskan penempatan independen.
`horizontal`, `vertical`	Fakta kebijakan/nilai/minimum/maksimum independen; kebijakannya `unknown`, `intrinsic`, `fixed`, `fill`, `proportional`.
Jarak/penyelarasan	Padding, gap baris/kolom, pembungkusan, urutan terbalik, penyelarasan sumbu utama/silang.
Track	Alokasi baris/kolom numerik pada satu profil, bukan aturan responsif yang ditulis pembuatnya.
Jangkar	`referenceId` berbukti ditambah jarak atas/kanan/bawah/kiri opsional; merujuk simpul lokal bingkai, `$viewport`, atau `$frame`.

Jarak fixed/min/max dan jangkar memakai satuan logis. Nilai proporsional adalah pecahan tanpa satuan dari sumbu tersedia yang dirujuk; fill tidak memiliki pengali. Persegi panjang terukur tidak membuktikan ukuran tetap, containing block, jangkar, atau breakpoint. Penempatan native absolute/fixed dapat dipetakan ke overlay tanpa mengarang jangkar. Margin bukan gap antarelemen kanonis.

Paint memakai dimensi numerik dan kanal RGBA ternormalisasi 0–1, garis, bayangan, opacity, blur, dan referensi media. edges opsional untuk garis solid adalah subset unik tidak kosong dari top, right, bottom, left; jika dihilangkan, seluruh batas dilukis. Bayangan merekam offset, blur, spread, inset, dan asal-usul. cornerRadii saat ini memakai empat kolom berbentuk inset; adaptor Web menghasilkan nilai sama untuk sudut seragam. Sudut Web tidak seragam/elips tetap tidak didukung, bukan diberi pemetaan sudut yang dikarang.

Penempatan media (content, background, surface) independen dari jenis simpul. Fit adalah unknown, contain, cover, stretch, atau original. Posisi (x,y) adalah jangkar pecahan pada ruang tersisa: 0 rata awal, 0.5 tengah, 1 rata akhir; pecahan di luar rentang diizinkan. Fit latar tidak boleh berasal dari gambar konten yang tidak terkait.

Rentang teks memuat text asli, batas opsional, dan tipografi: keluarga/sumber daya font, ukuran, ketebalan, tinggi baris, jarak huruf, warna, arah, penyelarasan, pembungkusan, dekorasi, dan kapitalisasi. Kapitalisasi (none, uppercase, lowercase, capitalize) mengubah penyajian secara independen dari teks asli dan nama aksesibel. Lukisan/gradien/efek teks yang tidak didukung tetap menjadi masalah. Ekspresi CSS native sembarang bukan nilai tata letak atau lukisan kanonis.

Sumber daya dan font

Sumber daya memiliki id, kind, uri opsional, mimeType, sha256, bytes, dan face font. Jenisnya unknown, image, vector, font, video, audio, paint. Referensi sumber daya simpul dan tipografi diselesaikan dalam dokumen ini. Face font merekam keluarga, jenis/referensi bukti, rentang ketebalan opsional, status miring, dan cakupan codepoint Unicode. Pertahankan byte arsip dan pilih face yang sesuai. Nama keluarga atau URL saja tidak membuktikan font yang dimaksud termuat atau fallback setara.

Tindakan menyatakan kemampuan interaksi: unknown, activate, edit, scroll, navigate, focus, hover, back, dengan tujuan opsional. Transisi memiliki bingkai sumber, simpul sumber opsional dan bingkai tujuan, tindakan, hasil, serta asal-usul. nodeId-nya selalu milik bingkai sumber.

Hasil	Makna
`unknown`	Hasil belum dibuktikan.
`changed`	Perubahan hasil diamati.
`unchanged`	Tidak ada perubahan diamati.
`failed`	Tindakan gagal.
`performedUnverified`	Input terkirim tanpa membuktikan hasil yang diharapkan.

ID snapshot baru atau caret berubah tidak membuktikan menu terbuka. Modal terbuka harus mempertahankan bingkai lengkap yang diamati: latar, panel, anak, dan konten di bawahnya. Ikuti entryFrameId dan transisi untuk membedakan persetujuan, konten yang ditutup, tab dialog, pencarian, dan menu terbuka. Pengukuran status paksa dan input pointer/sentuh nyata tetap memiliki bukti berbeda. Pemutaran ulang sumber bukan uji fungsional antarmuka baru yang dihasilkan.

Gerakan

Catatan gerakan simpul/transisi memuat property, durationMs, keyframes, kind, evidence, serta delayMs, iterations, dan easing Bézier kubik (x1, y1, x2, y2) opsional. Waktu dalam milidetik; offset 0–1 dalam urutan meningkat. Koordinat x easing adalah 0–1.

Properti	Komponen `value` keyframe
`opacity`	`[alpha]`, 0–1.
`translation`	`[x, y, z]`, satuan logis.
`scale`	`[x, y, z]`, pengali.
`rotation`	`[x, y, z]`, radian.
`bounds`	`[x, y, width, height]`, satuan logis.
`color`	`[red, green, blue, alpha]`, 0–1.

Opsi yang dihilangkan tetap tidak diketahui. Iterasi nol berarti tidak diputar. Pengulangan tidak diketahui atau tanpa batas tidak boleh diubah menjadi jumlah terbatas tebakan. Deklarasi CSS/WAAPI bersifat declared; sampel teramati dapat measured. Gambar diam atau dua titik akhir tidak membuktikan waktu maupun easing.

Validasi dan cakupan

Validasi struktur dengan skema ekspor, lalu validasi semantik: ID unik sesuai cakupan, referensi valid, induk tanpa siklus, geometri berhingga, ukuran nonnegatif, warna ternormalisasi, rentang font/codepoint, penyamaran, dan dimensi gerakan. SceneValidator backend menegakkan invariant tambahan ini. JSON Schema sendiri bukan validator graf atau privasi lengkap.

Skema struktural saat ini menolak kolom tidak dikenal dan nilai enum integer. Tetapkan pengenal serta hash-nya; gunakan adaptor eksplisit untuk versi format berbeda. Jangan tafsirkan ulang data tidak dikenal sebagai tata letak native. Kolom yang ada mempertahankan makna; perubahan makna tidak kompatibel memerlukan pengenal format baru. Pembaruan server dapat mengubah byte skema yang berlaku: simpan skema/hash bersama tiap ekspor arsip.

SceneIssue memiliki code, message, dan frameId/nodeId opsional. Baca artefak lengkap, bukan hanya pratinjau manifes, dan perhatikan pemotongan bingkai. Batas validator saat ini adalah 100 profil, 500 bingkai, 20.000 sumber daya, 100.000 simpul total, dan 20.000 simpul per bingkai. Perolehan/transport dapat memiliki batas lebih rendah; angka ini tidak menjanjikan cakupan tangkapan.

Tangkapan Web baru menghasilkan Scene bersama diagnostik native. Data Web lama dapat dikonversi dengan celah eksplisit. Adaptor Android dapat menormalkan pengukuran native, tetapi akses API/MCP tetap memerlukan Scene native terbitan. Dukungan model data tidak membuat lingkungan yang belum ditangkap tersedia. Status, sumber daya, gerakan, dan pengamatan responsif yang hilang tetap tidak diketahui. Keberhasilan ekspor atau validitas skema tidak membuktikan kesetiaan reproduksi.

Kebijakan pengajuan permintaan

Ketersediaan permintaan independen dari ketersediaan tangkapan katalog. Administrator mengaturnya melalui Requests → Job defaults → Request submissions. ProductRequestJobDefaults.Submission tersimpan berisi Enabled dan Targets bertipe (Type, Environment). Pengaturan lama tanpa anggota ini mempertahankan default: Desktop/Web, Desktop/WebExtension, dan Mobile/Web. Menonaktifkan pengajuan mempertahankan pilihan dan permintaan yang ada. API platform dan MCP terautentikasi sama-sama memvalidasi kebijakan terkini sebelum membuat permintaan. Request-options mengembalikan daftar platforms kosong saat ditutup; MCP juga mengembalikan enabled: false. ID lingkungan publik tetap web dan web-extension, bukan nama enum. Pemilih katalog memakai ketersediaan tangkapan per produk dan menyembunyikan pasangan yang tidak tersedia.

Target permintaan berkelompok

Klien baru mengirim CreateRequestRequest.targets sebagai pasangan platform/lingkungan eksplisit. Contohnya:

{
  "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" }
  ]
}

Server memvalidasi tiap pasangan terhadap ketersediaan permintaan terkini dan menyimpannya dalam detail permintaan bertipe. Persetujuan hanya membuat pasangan yang dipilih: contoh ini tidak membuat tugas Desktop/Web. views dan implementations tetap diterima untuk klien lama dan mewakili produk Kartesius keduanya; jangan gabungkan dengan targets. Sumber situs adalah url; tugas ekstensi memakai webExtensionUrl. Untuk pembaruan, kirim catalogId yang ada dan target tanpa tautan sumber. Pilih produk dahulu: platform hanya menawarkan pasangan platform/lingkungannya yang telah ditangkap dan kini diaktifkan untuk permintaan. Server secara mandiri menolak target yang tidak ada pada produk itu, menentukan sumber tiap lingkungan dari tangkapan terbitan produk tersebut, dan mengabaikan tautan pengganti dari klien. Ringkasan permintaan publik menghilangkan sumber ekstensi bersama detail permintaan privat.

Bukti Scene tambahan

Skema terkini menyertakan themes dengan token bertipe dan layoutSamples dengan pengukuran jarang pada lebar lain. Sampel merujuk node frameId; bukan frame dan tidak mengukur ulang teks atau tampilan. Node yang tidak disampel tidak berarti tersembunyi. nodes[].states memuat perubahan tampilan: bidang patch yang ada mengganti nilai, yang tidak ada tetap, dan daftar diganti seluruhnya. Layout mendukung flow, grow, shrink, basis, selfAlignment, order, gridCell; paint mencakup gradien dan gaya/posisi goresan. Bukti opsional ini bisa tidak ada pada tangkapan lama. Pertahankan asal dan jangan simpulkan aturan responsif dari satu pengukuran.

Lingkungan Web Extension​

Transport dan perolehan​

Envelope ekspor​

Dokumen dan identitas​

Fakta dan nilai tidak diketahui​

Koordinat dan profil​

Simpul, tata letak, dan lukisan​

Sumber daya dan font​

Tindakan dan status modal​

Gerakan​

Validasi dan cakupan​

Kebijakan pengajuan permintaan​

Target permintaan berkelompok​

Bukti Scene tambahan​