Camera Scene Sandbox

Interactive camera-framing sandbox for exploring profile-view geometry, field of view, tilt, and subject framing constraints.

The app includes:

• Profile view with draggable camera, line-of-sight handle, and subject top handle
• Camera preview panel with in-frame/out-of-frame status
• Minimum-distance solver with multi-step formula derivation (KaTeX)
• Persistent settings via URL and local storage

Tech Stack

• React + TypeScript + Vite
• Material UI
• Vitest + Testing Library
• ESLint
• KaTeX

Scripts

Run from project root:

npm install
npm run dev
npm run test
npm run lint
npm run build
npm run clean
npm run pristine

• npm run clean Removes build/test artifacts and local tool caches (dist, coverage, .vitest, node_modules/.vite, node_modules/.tmp).

• npm run pristine Performs a clone-like reset: runs clean and deletes node_modules without reinstalling dependencies.

Release Checklist

Before tagging a release:

1. Run npm run clean.
2. Run npm test.
3. Run npm run build.
4. Bump the version in package.json.
5. Commit changes and create a version tag (for example: v0.0.1).

Project Structure

Entry and Page Composition

• src/App.tsx Thin entry component. Delegates orchestration to controller hook and renders the page shell.

• src/components/SandboxPage.tsx High-level page layout (header, profile scene region, preview/solver region, controls region).

Components

• src/components/ProfileScene.tsx SVG-based profile view renderer and pointer event surface.

• src/components/CameraPreview.tsx Preview window status panel.

• src/components/MinimumDistancePanel.tsx Formula rendering, derivation steps, and solve result state UI.

• src/components/ControlsPanel.tsx Slider/input controls and reset actions.

Hooks

• src/hooks/useSandboxController.ts Aggregates all app-level orchestration and returns props for page composition.

• src/hooks/useSolveDistance.ts Solve state machine and minimum-distance solve flow.

• src/hooks/useSceneInteractions.ts Drag/pointer interaction logic for scene manipulators.

• src/hooks/useControlsPanel.ts Controls metadata, mark generation, and input/slider handlers.

• src/hooks/useScenePanelProps.ts Builds grouped props for scene and right-side panels.

Math and Settings

• src/math/sceneMath.ts Core geometry and solver math helpers.

• src/math/sceneLayout.ts Derived scene layout model from current settings.

• src/math/solvePresentation.ts Formula/derivation presentation formatting.

• src/sceneSettings.ts Source of truth for control ranges, defaults, snapping, normalization, and persistence serialization.

Testing Strategy

Current tests cover:

• UI integration behavior in src/App.test.tsx
• Math helper behavior in src/math/sceneMath.test.ts
• Solve presentation formatting in src/math/solvePresentation.test.ts
• Hook behavior in:
  • src/hooks/useSolveDistance.test.ts
  • src/hooks/useControlsPanel.test.ts

Notes

• Build currently reports a chunk-size warning from Vite reporter. This is informational and does not fail the build.
• If desired, next optimization can focus on route/component-level code splitting.

License

MIT. See the LICENSE file for details.