easter-egg-quest 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Easter Egg Quest Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# 🥚 Easter Egg Quest
+
+Drop a hidden Easter-themed mini-game onto **any website** with a single line of code. Users discover a secret entry point on your page and solve three poetic riddles — *Stillness*, *Motion*, *Rhythm* — to collect three symbolic eggs.
+
+**Zero configuration required.** The game overlays your page without breaking layout. Fully self-contained — Three.js 3D rendering is built in.
+
+## Quick Start
+
+### CDN (simplest)
+
+```html
+<script src="https://unpkg.com/easter-egg-quest"></script>
+<script>
+  EasterEggQuest.init();
+</script>
+```
+
+That's it. The game hides itself inside your page content and waits to be discovered.
+
+### npm
+
+```bash
+npm install easter-egg-quest
+```
+
+```js
+import { EasterEggQuest } from 'easter-egg-quest';
+
+EasterEggQuest.init();
+```
+
+## How It Works
+
+1. **Hidden entry** — the game injects a subtle "start hunt" trigger into existing text on your page
+2. **Stage 1: Stillness** — stop moving. The egg comes to those who wait
+3. **Stage 2: Motion** — keep moving. Be the river
+4. **Stage 3: Rhythm** — find the pulse. Breathe
+5. **Finale** — all three eggs appear in a 3D carousel with a "Happy Easter!" greeting
+6. **Results** — a personalized profile card based on your behavior (shareable as image)
+
+The user clicks "finish" to close — the game removes all traces of itself from the DOM.
+
+## Configuration
+
+All options are optional:
+
+```js
+EasterEggQuest.init({
+  // Lifecycle callbacks
+  callbacks: {
+    onInit: () => {},
+    onEntryFound: () => {},
+    onStageStart: (stage) => {},
+    onEggFound: (eggIndex) => {},
+    onComplete: (score) => {},
+    onDestroy: () => {},
+  },
+
+  // Stage durations
+  stageDurations: {
+    stillnessMs: 20000,
+    motionMs: 20000,
+    rhythmCycles: 6,
+  },
+
+  // Rendering: 'auto' | '3d' | '2d'
+  renderer: 'auto',
+
+  // Accessibility
+  accessibility: {
+    reducedMotion: 'auto',   // follows prefers-reduced-motion
+    disableHiddenEntry: false, // shows a visible button instead
+  },
+
+  // Hidden entry targeting
+  hiddenEntry: {
+    selector: undefined,       // CSS selector to limit entry candidates
+    excludeSelectors: [],      // selectors to exclude
+  },
+
+  // Custom narrative text
+  narrative: {
+    // Override any dialogue array:
+    // stage1Intro: ['your', 'custom', 'lines'],
+  },
+});
+```
+
+## API
+
+```js
+EasterEggQuest.init(config?)   // Start the game
+EasterEggQuest.pause()         // Pause
+EasterEggQuest.resume()        // Resume
+EasterEggQuest.destroy()       // Remove everything, restore DOM
+```
+
+## Safety
+
+Designed to be safe on production websites:
+
+- **No layout shifts** — all UI is `position: fixed` overlay
+- **Shadow DOM isolation** — CSS never collides with your styles
+- **Smart element filtering** — hidden entry avoids Buy, Delete, Checkout, Submit buttons
+- **Clean destroy** — removes all DOM elements, listeners, and WebGL resources
+
+## Browser Support
+
+Chrome/Edge 90+ · Firefox 90+ · Safari 15+ · Mobile browsers
+
+Falls back to CSS 2D rendering if WebGL is unavailable.
+
+## License
+
+MIT