@packvium/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Packvium contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @packvium/engine
+
+Deterministic 3D cartonization for Node.js. It uses the optional native engine when
+available and automatically falls back to the bundled JavaScript implementation.
+
+## Install
+
+```bash
+npm install @packvium/engine
+```
+
+Node.js 16 or later is required. Use a currently supported Node.js release in
+production.
+
+## Quick start
+
+```js
+import { backend, pack } from '@packvium/engine';
+
+const result = pack({
+  items: [{
+    id: 'book', quantity: 4,
+    dimensions: { length: '210', width: '140', height: '30' },
+  }],
+  containers: [{
+    id: 'carton',
+    inner_dimensions: { length: '400', width: '300', height: '250' },
+  }],
+});
+
+console.log(backend());       // "rust" or "javascript"
+console.log(result.status);   // "feasible"
+console.log(result.containers);
+```
+
+## Features
+
+- Exact, deterministic placement with no floating-point geometry decisions.
+- Rotation, payload, stackability, support, clearance, obstacle and tag constraints.
+- Multiple container types and clear explanations for unpacked items.
+- JSON input/output through `pack()` or `packJson()`.
+- Optional payload rebalancing with `rebalanceWeight()`.
+- Loading and removal sequence helpers for already placed boxes.
+
+The native addon is optional. `npm install` works on unsupported platforms too; call
+`backend()` if your application needs to know which implementation handled a request.
+
+## API and support
+
+TypeScript declarations are included. See the package's `index.d.ts` for the complete
+request and result types. Report security issues through [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/contact-graph.js

@@ -0,0 +1,61 @@
+/**
+ * Direct vertical-contact graph with a deterministic XY broad phase.
+ *
+ * Construction is expected O(n + q + e): q broad-phase candidates plus e real
+ * contact edges. A physically dense graph can still have e=O(n²), which no exact
+ * representation can avoid. The exact overlap function remains authoritative.
+ * This module is package-internal: package.json exports only the root entry point.
+ */
+export function buildContactGraph(boxes, overlapXY) {
+  const supporters = boxes.map(() => []);
+  const children = boxes.map(() => []);
+  if (boxes.length === 0) return { supporters, children, candidateChecks: 0 };
+
+  const cell = Math.max(1, ...boxes.map(box => Math.max(box.d[0], box.d[1])));
+  const byTop = new Map();
+  const levels = new Map();
+  const cells = box => {
+    const x1 = Math.floor(box.x / cell);
+    const x2 = Math.floor((box.x + box.d[0] - 1) / cell);
+    const y1 = Math.floor(box.y / cell);
+    const y2 = Math.floor((box.y + box.d[1] - 1) / cell);
+    return [...new Set([`${x1}:${y1}`, `${x2}:${y1}`, `${x1}:${y2}`, `${x2}:${y2}`])];
+  };
+
+  boxes.forEach((box, index) => {
+    const top = box.z + box.d[2];
+    if (!byTop.has(top)) byTop.set(top, []);
+    byTop.get(top).push(index);
+  });
+
+  let candidateChecks = 0;
+  boxes.forEach((upper, upperIndex) => {
+    const candidates = byTop.get(upper.z);
+    if (!candidates) return;
+    let level = levels.get(upper.z);
+    if (level == null) {
+      level = new Map();
+      for (const index of candidates) {
+        for (const key of cells(boxes[index])) {
+          if (!level.has(key)) level.set(key, []);
+          level.get(key).push(index);
+        }
+      }
+      levels.set(upper.z, level);
+    }
+    const nearby = new Set();
+    for (const key of cells(upper)) {
+      for (const index of level.get(key) ?? []) nearby.add(index);
+    }
+    for (const lowerIndex of [...nearby].sort((left, right) => left - right)) {
+      if (lowerIndex === upperIndex) continue;
+      candidateChecks++;
+      const area = overlapXY(boxes[lowerIndex], upper);
+      if (area > 0) {
+        supporters[upperIndex].push([lowerIndex, area]);
+        children[lowerIndex].push(upperIndex);
+      }
+    }
+  });
+  return { supporters, children, candidateChecks };
+}