# PUCKS Saat Yüzü (Clock Face) Spesifikasyonu
**Spec Versiyonu: 1.0.0** · Son güncelleme: 2026-06-24

Saat yüzleri C++ kodu **DEĞİL**, **JSON** ile tasarlanır. Cihazdaki özel saat çizim
motoru (`custom_clock_drawer.cpp`) bu JSON'u okuyup 240×240 ekrana çizer. Bu ekrandaki
**"Kodla Yükle"** ile JSON'unu doğrudan cihaza gönderip anında test edebilirsin.

---

## 0. Güvenlik (plugin'lerle aynı model)

> Saat yüzü de **bildirimsel veridir, kod değildir.** Cihazda kendi kodunu çalıştıramaz;
> yalnızca hazır çizim motorunu yapılandırır. Rastgele bellek/ağ/dosya erişimi YOKTUR.
> Cihaz şunları zorunlu doğrular: geçerli JSON, `id` güvenli (`[a-z0-9_-]`, ≤32, `..`/`/`
> yasak), hedef `240×240`, boyut limitleri. Bu sınırlar **gevşetilmez**.

---

## 1. İki Dosya

| Dosya | Zorunlu | İçerik |
|---|---|---|
| `manifest.json` | ★ | Kimlik/market bilgisi (id, name, version…) |
| `clockface.json` | ★ | Tasarım: arka plan + `elements[]` |

> **Kodla Yükle** ekranında sadece **`clockface.json`** (tasarım) ve bir **id/ad**
> girmen yeter; manifest'i app senin için üretir.

### manifest.json
```json
{
  "id": "matrix_clock",
  "name": "Matrix Hack",
  "version": "1.0.0",
  "description": "Yesil matrix stili dijital saat",
  "author": "Arda",
  "target_resolution": "240x240"
}
```

---

## 2. clockface.json (Tasarım)

```json
{
  "bgColor": "#000000",
  "bgPattern": "SOLID",
  "bgPatternColor": "#333333",
  "elements": [
    { "type": "TIME", "format": "%H:%M", "x": 120, "y": 100,
      "size": 1, "font": 7, "color": "#00FF00", "align": "CENTER" }
  ]
}
```

| Alan | Açıklama |
|---|---|
| `bgColor` | Arka plan rengi (`#RRGGBB`) |
| `bgPattern` | `SOLID` · `GRID` · `DOTS` · `STRIPES_H` · `STRIPES_V` · `DIAGONAL` · `CHECKERBOARD` |
| `bgPatternColor` | Desen rengi (pattern ≠ SOLID ise) |
| `elements` | Ekrana çizilecek öğeler dizisi (sırayla, üst üste çizilir) |

---

## 3. Ortak Element Alanları

Her element için geçerli:

| Alan | Açıklama |
|---|---|
| `type` | Element türü (§4) |
| `x`, `y` | Merkez/konum koordinatı (0–240) |
| `color` | `#RRGGBB` |
| `opacity` | 0–100 şeffaflık (vermezsen 100) |
| `align` | `LEFT` · `CENTER` · `RIGHT` (metin/saat hizası) |

> **Güvenli alan:** kenarlardan 8–12 px boşluk bırak; metin/şekil ekrandan taşmasın.

---

## 4. Element Türleri

### Metin / Bilgi
| `type` | Özel alanlar |
|---|---|
| `TEXT` | `text` (yazı), `size` (1–3), `font`: `1, 2, 4, 6, 7, 8` |
| `TIME` | `format`: `"%H:%M"`, `"%H:%M:%S"`, `"%I:%M"`, ya da `"ANALOG"` |
| `DATE` | `format`: `"%d.%m.%Y"`, `"%Y-%m-%d"`, `"%d %b"` … |
| `WEATHER_TEMP` | (sıcaklık, ör. `24°`) |
| `WEATHER_ICON` | `format`: `"ANIMATED"` veya `"SIMPLE"` |

### Şekiller (`width`, `height` kullanır; `format` ile stil)
| `type` | Not |
|---|---|
| `SHAPE_RECT` | `format:"HOLLOW"` → yalnız çerçeve |
| `SHAPE_CIRCLE` | **yarıçap** = `width`; `format:"HOLLOW"` |
| `SHAPE_LINE` | `format:"DASHED"` → kesik çizgi |
| `SHAPE_TRIANGLE` / `SHAPE_STAR` / `SHAPE_HEART` / `SHAPE_DIAMOND` | dolu (varsayılan) veya `HOLLOW` |

`font`: geçerli değerler `1, 2, 4, 6, 7, 8` — `0`, `3` ve `5` **yoktur**.
`2` ince, `4` orta, `7` yedi-segment dijital, `8` büyük. `size` çarpan (1=normal).

---

> **Bu dosya bir özettir, tam referans değildir.**
> Aşağıdaki özellikler cihazda ÇALIŞIR ama bu dosyada anlatılmaz:
> `SHAPE_ARC` + `bind: seconds/minutes/hours` (canlı gösterge yayları),
> `bgImage` (tam ekran arka plan; `preview.jpg`'yi çizer), `text_tr`/`text_en`
> (iki dilli metin), `settings.json` tema kaplaması, `requires.custom_clock_schema`.
> Güncel ve tam anlatım: https://pucks.tech/saat-yuzu-rehberi
> Çelişki olursa **rehber sayfası ve firmware** geçerlidir.

---

## 5. Komple Örnek

```json
{
  "bgColor": "#05070A",
  "bgPattern": "GRID",
  "bgPatternColor": "#102030",
  "elements": [
    { "type": "SHAPE_CIRCLE", "format": "HOLLOW", "x": 120, "y": 120,
      "width": 110, "color": "#00E5FF", "opacity": 35 },
    { "type": "TEXT", "text": "SMART DISPLAY", "x": 120, "y": 36,
      "size": 1, "font": 2, "color": "#8AF7FF", "align": "CENTER" },
    { "type": "TIME", "format": "%H:%M", "x": 120, "y": 99,
      "size": 1, "font": 7, "color": "#FFFFFF", "align": "CENTER" },
    { "type": "DATE", "format": "%d.%m.%Y", "x": 120, "y": 174,
      "size": 1, "font": 2, "color": "#B8C7FF", "align": "CENTER" }
  ]
}
```

---

## 6. Kalite İpuçları
- Yüksek kontrast (koyu zemin + parlak vurgu) okunaklı kalır.
- Tek/çift haneli saat, uzun tarih ve farklı dillerde taşmayı test et.
- Az ama anlamlı element; ekranı kalabalıklaştırma.
- Saniye gösteriyorsan (`%S`) animasyon akıcılığını kontrol et.

---

## 7. Nasıl Yüklenir
1. **Kodla Yükle** (bu ekran): `clockface.json`'unu yapıştır + id/ad ver → **Yükle ve
   Etkinleştir** → cihaza kurulur ve hemen aktif olur.
2. **Market**: yayınlanan yüzler `index.json` üzerinden listelenir, herkes indirir.