feat(ifs): set an AD5X slot's material/color from a Spoolman spool

Add an IFS material-station view with a "Set from Spoolman" action. The
user picks a spool from the existing Spoolman picker; the spool's
material/color are snapped to the AD5X's fixed 14-material / 24-color
palette client-side, then applied via a new server route that calls the
library's configureSlot (msConfig_cmd).

- src/webui/static/shared/ifs-palette.ts: pure palette + nearestColor
  (CIEDE2000) + nearestMaterial, with a Jest spec.
- POST /spoolman/slot-config: zod-validated, material-station gated,
  resolves the FiveMClient and calls control.configureSlot. Keeps the
  slot's current material when the spool material doesn't resolve.
- Reuses the Spoolman selection modal as the picker.
- jest.config.js: map ".js" ESM specifiers to ".ts" so static-module
  specs run under ts-jest.

Bumps @ghosttypes/ff-api to ^1.3.2 for configureSlot/SlotAction.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: GhostTypes

jest.config.js

@@ -28,6 +28,9 @@ module.exports = {
   coverageReporters: ['text', 'lcov', 'html'],
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
+    // Static browser modules use explicit `.js` ESM specifiers; map them back to
+    // the `.ts` sources so ts-jest can resolve them under test.
+    '^(\\.{1,2}/.*)\\.js$': '$1',
   },
   moduleFileExtensions: ['ts', 'js', 'json'],
   verbose: true,

package-lock.json

@@ -71,7 +71,7 @@
   "author": "Parallel-7",
   "license": "MIT",
   "dependencies": {
-    "@ghosttypes/ff-api": "^1.3.0",
+    "@ghosttypes/ff-api": "^1.3.2",
     "@parallel-7/slicer-meta": "1.1.0-20251121155836",
     "axios": "^1.8.4",
     "express": "^5.1.0",

package.json

@@ -128,7 +128,7 @@ export interface FiltrationStatus {
 export interface PrinterSettings {
   nozzleSize?: number; // mm (e.g. 0.4, 0.6) - undefined for legacy printers
   filamentType?: string; // PLA, ABS, etc - undefined for legacy printers
-  speedOffset?: number; // percentage 50-200 - undefined for legacy printers
+  speedOffset?: number; // percentage 0-1000 (AD5X reports up to 500) - undefined for legacy printers
   zAxisOffset?: number; // mm offset value - undefined for legacy printers
 }
 

src/types/polling.ts

@@ -294,6 +294,30 @@ export const SpoolClearRequestSchema = z.object({
   contextId: z.string().optional(),
 });
 
+/**
+ * Slot-config request validation (configure an AD5X material-station slot).
+ *
+ * The client snaps a Spoolman spool's material/color to the printer's fixed
+ * 14-material / 24-color palette and sends the already-snapped values here. Slot
+ * is 1-based (1-4); `materialName` is null when the spool's material did not
+ * resolve, in which case the slot keeps its current material. `colorHex` is a
+ * 3/6/8-digit hex (with or without leading '#').
+ */
+export const SlotConfigRequestSchema = z.object({
+  contextId: z.string().optional(),
+  slot: z
+    .number()
+    .int('slot must be an integer')
+    .min(1, 'slot must be at least 1')
+    .max(4, 'slot must be at most 4'),
+  materialName: z.string().min(1).nullable(),
+  colorHex: z
+    .string()
+    .regex(/^#?[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3}(?:[0-9a-fA-F]{2})?)?$/, 'Invalid hex color'),
+  /** Optional fallback material to keep when `materialName` is null. */
+  currentMaterial: z.string().min(1).nullable().optional(),
+});
+
 // ============================================================================
 // TYPE EXPORTS
 // ============================================================================
@@ -306,3 +330,4 @@ export type ValidatedPrinterCommand = z.infer<typeof PrinterCommandSchema>;
 export type ValidatedPrinterFeatures = z.infer<typeof PrinterFeaturesSchema>;
 export type ValidatedSpoolSelectRequest = z.infer<typeof SpoolSelectRequestSchema>;
 export type ValidatedSpoolClearRequest = z.infer<typeof SpoolClearRequestSchema>;
+export type ValidatedSlotConfigRequest = z.infer<typeof SlotConfigRequestSchema>;

src/webui/schemas/web-api.schemas.ts

@@ -2,15 +2,18 @@
  * @fileoverview Spoolman integration routes (config, search, active spool management).
  */
 
+import { FiveMClient } from '@ghosttypes/ff-api';
 import type { Response, Router } from 'express';
 import { toAppError } from '../../../utils/error.utils';
 import {
   createValidationError,
+  SlotConfigRequestSchema,
   SpoolClearRequestSchema,
   SpoolSelectRequestSchema,
 } from '../../schemas/web-api.schemas';
 import type {
   ActiveSpoolResponse,
+  SlotConfigResponse,
   SpoolmanConfigResponse,
   SpoolSearchResponse,
   SpoolSelectResponse,
@@ -88,6 +91,8 @@ export function registerSpoolmanRoutes(router: Router, deps: RouteDependencies):
         vendor: spool.filament.vendor?.name || null,
         material: spool.filament.material || null,
         colorHex: spool.filament.color_hex || '#808080',
+        rawColorHex: spool.filament.color_hex || null,
+        multiColorHexes: spool.filament.multi_color_hexes || null,
         remainingWeight: spool.remaining_weight || 0,
         remainingLength: spool.remaining_length || 0,
         archived: spool.archived,
@@ -215,4 +220,77 @@ export function registerSpoolmanRoutes(router: Router, deps: RouteDependencies):
       return sendErrorResponse<StandardAPIResponse>(res, 500, appError.message);
     }
   });
+
+  router.post('/spoolman/slot-config', async (req: AuthenticatedRequest, res: Response) => {
+    try {
+      const validation = SlotConfigRequestSchema.safeParse(req.body);
+      if (!validation.success) {
+        const validationError = createValidationError(validation.error);
+        return sendErrorResponse<SlotConfigResponse>(res, 400, validationError.error);
+      }
+
+      const { contextId, slot, materialName, colorHex, currentMaterial } = validation.data;
+      const overrideContextId = contextId || null;
+
+      const contextResult = resolveContext(req, deps, {
+        overrideContextId,
+        requireBackendReady: true,
+        requireBackendInstance: true,
+      });
+      if (!contextResult.success) {
+        return sendErrorResponse<SlotConfigResponse>(
+          res,
+          contextResult.statusCode,
+          contextResult.error
+        );
+      }
+
+      const { contextId: resolvedContextId, backend } = contextResult;
+      if (!backend) {
+        return sendErrorResponse<SlotConfigResponse>(res, 503, 'Backend not available');
+      }
+
+      if (!deps.backendManager.isFeatureAvailable(resolvedContextId, 'material-station')) {
+        return sendErrorResponse<SlotConfigResponse>(
+          res,
+          400,
+          'Material station not available on this printer'
+        );
+      }
+
+      // Resolve the material to write: the client snaps the spool material to the
+      // fixed palette; when it does not resolve, keep the slot's current material.
+      const materialToWrite = materialName ?? currentMaterial ?? null;
+      if (!materialToWrite) {
+        return sendErrorResponse<SlotConfigResponse>(
+          res,
+          400,
+          'Spool material did not match a known material and the slot has no current material to keep'
+        );
+      }
+
+      const primaryClient = backend.getPrimaryClient();
+      if (!(primaryClient instanceof FiveMClient)) {
+        return sendErrorResponse<SlotConfigResponse>(
+          res,
+          400,
+          'Material station control requires new API client'
+        );
+      }
+
+      const result = await primaryClient.control.configureSlot(slot, materialToWrite, colorHex);
+      const response: SlotConfigResponse = {
+        success: result,
+        slot,
+        material: materialToWrite,
+        colorHex,
+        message: result ? `Slot ${slot} updated` : undefined,
+        error: result ? undefined : 'Failed to configure slot',
+      };
+      return res.status(result ? 200 : 500).json(response);
+    } catch (error) {
+      const appError = toAppError(error);
+      return sendErrorResponse<SlotConfigResponse>(res, 500, appError.message);
+    }
+  });
 }

src/webui/server/routes/spoolman-routes.ts

@@ -62,6 +62,7 @@ import {
   confirmMaterialMatching,
   setupMaterialMatchingHandlers,
 } from './features/material-matching.js';
+import { setupIfsStationHandlers } from './features/ifs-station.js';
 import { initializeDiscovery } from './features/printer-discovery.js';
 import { loadSpoolmanConfig, setupSpoolmanHandlers } from './features/spoolman.js';
 import { $, hideElement, showElement } from './shared/dom.js';
@@ -272,6 +273,8 @@ export interface SpoolSummary {
   readonly vendor: string | null;
   readonly material: string | null;
   readonly colorHex: string;
+  readonly rawColorHex: string | null;
+  readonly multiColorHexes: string | null;
   readonly remainingWeight: number;
   readonly remainingLength: number;
   readonly archived: boolean;
@@ -297,6 +300,12 @@ export interface SpoolSelectResponse extends ApiResponse {
   spool: ActiveSpoolData;
 }
 
+export interface SlotConfigResponse extends ApiResponse {
+  slot: number;
+  material: string;
+  colorHex: string;
+}
+
 // ============================================================================
 // GRID AND SETTINGS MANAGEMENT
 // ============================================================================
@@ -365,6 +374,7 @@ async function initialize(): Promise<void> {
   setupJobControlEventHandlers();
   setupMaterialMatchingHandlers();
   setupSpoolmanHandlers();
+  setupIfsStationHandlers();
   initializeDiscovery();
 
   const contextHandlers = {