@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/README.md

@@ -1,247 +1,286 @@
-# @sametalmdr/word-editor
-
-Tarayıcıda çalışan bir **sayfa tuvali** editörü: sabit sayfa yüzeyleri
-üzerinde mutlak konumlu metin kutularının içeriğini ve yerleşimini düzenler,
-gerçek `.docx` dosyalarını açar ve orijinal paketi yamalayarak geri kaydeder.
-Akan metin / sayfalama / tablo yok (ADR-0006). Sıfır runtime bağımlılık, saf
-ESM, MIT lisanslı.
-
-> ⚠️ **Durum (2026-10-26): 0.2.0-alpha hazır (0.1.0-alpha'ya çok satırlı değer eklendi); npm'de yayını sahip yapar.** Editör çalışıyor:
-> `.docx` aç, metin yaz, kutu taşı, kalın/italik/altı çizili, punto, hizalama,
-> girinti, Kaydet. **Gerçek Word'de doğrulanan:** metin, kutu taşıma ve
-> kalın — kaydedilen dosya onarımsız açılıyor ve değişiklik görünüyor.
-> İtalik ve altı çizili aynı yazma yolundan geçiyor, ama Word'de ayrıca
-> açılmadı. Punto, hizalama ve girinti dosyaya yazılıyor ama **Word'de henüz
-> doğrulanmadı** (FIDELITY.md'de AÇIK). **Bugün yalnız örnek sayfalardan
-> kullanılabiliyor** (aşağıda `app.html`): paketin public API'si `createEditor()`
-> (bir `doc` alır, tuval editörünü dışa vermez). `.docx` import/export'u ve şablon doldurma
-> **`/docx` alt yolunda** (aşağıda; `0.2.0-alpha`), `/canvas` FR4'te geliyor
-> ([docs/MASTER-PLAN.md](./docs/MASTER-PLAN.md)). Kaydedilmeyen düzenlemeler ve bilinen
-> iki hata (yapıştırılan kutu kaydı engelliyor, silinen kutu sessizce
-> kayboluyor): [FIDELITY.md](./FIDELITY.md) "Kutu yerleşimi" bölümü. Yol
-> haritası: [ARCHITECTURE.md](./ARCHITECTURE.md) §6.
-
-Bu proje Microsoft Word'ün bir klonu değildir ve Microsoft ile hiçbir
-bağlantısı yoktur.
-
-## Kurulum
-
-```bash
-npm install @sametalmdr/word-editor@0.2.0-alpha
-```
-
-## Saf HTML ile kullanım
-
-Build adımı gerekmez.
-
-```html
-<link rel="stylesheet" href="./node_modules/@sametalmdr/word-editor/dist/styles.css" />
-<word-editor></word-editor>
-<script type="module">
-  import "@sametalmdr/word-editor/element";
-</script>
-```
-
-## React ile kullanım
-
-`react` bir optional peer dependency'dir — kendi React sürümünüzü kurmanız
-gerekir.
-
-```jsx
-import { WordEditor } from "@sametalmdr/word-editor/react";
-import "@sametalmdr/word-editor/styles.css";
-
-function App() {
-  return <WordEditor />;
-}
-```
-
-## Framework-agnostic çekirdek API
-
-```js
-import { createEditor } from "@sametalmdr/word-editor";
-
-const editor = createEditor({ container: document.getElementById("root") });
-// ...
-editor.destroy();
-```
-
-## `/docx` — şablon doldurma (DOM'suz; Node, Deno ve tarayıcı için yazıldı)
-
-`{etiket}`li bir `.docx` şablonunu veriyle doldurur. Orijinal paketi yamalar: yalnız
-`word/document.xml` yeniden yazılır, başka her parça bayt bayt aynı kalır. Hiçbir ağ isteği
-atmaz; sunucuda (ör. Supabase Edge Functions) ve tarayıcıda aynı fonksiyon. Kapılarla sınanan:
-Node 24.13.1 ve Deno 2.1.4; tarayıcıda (Chrome 152) yalnız incelendi, kanıt sınıfıyla değil.
-
-```js
-import { fillTemplate, inspectTemplate, TemplateError } from "@sametalmdr/word-editor/docx";
-
-// template: bir .docx dosyasının baytları (Uint8Array)
-try {
-  const { bytes, documentXml, report } = await fillTemplate(template, {
-    firma_adi: "Alrosoft Ltd",
-    rapor_no: "RPR-2026-0001",
-    notlar: null, // boş: serbest, report.empty'de listelenir
-  });
-  // bytes: doldurulmuş .docx
-  // documentXml: doldurulmuş word/document.xml, sıkıştırılmamış — çalışma ortamları
-  //   arasında karşılaştırmayı bunun özetiyle yapın (zip baytları ortama göre değişir)
-  // report: etiket -> [{docPrId, page}], empty, unused, warnings, counts, engine
-} catch (err) {
-  if (!(err instanceof TemplateError)) throw err;
-  for (const p of err.problems) console.log(p.code, p.tag, p.page); // hepsi birlikte
-}
-
-const info = await inspectTemplate(template); // doldurmadan: etiketler, sorunlar, uyarılar
-```
-
-Kurallar ([ADR-0037](./docs/adr/0037-template-fill-engine.md),
-[ADR-0038](./docs/adr/0038-generated-output-keeps-both-copies-equal.md)):
-
-- Etiket bir `w:t`'nin metninin tamamıdır: `{firma_adi}`, ad `[a-z][a-z0-9_]*`. Bölünmüş
-  etiket, `{ ad }`, `{#döngü}`, `{%görsel}` ve "Tarih: {tarih}" gibi karışık metin reddedilir.
-- Etiket yalnız metin kutusunda olabilir. Kutunun iki kopyası (`mc:Choice` ve `mc:Fallback`)
-  birlikte yazılır ve eşit kaldıkları denetlenir — Word yalnız Choice'u okur, yanlış bir
-  Fallback Word'de görünmez (FILL-E2).
-- Eksik anahtar hata; eksiklerin hepsi tek `TemplateError`'da. `null`, `""` ve yalnız boşluk
-  boştur: serbest, raporlanır.
-- Değer string olmalı; sekme ve denetim karakterleri reddedilir. Tarih ve sayı biçimlemek
-  çağıranın işi.
-- Satır sonu yalnız `multiline` seçeneğinin adlandırdığı etikette ve yalnız LF olarak
-  ([ADR-0039](./docs/adr/0039-multi-line-values.md)): her satır etiketin kendi run'ında, aralarında
-  `w:br`, run'ın biçimi her satırda. CR, CRLF, U+2028 ve U+2029 her etikette reddedilir — motor
-  değeri sessizce değiştirmez, normalleştirmek çağıranın işi. Şablonda olmayan bir ad
-  `UNKNOWN_MULTILINE_TAG`:
-
-  ```js
-  await fillTemplate(template, { ...data, notlar: "Birinci satır\nİkinci satır" }, { multiline: ["notlar"] });
-  ```
-
-  Kutunun alabileceğinden fazla satır Word'de sessizce kırpılır (FR3-WORD-ML2); sığmayı denetlemek
-  bugün çağıranın işi.
-- `validateTemplate(bytes, {expectedTags, multiline})` şablonun etiketlerini bir listeyle tam küme
-  olarak karşılaştırır. Bilinmeyen seçenek (`{linebreaks: true}` gibi) hata verir.
-- Rapor, sorunlar ve hata mesajları hiçbir değeri taşımaz.
-
-Bilinen sınırlar ve sınanan ortamlar: [CHANGELOG.md](./CHANGELOG.md).
-
-## Ürün sayfası — `app.html` (DOCX aç → düzenle → kaydet)
-
-Ribbon'lı tam editör. Paket henüz bu yüzeyi dışa vermediği için (yukarıdaki
-durum notu) bugün yalnız repo içinden çalışır:
-
-```bash
-npm run serve
-```
-
-```
-http://127.0.0.1:8080/examples/static/app.html
-```
-
-**Dosya** sekmesindeki **Dosya Seç** ile `test/corpus/` altındaki bir belgeyi
-seç (dosya yalnız okunur, değiştirilmez). Çift tık bir kutunun içinde metin moduna geçer,
-tek tık kutuyu seçer (ADR-0024). **Kaydet (.docx)** orijinal paketi yamalayarak
-indirir. "PDF indir" henüz bağlı değil — bugün PDF için görüntüleyicinin
-Ctrl+P'si var (aşağıda).
-
-## Corpus görüntüleyici (demo)
-
-46 corpus belgesini gerçek renderer ile tarayıcıda gösterir.
-**Görüntüleyici — düzenleme yok.** İki komut:
-
-```bash
-npm run corpus:canvas
-```
-
-```bash
-npm run serve
-```
-
-Sonra tarayıcıda aç:
-
-```
-http://127.0.0.1:8080/examples/static/viewer.html
-```
-
-Solda 46 belge, seçince sayfaları çizilir; başlıkta kutu/dekorasyon/sayfa
-sayısı ve render süresi görünür.
-
-**Çift tıklayarak açılmaz, ve bu ölçülmüş bir kısıt.** Chrome 151 /
-Windows 10 22H2'de `file://` üzerinde statik ES modül import'u, dinamik
-`import()` ve `fetch()` **üçü de bloklanıyor**; yalnızca inline klasik
-`<script>` koşuyor. Gerçek renderer'ı import etmenin başka yolu yok. Dört
-ölçümün tamamı [docs/viewer-measurement.md](./docs/viewer-measurement.md)
-§0'da; sunucu `node:http` ile yazıldı, **sıfır bağımlılık**, yalnızca
-loopback. Aynı kısıt `examples/static/canvas.html` ve `index.html` için de
-geçerli.
-
-`npm run corpus:canvas` Python ister (`scripts/docx-to-canvas-json.py`
-dönüştürücüsünü çağırır) ve bu yüzden `npm run ci`'nin parçası **değildir** —
-`corpus:check` ve `corpus:names` ile aynı gerekçe. Çıktı
-`examples/static/corpus-json/` altına yazılır, gitignore'ludur, her koşumda
-baştan üretilir. `test/corpus/` **okunur, asla yazılmaz** (CLAUDE.md #16).
-
-### PDF — Tier 0
-
-Görüntüleyicide **Ctrl+P → "PDF olarak kaydet"**. Sayfa yüzeyleri belgenin
-kendi boyutunda basılır (A4 dikey, A4 yatay ve A5 corpus'ta hepsi var), UI
-kromu gizlenir.
-
-**Bu bizim PDF writer'ımız değil, tarayıcınınki** — `ARCHITECTURE.md` §7'nin
-Tier 0'ı. Sunucuda üretilen, gömülü fontlu PDF FR5'te geliyor (eski MP10, yol
-haritasındaki P7); yolunu — kendi yazıcımız, pdf-lib ya da Cloudflare Browser Run — FR5
-başında sahip seçiyor (ADR-0036 Karar 5).
-
-**Gözle kontrol — henüz yapılmadı, yapılacaksa şöyle:** üç belgeyi seçip
-Ctrl+P ile önizlemeye bak; kâğıt boyutu belgenin kendi boyutuna oturmalı,
-kenar boşluğu olmamalı, sol liste ve üst başlık görünmemeli.
-
-| Belge | Beklenen kâğıt | Neden bu üçü |
-|---|---|---|
-| `AA01` | A4 dikey (595.5×842 pt) | corpus'un çoğunluğu |
-| `PK01` | **A4 YATAY** (842×595.5 pt) | sabit `A4` varsayımının kırılacağı yer |
-| `R001` | **A5** (420×595.5 pt) | ikinci kırılma noktası; 71 sayfa |
-
-Üçü de doğru basıyorsa sayfa boyutu belge başına yazılıyor demektir.
-
-Ölçüm sonuçları: [docs/viewer-measurement.md](./docs/viewer-measurement.md).
-
-## Tuval — kutu düzenleme (demo, P3b-a)
-
-Görüntüleyiciden farklı olarak **burada düzenleme var** — metin değil, kutu
-geometrisi: seç, tutamakla sürükle/boyutlandır, Ctrl+Z ile geri al,
-kopyala/yapıştır, dekoratif bir şeklin kenarına yaklaştırıp snap'i gör.
-`src/canvas/`'ın dokuz saf modülü + `CanvasController` + `Overlay`, gerçek
-bir tarayıcıya bağlı (`docs/adr/0018-canvas-interaction-layer.md`).
-
-```bash
-npm run serve
-```
-
-```
-http://127.0.0.1:8080/examples/static/canvas.html
-```
-
-Dosya seçiciyle bir belge JSON'u yükle: `test/fixtures/canvas/fifty-boxes.json`
-(50 kutu, 5 dekorasyon, 2 sayfa) hazır bir örnek; `npm run corpus:canvas`'ın
-ürettiği `examples/static/corpus-json/*.json` de aynı formatta çalışır.
-
-**Ölçülmemiş sabitler, sayfanın kendi geçici değerleri — kütüphaneye değil:**
-tutamak boyutu, snap eşiği, kademe eşikleri hiçbiri ölçülmedi (Ö2/Ö4,
-ADR-0018 §9.0). `canvas.html` kendi `EXAMPLE_METRICS` nesnesini enjekte
-ediyor; `src/canvas/controller.js`'in `requireMetrics`'i eksik alanda hâlâ
-gerçek `TypeError` atıyor, `src/` altına hiçbir varsayılan sızmadı.
-
-Aynı `file://` kısıtı geçerli (yukarıdaki görüntüleyici bölümüne bakınız).
-~~Metin düzenleme bu turun kapsamında değil~~ — 2026-08-29'dan beri
-(ADR-0024) çift tık kutunun içinde metin moduna geçiyor, ve sayfa artık
-`.docx` da açıp kaydedebiliyor. Ürün yüzeyi ise `app.html` (yukarıda).
-
-## Mimari
-
-Tasarım kararları için [ARCHITECTURE.md](./ARCHITECTURE.md),
-uyumluluk sözleşmesi için [FIDELITY.md](./FIDELITY.md).
-
-## Lisans
-
-MIT — bkz. [LICENSE](./LICENSE).
+# @sametalmdr/word-editor
+
+Tarayıcıda çalışan bir **sayfa tuvali** editörü: sabit sayfa yüzeyleri
+üzerinde mutlak konumlu metin kutularının içeriğini ve yerleşimini düzenler,
+gerçek `.docx` dosyalarını açar ve orijinal paketi yamalayarak geri kaydeder.
+Akan metin / sayfalama / tablo yok (ADR-0006). Sıfır runtime bağımlılık, saf
+ESM, MIT lisanslı.
+
+> ⚠️ **Durum (2026-10-26): 0.3.0-alpha hazır (0.2.0-alpha'ya `checkFit` eklendi); npm'de yayını sahip yapar. 0.2.0-alpha npm'de.** Editör çalışıyor:
+> `.docx` aç, metin yaz, kutu taşı, kalın/italik/altı çizili, punto, hizalama,
+> girinti, Kaydet. **Gerçek Word'de doğrulanan:** metin, kutu taşıma ve
+> kalın — kaydedilen dosya onarımsız açılıyor ve değişiklik görünüyor.
+> İtalik ve altı çizili aynı yazma yolundan geçiyor, ama Word'de ayrıca
+> açılmadı. Punto, hizalama ve girinti dosyaya yazılıyor ama **Word'de henüz
+> doğrulanmadı** (FIDELITY.md'de AÇIK). **Bugün yalnız örnek sayfalardan
+> kullanılabiliyor** (aşağıda `app.html`): paketin public API'si `createEditor()`
+> (bir `doc` alır, tuval editörünü dışa vermez). `.docx` import/export'u ve şablon doldurma
+> **`/docx` alt yolunda** (aşağıda; `0.3.0-alpha`), `/canvas` FR4b'de geliyor
+> ([docs/MASTER-PLAN.md](./docs/MASTER-PLAN.md)). Kaydedilmeyen düzenlemeler ve bilinen
+> iki hata (yapıştırılan kutu kaydı engelliyor, silinen kutu sessizce
+> kayboluyor): [FIDELITY.md](./FIDELITY.md) "Kutu yerleşimi" bölümü. Yol
+> haritası: [ARCHITECTURE.md](./ARCHITECTURE.md) §6.
+
+Bu proje Microsoft Word'ün bir klonu değildir ve Microsoft ile hiçbir
+bağlantısı yoktur.
+
+## Kurulum
+
+```bash
+npm install @sametalmdr/word-editor@0.3.0-alpha
+```
+
+## Saf HTML ile kullanım
+
+Build adımı gerekmez.
+
+```html
+<link rel="stylesheet" href="./node_modules/@sametalmdr/word-editor/dist/styles.css" />
+<word-editor></word-editor>
+<script type="module">
+  import "@sametalmdr/word-editor/element";
+</script>
+```
+
+## React ile kullanım
+
+`react` bir optional peer dependency'dir — kendi React sürümünüzü kurmanız
+gerekir.
+
+```jsx
+import { WordEditor } from "@sametalmdr/word-editor/react";
+import "@sametalmdr/word-editor/styles.css";
+
+function App() {
+  return <WordEditor />;
+}
+```
+
+## Framework-agnostic çekirdek API
+
+```js
+import { createEditor } from "@sametalmdr/word-editor";
+
+const editor = createEditor({ container: document.getElementById("root") });
+// ...
+editor.destroy();
+```
+
+## `/docx` — şablon doldurma (DOM'suz; Node, Deno ve tarayıcı için yazıldı)
+
+`{etiket}`li bir `.docx` şablonunu veriyle doldurur. Orijinal paketi yamalar: yalnız
+`word/document.xml` yeniden yazılır, başka her parça bayt bayt aynı kalır. Hiçbir ağ isteği
+atmaz; sunucuda (ör. Supabase Edge Functions) ve tarayıcıda aynı fonksiyon. Kapılarla sınanan:
+Node 24.13.1 ve Deno 2.1.4; tarayıcıda (Chrome 152) yalnız incelendi, kanıt sınıfıyla değil.
+
+```js
+import { fillTemplate, inspectTemplate, TemplateError } from "@sametalmdr/word-editor/docx";
+
+// template: bir .docx dosyasının baytları (Uint8Array)
+try {
+  const { bytes, documentXml, report } = await fillTemplate(template, {
+    firma_adi: "Alrosoft Ltd",
+    rapor_no: "RPR-2026-0001",
+    notlar: null, // boş: serbest, report.empty'de listelenir
+  });
+  // bytes: doldurulmuş .docx
+  // documentXml: doldurulmuş word/document.xml, sıkıştırılmamış — çalışma ortamları
+  //   arasında karşılaştırmayı bunun özetiyle yapın (zip baytları ortama göre değişir)
+  // report: etiket -> [{docPrId, page}], empty, unused, warnings, counts, engine
+} catch (err) {
+  if (!(err instanceof TemplateError)) throw err;
+  for (const p of err.problems) console.log(p.code, p.tag, p.page); // hepsi birlikte
+}
+
+const info = await inspectTemplate(template); // doldurmadan: etiketler, sorunlar, uyarılar
+```
+
+Kurallar ([ADR-0037](./docs/adr/0037-template-fill-engine.md),
+[ADR-0038](./docs/adr/0038-generated-output-keeps-both-copies-equal.md)):
+
+- Etiket bir `w:t`'nin metninin tamamıdır: `{firma_adi}`, ad `[a-z][a-z0-9_]*`. Bölünmüş
+  etiket, `{ ad }`, `{#döngü}`, `{%görsel}` ve "Tarih: {tarih}" gibi karışık metin reddedilir.
+- Etiket yalnız metin kutusunda olabilir. Kutunun iki kopyası (`mc:Choice` ve `mc:Fallback`)
+  birlikte yazılır ve eşit kaldıkları denetlenir — Word yalnız Choice'u okur, yanlış bir
+  Fallback Word'de görünmez (FILL-E2).
+- Eksik anahtar hata; eksiklerin hepsi tek `TemplateError`'da. `null`, `""` ve yalnız boşluk
+  boştur: serbest, raporlanır.
+- Değer string olmalı; sekme ve denetim karakterleri reddedilir. Tarih ve sayı biçimlemek
+  çağıranın işi.
+- Satır sonu yalnız `multiline` seçeneğinin adlandırdığı etikette ve yalnız LF olarak
+  ([ADR-0039](./docs/adr/0039-multi-line-values.md)): her satır etiketin kendi run'ında, aralarında
+  `w:br`, run'ın biçimi her satırda. CR, CRLF, U+2028 ve U+2029 her etikette reddedilir — motor
+  değeri sessizce değiştirmez, normalleştirmek çağıranın işi. Şablonda olmayan bir ad
+  `UNKNOWN_MULTILINE_TAG`:
+
+  ```js
+  await fillTemplate(template, { ...data, notlar: "Birinci satır\nİkinci satır" }, { multiline: ["notlar"] });
+  ```
+
+  Kutunun alabileceğinden fazla satır Word'de sessizce kırpılır (FR3-WORD-ML2); `checkFit` bunu
+  doldurmadan önce söyler (aşağıda).
+- `validateTemplate(bytes, {expectedTags, multiline})` şablonun etiketlerini bir listeyle tam küme
+  olarak karşılaştırır. Bilinmeyen seçenek (`{linebreaks: true}` gibi) hata verir.
+- Rapor, sorunlar ve hata mesajları hiçbir değeri taşımaz.
+
+### `checkFit` — değer kutusuna sığıyor mu? ([ADR-0042](./docs/adr/0042-dom-free-fit-check.md))
+
+Word kutuya sığmayan değeri sessizce kırpar. `checkFit` doldurmadan önce her değerin satırını şablonun
+kendi kutusuyla karşılaştırır. Tarayıcı gerekmez: Calibri'nin genişlikleri, onunla metrik-uyumlu
+Carlito'dan (OFL-1.1) bir tablo olarak paketin içinde.
+
+```js
+import { checkFit, fillTemplate } from "@sametalmdr/word-editor/docx";
+
+const fit = await checkFit(template, data, { ...manifest.options, ...manifest.fit });
+if (!fit.ok) {
+  for (const t of fit.tags) {
+    for (const o of t.occurrences) {
+      if (o.status === "overflows" || o.status === "unknown") console.log(t.name, o.status, o.reason, o.marginPt);
+    }
+  }
+}
+```
+
+- **Durumlar:** her occurrence `fits`, `overflows`, `unknown` ya da `empty` döner.
+  - Ölçülen occurrence en dar satırının `widthPt`, `availablePt` ve `marginPt` değerlerini taşır.
+  - `unknown` (ve sekmesini durağından iten `overflows`) kapalı bir listeden bir `reason` taşır.
+  - Etiketin durumu, occurrence'larının en kötüsüdür.
+- **Tolerans:** τ = 0,05 pt + glif başına 0,025 pt.
+  - `fits`: satır τ payıyla sığar.
+  - `overflows`: satır τ'nun ötesinde taşar.
+  - Aradaki `unknown(BORDERLINE)` için karar verilmez.
+- **Sondaki boşluklar:** Word'ün onları kenarın ötesine asılı bırakıp bırakmadığı sınanmadı. `fits` onları
+  sayarak sığmayı, `overflows` onlarsız taşmayı ister; yalnız onlar karar veriyorsa `unknown(TRAILING_SPACE)`.
+  Değeri kırpmak bu durumu ortadan kaldırır.
+- **Çok satırlı değer** `capacity` ister: `{etiket: satır}`, manifestin `fit` bloğunda. Taşan satır en az
+  bir satır daha alır. Satır sayısı ile taşan satır sayısının toplamı kapasiteyi geçerse `overflows`.
+- **Kırma yok:** satır kırma noktası seçilmez. Ölçülemeyen biçim `unknown` döner (başka bir font,
+  döndürülmüş ya da gruplanmış kutu, `kern`, sola dayalı olmayan sekme durağı, iç boşluklu kutuda ya da
+  sola dayalı olmayan satırda sekme vb.).
+- **Doğrulama:** `fillTemplate`'in reddettiğini aynı `TemplateError` ile reddeder. Hiçbir şey yazmaz;
+  rapor değer taşımaz.
+- **Öneri:** onayı `overflows` **ve** `unknown` durumunda kapatın.
+
+Bilinen sınırlar ve sınanan ortamlar: [CHANGELOG.md](./CHANGELOG.md).
+
+## Ürün sayfası — `app.html` (DOCX aç → düzenle → kaydet)
+
+Ribbon'lı tam editör. Paket henüz bu yüzeyi dışa vermediği için (yukarıdaki
+durum notu) bugün yalnız repo içinden çalışır:
+
+```bash
+npm run serve
+```
+
+```
+http://127.0.0.1:8080/examples/static/app.html
+```
+
+**Dosya** sekmesindeki **Dosya Seç** ile `test/corpus/` altındaki bir belgeyi
+seç (dosya yalnız okunur, değiştirilmez). Çift tık bir kutunun içinde metin moduna geçer,
+tek tık kutuyu seçer (ADR-0024). **Kaydet (.docx)** orijinal paketi yamalayarak
+indirir. "PDF indir" henüz bağlı değil — bugün PDF için görüntüleyicinin
+Ctrl+P'si var (aşağıda).
+
+## Corpus görüntüleyici (demo)
+
+46 corpus belgesini gerçek renderer ile tarayıcıda gösterir.
+**Görüntüleyici — düzenleme yok.** İki komut:
+
+```bash
+npm run corpus:canvas
+```
+
+```bash
+npm run serve
+```
+
+Sonra tarayıcıda aç:
+
+```
+http://127.0.0.1:8080/examples/static/viewer.html
+```
+
+Solda 46 belge, seçince sayfaları çizilir; başlıkta kutu/dekorasyon/sayfa
+sayısı ve render süresi görünür.
+
+**Çift tıklayarak açılmaz, ve bu ölçülmüş bir kısıt.** Chrome 151 /
+Windows 10 22H2'de `file://` üzerinde statik ES modül import'u, dinamik
+`import()` ve `fetch()` **üçü de bloklanıyor**; yalnızca inline klasik
+`<script>` koşuyor. Gerçek renderer'ı import etmenin başka yolu yok. Dört
+ölçümün tamamı [docs/viewer-measurement.md](./docs/viewer-measurement.md)
+§0'da; sunucu `node:http` ile yazıldı, **sıfır bağımlılık**, yalnızca
+loopback. Aynı kısıt `examples/static/canvas.html` ve `index.html` için de
+geçerli.
+
+`npm run corpus:canvas` Python ister (`scripts/docx-to-canvas-json.py`
+dönüştürücüsünü çağırır) ve bu yüzden `npm run ci`'nin parçası **değildir** —
+`corpus:check` ve `corpus:names` ile aynı gerekçe. Çıktı
+`examples/static/corpus-json/` altına yazılır, gitignore'ludur, her koşumda
+baştan üretilir. `test/corpus/` **okunur, asla yazılmaz** (CLAUDE.md #16).
+
+### PDF — Tier 0
+
+Görüntüleyicide **Ctrl+P → "PDF olarak kaydet"**. Sayfa yüzeyleri belgenin
+kendi boyutunda basılır (A4 dikey, A4 yatay ve A5 corpus'ta hepsi var), UI
+kromu gizlenir.
+
+**Bu bizim PDF writer'ımız değil, tarayıcınınki** — `ARCHITECTURE.md` §7'nin
+Tier 0'ı. Sunucuda üretilen, gömülü fontlu PDF FR5'te geliyor (eski MP10, yol
+haritasındaki P7); yolunu — kendi yazıcımız, pdf-lib ya da Cloudflare Browser Run — FR5
+başında sahip seçiyor (ADR-0036 Karar 5).
+
+**Gözle kontrol — henüz yapılmadı, yapılacaksa şöyle:** üç belgeyi seçip
+Ctrl+P ile önizlemeye bak; kâğıt boyutu belgenin kendi boyutuna oturmalı,
+kenar boşluğu olmamalı, sol liste ve üst başlık görünmemeli.
+
+| Belge | Beklenen kâğıt | Neden bu üçü |
+|---|---|---|
+| `AA01` | A4 dikey (595.5×842 pt) | corpus'un çoğunluğu |
+| `PK01` | **A4 YATAY** (842×595.5 pt) | sabit `A4` varsayımının kırılacağı yer |
+| `R001` | **A5** (420×595.5 pt) | ikinci kırılma noktası; 71 sayfa |
+
+Üçü de doğru basıyorsa sayfa boyutu belge başına yazılıyor demektir.
+
+Ölçüm sonuçları: [docs/viewer-measurement.md](./docs/viewer-measurement.md).
+
+## Tuval — kutu düzenleme (demo, P3b-a)
+
+Görüntüleyiciden farklı olarak **burada düzenleme var** — metin değil, kutu
+geometrisi: seç, tutamakla sürükle/boyutlandır, Ctrl+Z ile geri al,
+kopyala/yapıştır, dekoratif bir şeklin kenarına yaklaştırıp snap'i gör.
+`src/canvas/`'ın dokuz saf modülü + `CanvasController` + `Overlay`, gerçek
+bir tarayıcıya bağlı (`docs/adr/0018-canvas-interaction-layer.md`).
+
+```bash
+npm run serve
+```
+
+```
+http://127.0.0.1:8080/examples/static/canvas.html
+```
+
+Dosya seçiciyle bir belge JSON'u yükle: `test/fixtures/canvas/fifty-boxes.json`
+(50 kutu, 5 dekorasyon, 2 sayfa) hazır bir örnek; `npm run corpus:canvas`'ın
+ürettiği `examples/static/corpus-json/*.json` de aynı formatta çalışır.
+
+**Ölçülmemiş sabitler, sayfanın kendi geçici değerleri — kütüphaneye değil:**
+tutamak boyutu, snap eşiği, kademe eşikleri hiçbiri ölçülmedi (Ö2/Ö4,
+ADR-0018 §9.0). `canvas.html` kendi `EXAMPLE_METRICS` nesnesini enjekte
+ediyor; `src/canvas/controller.js`'in `requireMetrics`'i eksik alanda hâlâ
+gerçek `TypeError` atıyor, `src/` altına hiçbir varsayılan sızmadı.
+
+Aynı `file://` kısıtı geçerli (yukarıdaki görüntüleyici bölümüne bakınız).
+~~Metin düzenleme bu turun kapsamında değil~~ — 2026-08-29'dan beri
+(ADR-0024) çift tık kutunun içinde metin moduna geçiyor, ve sayfa artık
+`.docx` da açıp kaydedebiliyor. Ürün yüzeyi ise `app.html` (yukarıda).
+
+## Mimari
+
+Tasarım kararları için [ARCHITECTURE.md](./ARCHITECTURE.md),
+uyumluluk sözleşmesi için [FIDELITY.md](./FIDELITY.md).
+
+## Lisans
+
+MIT — bkz. [LICENSE](./LICENSE).