From 24ae68aa21d2ffca101badcd8dd973c324567dd5 Mon Sep 17 00:00:00 2001 From: TristanEDU Date: Fri, 30 May 2025 05:44:44 -0700 Subject: [PATCH] feat: initial working release with draggable overlay panel and full UI controls - Added iframe overlay with customizable source URL - Included opacity slider for pixel-perfect comparison - Implemented color inversion toggle - Added scroll lock for accurate layout preservation - Removed iframe scrollbars to avoid layout shifts - Built draggable control panel with dedicated handle - Added README.md with usage, warnings, and contribution guide - Created LICENSE (MIT) and CHANGELOG.md for version tracking --- CHANGELOG.md | 31 +++++++++++++++ LICENSE.txt | 21 ++++++++++ README.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 153 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e69de29..c8e9d14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -0,0 +1,31 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +This project adheres to [Semantic Versioning](https://semver.org/). + +--- + +## [1.0.0] – 2025-05-29 + +### Added + +- Initial working release +- Overlay iframe with customizable URL +- Opacity slider +- Invert color toggle +- Disable scrolling toggle +- Hidden iframe scrollbars for pixel accuracy +- Draggable control panel with dedicated handle + +--- + +## [Unreleased] + +### Planned + +- Persistent settings using chrome.storage +- Minimize/collapse control panel +- Overlay snapping grid / guide ruler +- Toggle overlay visibility with keyboard shortcut +- Export/import preset overlay configs diff --git a/LICENSE.txt b/LICENSE.txt index e69de29..f44abe2 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Tristan Thomas + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the “Software”), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 8c85de2..1ecab60 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,107 @@ # LiveOverlayExtension -A Chrome extension that overlays one live website over another for pixel-perfect comparison. +A Chrome extension for pixel-perfect visual comparison of two **live websites**. This tool is ideal for frontend developers, designers, and QA testers who need to overlay a staging or production site directly on top of another to validate layout accuracy, design drift, or content alignment — all in real time. -## Features +--- -- Overlays a live site via iframe -- Adjustable opacity via slider +## 🔧 Features -## Usage +- ✅ Live iframe overlay of any URL +- 🎚️ Adjustable opacity slider for visual blending +- 🌐 Custom overlay URL input for flexible comparisons +- 🌗 Invert colors toggle to aid visibility +- 🔒 Disable scrolling on the base site to freeze layout +- 🧱 Overlay iframe uses hidden scrollbars to prevent layout shift +- 🖱️ Draggable floating control panel (non-intrusive, lightweight) -1. Load the extension in Chrome (Developer Mode) -2. Visit your dev site -3. The overlay will appear automatically +--- + +## 🚀 Installation & Usage + +### 1. Clone this repo: + +```bash +git clone https://github.com/TristanEDU/LiveOverlayExtension.git +cd LiveOverlayExtension +``` + +### 2. Load in Chrome: + +1. Open Chrome and go to `chrome://extensions/` +2. Enable **Developer Mode** +3. Click **Load unpacked** +4. Select the `LiveOverlayExtension` directory + +### 3. Usage Instructions + +- Navigate to any site (e.g., your dev or test environment) +- The floating control panel will appear in the top-right corner +- Enter the overlay URL (e.g. your staging or production version) +- Adjust opacity, lock scrolling, or invert colors for better contrast +- Drag the control panel wherever you like for convenience + +--- + +## ⚠️ Important Warnings & Limitations + +### ❌ Iframe Restrictions + +Many websites (especially large platforms or secure systems) use headers like `X-Frame-Options: DENY` or CSP rules like `frame-ancestors 'none'`, which **prevent them from being embedded** in an iframe. + +If you attempt to overlay a site that blocks iframing, you’ll see this in the Chrome Console: + +``` +Refused to display 'https://example.com' in a frame because it set 'X-Frame-Options' to 'DENY'. +``` + +**✅ Recommended workaround:** +Use this tool in environments you control (dev/staging), and temporarily disable these headers during QA review. + +### 🔐 Security Notice + +This extension disables pointer events on the overlay for safety and overlays URLs in read-only mode. However: + +- You should **never enter passwords, API keys, or sensitive content** into the overlayed page +- The overlay is rendered but not sandboxed — treat it as real browser content +- Do not use on high-security internal systems without explicit authorization + +--- + +## 👥 Collaborators + +| Name | GitHub Username | Role | +| -------------- | ---------------------------------------------- | ------------------------ | +| Tristan Thomas | [`@TristanEDU`](https://github.com/TristanEDU) | Creator & Lead Developer | + +--- + +## 🤝 Contribution Guidelines + +We welcome clean, well-documented contributions that enhance the tool’s functionality or usability. + +### ✅ To Contribute: + +1. **Fork the repo** +2. **Create a feature branch**: + ```bash + git checkout -b feature/your-feature + ``` +3. **Write clear, maintainable code** +4. **Test on multiple pages and overlay URLs** +5. **Submit a pull request**, including: + - Summary of what you changed + - Screenshots (if UI-related) + - Why the change improves the tool + +### 🛠️ Development Principles + +- Use vanilla JavaScript only (no dependencies) +- Keep UI simple and minimal +- Maintain compatibility with all Chromium-based browsers +- Focus on developer experience and visual fidelity + +--- + +## 📄 License + +**MIT License** — free to use, modify, and distribute. Attribution appreciated.