Initialize Wishing Well SPA scaffold with layered isometric well and scroll-depth viewport

[Copilot]

This PR lays down the weekend-scope foundation for the Wishing Well GitHub Pages app: a vanilla HTML/CSS/JS single page that opens on an isometric well and supports a scroll-driven descent toward the water layer. It also scaffolds the canvas, modal, and Firestore integration surfaces needed for wish submission/discovery flows.

• Scene and layout scaffold

  • Added index.html semantic structure for the full journey: exterior → opening → shaft → water.
  • Introduced persistent UI shell elements (title/tagline, floating Make a Wish FAB, wish-entry modal, wish-discovery modal).
  • Wired Firebase compat SDK script loading and modular app scripts (scroll.js, canvas.js, firebase.js, app.js).

• Isometric well + scroll-depth styling

  • Added css/well.css with:
    • Midnight gradient background (#0f0c29 → #302b63 → #24243e).
    • Isometric stone well exterior (rim/walls/opening via layered transforms/gradients).
    • Sticky viewport + extended scroll space for depth journey.
    • Parallax-like layer transitions driven by CSS custom property --scroll-progress.
    • Base responsive behavior and modal styling (including textured wish textarea treatment).

• Runtime module scaffolding

  • js/scroll.js: computes normalized scroll progress and updates --scroll-progress.
  • js/canvas.js: initializes water/dust canvases with animation loop + visibility-based throttling.
  • js/firebase.js: provides Firestore init hook and wish submit/random fetch helpers against wishes schema.
  • js/app.js: implements modal state, character counter, and initial wish form submission path.

• Project setup docs

  • Replaced minimal README with setup-focused docs covering file layout, Firebase config injection, Firestore document shape, local static serving, and GitHub Pages deployment.

.layer-water {
  opacity: clamp(0, calc((var(--scroll-progress) - 0.62) * 3.2), 1);
  transform: translate3d(0, calc(108px - (var(--scroll-progress) * 46px)), 0) scale(1.12);
}

Original prompt

Role: You are an expert creative frontend engineer specializing in interactive CSS art, Canvas 2D animations, and elegant, performant UI.

Project: Wishing Well — A public, interactive single-page web app hosted on GitHub Pages. Users anonymously write wish notes, toss them into a well, and discover random wishes left by others.

Tech Stack:

Vanilla HTML5, CSS3, and ES6+ (no build step or frameworks for rapid deployment).

CSS 3D transforms and SVG for the isometric well illustration.

HTML5 Canvas for the animated water surface and floating origami boats.

Firebase Firestore (free Spark tier) for real-time, persistent shared wish storage.

GitHub Pages for hosting.

Visual Requirements:

Isometric Well & Scroll Journey:
The viewport opens on a CSS/SVG isometric stone wishing well. As the user scrolls down, the view descends through the well opening, past interior brick walls, and finally reveals the water surface at the bottom. Use parallax-style transitions between layers (exterior → opening → shaft → water) tied to scroll position.

Water Surface:
When the water layer is visible, render an animated water surface using Canvas 2D. Include subtle ripple gradients and shimmer reflections.

Origami Boats:
Wishes appear as small, colorful, paper-folded origami boats floating on the water. Only 8–12 random boats are rendered at once to avoid clutter. Boats must gently bob (sine-wave vertical drift) and slowly drift horizontally. Colors: pastel paper tones (crimson, gold, cyan, mint, lavender).

Boat Interaction:
On tap or click, a boat rocks gently, then a centered modal popup fades in displaying a random wish message from the database (boats are visual metaphors, not direct mappings). The modal uses elegant serif typography and a soft close button.

Functional Requirements:

Write & Toss Flow:
A floating action button labeled "Make a Wish" opens a modal. The modal contains:

A textarea (max 200 characters) with a subtle paper texture background.

A "Toss Coin" button.

On submission, play a brief coin-toss CSS animation, transform the note into a colorful origami boat, and animate it drifting onto the water surface. Persist the wish to Firestore with createdAt and a randomly assigned color.

Random Discovery:
Tapping any boat queries Firestore for one random wish document and displays it in the popup. If the network is slow, show a graceful loading state.

Data Schema:
Collection: wishes
Document fields: { text: string, createdAt: timestamp, color: string }

Responsiveness:
The well illustration, scroll depth, and touch targets must work fluidly on mobile (iOS Safari / Android Chrome) and desktop.

Design Aesthetic:

Background: deep midnight gradient (#0f0c29 → #302b63 → #24243e).

Typography for wishes: 'Playfair Display' or similar elegant serif via Google Fonts.

Ambient particle dust motes floating in the well shaft (Canvas or CSS).

All animations locked to 60fps; use transform and opacity only for motion.

File Structure to Generate:

index.html — Semantic structure, canvas layer, modals, and Firebase SDK scripts.

css/well.css — Isometric well illustration, scroll-driven parallax, modal styling, and responsive breakpoints.

js/scroll.js — Scroll observer logic and parallax layer transitions.

js/canvas.js — Water surface rendering, boat sprite animation, and particle effects.

js/firebase.js — Firestore config, wish submission, and random wish retrieval.

js/app.js — Event listeners, modal state management, and app initialization.

README.md — Setup instructions, Firebase project setup steps, and GitHub Pages deployment guide.

Constraints:

Weekend-project scope. Prioritize clean, modular, well-commented code over complex abstractions.

Do not use Three.js, WebGL, or heavy 3D engines. CSS 3D and Canvas 2D only.

Optimize for mid-range mobile devices; throttle canvas redraws when off-screen.

First Task: Initialize the repository with the file structure above, create index.html with the semantic skeleton and canvas overlay, and build css/well.css to render the initial isometric well exterior and scrollable viewport.

[kilo-code-bot]

WARNING: Project structure paths use CI-specific absolute paths instead of repository-relative paths

The README lists absolute paths like /home/runner/work/wishing-well/wishing-well/index.html that only exist in the GitHub Actions runner. Users cloning the repository will not have these paths. Replace them with relative paths (e.g., index.html) so the documentation is accurate for local development.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

WARNING: Missing error handling on wish submission

submitWish can reject (network failure, Firestore error) or return { ok: false } when Firebase is unconfigured. Currently the modal closes and the form resets without any user feedback, silently dropping the wish. Wrap the call in try/catch, check the returned status, and surface an error to the user before closing the modal.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

WARNING: Unconditional animation loop start can create duplicate loops

requestAnimationFrame(frame) on line 92 runs unconditionally on load. Because the IntersectionObserver callback also calls requestAnimationFrame(frame) when the water canvas is initially visible, two concurrent animation loops can start and run in parallel, doubling the rendering work. Track the animation frame ID and only start the loop if it is not already running.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	3
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
README.md	7	Project structure paths use CI-specific absolute paths instead of repository-relative paths
js/app.js	40	Missing error handling on wish submission
js/canvas.js	92	Unconditional animation loop start can create duplicate loops

Files Reviewed (7 files)

• README.md - 1 issue
• css/well.css
• index.html
• js/app.js - 1 issue
• js/canvas.js - 1 issue
• js/firebase.js
• js/scroll.js

Fix these issues in Kilo Cloud

---

_{Reviewed by step-3.7-flash · Input: 122K · Output: 9.6K · Cached: 169.6K}