\n\n# @0xdoublesharp/bin-packing-wasm\n\nWebAssembly build of the [`bin-packing`](https://crates.io/crates/bin-packing)\nRust crate — a cut list and bin packing optimizer for 1D cutting stock (linear\nbar / pipe), 2D rectangular sheet packing, and 3D box packing.\n\nRuns in **browsers, Node.js 18+, Deno, Bun, and Cloudflare Workers**. No\nnative binaries, no build step, no `node-gyp`.\n\n## Features\n\n- **1D cutting stock.** First-fit-decreasing, best-fit-decreasing, multistart\n local search, and an exact column-generation backend.\n- **2D rectangular packing.** MaxRects (best-area, BSSF, BLSF, bottom-left,\n contact-point), Skyline (+ min-waste), Guillotine beam search (7 variants),\n shelf heuristics (NFDH, FFDH, BFDH), multistart, and rotation search\n meta-strategies.\n- **3D box packing.** Extreme Points (6 variants), Guillotine 3D beam search\n (7 variants), layer/wall/column builders, Deepest-Bottom-Left, volume-sorted\n FFD/BFD, MultiStart, GRASP, LocalSearch, and a restricted branch-and-bound\n exact backend (29-algorithm catalog). Per-item rotation masks over all six\n axis permutations.\n- **Multi-stock / multi-sheet / multi-bin** with independent costs and optional\n inventory caps.\n- **Kerf and trim** modeling for 1D cuts; **kerf-aware gap enforcement** for 2D sheet packing.\n- **Per-item rotation** control for 2D demands and 3D rotation masks.\n- **`Auto` mode** runs multiple strategies and returns the best candidate.\n- **Reproducible** — all randomized strategies accept a `seed`.\n- **Fully typed** TypeScript definitions.\n\n## Installation\n\n```sh\npnpm add @0xdoublesharp/bin-packing-wasm\n# or\nnpm install @0xdoublesharp/bin-packing-wasm\n# or\nyarn add @0xdoublesharp/bin-packing-wasm\n```\n\n## Usage\n\nThe package ships combined targets plus smaller dimension-specific targets via\nthe `exports` map, so a single install works everywhere:\n\n| Import specifier | Target | Requires `init()`? |\n| ---- | ---- | ---- |\n| `@0xdoublesharp/bin-packing-wasm` | Combined 1D+2D+3D, bundlers (Vite, webpack, esbuild, Next.js, Rollup, Parcel) | No |\n| `@0xdoublesharp/bin-packing-wasm/web` | Combined 1D+2D+3D, browsers, Deno, native ES modules | Yes (`await init()`) |\n| `@0xdoublesharp/bin-packing-wasm/nodejs` | Combined 1D+2D+3D, Node.js, Bun | No |\n| `@0xdoublesharp/bin-packing-wasm/one-d` | 1D-only, bundlers | No |\n| `@0xdoublesharp/bin-packing-wasm/one-d/web` | 1D-only, browsers, Deno, native ES modules | Yes (`await init()`) |\n| `@0xdoublesharp/bin-packing-wasm/one-d/nodejs` | 1D-only, Node.js, Bun | No |\n| `@0xdoublesharp/bin-packing-wasm/two-d` | 2D-only, bundlers | No |\n| `@0xdoublesharp/bin-packing-wasm/two-d/web` | 2D-only, browsers, Deno, native ES modules | Yes (`await init()`) |\n| `@0xdoublesharp/bin-packing-wasm/two-d/nodejs` | 2D-only, Node.js, Bun | No |\n| `@0xdoublesharp/bin-packing-wasm/three-d` | 3D-only, bundlers | No |\n| `@0xdoublesharp/bin-packing-wasm/three-d/web` | 3D-only, browsers, Deno, native ES modules | Yes (`await init()`) |\n| `@0xdoublesharp/bin-packing-wasm/three-d/nodejs` | 3D-only, Node.js, Bun | No |\n\n### Bundler (Vite / webpack / esbuild / Next.js)\n\n```js\nimport { solve1d, solve2d, plan2dCuts } from '@0xdoublesharp/bin-packing-wasm';\n\nconst cutList = solve1d(\n {\n stock: [{ name: 'bar', length: 100, kerf: 1 }],\n demands: [\n { name: 'A', length: 45, quantity: 2 },\n { name: 'B', length: 30, quantity: 2 },\n ],\n },\n { algorithm: 'auto' },\n);\n\nconsole.log(cutList.stock_count, cutList.total_waste);\n\n// Generate a cut plan from a finished 2D layout\nconst layout = solve2d(\n {\n sheets: [{ name: 'plywood', width: 96, height: 48, kerf: 2 }],\n demands: [\n { name: 'panel', width: 24, height: 18, quantity: 4, can_rotate: true },\n ],\n },\n { algorithm: 'auto' },\n);\n\nconst cutPlan = plan2dCuts(layout, { preset: 'table_saw' });\n\n// cutPlan.total_cost — aggregate cost across all sheets\n// cutPlan.sheet_plans — per-sheet plans; each carries:\n// .steps — ordered cut steps (cut, line_cut, rotate, fence_reset, …)\n// .total_cost — cost for this sheet\n// .num_cuts, .num_rotations, .num_fence_resets, .num_tool_ups, .travel_distance\n```\n\nModern bundlers load the accompanying `.wasm` file automatically. Vite and\nwebpack 5+ need no configuration; older toolchains may need a wasm loader.\n\nFor browser payloads that only need one dimension, import the smaller\ndimension-specific entry point:\n\n```js\nimport { solve2d } from '@0xdoublesharp/bin-packing-wasm/two-d';\n```\n\nThe 1D-only WASM is currently ~200 KB, the 2D-only WASM is currently ~230 KB,\nthe 3D-only WASM is currently ~300 KB, and the combined 1D+2D+3D WASM is\ncurrently ~550 KB after `wasm-opt -Oz`. These are approximate; run the build\nlocally for current figures.\n\n### Browser (raw ES modules / Deno)\n\nThe `web` target needs an explicit `init()` call that loads the `.wasm` file\nfrom a URL:\n\n```html\n\n```\n\nIn Deno:\n\n```ts\nimport init, { solve1d } from 'npm:@0xdoublesharp/bin-packing-wasm/web';\n\nawait init();\nconst solution = solve1d(/* ... */);\n```\n\n### Node.js / Bun\n\n```js\nimport { solve1d } from '@0xdoublesharp/bin-packing-wasm/nodejs';\n\nconst solution = solve1d(\n {\n stock: [{ name: 'bar', length: 100 }],\n demands: [{ name: 'A', length: 45, quantity: 2 }],\n },\n { algorithm: 'auto' },\n);\n```\n\nThe Node target loads the `.wasm` file synchronously from disk — no async\nsetup required.\n\n### CommonJS\n\n```js\nconst { solve1d } = require('@0xdoublesharp/bin-packing-wasm/nodejs');\n```\n\n### Edge kerf relief\n\nSet `edge_kerf_relief: true` on a sheet when the final cut on each\naxis can run off the stock, consuming less than a full kerf of\nmaterial:\n\n```js\nsheets: [\n {\n name: 'plywood',\n width: 48000,\n height: 96000,\n kerf: 125,\n edge_kerf_relief: true,\n },\n];\n```\n\nEach part must still fit within the sheet's own dimensions, but the\nlast placement on a row or column may extend by up to one kerf past\nthe sheet boundary — the model treats this as the blade exiting the\nmaterial.\n\n## API\n\n### `plan2dCuts(solution, options?)`\n\n```ts\nfunction plan2dCuts(solution: TwoDSolution, options?: CutPlanOptions2D): CutPlanSolution2D;\n```\n\nGenerates an ordered cut plan for every sheet in a finished `TwoDSolution`.\nPresets (`options.preset`): `table_saw`, `panel_saw`, `cnc_router`.\n\nThe returned plan carries per-sheet steps and a `total_cost`. Each entry in\n`sheet_plans` includes an ordered `steps` array and counters for cuts,\nrotations, fence resets, tool ups, and total travel distance.\n\nThrows when `table_saw` or `panel_saw` is used on a non-guillotine layout\n(`NonGuillotineNotCuttable`) or when a cost override is invalid\n(`InvalidOptions`). Use `cnc_router` as the universal fallback for any layout.\n\n### `plan1dCuts(solution, options?)`\n\n```ts\nfunction plan1dCuts(solution: OneDSolution, options?: CutPlanOptions1D): CutPlanSolution1D;\n```\n\nGenerates an ordered cut plan for every bar in a finished `OneDSolution`. The\nonly preset is `chop_saw`. Each `bar_plans` entry carries ordered `steps`\n(`cut` and `fence_reset`) and a `total_cost`.\n\n### `solve1d(problem, options?)`\n\n```ts\nfunction solve1d(problem: OneDProblem, options?: OneDOptions): OneDSolution;\n```\n\nSolve a 1D cutting-stock problem. Throws a JavaScript `Error` on validation\nfailures, infeasible demands, or unsupported solver configurations.\n\nAlgorithms (`options.algorithm`):\n- `auto` *(default)* — runs FFD, BFD, local search, and optionally escalates\n to column generation\n- `first_fit_decreasing`\n- `best_fit_decreasing`\n- `local_search` — multistart; honors `seed`, `multistart_runs`, `improvement_rounds`\n- `column_generation` — exact backend; reports `exact: true` and a\n `lower_bound` when optimal\n\n### `solve2d(problem, options?)`\n\n```ts\nfunction solve2d(problem: TwoDProblem, options?: TwoDOptions): TwoDSolution;\n```\n\nSolve a 2D rectangular bin-packing problem. Throws on validation failures or\ninfeasible demands.\n\nAlgorithms (`options.algorithm`):\n- `auto` *(default)* — runs the full ensemble\n- MaxRects: `max_rects`, `max_rects_best_short_side_fit`, `max_rects_best_long_side_fit`,\n `max_rects_bottom_left`, `max_rects_contact_point`\n- Skyline: `skyline`, `skyline_min_waste`\n- Guillotine beam search: `guillotine`, `guillotine_best_short_side_fit`,\n `guillotine_best_long_side_fit`, `guillotine_shorter_leftover_axis`,\n `guillotine_longer_leftover_axis`, `guillotine_min_area_split`,\n `guillotine_max_area_split`\n- Shelf heuristics: `next_fit_decreasing_height`, `first_fit_decreasing_height`,\n `best_fit_decreasing_height`\n- Meta-strategies: `multi_start`, `rotation_search`\n\nSet `options.guillotine_required = true` to restrict `auto` to\nguillotine-compatible constructions.\n\n### `solve3d(problem, options?)`\n\n```ts\nfunction solve3d(problem: ThreeDProblem, options?: ThreeDOptions): ThreeDSolution;\n```\n\nSolve a 3D rectangular bin-packing problem. Throws a JavaScript `Error` on\nvalidation failures, infeasible demands, or unsupported solver configurations.\n\nAlgorithms (`options.algorithm`):\n- `auto` *(default)* — runs a tiered ensemble of algorithms and returns the\n best result\n- Extreme Points: `extreme_points`, `extreme_points_residual_space`,\n `extreme_points_free_volume`, `extreme_points_bottom_left_back`,\n `extreme_points_contact_point`, `extreme_points_euclidean`\n- Guillotine 3D: `guillotine_3d`, `guillotine_3d_best_short_side_fit`,\n `guillotine_3d_best_long_side_fit`, `guillotine_3d_shorter_leftover_axis`,\n `guillotine_3d_longer_leftover_axis`, `guillotine_3d_min_volume_split`,\n `guillotine_3d_max_volume_split`\n- Layer building: `layer_building`, `layer_building_max_rects`,\n `layer_building_skyline`, `layer_building_guillotine`, `layer_building_shelf`\n- Geometry: `wall_building`, `column_building`, `deepest_bottom_left`,\n `deepest_bottom_left_fill`, `first_fit_decreasing_volume`,\n `best_fit_decreasing_volume`\n- Meta-strategies: `multi_start`, `grasp`, `local_search`, `branch_and_bound`\n\n### JSON-string fallbacks\n\n`solve1dJson(problemJson, optionsJson?)`, `solve2dJson(problemJson, optionsJson?)`,\nand `solve3dJson(problemJson, optionsJson?)` accept and return JSON strings\ndirectly. Useful when the caller already has a JSON payload in hand (HTTP\nrequest body, file read, worker message). These are exported by the combined\nentry points; the dimension-specific entry points keep only the plain-object\nAPI to reduce browser payload size.\n\n### `version()`\n\nReturns the package version string.\n\n## TypeScript types\n\nAll input and output types are fully typed. Import them from the package:\n\n```ts\nimport type {\n OneDProblem,\n OneDSolution,\n OneDOptions,\n TwoDProblem,\n TwoDSolution,\n TwoDOptions,\n Placement2D,\n ThreeDProblem,\n ThreeDSolution,\n ThreeDOptions,\n Placement3D,\n} from '@0xdoublesharp/bin-packing-wasm';\n```\n\n## Performance notes\n\n- Browser WASM is ~1.5–3× slower than native for CPU-bound integer code.\n- The default `Auto` mode runs many strategies — for interactive UIs, pick a\n specific fast algorithm like `first_fit_decreasing_height` or\n `max_rects_best_short_side_fit`.\n- Consider running solves inside a Web Worker for large problems.\n- Reproducibility: pass `options.seed` to get deterministic output across\n runs.\n\n## Building from source\n\n```sh\ngit clone https://github.com/doublesharp/bin-packing\ncd bin-packing/bindings/wasm\n\n# One-time prerequisites\nrustup target add wasm32-unknown-unknown\ncargo install wasm-pack\n\n# Build combined and dimension-specific bundler, web, and nodejs targets into dist/\npnpm run build\n\n# Run the Node smoke test\npnpm test\n```\n\n## License\n\nMIT.\n\n### Workpiece-aware saw jobs\n\n`plan2dSawCuts(job, options?)` is available in combined and `two-d` builds for every\ntarget. It accepts explicit stock/demand provenance and returns one authoritative\nphysical schedule. See [the API and migration guide](../../docs/two-d/saw-planner.md).\nAfter building, run `node ../../examples/saw-planner.mjs wasm` or use `two-d`.\n","readmeFilename":"README.md"}
![\"bin-packing\"](\"https://raw.githubusercontent.com/doublesharp/bin-packing/main/docs/bin-packing.png\")
\n