### decodeVideo usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example of calling decodeVideo and handling the promise resolution and rejection.

```javascript
const scrollyVideo = new ScrollyVideo({ /* ... */ });
scrollyVideo
  .decodeVideo()
  .then(() => console.log('decode pass complete:', scrollyVideo.frames.length))
  .catch((err) => console.error('WebCodecs decode failed; falling back to <video>', err));
```

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

### npm install scrolly-video

Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md

Installation instructions for the scrolly-video npm package.

```APIDOC
## [INSTALL] npm install scrolly-video

### Description
Install the scrolly-video npm package.

### Method
npm install

### Endpoint
npm install scrolly-video --save

### Parameters
None

### Request Example
```bash
npm install scrolly-video --save
```

### Response
#### Success Response (200)
- **status** (string) - Installation successful

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### transitionToTargetTime usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example call to transitionToTargetTime, requiring targetTime to be pre-set. Uses a quadratic easing function.

```javascript
// Normally invoked via setVideoPercentage / setTargetTimePercent. Direct use
// requires targetTime to be pre-set.

scrollyVideo.targetTime = 10; // seconds
scrollyVideo.transitionToTargetTime({ transitionSpeed: 8, easing: (t) => t * t });
```

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

### setCoverStyle usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example of re-applying cover sizing after a container resize, using the canvas or video element.

```javascript
// re-apply cover sizing after you manually resize a container
window.addEventListener('resize', () => {
  scrollyVideo.setCoverStyle(scrollyVideo.canvas || scrollyVideo.video);
});
```

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

### Install scrolly-video npm package

Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md

Install the scrolly-video package using npm with the --save flag.

```bash
npm install scrolly-video --save
```

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

### Direct usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/videoDecoder.md

Shows how to call videoDecoder directly, collecting decoded frames into an array and handling errors.

```javascript
import videoDecoder from './videoDecoder';

const frames = [];
try {
  await videoDecoder(
    'https://scrollyvideo.js.org/goldengate.mp4',
    (bitmap) => frames.push(bitmap),
    false,
  );
  console.log('decoded frames:', frames.length);
} catch (err) {
  console.error('decode failed — keep using <video>', err);
}
```

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

### Usage example with options for ScrollyVideo Astro component

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/astro-component.md

Shows how to pass additional props to customize behavior, such as `scrollyVideoContainer`, `transitionSpeed`, `frameThreshold`, `trackScroll`, `useWebCodecs`, and `debug` using `import.meta.env.DEV`.

```astro
---
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';
---

<ScrollyVideo
  src="https://scrollyvideo.js.org/goldengate.mp4"
  scrollyVideoContainer="my-video-stage"
  :transitionSpeed="12"
  :frameThreshold="0.05"
  :trackScroll="false"
  :useWebCodecs="true"
  :debug="import.meta.env.DEV"
/>
```

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

### paintCanvasFrame example: paint first decoded frame

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example call to paintCanvasFrame with frame index 0 to paint the first decoded frame.

```javascript
scrollyVideo.paintCanvasFrame(0); // paint the first decoded frame
```

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

### setTargetTimePercent usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example calls to setTargetTimePercent. The first jumps instantly to the last frame, the second animates to 25%.

```javascript
// Internally driven by scroll, but callable directly.
// Note: setVideoPercentage is the public entry; this is the lower-level target setter.

scrollyVideo.setTargetTimePercent(1, { jump: true });   // go to the last frame instantly
scrollyVideo.setTargetTimePercent(0.25);                // animate to 25%
```

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

### Basic usage example of ScrollyVideo Astro component

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/astro-component.md

A minimal Astro page that imports the component and places it inside a `<main>` with a tall container to enable scrolling. The `src` prop is required.

```astro
---
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.astro';
---

<main>
  <div style="height: 300vh;">
    <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
  </div>
</main>
```

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

### debounce basic usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/utils.md

Example of using debounce to coalesce high-frequency resize events. The debounced function logs 'resize settled' 150 ms after the last resize event.

```javascript
import { debounce } from './utils';

const onResize = debounce(() => {
  console.log('resize settled');
}, 150);

window.addEventListener('resize', onResize);
```

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

### Controlled playback with ref and error handling

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/react-component.md

A more advanced example that uses a ref to control playback, a range input to set videoPercentage, and an effect to destroy the instance on unmount. Imports the CJS build from 'scrolly-video/dist/ScrollyVideo.cjs.jsx'.

```jsx
import React, { useRef, useEffect, useState } from 'react';
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';

function Controller() {
  const scrollyRef = useRef(null);
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    // destroy() unregisters listeners; guard the ref in strict-mode double effects
    return () => {
      if (scrollyRef.current) scrollyRef.current.destroy?.();
    };
  }, []);

  return (
    <>
      <div style={{ height: '300vh' }}>
        <ScrollyVideo
          ref={scrollyRef}
          src="https://scrollyvideo.js.org/goldengate.mp4"
          trackScroll={false}
          videoPercentage={progress}
          onChange={setProgress}
          onReady={() => console.log('ready')}
        />
      </div>
      <input
        type="range"
        min={0}
        max={1}
        step={0.01}
        value={progress}
        onChange={(e) => setProgress(Number(e.target.value))}
      />
      {scrollyRef.current && (
        <button onClick={() => scrollyRef.current.setVideoPercentage(0)}>
          Reset to start
        </button>
      )}
    </>
  );
}
```

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

### Basic ScrollyVideo example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/react-component.md

A minimal React component that renders a ScrollyVideo inside a container with a height of 300vh. Imports the ESM build from 'scrolly-video/dist/ScrollyVideo.esm.jsx'.

```jsx
import React from 'react';
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';

function App() {
  return (
    <div className="scrolly-container" style={{ height: '300vh' }}>
      <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
    </div>
  );
}

export default App;
```

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

### debounce preserving context and arguments example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/utils.md

Shows that the debounced wrapper preserves the this context and forwards arguments. Calling update.call(video, 0.7) schedules an update, and calling update.call(video, 0.8) cancels the previous timer, so only the last call executes after 50 ms.

```javascript
const video = { percent: 0.5 };
const update = debounce(function (value) {
  this.percent = value; // `this` is `video`
  render(video.percent);
}, 50);

update.call(video, 0.7);      // scheduled
update.call(video, 0.8);      // cancels the previous timer
// after 50ms: video.percent === 0.8
```

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

### new ScrollyVideo(options)

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Creates a new ScrollyVideo instance. It sets up the video element, attaches scroll and resize listeners, and begins decoding the video. The constructor throws errors for invalid container arguments.

```APIDOC
## new ScrollyVideo(options)

### Description
Creates a new ScrollyVideo instance. It sets up the video element, attaches scroll and resize listeners, and begins decoding the video. The constructor throws errors for invalid container arguments.

### Method
Constructor

### Parameters
#### options (Object) - Required
- **scrollyVideoContainer** (Element|string) - Required - The container element or its ID. If a string, it is resolved via `document.getElementById`. If not an Element or a resolvable string, throws an Error.
- **src** (string) - Required - The video source URL.
- **transitionSpeed** (number) - Optional - Speed of transition between frames.
- **frameThreshold** (number) - Optional - Threshold for frame changes.
- **onReady** (function) - Optional - Callback when the video is ready.
- **onChange** (function) - Optional - Callback with progress percentage.
- **debug** (boolean) - Optional - Enables debug logging.
- **useWebCodecs** (boolean) - Optional - If false, forces HTML5 video strategies.
- **trackScroll** (boolean) - Optional - If true, tracks scroll position.
- **sticky** (boolean) - Optional - Enables sticky positioning.
- **full** (boolean) - Optional - Enables full container sizing.
- **cover** (boolean) - Optional - Enables cover sizing.

### Behavior
- **DOM guard:** if `typeof document !== 'object'`, logs `'ScrollyVideo must be initiated in a DOM context'` and returns (no object constructed).
- **Argument guards:** falsy `scrollyVideoContainer` → `console.error('scrollyVideoContainer must be a valid DOM object')` and return. Falsy `src` → `console.error('Must provide valid video src to ScrollyVideo')` and return.
- **Container resolution:** `Element` instances are used directly; strings are resolved via `document.getElementById`; a string that resolves to `null`, or any other type, throws `new Error('scrollyVideoContainer must be a valid DOM object')`.
- **Video element setup:** creates `<video>` with `src`, `preload='auto'`, `tabIndex=0`, `autobuffer=true`, `playsInline=true`, `muted=true`, then `pause()` and `load()`. `videoPercentage` initializes to `0`.
- **CSS side effects** (per `sticky`/`full`/`cover` flags, see Parameters table).
- **Safari detection:** `new UAParser().getEngine().name === 'WebKit'` → `this.isSafari` (debug logs it).
- **State init:** `currentTime = 0`, `targetTime = 0`, `canvas = null`, `context = null`, `frames = []`, `frameRate = 0`.
- **Listeners:** if `trackScroll`, a `scroll` listener fires `updateScrollPercentage`, and `loadedmetadata` triggers `updateScrollPercentage(true)` once; otherwise, `loadedmetadata` triggers `setTargetTimePercent(0, { jump: true })` once. A window `resize` listener and a video `progress` listener both call `this.resize`.
- **Kickoff:** calls `this.decodeVideo()`.

### Example — plain JS
```html
<div style="height: 300vh;">
  <div id="scrolly-video"></div>
</div>
<script src="https://cdn.jsdelivr.net/npm/scrolly-video@latest/dist/scrolly-video.js"></script>
<script>
  const scrollyVideo = new ScrollyVideo({
    scrollyVideoContainer: 'scrolly-video', // or an Element
    src: 'https://scrollyvideo.js.org/goldengate.mp4',
    transitionSpeed: 12,
    frameThreshold: 0.05,
    onReady: () => console.log('ready to scroll'),
    onChange: (p) => console.log('progress', p),
    debug: true,
  });
</script>
```

### Example — with an `Element` container and error handling
```js
const container = document.querySelector('#video-stage');

let scrollyVideo;
try {
  scrollyVideo = new ScrollyVideo({
    scrollyVideoContainer: container,
    src: 'https://scrollyvideo.js.org/goldengate.mp4',
    useWebCodecs: false, // force HTML5 video strategies
  });
} catch (err) {
  // Thrown when scrollyVideoContainer is not an Element, or a string id
  // that document.getElementById cannot resolve.
  console.error('Could not start ScrollyVideo', err);
}
```
```

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

### setScrollPercent example: scroll to midpoint with trackScroll check

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Example usage of setScrollPercent that checks if trackScroll is enabled before calling, and warns otherwise.

```javascript
if (scrollyVideo.trackScroll) {
  scrollyVideo.setScrollPercent(0.5); // scroll so the video shows its midpoint
} else {
  console.warn('scroll percent only works with trackScroll enabled');
}
```

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

### Imperative control from the parent

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/svelte-component.md

Shows how to bind `videoPercentage` to a range input and use the exported `setVideoPercentage` function to jump to a specific percentage.

```svelte
<script>
  import ScrollyVideo, { setVideoPercentage } from 'scrolly-video/dist/ScrollyVideo.svelte';
  let progress = 0;
</script>

<ScrollyVideo
  src="https://scrollyvideo.js.org/goldengate.mp4"
  bind:videoPercentage={progress}
  trackScroll={false}
/>

<input type="range" min={0} max={1} step={0.01} bind:value={progress} />

<button on:click={() => setVideoPercentage(0.5, { transitionSpeed: 12 })}>
  Jump to middle
</button>
```

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

### Import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.js'

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Shows how to import the ScrollyVideo class, either via the module path or the IIFE global.

```javascript
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.js'; // or the IIFE global `ScrollyVideo`
```

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

### isScrollPositionAtTarget basic usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/utils.md

Example of using isScrollPositionAtTarget to check if the page is already near a target scroll position, and if not, smooth-scroll to it.

```javascript
import { isScrollPositionAtTarget } from './utils';

const target = 2000;
if (isScrollPositionAtTarget(target)) {
  console.log('already near target');
} else {
  window.scrollTo({ top: target, behavior: 'smooth' });
}
```

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

### Include ScrollyVideo script and initialize

Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md

Include the ScrollyVideo script from CDN and create a new ScrollyVideo instance before the closing body tag. Replace '@latest' with a specific version like '@0.0.2' if needed.

```html
<script src="https://cdn.jsdelivr.net/npm/scrolly-video@latest/dist/scrolly-video.js"></script>
<script type="text/javascript">
  new ScrollyVideo({
    scrollyVideoContainer: "scrolly-video",
    src: "https://scrollyvideo.js.org/goldengate.mp4"
  });
</script>
```

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

### Client script to instantiate ScrollyVideo core

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/astro-component.md

The client script imports the core `ScrollyVideo` component from './ScrollyVideo' (resolving to `dist/ScrollyVideo.js`) and instantiates it with all `Astro.props`. This script executes on page load without needing a `client:` directive.

```html
<script>
  import ScrollyVideoComponent from './ScrollyVideo';

  new ScrollyVideoComponent({ ...Astro.props });
</script>
```

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

### destroy() usage example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Calling destroy() on a ScrollyVideo instance empties the container and makes the instance no longer usable.

```javascript
scrollyVideo.destroy();
// container is now empty; the instance is no longer usable
```

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

### ScrollyVideo constructor options

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

The constructor accepts an options object with src and scrollyVideoContainer required, and optional settings for cover, sticky, full, trackScroll, lockScroll, transitionSpeed, frameThreshold, useWebCodecs, onReady, onChange, and debug.

```javascript
constructor({
  src, // The src of the video, required
  scrollyVideoContainer, // The dom element or id that this object will be created in, required
  cover = true, // Whether the video should "cover" inside the container
  sticky = true, // Whether the video should "stick" to the top of the container
  full = true, // Whether the container should expand to 100vh and 100vw
  trackScroll = true, // Whether this object should automatically respond to scroll
  lockScroll = true, // Whether it ignores human scroll while it runs `setVideoPercentage` with enabled `trackScroll`
  transitionSpeed = 8, // How fast the video transitions between points
  frameThreshold = 0.1, // When to stop the video animation, in seconds
  useWebCodecs = true, // Whether to try using the webcodecs approach
  onReady = () => {}, // A callback that invokes on video decode
  onChange = () => {}, // A callback that invokes on video percentage change
  debug = false, // Whether to print debug stats to the console
})
```

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

### Basic Svelte component usage

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/svelte-component.md

Example of using the ScrollyVideo component in a Svelte page with a container div and styling for scroll height.

```svelte
<!-- +page.svelte -->
<script>
  import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.svelte';
</script>

<div class="scrolly-video-container">
  <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
</div>

<style>
  .scrolly-video-container {
    height: 300vh;
  }
</style>
```

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

### constructor(options)

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Creates a new ScrollyVideo instance. The constructor requires a video source URL and a container element or ID, and accepts various optional configuration options to control video behavior, styling, and callbacks.

```APIDOC
## constructor(options)

### Description
Creates a new ScrollyVideo instance. The constructor requires a video source URL and a container element or ID, and accepts various optional configuration options to control video behavior, styling, and callbacks.

### Method
constructor

### Signature
```js
constructor({
  src, // The src of the video, required
  scrollyVideoContainer, // The dom element or id that this object will be created in, required
  cover = true, // Whether the video should "cover" inside the container
  sticky = true, // Whether the video should "stick" to the top of the container
  full = true, // Whether the container should expand to 100vh and 100vw
  trackScroll = true, // Whether this object should automatically respond to scroll
  lockScroll = true, // Whether it ignores human scroll while it runs `setVideoPercentage` with enabled `trackScroll`
  transitionSpeed = 8, // How fast the video transitions between points
  frameThreshold = 0.1, // When to stop the video animation, in seconds
  useWebCodecs = true, // Whether to try using the webcodecs approach
  onReady = () => {}, // A callback that invokes on video decode
  onChange = () => {}, // A callback that invokes on video percentage change
  debug = false, // Whether to print debug stats to the console
})
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `src` | string (URL) | **yes** (constructor returns early with a console error if falsy) | — | Source URL of the MP4 video |
| `scrollyVideoContainer` | `Element` \| string | **yes** (early return if falsy; `Error` thrown if unresolvable) | — | Container DOM element or element id |
| `cover` | boolean | no | `true` | Whether the video/canvas should "cover" inside the container (`setCoverStyle` applied) |
| `sticky` | boolean | no | `true` | Whether the container gets `position: sticky; top: 0; display: block` |
| `full` | boolean | no | `true` | Whether the container expands to `width: 100%; height: 100vh; overflow: hidden` |
| `trackScroll` | boolean | no | `true` | Whether the object auto-responds to window scroll |
| `lockScroll` | boolean | no | `true` | While `setVideoPercentage` has a pending smooth-scroll target (`targetScrollPosition`), ignore human scroll and keep re-issuing the scroll animation (used only inside `updateScrollPercentage`) |
| `transitionSpeed` | number | no | `8` | Playback transition speed — maximum `playbackRate` in video mode; denominator in canvas/currentTime stepping |
| `frameThreshold` | number | no | `0.1` | Animation stop threshold, in seconds; when `|targetTime − currentTime| < frameThreshold` the animation ends |
| `useWebCodecs` | boolean | no | `true` | Whether to attempt the WebCodecs canvas decoding strategy |
| `onReady` | `() => void` | no | `() => {}` | Called when decoding finishes (success or zero-frames fallback) |
| `onChange` | `(percentage: number) => void` | no | `() => {}` | Called with the scroll percentage (0..1) whenever it changes |
| `debug` | boolean | no | `false` | Logs debug information to the console |

### Notes
- `full` and `lockScroll` are consumed inside the constructor (CSS side effects / closure in `updateScrollPercentage`) but are not assigned to `this`.

### Example
```js
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.js';

const scrollyVideo = new ScrollyVideo({
  src: 'video.mp4',
  scrollyVideoContainer: '#container',
  cover: true,
  sticky: true,
  full: true,
  trackScroll: true,
  lockScroll: true,
  transitionSpeed: 8,
  frameThreshold: 0.1,
  useWebCodecs: true,
  onReady: () => console.log('ready'),
  onChange: (percentage) => console.log(percentage),
  debug: false
});
```
```

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

### isScrollPositionAtTarget custom tolerance example

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/utils.md

Shows using a custom threshold of 10 pixels to determine if the scroll position is within 10px of 4000.

```javascript
const isCloseEnough = isScrollPositionAtTarget(4000, 10); // within 10px
console.log(isCloseEnough);
```

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

### Error handling with setVideoPercentage

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/svelte-component.md

Demonstrates catching errors from `setVideoPercentage` when the instance is not yet created.

```svelte
<script>
  import ScrollyVideo, { setVideoPercentage } from 'scrolly-video/dist/ScrollyVideo.svelte';

  function jump() {
    try {
      setVideoPercentage(1); // finished state
    } catch (err) {
      // fires only if the instance hasn't been created yet
      console.error('ScrollyVideo not ready', err);
    }
  }
</script>

<ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
<button on:click={jump}>End</button>
```

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

### transitionToTargetTime method signature

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Method signature for transitionToTargetTime, which animates the video to the target time. Accepts options for jump, transitionSpeed, and easing.

```javascript
transitionToTargetTime({
  jump,
  transitionSpeed = this.transitionSpeed,
  easing = null,
})
```

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

### Basic ScrollyVideo usage in Vue

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/vue-component.md

Minimal setup importing the component and rendering it with a video source. The container div is given a height of 300vh to enable scroll-driven playback.

```vue
<!-- App.vue -->
<script setup>
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.vue';
</script>

<template>
  <div class="scrolly-video-container">
    <ScrollyVideo src="https://scrollyvideo.js.org/goldengate.mp4" />
  </div>
</template>

<style scoped>
.scrolly-video-container {
  height: 300vh;
}
</style>
```

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

### Import ScrollyVideo (CommonJS and ES modules)

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/react-component.md

Shows how to import the ScrollyVideo component from the CommonJS or ES module build. Use the appropriate import based on your module system.

```javascript
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';  // CommonJS
// or
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';  // ES modules
```

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

### package.json entry points

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/README.md

Defines the package name, version, main entry, and TypeScript types for the scrolly-video package.

```json
{
  "name": "scrolly-video",
  "version": "0.0.25",
  "main": "dist/scrolly-video.js",
  "types": "dist/ScrollyVideo.d.ts"
}
```

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

### Import ScrollyVideo in React (CJS or ESM)

Source: https://github.com/dkaoster/scrolly-video/blob/main/README.md

Import the ScrollyVideo component in a React application. Two import paths are shown: CommonJS (.cjs.jsx) and ES module (.esm.jsx). Use the one that matches your build setup.

```javascript
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.cjs.jsx';
or
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.esm.jsx';
```

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

### setVideoPercentage(...args)

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/svelte-component.md

Exported function that forwards arguments to the core instance's setVideoPercentage method. Throws if called before the instance exists.

```APIDOC
## setVideoPercentage(...args)

### Description
Exported function that forwards arguments to the core instance's `setVideoPercentage` method. Throws if called before the instance exists.

### Parameters
- `...args` (`[percentage: number, options?: object]`) - Forwarded verbatim to the core `setVideoPercentage(percentage, options = {})`.

### Returns
`undefined`. Note: throws if called before the instance exists (`scrollyVideo` is only assigned once `scrollyVideoContainer` binds and the reactive block has run) — the source does not guard `scrollyVideo` in this function.

### Example
```js
import ScrollyVideo, { setVideoPercentage } from 'scrolly-video/dist/ScrollyVideo.svelte';

setVideoPercentage(0.5, { transitionSpeed: 12 });
```
```

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

### setVideoPercentage(...args)

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/vue-component.md

Forwards the arguments to the core `setVideoPercentage` method if the ScrollyVideo instance exists. If the instance is not yet created, this method is a no-op.

```APIDOC
## setVideoPercentage(...args)

### Description
Forwards the arguments to the core `setVideoPercentage` method if the ScrollyVideo instance exists. If the instance is not yet created, this method is a no-op.

### Method
setVideoPercentage(...args)

### Parameters
- **...args** (`[percentage: number, options?: object]`) - Forwarded verbatim to the core `setVideoPercentage(percentage, options = {})`.

### Returns
`undefined`. No-op if the instance is not yet created.

### Source
`src/ScrollyVideo.vue:23`
```

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

### Import ScrollyVideo and setVideoPercentage

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/svelte-component.md

Shows the two import styles: default import for the component, and named import for the imperative API.

```javascript
import ScrollyVideo from 'scrolly-video/dist/ScrollyVideo.svelte';
// or, for the imperative API:
import ScrollyVideo, { setVideoPercentage } from 'scrolly-video/dist/ScrollyVideo.svelte';
```

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

### Environment Variables

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/configuration.md

Lists the build-time environment variables used by the rollup configuration.

```APIDOC
## Environment Variables

### Description
Environment variables used during the build process for the ScrollyVideo library.

### Variables
- **DOCS_SITE** - Used by `rollup.config.mjs` (scripts `dev`, `build-docs`). Values: `'true'`. Effect: Builds the docs site (`public/main.js` → `build/docs.js`) instead of the library bundles.
- **ROLLUP_WATCH** - Used by `rollup.config.mjs` (set by `rollup -w`). Values: any truthy. Effect: Enables dev-server serving (`sirv` on port 4000) and livereload.
- **NODE_ENV** (implied) - Used by `rollup.config.mjs` (`production = !watch`). Values: —. Effect: Drives minification via `terser`.

### Note
There are **no runtime environment variables** consumed by the compiled library.
```

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

### Module graph of src/ScrollyVideo.js

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/README.md

Shows the import relationships between the core class and its dependencies, including framework wrappers.

```text
src/ScrollyVideo.js      (core class, default export)  ── imports ──► src/videoDecoder.js (default export)
     │                                                            └──► src/utils.js (debounce, isScrollPositionAtTarget)
     │                                                              └──► mp4box (internal)
     │                                                              └── ua-parser-js (internal)
     ├── src/ScrollyVideo.jsx    (React wrapper, default export; imports core class)
     ├── src/ScrollyVideo.svelte (Svelte wrapper, default export; imports core class)
     ├── src/ScrollyVideo.vue    (Vue wrapper, default export; imports core class)
     └── src/ScrollyVideo.astro  (Astro wrapper, default export; imports core class)
```

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

### setVideoPercentage method implementation

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/vue-component.md

Implements the setVideoPercentage method. It forwards the arguments to the core ScrollyVideo instance's setVideoPercentage method if the instance exists. Returns undefined and is a no-op if the instance is not yet created.

```javascript
setVideoPercentage(...args) {
  if (this.scrollyVideo) this.scrollyVideo.setVideoPercentage(...args);
}
```

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

### setTargetTimePercent(percentage, options = {})

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Sets the target playback time as a percentage (0..1) of the video duration. The percentage is clamped, and the method optionally jumps directly to the target or animates to it using transitionToTargetTime.

```APIDOC
## setTargetTimePercent(percentage, options = {})

### Description
Sets the target playback time as a percentage (0..1) of the video duration. The percentage is clamped, and the method optionally jumps directly to the target or animates to it using transitionToTargetTime.

### Method
setTargetTimePercent

### Signature
```js
setTargetTimePercent(percentage, options = {})
```

### Parameters
- **percentage** (number) - Required - Percentage 0..1; clamped with `Math.max(Math.min(percentage, 1), 0)`
- **options** (object) - Optional - Default: `{}` - Same shape as `setVideoPercentage` options; reads `options.jump` here, forwards `transitionSpeed`/`easing` to `transitionToTargetTime`

### Returns
`undefined`. Sets `this.targetTime = clamp(percentage, 0, 1) * targetDuration`, where `targetDuration` is `frames.length / frameRate` when decoded frames exist, otherwise `this.video.duration`.

### Behavior
- **Early return** if `!options.jump && Math.abs(this.currentTime - this.targetTime) < this.frameThreshold`.
- Plays the video (`video.play()`) if in video mode and currently paused, then calls `transitionToTargetTime(options)`.

### Example
```js
// Internally driven by scroll, but callable directly.
// Note: setVideoPercentage is the public entry; this is the lower-level target setter.

scrollyVideo.setTargetTimePercent(1, { jump: true });   // go to the last frame instantly
scrollyVideo.setTargetTimePercent(0.25);                // animate to 25%
```
```

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

### Instance Fields

Source: https://github.com/dkaoster/scrolly-video/blob/main/_autodocs/api-reference/ScrollyVideo-class.md

Lists the public instance fields of the ScrollyVideo class, their types, when they are set, and their descriptions.

```APIDOC
## Instance Fields

| Field | Type | Set at | Description |
|-------|------|--------|-------------|
| `container` | `Element` | constructor | Resolved container element |
| `src` | string | constructor | Video source URL |
| `transitionSpeed` | number | constructor | Default `8` |
| `frameThreshold` | number | constructor | Default `0.1` |
| `useWebCodecs` | boolean | constructor | Default `true` |
| `cover` | boolean | constructor | Default `true` |
| `sticky` | boolean | constructor | Default `true` |
| `trackScroll` | boolean | constructor | Default `true` |
| `onReady` | `() => void` | constructor | Default no-op |
| `onChange` | `(percentage: number) => void` | constructor | Default no-op |
| `debug` | boolean | constructor | Default `false` |
| `isSafari` | boolean | constructor | Engine name `'WebKit'` |
| `video` | `HTMLVideoElement` | constructor | Hidden/muted video element |
| `videoPercentage` | number | constructor (`0`) | Current percentage |
| `currentTime` | number | constructor (`0`) | Synced with `video.currentTime` (canvas mode driven directly) |
| `targetTime` | number | constructor (`0`) | Destination time in seconds |
| `canvas` | `HTMLCanvasElement` \| null | `decodeVideo` | Canvas display surface (WebCodecs mode) |
| `context` | `CanvasRenderingContext2D` \| null | `decodeVideo` | Canvas 2D context |
| `frames` | `ImageBitmap[]` | constructor (`[]`) | Decoded frames |
| `frameRate` | number | constructor (`0`) | `frames.length / video.duration` after decode |
| `targetScrollPosition` | number \| null | `setScrollPercent` | Pending smooth-scroll target; `null` when idle |
| `updateScrollPercentage` | `(jump?: boolean) => void` | constructor | Internal scroll handler (window `scroll` listener) |
| `resize` | `() => void` | constructor | Re-applies cover style + repaints canvas |
| `transitioningRaf` | number \| null | `transitionToTargetTime` | Active `requestAnimationFrame` id |

> `full` and `lockScroll` are **not** instance fields — `full` only drives constructor CSS; `lockScroll` is captured by the `updateScrollPercentage` closure.
```