@ev-ry/fx 0.1.0-rc.1

package/build-report.json

@@ -0,0 +1,328 @@
+{
+  "version": "0.1.0-rc.1",
+  "effects": [
+    "dust-wind",
+    "smoke",
+    "drifting-snow",
+    "melt"
+  ],
+  "files": [
+    {
+      "file": "src/dom-reveal-boot.js",
+      "bytes": 580,
+      "gzip": 353
+    },
+    {
+      "file": "src/dom-free.js",
+      "bytes": 3047,
+      "gzip": 1159
+    },
+    {
+      "file": "src/dom-attachment.js",
+      "bytes": 9834,
+      "gzip": 3001
+    },
+    {
+      "file": "src/dom-reveal.js",
+      "bytes": 6042,
+      "gzip": 2310
+    },
+    {
+      "file": "src/dom-svg-surface.js",
+      "bytes": 4873,
+      "gzip": 1994
+    },
+    {
+      "file": "src/dom-image-surface.js",
+      "bytes": 10611,
+      "gzip": 3666
+    },
+    {
+      "file": "src/image-surface.js",
+      "bytes": 11834,
+      "gzip": 4227
+    },
+    {
+      "file": "src/motion-envelope.js",
+      "bytes": 886,
+      "gzip": 456
+    },
+    {
+      "file": "src/image-source.js",
+      "bytes": 4013,
+      "gzip": 1776
+    },
+    {
+      "file": "src/raster-texture-mesh.js",
+      "bytes": 2592,
+      "gzip": 1150
+    },
+    {
+      "file": "src/raster-texture-material.js",
+      "bytes": 4981,
+      "gzip": 1903
+    },
+    {
+      "file": "src/text-mesh-density.js",
+      "bytes": 2147,
+      "gzip": 1007
+    },
+    {
+      "file": "src/mesh-generator-core.js",
+      "bytes": 8403,
+      "gzip": 3519
+    },
+    {
+      "file": "src/font-mesh-engine.js",
+      "bytes": 19194,
+      "gzip": 5583
+    },
+    {
+      "file": "src/text-direction.js",
+      "bytes": 1057,
+      "gzip": 619
+    },
+    {
+      "file": "assets/vendor/bidi.min.js",
+      "bytes": 11924,
+      "gzip": 5753
+    },
+    {
+      "file": "src/triangle-coverage.js",
+      "bytes": 1211,
+      "gzip": 636
+    },
+    {
+      "file": "src/triangle-effect.js",
+      "bytes": 13694,
+      "gzip": 4287
+    },
+    {
+      "file": "src/particle-centers.js",
+      "bytes": 2936,
+      "gzip": 1069
+    },
+    {
+      "file": "src/text-edit-motions.js",
+      "bytes": 2068,
+      "gzip": 1035
+    },
+    {
+      "file": "src/text-motion-recipes.js",
+      "bytes": 4883,
+      "gzip": 1895
+    },
+    {
+      "file": "src/text-motion-programs.js",
+      "bytes": 3367,
+      "gzip": 897
+    },
+    {
+      "file": "src/text-effect-options.js",
+      "bytes": 2309,
+      "gzip": 1052
+    },
+    {
+      "file": "src/text-effect-path.js",
+      "bytes": 2924,
+      "gzip": 1132
+    },
+    {
+      "file": "src/text-motion-primitives.js",
+      "bytes": 4430,
+      "gzip": 1894
+    },
+    {
+      "file": "src/text-motion-contour.js",
+      "bytes": 1449,
+      "gzip": 666
+    },
+    {
+      "file": "src/triangle-motion-frame.js",
+      "bytes": 2124,
+      "gzip": 870
+    },
+    {
+      "file": "src/dom-image-raster.js",
+      "bytes": 1916,
+      "gzip": 870
+    },
+    {
+      "file": "src/image-preparation-queue.js",
+      "bytes": 1159,
+      "gzip": 573
+    },
+    {
+      "file": "src/dom-image-swap.js",
+      "bytes": 3050,
+      "gzip": 1225
+    },
+    {
+      "file": "src/dom-once.js",
+      "bytes": 3023,
+      "gzip": 1143
+    },
+    {
+      "file": "src/render-owner.js",
+      "bytes": 3954,
+      "gzip": 1456
+    },
+    {
+      "file": "src/viewport-render-owner.js",
+      "bytes": 24414,
+      "gzip": 7399
+    },
+    {
+      "file": "src/viewport-clip.js",
+      "bytes": 6751,
+      "gzip": 2611
+    },
+    {
+      "file": "src/dom-text-surface.js",
+      "bytes": 18914,
+      "gzip": 6011
+    },
+    {
+      "file": "src/hybrid-text-flow.js",
+      "bytes": 3717,
+      "gzip": 1689
+    },
+    {
+      "file": "src/runtime-font-engine.js",
+      "bytes": 12202,
+      "gzip": 3758
+    },
+    {
+      "file": "src/font-rasterizer.js",
+      "bytes": 3539,
+      "gzip": 1322
+    },
+    {
+      "file": "src/native-run-shaping.js",
+      "bytes": 2997,
+      "gzip": 1269
+    },
+    {
+      "file": "src/text-scene.js",
+      "bytes": 13688,
+      "gzip": 3998
+    },
+    {
+      "file": "src/motion.js",
+      "bytes": 1802,
+      "gzip": 691
+    },
+    {
+      "file": "src/text-edit-effect.js",
+      "bytes": 7704,
+      "gzip": 2580
+    },
+    {
+      "file": "src/insertion-range.js",
+      "bytes": 1858,
+      "gzip": 667
+    },
+    {
+      "file": "src/text-motion-character-centers.js",
+      "bytes": 4688,
+      "gzip": 1722
+    },
+    {
+      "file": "src/runtime-lifecycle.js",
+      "bytes": 848,
+      "gzip": 408
+    },
+    {
+      "file": "src/dom-surface-font.js",
+      "bytes": 3246,
+      "gzip": 1251
+    },
+    {
+      "file": "src/dom-raster-cache.js",
+      "bytes": 1677,
+      "gzip": 793
+    },
+    {
+      "file": "src/dom-rich-text.js",
+      "bytes": 11269,
+      "gzip": 4185
+    },
+    {
+      "file": "src/dom-text-runs.js",
+      "bytes": 3091,
+      "gzip": 1371
+    },
+    {
+      "file": "src/dom-text-fingerprint.js",
+      "bytes": 2060,
+      "gzip": 1005
+    },
+    {
+      "file": "src/dom-auto-route.js",
+      "bytes": 1884,
+      "gzip": 751
+    },
+    {
+      "file": "src/dom-auto-reveal.js",
+      "bytes": 3351,
+      "gzip": 1426
+    },
+    {
+      "file": "src/dom-free-script.js",
+      "bytes": 584,
+      "gzip": 357
+    },
+    {
+      "file": "src/dom-free-bootstrap.js",
+      "bytes": 2095,
+      "gzip": 946
+    },
+    {
+      "file": "assets/vendor/three.min.js",
+      "bytes": 651651,
+      "gzip": 162725
+    },
+    {
+      "file": "src/dom-free-loader.js",
+      "bytes": 593,
+      "gzip": 361
+    },
+    {
+      "file": "src/dom-free-loader.d.ts",
+      "bytes": 596,
+      "gzip": 331
+    },
+    {
+      "file": "src/dom-free.d.ts",
+      "bytes": 1259,
+      "gzip": 587
+    },
+    {
+      "file": "src/dom-auto-reveal.d.ts",
+      "bytes": 710,
+      "gzip": 418
+    },
+    {
+      "file": "src/dom-attachment.d.ts",
+      "bytes": 4471,
+      "gzip": 1373
+    },
+    {
+      "file": "assets/vendor/three-LICENSE.txt",
+      "bytes": 1081,
+      "gzip": 666
+    },
+    {
+      "file": "assets/vendor/bidi-LICENSE.txt",
+      "bytes": 1071,
+      "gzip": 650
+    },
+    {
+      "file": "assets/fonts/Estedad-OFL.txt",
+      "bytes": 4388,
+      "gzip": 1971
+    }
+  ],
+  "bytes": 954714,
+  "gzipSum": 274468
+}

package/docs/GUIDE.md

@@ -0,0 +1,125 @@
+<!-- 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.
+
+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.
+
+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.
+
+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)
+
+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.
+
+## Package identity
+
+EV-RY FX uses the package name `@ev-ry/fx`. `THDFree`, `data-thd-*`, the `/thd/` example deployment directory and existing module filenames remain compatible technical identifiers. The deployment directory can be renamed as long as module/asset paths stay intact.

package/docs/RELEASE-NOTES.md

@@ -0,0 +1,40 @@
+# 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)

package/examples/AnimatedTitle.jsx

@@ -0,0 +1,21 @@
+import {useEffect, useRef} from 'react';
+
+// Load /thd/src/dom-free-script.js before mounting React (without data-thd-auto).
+// React owns the element/text; THD owns only its optional presentation.
+export function AnimatedTitle({children = 'Hello EV-RY FX'}) {
+  const element = useRef(null);
+  useEffect(() => {
+    let cancelled = false, owner;
+    const ready = window.THDFree?.ready;
+    if (!ready) { console.error('Load the EV-RY FX Free script before mounting React'); return; }
+    ready.then(async api => {
+      if (cancelled || !element.current) return;
+      owner = api.create(element.current, {auto: false});
+      const surface = owner.attachText(element.current);
+      await surface.ready;
+      if (!cancelled) surface.play('enter');
+    }).catch(console.error);
+    return () => { cancelled = true; owner?.destroy(); };
+  }, [children]);
+  return <h2 ref={element}>{children}</h2>;
+}

package/examples/navigation-away.html

@@ -0,0 +1 @@
+<!doctype html><html lang="fa" dir="rtl"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>بازگشت به آزمون THD</title><style>body{max-width:640px;margin:60px auto;padding:24px;background:#f4f3ee;color:#234a42;font:20px/2 Tahoma,Arial}button{font:inherit;padding:10px 18px;background:white;border:1px solid #8aaba0;border-radius:10px}</style><h1>حالا برگردید</h1><p>با دکمهٔ Back مرورگر، حرکت بازگشت گوشی یا دکمهٔ زیر به صفحهٔ آزمون برگردید. سپس «نمایش عنوان تازه» را امتحان کنید.</p><button onclick="history.back()">بازگشت</button></html>

package/examples/navigation.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="fa" dir="rtl">
+<head>
+  <meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+  <script src="../src/dom-reveal-boot.js"></script>
+  <title>THD — بررسی نهایی روی گوشی</title>
+  <style>
+    *{box-sizing:border-box}body{margin:0;background:#f4f3ee;color:#234a42;font:18px/1.9 Tahoma,Arial}main{max-width:760px;margin:auto;padding:24px}h1{font-size:clamp(30px,7vw,48px);line-height:1.6}h2{font-size:28px}img{display:block;width:100%;height:230px;object-fit:cover;border-radius:18px}a,button{font:inherit;display:inline-block;color:inherit;background:white;border:1px solid #8aaba0;border-radius:10px;padding:9px 16px;text-decoration:none;cursor:pointer}section{padding:40px 0}.space{height:65vh}.note{font-size:15px;color:#526d65}#status{padding:10px 0;min-height:48px}
+  </style>
+</head>
+<body><main>
+  <div data-thd-ignore><strong>بررسی نهایی روی گوشی</strong><p class="note">ابتدا متن و تصویر را ببینید، پایین بروید و برگردید. سپس صفحهٔ دوم را باز کنید و با دکمهٔ Back مرورگر برگردید.</p></div>
+  <h1 data-thd-pending>جزئیات کوچک، حس بهتر</h1>
+  <img data-thd-image data-thd-pending width="640" height="360" alt="طرح سبز و طلایی"
+       src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='640' height='360'%3E%3Crect width='640' height='360' fill='%23476f64'/%3E%3Ccircle cx='320' cy='180' r='115' fill='%23e3bd88'/%3E%3C/svg%3E">
+  <section data-thd-ignore>
+    <a href="navigation-away.html">رفتن به صفحهٔ دوم</a>
+    <button id="add" type="button">نمایش عنوان تازه</button>
+    <p id="status" role="status">در حال آماده‌شدن…</p>
+    <p class="note">بعد از بازگشت، «نمایش عنوان تازه» باید همچنان افکت اجرا کند. عنوان‌های قبلی فقط بار اول افکت دارند.</p>
+  </section>
+  <div id="new-content"></div>
+  <div class="space"></div>
+  <section><h2>ادامهٔ یک تجربهٔ روان</h2><p class="note">اسکرول و تغییر جهت گوشی نباید متن یا تصویر را برای همیشه مخفی کند.</p></section>
+</main>
+<script src="../src/dom-free-script.js" data-thd-auto defer></script>
+<script>
+  let api,sequence=0;
+  function status(){if(api)document.querySelector('#status').textContent=api.instance.stats().disposed?'اتصال غیرفعال است؛ نتیجه را گزارش کنید.':'آمادهٔ آزمون';}
+  window.addEventListener('DOMContentLoaded',async()=>{
+    api=await THDFree.ready;status();
+    document.querySelector('#add').onclick=()=>{
+      const title=document.createElement('h2');title.textContent='عنوان تازه '+(++sequence);title.dataset.thdPending='';document.querySelector('#new-content').replaceChildren(title);
+      api.instance.refresh();title.scrollIntoView({block:'center'});status();
+    };
+  });
+  window.addEventListener('pageshow',()=>queueMicrotask(status));
+</script></body></html>

package/examples/script.html

@@ -0,0 +1,2 @@
+<!doctype html><html lang="fa" dir="rtl"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><script src="../src/dom-reveal-boot.js"></script><title>EV-RY FX Free script example</title><style>body{font:24px Arial;margin:40px}section{margin-top:70vh}</style><h1 data-thd-pending>شروع ساده با THD</h1><section><h2>عنوان بعدی با ورود به دید</h2></section><script src="../src/dom-free-script.js" data-thd-auto defer></script></html>
+

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ev-ry/fx",
+  "version": "0.1.0-rc.1",
+  "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/"
+}