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

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')` درخواست محو متحرک است.
-
+# 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

@@ -4,7 +4,7 @@
 
 <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.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> ·
@@ -38,7 +38,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.3.** Validate the supported content and layouts in your project before production use.
 
 Install from your project folder:
 
@@ -114,3 +114,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. Includes initial-reveal and lifecycle guidance; the full website is currently a local integration.

package/build-report.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "effects": [
     "dust-wind",
     "smoke",
@@ -14,8 +14,8 @@
     },
     {
       "file": "src/dom-free.js",
-      "bytes": 3047,
-      "gzip": 1159
+      "bytes": 5191,
+      "gzip": 1910
     },
     {
       "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": 14775,
+      "gzip": 4711
     },
     {
       "file": "src/image-surface.js",
-      "bytes": 11984,
-      "gzip": 4278
+      "bytes": 12425,
+      "gzip": 4356
     },
     {
       "file": "src/motion-envelope.js",
@@ -94,8 +94,8 @@
     },
     {
       "file": "src/triangle-effect.js",
-      "bytes": 13694,
-      "gzip": 4287
+      "bytes": 13758,
+      "gzip": 4313
     },
     {
       "file": "src/particle-centers.js",
@@ -129,8 +129,8 @@
     },
     {
       "file": "src/text-motion-primitives.js",
-      "bytes": 4430,
-      "gzip": 1894
+      "bytes": 4764,
+      "gzip": 2022
     },
     {
       "file": "src/text-motion-contour.js",
@@ -154,23 +154,23 @@
     },
     {
       "file": "src/dom-image-swap.js",
-      "bytes": 3050,
-      "gzip": 1225
+      "bytes": 3310,
+      "gzip": 1316
     },
     {
       "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": 22552,
+      "gzip": 7092
     },
     {
       "file": "src/hybrid-text-flow.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,
@@ -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": 4537,
+      "gzip": 1404
     },
     {
       "file": "assets/vendor/three-LICENSE.txt",
@@ -323,6 +328,6 @@
       "gzip": 1971
     }
   ],
-  "bytes": 960385,
-  "gzipSum": 276024
+  "bytes": 974292,
+  "gzipSum": 280473
 }

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,26 @@
+# 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.

package/examples/evry-website.md

@@ -0,0 +1,58 @@
+# EV-RY website: product showcase
+
+The EV-RY marketing website is a real integration case: a four-product showcase, animated captions, one shared FX installation across client-side navigation, and native content at rest.
+
+The website is currently a local integration at `http://127.0.0.1:8780/`, not a hosted demo included in this package. The public runnable examples are linked from the package README. The website backend, forms and artwork are not dependencies of FX.
+
+## Initial reveal without a flash
+
+Place `data-thd-pending` on the image and caption elements in the HTML, use the documented boot mask, then let `revealOnView` transfer the mask to the first rendered frame. Keep each returned handle until cleanup. Do not remove the mask manually on attachment readiness.
+
+```js
+const imageSurface = engine.attachImage(image, {
+  presentation: 'global',
+  revealOnView: { threshold: 0, once: true }
+});
+const captionSurfaces = captionLines.map(line => {
+  const surface = engine.attachText(line, {
+    presentation: 'local',
+    revealOnView: { threshold: 0, once: true }
+  });
+  surface.play('enter');
+  return surface;
+});
+```
+
+The captions explicitly start with the slide, even when below the viewport. `play()` takes control from automatic intersection reveal while retaining its initial paint mask until a rendered frame. It does not wait for visibility or restart on reentry. Without explicit `play()`, `revealOnView` continues to wait for the configured intersection and follows its `once` setting.
+
+## Alternate two image transitions
+
+After decoding the next mounted image, alternate between incoming snow over the previous image and outgoing melt above the already visible next image:
+
+```js
+const transition = engine.swapImage(previous, next, {
+  enter: !melt,
+  exit: melt,
+  topImage: melt ? 'previous' : 'next',
+  waitForExit: false,
+  presentation: 'global'
+});
+const result = await transition.finished;
+if (result.status === 'completed') previous.remove();
+```
+
+Use a busy flag to prevent overlapping swaps. Pause scheduling while the document is hidden. On navigation, cancel an outstanding transition, clear the scheduled timeout and destroy page handles; retain the shared engine and refresh its automatic attachments after inserting the new page. Install the boot mask before the new DOM can paint. Destroy the engine only when the application is disposed.
+
+The five-second scheduling interval, caption layout, routing and product artwork belong to the website, not to the FX API. Local caption surfaces share rendering infrastructure; the retained scratch buffer avoids resizing the GPU buffer for each caption line.
+
+Create incoming captions from fresh authored markup rather than cloning a currently attached element: a live attachment can carry temporary engine-owned visibility attributes and styles. Commit the incoming image and caption together only after `transition.finished` reports `completed`. If image decoding, attachment or the swap fails, destroy incoming caption handles, remove their layer, retain the previous caption and image, then retry. Track each acquired handle immediately so partial attachment failures can also be cleaned up.
+
+Schedule one deadline five seconds from each transition start. After completion, wait only for the remaining time. If the transition itself overruns that deadline, start one next transition when available and establish a new deadline; do not discard interval ticks or queue catch-up transitions. Returning from a hidden tab and retrying a failed transition each establish a fresh five-second wait. This keeps start-to-start cadence stable without overlapping jobs.
+
+## Completion
+
+After `surface.play()`, await `surface.whenFinished()`. It returns a status of `completed`, `cancelled`, or `unsupported`. Completion includes the native handoff; avoid fixed cleanup timers or renderer statistics. Destroy page surfaces when navigating away.
+
+Offscreen text and media retain their start time without running per-particle updates or drawing frames. Returning during the effect evaluates its current elapsed time; returning after it ends shows the final state without replay. `whenFinished()` also completes when content remains offscreen, so slider cleanup never depends on scrolling captions into view. It checks the suspended clock infrequently instead of maintaining a render loop. Concurrent waits share a pending promise; starting a new play cancels the previous wait. Cancel or destroy the handle to release an outstanding wait.
+
+When an exit is requested offscreen, the engine immediately suppresses native paint while retaining layout and the DOM content. Native paint also remains hidden if an active departure leaves view. Reentry renders only the remaining departure particles; an expired exit stays hidden. Text, image and SVG attachments own this masking, so the site should not toggle native opacity or visibility to emulate it. Cancel/destroy restores the original presentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ev-ry/fx",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "private": false,
   "type": "module",
   "exports": {

package/src/dom-attachment.d.ts

@@ -1,5 +1,5 @@
 export interface SurfaceOptions {
-  /** Text/image/SVG only. Re-arm after complete exit. */
+  /** Text/image/SVG only. Re-arm after complete exit when once is false. Explicit play takes over automatic triggering. */
   revealOnView?: false | {threshold?: number; once?: boolean; root?: Element | null};
   resting?: 'mesh' | 'native';
   inputEffect?: string;

package/src/dom-free.d.ts

@@ -1,16 +1,16 @@
-import type {AutoRevealOptions} from './dom-auto-reveal.js';
-import type {DOMPresentation, SurfaceOptions, TextSurface, createDOMRenderer} from './dom-attachment.js';
-export const FREE_EFFECTS: Readonly<{textEnter:'dust-wind';textExit:'smoke';imageEnter:'drifting-snow';imageExit:'melt'}>;
-export type FreeSurface = Pick<TextSurface,'ready'|'play'|'refresh'|'stats'|'destroy'> & {cancel():void};
-export interface FreeAttachOptions {revealOnView?: SurfaceOptions['revealOnView'];presentation?: DOMPresentation;}
-export function createFree(THREE: Parameters<typeof createDOMRenderer>[0],root?: Document|Element,options?: AutoRevealOptions & {auto?:boolean;zIndex?:number;documentCanvas?:boolean;experimentalDocumentCanvas?:boolean}): {
-  attachText(element:HTMLElement,options?:FreeAttachOptions):FreeSurface;
-  attachImage(element:HTMLImageElement,options?:FreeAttachOptions):FreeSurface;
-  attachSVG(element:SVGSVGElement,options?:FreeAttachOptions):FreeSurface;
-  swapImage(previous:HTMLImageElement,next:HTMLImageElement,options?:{exit?:boolean;waitForExit?:boolean;presentation?:DOMPresentation}):{finished:Promise<{status:string}>;cancel():void};
-  refresh():void;
-  stats():{disposed:boolean;automatic:unknown;renderer:unknown};
-  destroy():void;
-};
+import type {AutoRevealOptions} from './dom-auto-reveal.js';
+import type {DOMPresentation, SurfaceOptions, TextSurface, createDOMRenderer} from './dom-attachment.js';
+export const FREE_EFFECTS: Readonly<{textEnter:'dust-wind';textExit:'smoke';imageEnter:'drifting-snow';imageExit:'melt'}>;
+export type FreeSurface = Pick<TextSurface,'ready'|'play'|'refresh'|'stats'|'destroy'> & {cancel():void;whenFinished():Promise<{status:'completed'|'cancelled'|'unsupported'}>};
+export interface FreeAttachOptions {revealOnView?: SurfaceOptions['revealOnView'];presentation?: DOMPresentation;}
+export function createFree(THREE: Parameters<typeof createDOMRenderer>[0],root?: Document|Element,options?: AutoRevealOptions & {auto?:boolean;zIndex?:number;documentCanvas?:boolean;experimentalDocumentCanvas?:boolean}): {
+  attachText(element:HTMLElement,options?:FreeAttachOptions):FreeSurface;
+  attachImage(element:HTMLImageElement,options?:FreeAttachOptions):FreeSurface;
+  attachSVG(element:SVGSVGElement,options?:FreeAttachOptions):FreeSurface;
+  swapImage(previous:HTMLImageElement,next:HTMLImageElement,options?:{exit?:boolean;enter?:boolean;topImage?:'previous'|'next';waitForExit?:boolean;presentation?:DOMPresentation}):{finished:Promise<{status:string}>;cancel():void};
+  refresh():void;
+  stats():{disposed:boolean;automatic:unknown;renderer:unknown};
+  destroy():void;
+};