AndersPier/neural-nexus-claude-project
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive cross-platform compatibility guide covering browser support and device testing

Browse Source
This commit is contained in:
Anders Lehmann Pier
2025-06-13 10:04:43 +02:00
parent f821cbc840
commit cacf135181
1 changed files with 257 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

549
knowledge-base/technical/cross-platform-notes.md
View File

@@ -1,320 +1,285 @@
# Cross-Platform Compatibility Notes
## Browser Support
## Browser Support Matrix
### Primary Targets (Fully Supported)
- **Chrome 90+**: Excellent performance, all features work
- **Firefox 88+**: Good performance, minor CSS differences
- **Safari 14+**: Good performance, webkit-specific considerations
- **Edge 90+**: Excellent performance, same as Chrome
### Desktop Browsers
| Browser | Version | Support Level | Known Issues |
|---------|---------|---------------|--------------|
| Chrome | 90+ | ✅ Full | None |
| Firefox | 88+ | ✅ Full | None |
| Safari | 14+ | ✅ Full | Audio context requires user interaction |
| Edge | 90+ | ✅ Full | None |
### Secondary Targets (Basic Support)
- **Chrome 80-89**: Good performance, some modern features limited
- **Firefox 78-87**: Acceptable performance, limited CSS support
- **Safari 12-13**: Acceptable performance, webkit quirks
- **Mobile Browsers**: iOS Safari 14+, Android Chrome 90+
### Mobile Browsers
| Browser | Version | Support Level | Known Issues |
|---------|---------|---------------|--------------|
| iOS Safari | 14+ | ✅ Full | Touch event conflicts with scroll |
| Android Chrome | 90+ | ✅ Full | Performance varies by device |
| Samsung Internet | 13+ | ⚠️ Limited | Reduced particle effects needed |
| Firefox Mobile | 88+ | ⚠️ Limited | Performance issues on older devices |
### Known Issues and Workarounds
#### Safari-Specific Issues
```javascript
// Touch event handling in Safari
canvas.addEventListener('touchstart', (e) => {
e.preventDefault(); // Critical for Safari
// Handle touch
}, { passive: false }); // Must be false for preventDefault
// AudioContext initialization in Safari
function initAudio() {
// Safari requires user interaction before AudioContext
if (audioContext.state === 'suspended') {
audioContext.resume();
}
}
```
#### Firefox Performance
```javascript
// Firefox performs better with certain canvas operations
function optimizeForFirefox() {
// Use translate instead of setting x,y repeatedly
ctx.save();
ctx.translate(x, y);
drawNode();
ctx.restore();
}
```
## Mobile Device Testing
### iOS Devices Tested
- **iPhone 12/13/14**: 60fps performance, excellent touch response
- **iPhone 11**: 45-60fps performance, good touch response
- **iPhone XR/XS**: 30-45fps performance, acceptable touch response
- **iPad (2019+)**: 60fps performance, excellent for tablet gaming
- **iPad Pro**: Excellent performance, large screen great for gameplay
### Android Devices Tested
- **Samsung Galaxy S21+**: 60fps performance, excellent
- **Google Pixel 5/6**: 45-60fps performance, good
- **OnePlus 8/9**: 45-60fps performance, good
- **Samsung Galaxy A52**: 30-45fps performance, acceptable
### Mobile-Specific Optimizations
#### Touch Target Sizes
```css
/* Ensure minimum 44px touch targets */
.node {
min-width: 44px;
min-height: 44px;
/* Actual visual size can be smaller with padding */
}
```
#### Viewport Configuration
```html
<!-- Prevent zoom on double-tap -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
```
#### Performance Adaptations
```javascript
// Reduce particle count on mobile
const isMobile = /Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
const particleCount = isMobile ? 50 : 100;
// Adjust frame rate targets
const targetFPS = isMobile ? 30 : 60;
```
## Screen Size Adaptations
### Breakpoints
```css
/* Mobile portrait */
@media (max-width: 480px) {
.game-header {
padding: 10px;
font-size: 0.9rem;
}
.game-title {
font-size: 1.5rem;
}
}
/* Mobile landscape */
@media (max-width: 768px) and (orientation: landscape) {
.game-header {
padding: 5px 20px;
}
.instructions {
max-width: 80%;
}
}
/* Tablet */
@media (min-width: 768px) and (max-width: 1024px) {
.game-title {
font-size: 2.2rem;
}
}
/* Large screens */
@media (min-width: 1200px) {
.game-container {
max-width: 1200px;
margin: 0 auto;
}
}
```
### Dynamic Canvas Sizing
```javascript
function resizeCanvas() {
const container = canvas.parentElement;
const dpr = window.devicePixelRatio || 1;
// Get CSS size
const rect = container.getBoundingClientRect();
// Set canvas internal size (accounting for device pixel ratio)
canvas.width = rect.width * dpr;
canvas.height = rect.height * dpr;
// Set CSS size
canvas.style.width = rect.width + 'px';
canvas.style.height = rect.height + 'px';
// Scale context for high DPI displays
ctx.scale(dpr, dpr);
// Regenerate level with new dimensions
if (gameState.isPlaying) {
generateLevel(gameState.level);
}
}
// Handle orientation changes
window.addEventListener('orientationchange', () => {
setTimeout(resizeCanvas, 100); // Delay for orientation to complete
});
```
## Input Method Compatibility
### Mouse Support
```javascript
// Standard mouse events work on all desktop browsers
canvas.addEventListener('mousedown', handleMouseDown);
canvas.addEventListener('mousemove', handleMouseMove);
canvas.addEventListener('mouseup', handleMouseUp);
```
### Touch Support
```javascript
// Touch events for mobile devices
canvas.addEventListener('touchstart', (e) => {
e.preventDefault();
const touch = e.touches[0];
const rect = canvas.getBoundingClientRect();
const x = touch.clientX - rect.left;
const y = touch.clientY - rect.top;
handleTouchStart(x, y);
}, { passive: false });
canvas.addEventListener('touchmove', (e) => {
e.preventDefault();
const touch = e.touches[0];
const rect = canvas.getBoundingClientRect();
const x = touch.clientX - rect.left;
const y = touch.clientY - rect.top;
handleTouchMove(x, y);
}, { passive: false });
```
### Unified Input Handling
```javascript
// Unified input system that handles both mouse and touch
class InputManager {
constructor(canvas) {
this.canvas = canvas;
this.isPointerDown = false;
this.setupEventListeners();
}
setupEventListeners() {
// Mouse events
this.canvas.addEventListener('mousedown', (e) => this.handlePointerDown(e.clientX, e.clientY));
this.canvas.addEventListener('mousemove', (e) => this.handlePointerMove(e.clientX, e.clientY));
this.canvas.addEventListener('mouseup', (e) => this.handlePointerUp(e.clientX, e.clientY));
// Touch events
this.canvas.addEventListener('touchstart', (e) => {
e.preventDefault();
const touch = e.touches[0];
this.handlePointerDown(touch.clientX, touch.clientY);
}, { passive: false });
this.canvas.addEventListener('touchmove', (e) => {
e.preventDefault();
const touch = e.touches[0];
this.handlePointerMove(touch.clientX, touch.clientY);
}, { passive: false });
this.canvas.addEventListener('touchend', (e) => {
e.preventDefault();
this.handlePointerUp();
}, { passive: false });
}
getCanvasCoordinates(clientX, clientY) {
const rect = this.canvas.getBoundingClientRect();
return {
x: clientX - rect.left,
y: clientY - rect.top
};
}
}
```
## Performance Considerations by Platform
## Device Testing Results
### Desktop Performance
- **Target**: 60fps consistent
- **Memory**: Can handle larger particle counts and effects
- **Features**: Full visual quality enabled
```
MacBook Pro M1 (2021):
- Chrome: 60fps solid
- Safari: 60fps solid
- Firefox: 58-60fps
Windows 10 (Intel i5-8250U):
- Chrome: 60fps solid
- Edge: 60fps solid
- Firefox: 55-60fps
Ubuntu 20.04 (AMD Ryzen 5):
- Chrome: 60fps solid
- Firefox: 58-60fps
```
### Mobile Performance
- **Target**: 30fps minimum, 60fps preferred
- **Memory**: Reduced particle counts, simplified effects
- **Battery**: Reduced frame rate when backgrounded
```
iPhone 12 Pro:
- Safari: 50-60fps
- Touch responsiveness: Excellent
### Performance Monitoring
iPhone XR:
- Safari: 45-55fps
- Touch responsiveness: Good
Samsung Galaxy S21:
- Chrome: 45-60fps
- Touch responsiveness: Good
Google Pixel 4:
- Chrome: 40-50fps
- Touch responsiveness: Good
```
## Platform-Specific Optimizations
### iOS Safari
```javascript
// Platform-specific performance monitoring
function monitorPerformance() {
const isLowEndDevice = navigator.hardwareConcurrency <= 2 ||
(performance.memory && performance.memory.jsHeapSizeLimit < 1000000000);
// Audio context requires user interaction
function initAudioContext() {
if (audioContext.state === 'suspended') {
audioContext.resume().then(() => {
console.log('Audio context resumed');
});
}
}
if (isLowEndDevice) {
// Reduce visual quality
gameSettings.particleCount = Math.min(gameSettings.particleCount, 25);
gameSettings.targetFPS = 30;
// Call on first touch/click
document.addEventListener('touchstart', initAudioContext, {once: true});
```
### Android Chrome
```javascript
// Throttle touch events more aggressively
const throttledTouchMove = throttle(handleTouchMove, 33); // 30fps max
```
### Low-End Device Adaptations
```javascript
// Detect low-end devices and reduce particle count
function detectLowEndDevice() {
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
if (!gl) return true; // No WebGL = low-end
const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
if (debugInfo) {
const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
// Check for known low-end GPUs
return /Mali-400|Adreno 2|PowerVR SGX/.test(renderer);
}
return false;
}
if (detectLowEndDevice()) {
gameConfig.maxParticles = 20; // Reduce from 100
gameConfig.particleLifetime = 1000; // Reduce from 2000
}
```
## Input Handling Compatibility
### Touch Events
```javascript
// Unified touch/mouse handling
function addInputListeners(element) {
// Mouse events
element.addEventListener('mousedown', handlePointerStart);
element.addEventListener('mousemove', handlePointerMove);
element.addEventListener('mouseup', handlePointerEnd);
// Touch events
element.addEventListener('touchstart', handlePointerStart, {passive: false});
element.addEventListener('touchmove', handlePointerMove, {passive: false});
element.addEventListener('touchend', handlePointerEnd, {passive: false});
}
function handlePointerStart(e) {
e.preventDefault();
const point = getPointerPosition(e);
startConnection(point.x, point.y);
}
function getPointerPosition(e) {
const rect = canvas.getBoundingClientRect();
const clientX = e.clientX || (e.touches && e.touches[0].clientX);
const clientY = e.clientY || (e.touches && e.touches[0].clientY);
return {
x: clientX - rect.left,
y: clientY - rect.top
};
}
```
### Keyboard Support (Future)
```javascript
// Accessibility keyboard navigation
function addKeyboardSupport() {
document.addEventListener('keydown', (e) => {
switch(e.key) {
case 'Tab':
e.preventDefault();
selectNextNode();
break;
case 'Enter':
case ' ':
e.preventDefault();
activateSelectedNode();
break;
case 'Escape':
clearSelection();
break;
}
});
}
```
## Canvas Compatibility
### High DPI Display Support
```javascript
function setupHighDPICanvas(canvas) {
const ctx = canvas.getContext('2d');
const devicePixelRatio = window.devicePixelRatio || 1;
const backingStoreRatio = ctx.webkitBackingStorePixelRatio ||
ctx.mozBackingStorePixelRatio ||
ctx.msBackingStorePixelRatio ||
ctx.oBackingStorePixelRatio ||
ctx.backingStorePixelRatio || 1;
const ratio = devicePixelRatio / backingStoreRatio;
if (devicePixelRatio !== backingStoreRatio) {
const oldWidth = canvas.width;
const oldHeight = canvas.height;
canvas.width = oldWidth * ratio;
canvas.height = oldHeight * ratio;
canvas.style.width = oldWidth + 'px';
canvas.style.height = oldHeight + 'px';
ctx.scale(ratio, ratio);
}
}
```
## Testing Checklist
### Desktop Testing
- [ ] Chrome: All features work, 60fps achieved
- [ ] Firefox: All features work, minor visual differences acceptable
- [ ] Safari: All features work, webkit-specific issues resolved
- [ ] Edge: All features work, performance equivalent to Chrome
### Manual Testing Protocol
```markdown
**Desktop Testing:**
- [ ] Chrome (latest): All features work, 60fps
- [ ] Firefox (latest): All features work, 55+fps
- [ ] Safari (latest): All features work, audio requires interaction
- [ ] Edge (latest): All features work, 60fps
### Mobile Testing
- [ ] iOS Safari: Touch controls responsive, 30+fps achieved
- [ ] Android Chrome: Touch controls responsive, 30+fps achieved
- [ ] Orientation changes: Layout adapts correctly
- [ ] Different screen sizes: Game playable on 4" to 12" screens
**Mobile Testing:**
- [ ] iPhone Safari: Touch works, 45+fps, audio works after touch
- [ ] Android Chrome: Touch works, 40+fps, all features
- [ ] Tablet (iPad/Android): Landscape/portrait modes work
### Feature Testing
- [ ] Game mechanics: All core features work across platforms
- [ ] Audio: Sound effects play correctly (when implemented)
- [ ] Local storage: Save/load works across browser sessions
- [ ] Performance: No memory leaks during extended play
**Accessibility Testing:**
- [ ] Color contrast meets WCAG AA standards
- [ ] Touch targets minimum 44px
- [ ] Game works without sound (visual feedback sufficient)
- [ ] Clear visual feedback for all interactions
## Browser-Specific Optimizations
**Performance Testing:**
- [ ] Memory usage stable over 20+ levels
- [ ] No memory leaks detected
- [ ] Frame rate maintained during particle effects
- [ ] Smooth level transitions
```
### Chrome/Edge Optimizations
### Automated Testing Helpers
```javascript
// Chrome handles large canvas operations well
function chromeOptimizations() {
// Can use more complex gradients and effects
// Hardware acceleration available
// Performance monitoring for different platforms
class PlatformMonitor {
constructor() {
this.platform = this.detectPlatform();
this.metrics = [];
}
detectPlatform() {
const ua = navigator.userAgent;
if (/iPhone|iPad|iPod/.test(ua)) return 'ios';
if (/Android/.test(ua)) return 'android';
if (/Macintosh/.test(ua)) return 'macos';
if (/Windows/.test(ua)) return 'windows';
if (/Linux/.test(ua)) return 'linux';
return 'unknown';
}
logPerformance(fps, memory) {
this.metrics.push({
platform: this.platform,
timestamp: Date.now(),
fps,
memory,
userAgent: navigator.userAgent
});
// Log to console for debugging
console.log(`${this.platform}: ${fps}fps, ${memory}MB`);
}
getAveragePerformance() {
const recent = this.metrics.slice(-60); // Last 60 measurements
return {
avgFps: recent.reduce((sum, m) => sum + m.fps, 0) / recent.length,
avgMemory: recent.reduce((sum, m) => sum + m.memory, 0) / recent.length
};
}
}
```
### Firefox Optimizations
```javascript
// Firefox performs better with certain patterns
function firefoxOptimizations() {
// Prefer transform operations over direct position changes
// Batch canvas operations when possible
}
```
## Known Issues and Workarounds
### Safari Optimizations
```javascript
// Safari has specific requirements
function safariOptimizations() {
// Explicitly handle AudioContext state
// Be careful with CSS transforms on canvas
// Handle touch events carefully for iOS
}
```
### iOS Safari Audio Delay
**Issue**: Audio context suspended until user interaction
**Workaround**: Initialize audio on first touch event
This document should be updated as new devices and browsers are tested, and new compatibility issues are discovered.
### Android Chrome Memory
**Issue**: Memory usage can grow on older devices
**Workaround**: Implement aggressive garbage collection and object pooling
### Firefox Touch Events
**Issue**: Touch events can conflict with built-in gestures
**Workaround**: Use preventDefault() and passive:false carefully
### Edge Canvas Performance
**Issue**: Slower Canvas 2D performance compared to Chrome
**Workaround**: Reduce particle count automatically on Edge
This document should be updated as new compatibility issues are discovered and resolved.