Web okuyucu dokümantasyon bağlantıları

Bağlantı sözleşmesi

Web okuyucu ve dokümantasyon ayrı build ve deploy birimleridir. Web, apps/docs kodunu import etmez ve kullanıcı bir yardım bağlantısını açmadan docs runtime’ına istek göndermez. Docs origin’i public build-time değişkeniyle verilir:

NEXT_PUBLIC_MUNDERECAT_DOCS_URL=https://docs.example.test/

Production build/deployment bu değeri canonical current documentation root olarak sağlamalıdır. Değer HTTPS kullanır; yalnız yerel geliştirmede HTTP loopback kabul edilir. Credential, query veya fragment taşıyan base URL reddedilir. Değişken development ortamında yoksa http://127.0.0.1:4321/ kullanılır; production’da hosted domain uydurulmaz ve yapılandırma hatası açıkça başarısız olur.

Docs build’i de dönüş linki için izin verilen reader root’unu alır:

NEXT_PUBLIC_MUNDERECAT_WEB_URL=https://reader.example.test/

Değer HTTPS veya loopback root olmalı; credential, query, fragment ve alt path taşıyamaz. Eksik değerde yalnız http://127.0.0.1:3000/ kabul edilir. Bu nedenle hosted docs yanlış yapılandırılmışsa dış bir referrer’a dönmek yerine dönüş linkini gizler.

Tek route kaydı

apps/web/src/lib/user-docs.ts bütün reader hedeflerinin tek kaynağıdır:

Reader bağlamı	User-doc route
Dil ve alignment	/user/languages-and-alignment/
Latin ve Osmanlıca	/user/ottoman-and-latin/
Terimler ve geçtiği yerler	/user/terms-and-occurrences/
Heading ve içindekiler	/user/contents-and-headings/
Haşiye ve notlar	/user/footnotes/
Tekrar ve canonical pasajlar	/user/repetitions-and-canonical-passages/
Tema	/user/theme-and-display/

Route’lar başında slash olmadan saklanır; böylece docs deployment bir base path altındaysa bu path kaybolmaz. Component’lar route string’i yazmaz, yalnız semantic topic seçer.

UI davranışı

Bağlantılar ilgili kontrol veya panelde ? simgesiyle görünür ve her biri açık bir accessible name ile normal anchor olarak çalışır. Link, mevcut reader pathname’ini yalnız reader query alanında taşır; scheme, host, query, fragment, backslash ve protocol-relative değerler kabul edilmez.

Docs tarafındaki ReaderLink.astro, dönüş linkini ancak referrer origin’i kayıtlı reader root’uyla birebir eşleşirse açar. Path kapalı route grammar’ına tabidir: reader kökü veya UUID taşıyan /chapters/<id>. Böylece dış referrer, protocol-relative değer veya reader dışı path güvenilir dönüş linkine çevrilmez. Yeni pencere zorlanmaz; normal browser geri davranışı da çalışmaya devam eder. Link eklenmesi chapter RPC’lerini, popup yükleme davranışını, exact reconstruction’ı veya query budget’ini değiştirmez.

F8-017 reader’dan mevcut route’lara doğru bağlantıyı kurdu; F8-018 user-guide metinlerini güncel UI ile eşledi. F8-020 güvenli docs-to-reader dönüşünü ve iki production build arasındaki doğrudan navigasyon testini tamamladı.

Doğrulama

user-docs.test.mjs kapalı topic kaydını, source dosya varlığını, base-path birleşimini, dönüş path’ini ve URL güvenlik sınırını doğrular. reader-doc-links.spec.mjs production Next build içinde tema, dil, yazı, terim, not ve tekrar href’lerini kontrol eder. web-docs-integration.spec.mjs ise iki production build’i aynı anda açıp reader -> docs -> aynı reader path akışını, klavye odağını ve iki taraftaki axe sonucunu bir kez doğrular.

pnpm --filter @munderecat/web test
pnpm --filter @munderecat/web exec playwright test \
  --config playwright.config.mjs reader-doc-links.spec.mjs
pnpm --filter @munderecat/web exec playwright test \
  --config playwright.web-docs.config.mjs