Merge branch 'dev' into agent/dex/CUB-39-filament-usage-sync

backend/API/Controllers/CostAnalysisController.cs

@@ -0,0 +1,108 @@
+using Extrudex.API.DTOs.PrintJobs;
+using Extrudex.Domain.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Extrudex.API.Controllers;
+
+/// <summary>
+/// Controller for cost analysis endpoints. Provides spool-level
+/// cost breakdowns and aggregated COGS reporting.
+/// </summary>
+[ApiController]
+[Route("api/cost-analysis")]
+public class CostAnalysisController : ControllerBase
+{
+    private readonly ICostPerPrintService _costService;
+    private readonly ILogger<CostAnalysisController> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CostAnalysisController"/> class.
+    /// </summary>
+    /// <param name="costService">The cost-per-print calculation service.</param>
+    /// <param name="logger">The logger for diagnostic output.</param>
+    public CostAnalysisController(
+        ICostPerPrintService costService,
+        ILogger<CostAnalysisController> logger)
+    {
+        _costService = costService;
+        _logger = logger;
+    }
+
+    // ── POST /api/cost-analysis/spool ────────────────────────────
+
+    /// <summary>
+    /// Calculates cost breakdowns for all print jobs associated with a specific spool.
+    /// Returns per-job costs plus an aggregated total. Jobs with missing cost data
+    /// include warnings and null cost fields — the endpoint never throws for missing data.
+    /// </summary>
+    /// <param name="request">The request containing the spool identifier.</param>
+    /// <returns>A spool-level cost summary with per-job breakdowns.</returns>
+    /// <response code="200">Returns the spool cost breakdown with per-job details.</response>
+    /// <response code="404">If the spool has no print jobs.</response>
+    [HttpPost("spool")]
+    [ProducesResponseType(typeof(SpoolCostResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<SpoolCostResponse>> CalculateSpoolCost([FromBody] SpoolCostRequest request)
+    {
+        _logger.LogDebug("Calculating cost breakdown for spool {SpoolId}", request.SpoolId);
+
+        var results = await _costService.CalculateBySpoolAsync(request.SpoolId);
+
+        if (results.Count == 0)
+        {
+            return NotFound(new { error = $"No print jobs found for spool with ID '{request.SpoolId}'." });
+        }
+
+        // Build the spool-level summary
+        var firstResult = results[0];
+        var jobResponses = results.Select(MapCostToResponse).ToList();
+
+        // Aggregate total cost and grams — only include jobs that have a valid cost
+        var calculableJobs = results.Where(r => r.CostPerPrint.HasValue).ToList();
+        var totalCost = calculableJobs.Count == results.Count
+            ? Math.Round(calculableJobs.Sum(r => r.CostPerPrint!.Value), 4)
+            : (decimal?)null;
+
+        var aggregateWarnings = new List<string>();
+        if (calculableJobs.Count < results.Count)
+        {
+            aggregateWarnings.Add(
+                $"{results.Count - calculableJobs.Count} of {results.Count} print jobs have missing cost data. " +
+                "Total cost reflects only jobs with complete data.");
+        }
+
+        var response = new SpoolCostResponse
+        {
+            SpoolId = request.SpoolId,
+            SpoolSerial = firstResult.SpoolSerial,
+            PurchasePrice = firstResult.PurchasePrice,
+            WeightTotalGrams = firstResult.WeightTotalGrams,
+            CostPerGram = firstResult.CostPerGram,
+            TotalGramsConsumed = results.Sum(r => r.GramsDerived),
+            TotalCost = totalCost,
+            JobCount = results.Count,
+            Jobs = jobResponses,
+            Warnings = aggregateWarnings
+        };
+
+        return Ok(response);
+    }
+
+    /// <summary>
+    /// Maps a domain CostPerPrintResult to an API CostPerPrintResponse DTO.
+    /// </summary>
+    private static CostPerPrintResponse MapCostToResponse(CostPerPrintResult r) => new()
+    {
+        PrintJobId = r.PrintJobId,
+        PrintName = r.PrintName,
+        SpoolId = r.SpoolId,
+        SpoolSerial = r.SpoolSerial,
+        MmExtruded = r.MmExtruded,
+        GramsDerived = r.GramsDerived,
+        PurchasePrice = r.PurchasePrice,
+        WeightTotalGrams = r.WeightTotalGrams,
+        CostPerGram = r.CostPerGram,
+        CostPerPrint = r.CostPerPrint,
+        Warnings = r.Warnings
+    };
+}

backend/API/Controllers/PrintJobsController.cs

@@ -413,6 +413,92 @@ public class PrintJobsController : ControllerBase
         return NoContent();
     }
 
+    // ── GET /api/printjobs/{id}/cost-summary ──────────────────────────
+
+    /// <summary>
+    /// Gets the material cost summary for a specific print job.
+    /// Calculates total material cost from filament usage (grams derived)
+    /// and the spool's purchase price. Returns warnings instead of errors
+    /// when cost data is unavailable.
+    /// </summary>
+    /// <param name="id">The unique identifier of the print job.</param>
+    /// <returns>A cost summary with breakdown and any warnings about missing data.</returns>
+    /// <response code="200">Returns the cost summary. Warnings field lists any missing data.</response>
+    /// <response code="404">If the print job with the given ID is not found.</response>
+    [HttpGet("{id:guid}/cost-summary")]
+    [ProducesResponseType(typeof(CostSummaryResponse), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<CostSummaryResponse>> GetCostSummary(Guid id)
+    {
+        _logger.LogDebug("Getting cost summary for print job {Id}", id);
+
+        var job = await _dbContext.PrintJobs
+            .Include(j => j.Spool)
+                .ThenInclude(s => s!.MaterialBase)
+            .FirstOrDefaultAsync(j => j.Id == id);
+
+        if (job is null)
+        {
+            _logger.LogWarning("Print job {Id} not found for cost summary", id);
+            return NotFound(new { error = $"Print job with ID '{id}' not found." });
+        }
+
+        var warnings = new List<string>();
+        var spool = job.Spool;
+
+        // Build response with what we have
+        var response = new CostSummaryResponse
+        {
+            PrintJobId = job.Id,
+            PrintName = job.PrintName,
+            SpoolId = job.SpoolId,
+            SpoolSerial = spool?.SpoolSerial ?? string.Empty,
+            SpoolBrand = spool?.Brand ?? string.Empty,
+            SpoolColorName = spool?.ColorName ?? string.Empty,
+            MmExtruded = job.MmExtruded,
+            GramsDerived = job.GramsDerived,
+            SpoolPurchasePrice = spool?.PurchasePrice,
+            SpoolWeightTotalGrams = spool?.WeightTotalGrams,
+            StoredCostPerPrint = job.CostPerPrint
+        };
+
+        // Validate spool data availability
+        if (spool is null)
+        {
+            warnings.Add("Spool data is not available for this print job. Cost cannot be calculated.");
+            response.Warnings = warnings;
+            return Ok(response);
+        }
+
+        // Check if we can calculate cost
+        if (!spool.PurchasePrice.HasValue)
+        {
+            warnings.Add("Spool purchase price is not set. Cost per gram and total material cost cannot be calculated.");
+        }
+
+        if (spool.WeightTotalGrams <= 0)
+        {
+            warnings.Add("Spool total weight is zero or invalid. Cost per gram and total material cost cannot be calculated.");
+        }
+
+        // If we have enough data, calculate the cost
+        if (spool.PurchasePrice.HasValue && spool.WeightTotalGrams > 0)
+        {
+            var pricePerGram = spool.PurchasePrice.Value / spool.WeightTotalGrams;
+            response.PricePerGram = Math.Round(pricePerGram, 4);
+            response.TotalMaterialCost = Math.Round(job.GramsDerived * pricePerGram, 4);
+        }
+
+        // Warn if grams derived is zero but mm extruded is non-zero
+        if (job.GramsDerived == 0 && job.MmExtruded > 0)
+        {
+            warnings.Add("GramsDerived is zero despite MmExtruded being non-zero. Cost may be inaccurate. Consider re-deriving grams from filament parameters.");
+        }
+
+        response.Warnings = warnings;
+        return Ok(response);
+    }
+
     // ── Gram Derivation Formula ────────────────────────────────────
 
     /// <summary>

backend/API/DTOs/PrintJobs/CostPerPrintDtos.cs

@@ -0,0 +1,99 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Extrudex.API.DTOs.PrintJobs;
+
+/// <summary>
+/// Response DTO for cost-per-print calculation. Contains the full cost
+/// breakdown and any warnings about missing or incomplete data.
+/// </summary>
+public class CostPerPrintResponse
+{
+    /// <summary>The print job identifier this result belongs to.</summary>
+    public Guid PrintJobId { get; set; }
+
+    /// <summary>Human-readable name of the print job.</summary>
+    public string PrintName { get; set; } = string.Empty;
+
+    /// <summary>The spool identifier that provided filament.</summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>Serial number of the spool.</summary>
+    public string SpoolSerial { get; set; } = string.Empty;
+
+    /// <summary>Total millimeters of filament extruded.</summary>
+    public decimal MmExtruded { get; set; }
+
+    /// <summary>Derived grams consumed for this print.</summary>
+    public decimal GramsDerived { get; set; }
+
+    /// <summary>The spool's purchase price. Null if not recorded.</summary>
+    public decimal? PurchasePrice { get; set; }
+
+    /// <summary>The spool's total weight in grams when full.</summary>
+    public decimal? WeightTotalGrams { get; set; }
+
+    /// <summary>Cost per gram of filament. Null if purchase price or total weight is missing.</summary>
+    public decimal? CostPerGram { get; set; }
+
+    /// <summary>Calculated cost of this print job. Null if cost data is incomplete.</summary>
+    public decimal? CostPerPrint { get; set; }
+
+    /// <summary>
+    /// Warnings about missing or incomplete data. Empty when all data is available
+    /// and the calculation succeeded.
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}
+
+/// <summary>
+/// Request DTO for batch cost calculation by spool. Returns cost breakdowns
+/// for all print jobs associated with the specified spool.
+/// </summary>
+public class SpoolCostRequest
+{
+    /// <summary>The unique identifier of the spool to calculate costs for.</summary>
+    [Required(ErrorMessage = "SpoolId is required.")]
+    public Guid SpoolId { get; set; }
+}
+
+/// <summary>
+/// Response DTO for spool-level cost calculation. Contains cost breakdowns
+/// for all print jobs on the spool, plus a total cost summary.
+/// </summary>
+public class SpoolCostResponse
+{
+    /// <summary>The spool identifier.</summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>Serial number of the spool.</summary>
+    public string SpoolSerial { get; set; } = string.Empty;
+
+    /// <summary>The spool's purchase price. Null if not recorded.</summary>
+    public decimal? PurchasePrice { get; set; }
+
+    /// <summary>The spool's total weight in grams when full.</summary>
+    public decimal? WeightTotalGrams { get; set; }
+
+    /// <summary>Cost per gram of filament. Null if cost data is incomplete.</summary>
+    public decimal? CostPerGram { get; set; }
+
+    /// <summary>Total grams consumed across all print jobs on this spool.</summary>
+    public decimal TotalGramsConsumed { get; set; }
+
+    /// <summary>Total calculated cost across all print jobs. Null if any job has missing data.</summary>
+    public decimal? TotalCost { get; set; }
+
+    /// <summary>Number of print jobs included in this calculation.</summary>
+    public int JobCount { get; set; }
+
+    /// <summary>
+    /// Individual cost breakdowns per print job. Jobs with missing data
+    /// will have null cost fields and populated warnings.
+    /// </summary>
+    public List<CostPerPrintResponse> Jobs { get; set; } = new();
+
+    /// <summary>
+    /// Aggregate warnings about missing data across all jobs.
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}

backend/API/DTOs/PrintJobs/CostSummaryResponse.cs

@@ -0,0 +1,55 @@
+namespace Extrudex.API.DTOs.PrintJobs;
+
+/// <summary>
+/// Response DTO for the cost summary of a print job.
+/// Provides a breakdown of material cost based on filament usage
+/// and spool pricing data. If cost data is incomplete, warnings
+/// are returned instead of throwing an error.
+/// </summary>
+public class CostSummaryResponse
+{
+    /// <summary>Unique identifier of the print job.</summary>
+    public Guid PrintJobId { get; set; }
+
+    /// <summary>Human-readable name of the print job.</summary>
+    public string PrintName { get; set; } = string.Empty;
+
+    /// <summary>Foreign key to the spool used for this print job.</summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>Serial number of the spool.</summary>
+    public string SpoolSerial { get; set; } = string.Empty;
+
+    /// <summary>Brand of the spool.</summary>
+    public string SpoolBrand { get; set; } = string.Empty;
+
+    /// <summary>Color name of the spool.</summary>
+    public string SpoolColorName { get; set; } = string.Empty;
+
+    /// <summary>Total millimeters of filament extruded during this print.</summary>
+    public decimal MmExtruded { get; set; }
+
+    /// <summary>Derived grams consumed for this print job.</summary>
+    public decimal GramsDerived { get; set; }
+
+    /// <summary>Purchase price of the full spool, if available.</summary>
+    public decimal? SpoolPurchasePrice { get; set; }
+
+    /// <summary>Total weight of the spool in grams when full.</summary>
+    public decimal? SpoolWeightTotalGrams { get; set; }
+
+    /// <summary>Calculated price per gram (purchase price / total weight), if available.</summary>
+    public decimal? PricePerGram { get; set; }
+
+    /// <summary>Calculated total material cost for this print job, if available.</summary>
+    public decimal? TotalMaterialCost { get; set; }
+
+    /// <summary>The CostPerPrint stored on the print job entity, if set.</summary>
+    public decimal? StoredCostPerPrint { get; set; }
+
+    /// <summary>
+    /// Warnings about missing data that prevent cost calculation.
+    /// Empty if all data is available and cost was calculated successfully.
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}

backend/Domain/Interfaces/ICostPerPrintService.cs

@@ -0,0 +1,76 @@
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// Service interface for calculating the cost of goods sold (COGS) per print job.
+/// Uses the spool's purchase price and the print job's derived grams consumed
+/// to produce a cost breakdown. Handles missing cost data gracefully by returning
+/// warnings rather than throwing exceptions.
+/// </summary>
+public interface ICostPerPrintService
+{
+    /// <summary>
+    /// Calculates the cost per print for a specific print job.
+    /// </summary>
+    /// <param name="printJobId">The unique identifier of the print job.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>
+    /// A <see cref="CostPerPrintResult"/> containing the cost breakdown,
+    /// or warnings if cost data is missing or incomplete.
+    /// </returns>
+    Task<CostPerPrintResult> CalculateAsync(Guid printJobId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Calculates cost breakdowns for all print jobs associated with a specific spool.
+    /// Useful for spool-level COGS reporting.
+    /// </summary>
+    /// <param name="spoolId">The unique identifier of the spool.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>
+    /// A list of <see cref="CostPerPrintResult"/> for each print job on the spool.
+    /// Jobs with missing cost data will include warnings.
+    /// </returns>
+    Task<IReadOnlyList<CostPerPrintResult>> CalculateBySpoolAsync(Guid spoolId, CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Result of a cost-per-print calculation. Contains the cost breakdown
+/// and any warnings about missing or incomplete cost data.
+/// </summary>
+public class CostPerPrintResult
+{
+    /// <summary>The print job identifier this result belongs to.</summary>
+    public Guid PrintJobId { get; set; }
+
+    /// <summary>Human-readable name of the print job.</summary>
+    public string PrintName { get; set; } = string.Empty;
+
+    /// <summary>The spool identifier that provided filament.</summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>Serial number of the spool.</summary>
+    public string SpoolSerial { get; set; } = string.Empty;
+
+    /// <summary>Total millimeters of filament extruded.</summary>
+    public decimal MmExtruded { get; set; }
+
+    /// <summary>Derived grams consumed for this print.</summary>
+    public decimal GramsDerived { get; set; }
+
+    /// <summary>The spool's purchase price. Null if not recorded.</summary>
+    public decimal? PurchasePrice { get; set; }
+
+    /// <summary>The spool's total weight in grams when full.</summary>
+    public decimal? WeightTotalGrams { get; set; }
+
+    /// <summary>Cost per gram of filament. Null if purchase price or total weight is missing.</summary>
+    public decimal? CostPerGram { get; set; }
+
+    /// <summary>Calculated cost of this print job. Null if cost data is incomplete.</summary>
+    public decimal? CostPerPrint { get; set; }
+
+    /// <summary>
+    /// Warnings about missing or incomplete data that prevented a full calculation.
+    /// Empty when all data is available and the calculation succeeded.
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}

backend/Infrastructure/Services/CostPerPrintService.cs

@@ -0,0 +1,158 @@
+using Extrudex.Domain.Interfaces;
+using Extrudex.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+
+namespace Extrudex.Infrastructure.Services;
+
+/// <summary>
+/// Calculates the cost of goods sold (COGS) per print job using the spool's
+/// purchase price and the print job's derived grams consumed.
+///
+/// Formula:
+///   cost_per_gram = purchase_price / weight_total_grams
+///   cost_per_print = grams_derived × cost_per_gram
+///
+/// Handles missing data gracefully — if the spool has no purchase price or
+/// weight recorded, the result includes warnings and null cost fields
+/// instead of throwing exceptions.
+/// </summary>
+public class CostPerPrintService : ICostPerPrintService
+{
+    private readonly ExtrudexDbContext _dbContext;
+    private readonly ILogger<CostPerPrintService> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CostPerPrintService"/> class.
+    /// </summary>
+    /// <param name="dbContext">The database context for data access.</param>
+    /// <param name="logger">The logger for diagnostic output.</param>
+    public CostPerPrintService(ExtrudexDbContext dbContext, ILogger<CostPerPrintService> logger)
+    {
+        _dbContext = dbContext;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public async Task<CostPerPrintResult> CalculateAsync(Guid printJobId, CancellationToken cancellationToken = default)
+    {
+        _logger.LogDebug("Calculating cost per print for job {PrintJobId}", printJobId);
+
+        var job = await _dbContext.PrintJobs
+            .Include(j => j.Spool)
+            .ThenInclude(s => s!.MaterialBase)
+            .FirstOrDefaultAsync(j => j.Id == printJobId, cancellationToken);
+
+        if (job is null)
+        {
+            _logger.LogWarning("Print job {PrintJobId} not found for cost calculation", printJobId);
+            return new CostPerPrintResult
+            {
+                PrintJobId = printJobId,
+                Warnings = new List<string> { $"Print job with ID '{printJobId}' not found." }
+            };
+        }
+
+        return BuildResult(job);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<CostPerPrintResult>> CalculateBySpoolAsync(
+        Guid spoolId, CancellationToken cancellationToken = default)
+    {
+        _logger.LogDebug("Calculating cost per print for all jobs on spool {SpoolId}", spoolId);
+
+        var jobs = await _dbContext.PrintJobs
+            .Include(j => j.Spool)
+            .ThenInclude(s => s!.MaterialBase)
+            .Where(j => j.SpoolId == spoolId)
+            .OrderByDescending(j => j.CreatedAt)
+            .ToListAsync(cancellationToken);
+
+        if (jobs.Count == 0)
+        {
+            _logger.LogDebug("No print jobs found for spool {SpoolId}", spoolId);
+            return Array.Empty<CostPerPrintResult>();
+        }
+
+        return jobs.Select(BuildResult).ToList();
+    }
+
+    /// <summary>
+    /// Builds a <see cref="CostPerPrintResult"/> from a print job entity.
+    /// Computes cost_per_gram and cost_per_print when all required data is available.
+    /// Populates warnings when data is missing or incomplete.
+    /// </summary>
+    /// <param name="job">The print job entity with Spool navigation loaded.</param>
+    /// <returns>A cost calculation result with breakdown and any warnings.</returns>
+    private CostPerPrintResult BuildResult(Domain.Entities.PrintJob job)
+    {
+        var warnings = new List<string>();
+        var spool = job.Spool;
+
+        // Map what we always have
+        var result = new CostPerPrintResult
+        {
+            PrintJobId = job.Id,
+            PrintName = job.PrintName,
+            SpoolId = job.SpoolId,
+            SpoolSerial = spool?.SpoolSerial ?? string.Empty,
+            MmExtruded = job.MmExtruded,
+            GramsDerived = job.GramsDerived,
+        };
+
+        // Guard: spool must be loaded
+        if (spool is null)
+        {
+            warnings.Add("Spool data is not available for this print job.");
+            result.Warnings = warnings;
+            return result;
+        }
+
+        // Capture purchase price
+        result.PurchasePrice = spool.PurchasePrice;
+        result.WeightTotalGrams = spool.WeightTotalGrams;
+
+        // Check for missing purchase price
+        if (!spool.PurchasePrice.HasValue)
+        {
+            warnings.Add(
+                "Spool purchase price is not recorded. Cost calculation requires a purchase price on the spool.");
+        }
+
+        // Check for zero or negative weight — prevents division by zero
+        if (spool.WeightTotalGrams <= 0)
+        {
+            warnings.Add(
+                "Spool total weight is zero or not recorded. Cost calculation requires a positive weight_total_grams on the spool.");
+        }
+
+        // Check for zero grams derived
+        if (job.GramsDerived <= 0)
+        {
+            warnings.Add(
+                "Derived grams consumed is zero. Ensure mm_extruded, filament diameter, and material density are recorded for this print job.");
+        }
+
+        // If all data is present and valid, compute the cost
+        if (spool.PurchasePrice.HasValue && spool.WeightTotalGrams > 0 && job.GramsDerived > 0)
+        {
+            var costPerGram = spool.PurchasePrice.Value / spool.WeightTotalGrams;
+            result.CostPerGram = Math.Round(costPerGram, 6);
+            result.CostPerPrint = Math.Round(job.GramsDerived * costPerGram, 4);
+
+            _logger.LogDebug(
+                "Cost calculated for job {PrintJobId}: {GramsDerived}g × {CostPerGram:C}/g = {CostPerPrint:C}",
+                job.Id, job.GramsDerived, result.CostPerGram, result.CostPerPrint);
+        }
+        else
+        {
+            _logger.LogDebug(
+                "Cost calculation incomplete for job {PrintJobId}: missing data (warnings: {WarningCount})",
+                job.Id, warnings.Count);
+        }
+
+        result.Warnings = warnings;
+        return result;
+    }
+}

backend/Program.cs

@@ -52,6 +52,9 @@ builder.Services.AddSwaggerGen(c =>
 // ── QR Code Generation ──────────────────────────────────────
 builder.Services.AddSingleton<IQrCodeService, QrCodeService>();
 
+// ── Cost Per Print Calculation ─────────────────────────────
+builder.Services.AddScoped<ICostPerPrintService, CostPerPrintService>();
+
 // ── FluentValidation ──────────────────────────────────────
 // Registers all validators from the API assembly into DI.
 builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());

frontend/src/app/components/filament-filter/filament-filter.component.html

@@ -0,0 +1,76 @@
+<!-- Filament Filter Bar — material type, color search, low stock, active-only -->
+<div class="filament-filter-bar" role="search" aria-label="Filter filament inventory">
+
+  <!-- Material Type Multi-Select -->
+  <mat-form-field appearance="outline" class="filter-field material-filter">
+    <mat-label>Material</mat-label>
+    <mat-select multiple
+                [value]="selectedMaterials()"
+                (selectionChange)="onMaterialChange($event.value)"
+                aria-label="Filter by material type">
+      @for (material of materialOptions(); track material) {
+        <mat-option [value]="material">{{ material }}</mat-option>
+      }
+    </mat-select>
+    @if (selectedMaterials().length > 0) {
+      <mat-chip-set class="selected-chips" matSuffix>
+        @for (mat of selectedMaterials(); track mat) {
+          <mat-chip (removed)="removeMaterial(mat)"
+                    class="filter-chip">
+            <span>{{ mat }}</span>
+            <mat-icon matChipRemove>cancel</mat-icon>
+          </mat-chip>
+        }
+      </mat-chip-set>
+    }
+  </mat-form-field>
+
+  <!-- Color Search -->
+  <mat-form-field appearance="outline" class="filter-field color-filter">
+    <mat-label>Color</mat-label>
+    <input matInput
+           type="text"
+           [value]="colorSearch()"
+           (input)="onColorSearchChange($any($event.target).value)"
+           placeholder="Search color..."
+           aria-label="Filter by color name" />
+    @if (colorSearch().trim()) {
+      <mat-icon matSuffix class="filter-active-icon">filter_list</mat-icon>
+    }
+  </mat-form-field>
+
+  <!-- Low Stock Toggle -->
+  <mat-checkbox [checked]="lowStockOnly()"
+                (change)="onLowStockToggle($event.checked)"
+                class="filter-checkbox"
+                aria-label="Show low stock only"
+                matTooltip="Show only spools at 25% or less remaining"
+                matTooltipPosition="below">
+    <mat-icon class="checkbox-icon" [class.active]="lowStockOnly()">warning</mat-icon>
+    Low Stock
+  </mat-checkbox>
+
+  <!-- Active Only Toggle -->
+  <mat-checkbox [checked]="activeOnly()"
+                (change)="onActiveOnlyToggle($event.checked)"
+                class="filter-checkbox"
+                aria-label="Show active spools only"
+                matTooltip="Show only spools currently in use"
+                matTooltipPosition="below">
+    <mat-icon class="checkbox-icon" [class.active]="activeOnly()">check_circle</mat-icon>
+    Active Only
+  </mat-checkbox>
+
+  <!-- Clear All Filters -->
+  @if (hasActiveFilters()) {
+    <button mat-button
+            class="clear-filters-btn"
+            (click)="clearAll()"
+            aria-label="Clear all filters"
+            matTooltip="Remove all filters"
+            matTooltipPosition="below">
+      <mat-icon>filter_alt_off</mat-icon>
+      Clear
+    </button>
+  }
+</div>

frontend/src/app/components/filament-filter/filament-filter.component.scss

@@ -0,0 +1,134 @@
+/**
+ * Filament Filter Bar Styles
+ * Responsive filter layout for kiosk and mobile
+ */
+
+$spacing-unit: 8px;
+
+.filament-filter-bar {
+  display: flex;
+  align-items: center;
+  gap: $spacing-unit * 2;
+  flex-wrap: wrap;
+  padding: $spacing-unit * 2 0;
+  margin-bottom: $spacing-unit * 2;
+}
+
+// Form field sizing
+.filter-field {
+  flex: 0 1 auto;
+  min-width: 160px;
+
+  &.material-filter {
+    min-width: 200px;
+  }
+
+  &.color-filter {
+    min-width: 180px;
+  }
+
+  // Reduce vertical spacing inside filter fields
+  .mat-mdc-form-field-subscript-wrapper {
+    display: none; // No hint/error text needed for filters
+  }
+}
+
+// Selected material chips
+.selected-chips {
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.filter-chip {
+  font-size: 12px !important;
+  min-height: 24px !important;
+
+  mat-icon {
+    font-size: 14px !important;
+    width: 14px !important;
+    height: 14px !important;
+  }
+}
+
+// Active filter icon
+.filter-active-icon {
+  color: var(--mat-sys-primary);
+  font-size: 18px !important;
+  width: 18px !important;
+  height: 18px !important;
+}
+
+// Checkbox styling
+.filter-checkbox {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  white-space: nowrap;
+  user-select: none;
+  touch-action: manipulation; // Prevent zoom on double-tap
+
+  .checkbox-icon {
+    font-size: 18px !important;
+    width: 18px !important;
+    height: 18px !important;
+    color: var(--mat-sys-on-surface-variant);
+    transition: color 0.2s ease;
+
+    &.active {
+      color: var(--mat-sys-primary);
+    }
+  }
+}
+
+// Clear filters button
+.clear-filters-btn {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 13px;
+
+  mat-icon {
+    font-size: 18px !important;
+    width: 18px !important;
+    height: 18px !important;
+  }
+}
+
+// Responsive: stack filters vertically on small screens
+@media (max-width: 768px) {
+  .filament-filter-bar {
+    flex-direction: column;
+    align-items: stretch;
+    gap: $spacing-unit;
+  }
+
+  .filter-field {
+    width: 100%;
+    min-width: unset;
+
+    &.material-filter,
+    &.color-filter {
+      min-width: unset;
+    }
+  }
+
+  .filter-checkbox {
+    padding: $spacing-unit 0;
+  }
+
+  .clear-filters-btn {
+    align-self: flex-start;
+  }
+}
+
+// Extra-small screens (phone portrait)
+@media (max-width: 480px) {
+  .filament-filter-bar {
+    padding: $spacing-unit 0;
+    margin-bottom: $spacing-unit;
+  }
+
+  .filter-checkbox {
+    font-size: 13px;
+  }
+}

frontend/src/app/components/filament-filter/filament-filter.component.ts

@@ -0,0 +1,158 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  EventEmitter,
+  Input,
+  Output,
+  computed,
+  signal,
+} from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatSelectModule } from '@angular/material/select';
+import { MatInputModule } from '@angular/material/input';
+import { MatCheckboxModule } from '@angular/material/checkbox';
+import { MatIconModule } from '@angular/material/icon';
+import { MatChipsModule } from '@angular/material/chips';
+import { MatButtonModule } from '@angular/material/button';
+import { MatTooltipModule } from '@angular/material/tooltip';
+import {
+  Filament,
+  StockLevel,
+  classifyStockLevel,
+} from '../../models/filament.model';
+
+/** Filter state emitted by the filament filter component */
+export interface FilamentFilterState {
+  /** Selected material base names — empty means all */
+  materialBaseNames: string[];
+
+  /** Color search text — empty string means all */
+  colorSearch: string;
+
+  /** Whether to show only low/critical stock */
+  lowStockOnly: boolean;
+
+  /** Whether to show only active spools */
+  activeOnly: boolean;
+}
+
+/**
+ * FilamentFilterComponent — Filter bar for the filament inventory list.
+ *
+ * Provides:
+ * - Material type multi-select filter
+ * - Color name text search
+ * - Low stock toggle (shows only critical/low spools)
+ * - Active-only toggle
+ * - Clear all filters action
+ */
+@Component({
+  selector: 'app-filament-filter',
+  standalone: true,
+  imports: [
+    CommonModule,
+    FormsModule,
+    MatFormFieldModule,
+    MatSelectModule,
+    MatInputModule,
+    MatCheckboxModule,
+    MatIconModule,
+    MatChipsModule,
+    MatButtonModule,
+    MatTooltipModule,
+  ],
+  templateUrl: './filament-filter.component.html',
+  styleUrl: './filament-filter.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class FilamentFilterComponent {
+  /** Filament data input — used to derive material options */
+  @Input() set filaments(value: Filament[]) {
+    this._filaments.set(value);
+    const materials = [...new Set(value.map((f) => f.materialBaseName))].sort();
+    this.materialOptions.set(materials);
+  }
+  get filaments(): Filament[] {
+    return this._filaments();
+  }
+  private readonly _filaments = signal<Filament[]>([]);
+
+  /** Available material base names derived from filament data */
+  readonly materialOptions = signal<string[]>([]);
+
+  /** Selected material base names */
+  readonly selectedMaterials = signal<string[]>([]);
+
+  /** Color search text */
+  readonly colorSearch = signal('');
+
+  /** Low stock only toggle */
+  readonly lowStockOnly = signal(false);
+
+  /** Active only toggle */
+  readonly activeOnly = signal(false);
+
+  /** Computed: whether any filters are active */
+  readonly hasActiveFilters = computed(
+    () =>
+      this.selectedMaterials().length > 0 ||
+      this.colorSearch().trim().length > 0 ||
+      this.lowStockOnly() ||
+      this.activeOnly()
+  );
+
+  /** Emits the current filter state whenever filters change */
+  @Output() readonly filterChange = new EventEmitter<FilamentFilterState>();
+
+  /** Handle material selection change */
+  onMaterialChange(selected: string[]): void {
+    this.selectedMaterials.set(selected);
+    this.emitFilterState();
+  }
+
+  /** Handle color search input */
+  onColorSearchChange(value: string): void {
+    this.colorSearch.set(value);
+    this.emitFilterState();
+  }
+
+  /** Handle low stock toggle */
+  onLowStockToggle(checked: boolean): void {
+    this.lowStockOnly.set(checked);
+    this.emitFilterState();
+  }
+
+  /** Handle active-only toggle */
+  onActiveOnlyToggle(checked: boolean): void {
+    this.activeOnly.set(checked);
+    this.emitFilterState();
+  }
+
+  /** Remove a single material chip */
+  removeMaterial(material: string): void {
+    const updated = this.selectedMaterials().filter((m) => m !== material);
+    this.selectedMaterials.set(updated);
+    this.emitFilterState();
+  }
+
+  /** Clear all filters */
+  clearAll(): void {
+    this.selectedMaterials.set([]);
+    this.colorSearch.set('');
+    this.lowStockOnly.set(false);
+    this.activeOnly.set(false);
+    this.emitFilterState();
+  }
+
+  /** Emit the current filter state */
+  private emitFilterState(): void {
+    this.filterChange.emit({
+      materialBaseNames: this.selectedMaterials(),
+      colorSearch: this.colorSearch().trim().toLowerCase(),
+      lowStockOnly: this.lowStockOnly(),
+      activeOnly: this.activeOnly(),
+    });
+  }
+}

frontend/src/app/components/filament-table/filament-table.component.html

@@ -1,6 +1,12 @@
-<!-- Filament Inventory Table — with low stock indicators -->
+<!-- Filament Inventory Table — with filters and low stock indicators -->
 <div class="filament-table-container" role="region" aria-label="Filament inventory">
 
+  <!-- Filter Bar -->
+  <app-filament-filter
+    [filaments]="allFilaments()"
+    (filterChange)="onFilterChange($event)"
+    aria-label="Filter filament inventory" />
+
   <!-- Low Stock Alert Banner — shown when critical or low stock spools exist -->
   @if (criticalCount() > 0) {
     <div class="alert-banner critical" role="alert">
@@ -16,7 +22,7 @@
 
   <!-- Filament Table -->
   <table mat-table
-         [dataSource]="sortedFilaments()"
+         [dataSource]="filteredFilaments()"
          matSort
          (matSortChange)="sortData($event)"
          class="filament-table"
@@ -113,7 +119,15 @@
     </tr>
   </table>
 
-  <!-- Empty state -->
+  <!-- Filtered empty state -->
+  @if (filteredFilaments().length === 0 && filaments().length > 0) {
+    <div class="empty-state" role="status">
+      <mat-icon aria-hidden="true">filter_alt_off</mat-icon>
+      <p>No filaments match the current filters</p>
+    </div>
+  }
+
+  <!-- No data empty state -->
   @if (filaments().length === 0) {
     <div class="empty-state" role="status">
       <mat-icon aria-hidden="true">inventory_2</mat-icon>

frontend/src/app/components/filament-table/filament-table.component.ts

@@ -12,6 +12,7 @@ import { MatIconModule } from '@angular/material/icon';
 import { MatProgressBarModule } from '@angular/material/progress-bar';
 import { MatTooltipModule } from '@angular/material/tooltip';
 import { MatSortModule, Sort } from '@angular/material/sort';
+import { FilamentFilterComponent, FilamentFilterState } from '../filament-filter/filament-filter.component';
 import {
   Filament,
   StockLevel,
@@ -40,6 +41,7 @@ export type FilamentColumn =
     MatProgressBarModule,
     MatTooltipModule,
     MatSortModule,
+    FilamentFilterComponent,
   ],
   templateUrl: './filament-table.component.html',
   styleUrl: './filament-table.component.scss',
@@ -70,9 +72,24 @@ export class FilamentTableComponent {
   /** Default columns for template binding */
   readonly columns = this._displayedColumns;
 
+  /** Current filter state */
+  readonly filterState = signal<FilamentFilterState>({
+    materialBaseNames: [],
+    colorSearch: '',
+    lowStockOnly: false,
+    activeOnly: false,
+  });
+
   /** Sorted filament data */
   readonly sortedFilaments = signal<Filament[]>([]);
 
+  /** Computed: filtered + sorted filament data for display */
+  readonly filteredFilaments = computed(() => {
+    const data = this.sortedFilaments();
+    const filters = this.filterState();
+    return data.filter((f) => this.matchesFilter(f, filters));
+  });
+
   /** Computed: count of low/critical spools */
   readonly lowStockCount = computed(() =>
     this.filaments().filter(
@@ -211,6 +228,9 @@ export class FilamentTableComponent {
     this.sortedFilaments.set([...data]);
   }
 
+  /** All filament data — for the filter component to derive material options */
+  readonly allFilaments = this.filaments;
+
   /** Handle sort changes from MatSort */
   sortData(sort: Sort): void {
     const data = [...this.filaments()];
@@ -252,6 +272,46 @@ export class FilamentTableComponent {
     this.sortedFilaments.set(sorted);
   }
 
+  /** Handle filter changes from FilamentFilterComponent */
+  onFilterChange(state: FilamentFilterState): void {
+    this.filterState.set(state);
+  }
+
+  /** Check if a filament matches the current filter state */
+  private matchesFilter(filament: Filament, filters: FilamentFilterState): boolean {
+    // Material filter — empty means all
+    if (
+      filters.materialBaseNames.length > 0 &&
+      !filters.materialBaseNames.includes(filament.materialBaseName)
+    ) {
+      return false;
+    }
+
+    // Color search — empty means all
+    if (
+      filters.colorSearch &&
+      !filament.colorName.toLowerCase().includes(filters.colorSearch) &&
+      !filament.colorHex.toLowerCase().includes(filters.colorSearch)
+    ) {
+      return false;
+    }
+
+    // Low stock filter — show only critical/low
+    if (filters.lowStockOnly) {
+      const level = classifyStockLevel(filament);
+      if (level !== 'critical' && level !== 'low') {
+        return false;
+      }
+    }
+
+    // Active only filter
+    if (filters.activeOnly && !filament.isActive) {
+      return false;
+    }
+
+    return true;
+  }
+
   /** Template helper: get remaining percent */
   getRemainingPercent = getRemainingPercent;