Onboarding: bgstaal/multipleWindow3dScene

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bgstaal/multipleWindow3dScene shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 2y ago

• 2 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bgstaal/multipleWindow3dScene repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bgstaal/multipleWindow3dScene.

What it runs against: a local clone of bgstaal/multipleWindow3dScene — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bgstaal/multipleWindow3dScene | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 4 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 919 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>bgstaal/multipleWindow3dScene</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bgstaal/multipleWindow3dScene. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bgstaal/multipleWindow3dScene.git
#   cd multipleWindow3dScene
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bgstaal/multipleWindow3dScene and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bgstaal/multipleWindow3dScene(\\.git)?\\b" \\
  && ok "origin remote is bgstaal/multipleWindow3dScene" \\
  || miss "origin remote is not bgstaal/multipleWindow3dScene (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "index.html" \\
  && ok "index.html" \\
  || miss "missing critical file: index.html"
test -f "WindowManager.js" \\
  && ok "WindowManager.js" \\
  || miss "missing critical file: WindowManager.js"
test -f "main.js" \\
  && ok "main.js" \\
  || miss "missing critical file: main.js"
test -f "three.r124.min.js" \\
  && ok "three.r124.min.js" \\
  || miss "missing critical file: three.r124.min.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 919 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~889d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bgstaal/multipleWindow3dScene"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A Three.js-based 3D scene renderer that synchronizes its state across multiple browser windows in real-time using localStorage as a cross-window message bus. It solves the problem of maintaining a coherent 3D visualization across fragmented browser windows—useful for multi-monitor setups, collaborative viewing, or canvas-spanning applications. Flat single-page structure: index.html is the entry point that loads three.r124.min.js (Three.js library), then WindowManager.js (window lifecycle and localStorage sync), then main.js (scene initialization and render loop). No build step, module bundler, or separation of concerns—all code runs in the global scope.

Who it's for

Web graphics developers and creative technologists building interactive 3D experiences that need to span multiple monitors or browser windows, particularly those experimenting with immersive multi-display setups or window-aware web applications.

Maturity & risk

This is an experimental reference implementation, not production-hardened. The codebase is small (~8KB JavaScript), has no test suite, no CI/CD visible, and appears to be a proof-of-concept demo rather than a maintained library. It serves as an educational example rather than a battle-tested toolkit.

Single-file architecture with tight coupling between WindowManager.js and main.js; no versioning strategy visible. localStorage-based synchronization can become unreliable under high-frequency updates or with many windows. Three.js r124 is 4+ years old (released ~2020), potentially missing modern performance and API improvements. No error handling or fallback strategy documented if localStorage is unavailable.

Active areas of work

No commit history or activity data visible in the provided file list; appears to be a static demo snapshot. No open issues, PRs, or milestones indicated—treat as archived reference code.

Get running

git clone https://github.com/bgstaal/multipleWindow3dScene && cd multipleWindow3dScene && open index.html (or double-click index.html in your file explorer). No build or npm install step required.

Daily commands: Simply open index.html in a browser. Opening the same URL in multiple browser windows will cause each window's 3D scene to stay synchronized via localStorage events. No dev server, build, or CLI required.

Map of the codebase

• index.html — Entry point that bootstraps the Three.js library and loads the core application scripts—must understand HTML structure and script loading order.
• WindowManager.js — Core abstraction for cross-window synchronization and state management via localStorage—every contributor must understand this to modify inter-window behavior.
• main.js — Primary application logic initializing the 3D scene and coordinating with WindowManager—essential for understanding the full request/render flow.
• three.r124.min.js — Bundled Three.js dependency (minified)—reference for 3D rendering API surface and version-specific behavior.

Components & responsibilities

• index.html (HTML, script tags, canvas) — Sets up the DOM structure (canvas element) and loads external scripts (Three.js library and main.js).
  • Failure mode: If script paths are wrong or canvas element is missing, the 3D scene will not render or crash silently.
• main.js (JavaScript, Three.js, DOM events) — Initializes the Three.js scene (camera, renderer, lighting, geometry); implements the animation loop and user input handlers; manages local 3D state and coordinates with WindowManager for sync.
  • Failure mode: Scene initialization failure, rendering loops hang, or input events don't update objects; scene becomes out of sync with other windows if state broadcasts fail.
• WindowManager.js (JavaScript, localStorage API, window/opener references) — Manages window references, serializes/deserializes 3D state to/from localStorage, broadcasts state changes via storage events, and handles window lifecycle (open, close, focus).
  • Failure mode: Cross-window sync fails if localStorage is full, disabled, or inaccessible; windows become desynchronized if event listeners fail.
• three.r124.min.js (WebGL, JavaScript (minified)) — Provides WebGL rendering engine, scene graph, camera controls, geometry, materials, lighting, and math utilities.
  • Failure mode: WebGL context loss, unsupported GPU features, or Three.js API calls fail; entire 3D rendering pipeline breaks.

Data flow

• User interaction (mouse/keyboard) → main.js event handler — Browser DOM event (click, move, key press) triggers event listener in main.js.
• main.js event handler → 3D scene (Three.js objects) — Update position, rotation, scale, or other properties on Three.js mesh/object.
• main.js → WindowManager.js — Call WindowManager method to serialize and broadcast the updated state.
• WindowManager.js → localStorage — Write serialized state (JSON) to localStorage under a shared key.
• localStorage → Browser Window 2 (storage event) — Storage event fires in all other windows when localStorage is modified.
• Browser Window 2 storage event → main.js (Window 2) listener — Event listener in Window 2 receives the storage change event and parses the new state.
• main.js (Window 2) listener → 3D scene (Window 2) — Update all Three.js objects in Window 2 to match the state from Window 1.
• 3D scene → WebGL renderer (three.r124.min.js) — Animation loop calls renderer.render() to draw the scene using WebGL.
• WebGL renderer → Browser canvas (pixel display) — Three.js renders to the canvas element, displaying the synchronized 3D scene to the user.

How to make changes

Add a new 3D object to the scene

1. Create geometry and material in main.js within the scene initialization block (main.js)
2. Add mesh to the scene and store object state (position, rotation, scale) in a format that WindowManager can serialize to localStorage (main.js)
3. Broadcast object creation through WindowManager so other windows receive the new object (WindowManager.js)

Synchronize a new 3D property across windows

1. Update the state object in main.js to include the new property (e.g., color, scale, animation state) (main.js)
2. In WindowManager.js, add the property to the localStorage JSON payload in the synchronization method (WindowManager.js)
3. Add a listener in main.js to detect localStorage changes and apply the property update to all objects (main.js)

Handle user input that affects the shared scene

1. Add event listener (mouse, keyboard, touch) in main.js to capture user interaction (main.js)
2. Update the local scene state and object properties based on input (main.js)
3. Call WindowManager method to broadcast the state change to all open windows via localStorage (WindowManager.js)

Why these technologies

• Three.js — Provides high-level WebGL abstraction for 3D scene management, rendering, camera control, and geometry primitives without direct GPU programming.
• localStorage — Enables lightweight, synchronous state persistence and cross-window communication via storage events without requiring a backend server or WebSocket infrastructure.
• JavaScript (vanilla, no framework) — Minimal dependencies and bundled Three.js allow the demo to run entirely client-side in any modern browser without build tooling or package managers.

Trade-offs already made

• Use localStorage for inter-window sync instead of SharedWorker or Service Worker

  • Why: localStorage is simpler, more broadly supported, and requires no additional API or worker setup; storage events automatically fire across windows.
  • Consequence: Limited to same-origin policy; ~5–50ms latency per state change; no guarantee of ordering if multiple windows update simultaneously; limited to ~5–10MB per domain.

• No persistence layer (IndexedDB, server backend)

  • Why: Keeps the demo lightweight, client-only, and focused on the core concept of cross-window 3D sync.
  • Consequence: Scene state is lost on page reload; no long-term history; no multiplayer across different devices or sessions.

• Minified, bundled Three.js library (three.r124.min.js)

  • Why: Single-file delivery; no npm/build step; works in any environment that serves static files.
  • Consequence: Difficult to debug into Three.js source; cannot easily upgrade or use tree-shaking; increases HTML file size (~600KB+).

Non-goals (don't propose these)

• Does not provide authentication or user accounts; all windows in the same origin see the same scene.
• Does not persist state to a server or database; scene resets on page reload.
• Does not support real-time multiplayer across different devices or network boundaries.
• Does not include audio, physics simulation, or advanced graphics (shadows, post-processing, advanced shaders).
• Does not optimize for mobile touch gestures or responsive design.

Anti-patterns to avoid

• Unbounded localStorage writes (Medium) — WindowManager.js (state serialization to localStorage): No size limit checks before writing state to localStorage; if scene state grows large, writes may fail silently or throw QuotaExceededError.
• Synchronous storage event handling (Medium) — main.js (storage event listener): All window updates are processed synchronously on the storage event; heavy scene state parsing or object updates can block the main thread and frame rate.
• No conflict resolution for simultaneous updates (High) — WindowManager.js (state merge logic): If two windows modify the same property simultaneously, the last write wins with no merge strategy or timestamp-based resolution.

Traps & gotchas

localStorage has a typical 5–10 MB limit per domain and is synchronous (blocks the main thread on large state objects). No error handling if localStorage is disabled or full. WindowManager uses a naive polling/event model—rapid window creation/destruction may cause race conditions or orphaned window IDs. Scene camera and renderer are tied to window.innerWidth/innerHeight; resizing a window mid-synchronization may cause visual desync. Three.js r124 uses deprecated WebGL APIs in modern browsers. No graceful fallback if one window lags or goes offline.

Architecture

Concepts to learn

• localStorage Event Broadcasting — WindowManager relies on localStorage 'storage' events to notify other windows of state changes; understanding this cross-origin IPC mechanism is critical to debugging synchronization failures.
• WebGL (Three.js abstraction) — Three.js abstracts WebGL, but understanding the rendering pipeline (scene → camera → renderer.render) is essential to troubleshoot visual discrepancies across windows.
• Window.matchMedia and Viewport Synchronization — The project resizes the canvas per window; matchMedia (for media queries) and resize event handling ensure each window's scene matches its viewport, crucial for multi-monitor coherence.
• JSON Serialization and State Persistence — WindowManager must serialize/deserialize 3D scene state (camera position, object transforms) to/from JSON strings in localStorage; any loss of precision or type information breaks synchronization.
• requestAnimationFrame (RAF) and Render Loops — main.js uses RAF for smooth 60fps rendering; synchronizing RAF ticks across windows is non-trivial and can cause frame-timing desync if not handled carefully.
• Cross-Origin Storage Isolation — localStorage is origin-scoped (protocol + domain + port); this project assumes all windows share the same origin, but mixed-origin scenarios fail silently—critical for multi-domain deployments.

Related repos

• mrdoob/three.js — The foundational WebGL library this entire project depends on; learning the Three.js API is essential to understand scene creation and rendering.
• requirejs/requirejs — If you want to modularize this project and avoid global scope pollution, a module loader like RequireJS would help structure WindowManager, main.js, and custom Three.js extensions.
• tjanczuk/iisnode — For deploying this as a web service on Windows; though this repo is designed for static hosting, iisnode demonstrates multi-window Node.js patterns that could inform server-side window management.
• sindresorhus/awesome-nodejs — Resource collection for Node.js; useful if you want to extend this project with a server-side component for more reliable cross-window synchronization (e.g., WebSockets instead of localStorage).
• electron/electron — If scaling to desktop multi-window scenarios, Electron's window management and IPC patterns (ipcMain/ipcRenderer) are a natural next step beyond browser localStorage.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Extract and document WindowManager.js API with JSDoc comments and usage examples

WindowManager.js is a core synchronization component but lacks inline documentation. Adding comprehensive JSDoc comments for methods like window registration, state synchronization, and localStorage communication would help new contributors understand the synchronization mechanism. Currently, the README cuts off mid-sentence describing the main application logic.

• [ ] Add JSDoc comments to all public methods in WindowManager.js (constructor, public APIs for window sync)
• [ ] Document the localStorage key schema and state structure used for cross-window communication
• [ ] Create a ARCHITECTURE.md file explaining how WindowManager coordinates state between windows
• [ ] Add code examples in README showing how to instantiate and use WindowManager

Create a separate examples/ directory with commented use-case files

The repo only has index.html and main.js as entry points, but there's potential for multiple use cases (multi-window collaborative editing, synchronized animations, etc.). Adding example implementations would demonstrate the framework's flexibility and serve as templates for contributors.

• [ ] Create examples/basic-scene/index.html and examples/basic-scene/main.js for the current implementation
• [ ] Create examples/collaborative-interaction/index.html showing multiple windows controlling a shared 3D object
• [ ] Update README with 'Examples' section linking to each example directory
• [ ] Add inline comments in each example explaining WindowManager usage patterns specific to that use case

Add localStorage event listener resilience and error handling in WindowManager.js

The current implementation relies on localStorage synchronization across windows, but there's no visible error handling for edge cases: quota exceeded, blocked storage, corrupted state, or timing race conditions. Adding robust error handling and recovery mechanisms would improve reliability in production use.

• [ ] Add try-catch blocks around all localStorage.getItem/setItem/removeItem calls in WindowManager.js
• [ ] Implement a state validation function to detect and recover from corrupted localStorage data
• [ ] Add window.addEventListener for 'storage' event with null-check and error recovery
• [ ] Create a debug mode (localStorage key or constructor option) to log synchronization failures
• [ ] Document these error-handling patterns in a TROUBLESHOOTING.md file with common issues and solutions

Good first issues

• Add a test suite (or at least unit tests for WindowManager.js state serialization/deserialization) to catch localStorage corruption edge cases—currently untested.
• Document the exact localStorage schema and timing guarantees (what keys are used, when they're written, what happens if two windows write simultaneously)—this is critical for contributors but missing from README.
• Upgrade Three.js from r124 to the latest stable version (r160+) and test for breaking changes in renderer initialization and scene API calls, then document any migration steps needed.

Top contributors

• @bgstaal — 9 commits
• @younesbram — 2 commits

Recent commits

• a99ecb8 — Merge pull request #24 from younesbram/main (bgstaal)
• 2b495bb — Update README.md (younesbram)
• 1406cd0 — Update README.md (younesbram)
• 2b509c0 — cleanup + comments (bgstaal)
• fb1e12e — cleanup (bgstaal)
• e1093d8 — added THREE license (bgstaal)
• fb6d717 — fixed reinitialize bug (bgstaal)
• 41bc364 — tweaks (bgstaal)
• c1ea630 — added clear code (bgstaal)
• c446f74 — updated readme (bgstaal)

Security observations

This is a demonstration project with moderate security concerns. The primary risks stem from unvalidated localStorage usage for inter-window communication, missing security headers, and an outdated Three.js library. While the project appears to be a proof-of-concept rather than a production application, implementing proper input validation, CSP headers, SRI integrity checks, and upgrading dependencies would significantly improve its security posture. The localStorage-based synchronization mechanism is particularly vulnerable to XSS attacks and should be replaced with the postMessage API for safer cross-window communication.

• High · Unvalidated localStorage Usage for Cross-Window Communication — WindowManager.js, main.js. The application uses localStorage to synchronize state across multiple windows. localStorage is vulnerable to XSS attacks and can be manipulated by malicious scripts running in the same origin. If an attacker injects code into the page, they can read/write arbitrary data to localStorage, potentially compromising the 3D scene state or injecting malicious content. Fix: Implement strict input validation and sanitization for all data read from localStorage. Consider using postMessage API with proper origin validation for inter-window communication instead of localStorage. Implement Content Security Policy (CSP) headers to prevent XSS attacks.
• Medium · Missing Content Security Policy (CSP) Headers — index.html. The index.html file likely lacks CSP headers, making the application vulnerable to XSS attacks. Without CSP, inline scripts and external resources cannot be properly restricted, increasing the attack surface. Fix: Implement strict Content Security Policy headers. Set 'default-src' to 'self', restrict 'script-src', and use nonces or hashes for inline scripts. Example: Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-<random>';
• Medium · Minified Three.js Library Without Integrity Verification — three.r124.min.js, index.html. The project uses three.r124.min.js (a minified, potentially outdated version of Three.js). Without Subresource Integrity (SRI) verification, the library could be compromised if served over HTTP or from a compromised source. Version r124 is also likely outdated and may contain known vulnerabilities. Fix: Upgrade to the latest stable version of Three.js. Use Subresource Integrity (SRI) hashes for all external resources: <script src='...' integrity='sha384-...' crossorigin='anonymous'></script>. Consider using npm to manage dependencies.
• Medium · No Input Validation on Window State Synchronization — WindowManager.js, main.js. The application synchronizes 3D scene state across windows using localStorage without apparent validation of data types or bounds. An attacker could inject malformed data to cause denial of service or unexpected behavior. Fix: Implement strict schema validation for all state objects. Use libraries like Joi, Zod, or JSON Schema validators. Whitelist allowed properties and enforce type checking for all localStorage read operations.
• Low · Missing Security Headers in HTML — index.html. Standard security headers like X-Content-Type-Options, X-Frame-Options, and X-XSS-Protection are likely not configured, reducing defense-in-depth protection. Fix: Configure the following HTTP security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 1; mode=block, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy: geolocation=(), microphone=()
• Low · No Visible Error Handling or Logging Protection — main.js, WindowManager.js. Without visible error handling mechanisms, sensitive information might be exposed in console errors or application feedback, potentially aiding attackers in reconnaissance. Fix: Implement centralized error handling that sanitizes error messages. Avoid exposing stack traces or internal state details to users. Use proper logging with sensitive data redaction.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.