# iwanni/useless-inventions-window-interaction architecture

> Architecture diagram of the GitHub repository iwanni/useless-inventions-window-interaction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iwanni/useless-inventions-window-interaction
- Repository: https://github.com/iwanni/useless-inventions-window-interaction

## Overview

1. **Project shape**
   - This is a **single-page, static browser demo** with no backend, no build pipeline, and no server-side state.
   - The entire app appears to live in **`index.html`**, with media assets in **`assets/`**.

2. **Primary runtime boundary**
   - The architecture is centered on **multiple browser windows/tabs** running the same page.
   - Each window acts as an independent client, and the “shared world” emerges from **cross-window communication** rather than any central service.

3. **Cross-window communication**
   - The main coordination mechanism is **`BroadcastChannel`**.
   - Windows broadcast their presence and positional data so each instance can detect the other window and react to it.
   - This is the key integration boundary for the app: **local window state → channel messages → remote window awareness**.

4. **Position and proximity model**
   - Each window tracks its own screen position and the other window’s position.
   - The app computes **distance between window centers** and uses that value as the main trigger for behavior.
   - The readme indicates a **510px threshold** and a **100ms update cadence**, so the interaction is effectively a low-frequency polling/coordination loop.

5. **Interaction logic**
   - Far apart: Goku stays in the default state.
   - Close enough: Goku switches into a powered-up / Kamehameha state.
   - The window-to-window relationship therefore drives a simple state machine: **idle → charging → firing/beam**.

6. **Orientation and mirroring**
   - The demo supports two roles, selected via URL parameter:
     - `?w=1` for the default orientation
     - `?w=2` for the mirrored orientation
   - This creates a symmetric setup where one window faces right and the other faces left, making the visual interaction feel directed across the screen.

7. **Audio subsystem**
   - The app uses three sound assets:
     - **charge**
     - **fire**
     - **beam loop/continuous beam**
   - Audio playback is sequenced, so the visual transition is paired with staged sound effects rather than a single one-shot clip.

8. **Browser interaction requirement**
   - Audio is gated behind a user gesture, so the app supports **click, tap, or keyboard input** to unlock sound.
   - This is a browser-policy boundary rather than an application-level feature, and it affects the startup flow.

9. **Media/assets layer**
   - The repo contains only static audio files in `assets/`:
     - `kame_charge.mp3`
     - `basicbeam_fire.mp3`
     - `beamhead.mp3`
   - The readme also references animated Goku/GIF assets, which are likely embedded in the HTML or fetched from elsewhere, and serve as the visual states for the interaction.

10. **User experience flow**
   - Open the same page in two windows.
   - Assign one as `w=1` and the other as `w=2`.
   - Move the windows around the screen.
   - Each window broadcasts its position, the other computes distance, and both update their visuals and audio in response.
   - The result is a loosely coupled, browser-native “battle” between windows with no central coordinator.

11. **Architecture summary**
   - Conceptually, the app has three layers:
     - **Presentation**: Goku animation/rotation and mirrored rendering
     - **Coordination**: BroadcastChannel-based window discovery and position exchange
     - **Effects**: distance-triggered audio sequencing and state transitions
   - This makes the app a good example of a **client-only, multi-instance interactive demo** built entirely on standard browser APIs.

Main entry points: [`index.html`](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/index.html) (App page), [`README.md`](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/README.md) (README), [`assets/kame_charge.mp3`](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/kame_charge.mp3) (Charge sound), [`assets/basicbeam_fire.mp3`](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/basicbeam_fire.mp3) (Fire sound)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_page["App page<br/>html demo<br/>[index.html]"]
  node_layout["Window roles<br/>ui"]
  node_goku["Goku view<br/>visual state"]
  node_mirror["Mirroring<br/>render transform"]
end

subgraph group_coordination["Coordination"]
  node_channel{{"BroadcastChannel<br/>browser api"}}
  node_presence["Presence sync<br/>window discovery"]
  node_position["Position sync<br/>window telemetry"]
  node_distance["Distance check<br/>proximity model"]
  node_loop["Update loop<br/>polling cadence"]
end

subgraph group_effects["Effects"]
  node_state["Battle state<br/>state machine"]
  node_audio["Audio cues<br/>sound pipeline"]
  node_unlock["Audio unlock<br/>gesture gate"]
end

subgraph group_assets["Assets"]
  node_charge["Charge sound<br/>audio asset<br/>[kame_charge.mp3]"]
  node_fire["Fire sound<br/>audio asset<br/>[basicbeam_fire.mp3]"]
  node_beam["Beam loop<br/>audio asset<br/>[beamhead.mp3]"]
end

node_readme["README<br/>docs<br/>[README.md]"]

node_readme -.->|"describes"| node_page
node_page -->|"selects"| node_layout
node_layout -->|"renders"| node_goku
node_layout -->|"applies"| node_mirror
node_page -->|"uses"| node_channel
node_channel -->|"carries"| node_presence
node_channel -->|"carries"| node_position
node_position -->|"feeds"| node_distance
node_loop -->|"ticks"| node_position
node_distance -->|"drives"| node_state
node_state -->|"updates"| node_goku
node_state -->|"triggers"| node_audio
node_unlock -->|"enables"| node_audio
node_audio -->|"plays"| node_charge
node_audio -->|"plays"| node_fire
node_audio -->|"loops"| node_beam
node_page -->|"listens for"| node_unlock

click node_readme "https://github.com/iwanni/useless-inventions-window-interaction/blob/main/README.md"
click node_page "https://github.com/iwanni/useless-inventions-window-interaction/blob/main/index.html"
click node_charge "https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/kame_charge.mp3"
click node_fire "https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/basicbeam_fire.mp3"
click node_beam "https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/beamhead.mp3"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_page,node_layout,node_goku,node_mirror toneBlue
class node_channel,node_presence,node_position,node_distance,node_loop toneAmber
class node_state,node_audio,node_unlock toneMint
class node_charge,node_fire,node_beam toneRose
class node_readme toneNeutral
```

## Components

### Presentation

Browser rendering and mirrored window layout

- [App page](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/index.html): html demo · Single-page client entrypoint · `index.html`
- **Window roles**: ui · Selects default or mirrored orientation
- **Goku view**: visual state · Animated character presentation and rotation
- **Mirroring**: render transform · Faces opposite window directions

### Coordination

Cross-window presence and position exchange

- **BroadcastChannel**: browser api · Cross-window message bus
- **Presence sync**: window discovery · Announces each instance to peers
- **Position sync**: window telemetry · Shares window screen position
- **Distance check**: proximity model · Compares window centers against threshold
- **Update loop**: polling cadence · Refreshes state about every 100ms

### Effects

Distance-triggered state and audio sequencing

- **Battle state**: state machine · Idle, charging, and firing transitions
- **Audio cues**: sound pipeline · Plays charge, fire, and beam loop
- **Audio unlock**: gesture gate · Enables playback after user interaction

### Assets

Static media used by the demo

- [Charge sound](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/kame_charge.mp3): audio asset · Charging cue · `assets/kame_charge.mp3`
- [Fire sound](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/basicbeam_fire.mp3): audio asset · Initial firing cue · `assets/basicbeam_fire.mp3`
- [Beam loop](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/assets/beamhead.mp3): audio asset · Continuous beam audio · `assets/beamhead.mp3`

### Other components

- [README](https://github.com/iwanni/useless-inventions-window-interaction/blob/main/README.md): docs · Usage and interaction notes · `README.md`

## Connections

- README → App page: describes · Documents the demo flow and controls
- App page → Window roles: selects · Chooses one of two mirrored roles
- Window roles → Goku view: renders · Places the character in each window
- Window roles → Mirroring: applies · Flips orientation for the opposing window
- App page → BroadcastChannel: uses · Initializes the cross-window message bus
- BroadcastChannel → Presence sync: carries · Broadcasts instance availability
- BroadcastChannel → Position sync: carries · Broadcasts screen position updates
- Position sync → Distance check: feeds · Supplies local and remote coordinates
- Update loop → Position sync: ticks · Runs the periodic position exchange
- Distance check → Battle state: drives · Switches between idle and powered-up behavior
- Battle state → Goku view: updates · Changes the visible animation state
- Battle state → Audio cues: triggers · Starts the staged sound sequence
- Audio unlock → Audio cues: enables · Allows playback after gesture input
- Audio cues → Charge sound: plays · Charge stage sound
- Audio cues → Fire sound: plays · Fire stage sound
- Audio cues → Beam loop: loops · Sustains the beam effect
- App page → Audio unlock: listens for · Waits for click, tap, or keyboard input
