Home

Material Layout Planner — Wiki

📐 2D Material Layout Planner — a local, browser-only app for planning how rectangular materials are laid out across measured 2D surfaces. Draw real-world geometry, assign materials, preview placement patterns, and export cut lists and PDF documentation — all from your browser, with no server, no account, no cloud.

This wiki is the long-form documentation for every feature of the application. The README remains the quick start; everything else lives here.

---

What is this project?

The Material Layout Planner solves a single, very concrete problem: given a set of physical 2D surfaces (walls, floors, worktops, façades) and a catalogue of rectangular materials (tiles, boards, panels), where should every piece go, and how do I cut them?

It is designed for:

• 🧱 Tile setters and stone masons planning bonded patterns over a real room.
• 🪚 Carpenters and joiners laying out boards across cabinets, floors or cladding.
• 🏗️ Façade and dry-wall installers who need to know exactly how many panels to buy and how to cut them.
• 🧑‍🎨 Anyone designing an interior who wants to preview a finished surface before ordering material.

Everything runs locally in the browser. Your geometry, your materials, your patterns and the generated cut lists never leave your machine — they sit in IndexedDB and are exportable as portable JSON.

Why is it different?

• 📏 Real-world units — every coordinate is millimetres. Inputs accept compound units (1200, 1.2 m, 4 ft); the parser converts everything internally.
• 🧮 Optimisation, not just preview — assigning a material and a pattern produces a live preview layout immediately. Pressing Generate runs a worker-based optimiser that re-balances waste, symmetry, cut count, small pieces and joint alignment using configurable priorities.
• 🪟 Geometry that survives reality — openings, surface splits, connections between surfaces, and physical material overlap at edges are all first-class concepts; pieces are clipped and counted exactly the way the saw will cut them.
• 📄 Print-ready output — a single click produces a multi-page PDF with the project summary, scaled technical drawing, the material layout, the cut list, per-panel cutting diagrams and installation instructions.
• 🧰 Local-first — no account, no telemetry, no server. The app is a Vite + React + Konva static bundle.

How a project flows through the app

The recommended flow goes through five stages. Click through any link for the deep dive.

1. Draw the geometry. Use the 2D Drawing Tools (line, rectangle, polygon, meter, dimension, label, cut) to sketch your walls or panels. Toggle the grid (G), snap (S) and live "ortho measure" guides for accurate placement. Trace over a photo or plan with the Background Image Calibration workflow.
2. Turn shapes into surfaces. With the Surface tool (F), promote any closed shape into a named Surface. Punch openings for windows or sockets, split surfaces along a cut line, and tie neighbouring surfaces together with directional connections.
3. Configure materials and patterns. Define each material once in the Material Library (unit size, thickness, joint, minimum piece, default orientation, colour style). Define each layout style as a Placement Pattern (stacked, running bond ½ / ⅓, custom offset, diagonal, plus orientation, origin, direction, symmetry and optimisation priorities). Assign one of each to every surface.
4. Generate and inspect the layout. The Layouts & Cut List panel shows a live preview the moment you assign a material and a pattern. Press Generate material layout to run the optimiser in a worker. Use the Pattern origin tool (M) to nudge the result, and inspect overlap regions configured by edge rules on the canvas.
5. Export. Save the project as JSON or a PDF report via the File menu / Editor toolbar. See Local Storage & JSON for autosave and JSON import/export, and PDF Export for the per-page contents and the toggles that control them.

Feature index

Each entry below maps one-to-one with a feature bullet in the project README. Click through for the deep dive — every page also lists the exact files in src/ that implement the feature.

Feature	Page	What it covers
🖊️ Accurate 2D drawing with real dimensions, grid, and snapping	2D Drawing Tools	The full drawing toolbox, every keyboard shortcut, grid / snap behaviour, modifier keys, copy/paste selection workflow and the selection edit handles.
🧩 Named surfaces, openings, and multi-surface connections	Surfaces, Openings & Connections	Creating, naming and editing surfaces; punching openings; splitting; linking edges with connection types.
🎨 Material library with size, thickness, joints, and styles	Material Library	Material schema, the editor dialog, validation, default orientation and the style colour pickers.
🔁 Placement patterns (stacked, running bond, custom offsets, …)	Placement Patterns	Every pattern type, orientation / origin / direction / symmetry knobs, row-offset units and optimisation priorities.
🪚 Auto-generated cut lists, cutting diagrams, and waste reports	Cut Lists & Layouts	Live preview vs optimised layouts, the Layouts panel, blade-kerf-aware cut list and cutting diagrams.
↔️ Physical edge overlap with semi-transparent visualization	Edge Overlap Visualization	Edge rule types, max overlap, opacity rendering, thickness compensation and where to edit them.
🖼️ Background image import with two-point calibration	Background Image Calibration	Importing an image, the two-point calibration math, opacity / lock / visibility controls.
💾 Local project storage + JSON import/export	Local Storage & JSON	The IndexedDB schema, the project repository API, autosave, schema migrations and the JSON import/export workflow.
📄 One-click PDF export with technical drawings and instructions	PDF Export	The export pipeline, every page produced by buildPdfDocument and every entry in pdfSettings.

Project facts

• ⚛️ Stack — React 18, TypeScript, Vite, Zustand, Immer, Konva, Zod, pdf-lib, idb, polygon-clipping, ulid. Tested with Vitest + Testing Library.
• 💾 Persistence — IndexedDB (mlp.db) with separate stores for projects, thumbnails and binary blobs (large images).
• 📐 Coordinate system — world space in millimetres; viewport scale is applied at render time. The optimiser runs in a Web Worker.
• 🧪 Quality bar — every state mutation goes through the command system, so undo (Ctrl+Z) and redo (Ctrl+Shift+Z) are total.

Where things live

• App source — fihorvat/material-layout-planner
• Wiki source — fihorvat/material-layout-planner.wiki (this repo)
• Issues / Discussions — GitHub Issues
• Agent rules — AGENTS.md

Contributing to the wiki

All commit messages in this wiki follow the Conventional Commits specification and are enforced locally by commitlint + husky (mirroring the main repository). After cloning, run npm install once to wire up the commit-msg hook:

git clone https://github.com/fihorvat/material-layout-planner.wiki.git
cd material-layout-planner.wiki
npm install
# edit / add Markdown pages, then:
git commit -m "docs: ..."   # husky will reject non-conventional messages
git push

GitHub renders the filename of each page as its title with dashes replaced by spaces. _Sidebar.md and _Footer.md control the navigation chrome you see on the right and bottom of every page.

If you change the application, you also need to update the wiki — see AGENTS.md in the main repository for the agent-level rules.