Easter Eggs Integration
Relevant source files
The following files were used as context for generating this wiki page:
Easter eggs integration provides hidden, interactive experiences within the website triggered by specific keyboard sequences or the command palette. The system manages the discovery, state persistence, and visual styling of these "eggs," which include thematic transformations like the Hyrule, Aurora, and Lamp modes.
Sources: src/components/EasterEggs/easter-eggs.ts:1-25
System Architecture
The Easter Egg system operates as a centralized manager that tracks user keyboard input and matches it against predefined sequences. It handles the lifecycle of an egg from initialization to dismissal, coordinating sound effects, persistent storage, and dynamic CSS loading.
Core Components and Logic
The system utilizes an Egg type to define the behavior and requirements of each easter egg.
The manager maintains a progressById map to track how many keys of a specific sequence a user has correctly entered.
Sources: src/components/EasterEggs/easter-eggs.ts:27-46
Data Flow and Input Handling
The system listens for keydown events on the document. It ignores input if the user is typing in a form field, has a dialog open, or uses modifier keys like Ctrl or Meta.
The advanceProgress function checks if the current keypress continues the sequence for any registered egg. If a sequence is completed, the egg is toggled or cycled.
Sources: src/components/EasterEggs/easter-eggs.ts:182-205, src/components/EasterEggs/easter-eggs.ts:314-329
State Management and Persistence
The system persists discovered and active easter eggs using browser local storage. This ensures that an active egg remains visible across page navigations and site visits.
| Storage Key | Description |
|---|---|
easterEggPrefix | Prefix used for the specific ID of the currently active egg. |
easterEggFound | A JSON array of strings containing IDs of eggs the user has discovered. |
easterEggCycle | An integer representing the current index in the egg rotation. |
Sources: src/components/EasterEggs/easter-eggs.ts:11-20, src/components/EasterEggs/easter-eggs.ts:145-155
When the site loads, restoreEgg checks storage for an active egg ID. If found, it re-activates the egg and marks it as "found" in the user's discovery list.
Sources: src/components/EasterEggs/easter-eggs.ts:275-288
Command Palette Integration
The command palette provides a secondary interface for managing discovered easter eggs. Users can view their progress and toggle discovered eggs through a "Secrets" view within the palette.
Secrets Discovery
The command palette tracks how many eggs have been found versus the total available. It uses getFoundEasterEggIds to filter which eggs are visible to the user in the UI.
Visual Implementation
Active easter eggs are applied by setting a data-easter-egg attribute on the <html> element. This attribute allows scoped CSS to transform the entire site's appearance.
Hyrule Mode
The Hyrule egg (id: 'hyrule') transforms the site into a retro-gaming theme. It replaces system fonts with "Press Start 2P" and changes the cursor to a sword icon. It also applies a pixelation filter to images and landscapes.
Sources: src/components/EasterEggs/eggs/hyrule.css:10-40
Lamp Mode
The Lamp egg (id: 'lamp') creates a dark "veil" over the site with a radial gradient "glow" that follows the cursor. This mode also displays a specific scripture verse centered on the screen, visible only through the cursor's glow.
Sources: src/components/EasterEggs/eggs/lamp.css:1-25, src/components/EasterEggs/eggs/lamp.css:126-150
Testing and Identification
The project uses specific naming conventions for test IDs to ensure reliable end-to-end testing of easter egg features.
| Feature | Test ID Pattern |
|---|---|
| Egg Button | command-palette-egg-{id} |
| Secrets Footer | command-palette-secrets-footer |
| Secrets List | command-palette-secrets |
Sources: e2e/constants.ts:10-30, e2e/constants.ts:40-42
Summary
The Easter Eggs Integration is a robust system for handling hidden interactive content. It combines sequence-based keyboard triggers with command palette accessibility. By utilizing centralized state management and scoped CSS via data attributes, it provides immersive thematic changes while maintaining performance through dynamic style loading and persistent local storage.
Sources: src/components/EasterEggs/easter-eggs.ts:1-10, src/components/CommandPalette/command-palette.ts:310-330