PlanProof

Deterministic Spatial Verification & Pre-Construction Planning Engine

PlanProof bridges the gap between decorative interior layouts and physical pre-construction reality. It pairs the multimodal capabilities of Meta AI with a deterministic local spatial geometry verifier and a joinery panel cut-sheet optimizer.

---

🛑 The Core Problem: Why Rooms Fail at Installation

Interior layouts frequently encounter costly physical clashes on installation day:

1. Door & Clearance Clashes: Wardrobe doors swing into the arc of the entrance door or collide with nightstands and ceiling fixtures.
2. Hidden Utilities: Custom cabinetry is planned over room switchboards, thermostat panels, or AC isolators, requiring emergency rewiring or on-site joinery alterations.
3. Ergonomic & Egress Shortfalls: Desks lack sufficient rear clearance to pull out a chair comfortably, or furniture encroaches on the primary 0.80 m entrance walk route.
4. Thermal & Lighting Discomfort: Beds placed directly in the concentrated airflow path of split air conditioners, or computer monitors positioned with direct rear window glare.
5. Aperture Delivery Failures: Large solid furniture units arrive on site only to discover they cannot physically pass through the door frame upright.
6. Joinery Fabrication Guesswork: Hand sketches rarely account for standard sheet nesting, saw kerf allowance, or veneer grain matching, leading to unexpected sheet counts and material miscalculations.

---

💡 Core Principle: AI Proposes. Deterministic Geometry Evaluates.

PlanProof enforces a strict separation between generative AI proposals and physical validation:

• AI Proposes: Meta AI models analyze room photos, transcribe spoken instructions, and propose layout changes or auto-repair mutations.
• Deterministic Geometry Evaluates: A local, deterministic mathematical engine audits every proposed layout against 11 spatial, ergonomic, and utility rules. If a rule fails, the exact clearance shortfall is flagged. No AI model is permitted to overrule physical geometry.

flowchart LR
    A[📐 Step 1: Room & Plan] -->|Room Setup & Scale Calibration| B[🔌 Step 2: Wall Fixtures & 3D Layout]
    B -->|Meta Muse Spark 1.3 + Deterministic Verifier| C[📱 Step 3: Spatial Audit & Cut Maps]
    C -->|8x4 ft Plywood Guillotine Nesting| D[📋 Master Procurement Dossier]

Loading

---

🏗️ Architecture

PlanProof operates as a lightweight, full-stack TypeScript application with a strict single-provider AI architecture:

planproof/
├── src/                          # Vite + React 19 Frontend
│   ├── components/               # UI Modals & Views
│   │   ├── SceneView.tsx         # 3D Three.js room visualization & dynamic wall cutaway
│   │   ├── PlanView.tsx          # 2D architectural top-down floorplan view
│   │   ├── ScaleCalibrationModal.tsx # Room reference scale calibration (doors, tiles, switchboards)
│   │   ├── FloorPlanScannerModal.tsx # 2D floorplan photo analysis via Meta SAM 3.1
│   │   ├── WallScannerModal.tsx  # Wall fixture detection via Meta SAM 3.1
│   │   ├── MultiObjectImportModal.tsx# Photo furniture segmentation via Meta SAM 3.1
│   │   ├── PlywoodOptimizerModal.tsx # 8x4 ft plywood nesting, kerf spacing & cut maps
│   │   ├── ArPreviewModal.tsx    # Mobile device-orientation 360° camera pass-through
│   │   ├── VerifiableAgentDrawer.tsx # Self-healing layout loop via Meta Muse Spark 1.3
│   │   ├── ObjectInspector.tsx   # Item dimensions, GLB loader, and provenance badges
│   │   └── ProofModal.tsx        # Pre-construction procurement dossier & export
│   └── lib/                      # Deterministic Verification & Math Engines
│       ├── model.ts              # Scene model, 11 spatial verification checks, autoFix
│       ├── plywoodOptimizer.ts   # 2D guillotine bin packing & panel decomposition
│       ├── referenceCalibration.ts # Perspective-aware scale estimation & margin calculations
│       ├── procurementModel.ts   # Master procurement schedule & material take-offs
│       └── units.ts              # Conversions between metres (m), centimetres (cm), and feet (ft)
├── server/                       # Express Node.js Backend API (Port 8787)
│   ├── app.ts                    # REST endpoints (/api/interpret, /api/vision/*, /api/voice/*)
│   ├── config.ts                 # Strict Meta-only configuration loader
│   ├── providers/
│   │   └── meta.ts               # Official Meta AI client (Muse Spark 1.3, SAM 3.1, Voice, Image)
│   ├── vision.ts                 # Vision processing pipeline & schema validation
│   └── usageTracker.ts           # Per-model rate limiting & token telemetry
└── scripts/                      # Developer tooling & smoke test suite
    ├── check-archive-secrets.ts  # Pre-commit & archive secret protection gate
    └── smoke-meta.ts             # Reproducible Meta API model verification runner

---

🤖 Meta AI Model Verification Status

PlanProof interfaces exclusively with official Meta AI endpoints. Verification statuses reflect reproducible, evidence-based testing:

Capability	Model	Model ID	Status	Evidence / Notes
Spatial Reasoning	Meta Muse Spark 1.3	muse-spark-1.3	Live verified by successful structured API request	Verified via live API request returning HTTP 200 and schema-validated structured action payload.
Vision & Segmentation	Meta SAM 3.1	sam-3.1	Pending meaningful live result verification	Endpoint integration complete (wire payload validated); pending live smoke test returning verified non-zero object bounding boxes.
Speech Transcription	Meta Muse Voice Transcribe 1.0	muse-voice-transcribe-1.0	Pending meaningful live result verification	Multipart ASR endpoint integration complete; pending live smoke test returning verified speech transcript text.
Concept Visualization	Meta Muse Image 1.0	muse-image-1.0	Pending meaningful live result verification	Wire payload and generation endpoint integration complete; pending verified live image generation run.

---

🚀 Implemented Capabilities

1. Dual 2D/3D Room Editor & Smart Cutaway

• Dual Visualizer: Real-time synchronization between north-up 2D architectural plan view and interactive 3D perspective view.
• Dynamic Wall Cutaway: Far walls remain solid; near walls cut away based on camera angle so furniture and wall utilities are never obscured.
• Parametric Catalogue: Curated procedural materials for flooring (tile, wood, marble, terrazzo), wall colors, electrical utilities, lighting, and furniture.

2. Room-Scale Reference Calibration

• Two-Point Photo Ruler: Calibrate metric pixels-per-meter on imported 2D floorplans or wall photos using known physical references:
  • Interior door frame height (2100 mm) or width (900 mm)
  • Modular electrical switchboard plates (8-module 250 mm, 4-module 150 mm)
  • Standard floor tile edges (600 × 600 mm)
  • Standard A4 documentation sheet (297 mm)
  • Physical tape measure marks
• Perspective Margin: Explicitly flags all image-derived scale estimates with an honest uncertainty margin ($\pm 10%$) until physically confirmed with an on-site laser distance meter.

3. The 11 Deterministic Spatial & Utility Checks

Every scene mutation is audited in real time against strict geometric rules:

#	Check Name	Rule & Metric	Purpose
1	Door Swing Arc	Radial polygon sweep vs furniture footprints	Prevents entrance door collisions with nearby furniture
2	Primary Walkway	Continuous unobstructed 0.80 m corridor	Ensures accessible egress from door into room
3	Solid Overlap	2D/3D bounding volume intersections	Prevents physical collisions between solid objects
4	Room Boundary	Strict containment within outer room footprint	Prevents objects from protruding through walls
5	Switchboard Access	$\ge 0.15\text{ m}$ front clearance for electrical panels	Prevents tall wardrobes or headboards from blocking switches
6	Desk Power Reach	Study desk within $1.80\text{ m}$ of a wall outlet	Convenience planning guideline to avoid trailing extension cords
7	Ceiling Fan Envelope	$1.20\text{ m}$ cylinder clearance below fan hub	Prevents tall bunk beds or wardrobe crowns from blade conflicts
8	Window Daylight Glare	Desk monitor back-to-window angle $> 30^\circ$ & offset $\ge 0.50\text{ m}$	Reduces direct sunlight reflections on computer screens
9	Chair Clearance	$\ge 0.80\text{ m}$ clear space behind desk seating edge	Ensures adequate room to pull out and occupy an office chair
10	AC Cold Draft	Split AC direct discharge $> 0.50\text{ m}$ from bed headrest	Improves thermal comfort by avoiding direct cold air dumping
11	Doorway Delivery	Item $\min(\text{width}, \text{depth}) \le (\text{door width} - 0.02\text{ m})$	Validates whether assembled furniture can physically enter the room

4. Verifiable Agent Self-Healing Loop

• Natural language instructions ("Move the wardrobe away from the door") are interpreted by Meta Muse Spark 1.3 into structured actions.
• The proposed layout is immediately evaluated by the local geometry engine. If the change creates new conflicts or fails spatial rules, it is rejected, preserving the existing scene without silent fallback.

5. Joinery Pre-Construction Plywood Optimizer

• Panel Decomposition: Automatically breaks down custom millwork items (wardrobes, desks, beds with explicit recipes) into individual carcass gables, shelves, doors, and back plies. Ready-made retail items (chairs, lamps, rugs) are preserved as finished goods.
• 2D Guillotine Bin Packing: Packs panels onto standard 2440 × 1220 mm (8×4 ft) plywood sheets with 3 mm saw kerf and configurable carcass thickness (12, 16, 18, 25 mm).
• Grain Direction Alignment: Enforces vertical grain constraints on exterior gables and doors.
• Export Formats: Interactive SVG cut maps and exportable Bill of Materials (BOM) CSV.

6. Master Procurement Dossier

• Generates a consolidated 8-page pre-construction dossier: Executive Summary, Room Measurements, Shopping List, Flooring Take-Off, Wall Finishes, Carpentry Schedule, Master Checklist, and Spatial Audit.
• Available for in-browser screen review, CSV data export, structured JSON export, or multi-page PDF printing.

---

🛠️ Getting Started

Prerequisites

• Node.js (v18.0.0 or v20.0.0+ recommended)
• npm (v9.0.0+)

1. Installation

Clone the repository and install dependencies using npm ci:

git clone https://github.com/mohamad-shafeez/planproof.git
cd planproof
npm ci

2. Configuration (.env)

Copy the sample environment file to .env:

cp .env.example .env

Open .env and set your Meta API key:

PORT=8787
PLANPROOF_PROVIDER=meta
META_API_KEY=your_meta_api_key_here
META_BASE_URL=https://api.meta.ai/v1
META_MODEL=muse-spark-1.3
META_VISION_MODEL=sam-3.1
META_VOICE_MODEL=muse-voice-transcribe-1.0
META_IMAGE_MODEL=muse-image-1.0

# Optional Sketchfab API token for 3D model search
SKETCHFAB_API_TOKEN=

Security Note: Never commit .env or paste real credentials into .env.example. .env is strictly gitignored. All AI capabilities run server-side; credentials are never exposed to the client bundle.

3. Run Development Server

npm run dev

• Express Backend: http://127.0.0.1:8787
• Vite Client UI: http://127.0.0.1:5173

---

🧪 Quality Gates & Automated Verification

PlanProof enforces strict automated quality gates prior to release:

# 1. Secret Protection & Release Integrity Gate
npm run check:archive

# 2. Automated Test Suite (Vitest)
npx vitest run

# 3. Linter (Oxlint)
npm run lint

# 4. TypeScript & Vite Production Build
npm run build

Latest Verified Results:

• Test Suite: 30 test files passed (184 tests passed, 0 failures)
• Linter: 0 warnings, 0 errors across 92 files
• Build: Client bundle and server compilation passed cleanly
• Security Check: 0 tracked secrets, .env.example verified with safe placeholders

---

🔬 Reproducible Meta Model Smoke Tests

The smoke test suite (scripts/smoke-meta.ts) validates model integration contracts without relying on private fixtures:

# Run local dry run (validates payloads and shapes without network calls)
npx tsx scripts/smoke-meta.ts all --dry-run

# Test Muse Spark 1.3 live spatial command interpretation
npx tsx scripts/smoke-meta.ts spark

# Test SAM 3.1 with a developer-provided wall photo
npx tsx scripts/smoke-meta.ts sam --image /path/to/wall-photo.jpg --concept switchboard

# Test Voice Transcribe with a developer-provided speech recording
# (Recording must be mono 16-bit PCM WAV at 16000 or 24000 Hz)
npx tsx scripts/smoke-meta.ts voice --audio /path/to/speech.wav

# Test Muse Image 1.0 concept visualization
npx tsx scripts/smoke-meta.ts image

---

📂 Demo Project

A synthetic sample room layout is bundled at public/demo-project.json:

• Purpose: Allows instant testing of 2D/3D rendering, the 11 spatial checks, the plywood nesting algorithm, and procurement dossier generation without configuring an API key.
• Limitations: The demo project represents a synthetic bedroom test case with deliberate clearance constraints (e.g., doorway swing proximity) to demonstrate deterministic conflict detection.

---

⚠️ Known Limitations & Disclaimers

1. Visual Estimates vs. Physical Measurement: All dimensions extracted from photographs or 2D floor plans are ESTIMATED planning approximations subject to camera perspective, lens distortion, and user alignment. Physical on-site verification with a calibrated laser tape measure is required before cutting materials or placing orders.
2. Advisory Doorway Clearance: The doorway aperture check verifies the minimum bounding cross-section against the door frame with a 20 mm handling margin. It does not model tight stairwells, elevator turns, or complex multi-axis rotations.
3. Planning Tool, Not Structural Engineering: PlanProof detects geometric, ergonomic, and utility placement conflicts. It is not a licensed structural engineering certifier or municipal building code compliance tool.
4. Custom Millwork vs. Retail Goods: Only custom cabinetry items with explicit construction recipes decompose into plywood cut maps; standard retail furniture items (chairs, sofas, beds, rugs) are tracked as finished goods.
5. AR Mode: AR preview provides 360° device-orientation camera pass-through and WebXR viewing on supported devices; it is not a hardware-tracked 6DoF SLAM system.

---

📄 License & Attribution

• See ATTRIBUTION.md for open-source library licenses, procedural asset specifications, and third-party API policies.
• The repository software license will be designated by the repository owner prior to public distribution.