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

package/build-report.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-rc.1",
+  "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": 11834,
-      "gzip": 4227
+      "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",
@@ -144,8 +144,8 @@
     },
     {
       "file": "src/dom-image-raster.js",
-      "bytes": 1916,
-      "gzip": 870
+      "bytes": 3273,
+      "gzip": 1287
     },
     {
       "file": "src/image-preparation-queue.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": 18914,
-      "gzip": 6011
+      "bytes": 22552,
+      "gzip": 7092
     },
     {
       "file": "src/hybrid-text-flow.js",
@@ -194,8 +194,8 @@
     },
     {
       "file": "src/font-rasterizer.js",
-      "bytes": 3539,
-      "gzip": 1322
+      "bytes": 4384,
+      "gzip": 1544
     },
     {
       "file": "src/native-run-shaping.js",
@@ -204,8 +204,8 @@
     },
     {
       "file": "src/text-scene.js",
-      "bytes": 13688,
-      "gzip": 3998
+      "bytes": 13840,
+      "gzip": 4007
     },
     {
       "file": "src/motion.js",
@@ -234,8 +234,8 @@
     },
     {
       "file": "src/dom-surface-font.js",
-      "bytes": 3246,
-      "gzip": 1251
+      "bytes": 3475,
+      "gzip": 1315
     },
     {
       "file": "src/dom-raster-cache.js",
@@ -244,8 +244,8 @@
     },
     {
       "file": "src/dom-rich-text.js",
-      "bytes": 11269,
-      "gzip": 4185
+      "bytes": 12881,
+      "gzip": 4613
     },
     {
       "file": "src/dom-text-runs.js",
@@ -254,8 +254,13 @@
     },
     {
       "file": "src/dom-text-fingerprint.js",
-      "bytes": 2060,
-      "gzip": 1005
+      "bytes": 2103,
+      "gzip": 1021
+    },
+    {
+      "file": "src/dom-text-paint-mask.js",
+      "bytes": 1469,
+      "gzip": 644
     },
     {
       "file": "src/dom-auto-route.js",
@@ -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": 954714,
-  "gzipSum": 274468
+  "bytes": 974292,
+  "gzipSum": 280473
 }

package/docs/GUIDE.md

@@ -1,124 +1,134 @@
 <!-- Generated by scripts/prepare-free-release.cjs from FREE-PACKAGE.md. -->
-# EV-RY FX Free — integration guide
-
-Four fixed behaviors: text enters with wind and exits as smoke; images enter as snow and exit with melt. Triangle particles, 2000ms, native resting. Existing native semantics remain with the host. SVG/icon attachment and simple image swaps are included with the image presets. Editable controls and other effect recipes remain outside this build. Shared text shaping and rendering utilities remain where required by display text.
-
-## Script
-
-Serve this directory intact at `/thd/`:
-
-```html
-<script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
-```
-
-The loader uses existing window.THREE or loads the accompanying r158 asset. After the script executes, await `THDFree.ready`; its `instance` is the automatic installation. Without data-thd-auto, call `(await THDFree.ready).create(document, options)` explicitly. This is a script entry with accompanying modules/assets, not a single-file bundle.
-
-## Modules
-
-```js
-import {createFree} from '@ev-ry/fx';
-const free = createFree(THREE, document, {auto: false});
-const text = free.attachText(document.querySelector('.title'));
-await text.ready;
-text.play('exit');
-// free.destroy() on page/component unmount.
-```
-
-Provide a compatible THREE namespace; r158 is the version tested here. The package import itself has no page side effects. Copy the assets directory with its relative paths if your bundler does not preserve new URL assets.
-
-For explicit initialization from an ES module, use the separate loader entry:
-
-```js
-import * as THREE from 'three'; // r158 is the tested version.
-import {loadFree} from '@ev-ry/fx/script';
-const api = await loadFree({THREE, auto: true});
-// api.instance is the automatic installation.
-```
-
-Importing this entry is inert, including during server-side rendering. Call `loadFree()` only in the browser after mounting the document. Without an injected THREE namespace it reuses `window.THREE` or loads the accompanying asset; keep that asset reachable when bundling. Repeated calls reuse the first `THDFree.ready`, so the first initialization chooses `auto`. For manual ownership, use `auto:false` then `api.create(root, options)`. Loaders do not silently start a second automatic installation.
-
-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.
-
+# EV-RY FX Free — integration guide
+
+Four fixed behaviors: text enters with wind and exits as smoke; images enter as snow and exit with melt. Triangle particles, 2000ms, native resting. Existing native semantics remain with the host. SVG/icon attachment and simple image swaps are included with the image presets. Editable controls and other effect recipes remain outside this build. Shared text shaping and rendering utilities remain where required by display text.
+
+## Script
+
+Serve this directory intact at `/thd/`:
+
+```html
+<script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
+```
+
+The loader uses existing window.THREE or loads the accompanying r158 asset. After the script executes, await `THDFree.ready`; its `instance` is the automatic installation. Without data-thd-auto, call `(await THDFree.ready).create(document, options)` explicitly. This is a script entry with accompanying modules/assets, not a single-file bundle.
+
+## Modules
+
+```js
+import {createFree} from '@ev-ry/fx';
+const free = createFree(THREE, document, {auto: false});
+const text = free.attachText(document.querySelector('.title'));
+await text.ready;
+text.play('exit');
+// free.destroy() on page/component unmount.
+```
+
+Provide a compatible THREE namespace; r158 is the version tested here. The package import itself has no page side effects. Copy the assets directory with its relative paths if your bundler does not preserve new URL assets.
+
+For explicit initialization from an ES module, use the separate loader entry:
+
+```js
+import * as THREE from 'three'; // r158 is the tested version.
+import {loadFree} from '@ev-ry/fx/script';
+const api = await loadFree({THREE, auto: true});
+// api.instance is the automatic installation.
+```
+
+Importing this entry is inert, including during server-side rendering. Call `loadFree()` only in the browser after mounting the document. Without an injected THREE namespace it reuses `window.THREE` or loads the accompanying asset; keep that asset reachable when bundling. Repeated calls reuse the first `THDFree.ready`, so the first initialization chooses `auto`. For manual ownership, use `auto:false` then `api.create(root, options)`. Loaders do not silently start a second automatic installation.
+
+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.
 
-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.
-
-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.
-
-Unchanged text reuses validated layout and document-scoped raster pixels. The retained shared pixel cache is bounded at 16MiB; active geometry, textures and referenced pixels are separate, so this is not a total memory limit. Font loading invalidates cached pixels. Unsupported text is shown natively without repeated preparation retries; correct its layout and call `refresh()` to retry. Always destroy attachments on unmount.
-
-## First-paint setup: avoid an initial flash
-
-Load the small boot script synchronously in the head, before body content (no async/defer). Keep the main loader deferred:
-
-```html
-<head>
-  <script src="/thd/src/dom-reveal-boot.js"></script>
-  <script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
-</head>
-<body>
-  <h1 data-thd-pending>Hello EV-RY FX</h1>
-  <img data-thd-image data-thd-pending src="photo.jpg"
-       width="640" height="400" alt="A descriptive caption">
-</body>
-```
-
-`data-thd-pending` only requests initial masking; it does not select or attach an element. Use it on targets that will actually receive entry effects. The mask preserves layout and transfers to the reveal controller during attachment. Never edit the controller-owned `data-thd-reveal` attribute. Specify image dimensions or aspect-ratio to prevent loading-related layout shifts.
-
-Without JavaScript the boot mask is never installed. If the engine fails to load, `thd:error` releases the boot mask; an eight-second timer from boot execution also releases unclaimed masks. This timer is a failure fallback, not an animation delay. Late initialization after that timeout cannot guarantee flash-free entry. Once attached, the reveal controller owns its own preparation/error handling. A late-loaded boot script cannot undo an earlier paint. Sites with a restrictive CSP must allow the boot script and its injected style; otherwise omit pre-masking or integrate an equivalent permitted policy.
-
-## Reveal, replay and component lifecycle
-
-Automatic reveal defaults to `threshold:0` and `once:true`. Threshold is visible area ratio: `0` means a positive intersection, `.5` half, `1` full visibility; an element larger than the viewport may never reach `1`.
-
-```js
-const free = (await THDFree.ready).create(document, {
-  once: false, threshold: 0.5
-}); // Load the script WITHOUT data-thd-auto for this manual setup.
-```
-
-With `once:false`, a full exit rearms the target and hides it immediately; it does not play the exit effect. Small scroll changes while still intersecting do not rearm. Reentry during unfinished entry resumes the timeline; reentry after completion starts a new entry. Explicit `surface.play('enter')` is a replay request. Use `surface.play('exit')` for animated disappearance.
-
-Do not attach manually to an automatically selected element. Use `auto:false` for fully manual ownership, or exclude manual targets from the automatic selectors. Call `free.refresh()` after adding/removing targets; discovery is not a blanket DOM mutation watcher. Destroy the surface or installation on component unmount. In React, initialize after the host exists and return cleanup from the effect; see `examples/AnimatedTitle.jsx`. Its children are a string, not an arbitrary React subtree adapter.
-
-Automatic loader installations survive a persisted `pagehide`/`pageshow` round trip (the browser's back/forward cache). Return refreshes the same owner and preserves completed once-only entries; a non-persisted page exit releases it. A manually destroyed installation is never revived. For installations created with `api.create()` or `createFree()`, lifecycle belongs to the host: avoid destroying solely for `pagehide` when `event.persisted` is true, refresh on persisted return, and still destroy on actual component unmount.
-
-## Troubleshooting
-
-Plain headings that wrap across lines use the existing DOM-measured multi-line text path automatically. A line break caused by available width alone does not require nested spans or a smaller font to animate. Unsupported typography can still retain native fallback.
+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.
 
-Normal/nowrap HTML whitespace is collapsed for raster text while DOM source offsets are preserved. NBSP and preformatted spacing are not globally trimmed. An initially empty manually attached target can reveal after content arrives; a recoverable unsupported layout can reveal after correction and refresh. Automatic scanning still requires `free.refresh()` to discover a previously empty, unattached target. Recovery does not replay an already completed once-only entry.
-
-| Symptom | Check |
-| --- | --- |
-| Initial flash | Boot script precedes body paint; target has `data-thd-pending`; no async/defer on boot. |
-| Target stays hidden until fallback | Target matches an attachment selector and is not inside an excluded region. |
-| No entry at full visibility threshold | Target fits inside the intersection root; try a smaller threshold. |
-| Image stays native | Inspect CORS restrictions, image loading and supported CSS; native fallback is intentional. |
-| Effect appears above an unrelated layer | Review zIndex and presentation routing; try local presentation for that target. |
-| Duplicate work after navigation | Destroy old owners, avoid simultaneous auto/manual attachment, then refresh new targets. |
-
-See [the Persian quickstart](../QUICKSTART.fa.md), [script example](../examples/script.html) and [phone/history check](../examples/navigation.html). Serve examples over HTTP. The boot helper applies to manual reveal attachment as well; the main loader is not required when using the module API.
-
-Build specialization strips unused attachment entry points and effect graphs, with assertions that fail on incompatible source changes. It is not source protection: browser code is inspectable. This Free distribution is MIT licensed; see ../LICENSE and ../NOTICE.md. Third-party notices retain their original terms. The private full-product source and unpublished Pro code are outside this distribution.
+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.
 
-## Media additions
-
-attachSVG(svg, options) uses snow/melt and native resting, supporting the existing static path/shape SVG subset. Unsupported filters, masks, use, embedded text/images and external paint references retain native fallback. This is not arbitrary SVG support.
-
-swapImage(previous, next, {exit:true, waitForExit:false, presentation:'global'}) returns {finished,cancel}. Both images must be unattached. Entry uses snow; optional exit uses melt. waitForExit sequences them. Arbitrary effect selection stays unavailable. The next image takes the previous image's placement on success; previous is hidden. These APIs reuse the main engine.
+`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.
+
+Unchanged text reuses validated layout and document-scoped raster pixels. The retained shared pixel cache is bounded at 16MiB; active geometry, textures and referenced pixels are separate, so this is not a total memory limit. Font loading invalidates cached pixels. Unsupported text is shown natively without repeated preparation retries; correct its layout and call `refresh()` to retry. Always destroy attachments on unmount.
+
+## First-paint setup: avoid an initial flash
+
+Load the small boot script synchronously in the head, before body content (no async/defer). Keep the main loader deferred:
+
+```html
+<head>
+  <script src="/thd/src/dom-reveal-boot.js"></script>
+  <script src="/thd/src/dom-free-script.js" data-thd-auto defer></script>
+</head>
+<body>
+  <h1 data-thd-pending>Hello EV-RY FX</h1>
+  <img data-thd-image data-thd-pending src="photo.jpg"
+       width="640" height="400" alt="A descriptive caption">
+</body>
+```
+
+`data-thd-pending` only requests initial masking; it does not select or attach an element. Use it on targets that will actually receive entry effects. The mask preserves layout and transfers to the reveal controller during attachment. Never edit the controller-owned `data-thd-reveal` attribute. Specify image dimensions or aspect-ratio to prevent loading-related layout shifts.
+
+Without JavaScript the boot mask is never installed. If the engine fails to load, `thd:error` releases the boot mask; an eight-second timer from boot execution also releases unclaimed masks. This timer is a failure fallback, not an animation delay. Late initialization after that timeout cannot guarantee flash-free entry. Once attached, the reveal controller owns its own preparation/error handling. A late-loaded boot script cannot undo an earlier paint. Sites with a restrictive CSP must allow the boot script and its injected style; otherwise omit pre-masking or integrate an equivalent permitted policy.
+
+## Reveal, replay and component lifecycle
+
+Automatic reveal defaults to `threshold:0` and `once:true`. Threshold is visible area ratio: `0` means a positive intersection, `.5` half, `1` full visibility; an element larger than the viewport may never reach `1`.
+
+```js
+const free = (await THDFree.ready).create(document, {
+  once: false, threshold: 0.5
+}); // Load the script WITHOUT data-thd-auto for this manual setup.
+```
+
+With `once:false`, a full exit rearms the target and hides it immediately; it does not play the exit effect. Small scroll changes while still intersecting do not rearm. Reentry during unfinished entry resumes the timeline; reentry after completion starts a new entry. Explicit `surface.play('enter')` is a replay request. Use `surface.play('exit')` for animated disappearance.
+
+Do not attach manually to an automatically selected element. Use `auto:false` for fully manual ownership, or exclude manual targets from the automatic selectors. Call `free.refresh()` after adding/removing targets; discovery is not a blanket DOM mutation watcher. Destroy the surface or installation on component unmount. In React, initialize after the host exists and return cleanup from the effect; see `examples/AnimatedTitle.jsx`. Its children are a string, not an arbitrary React subtree adapter.
+
+Automatic loader installations survive a persisted `pagehide`/`pageshow` round trip (the browser's back/forward cache). Return refreshes the same owner and preserves completed once-only entries; a non-persisted page exit releases it. A manually destroyed installation is never revived. For installations created with `api.create()` or `createFree()`, lifecycle belongs to the host: avoid destroying solely for `pagehide` when `event.persisted` is true, refresh on persisted return, and still destroy on actual component unmount.
+
+## Troubleshooting
+
+Plain headings that wrap across lines use the existing DOM-measured multi-line text path automatically. A line break caused by available width alone does not require nested spans or a smaller font to animate. Unsupported typography can still retain native fallback.
+
+Normal/nowrap HTML whitespace is collapsed for raster text while DOM source offsets are preserved. NBSP and preformatted spacing are not globally trimmed. An initially empty manually attached target can reveal after content arrives; a recoverable unsupported layout can reveal after correction and refresh. Automatic scanning still requires `free.refresh()` to discover a previously empty, unattached target. Recovery does not replay an already completed once-only entry.
+
+| Symptom | Check |
+| --- | --- |
+| Initial flash | Boot script precedes body paint; target has `data-thd-pending`; no async/defer on boot. |
+| Target stays hidden until fallback | Target matches an attachment selector and is not inside an excluded region. |
+| No entry at full visibility threshold | Target fits inside the intersection root; try a smaller threshold. |
+| Image stays native | Inspect CORS restrictions, image loading and supported CSS; native fallback is intentional. |
+| Effect appears above an unrelated layer | Review zIndex and presentation routing; try local presentation for that target. |
+| Duplicate work after navigation | Destroy old owners, avoid simultaneous auto/manual attachment, then refresh new targets. |
+
+See [the Persian quickstart](../QUICKSTART.fa.md), [script example](../examples/script.html) and [phone/history check](../examples/navigation.html). Serve examples over HTTP. The boot helper applies to manual reveal attachment as well; the main loader is not required when using the module API.
+
+Build specialization strips unused attachment entry points and effect graphs, with assertions that fail on incompatible source changes. It is not source protection: browser code is inspectable. This Free distribution is MIT licensed; see ../LICENSE and ../NOTICE.md. Third-party notices retain their original terms. The private full-product source and unpublished Pro code are outside this distribution.
+
+
+## Media additions
+
+attachSVG(svg, options) uses snow/melt and native resting, supporting the existing static path/shape SVG subset. Unsupported filters, masks, use, embedded text/images and external paint references retain native fallback. This is not arbitrary SVG support.
+
+swapImage(previous, next, {exit:true, waitForExit:false, presentation:'global'}) returns {finished,cancel}. Both images must be unattached. Entry uses snow; optional exit uses melt. waitForExit sequences them. Arbitrary effect selection stays unavailable. The next image takes the previous image's placement on success; previous is hidden. These APIs reuse the main engine.
+
+
+### Native image shape and layering
+
+Free global canvas defaults to zIndex:1; createFree accepts zIndex to fit the host's layer convention. A header at z-index 20 now stays above the effect. This is an explicit shared-layer policy, not automatic reconstruction of arbitrary stacking contexts.
 
-
-### Native image shape and layering
-
-Free global canvas defaults to zIndex:1; createFree accepts zIndex to fit the host's layer convention. A header at z-index 20 now stays above the effect. This is an explicit shared-layer policy, not automatic reconstruction of arbitrary stacking contexts.
-
 DOM images are rasterized from their displayed box before meshing, applying supported centered object-fit fill/contain/cover and elliptical/percentage corner radii. The alpha mask travels with particles instead of appearing only on native handoff. Changes in size/fit/radii rebuild that raster. This adds preparation work. Tainted canvas/unsupported layouts retain native fallback. Borders, shadows, arbitrary CSS clipping and complete screenshot equivalence are not claimed.
-
-### Default shared canvas (2026-09-14)
-
+
+### Default shared canvas (2026-09-14)
+
 createFree defaults to auto routing with documentCanvas:true. Ordinary page effects use the bounded document-connected shared canvas; nested scroll containers, fixed/sticky content and explicit positioned stacking contexts route conservatively to local presentation. Force local with presentation:'local'; select legacy fixed shared rendering with presentation:'global',documentCanvas:false. experimentalDocumentCanvas is retained as a compatibility alias. Dialog-root rendering is unchanged. This is not general CSS stacking equivalence.
+
+## Native text handoff
+
+Display text returns to native paint with a 350ms transition. Native text begins fading in 175ms before the entry timeline ends; mesh fade-out starts at the end. Allow preparation plus the 2000ms effect plus 350ms when observing completion; do not destroy a surface on a fixed 2000ms timer. Reduced-motion users bypass the handoff. Unsupported typography still falls back to native immediately.
 
 ## Package identity
 

package/docs/RELEASE-NOTES.md

@@ -1,40 +1,75 @@
-# EV-RY FX Free 0.1.0-rc.1
+# EV-RY FX Free 0.1.0-rc.3
 
-Public preview release candidate from EV-RY. The Free edition uses the [MIT license](../LICENSE). Package: `@ev-ry/fx`. Try the [live demo](https://kbaghini.github.io/evry-fx/docs/) or browse the [source and examples](https://github.com/kbaghini/evry-fx).
-
-The product is now EV-RY FX. Existing `THDFree`, `data-thd-*`, `createFree`, `loadFree` and `src/dom-*` names remain compatible. No behavior or API rename is implied by the branding change.
-
-## Included
-
-- Automatic intersection reveal for headings, marked display text and marked images.
-- Manual text, image and supported static SVG attachment, plus simple image swaps.
-- Four fixed presets: dust wind / smoke for text, drifting snow / melt for media. Textured triangular particles, a 2000ms timeline and native resting presentation.
-- Classic script loading, explicit `loadFree()` ES-module initialization, TypeScript declarations and integration examples.
-- Document-connected shared canvas with conservative local routing for special layouts.
-
-## Reliability work
-
-- Early opt-in masking prevents native content flashing before initial reveal, while preserving layout and providing failure recovery.
-- Wrapped headings and ordinary HTML whitespace use browser-measured placement. Initially empty or recoverable unsupported text can resume after valid content/layout and refresh.
-- Reentry during an unfinished reveal preserves its clock. Completed once-only entries are not restarted by minor scrolling or presentation updates.
-- Unsupported content returns to native rendering instead of repeatedly retrying known failures. Repeated local refresh preserves valid attachments.
-- Font loading invalidates shared pixels and refreshes rich-text meshes even when the CSS font name and line metrics stay unchanged.
-- Automatic loader ownership handles browser back/forward-cache returns; manual owners retain explicit lifecycle responsibility.
-- `FreeSurface.cancel()` is required in the declarations, matching the runtime API. The module loader has its own typed export.
-
-## Performance work
-
-- Validated, unchanged text reuses its layout before the expensive per-character placement pass. Character-frame data is collected only when the selected entry/exit effect needs it.
-- Display-text raster pixels use a document-scoped cache capped at 16MiB. This is a cache limit, not total page or GPU memory.
-- Offscreen images prepare near the viewport. Internal image preparation avoids an intermediate PNG encode/decode, and rapid resize requests are coalesced.
-- Geometry settings, visual quality, preset choices and effect duration are preserved. These changes remove redundant work; they do not promise a universal FPS improvement or eliminate all cold WebGL startup cost.
-
-## Validation and limits
-
-Chrome desktop regression checks cover actual entry/exit motion, rapid reentry, plain/rich text rebuilding, whitespace and Persian mixed-text cases, fallback recovery, lifecycle cleanup and cache invalidation. Strict TypeScript consumer checks cover source and packaged declarations, cancellation, module-loader exports and rejected Free-only configuration.
-
-Earlier document-canvas scrolling tests on physical iPhone and Android devices were reported successful by the user. That is not fresh physical-device acceptance of every optimization in this candidate, nor a guarantee for all browsers, GPUs or websites.
-
-The Free build retains native fallback for unsupported content. Complete CSS stacking/clipping reproduction, arbitrary SVG, editable controls, custom effect recipes and dedicated framework component packs are outside this release. Cross-origin media must satisfy browser canvas restrictions. Review the [guide](GUIDE.md) before integration.
-
-[Back to the overview](../README.md)
+- 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.
+- Respect DOM font kerning and text-rendering settings; include them in cache identity and invalidation.
+- Normalize high-resolution raster advances using the actual display font size. Physical iOS width parity remains to be confirmed.
+- Smooth native-rest handoff: native text fades in over 350ms starting 175ms before entry ends; the mesh fades out over the following 350ms. Reduced motion skips this transition.
+- Tie the handoff to the original effect clock to avoid restarting on delayed frames.
+
+No Free API removal or effect expansion. The marketing site's SPA router, loader and staged headlines are site behavior, not package exports.
+
+## Previous release
+
+# EV-RY FX Free 0.1.0-rc.1
+
+Public preview release candidate from EV-RY. The Free edition uses the [MIT license](../LICENSE). Package: `@ev-ry/fx`. Try the [live demo](https://kbaghini.github.io/evry-fx/docs/) or browse the [source and examples](https://github.com/kbaghini/evry-fx).
+
+The product is now EV-RY FX. Existing `THDFree`, `data-thd-*`, `createFree`, `loadFree` and `src/dom-*` names remain compatible. No behavior or API rename is implied by the branding change.
+
+## Included
+
+- Automatic intersection reveal for headings, marked display text and marked images.
+- Manual text, image and supported static SVG attachment, plus simple image swaps.
+- Four fixed presets: dust wind / smoke for text, drifting snow / melt for media. Textured triangular particles, a 2000ms timeline and native resting presentation.
+- Classic script loading, explicit `loadFree()` ES-module initialization, TypeScript declarations and integration examples.
+- Document-connected shared canvas with conservative local routing for special layouts.
+
+## Reliability work
+
+- Early opt-in masking prevents native content flashing before initial reveal, while preserving layout and providing failure recovery.
+- Wrapped headings and ordinary HTML whitespace use browser-measured placement. Initially empty or recoverable unsupported text can resume after valid content/layout and refresh.
+- Reentry during an unfinished reveal preserves its clock. Completed once-only entries are not restarted by minor scrolling or presentation updates.
+- Unsupported content returns to native rendering instead of repeatedly retrying known failures. Repeated local refresh preserves valid attachments.
+- Font loading invalidates shared pixels and refreshes rich-text meshes even when the CSS font name and line metrics stay unchanged.
+- Automatic loader ownership handles browser back/forward-cache returns; manual owners retain explicit lifecycle responsibility.
+- `FreeSurface.cancel()` is required in the declarations, matching the runtime API. The module loader has its own typed export.
+
+## Performance work
+
+- Validated, unchanged text reuses its layout before the expensive per-character placement pass. Character-frame data is collected only when the selected entry/exit effect needs it.
+- Display-text raster pixels use a document-scoped cache capped at 16MiB. This is a cache limit, not total page or GPU memory.
+- Offscreen images prepare near the viewport. Internal image preparation avoids an intermediate PNG encode/decode, and rapid resize requests are coalesced.
+- Geometry settings, visual quality, preset choices and effect duration are preserved. These changes remove redundant work; they do not promise a universal FPS improvement or eliminate all cold WebGL startup cost.
+
+## Validation and limits
+
+Chrome desktop regression checks cover actual entry/exit motion, rapid reentry, plain/rich text rebuilding, whitespace and Persian mixed-text cases, fallback recovery, lifecycle cleanup and cache invalidation. Strict TypeScript consumer checks cover source and packaged declarations, cancellation, module-loader exports and rejected Free-only configuration.
+
+Earlier document-canvas scrolling tests on physical iPhone and Android devices were reported successful by the user. That is not fresh physical-device acceptance of every optimization in this candidate, nor a guarantee for all browsers, GPUs or websites.
+
+The Free build retains native fallback for unsupported content. Complete CSS stacking/clipping reproduction, arbitrary SVG, editable controls, custom effect recipes and dedicated framework component packs are outside this release. Cross-origin media must satisfy browser canvas restrictions. Review the [guide](GUIDE.md) before integration.
+
+[Back to the overview](../README.md)