@profpowell/screen-saver

v1.1.1

Published

3 months ago

A vanilla JavaScript web component that displays retro screen saver effects after idle timeout

0High
0Medium
0Low

tpowell2

web-component custom-element screensaver screen-saver retro animation

<screen-saver>

A vanilla JavaScript web component that displays retro screen saver effects after idle timeout.

Features

Zero dependencies - pure vanilla JavaScript
Three built-in effects: bounce3d, matrix, ascii-glitch
Automatic idle detection with configurable timeout
Custom effect registration API
Full CSS custom property support
Respects prefers-reduced-motion
TypeScript definitions included

Installation

npm install @profpowell/screen-saver

Or use via CDN:

<script type="module" src="https://unpkg.com/@profpowell/screen-saver/dist/screen-saver.js"></script>

Usage

<screen-saver timeout="180" effect="bounce3d">
  Your Text Here
</screen-saver>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | timeout | number | 180 | Idle delay in seconds | | effect | string | "bounce3d" | Effect name | | speed | number | 1 | Animation speed multiplier | | background | string | - | Background color or image URL | | palette | string | "rainbow" | Palette mode: rainbow keeps built-in colors; theme cycles through VB tokens |

Available Effects

bounce3d (default)

Classic bouncing 3D extruded text with color cycling on edge bounces.

matrix

Matrix-style falling character rain with your text glowing in the center.

ascii-glitch

Glitchy ASCII effect with random character corruption and chromatic aberration.

bauhaus

Primitive shapes (circle, square, triangle) drifting in primary colors. Designed for the VB bauhaus theme.

memphis

Squiggles, dots, zigzags, and confetti triangles drifting and spinning. No text required. Designed for the VB memphis theme.

art-deco

Symmetrical radiating arcs with slow inhale/exhale scaling. Designed for the VB art-deco theme.

brutalist

Loud blocks of monospace text snapping into grid cells, occasional inverted blocks. Designed for the VB brutalist theme.

kawaii

Pastel sprites (hearts, stars, sparkles, clouds) floating upward and fading. No text required. Designed for the VB kawaii theme.

API

const el = document.querySelector('screen-saver');

// Programmatic control
el.activate();    // Start the screen saver
el.deactivate();  // Stop the screen saver
el.isActive;      // Check if active (readonly)

// Properties
el.timeout = 300;        // Set timeout
el.effect = 'matrix';    // Change effect
el.speed = 1.5;          // Adjust speed

Events

el.addEventListener('screensaver-activate', () => {
  console.log('Screen saver started');
});

el.addEventListener('screensaver-deactivate', (e) => {
  console.log(`Active for ${e.detail.duration}ms`);
});

CSS Custom Properties

screen-saver {
  --screen-saver-bg: rgba(0, 0, 0, 0.95);
  --screen-saver-text-color: #00ff00;
  --screen-saver-font-family: 'Arial Black', sans-serif;
  --screen-saver-font-size: 4rem;
  --screen-saver-z-index: 999999;
}

Using with Vanilla Breeze

<screen-saver> reads Vanilla Breeze design tokens (--color-primary, --color-text, --font-sans, etc.) when no --screen-saver-* override is set. Apply a VB theme to the page and the screensaver inherits it:

<html data-theme="bauhaus">
  <screen-saver effect="bauhaus">Hello</screen-saver>
</html>

To make JS-driven palette effects (bounce3d, fireworks, bubbles, pipes, mystify, plasma) cycle through VB tokens instead of their built-in rainbow palettes, opt in with palette="theme":

<screen-saver effect="bounce3d" palette="theme">Hello</screen-saver>

For the full integration contract — tokens consumed, recommended theme pairings, reduced-motion contract — see admin/handoffs/screen-saver-integration.md in the Vanilla Breeze repo.

Custom Effects

import { ScreenSaver, Effect } from 'screen-saver';

class MyEffect extends Effect {
  start() {
    // Create your effect in this.container
    // Use this.text for the slot content
    // Use this.speed for animation speed
    // Check this.reducedMotion for accessibility
  }

  stop() {
    super.stop(); // Cancels requestAnimationFrame
  }

  destroy() {
    super.destroy(); // Full cleanup
  }
}

ScreenSaver.registerEffect('my-effect', MyEffect);

Development

npm install          # Install dependencies
npm run dev          # Start dev server
npm run build        # Build for production
npm run test         # Run tests

License

MIT