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

package/QUICKSTART.fa.md

@@ -1,6 +1,6 @@
-# EV-RY FX Free 0.1.0-rc.3 — نصب آزمایشی
+# EV-RY FX Free 0.1.0-rc.4 — نصب آزمایشی
 
-این نسخهٔ آزمایشی عمومی با مجوز MIT ارائه می‌شود. نام بسته در npm برابر @ev-ry/fx است.
+این نسخهٔ آزمایشی عمومی با مجوز MIT ارائه می‌شود. نام بسته در npm برابر @ev-ry/fx است. [صفحهٔ رسمی FX](https://ev-ry.com/fx/) و [دموی تعاملی Free](https://kbaghini.github.io/evry-fx/docs/) جداگانه در دسترس‌اند.
 
 ## روش script
 
@@ -34,7 +34,7 @@ H1/H2 خودکار انتخاب می‌شوند. برای تصویر `data-thd-i
 ## نصب با npm
 
 ```sh
-npm install ./thd-free-0.1.0-rc.3.tgz
+npm install @ev-ry/fx
 ```
 
 برای import از `@ev-ry/fx`، namespace سازگار THREE را خودتان ارائه کنید؛ نسخهٔ همراه script همان r158 است. راهنمای کامل API در docs/GUIDE.md قرار دارد.
@@ -63,13 +63,13 @@ const api = await loadFree({THREE, auto: true});
 
 پیش‌فرض `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 اعمال می‌شود.
+`threshold` نسبت مساحت قابل مشاهده است: صفر برای اولین تقاطع مثبت، `0.5` برای نصف و `1` برای تمام آیتم. آیتم بزرگ‌تر از محدودهٔ دید ممکن است هرگز به مقدار یک نرسد.
+
+اگر بعد از اتصال دارای `revealOnView`، صریحاً `play()` را فراخوانی کنید، زمان‌بندی دستی جای ورود خودکار را می‌گیرد؛ ماسک اولیه تا اولین فریم حفظ می‌شود، اما ورود به دید دیگر افکت را از نو شروع نمی‌کند. برای متن اسلایدر که باید هم‌زمان با اسلاید شروع شود، همین روش مناسب است. متن خارج از دید فقط زمان شروع را نگه می‌دارد و رسم و محاسبات ذرات متوقف می‌شوند؛ با برگشت، وضعیت متناسب با زمان سپری‌شده نمایش داده می‌شود. اگر زمان تمام شده باشد، افکت دوباره اجرا نمی‌شود.
+
+برای پایان افکت از `await surface.whenFinished()` استفاده کنید؛ پایان گذار به متن بومی را هم در نظر می‌گیرد و خارج از دید نیز تکمیل می‌شود. نتیجه یکی از وضعیت‌های `completed`، `cancelled` و `unsupported` است. برای تشخیص پایان، تایمر ثابت یا آمار رندر را در کد سایت بررسی نکنید. لغو یا تخریب اتصال، انتظار جاری را با وضعیت `cancelled` آزاد می‌کند.
+
+اگر `play('exit')` را خارج از دید فراخوانی کنید، نمایش بومی همان لحظه مخفی می‌شود؛ اندازه، جای عنصر و محتوای DOM حذف نمی‌شوند. اگر حذف در حال اجرا از دید خارج شود نیز نمایش بومی مخفی می‌ماند. هنگام برگشت، فقط ذرات متناسب با زمان سپری‌شده رسم می‌شوند و اگر حذف تمام شده باشد، آیتم مخفی می‌ماند. `play('enter')` آن را دوباره تشکیل می‌دهد؛ `cancel()` یا `destroy()` نمایش و سبک‌های بومی را بازمی‌گردانند. این رفتار در خود موتور برای متن، تصویر و SVG اعمال می‌شود.
 
 ### محل canvas و لایه‌ها
 
@@ -83,19 +83,19 @@ const api = await loadFree({THREE, auto: true});
 
 loader خودکار هنگام رفتن صفحه به حافظهٔ Back/Forward مرورگر، اتصال را نگه می‌دارد و هنگام بازگشت موقعیتش را تازه می‌کند؛ ورودهای یک‌باره دوباره ساخته نمی‌شوند. خروج واقعی صفحه منابع را آزاد می‌کند. اگر اتصال را خودتان با `api.create()` یا `createFree()` ساخته‌اید، مدیریت عمر آن هم با شماست: روی `pagehide` فقط در صورت `event.persisted === false` آن را آزاد کنید؛ در بازگشتِ persisted، `refresh()` کافی است. اتصال عمداً destroyشده خودکار زنده نمی‌شود. پاک‌سازی هنگام unmount واقعی همچنان لازم است.
 
-### آماده‌سازی و مصرف پردازش
-
-`surface.ready` نتیجهٔ آماده‌سازی است، نه پایان نصب موتور؛ برای متن یا SVG پایین صفحه ممکن است تا نزدیک‌شدن به دید منتظر بماند. فعال‌شدن دکمه‌های کل صفحه را به `ready` همهٔ آیتم‌ها وابسته نکنید. پس از ساخت اتصال می‌توانید `play()` را صدا بزنید و پایان اجرای درخواست‌شده را با `whenFinished()` بگیرید.
+### آماده‌سازی و مصرف پردازش
+
+`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 کرد.
+### مشخصات نسخه
+
+برای پایان افکت از `await surface.whenFinished()` استفاده کنید؛ نتیجه `completed`، `cancelled` یا `unsupported` است و پایان تبدیل مش به نمایش بومی را هم لحاظ می‌کند. چند فراخوانی هم‌زمان یک انتظار مشترک دارند. اجرای جدید، انتظار اجرای قبلی را لغو می‌کند؛ `cancel()`، `destroy()` و جداشدن عنصر از سند نیز انتظار را آزاد می‌کنند. انتظار ورود خودکار تا اولین intersection محدود به زمان آماده‌سازی نیست.
+
+متن، تصویر و SVG خارج دید ساعت افکت را با پردازش کم حفظ می‌کنند؛ ورود مجدد افکت را از ابتدا شروع نمی‌کند. هنگام درخواست محو خارج دید، نمایش بومی همان لحظه مخفی می‌شود. در اسلایدر، متن و تصویر بعدی را تنها پس از موفقیت تعویض نهایی کنید. برای متن بعدی عنصر تازه بسازید؛ عنصر متصل به موتور ممکن است سبک یا ویژگی موقت داشته باشد و نباید همان حالت زنده را clone کرد.
 
 - متن: ورود باد، خروج دود. تصویر/SVG: ورود برف، خروج ذوب.
 - مدت۲ ثانیه، ذرات مثلثی، سکون بومی، شکل‌گیری دیرتر برای نمایش‌دهنده‌ها.

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.3 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.3.** 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:
 
@@ -117,4 +118,4 @@ EV-RY FX Free is [MIT licensed](https://github.com/kbaghini/evry-fx/blob/main/LI
 
 ## 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.
+[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.3",
+  "version": "0.1.0-rc.4",
   "effects": [
     "dust-wind",
     "smoke",
@@ -14,8 +14,8 @@
     },
     {
       "file": "src/dom-free.js",
-      "bytes": 5191,
-      "gzip": 1910
+      "bytes": 5268,
+      "gzip": 1952
     },
     {
       "file": "src/dom-attachment.js",
@@ -34,8 +34,8 @@
     },
     {
       "file": "src/dom-image-surface.js",
-      "bytes": 14775,
-      "gzip": 4711
+      "bytes": 15284,
+      "gzip": 4834
     },
     {
       "file": "src/image-surface.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": 13758,
-      "gzip": 4313
+      "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": 4764,
-      "gzip": 2022
+      "bytes": 4862,
+      "gzip": 2031
     },
     {
       "file": "src/text-motion-contour.js",
@@ -154,8 +154,8 @@
     },
     {
       "file": "src/dom-image-swap.js",
-      "bytes": 3310,
-      "gzip": 1316
+      "bytes": 3722,
+      "gzip": 1441
     },
     {
       "file": "src/dom-once.js",
@@ -179,8 +179,8 @@
     },
     {
       "file": "src/dom-text-surface.js",
-      "bytes": 22552,
-      "gzip": 7092
+      "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",
@@ -274,8 +274,8 @@
     },
     {
       "file": "src/dom-free-script.js",
-      "bytes": 584,
-      "gzip": 357
+      "bytes": 760,
+      "gzip": 446
     },
     {
       "file": "src/dom-free-bootstrap.js",
@@ -289,8 +289,8 @@
     },
     {
       "file": "src/dom-free-loader.js",
-      "bytes": 593,
-      "gzip": 361
+      "bytes": 761,
+      "gzip": 448
     },
     {
       "file": "src/dom-free-loader.d.ts",
@@ -309,8 +309,8 @@
     },
     {
       "file": "src/dom-attachment.d.ts",
-      "bytes": 4537,
-      "gzip": 1404
+      "bytes": 4609,
+      "gzip": 1410
     },
     {
       "file": "assets/vendor/three-LICENSE.txt",
@@ -328,6 +328,6 @@
       "gzip": 1971
     }
   ],
-  "bytes": 974292,
-  "gzipSum": 280473
-}
+  "bytes": 976567,
+  "gzipSum": 280968
+}

package/docs/RELEASE-NOTES.md

@@ -1,15 +1,25 @@
-# EV-RY FX Free 0.1.0-rc.3
+# 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.
 
-- 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.
+# 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.

package/examples/evry-website.md

@@ -2,7 +2,7 @@
 
 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.
+The [EV-RY website](https://ev-ry.com/) and [FX product page](https://ev-ry.com/fx/) are public. This file describes an integration pattern, not a copy of the deployed website or a Free-only live demo. Try the package's separate [interactive Free demo](https://kbaghini.github.io/evry-fx/docs/) for its four fixed effects. The website backend, forms and artwork are not dependencies of FX.
 
 ## Initial reveal without a flash
 
@@ -13,17 +13,17 @@ 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.
+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
 
@@ -41,18 +41,18 @@ 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.
+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.
 
-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.
+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.
+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,57 +1,57 @@
-{
-  "name": "@ev-ry/fx",
-  "version": "0.1.0-rc.3",
-  "private": false,
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./src/dom-free.d.ts",
-      "import": "./src/dom-free.js"
-    },
-    "./script": {
-      "types": "./src/dom-free-loader.d.ts",
-      "import": "./src/dom-free-loader.js"
-    },
-    "./classic-script": "./src/dom-free-script.js"
-  },
-  "files": [
-    "src",
-    "assets",
-    "examples",
-    "README.md",
-    "LICENSE",
-    "NOTICE.md",
-    "QUICKSTART.fa.md",
-    "docs/GUIDE.md",
-    "docs/RELEASE-NOTES.md",
-    "build-report.json"
-  ],
-  "description": "Textured particle effects for existing HTML text, images and SVG. Native when still.",
-  "license": "MIT",
-  "author": {
-    "name": "Kamran Baghini",
-    "url": "https://ev-ry.com"
-  },
-  "keywords": [
-    "animation",
-    "particles",
-    "webgl",
-    "text-effects",
-    "image-effects",
-    "scroll-reveal",
-    "svg",
-    "rtl",
-    "ev-ry"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kbaghini/evry-fx.git"
-  },
-  "bugs": {
-    "url": "https://github.com/kbaghini/evry-fx/issues"
-  },
-  "homepage": "https://kbaghini.github.io/evry-fx/docs/"
-}
+{
+  "name": "@ev-ry/fx",
+  "version": "0.1.0-rc.4",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/dom-free.d.ts",
+      "import": "./src/dom-free.js"
+    },
+    "./script": {
+      "types": "./src/dom-free-loader.d.ts",
+      "import": "./src/dom-free-loader.js"
+    },
+    "./classic-script": "./src/dom-free-script.js"
+  },
+  "files": [
+    "src",
+    "assets",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "QUICKSTART.fa.md",
+    "docs/GUIDE.md",
+    "docs/RELEASE-NOTES.md",
+    "build-report.json"
+  ],
+  "description": "Textured particle effects for existing HTML text, images and SVG. Native when still.",
+  "license": "MIT",
+  "author": {
+    "name": "Kamran Baghini",
+    "url": "https://ev-ry.com"
+  },
+  "keywords": [
+    "animation",
+    "particles",
+    "webgl",
+    "text-effects",
+    "image-effects",
+    "scroll-reveal",
+    "svg",
+    "rtl",
+    "ev-ry"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kbaghini/evry-fx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kbaghini/evry-fx/issues"
+  },
+  "homepage": "https://ev-ry.com/fx/"
+}