@cratefit/pack 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1280 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * CrateFit Core Types
+ */
+export interface Point3D {
+	x: number;
+	y: number;
+	z: number;
+}
+export interface Dimensions3D {
+	width: number;
+	height: number;
+	depth: number;
+}
+export interface AABB {
+	minX: number;
+	maxX: number;
+	minY: number;
+	maxY: number;
+	minZ: number;
+	maxZ: number;
+}
+/**
+ * 6 rotation types for 3D items
+ * RT_WHD: W×H×D (original)
+ * RT_HWD: H×W×D
+ * RT_HDW: H×D×W
+ * RT_DHW: D×H×W
+ * RT_DWH: D×W×H
+ * RT_WDH: W×D×H
+ */
+export declare const RotationType: {
+	readonly RT_WHD: 0;
+	readonly RT_HWD: 1;
+	readonly RT_HDW: 2;
+	readonly RT_DHW: 3;
+	readonly RT_DWH: 4;
+	readonly RT_WDH: 5;
+};
+export type RotationTypeValue = (typeof RotationType)[keyof typeof RotationType];
+export type RotationMode = "all" | "horizontal" | "fixed";
+export interface ItemSpec {
+	id: string;
+	width: number;
+	height: number;
+	depth: number;
+	weight?: number;
+	rotationType?: RotationMode;
+	allowedRotations?: RotationTypeValue[];
+	maxStackWeight?: number;
+	requiresFloor?: boolean;
+	requiresSupport?: number;
+	groupId?: string;
+	incompatibleWith?: string[];
+	deliveryOrder?: number;
+	metadata?: Record<string, unknown>;
+}
+export interface PlacedItem {
+	item: ItemSpec;
+	position: Point3D;
+	rotation: RotationTypeValue;
+	dimensions: Dimensions3D;
+}
+export type ContainerType = "box" | "pallet" | "container" | "truck" | "shelf" | "custom";
+export interface ScenarioConstraints {
+	maxStackHeight?: number;
+	overhangAllowed?: boolean;
+	palletPattern?: "column" | "interlock";
+	axleWeights?: {
+		front: number;
+		rear: number;
+	};
+	loadingDirection?: "rear" | "side";
+	shelfLevels?: number[];
+	accessibility?: "fifo" | "lifo" | "random";
+	maxGirth?: number;
+	maxLinearDim?: number;
+	volumetricDivisor?: number;
+}
+export interface BinSpec {
+	id: string;
+	type: ContainerType;
+	width: number;
+	height: number;
+	depth: number;
+	maxWeight?: number;
+	cost?: number;
+	existingItems?: PlacedItem[];
+	excludeZones?: AABB[];
+	constraints?: ScenarioConstraints;
+}
+export type AlgorithmType = "extreme-point" | "layer-building" | "wall-building" | "eb-afit";
+export type PreprocessorType = "block-building" | "none";
+export type EnhancerType = "genetic" | "simulated-annealing" | "tabu-search" | "none";
+export type OptimizeTarget = "space" | "cost" | "balanced";
+export type BinSelectionStrategy = "first-fit" | "best-fit" | "spread";
+export type SpatialIndexType = "naive" | "octree";
+export interface PackOptions {
+	preprocessor?: PreprocessorType;
+	algorithm?: AlgorithmType;
+	enhancer?: EnhancerType;
+	timeBudgetMs?: number;
+	features?: {
+		supportCheck?: boolean;
+		weightBalance?: boolean;
+		stackingLimit?: boolean;
+	};
+	constraints?: {
+		respectDeliveryOrder?: boolean;
+		keepGroupsTogether?: boolean;
+		enforceIncompatibility?: boolean;
+	};
+	optimize?: {
+		target?: OptimizeTarget;
+	};
+	binSelection?: BinSelectionStrategy;
+	spatialIndex?: SpatialIndexType;
+}
+export interface PackConfig {
+	bins: BinSpec[];
+	items: ItemSpec[];
+	options?: PackOptions;
+}
+export interface PackedBin {
+	bin: BinSpec;
+	items: PlacedItem[];
+	utilization: number;
+	weight: number;
+	centerOfGravity: Point3D;
+}
+export interface PackStats {
+	totalBins: number;
+	totalItems: number;
+	packedItems: number;
+	unpackedItems: number;
+	avgUtilization: number;
+	totalVolume: number;
+	usedVolume: number;
+	totalWeight: number;
+	totalCost?: number;
+	actualWeight: number;
+	volumetricWeight?: number;
+	chargeableWeight?: number;
+}
+export interface PackResult {
+	packed: PackedBin[];
+	unpacked: ItemSpec[];
+	stats: PackStats;
+}
+export interface SpatialIndex {
+	insert(item: PlacedItem): void;
+	remove(item: PlacedItem): void;
+	query(bounds: AABB): PlacedItem[];
+	clear(): void;
+}
+/**
+ * Core pack function
+ */
+/**
+ * Main pack function
+ */
+export declare function pack(config: PackConfig): PackResult;
+/**
+ * Packer class - chainable API wrapper
+ */
+/**
+ * Chainable Packer class
+ */
+export declare class Packer {
+	private bins;
+	private items;
+	private options;
+	/**
+	 * Add a bin/container
+	 */
+	addBin(bin: BinSpec): this;
+	/**
+	 * Add multiple bins
+	 */
+	addBins(bins: BinSpec[]): this;
+	/**
+	 * Add an item
+	 */
+	addItem(item: ItemSpec): this;
+	/**
+	 * Add multiple items
+	 */
+	addItems(items: ItemSpec[]): this;
+	/**
+	 * Set pack options
+	 */
+	setOptions(options: Partial<PackOptions>): this;
+	/**
+	 * Execute packing
+	 */
+	pack(options?: Partial<PackOptions>): PackResult;
+	/**
+	 * Reset packer state
+	 */
+	reset(): this;
+	/**
+	 * Get current bins
+	 */
+	getBins(): BinSpec[];
+	/**
+	 * Get current items
+	 */
+	getItems(): ItemSpec[];
+	/**
+	 * Get current options
+	 */
+	getOptions(): PackOptions;
+}
+/**
+ * Create a new Packer instance
+ */
+export declare function createPacker(): Packer;
+/**
+ * Extreme Point Algorithm (Optimized)
+ *
+ * An advanced heuristic algorithm that tracks "extreme points" (candidate positions)
+ * where items can be placed. This implementation includes:
+ * - Projection of extreme points to support surfaces
+ * - Multiple point generation strategies
+ * - Best-fit selection option
+ * - Efficient point management
+ *
+ * Based on research and improvements over basic First-Fit approaches like py3dbp.
+ */
+/**
+ * Pack items into a single bin using Extreme Point algorithm
+ */
+export declare function packWithExtremePoint(bin: BinSpec, items: ItemSpec[], options?: PackOptions): {
+	packed: PlacedItem[];
+	unpacked: ItemSpec[];
+};
+/**
+ * Layer Building Algorithm
+ *
+ * A height-based packing algorithm that builds horizontal layers.
+ * Well-suited for pallet packing where items need stable stacking.
+ *
+ * Key concepts:
+ * - Groups items by similar heights into layers
+ * - Uses 2D bottom-left placement within each layer
+ * - Builds layers from bottom to top
+ * - Ensures proper support between layers
+ */
+/**
+ * Pack items into a single bin using Layer Building algorithm
+ */
+export declare function packWithLayerBuilding(bin: BinSpec, items: ItemSpec[], options?: PackOptions): {
+	packed: PlacedItem[];
+	unpacked: ItemSpec[];
+};
+/**
+ * Layer information for analysis
+ */
+export interface Layer {
+	yLevel: number;
+	height: number;
+	items: PlacedItem[];
+	coverage: number;
+}
+/**
+ * Extract layer information from packed result
+ */
+export declare function extractLayers(packed: PlacedItem[], binWidth?: number, binDepth?: number): Layer[];
+/**
+ * Wall Building Algorithm
+ *
+ * A depth-based packing algorithm that builds vertical "walls" from back to front.
+ * Well-suited for container loading with LIFO (Last In First Out) requirements.
+ *
+ * Key concepts:
+ * - Builds walls perpendicular to the Z-axis (depth direction)
+ * - Each wall is a 2D packing problem in the X-Y plane
+ * - Items are packed from the back of the container forward
+ * - Supports unloading order requirements
+ */
+/**
+ * Pack items into a single bin using Wall Building algorithm
+ */
+export declare function packWithWallBuilding(bin: BinSpec, items: ItemSpec[], options?: PackOptions): {
+	packed: PlacedItem[];
+	unpacked: ItemSpec[];
+};
+/**
+ * Wall information for analysis
+ */
+export interface Wall {
+	zStart: number;
+	zEnd: number;
+	items: PlacedItem[];
+	utilization: number;
+}
+/**
+ * Extract wall information from packed result
+ */
+export declare function extractWalls(packed: PlacedItem[], bin: BinSpec): Wall[];
+/**
+ * EB-AFIT Algorithm
+ *
+ * Based on Erhan Baltacıoğlu's thesis at Air Force Institute of Technology (2001).
+ * A human intelligence-based heuristic approach for 3D bin packing.
+ *
+ * Key concepts:
+ * - Evaluates all possible layer heights based on item dimensions
+ * - Selects optimal layer height by analyzing potential space utilization
+ * - Uses sophisticated gap management for better packing
+ * - Considers both horizontal and vertical space optimization
+ */
+/**
+ * Pack items using EB-AFIT algorithm
+ */
+export declare function packWithEBAFIT(bin: BinSpec, items: ItemSpec[], options?: PackOptions): {
+	packed: PlacedItem[];
+	unpacked: ItemSpec[];
+};
+/**
+ * Block Building Preprocessor
+ *
+ * Groups identical or similar items into larger blocks to reduce problem complexity.
+ * This is a preprocessing step that can improve packing efficiency for homogeneous items.
+ *
+ * Key concepts:
+ * - Groups items with identical dimensions
+ * - Creates composite blocks from multiple items
+ * - Reduces the number of items to place
+ * - Expands blocks back to original items after placement
+ */
+export interface Block {
+	id: string;
+	originalItems: ItemSpec[];
+	width: number;
+	height: number;
+	depth: number;
+	weight: number;
+	count: number;
+	/** How items are arranged in the block */
+	arrangement: BlockArrangement;
+}
+export interface BlockArrangement {
+	countX: number;
+	countY: number;
+	countZ: number;
+	itemWidth: number;
+	itemHeight: number;
+	itemDepth: number;
+}
+export interface BlockBuildingOptions {
+	/** Minimum items to form a block */
+	minBlockSize?: number;
+	/** Maximum items in a block */
+	maxBlockSize?: number;
+	/** Tolerance for matching dimensions (as percentage, 0-1) */
+	tolerancePct?: number;
+	/** Prefer blocks that fit container dimensions well */
+	optimizeForContainer?: {
+		width: number;
+		height: number;
+		depth: number;
+	};
+}
+/**
+ * Build blocks from items by grouping identical items
+ */
+export declare function buildBlocks(items: ItemSpec[], options?: BlockBuildingOptions): {
+	blocks: Block[];
+	remaining: ItemSpec[];
+};
+/**
+ * Expand blocks back to original items (for unpacked items)
+ */
+export declare function expandBlocks(blocks: Block[]): ItemSpec[];
+/**
+ * Genetic Algorithm Enhancer
+ *
+ * Post-processing optimizer using genetic algorithm to improve packing results.
+ * Uses evolutionary strategies to find better item orderings and configurations.
+ *
+ * Key concepts:
+ * - Chromosome: An ordering of items (permutation)
+ * - Fitness: Packing utilization and quality metrics
+ * - Crossover: Combine good orderings from parents
+ * - Mutation: Random swaps and rotations
+ * - Selection: Keep best solutions
+ */
+export interface GeneticOptions {
+	/** Number of solutions in population */
+	populationSize?: number;
+	/** Number of generations to evolve */
+	generations?: number;
+	/** Probability of crossover (0-1) */
+	crossoverRate?: number;
+	/** Probability of mutation (0-1) */
+	mutationRate?: number;
+	/** Number of best solutions to preserve */
+	elitismCount?: number;
+	/** Maximum time budget in milliseconds */
+	timeBudgetMs?: number;
+	/** Base packing options to use */
+	packOptions?: PackOptions;
+}
+/**
+ * Enhance packing result using genetic algorithm
+ */
+export declare function enhanceWithGenetic(result: PackResult, options?: GeneticOptions): PackResult;
+/**
+ * Collision detection constraints
+ */
+/**
+ * Check if placing an item at a position would collide with existing items
+ */
+export declare function hasCollision(position: Point3D, dimensions: Dimensions3D, spatialIndex: SpatialIndex): boolean;
+/**
+ * Check if item fits within bin boundaries
+ */
+export declare function fitsInBin(position: Point3D, dimensions: Dimensions3D, bin: BinSpec): boolean;
+/**
+ * Check if position is within any exclude zone
+ */
+export declare function isInExcludeZone(position: Point3D, dimensions: Dimensions3D, bin: BinSpec): boolean;
+/**
+ * Weight-related constraints
+ */
+/**
+ * Check if adding an item would exceed bin's max weight
+ */
+export declare function canAddWeight(existingItems: PlacedItem[], newItem: ItemSpec, bin: BinSpec): boolean;
+/**
+ * Calculate total weight of placed items
+ */
+export declare function calcTotalWeight(items: PlacedItem[]): number;
+/**
+ * Calculate center of gravity
+ */
+export declare function calcCenterOfGravity(items: PlacedItem[], bin: BinSpec): Point3D;
+/**
+ * Check if weight distribution is balanced
+ */
+export declare function isWeightBalanced(items: PlacedItem[], bin: BinSpec, tolerance?: number): boolean;
+/**
+ * Support/stability constraints
+ */
+/**
+ * Calculate supported area for an item
+ */
+export declare function calcSupportedArea(position: Point3D, dimensions: Dimensions3D, existingItems: PlacedItem[]): number;
+/**
+ * Check if an item has sufficient support
+ */
+export declare function hasSufficientSupport(position: Point3D, dimensions: Dimensions3D, existingItems: PlacedItem[], minSupportRatio?: number): boolean;
+/**
+ * Check stacking weight limit
+ */
+export declare function canStackOn(bottomItem: PlacedItem, topItemWeight: number, existingItems: PlacedItem[]): boolean;
+/**
+ * Grouping and compatibility constraints
+ */
+/**
+ * Check if an item can be mixed with existing items in a bin
+ */
+export declare function canMixInBin(existingItems: PlacedItem[], newItem: ItemSpec): boolean;
+/**
+ * Group items by groupId
+ */
+export declare function groupItems(items: ItemSpec[]): Map<string, ItemSpec[]>;
+/**
+ * Sort items by delivery order (higher order = process first = pack at back)
+ */
+export declare function sortByDeliveryOrder(items: ItemSpec[]): ItemSpec[];
+/**
+ * Sort items by volume (larger first by default)
+ */
+export declare function sortByVolume(items: ItemSpec[], ascending?: boolean): ItemSpec[];
+/**
+ * Sort items by weight (heavier first by default)
+ */
+export declare function sortByWeight(items: ItemSpec[], ascending?: boolean): ItemSpec[];
+/**
+ * Naive spatial index (linear search)
+ * Simple implementation for small item counts
+ */
+export declare class NaiveSpatialIndex implements SpatialIndex {
+	private items;
+	insert(item: PlacedItem): void;
+	remove(item: PlacedItem): void;
+	query(bounds: AABB): PlacedItem[];
+	clear(): void;
+	/**
+	 * Get all items (for iteration)
+	 */
+	getAll(): PlacedItem[];
+	/**
+	 * Get item count
+	 */
+	get size(): number;
+}
+/**
+ * Create a naive spatial index
+ */
+export declare function createNaiveIndex(): NaiveSpatialIndex;
+/**
+ * Octree spatial index for efficient 3D collision queries
+ *
+ * Provides O(log n) query performance for large item counts,
+ * compared to O(n) for naive linear search.
+ */
+/**
+ * Configuration for Octree
+ */
+export interface OctreeConfig {
+	/** Maximum items per node before splitting (default: 8) */
+	maxItemsPerNode?: number;
+	/** Maximum tree depth (default: 8) */
+	maxDepth?: number;
+	/** Minimum node size - won't split below this (default: 1) */
+	minNodeSize?: number;
+}
+/**
+ * Octree spatial index implementation
+ *
+ * Efficiently organizes 3D items for fast spatial queries.
+ * Best for scenarios with 100+ items.
+ */
+export declare class OctreeIndex implements SpatialIndex {
+	private root;
+	private config;
+	private itemCount;
+	private itemMap;
+	constructor(bounds: AABB, config?: OctreeConfig);
+	/**
+	 * Insert an item into the octree
+	 */
+	insert(item: PlacedItem): void;
+	/**
+	 * Recursively insert item into appropriate node(s)
+	 */
+	private insertIntoNode;
+	/**
+	 * Check if a node should be subdivided
+	 */
+	private shouldSubdivide;
+	/**
+	 * Subdivide a node and redistribute its items
+	 */
+	private subdivideNode;
+	/**
+	 * Remove an item from the octree
+	 */
+	remove(item: PlacedItem): void;
+	/**
+	 * Recursively remove item from node and children
+	 */
+	private removeFromNode;
+	/**
+	 * Query all items that intersect with the given bounds
+	 */
+	query(bounds: AABB): PlacedItem[];
+	/**
+	 * Recursively query node and children
+	 */
+	private queryNode;
+	/**
+	 * Clear all items from the octree
+	 */
+	clear(): void;
+	/**
+	 * Get all items in the octree
+	 */
+	getAll(): PlacedItem[];
+	/**
+	 * Get the number of items in the octree
+	 */
+	get size(): number;
+	/**
+	 * Get statistics about the octree structure
+	 */
+	getStats(): OctreeStats;
+	private collectStats;
+}
+/**
+ * Statistics about octree structure
+ */
+export interface OctreeStats {
+	totalNodes: number;
+	leafNodes: number;
+	maxDepth: number;
+	itemCount: number;
+	avgItemsPerLeaf: number;
+}
+/**
+ * Create an octree spatial index
+ */
+export declare function createOctreeIndex(bounds: AABB, config?: OctreeConfig): OctreeIndex;
+/**
+ * Integer conversion utilities for precision handling
+ */
+/**
+ * Set the scale factor for integer conversion
+ */
+export declare function setScale(scale: number): void;
+/**
+ * Get the current scale factor
+ */
+export declare function getScale(): number;
+/**
+ * Convert external value to internal integer
+ */
+export declare function toInternal(value: number): number;
+/**
+ * Convert internal integer to external value
+ */
+export declare function toExternal(value: number): number;
+/**
+ * Rotation utilities
+ */
+/**
+ * Get rotated dimensions based on rotation type
+ */
+export declare function getRotatedDimensions(width: number, height: number, depth: number, rotation: RotationTypeValue): Dimensions3D;
+/**
+ * Get allowed rotations based on rotation mode
+ */
+export declare function getAllowedRotations(mode: RotationMode): RotationTypeValue[];
+/**
+ * Get all rotation variants for an item
+ */
+export declare function getRotationVariants(width: number, height: number, depth: number, allowedRotations: RotationTypeValue[]): Array<{
+	rotation: RotationTypeValue;
+	dimensions: Dimensions3D;
+}>;
+/**
+ * Geometry utilities
+ */
+/**
+ * Create AABB from position and dimensions
+ */
+export declare function createAABB(position: Point3D, dimensions: Dimensions3D): AABB;
+/**
+ * Check if two AABBs intersect
+ */
+export declare function intersectsAABB(a: AABB, b: AABB): boolean;
+/**
+ * Check if AABB a contains AABB b
+ */
+export declare function containsAABB(a: AABB, b: AABB): boolean;
+/**
+ * Calculate volume of AABB
+ */
+export declare function volumeAABB(aabb: AABB): number;
+/**
+ * Calculate volume from dimensions
+ */
+export declare function volume(dims: Dimensions3D): number;
+/**
+ * Get AABB of a placed item
+ */
+export declare function getItemAABB(item: PlacedItem): AABB;
+/**
+ * Calculate overlap area on XZ plane (for support calculation)
+ */
+export declare function calcOverlapAreaXZ(a: AABB, b: AABB): number;
+/**
+ * Check if item is directly above another (for stacking)
+ */
+export declare function isDirectlyAbove(top: PlacedItem, bottom: PlacedItem): boolean;
+/**
+ * Validation utilities for packing results
+ *
+ * Verifies that packing results are correct:
+ * - No collisions between items
+ * - All items within bin boundaries
+ * - Volume calculations are accurate
+ * - All constraints are satisfied
+ */
+export interface ValidationResult {
+	valid: boolean;
+	errors: ValidationError[];
+	warnings: ValidationWarning[];
+}
+export interface ValidationOptions {
+	/** Check support constraint (items should not float) */
+	checkSupport?: boolean;
+}
+export interface ValidationError {
+	type: "collision" | "boundary" | "volume" | "count" | "support";
+	message: string;
+	items?: string[];
+}
+export interface ValidationWarning {
+	type: "utilization" | "balance" | "gap";
+	message: string;
+}
+/**
+ * Validate a packing result
+ */
+export declare function validatePackingResult(bin: BinSpec, packed: PlacedItem[], unpacked: ItemSpec[], originalItems: ItemSpec[], options?: ValidationOptions): ValidationResult;
+/**
+ * Quick validation check (returns true/false only)
+ */
+export declare function isValidPacking(bin: BinSpec, packed: PlacedItem[], unpacked: ItemSpec[], originalItems: ItemSpec[], options?: ValidationOptions): boolean;
+/**
+ * Packing Instructions Types
+ *
+ * Types for generating human-readable packing instructions
+ */
+/**
+ * Action type for packing instruction
+ */
+export type InstructionAction = "place" | "rotate" | "stack";
+/**
+ * Orientation description
+ */
+export type OrientationDescription = "upright" | "flat" | "sideways" | "rotated-90" | "rotated-180" | "custom";
+/**
+ * Position description relative to bin or other items
+ */
+export interface PositionDescription {
+	/** Human-readable position description */
+	description: string;
+	/** Exact coordinates */
+	coordinates: Point3D;
+	/** Reference item ID (if stacking or adjacent) */
+	referenceItemId?: string;
+	/** Relationship to reference item */
+	relationship?: "above" | "beside" | "behind" | "in-front";
+}
+/**
+ * Single packing instruction step
+ */
+export interface PackingInstruction {
+	/** Step number (1-indexed) */
+	step: number;
+	/** Action type */
+	action: InstructionAction;
+	/** Item ID */
+	itemId: string;
+	/** Human-readable item name (from metadata or ID) */
+	itemName: string;
+	/** Position information */
+	position: PositionDescription;
+	/** Item dimensions after rotation */
+	dimensions: Dimensions3D;
+	/** Orientation description */
+	orientation: OrientationDescription;
+	/** Layer number (1-indexed, from bottom) */
+	layer: number;
+	/** Additional notes/warnings */
+	notes: string[];
+	/** Original placed item reference */
+	placedItem: PlacedItem;
+}
+/**
+ * Bin instruction summary
+ */
+export interface BinInstructionSummary {
+	/** Bin ID */
+	binId: string;
+	/** Bin type */
+	binType: string;
+	/** Bin dimensions (W x H x D) */
+	binDimensions: string;
+	/** Total item count */
+	itemCount: number;
+	/** Total weight */
+	totalWeight: number;
+	/** Layer count */
+	layerCount: number;
+	/** Space utilization percentage */
+	utilization: number;
+}
+/**
+ * Instructions for a single bin
+ */
+export interface BinInstructions {
+	/** Bin summary info */
+	summary: BinInstructionSummary;
+	/** Ordered list of packing steps */
+	steps: PackingInstruction[];
+	/** General notes for this bin */
+	notes: string[];
+}
+/**
+ * Complete packing instructions for all bins
+ */
+export interface PackingInstructions {
+	/** Generated timestamp */
+	generatedAt: string;
+	/** Total bins */
+	totalBins: number;
+	/** Total items */
+	totalItems: number;
+	/** Instructions per bin */
+	bins: BinInstructions[];
+	/** Global notes/warnings */
+	globalNotes: string[];
+}
+/**
+ * Output format for instructions
+ */
+export type InstructionFormat = "json" | "markdown" | "html";
+/**
+ * Language for instructions
+ */
+export type InstructionLanguage = "en" | "zh-TW";
+/**
+ * Detail level for instructions
+ */
+export type InstructionDetailLevel = "simple" | "detailed";
+/**
+ * Options for generating instructions
+ */
+export interface GenerateInstructionsOptions {
+	/** Output format */
+	format?: InstructionFormat;
+	/** Language */
+	language?: InstructionLanguage;
+	/** Detail level */
+	detailLevel?: InstructionDetailLevel;
+	/** Include coordinate details */
+	includeCoordinates?: boolean;
+	/** Include weight information */
+	includeWeight?: boolean;
+	/** Layer height threshold for grouping (in same units as dimensions) */
+	layerHeightThreshold?: number;
+}
+/**
+ * Result of instruction generation
+ */
+export interface GenerateInstructionsResult {
+	/** Structured instructions */
+	instructions: PackingInstructions;
+	/** Formatted output string */
+	formatted: string;
+	/** Format used */
+	format: InstructionFormat;
+	/** Language used */
+	language: InstructionLanguage;
+}
+/**
+ * Packing Instructions Generator
+ *
+ * Converts PackResult to human-readable packing instructions
+ */
+/**
+ * Generate complete packing instructions from pack result
+ */
+export declare function generateInstructions(result: PackResult, options?: GenerateInstructionsOptions): GenerateInstructionsResult;
+/**
+ * JSON Formatter for Packing Instructions
+ */
+/**
+ * Format instructions as JSON string
+ */
+export declare function formatAsJson(instructions: PackingInstructions, options: Required<GenerateInstructionsOptions>): string;
+/**
+ * Markdown Formatter for Packing Instructions
+ */
+/**
+ * Format instructions as Markdown
+ */
+export declare function formatAsMarkdown(instructions: PackingInstructions, options: Required<GenerateInstructionsOptions>): string;
+/**
+ * HTML Formatter for Packing Instructions
+ *
+ * Generates a print-friendly HTML document with embedded styles
+ */
+/**
+ * Format instructions as HTML document
+ */
+export declare function formatAsHtml(instructions: PackingInstructions, options: Required<GenerateInstructionsOptions>): string;
+/**
+ * Online Packing Types
+ *
+ * Types for real-time/online bin packing where items arrive one at a time
+ * and placement decisions must be made immediately without knowing future items.
+ */
+/**
+ * Placement result for a single item
+ */
+export interface PlacementResult {
+	/** Whether the item was successfully placed */
+	success: boolean;
+	/** ID of the bin where item was placed (if successful) */
+	binId?: string;
+	/** Position where item was placed */
+	position?: Point3D;
+	/** Placed item details */
+	placedItem?: PlacedItem;
+	/** Reason for failure (if unsuccessful) */
+	reason?: "no-fit" | "weight-exceeded" | "no-bins";
+}
+/**
+ * Current state of an online packer bin
+ */
+export interface OnlineBinState {
+	/** The bin specification */
+	bin: BinSpec;
+	/** Items currently placed in this bin */
+	items: PlacedItem[];
+	/** Current utilization (0-1) */
+	utilization: number;
+	/** Current total weight */
+	weight: number;
+	/** Remaining capacity (volume) */
+	remainingVolume: number;
+}
+/**
+ * Options for online packing
+ */
+export interface OnlinePackerOptions extends Pick<PackOptions, "features" | "constraints"> {
+	/** Algorithm to use for placement decisions */
+	algorithm?: "online-extreme-point" | "online-first-fit";
+	/** Strategy for selecting which bin to use */
+	binSelection?: "first-fit" | "best-fit" | "worst-fit";
+	/** Whether to automatically add new bins when needed */
+	autoAddBins?: boolean;
+	/** Template for auto-added bins (required if autoAddBins is true) */
+	binTemplate?: BinSpec;
+	/** Maximum number of bins to auto-create */
+	maxBins?: number;
+}
+/**
+ * Statistics for online packing session
+ */
+export interface OnlinePackerStats {
+	/** Total items processed */
+	totalItems: number;
+	/** Items successfully placed */
+	placedItems: number;
+	/** Items that could not be placed */
+	rejectedItems: number;
+	/** Number of bins in use */
+	binsInUse: number;
+	/** Average utilization across all bins */
+	avgUtilization: number;
+	/** Total weight packed */
+	totalWeight: number;
+}
+/**
+ * Event types for online packer
+ */
+export type OnlinePackerEventType = "item-placed" | "item-rejected" | "bin-added" | "bin-full";
+/**
+ * Event data for online packer events
+ */
+export interface OnlinePackerEvent {
+	type: OnlinePackerEventType;
+	item?: ItemSpec;
+	bin?: BinSpec;
+	placement?: PlacementResult;
+	timestamp: number;
+}
+/**
+ * Event listener type
+ */
+export type OnlinePackerEventListener = (event: OnlinePackerEvent) => void;
+/**
+ * Online Packer
+ *
+ * A stateful packer for real-time/online bin packing scenarios where items
+ * arrive one at a time and placement decisions must be made immediately.
+ *
+ * Key differences from offline packing:
+ * - Items are processed one at a time as they arrive
+ * - No knowledge of future items
+ * - Placement decisions are immediate and irreversible
+ * - State is maintained between item placements
+ */
+/**
+ * Online Packer Class
+ *
+ * Handles real-time bin packing where items arrive sequentially.
+ */
+export declare class OnlinePacker {
+	private options;
+	private binStates;
+	private binOrder;
+	private stats;
+	private eventListeners;
+	private autoAddCounter;
+	constructor(options?: OnlinePackerOptions & {
+		bins?: BinSpec[];
+	});
+	/**
+	 * Add a new bin to the packer
+	 */
+	addBin(bin: BinSpec): void;
+	/**
+	 * Remove a bin from the packer
+	 */
+	removeBin(binId: string): OnlineBinState | null;
+	/**
+	 * Place a single item immediately
+	 *
+	 * This is the core method for online packing. It attempts to place
+	 * the item in one of the available bins using the configured algorithm.
+	 */
+	placeItem(item: ItemSpec): PlacementResult;
+	/**
+	 * Check if an item can possibly fit in the bin template
+	 */
+	private canFitInTemplate;
+	/**
+	 * Find a valid placement for an item across all bins
+	 */
+	private findPlacement;
+	/**
+	 * Find placement within a specific bin
+	 */
+	private findPlacementInBin;
+	/**
+	 * Update extreme points after placing an item
+	 */
+	private updateExtremePoints;
+	/**
+	 * Get bin order based on selection strategy
+	 */
+	private getBinOrder;
+	/**
+	 * Automatically add a new bin
+	 */
+	private autoAddBin;
+	/**
+	 * Update average utilization statistic
+	 */
+	private updateAvgUtilization;
+	/**
+	 * Get current statistics
+	 */
+	getStats(): OnlinePackerStats;
+	/**
+	 * Get state of a specific bin
+	 */
+	getBinState(binId: string): OnlineBinState | null;
+	/**
+	 * Get states of all bins
+	 */
+	getAllBinStates(): OnlineBinState[];
+	/**
+	 * Get list of bin IDs
+	 */
+	getBinIds(): string[];
+	/**
+	 * Reset the packer to initial state
+	 */
+	reset(): void;
+	/**
+	 * Subscribe to events
+	 */
+	on(event: OnlinePackerEventType, listener: OnlinePackerEventListener): () => void;
+	/**
+	 * Emit an event
+	 */
+	private emit;
+	/**
+	 * Generate initial extreme points considering exclude zones
+	 */
+	private generateInitialExtremePoints;
+}
+/**
+ * Pallet standard sizes
+ */
+export interface PalletStandard {
+	width: number;
+	depth: number;
+	height: number;
+	name: string;
+}
+/**
+ * Standard pallet sizes (in mm)
+ */
+export declare const PALLET_STANDARDS: {
+	readonly EUR1: {
+		readonly width: 800;
+		readonly depth: 1200;
+		readonly height: 144;
+		readonly name: "EUR1 (Euro Pallet)";
+	};
+	readonly EUR2: {
+		readonly width: 1200;
+		readonly depth: 1000;
+		readonly height: 144;
+		readonly name: "EUR2";
+	};
+	readonly EUR3: {
+		readonly width: 1000;
+		readonly depth: 1200;
+		readonly height: 144;
+		readonly name: "EUR3";
+	};
+	readonly EUR6: {
+		readonly width: 600;
+		readonly depth: 800;
+		readonly height: 144;
+		readonly name: "EUR6 (Half Pallet)";
+	};
+	readonly US: {
+		readonly width: 1016;
+		readonly depth: 1219;
+		readonly height: 150;
+		readonly name: "US (40\"\u00D748\")";
+	};
+	readonly US_GROCERY: {
+		readonly width: 1016;
+		readonly depth: 1219;
+		readonly height: 150;
+		readonly name: "US Grocery";
+	};
+	readonly ASIA: {
+		readonly width: 1100;
+		readonly depth: 1100;
+		readonly height: 150;
+		readonly name: "Asia Standard";
+	};
+	readonly AUSTRALIA: {
+		readonly width: 1165;
+		readonly depth: 1165;
+		readonly height: 150;
+		readonly name: "Australia Standard";
+	};
+};
+export type PalletStandardName = keyof typeof PALLET_STANDARDS;
+/**
+ * Get pallet standard by name
+ */
+export declare function getPalletStandard(name: PalletStandardName): PalletStandard;
+/**
+ * Pallet packing function
+ */
+export interface PalletOptions {
+	/** Pallet size - standard name or custom dimensions */
+	palletSize?: PalletStandardName | {
+		width: number;
+		depth: number;
+	};
+	/** Maximum stack height (mm) */
+	maxHeight?: number;
+	/** Maximum weight (kg) */
+	maxWeight?: number;
+	/** Algorithm to use */
+	algorithm?: "layer-building" | "eb-afit" | "extreme-point";
+	/** Additional pack options */
+	packOptions?: Partial<PackOptions>;
+}
+export interface PalletResult extends PackResult {
+	/** Pallet specification used */
+	palletSpec: BinSpec;
+}
+/**
+ * Pack items onto a pallet
+ */
+export declare function packPallet(items: ItemSpec[], options?: PalletOptions): PalletResult;
+/**
+ * Container standard sizes
+ */
+export interface ContainerStandard {
+	width: number;
+	height: number;
+	depth: number;
+	maxWeight: number;
+	name: string;
+}
+/**
+ * Standard container sizes (internal dimensions in mm, weight in kg)
+ */
+export declare const CONTAINER_STANDARDS: {
+	readonly "20ft": {
+		readonly width: 2352;
+		readonly height: 2393;
+		readonly depth: 5898;
+		readonly maxWeight: 21770;
+		readonly name: "20ft Standard";
+	};
+	readonly "40ft": {
+		readonly width: 2352;
+		readonly height: 2393;
+		readonly depth: 12032;
+		readonly maxWeight: 26680;
+		readonly name: "40ft Standard";
+	};
+	readonly "40ftHC": {
+		readonly width: 2352;
+		readonly height: 2698;
+		readonly depth: 12032;
+		readonly maxWeight: 26460;
+		readonly name: "40ft High Cube";
+	};
+	readonly "45ftHC": {
+		readonly width: 2352;
+		readonly height: 2698;
+		readonly depth: 13556;
+		readonly maxWeight: 25600;
+		readonly name: "45ft High Cube";
+	};
+};
+export type ContainerStandardName = keyof typeof CONTAINER_STANDARDS;
+/**
+ * Get container standard by name
+ */
+export declare function getContainerStandard(name: ContainerStandardName): ContainerStandard;
+/**
+ * Container packing function
+ */
+export interface ContainerOptions {
+	/** Container size - standard name or custom dimensions */
+	containerSize?: ContainerStandardName | {
+		width: number;
+		height: number;
+		depth: number;
+	};
+	/** Maximum weight (kg) */
+	maxWeight?: number;
+	/** Loading direction */
+	loadingDirection?: "rear" | "side";
+	/** Respect delivery order (LIFO) */
+	respectDeliveryOrder?: boolean;
+	/** Algorithm to use */
+	algorithm?: "wall-building" | "extreme-point" | "layer-building";
+	/** Additional pack options */
+	packOptions?: Partial<PackOptions>;
+}
+export interface ContainerResult extends PackResult {
+	/** Container specification used */
+	containerSpec: BinSpec;
+}
+/**
+ * Pack items into a container
+ */
+export declare function packContainer(items: ItemSpec[], options?: ContainerOptions): ContainerResult;
+/**
+ * Truck loading function
+ */
+export interface TruckOptions {
+	/** Truck cargo dimensions */
+	truckSize: {
+		width: number;
+		height: number;
+		depth: number;
+	};
+	/** Maximum weight (kg) */
+	maxWeight?: number;
+	/** Axle weight limits */
+	axleWeights?: {
+		front: number;
+		rear: number;
+	};
+	/** Wheelbase position (distance from front) */
+	wheelbase?: number;
+	/** Front axle position from cargo area start */
+	frontAxleOffset?: number;
+	/** Algorithm to use */
+	algorithm?: "wall-building" | "extreme-point";
+	/** Additional pack options */
+	packOptions?: Partial<PackOptions>;
+}
+export interface AxleWeightResult {
+	front: number;
+	rear: number;
+	isValid: boolean;
+}
+export interface TruckResult extends PackResult {
+	/** Truck specification used */
+	truckSpec: BinSpec;
+	/** Calculated axle weights */
+	axleWeights: AxleWeightResult;
+}
+/**
+ * Calculate axle weights based on item positions
+ */
+export declare function calcAxleWeights(items: PlacedItem[], truckDepth: number, wheelbase?: number, frontAxleOffset?: number): AxleWeightResult;
+/**
+ * Pack items into a truck
+ */
+export declare function packTruck(items: ItemSpec[], options: TruckOptions): TruckResult;
+
+export {};