Onboarding: wagerfield/parallax

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wagerfield/parallax shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 2y ago

• 6 active contributors
• Other licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wagerfield/parallax repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wagerfield/parallax.

What it runs against: a local clone of wagerfield/parallax — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wagerfield/parallax | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 790 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>wagerfield/parallax</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wagerfield/parallax. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wagerfield/parallax.git
#   cd parallax
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wagerfield/parallax and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wagerfield/parallax(\\.git)?\\b" \\
  && ok "origin remote is wagerfield/parallax" \\
  || miss "origin remote is not wagerfield/parallax (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/parallax.js" \\
  && ok "src/parallax.js" \\
  || miss "missing critical file: src/parallax.js"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "gulpfile.js" \\
  && ok "gulpfile.js" \\
  || miss "missing critical file: gulpfile.js"
test -f "examples/pages/simple.html" \\
  && ok "examples/pages/simple.html" \\
  || miss "missing critical file: examples/pages/simple.html"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 790 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~760d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wagerfield/parallax"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Parallax.js is a lightweight JavaScript library that creates parallax scroll/tilt effects by reacting to device orientation (gyroscope/accelerometer) or mouse cursor position. It transforms DOM elements into layers that shift based on input, enabling depth effects without complex animation frameworks—the core engine in src/parallax.js applies motion transforms to child elements of a container scene. Single-file engine: src/parallax.js exports the main Parallax class (~20KB unminified). Build pipeline via gulpfile.js produces dist/parallax.js and dist/parallax.min.js. Examples/ directory contains 8 HTML demo pages (simple.html, interactive.html, callback.html, etc.) showing different configuration patterns. No monorepo or module splitting—all functionality in one class.

Who it's for

Web developers and designers building interactive websites who want to add parallax depth effects with minimal code; particularly useful for landing pages, portfolios, and mobile-first sites where device tilt should trigger visual responses. Maintainers: Matthew Wagerfield and René Roth.

Maturity & risk

Production-ready and stable. Version 3.1.0 with an established CDN presence on cdnjs, MIT licensed, and archived in multiple distribution formats (compiled, minified, npm). However, the repo shows limited recent activity—no visible commit timestamps in provided data, and the sparse npm script configuration suggests the build tooling (Gulp, Browserify, Babel) reflects pre-2019 standards.

Low technical risk but moderate maintenance risk. Dependencies are minimal (only object-assign and raf for requestAnimationFrame polyfill), reducing supply-chain attack surface. The single-maintainer pattern and legacy build stack (Gulp 3.x, Browserify) create friction for modern contributions. No test suite visible in file list. Browser compatibility and mobile API changes (DeviceOrientationEvent) could break functionality without active monitoring.

Active areas of work

No explicit milestones or active PRs visible in provided data. The repo appears to be in maintenance mode—issues are likely managed on GitHub but not reflected in the file structure. Last documented version is 3.1.0; no pending breaking changes apparent.

Get running

git clone https://github.com/wagerfield/parallax.git && cd parallax && npm install && npm run [task]

Daily commands: package.json has no 'scripts' section defined, so gulp tasks are invoked directly: npx gulp [task]. Likely tasks include 'build', 'watch', 'serve'—check gulpfile.js for available targets. For examples: browser-sync is configured as a dev dependency, so npx browser-sync likely serves examples/ directory on localhost.

Map of the codebase

• src/parallax.js — Core parallax engine—the single source file containing all motion detection, gyroscope/cursor input handling, and DOM manipulation logic; understand this first
• package.json — Entry point definition (main: dist/parallax.js) and build pipeline config; defines what gets published and how
• gulpfile.js — Build orchestration for transpilation (Babel), bundling (Browserify), and CSS preprocessing; required to generate dist output
• examples/pages/simple.html — Minimal working example showing the canonical API usage pattern—start here to understand integration
• README.md — Full API documentation, configuration options, and known issues; essential reference for all feature behavior

Components & responsibilities

• Parallax Constructor (JavaScript ES6, DeviceOrientation API, requestAnimationFrame) — Initializes engine: wires up event listeners, stores config, calibrates baseline orientation, starts animation loop
  • Failure mode: If DeviceOrientation permission denied, falls back silently to mouse tracking; library still functions
• onDeviceOrientation / onMouseMove handlers (Event handling, trigonometry for angle calculations) — Capture raw input (gyroscope or cursor) and update internal motion state (x, y, z angles or cursor coords)
  • Failure mode: Events not fired = no updates; library is inert but does not error
• update() method (CSS transforms, DOM manipulation, floating-point arithmetic) — Main loop: interpolates motion state, calculates new transform offsets per layer, applies CSS transforms to DOM
  • Failure mode: If DOM node is removed, transform assignment becomes a no-op but loop continues (memory safe)
• calibrate() / resetCalibration() (Sensor baseline capture, coordinate geometry) — Establishes baseline orientation/cursor position; subsequent motion is relative to this baseline
  • Failure mode: Without calibration, parallax operates from implicit zero; user must manually move device to see effect

Data flow

• Device (gyroscope / mouse) → onDeviceOrientation() / onMouseMove() — Raw sensor data (alpha/beta/gamma or clientX/clientY) captured from native events
• onDeviceOrientation() / onMouseMove() → Parallax state (this.x, this.y, this.z or cursor coords) — Input processed and stored as internal motion state
• Parallax state → update() method — Current motion state passed to frame-by-frame calculation routine
• update() method → Layer transform calculations — Motion state multiplied by per-layer depth value to compute translate3d offsets
• Transform calculations → DOM element.style.transform — Computed CSS translate3d string applied to each layer element for visual parallax

How to make changes

Add a new configuration option

1. Define the option as a default property in the Parallax constructor (e.g. this.myOption = config.myOption || defaultValue) (src/parallax.js)
2. Implement the logic that uses the option in the appropriate method (e.g. update(), calibrate(), or motion event handler) (src/parallax.js)
3. Document the new option in the Configuration Options section of README.md with type, default, and example usage (README.md)
4. Create an example HTML file in examples/pages demonstrating the new option (examples/pages/[feature_name].html)

Add a new demo page

1. Create a new .html file in examples/pages with standard structure: CDN script tag, container divs with data-depth attributes, and Parallax instantiation (examples/pages/[page_name].html)
2. Use examples/assets/images and examples/assets/styles.scss as reference for layers and styling (examples/assets/styles.scss)
3. Link the new page from the README.md examples section if it demonstrates a key feature (README.md)

Modify motion detection or input handling

1. Locate the relevant input handler in src/parallax.js: onDeviceOrientation() for gyroscope, onMouseMove() for cursor, or constructor DeviceOrientation event listener setup (src/parallax.js)
2. Update the calculation logic that translates input (alpha/beta/gamma or clientX/clientY) to parallax displacement (src/parallax.js)
3. Test against all input modes: run on a physical device (gyroscope), test mouse fallback in desktop browser, and verify the example pages still work (examples/pages/simple.html)

Why these technologies

• DeviceOrientation API (native browser) — Provides gyroscope data on mobile devices for motion-responsive parallax; zero external dependency
• Mouse/Cursor events (fallback) — Desktop browsers lack gyroscope; cursor position provides reasonable approximation of parallax intent
• CSS 3D transforms (translate3d) — Hardware-accelerated, GPU-composited transformations ensure smooth 60fps parallax on mobile
• Babel + Browserify — Transpiles ES6+ to ES5 for broad browser compatibility; bundles single distributable file
• Autoprefixer — Ensures vendor prefixes (-webkit, -moz) on transform properties for cross-browser CSS support

Trade-offs already made

• Single src/parallax.js file (not modularized)

  • Why: Minimizes build output, single CDN bundle, simple API surface
  • Consequence: Code grows monolithic; harder to test individual components; limited code reuse in large projects

• Mouse cursor as gyroscope fallback (not optional)

  • Why: Ensures demo works on desktop without hardware; universal user experience
  • Consequence: Adds latency/jitter on cursor-based systems; may feel unresponsive vs true gyroscope

• No framework dependencies (vanilla JS only)

  • Why: Library works with any HTML/CSS/JS stack; minimal footprint
  • Consequence: Must manually handle DOM selection and event delegation; no declarative rendering

Non-goals (don't propose these)

• Real-time sensor fusion (does not merge gyroscope + accelerometer for enhanced precision)
• Touch input mapping (only supports mouse/cursor and device orientation)
• Animation library (engine is stateless; does not provide keyframes or tweening)
• Framework integration (no React, Vue, Angular adapters; vanilla JS only)

Anti-patterns to avoid

• Polyfill / feature detection in global scope (Medium) — src/parallax.js (likely constructor or top-level code): If library checks for DeviceOrientation API without graceful degradation, it may fail silently on older browsers instead of clearly indicating lack of support
• Tight requestAnimationFrame loop without throttling (Medium) — src/parallax.js (update loop): If the parallax update logic runs at full 60 FPS without throttling high-frequency sensor input, it can cause unnecessary DOM churn and battery drain on mobile
• Mutable config object passed by reference — src/parallax.js (constructor): If constructor stores config object without copying, external modifications to caller's config object after init

Traps & gotchas

1. gulpfile.js uses Gulp 3.x syntax; modern Gulp 4.x code will not run this file without refactoring. 2) No npm scripts defined in package.json—must know gulp task names from gulpfile inspection. 3) .nvmrc present but Node version not stated in README; check file for required version. 4) DeviceOrientationEvent API requires https:// and user permission on iOS 13+—examples on http://localhost may fail on mobile. 5) raf polyfill assumes older browser compatibility; modern environments may not need it. 6) No minified source maps in dist/ if build is stale.

Architecture

Concepts to learn

• Device Orientation API (DeviceOrientationEvent) — Core input source for mobile parallax—gyroscope and accelerometer data drives layer transforms; understanding alpha/beta/gamma angles is essential to modifying input logic
• CSS 3D Transforms (translate3d) — Parallax applies hardware-accelerated 3D transforms to layer elements; knowing translate3d, perspective, and will-change is critical for performance tuning
• requestAnimationFrame (RAF) Loop — Library uses RAF for smooth 60fps animation; the raf polyfill dependency ensures cross-browser animation loop consistency
• Fallback Input Patterns (Gyro → Mouse) — Parallax intelligently falls back from device orientation to mouse cursor position when gyroscope unavailable; understanding this dual-mode input strategy explains layer behavior across desktop/mobile
• Browserify Module Bundling — Build pipeline uses Browserify to wrap a single-file module for both CommonJS (npm) and browser globals; understanding require() syntax and CommonJS exports is necessary to modify build
• Babel ES2015 Transpilation — Source likely uses modern JavaScript (arrow functions, const/let, classes) which Babel transpiles to ES5 for backward compatibility; contributors must understand both source and compiled output
• Parallax Depth Calculation (Layer Multipliers) — Layers move by different amounts based on depth multiplier; understanding how motion data maps to individual layer transform offsets reveals the visual illusion algorithm

Related repos

• jquery-parallax/jquery-parallax — jQuery-based parallax predecessor; similar scroll-based depth effect but tightly coupled to jQuery DOM manipulation
• peachananr/parallax — Alternative vanilla JS parallax library with similar device orientation + mouse input dual-mode design
• CreateJS/TweenJS — Complementary animation library often used alongside parallax for smooth layer transitions and complex motion paths
• Modernizr/Modernizr — Feature detection library helpful for gracefully detecting DeviceOrientationEvent and gyroscope availability across browsers
• threejs/three.js — Heavy-lift 3D alternative when parallax effects need to evolve into full WebGL-rendered scenes with complex geometry

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add build and test scripts to package.json

The package.json has an empty 'scripts' object despite having a gulpfile.js and devDependencies for building (gulp, browserify, babel, uglify). Contributors cannot easily build the project or run tests. Adding standard npm scripts (build, watch, test) would improve developer experience and enable CI/CD integration.

• [ ] Review gulpfile.js to identify the main build task(s)
• [ ] Add 'build' script that runs gulp to compile src/parallax.js to dist/parallax.js
• [ ] Add 'watch' script for development (using browser-sync and gulp watch)
• [ ] Add 'test' script (currently missing - could be placeholder or link to test framework)
• [ ] Document new scripts in README.md section 4.1 (Running the Project)

Add unit tests for src/parallax.js core functionality

The repo has no tests directory or test files despite being a widely-used library. Key features like gyroscope detection, cursor fallback, element selection, and destroy() method need test coverage to prevent regressions and aid future contributors.

• [ ] Choose a test framework (Jest or Mocha + Chai are common for browser libraries)
• [ ] Create tests/parallax.test.js with tests for: initialization with different config options, gyroscope detection fallback to cursor tracking, element selection via selector/input, and destroy() cleanup
• [ ] Test the callback mechanism (referenced in examples/pages/callback.html)
• [ ] Add test runner to package.json scripts
• [ ] Document testing approach in README.md section 4 (Development)

Create GitHub Actions workflow for automated builds and releases

The repo uses an older build stack (Gulp 3, Browserify, Babel ES2015) with no CI validation. Adding a GitHub Action to build on commits and validate the output dist/ directory would catch build regressions and ensure consistent releases to npm.

• [ ] .github/workflows/build.yml: Run 'npm run build' on push/PR to verify src/parallax.js compiles correctly
• [ ] Verify dist/parallax.js and dist/parallax.min.js are generated without errors
• [ ] Add a lint step checking for outdated dependencies (npm outdated) or security vulnerabilities
• [ ] Optional: Add workflow for automated npm publish on tagged releases
• [ ] Add build status badge to README.md

Good first issues

• Add unit tests for src/parallax.js—currently no test suite visible (no test/, spec/, or .test.js files). Start with Jest/Mocha setup testing constructor initialization and transform calculations.: Library lacks test coverage despite being production-grade; contributors cannot safely refactor. This unblocks modernization.
• Migrate gulpfile.js from Gulp 3 to Gulp 4 syntax and update Babel preset from es2015 to @babel/preset-env. Current setup blocks newer Node/npm adoption.: Build tooling is 5+ years outdated; this modernizes the dev experience and enables better tree-shaking in bundles.
• Document iOS 13+ DeviceOrientationEvent permission model in README. Add example or note explaining why examples may fail on mobile and how to request user permission.: Common pain point for new users on iOS; clear docs prevent duplicate issues and improve first-time experience.

Top contributors

• [@René Roth](https://github.com/René Roth) — 90 commits
• @reneroth — 6 commits
• @gndzro — 1 commits
• @extend1994 — 1 commits
• @thehink — 1 commits

Recent commits

• 04e53e9 — Update README.md (reneroth)
• cacad0b — Update README.md (reneroth)
• 14812a1 — Update README.md (reneroth)
• 10b2d84 — Update README.md (reneroth)
• b6b9060 — Update README.md (reneroth)
• d0e1cd5 — Update README.md (reneroth)
• 71a804e — Merge pull request #315 from gndzro/master (René Roth)
• 391c3a4 — Update README.md (gndzro)
• 3c8f770 — Update README.md (René Roth)
• e4b8bc8 — Fix broken link in Readme (René Roth)

Security observations

The parallax-js library has moderate security concerns primarily related to outdated development dependencies from 2017-2018 that likely contain known CVEs. The core library appears to be a client-side DOM manipulation tool with no apparent backend vulnerabilities or hardcoded secrets. The main risks are: (1) vulnerable build tools in the supply chain, (2) potential XSS risks if DOM manipulation isn't properly sanitized, and (3) missing security headers in development server configuration. The library itself is relatively simple (JavaScript-only parallax effects) with minimal attack surface, but the development toolchain should be modernized urgently.

• High · Outdated and Vulnerable Dependencies — package.json - devDependencies. Multiple devDependencies use pinned versions from 2017-2018 that contain known vulnerabilities. Specifically: gulp (^3.9.1) and browserify (^14.0.0) have deprecated versions with CVEs. The babel-preset-es2015 package is deprecated. These tools handle code transformation and bundling, making vulnerable versions a supply chain risk. Fix: Update to the latest versions of all dependencies: gulp (^4.x), browserify (^17.x), babel-preset-env (instead of babel-preset-es2015), and all other tools. Run 'npm audit' and address all reported vulnerabilities.
• Medium · Missing Security Headers Configuration — gulpfile.js (not provided but referenced in package.json). The browser-sync configuration (used for development server) does not show explicit security header configuration. Browser-sync may serve content without proper Content-Security-Policy, X-Frame-Options, or other security headers, potentially exposing users to XSS or clickjacking attacks during development. Fix: Configure browser-sync with appropriate security headers in gulpfile.js. Implement CSP headers to prevent inline script execution and restrict resource loading sources.
• Medium · Potential DOM Manipulation Risk — src/parallax.js. The parallax library manipulates DOM elements based on device orientation/cursor position. Without seeing the source code in src/parallax.js, there's a risk of XSS if user-controlled data is injected into the DOM without sanitization, especially in scenarios where it accepts configuration from untrusted sources. Fix: Review parallax.js for DOM manipulation patterns. Ensure all user-controlled input is properly sanitized before DOM insertion. Use textContent instead of innerHTML when possible. Validate and escape all configuration parameters.
• Low · Deprecated Babel Preset — package.json - devDependencies. babel-preset-es2015 (^6.24.1) is deprecated. The Babel team recommends using babel-preset-env instead, which provides better configuration and maintenance. Fix: Replace babel-preset-es2015 with @babel/preset-env and update babel configuration accordingly.
• Low · Missing .nvmrc Validation — .nvmrc. .nvmrc file exists but no content was provided. If it specifies an outdated Node.js version, it could lead to using versions with security vulnerabilities. Fix: Ensure .nvmrc specifies a currently supported LTS version of Node.js (18.x or 20.x as of 2024). Document the minimum Node.js version requirement in README.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.