easter-egg-quest 1.0.0

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

@@ -0,0 +1,37 @@
+import type { FinalScore, StageResult, InputSnapshot } from '../types';
+/**
+ * Scoring engine — tracks all competition metrics and computes the
+ * predictability score at game end.
+ */
+export declare class ScoringEngine {
+    private _startTime;
+    private _entryTime;
+    private _stageResults;
+    /** Raw activity counters for predictability analysis. */
+    private _extraClicks;
+    private _chaoticMoveFrames;
+    private _hesitations;
+    private _failedAttempts;
+    private _overcorrections;
+    start(): void;
+    recordEntryFound(): void;
+    recordStageResult(result: StageResult): void;
+    /** Called each frame to analyse input patterns for predictability. */
+    analyseFrame(snap: InputSnapshot): void;
+    /** Increment extra clicks (clicks outside meaningful interaction). */
+    recordExtraClick(): void;
+    /** Record hesitation events (start-stop-start within 600 ms). */
+    recordHesitation(): void;
+    recordOvercorrection(): void;
+    computeFinalScore(inputStats?: {
+        totalClicks: number;
+        totalScrolls: number;
+        totalKeyPresses: number;
+        totalDistance: number;
+        maxVelocity: number;
+    }): FinalScore;
+    private _computeBehaviorProfile;
+    private _pickTitle;
+    private _computePredictability;
+    private _labelForScore;
+}

package/dist/types/stages/MotionStage.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedConfig, NarrativeScript, StageResult, StageStatus, StageHandler } from '../types';
+import type { InputTracker } from '../input/InputTracker';
+import type { EventBus } from '../core/EventBus';
+/**
+ * Stage 2 — Motion
+ *
+ * The user must keep moving continuously for the configured duration.
+ * Stopping for too long resets progress. Continuous motion creates
+ * luminous trails and eventually crystallizes the second egg.
+ */
+export declare class MotionStage implements StageHandler {
+    private config;
+    private script;
+    private input;
+    private bus;
+    private _status;
+    private _startTime;
+    private _fades;
+    private _attempts;
+    private _movingAccum;
+    private _lastUpdateTime;
+    private _narrativeIndex;
+    private _lastFadeNarrativeTime;
+    private _introPlayed;
+    /** How long without movement before the user "fades" (ms). */
+    private readonly FADE_THRESHOLD_MS;
+    constructor(config: ResolvedConfig, script: NarrativeScript, input: InputTracker, bus: EventBus);
+    start(): Promise<void>;
+    update(_dt: number): StageStatus;
+    cleanup(): void;
+    getResult(): StageResult;
+    private _handleFade;
+    private _wait;
+}

package/dist/types/stages/RhythmStage.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig, NarrativeScript, StageResult, StageStatus, StageHandler } from '../types';
+import type { InputTracker } from '../input/InputTracker';
+import type { EventBus } from '../core/EventBus';
+/**
+ * Stage 3 — Rhythm
+ *
+ * Synthesizes stillness and motion. The user must alternate between
+ * moving and pausing in a natural rhythm. Neither pure stillness nor
+ * pure constant motion works. The ideal cycle is ~3–4 s move, ~2–3 s pause.
+ *
+ * When the user's rhythm approaches coherence, the page "breathes" in sync.
+ */
+export declare class RhythmStage implements StageHandler {
+    private config;
+    private script;
+    private input;
+    private bus;
+    private _status;
+    private _startTime;
+    private _attempts;
+    private _narrativeIndex;
+    private _lastNarrativeTime;
+    private _introPlayed;
+    private _goodCycles;
+    private _totalCycles;
+    private _lastPhaseCount;
+    private _bestAccuracy;
+    /** Ideal move duration range (ms). */
+    private readonly IDEAL_MOVE_MIN;
+    private readonly IDEAL_MOVE_MAX;
+    /** Ideal pause duration range (ms). */
+    private readonly IDEAL_PAUSE_MIN;
+    private readonly IDEAL_PAUSE_MAX;
+    constructor(config: ResolvedConfig, script: NarrativeScript, input: InputTracker, bus: EventBus);
+    start(): Promise<void>;
+    update(_dt: number): StageStatus;
+    cleanup(): void;
+    getResult(): StageResult;
+    private _evaluateCycle;
+    private _showReaction;
+    private _wait;
+}

package/dist/types/stages/StillnessStage.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedConfig, NarrativeScript, StageResult, StageStatus, StageHandler } from '../types';
+import type { InputTracker } from '../input/InputTracker';
+import type { EventBus } from '../core/EventBus';
+/**
+ * Stage 1 — Stillness
+ *
+ * The user must remain completely still for the configured duration.
+ * Any mouse movement, click, scroll, or keypress resets progress.
+ * As the user approaches success, we emit visual-softening events.
+ * On success, emits 'egg:reveal' with egg index 0.
+ */
+export declare class StillnessStage implements StageHandler {
+    private config;
+    private script;
+    private input;
+    private bus;
+    private _status;
+    private _startTime;
+    private _breaks;
+    private _attempts;
+    private _lastBreakNarrativeTime;
+    private _narrativeIndex;
+    private _bestProgress;
+    private _introPlayed;
+    constructor(config: ResolvedConfig, script: NarrativeScript, input: InputTracker, bus: EventBus);
+    start(): Promise<void>;
+    update(_dt: number): StageStatus;
+    cleanup(): void;
+    getResult(): StageResult;
+    private _handleBreak;
+    private _wait;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,202 @@
+export interface EasterEggQuestConfig {
+    theme?: 'auto' | 'light' | 'dark' | ThemeConfig;
+    hiddenEntry?: HiddenEntryConfig;
+    hud?: boolean | HUDConfig;
+    shrine?: boolean | ShrineConfig;
+    sounds?: boolean;
+    stageDurations?: StageDurationsConfig;
+    narrative?: Partial<NarrativeScript>;
+    renderer?: '3d' | '2d' | 'auto';
+    scoring?: ScoringConfig;
+    accessibility?: AccessibilityConfig;
+    callbacks?: EventCallbacks;
+}
+export interface HiddenEntryConfig {
+    mode: 'auto' | 'manual';
+    selector?: string;
+    excludeSelectors?: string[];
+}
+export interface HUDConfig {
+    enabled?: boolean;
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+export interface ShrineConfig {
+    enabled?: boolean;
+    position?: 'bottom-right' | 'bottom-left' | 'bottom-center';
+}
+export interface StageDurationsConfig {
+    stillnessMs?: number;
+    motionMs?: number;
+    rhythmCycles?: number;
+}
+export interface ThemeConfig {
+    overlayBg?: string;
+    textColor?: string;
+    textSecondary?: string;
+    accent?: string;
+    accentGlow?: string;
+    hudBg?: string;
+    hudText?: string;
+}
+export interface ScoringConfig {
+    enableLocal?: boolean;
+    leaderboardAdapter?: LeaderboardAdapter;
+}
+export interface AccessibilityConfig {
+    reducedMotion?: boolean | 'auto';
+    highContrast?: boolean;
+    disableHiddenEntry?: boolean;
+    subtitlesLog?: boolean;
+}
+export interface EventCallbacks {
+    onInit?: () => void;
+    onEntryFound?: () => void;
+    onStageStart?: (stage: GameStage) => void;
+    onEggFound?: (eggIndex: number) => void;
+    onStageComplete?: (stage: GameStage, result: StageResult) => void;
+    onFinaleStart?: () => void;
+    onComplete?: (score: FinalScore) => void;
+    onDestroy?: () => void;
+}
+export interface ResolvedConfig {
+    theme: ResolvedTheme;
+    hiddenEntry: {
+        mode: 'auto' | 'manual';
+        selector?: string;
+        excludeSelectors: string[];
+    };
+    hud: {
+        enabled: boolean;
+        position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    };
+    shrine: {
+        enabled: boolean;
+        position: 'bottom-right' | 'bottom-left' | 'bottom-center';
+    };
+    sounds: boolean;
+    stageDurations: {
+        stillnessMs: number;
+        motionMs: number;
+        rhythmCycles: number;
+    };
+    renderer: '3d' | '2d' | 'auto';
+    scoring: {
+        enableLocal: boolean;
+        leaderboardAdapter?: LeaderboardAdapter;
+    };
+    accessibility: {
+        reducedMotion: boolean;
+        highContrast: boolean;
+        disableHiddenEntry: boolean;
+        subtitlesLog: boolean;
+    };
+    callbacks: EventCallbacks;
+}
+export interface ResolvedTheme {
+    overlayBg: string;
+    textColor: string;
+    textSecondary: string;
+    accent: string;
+    accentGlow: string;
+    hudBg: string;
+    hudText: string;
+}
+export interface NarrativeScript {
+    hiddenEntryHints: string[];
+    entryConfirmation: string[];
+    stage1Intro: string[];
+    stage1Reactions: string[];
+    stage1Success: string[];
+    stage2Intro: string[];
+    stage2Reactions: string[];
+    stage2Success: string[];
+    stage3Intro: string[];
+    stage3Reactions: string[];
+    stage3Success: string[];
+    finale: string[];
+    results: string[];
+}
+export type GameStage = 'idle' | 'entry' | 'stage1-intro' | 'stage1-active' | 'stage1-success' | 'stage2-intro' | 'stage2-active' | 'stage2-success' | 'stage3-intro' | 'stage3-active' | 'stage3-success' | 'finale' | 'results' | 'complete';
+export interface GameState {
+    stage: GameStage;
+    eggsFound: number;
+    startTime: number;
+    stageStartTime: number;
+    isPaused: boolean;
+    eggs: [EggState, EggState, EggState];
+}
+export interface EggState {
+    found: boolean;
+    foundTime?: number;
+    stageTime?: number;
+}
+export interface StageResult {
+    stageTime: number;
+    attempts: number;
+    breaks?: number;
+    fades?: number;
+    rhythmAccuracy?: number;
+}
+export interface FinalScore {
+    eggsFound: number;
+    totalTime: number;
+    entryTime: number;
+    egg1Time: number;
+    egg2Time: number;
+    egg3Time: number;
+    stillnessBreaks: number;
+    motionFades: number;
+    rhythmAccuracy: number;
+    predictabilityScore: number;
+    predictabilityLabel: string;
+    stageResults: StageResult[];
+    behaviorProfile: BehaviorProfile;
+    totalClicks: number;
+    totalScrolls: number;
+    totalKeyPresses: number;
+    totalDistance: number;
+    eggSeed: number;
+}
+export interface LeaderboardAdapter {
+    submitScore(score: FinalScore): Promise<void>;
+    getLeaderboard(): Promise<LeaderboardEntry[]>;
+}
+export interface LeaderboardEntry {
+    name: string;
+    totalTime: number;
+    predictabilityScore: number;
+    date: string;
+}
+export interface InputSnapshot {
+    isMoving: boolean;
+    lastMoveTime: number;
+    lastStillTime: number;
+    mouseX: number;
+    mouseY: number;
+    velocity: number;
+    totalClicks: number;
+    totalScrolls: number;
+    totalKeyPresses: number;
+    totalDistance: number;
+    maxVelocity: number;
+}
+export interface BehaviorProfile {
+    title: string;
+    dominantAction: string;
+    mousePersonality: string;
+    pace: string;
+}
+export interface MovementPhase {
+    type: 'move' | 'still';
+    startTime: number;
+    endTime: number;
+    duration: number;
+}
+export type StageStatus = 'active' | 'complete';
+export interface StageHandler {
+    start(): Promise<void>;
+    update(dt: number): StageStatus;
+    cleanup(): void;
+    getResult(): StageResult;
+}
+export type ThreeModule = typeof import('three');

package/dist/types/utils/helpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DOM utility helpers. All are safe to call in non-browser environments
+ * (they degrade gracefully).
+ */
+/** Check if an element is visible in the viewport and has a non-zero size. */
+export declare function isElementVisible(el: Element): boolean;
+/** Check if an element's text suggests a dangerous / transactional action. */
+export declare function isDangerousElement(el: Element): boolean;
+/**
+ * Query safe clickable elements that are eligible for the hidden entry.
+ * Filters out dangerous elements, invisible ones, and elements too small to click.
+ */
+export declare function findEligibleEntryElements(containerSelector?: string, excludeSelectors?: string[]): Element[];
+/** Pick a random element from an array. */
+export declare function pickRandom<T>(arr: T[]): T | undefined;
+/** Create an element inside an optional Shadow DOM host. */
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, styles?: Partial<CSSStyleDeclaration>): HTMLElementTagNameMap[K];
+/** Clamp a value between min and max. */
+export declare function clamp(val: number, min: number, max: number): number;
+/** Linear interpolation. */
+export declare function lerp(a: number, b: number, t: number): number;
+/** Format milliseconds as mm:ss. */
+export declare function formatTime(ms: number): string;
+/** Smooth ease-in-out (cubic). */
+export declare function easeInOutCubic(t: number): number;
+/** Smooth ease-out (quad). */
+export declare function easeOutQuad(t: number): number;
+/** Detect prefers-reduced-motion. */
+export declare function prefersReducedMotion(): boolean;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "easter-egg-quest",
+  "version": "1.0.0",
+  "description": "A hidden Easter-themed narrative mini-game overlay for any website",
+  "main": "dist/easter-egg-quest.umd.js",
+  "module": "dist/easter-egg-quest.es.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/easter-egg-quest.es.js",
+      "require": "./dist/easter-egg-quest.umd.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "three": "^0.160.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.160.0",
+    "terser": "^5.46.1",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0"
+  },
+  "keywords": [
+    "easter",
+    "egg",
+    "game",
+    "overlay",
+    "interactive",
+    "threejs",
+    "mini-game",
+    "easter-egg"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/example/easter-egg-quest"
+  }
+}