easter-egg-quest 1.0.0

package/dist/types/GameController.d.ts

@@ -0,0 +1,67 @@
+import type { ResolvedConfig, NarrativeScript } from './types';
+/**
+ * GameController — orchestrates the entire Easter Egg Quest experience.
+ *
+ * Manages the lifecycle: initialization → hidden entry → 3 stages → finale → results.
+ * Coordinates between renderers, input tracker, stage logic, and scoring.
+ */
+export declare class GameController {
+    private config;
+    private script;
+    private bus;
+    private fsm;
+    private input;
+    private scoring;
+    private persistence;
+    private hiddenEntry;
+    private narrative;
+    private hud;
+    private shrine;
+    private threeRenderer;
+    private fallbackRenderer;
+    private overlay;
+    private results;
+    private eggRenderer;
+    private activeStage;
+    private pageReactor;
+    private _lastPageReactTime;
+    private _lastReactProgress;
+    private pageBreather;
+    private state;
+    private _updateRaf;
+    private _running;
+    private _destroyed;
+    private _onPageHide;
+    constructor(config: ResolvedConfig, script: NarrativeScript);
+    init(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    restart(): Promise<void>;
+    destroy(): void;
+    private _handlePageClose;
+    private _onTransition;
+    private _saveCheckpoint;
+    private _resumeFromCheckpoint;
+    private _startEntry;
+    private _onEntryFound;
+    private _tremorStyle;
+    private _tremorClass;
+    private _startAnticipationTremor;
+    private _stopAnticipationTremor;
+    private _startStage1;
+    private _startStage2;
+    private _startStage3;
+    private _startGameLoop;
+    private _lastFrameTime;
+    private _gameLoop;
+    private _handleEggReveal;
+    private _handleStageSuccess;
+    private _onShrineEggClick;
+    private _onEggLongPressCollect;
+    private _handleStageProgress;
+    private _startFinale;
+    private _showResults;
+    private _initEggRenderer;
+    private _cleanup;
+    private _wait;
+}

package/dist/types/config.d.ts

@@ -0,0 +1,5 @@
+import type { EasterEggQuestConfig, ResolvedConfig, NarrativeScript } from './types';
+export declare const DANGEROUS_KEYWORDS: string[];
+export declare const DEFAULT_EXCLUDE_SELECTORS: string[];
+export declare function resolveConfig(raw?: EasterEggQuestConfig): ResolvedConfig;
+export declare function resolveNarrative(overrides?: Partial<NarrativeScript>): NarrativeScript;

package/dist/types/core/EventBus.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal typed event bus for internal library communication.
+ * Not exposed to integrators — they use config.callbacks instead.
+ */
+export declare class EventBus {
+    private listeners;
+    on(event: string, fn: (...args: any[]) => void): void;
+    off(event: string, fn: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+    clear(): void;
+}

package/dist/types/core/StateMachine.d.ts

@@ -0,0 +1,22 @@
+import type { GameStage } from '../types';
+/**
+ * Finite state machine governing the game's stage progression.
+ * Transitions are strictly defined — invalid transitions are rejected.
+ */
+type TransitionCallback = (from: GameStage, to: GameStage) => void;
+export declare class StateMachine {
+    private _state;
+    private _onTransition;
+    get state(): GameStage;
+    /** Register a callback invoked on every valid transition. */
+    onTransition(cb: TransitionCallback): void;
+    /** Attempt a transition. Returns true if valid, false otherwise. */
+    transitionTo(next: GameStage): boolean;
+    /** Force-reset to idle (used for restart / destroy). */
+    reset(): void;
+    /** Force state to a specific value (used for resuming from checkpoint). */
+    forceState(state: GameStage): void;
+    /** Human-readable label for the current stage. */
+    get label(): string;
+}
+export {};

package/dist/types/entry/HiddenEntry.d.ts

@@ -0,0 +1,43 @@
+import type { NarrativeScript, ResolvedConfig } from "../types";
+/**
+ * Stage 0: Hidden Entry system.
+ *
+ * Two strategies, randomly chosen:
+ *  1. "Possess" — picks an existing safe element and enchants it with shimmer
+ *  2. "Disguise" — injects a camouflaged fake element styled to look like
+ *     a neighboring button/link/nav item on the page
+ *
+ * Escalating narrative hints guide the user toward noticing it.
+ * Clicking triggers the game.
+ */
+export declare class HiddenEntry {
+    private config;
+    private script;
+    private onFound;
+    private targetElement;
+    private hintTimers;
+    private hintIndex;
+    private hintContainer;
+    private shimmerStyle;
+    private clickHandler;
+    private fallbackButton;
+    private _injectedElement;
+    private _destroyed;
+    constructor(config: ResolvedConfig, script: NarrativeScript, onFound: () => void);
+    start(): void;
+    cleanup(): void;
+    private _possessElement;
+    private _injectIntoExisting;
+    /**
+     * Try to insert the trigger span between words inside a text node.
+     * Picks a random word boundary in the element's first direct text node.
+     * Returns true if inserted without layout shift.
+     */
+    private _tryInsertBetweenWords;
+    private _attachToElement;
+    private _startHintEscalation;
+    private _showHint;
+    private _createHintContainer;
+    private _injectShimmerStyles;
+    private _createFallbackEntry;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Easter Egg Quest — Public API
+ *
+ * This is the main entry point for both npm and CDN usage.
+ *
+ * npm:
+ *   import { EasterEggQuest } from 'easter-egg-quest';
+ *   EasterEggQuest.init({ ... });
+ *
+ * CDN:
+ *   <script src="easter-egg-quest.umd.js"></script>
+ *   <script> EasterEggQuest.init({ ... }); </script>
+ */
+import type { EasterEggQuestConfig, FinalScore, LeaderboardAdapter, LeaderboardEntry } from './types';
+export declare const EasterEggQuest: {
+    /**
+     * Initialize and start the Easter Egg Quest experience.
+     * Safe to call multiple times — destroys any previous instance first.
+     */
+    init(config?: EasterEggQuestConfig): Promise<void>;
+    /** Pause the game. */
+    pause(): void;
+    /** Resume the game. */
+    resume(): void;
+    /** Restart from the beginning. */
+    restart(): Promise<void>;
+    /** Destroy the instance, remove all overlays, restore DOM. */
+    destroy(): void;
+};
+export type { EasterEggQuestConfig, FinalScore, LeaderboardAdapter, LeaderboardEntry, };

package/dist/types/input/InputTracker.d.ts

@@ -0,0 +1,55 @@
+import type { InputSnapshot, MovementPhase } from '../types';
+/**
+ * Tracks all user input — mouse, touch, keyboard, scroll — and provides
+ * a real-time snapshot plus movement-phase history for rhythm analysis.
+ *
+ * Designed to be non-intrusive: uses passive listeners and never
+ * prevents default on host-page events.
+ */
+export declare class InputTracker {
+    private _snapshot;
+    /** Completed move/still phases for rhythm analysis. */
+    private _phases;
+    /** Current phase tracking. */
+    private _currentPhaseType;
+    private _currentPhaseStart;
+    /** Movement velocity tracking. */
+    private _prevX;
+    private _prevY;
+    private _prevMoveTs;
+    /** How long without movement before we consider user "still". */
+    private readonly STILL_THRESHOLD_MS;
+    /** Minimum phase duration to record (ignore micro-jitter). */
+    private readonly MIN_PHASE_MS;
+    /** Timer for detecting stillness transitions. */
+    private _stillTimer;
+    /** Bound handlers (for clean removal). */
+    private _handlers;
+    private _active;
+    get snapshot(): InputSnapshot;
+    get phases(): MovementPhase[];
+    /** How long the user has been continuously still (ms). Returns 0 if moving. */
+    get stillDuration(): number;
+    /** How long the user has been continuously moving (ms). Returns 0 if still. */
+    get moveDuration(): number;
+    /** Time since any recorded activity. */
+    get timeSinceLastActivity(): number;
+    start(): void;
+    stop(): void;
+    /** Reset phase history (e.g., between stages). */
+    resetPhases(): void;
+    resetCounts(): void;
+    /** Page hidden/visible — reset stillness so off-tab time doesn't count. */
+    private _onVisibilityChange;
+    /** Window blur (alt-tab, click outside) — same reset. */
+    private _onWindowBlur;
+    private _onPointerMove;
+    private _onTouchMove;
+    private _onClick;
+    private _onActivity;
+    private _onScroll;
+    private _onKeyDown;
+    private _registerMove;
+    private _becomeStill;
+    private _completePhase;
+}

package/dist/types/narrative/Script.d.ts

@@ -0,0 +1,7 @@
+import type { NarrativeScript } from '../types';
+/**
+ * Default narrative script. All lines are in English.
+ * Every array is sequenced: lines are shown one after another with pauses.
+ * Integrators can override any key via config.narrative.
+ */
+export declare const DEFAULT_SCRIPT: NarrativeScript;

package/dist/types/rendering/FallbackRenderer.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedConfig } from '../types';
+/**
+ * FallbackRenderer — CSS-based 2D egg rendering when Three.js is unavailable.
+ *
+ * Uses CSS gradients, pseudo-elements, and transforms to create stylized
+ * egg shapes with animations. Not as premium as Three.js but graceful.
+ */
+export declare class FallbackRenderer {
+    private config;
+    private host;
+    private shadow;
+    private container;
+    private eggs;
+    private _finaleActive;
+    constructor(config: ResolvedConfig);
+    init(): Promise<boolean>;
+    startRenderLoop(): void;
+    stopRenderLoop(): void;
+    revealEgg(index: number): void;
+    collectEgg(index: number): void;
+    addTrail(x: number, y: number, _velocity: number): void;
+    startFinale(): void;
+    setBreathIntensity(_intensity: number): void;
+    setOverlayIntensity(_progress: number): void;
+    destroy(): void;
+    private _getStyles;
+}

package/dist/types/rendering/HUDRenderer.d.ts

@@ -0,0 +1,28 @@
+import type { ResolvedConfig, GameState } from '../types';
+/**
+ * Minimal HUD showing eggs found, elapsed time, and current stage.
+ * Rendered inside a Shadow DOM host for style isolation.
+ */
+export declare class HUDRenderer {
+    private config;
+    private host;
+    private shadow;
+    private eggsEl;
+    private timeEl;
+    private stageEl;
+    private _timerInterval;
+    private _startTime;
+    private _paused;
+    private _pauseOffset;
+    constructor(config: ResolvedConfig);
+    mount(): void;
+    startTimer(): void;
+    pause(): void;
+    resume(): void;
+    /** Update displayed values. */
+    update(state: GameState, stageLabel: string): void;
+    /** Briefly flash an egg-found notification. */
+    flashEggFound(index: number): void;
+    destroy(): void;
+    private _getStyles;
+}

package/dist/types/rendering/NarrativeRenderer.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedConfig } from '../types';
+/**
+ * Renders poetic narrative text as floating, fading overlays.
+ *
+ * Text appears by fading in with a slight blur resolve and gentle upward drift.
+ * Each new line replaces the previous after a graceful transition.
+ * All elements are injected into a Shadow DOM host to isolate styles.
+ */
+export declare class NarrativeRenderer {
+    private config;
+    private host;
+    private shadow;
+    private container;
+    private currentLine;
+    private clearTimer;
+    constructor(config: ResolvedConfig);
+    mount(): void;
+    /** Show a single narrative line. Fades in, replaces any previous line. */
+    showLine(text: string, className?: string): void;
+    /** Show a sequence of lines with pauses. */
+    showSequence(lines: string[], pauseMs?: number): Promise<void>;
+    /** Show a celebratory line with golden styling. */
+    showCelebration(text: string): void;
+    /** Clear current narrative text. */
+    clear(): void;
+    /** Remove all DOM. */
+    destroy(): void;
+    private _getStyles;
+}

package/dist/types/rendering/OverlayManager.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedConfig } from '../types';
+/**
+ * OverlayManager — manages the semi-transparent backdrop layer
+ * that sits between the host site and the game UI. Controls dim,
+ * blur, and vignette effects during gameplay.
+ */
+export declare class OverlayManager {
+    private config;
+    private overlay;
+    private _visible;
+    constructor(config: ResolvedConfig);
+    mount(): void;
+    /** Fade in the overlay. */
+    show(): void;
+    /** Adjust overlay intensity for visual softening (0–1). */
+    setIntensity(progress: number): void;
+    /** Fade out the overlay. */
+    hide(): void;
+    destroy(): void;
+}

package/dist/types/rendering/PageBreather.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PageBreather — guides the user to find a move/pause rhythm.
+ *
+ * A vignette overlay pulses on its own steady cycle (~6s):
+ *   - "move" half: vignette fades away (bright = move!)
+ *   - "pause" half: vignette darkens edges (dark = be still!)
+ *
+ * When the user syncs with the rhythm, the effect intensifies as positive feedback
+ * and `inSync` becomes true (checked via `isInSync()`).
+ */
+export declare class PageBreather {
+    private _active;
+    private _intensity;
+    private _targetIntensity;
+    private _rafId;
+    private _overlay;
+    private _startTime;
+    private _isUserMoving;
+    private _inSync;
+    /** Full breath cycle duration in ms (move half + pause half). */
+    private readonly CYCLE_MS;
+    start(): void;
+    update(accuracy: number, isMoving: boolean): void;
+    /** Whether the user is currently in sync with the breathing rhythm. */
+    isInSync(): boolean;
+    stop(): void;
+    destroy(): void;
+    private _tick;
+}

package/dist/types/rendering/PageReactor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * PageReactor — subtly animates real page elements as positive feedback.
+ *
+ * When the user is on the right track (progress increasing), nearby page
+ * elements react with gentle pulses, glows, and lifts — creating the feeling
+ * that the world around them is responding.
+ */
+export declare class PageReactor {
+    private _styleEl;
+    private _reactClass;
+    constructor();
+    /** Trigger a reaction wave on 2-4 random visible page elements. */
+    react(): void;
+    destroy(): void;
+    private _findCandidates;
+    private _pickRandom;
+    private _injectStyles;
+}

package/dist/types/rendering/ResultsRenderer.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedConfig } from '../types';
+import type { FinalScore } from '../types';
+/**
+ * ResultsRenderer — premium results card with type-accurate egg tray.
+ * Eggs match their 3D counterparts: silver (polka dots), gold (ornate), festive (enamel).
+ * Unfound eggs shown as elegant dashed outlines.
+ */
+export declare class ResultsRenderer {
+    private config;
+    private host;
+    private shadow;
+    private _onFinish;
+    /** Egg type palettes matching ThreeRenderer textures. */
+    private static readonly EGG_PALETTES;
+    constructor(config: ResolvedConfig);
+    show(score: FinalScore, onFinish: () => void): void;
+    destroy(): void;
+    private _buildContent;
+    private _makeRand;
+    /** Draw a type-accurate egg on canvas. eggIdx: 0=silver, 1=gold, 2=festive. */
+    private _drawTypedEgg2D;
+    /** Egg path helper — builds egg-shaped path. */
+    private _eggPath;
+    /** Dashed or solid egg outline. */
+    private _drawEggOutline;
+    /** Specular highlight on top-left of egg. */
+    private _drawSpecular;
+    /** Silver egg — cool chrome gradient with white polka dots and metallic sheen. */
+    private _paintSilverEgg;
+    /** Gold egg — warm yellow gradient, horizontal ornate bands, diamond lattice. */
+    private _paintGoldEgg;
+    /** Festive Fabergé egg — seeded enamel bands + golden dividers + gem dots. */
+    private _paintFestiveEgg;
+    private _copyShareImage;
+    private _downloadBlob;
+    private _renderCard;
+    private _roundRect;
+    private _flashButton;
+    private _escapeHtml;
+    private _getStyles;
+}

package/dist/types/rendering/ShrineRenderer.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedConfig } from '../types';
+/**
+ * Shrine / Trophy area — shows 3 egg slots.
+ * Found eggs appear filled, uncollected ones show as outline placeholders.
+ * Active (just-found) egg can pulse before click-to-continue.
+ *
+ * Rendered inside a Shadow DOM host for style isolation.
+ */
+export declare class ShrineRenderer {
+    private config;
+    private host;
+    private shadow;
+    private slots;
+    private _activeSlot;
+    private _onEggClick;
+    constructor(config: ResolvedConfig);
+    mount(onEggClick: (index: number) => void): void;
+    /** Fade in the shrine. Call after entry is found. */
+    show(): void;
+    /** Mark an egg slot as found (filled). */
+    fillSlot(index: number): void;
+    /** Activate a slot for click-to-continue (pulsing). */
+    activateSlot(index: number): void;
+    /** Deactivate the active slot. */
+    deactivateSlot(index: number): void;
+    /** Animate all eggs leaving the shrine (for finale). */
+    hideAll(): void;
+    /** Show all slots again (for reset). */
+    reset(): void;
+    destroy(): void;
+    private _getStyles;
+}

package/dist/types/rendering/ThreeRenderer.d.ts

@@ -0,0 +1,147 @@
+import type { ResolvedConfig } from '../types';
+/**
+ * Three.js-based 3D Easter egg renderer — premium, wow-factor edition.
+ *
+ * Each egg is a unique, beautiful Easter egg with decorative ornaments,
+ * premium PBR materials, and increasingly elaborate ornamentation.
+ *
+ * - Egg 1: Polished silver with chrome shader reflections — elegant & pure
+ * - Egg 2: Rich 24k gold with baroque shader patterns — opulent & warm
+ * - Egg 3: Royal Fabergé with multicolor enamel & gem shader — ultimate prize
+ *
+ * Features:
+ * - Spectacular reveal animations with particle bursts
+ * - User can drag/rotate the won egg interactively
+ * - Long-press on egg to collect it (hold-to-absorb with visual ring)
+ * - Ambient progress particles for stage feedback
+ */
+export declare class ThreeRenderer {
+    private config;
+    private canvas;
+    private THREE;
+    private renderer;
+    private scene;
+    private camera;
+    private eggs;
+    private eggBodies;
+    private lights;
+    private _raf;
+    private _running;
+    private _reducedMotion;
+    private _clock;
+    private _eggStates;
+    private _finaleActive;
+    private _finaleT;
+    private _greetingOverlay;
+    private _trailParticles;
+    private _ambientParticles;
+    private _revealParticles;
+    private _disposed;
+    private _interactiveEgg;
+    private _isDragging;
+    private _dragStartX;
+    private _dragStartY;
+    private _dragRotX;
+    private _dragRotY;
+    private _dragMoved;
+    private _longPressStartTime;
+    private _longPressActive;
+    private _holdProgress;
+    private _holdRing;
+    private _holdShockwave;
+    private _miniEggs;
+    private _collectLight;
+    private _onCollectEgg;
+    private _vortexParticles;
+    private _emberParticles;
+    private _collectFlashOpacity;
+    private _collectShake;
+    private _collectCamBaseZ;
+    constructor(config: ResolvedConfig);
+    /** Set callback for when user completes long-press collect. */
+    onCollectEgg(cb: (index: number) => void): void;
+    init(): Promise<boolean>;
+    startRenderLoop(): void;
+    stopRenderLoop(): void;
+    /** Make an egg interactively draggable. */
+    enableInteraction(index: number): void;
+    /** Disable drag interaction. */
+    disableInteraction(): void;
+    /** Trigger spectacular egg reveal. */
+    revealEgg(index: number): void;
+    /** Collect egg — hide immediately (mini-egg burst already happened during hold). */
+    collectEgg(index: number): void;
+    /** Reset renderer state for game restart (preserves WebGL context). */
+    resetForRestart(): void;
+    /** Add a luminous motion trail at screen coordinates. */
+    addTrail(x: number, y: number, velocity: number): void;
+    /** Spawn gentle ambient particles to show stage progress. */
+    showProgressParticles(progress: number): void;
+    /** Start the finale composition. */
+    startFinale(): void;
+    /** Re-draw the festive (3rd) egg texture with a specific seed for uniqueness. */
+    setFestiveEggSeed(seed: number): void;
+    setBreathIntensity(intensity: number): void;
+    setOverlayIntensity(_progress: number): void;
+    destroy(): void;
+    private _setupLights;
+    private _setupEnvironment;
+    private _createEggs;
+    /** Create a tiny egg-shaped geometry (same squash as main eggs, lower poly). */
+    private _createMiniEggGeo;
+    /** Create a minimalist randomly-decorated mini egg material. */
+    /** Create a decorated mini egg material — pastel base with visible patterns. */
+    private _createMiniEggMat;
+    private _createEggGeometry;
+    /** Silver polka-dot color map */
+    private _drawSilverPolkaDots;
+    /** Silver roughness map (dots are more rough = less shiny) */
+    private _drawSilverRoughness;
+    /** Gold color map with ornamental scrollwork */
+    private _drawGoldPattern;
+    /** Gold roughness map */
+    private _drawGoldRoughness;
+    /** Festive Fabergé color map — randomized enamel bands + golden dividers */
+    private _drawFestivePattern;
+    /** Festive roughness map */
+    private _drawFestiveRoughness;
+    private _createHoldRing;
+    private _spawnRevealBurst;
+    /** Spawn golden energy vortex particles that orbit and spiral inward. */
+    private _spawnVortex;
+    /** Spawn upward-drifting golden ember particles after implosion. */
+    private _spawnEmbers;
+    /** Update vortex particles — orbit, spiral inward, fade in then out. */
+    private _updateVortexParticles;
+    /** Update ember particles — drift up, sway, flicker, fade. */
+    private _updateEmberParticles;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    /** Prevent scroll when pointer is over the interactive egg. */
+    private _onWheel;
+    /** Prevent click from reaching elements behind the egg. */
+    private _onClickCapture;
+    /** Block mousedown from reaching elements behind the egg (browsers fire both pointer + mouse events). */
+    private _onMouseDownCapture;
+    /** Block mouseup from reaching elements behind the egg. */
+    private _onMouseUpCapture;
+    /** Block touch events from reaching elements behind the egg. */
+    private _onTouchStartCapture;
+    /** Block touch move events during egg interaction. */
+    private _onTouchMoveCapture;
+    private _cancelLongPress;
+    private _worldToScreen;
+    private _screenToWorld;
+    private _animate;
+    private _updateEggs;
+    private _updateHoldRing;
+    /** Spawn a burst of shards flying outward from the collected egg, in the egg's own colour. */
+    private _spawnMiniEggBurst;
+    private _updateMiniEggs;
+    private _updateFinale;
+    private _updateTrails;
+    private _updateAmbientParticles;
+    private _updateRevealParticles;
+    private _onResize;
+}

package/dist/types/scoring/Persistence.d.ts

@@ -0,0 +1,26 @@
+import type { FinalScore, GameStage } from '../types';
+/**
+ * Local persistence layer using localStorage.
+ * Stores past scores and best times.
+ */
+export declare class Persistence {
+    private _enabled;
+    constructor(enabled: boolean);
+    saveScore(score: FinalScore): void;
+    getBestTime(): number | null;
+    getScoreCount(): number;
+    getLastScore(): (FinalScore & {
+        date: string;
+    }) | null;
+    clearScores(): void;
+    private _loadAll;
+    saveProgress(data: ProgressCheckpoint): void;
+    loadProgress(): ProgressCheckpoint | null;
+    clearProgress(): void;
+}
+export interface ProgressCheckpoint {
+    stage: GameStage;
+    eggsFound: number;
+    eggsState: [boolean, boolean, boolean];
+    savedAt: number;
+}