# Scrollsmith Free Chrome extension

Scrollsmith Free is a Manifest V3 extension that reskins native website scrollbars. It includes exactly three themes: Minimal, Glass, and Neon.

This phase does not include accounts, payments, premium access, premium website application, a backend, analytics, or remotely downloaded code.

The selector also contains twelve locked Premium previews. They demonstrate future visual directions inside the extension interface only. They cannot be selected or applied to websites.

## Theme architecture

- `themes/base-scrollbar.css` contains shared native scrollbar mechanics and accessibility fallbacks.
- `themes/free/` contains one website theme file per free theme.
- `themes/premium/` contains preview-only CSS. These files are linked by the popup and options page, not by the website content script.
- `shared/theme-catalog.js` contains IDs, names, descriptions, plan classification, light and dark palettes, reduced-motion behavior, browser compatibility, customization limits, and preview metadata.
- `shared/theme-engine.js` validates saved settings, writes customization properties, and refuses any theme that is not marked as website-applicable.

The locked previews are Wave, Liquid, Aurora, Galaxy, Luxury Metal, Pixel Retro, Nature Organic, Cyber Grid, Neon Pulse, Floating Dot, Ribbon, and Signature Experimental.

## Load unpacked in Chrome

1. Open `chrome://extensions` in Chrome.
2. Turn on **Developer mode** in the upper-right corner.
3. Select **Load unpacked**.
4. Choose this `extension` folder, the folder containing `manifest.json`.
5. Pin **Scrollsmith Free** from Chrome's Extensions menu.
6. Reload any website tabs that were open before installation.

Chrome does not allow extensions to change `chrome://` pages or the Chrome Web Store. The scrollbar remains unchanged on those pages.

## Use the extension

- Open the toolbar popup to turn Scrollsmith on or off.
- Select Minimal, Glass, or Neon.
- Adjust width from 8px to 20px.
- Adjust corner radius from 0px to 20px.
- Choose any accent color.
- Use **Disable on this website** to create an exact-hostname exception.
- Select **Manage websites** to reopen disabled sites or adjust settings in a full tab.
- **Reset settings** restores the theme, width, radius, and accent defaults. It does not erase website exceptions.

Settings are stored with `chrome.storage.local`, so they remain after browser restarts but stay on this Chrome installation. The extension does not operate its own server.

## Permissions and privacy

The extension requests:

- `storage`: saves the enabled state, selected theme, dimensions, accent color, and disabled hostnames on this Chrome installation.
- `activeTab`: lets the popup identify the current hostname after you deliberately open the extension.
- Website matching for HTTP and HTTPS pages: loads the content script that applies native scrollbar CSS.

The content script does not read page text, images, forms, browsing history, keystrokes, wheel events, or scroll position. It does not send data anywhere.

## Native scrolling guarantee

The content script adds a single style element containing native scrollbar CSS. It does not listen for scroll, wheel, touch, pointer, or keyboard events. It does not set `scrollTop`, call `scrollTo`, or replace the browser's scrolling physics.

Mouse wheels, trackpads, keyboard scrolling, and touch continue to use the browser's native behavior.

## Validate locally

With Node.js installed, run this command from the `extension` folder:

```powershell
node .\tests\validate-extension.mjs
```

For the basic page test, start any local static server that can serve the repository, open `tests/fixtures/basic-page.html`, then reload the page after installing the extension.

## Manual test checklist

1. Open a long page and confirm wheel and trackpad scrolling feel unchanged.
2. Use Page Up, Page Down, Home, End, Space, Shift and Space, and arrow keys.
3. Switch through all three themes.
4. Adjust width, radius, and accent color.
5. Reload the page and restart Chrome to confirm persistence.
6. Turn the global switch off and on.
7. Disable the current website, reload, and confirm the native appearance returns.
8. Open **Manage websites**, re-enable the hostname, and reload.
9. Repeat on Google Search, YouTube, GitHub, Reddit, and the included static fixture.
10. Test a light page and a dark page.
11. Enable the operating system's reduced-motion preference and repeat the tests.

## Known limitations

- Chromium scrollbar pseudo-elements are non-standard. Firefox supports only coarse `scrollbar-width` and `scrollbar-color` values, though this Chrome package targets Chromium.
- Operating systems configured to hide overlay scrollbars may hide them until scrolling begins.
- Some websites apply stronger scrollbar styles after the content script runs. Scrollsmith uses `!important`, but browser or shadow-root isolation can still win.
- Closed shadow roots cannot be styled from a normal content script.
- Cross-origin frames are styled only when Chrome permits the content script to run in that frame.
- Exact-hostname exceptions treat `www.example.com` and `example.com` as different websites.
- Glass is a native CSS approximation. Native scrollbar thumbs do not support true background blur or physical refraction.
- Animated particles, unusual silhouettes, and overlay effects are intentionally excluded from this phase. Implementing them reliably on arbitrary websites would require a more complex custom visual layer.