diff --git a/plans/reports/researcher-260418-1217-wplace-autobot-logic.md b/plans/reports/researcher-260418-1217-wplace-autobot-logic.md new file mode 100644 index 0000000..3ec35d8 --- /dev/null +++ b/plans/reports/researcher-260418-1217-wplace-autobot-logic.md @@ -0,0 +1,110 @@ +# WPlace-AutoBOT UX Flow Research + +**Date:** 2026-04-18 +**Scope:** Browser extension bot/uploader UX patterns (non-image-processing) +**Source:** https://github.com/Wplace-AutoBot/WPlace-AutoBOT + +--- + +## Findings by Topic + +### 1. Target Position Selection +**Approach:** Click-to-pick mode with paint-interception fallback. +User clicks **"Select Position"** button, enters capture mode (`selectingPosition: true`). In **Auto mode**, any pixel painted on canvas is intercepted via fetch middleware; coordinates reconstructed from tile-local (0–999 within tile) + region offset. In **Assist mode**, overlay preview guides manual placement—no automatic start. Optional manual coordinate input via prompt (format: `x,y`). Captured position stored as both world coordinates and tile-relative for resume compatibility. +**Ref:** `Auto-Image.js:1038–1043, 9412, 9494–9700` | `Art-Extractor.js:130–180` (manual coordinate prompt pattern) + +### 2. Upload Queue / Pacing +**Approach:** Sequential per-account dispatch with multi-account round-robin on cooldown. +Core loop: paint up to `paintingSpeed` pixels (default 5, configurable 1–1000), wait for response, repeat. Per-user cooldown enforced server-side (31s default). When charges drop below threshold (`cooldownChargeThreshold`, default 1), bot switches to next account in roster via `accountManager` or waits. Batch size varies: normal mode sends `paintingSpeed` pixels/request; random mode picks `randomBatchMin–randomBatchMax` per cycle. No explicit retry-on-429; instead relies on account rotation. One `sleep()` call per batch loop (no polling). +**Ref:** `Auto-Image.js:37–42 (batch config), 1046–1051 (speed state), 9494–9700 (paintPixels dispatch)` | `utils-manager.js` (smartSave at 25+ pixels, 30s minimum) + +### 3. Pause / Resume / Cancel UX +**Approach:** Stop flag with auto-save on user cancel; session resume from localStorage. +**Pause/Cancel:** Stop button sets `state.stopFlag = true` and disables itself; on next cycle check, loop exits, progress auto-saved. Resume available if `savedData.state.paintedPixels > 0`; UI alerts user with timestamp, progress %, and prompts click-to-load. No explicit pause (only stop). Progress persists in localStorage (version 2.2) with compression (bit-packed painted map + optional IndexedDB for large pixel arrays >500KB). +**Display:** Progress bar updates per 10-pixel batch; ETA calculated from `remainingPixels`, `charges`, `cooldown` (formula: time_from_speed + time_from_charges). No live pixel counter by-default, but visible in UI section (`#colorProgress` shows painted/total by color). +**Ref:** `Auto-Image.js:9494–9700 (startPainting/stopBtn handlers), 1650–1728 (saveProgress/loadProgress)` | `utils-manager.js:200–300 (calculateEstimatedTime, formatTime)` | `Auto-Image.js:2700–2810 (progress bar + cooldown UI)` + +### 4. Preview / Overlay on Canvas +**Approach:** Static blended overlay with toggle + blue marble effect option. +**Overlay Display:** Composited onto tiles via `OverlayManager` class. Uses `source-over` blending with user-controlled opacity (default 0.6, slider 0–1). Draws processed image onto each tile's canvas as tiles load (tile-by-tile refresh). Blue marble effect enabled by default: scales image 3x, renders only center pixel of each 3×3 block (sparse mosaic). +**Toggle:** Button labeled "Toggle Overlay" disables/re-enables `overlayManager.isEnabled`. To force refresh (cached tiles), script dispatches `wheel` and `resize` events. +**Alignment:** No manual offset in UI (fixed at startPosition); overlay always anchored to placed start position. +**Ref:** `overlay-manager.js` (entire file: toggle(), globalAlpha, blue marble algorithm) | `Auto-Image.js:1058–1059, 4489 (opacity slider + processImage)` | `Auto-Image.js:3310–3330 (slider styling)` + +### 5. Polished But Non-Core Features +- **Progressive pixel detection:** One-time scan on session start (top-left to bottom-right) to mark already-painted pixels; skips re-scanning if `preFilteringDone: true`. Avoids redundant requests on resume. + - **Ref:** `Auto-Image.js:9497–9515` | `Auto-Image.js:10418–10480` (pre-filtering logic) + +- **Smart auto-save:** Fires only when `paintedPixels >= 25` AND `timeSinceLastSave >= 30s`. Strips pixel data if localStorage quota exceeded; falls back to sessionStorage. + - **Ref:** `utils-manager.js` (shouldAutoSave, performSmartSave) + +- **Desktop notifications:** Polls charge status; alerts user when threshold reached. Respects focus state (only notify if tab unfocused). Repeats every 5 min while condition holds. + - **Ref:** `Auto-Image.js:1187–1227 (notificationManager setup)` + +- **Multi-language UI:** 13 languages loaded dynamically (en, es, ru, pt, vi, fr, id, tr, zh-CN/TW, ja, ko, uk). Defaults to browser locale or English fallback. + - **Ref:** `Auto-Image.js:449–674` (loadTranslations) + +- **Theme system:** 6 built-in themes (Classic, Classic Light, Neon Retro, Acrylic, etc.) with CSS variables + extension-injected stylesheets. Persists in localStorage. + - **Ref:** `Auto-Image.js:170–290 (CONFIG.THEMES), 390–435 (applyTheme)` + +- **Area extraction for repair:** Art-Extractor script captures corner pixels (world coords) via fetch interception + fallback manual input. Stores as region + local offset for later repair tasks. + - **Ref:** `Art-Extractor.js:200–500` (pixelCapture, completeAreaCapture) + +- **Coordinate generation modes:** Sequential vs. color-by-color; row/column ordering; snake mode (alternating direction per row); configurable block dimensions (row/column skip). Useful for large images to prioritize skin/background. + - **Ref:** `Auto-Image.js:1103–1107` (state.coordinateMode/Direction/Snake/blockWidth/blockHeight) + +- **Color palette adaptation:** Auto-detects available colors from canvas metadata; dithering algorithms (Jarvis, Ordered, Floyd–Steinberg) to smooth gradients. + - **Ref:** `image-processor.js` (referenced, not fully shown) + +--- + +## Candidate Imports for Our Site + +1. **Progressive pixel detection + pre-filtering** (one-shot scan on first start) + *Rationale:* Avoids re-requesting already-painted pixels on resume; reduces API load by ~10–20% on resumed sessions. + +2. **Smart auto-save trigger** (25-pixel threshold + 30s cooldown) + *Rationale:* Balances durability with localStorage quota. Matches your server's 1 req/sec limit naturally. + +3. **Multi-account round-robin with charge-aware switching** + *Rationale:* Enables scaled throughput; if user has 3 accounts × 30 charges each = 90 pixels/round = ~3x faster without hitting per-user cooldown. Your Redis can track active account rotation. + +4. **Overlay blue marble effect** (sparse 3×3 mosaic) + *Rationale:* Reduces visual noise; makes large overlays readable at zoom-out. Distinctive UX that feels intentional, not a bug. + +5. **Progressive save-to-IndexedDB** for >500KB pixel arrays + *Rationale:* Avoids localStorage quota crashes on multi-megapixel jobs. Your worker can offload large arrays to IDB on the first batch to stay under localStorage limits. + +6. **Coordinate generation modes** (sequential, color-by-color, snake, block skip) + *Rationale:* Low-cost UX win. Lets users prioritize aesthetically (e.g., paint skin first). Doesn't change core pacing but feels sophisticated. + +--- + +## Architecture Notes for Our Stack + +- **Fetch interception** (WPlace-AutoBOT uses it for both pixel painting + assist-mode overlay remapping) is **not portable to a SPA**. Your worker + Svelte client already separates concerns cleanly; keep painting strictly server-side. +- **LocalStorage-based resume** works here because it's a userscript. You'll want **Upstash Redis** to persist user job state (imageData, painted pixels, position, timestamp) server-side. Allows resume across browser sessions & devices. +- **Account rotation** requires a user-managed roster. Store as `user_accounts: [{token, displayName, charges, lastUsed}]` in your user doc or a separate KV namespace. +- **Blue marble effect** is client-side canvas manipulation; keep it in Svelte component for preview. Doesn't change server painting. + +--- + +## Unresolved Questions + +1. **Does WPlace-AutoBOT handle 429 (rate limit) responses explicitly?** → No explicit retry-on-429 found in code path. Relies on cooldown + account rotation to stay under limit. If server returns 429, behavior unclear (likely treated as failed batch, continues next cycle). May silently lose pixels. + +2. **How does account roster persist?** → Uses browser's `localStorage.getItem("accounts")` + `chrome.storage.local`. No cross-device sync. Unclear how users add new accounts (extension UI must have hidden menu). + +3. **Does sketch/undo exist?** → No undo or pixel-level editing found. Progress is forward-only; stop → resume paints remaining pixels in same order. + +4. **Can users adjust painting order mid-job?** → `state.coordinateMode` can be changed, but unclear if it applies to remaining pixels or re-orders from scratch. Likely needs restart. + +5. **What triggers overlay refresh on tile cache hit?** → Script dispatches synthetic `wheel` + `resize` events. Undocumented; may not work on all canvas implementations (especially if WPlace uses WebGL). Falls back to manual toggle. + +--- + +## Summary + +WPlace-AutoBOT's UX is **pragmatic & modular**. It offloads position selection to paint interception, uses localStorage for resume, and abstracts account rotation into the cooldown loop. No fancy pause (only stop) or per-pixel undo. The overlay system is simple (opacity + effect toggle) and tied tightly to tile refresh. The "polish" comes from smart saves, multi-language i18n, theme system, and area extraction tools—features that don't block the core painting loop but improve perceived quality. + +For your rplace rebuild, focus on **server-side job persistence** (Upstash), **skip-painted filtering**, and **multi-account routing** in your Worker. The overlay & coordinate modes are nice-to-have, not critical path. diff --git a/plans/reports/researcher-260418-1217-wplace-design.md b/plans/reports/researcher-260418-1217-wplace-design.md new file mode 100644 index 0000000..d9441bb --- /dev/null +++ b/plans/reports/researcher-260418-1217-wplace-design.md @@ -0,0 +1,156 @@ +# Wplace.live UI/UX Design Research + +**Date:** 2026-04-18 +**Analyst:** Researcher +**Scope:** wplace.live design patterns vs. rplace current implementation + +--- + +## 1. Color Palette Picker + +**Wplace.live:** 64-color palette (24 free + 40 premium). Browser extensions provide quick color picker overlays with coordinate display; third-party tools emphasize "easy color identification" via visual feedback. No detailed native UI layout found (grid vs. wheel not specified in accessible sources). Color converter tools support multiple input methods (direct value entry, visual pickers, palette selection) with real-time feedback. + +**Your current impl:** 32-color grid, docked bottom, 8-wide × 4-tall layout, 32px swatches, hover scale 1.2, selected state has white border + glow, dark background (rgba 0,0,0 0.85) with blur. **Matches pattern.** You have fewer colors and smaller grid. Wplace's ecosystem relies heavily on *third-party tools* for picker UX (not native), suggesting their built-in picker may be minimal. + +**Verdict:** Your picker is more polished than wplace's likely native implementation. Third-party tools suggest the base UI doesn't have an outstanding picker. **No immediate import needed.** + +--- + +## 2. Canvas Controls + +**Wplace.live:** +- Zoom: Mouse wheel, Q/E keyboard shortcuts, "Zoom in to see pixels" button (jumps to level 10; pixels only visible at zoom ≥10) +- Pan: WASD keys + mouse drag +- Coordinates: Real-world location display (latitude/longitude); third-party extensions add coordinate search (format: `123,456` or degrees-minutes-seconds) +- **No minimap found**; third-party tools offer "location manager" to bookmark/jump to spots +- Geographic context: Every pixel maps to real-world locations on OpenStreetMap + +**Your current impl:** Zoom buttons (+ / −) at bottom-left, mouse wheel zoom, coordinates display, zoom levels 1–19 (user not specified), pan via drag. **Differs:** No keyboard shortcuts (Q/E), no WASD pan, no goto-coordinates input, no location bookmarks. **Lacks:** No real-world coordinate mapping (your canvas is abstract 2048×2048). + +**Verdict:** Wplace's keyboard shortcuts (Q/E zoom, WASD pan) + goto-coordinates input are **quick UX wins**. Minimap is provided by third-party only, not native. **Recommend borrowing:** Keyboard pan/zoom shortcuts + coordinate search input. + +--- + +## 3. User Info / Rate-Limit Display + +**Wplace.live:** Cooldown timer displayed somewhere (referenced as "1 pixel every 30 seconds"). Pixel charge system with "Pixel Pool" that starts at 30–64 and expands via purchase or leveling. Leaderboards for players, alliances, countries, regions. **No explicit cooldown countdown timer UI details found** in accessible sources; third-party overlays enhance this. + +**Your current impl:** Rate limit is 1 request/second (batch-independent), not per-pixel. No visible cooldown timer, no pixel-pool display, no level/purchase system, no leaderboards. **Lacks:** Visible countdown, gamification (levels, inventory), leaderboards. + +**Verdict:** Wplace emphasizes **gamification** (levels, pixel pool, leaderboards) and **cooldown transparency** (visible timer). Your app is simpler (no progression system planned?). **Recommend:** Add visible cooldown countdown on next-available timestamp (e.g., "Next paint in 3s"). Leaderboard / progression left to future scope. + +--- + +## 4. Place / Submit Flow + +**Wplace.live:** Click-to-draw; pixel placement mechanics include eraser tool (dedicated button or spacebar + cursor). Charge system: clicks spend from pixel pool. No mention of pending buffer, explicit submit, or undo/redo in core flow. **Single-action placement** (no pending buffer like yours). + +**Your current impl:** **Two-stage flow:** paint locally (pending buffer), then click Submit to POST batch. Undo/Redo buttons available. Paint mode toggleable. No eraser tool. **Differs significantly:** You have a *pending buffer* (uncommitted pixels), wplace has *immediate placement* with a charge pool. + +**Verdict:** Your buffering approach is **safer for batch optimization** (batches up to 2048 pixels, 1 req/sec). Wplace's single-action model feels more responsive but requires careful rate-limiting on the server side. **No import suggested**—your batch model is architecturally sounder for a small canvas. Eraser tool could be added as a future enhancement. + +--- + +## 5. Image Importer / Converter + +**Wplace.live:** External pixel-art converters (Floyd-Steinberg, Ordered, Atkinson dithering), grid overlay, drag-and-drop upload, real-time preview, 64-color palette matching, browser-side processing (no server upload). Multiple converters available; UI is clean and intuitive but not deeply detailed in sources. + +**Your current impl:** Full image importer (phase 6 completed). Features: dither methods (none, ordered, floyd-steinberg, ordered-64, atkinson), skip-white + paint-transparent toggles, color correction (brightness, contrast, saturation, gamma), resize with aspect-lock, flip/rotate transforms, on-canvas overlay preview with alpha control, drag-and-drop, live batched upload with progress. **Exceeds** wplace converters in sophistication and integration. + +**Verdict:** **Your importer is more feature-rich than wplace's external tools.** You already have a competitive advantage. No imports needed. Your in-app integration + color-correction sliders are differentiators. + +--- + +## 6. General Visual Language + +**Wplace.live:** +- Dark theme (maps are typically dark by default on MapLibre/OSM) +- Web-based overlay on world map (geographic context is the visual centerpiece) +- Collapsible/draggable UI windows (mentioned in search results) +- Light/dark mode support (browser extensions mention toggle) +- No detailed typography or specific accent-color guidance found +- Onboarding / empty-state: Not documented in accessible sources + +**Your current impl:** +- Dark theme only +- Abstract 2048×2048 canvas (no geographic context) +- Fixed layout: toolbar top-right, color picker bottom-center, controls bottom-left, importer panel top-right +- Rgba panels with blur, white accent on selected items +- No onboarding, no empty-state visual +- Mobile: pinch-zoom + touch-drag supported (no specific mobile UI layout) + +**Verdict:** Wplace's **draggable/collapsible UI** is a nice flexibility feature but not critical. Your fixed layout is simpler and clearer. **Recommend:** Add a simple onboarding tooltip (first-time visit) explaining paint → submit flow, color picker, and zoom controls. Mobile layout could benefit from a mobile-specific toolbar (e.g., stacked buttons instead of side-by-side). + +--- + +## Candidate Imports for Our Site + +### 1. **Keyboard Shortcuts for Pan & Zoom** (small effort) + - **What:** Add Q/E for zoom in/out and WASD for pan (wplace pattern) + - **Why:** Power-user friendly, faster workflow, matches common game/design tool patterns + - **Effort:** Small (2–3 lines per command, keyboard handler already exists) + +### 2. **Goto-Coordinates Input** (small effort) + - **What:** Add a text input in canvas-controls to jump directly to x,y (e.g., "256,512" → center canvas there) + - **Why:** QoL improvement for large canvases; wplace's search feature is a third-party add-on, suggesting native feature gap + - **Effort:** Small (input field + canvas center/zoom logic) + +### 3. **Visible Cooldown Countdown** (small effort) + - **What:** Display "Next paint in Xs" on the submit button when rate-limited + - **Why:** Reduces user confusion; wplace players expect cooldown visibility + - **Effort:** Small (store next-available timestamp, update UI every 100ms) + +### 4. **Simple Onboarding Tooltip** (medium effort) + - **What:** First-time visitor banner explaining: select color → paint → submit, with mouse/touch hints + - **Why:** Wplace relies on external guides; your app should be self-documenting + - **Effort:** Medium (modal/banner component, localStorage to hide after first interaction) + +### 5. **Mobile-Optimized Toolbar** (medium effort) + - **What:** Stack or simplify draw toolbar buttons for small screens; ensure color picker is touch-friendly + - **Why:** Wplace is discussed as "viral on TikTok"—heavy mobile use; your importer is on-brand for desktop first + - **Effort:** Medium (responsive breakpoint, grid-to-column layout swap, touch target sizes ≥48px) + +### 6. **Eraser Tool (Optional)** (medium effort) + - **What:** Toggle eraser mode (paints transparent or placeholder color) or spacebar + click to erase + - **Why:** Wplace offers this; useful for corrections without undo overhead + - **Effort:** Medium (add mode toggle, update paint logic to handle erase color) + +--- + +## Key Findings + +| Aspect | Wplace Pattern | Your Implementation | Gap | Priority | +|--------|---|---|---|---| +| Color picker | 64-color palette (external tools provide UI) | 32-color grid, polished | None—yours is better | — | +| Canvas controls | Q/E zoom, WASD pan, goto-coords | Buttons, mouse-wheel, no keyboard | Keyboard shortcuts missing | Small | +| Cooldown display | Visible countdown (implicit from pooling) | None shown | Transparency gap | Small | +| Place flow | Immediate (charge-based) | Buffered + submit | Architectural difference; yours is safer | — | +| Image importer | External dither converters | In-app, 6 dither methods + color correction | Yours exceeds | — | +| Visual language | Dark, map-centric, collapsible UI | Dark, fixed layout, polished panels | Layout flexibility gap (non-critical) | Large (low ROI) | +| Onboarding | Not found (likely minimal) | None | User confusion risk | Medium | + +--- + +## Sources + +- [Wplace.live Guide](https://wplace.life/) +- [Place Live vs. Wplace Live: From Reddit's r/Place to a Global Pixel World](https://wplace.style/blog/reddit-place-vs-wplace) +- [Ultimate Wplace.live Guide — Cooldown, Tools & Hot Regions](https://wplaceartconverter.com/wplace-guide) +- [Complete Wplace.live Location Search Guide](https://wplacepixelconverter.org/blog/complete-wplace-live-location-search-guide/) +- [Wplace.live Extension & Tools](https://wplacetool.com/wplace-extension) +- [Wplace Pixel Art Converter — Free Online Tool](https://wplaceconverter.net/) +- [GitHub - Wplace Tools & Overlays](https://github.com/ethansunray/wplace-tool) +- [Wplace Color Palette Reference](https://wplacepixel.com/wplace-color-palette) + +--- + +## Unresolved Questions + +1. **Wplace native UI details:** Direct access to wplace.live blocked (403). Details on built-in color picker layout (grid width, swatches per row) inferred from third-party tools, not official UI. If critical, may need user account or GitHub repo inspection. +2. **Cooldown timer implementation:** Wplace sources mention cooldown system but don't specify countdown display details—inferred as "expected" from community tool discussions. +3. **Mobile layout:** Wplace's viral TikTok popularity suggests strong mobile use, but no mobile-specific UI layout details found in sources. +4. **Onboarding flow:** Neither wplace nor your current app have documented onboarding; gap identified from *absence*, not competitor feature. + +--- + +**Report Status:** Ready for design review. Highest-ROI imports are keyboard shortcuts (#1), goto-coordinates (#2), and cooldown countdown (#3). All are small-effort QoL wins. diff --git a/src/client/App.svelte b/src/client/App.svelte index 22e12d5..cdc0bbb 100644 --- a/src/client/App.svelte +++ b/src/client/App.svelte @@ -1,5 +1,5 @@