scragz/01-idea.md

Last active July 23, 2025 22:00

Star (0) You must be signed in to star a gist
Fork (0) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/scragz/c9f79786d0a406536fed1b3bca77a45c.js"></script>
Save scragz/c9f79786d0a406536fed1b3bca77a45c to your computer and use it in GitHub Desktop.

Raw

we want to make a browser-based game using three.js that will distract your cat while you eat dinner so they don't steal your food.

Raw

02-request-prompt.md

Idea Refinement

Your task is to collaborate on developing or refining a project or feature concept. This prompt solicits iterative feedback to expand a basic idea into a comprehensive, well-structured request.

Required Inputs

PROJECT_REQUEST: A short description of the project or feature’s initial concept.

Task Overview

In each exchange, the AI will:

Ask questions to clarify the project or feature.
Suggest missing considerations or user flows.
Organize requirements logically.
Present the updated project request in a well-defined Markdown specification.

This ensures you iterate toward a final, clear “Project Request” doc.

Detailed Process Outline

User Provides Concept: User supplies the idea.
AI Gathers Clarifications: The AI asks targeted questions to flesh out missing details, such as feature scope or user needs.
AI Updates the Specification: After each round of questions/answers, the AI returns a new version of the Markdown-based request format.
Repeat until the request is complete, well-defined, and you are satisfied.

Output Template

# Project Name

[Description goes here]

## Target Audience

[Who will use this? What are their needs?]

## Desired Features

### [Feature Category]

- [ ] [High-level requirement]
  - [ ] [Further detail, sub-requirement]

## Design Requests

- [ ] [Visual or UX requirement]
  - [ ] [Relevant detail or constraint]

## Other Notes

- [Any additional considerations or open questions]

Context

<project_request> we want to make a browser-based game using three.js that will distract your cat while you eat dinner so they don't steal your food. </project_request>

Raw

05-spec-response.md

PawPursuit Technical Specification (New Project)

1. System Overview

Core Purpose & Goals
A zero-interaction, browser-based visual “motion lure” for cats. Loads, enters (or requests) full-screen, and continuously renders erratic, high-contrast motion patterns on a dark background to maintain feline attention while the human eats.
Primary Use Cases
1. Human opens URL on tablet/TV → animation auto-starts, runs indefinitely.
2. (Dev only) Load with ?debug=1 to tweak parameters during development.
High-Level Architecture
Pure client-side PWA:
- Client: HTML shell + JavaScript modules using Three.js for WebGL rendering.
- Service Worker: Offline caching of static assets.
- No backend / database / telemetry.


\[HTML Shell] --> \[Bootstrap JS]
├─ Renderer (Three.js)
├─ Mode Manager
│    ├─ Motion Algorithms
│    └─ Attention Reset System
├─ Performance Governor
└─ PWA Service Worker

2. Technology & Tools

Languages & Frameworks: ES2020+ JavaScript, Three.js.
Libraries & Dependencies:
Three.js (rendering)
(Optional) GSAP or custom tween functions (only if needed)
Database & ORM: None.
DevOps & Hosting:
Static hosting (e.g., GitHub Pages, Netlify, Cloudflare Pages).
Optional Docker for local dev consistency.
CI/CD Pipeline:
GitHub Actions: lint, unit tests on push, deploy to Pages on main merge.

3. Project Structure


/public
index.html
manifest.webmanifest
sw\.js                # service worker
assets/              # icons, splash screens if any
/src
main.js              # entry, bootstrap
core/
renderer.js        # Three.js init, resize logic
sceneFactory.js    # Builds scene, camera, lights
performanceGovernor.js
fullscreen.js
config.js          # constants (durations, counts)
modes/
index.js           # Mode registry & manager
laserDot.js
flutterMoth.js
scurryBug.js
ribbonTrail.js
systems/
attentionReset.js
random.js          # RNG utilities
mathUtil.js        # bezier, easing, noise
debug/
debugOverlay.js    # Only loaded with ?debug=1
/test
unit/
mathUtil.spec.js
performanceGovernor.spec.js
e2e/
autoplay.spec.js   # e.g., Playwright

Naming Conventions: lowerCamelCase for JS variables/functions, PascalCase for classes. File names kebab-case or camelCase consistently (pick one).
Key Modules:
- renderer.js: abstracts Three.js boilerplate.
- modes/*: independent motion archetypes implementing a shared interface.
- performanceGovernor.js: monitors FPS/time, adjusts density.
- attentionReset.js: triggers bursts/pulses.

4. Feature Specification

4.1 Core Visual Loop

User Story & Requirements
- As a human, I open the page; it instantly displays moving prey-like visuals indefinitely, without any interaction.
- As a cat, I see rapidly moving targets with occasional bursts to renew interest.
Implementation Details
- ModeManager cycles modes every 60–120s (hardcoded).
- Each mode spawns entities implementing update(deltaTime) and render() hooks.
- Randomized reset events via AttentionResetSystem.trigger() at pseudo-random intervals (e.g., 20–45s).
Edge Cases & Error Handling
- WebGL context loss → try to recover or reload renderer.
- Full-screen API denied → still run in windowed mode.
- Low FPS (<30) → reduce spawn count, lower resolution (set renderer.setPixelRatio).
UI/UX Considerations
- No visible UI in production mode.
- Avoid harsh flashes (>3 Hz). Use eased pulses instead.

4.2 Environment & Startup Behavior

Requirements
- Auto-play on DOMContentLoaded.
- Attempt requestFullscreen(). If fails, continue.
- Silent—no audio engine initialization.
Edge Cases
- Some TV browsers block fullscreen or autoplay requests; handle gracefully.
- Device sleeps—no prevention; human responsibility.

4.3 Performance & Safety

Requirements
- Target ~60 FPS on mid-range tablets (A12/A13, Snapdragon mid-tier).
- PerformanceGovernor checks moving average FPS every 5 seconds:
  - If FPS < 45: reduce particle/entity counts by 25%.
  - If still < 30: reduce renderer pixelRatio to 0.75, etc.
Edge Cases
- Thermal throttling triggers low-FPS signals; degrade effects automatically.

4.4 Optional Dev Debug Mode

Requirements
- ?debug=1 query param loads debugOverlay.js.
- Overlay shows sliders for speed, spawnCount, modeDuration.
- Hidden in production build (tree-shaken or env-flagged).

5. Database Schema

N/A – No persistent backend.
Rationale: All settings are hardcoded or ephemeral; no user data.

6. Server Actions

6.1 Database Actions

N/A

6.2 Other Backend Logic

External API Integrations: None.
File/Media Handling: None—assets are procedural or prebundled textures.
Background Jobs/Workers: None on server; optional Web Worker for heavy math could be future enhancement.

7. Design System

7.1 Visual Style

Branding & Theme: Dark background (#000–#111). Saturated hues (greens/blues/neons) for foreground trails. Avoid pure white.
Layout & Spacing: Full-bleed canvas; no DOM UI except hidden debug overlay.
Accessibility:
- Avoid flicker >3 Hz.
- Provide meta tag or link to “safety note” (small text in HTML head or comments).

7.2 UI Components

Production: None.
Debug: Simple sliders, toggles, numeric inputs (plain HTML/CSS).

8. Component Architecture

8.1 Backend Components

N/A

8.2 Frontend Components

Renderer (class): initializes WebGLRenderer, Scene, Camera; manages resize & render loop.
ModeManager: holds array of mode definitions, switches mode on timeout.

Mode Interface:

interface Mode {
  name: string;
  init(scene: THREE.Scene, config: ModeConfig): void;
  update(dt: number): void;
  dispose(): void;
}

Prey Entity Interface:

interface PreyEntity {
  mesh: THREE.Object3D;
  update(dt: number): void;
  reset?(reason: ResetReason): void;
}

PerformanceGovernor: monitors FPS, toggles flags or calls mode to adjust spawn counts.
AttentionResetSystem: ephemeral particle systems or color pulses layered over scene.

9. Authentication & Authorization

N/A – Public, no user accounts.

10. Data Flow

Request/Response Lifecycle: Initial GET of static files. No further network calls.
State Sync: Internal JS state only; config constants loaded at boot.
Real-Time Updates: Render loop (requestAnimationFrame) updates entities each frame.

Sequence (simplified):

window load -> bootstrap -> init Renderer -> ModeManager.init(firstMode)
             -> renderLoop(dt):
                   Mode.update(dt)
                   Governor.checkFps()
                   Renderer.render(scene, camera)
             -> setTimeout (mode switch)
             -> randomInterval (attention reset)

11. Payment Integration

N/A

12. Analytics Integration

N/A (explicitly declined)

13. Security & Compliance

Encryption: HTTPS hosting recommended (PWA requires).
Compliance: No personal data; minimal risk.
Threat Modeling: Only surface is static hosting. Harden service worker against cache poisoning (versioned cache names).
Secrets Management: None.

14. Environment Configuration & Deployment

Local Setup
- npm install
- npm run dev (Vite) → localhost:5173
- Env var DEBUG=1 for local debug.
Staging/Production
- Build: npm run build → /dist static bundle.
- Deploy: Push to main triggers GitHub Action → deploy to CDN/Pages.
CI/CD
- Jobs: lint, test, build.
- Cache node_modules for faster builds.
Monitoring & Logging
- Browser console for dev. No runtime logs in prod (optional Sentry if crashes matter, but likely overkill).

15. Testing

Unit Testing
- Math & utility functions (bezier path gen, random ranges, FPS averaging).
- Jest or Vitest.
Integration Testing
- Ensure ModeManager switches modes, resets trigger correctly (mock timers).
End-to-End (E2E)
- Playwright/Puppeteer: open page, confirm canvas, verify RAF called, ensure no console errors.
- Visual regression (optional) using screenshot diffs for key frames.
Performance & Security Testing
- Manual FPS checks on target devices.
- Lighthouse for PWA compliance & basic performance (though it’s WebGL-heavy).

Summary & Next Steps

Recap

Client-only, Three.js-based, auto-playing visual toy.
Core modules: Renderer, ModeManager, Motion modes, Attention Reset, Performance Governor.
No UI, no analytics, no backend. PWA enabled for offline.
Safety: avoid strobe, auto-degrade performance.

Open Questions

License (MIT assumed) — confirm.
Minimum device/browser support list? (Chrome ≥ 90, Safari iPadOS 15+, Samsung Internet?)
Do we want a fallback 2D canvas mode for non-WebGL browsers?
Maximum runtime to trigger “cool down” mode or just loop forever?

Future Enhancements

Web Worker for heavy path calculations.
Additional mode packs (seasonal, themed).
Optional audio cues (if ever desired).
Remote control micro-site (if you later want controls on a phone while TV runs visuals).

Raw

06-plan-prompt.md

Implementation Plan Generation

Your task is to create a comprehensive, step-by-step implementation plan for building a fully functional web application based on provided input documents. The plan should be detailed enough for a code-generation AI to execute each step sequentially.

Required Inputs

PROJECT_REQUEST: An overview of the project requirements or user request.
PROJECT_RULES: Any specific rules, guidelines, or best practices to follow.
TECHNICAL_SPECIFICATION: A thorough technical spec outlining architecture, data flows, features, etc.
REFERENCE_CODE: Any initial code or directory structure templates that should be referenced or expanded.

Task Overview

In each exchange, you will:

Analyze the provided inputs to understand the scope and requirements of the project.
Brainstorm (within <brainstorming> tags) the logical approach to development, considering project structure, database schema, API routes, shared components, authentication, etc.
Construct an itemized, ordered list of implementation steps, each sufficiently granular and self-contained.
Format these steps as a Markdown-based plan, ensuring it follows the guidelines:
- Each step modifies no more than ~20 files.
- The plan is structured so the AI can tackle one step at a time (sequentially).
- Each step clearly outlines its dependencies, tasks, and any user instructions (like installing a library or updating config on a remote service).

Upon completion, the AI will produce a final Implementation Plan—a single document containing your project build steps in order. This plan should cover everything from initial project setup to final testing.

Detailed Process Outline

Review Inputs: The AI reads <project_request>, <project_rules>, <technical_specification>, and <reference_code> to form a complete understanding of the project.
Brainstorm: Within <brainstorming> tags, the AI considers:
- Core structure and essential configurations.
- Database schema, server actions, and API routes.
- Shared components, layouts, and feature pages.
- Authentication, authorization, and third-party service integrations.
- Client-side interactivity and state management.
- Testing strategy and error handling.
Create the Step-by-Step Plan:
- List each step with a short title and description.
- Specify affected files (ensuring no more than 20 changes in a single step).
- Indicate step dependencies (if any).
- Highlight any user instructions for manual tasks.
Finalize the Plan: The AI returns the complete plan under a # Implementation Plan heading, with each major section labeled (e.g., “## [Section Name]”) and the sub-steps in a checklist format.

Output Template

Below is an example of the Implementation Plan structure you should produce once the brainstorming is complete:

# Implementation Plan

## [Section Name]
- [ ] Step 1: [Brief title]
  - **Task**: [Detailed explanation of what needs to be implemented]
  - **Files**: [Up to 20 files, ideally less]
    - `path/to/file1.ts`: [Description of changes]
    - ...
  - **Step Dependencies**: [e.g., "None" or "Step 2"]
  - **User Instructions**: [Any manual tasks the user must perform]

[Additional steps... up to final deployment and testing]

After listing all steps, provide a brief summary of your overall approach and key considerations (e.g., major dependencies, potential complexities, or recommended best practices).

Context

<technical_specification> [removed] </technical_specification>

<project_request> [removed] </project_request>

Raw

08-final-prompt.md

follow the plan below and make my game!

PawPursuit Technical Specification (New Project)

1. System Overview

Core Purpose & Goals
A zero-interaction, browser-based visual “motion lure” for cats. Loads, enters (or requests) full-screen, and continuously renders erratic, high-contrast motion patterns on a dark background to maintain feline attention while the human eats.
Primary Use Cases
1. Human opens URL on tablet/TV → animation auto-starts, runs indefinitely.
2. (Dev only) Load with ?debug=1 to tweak parameters during development.
High-Level Architecture
Pure client-side PWA:
- Client: HTML shell + JavaScript modules using Three.js for WebGL rendering.
- Service Worker: Offline caching of static assets.
- No backend / database / telemetry.


\[HTML Shell] --> \[Bootstrap JS]
├─ Renderer (Three.js)
├─ Mode Manager
│    ├─ Motion Algorithms
│    └─ Attention Reset System
├─ Performance Governor
└─ PWA Service Worker

2. Technology & Tools

Languages & Frameworks: ES2020+ JavaScript, Three.js.
Libraries & Dependencies:
Three.js (rendering)
(Optional) GSAP or custom tween functions (only if needed)
Database & ORM: None.
DevOps & Hosting:
Static hosting (e.g., GitHub Pages, Netlify, Cloudflare Pages).
Optional Docker for local dev consistency.
CI/CD Pipeline:
GitHub Actions: lint, unit tests on push, deploy to Pages on main merge.

3. Project Structure


/public
index.html
manifest.webmanifest
sw\.js                # service worker
assets/              # icons, splash screens if any
/src
main.js              # entry, bootstrap
core/
renderer.js        # Three.js init, resize logic
sceneFactory.js    # Builds scene, camera, lights
performanceGovernor.js
fullscreen.js
config.js          # constants (durations, counts)
modes/
index.js           # Mode registry & manager
laserDot.js
flutterMoth.js
scurryBug.js
ribbonTrail.js
systems/
attentionReset.js
random.js          # RNG utilities
mathUtil.js        # bezier, easing, noise
debug/
debugOverlay.js    # Only loaded with ?debug=1
/test
unit/
mathUtil.spec.js
performanceGovernor.spec.js
e2e/
autoplay.spec.js   # e.g., Playwright

Naming Conventions: lowerCamelCase for JS variables/functions, PascalCase for classes. File names kebab-case or camelCase consistently (pick one).
Key Modules:
- renderer.js: abstracts Three.js boilerplate.
- modes/*: independent motion archetypes implementing a shared interface.
- performanceGovernor.js: monitors FPS/time, adjusts density.
- attentionReset.js: triggers bursts/pulses.

4. Feature Specification

4.1 Core Visual Loop

User Story & Requirements
- As a human, I open the page; it instantly displays moving prey-like visuals indefinitely, without any interaction.
- As a cat, I see rapidly moving targets with occasional bursts to renew interest.
Implementation Details
- ModeManager cycles modes every 60–120s (hardcoded).
- Each mode spawns entities implementing update(deltaTime) and render() hooks.
- Randomized reset events via AttentionResetSystem.trigger() at pseudo-random intervals (e.g., 20–45s).
Edge Cases & Error Handling
- WebGL context loss → try to recover or reload renderer.
- Full-screen API denied → still run in windowed mode.
- Low FPS (<30) → reduce spawn count, lower resolution (set renderer.setPixelRatio).
UI/UX Considerations
- No visible UI in production mode.
- Avoid harsh flashes (>3 Hz). Use eased pulses instead.

4.2 Environment & Startup Behavior

Requirements
- Auto-play on DOMContentLoaded.
- Attempt requestFullscreen(). If fails, continue.
- Silent—no audio engine initialization.
Edge Cases
- Some TV browsers block fullscreen or autoplay requests; handle gracefully.
- Device sleeps—no prevention; human responsibility.

4.3 Performance & Safety

Requirements
- Target ~60 FPS on mid-range tablets (A12/A13, Snapdragon mid-tier).
- PerformanceGovernor checks moving average FPS every 5 seconds:
  - If FPS < 45: reduce particle/entity counts by 25%.
  - If still < 30: reduce renderer pixelRatio to 0.75, etc.
Edge Cases
- Thermal throttling triggers low-FPS signals; degrade effects automatically.

4.4 Optional Dev Debug Mode

Requirements
- ?debug=1 query param loads debugOverlay.js.
- Overlay shows sliders for speed, spawnCount, modeDuration.
- Hidden in production build (tree-shaken or env-flagged).

5. Database Schema

N/A – No persistent backend.
Rationale: All settings are hardcoded or ephemeral; no user data.

6. Server Actions

6.1 Database Actions

N/A

6.2 Other Backend Logic

External API Integrations: None.
File/Media Handling: None—assets are procedural or prebundled textures.
Background Jobs/Workers: None on server; optional Web Worker for heavy math could be future enhancement.

7. Design System

7.1 Visual Style

Branding & Theme: Dark background (#000–#111). Saturated hues (greens/blues/neons) for foreground trails. Avoid pure white.
Layout & Spacing: Full-bleed canvas; no DOM UI except hidden debug overlay.
Accessibility:
- Avoid flicker >3 Hz.
- Provide meta tag or link to “safety note” (small text in HTML head or comments).

7.2 UI Components

Production: None.
Debug: Simple sliders, toggles, numeric inputs (plain HTML/CSS).

8. Component Architecture

8.1 Backend Components

N/A

8.2 Frontend Components

Renderer (class): initializes WebGLRenderer, Scene, Camera; manages resize & render loop.
ModeManager: holds array of mode definitions, switches mode on timeout.

Mode Interface:

interface Mode {
  name: string;
  init(scene: THREE.Scene, config: ModeConfig): void;
  update(dt: number): void;
  dispose(): void;
}

Prey Entity Interface:

interface PreyEntity {
  mesh: THREE.Object3D;
  update(dt: number): void;
  reset?(reason: ResetReason): void;
}

PerformanceGovernor: monitors FPS, toggles flags or calls mode to adjust spawn counts.
AttentionResetSystem: ephemeral particle systems or color pulses layered over scene.

9. Authentication & Authorization

N/A – Public, no user accounts.

10. Data Flow

Request/Response Lifecycle: Initial GET of static files. No further network calls.
State Sync: Internal JS state only; config constants loaded at boot.
Real-Time Updates: Render loop (requestAnimationFrame) updates entities each frame.

Sequence (simplified):

window load -> bootstrap -> init Renderer -> ModeManager.init(firstMode)
             -> renderLoop(dt):
                   Mode.update(dt)
                   Governor.checkFps()
                   Renderer.render(scene, camera)
             -> setTimeout (mode switch)
             -> randomInterval (attention reset)

11. Payment Integration

N/A

12. Analytics Integration

N/A (explicitly declined)

13. Security & Compliance

Encryption: HTTPS hosting recommended (PWA requires).
Compliance: No personal data; minimal risk.
Threat Modeling: Only surface is static hosting. Harden service worker against cache poisoning (versioned cache names).
Secrets Management: None.

14. Environment Configuration & Deployment

Local Setup
- npm install
- npm run dev (Vite) → localhost:5173
- Env var DEBUG=1 for local debug.
Staging/Production
- Build: npm run build → /dist static bundle.
- Deploy: Push to main triggers GitHub Action → deploy to CDN/Pages.
CI/CD
- Jobs: lint, test, build.
- Cache node_modules for faster builds.
Monitoring & Logging
- Browser console for dev. No runtime logs in prod (optional Sentry if crashes matter, but likely overkill).

15. Testing

Unit Testing
- Math & utility functions (bezier path gen, random ranges, FPS averaging).
- Jest or Vitest.
Integration Testing
- Ensure ModeManager switches modes, resets trigger correctly (mock timers).
End-to-End (E2E)
- Playwright/Puppeteer: open page, confirm canvas, verify RAF called, ensure no console errors.
- Visual regression (optional) using screenshot diffs for key frames.
Performance & Security Testing
- Manual FPS checks on target devices.
- Lighthouse for PWA compliance & basic performance (though it’s WebGL-heavy).

Summary & Next Steps

Recap

Client-only, Three.js-based, auto-playing visual toy.
Core modules: Renderer, ModeManager, Motion modes, Attention Reset, Performance Governor.
No UI, no analytics, no backend. PWA enabled for offline.
Safety: avoid strobe, auto-degrade performance.

Open Questions

License (MIT assumed) — confirm.
Minimum device/browser support list? (Chrome ≥ 90, Safari iPadOS 15+, Samsung Internet?)
Do we want a fallback 2D canvas mode for non-WebGL browsers?
Maximum runtime to trigger “cool down” mode or just loop forever?

Future Enhancements

Web Worker for heavy path calculations.
Additional mode packs (seasonal, themed).
Optional audio cues (if ever desired).
Remote control micro-site (if you later want controls on a phone while TV runs visuals).

Single-page PWA, no backend. Core chunks: toolchain (Vite), Three.js bootstrapping, renderer wrapper, mode system, attention reset, performance governor, fullscreen + startup, PWA (manifest + SW), optional debug overlay, testing (unit + e2e), CI/CD.

Keep each step ≤20 files by grouping logically (e.g., one step = create base folders + minimal files). Later steps add one mode per step to spread changes.

We’ll scaffold config first, then core engine, then systems, then modes, then polish (governor, resets), then PWA, tests, CI, deploy.

We’ll add “User Instructions” where manual (e.g., set GitHub Pages). We’ll note dependencies.

We’ll ensure each step mentions exact files.

Implementation Plan

0. Prep & Repo Initialization

Step 0.1: Create repo & baseline tooling
- Task: Init Git repo, Node project, add Vite, ESLint/Prettier, basic scripts.
- Files:
  - package.json: init, add scripts (dev, build, preview, test, lint)
  - .gitignore: node_modules, dist
  - vite.config.js: basic ES module build
  - .eslintrc.cjs, .prettierrc: lint/format config
  - README.md: quick start commands
- Step Dependencies: None
- User Instructions: git init && npm init -y && npm i three vite vitest @vitest/ui eslint prettier

1. Public Shell & PWA Skeleton

Step 1.1: Public assets & HTML shell
- Task: Add minimal HTML with canvas container, meta tags, dark theme; add manifest + icons; stub service worker.
- Files:
  - public/index.html: root, <canvas id="app"> placeholder, meta “safety note”
  - public/manifest.webmanifest: name, icons, theme_color
  - public/sw.js: empty install/activate listeners with versioned cache name constant
  - public/assets/icon-512.png, public/assets/icon-192.png (placeholders)
- Step Dependencies: Step 0.1
- User Instructions: Provide/replace real icons later.

2. Source Structure & Bootstrap

Step 2.1: Create src layout & bootstrap entry
- Task: Create folder tree and minimal boot code to start RAF loop.
- Files:
  - src/main.js: entry; imports renderer, modeManager (stub), fullscreen attempt
  - src/core/renderer.js: init Three.js renderer, scene, camera, resize handler
  - src/core/sceneFactory.js: build scene/camera defaults
  - src/core/fullscreen.js: helper to request fullscreen gracefully
  - src/core/config.js: constants (modeDuration, resetIntervals, etc.)
  - src/modes/index.js: exports ModeManager stub
  - src/systems/random.js: RNG utilities stub
- Step Dependencies: Step 1.1
- User Instructions: None

3. Render Loop & Timekeeping

Step 3.1: Implement render loop & delta calc
- Task: Add RAF loop, dt calc, call current mode.update, renderer.render; error guard for WebGL loss.
- Files:
  - src/core/renderer.js: add startLoop() method
  - src/main.js: wire loop start, try/catch around render
  - src/modes/index.js: expose getCurrentModeUpdate()
- Step Dependencies: Step 2.1
- User Instructions: None

4. Mode Interface & First Mode (Laser Dot)

Step 4.1: Define Mode & PreyEntity interfaces
- Task: Create JS doc typedefs or TS-like comments; implement base class/helpers.
- Files:
  - src/modes/types.d.ts (or .js with JSDoc): Mode, PreyEntity, ModeConfig
  - src/modes/baseMode.js: utility parent with common init/dispose
- Step Dependencies: Step 3.1
- User Instructions: None
Step 4.2: Implement laserDot mode
- Task: Single moving dot with zigzag behavior.
- Files:
  - src/modes/laserDot.js
  - src/systems/mathUtil.js: bezier/zigzag helpers
- Step Dependencies: Step 4.1
- User Instructions: None

5. Mode Manager & Auto Cycling

Step 5.1: ModeManager implementation
- Task: Load array of modes, switch on timer; dispose old, init new.
- Files:
  - src/modes/index.js: full manager (init, update, switchMode)
  - src/core/config.js: add MODE_DURATION_MS = 90000 (example)
- Step Dependencies: Step 4.2
- User Instructions: None

6. Additional Modes

Step 6.1: Flutter Moth Mode
- Task: Entities with erratic fluttering (noise-based paths).
- Files:
  - src/modes/flutterMoth.js
  - src/systems/mathUtil.js: add perlin/simplex noise or pseudo-noise func
- Step Dependencies: Step 5.1
- User Instructions: None
Step 6.2: Scurry Bug Mode
- Task: Short darting bursts with pauses.
- Files:
  - src/modes/scurryBug.js
- Step Dependencies: Step 6.1
- User Instructions: None
Step 6.3: Ribbon Trail Mode
- Task: Trail-rendered ribbons (line segments or tube geometry).
- Files:
  - src/modes/ribbonTrail.js
- Step Dependencies: Step 6.2
- User Instructions: None

7. Attention Reset System

Step 7.1: Particle/Color Pulse System
- Task: Implement AttentionResetSystem that spawns transient particles or screen tint pulse.
- Files:
  - src/systems/attentionReset.js
  - src/core/config.js: add reset interval constants (min/max secs)
  - (Optional) src/systems/particles.js: simple particle group helper
- Step Dependencies: Step 6.3
- User Instructions: None

8. Performance Governor

Step 8.1: FPS monitor & adaptive degradation
- Task: Moving average FPS; adjust spawn counts/pixelRatio.
- Files:
  - src/core/performanceGovernor.js
  - src/core/renderer.js: expose setPixelRatio
  - src/modes/index.js: allow ModeManager to forward “degrade” signals to modes
- Step Dependencies: Step 7.1
- User Instructions: None

9. Fullscreen & Startup Flow Finalization

Step 9.1: Auto-start & fullscreen request logic
- Task: On DOMContentLoaded, request fullscreen, start visuals; fall back gracefully.
- Files:
  - src/main.js: finalize startup orchestration
  - src/core/fullscreen.js: handle various browser APIs
- Step Dependencies: Step 8.1
- User Instructions: Test on target tablet/TV browsers.

10. Optional Debug Overlay

Step 10.1: Debug overlay gated by ?debug=1
- Task: Create simple DOM overlay with sliders; only load when flag present.
- Files:
  - src/debug/debugOverlay.js
  - src/main.js: conditional import
  - src/core/config.js: expose config mutators in debug mode
- Step Dependencies: Step 9.1
- User Instructions: Access via http://localhost:5173/?debug=1

11. PWA Completion

Step 11.1: Service worker cache & offline
- Task: Implement install/activate/fetch handlers; precache core assets; versioning.
- Files:
  - public/sw.js: full cache logic
  - public/manifest.webmanifest: confirm scope/start_url
  - src/main.js: register SW (navigator.serviceWorker.register)
- Step Dependencies: Step 9.1
- User Instructions: In Chrome dev tools, “Application” tab → verify PWA installability.

12. Testing Setup

Step 12.1: Unit test framework
- Task: Configure Vitest/Jest; write initial mathUtil + governor tests.
- Files:
  - vitest.config.js or jest.config.cjs
  - test/unit/mathUtil.spec.js
  - test/unit/performanceGovernor.spec.js
- Step Dependencies: Step 8.1
- User Instructions: npm run test:unit
Step 12.2: E2E smoke test
- Task: Add Playwright; open page, verify canvas, no errors.
- Files:
  - playwright.config.ts
  - test/e2e/autoplay.spec.ts
- Step Dependencies: Step 9.1
- User Instructions: npx playwright install && npm run test:e2e

13. CI/CD Pipeline

Step 13.1: GitHub Actions workflow
- Task: Add workflow to lint, test, build; deploy to Pages/Netlify.
- Files:
  - .github/workflows/ci.yml: run lint/test/build
  - (If GitHub Pages) .github/workflows/deploy.yml: deploy dist
- Step Dependencies: Steps 12.1 & 12.2
- User Instructions: Configure repo secrets if using Netlify/Cloudflare; for Pages, enable it in repo settings.

14. QA & Optimization

Step 14.1: Manual device tests & tweaks
- Task: Test on iPad Safari, Android Chrome, TV browser; adjust constants.
- Files:
  - src/core/config.js: tweak defaults
  - Possibly minor fixes across mode files (<5 files)
- Step Dependencies: Step 11.1
- User Instructions: Manually test on actual hardware, record FPS/perceived engagement.

15. Release & Docs

Step 15.1: Finalize README & LICENSE
- Task: Document usage, dev/debug flags, build steps; add MIT license.
- Files:
  - README.md: production instructions + dev docs
  - LICENSE (MIT)
- Step Dependencies: Step 14.1
- User Instructions: None

Summary

We scaffold a Vite-based pure JS project, implement a modular Three.js engine with a mode system, attention resets, and a performance governor. We ensure autoplay + fullscreen with no UI, only an optional debug overlay. PWA caching provides offline capability. Testing (unit & E2E) and CI/CD are integrated. Each step is isolated to ≤20 files and sequenced logically for codegen automation.

Key complexities: performant motion algorithms, adaptive degradation, and ensuring fullscreen/autoplay across diverse browsers. Keep constants tweakable and avoid strobing. Future enhancements (workers, extra modes) can slot in after Step 6 without architectural changes.

scragz/01-idea.md

Idea Refinement

Required Inputs

Task Overview

Detailed Process Outline

Output Template

Context

Project Name

Description

Target Audience

Desired Features

Core Visual Loop

Environment & Startup Behavior

Performance & Safety

Architecture / Tech

Optional / Nice-to-Have (If you change your mind)

Design Requests

Other Notes

Technical Specification Generation

Required Inputs

Optional Inputs

Task Overview

Detailed Process Outline

Guidelines

Output Templates

Template A: New Project Specification

Template B: Existing Project Feature Specification

Context

Project Name

Description

Target Audience

Desired Features

Core Visual Loop

Environment & Startup Behavior

Performance & Safety

Architecture / Tech

Optional / Nice-to-Have (If you change your mind)

Design Requests

Other Notes

PawPursuit Technical Specification (New Project)

1. System Overview

2. Technology & Tools

3. Project Structure

4. Feature Specification

4.1 Core Visual Loop

4.2 Environment & Startup Behavior

4.3 Performance & Safety

4.4 Optional Dev Debug Mode

5. Database Schema

6. Server Actions

6.1 Database Actions

6.2 Other Backend Logic

7. Design System

7.1 Visual Style

7.2 UI Components

8. Component Architecture

8.1 Backend Components

8.2 Frontend Components

9. Authentication & Authorization

10. Data Flow

11. Payment Integration

12. Analytics Integration

13. Security & Compliance

14. Environment Configuration & Deployment

15. Testing

Summary & Next Steps

Implementation Plan Generation

Required Inputs

Task Overview

Detailed Process Outline

Output Template

Context

Implementation Plan

0. Prep & Repo Initialization

1. Public Shell & PWA Skeleton

2. Source Structure & Bootstrap

3. Render Loop & Timekeeping

4. Mode Interface & First Mode (Laser Dot)

5. Mode Manager & Auto Cycling

6. Additional Modes