TraceBuddy

Kid-friendly camera overlay tracing helper built as a mobile-first React/Vite PWA with an Expo native mobile app.

Why we built it

TraceBuddy came from a simple family use case: build a tracing app with a phone camera so Stassie can trace and draw whatever she wants.

The first releases proved the fixed phone/iPad camera-overlay idea. Version 1.3 adds Paper Lock, an iOS RealityKit experience that keeps the selected guide anchored to a real table or printed marker while the device moves.

What it does

TraceBuddy lets a child or parent:

1. Pick a simple line-art drawing.
2. Open trace mode.
3. Choose Paper Lock, regular camera tracing, or on-screen practice.
4. Anchor a semi-transparent drawing to a real surface, place it over paper with the regular camera, or trace directly with a finger/stylus.
5. Follow the first-run parent setup check, then use paper detection or the manual alignment controls.
6. Save a good portrait or landscape alignment and start the low-distraction child trace view.
7. Unlock the digital canvas only when you want to pan or zoom in for detailed coloring.

The MVP is designed for Stassie-style drawing practice: simple, friendly, private, and usable on a phone or iPad with a stand.

Current features

• Mobile-first responsive interface
• Clean, modern, kid-friendly visual design
• 54 individually reviewed SVG tracing templates with category, difficulty, and text search filters
• Local favorites and recent picks for quickly returning to family favorites
• Eight gentle guided lessons with highlighted new strokes, resumable local progress, and no scores or failure states
• A handwriting studio for turning a name, word, number, or short family message into an on-screen practice guide
• Twelve no-score Together activities for family drawing, storytelling, turn-taking, and keepsakes
• Printable/shareable PDF worksheets in the native app and printable/downloadable SVG worksheets on the web
• Save finished web practice drawings as PNG keepsakes; save native practice drawings to Photos
• Local image upload with optional cleanup modes
• Camera access with getUserMedia
• On-screen coloring/practice mode for finger, stylus, or mouse tracing
• Custom word/name/phrase tracing
• Expanded color palette including pinks, brush sizes, pencil/marker/crayon/paint brush styles, and an eraser
• Locked-by-default digital canvas with optional pan/zoom for detailed coloring
• Lines-on-top coloring option so template outlines remain visible
• Mobile practice add-ons for built-in shapes and local photo/image stickers
• Save finished mobile practice drawings to the device Photos library
• Local autosave for on-screen coloring sessions
• Previous Work gallery for resuming, duplicating, deleting, or starting fresh from saved coloring
• Clear-all confirmation to protect kids' work
• Demo camera surface when camera is unavailable/blocked
• iOS Paper Lock with RealityKit world tracking, horizontal-surface placement, and optional printed-marker tracking
• Letter/A4 portrait and landscape sizing, opacity, scale, rotation, precise nudges, lock/relock, and child mode
• Drag-to-position overlay
• Mobile-friendly floating trace controls
• A 30-second parent setup coach with stand, framing, and lighting checks
• Portrait/landscape presets plus locally saved alignment settings
• A locked, low-distraction child trace view with optional browser fullscreen
• Opacity, scale, rotation, nudge, lock, reset controls
• Experimental paper rectangle detection and tracking
• Uploaded image background cleanup and line-art conversion
• Outline/high-contrast display mode
• Screen Wake Lock request where supported
• PWA manifest metadata
• Service worker app-shell caching
• No account, backend, ads, analytics, or uploads

Important boundaries

TraceBuddy remains deliberately local-first.

• Paper Lock uses native ARKit/RealityKit on supported iPhones and iPads and falls back to Camera Trace elsewhere.
• AR sessions, camera frames, anchors, and guide textures are processed on-device and are not persisted or uploaded.
• No backend
• No image/video upload
• No remote or server-side image processing
• Camera frames stay local and are never recorded. Previous Work, practice strokes, custom words, selected images, favorites, recents, guided-lesson progress, parent-setup completion, and a saved alignment may persist in private browser/app storage until deleted.

For real tracing, use a phone/iPad stand or prop the device above the paper. Experimental paper tracking can follow small camera shifts when the page is clearly visible, but manual realignment may still be needed.

Documentation

• Product brief
• Physical setup guide
• Paper tracking notes
• Uploaded image cleanup
• Expo mobile app plan
• Real-device testing checklist
• Roadmap
• Privacy notes

Run the web app locally

npm install
npm run dev -- --host 127.0.0.1

Open:

http://127.0.0.1:5173

Camera access on mobile requires HTTPS. Localhost works on desktop for development, but real phone/iPad testing should use an HTTPS deployment such as Netlify or Vercel.

Run the Expo mobile app

npm install
npm --prefix mobile install
cd mobile
eas build --platform ios --profile development

Install the resulting development build on a registered device, then run npm run start in mobile/ and open the project from that build. The public App Store version of Expo Go does not support this app's pinned Expo SDK 56 runtime. For release-candidate testing, use the latest TraceBuddy TestFlight build instead.

The mobile app uses native camera, a local RealityKit Expo module, local image picker, keep-awake, shared built-in templates, and both spatial and manual overlay controls. Paper Lock requires a development or TestFlight build and a physical AR-capable iPhone or iPad; it does not run in Expo Go or the iOS Simulator.

Verify

npm run check

Build first, then start a production preview in one terminal:

npm run build
npm run preview

In another terminal, run the browser checks against that preview:

CHECK_URL=http://127.0.0.1:4173 npm run check:viewports
CHECK_URL=http://127.0.0.1:4173 npm run check:storage
CHECK_URL=http://127.0.0.1:4173 npm run check:offline
CHECK_URL=http://127.0.0.1:4173 npm run check:discovery
CHECK_URL=http://127.0.0.1:4173 npm run check:learning
CHECK_URL=http://127.0.0.1:4173 npm run check:setup
CHECK_URL=http://127.0.0.1:4173 npm run check:family
CHECK_URL=http://127.0.0.1:4173 npm run check:navigation

Or against another local port:

CHECK_URL=http://127.0.0.1:5174 npm run check:viewports

Capture screenshots

With the dev server running:

npm run screenshots

Generated files:

• /tmp/tracebuddy-01-home-desktop.png
• /tmp/tracebuddy-02-picker-desktop.png
• /tmp/tracebuddy-03-trace-desktop.png
• /tmp/tracebuddy-04-practice-desktop.png
• /tmp/tracebuddy-05-home-mobile.png
• /tmp/tracebuddy-06-trace-mobile.png
• /tmp/tracebuddy-07-practice-mobile.png

Suggested next steps

• Deploy to HTTPS for real iPad/phone camera testing
• Test with a physical stand and real paper
• Capture real-device notes in docs/REAL_DEVICE_TESTING.md
• Test a development or TestFlight build on a real phone over paper and in on-screen practice mode
• Expand the guided-learning library after family playtesting shows which instructions and subjects work best
• Refine family activities and worksheet prompts after family playtesting
• Prototype printable marker-based tracking if plain paper detection is not stable enough
• Keep the development-build workflow documented as Expo SDK requirements change