From 1d00bf96e453d1fefaa6d68b33e1f96a61a81861 Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Sun, 16 Mar 2025 10:11:01 +0000
Subject: [PATCH 1/6] Add installation steps, known limitations to README

Also do some formatting, add more links, and fix language issues for existing parts of the README.
---
 README.md | 201 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 160 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index cd3c5db..c9e8cf1 100644
--- a/README.md
+++ b/README.md
@@ -1,84 +1,203 @@
-# Scroll-timeline Polyfill
+# Scroll-timeline Polyfill for Scroll-driven Animations
 
-A polyfill of ScrollTimeline and ViewTimeline as defined by the [spec](https://drafts.csswg.org/scroll-animations-1/).
+A polyfill of ScrollTimeline and ViewTimeline as defined by [the CSS WG spec](https://drafts.csswg.org/scroll-animations-1/).
 
-View a [cool demo showing its usage](https://flackr.github.io/scroll-timeline/demo/parallax/)!
+- [View a cool demo showing its usage.](https://flackr.github.io/scroll-timeline/demo/parallax/)
+- [Track the browser support for native Scroll-driven Animations.](https://caniuse.com/?search=animation-timeline)
 
-# Usage
+When the scroll-driven animations feature is widely available as a native feature, this polyfill may not be necessary except to support older versions of browsers.
 
-To use this polyfill, import the module into your site and you can start creating animations that use a `ScrollTimeline` or `ViewTimeline`.
+## Installation
+
+Use one of these methods to add the polyfill and it should begin working immediately. If it's not working, see the [_Known Limitations_](#known-limitations) section.
+
+### [NPM package](https://www.npmjs.com/package/scroll-timeline-polyfill)
+
+```sh
+npm install scroll-timeline-polyfill
+```
+
+You may also use `pnpm` or `yarn`. Once installed, import it:
 
 ```js
-import 'https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js';
+import "scroll-timeline-polyfill/dist/scroll-timeline.js";
+```
 
-document.getElementById('parallax').animate(
-    { transform: ['translateY(0)', 'translateY(100px)']},
-    { fill: 'both',
-      timeline: new ScrollTimeline({
-        source: document.documentElement,
-      }),
-      rangeStart: new CSSUnitValue(0, 'px'),
-      rangeEnd: new CSSUnitValue(200, 'px'),
-    });
+### JavaScript import (CDN)
+
+```js
+import "https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js";
 ```
 
-Also works with CSS Animations that use a `view-timeline` or `scroll-timeline`
+### HTML script tag (CDN)
 
 ```html
 <script src="https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js"></script>
 ```
 
+## Usage
+
+To use this polyfill, start creating animations using CSS or JavaScript.
+
+### JavaScript usage
+
+Use a `ScrollTimeline` or `ViewTimeline` instance to define animations.
+
+```js
+document.getElementById("parallax").animate(
+  { transform: ["translateY(0)", "translateY(100px)"] },
+  {
+    fill: "both",
+    timeline: new ScrollTimeline({
+      source: document.documentElement,
+    }),
+    rangeStart: new CSSUnitValue(0, "px"),
+    rangeEnd: new CSSUnitValue(200, "px"),
+  }
+);
+```
+
+### CSS usage
+
+Use `animation-timeline` property with `scroll` or `view` to define animations:
+
 ```css
 @keyframes parallax-effect {
-  to { transform: translateY(100px) }
+  to {
+    transform: translateY(100px);
+  }
 }
-#parallax {
+.parallax {
   animation: parallax-effect linear both;
   animation-timeline: scroll(block root);
   animation-range: 0px 200px;
 }
 ```
 
-Please ensure your CSS is hosted on the same domain as your website or included directly on the page within a <style> tag.
+> [!CAUTION]
+> Please ensure your CSS is hosted on the same domain as your website or included directly on the page within a `<style>` tag.
+>
+> If you are loading stylesheets from other origins, the polyfill might not be able to fetch and apply them correctly, due to browser security restrictions.
+
+### More details and Use Cases
+
+- [Animate elements on scroll with Scroll-driven animations](https://developer.chrome.com/articles/scroll-driven-animations/)
+- [Scroll-driven Animations - Demos and Tools](https://scroll-driven-animations.style/)
+
+## Known Limitations
+
+### Safari Feature Flag
+
+In Safari (macOS), a developer feature flag called "Scroll-driven Animations" can be enabled in the Feature Flags panel. (This panel is shown if "Show features for web developers" advanced option is checked.)
+
+This feature flag reports to feature detection that the scroll-driven animations feature is natively available in the browser, effectively disabling the polyfill. However, the developer preview version of the feature doesn't work correctly, causing broken animations.
+
+If this is your case, disable the feature flag and reload your web page. The polyfill will apply the animations.
 
-If you are loading stylesheets from other origins, the polyfill might not be able to fetch and apply them correctly, due to browser security restrictions.
+### Media Query for Reduced Motion
 
-For more details on and use-cases of scroll-driven animations, please refer to [https://developer.chrome.com/articles/scroll-driven-animations/](https://developer.chrome.com/articles/scroll-driven-animations/) and [https://scroll-driven-animations.style/](https://scroll-driven-animations.style/)
+If you wrap the CSS in a media query block to apply it only when reduced motion is not preferred, the polyfill will not be able to process it:
 
-# Contributing
- 
-### 1. Polyfill dev 
+```css
+/* ❌ Don't do this */
+@media (prefers-reduced-motion: no-preference) {
+  .parallax {
+    animation: parallax-effect linear both;
+    animation-timeline: scroll(block root);
+  }
+}
+```
+
+Instead, override the `animation` property when reduced motion is preferred:
 
-Running a dev environment
+```css
+.parallax {
+  animation: parallax-effect linear both;
+  animation-timeline: scroll(block root);
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+```
+
+### Dynamic CSS classes
+
+Using Javascript to dynamically apply CSS classes in order to apply a scroll-driven anmiation will not work with the polyfill.
+
+This is because the polyfill needs to read the static classes and the CSS to track the DOM elements that should have the animations.
+
+Instead, dynamically attach overriding classes to disable the statically applied animation:
+
+```css
+.no-parallax {
+  animation: none !important;
+}
+```
+
+#### Tailwind utility classes
+
+Tailwind v4 brings the power of [utility classes](https://tailwindcss.com/docs/styling-with-utility-classes). However, the polyfill may not work with them since they are a form of dynamic classes.
+
+Instead, use regular CSS classes. You can use CSS features like variables to apply dynamic configurations to the same animation.
+
+```css
+@keyframes parallax-effect {
+  to {
+    transform: translateY(calc(var(--parallax-multiplier, 1) * 100px));
+  }
+}
+
+.parallax-2 {
+  --parallax-multiplier: 2;
+}
+
+.parallax-3 {
+  --parallax-multiplier: 3;
+}
+
+.parallax,
+.parallax-2,
+.parallax-3 {
+  animation: parallax-effect linear both;
+  animation-timeline: scroll(block root);
+}
+```
+
+## Contributing
+
+### 1. Polyfill dev
+
+Run a dev environment:
 
 ```shell script
 npm i
-npm run dev 
+npm run dev
 ```
 
-Then open the browser `http://localhost:3000`, choose one of the demos (test) to see how your changes. 
+Then open `http://localhost:3000` and choose one of the demos (test) to see how your changes apply.
 
 ### 2. Configure & Run Tests
 
-Test configurations are available in: `test/tests.config.json` that file includes:
+Test configurations are available in `test/tests.config.json` which include:
 
-1. polyfillFiles: an array of our JS shim / polyfill files, those will be injected in WPT tests files.
-2. harnessTests: an array of WPT harness tests we want to test the polyfill against.
-3. browsers.local: Browser our local selenium-webdriver will test against
-4. browsers.sauce: Browser our local selenium-webdriver will test against in Saucelabs / CI environment.   
+- `polyfillFiles`: an array of our JS shim / polyfill files, those will be injected in WPT tests files.
+- `harnessTests`: an array of WPT harness tests we want to test the polyfill against.
+- `browsers.local`: Browser our local selenium-webdriver will test against locally.
+- `browsers.sauce`: Browser our local selenium-webdriver will test against in Saucelabs / CI environment.
 
 #### Run the tests locally
 
-Simple test will serve the WPT tests folder and intercepts requests, if the request path matches a harness test we are interested in polyfilling, it will inject the polyfill.
+Simple test will serve the WPT tests folder and intercepts requests. If the request path matches a harness test we are interested in polyfilling, it will inject the polyfill.
 
-*Required environment variables:*
+_Required environment variables:_
 
 ```dotenv
 WPT_DIR=test/wpt #defaults to test/wpt
 WPT_SERVER_PORT=8081 # choose any port available on your machine
 ```
 
-*Command*
+_Command_
 
 ```shell script
 npm run test:simple
@@ -90,16 +209,16 @@ Go to `localhost:8081/scroll-animations/current-time-nan.html` as an example.
 
 ##### Local web driver
 
-*Required environment variables:*
+_Required environment variables:_
 
 ```dotenv
-WPT_DIR=test/wpt #defaults to test/wpt
+WPT_DIR=test/wpt # defaults to test/wpt
 WPT_SERVER_PORT=8081 # choose any port available on your machine
 LOCAL_BROWSER=chrome # choose one of 'chrome', 'edge', 'firefox', 'safari'
 LOCAL_WEBDRIVER_BIN=? #/path/to/webdriver-binaries
 ```
 
-*Command*
+_Command_
 
 ```shell script
 npm run test:wpt
@@ -107,11 +226,11 @@ npm run test:wpt
 
 ##### SauceLabs / CI
 
-*Required environment variables:*
+_Required environment variables:_
 
 ```dotenv
 TEST_ENV=sauce
-WPT_DIR=test/wpt #defaults to test/wpt
+WPT_DIR=test/wpt # defaults to test/wpt
 WPT_SERVER_PORT=8081 # choose any port available on your machine
 SC_TUNNEL_ID=sc-wpt-tunnel # please specify 'sc-wpt-tunnel' as a SauceConnect Proxy Tunnel ID
 
@@ -119,7 +238,7 @@ SAUCE_NAME=<secret> # Your saucelabs account username
 SAUCE_KEY=<secret> # Your API key
 ```
 
-*Command*
+_Command_
 
 ```shell script
 TEST_ENV=sauce npm run test:wpt

From cc7a594fa967558eb4082f22587ceb7f929ce48c Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Sun, 16 Mar 2025 10:36:53 +0000
Subject: [PATCH 2/6] Add "Loading Demos or Running Locally"

---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index c9e8cf1..7777a98 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,13 @@ Use `animation-timeline` property with `scroll` or `view` to define animations:
 
 ## Known Limitations
 
+### Loading Demos or Running Locally
+
+Ensure that the demo project or your project is built and/or served using an HTTP server. For example, you may need to execute `npm run build` and then `npm run dev`. You may also use other methods like a Python3 HTTP server, WAMP server, Nginx or `npx http-server`.
+
+> [!NOTE]
+> You won't be able to use the polyfill if you open the `.html` file directly in a file browser. This is because the polyfill needs to be able to fetch the CSS files in order to read them. The browser doesn't allow this from `file:///` origins as that would allow reading other files from your system.
+
 ### Safari Feature Flag
 
 In Safari (macOS), a developer feature flag called "Scroll-driven Animations" can be enabled in the Feature Flags panel. (This panel is shown if "Show features for web developers" advanced option is checked.)

From fcbbec2e4d2a35087ded00c38319806c3c9a907a Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Sun, 16 Mar 2025 10:40:58 +0000
Subject: [PATCH 3/6] Minor formatting for Safari Feature Flag

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7777a98..ac46edb 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,8 @@ In Safari (macOS), a developer feature flag called "Scroll-driven Animations" ca
 
 This feature flag reports to feature detection that the scroll-driven animations feature is natively available in the browser, effectively disabling the polyfill. However, the developer preview version of the feature doesn't work correctly, causing broken animations.
 
-If this is your case, disable the feature flag and reload your web page. The polyfill will apply the animations.
+> [!IMPORTANT]
+> If this is your case, disable the feature flag and reload your web page. The polyfill will apply the animations.
 
 ### Media Query for Reduced Motion
 

From 2881bf1401ba58cf9016daacaa997783decfb582 Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Sun, 16 Mar 2025 10:47:05 +0000
Subject: [PATCH 4/6] Minor formatting changes

---
 README.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ac46edb..0d6a4ed 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,8 @@ A polyfill of ScrollTimeline and ViewTimeline as defined by [the CSS WG spec](ht
 - [View a cool demo showing its usage.](https://flackr.github.io/scroll-timeline/demo/parallax/)
 - [Track the browser support for native Scroll-driven Animations.](https://caniuse.com/?search=animation-timeline)
 
-When the scroll-driven animations feature is widely available as a native feature, this polyfill may not be necessary except to support older versions of browsers.
+> [!TIP]
+> When the scroll-driven animations feature is widely available as a native feature, this polyfill may not be necessary except to support older versions of browsers.
 
 ## Installation
 
@@ -131,9 +132,7 @@ Instead, override the `animation` property when reduced motion is preferred:
 
 ### Dynamic CSS classes
 
-Using Javascript to dynamically apply CSS classes in order to apply a scroll-driven anmiation will not work with the polyfill.
-
-This is because the polyfill needs to read the static classes and the CSS to track the DOM elements that should have the animations.
+Using Javascript to dynamically apply CSS classes in order to apply a scroll-driven anmiation will not work with the polyfill. This is because the polyfill needs to read the static classes and the CSS to track the DOM elements that should have the animations.
 
 Instead, dynamically attach overriding classes to disable the statically applied animation:
 

From 8340bb60474973d9ff3aa5ec81880838efdc1bb6 Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Wed, 19 Mar 2025 13:48:26 +0000
Subject: [PATCH 5/6] Move dev & test info to CONTRIBUTING.md & improve the
 text

---
 CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++--
 README.md       | 78 +-------------------------------------------
 2 files changed, 84 insertions(+), 80 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 939e534..15dfb55 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,10 +8,10 @@ just a few small guidelines you need to follow.
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution;
 this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+part of the project. Head over to [Google Open Source CLA](https://cla.developers.google.com/)
+to see your current agreements on file or to sign a new one.
 
-You generally only need to submit a CLA once, so if you've already submitted one
+You generally only need to submit a CLA once. So if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 
@@ -26,3 +26,83 @@ information on using pull requests.
 
 This project follows [Google's Open Source Community
 Guidelines](https://opensource.google.com/conduct/).
+
+## Developing & testing your changes
+
+### 1. Polyfill development environment
+
+Run a development environment:
+
+```shell script
+npm i
+npm run dev
+```
+
+Then open `http://localhost:3000` and choose one of the demos (test) to see how your changes apply.
+
+### 2. Configuring & running tests
+
+Test configurations are available in `test/tests.config.json` which include:
+
+- `polyfillFiles`: an array of our JS shim / polyfill files, those will be injected in WPT tests files.
+- `harnessTests`: an array of WPT harness tests we want to test the polyfill against.
+- `browsers.local`: Browser our local selenium-webdriver will test against locally.
+- `browsers.sauce`: Browser our local selenium-webdriver will test against in Saucelabs / CI environment.
+
+#### Run the tests locally
+
+Simple test will serve the WPT tests folder and intercepts requests. If the request path matches a harness test we are interested in polyfilling, it will inject the polyfill.
+
+_Required environment variables:_
+
+```dotenv
+WPT_DIR=test/wpt #defaults to test/wpt
+WPT_SERVER_PORT=8081 # choose any port available on your machine
+```
+
+_Command_
+
+```shell script
+npm run test:simple
+```
+
+Go to `localhost:8081/scroll-animations/current-time-nan.html` as an example.
+
+#### Run the tests via Web Driver
+
+##### Local web driver
+
+_Required environment variables:_
+
+```dotenv
+WPT_DIR=test/wpt # defaults to test/wpt
+WPT_SERVER_PORT=8081 # choose any port available on your machine
+LOCAL_BROWSER=chrome # choose one of 'chrome', 'edge', 'firefox', 'safari'
+LOCAL_WEBDRIVER_BIN=? #/path/to/webdriver-binaries
+```
+
+_Command_
+
+```shell script
+npm run test:wpt
+```
+
+##### SauceLabs / CI
+
+_Required environment variables:_
+
+```dotenv
+TEST_ENV=sauce
+WPT_DIR=test/wpt # defaults to test/wpt
+WPT_SERVER_PORT=8081 # choose any port available on your machine
+SC_TUNNEL_ID=sc-wpt-tunnel # please specify 'sc-wpt-tunnel' as a SauceConnect Proxy Tunnel ID
+
+SAUCE_NAME=<secret> # Your saucelabs account username
+SAUCE_KEY=<secret> # Your API key
+```
+
+_Command_
+
+```shell script
+TEST_ENV=sauce npm run test:wpt
+```
diff --git a/README.md b/README.md
index 0d6a4ed..ee64264 100644
--- a/README.md
+++ b/README.md
@@ -173,80 +173,4 @@ Instead, use regular CSS classes. You can use CSS features like variables to app
 
 ## Contributing
 
-### 1. Polyfill dev
-
-Run a dev environment:
-
-```shell script
-npm i
-npm run dev
-```
-
-Then open `http://localhost:3000` and choose one of the demos (test) to see how your changes apply.
-
-### 2. Configure & Run Tests
-
-Test configurations are available in `test/tests.config.json` which include:
-
-- `polyfillFiles`: an array of our JS shim / polyfill files, those will be injected in WPT tests files.
-- `harnessTests`: an array of WPT harness tests we want to test the polyfill against.
-- `browsers.local`: Browser our local selenium-webdriver will test against locally.
-- `browsers.sauce`: Browser our local selenium-webdriver will test against in Saucelabs / CI environment.
-
-#### Run the tests locally
-
-Simple test will serve the WPT tests folder and intercepts requests. If the request path matches a harness test we are interested in polyfilling, it will inject the polyfill.
-
-_Required environment variables:_
-
-```dotenv
-WPT_DIR=test/wpt #defaults to test/wpt
-WPT_SERVER_PORT=8081 # choose any port available on your machine
-```
-
-_Command_
-
-```shell script
-npm run test:simple
-```
-
-Go to `localhost:8081/scroll-animations/current-time-nan.html` as an example.
-
-#### Run the tests via Web Driver
-
-##### Local web driver
-
-_Required environment variables:_
-
-```dotenv
-WPT_DIR=test/wpt # defaults to test/wpt
-WPT_SERVER_PORT=8081 # choose any port available on your machine
-LOCAL_BROWSER=chrome # choose one of 'chrome', 'edge', 'firefox', 'safari'
-LOCAL_WEBDRIVER_BIN=? #/path/to/webdriver-binaries
-```
-
-_Command_
-
-```shell script
-npm run test:wpt
-```
-
-##### SauceLabs / CI
-
-_Required environment variables:_
-
-```dotenv
-TEST_ENV=sauce
-WPT_DIR=test/wpt # defaults to test/wpt
-WPT_SERVER_PORT=8081 # choose any port available on your machine
-SC_TUNNEL_ID=sc-wpt-tunnel # please specify 'sc-wpt-tunnel' as a SauceConnect Proxy Tunnel ID
-
-SAUCE_NAME=<secret> # Your saucelabs account username
-SAUCE_KEY=<secret> # Your API key
-```
-
-_Command_
-
-```shell script
-TEST_ENV=sauce npm run test:wpt
-```
+Thank you for choosing to contribute to this project. Please see our [contribution guidelines](/CONTRIBUTING.md) to learn how you can help.

From d74a94b5e791bc0d0d81d9b3cbd672b7c638ff4b Mon Sep 17 00:00:00 2001
From: ADTC <send2adtc@gmail.com>
Date: Wed, 19 Mar 2025 13:56:09 +0000
Subject: [PATCH 6/6] Write a better blurb in the Contributing section

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ee64264..652bba8 100644
--- a/README.md
+++ b/README.md
@@ -173,4 +173,10 @@ Instead, use regular CSS classes. You can use CSS features like variables to app
 
 ## Contributing
 
-Thank you for choosing to contribute to this project. Please see our [contribution guidelines](/CONTRIBUTING.md) to learn how you can help.
+Thank you for choosing to contribute fixes and improvements to our project.
+
+Please see our [contribution guidelines](/CONTRIBUTING.md) page to:
+- Sign the Contributor License Agreement.
+- Understand the code review process.
+- Read the open source community guidelines.
+- Learn how to develop and test your changes.