1. Core Philosophy & App Modes

CutList Workspace is designed to scale with your project's complexity. You can toggle between two primary workflow modes in the main header:

Basic Mode (Streamlined Workflow)

Basic Mode strips away professional overhead to give you a clean, rapid-entry workspace. It is perfect for quick calculations or simple home workshop projects where you just want to see how parts fit on boards without detailed inventory tracking:

• Unitless Dimensions: All width and length values are treated as "generic" units. The Unit column is hidden.
• No Grain Constraints: Grain Direction defaults to **Optimized** (free rotation) for all parts. The Grain column is hidden, letting the algorithm rotate parts freely to find the tightest fit.
• No Cost Tracking: Price and currency inputs are completely hidden to reduce visual noise.
• Single Material Matching: The **Target Material** column in parts is hidden. The optimizer assumes all active parts are cut from your first active stock material.
• Simplified UI: Features like Edge Banding and advanced diagram settings are hidden.

Advanced Mode (Professional Suite)

Advanced Mode unlocks the complete suite of material nesting, cost estimating, and workshop planning features. Use this mode for complex assemblies, multi-material jobs, or commercial shop work:

• Real-world Units: Select and mix real-world units (inches, feet, millimeters, centimeters, meters, yards) with automatic fractional rounding and conversion.
• Grain Enforcement: Lock part orientations to **Lengthwise** or **Widthwise** alignment to preserve wood grain directions or sheet textures.
• Multi-Material Optimization: Define multiple different sheet stocks (using different SKUs, dimensions, and names) and map each required part to its specific **Target Material** source.
• Financial Cost Estimating: Input sheet costs to calculate total project costs, scrap wastage values, and the precise proportional cost consumed by each part.
• Specialized Add-ons: Unlocks advanced features like the **Edge Banding Calculator** and detailed PDF layout formatting configurations.

2. Interface Controls & Mobile Layout

The layout and data tables are engineered to be highly responsive and customizable to fit your screen and preferences.

• Persistent Header Actions: The top-right header contains direct controls for <strong>Help & FAQs (?)</strong> and <strong>Preferences & Settings (⚙)</strong>. These actions are available at all times for quick configuration, and align perfectly with standard shop layout standards.
• Slide-out Navigation Drawer: Click the ☰ hamburger icon at the top-left to access local backups, merge actions, or support logs. A **permanently visible custom-styled scrollbar** is integrated into this drawer, providing a clear visual indicator that you can scroll to reach lower options.
• Cloud Sync & Login (On the Roadmap): The **👤 Login** option in the navigation drawer is a feature on the roadmap that will enable cloud backup and multi-device sync in a future update.
• Column Management & Locks:
  • Reorder & Resize: Click and drag any column header to rearrange the columns. Drag the border line between columns to adjust their width.
  • Auto-Fit Spacing: Double-click the separator line between headers to instantly shrink the column to exactly 1% width, tightly wrapping the content to save maximum screen space.
  • Algorithm Column Locks: Note that the <strong>Material (SKU)</strong> column in stock and the <strong>Target Material</strong> column in parts are permanently locked and cannot be disabled in Preferences. These columns are mandatory key indices for the optimization engine to correctly pair parts to their source boards.
• Smart Dimensions (Decimal vs. Fraction): Toggle between decimal (e.g., 23.5) and fractional (e.g., 23 1/2) input. <em>Pro-Tip: In Preferences &gt; Defaults, you can set the fractional step (e.g., round to the nearest 1/16").</em>
• High-Density Mobile Spacing System: On mobile screens, the app dynamically reorganizes into space-saving layouts. Length, Width, Qty, and Unit are combined into a single, compact baseline row on each card to minimize vertical scrolling and eliminate the need for horizontal table scrolling.
• Mobile Ad Height Restrictions: On mobile viewports, advertisements are strictly limited to exactly **90px** high using high-priority dynamic container constraints, ensuring that promotional banners never interfere with your workspace on small screens.
• Quick Duplication & Mass Toggles: Click the ⎘ (Copy) icon on any row to instantly duplicate a complex part or material. Check the top column header checkbox to toggle the active state of all items at once.

3. Material & Part Management

1D vs 2D Optimization Modes

• 2D (Sheet Goods): Used for flat panels like plywood, acrylic, or sheet metal. Parts have independent Length and Width, and the optimizer packs them dynamically across the 2D surface.
• 1D (Linear Goods): Used for lumber, metal tubing, pipes, or extrusion. Parts only require a "Length". The Width and Grain are automatically inherited from the Stock material they are assigned to, and they are packed strictly end-to-end.

Stock (Your Raw Materials)

This table defines the raw sheet goods or linear boards you currently have in inventory. The optimizer uses these as the source materials to fit your parts.

• Standard Presets: Instead of typing out standard dimensions, use the dropdown to inject common materials instantly (e.g., 4x8 3/4" Plywood). You can add custom presets in Preferences.
• Cost Tracking: Entering a unit cost allows the engine to calculate Total Cost (raw materials off the rack) and Used Cost (the fractional cost of the material actually utilized, minus waste).

Stock Columns:

Parts (Your Cut List)

This table defines the final components you need to cut out of your available raw material. The optimizer groups, rotates, and places these parts dynamically.

• Target Material Mapping: If you have multiple types of stock, you must explicitly tell the engine which stock each part is cut from using the Target Material column.
• Grain Direction:
  • Optimized: The engine freely rotates the part 90 degrees to find the absolute best fit.
  • Lengthwise / Widthwise: Locks the part's orientation. The engine will not rotate it, ensuring the wood grain runs the correct direction on your final project.

Parts Columns:

4. The Optimization Engine & Kerf

The app utilizes a "Guillotine Packing" algorithm, calculating cuts that go completely from one edge of the available material to the other—mimicking how a table saw actually cuts.

Understanding the Algorithm's Decisions

The optimizer runs thousands of simulations to find the most efficient layout. Sometimes, its mathematical decisions might look "awkward" to a human eye. Here is how to leverage its logic:

• Global Yield vs. Local Neatness: You might see two identical parts placed side-by-side, but one is rotated vertically and the other horizontally. The algorithm doesn't care about visual neatness; if rotating a part awkwardly leaves a perfectly shaped off-cut for a different part later in your list, it will do it to save you from buying an extra sheet.
• Forcing Alignment (The Rip Cut Trick): If you want to force the algorithm to behave more like a human cabinet maker (prioritizing continuous straight rip cuts on a table saw), use the <strong>Grain Direction</strong> locks. Changing a part from "Optimized" to "Lengthwise" strips the engine of its ability to arbitrarily rotate it. Your utilization might drop by 1-2%, but the resulting cut map will be much faster to physically cut.
• Different Results on Re-Runs: Because the engine uses advanced randomized simulations to brute-force the best possible pack, clicking "Run Optimization" multiple times on the exact same list may yield slightly different layouts. If you don't love a layout, try running it again to see if it finds a pattern you prefer!

Blade Kerf (The Silent Space Eater)

Kerf is the thickness of your saw blade. Every cut turns a small amount of material into sawdust.

• Why it matters: If you need two 24" parts from a 48" board, they will <em>not</em> fit if your blade has a 1/8" kerf. The first cut consumes 1/8", leaving you with 47 7/8".
• Settings: Set your Kerf in the top header or Preferences. You can save specific presets (e.g., "Standard 1/8", "Channel 3/4").

5. Manual Adjustments & Drag-and-Drop (Hold Bin)

CutList Workspace supports manual nesting, letting you override or fine-tune the automatic layouts using an intuitive drag-and-drop workflow.

The Hold Bin

The <strong>📥 Hold Bin</strong> acts as a temporary holding area for parts. It is located at the bottom of the screen and can be expanded or collapsed as needed.

• Unplacing Parts: Drag any placed part directly off a cut sheet diagram and drop it into the Hold Bin to remove it from the layout. Alternatively, click the part to select it and click the <strong>Unplace</strong> option in the menu.
• Placing Parts: Drag any part from the Hold Bin and drop it onto a specific sheet. The app highlights valid drop target areas to help you place the part. You can also click the part in the Hold Bin to instantly send it to the center of a sheet.
• State Indicator: The Hold Bin shows a badge with the count of currently unplaced parts. It also automatically opens when you begin dragging a part.

Snapping Engine vs. Clamped Collisions

When dragging a part onto a sheet, the app runs a real-time snapping engine to help you align your cuts:

• Automatic Snapping: The engine automatically searches for and snaps the part to the nearest valid, collision-free position (taking your blade **Kerf** into account).
• Manual Override (Collisions): If no valid collision-free spot is found near your drop location, the part will be placed exactly where you release it (clamped to the sheet boundaries). Overlapping or colliding parts will be highlighted in red with warning alerts.

Interactive Part Actions

Clicking on any placed part opens an interactive selection menu with the following tools:

• 🔄 Rotate Part: Rotates the part 90 degrees. The engine checks for collisions and snaps the rotated part to the nearest valid location.
• ⚡ Snap to Closest Edge: Runs an alignment pass to instantly snap the part to the nearest collision-free sheet edge or neighboring part.
• 📥 Unplace Part: Moves the part off the sheet back into the Hold Bin.
• 🗑️ Delete Placed Part: Removes this copy of the part from the sheet entirely.

Undo, Redo, and Keyboard Shortcuts

Making manual modifications is safe and easy with built-in history tracking:

• Controls: Undo and Redo buttons are floating just above the Hold Bin for easy access. There are also Undo/Redo buttons next to the Cut Maps header for convenience.
• Shortcuts: Use standard keyboard shortcuts to undo or redo:
  • Ctrl + Z to Undo your last drag-and-drop or manual nesting change.
  • Ctrl + Y to Redo an action you undid.

Enabling & Disabling Drag-and-Drop

To prevent accidental movements on your layout, you can toggle manual editing on or off using either of these controls:

• Quick Header Toggle: Use the <strong>Drag & Drop</strong> toggle switch located in the main header of the "Cut Maps" section, next to the header Undo/Redo controls.
• Preferences Panel: Toggle the <strong>Manual Drag & Drop</strong> option under the "Optimization Options" section in Preferences & Settings (⚙).

6. Edge Banding Calculator (Advanced Mode Only)

The Edge Banding Calculator (available in <strong>Advanced Mode</strong> only) helps you track exactly how much edge banding material (veneer tape, PVC banding, etc.) you need for your cabinet and furniture projects.

Enabling Edge Banding

This feature is turned off by default to keep the interface clean. To enable it:

• Open <strong>Options (Advanced Features)</strong> in the top header.
• Toggle <strong>Enable Edge Banding Calculator</strong>.
• A new "Banding" column will appear in your Parts table.

How it Works

The Banding column allows you to selectively apply banding to specific edges of a part.

• Per-Edge Selection: [T] Top, [B] Bottom, [L] Left, and [R] Right. Click these to toggle banding on that specific edge.
• Linear Math: The app automatically computes the linear amount needed based on the part's dimensions. For example, banding the Top edge requires a length of banding equal to the part's Width. Banding the Left edge requires a length equal to the part's Length.
• Subtotals: The total linear amount of edge banding required for all parts (accounting for quantities) is tallied at the bottom of the Parts table.

Exports and Reporting

• CSV Export: The CSV file will include two new columns: "Banding" (listing the edges, e.g., "T,B") and "Banding Amount" (the exact linear amount required for that part, e.g., "51 in"). The total project amount is also included at the top of the file.
• PDF Printouts: The PDF shop sheets will display the chosen edges for each part in a dedicated column, and the grand total edge banding amount is prominently displayed in the summary footer.

7. Export, Import & Printing

PDF Shop Printouts

Clicking **Print (PDF)** compiles a professional, print-ready packet including all visual cut maps and project metrics. You can customize the PDF content in **Preferences (⚙) &gt; PDF Exports**:

• Hide/Show Lists: Disable stock or part lists to save paper, printing only the graphical diagrams.
• Column Customization: Selectively hide fields (e.g. costs or SKU numbers) from appearing on printed copies.
• Scrap Pattern Styling: Select how wasted offcuts are visually styled (slashed lines, solid gray fills, etc.) on the cut sheet diagrams.

Export Formats & Data Portability

Use the export buttons to save or share your project details:

• Export JSON (Full Backup): Saves the entire session workspace state. This includes stock sheets, parts lists, settings, and any manual nesting/drag-and-drop modifications you have completed. This is the best way to back up projects to load back later.
• Export CSV (Spreadsheet-friendly): Generates a tabular CSV file containing stock and part lists. If Edge Banding is active, CSV sheets include the edge banding subtotal calculations and individual edge banding labels (T, B, L, R) for simple integration with external inventory tools.

Importing & Merging Projects

When loading JSON backup files back into the workspace, you can choose two import behaviors:

• Overwrite: Completely clears your current workspace lists and settings, replacing them with the project contents of the imported file.
• Merge: Keeps your current stocks and settings, but appends all the new parts from the imported file onto your active parts list. This is highly useful for combining multiple orders into a single, high-yield nesting run.

8. Practical Use Cases

• Cabinetry & Furniture: Utilize the Grain Direction locks to ensure all cabinet doors have matching vertical grain. Set a 1/8" Kerf for the table saw.
• Welding & Metal Fab (1D): Add 20-foot steel square tubing to the Stock list. Enter your required lengths. The 2D engine naturally handles 1D linear packing if the width of your stock and parts match.
• Laser Cutting / CNC: Set Kerf to 0 (or your laser's specific focal width) and use Decimal millimeters. Turn off Grain Direction to allow maximum rotational optimization.

9. Things to Watch Out For (Gotchas)

• The "Outdated Results" Warning: If you run an optimization and then change a dimension, quantity, or kerf size, a warning will appear. The cut maps on screen are now stale. You must hit <em>Run Optimization</em> again.
• Zero or Blank Quantities: A part with a blank quantity will halt the optimizer. Either set it to a number, or uncheck the "Enable" box to ignore it.
• Mixing Units: Advanced mode allows you to mix units (e.g., Stock in feet, Parts in inches). The engine handles the math perfectly, but it is easy for you to make a data-entry mistake. Keep units consistent when possible.
• Target Material Mismatches & Locked Columns: If you import data from CSV, or delete a stock row that parts were assigned to, those parts will throw an error. Check the "Target Material" column to ensure all parts have a valid home. Note that "Material" (SKU) and "Target Material" are locked and cannot be hidden in preferences because they link the parts to the stock.
• Offline Mode & Auto-Save: The **👤 Login** feature in the Side Navigation is **on the roadmap** and not yet available. However, your work is <strong>automatically saved</strong> to your browser's Local Storage as you type. Your data will persist between sessions securely on your own device. We still recommend exporting JSON backups of complex projects periodically until cloud sync is officially released.

10. Warning Messages & Troubleshooting

Critical Shortage: Not Enough Material

This red table appears when the optimizer runs out of usable stock before all parts are placed. The "Reason" column helps diagnose the failure:

• Not enough material quantity: The parts fit dimensionally, but you don't have enough boards/rods in your Stock. <em>Fix: Increase the Qty of your Stock.</em>
• Part exceeds material length/width: A single part is physically larger than any piece of your Stock (e.g., a 100" part trying to fit on a 96" board). <em>Fix: Review the part dimensions, or add larger material to your stock.</em>

Material Assignment Warnings

If you try to delete a row of Stock that is actively selected as the "Target Material" for one or more Parts, a warning popup will appear. Deleting the stock will leave those parts orphaned, and they will fail to optimize until you re-assign them to a new material.

No Space to Snap Part

This warning pop-up appears when you use the **Snap to Closest Edge** action on a part, but the snapping engine cannot find any collision-free alignment point nearby. The part will remain in its original position.

Export Warnings (Attention Required)

If you try to Export or Print your project while there are layout anomalies, the app displays an alert prompting you to **Cancel to Fix** or **Ignore & Export Anyway**. This occurs when the app detects:

• Overlapping or Out-of-Bounds Parts: Parts that visually overlap or exceed sheet dimensions.
• Unplaced Parts: Parts that could not fit onto sheets during auto-optimization due to material shortage.
• Shelved Parts: Unplaced parts currently sitting in the manual **Hold Bin**.
• Modifications Added (Stale Results): Changes were made to parts/stock inputs since your last optimization, making the current cut maps out of date.