### Install Dependencies for Development

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Install project dependencies using npm. This is the first step for setting up a local development environment.

```shell
npm i
npm run dev 

```

--------------------------------

### Programmatic Installation with initPolyfill()

Source: https://context7.com/flackr/scroll-timeline/llms.txt

For module-based builds or lazy loading, use `initPolyfill()` to manually install the polyfill. This function registers ScrollTimeline, ViewTimeline, Animation, and related methods on the window object. It checks for native support and no-ops if ViewTimeline is already available.

```javascript
import { initPolyfill } from 'scroll-timeline-polyfill/src/init-polyfill.js';

// Installs ScrollTimeline, ViewTimeline, Animation, element.animate,
// element.getAnimations, and document.getAnimations on window.
// No-ops if the browser already supports ViewTimeline natively.
initPolyfill();

// Now safe to use the APIs
const tl = new ScrollTimeline({ axis: 'block' });
document.querySelector('.hero').animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { timeline: tl, fill: 'both' }
);
```

--------------------------------

### Basic CSS Setup for Scroll-Timeline

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/basic/css.html

Sets up basic page height and a fixed element. This is the foundational CSS for the scroll-timeline demo.

```css
body { height: 2000px; padding-top: 200px; } #test { display: block; width: 100px; height: 100px; background: green; position: fixed; top: 0; } #container { position: absolute; top: 400px; height: 200px; width: 200px; background: blue; }
```

--------------------------------

### Shorthand contraction examples

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

These examples illustrate the shorthand contraction of 'scroll-timeline-name' and 'scroll-timeline-axis' properties, showing how multiple named timelines and their orientations are represented concisely.

```css
Shorthand contraction of scroll-timeline-name:--abc:undefined;scroll-timeline-axis:inline:undefined
```

```css
Shorthand contraction of scroll-timeline-name:--a, --b:undefined;scroll-timeline-axis:inline, block:undefined
```

--------------------------------

### CSS Keyframes and Animation Setup

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/basic/anonymous-scroll-timeline-animation-shorthand.html

Defines keyframe animations for movement, color, width, and outline changes. Applies these animations to `#box_one` with different scroll timelines.

```css
@keyframes move {
  to { transform: translateX(350px) translateY(2000px); }
}

@keyframes colorChange {
  from { background: red; }
  to { background: blue; }
}

@keyframes widthChange {
  from { width: 100px; }
  to { width: 120px; }
}

@keyframes outlineChange {
  from { outline: 0px solid lime; }
  to { outline: 10px solid lime; }
}

#box_one {
  width: 100px;
  height: 100px;
  background-color: green;
  overflow-y: scroll;
  animation: linear colorChange both, linear widthChange both, move linear, linear outlineChange both;
  animation-timeline: scroll(root), auto, scroll(nearest y), scroll(self y);
}

.content {
  height: 400px;
}

.spacer {
  width: 100%;
  height: 2000px;
}

#container {
  width: 500px;
  height: 500px;
  background-color:beige;
  overflow: auto;
}

body {
  height: 1000px;
}
```

--------------------------------

### Progress Bar Animation with Mixed Shorthand and Longhands

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Demonstrates using `animation-range` with `animation-delay` and `animation-end-delay` to control animation timing relative to scroll events. This example uses 'entry' and 'contain' for delays.

```css
#progress-bar-progress-g { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; /* mixed shorthand and longhands */ animation-range: entry; animation-delay: cover; animation-end-delay: contain; }
```

--------------------------------

### ViewTimeline Constructor Examples

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Create a ViewTimeline instance to track an element's progress through the viewport. Use `subject` to specify the element, and `inset` to define the viewport margins. The `rangeStart` and `rangeEnd` options control when the animation begins and finishes relative to the subject's visibility.

```javascript
const subject = document.getElementById('card');

const viewTimeline = new ViewTimeline({
  subject,
  axis: 'block',
  inset: '50px',
});

// Fade in while the card enters the viewport
subject.animate(
  [{ opacity: 0, transform: 'translateY(40px)' },
   { opacity: 1, transform: 'translateY(0)' }],
  {
    fill: 'both',
    timeline: viewTimeline,
    rangeStart: 'entry 0%',
    rangeEnd:   'entry 100%',
  }
);

console.log(viewTimeline.subject);
console.log(viewTimeline.startOffset);
console.log(viewTimeline.endOffset);
console.log(viewTimeline.currentTime);
```

--------------------------------

### Element.prototype.animate() with Scroll/View Timelines

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Demonstrates how to use the overridden Element.prototype.animate method to create animations tied to scroll or view timelines. It shows examples for parallax effects and revealing content.

```APIDOC
## `element.animate()` with Scroll/View Timeline

The polyfill overrides `Element.prototype.animate` to accept `timeline`, `rangeStart`, and `rangeEnd` options, returning a `ProxyAnimation` that mirrors the full Web Animations API.

```js
// Parallax translateY driven by root scroll
const parallax = document.getElementById('parallax');
const anim = parallax.animate(
  { transform: ['translateY(0)', 'translateY(200px)'] },
  {
    fill: 'both',
    timeline: new ScrollTimeline({ source: document.scrollingElement }),
    rangeStart: new CSSUnitValue(0, 'px'),
    rangeEnd:   new CSSUnitValue(400, 'px'),
  }
);

// ViewTimeline with named range bounds (JS objects or strings both work)
const card = document.getElementById('card');
const reveal = card.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  {
    fill: 'both',
    timeline: new ViewTimeline({ subject: card }),
    rangeStart: { rangeName: 'entry', offset: CSS.percent(0) },
    rangeEnd:   { rangeName: 'entry', offset: CSS.percent(100) },
  }
);

// ProxyAnimation API — same as native Animation
console.log(reveal.playState);   // 'running'
reveal.pause();
console.log(reveal.playState);   // 'paused'
reveal.play();
reveal.finished.then(() => console.log('animation complete'));
```
```

--------------------------------

### Set multiple CSS animations using shorthand

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

This example shows how to define multiple animations using the 'animation' shorthand property, separated by commas. It sets various animation sub-properties for each animation.

```css
e.style['animation'] = "1s linear 1s 2 reverse forwards paused anim1,
   1s linear 1s 2 reverse forwards paused anim2,
   1s linear 1s 2 reverse forwards paused anim3"
```

--------------------------------

### HTML Setup for CSS Scroll Timeline Polyfill

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Include the polyfill script and define CSS rules for scroll-driven animations. The polyfill intercepts style and link elements at runtime.

```html
<script src="/dist/scroll-timeline.js"></script>
<!-- The polyfill intercepts <style> and <link rel="stylesheet"> at runtime -->
<style>
  #scroller { scroll-timeline-name: --page; overflow-y: scroll; height: 300px; }
  #bar { animation: fill linear forwards; animation-timeline: --page; }
  @keyframes fill { from { width: 0 } to { width: 100% } }
</style>
<div id="scroller"><div style="height:2000px"></div></div>
<div id="bar"></div>
```

--------------------------------

### ScrollTimeline Constructor Examples

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Create a ScrollTimeline instance to track scroll progress. The `source` option defaults to the document's scrolling element, and `axis` can be 'block', 'inline', 'x', or 'y'. Use this timeline with the `animate` method to create scroll-driven animations.

```javascript
import 'https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js';

// Scroll progress of the entire page (block/vertical axis, the default)
const pageTimeline = new ScrollTimeline({
  source: document.scrollingElement, // default when omitted
  axis: 'block',                     // 'block' | 'inline' | 'x' | 'y'
});

// Scroll progress of a custom overflow container (horizontal)
const container = document.getElementById('h-scroller');
const hTimeline = new ScrollTimeline({ source: container, axis: 'inline' });

// Animate an element's opacity from 0 → 1 over the full page scroll
document.getElementById('hero').animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { fill: 'both', timeline: pageTimeline }
);

console.log(pageTimeline.source);
console.log(pageTimeline.axis);
console.log(pageTimeline.currentTime);
console.log(pageTimeline.phase);
console.log(pageTimeline.duration);
```

--------------------------------

### Progress Bar Animation with Custom 'entry' and 'exit' Range

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Applies a progress animation using custom 'entry' and 'exit' ranges. The animation starts 150% into the entry phase and ends 50% before the exit phase.

```css
#progress-bar-progress-f { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; animation-range: entry 150% exit -50%; }
```

--------------------------------

### Scroll-Driven Animation Setup

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/index.html

Applies a CSS animation to an element and links it to a scroll timeline. The `animation-timeline` property must reference a defined scroll timeline name.

```css
#box {
  position: fixed;
  top: 0;
  background-color: red;
  width: 50px;
  height: 50px;
  /* Please don't delete the following comments */
  /* This comment has been added to make sure css parser ignores it */
  /* animation-range: entry 0% 100%; */
  animation: linear anim forwards;
  animation-timeline: --foo;
}
```

--------------------------------

### Progress Bar Animation with 'entry' Range

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Applies a progress animation to a bar using the 'entry' `animation-range`. The animation starts when the element enters the scrollport and ends when it is fully visible.

```css
#progress-bar-progress-c { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; animation-range: entry; }
```

--------------------------------

### Setting scroll-timeline with various values

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

These examples demonstrate setting the 'scroll-timeline' CSS property with different shorthand values. Use these to verify correct parsing and application of named scroll timelines and axis orientations.

```css
e.style['scroll-timeline'] = "--block block"
```

```css
e.style['scroll-timeline'] = "--y block"
```

```css
e.style['scroll-timeline'] = "--x block"
```

```css
e.style['scroll-timeline'] = "--a, --b, --c"
```

```css
e.style['scroll-timeline'] = "--a inline, --b block, --c y"
```

```css
e.style['scroll-timeline'] = "--auto"
```

--------------------------------

### Do not set invalid view-timeline-inset CSS property

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Demonstrates invalid values for the `view-timeline-inset` CSS property that should not be set. These examples ensure the property is not modified with incorrect syntax or values.

```css
e.style['view-timeline-inset'] = "none"
```

```css
e.style['view-timeline-inset'] = "foo bar"
```

```css
e.style['view-timeline-inset'] = "\"foo\" \"bar\""
```

```css
e.style['view-timeline-inset'] = "rgb(1, 2, 3)"
```

```css
e.style['view-timeline-inset'] = "#fefefe"
```

```css
e.style['view-timeline-inset'] = "1px 2px 3px"
```

```css
e.style['view-timeline-inset'] = "1px 2px auto"
```

```css
e.style['view-timeline-inset'] = "auto 2px 3px"
```

```css
e.style['view-timeline-inset'] = "auto auto auto"
```

```css
e.style['view-timeline-inset'] = "1px / 2px"
```

--------------------------------

### Get Animations on Page and Element

Source: https://context7.com/flackr/scroll-timeline/llms.txt

The polyfill wraps `document.getAnimations()` and `element.getAnimations()` to return `ProxyAnimation` instances for scroll-driven animations. This preserves API transparency and allows inspection of animation properties like play state and timeline constructor name.

```javascript
// All animations on the page (includes polyfilled scroll-driven ones)
const all = document.getAnimations();
all.forEach(anim => {
  console.log(anim.playState, anim.timeline?.constructor.name);
  // e.g. "running ScrollTimeline"
});

// Animations on a specific element
const el = document.getElementById('card');
const elAnims = el.getAnimations({ subtree: false });
elAnims.forEach(anim => {
  if (anim.timeline instanceof ViewTimeline) {
    console.log('View timeline subject:', anim.timeline.subject);
    console.log('Range start:', anim.rangeStart);
  }
});
```

--------------------------------

### Progress Bar Animation with 'exit' Range

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Applies a progress animation to a bar using the 'exit' `animation-range`. The animation starts when the element begins to exit the scrollport and ends when it is completely out of view.

```css
#progress-bar-progress-d { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; animation-range: exit; }
```

--------------------------------

### Initialize and Run Scroll Animations

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/parallax/index.html

Sets up the code by populating code blocks with function source code and then invoking the animation functions. It also initializes syntax highlighting.

```javascript
function initCode(functions) {
  for (let i = 0; i < functions.length; i++) {
    $('#demo' + (i + 1) + ' > code').textContent = functions[i].toString();
  }
  // Invoke all functions.
  for (let i = 0; i < functions.length; i++) {
    functions[i]();
  }
  hljs.initHighlightingOnLoad();
}

function init() {
  initCode([
    animateParallax,
    animateHeaders,
    animateZoom,
    animatePan,
    animateWipe,
  ]);
}

document.addEventListener('DOMContentLoaded', init);
```

--------------------------------

### Run Simple Tests

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Execute the simple test command. This command serves the WPT tests folder and injects the polyfill for matching requests.

```shell
npm run test:simple

```

--------------------------------

### Invalid scroll-timeline-axis CSS Property Values

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Shows examples of invalid values for the `scroll-timeline-axis` property that should not be set. These demonstrate the parser's strictness.

```javascript
e.style['scroll-timeline-axis'] = "abc"
```

```javascript
e.style['scroll-timeline-axis'] = "10px"
```

```javascript
e.style['scroll-timeline-axis'] = "auto"
```

```javascript
e.style['scroll-timeline-axis'] = "none"
```

```javascript
e.style['scroll-timeline-axis'] = "block inline"
```

```javascript
e.style['scroll-timeline-axis'] = "block / inline"
```

--------------------------------

### Set CSS animation property with 'auto'

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

The 'animation' shorthand property can accept 'auto' for its duration component. This example shows a complex animation value with 'auto'.

```css
e.style['animation'] = "auto cubic-bezier(0, -2, 1, 3) -3s 4 reverse both paused anim"
```

--------------------------------

### Set up Scroll Container

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/basic/anonymous-scroll-timeline.html

Configures the container that will handle the scrolling and trigger the animation.

```css
#container {
  width: 500px;
  height: 500px;
  background-color:beige;
  overflow: auto;
}
```

--------------------------------

### Set Up Environment Variables for Simple Tests

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Configure required environment variables for running simple tests. These variables specify the Web Platform Tests directory and the server port.

```dotenv
WPT_DIR=test/wpt #defaults to test/wpt
WPT_SERVER_PORT=8081 # choose any port available on your machine

```

--------------------------------

### Initialize View Timeline Animations with CSS Math Values

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline/with-math-value-range.html

This script sets up two scroll-driven animations using ViewTimeline. It demonstrates defining rangeStart and rangeEnd with both simple CSS.percent and complex CSSMathSum/CSSMathProduct values.

```javascript
"use strict"; const progressBars = document.querySelectorAll('.progress-bar-progress'); const createProgressAnimation = (bar, rangeStart, rangeEnd, axis, inset = 'auto') => { const subject = document.getElementById('subject'); const viewTimeline = new ViewTimeline({ 'subject': subject, 'axis': axis, 'inset': inset }); bar.animate( { width: ['0px', '300px' ] }, { timeline: viewTimeline, rangeStart: rangeStart, rangeEnd: rangeEnd, fill: 'both' }); } const createAnimations = (selection) => { const axis = 'block'; document.getAnimations().forEach(anim => { anim.cancel(); }); createProgressAnimation(progressBars[0], { rangeName: 'cover', offset: CSS.percent(0) }, { rangeName: 'cover', offset: CSS.percent(100) }, axis); createProgressAnimation(progressBars[1], { rangeName: "cover", offset: new CSSMathSum(CSS.percent(0), new CSSMathProduct(CSS.number(2), CSS.px(100))), }, { rangeName: "cover", offset: new CSSMathSum(CSS.percent(100), CSS.px(-100)), }, axis) }; createAnimations();
```

--------------------------------

### Set Up Environment Variables for SauceLabs / CI Tests

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Configure environment variables for running tests in a SauceLabs or CI environment. Requires Sauce Connect tunnel ID and SauceLabs credentials.

```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

```

--------------------------------

### Set Up Environment Variables for Local WebDriver Tests

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Configure environment variables for running tests via local WebDriver. Includes paths to WebDriver binaries and the desired browser.

```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

```

--------------------------------

### Progress Bar Animation with 'contain' Range

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Applies a progress animation to a bar using the 'contain' `animation-range`. The animation starts when the element enters the scrollport and ends when it is fully contained.

```css
#progress-bar-progress-b { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; animation-range: contain; }
```

--------------------------------

### Run Tests via SauceLabs / CI

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Execute tests using SauceLabs for CI environments. This command sets the test environment to 'sauce' and runs the WebDriver tests.

```shell
TEST_ENV=sauce npm run test:wpt

```

--------------------------------

### Animate Zoom Effect with ViewTimeline

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/parallax/index.html

Creates a zoom-out effect on an image as it scrolls into view. The animation is controlled by the 'contain' range of the container element, starting at 30% and ending at 80% of its scroll progress.

```javascript
function animateZoom() {
  let container = $('#zoom');
  $('#zoom > div').animate({
    transform: 
      ['scale(3) translateX(10%)', 'scale(1)']
  }, {
    fill: 'both',
    timeline: new ViewTimeline({ subject: container }),
    rangeStart: { rangeName: 'contain', offset: CSS.percent(30) },
    rangeEnd: { rangeName: 'contain', offset: CSS.percent(80) },
  });
}
```

--------------------------------

### Run Tests via Local WebDriver

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Execute tests using a local WebDriver instance. This command is used for local testing with specified browsers.

```shell
npm run test:wpt

```

--------------------------------

### Import and Use ScrollTimeline in JavaScript

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Import the polyfill module and create animations using ScrollTimeline. Specify the source element and the range for the timeline.

```javascript
import 'https://flackr.github.io/scroll-timeline/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'),
    });

```

--------------------------------

### Setting scroll-timeline to affect axis and name

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

These examples demonstrate how setting the 'scroll-timeline' shorthand property with specific values like '--abc y' correctly sets the 'scroll-timeline-axis' and 'scroll-timeline-name' longhand properties, while ignoring unrelated longhands.

```css
e.style['scroll-timeline'] = "--abc y"
```

```css
e.style['scroll-timeline'] = "--abc y"
```

```css
e.style['scroll-timeline'] = "--abc y"
```

```css
e.style['scroll-timeline'] = "--inline x"
```

```css
e.style['scroll-timeline'] = "--inline x"
```

```css
e.style['scroll-timeline'] = "--inline x"
```

--------------------------------

### ProxyAnimation API

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Details the API of `ProxyAnimation`, the object returned by the polyfilled `element.animate()` and `new Animation()`. It covers standard lifecycle methods, playback rate control, time scrubbing, range adjustment, promises, events, and state inspection.

```APIDOC
## `ProxyAnimation` API

`ProxyAnimation` is the object returned by the polyfilled `element.animate()` and `new Animation()`. It is a transparent proxy over the native `Animation`, with all standard properties and lifecycle methods adapted for progress-based timelines.

```js
const anim = element.animate(keyframes, { fill: 'both', timeline: scrollTimeline });
// anim is a ProxyAnimation

// Standard lifecycle
anim.play();
anim.pause();
anim.reverse();
anim.finish();
anim.cancel();
anim.persist();

// Playback rate
anim.playbackRate = 2;         // 2× speed
anim.updatePlaybackRate(-1);   // pending rate change (non-breaking)

// Time scrubbing
anim.currentTime = CSS.percent(50); // jump to midpoint
anim.startTime   = CSS.percent(0);

// Range adjustment after creation
anim.rangeStart = 'entry 0%';
anim.rangeEnd   = 'exit 100%';

// Promises
anim.ready.then(a => console.log('ready', a.playState));
anim.finished.then(a => console.log('finished'));

// Events
anim.onfinish = (e) => console.log('finished at', e.currentTime);
anim.oncancel = () => console.log('cancelled');
anim.addEventListener('finish', handler);

// Inspect state
console.log(anim.effect);       // KeyframeEffect (proxied for percent timing)
console.log(anim.timeline);     // the ScrollTimeline or ViewTimeline
console.log(anim.playState);    // 'idle' | 'running' | 'paused' | 'finished'
console.log(anim.pending);      // true while play/pause task is scheduled
console.log(anim.id);
```
```

--------------------------------

### Unsetting scroll-timeline with empty or invalid values

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

These examples show how to unset or invalidate the 'scroll-timeline' CSS property by assigning empty strings or syntactically incorrect values. This is useful for resetting animations or ensuring invalid configurations are ignored.

```css
e.style['scroll-timeline'] = ""
```

```css
e.style['scroll-timeline'] = "--abc --abc"
```

```css
e.style['scroll-timeline'] = "block none"
```

```css
e.style['scroll-timeline'] = "inline --abc"
```

```css
e.style['scroll-timeline'] = "default"
```

```css
e.style['scroll-timeline'] = ","
```

```css
e.style['scroll-timeline'] = ",,block,,"
```

--------------------------------

### Create Scroll-Driven Animations with View Timeline

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline/index.html

Initializes and creates various scroll-driven animations using View Timeline. It sets up animations for different range types and axis based on the current layout. Cancels existing animations before creating new ones.

```javascript
"use strict";
let layout = 'vertical-tb';
let inset = 'auto';
const progressBars = document.querySelectorAll('.progress-bar-progress');
const createProgressAnimation = (bar, rangeStart, rangeEnd, axis, inset) => {
    const target = document.getElementById('target');
    const viewTimeline = new ViewTimeline({
        'subject': target,
        'axis': axis,
        'inset': inset
    });
    bar.animate({
        width: ['0px', '200px']
    }, {
        timeline: viewTimeline,
        rangeStart: `${rangeStart}`,
        rangeEnd: `${rangeEnd}`,
        fill: 'both'
    });
}
const createAnimations = () => {
    const axis = layout == 'vertical-tb' ? 'block' : 'inline';
    document.getAnimations().forEach(anim => {
        anim.cancel();
    });
    createProgressAnimation(progressBars[0], 'cover', 'cover', axis, inset);
    createProgressAnimation(progressBars[1], 'contain', 'contain', axis, inset);
    createProgressAnimation(progressBars[2], 'entry', 'entry', axis, inset);
    createProgressAnimation(progressBars[3], 'exit', 'exit', axis, inset);
    createProgressAnimation(progressBars[4], 'contain 25%', 'contain 75%', axis, inset);
    createProgressAnimation(progressBars[5], 'entry 150%', 'exit -50%', axis, inset);
    createProgressAnimation(progressBars[6], 'entry-crossing', 'entry-crossing', axis, inset);
    createProgressAnimation(progressBars[7], 'exit-crossing', 'exit-crossing', axis, inset);
};
document.querySelectorAll('input').forEach(input => {
    input.addEventListener('change', (evt) => {
        document.getAnimations().forEach(anim => {
            anim.cancel();
        });
        switch (event.target.name) {
            case 'layout':
                const selection = event.target.id;
                switch(selection) {
                    case 'vertical-tb':
                        container.classList.remove('rtl');
                        container.classList.remove('ltr');
                        overlay.classList.remove('rtl');
                        break;
                    case 'horizontal-ltr':
                        container.classList.remove('rtl');
                        container.classList.add('ltr');
                        overlay.classList.remove('rtl');
                        break;
                    case 'horizontal-rtl':
                        container.classList.add('rtl');
                        container.classList.remove('ltr');
                        overlay.classList.add('rtl');
                }
                layout = selection;
                break;
            case 'subject-size':
                if(event.target.checked) {
                    target.classList.add('taller');
                } else {
                    target.classList.remove('taller');
                }
                break;
            case 'subject-borders':
                if(event.target.checked) {
                    target.classList.add('borders');
                } else {
                    target.classList.remove('borders');
                }
                break;
            case 'timeline-insets':
                if(event.target.checked) {
                    inset = '100px 200px';
                    containerwrapper.classList.add('inset');
                } else {
                    inset = 'auto';
                    containerwrapper.classList.remove('inset');
                }
                break;
        }
        createAnimations();
    });
});
createAnimations('vertical-tb');
```

--------------------------------

### View-timeline lookup on ancestor

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Shows how to use `view-timeline` to reference an ancestor element. This allows animations to be driven by the scroll position of a parent container.

```css
view-timeline on ancestor
```

--------------------------------

### Styling for View Timeline Demo Elements

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline/with-math-value-range.html

Defines the visual styles and layout for the scroll container, subject element, and progress bars used in the View Timeline demonstration.

```css
#container { display: flex; flex-direction: column; border: 1px solid black; height: 500px; width: 500px; overflow-x: hidden; overflow-y: scroll; position: relative; align-items: flex-start; } .overlay { position: absolute; top: 10px; left: 10px; width: 500px; height: 500px; pointer-events: none; } .spacer { display: inline-block; flex: none; height: 120vh; width: 120vw; } #subject { background-color: rgba(0, 0, 255, 0.5); display: inline-block; flex: none; height: 100px; width: 90%; } .progress-bar, .progress-bar-progress { border: 1px solid green; height: 20px; width: 300px; position: absolute; inset-inline-start: 20px; padding: 0; } .progress-bar > span { padding-left: 5px; padding-right: 5px; } .progress-bar-progress { border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; }
```

--------------------------------

### View-timeline lookup with timeline-scope

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Illustrates the use of `timeline-scope` with `view-timeline` to specify the scrolling container. This includes scenarios with preceding siblings, ancestors, and potential conflicts.

```css
timeline-scope on preceding sibling
```

```css
timeline-scope on ancestor sibling
```

```css
timeline-scope on ancestor sibling, conflict remains unresolved
```

```css
timeline-scope on ancestor sibling, closer timeline wins
```

```css
view-timeline on ancestor sibling, scroll-timeline wins on same element
```

--------------------------------

### Include Scroll Timeline Polyfill

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Include the full or lite build of the polyfill using a script tag. The full build supports JS API and CSS properties, while the lite build supports JS API only.

```html
<!-- Full build: JS API + CSS animation-timeline properties -->
<script src="https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js"></script>

<!-- Lite build: JS API only, no CSS property parsing -->
<script src="https://flackr.github.io/scroll-timeline/dist/scroll-timeline-lite.js"></script>
```

--------------------------------

### Basic Scroll Timeline Container

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-inset.html

Sets up a scrollable container with defined dimensions and timeline scopes. This is the foundational element for scroll-driven animations.

```css
#container {
  display: flex;
  flex-direction: column;
  border: 1px solid black;
  height: 500px;
  width: 500px;
  overflow-x: hidden;
  overflow-y: scroll;
  position: relative;
  align-items: flex-start;
  timeline-scope: --firstVT, --secondVT;
}
```

--------------------------------

### ScrollTimeline Constructor

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Creates a progress-based timeline that maps scroll progress of a source element to its `currentTime`. This allows animations to be driven by scrolling behavior.

```APIDOC
## ScrollTimeline Constructor

Creates a progress-based timeline whose `currentTime` (0 %–100 %) maps to the scroll progress of a source element along a given axis.

```js
import 'https://flackr.github.io/scroll-timeline/dist/scroll-timeline.js';

// Scroll progress of the entire page (block/vertical axis, the default)
const pageTimeline = new ScrollTimeline({
  source: document.scrollingElement, // default when omitted
  axis: 'block',                     // 'block' | 'inline' | 'x' | 'y'
});

// Scroll progress of a custom overflow container (horizontal)
const container = document.getElementById('h-scroller');
const hTimeline = new ScrollTimeline({ source: container, axis: 'inline' });

// Animate an element's opacity from 0 → 1 over the full page scroll
document.getElementById('hero').animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { fill: 'both', timeline: pageTimeline }
);

console.log(pageTimeline.source);      // → <html> (scrollingElement)
console.log(pageTimeline.axis);        // → 'block'
console.log(pageTimeline.currentTime); // → CSSUnitValue e.g. CSS.percent(42)
console.log(pageTimeline.phase);       // → 'active' | 'inactive'
console.log(pageTimeline.duration);    // → CSS.percent(100) always
```
```

--------------------------------

### ViewTimeline Constructor

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Creates a progress-based timeline that tracks how far a subject element has progressed through its scroll container's viewport. It supports named range phases for precise control over animation timing relative to element visibility.

```APIDOC
## ViewTimeline Constructor

Creates a progress-based timeline whose `currentTime` tracks how far a subject element has progressed through its scroll container's viewport ("view progress visibility range"), supporting named range phases.

```js
const subject = document.getElementById('card');

const viewTimeline = new ViewTimeline({
  subject,                // required: element being tracked
  axis: 'block',          // optional, defaults to 'block'
  inset: '50px',          // optional: shrink the viewport by 50px on each side
  // inset: '100px 200px' // different start / end inset
});

// Fade in while the card enters the viewport
subject.animate(
  [{ opacity: 0, transform: 'translateY(40px)' },
   { opacity: 1, transform: 'translateY(0)' }],
  {
    fill: 'both',
    timeline: viewTimeline,
    rangeStart: 'entry 0%',   // start when leading edge enters
    rangeEnd:   'entry 100%', // finish when fully entered
  }
);

console.log(viewTimeline.subject);     // → #card element
console.log(viewTimeline.startOffset); // → CSSUnitValue in px (cover start)
console.log(viewTimeline.endOffset);   // → CSSUnitValue in px (cover end)
console.log(viewTimeline.currentTime); // → CSSUnitValue percent
```
```

--------------------------------

### Container Styling for Scroll Timeline

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Sets up a scrollable container with a defined timeline scope. Elements within this container can be linked to this timeline.

```css
#container { display: flex; flex-direction: column; border: 1px solid black; height: 500px; width: 500px; overflow-x: hidden; overflow-y: scroll; position: relative; align-items: flex-start; timeline-scope: --foo; }
```

--------------------------------

### Set CSS animation-timeline with view()

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Tests setting the 'animation-timeline' CSS property using the 'view()' function. Various syntaxes are tested, with some expected to fail parsing and not set the property.

```css
e.style['animation-timeline'] = "view()"
```

```css
e.style['animation-timeline'] = " view() "
```

```css
e.style['animation-timeline'] = "view(block)"
```

```css
e.style['animation-timeline'] = "view(inline)"
```

```css
e.style['animation-timeline'] = "view(x)"
```

```css
e.style['animation-timeline'] = "view(y)"
```

```css
e.style['animation-timeline'] = "view(y 1px 2px)"
```

```css
e.style['animation-timeline'] = "view(y 1px)"
```

```css
e.style['animation-timeline'] = "view(y auto)"
```

```css
e.style['animation-timeline'] = "view(y auto auto)"
```

```css
e.style['animation-timeline'] = "view(y auto 1px)"
```

```css
e.style['animation-timeline'] = "view(1px 2px y)"
```

```css
e.style['animation-timeline'] = "view(1px y)"
```

```css
e.style['animation-timeline'] = "view(auto x)"
```

```css
e.style['animation-timeline'] = "view(1px 2px)"
```

```css
e.style['animation-timeline'] = "view(1px)"
```

```css
e.style['animation-timeline'] = "view(1px 1px)"
```

```css
e.style['animation-timeline'] = "view(1px auto)"
```

```css
e.style['animation-timeline'] = "view(auto calc(1% + 1px))"
```

```css
e.style['animation-timeline'] = "view(auto)"
```

```css
e.style['animation-timeline'] = "view(auto auto)"
```

--------------------------------

### JavaScript for Scroll-Linked Animations

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline/with-inset.html

Sets up scroll-linked animations using View Timeline. It defines functions to create animations based on scroll progress and applies them to progress bar elements. The 'inset' parameter is used to adjust the scroll range.

```javascript
"use strict"; const progressBars = document.querySelectorAll('.progress-bar-progress'); const createProgressAnimation = (bar, rangeStart, rangeEnd, axis, inset = 'auto') => { const subject = document.getElementById('subject'); const viewTimeline = new ViewTimeline({ 'subject': subject, 'axis': axis, 'inset': inset }); bar.animate( { width: 
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																											100px 200px' 
 }); } const createAnimations = (selection) => { const axis = 'block'; document.getAnimations().forEach(anim => { anim.cancel(); }); createProgressAnimation(progressBars[0], { rangeName: 'cover', offset: CSS.percent(0) }, { rangeName: 'cover', offset: CSS.percent(100) }, axis); createProgressAnimation(progressBars[1], { rangeName: 'cover', offset: CSS.percent(0) }, { rangeName: 'cover', offset: CSS.percent(100) }, axis, '100px 200px'); }; createAnimations();
```

--------------------------------

### View-timeline lookup on self

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Demonstrates using `view-timeline` to reference the element itself. This is a basic case for scroll-driven animations.

```css
view-timeline on self
```

--------------------------------

### Progress Bar Base Styling

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Provides base styling for progress bar elements, including borders, height, and positioning.

```css
.progress-bar { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; }
```

--------------------------------

### Set view-timeline-inset CSS property

Source: https://github.com/flackr/scroll-timeline/blob/master/test/expected.txt

Demonstrates setting the `view-timeline-inset` CSS property with various valid values. This property controls the offset of a view timeline.

```css
e.style['view-timeline-inset'] = "initial"
```

```css
e.style['view-timeline-inset'] = "inherit"
```

```css
e.style['view-timeline-inset'] = "unset"
```

```css
e.style['view-timeline-inset'] = "revert"
```

```css
e.style['view-timeline-inset'] = "1px"
```

```css
e.style['view-timeline-inset'] = "1px 2px"
```

```css
e.style['view-timeline-inset'] = "1px 2em"
```

```css
e.style['view-timeline-inset'] = "calc(1em + 1px) 2px"
```

```css
e.style['view-timeline-inset'] = "1px 2px, 3px 4px"
```

```css
e.style['view-timeline-inset'] = "1px auto, auto 4px"
```

```css
e.style['view-timeline-inset'] = "1px, 2px, 3px"
```

```css
e.style['view-timeline-inset'] = "1px 1px, 2px 3px"
```

```css
e.style['view-timeline-inset'] = "auto auto, auto auto"
```

--------------------------------

### Apply Scroll-Driven Animation with CSS

Source: https://github.com/flackr/scroll-timeline/blob/master/README.md

Define CSS keyframes and apply them to an element using `animation-timeline` and `animation-range` for scroll-driven effects.

```css
@keyframes parallax-effect {
  to { transform: translateY(100px) }
}
#parallax {
  animation: parallax-effect linear both;
  animation-timeline: scroll(block root);
  animation-range: 0px 200px;
}

```

--------------------------------

### Element.animate() with Scroll/View Timelines (JS)

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Use `Element.prototype.animate` with `ScrollTimeline` or `ViewTimeline` for scroll-driven animations. The polyfill returns a `ProxyAnimation` that mirrors the Web Animations API.

```javascript
// Parallax translateY driven by root scroll
const parallax = document.getElementById('parallax');
const anim = parallax.animate(
  { transform: ['translateY(0)', 'translateY(200px)'] },
  {
    fill: 'both',
    timeline: new ScrollTimeline({ source: document.scrollingElement }),
    rangeStart: new CSSUnitValue(0, 'px'),
    rangeEnd:   new CSSUnitValue(400, 'px'),
  }
);

// ViewTimeline with named range bounds (JS objects or strings both work)
const card = document.getElementById('card');
const reveal = card.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  {
    fill: 'both',
    timeline: new ViewTimeline({ subject: card }),
    rangeStart: { rangeName: 'entry', offset: CSS.percent(0) },
    rangeEnd:   { rangeName: 'entry', offset: CSS.percent(100) },
  }
);

// ProxyAnimation API — same as native Animation
console.log(reveal.playState);   // 'running'
reveal.pause();
console.log(reveal.playState);   // 'paused'
reveal.play();
reveal.finished.then(() => console.log('animation complete'));
```

--------------------------------

### CSS for Scrollable Container

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/subject-target-the-same.html

Sets up a scrollable container with a fixed height and overflow. This element will also serve as the scroll timeline for the animation.

```css
#container {
  overflow-y: scroll;
  height: 300px;
  width: 300px;
  border: 1px solid black;
}
.big-spacer {
  height: 800px;
}
```

--------------------------------

### Progress Bar Styles

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-inset.html

Styles for a progress bar and its progress indicator. The progress bar is positioned absolutely within its container.

```css
.progress-bar, .progress-bar-progress {
  border: 1px solid green;
  height: 20px;
  width: 200px;
  position: absolute;
  inset-inline-start: 20px;
  padding: 0;
}
```

```css
.progress-bar > span {
  padding-left: 5px;
  padding-right: 5px;
}
```

```css
.progress-bar-progress {
  border-color: transparent;
  background-color: rgba(0, 200, 0, 0.3);
  width: 0px;
  animation: linear simpleAnimation both;
}
```

--------------------------------

### Progress Bar Animation with 'cover' Range

Source: https://github.com/flackr/scroll-timeline/blob/master/demo/view-timeline-css/with-delays-using-animation-time-range.html

Applies a progress animation to a bar using the 'cover' `animation-range`. The animation spans the entire duration of the scroll timeline.

```css
#progress-bar-progress-a { border: 1px solid green; height: 20px; width: 200px; position: absolute; inset-inline-start: 20px; padding: 0; animation: linear progress forwards; animation-timeline: --foo; border-color: transparent; background-color: rgba(0, 200, 0, 0.3); width: 0px; animation-range: cover; }
```

--------------------------------

### CSS `scroll-timeline` Property (CSS Polyfill)

Source: https://context7.com/flackr/scroll-timeline/llms.txt

Explains how to declare named scroll timelines using CSS properties like `scroll-timeline-name` and `scroll-timeline-axis`. It shows how to reference these timelines in animations using `animation-timeline`.

```APIDOC
## CSS `scroll-timeline` Property (CSS Polyfill)

Named scroll timelines declared purely in CSS; the polyfill's CSS parser transpiles these at runtime.

```css
/* Declare a named scroll timeline on a scroll container */
#scroller {
  scroll-timeline-name: --my-timeline;
  scroll-timeline-axis: block; /* optional */
  overflow: scroll;
  height: 400px;
}

/* Reference it on an animated element */
#progress-bar {
  animation: grow-bar linear forwards;
  animation-timeline: --my-timeline;
}

@keyframes grow-bar {
  from { width: 0; }
  to   { width: 100%; }
}
```

```html
<script src="/dist/scroll-timeline.js"></script>
<!-- The polyfill intercepts <style> and <link rel="stylesheet"> at runtime -->
<style>
  #scroller { scroll-timeline-name: --page; overflow-y: scroll; height: 300px; }
  #bar { animation: fill linear forwards; animation-timeline: --page; }
  @keyframes fill { from { width: 0 } to { width: 100% } }
</style>
<div id="scroller"><div style="height:2000px"></div></div>
<div id="bar"></div>
```
```