@ev-ry/fx 0.1.0-rc.1 → 0.1.0-rc.3

package/QUICKSTART.fa.md

@@ -1,94 +1,106 @@
-# EV-RY FX Free 0.1.0-rc.1 — نصب آزمایشی
-
-این نسخهٔ آزمایشی عمومی با مجوز MIT ارائه می‌شود. نام بسته در npm برابر @ev-ry/fx است.
-
-## روش script
-
-آرشیو را استخراج کنید و پوشه package را کامل در مسیر عمومی `/thd/` سایت قرار دهید. این خط را اضافه کنید:
-
-```html
-<script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
-```
-
-H1/H2 خودکار انتخاب می‌شوند. برای تصویر `data-thd-image` و برای متن دیگر `data-thd-text` بگذارید. برای استثناکردن یک بخش، `data-thd-ignore` روی آن یا والدش قرار دهید. فایل examples/script.html نمونهٔ آماده است؛ آن را از HTTP باز کنید، نه file://.
-
-### جلوگیری از چشمک در اولین نمایش صفحه
-
-این اسکریپت کوچک را در `head`، پیش از محتوای صفحه و **بدون defer یا async** قرار دهید:
-
-```html
-<script src="/thd/src/dom-reveal-boot.js"></script>
-```
-
-روی آیتمی که منتظر افکت ورود است `data-thd-pending` بگذارید؛ این نشانگر جایگزین انتخاب‌گر اتصال نیست:
-
-```html
-<img data-thd-image data-thd-pending src="photo.jpg" width="640" height="400" alt="Photo">
-<h1 data-thd-pending>Hello</h1>
-```
-
-فضا حفظ می‌شود و ماسک اولیه در همان لحظهٔ اتصال به ماسک افکت تحویل داده می‌شود. اگر موتور بارگیری نشود، ماسک اولیه حداکثر پس از ۸ ثانیه برداشته می‌شود؛ بدون JavaScript محتوا بومی و قابل مشاهده است. آماده‌سازی افکت پس از اتصال، مراقبت خطای مستقل خود را دارد. برای تصویر ابعاد یا aspect-ratio تعیین کنید تا بارگیری آن چیدمان را جابه‌جا نکند.
-
-نشانگر `data-thd-pending` فقط برای مخفی‌سازی اولیه است و روی آیتم‌های خارج از انتخاب‌گر یا مستثناشده نگذارید. ویژگی `data-thd-reveal` متعلق به موتور است؛ آن را دستی تغییر ندهید. مهلت ۸ ثانیه از اجرای اسکریپت اولیه محاسبه می‌شود و تأخیر افکت نیست. اگر موتور پس از این مهلت آماده شود، جلوگیری از چشمک تضمین نمی‌شود. در سایت دارای CSP محدود، اجرای اسکریپت و style تزریق‌شده باید مجاز باشد.
-
-## نصب با npm
-
-```sh
-npm install @ev-ry/fx
-```
-
-برای import از `@ev-ry/fx`، namespace سازگار THREE را خودتان ارائه کنید؛ نسخهٔ همراه script همان r158 است. راهنمای کامل API در docs/GUIDE.md قرار دارد.
-
-برای شروع صریح از داخل ماژول نیز می‌توانید از loader استفاده کنید:
-
-```js
-import * as THREE from 'three';
-import {loadFree} from '@ev-ry/fx/script';
-const api = await loadFree({THREE, auto: true});
-```
-
-خود import روی صفحه اثری ندارد و هنگام رندر سمت سرور هم قابل import است؛ `loadFree()` را فقط در مرورگر و پس از وجود صفحه اجرا کنید. نسخهٔ آزمایش‌شدهٔ Three.js همان r158 است. در صورت ندادن THREE، loader از نسخهٔ موجود در window یا فایل همراه استفاده می‌کند؛ مسیر فایل همراه باید پس از بسته‌بندی قابل دسترس بماند. اولین فراخوانی حالت خودکار را تعیین می‌کند و فراخوانی‌های بعدی همان آماده‌سازی را به اشتراک می‌گذارند. برای مدیریت دستی از `auto:false` و سپس `api.create()` استفاده کنید.
-
-آدرس قبلی `src/dom-free-script.js` برای تگ script معمولی حفظ شده است. روی آن `type="module"` نگذارید. مسیر `@ev-ry/fx/classic-script` فقط برای یافتن فایل script معمولی است؛ ورودی import همان `@ev-ry/fx/script` و تابع `loadFree` است.
-
-## React
-
-مثال `examples/AnimatedTitle.jsx` عمداً از همان script استفاده می‌کند تا نیازی به تنظیم بسته‌بندی فایل‌های همراه موتور نباشد. script را بدون data-thd-auto پیش از اجرای React بارگیری کنید و سپس AnimatedTitle را در برنامه استفاده کنید. روی همان عنصر اتصال خودکار و دستی را هم‌زمان فعال نکنید.
-
-این مثال cleanup دارد و در StrictMode و تغییر متن باید اتصال قبلی را آزاد کند. children در این مثال یک رشته است؛ این یک پک کامپوننت React مستقل نیست.
-
-## رفتار و محدودیت‌ها
-
-### ورود به دید و تکرار
-
-پیش‌فرض `once:true` یعنی تنها اولین ورود. با `once:false`، خروج کامل آیتم آن را فوراً مخفی و برای ورود مجدد آماده می‌کند؛ این خروج افکت محو اجرا نمی‌کند. حرکت کوچک داخل محدوده نباید افکت را تکرار کند. ورود مجدد در حین افکت ناتمام، همان زمان‌بندی را ادامه می‌دهد؛ پس از پایان، ورود جدید افکت تازه می‌سازد. `play('enter')` درخواست بازپخش صریح و `play('exit')` درخواست محو متحرک است.
-
+# EV-RY FX Free 0.1.0-rc.3 — نصب آزمایشی
+
+این نسخهٔ آزمایشی عمومی با مجوز MIT ارائه می‌شود. نام بسته در npm برابر @ev-ry/fx است.
+
+## روش script
+
+آرشیو را استخراج کنید و پوشه package را کامل در مسیر عمومی `/thd/` سایت قرار دهید. این خط را اضافه کنید:
+
+```html
+<script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
+```
+
+H1/H2 خودکار انتخاب می‌شوند. برای تصویر `data-thd-image` و برای متن دیگر `data-thd-text` بگذارید. برای استثناکردن یک بخش، `data-thd-ignore` روی آن یا والدش قرار دهید. فایل examples/script.html نمونهٔ آماده است؛ آن را از HTTP باز کنید، نه file://.
+
+### جلوگیری از چشمک در اولین نمایش صفحه
+
+این اسکریپت کوچک را در `head`، پیش از محتوای صفحه و **بدون defer یا async** قرار دهید:
+
+```html
+<script src="/thd/src/dom-reveal-boot.js"></script>
+```
+
+روی آیتمی که منتظر افکت ورود است `data-thd-pending` بگذارید؛ این نشانگر جایگزین انتخاب‌گر اتصال نیست:
+
+```html
+<img data-thd-image data-thd-pending src="photo.jpg" width="640" height="400" alt="Photo">
+<h1 data-thd-pending>Hello</h1>
+```
+
+فضا حفظ می‌شود و ماسک اولیه در همان لحظهٔ اتصال به ماسک افکت تحویل داده می‌شود. اگر موتور بارگیری نشود، ماسک اولیه حداکثر پس از ۸ ثانیه برداشته می‌شود؛ بدون JavaScript محتوا بومی و قابل مشاهده است. آماده‌سازی افکت پس از اتصال، مراقبت خطای مستقل خود را دارد. برای تصویر ابعاد یا aspect-ratio تعیین کنید تا بارگیری آن چیدمان را جابه‌جا نکند.
+
+نشانگر `data-thd-pending` فقط برای مخفی‌سازی اولیه است و روی آیتم‌های خارج از انتخاب‌گر یا مستثناشده نگذارید. ویژگی `data-thd-reveal` متعلق به موتور است؛ آن را دستی تغییر ندهید. مهلت ۸ ثانیه از اجرای اسکریپت اولیه محاسبه می‌شود و تأخیر افکت نیست. اگر موتور پس از این مهلت آماده شود، جلوگیری از چشمک تضمین نمی‌شود. در سایت دارای CSP محدود، اجرای اسکریپت و style تزریق‌شده باید مجاز باشد.
+
+## نصب با npm
+
+```sh
+npm install ./thd-free-0.1.0-rc.3.tgz
+```
+
+برای import از `@ev-ry/fx`، namespace سازگار THREE را خودتان ارائه کنید؛ نسخهٔ همراه script همان r158 است. راهنمای کامل API در docs/GUIDE.md قرار دارد.
+
+برای شروع صریح از داخل ماژول نیز می‌توانید از loader استفاده کنید:
+
+```js
+import * as THREE from 'three';
+import {loadFree} from '@ev-ry/fx/script';
+const api = await loadFree({THREE, auto: true});
+```
+
+خود import روی صفحه اثری ندارد و هنگام رندر سمت سرور هم قابل import است؛ `loadFree()` را فقط در مرورگر و پس از وجود صفحه اجرا کنید. نسخهٔ آزمایش‌شدهٔ Three.js همان r158 است. در صورت ندادن THREE، loader از نسخهٔ موجود در window یا فایل همراه استفاده می‌کند؛ مسیر فایل همراه باید پس از بسته‌بندی قابل دسترس بماند. اولین فراخوانی حالت خودکار را تعیین می‌کند و فراخوانی‌های بعدی همان آماده‌سازی را به اشتراک می‌گذارند. برای مدیریت دستی از `auto:false` و سپس `api.create()` استفاده کنید.
+
+آدرس قبلی `src/dom-free-script.js` برای تگ script معمولی حفظ شده است. روی آن `type="module"` نگذارید. مسیر `@ev-ry/fx/classic-script` فقط برای یافتن فایل script معمولی است؛ ورودی import همان `@ev-ry/fx/script` و تابع `loadFree` است.
+
+## React
+
+مثال `examples/AnimatedTitle.jsx` عمداً از همان script استفاده می‌کند تا نیازی به تنظیم بسته‌بندی فایل‌های همراه موتور نباشد. script را بدون data-thd-auto پیش از اجرای React بارگیری کنید و سپس AnimatedTitle را در برنامه استفاده کنید. روی همان عنصر اتصال خودکار و دستی را هم‌زمان فعال نکنید.
+
+این مثال cleanup دارد و در StrictMode و تغییر متن باید اتصال قبلی را آزاد کند. children در این مثال یک رشته است؛ این یک پک کامپوننت React مستقل نیست.
+
+## رفتار و محدودیت‌ها
+
+### ورود به دید و تکرار
+
+پیش‌فرض `once:true` یعنی تنها اولین ورود. با `once:false`، خروج کامل آیتم آن را فوراً مخفی و برای ورود مجدد آماده می‌کند؛ این خروج افکت محو اجرا نمی‌کند. حرکت کوچک داخل محدوده نباید افکت را تکرار کند. ورود مجدد در حین افکت ناتمام، همان زمان‌بندی را ادامه می‌دهد؛ پس از پایان، ورود جدید افکت تازه می‌سازد. `play('enter')` درخواست بازپخش صریح و `play('exit')` درخواست محو متحرک است.
+
 `threshold` نسبت مساحت قابل مشاهده است: صفر برای اولین تقاطع مثبت، `0.5` برای نصف و `1` برای تمام آیتم. آیتم بزرگ‌تر از محدودهٔ دید ممکن است هرگز به مقدار یک نرسد.
 
-### محل canvas و لایه‌ها
-
-پیش‌فرض `auto` با `documentCanvas:true` است؛ canvas مشترک همراه سند حرکت می‌کند. محدوده‌های خاص ممکن است به حالت محلی بروند. برای اجبار به حالت محلی از `presentation:'local'` استفاده کنید. canvas مشترک تمام ترکیب‌های لایه‌بندی CSS را بازسازی نمی‌کند؛ برای تداخل با هدر، zIndex و حالت نمایش را بررسی کنید.
-
-### اتصال و پاک‌سازی
-
-عنصرِ خالی که دستی متصل شده، پس از دریافت متن می‌تواند افکت ورود را اجرا کند. اما عنصر خالی‌ای که اسکن خودکار آن را انتخاب نکرده، برای کشف‌شدن به `free.refresh()` نیاز دارد. اگر سبک پشتیبانی‌نشده را اصلاح کردید، refresh امکان اجرای اولین ورود را بازمی‌گرداند؛ ورودِ یک‌باره‌ای که قبلاً کامل شده تکرار نمی‌شود. فاصله‌های معمولی HTML طبق CSS جمع می‌شوند؛ فاصلهٔ نشکن و فاصله‌های پیش‌قالب‌بندی‌شده حذف سراسری نمی‌شوند.
-
-اتصال خودکار و دستی را روی یک آیتم هم‌زمان انجام ندهید. اسکن تغییرات DOM خودکار و دائمی نیست؛ پس از افزودن یا حذف آیتم‌ها `free.refresh()` را اجرا کنید. هنگام unmount، اتصال یا مالک آن را `destroy()` کنید. تصویر خارجی بدون مجوز CORS یا CSS/SVG پشتیبانی‌نشده ممکن است بومی باقی بماند؛ نبود افکت همیشه خطای بارگذاری موتور نیست.
-
-loader خودکار هنگام رفتن صفحه به حافظهٔ Back/Forward مرورگر، اتصال را نگه می‌دارد و هنگام بازگشت موقعیتش را تازه می‌کند؛ ورودهای یک‌باره دوباره ساخته نمی‌شوند. خروج واقعی صفحه منابع را آزاد می‌کند. اگر اتصال را خودتان با `api.create()` یا `createFree()` ساخته‌اید، مدیریت عمر آن هم با شماست: روی `pagehide` فقط در صورت `event.persisted === false` آن را آزاد کنید؛ در بازگشتِ persisted، `refresh()` کافی است. اتصال عمداً destroyشده خودکار زنده نمی‌شود. پاک‌سازی هنگام unmount واقعی همچنان لازم است.
-
+اگر بعد از اتصال دارای `revealOnView`، صریحاً `play()` را فراخوانی کنید، زمان‌بندی دستی جای ورود خودکار را می‌گیرد؛ ماسک اولیه تا اولین فریم حفظ می‌شود، اما ورود به دید دیگر افکت را از نو شروع نمی‌کند. برای متن اسلایدر که باید هم‌زمان با اسلاید شروع شود، همین روش مناسب است. متن خارج از دید فقط زمان شروع را نگه می‌دارد و رسم و محاسبات ذرات متوقف می‌شوند؛ با برگشت، وضعیت متناسب با زمان سپری‌شده نمایش داده می‌شود. اگر زمان تمام شده باشد، افکت دوباره اجرا نمی‌شود.
+
+برای پایان افکت از `await surface.whenFinished()` استفاده کنید؛ پایان گذار به متن بومی را هم در نظر می‌گیرد و خارج از دید نیز تکمیل می‌شود. نتیجه یکی از وضعیت‌های `completed`، `cancelled` و `unsupported` است. برای تشخیص پایان، تایمر ثابت یا آمار رندر را در کد سایت بررسی نکنید. لغو یا تخریب اتصال، انتظار جاری را با وضعیت `cancelled` آزاد می‌کند.
+
+اگر `play('exit')` را خارج از دید فراخوانی کنید، نمایش بومی همان لحظه مخفی می‌شود؛ اندازه، جای عنصر و محتوای DOM حذف نمی‌شوند. اگر حذف در حال اجرا از دید خارج شود نیز نمایش بومی مخفی می‌ماند. هنگام برگشت، فقط ذرات متناسب با زمان سپری‌شده رسم می‌شوند و اگر حذف تمام شده باشد، آیتم مخفی می‌ماند. `play('enter')` آن را دوباره تشکیل می‌دهد؛ `cancel()` یا `destroy()` نمایش و سبک‌های بومی را بازمی‌گردانند. این رفتار در خود موتور برای متن، تصویر و SVG اعمال می‌شود.
+
+### محل canvas و لایه‌ها
+
+پیش‌فرض `auto` با `documentCanvas:true` است؛ canvas مشترک همراه سند حرکت می‌کند. محدوده‌های خاص ممکن است به حالت محلی بروند. برای اجبار به حالت محلی از `presentation:'local'` استفاده کنید. canvas مشترک تمام ترکیب‌های لایه‌بندی CSS را بازسازی نمی‌کند؛ برای تداخل با هدر، zIndex و حالت نمایش را بررسی کنید.
+
+### اتصال و پاک‌سازی
+
+عنصرِ خالی که دستی متصل شده، پس از دریافت متن می‌تواند افکت ورود را اجرا کند. اما عنصر خالی‌ای که اسکن خودکار آن را انتخاب نکرده، برای کشف‌شدن به `free.refresh()` نیاز دارد. اگر سبک پشتیبانی‌نشده را اصلاح کردید، refresh امکان اجرای اولین ورود را بازمی‌گرداند؛ ورودِ یک‌باره‌ای که قبلاً کامل شده تکرار نمی‌شود. فاصله‌های معمولی HTML طبق CSS جمع می‌شوند؛ فاصلهٔ نشکن و فاصله‌های پیش‌قالب‌بندی‌شده حذف سراسری نمی‌شوند.
+
+اتصال خودکار و دستی را روی یک آیتم هم‌زمان انجام ندهید. اسکن تغییرات DOM خودکار و دائمی نیست؛ پس از افزودن یا حذف آیتم‌ها `free.refresh()` را اجرا کنید. هنگام unmount، اتصال یا مالک آن را `destroy()` کنید. تصویر خارجی بدون مجوز CORS یا CSS/SVG پشتیبانی‌نشده ممکن است بومی باقی بماند؛ نبود افکت همیشه خطای بارگذاری موتور نیست.
+
+loader خودکار هنگام رفتن صفحه به حافظهٔ Back/Forward مرورگر، اتصال را نگه می‌دارد و هنگام بازگشت موقعیتش را تازه می‌کند؛ ورودهای یک‌باره دوباره ساخته نمی‌شوند. خروج واقعی صفحه منابع را آزاد می‌کند. اگر اتصال را خودتان با `api.create()` یا `createFree()` ساخته‌اید، مدیریت عمر آن هم با شماست: روی `pagehide` فقط در صورت `event.persisted === false` آن را آزاد کنید؛ در بازگشتِ persisted، `refresh()` کافی است. اتصال عمداً destroyشده خودکار زنده نمی‌شود. پاک‌سازی هنگام unmount واقعی همچنان لازم است.
+
 ### آماده‌سازی و مصرف پردازش
 
-برای تصویر خارج از دید یا با اندازهٔ صفر، `ready` ممکن است با وضعیت موقت بومی و دلیل `Image not visible` تمام شود؛ این به معنی آماده‌بودن مش روی GPU نیست. آماده‌سازی تصویر از نزدیکی صفحه، حدود نصف ارتفاع viewport جلوتر، آغاز می‌شود. بارگیری شبکهٔ خود `img` همچنان تابع مرورگر است. هنگام resize سریع، مش قبلی برای مدت کوتاه با کادر حرکت می‌کند و برش و گوشه‌های نهایی پس از تجمیع تغییرات بازسازی می‌شوند؛ ساعت افکت از ابتدا شروع نمی‌شود.
-
-متن ثابت از چیدمان معتبر و پیکسل‌های کش‌شده استفاده می‌کند. سقف کش مشترک پیکسل‌ها ۱۶MiB است؛ این سقف کل حافظهٔ صفحه یا GPU نیست. بارگیری فونت کش مرتبط را تازه می‌کند. متن پشتیبانی‌نشده بومی نمایش داده می‌شود و موتور روی همان خطای معلوم مدام تلاش نمی‌کند؛ پس از اصلاح سبک، `refresh()` امکان تلاش مجدد را می‌دهد.
-
+`surface.ready` نتیجهٔ آماده‌سازی است، نه پایان نصب موتور؛ برای متن یا SVG پایین صفحه ممکن است تا نزدیک‌شدن به دید منتظر بماند. فعال‌شدن دکمه‌های کل صفحه را به `ready` همهٔ آیتم‌ها وابسته نکنید. پس از ساخت اتصال می‌توانید `play()` را صدا بزنید و پایان اجرای درخواست‌شده را با `whenFinished()` بگیرید.
+
+برای تصویر خارج از دید یا با اندازهٔ صفر، `ready` ممکن است با وضعیت موقت بومی و دلیل `Image not visible` تمام شود؛ این به معنی آماده‌بودن مش روی GPU نیست. آماده‌سازی تصویر از نزدیکی صفحه، حدود نصف ارتفاع viewport جلوتر، آغاز می‌شود. بارگیری شبکهٔ خود `img` همچنان تابع مرورگر است. هنگام resize سریع، مش قبلی برای مدت کوتاه با کادر حرکت می‌کند و برش و گوشه‌های نهایی پس از تجمیع تغییرات بازسازی می‌شوند؛ ساعت افکت از ابتدا شروع نمی‌شود.
+
+متن ثابت از چیدمان معتبر و پیکسل‌های کش‌شده استفاده می‌کند. سقف کش مشترک پیکسل‌ها ۱۶MiB است؛ این سقف کل حافظهٔ صفحه یا GPU نیست. بارگیری فونت کش مرتبط را تازه می‌کند. متن پشتیبانی‌نشده بومی نمایش داده می‌شود و موتور روی همان خطای معلوم مدام تلاش نمی‌کند؛ پس از اصلاح سبک، `refresh()` امکان تلاش مجدد را می‌دهد.
+
 ### مشخصات نسخه
 
-- متن: ورود باد، خروج دود. تصویر/SVG: ورود برف، خروج ذوب.
-- مدت۲ ثانیه، ذرات مثلثی، سکون بومی، شکل‌گیری دیرتر برای نمایش‌دهنده‌ها.
-- canvas متصل به سند پیش‌فرض است؛ حالت خودکار برای بعضی محدوده‌ها محلی می‌شود.
-- قبل از جداکردن بخش صفحه owner.destroy() را صدا بزنید. برای اسکن عناصر جدید owner.refresh().
-- چهار افکت ثابت؛ ویرایشگر، افکت سفارشی و پشتیبانی تمام CSS/SVG در این بسته نیستند.
-- یک script با فایل‌های همراه است، نه یک فایل یکپارچه. ساختار پوشه‌ها را حفظ کنید.
+برای پایان افکت از `await surface.whenFinished()` استفاده کنید؛ نتیجه `completed`، `cancelled` یا `unsupported` است و پایان تبدیل مش به نمایش بومی را هم لحاظ می‌کند. چند فراخوانی هم‌زمان یک انتظار مشترک دارند. اجرای جدید، انتظار اجرای قبلی را لغو می‌کند؛ `cancel()`، `destroy()` و جداشدن عنصر از سند نیز انتظار را آزاد می‌کنند. انتظار ورود خودکار تا اولین intersection محدود به زمان آماده‌سازی نیست.
+
+متن، تصویر و SVG خارج دید ساعت افکت را با پردازش کم حفظ می‌کنند؛ ورود مجدد افکت را از ابتدا شروع نمی‌کند. هنگام درخواست محو خارج دید، نمایش بومی همان لحظه مخفی می‌شود. در اسلایدر، متن و تصویر بعدی را تنها پس از موفقیت تعویض نهایی کنید. برای متن بعدی عنصر تازه بسازید؛ عنصر متصل به موتور ممکن است سبک یا ویژگی موقت داشته باشد و نباید همان حالت زنده را clone کرد.
+
+- متن: ورود باد، خروج دود. تصویر/SVG: ورود برف، خروج ذوب.
+- مدت۲ ثانیه، ذرات مثلثی، سکون بومی، شکل‌گیری دیرتر برای نمایش‌دهنده‌ها.
+- canvas متصل به سند پیش‌فرض است؛ حالت خودکار برای بعضی محدوده‌ها محلی می‌شود.
+- قبل از جداکردن بخش صفحه owner.destroy() را صدا بزنید. برای اسکن عناصر جدید owner.refresh().
+- چهار افکت ثابت؛ ویرایشگر، افکت سفارشی و پشتیبانی تمام CSS/SVG در این بسته نیستند.
+- یک script با فایل‌های همراه است، نه یک فایل یکپارچه. ساختار پوشه‌ها را حفظ کنید.
 - تست‌های واقعی آیفون و Android توسط کاربر موفق گزارش شده‌اند؛ این تضمین تمام دستگاه‌ها و سایت‌ها نیست.

package/README.md

@@ -1,116 +1,120 @@
-<p align="center"><img src="https://raw.githubusercontent.com/kbaghini/evry-fx/main/docs/assets/cover.svg" alt="EV-RY FX — Motion for the text and images already on your page." width="100%"></p>
-
-<h1 align="center">EV-RY FX</h1>
-
-<p align="center"><strong>Your HTML. Four particle effects. Native when still.</strong></p>
-
-<p align="center">Free edition · 0.1.0-rc.1 preview · <a href="https://github.com/kbaghini/evry-fx/blob/main/LICENSE">MIT licensed</a> · JavaScript + TypeScript declarations</p>
-
-<p align="center">
-  <a href="#quick-start">Quick start</a> ·
-  <a href="https://kbaghini.github.io/evry-fx/docs/">Live demo</a> ·
-  <a href="https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md">Guide</a> ·
-  <a href="https://github.com/kbaghini/evry-fx/blob/main/QUICKSTART.fa.md">راهنمای فارسی</a>
-</p>
-
-Add WebGL particle motion to existing headings, display text, images and supported SVG icons. EV-RY FX borrows their content and placement from the page, animates textured particles, then returns to native browser rendering.
-
-Start with automatic scroll reveals, or attach selected elements through a small API. Keep your existing layout and components.
-
-## See it move
-
-![EV-RY FX motion preview](https://raw.githubusercontent.com/kbaghini/evry-fx/main/docs/assets/thd-preview.gif)
-
-The README shows an animated preview. Open the [live interactive demo](https://kbaghini.github.io/evry-fx/docs/) to try entry and exit effects on real text and images.
-
-## What you get
-
-| Content | Entry | Exit |
-| --- | --- | --- |
-| Text | Dust wind | Smoke |
-| Images and supported SVG | Drifting snow | Melt |
-
-- **A small automatic setup.** Reveal `h1`, `h2`, `[data-thd-text]` and `img[data-thd-image]` on intersection. Mark exclusions with `data-thd-ignore`.
-- **Manual control when needed.** Attach display text, images or supported static SVG; replay, cancel, refresh and destroy individual attachments. Simple image replacement is included.
-- **Your page keeps ownership.** Native DOM elements retain their content and semantics. Native rendering resumes when entry motion settles.
-- **One visual engine.** Text and media use textured triangular particles, four fixed presets and a 2000ms effect timeline. Individual particles can finish earlier within that timeline.
-- **A practical integration boundary.** Framework-independent JavaScript, typed APIs, a classic script entry and an explicit ES-module loader. A React integration example is included.
-
-## Quick start
-
-**Public preview: 0.1.0-rc.1.** Validate the supported content and layouts in your project before production use.
-
-Install from your project folder:
-
-```sh
-npm install @ev-ry/fx
-```
-
-### Add a script
-
-Serve the complete installed `node_modules/@ev-ry/fx` directory at `/thd/`. Preserve its modules and asset folders; this is not a single-file bundle.
-
-```html
-<head>
-  <!-- Early mask: load before body content, without async or defer. -->
-  <script src="/thd/src/dom-reveal-boot.js"></script>
-  <script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
-</head>
-<body>
-  <h1 data-thd-pending>Small details. A better feeling.</h1>
-  <p data-thd-text data-thd-pending>Made for your existing page.</p>
-  <img data-thd-image data-thd-pending src="photo.jpg"
-       width="640" height="400" alt="Describe your photograph">
-</body>
-```
-
-`data-thd-pending` prevents initial native paint before the entry effect; it does **not** select an element for attachment. Use it only on selected targets. The mask preserves space, is absent without JavaScript, and has a failure fallback. [First-paint setup, CSP and troubleshooting →](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md#first-paint-setup-avoid-an-initial-flash)
-
-The classic loader uses an existing `window.THREE` or loads the bundled Three.js r158 asset. Serve examples over HTTP, not `file://`. Existing `THDFree`, `data-thd-*` and `src/dom-*` API/file names are retained in this release.
-
-### Use a module
-
-Provide a compatible Three.js namespace; r158 is the tested version. Call the loader in the browser after the host elements exist:
-
-```js
-import * as THREE from 'three';
-import { loadFree } from '@ev-ry/fx/script';
-
-const api = await loadFree({ THREE, auto: false });
-const free = api.create(document, { auto: false });
-
-const title = free.attachText(document.querySelector('.title'), {
-  revealOnView: { threshold: 0.5, once: false }
-});
-
-// Later, on an explicit user action:
-// title.play('exit');
-// title.cancel();
-
-// On component unmount: free.destroy();
-```
-
-Importing the loader does not initialize the page. Its first call chooses automatic initialization; repeated calls share that initialization. Use `auto:true` for automatic scanning, or `auto:false` with `api.create()` for manual ownership. Do not attach the same element both ways.
-
-For direct ownership with injected Three.js, `createFree` is also exported from `@ev-ry/fx`. See the [API and lifecycle guide](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md).
-
-## Examples and guide
-
-| Start here | What it demonstrates |
-| --- | --- |
-| [Script example](https://github.com/kbaghini/evry-fx/blob/main/examples/script.html) | Automatic heading entry, including the early mask |
-| [Navigation example](https://github.com/kbaghini/evry-fx/blob/main/examples/navigation.html) | Back/forward navigation and page lifecycle |
-| [React example](https://github.com/kbaghini/evry-fx/blob/main/examples/AnimatedTitle.jsx) | A string title with effect cleanup and StrictMode handling |
-| [Detailed guide](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md) | SVG, image swaps, selectors, thresholds, canvas routing and troubleshooting |
-| [Persian quickstart](https://github.com/kbaghini/evry-fx/blob/main/QUICKSTART.fa.md) | Installation and integration notes in Persian |
-| [Release notes](https://github.com/kbaghini/evry-fx/blob/main/docs/RELEASE-NOTES.md) | Changes, tested scope and remaining limits |
-
-## A few useful boundaries
-
-- Repeated scroll reveals hide and rearm after a **complete exit**. Scroll exit does not run the smoke/melt effect; use `play('exit')` for animated disappearance.
-- After adding or removing automatic targets, call `refresh()`. Destroy owned attachments on component unmount; see the guide for back/forward-cache handling.
-- Ordinary page content uses a shared document-connected canvas. Special layouts can route to a local canvas. Arbitrary CSS stacking, clipping and typography are not fully reproduced.
-- SVG support is a static shape/path subset. Unsupported SVG/CSS and images blocked by canvas CORS restrictions can remain native.
-- This Free build does not include editable inputs, arbitrary effect customization or a dedicated React/Vue component pack.
-
-EV-RY FX Free is [MIT licensed](https://github.com/kbaghini/evry-fx/blob/main/LICENSE). Bundled dependencies retain their own licenses and [notices](https://github.com/kbaghini/evry-fx/blob/main/NOTICE.md). This license covers the Free distribution; other editions are separate.
+<p align="center"><img src="https://raw.githubusercontent.com/kbaghini/evry-fx/main/docs/assets/cover.svg" alt="EV-RY FX — Motion for the text and images already on your page." width="100%"></p>
+
+<h1 align="center">EV-RY FX</h1>
+
+<p align="center"><strong>Your HTML. Four particle effects. Native when still.</strong></p>
+
+<p align="center">Free edition · 0.1.0-rc.3 preview · <a href="https://github.com/kbaghini/evry-fx/blob/main/LICENSE">MIT licensed</a> · JavaScript + TypeScript declarations</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="https://kbaghini.github.io/evry-fx/docs/">Live demo</a> ·
+  <a href="https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md">Guide</a> ·
+  <a href="https://github.com/kbaghini/evry-fx/blob/main/QUICKSTART.fa.md">راهنمای فارسی</a>
+</p>
+
+Add WebGL particle motion to existing headings, display text, images and supported SVG icons. EV-RY FX borrows their content and placement from the page, animates textured particles, then returns to native browser rendering.
+
+Start with automatic scroll reveals, or attach selected elements through a small API. Keep your existing layout and components.
+
+## See it move
+
+![EV-RY FX motion preview](https://raw.githubusercontent.com/kbaghini/evry-fx/main/docs/assets/thd-preview.gif)
+
+The README shows an animated preview. Open the [live interactive demo](https://kbaghini.github.io/evry-fx/docs/) to try entry and exit effects on real text and images.
+
+## What you get
+
+| Content | Entry | Exit |
+| --- | --- | --- |
+| Text | Dust wind | Smoke |
+| Images and supported SVG | Drifting snow | Melt |
+
+- **A small automatic setup.** Reveal `h1`, `h2`, `[data-thd-text]` and `img[data-thd-image]` on intersection. Mark exclusions with `data-thd-ignore`.
+- **Manual control when needed.** Attach display text, images or supported static SVG; replay, cancel, refresh and destroy individual attachments. Simple image replacement is included.
+- **Your page keeps ownership.** Native DOM elements retain their content and semantics. Native rendering resumes when entry motion settles.
+- **One visual engine.** Text and media use textured triangular particles, four fixed presets and a 2000ms effect timeline. Individual particles can finish earlier within that timeline.
+- **A practical integration boundary.** Framework-independent JavaScript, typed APIs, a classic script entry and an explicit ES-module loader. A React integration example is included.
+
+## Quick start
+
+**Public preview: 0.1.0-rc.3.** Validate the supported content and layouts in your project before production use.
+
+Install from your project folder:
+
+```sh
+npm install @ev-ry/fx
+```
+
+### Add a script
+
+Serve the complete installed `node_modules/@ev-ry/fx` directory at `/thd/`. Preserve its modules and asset folders; this is not a single-file bundle.
+
+```html
+<head>
+  <!-- Early mask: load before body content, without async or defer. -->
+  <script src="/thd/src/dom-reveal-boot.js"></script>
+  <script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
+</head>
+<body>
+  <h1 data-thd-pending>Small details. A better feeling.</h1>
+  <p data-thd-text data-thd-pending>Made for your existing page.</p>
+  <img data-thd-image data-thd-pending src="photo.jpg"
+       width="640" height="400" alt="Describe your photograph">
+</body>
+```
+
+`data-thd-pending` prevents initial native paint before the entry effect; it does **not** select an element for attachment. Use it only on selected targets. The mask preserves space, is absent without JavaScript, and has a failure fallback. [First-paint setup, CSP and troubleshooting →](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md#first-paint-setup-avoid-an-initial-flash)
+
+The classic loader uses an existing `window.THREE` or loads the bundled Three.js r158 asset. Serve examples over HTTP, not `file://`. Existing `THDFree`, `data-thd-*` and `src/dom-*` API/file names are retained in this release.
+
+### Use a module
+
+Provide a compatible Three.js namespace; r158 is the tested version. Call the loader in the browser after the host elements exist:
+
+```js
+import * as THREE from 'three';
+import { loadFree } from '@ev-ry/fx/script';
+
+const api = await loadFree({ THREE, auto: false });
+const free = api.create(document, { auto: false });
+
+const title = free.attachText(document.querySelector('.title'), {
+  revealOnView: { threshold: 0.5, once: false }
+});
+
+// Later, on an explicit user action:
+// title.play('exit');
+// title.cancel();
+
+// On component unmount: free.destroy();
+```
+
+Importing the loader does not initialize the page. Its first call chooses automatic initialization; repeated calls share that initialization. Use `auto:true` for automatic scanning, or `auto:false` with `api.create()` for manual ownership. Do not attach the same element both ways.
+
+For direct ownership with injected Three.js, `createFree` is also exported from `@ev-ry/fx`. See the [API and lifecycle guide](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md).
+
+## Examples and guide
+
+| Start here | What it demonstrates |
+| --- | --- |
+| [Script example](https://github.com/kbaghini/evry-fx/blob/main/examples/script.html) | Automatic heading entry, including the early mask |
+| [Navigation example](https://github.com/kbaghini/evry-fx/blob/main/examples/navigation.html) | Back/forward navigation and page lifecycle |
+| [React example](https://github.com/kbaghini/evry-fx/blob/main/examples/AnimatedTitle.jsx) | A string title with effect cleanup and StrictMode handling |
+| [Detailed guide](https://github.com/kbaghini/evry-fx/blob/main/docs/GUIDE.md) | SVG, image swaps, selectors, thresholds, canvas routing and troubleshooting |
+| [Persian quickstart](https://github.com/kbaghini/evry-fx/blob/main/QUICKSTART.fa.md) | Installation and integration notes in Persian |
+| [Release notes](https://github.com/kbaghini/evry-fx/blob/main/docs/RELEASE-NOTES.md) | Changes, tested scope and remaining limits |
+
+## A few useful boundaries
+
+- Repeated scroll reveals hide and rearm after a **complete exit**. Scroll exit does not run the smoke/melt effect; use `play('exit')` for animated disappearance.
+- After adding or removing automatic targets, call `refresh()`. Destroy owned attachments on component unmount; see the guide for back/forward-cache handling.
+- Ordinary page content uses a shared document-connected canvas. Special layouts can route to a local canvas. Arbitrary CSS stacking, clipping and typography are not fully reproduced.
+- SVG support is a static shape/path subset. Unsupported SVG/CSS and images blocked by canvas CORS restrictions can remain native.
+- This Free build does not include editable inputs, arbitrary effect customization or a dedicated React/Vue component pack.
+
+EV-RY FX Free is [MIT licensed](https://github.com/kbaghini/evry-fx/blob/main/LICENSE). Bundled dependencies retain their own licenses and [notices](https://github.com/kbaghini/evry-fx/blob/main/NOTICE.md). This license covers the Free distribution; other editions are separate.
+
+## Real integration: EV-RY website
+
+[See the EV-RY product-showcase integration](examples/evry-website.md): alternating snow/melt image transitions, animated captions and persistent-engine navigation. Includes initial-reveal and lifecycle guidance; the full website is currently a local integration.