
# Canvas

Canvas menyediakan tampilan menyeluruh yang diperkecil, mirip Figma, untuk semua halaman yang dikelola Blockstudio. Setiap halaman ditampilkan sebagai artboard iframe aktif dalam satu baris horizontal. Geser dengan trackpad, lalu zoom dengan gerakan pinch atau Ctrl+scroll.

## Aktivasi

Canvas tersedia sebagai halaman admin tersembunyi. Buka:

```
/wp-admin/admin.php?page=blockstudio-canvas
```

Halaman ini hanya dapat diakses jika `dev.canvas.enabled` bernilai `true` dan pengguna saat ini memiliki kapabilitas `edit_posts`.

## Pengaturan

Aktifkan canvas dan konfigurasikan perilakunya di `blockstudio.json` tema Anda:

```json title="blockstudio.json"
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
```

| Properti | Tipe | Default | Deskripsi |
|----------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Aktifkan fitur canvas. |
| `adminBar` | `boolean` | `true` | Tampilkan bilah admin WordPress di dalam iframe artboard. Atur ke `false` untuk pratinjau yang lebih rapi. |

Kedua pengaturan juga tersedia sebagai filter:

```php
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');
```

## Tampilan

Beralih tampilan menggunakan menu dropdown di sudut kanan atas.

- **Halaman**: Semua halaman yang dikelola Blockstudio sebagai artboard selebar penuh dalam satu baris.
- **Blok**: Semua blok Blockstudio terdaftar dalam tata letak kisi, masing-masing dirender dengan nilai atribut defaultnya.

## Inventaris Publik dan API Dokumen

`Canvas` menyediakan kontrak PHP berversi dan netral terhadap konsumen bagi alat yang membutuhkan konten terdaftar yang sama tanpa perlu membangun ulang logika penemuan atau perenderan Blockstudio:

```php
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);
```

Versi saat ini tersedia sebagai `Canvas::SCHEMA_VERSION`. Hasil inventaris mencakup:

- `inventory`: `pages`, `blocks`, `patterns`, `templates`, `parts` yang dinormalisasi, serta contoh keluarga `ui` publik
- `order`: urutan tampilan stabil lintas jenis
- `sources`: jalur sumber terpilih yang tepat dengan asal-usul pada setiap rekaman; `source` pada rekaman halaman adalah identitas sumbernya yang stabil, sedangkan `path` adalah jalur templat render fisik
- `warnings` dan `errors`: masalah terstruktur, bukan output yang dihasilkan
- `deleted`: pengenal yang diminta tetapi sudah tidak ada
- `selection`: pilihan yang dinormalisasi dan apakah pilihan itu ditargetkan

`Canvas::documents()` menambahkan satu dokumen render lengkap untuk setiap rekaman terpilih. Setiap dokumen berisi isi, HTML yang dirangkai, nama blok yang seluruh dependensinya terpenuhi, serta CSS, JavaScript, modul, bootstrap interaktivitas, global UI yang dibundel, dan output Tailwind. Dokumen halaman menggunakan pembungkus konten `<main>` semantik; pemanggil dapat mengganti atau menonaktifkannya melalui opsi dokumen Render bersama. Setiap halaman terpilih dirender dalam konteks WordPress frontend yang dipulihkan secara tersendiri, sehingga conditional query, filter body-class, shortcode, tata letak, pengalihan, dan callback `wp_enqueue_scripts` menerima halaman tersebut sebagai konteksnya, bukan permintaan admin atau REST yang meminta hasil Canvas. Kelas body yang diberikan pemanggil digabungkan dengan kelas kontekstual halaman, dan registri enqueue frontend diisolasi antar dokumen. Canvas menyelesaikan callback siklus hidup tersebut berdasarkan nama fungsi publik WordPress, sehingga konteks yang sama tetap terjaga saat Blockstudio dimuat melalui Composer atau namespace aplikasi yang dipindahkan.

### Semantik pilihan persis

Pemilihan bersifat ketat:

- Tanpa kunci jenis yang dikenali, semua jenis dimuat.
- `true`, `null`, atau `"*"` memuat semua rekaman untuk jenis tersebut.
- String atau daftar memuat hanya ID, nama, slug, jalur, atau jalur sumber yang cocok persis.
- String/daftar kosong atau `false` tidak memuat apa pun untuk jenis tersebut.
- Setelah kunci jenis apa pun tersedia, jenis yang tidak dicantumkan tidak ditemukan, disinkronkan, dirender, atau dikompilasi.

Dengan begitu, permintaan yang hanya mencakup perubahan aman untuk proyek besar. Blok dan halaman yang ada dicari melalui registri kanonisnya. Jika permintaan frontend hanya memuat proyeksi halaman yang tersimpan, Canvas melakukan penemuan sumber hanya-baca dan menggabungkan ID post serta permalink yang cocok tanpa menyinkronkan konten. Penggabungan identitas yang sama diterapkan ketika sumber penemuan logis terlebih dahulu mengisi registri berbasis sumber, sehingga perenderan halaman kontekstual tetap menggunakan post WordPress terkelola yang cocok. Topologi sesi langsung baru ditemukan hanya di sekitar direktori yang berubah, sedangkan sumber pola terpilih dan templat Site Editor dikompilasi hanya setelah dipilih.

Endpoint penyegaran REST mengikuti aturan yang sama untuk parameter kueri `blocks` dan `pages` yang sudah ada. Contohnya, `?blocks=theme/hero` mengembalikan blok tersebut tanpa halaman; gunakan kedua parameter untuk respons campuran. Pemanggilan endpoint tanpa parameter apa pun akan mempertahankan respons lama yang lengkap.

## Mode Langsung

Mode langsung menggunakan Server-Sent Events (SSE) untuk mendeteksi perubahan file dan memperbarui canvas secara real-time. Saat Anda mengedit templat blok, templat halaman, atau stylesheet, artboard yang terdampak akan otomatis diperbarui dalam waktu sekitar satu detik.

Aktifkan atau nonaktifkan mode langsung dari menu dropdown. Indikator hijau yang berdenyut akan muncul saat mode ini aktif. Pengaturan ini tersimpan antar sesi melalui localStorage.

Mode langsung melacak perubahan pada file `.php`, `.json`, `.css`, `.scss`, `.js`, `.twig`, dan `.html` di dalam direktori blok dan halaman. Perubahan yang dikenali hanya akan memperbarui blok atau halaman terdaftarnya. Blok atau halaman yang benar-benar baru memicu satu pemindaian topologi khusus direktori, sehingga pembuatan konten selama sesi langsung tetap berfungsi tanpa memindai ulang sumber yang tidak terkait.

## Mode Fokus

Klik label artboard mana pun untuk masuk ke mode fokus. Artboard terpilih memenuhi viewport selebar penuh dengan pengguliran vertikal. Tekan Escape atau klik tombol tutup untuk kembali ke ikhtisar.

## Kontrol

| Aksi | Input |
|--------|-------|
| Geser | Scroll / seret dua jari di trackpad |
| Zoom | Ctrl+scroll atau pinch |
| Sesuaikan dengan tampilan | Menu dropdown |
| Zoom ke 100% | Menu dropdown |
| Fokus ke artboard | Klik label artboard |
| Keluar dari fokus | Escape / tombol tutup |

## Keamanan

Skrip kanvas dan data halaman hanya dimuat jika semua kondisi terpenuhi:

- Pengaturan `dev.canvas.enabled` bernilai `true`.
- Pengguna saat ini memiliki kemampuan `edit_posts`.

Pengunjung publik tidak pernah melihat skrip kanvas atau metadata halaman.
