Upload 31 files

Dockerfile

@@ -0,0 +1,24 @@
+# Use Python 3.12 base image
+FROM python:3.12
+
+# Install JDK 21 (required for solverforge-legacy)
+RUN apt-get update && \
+    apt-get install -y wget gnupg2 && \
+    wget -O- https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor > /usr/share/keyrings/adoptium-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/adoptium-archive-keyring.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list && \
+    apt-get update && \
+    apt-get install -y temurin-21-jdk && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy application files
+COPY . .
+
+# Install the application
+RUN pip install --no-cache-dir -e .
+
+# Expose port 8080
+EXPOSE 8080
+
+# Run the application
+CMD ["run-app"]

README.md

@@ -1,12 +1,79 @@
 ---
-title: Order Picking Python
-emoji: 🏢
-colorFrom: yellow
-colorTo: blue
+title: Order Picking (Python)
+emoji: 🏭
+colorFrom: gray
+colorTo: green
 sdk: docker
+app_port: 8080
 pinned: false
 license: apache-2.0
 short_description: SolverForge Quickstart for the Order Picking problem
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Order Picking (Python)
+
+Optimize warehouse order picking by assigning items to trolleys and minimizing travel distance.
+
+- [Prerequisites](#prerequisites)
+- [Run the application](#run-the-application)
+- [Test the application](#test-the-application)
+
+## Prerequisites
+
+1. Install [Python 3.11 or 3.12](https://www.python.org/downloads/).
+
+2. Install JDK 17+, for example with [Sdkman](https://sdkman.io):
+
+   ```sh
+   $ sdk install java
+   ```
+
+## Run the application
+
+1. Git clone the solverforge-solver-python repo and navigate to this directory:
+
+   ```sh
+   $ git clone https://github.com/SolverForge/solverforge-quickstarts.git
+   ...
+   $ cd solverforge-quickstarts/fast/order-picking-fast
+   ```
+
+2. Create a virtual environment:
+
+   ```sh
+   $ python -m venv .venv
+   ```
+
+3. Activate the virtual environment:
+
+   ```sh
+   $ . .venv/bin/activate
+   ```
+
+4. Install the application:
+
+   ```sh
+   $ pip install -e .
+   ```
+
+5. Run the application:
+
+   ```sh
+   $ run-app
+   ```
+
+6. Visit [http://localhost:8080](http://localhost:8080) in your browser.
+
+7. Click on the **Solve** button.
+
+## Test the application
+
+1. Run tests:
+
+   ```sh
+   $ pytest
+   ```
+
+## More information
+
+Visit [solverforge.org](https://www.solverforge.org).

logging.conf

@@ -0,0 +1,30 @@
+[loggers]
+keys=root,timefold_solver
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=simpleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[logger_timefold_solver]
+level=INFO
+qualname=timefold.solver
+handlers=consoleHandler
+propagate=0
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=simpleFormatter
+args=(sys.stdout,)
+
+[formatter_simpleFormatter]
+class=uvicorn.logging.ColourizedFormatter
+format={levelprefix:<8} @ {name} : {message}
+style={
+use_colors=True

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "order_picking"
+version = "1.0.0"
+requires-python = ">=3.10"
+dependencies = [
+    'solverforge-legacy == 1.24.1',
+    'fastapi == 0.111.0',
+    'pydantic == 2.7.3',
+    'uvicorn == 0.30.1',
+    'pytest == 8.2.2',
+]
+
+
+[project.scripts]
+run-app = "order_picking:main"

src/order_picking/__init__.py

@@ -0,0 +1,19 @@
+import uvicorn
+
+from .rest_api import app as app
+
+
+def main():
+    config = uvicorn.Config(
+        "order_picking:app",
+        host="0.0.0.0",
+        port=8080,
+        log_config="logging.conf",
+        use_colors=True,
+    )
+    server = uvicorn.Server(config)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

src/order_picking/constraints.py

@@ -0,0 +1,68 @@
+from solverforge_legacy.solver.score import (
+    constraint_provider,
+    ConstraintFactory,
+    HardSoftDecimalScore,
+)
+
+from .domain import Trolley
+
+
+REQUIRED_NUMBER_OF_BUCKETS = "Required number of buckets"
+MINIMIZE_ORDER_SPLIT = "Minimize order split by trolley"
+MINIMIZE_DISTANCE = "Minimize total distance"
+
+
+@constraint_provider
+def define_constraints(factory: ConstraintFactory):
+    return [
+        # Hard constraints
+        required_number_of_buckets(factory),
+        # Soft constraints
+        minimize_order_split_by_trolley(factory),
+        minimize_total_distance(factory),
+    ]
+
+
+def required_number_of_buckets(factory: ConstraintFactory):
+    """
+    Hard: Ensure trolley has enough buckets for all orders.
+    """
+    return (
+        factory.for_each(Trolley)
+        .filter(lambda trolley: trolley.calculate_excess_buckets() > 0)
+        .penalize(
+            HardSoftDecimalScore.ONE_HARD,
+            lambda trolley: trolley.calculate_excess_buckets()
+        )
+        .as_constraint(REQUIRED_NUMBER_OF_BUCKETS)
+    )
+
+
+def minimize_order_split_by_trolley(factory: ConstraintFactory):
+    """
+    Soft: Orders should ideally be on the same trolley.
+    """
+    return (
+        factory.for_each(Trolley)
+        .filter(lambda trolley: len(trolley.steps) > 0)
+        .penalize(
+            HardSoftDecimalScore.ONE_SOFT,
+            lambda trolley: trolley.calculate_order_split_penalty()
+        )
+        .as_constraint(MINIMIZE_ORDER_SPLIT)
+    )
+
+
+def minimize_total_distance(factory: ConstraintFactory):
+    """
+    Soft: Minimize total distance traveled by all trolleys.
+    Aggregated at Trolley level (like vehicle-routing) for performance.
+    """
+    return (
+        factory.for_each(Trolley)
+        .penalize(
+            HardSoftDecimalScore.ONE_SOFT,
+            lambda trolley: trolley.calculate_total_distance()
+        )
+        .as_constraint(MINIMIZE_DISTANCE)
+    )

src/order_picking/converters.py

@@ -0,0 +1,185 @@
+from typing import Dict
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.score import HardSoftDecimalScore
+
+from . import domain
+from .warehouse import WarehouseLocation, Side
+
+
+# =============================================================================
+# Domain to API Model Conversion
+# =============================================================================
+
+def location_to_model(location: WarehouseLocation) -> domain.WarehouseLocationModel:
+    return domain.WarehouseLocationModel(
+        shelving_id=location.shelving_id,
+        side=location.side.name,
+        row=location.row
+    )
+
+
+def product_to_model(product: domain.Product) -> domain.ProductModel:
+    return domain.ProductModel(
+        id=product.id,
+        name=product.name,
+        volume=product.volume,
+        location=location_to_model(product.location)
+    )
+
+
+def order_item_to_model(item: domain.OrderItem) -> domain.OrderItemModel:
+    return domain.OrderItemModel(
+        id=item.id,
+        order_id=item.order_id,
+        product=product_to_model(item.product)
+    )
+
+
+def order_to_model(order: domain.Order) -> domain.OrderModel:
+    return domain.OrderModel(
+        id=order.id,
+        items=[order_item_to_model(item) for item in order.items]
+    )
+
+
+def trolley_step_to_model(step: domain.TrolleyStep) -> domain.TrolleyStepModel:
+    return domain.TrolleyStepModel(
+        id=step.id,
+        order_item=order_item_to_model(step.order_item),
+        trolley=step.trolley.id if step.trolley else None,
+        trolley_id=step.trolley_id
+    )
+
+
+def trolley_to_model(trolley: domain.Trolley) -> domain.TrolleyModel:
+    return domain.TrolleyModel(
+        id=trolley.id,
+        bucket_count=trolley.bucket_count,
+        bucket_capacity=trolley.bucket_capacity,
+        location=location_to_model(trolley.location),
+        steps=[step.id for step in trolley.steps]
+    )
+
+
+def solution_to_model(solution: domain.OrderPickingSolution) -> domain.OrderPickingSolutionModel:
+    return domain.OrderPickingSolutionModel(
+        trolleys=[trolley_to_model(t) for t in solution.trolleys],
+        trolley_steps=[trolley_step_to_model(s) for s in solution.trolley_steps],
+        score=str(solution.score) if solution.score else None,
+        solver_status=solution.solver_status.name if solution.solver_status else None
+    )
+
+
+# =============================================================================
+# API Model to Domain Conversion
+# =============================================================================
+
+def model_to_location(model: domain.WarehouseLocationModel) -> WarehouseLocation:
+    return WarehouseLocation(
+        shelving_id=model.shelving_id,
+        side=Side[model.side],
+        row=model.row
+    )
+
+
+def model_to_product(model: domain.ProductModel) -> domain.Product:
+    return domain.Product(
+        id=model.id,
+        name=model.name,
+        volume=model.volume,
+        location=model_to_location(model.location)
+    )
+
+
+def model_to_solution(model: domain.OrderPickingSolutionModel) -> domain.OrderPickingSolution:
+    """Convert API model to domain object."""
+    # First pass: create all products and orders without cross-references
+    products: Dict[str, domain.Product] = {}
+    orders: Dict[str, domain.Order] = {}
+
+    # Extract unique products and orders from trolley steps
+    for step_model in model.trolley_steps:
+        item_model = step_model.order_item
+        product_model = item_model.product
+
+        # Create product if not seen
+        if product_model.id not in products:
+            products[product_model.id] = model_to_product(product_model)
+
+        # Create order if not seen
+        order_id = item_model.order_id
+        if order_id and order_id not in orders:
+            orders[order_id] = domain.Order(id=order_id, items=[])
+
+    # Second pass: create order items and trolley steps
+    trolley_steps = []
+    step_lookup: Dict[str, domain.TrolleyStep] = {}
+
+    for step_model in model.trolley_steps:
+        item_model = step_model.order_item
+        product = products[item_model.product.id]
+        order = orders.get(item_model.order_id) if item_model.order_id else None
+
+        order_item = domain.OrderItem(
+            id=item_model.id,
+            order=order,
+            product=product
+        )
+
+        # Add item to order's item list
+        if order:
+            order.items.append(order_item)
+
+        step = domain.TrolleyStep(
+            id=step_model.id,
+            order_item=order_item
+        )
+        trolley_steps.append(step)
+        step_lookup[step.id] = step
+
+    # Third pass: create trolleys and set up relationships
+    trolleys = []
+    trolley_lookup: Dict[str, domain.Trolley] = {}
+
+    for trolley_model in model.trolleys:
+        trolley = domain.Trolley(
+            id=trolley_model.id,
+            bucket_count=trolley_model.bucket_count,
+            bucket_capacity=trolley_model.bucket_capacity,
+            location=model_to_location(trolley_model.location),
+            steps=[]
+        )
+        trolleys.append(trolley)
+        trolley_lookup[trolley.id] = trolley
+
+        # Populate steps list
+        for step_ref in trolley_model.steps:
+            step_id = step_ref if isinstance(step_ref, str) else step_ref.id
+            if step_id in step_lookup:
+                step = step_lookup[step_id]
+                trolley.steps.append(step)
+                # Set shadow variable (for consistency, though solver will reset)
+                step.trolley = trolley
+
+    # Set up previous/next step references based on list order
+    for trolley in trolleys:
+        for i, step in enumerate(trolley.steps):
+            step.previous_step = trolley.steps[i - 1] if i > 0 else None
+            step.next_step = trolley.steps[i + 1] if i < len(trolley.steps) - 1 else None
+
+    # Handle score
+    score = None
+    if model.score:
+        score = HardSoftDecimalScore.parse(model.score)
+
+    # Handle solver status
+    solver_status = SolverStatus.NOT_SOLVING
+    if model.solver_status:
+        solver_status = SolverStatus[model.solver_status]
+
+    return domain.OrderPickingSolution(
+        trolleys=trolleys,
+        trolley_steps=trolley_steps,
+        score=score,
+        solver_status=solver_status
+    )

src/order_picking/demo_data.py

@@ -0,0 +1,258 @@
+from dataclasses import dataclass
+from enum import Enum
+from random import Random
+from typing import List
+
+from .domain import Product, Order, OrderItem, Trolley, TrolleyStep, OrderPickingSolution
+from .warehouse import WarehouseLocation, Side, Column, Row, new_shelving_id, Shelving
+
+
+# Configuration constants - matches Java timefold-quickstarts
+TROLLEYS_COUNT = 5
+BUCKET_COUNT = 4
+BUCKET_CAPACITY = 60 * 40 * 20  # 48000 cm3
+ORDERS_COUNT = 8
+ORDER_ITEMS_SIZE_MINIMUM = 1
+
+# Start location for all trolleys
+START_LOCATION = WarehouseLocation(
+    shelving_id=new_shelving_id(Column.COL_A, Row.ROW_1),
+    side=Side.LEFT,
+    row=0
+)
+
+
+class ProductFamily(Enum):
+    GENERAL_FOOD = "GENERAL_FOOD"
+    FRESH_FOOD = "FRESH_FOOD"
+    MEET_AND_FISH = "MEET_AND_FISH"
+    FROZEN_PRODUCTS = "FROZEN_PRODUCTS"
+    FRUITS_AND_VEGETABLES = "FRUITS_AND_VEGETABLES"
+    HOUSE_CLEANING = "HOUSE_CLEANING"
+    DRINKS = "DRINKS"
+    SNACKS = "SNACKS"
+    PETS = "PETS"
+
+
+@dataclass
+class ProductTemplate:
+    """Template for a product before location is assigned."""
+    id: str
+    name: str
+    volume: int  # in cm3
+    family: ProductFamily
+
+
+# Product templates without locations (locations are assigned randomly)
+PRODUCT_TEMPLATES: List[ProductTemplate] = [
+    # GENERAL_FOOD
+    ProductTemplate("0", "Kelloggs Cornflakes", 30 * 12 * 35, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("1", "Cream Crackers", 23 * 7 * 2, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("2", "Tea Bags 240 packet", 2 * 6 * 15, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("3", "Tomato Soup Can", 10 * 10 * 10, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("4", "Baked Beans in Tomato Sauce", 10 * 10 * 10, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("5", "Classic Mint Sauce", 8 * 10 * 8, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("6", "Raspberry Conserve", 8 * 10 * 8, ProductFamily.GENERAL_FOOD),
+    ProductTemplate("7", "Orange Fine Shred Marmalade", 7 * 8 * 7, ProductFamily.GENERAL_FOOD),
+
+    # FRESH_FOOD
+    ProductTemplate("8", "Free Range Eggs 6 Pack", 15 * 10 * 8, ProductFamily.FRESH_FOOD),
+    ProductTemplate("9", "Mature Cheddar 400G", 10 * 9 * 5, ProductFamily.FRESH_FOOD),
+    ProductTemplate("10", "Butter Packet", 12 * 5 * 5, ProductFamily.FRESH_FOOD),
+
+    # FRUITS_AND_VEGETABLES
+    ProductTemplate("11", "Iceberg Lettuce Each", 2500, ProductFamily.FRUITS_AND_VEGETABLES),
+    ProductTemplate("12", "Carrots 1Kg", 1000, ProductFamily.FRUITS_AND_VEGETABLES),
+    ProductTemplate("13", "Organic Fair Trade Bananas 5 Pack", 1800, ProductFamily.FRUITS_AND_VEGETABLES),
+    ProductTemplate("14", "Gala Apple Minimum 5 Pack", 25 * 20 * 10, ProductFamily.FRUITS_AND_VEGETABLES),
+    ProductTemplate("15", "Orange Bag 3kg", 29 * 20 * 15, ProductFamily.FRUITS_AND_VEGETABLES),
+
+    # HOUSE_CLEANING
+    ProductTemplate("16", "Fairy Non Biological Laundry Liquid 4.55L", 5000, ProductFamily.HOUSE_CLEANING),
+    ProductTemplate("17", "Toilet Tissue 8 Roll White", 50 * 20 * 20, ProductFamily.HOUSE_CLEANING),
+    ProductTemplate("18", "Kitchen Roll 200 Sheets x 2", 30 * 30 * 15, ProductFamily.HOUSE_CLEANING),
+    ProductTemplate("19", "Stainless Steel Cleaner 500Ml", 500, ProductFamily.HOUSE_CLEANING),
+    ProductTemplate("20", "Antibacterial Surface Spray", 12 * 4 * 25, ProductFamily.HOUSE_CLEANING),
+
+    # MEET_AND_FISH
+    ProductTemplate("21", "Beef Lean Steak Mince 500g", 500, ProductFamily.MEET_AND_FISH),
+    ProductTemplate("22", "Smoked Salmon 120G", 150, ProductFamily.MEET_AND_FISH),
+    ProductTemplate("23", "Steak Burgers 454G", 450, ProductFamily.MEET_AND_FISH),
+    ProductTemplate("24", "Pork Cooked Ham 125G", 125, ProductFamily.MEET_AND_FISH),
+    ProductTemplate("25", "Chicken Breast Fillets 300G", 300, ProductFamily.MEET_AND_FISH),
+
+    # DRINKS
+    ProductTemplate("26", "6 Milk Bricks Pack", 22 * 16 * 21, ProductFamily.DRINKS),
+    ProductTemplate("27", "Milk Brick", 1232, ProductFamily.DRINKS),
+    ProductTemplate("28", "Skimmed Milk 2.5L", 2500, ProductFamily.DRINKS),
+    ProductTemplate("29", "3L Orange Juice", 3 * 1000, ProductFamily.DRINKS),
+    ProductTemplate("30", "Alcohol Free Beer 4 Pack", 30 * 15 * 30, ProductFamily.DRINKS),
+    ProductTemplate("31", "Pepsi Regular Bottle", 1000, ProductFamily.DRINKS),
+    ProductTemplate("32", "Pepsi Diet 6 x 330ml", 35 * 12 * 12, ProductFamily.DRINKS),
+    ProductTemplate("33", "Schweppes Lemonade 2L", 2000, ProductFamily.DRINKS),
+    ProductTemplate("34", "Coke Zero 8 x 330ml", 40 * 12 * 12, ProductFamily.DRINKS),
+    ProductTemplate("35", "Natural Mineral Water Still 6 X 1.5Ltr", 6 * 1500, ProductFamily.DRINKS),
+
+    # SNACKS
+    ProductTemplate("36", "Cocktail Crisps 6 Pack", 20 * 10 * 10, ProductFamily.SNACKS),
+]
+
+# Shelving assignments per product family
+SHELVINGS_PER_FAMILY = {
+    ProductFamily.FRUITS_AND_VEGETABLES: [
+        new_shelving_id(Column.COL_A, Row.ROW_1),
+        new_shelving_id(Column.COL_A, Row.ROW_2),
+    ],
+    ProductFamily.FRESH_FOOD: [
+        new_shelving_id(Column.COL_A, Row.ROW_3),
+    ],
+    ProductFamily.MEET_AND_FISH: [
+        new_shelving_id(Column.COL_B, Row.ROW_2),
+        new_shelving_id(Column.COL_B, Row.ROW_3),
+    ],
+    ProductFamily.FROZEN_PRODUCTS: [
+        new_shelving_id(Column.COL_B, Row.ROW_2),
+        new_shelving_id(Column.COL_B, Row.ROW_1),
+    ],
+    ProductFamily.DRINKS: [
+        new_shelving_id(Column.COL_D, Row.ROW_1),
+    ],
+    ProductFamily.SNACKS: [
+        new_shelving_id(Column.COL_D, Row.ROW_2),
+    ],
+    ProductFamily.GENERAL_FOOD: [
+        new_shelving_id(Column.COL_B, Row.ROW_2),
+        new_shelving_id(Column.COL_C, Row.ROW_3),
+        new_shelving_id(Column.COL_D, Row.ROW_2),
+        new_shelving_id(Column.COL_D, Row.ROW_3),
+    ],
+    ProductFamily.HOUSE_CLEANING: [
+        new_shelving_id(Column.COL_E, Row.ROW_2),
+        new_shelving_id(Column.COL_E, Row.ROW_1),
+    ],
+    ProductFamily.PETS: [
+        new_shelving_id(Column.COL_E, Row.ROW_3),
+    ],
+}
+
+
+def get_max_product_size() -> int:
+    """Get the maximum product volume."""
+    return max(p.volume for p in PRODUCT_TEMPLATES)
+
+
+def validate_bucket_capacity(bucket_capacity: int) -> None:
+    """Ensure bucket capacity can hold the largest product."""
+    max_size = get_max_product_size()
+    if bucket_capacity < max_size:
+        raise ValueError(
+            f"The selected bucketCapacity: {bucket_capacity}, is lower than the "
+            f"maximum product size: {max_size}. Please use a higher value."
+        )
+
+
+def build_products(random: Random) -> List[Product]:
+    """Build products with random warehouse locations based on their family."""
+    products = []
+    for template in PRODUCT_TEMPLATES:
+        shelving_ids = SHELVINGS_PER_FAMILY[template.family]
+        shelving_id = random.choice(shelving_ids)
+        side = random.choice(list(Side))
+        row = random.randint(1, Shelving.ROWS_SIZE)
+
+        location = WarehouseLocation(
+            shelving_id=shelving_id,
+            side=side,
+            row=row
+        )
+        products.append(Product(
+            id=template.id,
+            name=template.name,
+            volume=template.volume,
+            location=location
+        ))
+    return products
+
+
+def build_trolleys(
+    count: int,
+    bucket_count: int,
+    bucket_capacity: int,
+    start_location: WarehouseLocation
+) -> List[Trolley]:
+    """Build trolleys at the start location."""
+    return [
+        Trolley(
+            id=str(i),
+            bucket_count=bucket_count,
+            bucket_capacity=bucket_capacity,
+            location=start_location
+        )
+        for i in range(1, count + 1)
+    ]
+
+
+def build_orders(count: int, products: List[Product], random: Random) -> List[Order]:
+    """Build orders with random products - matches Java implementation."""
+    orders = []
+    for order_num in range(1, count + 1):
+        # Java: ORDER_ITEMS_SIZE_MINIMUM + random.nextInt(products.size() - ORDER_ITEMS_SIZE_MINIMUM)
+        order_items_size = ORDER_ITEMS_SIZE_MINIMUM + random.randint(0, len(products) - ORDER_ITEMS_SIZE_MINIMUM - 1)
+
+        order_items = []
+        order_product_ids = set()
+        order = Order(id=str(order_num), items=order_items)
+
+        item_num = 1
+        for _ in range(order_items_size):
+            product_index = random.randint(0, len(products) - 1)
+            product = products[product_index]
+            # Avoid duplicate products in the same order
+            if product.id not in order_product_ids:
+                order_items.append(OrderItem(
+                    id=str(item_num),
+                    order=order,
+                    product=product
+                ))
+                order_product_ids.add(product.id)
+                item_num += 1
+
+        orders.append(order)
+    return orders
+
+
+def build_trolley_steps(orders: List[Order]) -> List[TrolleyStep]:
+    """Build trolley steps from order items."""
+    steps = []
+    for order in orders:
+        for idx, item in enumerate(order.items):
+            steps.append(TrolleyStep(
+                id=f"{order.id}-{idx}",
+                order_item=item
+            ))
+    return steps
+
+
+def generate_demo_data() -> OrderPickingSolution:
+    """Generate the complete demo data set."""
+    random = Random(37)  # Fixed seed for reproducibility
+
+    validate_bucket_capacity(BUCKET_CAPACITY)
+
+    products = build_products(random)
+    trolleys = build_trolleys(TROLLEYS_COUNT, BUCKET_COUNT, BUCKET_CAPACITY, START_LOCATION)
+    orders = build_orders(ORDERS_COUNT, products, random)
+    trolley_steps = build_trolley_steps(orders)
+
+    # Pre-assign steps evenly across trolleys so we have paths to visualize immediately
+    # The solver will optimize the distribution
+    if trolleys:
+        for i, step in enumerate(trolley_steps):
+            trolley = trolleys[i % len(trolleys)]
+            trolley.steps.append(step)
+            step.trolley = trolley
+
+    return OrderPickingSolution(
+        trolleys=trolleys,
+        trolley_steps=trolley_steps
+    )

src/order_picking/domain.py

@@ -0,0 +1,286 @@
+from dataclasses import dataclass, field
+from typing import Annotated, Optional, List, Union
+
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.score import HardSoftDecimalScore
+from solverforge_legacy.solver.domain import (
+    planning_entity,
+    planning_solution,
+    PlanningId,
+    PlanningScore,
+    PlanningListVariable,
+    PlanningEntityCollectionProperty,
+    ValueRangeProvider,
+    InverseRelationShadowVariable,
+    PreviousElementShadowVariable,
+    NextElementShadowVariable,
+    CascadingUpdateShadowVariable,
+)
+
+from .warehouse import WarehouseLocation, Side
+from .json_serialization import JsonDomainBase
+from pydantic import Field
+
+
+# =============================================================================
+# Domain Classes (used internally by solver - @dataclass for performance)
+# =============================================================================
+
+@dataclass
+class Product:
+    """A store product that can be included in an order."""
+    id: str
+    name: str
+    volume: int  # in cm3
+    location: WarehouseLocation
+
+
+@dataclass
+class Order:
+    """Represents an order submitted by a customer."""
+    id: str
+    items: list["OrderItem"] = field(default_factory=list)
+
+
+@dataclass
+class OrderItem:
+    """An indivisible product added to an order."""
+    id: str
+    order: Order
+    product: Product
+
+    @property
+    def volume(self) -> int:
+        return self.product.volume
+
+    @property
+    def order_id(self) -> str:
+        return self.order.id if self.order else None
+
+    @property
+    def location(self) -> WarehouseLocation:
+        return self.product.location
+
+
+@planning_entity
+@dataclass
+class TrolleyStep:
+    """
+    Represents a 'stop' in a Trolley's path where an order item is to be picked.
+
+    Shadow variables automatically track the trolley assignment and position in the list.
+    The distance_from_previous is a cascading shadow variable that precomputes distance.
+    """
+    id: Annotated[str, PlanningId]
+    order_item: OrderItem
+
+    # Shadow variables - automatically maintained by solver
+    trolley: Annotated[
+        Optional["Trolley"],
+        InverseRelationShadowVariable(source_variable_name="steps")
+    ] = None
+
+    previous_step: Annotated[
+        Optional["TrolleyStep"],
+        PreviousElementShadowVariable(source_variable_name="steps")
+    ] = None
+
+    next_step: Annotated[
+        Optional["TrolleyStep"],
+        NextElementShadowVariable(source_variable_name="steps")
+    ] = None
+
+    # Cascading shadow variable - precomputes distance from previous element
+    # This is updated automatically when the step is assigned/moved
+    distance_from_previous: Annotated[
+        Optional[int],
+        CascadingUpdateShadowVariable(target_method_name="update_distance_from_previous")
+    ] = None
+
+    def update_distance_from_previous(self):
+        """Called automatically by solver when step is assigned/moved."""
+        from .warehouse import calculate_distance
+        if self.trolley is None:
+            self.distance_from_previous = None
+        elif self.previous_step is None:
+            # First step - distance from trolley start
+            self.distance_from_previous = calculate_distance(
+                self.trolley.location, self.location
+            )
+        else:
+            # Distance from previous step
+            self.distance_from_previous = calculate_distance(
+                self.previous_step.location, self.location
+            )
+
+    @property
+    def location(self) -> WarehouseLocation:
+        return self.order_item.location
+
+    @property
+    def is_last(self) -> bool:
+        return self.next_step is None
+
+    @property
+    def trolley_id(self) -> Optional[str]:
+        return self.trolley.id if self.trolley else None
+
+    def __str__(self) -> str:
+        return f"TrolleyStep({self.id})"
+
+    def __repr__(self) -> str:
+        return f"TrolleyStep({self.id})"
+
+
+@planning_entity
+@dataclass
+class Trolley:
+    """
+    A trolley that will be filled with order items.
+
+    The steps list is the planning variable that the solver modifies.
+    """
+    id: Annotated[str, PlanningId]
+    bucket_count: int
+    bucket_capacity: int  # in cm3
+    location: WarehouseLocation
+
+    # Planning variable - solver assigns TrolleySteps to this list
+    steps: Annotated[list[TrolleyStep], PlanningListVariable] = field(default_factory=list)
+
+    def total_capacity(self) -> int:
+        """Total volume capacity of this trolley."""
+        return self.bucket_count * self.bucket_capacity
+
+    def calculate_total_volume(self) -> int:
+        """Sum of volumes of all items assigned to this trolley."""
+        return sum(step.order_item.volume for step in self.steps)
+
+    def calculate_excess_volume(self) -> int:
+        """Volume exceeding capacity (0 if within capacity)."""
+        excess = self.calculate_total_volume() - self.total_capacity()
+        return max(0, excess)
+
+    def calculate_required_buckets(self) -> int:
+        """
+        Calculate total buckets needed for all orders on this trolley.
+        Buckets are NOT shared between orders - each order needs its own buckets.
+        """
+        if len(self.steps) == 0:
+            return 0
+        # Group steps by order and calculate buckets per order
+        order_volumes: dict = {}
+        for step in self.steps:
+            order = step.order_item.order
+            order_volumes[order.id] = order_volumes.get(order.id, 0) + step.order_item.volume
+        # Sum up required buckets (ceiling division for each order)
+        total_buckets = 0
+        for volume in order_volumes.values():
+            total_buckets += (volume + self.bucket_capacity - 1) // self.bucket_capacity
+        return total_buckets
+
+    def calculate_excess_buckets(self) -> int:
+        """Buckets needed beyond capacity (0 if within capacity)."""
+        excess = self.calculate_required_buckets() - self.bucket_count
+        return max(0, excess)
+
+    def calculate_order_split_penalty(self) -> int:
+        """
+        Penalty for orders split across trolleys.
+        Returns 1000 per unique order on this trolley (will be summed across all trolleys).
+        """
+        if len(self.steps) == 0:
+            return 0
+        unique_orders = set(step.order_item.order.id for step in self.steps)
+        return len(unique_orders) * 1000
+
+    def calculate_total_distance(self) -> int:
+        """
+        Calculate total distance for this trolley's route.
+        Uses precomputed distance_from_previous shadow variable for speed.
+        """
+        if len(self.steps) == 0:
+            return 0
+        from .warehouse import calculate_distance
+        # Sum precomputed distances (already includes start -> first step)
+        total = 0
+        for step in self.steps:
+            if step.distance_from_previous is not None:
+                total += step.distance_from_previous
+        # Add return trip from last step to origin
+        last_step = self.steps[-1]
+        total += calculate_distance(last_step.location, self.location)
+        return total
+
+    def __str__(self) -> str:
+        return f"Trolley({self.id})"
+
+    def __repr__(self) -> str:
+        return f"Trolley({self.id})"
+
+
+@planning_solution
+@dataclass
+class OrderPickingSolution:
+    """The planning solution containing trolleys and steps to be optimized."""
+
+    trolleys: Annotated[list[Trolley], PlanningEntityCollectionProperty]
+
+    trolley_steps: Annotated[
+        list[TrolleyStep],
+        PlanningEntityCollectionProperty,
+        ValueRangeProvider
+    ]
+
+    score: Annotated[Optional[HardSoftDecimalScore], PlanningScore] = None
+    solver_status: SolverStatus = SolverStatus.NOT_SOLVING
+
+
+# =============================================================================
+# Pydantic API Models (for REST serialization only)
+# =============================================================================
+
+class WarehouseLocationModel(JsonDomainBase):
+    shelving_id: str = Field(..., alias="shelvingId")
+    side: str
+    row: int
+
+
+class ProductModel(JsonDomainBase):
+    id: str
+    name: str
+    volume: int
+    location: WarehouseLocationModel
+
+
+class OrderItemModel(JsonDomainBase):
+    id: str
+    order_id: Optional[str] = Field(None, alias="orderId")
+    product: ProductModel
+
+
+class OrderModel(JsonDomainBase):
+    id: str
+    items: List[OrderItemModel] = Field(default_factory=list)
+
+
+class TrolleyStepModel(JsonDomainBase):
+    id: str
+    order_item: OrderItemModel = Field(..., alias="orderItem")
+    trolley: Optional[Union[str, "TrolleyModel"]] = None
+    trolley_id: Optional[str] = Field(None, alias="trolleyId")
+
+
+class TrolleyModel(JsonDomainBase):
+    id: str
+    bucket_count: int = Field(..., alias="bucketCount")
+    bucket_capacity: int = Field(..., alias="bucketCapacity")
+    location: WarehouseLocationModel
+    steps: List[Union[str, TrolleyStepModel]] = Field(default_factory=list)
+
+
+class OrderPickingSolutionModel(JsonDomainBase):
+    trolleys: List[TrolleyModel]
+    trolley_steps: List[TrolleyStepModel] = Field(..., alias="trolleySteps")
+    score: Optional[str] = None
+    solver_status: Optional[str] = Field(None, alias="solverStatus")

src/order_picking/json_serialization.py

@@ -0,0 +1,47 @@
+from solverforge_legacy.solver.score import HardSoftDecimalScore
+
+from typing import Any
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    PlainSerializer,
+    BeforeValidator,
+    ValidationInfo,
+)
+from pydantic.alias_generators import to_camel
+
+
+class JsonDomainBase(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+        serialize_by_alias=True,  # Output camelCase in JSON responses
+    )
+
+
+ScoreSerializer = PlainSerializer(
+    lambda score: str(score) if score is not None else None,
+    return_type=str | None
+)
+
+IdSerializer = PlainSerializer(
+    lambda item: item.id if item is not None else None,
+    return_type=str | None
+)
+
+IdListSerializer = PlainSerializer(
+    lambda items: [item.id for item in items],
+    return_type=list
+)
+
+
+def validate_score(v: Any, info: ValidationInfo) -> Any:
+    if isinstance(v, HardSoftDecimalScore) or v is None:
+        return v
+    if isinstance(v, str):
+        return HardSoftDecimalScore.parse(v)
+    raise ValueError('"score" should be a string')
+
+
+ScoreValidator = BeforeValidator(validate_score)

src/order_picking/rest_api.py

@@ -0,0 +1,289 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.staticfiles import StaticFiles
+from uuid import uuid4
+from typing import Dict, List, Any
+from dataclasses import dataclass, asdict
+from threading import Lock, Event
+import re
+import copy
+
+from pydantic import BaseModel, Field as PydanticField
+from random import Random
+
+from .domain import OrderPickingSolution, OrderPickingSolutionModel
+from .converters import solution_to_model, model_to_solution
+from .demo_data import (
+    generate_demo_data, build_products, build_trolleys, build_orders,
+    build_trolley_steps, validate_bucket_capacity, START_LOCATION, BUCKET_CAPACITY
+)
+from .solver import solver_manager, solution_manager
+from .warehouse import calculate_distance_to_travel
+
+
+app = FastAPI(docs_url='/q/swagger-ui')
+
+# =============================================================================
+# Thread-safe solution caching
+# =============================================================================
+# The solver runs in a Java thread (via JPype) and calls Python callbacks.
+# We snapshot solution data IMMEDIATELY in the callback (while solver paused)
+# and store the immutable snapshot. API handlers read from this cache.
+
+# Thread-safe cache: stores SNAPSHOTS as dicts (immutable after creation)
+cached_solutions: Dict[str, Dict[str, Any]] = {}
+cached_distances: Dict[str, Dict[str, int]] = {}
+cache_lock = Lock()
+
+# Events to signal when first solution is ready
+first_solution_events: Dict[str, Event] = {}
+
+# Domain objects for score analysis
+data_sets: Dict[str, OrderPickingSolution] = {}
+
+
+@dataclass
+class MatchAnalysisDTO:
+    name: str
+    score: str
+    justification: str
+
+
+@dataclass
+class ConstraintAnalysisDTO:
+    name: str
+    weight: str
+    score: str
+    matches: List[MatchAnalysisDTO]
+
+
+class DemoConfigModel(BaseModel):
+    """Configuration for generating custom demo data."""
+    orders_count: int = PydanticField(default=40, ge=5, le=100, alias="ordersCount")
+    trolleys_count: int = PydanticField(default=8, ge=2, le=15, alias="trolleysCount")
+    bucket_count: int = PydanticField(default=6, ge=2, le=10, alias="bucketCount")
+
+    model_config = {"populate_by_name": True}
+
+
+@app.get("/demo-data")
+async def get_demo_data_list() -> List[str]:
+    """Get available demo data sets."""
+    return ["DEFAULT"]
+
+
+@app.get("/demo-data/{demo_name}", response_model=OrderPickingSolutionModel)
+async def get_demo_data_by_name(demo_name: str) -> OrderPickingSolutionModel:
+    """Get a specific demo data set."""
+    if demo_name != "DEFAULT":
+        raise HTTPException(status_code=404, detail=f"Demo data '{demo_name}' not found")
+    domain_solution = generate_demo_data()
+    return solution_to_model(domain_solution)
+
+
+@app.post("/demo-data/generate", response_model=OrderPickingSolutionModel)
+async def generate_custom_demo(config: DemoConfigModel) -> OrderPickingSolutionModel:
+    """Generate demo data with custom configuration."""
+    random = Random(37)  # Fixed seed for reproducibility
+
+    validate_bucket_capacity(BUCKET_CAPACITY)
+
+    products = build_products(random)
+    trolleys = build_trolleys(
+        config.trolleys_count,
+        config.bucket_count,
+        BUCKET_CAPACITY,
+        START_LOCATION
+    )
+    orders = build_orders(config.orders_count, products, random)
+    trolley_steps = build_trolley_steps(orders)
+
+    # Pre-assign steps evenly across trolleys so we have paths to visualize immediately
+    if trolleys:
+        for i, step in enumerate(trolley_steps):
+            trolley = trolleys[i % len(trolleys)]
+            trolley.steps.append(step)
+            step.trolley = trolley
+
+    domain_solution = OrderPickingSolution(
+        trolleys=trolleys,
+        trolley_steps=trolley_steps
+    )
+    return solution_to_model(domain_solution)
+
+
+def update_solution(job_id: str, solution: OrderPickingSolution):
+    """
+    Update solution cache. Called by solver callback from Java thread.
+
+    CRITICAL: We snapshot ALL data IMMEDIATELY in the callback while the solver
+    is paused. This prevents race conditions where the Java solver modifies
+    domain objects while we're reading them.
+    """
+    # Snapshot step assignments for each trolley FIRST (before any iteration)
+    trolley_snapshots = []
+    for t in solution.trolleys:
+        # Copy the steps list immediately - this is the critical snapshot
+        step_ids = [s.id for s in t.steps]
+        trolley_snapshots.append((t.id, len(step_ids), step_ids))
+
+    # Log for debugging
+    step_counts = [f"T{tid}:{count}" for tid, count, _ in trolley_snapshots]
+    print(f"[CALLBACK] job={job_id} score={solution.score} steps=[{' '.join(step_counts)}]")
+
+    # Now convert to API model (uses the same solution state we just logged)
+    api_model = solution_to_model(solution)
+    solution_dict = api_model.model_dump(by_alias=True)
+
+    # Calculate distances
+    distances = {}
+    for trolley in solution.trolleys:
+        distances[trolley.id] = calculate_distance_to_travel(trolley)
+
+    # Update cache atomically
+    with cache_lock:
+        cached_solutions[job_id] = solution_dict
+        cached_distances[job_id] = distances
+
+    # Signal that first solution is ready
+    if job_id in first_solution_events:
+        first_solution_events[job_id].set()
+
+    # Keep domain object reference for score analysis
+    data_sets[job_id] = solution
+
+
+@app.post("/schedules")
+async def solve(solution_model: OrderPickingSolutionModel) -> str:
+    """Submit a problem to solve. Returns job ID."""
+    job_id = str(uuid4())
+    domain_solution = model_to_solution(solution_model)
+
+    data_sets[job_id] = domain_solution
+
+    # Initialize cache with empty state - will be updated by callbacks
+    with cache_lock:
+        cached_solutions[job_id] = solution_to_model(domain_solution).model_dump(by_alias=True)
+        cached_distances[job_id] = {}
+
+    # Start solver - callbacks update cache when construction completes and on improvements
+    (solver_manager.solve_builder()
+        .with_problem_id(job_id)
+        .with_problem(domain_solution)
+        .with_first_initialized_solution_consumer(lambda solution: update_solution(job_id, solution))
+        .with_best_solution_consumer(lambda solution: update_solution(job_id, solution))
+        .run())
+
+    return job_id
+
+
+@app.get("/schedules/{problem_id}")
+async def get_solution(problem_id: str) -> Dict[str, Any]:
+    """Get the current solution for a given job ID."""
+    solver_status = solver_manager.get_solver_status(problem_id)
+
+    # Read from thread-safe cache (populated by solver callbacks)
+    with cache_lock:
+        cached = cached_solutions.get(problem_id)
+
+    if not cached:
+        raise HTTPException(status_code=404, detail="Solution not found")
+
+    # Return cached solution with current status
+    result = dict(cached)
+    result["solverStatus"] = solver_status.name if solver_status else None
+
+    return result
+
+
+@app.get("/schedules/{problem_id}/status")
+async def get_status(problem_id: str) -> dict:
+    """Get the solution status, score, and distances for a given job ID."""
+    # Read from thread-safe cache
+    with cache_lock:
+        cached = cached_solutions.get(problem_id)
+        distances = cached_distances.get(problem_id, {})
+
+    if not cached:
+        raise HTTPException(status_code=404, detail="Solution not found")
+
+    solver_status = solver_manager.get_solver_status(problem_id)
+
+    # Parse score from cached solution
+    score_str = cached.get("score", "")
+    hard_score = 0
+    soft_score = 0
+    if score_str:
+        # Parse score like "0hard/-12345soft"
+        match = re.match(r"(-?\d+)hard/(-?\d+)soft", str(score_str))
+        if match:
+            hard_score = int(match.group(1))
+            soft_score = int(match.group(2))
+
+    return {
+        "score": {
+            "hardScore": hard_score,
+            "softScore": soft_score,
+        },
+        "solverStatus": solver_status.name if solver_status else None,
+        "distances": distances,
+    }
+
+
+@app.delete("/schedules/{problem_id}")
+async def stop_solving(problem_id: str) -> Dict[str, Any]:
+    """Terminate solving for a given job ID. Returns the best solution so far."""
+    solver_manager.terminate_early(problem_id)
+
+    # Read from thread-safe cache
+    with cache_lock:
+        cached = cached_solutions.get(problem_id)
+        if not cached:
+            raise HTTPException(status_code=404, detail="Solution not found")
+        result = dict(cached)
+
+    solver_status = solver_manager.get_solver_status(problem_id)
+    result["solverStatus"] = solver_status.name if solver_status else None
+
+    return result
+
+
+@app.get("/schedules/{problem_id}/score-analysis")
+async def analyze_score(problem_id: str) -> dict:
+    """Get score analysis for current solution."""
+    import asyncio
+    from concurrent.futures import ThreadPoolExecutor
+
+    solution = data_sets.get(problem_id)
+    if not solution:
+        raise HTTPException(status_code=404, detail="Solution not found")
+
+    # Run blocking JPype call in thread pool to not block async event loop
+    loop = asyncio.get_event_loop()
+    with ThreadPoolExecutor() as pool:
+        analysis = await loop.run_in_executor(pool, solution_manager.analyze, solution)
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            MatchAnalysisDTO(
+                name=str(getattr(getattr(match, 'constraint_ref', None), 'constraint_name', "")),
+                score=str(getattr(match, 'score', "0hard/0soft")),
+                justification=str(getattr(match, 'justification', ""))
+            )
+            for match in getattr(constraint, 'matches', []) or []
+        ]
+        constraints.append(ConstraintAnalysisDTO(
+            name=str(getattr(constraint, 'constraint_name', "")),
+            weight=str(getattr(constraint, 'weight', "0hard/0soft")),
+            score=str(getattr(constraint, 'score', "0hard/0soft")),
+            matches=matches
+        ))
+    return {"constraints": [asdict(constraint) for constraint in constraints]}
+
+
+@app.get("/schedules")
+async def list_solutions() -> List[str]:
+    """List the job IDs of all submitted solutions."""
+    return list(data_sets.keys())
+
+
+app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/order_picking/solver.py

@@ -0,0 +1,23 @@
+from solverforge_legacy.solver import SolverManager, SolutionManager
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import Trolley, TrolleyStep, OrderPickingSolution
+from .constraints import define_constraints
+
+
+solver_config = SolverConfig(
+    solution_class=OrderPickingSolution,
+    entity_class_list=[Trolley, TrolleyStep],
+    score_director_factory_config=ScoreDirectorFactoryConfig(
+        constraint_provider_function=define_constraints
+    ),
+    termination_config=TerminationConfig(spent_limit=Duration(minutes=10)),
+)
+
+solver_manager = SolverManager.create(solver_config)
+solution_manager = SolutionManager.create(solver_manager)

src/order_picking/warehouse.py

@@ -0,0 +1,165 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from .domain import Trolley
+
+
+class Side(Enum):
+    """Available shelving sides where products can be located."""
+    LEFT = "LEFT"
+    RIGHT = "RIGHT"
+
+
+class Column(Enum):
+    """Defines the warehouse columns."""
+    COL_A = 'A'
+    COL_B = 'B'
+    COL_C = 'C'
+    COL_D = 'D'
+    COL_E = 'E'
+
+
+class Row(Enum):
+    """Defines the warehouse rows."""
+    ROW_1 = 1
+    ROW_2 = 2
+    ROW_3 = 3
+
+
+@dataclass
+class Shelving:
+    """
+    Represents a products container. Each shelving has two sides where
+    products can be stored, and a number of rows.
+    """
+    id: str
+    x: int  # Absolute x position of shelving's left bottom corner
+    y: int  # Absolute y position of shelving's left bottom corner
+
+    ROWS_SIZE: ClassVar[int] = 10
+
+
+@dataclass
+class WarehouseLocation:
+    """
+    Represents a location in the warehouse where a product can be stored.
+    """
+    shelving_id: str
+    side: Side
+    row: int
+
+    def __str__(self) -> str:
+        return f"WarehouseLocation(shelving={self.shelving_id}, side={self.side.name}, row={self.row})"
+
+
+def new_shelving_id(column: Column, row: Row) -> str:
+    """Create a shelving ID from column and row."""
+    return f"({column.value},{row.value})"
+
+
+# Warehouse constants
+SHELVING_WIDTH = 2   # meters
+SHELVING_HEIGHT = 10  # meters
+SHELVING_PADDING = 3  # spacing between shelvings in meters
+
+# Initialize static shelving map
+SHELVING_MAP: dict[str, Shelving] = {}
+
+def _init_shelving_map():
+    """Initialize the warehouse shelving grid."""
+    shelving_x = 0
+    for col in Column:
+        shelving_y = 0
+        for row in Row:
+            shelving_id = new_shelving_id(col, row)
+            SHELVING_MAP[shelving_id] = Shelving(
+                id=shelving_id,
+                x=shelving_x,
+                y=shelving_y
+            )
+            shelving_y += SHELVING_HEIGHT + SHELVING_PADDING
+        shelving_x += SHELVING_WIDTH + SHELVING_PADDING
+
+_init_shelving_map()
+
+
+def get_absolute_x(shelving: Shelving, location: WarehouseLocation) -> int:
+    """Calculate absolute X position of a location."""
+    if location.side == Side.LEFT:
+        return shelving.x
+    else:
+        return shelving.x + SHELVING_WIDTH
+
+
+def get_absolute_y(shelving: Shelving, location: WarehouseLocation) -> int:
+    """Calculate absolute Y position of a location."""
+    return shelving.y + location.row
+
+
+def calculate_best_y_distance_in_shelving_row(start_row: int, end_row: int) -> int:
+    """Calculate the best Y distance when crossing a shelving."""
+    north_direction = start_row + end_row
+    south_direction = (SHELVING_HEIGHT - start_row) + (SHELVING_HEIGHT - end_row)
+    return min(north_direction, south_direction)
+
+
+def calculate_distance(start: WarehouseLocation, end: WarehouseLocation) -> int:
+    """
+    Calculate distance in meters between two locations considering warehouse structure.
+    """
+    start_shelving = SHELVING_MAP.get(start.shelving_id)
+    if start_shelving is None:
+        raise IndexError(f"Shelving: {start.shelving_id} was not found in current Warehouse structure.")
+
+    end_shelving = SHELVING_MAP.get(end.shelving_id)
+    if end_shelving is None:
+        raise IndexError(f"Shelving: {end.shelving_id} was not found in current Warehouse structure.")
+
+    delta_x = 0
+
+    start_x = get_absolute_x(start_shelving, start)
+    start_y = get_absolute_y(start_shelving, start)
+    end_x = get_absolute_x(end_shelving, end)
+    end_y = get_absolute_y(end_shelving, end)
+
+    if start_shelving == end_shelving:
+        # Same shelving
+        if start.side == end.side:
+            # Same side - just vertical distance
+            delta_y = abs(start_y - end_y)
+        else:
+            # Different side - calculate shortest walk around
+            delta_x = SHELVING_WIDTH
+            delta_y = calculate_best_y_distance_in_shelving_row(start.row, end.row)
+    elif start_shelving.y == end_shelving.y:
+        # Different shelvings but on same warehouse row
+        if abs(start_x - end_x) == SHELVING_PADDING:
+            # Neighbor shelvings with contiguous sides
+            delta_x = SHELVING_PADDING
+            delta_y = abs(start_y - end_y)
+        else:
+            # Other combinations in same warehouse row
+            delta_x = abs(start_x - end_x)
+            delta_y = calculate_best_y_distance_in_shelving_row(start.row, end.row)
+    else:
+        # Shelvings on different warehouse rows
+        delta_x = abs(start_x - end_x)
+        delta_y = abs(start_y - end_y)
+
+    return delta_x + delta_y
+
+
+def calculate_distance_to_travel(trolley: "Trolley") -> int:
+    """Calculate total distance a trolley needs to travel through its steps."""
+    distance = 0
+    previous_location = trolley.location
+
+    for step in trolley.steps:
+        distance += calculate_distance(previous_location, step.location)
+        previous_location = step.location
+
+    # Return trip to origin
+    distance += calculate_distance(previous_location, trolley.location)
+    return distance

static/app.js

@@ -0,0 +1,653 @@
+/**
+ * Order Picking Optimization - Frontend Application
+ *
+ * This application demonstrates real-time constraint optimization for warehouse
+ * order picking. It uses SolverForge (a constraint solver) to optimize which
+ * trolley picks which items and in what order, minimizing total travel distance
+ * while respecting capacity constraints.
+ *
+ * Architecture:
+ * - Backend: FastAPI server with SolverForge solver
+ * - Frontend: jQuery + Canvas for visualization
+ * - Communication: REST API with 250ms polling for real-time updates
+ *
+ * Key concepts:
+ * - Planning entities: TrolleySteps (items to pick)
+ * - Planning variable: Which trolley picks each step
+ * - Constraints: Bucket capacity (hard), minimize distance (soft)
+ */
+
+// =============================================================================
+// Application State
+// =============================================================================
+
+/** Current solution data from the solver */
+let loadedSchedule = null;
+
+/** Active problem ID when solving (null when not solving) */
+let currentProblemId = null;
+
+/** Interval ID for polling updates during solving */
+let autoRefreshIntervalId = null;
+
+/** Last score string for detecting improvements */
+let lastScore = null;
+
+/** Cached distances per trolley (Map<trolleyId, distance>) */
+let distances = new Map();
+
+/** Tracks user intent to solve (prevents race condition with solver startup) */
+let userRequestedSolving = false;
+
+// =============================================================================
+// Initialization
+// =============================================================================
+
+/**
+ * Initialize the application when the DOM is ready.
+ * Sets up event handlers and loads initial demo data.
+ */
+$(document).ready(function() {
+    // Add SolverForge header and footer branding
+    replaceQuickstartSolverForgeAutoHeaderFooter();
+
+    // Initialize the isometric 3D warehouse canvas
+    initWarehouseCanvas();
+
+    // Load default demo data to show something immediately
+    loadDemoData();
+
+    // Wire up button click handlers
+    $("#solveButton").click(solve);
+    $("#stopSolvingButton").click(stopSolving);
+    $("#analyzeButton").click(analyze);
+    $("#generateButton").click(generateNewData);
+
+    // Update displayed values when sliders change
+    $("#ordersCountSlider").on("input", function() {
+        $("#ordersCountValue").text($(this).val());
+    });
+    $("#trolleysCountSlider").on("input", function() {
+        $("#trolleysCountValue").text($(this).val());
+    });
+    $("#bucketsCountSlider").on("input", function() {
+        $("#bucketsCountValue").text($(this).val());
+    });
+
+    // Redraw warehouse on window resize
+    window.addEventListener('resize', () => {
+        initWarehouseCanvas();
+        if (loadedSchedule) {
+            renderWarehouse(loadedSchedule);
+        }
+    });
+});
+
+// =============================================================================
+// Data Loading
+// =============================================================================
+
+/**
+ * Load the default demo dataset from the server.
+ * This provides a starting point with pre-configured orders and trolleys.
+ */
+function loadDemoData() {
+    fetch('/demo-data/DEFAULT')
+        .then(r => r.json())
+        .then(solution => {
+            loadedSchedule = solution;
+            currentProblemId = null;
+            updateUI(solution, false);
+        })
+        .catch(error => {
+            showError("Failed to load demo data", error);
+        });
+}
+
+/**
+ * Generate new random demo data based on slider settings.
+ * Allows testing with different problem sizes.
+ */
+function generateNewData() {
+    // Read configuration from UI sliders
+    const config = {
+        ordersCount: parseInt($("#ordersCountSlider").val()),
+        trolleysCount: parseInt($("#trolleysCountSlider").val()),
+        bucketCount: parseInt($("#bucketsCountSlider").val())
+    };
+
+    // Show loading state
+    const btn = $("#generateButton");
+    btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i> Generating...');
+
+    fetch('/demo-data/generate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(config)
+    })
+    .then(r => {
+        if (!r.ok) {
+            return r.text().then(text => {
+                throw new Error(`Server error ${r.status}: ${text}`);
+            });
+        }
+        return r.json();
+    })
+    .then(solution => {
+        loadedSchedule = solution;
+        currentProblemId = null;
+        distances.clear();
+        updateUI(solution, false);
+        $("#settingsPanel").collapse('hide');
+        showSuccess(`Generated ${config.ordersCount} orders with ${config.trolleysCount} trolleys`);
+    })
+    .catch(error => {
+        console.error("Generate error:", error);
+        showError("Failed to generate data: " + error.message, error);
+    })
+    .finally(() => {
+        btn.prop('disabled', false).html('<i class="fas fa-sync-alt"></i> Generate New');
+    });
+}
+
+// =============================================================================
+// Solving - Start/Stop Optimization
+// =============================================================================
+
+/**
+ * Start the optimization solver.
+ *
+ * Flow:
+ * 1. POST current schedule to /schedules to start solving
+ * 2. Server returns a problemId for tracking
+ * 3. Start polling every 250ms for solution updates
+ * 4. Update UI in real-time as solver finds better solutions
+ */
+function solve() {
+    lastScore = null;
+    userRequestedSolving = true;
+
+    // Show solving state immediately for user feedback
+    setSolving(true);
+
+    // Submit the problem to the solver
+    fetch('/schedules', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(loadedSchedule)
+    })
+    .then(r => r.text())
+    .then(problemId => {
+        // Store problem ID for subsequent API calls
+        currentProblemId = problemId.replace(/"/g, '');
+
+        // Start animation from first poll response, not stale loadedSchedule
+        ISO.isSolving = true;
+
+        // Poll for updates every 250ms for smooth real-time visualization
+        autoRefreshIntervalId = setInterval(refreshSchedule, 250);
+
+        // Trigger immediate first poll to get real data ASAP
+        refreshSchedule();
+    })
+    .catch(error => {
+        showError("Failed to start solving", error);
+        setSolving(false);
+        stopWarehouseAnimation();
+    });
+}
+
+/**
+ * Stop the optimization solver early.
+ * Returns the best solution found so far.
+ */
+function stopSolving() {
+    if (!currentProblemId) return;
+    userRequestedSolving = false;
+
+    // Stop polling immediately
+    if (autoRefreshIntervalId) {
+        clearInterval(autoRefreshIntervalId);
+        autoRefreshIntervalId = null;
+    }
+
+    // Update UI immediately - don't wait for server
+    setSolving(false);
+    stopWarehouseAnimation();
+
+    // Tell the server to terminate solving
+    fetch(`/schedules/${currentProblemId}`, { method: 'DELETE' })
+        .then(r => r.ok ? r.json() : Promise.reject(`HTTP ${r.status}`))
+        .then(solution => {
+            loadedSchedule = solution;
+            updateUI(solution, false);
+        })
+        .catch(error => showError("Failed to stop solving", error));
+}
+
+// =============================================================================
+// Real-Time Polling
+// =============================================================================
+
+/**
+ * Fetch the latest solution and status from the server.
+ * Called every 250ms during solving to provide real-time updates.
+ *
+ * Why polling instead of WebSockets/SSE?
+ * - Simpler implementation and debugging
+ * - Works reliably across all environments
+ * - 250ms is fast enough for smooth visualization
+ * - Proven pattern used across SolverForge quickstarts
+ */
+function refreshSchedule() {
+    if (!currentProblemId) return;
+    if (!userRequestedSolving) return;  // Don't process if user stopped
+
+    // Fetch solution and status in parallel for efficiency
+    Promise.all([
+        fetch(`/schedules/${currentProblemId}`).then(r => r.json()),
+        fetch(`/schedules/${currentProblemId}/status`).then(r => r.json())
+    ])
+    .then(([solution, status]) => {
+        // Double-check user hasn't stopped while fetch was in-flight
+        if (!userRequestedSolving) return;
+
+        // CRITICAL: Sync animation state IMMEDIATELY before any rendering
+        // This prevents race conditions where animation loop uses stale data
+        if (typeof ISO !== 'undefined') {
+            ISO.currentSolution = solution;
+        }
+
+        // Update distance cache from status response
+        distances = new Map(Object.entries(status.distances || {}));
+
+        // Detect score improvements and trigger visual feedback
+        const newScoreStr = `${status.score.hardScore}hard/${status.score.softScore}soft`;
+        if (lastScore && newScoreStr !== lastScore) {
+            flashScoreImprovement();
+        }
+        lastScore = newScoreStr;
+
+        // Update application state
+        loadedSchedule = solution;
+        const isSolving = status.solverStatus !== 'NOT_SOLVING' && status.solverStatus != null;
+        updateUI(solution, isSolving);
+
+        // Update animation paths when solution changes
+        if (userRequestedSolving) {
+            if (ISO.trolleyAnimations.size === 0) {
+                startWarehouseAnimation(solution);
+            }
+            updateWarehouseAnimation(solution);
+        }
+
+        // Auto-stop polling when solver finishes (with valid score) or user stopped
+        const solverSaysNotSolving = status.solverStatus === 'NOT_SOLVING';
+        const solverActuallyFinished = solverSaysNotSolving && solution.score !== null;
+        const shouldStop = !userRequestedSolving || solverActuallyFinished;
+
+        if (shouldStop) {
+            if (autoRefreshIntervalId) {
+                clearInterval(autoRefreshIntervalId);
+                autoRefreshIntervalId = null;
+            }
+            userRequestedSolving = false;
+            setSolving(false);
+            stopWarehouseAnimation();
+        }
+    })
+    .catch(error => {
+        console.error("Refresh error:", error);
+    });
+}
+
+// =============================================================================
+// UI Updates
+// =============================================================================
+
+/**
+ * Update all UI components with the current solution state.
+ *
+ * @param {Object} solution - The current solution from the solver
+ * @param {boolean} solving - Whether the solver is currently running
+ */
+function updateUI(solution, solving) {
+    updateScore(solution);
+    updateStats(solution);
+    updateLegend(solution, distances);
+    updateTrolleyCards(solution);
+    renderWarehouse(solution);
+    setSolving(solving && solution.solverStatus !== 'NOT_SOLVING');
+}
+
+/**
+ * Update the score display.
+ * Score format: "{hardScore}hard/{softScore}soft"
+ * - Hard score: Constraint violations (must be 0 for valid solution)
+ * - Soft score: Optimization objective (minimize distance)
+ */
+function updateScore(solution) {
+    const score = solution.score;
+    if (!score) {
+        $("#score").text("?");
+    } else if (typeof score === 'string') {
+        $("#score").text(score);
+    } else {
+        $("#score").text(`${score.hardScore}hard/${score.softScore}soft`);
+    }
+}
+
+/**
+ * Update statistics cards showing problem metrics.
+ * Calculates totals from the solution data structure.
+ */
+function updateStats(solution) {
+    const orderIds = new Set();
+    let totalItems = 0;
+    let activeTrolleys = 0;
+    let totalDistance = 0;
+
+    // Build lookup for resolving step references
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    // Aggregate statistics from all trolleys
+    for (const trolley of solution.trolleys || []) {
+        // Resolve step references (may be IDs or objects)
+        const steps = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? stepLookup.get(ref) : ref
+        ).filter(s => s);
+
+        if (steps.length > 0) {
+            activeTrolleys++;
+            totalItems += steps.length;
+
+            // Track unique orders
+            for (const step of steps) {
+                if (step.orderItem) {
+                    orderIds.add(step.orderItem.orderId);
+                }
+            }
+        }
+
+        // Sum distances from cache
+        const dist = distances.get(trolley.id) || 0;
+        totalDistance += dist;
+    }
+
+    // Update UI with animations
+    animateValue("#totalOrders", orderIds.size);
+    animateValue("#totalItems", totalItems);
+    animateValue("#activeTrolleys", activeTrolleys);
+    animateValue("#totalDistance", Math.round(totalDistance / 100)); // cm -> m
+}
+
+/**
+ * Animate a value change with a brief highlight effect.
+ */
+function animateValue(selector, newValue) {
+    const el = $(selector);
+    const oldValue = parseInt(el.text()) || 0;
+    if (oldValue !== newValue) {
+        el.text(newValue);
+        el.addClass('value-changed');
+        setTimeout(() => el.removeClass('value-changed'), 500);
+    }
+}
+
+/**
+ * Render the trolley assignment cards showing items per trolley.
+ * Updates in place to avoid flicker.
+ */
+function updateTrolleyCards(solution) {
+    const container = $("#trolleyCardsContainer");
+
+    // Build step lookup for reference resolution
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    const trolleys = solution.trolleys || [];
+
+    // Create cards if needed (first time or count changed)
+    if (container.children().length !== trolleys.length) {
+        container.empty();
+        for (const trolley of trolleys) {
+            const color = getTrolleyColor(trolley.id);
+            const card = $(`
+                <div class="trolley-card" data-trolley-id="${trolley.id}">
+                    <div class="trolley-card-header">
+                        <div class="trolley-color-badge" style="background: ${color}"></div>
+                        <div class="trolley-card-info">
+                            <div class="trolley-card-title">Trolley ${trolley.id}</div>
+                            <div class="trolley-card-stats"></div>
+                        </div>
+                        <div class="trolley-capacity-bar">
+                            <div class="trolley-capacity-fill"></div>
+                        </div>
+                    </div>
+                    <div class="trolley-card-body"></div>
+                </div>
+            `);
+            container.append(card);
+        }
+    }
+
+    // Update each card in place
+    for (const trolley of trolleys) {
+        const card = container.find(`[data-trolley-id="${trolley.id}"]`);
+        if (!card.length) continue;
+
+        const steps = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? stepLookup.get(ref) : ref
+        ).filter(s => s);
+
+        const itemCount = steps.length;
+
+        // Calculate capacity
+        let totalVolume = 0;
+        const bucketCapacity = 50000;
+        const bucketCount = trolley.bucketCount || 6;
+        const maxCapacity = bucketCapacity * bucketCount;
+        for (const step of steps) {
+            if (step.orderItem?.product?.volume) {
+                totalVolume += step.orderItem.product.volume;
+            }
+        }
+        const capacityPercent = Math.min(100, Math.round((totalVolume / maxCapacity) * 100));
+        const capacityClass = capacityPercent > 90 ? 'high' : capacityPercent > 70 ? 'medium' : 'low';
+
+        // Update stats
+        card.find('.trolley-card-stats').text(`${itemCount} items`);
+
+        // Update capacity bar
+        const fill = card.find('.trolley-capacity-fill');
+        fill.css('width', `${capacityPercent}%`);
+        fill.removeClass('low medium high').addClass(capacityClass);
+
+        // Update items list
+        const body = card.find('.trolley-card-body');
+        if (itemCount > 0) {
+            body.html(`
+                <div class="trolley-items-list">
+                    ${steps.map((step, i) => `
+                        <div class="trolley-item">
+                            <span class="trolley-item-number">${i + 1}</span>
+                            ${step.orderItem?.product?.name?.substring(0, 15) || 'Item'}
+                        </div>
+                    `).join('')}
+                </div>
+            `);
+        } else {
+            body.html('<div class="trolley-empty">No items assigned</div>');
+        }
+    }
+}
+
+/**
+ * Update UI to reflect solving/not-solving state.
+ */
+function setSolving(solving) {
+    if (solving) {
+        $("#solveButton").hide();
+        $("#stopSolvingButton").show();
+        $("#solvingIndicator").show();
+        $("#generateButton").prop('disabled', true);
+    } else {
+        $("#solveButton").show();
+        $("#stopSolvingButton").hide();
+        $("#solvingIndicator").hide();
+        $("#generateButton").prop('disabled', false);
+    }
+}
+
+/**
+ * Flash the score display to indicate improvement.
+ */
+function flashScoreImprovement() {
+    const display = $("#scoreDisplay");
+    display.addClass('improved');
+    setTimeout(() => display.removeClass('improved'), 500);
+}
+
+// =============================================================================
+// Score Analysis
+// =============================================================================
+
+/**
+ * Fetch and display detailed constraint analysis.
+ * Shows which constraints are satisfied/violated and their contribution to score.
+ */
+function analyze() {
+    if (!currentProblemId) {
+        showError("No active solution to analyze");
+        return;
+    }
+
+    // Show loading state
+    const btn = $("#analyzeButton");
+    btn.prop('disabled', true).html('<i class="fas fa-spinner fa-spin"></i>');
+
+    fetch(`/schedules/${currentProblemId}/score-analysis`)
+        .then(r => r.json())
+        .then(analysis => {
+            showScoreAnalysis(analysis);
+        })
+        .catch(error => {
+            showError("Failed to load score analysis", error);
+        })
+        .finally(() => {
+            btn.prop('disabled', false).html('<i class="fas fa-chart-bar"></i>');
+        });
+}
+
+/**
+ * Display score analysis in a modal dialog.
+ */
+function showScoreAnalysis(analysis) {
+    const content = $("#scoreAnalysisModalContent");
+    content.empty();
+
+    if (!analysis || !analysis.constraints) {
+        content.html('<p>No constraint data available.</p>');
+    } else {
+        for (const constraint of analysis.constraints) {
+            const score = constraint.score || '0';
+            const isHard = score.includes('hard');
+
+            const group = $(`
+                <div class="constraint-group">
+                    <div class="constraint-header">
+                        <span class="constraint-name">${constraint.name}</span>
+                        <span class="constraint-score ${isHard ? 'hard' : 'soft'}">${score}</span>
+                    </div>
+                </div>
+            `);
+            content.append(group);
+        }
+    }
+
+    // Use getOrCreateInstance to avoid stacking modal instances
+    const modalEl = document.getElementById('scoreAnalysisModal');
+    bootstrap.Modal.getOrCreateInstance(modalEl).show();
+}
+
+// =============================================================================
+// Notifications
+// =============================================================================
+
+/**
+ * Display an error notification that auto-dismisses.
+ */
+function showError(message, error) {
+    console.error(message, error);
+    const alert = $(`
+        <div class="alert alert-danger alert-dismissible fade show">
+            <i class="fas fa-exclamation-circle me-2"></i>
+            <strong>Error:</strong> ${message}
+            <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+        </div>
+    `);
+    $("#notificationPanel").append(alert);
+    setTimeout(() => alert.alert('close'), 5000);
+}
+
+/**
+ * Display a success notification that auto-dismisses.
+ */
+function showSuccess(message) {
+    const alert = $(`
+        <div class="alert alert-success alert-dismissible fade show">
+            <i class="fas fa-check-circle me-2"></i>${message}
+            <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+        </div>
+    `);
+    $("#notificationPanel").append(alert);
+    setTimeout(() => alert.alert('close'), 3000);
+}
+
+// =============================================================================
+// SolverForge Branding
+// =============================================================================
+
+/**
+ * Add SolverForge header and footer branding.
+ * Matches the pattern used in other SolverForge quickstarts.
+ */
+function replaceQuickstartSolverForgeAutoHeaderFooter() {
+    const header = $("header#solverforge-auto-header");
+    if (header.length) {
+        header.css("background-color", "#ffffff");
+        header.append($(`
+            <div class="container-fluid">
+                <nav class="navbar sticky-top navbar-expand-lg shadow-sm mb-3" style="background-color: #ffffff;">
+                    <a class="navbar-brand" href="https://www.solverforge.org">
+                        <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge logo" width="400">
+                    </a>
+                </nav>
+            </div>
+        `));
+    }
+
+    const footer = $("footer#solverforge-auto-footer");
+    if (footer.length) {
+        footer.append($(`
+            <footer class="bg-black text-white-50">
+                <div class="container">
+                    <div class="hstack gap-3 p-4">
+                        <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+                        <div class="vr"></div>
+                        <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+                        <div class="vr"></div>
+                        <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+                        <div class="vr"></div>
+                        <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+                    </div>
+                </div>
+            </footer>
+        `));
+    }
+}

static/index.html

@@ -0,0 +1,179 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Order Picking - SolverForge</title>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/css/bootstrap.min.css"/>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css"/>
+    <link rel="stylesheet" href="/webjars/solverforge/css/solverforge-webui.css"/>
+    <link rel="stylesheet" href="/style.css"/>
+    <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
+</head>
+<body>
+<header id="solverforge-auto-header"></header>
+
+<div class="container-fluid main-container">
+    <!-- Notification Area -->
+    <div class="notification-area">
+        <div id="notificationPanel"></div>
+    </div>
+
+    <!-- Header Bar -->
+    <div class="header-bar">
+        <div class="header-left">
+            <h1>Order Picking</h1>
+        </div>
+        <div class="header-center">
+            <button id="solveButton" class="btn btn-solve">
+                <i class="fas fa-play"></i> Solve
+            </button>
+            <button id="stopSolvingButton" class="btn btn-stop" style="display: none">
+                <i class="fas fa-stop"></i> Stop
+            </button>
+            <div id="scoreDisplay" class="score-display">
+                <span class="score-label">Score</span>
+                <span id="score" class="score-value">?</span>
+            </div>
+            <div id="solvingIndicator" class="solving-indicator" style="display: none">
+                <div class="solving-spinner"></div>
+                <span>Optimizing...</span>
+            </div>
+        </div>
+        <div class="header-right">
+            <button id="settingsToggle" class="btn btn-settings" data-bs-toggle="collapse" data-bs-target="#settingsPanel">
+                <i class="fas fa-sliders-h"></i>
+            </button>
+            <button id="analyzeButton" class="btn btn-analyze">
+                <i class="fas fa-chart-bar"></i>
+            </button>
+        </div>
+    </div>
+
+    <!-- Settings Panel (Collapsible) -->
+    <div class="collapse" id="settingsPanel">
+        <div class="settings-panel">
+            <div class="settings-grid">
+                <div class="setting-item">
+                    <label>
+                        <i class="fas fa-shopping-cart"></i> Orders
+                        <span class="badge" id="ordersCountValue">40</span>
+                    </label>
+                    <input type="range" id="ordersCountSlider" min="10" max="100" value="40">
+                </div>
+                <div class="setting-item">
+                    <label>
+                        <i class="fas fa-dolly"></i> Trolleys
+                        <span class="badge" id="trolleysCountValue">8</span>
+                    </label>
+                    <input type="range" id="trolleysCountSlider" min="3" max="15" value="8">
+                </div>
+                <div class="setting-item">
+                    <label>
+                        <i class="fas fa-box"></i> Buckets
+                        <span class="badge" id="bucketsCountValue">6</span>
+                    </label>
+                    <input type="range" id="bucketsCountSlider" min="2" max="10" value="6">
+                </div>
+                <div class="setting-item">
+                    <button id="generateButton" class="btn btn-generate">
+                        <i class="fas fa-sync-alt"></i> Generate New
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- Main Content Area -->
+    <div class="content-area">
+        <!-- Stats Cards -->
+        <div class="stats-sidebar">
+            <div class="stat-card" id="ordersCard">
+                <div class="stat-icon"><i class="fas fa-clipboard-list"></i></div>
+                <div class="stat-info">
+                    <span class="stat-value" id="totalOrders">0</span>
+                    <span class="stat-label">Orders</span>
+                </div>
+            </div>
+            <div class="stat-card" id="itemsCard">
+                <div class="stat-icon"><i class="fas fa-cube"></i></div>
+                <div class="stat-info">
+                    <span class="stat-value" id="totalItems">0</span>
+                    <span class="stat-label">Items</span>
+                </div>
+            </div>
+            <div class="stat-card" id="trolleysCard">
+                <div class="stat-icon"><i class="fas fa-dolly"></i></div>
+                <div class="stat-info">
+                    <span class="stat-value" id="activeTrolleys">0</span>
+                    <span class="stat-label">Active</span>
+                </div>
+            </div>
+            <div class="stat-card" id="distanceCard">
+                <div class="stat-icon"><i class="fas fa-route"></i></div>
+                <div class="stat-info">
+                    <span class="stat-value" id="totalDistance">0</span>
+                    <span class="stat-label">meters</span>
+                </div>
+            </div>
+        </div>
+
+        <!-- Canvas Area -->
+        <div class="canvas-area">
+            <div id="warehouseContainer">
+                <canvas id="warehouseCanvas"></canvas>
+                <!-- Legend Overlay -->
+                <div id="legendOverlay">
+                    <div class="legend-header">
+                        <i class="fas fa-dolly"></i> Trolleys
+                    </div>
+                    <div id="trolleyLegend">
+                        <!-- Populated by JS -->
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- Trolley Cards Section -->
+    <div class="trolley-section">
+        <div class="section-header">
+            <h2><i class="fas fa-tasks"></i> Picking Plan</h2>
+        </div>
+        <div id="trolleyCardsContainer" class="trolley-cards-grid">
+            <!-- Populated by JS -->
+        </div>
+    </div>
+</div>
+
+<!-- Score Analysis Modal -->
+<div class="modal fade" id="scoreAnalysisModal" tabindex="-1">
+    <div class="modal-dialog modal-lg modal-dialog-scrollable">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title">
+                    <i class="fas fa-chart-bar"></i> Score Analysis
+                    <span id="scoreAnalysisScoreLabel"></span>
+                </h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+            </div>
+            <div class="modal-body" id="scoreAnalysisModalContent">
+                <!-- Populated by JS -->
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>
+
+<footer id="solverforge-auto-footer"></footer>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/js/bootstrap.bundle.min.js"></script>
+<script src="/webjars/solverforge/js/solverforge-webui.js"></script>
+<script src="/warehouse-api.js"></script>
+<script src="/logisim-view.js"></script>
+<script src="/app.js"></script>
+</body>
+</html>

static/logisim-view.js

@@ -0,0 +1,850 @@
+/**
+ * Isometric 3D Warehouse Visualization
+ * Professional order picking visualization with animated trolleys
+ */
+
+const ISO = {
+    // Isometric projection angles
+    ANGLE: Math.PI / 6, // 30 degrees
+
+    // Tile dimensions
+    TILE_WIDTH: 48,
+    TILE_HEIGHT: 24,
+
+    // Shelf dimensions (in tiles)
+    SHELF_WIDTH: 3,
+    SHELF_DEPTH: 1,
+    SHELF_HEIGHT: 2,
+
+    // Warehouse layout: 5 columns (A-E) x 3 rows
+    COLS: 5,
+    ROWS: 3,
+
+    // Spacing between shelves
+    AISLE_WIDTH: 2,
+
+    // Colors
+    COLORS: {
+        floor: '#e2e8f0',
+        floorGrid: '#cbd5e1',
+        shelfTop: '#ffffff',
+        shelfFront: '#f1f5f9',
+        shelfSide: '#e2e8f0',
+        shelfBorder: '#94a3b8',
+        shadow: 'rgba(0, 0, 0, 0.1)',
+        trolley: [
+            '#ef4444', // red
+            '#3b82f6', // blue
+            '#10b981', // green
+            '#f59e0b', // amber
+            '#8b5cf6', // purple
+            '#06b6d4', // cyan
+            '#ec4899', // pink
+            '#84cc16', // lime
+        ],
+        path: 'rgba(59, 130, 246, 0.3)',
+        pathActive: 'rgba(59, 130, 246, 0.6)',
+    },
+
+    // Animation state
+    animationId: null,
+    isSolving: false,
+    trolleyAnimations: new Map(),
+    currentSolution: null,
+
+    // Canvas state
+    canvas: null,
+    ctx: null,
+    dpr: 1,
+    width: 0,
+    height: 0,
+    originX: 0,
+    originY: 0,
+    // Grid offset to center the warehouse
+    gridOffsetX: 0,
+    gridOffsetY: 0,
+};
+
+// Column/Row mapping
+const COLUMNS = ['A', 'B', 'C', 'D', 'E'];
+const ROWS = ['1', '2', '3'];
+
+/**
+ * Convert isometric coordinates to screen coordinates
+ */
+function isoToScreen(x, y, z = 0) {
+    // Apply grid offset to center the warehouse
+    const centeredX = x - ISO.gridOffsetX;
+    const centeredY = y - ISO.gridOffsetY;
+    const screenX = ISO.originX + (centeredX - centeredY) * (ISO.TILE_WIDTH / 2);
+    const screenY = ISO.originY + (centeredX + centeredY) * (ISO.TILE_HEIGHT / 2) - z * ISO.TILE_HEIGHT;
+    return { x: screenX, y: screenY };
+}
+
+/**
+ * Get trolley color by ID
+ */
+function getTrolleyColor(trolleyId) {
+    const index = (parseInt(trolleyId) - 1) % ISO.COLORS.trolley.length;
+    return ISO.COLORS.trolley[index];
+}
+
+/**
+ * Initialize the canvas
+ */
+function initWarehouseCanvas() {
+    const container = document.getElementById('warehouseContainer');
+    if (!container) return;
+
+    let canvas = document.getElementById('warehouseCanvas');
+    if (!canvas) {
+        canvas = document.createElement('canvas');
+        canvas.id = 'warehouseCanvas';
+        container.appendChild(canvas);
+    }
+
+    ISO.canvas = canvas;
+    ISO.ctx = canvas.getContext('2d');
+    ISO.dpr = window.devicePixelRatio || 1;
+
+    // Calculate canvas size based on warehouse dimensions
+    const totalWidth = (ISO.COLS * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH) * ISO.TILE_WIDTH;
+    const totalHeight = (ISO.ROWS * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH) * ISO.TILE_WIDTH;
+
+    // Isometric dimensions
+    ISO.width = totalWidth + 200;
+    ISO.height = totalHeight / 2 + 300;
+
+    // Set canvas size with HiDPI support
+    canvas.width = ISO.width * ISO.dpr;
+    canvas.height = ISO.height * ISO.dpr;
+    canvas.style.width = ISO.width + 'px';
+    canvas.style.height = ISO.height + 'px';
+
+    ISO.ctx.scale(ISO.dpr, ISO.dpr);
+
+    // Calculate grid center offset for centering
+    const gridSize = ISO.COLS * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH;
+    const gridDepth = ISO.ROWS * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH;
+    ISO.gridOffsetX = gridSize / 2;
+    ISO.gridOffsetY = gridDepth / 2;
+
+    // Set origin point (center of canvas)
+    ISO.originX = ISO.width / 2;
+    ISO.originY = ISO.height / 2 - 50; // Slightly above center
+}
+
+/**
+ * Draw the warehouse floor grid
+ */
+function drawFloor() {
+    const ctx = ISO.ctx;
+    const gridSize = ISO.COLS * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH;
+    const gridDepth = ISO.ROWS * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH) + ISO.AISLE_WIDTH;
+
+    // Draw floor tiles
+    for (let x = 0; x < gridSize; x++) {
+        for (let y = 0; y < gridDepth; y++) {
+            const p1 = isoToScreen(x, y);
+            const p2 = isoToScreen(x + 1, y);
+            const p3 = isoToScreen(x + 1, y + 1);
+            const p4 = isoToScreen(x, y + 1);
+
+            ctx.beginPath();
+            ctx.moveTo(p1.x, p1.y);
+            ctx.lineTo(p2.x, p2.y);
+            ctx.lineTo(p3.x, p3.y);
+            ctx.lineTo(p4.x, p4.y);
+            ctx.closePath();
+
+            ctx.fillStyle = ISO.COLORS.floor;
+            ctx.fill();
+            ctx.strokeStyle = ISO.COLORS.floorGrid;
+            ctx.lineWidth = 0.5;
+            ctx.stroke();
+        }
+    }
+}
+
+/**
+ * Draw a 3D shelf at grid position
+ */
+function drawShelf(col, row, label) {
+    const ctx = ISO.ctx;
+
+    // Calculate grid position
+    const gridX = ISO.AISLE_WIDTH + col * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH);
+    const gridY = ISO.AISLE_WIDTH + row * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH);
+
+    const w = ISO.SHELF_WIDTH;
+    const d = ISO.SHELF_DEPTH;
+    const h = ISO.SHELF_HEIGHT;
+
+    // Get corner points
+    const topFront = [
+        isoToScreen(gridX, gridY + d, h),
+        isoToScreen(gridX + w, gridY + d, h),
+        isoToScreen(gridX + w, gridY, h),
+        isoToScreen(gridX, gridY, h),
+    ];
+
+    const bottomFront = [
+        isoToScreen(gridX, gridY + d, 0),
+        isoToScreen(gridX + w, gridY + d, 0),
+    ];
+
+    const bottomSide = [
+        isoToScreen(gridX + w, gridY, 0),
+    ];
+
+    // Draw shadow
+    ctx.beginPath();
+    const shadowOffset = 0.3;
+    const s1 = isoToScreen(gridX + shadowOffset, gridY + d + shadowOffset, 0);
+    const s2 = isoToScreen(gridX + w + shadowOffset, gridY + d + shadowOffset, 0);
+    const s3 = isoToScreen(gridX + w + shadowOffset, gridY + shadowOffset, 0);
+    const s4 = isoToScreen(gridX + shadowOffset, gridY + shadowOffset, 0);
+    ctx.moveTo(s1.x, s1.y);
+    ctx.lineTo(s2.x, s2.y);
+    ctx.lineTo(s3.x, s3.y);
+    ctx.lineTo(s4.x, s4.y);
+    ctx.closePath();
+    ctx.fillStyle = ISO.COLORS.shadow;
+    ctx.fill();
+
+    // Draw front face
+    ctx.beginPath();
+    ctx.moveTo(topFront[0].x, topFront[0].y);
+    ctx.lineTo(topFront[1].x, topFront[1].y);
+    ctx.lineTo(bottomFront[1].x, bottomFront[1].y);
+    ctx.lineTo(bottomFront[0].x, bottomFront[0].y);
+    ctx.closePath();
+    ctx.fillStyle = ISO.COLORS.shelfFront;
+    ctx.fill();
+    ctx.strokeStyle = ISO.COLORS.shelfBorder;
+    ctx.lineWidth = 1;
+    ctx.stroke();
+
+    // Draw side face
+    ctx.beginPath();
+    ctx.moveTo(topFront[1].x, topFront[1].y);
+    ctx.lineTo(topFront[2].x, topFront[2].y);
+    ctx.lineTo(bottomSide[0].x, bottomSide[0].y);
+    ctx.lineTo(bottomFront[1].x, bottomFront[1].y);
+    ctx.closePath();
+    ctx.fillStyle = ISO.COLORS.shelfSide;
+    ctx.fill();
+    ctx.strokeStyle = ISO.COLORS.shelfBorder;
+    ctx.stroke();
+
+    // Draw top face
+    ctx.beginPath();
+    ctx.moveTo(topFront[0].x, topFront[0].y);
+    ctx.lineTo(topFront[1].x, topFront[1].y);
+    ctx.lineTo(topFront[2].x, topFront[2].y);
+    ctx.lineTo(topFront[3].x, topFront[3].y);
+    ctx.closePath();
+    ctx.fillStyle = ISO.COLORS.shelfTop;
+    ctx.fill();
+    ctx.strokeStyle = ISO.COLORS.shelfBorder;
+    ctx.stroke();
+
+    // Draw label
+    const centerX = (topFront[0].x + topFront[1].x + topFront[2].x + topFront[3].x) / 4;
+    const centerY = (topFront[0].y + topFront[1].y + topFront[2].y + topFront[3].y) / 4;
+
+    ctx.font = 'bold 14px -apple-system, BlinkMacSystemFont, sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillStyle = '#475569';
+    ctx.fillText(label, centerX, centerY);
+}
+
+/**
+ * Draw all shelves
+ */
+function drawShelves() {
+    for (let col = 0; col < ISO.COLS; col++) {
+        for (let row = 0; row < ISO.ROWS; row++) {
+            const label = COLUMNS[col] + ',' + ROWS[row];
+            drawShelf(col, row, label);
+        }
+    }
+}
+
+/**
+ * Draw a trolley at position
+ */
+function drawTrolley(x, y, color, trolleyId, progress = 1) {
+    const ctx = ISO.ctx;
+    const pos = isoToScreen(x, y, 0.3);
+
+    // Trolley body dimensions
+    const bodyWidth = 20;
+    const bodyHeight = 14;
+    const bodyDepth = 8;
+
+    // Draw trolley body (isometric box)
+    ctx.save();
+    ctx.translate(pos.x, pos.y);
+
+    // Shadow
+    ctx.beginPath();
+    ctx.ellipse(0, 6, 12, 6, 0, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.15)';
+    ctx.fill();
+
+    // Body - front
+    ctx.beginPath();
+    ctx.moveTo(-bodyWidth/2, -bodyDepth);
+    ctx.lineTo(bodyWidth/2, -bodyDepth);
+    ctx.lineTo(bodyWidth/2, bodyHeight - bodyDepth);
+    ctx.lineTo(-bodyWidth/2, bodyHeight - bodyDepth);
+    ctx.closePath();
+    ctx.fillStyle = color;
+    ctx.fill();
+    ctx.strokeStyle = 'rgba(0, 0, 0, 0.2)';
+    ctx.lineWidth = 1;
+    ctx.stroke();
+
+    // Body - top
+    ctx.beginPath();
+    ctx.moveTo(-bodyWidth/2, -bodyDepth);
+    ctx.lineTo(0, -bodyDepth - 6);
+    ctx.lineTo(bodyWidth/2, -bodyDepth);
+    ctx.lineTo(0, -bodyDepth + 3);
+    ctx.closePath();
+    const lighterColor = lightenColor(color, 20);
+    ctx.fillStyle = lighterColor;
+    ctx.fill();
+    ctx.stroke();
+
+    // Handle
+    ctx.beginPath();
+    ctx.moveTo(-bodyWidth/2 + 3, -bodyDepth - 2);
+    ctx.lineTo(-bodyWidth/2 + 3, -bodyDepth - 12);
+    ctx.lineTo(bodyWidth/2 - 3, -bodyDepth - 12);
+    ctx.lineTo(bodyWidth/2 - 3, -bodyDepth - 2);
+    ctx.strokeStyle = darkenColor(color, 20);
+    ctx.lineWidth = 2;
+    ctx.stroke();
+
+    // Trolley number badge
+    ctx.beginPath();
+    ctx.arc(0, -bodyDepth - 16, 10, 0, Math.PI * 2);
+    ctx.fillStyle = 'white';
+    ctx.fill();
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 2;
+    ctx.stroke();
+
+    ctx.font = 'bold 11px -apple-system, sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillStyle = color;
+    ctx.fillText(trolleyId, 0, -bodyDepth - 16);
+
+    ctx.restore();
+}
+
+/**
+ * Lighten a hex color
+ */
+function lightenColor(hex, percent) {
+    const num = parseInt(hex.slice(1), 16);
+    const amt = Math.round(2.55 * percent);
+    const R = Math.min(255, (num >> 16) + amt);
+    const G = Math.min(255, ((num >> 8) & 0x00FF) + amt);
+    const B = Math.min(255, (num & 0x0000FF) + amt);
+    return '#' + (0x1000000 + R * 0x10000 + G * 0x100 + B).toString(16).slice(1);
+}
+
+/**
+ * Darken a hex color
+ */
+function darkenColor(hex, percent) {
+    const num = parseInt(hex.slice(1), 16);
+    const amt = Math.round(2.55 * percent);
+    const R = Math.max(0, (num >> 16) - amt);
+    const G = Math.max(0, ((num >> 8) & 0x00FF) - amt);
+    const B = Math.max(0, (num & 0x0000FF) - amt);
+    return '#' + (0x1000000 + R * 0x10000 + G * 0x100 + B).toString(16).slice(1);
+}
+
+/**
+ * Convert warehouse location to grid position
+ * Returns position in aisle next to the shelf
+ */
+function locationToGrid(location) {
+    if (!location) return { x: 1, y: 1 };
+
+    // Parse shelving ID like "(A, 1)"
+    const shelvingId = location.shelvingId || '';
+    const match = shelvingId.match(/\(([A-E]),\s*(\d)\)/);
+
+    let col = 0, row = 0;
+    if (match) {
+        col = COLUMNS.indexOf(match[1]);
+        row = parseInt(match[2]) - 1;
+    }
+
+    // Calculate shelf's grid position
+    const shelfGridX = ISO.AISLE_WIDTH + col * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH);
+    const shelfGridY = ISO.AISLE_WIDTH + row * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH);
+
+    // Position in the aisle in front of the shelf (below it in grid terms)
+    const aisleY = shelfGridY + ISO.SHELF_DEPTH + 0.5;
+
+    // Adjust X for side (LEFT/RIGHT of shelf)
+    const side = location.side;
+    let gridX;
+    if (side === 'LEFT') {
+        gridX = shelfGridX - 0.5; // Left aisle
+    } else {
+        gridX = shelfGridX + ISO.SHELF_WIDTH + 0.5; // Right aisle
+    }
+
+    return { x: gridX, y: aisleY };
+}
+
+/**
+ * Get the main aisle Y position (horizontal corridor)
+ */
+function getMainAisleY() {
+    // Main aisle runs at the bottom of the warehouse
+    return (ISO.ROWS * (ISO.SHELF_DEPTH + ISO.AISLE_WIDTH)) + ISO.AISLE_WIDTH + 0.5;
+}
+
+/**
+ * Get vertical aisle X positions (between shelves)
+ */
+function getVerticalAisleX(col) {
+    // Aisle to the left of column 'col'
+    return ISO.AISLE_WIDTH + col * (ISO.SHELF_WIDTH + ISO.AISLE_WIDTH) - 0.5;
+}
+
+/**
+ * Build a path that follows aisles from start to end
+ * Uses a simple strategy: go to main aisle, traverse horizontally, go up to destination
+ */
+function buildAislePath(start, end) {
+    const path = [start];
+
+    // If start and end are very close, just go directly
+    const dx = Math.abs(start.x - end.x);
+    const dy = Math.abs(start.y - end.y);
+    if (dx < 2 && dy < 2) {
+        path.push(end);
+        return path;
+    }
+
+    const mainAisleY = getMainAisleY();
+
+    // Strategy: go down to main aisle (or near it), traverse, then go up
+    // First, go to the nearest vertical aisle
+    const startAisleY = Math.max(start.y, mainAisleY - 1);
+    const endAisleY = Math.max(end.y, mainAisleY - 1);
+
+    // Move to horizontal travel position
+    if (Math.abs(start.y - startAisleY) > 0.5) {
+        path.push({ x: start.x, y: startAisleY });
+    }
+
+    // Move horizontally to align with destination column
+    if (Math.abs(start.x - end.x) > 0.5) {
+        path.push({ x: end.x, y: startAisleY });
+    }
+
+    // Move vertically to destination
+    if (Math.abs(path[path.length - 1].y - end.y) > 0.5) {
+        path.push({ x: end.x, y: end.y });
+    }
+
+    // Add final destination if different from last point
+    const last = path[path.length - 1];
+    if (Math.abs(last.x - end.x) > 0.1 || Math.abs(last.y - end.y) > 0.1) {
+        path.push(end);
+    }
+
+    return path;
+}
+
+/**
+ * Build trolley path from steps with proper aisle routing
+ * Returns { path: [], pickupIndices: [] }
+ */
+function buildTrolleyPath(trolley, steps) {
+    const waypoints = [];
+    const waypointTypes = []; // 'start', 'pickup', 'end'
+
+    // Start position
+    if (trolley.location) {
+        waypoints.push(locationToGrid(trolley.location));
+        waypointTypes.push('start');
+    }
+
+    // Add each step location
+    for (const step of steps) {
+        if (step.orderItem && step.orderItem.product && step.orderItem.product.location) {
+            waypoints.push(locationToGrid(step.orderItem.product.location));
+            waypointTypes.push('pickup');
+        }
+    }
+
+    // Return to start
+    if (waypoints.length > 1 && trolley.location) {
+        waypoints.push(locationToGrid(trolley.location));
+        waypointTypes.push('end');
+    }
+
+    if (waypoints.length <= 1) {
+        return { path: waypoints, pickupIndices: [] };
+    }
+
+    // Build full path with aisle routing between each waypoint
+    const fullPath = [waypoints[0]];
+    const pickupIndices = [];
+
+    for (let i = 1; i < waypoints.length; i++) {
+        const segmentPath = buildAislePath(waypoints[i - 1], waypoints[i]);
+        // Skip first point (it's the same as last point of previous segment)
+        for (let j = 1; j < segmentPath.length; j++) {
+            fullPath.push(segmentPath[j]);
+        }
+        // Track pickup point index
+        if (waypointTypes[i] === 'pickup') {
+            pickupIndices.push(fullPath.length - 1);
+        }
+    }
+
+    return { path: fullPath, pickupIndices: pickupIndices };
+}
+
+/**
+ * Draw trolley path
+ */
+function drawPath(path, color, pickupIndices, active = false) {
+    if (path.length < 2) return;
+
+    const ctx = ISO.ctx;
+    ctx.beginPath();
+
+    const start = isoToScreen(path[0].x, path[0].y, 0.1);
+    ctx.moveTo(start.x, start.y);
+
+    for (let i = 1; i < path.length; i++) {
+        const point = isoToScreen(path[i].x, path[i].y, 0.1);
+        ctx.lineTo(point.x, point.y);
+    }
+
+    ctx.strokeStyle = active ? ISO.COLORS.pathActive : ISO.COLORS.path;
+    ctx.lineWidth = active ? 4 : 2;
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+    ctx.stroke();
+
+    // Draw pickup markers only at actual pickup points
+    let pickupNum = 1;
+    for (const idx of pickupIndices) {
+        if (idx >= 0 && idx < path.length) {
+            const point = isoToScreen(path[idx].x, path[idx].y, 0.5);
+
+            ctx.beginPath();
+            ctx.arc(point.x, point.y, 8, 0, Math.PI * 2);
+            ctx.fillStyle = color;
+            ctx.fill();
+            ctx.strokeStyle = 'white';
+            ctx.lineWidth = 2;
+            ctx.stroke();
+
+            ctx.font = 'bold 9px -apple-system, sans-serif';
+            ctx.textAlign = 'center';
+            ctx.textBaseline = 'middle';
+            ctx.fillStyle = 'white';
+            ctx.fillText(pickupNum.toString(), point.x, point.y);
+            pickupNum++;
+        }
+    }
+}
+
+/**
+ * Get position along path at progress (0-1)
+ */
+function getPositionOnPath(path, progress) {
+    if (!path || path.length === 0) return { x: 0, y: 0 };
+    if (path.length === 1) return path[0];
+
+    const totalSegments = path.length - 1;
+    const segmentProgress = progress * totalSegments;
+    const currentSegment = Math.min(Math.floor(segmentProgress), totalSegments - 1);
+    const segmentT = segmentProgress - currentSegment;
+
+    const start = path[currentSegment];
+    const end = path[currentSegment + 1];
+
+    // Safety check for undefined points
+    if (!start || !end) return path[0] || { x: 0, y: 0 };
+
+    return {
+        x: start.x + (end.x - start.x) * segmentT,
+        y: start.y + (end.y - start.y) * segmentT,
+    };
+}
+
+/**
+ * Render the full warehouse scene
+ */
+function renderWarehouse(solution) {
+    if (!ISO.ctx) return;
+
+    const ctx = ISO.ctx;
+    ctx.clearRect(0, 0, ISO.width, ISO.height);
+
+    // Draw floor
+    drawFloor();
+
+    // Draw shelves (back to front for proper overlap)
+    drawShelves();
+
+    if (!solution || !solution.trolleys) return;
+
+    // Build step lookup
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    // Draw paths and trolleys
+    const trolleys = solution.trolleys || [];
+
+    for (const trolley of trolleys) {
+        const steps = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? stepLookup.get(ref) : ref
+        ).filter(s => s);
+
+        const color = getTrolleyColor(trolley.id);
+        const pathData = buildTrolleyPath(trolley, steps);
+        const path = pathData.path;
+        const pickupIndices = pathData.pickupIndices;
+
+        // Draw path
+        if (path.length > 1) {
+            drawPath(path, color, pickupIndices, ISO.isSolving);
+        }
+
+        // Draw trolley
+        const anim = ISO.trolleyAnimations.get(trolley.id);
+        let pos;
+
+        if (anim && ISO.isSolving && path.length > 1) {
+            const now = Date.now();
+            const elapsed = now - anim.startTime;
+            const progress = (elapsed % anim.duration) / anim.duration;
+            pos = getPositionOnPath(path, progress);
+        } else if (path.length > 0) {
+            pos = path[0];
+        } else {
+            pos = locationToGrid(trolley.location);
+        }
+
+        if (pos) {
+            drawTrolley(pos.x, pos.y, color, trolley.id);
+        }
+    }
+}
+
+/**
+ * Animation loop - only runs when solving to animate trolley positions
+ */
+function animate() {
+    if (!ISO.isSolving) {
+        ISO.animationId = null;
+        return;
+    }
+
+    // Only re-render if we have a valid solution
+    // The animation loop provides smooth trolley movement
+    if (ISO.currentSolution && ISO.currentSolution.trolleys) {
+        renderWarehouse(ISO.currentSolution);
+    }
+
+    ISO.animationId = requestAnimationFrame(animate);
+}
+
+/**
+ * Start solving animation
+ */
+function startWarehouseAnimation(solution) {
+    ISO.isSolving = true;
+    ISO.currentSolution = solution;
+    ISO.trolleyAnimations.clear();
+
+    // Initialize animations for each trolley
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    for (const trolley of solution.trolleys || []) {
+        // Get step IDs for signature
+        const stepIds = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? ref : ref.id
+        );
+
+        const steps = stepIds.map(id => stepLookup.get(id)).filter(s => s);
+
+        const pathData = buildTrolleyPath(trolley, steps);
+        const path = pathData.path;
+        const duration = Math.max(3000, path.length * 400);
+
+        ISO.trolleyAnimations.set(trolley.id, {
+            startTime: Date.now() + parseInt(trolley.id) * 200,
+            duration: duration,
+            path: path,
+            stepSignature: stepIds.join(','),  // Track initial signature
+        });
+    }
+
+    if (!ISO.animationId) {
+        animate();
+    }
+}
+
+/**
+ * Update animation with new solution data
+ */
+function updateWarehouseAnimation(solution) {
+    console.log('[updateWarehouseAnimation] Called with', solution?.trolleys?.length, 'trolleys');
+    ISO.currentSolution = solution;
+
+    // Build step lookup for resolving references
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    let anyPathChanged = false;
+
+    for (const trolley of solution.trolleys || []) {
+        // Get step IDs for this trolley (for change detection)
+        const stepIds = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? ref : ref.id
+        );
+
+        // Resolve to full step objects
+        const steps = stepIds.map(id => stepLookup.get(id)).filter(s => s);
+
+        const pathData = buildTrolleyPath(trolley, steps);
+        const path = pathData.path;
+        const existingAnim = ISO.trolleyAnimations.get(trolley.id);
+
+        if (existingAnim) {
+            // Create signature of step assignments to detect any change
+            const oldSignature = existingAnim.stepSignature || '';
+            const newSignature = stepIds.join(',');
+            const pathChanged = oldSignature !== newSignature;
+
+            if (pathChanged) {
+                anyPathChanged = true;
+                console.log(`[PATH CHANGE] Trolley ${trolley.id}:`, {
+                    old: oldSignature.substring(0, 50),
+                    new: newSignature.substring(0, 50),
+                    oldLen: oldSignature.split(',').filter(x=>x).length,
+                    newLen: stepIds.length
+                });
+            }
+
+            existingAnim.path = path;
+            existingAnim.stepSignature = newSignature;
+            existingAnim.duration = Math.max(3000, path.length * 400);
+
+            // Reset animation timing when path changes to prevent position jumps
+            if (pathChanged) {
+                existingAnim.startTime = Date.now();
+            }
+        } else {
+            ISO.trolleyAnimations.set(trolley.id, {
+                startTime: Date.now(),
+                duration: Math.max(3000, path.length * 400),
+                path: path,
+                stepSignature: stepIds.join(','),
+            });
+            anyPathChanged = true;
+        }
+    }
+
+    // Visual feedback when paths change
+    if (anyPathChanged) {
+        console.log('[RENDER] Paths changed, forcing immediate render');
+        // Flash the canvas border to indicate update
+        if (ISO.canvas) {
+            ISO.canvas.style.outline = '3px solid #10b981';
+            setTimeout(() => { ISO.canvas.style.outline = 'none'; }, 200);
+        }
+    }
+
+    // Force immediate render with updated paths
+    renderWarehouse(solution);
+
+    // Restart animation loop if it died
+    if (ISO.isSolving && !ISO.animationId) {
+        animate();
+    }
+}
+
+/**
+ * Stop animation
+ */
+function stopWarehouseAnimation() {
+    ISO.isSolving = false;
+    if (ISO.animationId) {
+        cancelAnimationFrame(ISO.animationId);
+        ISO.animationId = null;
+    }
+    // Render final state
+    if (ISO.currentSolution) {
+        renderWarehouse(ISO.currentSolution);
+    }
+}
+
+/**
+ * Update legend with trolley info
+ */
+function updateLegend(solution, distances) {
+    const container = document.getElementById('trolleyLegend');
+    if (!container) return;
+
+    container.innerHTML = '';
+
+    const stepLookup = new Map();
+    for (const step of solution.trolleySteps || []) {
+        stepLookup.set(step.id, step);
+    }
+
+    for (const trolley of solution.trolleys || []) {
+        const steps = (trolley.steps || []).map(ref =>
+            typeof ref === 'string' ? stepLookup.get(ref) : ref
+        ).filter(s => s);
+
+        const color = getTrolleyColor(trolley.id);
+        const distance = distances ? distances.get(trolley.id) || 0 : 0;
+
+        const item = document.createElement('div');
+        item.className = 'legend-item';
+        item.innerHTML = `
+            <div class="legend-color" style="background: ${color}"></div>
+            <span class="legend-text">Trolley ${trolley.id}</span>
+            <span class="legend-distance">${steps.length} items</span>
+        `;
+        container.appendChild(item);
+    }
+}
+
+// Export for app.js
+window.initWarehouseCanvas = initWarehouseCanvas;
+window.renderWarehouse = renderWarehouse;
+window.startWarehouseAnimation = startWarehouseAnimation;
+window.updateWarehouseAnimation = updateWarehouseAnimation;
+window.stopWarehouseAnimation = stopWarehouseAnimation;
+window.updateLegend = updateLegend;
+window.getTrolleyColor = getTrolleyColor;

static/style.css

@@ -0,0 +1,810 @@
+/* =============================================================================
+   Order Picking - Professional UI Styles
+   ============================================================================= */
+
+:root {
+    --primary: #10b981;
+    --primary-dark: #059669;
+    --primary-light: #34d399;
+    --danger: #ef4444;
+    --warning: #f59e0b;
+    --info: #3b82f6;
+    --dark: #1e293b;
+    --gray-50: #f8fafc;
+    --gray-100: #f1f5f9;
+    --gray-200: #e2e8f0;
+    --gray-300: #cbd5e1;
+    --gray-400: #94a3b8;
+    --gray-500: #64748b;
+    --gray-600: #475569;
+    --gray-700: #334155;
+    --gray-800: #1e293b;
+    --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+    --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06);
+    --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -2px rgba(0,0,0,0.05);
+    --shadow-xl: 0 20px 25px -5px rgba(0,0,0,0.1), 0 10px 10px -5px rgba(0,0,0,0.04);
+    --radius-sm: 6px;
+    --radius-md: 10px;
+    --radius-lg: 16px;
+    --transition: 200ms ease;
+
+    /* Trolley colors */
+    --trolley-1: #ef4444;
+    --trolley-2: #3b82f6;
+    --trolley-3: #10b981;
+    --trolley-4: #f59e0b;
+    --trolley-5: #8b5cf6;
+    --trolley-6: #06b6d4;
+    --trolley-7: #ec4899;
+    --trolley-8: #84cc16;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+    background: var(--gray-100);
+    color: var(--gray-800);
+    min-height: 100vh;
+}
+
+/* =============================================================================
+   Main Container
+   ============================================================================= */
+
+.main-container {
+    padding: 0 1rem 2rem;
+    max-width: 1600px;
+    margin: 0 auto;
+}
+
+/* =============================================================================
+   Notification Area
+   ============================================================================= */
+
+.notification-area {
+    position: fixed;
+    top: 4rem;
+    right: 1rem;
+    z-index: 1050;
+    max-width: 400px;
+}
+
+.notification-area .alert {
+    box-shadow: var(--shadow-lg);
+    border: none;
+    border-radius: var(--radius-md);
+}
+
+/* =============================================================================
+   Header Bar
+   ============================================================================= */
+
+.header-bar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1rem 0;
+    margin-bottom: 1rem;
+    gap: 1rem;
+    flex-wrap: wrap;
+}
+
+.header-left {
+    flex: 0 0 auto;
+}
+
+.header-left h1 {
+    font-size: 1.75rem;
+    font-weight: 600;
+    color: var(--gray-800);
+    margin: 0;
+    letter-spacing: -0.02em;
+}
+
+.app-title {
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--gray-800);
+    margin: 0;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+
+.app-title i {
+    color: var(--primary);
+}
+
+.header-center {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    flex: 1;
+    justify-content: center;
+}
+
+.header-right {
+    display: flex;
+    gap: 0.5rem;
+}
+
+/* Buttons */
+.btn-solve {
+    background: linear-gradient(135deg, var(--primary) 0%, var(--primary-dark) 100%);
+    color: white;
+    border: none;
+    padding: 0.75rem 1.5rem;
+    border-radius: var(--radius-md);
+    font-weight: 600;
+    font-size: 1rem;
+    cursor: pointer;
+    transition: all var(--transition);
+    box-shadow: var(--shadow-md);
+}
+
+.btn-solve:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-lg);
+    background: linear-gradient(135deg, var(--primary-dark) 0%, #047857 100%);
+}
+
+.btn-stop {
+    background: linear-gradient(135deg, var(--danger) 0%, #dc2626 100%);
+    color: white;
+    border: none;
+    padding: 0.75rem 1.5rem;
+    border-radius: var(--radius-md);
+    font-weight: 600;
+    cursor: pointer;
+    transition: all var(--transition);
+    box-shadow: var(--shadow-md);
+}
+
+.btn-stop:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-lg);
+}
+
+.btn-settings, .btn-analyze {
+    background: white;
+    border: 1px solid var(--gray-200);
+    color: var(--gray-600);
+    width: 44px;
+    height: 44px;
+    border-radius: var(--radius-md);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: all var(--transition);
+}
+
+.btn-settings:hover, .btn-analyze:hover {
+    background: var(--gray-50);
+    color: var(--primary);
+    border-color: var(--primary);
+}
+
+/* Score Display */
+.score-display {
+    background: white;
+    border-radius: var(--radius-md);
+    padding: 0.5rem 1rem;
+    box-shadow: var(--shadow-sm);
+    border: 1px solid var(--gray-200);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    min-width: 120px;
+}
+
+.score-label {
+    font-size: 0.7rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--gray-500);
+}
+
+.score-value {
+    font-size: 1.1rem;
+    font-weight: 700;
+    font-family: 'SF Mono', 'Consolas', monospace;
+    color: var(--gray-800);
+}
+
+.score-display.improved {
+    animation: scoreFlash 0.5s ease-out;
+    background: linear-gradient(135deg, var(--primary-light) 0%, var(--primary) 100%);
+    border-color: var(--primary);
+}
+
+.score-display.improved .score-label,
+.score-display.improved .score-value {
+    color: white;
+}
+
+@keyframes scoreFlash {
+    0% { transform: scale(1); }
+    50% { transform: scale(1.05); box-shadow: 0 0 20px rgba(16, 185, 129, 0.5); }
+    100% { transform: scale(1); }
+}
+
+/* Solving Indicator */
+.solving-indicator {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--primary);
+    font-weight: 500;
+}
+
+.solving-spinner {
+    width: 20px;
+    height: 20px;
+    border: 2px solid var(--primary-light);
+    border-top-color: var(--primary);
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+
+/* =============================================================================
+   Settings Panel
+   ============================================================================= */
+
+.settings-panel {
+    background: white;
+    border-radius: var(--radius-lg);
+    padding: 1.5rem;
+    margin-bottom: 1rem;
+    box-shadow: var(--shadow-md);
+    border: 1px solid var(--gray-200);
+}
+
+.settings-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 1.5rem;
+    align-items: end;
+}
+
+.setting-item label {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 500;
+    color: var(--gray-700);
+    margin-bottom: 0.5rem;
+}
+
+.setting-item label i {
+    color: var(--primary);
+}
+
+.setting-item label .badge {
+    background: var(--primary);
+    color: white;
+    padding: 0.2rem 0.5rem;
+    border-radius: 4px;
+    font-size: 0.8rem;
+    margin-left: auto;
+}
+
+.setting-item input[type="range"] {
+    width: 100%;
+    accent-color: var(--primary);
+    height: 6px;
+    cursor: pointer;
+}
+
+.btn-generate {
+    background: linear-gradient(135deg, var(--info) 0%, #2563eb 100%);
+    color: white;
+    border: none;
+    padding: 0.75rem 1.25rem;
+    border-radius: var(--radius-md);
+    font-weight: 600;
+    cursor: pointer;
+    transition: all var(--transition);
+    width: 100%;
+}
+
+.btn-generate:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-md);
+}
+
+/* =============================================================================
+   Content Area
+   ============================================================================= */
+
+.content-area {
+    display: grid;
+    grid-template-columns: 140px 1fr;
+    gap: 1rem;
+    margin-bottom: 1.5rem;
+}
+
+/* Stats Sidebar */
+.stats-sidebar {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+}
+
+.stat-card {
+    background: white;
+    border-radius: var(--radius-md);
+    padding: 1rem;
+    box-shadow: var(--shadow-sm);
+    border: 1px solid var(--gray-200);
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    transition: all var(--transition);
+}
+
+.stat-card:hover {
+    transform: translateX(4px);
+    box-shadow: var(--shadow-md);
+}
+
+.stat-card .stat-icon {
+    width: 40px;
+    height: 40px;
+    background: linear-gradient(135deg, var(--primary-light) 0%, var(--primary) 100%);
+    border-radius: var(--radius-sm);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: white;
+    font-size: 1rem;
+}
+
+.stat-card .stat-info {
+    display: flex;
+    flex-direction: column;
+}
+
+.stat-card .stat-value {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: var(--gray-800);
+    line-height: 1.2;
+}
+
+.stat-card .stat-label {
+    font-size: 0.75rem;
+    color: var(--gray-500);
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+}
+
+/* Canvas Area */
+.canvas-area {
+    background: white;
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow-md);
+    border: 1px solid var(--gray-200);
+    overflow: hidden;
+    position: relative;
+}
+
+#warehouseContainer {
+    position: relative;
+    width: 100%;
+    min-height: 500px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%);
+}
+
+#warehouseCanvas {
+    display: block;
+    max-width: 100%;
+    height: auto;
+}
+
+/* Legend Overlay */
+#legendOverlay {
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
+    background: rgba(255, 255, 255, 0.95);
+    backdrop-filter: blur(8px);
+    border-radius: var(--radius-md);
+    padding: 0.75rem;
+    box-shadow: var(--shadow-md);
+    border: 1px solid var(--gray-200);
+    min-width: 140px;
+    z-index: 10;
+}
+
+.legend-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--gray-500);
+    margin-bottom: 0.5rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid var(--gray-200);
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+
+.legend-header i {
+    color: var(--primary);
+}
+
+.legend-item {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.35rem 0;
+    font-size: 0.85rem;
+    color: var(--gray-600);
+    cursor: pointer;
+    border-radius: var(--radius-sm);
+    transition: all var(--transition);
+}
+
+.legend-item:hover {
+    background: var(--gray-100);
+    padding-left: 0.5rem;
+}
+
+.legend-color {
+    width: 16px;
+    height: 16px;
+    border-radius: 4px;
+    flex-shrink: 0;
+}
+
+.legend-text {
+    flex: 1;
+    font-weight: 500;
+}
+
+.legend-distance {
+    font-size: 0.75rem;
+    color: var(--gray-400);
+    font-family: 'SF Mono', monospace;
+}
+
+/* =============================================================================
+   Trolley Section
+   ============================================================================= */
+
+.trolley-section {
+    margin-top: 1rem;
+}
+
+.section-header {
+    margin-bottom: 1rem;
+}
+
+.section-header h2 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--gray-800);
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin: 0;
+}
+
+.section-header h2 i {
+    color: var(--primary);
+}
+
+.trolley-cards-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+    gap: 1rem;
+}
+
+/* Trolley Card */
+.trolley-card {
+    background: white;
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow-sm);
+    border: 1px solid var(--gray-200);
+    overflow: hidden;
+    transition: all var(--transition);
+    cursor: pointer;
+}
+
+.trolley-card:hover {
+    box-shadow: var(--shadow-lg);
+    transform: translateY(-2px);
+}
+
+.trolley-card-header {
+    padding: 1rem;
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    border-bottom: 1px solid var(--gray-100);
+}
+
+.trolley-color-badge {
+    width: 12px;
+    height: 40px;
+    border-radius: 4px;
+    flex-shrink: 0;
+}
+
+.trolley-card-info {
+    flex: 1;
+}
+
+.trolley-card-title {
+    font-weight: 600;
+    font-size: 1rem;
+    color: var(--gray-800);
+}
+
+.trolley-card-stats {
+    font-size: 0.85rem;
+    color: var(--gray-500);
+    margin-top: 0.25rem;
+}
+
+.trolley-capacity-bar {
+    width: 80px;
+    height: 8px;
+    background: var(--gray-200);
+    border-radius: 4px;
+    overflow: hidden;
+}
+
+.trolley-capacity-fill {
+    height: 100%;
+    border-radius: 4px;
+    transition: width var(--transition);
+}
+
+.trolley-capacity-fill.low { background: var(--primary); }
+.trolley-capacity-fill.medium { background: var(--warning); }
+.trolley-capacity-fill.high { background: var(--danger); }
+
+.trolley-card-body {
+    padding: 1rem;
+    background: var(--gray-50);
+    max-height: 200px;
+    overflow-y: auto;
+}
+
+.trolley-items-list {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+}
+
+.trolley-item {
+    background: white;
+    border: 1px solid var(--gray-200);
+    border-radius: var(--radius-sm);
+    padding: 0.35rem 0.6rem;
+    font-size: 0.8rem;
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+}
+
+.trolley-item-number {
+    background: var(--primary);
+    color: white;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.7rem;
+    font-weight: 600;
+}
+
+.trolley-empty {
+    color: var(--gray-400);
+    font-style: italic;
+    padding: 1rem;
+    text-align: center;
+}
+
+/* =============================================================================
+   3D Bucket View Modal
+   ============================================================================= */
+
+.bucket-modal .modal-body {
+    padding: 0;
+    background: linear-gradient(135deg, #1e293b 0%, #334155 100%);
+    min-height: 400px;
+}
+
+#bucketViewCanvas {
+    width: 100%;
+    height: 400px;
+    display: block;
+}
+
+.bucket-modal-stats {
+    background: rgba(255, 255, 255, 0.1);
+    backdrop-filter: blur(8px);
+    padding: 1rem;
+    display: flex;
+    justify-content: space-around;
+    border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.bucket-stat {
+    text-align: center;
+    color: white;
+}
+
+.bucket-stat-value {
+    font-size: 1.5rem;
+    font-weight: 700;
+}
+
+.bucket-stat-label {
+    font-size: 0.75rem;
+    opacity: 0.7;
+    text-transform: uppercase;
+}
+
+/* =============================================================================
+   Modal Styling
+   ============================================================================= */
+
+.modal-content {
+    border: none;
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+    box-shadow: var(--shadow-xl);
+}
+
+.modal-header {
+    background: var(--gray-50);
+    border-bottom: 1px solid var(--gray-200);
+    padding: 1rem 1.5rem;
+}
+
+.modal-title {
+    font-weight: 600;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+
+.modal-title i {
+    color: var(--primary);
+}
+
+.modal-body {
+    padding: 1.5rem;
+}
+
+.modal-footer {
+    border-top: 1px solid var(--gray-200);
+    padding: 1rem 1.5rem;
+}
+
+/* Score Analysis */
+.constraint-group {
+    margin-bottom: 1rem;
+    border: 1px solid var(--gray-200);
+    border-radius: var(--radius-md);
+    overflow: hidden;
+}
+
+.constraint-header {
+    background: var(--gray-50);
+    padding: 0.75rem 1rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    cursor: pointer;
+}
+
+.constraint-name {
+    font-weight: 600;
+    color: var(--gray-800);
+}
+
+.constraint-score {
+    font-family: 'SF Mono', monospace;
+    font-size: 0.9rem;
+}
+
+.constraint-score.hard { color: var(--danger); }
+.constraint-score.soft { color: var(--warning); }
+
+/* =============================================================================
+   Responsive
+   ============================================================================= */
+
+@media (max-width: 768px) {
+    .header-bar {
+        flex-direction: column;
+        align-items: stretch;
+    }
+
+    .header-center {
+        order: 3;
+        justify-content: center;
+    }
+
+    .header-right {
+        position: absolute;
+        right: 1rem;
+        top: 1rem;
+    }
+
+    .content-area {
+        grid-template-columns: 1fr;
+    }
+
+    .stats-sidebar {
+        flex-direction: row;
+        flex-wrap: wrap;
+    }
+
+    .stat-card {
+        flex: 1;
+        min-width: 120px;
+    }
+
+    .trolley-cards-grid {
+        grid-template-columns: 1fr;
+    }
+
+    #legendOverlay {
+        position: relative;
+        top: auto;
+        right: auto;
+        margin: 1rem;
+    }
+}
+
+/* =============================================================================
+   Animations
+   ============================================================================= */
+
+@keyframes fadeIn {
+    from { opacity: 0; transform: translateY(10px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes pulse {
+    0%, 100% { transform: scale(1); }
+    50% { transform: scale(1.02); }
+}
+
+.fade-in {
+    animation: fadeIn 0.3s ease-out;
+}
+
+.pulse {
+    animation: pulse 2s ease-in-out infinite;
+}
+
+/* Value change animation */
+.value-changed {
+    animation: valueChange 0.5s ease-out;
+}
+
+@keyframes valueChange {
+    0% { transform: scale(1); color: var(--primary); }
+    50% { transform: scale(1.2); }
+    100% { transform: scale(1); color: inherit; }
+}

static/warehouse-api.js

@@ -0,0 +1,371 @@
+const LEFT = 'LEFT';
+const RIGHT = 'RIGHT';
+
+const WAREHOUSE_COLUMNS = ['A', 'B', 'C', 'D', 'E'];
+const WAREHOUSE_ROWS = ['1', '2', '3'];
+
+const WAREHOUSE_PADDING_TOP = 100;
+const WAREHOUSE_PADDING_LEFT = 100;
+
+const SHELVING_PADDING = 80;
+const SHELVING_WIDTH = 150;
+const SHELVING_HEIGHT = 300;
+const SHELVING_ROWS = 10;
+
+const SHELVING_LINE_WIDTH = 5;
+const SHELVING_STROKE_STYLE = 'green';
+const SHELVING_LINE_JOIN = 'bevel';
+
+const TROLLEY_PATH_LINE_WIDTH = 5;
+const TROLLEY_PATH_LINE_JOIN = 'round';
+
+const SHELVINGS_MAP = new Map();
+
+function shelvingId(i, j) {
+    return '(' + i + ',' + j + ')';
+}
+
+class Point {
+    x = 0;
+    y = 0;
+
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+}
+
+class ShelvingShape {
+    id;
+    x = 0;
+    y = 0;
+    width = 0;
+    height = 0;
+
+    constructor(id, x, y, width, height) {
+        this.id = id;
+        this.x = x;
+        this.y = y;
+        this.width = width;
+        this.height = height;
+    }
+}
+
+class WarehouseLocation {
+    shelvingId;
+    side;
+    row;
+
+    constructor(shelvingId, side, row) {
+        this.shelvingId = shelvingId;
+        this.side = side;
+        this.row = row;
+    }
+}
+
+/**
+ * Returns the WarehouseCanvas.
+ */
+function getWarehouseCanvasContext() {
+    return document.getElementById('warehouseCanvas').getContext('2d');
+}
+
+/**
+ * Clears the WarehouseCanvas.
+ */
+function clearWarehouseCanvas() {
+    const canvas = document.getElementById('warehouseCanvas');
+    const ctx = canvas.getContext('2d');
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    const parentWidth = canvas.parentElement.clientWidth;
+    const parentHeight = canvas.parentElement.clientHeight;
+    const contentWidth = 2 * WAREHOUSE_PADDING_LEFT + (SHELVING_WIDTH + SHELVING_PADDING) * WAREHOUSE_COLUMNS.length;
+    const contentHeight = 2 * WAREHOUSE_PADDING_TOP + (SHELVING_HEIGHT + SHELVING_PADDING) * WAREHOUSE_ROWS.length;
+    const minToFillParent = Math.min(parentWidth / contentWidth, parentHeight / contentHeight);
+    const xOffset = (parentWidth - (contentWidth * minToFillParent)) / 2;
+    const yOffset = (parentHeight - (contentHeight * minToFillParent)) / 2;
+    canvas.width = parentWidth;
+    canvas.height = parentHeight;
+    ctx.translate(xOffset, yOffset);
+    ctx.scale(minToFillParent, minToFillParent);
+}
+
+/**
+ * Draws the WarehouseStructure on the WarehouseCanvas.
+ */
+function drawWarehouse() {
+    const ctx = getWarehouseCanvasContext();
+    let x = WAREHOUSE_PADDING_LEFT;
+    for (let column = 0; column < WAREHOUSE_COLUMNS.length; column++) {
+        let y = WAREHOUSE_PADDING_TOP;
+        for (let row = 0; row < WAREHOUSE_ROWS.length; row++) {
+            const shelving = new ShelvingShape(shelvingId(WAREHOUSE_COLUMNS[column], WAREHOUSE_ROWS[row]), x, y, SHELVING_WIDTH, SHELVING_HEIGHT);
+            drawShelving(ctx, shelving);
+            SHELVINGS_MAP.set(shelving.id, shelving);
+            y = y + SHELVING_HEIGHT + SHELVING_PADDING;
+        }
+        x = x + SHELVING_WIDTH + SHELVING_PADDING;
+    }
+}
+
+/**
+ * Draws a ShelvingShape on the Warehouse canvas.
+ */
+function drawShelving(ctx, shelving) {
+    ctx.strokeStyle = SHELVING_STROKE_STYLE;
+    ctx.lineJoin = SHELVING_LINE_JOIN;
+    ctx.lineWidth = SHELVING_LINE_WIDTH;
+    ctx.strokeRect(shelving.x, shelving.y, shelving.width, shelving.height);
+
+    ctx.font = '30px serif';
+    ctx.textAlign = 'center';
+    ctx.fillStyle = SHELVING_STROKE_STYLE
+
+    const shelvingTextParts = shelving.id.split(',');
+    ctx.fillText(shelvingTextParts[0].substring(1) + shelvingTextParts[1].substring(0, shelvingTextParts[1].length - 1),
+               shelving.x + shelving.width / 2, shelving.y + shelving.height / 2);
+}
+
+/**
+ * Draws the path travelled by a Trolley.
+ */
+function drawTrolleyPath(strokeStyle, warehouseLocations, trolleyIndex, trolleyCount) {
+    const ctx = getWarehouseCanvasContext();
+    ctx.lineJoin = TROLLEY_PATH_LINE_JOIN;
+    ctx.lineWidth = TROLLEY_PATH_LINE_WIDTH;
+    ctx.strokeStyle = strokeStyle;
+    drawWarehousePath(warehouseLocations, trolleyIndex, trolleyCount);
+}
+
+function drawTrolleyText(strokeStyle, warehouseLocations, trolleyIndex, trolleyCount) {
+    const ctx = getWarehouseCanvasContext();
+    ctx.lineJoin = TROLLEY_PATH_LINE_JOIN;
+    ctx.lineWidth = TROLLEY_PATH_LINE_WIDTH;
+    ctx.strokeStyle = strokeStyle;
+    drawTextForTrolley(strokeStyle, warehouseLocations, trolleyIndex, trolleyCount);
+}
+
+/**
+ * Draws a path composed of WarehouseLocations.
+ */
+function drawWarehousePath(warehouseLocations, trolleyIndex, trolleyCount) {
+    const ctx = getWarehouseCanvasContext();
+    const startLocation = warehouseLocations[0];
+    const startShelving = SHELVINGS_MAP.get(startLocation.shelvingId);
+    const startPoint = location2Point(startShelving, startLocation.side, startLocation.row, trolleyIndex, trolleyCount);
+    let lastPoint = startPoint;
+    let lastShelving = startShelving;
+    let lastSide = startLocation.side;
+    let lastRow = startLocation.row;
+
+    ctx.beginPath();
+    ctx.moveTo(startPoint.x, startPoint.y);
+    ctx.arc(startPoint.x, startPoint.y, 5, 0, 2 * Math.PI);
+
+    for (let i = 1; i < warehouseLocations.length; i++) {
+        const location = warehouseLocations[i];
+        const shelving = SHELVINGS_MAP.get(location.shelvingId);
+        const side = location.side;
+        const row = location.row;
+        const point = location2Point(shelving, location.side, location.row, trolleyIndex, trolleyCount);
+        drawWarehousePathBetweenShelves(ctx, trolleyIndex, trolleyCount, lastShelving, lastSide, lastRow, lastPoint,
+                shelving, side, row, point);
+        ctx.arc(point.x, point.y, 5, 0, 2 * Math.PI);
+        lastPoint = point;
+        lastShelving = shelving;
+        lastSide = side;
+        lastRow = row;
+    }
+    ctx.stroke();
+    ctx.closePath();
+}
+
+function drawTextForTrolley(strokeStyle, warehouseLocations, trolleyIndex, trolleyCount) {
+    const ctx = getWarehouseCanvasContext();
+
+    ctx.fillStyle = strokeStyle;
+    ctx.strokeStyle = "#000000";
+    let overlappingOrderTexts = [];
+    const SHELVING_ROW_HEIGHT = SHELVING_HEIGHT / SHELVING_ROWS;
+    const TEXT_SEPERATOR_HEIGHT = SHELVING_ROW_HEIGHT * 4;
+    const SEPERATION_PER_TROLLEY = TEXT_SEPERATOR_HEIGHT / trolleyCount;
+    for (let i = 0; i < warehouseLocations.length; i++) {
+        const location = warehouseLocations[i];
+        const shelving = SHELVINGS_MAP.get(location.shelvingId);
+        const point = location2Point(shelving, location.side, location.row, trolleyIndex, trolleyCount);
+        const pointFlooredRow = Math.floor(point.y / TEXT_SEPERATOR_HEIGHT) * TEXT_SEPERATOR_HEIGHT;
+
+        point.y = pointFlooredRow + SEPERATION_PER_TROLLEY * trolleyIndex;
+        addToOverlap(overlappingOrderTexts, i.toString(10), point);
+    }
+
+    for (let i = 0; i < overlappingOrderTexts.length; i++) {
+        const overlappingOrders = overlappingOrderTexts[i];
+        const text = '(' + overlappingOrders.orders.join(', ') + ')';
+
+        ctx.strokeText(text, overlappingOrders.x, overlappingOrders.y);
+        ctx.fillText(text, overlappingOrders.x, overlappingOrders.y);
+    }
+}
+
+function addToOverlap(overlappingOrderTexts, orderText, orderPoint) {
+    const SHELVING_ROW_HEIGHT = SHELVING_HEIGHT / SHELVING_ROWS;
+    for (let i = 0; i < overlappingOrderTexts.length; i++) {
+        const overlappingOrderText = overlappingOrderTexts[i];
+        const distance = Math.abs(orderPoint.x - overlappingOrderText.x) + Math.abs(orderPoint.y - overlappingOrderText.y);
+        if (distance < 2 * SHELVING_ROW_HEIGHT) {
+            overlappingOrderText.orders.push(orderText);
+            return;
+        }
+    }
+    const newOverlappingOrderText = {
+        orders: [orderText],
+        x: orderPoint.x,
+        y: orderPoint.y,
+    };
+    overlappingOrderTexts.push(newOverlappingOrderText);
+}
+
+/**
+ * Draw a path around shelves connecting two WarehouseLocations
+ */
+function drawWarehousePathBetweenShelves(ctx, trolleyIndex, trolleyCount,
+        startShelving, startSide, startRow, startPoint,
+        endShelving, endSide, endRow, endPoint) {
+    ctx.moveTo(startPoint.x, startPoint.y);
+    if (startShelving === endShelving) {
+        if (startSide === endSide) {
+            // Two points on the same shelf and same side
+            ctx.lineTo(endPoint.x, endPoint.y);
+        } else {
+            // Two points on the same shelf but different sides
+            const isAbove = startRow + endRow < 2*SHELVING_ROWS - startRow - endRow;
+            const aisleChangeStartPoint = location2AisleLane(startShelving, startSide, isAbove, trolleyIndex, trolleyCount);
+            const aisleChangeEndPoint = location2AisleLane(endShelving, endSide, isAbove, trolleyIndex, trolleyCount);
+            ctx.lineTo(aisleChangeStartPoint.x, aisleChangeStartPoint.y);
+            ctx.lineTo(aisleChangeEndPoint.x, aisleChangeEndPoint.y);
+            ctx.lineTo(endPoint.x, endPoint.y);
+        }
+    } else if (startShelving.x === endShelving.x) {
+        if (startSide === endSide) {
+            // Same Aisle, different rows
+            ctx.lineTo(endPoint.x, endPoint.y);
+        } else {
+            // Different Aisle
+            if (startShelving.y < endShelving.y) {
+                // Going up
+                const aisleChangeStartPoint = location2AisleLane(endShelving, startSide, false, trolleyIndex, trolleyCount);
+                const aisleChangeEndPoint = location2AisleLane(endShelving, endSide, false, trolleyIndex, trolleyCount);
+                ctx.lineTo(aisleChangeStartPoint.x, aisleChangeStartPoint.y);
+                ctx.lineTo(aisleChangeEndPoint.x, aisleChangeEndPoint.y);
+                ctx.lineTo(endPoint.x, endPoint.y);
+            } else {
+                // Going down
+                const aisleChangeStartPoint = location2AisleLane(endShelving, startSide, true, trolleyIndex, trolleyCount);
+                const aisleChangeEndPoint = location2AisleLane(endShelving, endSide, true, trolleyIndex, trolleyCount);
+                ctx.lineTo(aisleChangeStartPoint.x, aisleChangeStartPoint.y);
+                ctx.lineTo(aisleChangeEndPoint.x, aisleChangeEndPoint.y);
+                ctx.lineTo(endPoint.x, endPoint.y);
+            }
+        }
+    } else if (startShelving.y === endShelving.y) {
+        const startColumn = shelvingToColumn(startShelving);
+        const endColumn = shelvingToColumn(endShelving);
+        if (startSide === LEFT) {
+            if (endSide === RIGHT && endColumn === startColumn - 1) {
+                // Same Aisle, different shelving
+                ctx.lineTo(endPoint.x, startPoint.y);
+                ctx.lineTo(endPoint.x, endPoint.y);
+            } else {
+                drawWarehousePathBetweenColumns(ctx, trolleyIndex, trolleyCount,
+                        startShelving, startSide, startRow, startPoint,
+                        endShelving, endSide, endRow, endPoint);
+            }
+        } else {
+            if (endSide === LEFT && endColumn === startColumn + 1) {
+                // Same Aisle, different shelving
+                ctx.lineTo(endPoint.x, startPoint.y);
+                ctx.lineTo(endPoint.x, endPoint.y);
+            } else {
+                drawWarehousePathBetweenColumns(ctx, trolleyIndex, trolleyCount,
+                        startShelving, startSide, startRow, startPoint,
+                        endShelving, endSide, endRow, endPoint);
+            }
+        }
+    } else {
+        drawWarehousePathBetweenColumns(ctx, trolleyIndex, trolleyCount,
+                startShelving, startSide, startRow, startPoint,
+                endShelving, endSide, endRow, endPoint);
+    }
+}
+
+/**
+ * Draws a path between shelvings in two different columns
+ */
+function drawWarehousePathBetweenColumns(ctx, trolleyIndex, trolleyCount,
+        startShelving, startSide, startRow, startPoint,
+        endShelving, endSide, endRow, endPoint) {
+    if (startShelving.y === endShelving.y) {
+        const isAbove = startRow + endRow < 2*SHELVING_ROWS - startRow - endRow;
+        const aisleChangeStartPoint = location2AisleLane(startShelving, startSide, isAbove, trolleyIndex, trolleyCount);
+        const aisleChangeEndPoint = location2AisleLane(endShelving, endSide, isAbove, trolleyIndex, trolleyCount);
+        ctx.lineTo(aisleChangeStartPoint.x, aisleChangeStartPoint.y);
+        ctx.lineTo(aisleChangeEndPoint.x, aisleChangeEndPoint.y);
+        ctx.lineTo(endPoint.x, endPoint.y);
+    } else {
+        const isAbove = endShelving.y < startShelving.y;
+        const aisleChangeStartPoint = location2AisleLane(startShelving, startSide, isAbove, trolleyIndex, trolleyCount);
+        const aisleChangeEndPoint = location2AisleLane(endShelving, endSide, isAbove, trolleyIndex, trolleyCount);
+        ctx.lineTo(aisleChangeStartPoint.x, aisleChangeStartPoint.y);
+        ctx.lineTo(aisleChangeEndPoint.x, aisleChangeStartPoint.y);
+        ctx.lineTo(aisleChangeEndPoint.x, aisleChangeEndPoint.y);
+        ctx.lineTo(endPoint.x, endPoint.y);
+    }
+}
+
+/**
+ * Transforms a WarehouseLocation into an absolute Point in the canvas.
+ */
+function location2Point(shelving, side, row, trolleyIndex, trolleyCount) {
+    let x;
+    let y;
+    if (side === LEFT) {
+        x = shelving.x - SHELVING_LINE_WIDTH - ((0.5 * SHELVING_PADDING) / trolleyCount) * trolleyIndex;
+    } else {
+        x = shelving.x + shelving.width + SHELVING_LINE_WIDTH + ((0.5 * SHELVING_PADDING) / trolleyCount) * trolleyIndex;
+    }
+    const rowWidth = shelving.height / SHELVING_ROWS;
+    y = shelving.y + row * rowWidth;
+
+    return new Point(x, y);
+}
+
+/**
+ * Get location for the aisle lane above or below a shelving side
+ */
+function location2AisleLane(shelving, side, isAbove, trolleyIndex, trolleyCount) {
+    let x;
+    let y;
+    if (side === LEFT) {
+        x = shelving.x - SHELVING_LINE_WIDTH - ((0.5 * SHELVING_PADDING) / trolleyCount) * trolleyIndex;
+    } else {
+        x = shelving.x + SHELVING_LINE_WIDTH + shelving.width + ((0.5 * SHELVING_PADDING) / trolleyCount) * trolleyIndex;
+    }
+
+    if (isAbove) {
+        y = shelving.y - 0.25 * SHELVING_PADDING - (((0.25 * SHELVING_PADDING) / trolleyCount) * trolleyIndex);
+    } else {
+        y = shelving.y + shelving.height + 0.25 * SHELVING_PADDING + (((0.25 * SHELVING_PADDING) / trolleyCount) * trolleyIndex);
+    }
+
+    return new Point(x, y);
+}
+
+/**
+ * Get the column number of a shelving
+ */
+function shelvingToColumn(shelving) {
+    const COLUMN_WIDTH = SHELVING_WIDTH + SHELVING_PADDING;
+    return (shelving.x - WAREHOUSE_PADDING_LEFT) / COLUMN_WIDTH;
+}

static/webjars/solverforge/css/solverforge-webui.css

@@ -0,0 +1,68 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-green-1-rgb: #10b981;
+    --ts-green-2-rgb: #059669;
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link:hover {
+    color: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link.active:hover {
+    color: var(--ts-white-rgb);
+}

static/webjars/solverforge/js/solverforge-webui.js

@@ -0,0 +1,142 @@
+function replaceSolverForgeAutoHeaderFooter() {
+  const solverforgeHeader = $("header#solverforge-auto-header");
+  if (solverforgeHeader != null) {
+    solverforgeHeader.addClass("bg-black")
+    solverforgeHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/solverforge/img/solverforge-horizontal-white.svg" alt="SolverForge logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const solverforgeFooter = $("footer#solverforge-auto-footer");
+  if (solverforgeFooter != null) {
+    solverforgeFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

static/webjars/timefold/css/timefold-webui.css

@@ -0,0 +1,60 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-violet-1-rgb);
+}

static/webjars/timefold/js/timefold-webui.js

@@ -0,0 +1,142 @@
+function replaceTimefoldAutoHeaderFooter() {
+  const timefoldHeader = $("header#timefold-auto-header");
+  if (timefoldHeader != null) {
+    timefoldHeader.addClass("bg-black")
+    timefoldHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://timefold.ai">
+            <img src="/timefold/img/timefold-logo-horizontal-negative.svg" alt="Timefold logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const timefoldFooter = $("footer#timefold-auto-footer");
+  if (timefoldFooter != null) {
+    timefoldFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://timefold.ai">Timefold</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://timefold.ai/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/TimefoldAI/timefold-solver-python">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="https://timefold.ai/product/support/">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

tests/test_constraints.py

@@ -0,0 +1,202 @@
+from solverforge_legacy.solver.test import ConstraintVerifier
+
+from order_picking.domain import (
+    Product, Order, OrderItem, Trolley, TrolleyStep, OrderPickingSolution
+)
+from order_picking.warehouse import WarehouseLocation, Side, new_shelving_id, Column, Row
+from order_picking.constraints import (
+    define_constraints,
+    required_number_of_buckets,
+    minimize_order_split_by_trolley,
+    minimize_distance_from_previous_step,
+    minimize_distance_from_last_step_to_origin,
+)
+
+
+# Test locations
+LOCATION_A1_LEFT_5 = WarehouseLocation(
+    shelving_id=new_shelving_id(Column.COL_A, Row.ROW_1),
+    side=Side.LEFT,
+    row=5
+)
+LOCATION_A1_LEFT_8 = WarehouseLocation(
+    shelving_id=new_shelving_id(Column.COL_A, Row.ROW_1),
+    side=Side.LEFT,
+    row=8
+)
+LOCATION_B1_LEFT_3 = WarehouseLocation(
+    shelving_id=new_shelving_id(Column.COL_B, Row.ROW_1),
+    side=Side.LEFT,
+    row=3
+)
+LOCATION_E3_RIGHT_9 = WarehouseLocation(
+    shelving_id=new_shelving_id(Column.COL_E, Row.ROW_3),
+    side=Side.RIGHT,
+    row=9
+)
+
+# Bucket capacity for tests (48,000 cm3)
+BUCKET_CAPACITY = 48000
+
+
+constraint_verifier = ConstraintVerifier.build(
+    define_constraints, OrderPickingSolution, Trolley, TrolleyStep
+)
+
+
+def create_product(id: str, volume: int, location: WarehouseLocation) -> Product:
+    return Product(id=id, name=f"Product {id}", volume=volume, location=location)
+
+
+def create_order_with_items(order_id: str, products: list[Product]) -> tuple[Order, list[OrderItem]]:
+    order = Order(id=order_id, items=[])
+    items = []
+    for i, product in enumerate(products):
+        item = OrderItem(id=f"{order_id}-{i}", order=order, product=product)
+        order.items.append(item)
+        items.append(item)
+    return order, items
+
+
+def connect(trolley: Trolley, *steps: TrolleyStep):
+    """Set up trolley-step relationships."""
+    trolley.steps = list(steps)
+    for i, step in enumerate(steps):
+        step.trolley = trolley
+        step.previous_step = steps[i - 1] if i > 0 else None
+        step.next_step = steps[i + 1] if i < len(steps) - 1 else None
+
+
+class TestRequiredNumberOfBuckets:
+    def test_not_penalized_when_under_capacity(self):
+        """Trolley with enough buckets should not be penalized."""
+        trolley = Trolley(
+            id="1",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        product = create_product("p1", 10000, LOCATION_B1_LEFT_3)
+        order, items = create_order_with_items("o1", [product])
+        step = TrolleyStep(id="s1", order_item=items[0])
+
+        connect(trolley, step)
+
+        constraint_verifier.verify_that(required_number_of_buckets).given(
+            trolley, step
+        ).penalizes_by(0)
+
+    def test_penalized_when_over_bucket_count(self):
+        """Trolley with too few buckets should be penalized."""
+        trolley = Trolley(
+            id="1",
+            bucket_count=1,  # Only 1 bucket
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        # Create order with volume requiring 2 buckets
+        product1 = create_product("p1", 40000, LOCATION_B1_LEFT_3)
+        product2 = create_product("p2", 40000, LOCATION_A1_LEFT_8)
+        order, items = create_order_with_items("o1", [product1, product2])
+        step1 = TrolleyStep(id="s1", order_item=items[0])
+        step2 = TrolleyStep(id="s2", order_item=items[1])
+
+        connect(trolley, step1, step2)
+
+        # Total volume: 80000, bucket capacity: 48000
+        # Required buckets: ceil(80000/48000) = 2
+        # Available: 1, excess: 1
+        constraint_verifier.verify_that(required_number_of_buckets).given(
+            trolley, step1, step2
+        ).penalizes_by(1)
+
+
+class TestMinimizeOrderSplitByTrolley:
+    def test_single_trolley_per_order(self):
+        """Order on single trolley should be minimally penalized."""
+        trolley = Trolley(
+            id="1",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        product = create_product("p1", 10000, LOCATION_B1_LEFT_3)
+        order, items = create_order_with_items("o1", [product])
+        step = TrolleyStep(id="s1", order_item=items[0])
+
+        connect(trolley, step)
+
+        # 1 trolley * 1000 = 1000
+        constraint_verifier.verify_that(minimize_order_split_by_trolley).given(
+            trolley, step
+        ).penalizes_by(1000)
+
+    def test_order_split_across_trolleys(self):
+        """Order split across trolleys should be penalized more."""
+        trolley1 = Trolley(
+            id="1",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        trolley2 = Trolley(
+            id="2",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        product1 = create_product("p1", 10000, LOCATION_B1_LEFT_3)
+        product2 = create_product("p2", 10000, LOCATION_A1_LEFT_8)
+        order, items = create_order_with_items("o1", [product1, product2])
+        step1 = TrolleyStep(id="s1", order_item=items[0])
+        step2 = TrolleyStep(id="s2", order_item=items[1])
+
+        connect(trolley1, step1)
+        connect(trolley2, step2)
+
+        # 2 trolleys * 1000 = 2000
+        constraint_verifier.verify_that(minimize_order_split_by_trolley).given(
+            trolley1, trolley2, step1, step2
+        ).penalizes_by(2000)
+
+
+class TestMinimizeDistanceFromPreviousStep:
+    def test_distance_from_trolley_start(self):
+        """Distance from trolley start location to first step."""
+        trolley = Trolley(
+            id="1",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        product = create_product("p1", 10000, LOCATION_A1_LEFT_8)
+        order, items = create_order_with_items("o1", [product])
+        step = TrolleyStep(id="s1", order_item=items[0])
+
+        connect(trolley, step)
+
+        # Same shelving, same side: |8 - 5| = 3 meters
+        constraint_verifier.verify_that(minimize_distance_from_previous_step).given(
+            trolley, step
+        ).penalizes_by(3)
+
+
+class TestMinimizeDistanceFromLastStepToOrigin:
+    def test_distance_back_to_origin(self):
+        """Distance from last step back to trolley start location."""
+        trolley = Trolley(
+            id="1",
+            bucket_count=4,
+            bucket_capacity=BUCKET_CAPACITY,
+            location=LOCATION_A1_LEFT_5
+        )
+        product = create_product("p1", 10000, LOCATION_A1_LEFT_8)
+        order, items = create_order_with_items("o1", [product])
+        step = TrolleyStep(id="s1", order_item=items[0])
+
+        connect(trolley, step)
+
+        # Same shelving, same side: |8 - 5| = 3 meters
+        constraint_verifier.verify_that(minimize_distance_from_last_step_to_origin).given(
+            trolley, step
+        ).penalizes_by(3)