@sametalmdr/word-editor 0.0.0-stage → 0.3.0-alpha

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Değişiklik günlüğü
+
+## 0.3.0-alpha — 2026-10-26 (yayını sahip yapar)
+
+### Eklenenler
+
+- **`checkFit(bytes, data, {expectedTags?, multiline?, capacity?})`** — `/docx`'ten
+  ([ADR-0042](./docs/adr/0042-dom-free-fit-check.md)).
+  - **Ne yapar:** doldurmadan önce her değerin satırını şablonun kendi kutusuyla karşılaştırır. Tarayıcı
+    gerekmez.
+  - **Durumlar:** `fits`, `overflows`, `unknown` ya da `empty`; en dar satırın genişliği, yeri ve payı (pt).
+    `unknown`'ın nedeni kapalı bir listeden gelir.
+  - **Doğrulama:** `fillTemplate`'in reddettiğini aynı `TemplateError` ile reddeder; hiçbir şey yazmaz.
+    Rapor değer taşımaz.
+  - **Çok satırlı değer** `capacity` ister. Bağlama manifesti onu `fit` bloğunda taşır:
+    `checkFit(b, d, {...m.options, ...m.fit})`.
+  - **Word'e karşı:** masaüstü 16'da ön kayıtlı kapıyla sınandı (FR4-WORD-FIT2). 210 satırın hepsi
+    `checkFit`'in dediği gibi dizildi: KR09'un bütün kutuları bandın iki yanında, ayrıca 14 kalibrasyon dalı.
+- **Calibri genişlik tablosu** — `dist/fonts/calibri-metrics.js`.
+  - Carlito 1.104'ten (SIL OFL-1.1, ayrılmış ad "Carlito"); lisans metni yanında
+    (`dist/fonts/OFL-Carlito.txt`).
+  - Yalnız Calibri 6.23 ile eşit olduğu 344 kod noktası, dört kesim. Tabloda olmayan karakter `unknown`
+    (örneğin ₺).
+
+### Değişenler
+
+- Bağlama manifesti (repo içi, `templates/`) `fit: {capacity}` kazandı. `fillTemplate` ve `validateTemplate`
+  `capacity`'yi bilinmeyen seçenek saymayı sürdürür.
+
+### Bilinen sınırlar
+
+- **Yalnız Calibri** (tablo) ve yalnız sınanan kutu ve paragraf biçimleri ölçülür; geri kalanı `unknown`.
+  Başka Calibri yapıları (Mac, Word web) ve `compatibilityMode` 15 doğrulanmadı (ADR-0042 DOĞRULANMALI).
+- **Çok satırlı değerde** taşan bir satırın kaç satır alacağını tarayıcı söyler (FR4b). Kapasitenin
+  sığabileceği durumda sonuç `unknown(WRAPS)`.
+- **Word'de sınanmayan dallar `unknown`:** sondaki boşlukların belirlediği satır (`TRAILING_SPACE`, U+0020
+  dahil), iç boşluklu kutuda ya da sola dayalı olmayan satırda sekme (`TAB_INSET`, `TAB_ALIGNMENT`), şablonda
+  olmayan paragraf stili (`STYLE_MISSING`), `xml:space` korunmayan kenar boşluğu (`WHITESPACE_UNPRESERVED`).
+  KR09'un örneklerinde hiçbiri yok (0 `unknown`).
+
+## 0.2.0-alpha — 2026-10-26 (yayınlandı)
+
+### Eklenenler
+
+- **Çok satırlı değer** ([ADR-0039](./docs/adr/0039-multi-line-values.md)) —
+  `fillTemplate(bytes, data, {expectedTags?, multiline?})` ve
+  `validateTemplate(bytes, {expectedTags, multiline?})`. `multiline`'ın adlandırdığı etikette LF bir
+  satır sonudur: satırlar etiketin kendi run'ında, aralarında `w:br`; run'ın biçimi her satırda.
+  Okuma-geri `w:t` + `w:br` dizisini karşılaştırır. Şablonda olmayan ad `UNKNOWN_MULTILINE_TAG`.
+  Word'de (masaüstü 16) KR09'un iki uzun kutusunda ölçüldü: Calibri 8,5 pt'de 3 ve 2 satır sığıyor,
+  fazlası kırpılıyor.
+
+### Değişenler
+
+- Satır sonu kuralı: tek satırlı etikette LF de, her etikette CR, CRLF, U+2028 ve U+2029 eskisi gibi
+  `VALUE_LINE_BREAK`. Motor değeri normalleştirmez.
+
+### Bilinen sınırlar
+
+- `importDocx` `w:br`'yi okumuyor: çok satırlı bir değer editörde tek satıra birleşir; düzenlenip
+  export edilirse satır sonları kaybolur (FR4).
+- Kutuya sığmayan değer Word'de sessizce kırpılır; sığma denetimi bugün çağıranın işi (FR4).
+
+Paketin dışında (repo içi, `files`'a girmez): şablon tarifleri, bağlama manifesti ve alan kaydı v0
+(`templates/`, ADR-0040/0041) — PeriKont'un KR09 şablonu bunlarla üretilir. Şablonun kendisi
+`templates/kr09/KR09-template.docx`'te commit'li.
+
+## 0.1.0-alpha — 2026-10-17 (yayını sahip yapar)
+
+İlk açık alfa. Editörün kendi yüzeyi (`.`, `./element`, `./react`) değişmedi ve 1.0
+öncesi.
+
+### Eklenenler
+
+- **`/docx` alt yolu** — DOM'suz; Node'da ve Deno'da (ör. Supabase Edge Functions) sınandı,
+  tarayıcı için de yazıldı (Chrome 152'de yalnız incelendi). Hiçbir ağ isteği atmaz.
+  - `fillTemplate(bytes, data, {expectedTags?})` — bir `.docx` şablonunun `{etiket}`lerini
+    doldurur. `{bytes, documentXml, report}` döndürür.
+  - `inspectTemplate(bytes)` — şablondaki etiketler (kutunun `wp:docPr` kimliği ve sayfasıyla),
+    doldurmayı durduracak sorunlar ve uyarılar. Şablon sorununda atmaz.
+  - `validateTemplate(bytes, {expectedTags})` — bağlama listesini tam küme olarak denetler.
+  - `TemplateError` — `problems` dizisi; her sorunun `code`'u sözleşmedir.
+  - `ENGINE_VERSION`.
+  - `importDocx`, `exportDocx` — editörün kendi IO'su; şekilleri alfa boyunca kararsız.
+
+### Doldurma kuralları (ADR-0037, ADR-0038)
+
+- Etiket bir `w:t`'nin metninin tamamıdır: `{firma_adi}`, ad `[a-z][a-z0-9_]*`.
+- Etiketler yalnız metin kutularında (`mc:AlternateContent`). Kutunun iki kopyası
+  (`mc:Choice` ve `mc:Fallback`) birlikte yazılır; önceden yapısal olarak eşit değillerse
+  reddedilir, sonra eşitlikleri yeniden denetlenir.
+- Eksik anahtar doldurmayı durdurur; eksiklerin hepsi tek hatada raporlanır. `null`, `""` ve
+  yalnız boşluktan oluşan değer **boştur**: serbesttir, `report.empty`'de listelenir.
+- Değer string olmalı. Satır sonu, sekme ve XML'in kabul etmediği karakterler reddedilir.
+- Rapor, sorunlar ve hata mesajları hiçbir değeri taşımaz.
+- Yalnız `word/document.xml` yeniden yazılır; başka her parçanın baytları aynen kopyalanır.
+
+### Bilinen sınırlar
+
+- Yalnız ana belge doldurulur. Üst/alt bilgi, dipnot, son not, yorum, grafik ya da
+  `docProps` metnindeki bir parantez hata verir.
+- Döngü (`{#…}`), koşul, görsel (`{%…}`), bölünmüş etiket, gövde paragrafındaki etiket yok.
+- Çok satırlı değer yok (satır sonu reddedilir); politika FR3'te.
+- Sıkıştırılmış `.docx` baytları çalışma ortamına göre değişir; ortamlar arasında
+  karşılaştırmayı `documentXml`'in özetiyle yapın.
+- Gereken platform API'leri: `TextEncoder`/`TextDecoder` ve
+  `CompressionStream`/`DecompressionStream("deflate-raw")` — Node 20.12+ ya da 21.2+, Deno,
+  güncel tarayıcılar. Sınanan: Node 24.13.1, Deno 2.1.4.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samet Alemdaroğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,286 @@
-# Temporary Holding Version
+# @sametalmdr/word-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).

package/dist/canvas/box-clipboard.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The clipboard payload for a set of boxes — `null` if the selection is
+ * empty or any id no longer names a real box (a stale selection copying
+ * nothing meaningful is a no-op, not a partial copy).
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {import("../model/node.js").NodeId[]} containerIds
+ * @returns {BoxPayload | null}
+ */
+export function serializeBoxes(doc: import("../model/node.js").Doc, containerIds: import("../model/node.js").NodeId[]): BoxPayload | null;
+/**
+ * The plain-text mirror written to the system clipboard's `text/plain`
+ * slot alongside the real payload (§7.1) — every paragraph of every box,
+ * in payload order, joined the same way `serializeToText` joins a text
+ * selection's paragraphs.
+ * @param {BoxPayload} payload
+ * @returns {string}
+ */
+export function payloadToText(payload: BoxPayload): string;
+/**
+ * @typedef {object} MintedBoxIds
+ * @property {import("../model/node.js").NodeId} containerId
+ * @property {import("../model/node.js").NodeId[]} paragraphIds  same length and order as `box.paragraphs`
+ */
+/**
+ * Fresh ids for one payload box, minted from `ids` — NEVER the ids the
+ * payload itself carries (those are the ORIGINAL box's, and reusing them
+ * would collide the moment the original still exists, CANV12's own
+ * target). Minted before any step exists (ADR-0003: `apply()` never mints
+ * an id) — the same ordering `commands/clipboard.js`'s `pasteText` already
+ * uses for a pasted paragraph's id, generalized to a whole box.
+ *
+ * @param {BoxPayloadEntry} box
+ * @param {import("../model/ids.js").IdFactory} ids
+ * @returns {MintedBoxIds}
+ */
+export function mintBoxIds(box: BoxPayloadEntry, ids: import("../model/ids.js").IdFactory): MintedBoxIds;
+/**
+ * @typedef {object} PastePage
+ * @property {number} page  1-based, the ACTIVE page paste targets — never the page the boxes were copied from (§7.2)
+ * @property {number} width
+ * @property {number} height
+ */
+/**
+ * @typedef {object} PastedBox
+ * @property {import("../model/node.js").Container} container  fresh ids throughout
+ * @property {import("../model/node.js").BoxLayout} layout
+ */
+/**
+ * Rebuilds `payload` as fresh containers + layouts, ready for the (future)
+ * caller to turn into `insertContainerStep`s — one transaction, so the
+ * whole paste is one undo entry.
+ *
+ * Relative geometry is preserved EXACTLY (§7.4): the offset from
+ * `payload.origin` to its post-paste position is computed ONCE, from the
+ * group's own bounding rect, and applied IDENTICALLY to every box's own
+ * absolute `{x,y}` — never computed per box. A per-box offset (e.g. each
+ * box separately clamped against the page) would let two boxes drift
+ * apart or together depending on which one needed clamping (CANV9's own
+ * target): two boxes 40pt apart must land 40pt apart, whether or not the
+ * paste needed to shift for the page edge.
+ *
+ * Falling outside the target page CLIPS the whole group's bounding rect
+ * into it (§7.2) — smart placement is not attempted; ARCHITECTURE.md:357
+ * already calls "no overlap" an unrealistic goal, and clipping the whole
+ * group keeps that same "don't pretend to solve overlap" stance instead
+ * of inventing a different unsolved problem (per-box collision avoidance).
+ *
+ * @param {BoxPayload} payload
+ * @param {import("../model/ids.js").IdFactory} ids
+ * @param {PastePage} targetPage
+ * @param {number} pasteOffsetPt  pt — injected, no default (an unmeasured UI constant, CanvasMetrics' `pasteOffsetPt`)
+ * @returns {PastedBox[]}
+ */
+export function pasteBoxes(payload: BoxPayload, ids: import("../model/ids.js").IdFactory, targetPage: PastePage, pasteOffsetPt: number): PastedBox[];
+/** Bumped when the shape changes incompatibly — mirrors document-json.js's own field. */
+export const BOX_PAYLOAD_VERSION: 1;
+export type BoxPayloadParagraph = {
+    id: import("../model/node.js").NodeId;
+    pPrRef?: string | undefined;
+    runs: {
+        text: string;
+        marks: import("../model/node.js").Marks;
+    }[];
+};
+export type BoxPayloadEntry = {
+    /**
+     * a fresh, field-by-field copy — never a live reference
+     */
+    layout: Partial<import("../model/node.js").BoxLayout>;
+    paragraphs: BoxPayloadParagraph[];
+};
+export type BoxPayload = {
+    version: number;
+    /**
+     * the copied selection's own bounding-rect top-left (ADR-0018 §7.3's "grubun sol-üstü")
+     */
+    origin: {
+        x: number;
+        y: number;
+    };
+    boxes: BoxPayloadEntry[];
+};
+export type MintedBoxIds = {
+    containerId: import("../model/node.js").NodeId;
+    /**
+     * same length and order as `box.paragraphs`
+     */
+    paragraphIds: import("../model/node.js").NodeId[];
+};
+export type PastePage = {
+    /**
+     * 1-based, the ACTIVE page paste targets — never the page the boxes were copied from (§7.2)
+     */
+    page: number;
+    width: number;
+    height: number;
+};
+export type PastedBox = {
+    /**
+     * fresh ids throughout
+     */
+    container: import("../model/node.js").Container;
+    layout: import("../model/node.js").BoxLayout;
+};