# PUCKS Saat Yüzü (Clock Face) Spesifikasyonu
**Spec Versiyonu: 3.0.0** · Son güncelleme: 2026-09-07

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",
  "requires": { "custom_clock_schema": 3 },
  "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`) |
| `requires.custom_clock_schema` | Şema 3 alanları kullanılıyorsa `3` |
| `bgGradient` | `{ "from":"#RRGGBB", "to":"#RRGGBB", "direction":"VERTICAL|HORIZONTAL", "steps":2..120 }` |
| `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ı) |
| `showWhen` | `ALWAYS` · `BLINK` · `SECOND_EVEN` · `SECOND_ODD` |
| `pulse` | `true`: opaklığı iki saniyelik yumuşak döngüyle hareketlendirir |

> **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`/`text_tr`/`text_en`; `{time}`, `{date}`, `{temp}`, `{weather}`; `timeFormat`, `dateFormat`, `maxWidth`, `shadowColor`, `shadowX`, `shadowY` |
| `TIME` | `format`: zaman biçimi veya `ANALOG`; analogda `showFace`, `showTicks`, `showSeconds`, `faceColor`, `hourColor`, `minuteColor`, `secondColor` |
| `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_ROUND_RECT` | `radius` ile yuvarlatılmış kart; `format:"HOLLOW"` destekler |
| `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` |
| `SHAPE_ARC` | `width` dış ve `height` iç yarıçap; `start`, `end`; `bind`: `seconds`/`minutes`/`hours` |
| `PROGRESS_BAR` | `width`, `height`, `radius`, `trackColor`; `bind`: `seconds`/`minutes`/`hours`/`day` veya `value`/`max` |

`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).

`bgImage:true`, aynı klasördeki `preview.jpg` dosyasını tam ekran arka plan olarak
çizer. `settings.json` içindeki `bg` ve `color`, uygulamanın tema kaplamasıdır.

## 5. Komple Örnek

```json
{
  "requires": { "custom_clock_schema": 3 },
  "bgColor": "#08111F",
  "bgGradient": {
    "from": "#08111F", "to": "#241044", "direction": "VERTICAL", "steps": 60
  },
  "elements": [
    { "type": "SHAPE_ROUND_RECT", "x": 18, "y": 62, "width": 204,
      "height": 112, "radius": 18, "color": "#101B34", "opacity": 92 },
    { "type": "TEXT", "text": "{time}", "timeFormat": "%H:%M", "x": 120,
      "y": 104, "font": 7, "size": 2, "maxWidth": 190, "align": "CENTER",
      "color": "#FFFFFF", "shadowColor": "#000000", "shadowX": 3, "shadowY": 3 },
    { "type": "TEXT", "text": "{date}  {temp}°", "dateFormat": "%d %b",
      "x": 120, "y": 148, "font": 2, "color": "#B9C8FF" },
    { "type": "PROGRESS_BAR", "x": 28, "y": 190, "width": 184,
      "height": 7, "radius": 4, "bind": "seconds", "max": 59,
      "trackColor": "#27324F", "color": "#63E6FF" },
    { "type": "SHAPE_CIRCLE", "x": 120, "y": 216, "width": 3,
      "color": "#63E6FF", "pulse": true }
  ]
}
```

---

## 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.
- `clockface.json` en fazla 64 KiB ve 64 element olabilir; geometriyi 0–239 alanında tut.

---

## 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.