@ev-ry/fx 0.1.0-rc.2 → 0.1.0-rc.4

package/QUICKSTART.fa.md

@@ -1,94 +1,106 @@
-# EV-RY FX Free 0.1.0-rc.2 — نصب آزمایشی
-
-این نسخهٔ آزمایشی عمومی با مجوز 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.2.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 واقعی همچنان لازم است.
-
-### آماده‌سازی و مصرف پردازش
-
-برای تصویر خارج از دید یا با اندازهٔ صفر، `ready` ممکن است با وضعیت موقت بومی و دلیل `Image not visible` تمام شود؛ این به معنی آماده‌بودن مش روی GPU نیست. آماده‌سازی تصویر از نزدیکی صفحه، حدود نصف ارتفاع viewport جلوتر، آغاز می‌شود. بارگیری شبکهٔ خود `img` همچنان تابع مرورگر است. هنگام resize سریع، مش قبلی برای مدت کوتاه با کادر حرکت می‌کند و برش و گوشه‌های نهایی پس از تجمیع تغییرات بازسازی می‌شوند؛ ساعت افکت از ابتدا شروع نمی‌شود.
-
-متن ثابت از چیدمان معتبر و پیکسل‌های کش‌شده استفاده می‌کند. سقف کش مشترک پیکسل‌ها ۱۶MiB است؛ این سقف کل حافظهٔ صفحه یا GPU نیست. بارگیری فونت کش مرتبط را تازه می‌کند. متن پشتیبانی‌نشده بومی نمایش داده می‌شود و موتور روی همان خطای معلوم مدام تلاش نمی‌کند؛ پس از اصلاح سبک، `refresh()` امکان تلاش مجدد را می‌دهد.
-
-### مشخصات نسخه
-
-- متن: ورود باد، خروج دود. تصویر/SVG: ورود برف، خروج ذوب.
-- مدت۲ ثانیه، ذرات مثلثی، سکون بومی، شکل‌گیری دیرتر برای نمایش‌دهنده‌ها.
-- canvas متصل به سند پیش‌فرض است؛ حالت خودکار برای بعضی محدوده‌ها محلی می‌شود.
-- قبل از جداکردن بخش صفحه owner.destroy() را صدا بزنید. برای اسکن عناصر جدید owner.refresh().
-- چهار افکت ثابت؛ ویرایشگر، افکت سفارشی و پشتیبانی تمام CSS/SVG در این بسته نیستند.
-- یک script با فایل‌های همراه است، نه یک فایل یکپارچه. ساختار پوشه‌ها را حفظ کنید.
+# EV-RY FX Free 0.1.0-rc.4 — نصب آزمایشی
+
+این نسخهٔ آزمایشی عمومی با مجوز MIT ارائه می‌شود. نام بسته در npm برابر @ev-ry/fx است. [صفحهٔ رسمی FX](https://ev-ry.com/fx/) و [دموی تعاملی Free](https://kbaghini.github.io/evry-fx/docs/) جداگانه در دسترس‌اند.
+
+## روش 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')` درخواست محو متحرک است.
+
+`threshold` نسبت مساحت قابل مشاهده است: صفر برای اولین تقاطع مثبت، `0.5` برای نصف و `1` برای تمام آیتم. آیتم بزرگ‌تر از محدودهٔ دید ممکن است هرگز به مقدار یک نرسد.
+
+اگر بعد از اتصال دارای `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 واقعی همچنان لازم است.
+
+### آماده‌سازی و مصرف پردازش
+
+`surface.ready` نتیجهٔ آماده‌سازی است، نه پایان نصب موتور؛ برای متن یا SVG پایین صفحه ممکن است تا نزدیک‌شدن به دید منتظر بماند. فعال‌شدن دکمه‌های کل صفحه را به `ready` همهٔ آیتم‌ها وابسته نکنید. پس از ساخت اتصال می‌توانید `play()` را صدا بزنید و پایان اجرای درخواست‌شده را با `whenFinished()` بگیرید.
+
+برای تصویر خارج از دید یا با اندازهٔ صفر، `ready` ممکن است با وضعیت موقت بومی و دلیل `Image not visible` تمام شود؛ این به معنی آماده‌بودن مش روی GPU نیست. آماده‌سازی تصویر از نزدیکی صفحه، حدود نصف ارتفاع viewport جلوتر، آغاز می‌شود. بارگیری شبکهٔ خود `img` همچنان تابع مرورگر است. هنگام resize سریع، مش قبلی برای مدت کوتاه با کادر حرکت می‌کند و برش و گوشه‌های نهایی پس از تجمیع تغییرات بازسازی می‌شوند؛ ساعت افکت از ابتدا شروع نمی‌شود.
+
+متن ثابت از چیدمان معتبر و پیکسل‌های کش‌شده استفاده می‌کند. سقف کش مشترک پیکسل‌ها ۱۶MiB است؛ این سقف کل حافظهٔ صفحه یا GPU نیست. بارگیری فونت کش مرتبط را تازه می‌کند. متن پشتیبانی‌نشده بومی نمایش داده می‌شود و موتور روی همان خطای معلوم مدام تلاش نمی‌کند؛ پس از اصلاح سبک، `refresh()` امکان تلاش مجدد را می‌دهد.
+
+### مشخصات نسخه
+
+برای پایان افکت از `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,14 +1,15 @@
-<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>
+<p align="center"><a href="https://ev-ry.com/fx/"><img src="https://raw.githubusercontent.com/kbaghini/evry-fx/main/docs/assets/cover.svg" alt="EV-RY FX Free — visit the official FX website." width="100%"></a></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.2 preview · <a href="https://github.com/kbaghini/evry-fx/blob/main/LICENSE">MIT licensed</a> · JavaScript + TypeScript declarations</p>
+<p align="center">Free edition · 0.1.0-rc.4 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> ·
+<p align="center">
+  <a href="https://ev-ry.com/fx/">Official FX website ↗</a> ·
+  <a href="https://kbaghini.github.io/evry-fx/docs/">See FX Free in action ↗</a> ·
+  <a href="#quick-start">Quick start</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>
@@ -21,7 +22,7 @@ Start with automatic scroll reveals, or attach selected elements through a small
 
 ![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.
+The README shows an animated preview. Open the [live interactive Free demo](https://kbaghini.github.io/evry-fx/docs/) to try the four fixed effects on real text and images. [Other FX editions](https://ev-ry.com/fx/) are separate from this MIT-licensed package.
 
 ## What you get
 
@@ -38,7 +39,7 @@ The README shows an animated preview. Open the [live interactive demo](https://k
 
 ## Quick start
 
-**Public preview: 0.1.0-rc.2.** Validate the supported content and layouts in your project before production use.
+**Public preview: 0.1.0-rc.4.** Validate the supported content and layouts in your project before production use.
 
 Install from your project folder:
 
@@ -114,3 +115,7 @@ For direct ownership with injected Three.js, `createFree` is also exported from
 - 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. This is an integration recipe; the [public FX page](https://ev-ry.com/fx/) may use features beyond the four-effect Free demo.

package/build-report.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.4",
   "effects": [
     "dust-wind",
     "smoke",
@@ -14,8 +14,8 @@
     },
     {
       "file": "src/dom-free.js",
-      "bytes": 3047,
-      "gzip": 1159
+      "bytes": 5268,
+      "gzip": 1952
     },
     {
       "file": "src/dom-attachment.js",
@@ -24,23 +24,23 @@
     },
     {
       "file": "src/dom-reveal.js",
-      "bytes": 6042,
-      "gzip": 2310
+      "bytes": 6790,
+      "gzip": 2528
     },
     {
       "file": "src/dom-svg-surface.js",
-      "bytes": 4873,
-      "gzip": 1994
+      "bytes": 5096,
+      "gzip": 2098
     },
     {
       "file": "src/dom-image-surface.js",
-      "bytes": 10611,
-      "gzip": 3666
+      "bytes": 15284,
+      "gzip": 4834
     },
     {
       "file": "src/image-surface.js",
-      "bytes": 11984,
-      "gzip": 4278
+      "bytes": 12425,
+      "gzip": 4356
     },
     {
       "file": "src/motion-envelope.js",
@@ -54,13 +54,13 @@
     },
     {
       "file": "src/raster-texture-mesh.js",
-      "bytes": 2592,
-      "gzip": 1150
+      "bytes": 2627,
+      "gzip": 1159
     },
     {
       "file": "src/raster-texture-material.js",
-      "bytes": 4981,
-      "gzip": 1903
+      "bytes": 5060,
+      "gzip": 1914
     },
     {
       "file": "src/text-mesh-density.js",
@@ -94,8 +94,8 @@
     },
     {
       "file": "src/triangle-effect.js",
-      "bytes": 13694,
-      "gzip": 4287
+      "bytes": 13953,
+      "gzip": 4324
     },
     {
       "file": "src/particle-centers.js",
@@ -104,13 +104,13 @@
     },
     {
       "file": "src/text-edit-motions.js",
-      "bytes": 2068,
-      "gzip": 1035
+      "bytes": 2083,
+      "gzip": 1045
     },
     {
       "file": "src/text-motion-recipes.js",
-      "bytes": 4883,
-      "gzip": 1895
+      "bytes": 4954,
+      "gzip": 1907
     },
     {
       "file": "src/text-motion-programs.js",
@@ -119,18 +119,18 @@
     },
     {
       "file": "src/text-effect-options.js",
-      "bytes": 2309,
-      "gzip": 1052
+      "bytes": 2337,
+      "gzip": 1055
     },
     {
       "file": "src/text-effect-path.js",
-      "bytes": 2924,
-      "gzip": 1132
+      "bytes": 2985,
+      "gzip": 1141
     },
     {
       "file": "src/text-motion-primitives.js",
-      "bytes": 4430,
-      "gzip": 1894
+      "bytes": 4862,
+      "gzip": 2031
     },
     {
       "file": "src/text-motion-contour.js",
@@ -154,23 +154,23 @@
     },
     {
       "file": "src/dom-image-swap.js",
-      "bytes": 3050,
-      "gzip": 1225
+      "bytes": 3722,
+      "gzip": 1441
     },
     {
       "file": "src/dom-once.js",
-      "bytes": 3023,
-      "gzip": 1143
+      "bytes": 3463,
+      "gzip": 1357
     },
     {
       "file": "src/render-owner.js",
-      "bytes": 3954,
-      "gzip": 1456
+      "bytes": 4268,
+      "gzip": 1583
     },
     {
       "file": "src/viewport-render-owner.js",
-      "bytes": 24414,
-      "gzip": 7399
+      "bytes": 25171,
+      "gzip": 7607
     },
     {
       "file": "src/viewport-clip.js",
@@ -179,8 +179,8 @@
     },
     {
       "file": "src/dom-text-surface.js",
-      "bytes": 20197,
-      "gzip": 6360
+      "bytes": 22605,
+      "gzip": 7056
     },
     {
       "file": "src/hybrid-text-flow.js",
@@ -189,13 +189,13 @@
     },
     {
       "file": "src/runtime-font-engine.js",
-      "bytes": 12202,
-      "gzip": 3758
+      "bytes": 12245,
+      "gzip": 3731
     },
     {
       "file": "src/font-rasterizer.js",
-      "bytes": 4384,
-      "gzip": 1544
+      "bytes": 4404,
+      "gzip": 1531
     },
     {
       "file": "src/native-run-shaping.js",
@@ -214,13 +214,13 @@
     },
     {
       "file": "src/text-edit-effect.js",
-      "bytes": 7704,
-      "gzip": 2580
+      "bytes": 7805,
+      "gzip": 2590
     },
     {
       "file": "src/insertion-range.js",
-      "bytes": 1858,
-      "gzip": 667
+      "bytes": 1887,
+      "gzip": 675
     },
     {
       "file": "src/text-motion-character-centers.js",
@@ -239,8 +239,8 @@
     },
     {
       "file": "src/dom-raster-cache.js",
-      "bytes": 1677,
-      "gzip": 793
+      "bytes": 1710,
+      "gzip": 800
     },
     {
       "file": "src/dom-rich-text.js",
@@ -257,6 +257,11 @@
       "bytes": 2103,
       "gzip": 1021
     },
+    {
+      "file": "src/dom-text-paint-mask.js",
+      "bytes": 1469,
+      "gzip": 644
+    },
     {
       "file": "src/dom-auto-route.js",
       "bytes": 1884,
@@ -269,8 +274,8 @@
     },
     {
       "file": "src/dom-free-script.js",
-      "bytes": 584,
-      "gzip": 357
+      "bytes": 760,
+      "gzip": 446
     },
     {
       "file": "src/dom-free-bootstrap.js",
@@ -284,8 +289,8 @@
     },
     {
       "file": "src/dom-free-loader.js",
-      "bytes": 593,
-      "gzip": 361
+      "bytes": 761,
+      "gzip": 448
     },
     {
       "file": "src/dom-free-loader.d.ts",
@@ -294,8 +299,8 @@
     },
     {
       "file": "src/dom-free.d.ts",
-      "bytes": 1259,
-      "gzip": 587
+      "bytes": 1387,
+      "gzip": 639
     },
     {
       "file": "src/dom-auto-reveal.d.ts",
@@ -304,8 +309,8 @@
     },
     {
       "file": "src/dom-attachment.d.ts",
-      "bytes": 4471,
-      "gzip": 1373
+      "bytes": 4609,
+      "gzip": 1410
     },
     {
       "file": "assets/vendor/three-LICENSE.txt",
@@ -323,6 +328,6 @@
       "gzip": 1971
     }
   ],
-  "bytes": 960385,
-  "gzipSum": 276024
-}
+  "bytes": 976567,
+  "gzipSum": 280968
+}

package/docs/GUIDE.md

@@ -39,9 +39,15 @@ Importing this entry is inert, including during server-side rendering. Call `loa
 
 The classic `<script src="…/src/dom-free-script.js">` URL remains unchanged. `@ev-ry/fx/classic-script` resolves that classic asset; it is not an ES-module import entry. Do not use `type="module"` with the classic asset: use `loadFree` instead.
 
-Auto selects h1/h2/[data-thd-text] and img[data-thd-image]; data-thd-ignore and interactive/navigation/dialog regions are excluded. Options: auto, textSelector, imageSelector, presentation, threshold, once, intersectionRoot. Call refresh after route/DOM changes. Manual attachment accepts presentation and revealOnView. play/cancel/refresh/stats/destroy are exposed; arbitrary effects are not. Scroll exit hides repeated targets rather than running an exit animation.
+Auto selects h1/h2/[data-thd-text] and img[data-thd-image]; data-thd-ignore and interactive/navigation/dialog regions are excluded. Options: auto, textSelector, imageSelector, presentation, threshold, once, intersectionRoot. Call refresh after route/DOM changes. Manual attachment accepts presentation and revealOnView. play/cancel/refresh/stats/destroy are exposed; arbitrary effects are not. Scroll exit hides repeated targets rather than running an exit animation.
+
+An explicit `surface.play()` takes ownership from automatic `revealOnView` for that attachment, retaining the initial mask until rendering starts. Offscreen text, images and SVG keep their start timestamp without particle updates or drawing, and resume at the elapsed position instead of restarting. Use `await surface.whenFinished()` for cleanup, including native handoff and offscreen completion; it returns `{status: 'completed' | 'cancelled' | 'unsupported'}`. See `examples/evry-website.md` for captions driven by a slider clock.
+
+Concurrent `whenFinished()` calls share one pending completion and polling loop. A new successful `play()` cancels the previous pending wait; an invalid phase does not interrupt it. Cancellation, destruction of the attachment or its installation, and detaching the target resolve outstanding waits as `cancelled`. An untouched automatic reveal can wait for its first intersection without a preparation timeout. The 30-second watchdog only bounds an actual play/preparation attempt. Suspended effects are checked infrequently; waiting does not require a per-frame render loop.
 
-Preparation is lazy for offscreen targets. Native content may paint before a late script initializes; use the optional early mask below for initial-page entry effects. Unsupported content falls back to native presentation. Cross-origin image canvas restrictions and unsupported rich CSS still apply. This does not claim general CSS reproduction or new physical-device validation.
+Preparation is lazy for offscreen targets. Native content may paint before a late script initializes; use the optional early mask below for initial-page entry effects. Unsupported content falls back to native presentation. Cross-origin image canvas restrictions and unsupported rich CSS still apply. This does not claim general CSS reproduction or new physical-device validation.
+
+`surface.ready` describes the first preparation result, not installation readiness. A text/SVG target below the viewport can remain unprepared until it approaches view. Enable ordinary controls after attachment creation rather than waiting for every page target's `ready`. `play()` can queue a request before preparation; use `whenFinished()` for the end of that requested effect. Targets without an entry request keep their native presentation.
 
 For an offscreen or zero-area image, `ready` can resolve with temporary native reason `Image not visible`; it does not promise a prepared GPU mesh outside the viewport. Image preparation begins near the viewport (roughly half a viewport height ahead). The native image's network loading policy is unchanged. Resize work is coalesced: the current raster follows the new box briefly, then the final crop and rounded corners are rebuilt after about 50ms of quiet, with a roughly 150ms bound during continuous resizing. Existing motion keeps its timeline.
 

package/docs/RELEASE-NOTES.md

@@ -1,3 +1,36 @@
+# EV-RY FX Free 0.1.0-rc.4
+
+- Failed classic/module initialization can be retried after a dependency-loading error; successful first initialization remains shared.
+- Cancelling an image swap settles promptly even if image decoding stalls. A late job cannot roll back host changes twice.
+- Image cleanup preserves an inline opacity change made by the host while attached.
+- The Free package retains the verified four-preset runtime from rc.3; no private Studio/Pro features were imported from the shared development tree.
+- Documentation links the official [FX page](https://ev-ry.com/fx/) and keeps the [four-effect Free demo](https://kbaghini.github.io/evry-fx/docs/) distinct.
+
+Validation covers a clean tarball install, Chrome desktop/mobile-layout/reduced-motion scenarios, loader retry and lifecycle checks. It does not certify physical devices, all SVG/CORS cases or production-site performance.
+
+# EV-RY FX Free 0.1.0-rc.3
+
+- Cancel/update no longer starts a fresh text handoff; invalid play phases leave automatic reveal intact, and offscreen no-effect calls complete immediately.
+- Image/SVG source refresh preserves the active effect clock, seed and settled exit mask. SVG snapshot errors retain native fallback diagnostics.
+- SVG native pixels now appear below the settled mesh during the same 250ms handoff as images.
+- Cancelling an image swap restores the incoming image's original location, including removal when it was initially detached.
+- Completion waits share one pending poller, cancel promptly on superseding play or owner disposal, and do not time out untouched intersection reveals.
+- Public whenFinished() for completion, cancellation and unsupported rendering.
+- Offscreen text preserves its effect clock without particle updates or drawing; plain/rich text resumes at elapsed time and completion no longer waits for viewport entry.
+- Explicit play takes ownership from automatic reveal without dropping the initial mask or restarting on intersection. Existing automatic reveal behavior remains in effect until explicit play.
+- Offscreen exits suppress native text/image/SVG paint immediately and retain it through reentry and completion; cancellation and disposal restore original styles. Regression covers actual departure shader clocks, seeds, coordinates and rendered smoke pixels.
+- Transient effects and image swaps complete on their original offscreen timeline without waiting for visual readiness; hidden transient polling is infrequent and cancellation still restores native content.
+- Images reveal native pixels at assembly completion, then fade the mesh for 250ms, including swaps.
+
+- Reuse local rendering buffers across differently sized surfaces, avoiding repeated GPU buffer allocation.
+- Clear retained scratch pixels before each local surface copy.
+- Image motion preserves source colors by default (recipe glow defaults to zero).
+- Gradual particle appearance on the existing effect clock.
+- Free image swaps support `enter` and `topImage`, including outgoing-only melt over the next native image.
+- Include the EV-RY website integration recipe and initial-reveal lifecycle guidance.
+
+Website artwork and SPA changes are not package runtime exports. Physical-device performance and the reported first-image brightness difference are not certified by this release.
+
 # EV-RY FX Free 0.1.0-rc.2
 
 - Fix collapsed whitespace at wrapped line ends triggering native fallback, including Android headings with negative letter spacing.