feat: add sprite sheet support for 3D model thumbnails (#213)

* feat: add sprite sheet support for 3D model thumbnails

Implements sprite sheet generation and interactive viewing for OpenForge 3D models, reducing storage costs and improving user experience with 360° model previews.

## Backend Changes
- Add `sprite_metadata` JSONB column to images table (schema v15-16)
- Update image SQL queries to handle sprite_metadata
- Add `/api/sprites` endpoint for sprite sheet generation
- Fix image comparison to detect sprite_metadata changes
- Update `insert_image()` to use ON CONFLICT DO UPDATE for sprite metadata

## Scanner Improvements
- Add `--sprites` flag to generate sprite sheets during scan
- Add `bin/generate_sprite` tool for sprite sheet creation
- Add `bin/resort_fixtures` tool for stable fixture sorting
- Fix fixture sorting to use full_name for top-level array
- Use /tmp for temp sprite files to avoid path length issues
- Preserve sprite_metadata.angles sort order by index

## Frontend Components
- Add SpriteViewer component with interactive 3D rotation
- Implement unwrapped cube layout for angle selection (10 angles)
- Add keyboard navigation (arrow keys for rotation)
- Add mouse drag support for horizontal rotation
- Auto-focus viewer for immediate keyboard interaction
- Reset angle when switching between blueprints

## Type Definitions
- Add SpriteThumbnailData, SpriteAngle types
- Update ThumbnailData union type
- Add comprehensive test coverage (27 tests for SpriteViewer)

## Testing
- Add sprite_metadata change detection test
- Update image-gallery tests for sprite support
- Add full SpriteViewer test suite (rendering, controls, keyboard, mouse, a11y)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* adding design

* fix: address review feedback - improve code quality and maintainability

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: use tempfile.gettempdir() for subprocess cwd

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: decompose generate_sprite into focused helper functions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add sprite_metadata support to update_image()

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: remove accidentally shipped progress tracking file

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: remove accidentally shipped fixture data files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: restore sewers.json to original state

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: remove version_15.py - should come from PR #153

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: extract sprite viewer event handling into custom hooks

- Extract keyboard rotation logic into useKeyboardRotation hook
- Extract mouse drag rotation logic into useMouseDragRotation hook
- Reduce SpriteViewer component from handling state + rendering + keyboard + mouse events to just state + rendering
- Follows single responsibility principle and reduces cognitive load
- Raise NotImplementedError for --db-update flag instead of silent warning

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: remove --db-update flag from generate_sprite

Database updates will be handled through the fixture workflow,
not directly by this CLI tool.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: use key prop pattern for sprite viewer state reset

Replace useEffect-based state reset with React key prop pattern.
When sprite_url changes, React will unmount and remount the
component with fresh state - more idiomatic than manual reset.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address code quality improvements from Gemini review

1. Add try/finally cleanup for sprite files in bin/generate_sprite
2. Validate default_angle against actual sprite_metadata instead of hardcoded max
3. Add try/finally cleanup for temp files in create_and_upload_thumbnail
4. Simplify CTE in insert_image (remove unnecessary WITH clause)
5. Derive angle constants from sprite metadata instead of hardcoding

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: use blueprint.id for key and dynamic angleMap

1. Use blueprint.id instead of sprite_url for SpriteViewer key
   - More explicit and robust for component remounting
2. Build angleMap dynamically from angle names
   - Decouple frontend from backend array order
   - Component adapts if angle structure changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add specific error handling for stl-thumb failures

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: improve exception handling in helper functions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* security: only pass required environment keys to config

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: devonjones

.beads/.gitignore

@@ -0,0 +1,32 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Keep JSONL exports and config (source of truth for git)
+!issues.jsonl
+!metadata.json
+!config.json

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/interactions.jsonl

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

.beads/issues.jsonl

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

.beads/metadata.json

@@ -7,4 +7,4 @@
     "quickfix.biome": "explicit",
     "source.organizeImports.biome": "explicit"
   }
-}
+}

.gitattributes

@@ -0,0 +1,39 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>         # Complete work
+bd sync               # Sync with git
+```
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds

.vscode/settings.json

@@ -126,6 +126,25 @@ For language-specific coding preferences and patterns, see:
 - Python/Backend: `openforge/CLAUDE.md`
 - JavaScript/Frontend: `src/CLAUDE.md`
 
+## Code Organization Philosophy
+
+### Function Complexity and Cognitive Load
+
+**Core Principle**: Functions should be describable with as few uses of "and" or "or" as possible.
+
+- **Single Screen Rule**: Generally, a function should be viewable on a single screen to keep cognitive load down
+- **Helper Functions**: Use private/helper functions extensively to extract specific tasks
+  - Python: Use `_function_name()` for private helpers
+  - JavaScript/React: Use custom hooks or helper functions
+- **Pragmatic Exceptions**: Larger functions are acceptable when breaking them up would genuinely complicate rather than simplify
+- **Test for Complexity**: If you're describing what a function does and you use multiple "and"s or "or"s, it's probably doing too much
+
+**Examples**:
+- ❌ "This component handles state AND rendering AND keyboard events AND mouse drag events" - too many responsibilities
+- ✅ "This component manages sprite viewer state and delegates event handling to custom hooks"
+- ❌ "This function validates input AND transforms data AND saves to database" - should be 3 functions
+- ✅ "This function validates and saves user data (validation is a prerequisite for saving, so it's cohesive)"
+
 ## Background Context
 
 ### Technical Experience