stegasoo/PLAN-4.1.2.md

Stegasoo 4.1.2 Plan

Release Theme

Polish and UX improvements after the 4.1.1 stability release.

---

1. Real Progress Bar for Encode/Decode

Status: Planned

Problem: Users see elapsed time but no indication of how far along the operation is. Long DCT encodes on Pi can take 2-3 minutes with no feedback.

Solution: Polling + progress file approach

Backend Changes

1. dct_steganography.py - Write progress during block loop:

   if progress_file and block_num % 50 == 0:
       with open(progress_file, 'w') as f:
           json.dump({"current": block_num, "total": total_blocks, "phase": "embedding"}, f)
   

2. app.py - New endpoints:

   • POST /encode returns job_id, starts subprocess
   • GET /encode/progress/<job_id> returns progress JSON
   • GET /encode/result/<job_id> returns final result when done

3. Subprocess wrapper - Pass progress file path to encode/decode functions

Frontend Changes

1. stegasoo.js - After form submit:

   • Show progress bar (Bootstrap progress component)
   • Poll /encode/progress/{job_id} every 500ms
   • Update bar width and percentage text
   • Show phase (hashing, embedding, encoding, etc.)

2. Templates - Add progress bar markup to encode.html and decode.html

Files to Modify

• src/stegasoo/dct_steganography.py
• frontends/web/app.py
• frontends/web/static/js/stegasoo.js
• frontends/web/templates/encode.html
• frontends/web/templates/decode.html

---

2. Granular Decode Error Messages

Status: Done

Problem: Decode failures show generic "Decryption failed" - users don't know if it's wrong photo, wrong passphrase, wrong PIN, corrupted image, or format mismatch.

Solution: Bubble up specific error types from library to UI

Implementation

• Added new exceptions: InvalidMagicBytesError, ReedSolomonError, NoDataFoundError, ModeMismatchError
• DCT decode now raises InvalidMagicBytesError for wrong magic bytes
• DCT decode now raises ReedSolomonError (renamed from reedsolo's) for corruption
• app.py catches specific exceptions with user-friendly messages:
  • Invalid magic → "Try a different mode (LSB/DCT)"
  • RS error → "Image too corrupted, may have been re-saved"
  • Invalid header → "Image may have been modified"
  • Decryption error → "Wrong credentials"

Files Modified

• src/stegasoo/exceptions.py (new exceptions)
• src/stegasoo/__init__.py (exports)
• src/stegasoo/dct_steganography.py (raise specific exceptions)
• frontends/web/app.py (catch and display)

---

3. Mobile-Responsive Polish

Status: Planned

Problem: UI works on mobile but has rough edges - cramped buttons, hard-to-tap targets, awkward layouts on small screens.

Solution: Targeted CSS/layout fixes for mobile breakpoints

Areas to Improve

1. Encode/Decode Forms:

   • Stack image drop zones vertically on mobile (currently side-by-side)
   • Larger touch targets for file inputs
   • Full-width buttons on small screens
   • Passphrase input readable at smaller sizes

2. Navigation:

   • Hamburger menu for mobile navbar (if not already)
   • Sticky header doesn't eat too much screen
   • Easy thumb reach for main actions

3. Results/Output:

   • Download buttons full-width on mobile
   • QR codes sized appropriately
   • Click-to-copy message box works well with touch

4. Drop Zones:

   • Larger tap targets
   • Visual feedback for touch (not just hover)
   • Camera integration hint on mobile ("Tap to take photo or choose file")

Testing Targets

• iPhone SE (small)
• iPhone 14 (medium)
• iPad (tablet)
• Android Chrome

Files to Modify

• frontends/web/static/css/style.css (or new mobile.css)
• frontends/web/templates/encode.html
• frontends/web/templates/decode.html
• frontends/web/templates/base.html (navbar)

---

Testing Checklist

• Progress bar works on localhost
• Progress bar works on Pi (slower, more visible)
• Cancellation handling (what if user navigates away?)
• Error states display correctly
• Smoke test passes

---

4. Forced First-Login Setup

Status: Done

Problem: Users can navigate the app without creating an admin account first. Should force password setup before anything else.

Solution: Middleware/decorator that redirects to setup page if no users exist.

Implementation

• Added @app.before_request hook that redirects to /setup if no users exist
• Skips redirect for static files and setup-related routes

Files Modified

• frontends/web/app.py (added require_setup before_request hook)

---

5. Dropzone UX Fixes

Status: Done

Problem: Dropzone has some interaction bugs:

• Dropzone doesn't clear properly if first QR image fails
• Can't click on image preview to replace file (have to click surrounding border)

Solution: Fix JS event handling and state management

Implementation

• Added click handler on preview images to trigger file input
• Made entire drop zone clickable (not just label)
• QR zone now resets after 2 seconds on error, allowing retry
• Clear file input on QR error so same file can be re-selected

Files Modified

• frontends/web/static/js/stegasoo.js

---

6. Smoke Test Benchmarking

Status: Done

Problem: No way to measure encode/decode performance or track regressions.

Solution: Add timing to smoke tests using hyperfine or time.

Implementation

• Added --benchmark flag to run encode/decode benchmarks after tests
• Added --runs=N flag to customize number of benchmark runs (default: 5)
• Uses hyperfine if available for precise timing with warmup
• Falls back to manual timing with bc if hyperfine not installed
• Outputs min/max/avg stats for both encode and decode operations

Files Modified

• tests/smoke-test.sh

---

7. Docker Cleanup

Status: Done (4.1.1)

Problem: Docker build context is larger than needed (includes test images, rpi scripts, etc.)

Solution: Added .dockerignore and fixed volume permissions in Dockerfile

Files Modified

• .dockerignore (created)
• Dockerfile (instance dir permissions)

---

8. Release Validation Script

Status: Planned

Problem: Manual release checklist is error-prone. Need automated validation.

Solution: Script that runs through testable checklist items

Features

• Run pytest
• Build and test Docker image
• SSH to Pi and run smoke test (optional, if PI_IP provided)
• Report pass/fail summary

Files to Create

• scripts/validate-release.sh

---

9. Smoke Test Docker Support

Status: Done

Problem: Smoke test expects systemd service, doesn't auto-create admin for Docker.

Solution: Make smoke test Docker-aware

Features

• Skip systemd checks if not on Pi/Linux with systemd
• Auto-detect fresh Docker (no users) and create admin via /setup
• Add --docker flag to skip Pi-specific checks

Implementation

• Added --docker flag that sets localhost and skips SSH/systemd checks
• Docker health check verifies container responds with HTTP 200/302
• Header shows "Docker Smoke Test" in Docker mode

Files Modified

• rpi/smoke-test.sh

---

Notes

• Keep 4.1.2 focused - 9 features (6 done)
• Don't break DCT compatibility (4.1.1 RS format is stable)
• Test on Pi before release