# Scroll Product Story

> Build or debug a scroll-driven product story with one persistent visual object, especially a video or image-sequence rotation controlled by scrolling.

- Skill: `alexdubaev/scroll-product-story` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alexdubaev/scroll-product-story`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexdubaev/scroll-product-story/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexdubaev (https://skillmd.com/u/alexdubaev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alexdubaev/scroll-product-story

---


# Scroll Product Story

Use this for cinematic landing-page scenes where scrolling controls a product, object, vehicle, render, or other persistent visual while copy changes around it. Do not use it for ordinary entrance animations or decorative parallax.

## Choose the renderer before tuning motion

- Use an image sequence drawn on a DPR-capped canvas when the object must scrub precisely forward and backward. This is the dependable choice for iPhone/iPad WebKit.
- A paused `<video>` with `currentTime` seeks is acceptable only after it has been tested on the actual target Safari environment. Do not treat desktop Chromium success as proof for iOS.
- A real 3D model can use WebGL/Three.js if it materially improves the scene. Do not fake rotation with CSS transforms on a still image.
- Keep an accessible static representative frame for reduced-motion and no-JavaScript states.

## Image-sequence baseline

- Render enough evenly spaced WebP/AVIF frames for the source motion. For a short rotating product clip, begin around 120–150 frames; 20–60 frames commonly reads as stepping once the object is large on screen.
- Load frames before starting the pinned story. Show a restrained loading state with real progress; never reveal a blank canvas.
- Draw frames to one canvas, cap DPR at 2, and redraw after a debounced resize. Use cover or contain deliberately; do not let the browser’s default sizing decide the crop.
- During loading or partial-cache operation, draw the nearest available frame rather than showing empty space.
- Let one normalized GSAP/ScrollTrigger timeline drive frame index, copy visibility, object scale/crop, and progress. The user must be able to scroll backward through the exact same states.
- Keep mobile composition independent: use the same sequence if suitable, but choose its own crop, copy positions, and shorter pinned distance. Do not force a desktop layout onto a phone.

## Motion and composition

- The object should be a continuous physical presence; text leaves before or while the object moves, and incoming copy uses the space released by it.
- Use transform and opacity for overlays. Avoid bounce, elastic easing, independent step animations, and multiple competing scroll controllers.
- Verify that overlays do not cover the object unintentionally at the key beats. Large editorial type may overlap only as a deliberate art-direction choice.

## Debugging order

1. Add a diagnostic URL or local panel only when the issue cannot be reproduced. Capture renderer, ready state, decoded frames, current frame/time, events, scroll updates, and reduced-motion state.
2. Diagnose the complete path: media loading, decode, canvas draw, stacking/crop, and ScrollTrigger updates. A changed `currentTime` does not prove a video frame has been rendered.
3. After two failed video-scrub hypotheses on iOS, switch to canvas image sequence instead of layering more video fallbacks.
4. Remove diagnostic UI from the normal URL after the issue is resolved; retain it only behind an explicit query parameter when useful.

## Validation

- Check real device or iOS WebKit at the target viewport, including reverse scroll and loading from a cold cache.
- Check desktop and mobile separately for crop, text collisions, first-frame visibility, scroll release, and reduced motion.
- Run the repository’s typecheck, tests, and production build before publishing. Do not claim the motion is fixed based only on code compilation.