@sealab/mcp-server 1.0.1 → 1.0.3

package/src/tools/ai-drawing-session-review-renderer.ts

@@ -0,0 +1,1297 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { PNG } from 'pngjs';
+
+export type AiDrawingReviewCanvasType = 'plan' | 'north' | 'south' | 'east' | 'west';
+
+export type AiDrawingSessionReviewIssueCode =
+  | 'missing_background_image'
+  | 'unsupported_background_image_reference'
+  | 'background_image_read_failed'
+  | 'placement_outside_image_bounds'
+  | 'missing_or_invalid_basis_image_dimensions'
+  | 'invalid_placement_dimensions'
+  | 'non_image_pixels_placement_space'
+  | 'placement_without_matching_cart_item'
+  | 'cart_item_without_placement'
+  | 'duplicate_position_name_on_canvas'
+  | 'placement_overlap'
+  | 'placement_category_conflict'
+  | 'base_elevation_without_plinth_placement'
+  | 'source_boundary_review_required'
+  | 'canvas_with_no_placements';
+
+export interface AiDrawingSessionReviewIssue {
+  code: AiDrawingSessionReviewIssueCode;
+  severity: 'warning' | 'error';
+  message: string;
+  canvasType?: AiDrawingReviewCanvasType;
+  positionName?: string;
+  relatedPositionName?: string;
+  aiCartItemId?: string;
+  imageReference?: string;
+}
+
+export interface AiDrawingSessionReviewCanvasResult {
+  canvasType: AiDrawingReviewCanvasType;
+  outputImagePath?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+  renderedPlacementCount: number;
+  sourceBoundaryReviewTasks: AiDrawingSourceBoundaryReviewTask[];
+  issues: AiDrawingSessionReviewIssue[];
+}
+
+export interface AiDrawingSessionReviewManifest {
+  sessionId?: string;
+  generatedAt: string;
+  visualInspectionRequired: true;
+  visualReviewStatus: 'requires_native_vision';
+  completionBlockedUntil: string;
+  visualInspectionChecklist: string[];
+  canvases: AiDrawingSessionReviewCanvasResult[];
+  issues: AiDrawingSessionReviewIssue[];
+  manifestPath?: string;
+}
+
+export interface AiDrawingSourceBoundaryReviewTask {
+  canvasType: AiDrawingReviewCanvasType;
+  positionName: string;
+  aiCartItemId?: string;
+  placementCategory: 'plan_footprint' | 'cabinet_face' | 'base_cabinet_body' | 'plinth_toekick';
+  sourceImageAuthority: true;
+  passRequiresEvidenceFormat: string[];
+  failIf: string[];
+  checklist: string[];
+}
+
+export interface AiDrawingSessionReviewRenderOptions {
+  outputDir: string;
+  canvases?: AiDrawingReviewCanvasType[];
+  imagePathByCanvas?: Partial<Record<AiDrawingReviewCanvasType, string>>;
+  localArtifactRoots?: string[];
+  writeJsonManifest?: boolean;
+  manifestFileName?: string;
+}
+
+interface AiDrawingStateLike {
+  session?: {
+    id?: unknown;
+    sessionId?: unknown;
+  } | null;
+  activeCart?: {
+    id?: unknown;
+    items?: unknown;
+  } | null;
+  canvasImages?: unknown;
+  canvasCabinetPlacements?: unknown;
+  activeCanvases?: unknown;
+}
+
+interface CanvasImageLike {
+  canvasType?: unknown;
+  imageType?: unknown;
+  s3Key?: unknown;
+  imagePath?: unknown;
+  path?: unknown;
+}
+
+interface CartItemLike {
+  id?: unknown;
+  aiCartItemId?: unknown;
+  positionName?: unknown;
+  serialNumber?: unknown;
+  displayName?: unknown;
+  itemPayload?: unknown;
+  originalItemPayload?: unknown;
+  orderReadyPayload?: unknown;
+  drawingClassificationEvidence?: unknown;
+}
+
+interface PlacementLike {
+  id?: unknown;
+  aiCartItemId?: unknown;
+  canvasType?: unknown;
+  positionName?: unknown;
+  centerX?: unknown;
+  centerY?: unknown;
+  width?: unknown;
+  height?: unknown;
+  rotation?: unknown;
+  placementSpace?: unknown;
+  basisImageWidthPx?: unknown;
+  basisImageHeightPx?: unknown;
+  objectType?: unknown;
+  drawingClassificationEvidence?: unknown;
+  viewAssociationEvidence?: unknown;
+}
+
+interface RenderablePlacement {
+  placement: PlacementLike;
+  positionName: string;
+  aiCartItemId?: string;
+  centerX: number;
+  centerY: number;
+  width: number;
+  height: number;
+  rotation: number;
+  scaleX: number;
+  scaleY: number;
+  label: string;
+  placementCategory: 'cabinet' | 'plinth';
+}
+
+const CANVAS_TYPES: AiDrawingReviewCanvasType[] = ['plan', 'north', 'south', 'east', 'west'];
+
+type Rgba = { r: number; g: number; b: number; a: number };
+
+const CABINET_PLACEMENT_FILL: Rgba = { r: 37, g: 99, b: 235, a: 70 };
+const CABINET_PLACEMENT_STROKE: Rgba = { r: 29, g: 78, b: 216, a: 255 };
+const PLINTH_PLACEMENT_FILL: Rgba = { r: 255, g: 146, b: 43, a: 80 };
+const PLINTH_PLACEMENT_STROKE: Rgba = { r: 225, g: 89, b: 12, a: 255 };
+const LABEL_BACKGROUND = { r: 255, g: 255, b: 255, a: 220 };
+const LABEL_TEXT = { r: 20, g: 27, b: 35, a: 255 };
+const ISSUE_MARK = { r: 180, g: 20, b: 20, a: 255 };
+const VISUAL_INSPECTION_CHECKLIST = [
+  'Open every full-canvas overlay with native vision.',
+  'Compare the rectangle edges to the visible cabinet face or plan footprint, not to labels or evidence text.',
+  'Source drawing pixels are the authority: do not treat non-overlap, adjacency, dimensions, labels, or evidence prose as proof that a bbox is visually correct.',
+  'For every placement, write a boundary evidence sentence naming the visible source linework at LEFT, RIGHT, TOP, and BOTTOM before assigning PASS.',
+  'If any side cannot be tied to visible cabinet/appliance/plinth linework, mark FAIL or UNCERTAIN; do not infer the side from labels, generated boxes, nearby dimensions, or expected cabinet size.',
+  'Blue overlays are cabinet front-facing bboxes; orange overlays are separate plinth/toekick bboxes.',
+  'Mark FAIL if a cabinet box is shifted, oversized, undersized, overlaps another cabinet, or includes appliance, fixture, counter, toekick/plinth, floor, wall, ceiling, annotation, or blank/context area.',
+  'Mark FAIL if a base cabinet bbox includes toekick/plinth or countertop height; base body height must be exclusive of both.',
+  'Mark FAIL if any cabinet bbox extends below the Z0/floor reference line or into floor, wall, or ceiling area.',
+  'Mark FAIL if a visible toekick is merged into a cabinet instead of represented as a separate orange plinth placement and AI cart item.',
+  'On elevations with base or sink-base cabinets, verify whether the lower support/toekick band is visible; if visible, require a separate orange plinth placement before PASS.',
+  'Mark FAIL if a visible cabinet on that canvas is missing, or if a side/return/context face is treated as a primary cabinet face.',
+  'Mark FAIL if plan footprint geometry is reused as an elevation face, or elevation face geometry is reused as a plan footprint.',
+  'Use called-out scale, known dimensions, and repeated modules to sanity-check cabinet body dimensions, single-door/double-door splits, drawer stacks, plinths, and gaps.',
+  'Patch bad placements with AI-only placement tools, rerender, and reinspect before completion.',
+  'If visual evidence is ambiguous, report UNCERTAIN and ask the user instead of declaring the review correct.',
+];
+const SOURCE_BOUNDARY_PASS_EVIDENCE_FORMAT = [
+  'PASS evidence must use this form: LEFT=<visible source linework>, RIGHT=<visible source linework>, TOP=<visible source linework>, BOTTOM=<visible source linework>, EXCLUDED=<labels/dimensions/wall/tile/counter/floor/toekick/context excluded>.',
+  'Each side must cite visible drawing geometry, such as cabinet side stile, door/front edge, carcass side, plan footprint edge, appliance front edge, plinth top/bottom line, countertop underside/top exclusion, or floor/Z0 line.',
+  'Do not write PASS when a side is justified by label position, generated bbox adjacency, non-overlap, broad run region, expected catalog size, or a dimension string alone.',
+];
+const SOURCE_BOUNDARY_FAIL_CONDITIONS = [
+  'Any bbox edge floats in blank/context area instead of on visible source linework.',
+  'Any bbox edge is aligned to label text, broad run area, tile hatch/backsplash, dimension string, generated bbox adjacency, or expected size rather than the visible object boundary.',
+  'The bbox includes wall, ceiling, floor, countertop, tile/backsplash hatch, appliance/hood context, neighboring cabinet, labels, or dimension text that is not part of the represented object.',
+  'The reviewer cannot name visible LEFT/RIGHT/TOP/BOTTOM source boundaries for the placement.',
+];
+const BASE_SOURCE_BOUNDARY_CHECKLIST = [
+  'Verify against the full source image, not against the orange plinth bbox or another generated bbox.',
+  'Blue base cabinet body bottom must stop at the visible transition from cabinet/front/carcass body to the separate toekick/plinth band.',
+  'Blue base cabinet body top must exclude any visible countertop line, slab, overhang, or counter thickness.',
+  'Blue base cabinet body must not extend below the visible floor/Z0 line or into floor/wall/context area.',
+  'If the visible drawing does not clearly show the body bottom, plinth band, floor/Z0, and countertop relationship, mark UNCERTAIN instead of PASS.',
+];
+const PLAN_FOOTPRINT_SOURCE_BOUNDARY_CHECKLIST = [
+  'Verify against the full source plan image, not against labels, broad run regions, dimensions, or evidence prose.',
+  'Blue plan bbox must cover only the actual cabinet/appliance footprint linework in plan view.',
+  'Blue plan bbox must not include labels, room/floor area, walls, dimension strings, dashed clearance lines, counter overhang context, neighboring cabinets, or unrelated broad run areas.',
+  'If the visible plan footprint is obscured or not clearly bounded, mark UNCERTAIN instead of PASS.',
+];
+const ELEVATION_FACE_SOURCE_BOUNDARY_CHECKLIST = [
+  'Verify against the full source elevation image, not against labels, broad run regions, dimensions, or evidence prose.',
+  'Blue elevation bbox must cover only the visible cabinet/appliance front face represented by that placement.',
+  'Blue elevation bbox must not include tile/backsplash hatch, wall, ceiling, floor, countertop, hood, appliance context, adjacent cabinets, labels, dimensions, or blank/context area.',
+  'If the visible face boundary is obscured or not clearly bounded, mark UNCERTAIN instead of PASS.',
+];
+const PLINTH_SOURCE_BOUNDARY_CHECKLIST = [
+  'Verify against the full source image, not against the blue base cabinet bbox.',
+  'Orange plinth/toekick bbox must cover the actual visible toekick/plinth band in the drawing, not a synthetic strip placed under the generated base bbox.',
+  'Orange plinth/toekick bbox must not extend below the visible floor/Z0 line or include floor/wall/context area.',
+  'Orange plinth/toekick bbox should align with the visible plinth band height and run width shown by source linework.',
+  'If the visible drawing does not clearly show the plinth/toekick band, mark UNCERTAIN instead of PASS.',
+];
+
+export function renderAiDrawingSessionReview(
+  state: AiDrawingStateLike,
+  options: AiDrawingSessionReviewRenderOptions
+): AiDrawingSessionReviewManifest {
+  if (!options.outputDir?.trim()) {
+    throw new Error('outputDir is required for AI drawing session review artifacts');
+  }
+
+  fs.mkdirSync(options.outputDir, { recursive: true });
+
+  const requestedCanvases = normalizeRequestedCanvases(state, options.canvases);
+  const cartItems = normalizeArray<CartItemLike>(state.activeCart?.items);
+  const placements = normalizeArray<PlacementLike>(state.canvasCabinetPlacements);
+  const results = requestedCanvases.map((canvasType) => renderCanvasReview(
+    state,
+    canvasType,
+    placements.filter((placement) => placement.canvasType === canvasType),
+    cartItems,
+    options
+  ));
+
+  const cartItemIssues = buildCartItemsWithoutPlacementIssues(cartItems, placements);
+
+  const manifest: AiDrawingSessionReviewManifest = {
+    sessionId: stringifyId(state.session?.id ?? state.session?.sessionId),
+    generatedAt: new Date().toISOString(),
+    visualInspectionRequired: true,
+    visualReviewStatus: 'requires_native_vision',
+    completionBlockedUntil:
+      'Resolve every source_boundary_review_required issue by opening every full-canvas outputImagePath with native vision, comparing each placement against source drawing pixels, recording PASS/FAIL/UNCERTAIN per canvas and placement, patching failures, and rerendering.',
+    visualInspectionChecklist: VISUAL_INSPECTION_CHECKLIST,
+    canvases: results,
+    issues: [...results.flatMap((result) => result.issues), ...cartItemIssues],
+  };
+
+  if (options.writeJsonManifest) {
+    const manifestPath = path.join(options.outputDir, options.manifestFileName ?? 'ai-drawing-session-review-manifest.json');
+    fs.writeFileSync(manifestPath, JSON.stringify({ ...manifest, manifestPath }, null, 2), 'utf8');
+    manifest.manifestPath = manifestPath;
+  }
+
+  return manifest;
+}
+
+function renderCanvasReview(
+  state: AiDrawingStateLike,
+  canvasType: AiDrawingReviewCanvasType,
+  placements: PlacementLike[],
+  cartItems: CartItemLike[],
+  options: AiDrawingSessionReviewRenderOptions
+): AiDrawingSessionReviewCanvasResult {
+  const issues: AiDrawingSessionReviewIssue[] = [];
+  const background = resolveBackgroundImage(state, canvasType, options);
+
+  if (!background.path) {
+    issues.push(background.issue ?? {
+      code: 'missing_background_image',
+      severity: 'warning',
+      canvasType,
+      message: `Canvas ${canvasType} has no renderable local background image.`,
+    });
+    return {
+      canvasType,
+      renderedPlacementCount: 0,
+      sourceBoundaryReviewTasks: [],
+      issues: addCanvasPlacementIssues(canvasType, placements, cartItems, undefined, issues),
+    };
+  }
+
+  const rawImage = readPngBackground(background.path, canvasType, background.reference, issues);
+  if (!rawImage) {
+    return {
+      canvasType,
+      renderedPlacementCount: 0,
+      sourceBoundaryReviewTasks: [],
+      issues: addCanvasPlacementIssues(canvasType, placements, cartItems, undefined, issues),
+    };
+  }
+
+  const image = clonePng(rawImage);
+  const renderablePlacements = buildRenderablePlacements(canvasType, placements, cartItems, image.width, image.height, issues);
+  addPlacementOverlapIssues(canvasType, renderablePlacements, issues);
+  addPlacementCategoryConflictIssues(canvasType, renderablePlacements, issues);
+  addMissingPlinthIssues(canvasType, renderablePlacements, issues);
+  const sourceBoundaryReviewTasks = buildSourceBoundaryReviewTasks(canvasType, renderablePlacements);
+  addSourceBoundaryReviewRequiredIssues(canvasType, sourceBoundaryReviewTasks, issues);
+  for (const renderable of renderablePlacements) {
+    drawPlacement(image, renderable);
+  }
+
+  const outputImagePath = path.join(
+    options.outputDir,
+    `ai-drawing-session-review-${sanitizeFilePart(stringifyId(state.session?.id ?? state.session?.sessionId) ?? 'session')}-${canvasType}.png`
+  );
+  fs.writeFileSync(outputImagePath, PNG.sync.write(image));
+
+  return {
+    canvasType,
+    outputImagePath,
+    imageWidth: image.width,
+    imageHeight: image.height,
+    renderedPlacementCount: renderablePlacements.length,
+    sourceBoundaryReviewTasks,
+    issues: addCanvasPlacementIssues(canvasType, placements, cartItems, { width: image.width, height: image.height }, issues),
+  };
+}
+
+function normalizeRequestedCanvases(
+  state: AiDrawingStateLike,
+  requestedCanvases: AiDrawingReviewCanvasType[] | undefined
+): AiDrawingReviewCanvasType[] {
+  const source = requestedCanvases?.length
+    ? requestedCanvases
+    : normalizeArray<unknown>(state.activeCanvases).filter(isCanvasType);
+  const normalized = source.filter(isCanvasType);
+  return normalized.length > 0 ? [...new Set(normalized)] : ['plan'];
+}
+
+function resolveBackgroundImage(
+  state: AiDrawingStateLike,
+  canvasType: AiDrawingReviewCanvasType,
+  options: AiDrawingSessionReviewRenderOptions
+): { path?: string; reference?: string; issue?: AiDrawingSessionReviewIssue } {
+  const explicitPath = options.imagePathByCanvas?.[canvasType];
+  if (explicitPath) {
+    return resolveLocalImageReference(explicitPath, canvasType, options);
+  }
+
+  const image = normalizeArray<CanvasImageLike>(state.canvasImages).find((candidate) => (
+    candidate.canvasType === canvasType &&
+    String(candidate.imageType ?? '').toLowerCase() === 'background'
+  ));
+
+  const reference = stringifyId(image?.imagePath ?? image?.path ?? image?.s3Key);
+  if (!reference) {
+    return {
+      issue: {
+        code: 'missing_background_image',
+        severity: 'warning',
+        canvasType,
+        message: `Canvas ${canvasType} has no background image reference.`,
+      },
+    };
+  }
+
+  return resolveLocalImageReference(reference, canvasType, options);
+}
+
+function resolveLocalImageReference(
+  reference: string,
+  canvasType: AiDrawingReviewCanvasType,
+  options: AiDrawingSessionReviewRenderOptions
+): { path?: string; reference: string; issue?: AiDrawingSessionReviewIssue } {
+  if (/^https?:\/\//i.test(reference)) {
+    return {
+      reference,
+      issue: {
+        code: 'unsupported_background_image_reference',
+        severity: 'warning',
+        canvasType,
+        imageReference: reference,
+        message: `Canvas ${canvasType} background image is not a local file reference and cannot be rendered in this phase.`,
+      },
+    };
+  }
+
+  const withoutFileScheme = reference.startsWith('file://')
+    ? decodeURIComponent(reference.slice('file://'.length))
+    : reference;
+  const candidates = [
+    withoutFileScheme,
+    ...((options.localArtifactRoots ?? []).map((root) => path.join(root, withoutFileScheme))),
+  ];
+
+  const resolved = candidates.find((candidate) => path.isAbsolute(candidate) && fs.existsSync(candidate));
+  if (!resolved) {
+    return {
+      reference,
+      issue: {
+        code: 'unsupported_background_image_reference',
+        severity: 'warning',
+        canvasType,
+        imageReference: reference,
+        message: `Canvas ${canvasType} background image reference is not a readable local file.`,
+      },
+    };
+  }
+
+  if (path.extname(resolved).toLowerCase() !== '.png') {
+    return {
+      reference,
+      issue: {
+        code: 'unsupported_background_image_reference',
+        severity: 'warning',
+        canvasType,
+        imageReference: reference,
+        message: `Canvas ${canvasType} background image is local but not a PNG file supported by this renderer.`,
+      },
+    };
+  }
+
+  return { path: resolved, reference };
+}
+
+function readPngBackground(
+  imagePath: string,
+  canvasType: AiDrawingReviewCanvasType,
+  reference: string | undefined,
+  issues: AiDrawingSessionReviewIssue[]
+): PNG | null {
+  try {
+    return PNG.sync.read(fs.readFileSync(imagePath));
+  } catch (error) {
+    issues.push({
+      code: 'background_image_read_failed',
+      severity: 'error',
+      canvasType,
+      imageReference: reference ?? imagePath,
+      message: `Canvas ${canvasType} background image could not be read as PNG: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return null;
+  }
+}
+
+function buildRenderablePlacements(
+  canvasType: AiDrawingReviewCanvasType,
+  placements: PlacementLike[],
+  cartItems: CartItemLike[],
+  imageWidth: number,
+  imageHeight: number,
+  issues: AiDrawingSessionReviewIssue[]
+): RenderablePlacement[] {
+  const cartLookup = buildCartLookup(cartItems);
+  const renderable: RenderablePlacement[] = [];
+
+  for (const placement of placements) {
+    const positionName = stringifyId(placement.positionName);
+    const aiCartItemId = stringifyId(placement.aiCartItemId);
+    if (!positionName) {
+      continue;
+    }
+
+    const placementSpace = String(placement.placementSpace ?? 'IMAGE_PIXELS').toUpperCase();
+    if (placementSpace !== 'IMAGE_PIXELS') {
+      issues.push({
+        code: 'non_image_pixels_placement_space',
+        severity: 'error',
+        canvasType,
+        positionName,
+        aiCartItemId,
+        message: `Placement ${positionName} on ${canvasType} uses unsupported placementSpace ${placement.placementSpace}.`,
+      });
+      continue;
+    }
+
+    const centerX = toFiniteNumber(placement.centerX);
+    const centerY = toFiniteNumber(placement.centerY);
+    const width = toFiniteNumber(placement.width);
+    const height = toFiniteNumber(placement.height);
+    if (centerX === null || centerY === null || width === null || height === null || width <= 0 || height <= 0) {
+      issues.push({
+        code: 'invalid_placement_dimensions',
+        severity: 'error',
+        canvasType,
+        positionName,
+        aiCartItemId,
+        message: `Placement ${positionName} on ${canvasType} has missing, zero, negative, or non-finite rectangle dimensions.`,
+      });
+      continue;
+    }
+
+    const basisWidth = toFiniteNumber(placement.basisImageWidthPx);
+    const basisHeight = toFiniteNumber(placement.basisImageHeightPx);
+    const hasValidBasis = basisWidth !== null && basisHeight !== null && basisWidth > 0 && basisHeight > 0;
+    if (!hasValidBasis) {
+      issues.push({
+        code: 'missing_or_invalid_basis_image_dimensions',
+        severity: 'warning',
+        canvasType,
+        positionName,
+        aiCartItemId,
+        message: `Placement ${positionName} on ${canvasType} has missing or invalid basis image dimensions.`,
+      });
+    }
+
+    const scaleX = hasValidBasis ? imageWidth / basisWidth : 1;
+    const scaleY = hasValidBasis ? imageHeight / basisHeight : 1;
+    const rotation = toFiniteNumber(placement.rotation) ?? 0;
+    const matchingCartItem = findMatchingCartItem(placement, cartLookup);
+    const placementCategory: RenderablePlacement['placementCategory'] = isPlinthPlacement(placement, matchingCartItem)
+      ? 'plinth'
+      : 'cabinet';
+
+    if (!matchingCartItem) {
+      issues.push({
+        code: 'placement_without_matching_cart_item',
+        severity: 'warning',
+        canvasType,
+        positionName,
+        aiCartItemId,
+        message: `Placement ${positionName} on ${canvasType} does not match an active AI cart item.`,
+      });
+    }
+
+    const scaledPlacement = {
+      placement,
+      positionName,
+      aiCartItemId,
+      centerX,
+      centerY,
+      width,
+      height,
+      rotation,
+      scaleX,
+      scaleY,
+      label: buildPlacementLabel(positionName, matchingCartItem, aiCartItemId),
+      placementCategory,
+    };
+
+    if (isPlacementOutsideImageBounds(scaledPlacement, imageWidth, imageHeight)) {
+      issues.push({
+        code: 'placement_outside_image_bounds',
+        severity: 'warning',
+        canvasType,
+        positionName,
+        aiCartItemId,
+        message: `Placement ${positionName} on ${canvasType} extends outside the background image bounds.`,
+      });
+    }
+
+    renderable.push(scaledPlacement);
+  }
+
+  return renderable;
+}
+
+function addCanvasPlacementIssues(
+  canvasType: AiDrawingReviewCanvasType,
+  placements: PlacementLike[],
+  cartItems: CartItemLike[],
+  imageSize: { width: number; height: number } | undefined,
+  issues: AiDrawingSessionReviewIssue[]
+): AiDrawingSessionReviewIssue[] {
+  const nextIssues = [...issues];
+  if (placements.length === 0) {
+    nextIssues.push({
+      code: 'canvas_with_no_placements',
+      severity: cartItems.length > 0 ? 'error' : 'warning',
+      canvasType,
+      message: cartItems.length > 0
+        ? `Canvas ${canvasType} has AI cart items but no stored per-canvas cabinet placements. A drawing session/cart creation pass is not complete until visible cabinets are placed and reviewed.`
+        : `Canvas ${canvasType} has no stored per-canvas cabinet placements.`,
+    });
+  }
+
+  const seenPositionNames = new Set<string>();
+  const duplicatePositionNames = new Set<string>();
+  for (const placement of placements) {
+    const positionName = stringifyId(placement.positionName);
+    if (!positionName) {
+      continue;
+    }
+    if (seenPositionNames.has(positionName)) {
+      duplicatePositionNames.add(positionName);
+    }
+    seenPositionNames.add(positionName);
+  }
+  for (const positionName of duplicatePositionNames) {
+    nextIssues.push({
+      code: 'duplicate_position_name_on_canvas',
+      severity: 'error',
+      canvasType,
+      positionName,
+      message: `Canvas ${canvasType} has duplicate placement positionName ${positionName}.`,
+    });
+  }
+
+  if (!imageSize) {
+    const cartLookup = buildCartLookup(cartItems);
+    for (const placement of placements) {
+      const positionName = stringifyId(placement.positionName);
+      if (positionName && !findMatchingCartItem(placement, cartLookup)) {
+        nextIssues.push({
+          code: 'placement_without_matching_cart_item',
+          severity: 'warning',
+          canvasType,
+          positionName,
+          aiCartItemId: stringifyId(placement.aiCartItemId),
+          message: `Placement ${positionName} on ${canvasType} does not match an active AI cart item.`,
+        });
+      }
+    }
+  }
+
+  return nextIssues;
+}
+
+function addPlacementOverlapIssues(
+  canvasType: AiDrawingReviewCanvasType,
+  renderablePlacements: RenderablePlacement[],
+  issues: AiDrawingSessionReviewIssue[]
+): void {
+  for (let firstIndex = 0; firstIndex < renderablePlacements.length; firstIndex += 1) {
+    for (let secondIndex = firstIndex + 1; secondIndex < renderablePlacements.length; secondIndex += 1) {
+      const first = renderablePlacements[firstIndex];
+      const second = renderablePlacements[secondIndex];
+      if (first.positionName === second.positionName) {
+        continue;
+      }
+
+      const overlap = calculateAxisAlignedOverlap(first, second);
+      if (!overlap) {
+        continue;
+      }
+
+      const smallerArea = Math.min(overlap.firstArea, overlap.secondArea);
+      const overlapRatio = smallerArea > 0 ? overlap.area / smallerArea : 0;
+      if (overlap.area < 16 || overlapRatio < 0.02) {
+        continue;
+      }
+
+      issues.push({
+        code: 'placement_overlap',
+        severity: 'warning',
+        canvasType,
+        positionName: first.positionName,
+        relatedPositionName: second.positionName,
+        aiCartItemId: first.aiCartItemId,
+        message:
+          `Canvas ${canvasType} placements ${first.positionName} and ${second.positionName} overlap by ` +
+          `${Math.round(overlap.area)} rendered pixels (${Math.round(overlapRatio * 100)}% of the smaller rectangle). ` +
+          'Verify this is intentional; cabinet placement boxes should not overlap separate cabinets, appliances, fixtures, counters, toe kicks, walls, labels, or blank/context areas.',
+      });
+    }
+  }
+}
+
+function addMissingPlinthIssues(
+  canvasType: AiDrawingReviewCanvasType,
+  renderablePlacements: RenderablePlacement[],
+  issues: AiDrawingSessionReviewIssue[]
+): void {
+  if (canvasType === 'plan') {
+    return;
+  }
+
+  const basePlacements = renderablePlacements.filter(isBaseCabinetPlacement);
+  if (basePlacements.length === 0 || renderablePlacements.some((placement) => placement.placementCategory === 'plinth')) {
+    return;
+  }
+
+  issues.push({
+    code: 'base_elevation_without_plinth_placement',
+    severity: 'warning',
+    canvasType,
+    positionName: basePlacements.map((placement) => placement.positionName).join(', '),
+    message:
+      `Canvas ${canvasType} has base/sink cabinet placements but no separate orange plinth/toekick placement. ` +
+      'If a lower support/toekick band is visible, create one or more separate plinth AI cart items and orange placements, ' +
+      'then shrink the blue base cabinet boxes so they exclude plinth/toekick height. Do not mark review PASS until the plinth decision is visually verified.',
+  });
+}
+
+function addPlacementCategoryConflictIssues(
+  canvasType: AiDrawingReviewCanvasType,
+  renderablePlacements: RenderablePlacement[],
+  issues: AiDrawingSessionReviewIssue[]
+): void {
+  for (const placement of renderablePlacements) {
+    if (placement.placementCategory === 'plinth' && isBaseCabinetPlacement(placement)) {
+      issues.push({
+        code: 'placement_category_conflict',
+        severity: 'error',
+        canvasType,
+        positionName: placement.positionName,
+        aiCartItemId: placement.aiCartItemId,
+        message:
+          `Placement ${placement.positionName} on ${canvasType} is linked to a base/sink cabinet but was categorized as plinth. ` +
+          'Review cannot pass with base cabinet overlays rendered orange; classify the base cabinet as a blue cabinet placement and keep the plinth/toekick as a separate orange placement.',
+      });
+    }
+  }
+}
+
+function buildSourceBoundaryReviewTasks(
+  canvasType: AiDrawingReviewCanvasType,
+  renderablePlacements: RenderablePlacement[]
+): AiDrawingSourceBoundaryReviewTask[] {
+  const tasks: AiDrawingSourceBoundaryReviewTask[] = [];
+  for (const placement of renderablePlacements) {
+    if (canvasType === 'plan') {
+      tasks.push({
+        canvasType,
+        positionName: placement.positionName,
+        aiCartItemId: placement.aiCartItemId,
+        placementCategory: 'plan_footprint',
+        sourceImageAuthority: true,
+        passRequiresEvidenceFormat: SOURCE_BOUNDARY_PASS_EVIDENCE_FORMAT,
+        failIf: SOURCE_BOUNDARY_FAIL_CONDITIONS,
+        checklist: PLAN_FOOTPRINT_SOURCE_BOUNDARY_CHECKLIST,
+      });
+      continue;
+    }
+
+    if (isBaseCabinetPlacement(placement)) {
+      tasks.push({
+        canvasType,
+        positionName: placement.positionName,
+        aiCartItemId: placement.aiCartItemId,
+        placementCategory: 'base_cabinet_body',
+        sourceImageAuthority: true,
+        passRequiresEvidenceFormat: SOURCE_BOUNDARY_PASS_EVIDENCE_FORMAT,
+        failIf: SOURCE_BOUNDARY_FAIL_CONDITIONS,
+        checklist: BASE_SOURCE_BOUNDARY_CHECKLIST,
+      });
+      continue;
+    }
+
+    if (placement.placementCategory === 'plinth') {
+      tasks.push({
+        canvasType,
+        positionName: placement.positionName,
+        aiCartItemId: placement.aiCartItemId,
+        placementCategory: 'plinth_toekick',
+        sourceImageAuthority: true,
+        passRequiresEvidenceFormat: SOURCE_BOUNDARY_PASS_EVIDENCE_FORMAT,
+        failIf: SOURCE_BOUNDARY_FAIL_CONDITIONS,
+        checklist: PLINTH_SOURCE_BOUNDARY_CHECKLIST,
+      });
+      continue;
+    }
+
+    tasks.push({
+      canvasType,
+      positionName: placement.positionName,
+      aiCartItemId: placement.aiCartItemId,
+      placementCategory: 'cabinet_face',
+      sourceImageAuthority: true,
+      passRequiresEvidenceFormat: SOURCE_BOUNDARY_PASS_EVIDENCE_FORMAT,
+      failIf: SOURCE_BOUNDARY_FAIL_CONDITIONS,
+      checklist: ELEVATION_FACE_SOURCE_BOUNDARY_CHECKLIST,
+    });
+  }
+
+  return tasks;
+}
+
+function addSourceBoundaryReviewRequiredIssues(
+  canvasType: AiDrawingReviewCanvasType,
+  tasks: AiDrawingSourceBoundaryReviewTask[],
+  issues: AiDrawingSessionReviewIssue[]
+): void {
+  for (const task of tasks) {
+    issues.push({
+      code: 'source_boundary_review_required',
+      severity: 'error',
+      canvasType,
+      positionName: task.positionName,
+      aiCartItemId: task.aiCartItemId,
+      message:
+        `Canvas ${canvasType} placement ${task.positionName} requires full-source-image boundary review for ${task.placementCategory}. ` +
+        'This is a blocking review task: non-overlap, adjacency, labels, dimensions, and evidence prose do not prove visual correctness. ' +
+        'Open the full-canvas overlay, compare against the source drawing pixels, and record PASS/FAIL/UNCERTAIN before claiming completion.',
+    });
+  }
+}
+
+function calculateAxisAlignedOverlap(
+  first: RenderablePlacement,
+  second: RenderablePlacement
+): { area: number; firstArea: number; secondArea: number } | null {
+  const firstBounds = getAxisAlignedBounds(first);
+  const secondBounds = getAxisAlignedBounds(second);
+  const width = Math.max(0, Math.min(firstBounds.right, secondBounds.right) - Math.max(firstBounds.left, secondBounds.left));
+  const height = Math.max(0, Math.min(firstBounds.bottom, secondBounds.bottom) - Math.max(firstBounds.top, secondBounds.top));
+  const area = width * height;
+  return area > 0
+    ? { area, firstArea: firstBounds.area, secondArea: secondBounds.area }
+    : null;
+}
+
+function getAxisAlignedBounds(renderable: RenderablePlacement): {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  area: number;
+} {
+  const corners = getScaledRotatedCorners(renderable);
+  const left = Math.min(...corners.map((corner) => corner.x));
+  const right = Math.max(...corners.map((corner) => corner.x));
+  const top = Math.min(...corners.map((corner) => corner.y));
+  const bottom = Math.max(...corners.map((corner) => corner.y));
+  return {
+    left,
+    top,
+    right,
+    bottom,
+    area: Math.max(0, right - left) * Math.max(0, bottom - top),
+  };
+}
+
+function buildCartItemsWithoutPlacementIssues(
+  cartItems: CartItemLike[],
+  placements: PlacementLike[]
+): AiDrawingSessionReviewIssue[] {
+  const issues: AiDrawingSessionReviewIssue[] = [];
+  for (const item of cartItems) {
+    const itemId = stringifyId(item.id ?? item.aiCartItemId);
+    const positionName = stringifyId(item.positionName);
+    const hasPlacement = placements.some((placement) => (
+      (itemId && stringifyId(placement.aiCartItemId) === itemId) ||
+      (positionName && stringifyId(placement.positionName) === positionName)
+    ));
+    if (!hasPlacement) {
+      issues.push({
+        code: 'cart_item_without_placement',
+        severity: 'warning',
+        positionName,
+        aiCartItemId: itemId,
+        message: `AI cart item ${positionName ?? itemId ?? 'unknown'} has no stored placement on any canvas.`,
+      });
+    }
+  }
+  return issues;
+}
+
+function drawPlacement(image: PNG, renderable: RenderablePlacement): void {
+  const fill = renderable.placementCategory === 'plinth' ? PLINTH_PLACEMENT_FILL : CABINET_PLACEMENT_FILL;
+  const stroke = renderable.placementCategory === 'plinth' ? PLINTH_PLACEMENT_STROKE : CABINET_PLACEMENT_STROKE;
+  const corners = getScaledRotatedCorners(renderable);
+  fillPolygon(image, corners, fill);
+  drawPolygonOutline(image, corners, stroke, 2);
+
+  const centerX = Math.round(renderable.centerX * renderable.scaleX);
+  const centerY = Math.round(renderable.centerY * renderable.scaleY);
+  drawLine(image, centerX - 4, centerY, centerX + 4, centerY, ISSUE_MARK, 1);
+  drawLine(image, centerX, centerY - 4, centerX, centerY + 4, ISSUE_MARK, 1);
+  drawLabel(image, renderable.label, centerX, centerY);
+}
+
+function clonePng(image: PNG): PNG {
+  const cloned = new PNG({ width: image.width, height: image.height });
+  image.data.copy(cloned.data);
+  return cloned;
+}
+
+function getScaledRotatedCorners(renderable: RenderablePlacement): Array<{ x: number; y: number }> {
+  const centerX = renderable.centerX * renderable.scaleX;
+  const centerY = renderable.centerY * renderable.scaleY;
+  const halfWidth = (renderable.width * renderable.scaleX) / 2;
+  const halfHeight = (renderable.height * renderable.scaleY) / 2;
+  const angle = (renderable.rotation * Math.PI) / 180;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+
+  return [
+    { x: -halfWidth, y: -halfHeight },
+    { x: halfWidth, y: -halfHeight },
+    { x: halfWidth, y: halfHeight },
+    { x: -halfWidth, y: halfHeight },
+  ].map((point) => ({
+    x: centerX + point.x * cos - point.y * sin,
+    y: centerY + point.x * sin + point.y * cos,
+  }));
+}
+
+function isPlacementOutsideImageBounds(renderable: RenderablePlacement, imageWidth: number, imageHeight: number): boolean {
+  return getScaledRotatedCorners(renderable).some((corner) => (
+    corner.x < 0 || corner.y < 0 || corner.x > imageWidth || corner.y > imageHeight
+  ));
+}
+
+function fillPolygon(image: PNG, points: Array<{ x: number; y: number }>, color: Rgba): void {
+  const minX = Math.max(0, Math.floor(Math.min(...points.map((point) => point.x))));
+  const maxX = Math.min(image.width - 1, Math.ceil(Math.max(...points.map((point) => point.x))));
+  const minY = Math.max(0, Math.floor(Math.min(...points.map((point) => point.y))));
+  const maxY = Math.min(image.height - 1, Math.ceil(Math.max(...points.map((point) => point.y))));
+
+  for (let y = minY; y <= maxY; y += 1) {
+    for (let x = minX; x <= maxX; x += 1) {
+      if (pointInPolygon(x + 0.5, y + 0.5, points)) {
+        blendPixel(image, x, y, color);
+      }
+    }
+  }
+}
+
+function drawPolygonOutline(
+  image: PNG,
+  points: Array<{ x: number; y: number }>,
+  color: Rgba,
+  thickness: number
+): void {
+  for (let index = 0; index < points.length; index += 1) {
+    const start = points[index];
+    const end = points[(index + 1) % points.length];
+    drawLine(image, start.x, start.y, end.x, end.y, color, thickness);
+  }
+}
+
+function drawLine(
+  image: PNG,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  color: Rgba,
+  thickness: number
+): void {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const steps = Math.max(Math.abs(dx), Math.abs(dy), 1);
+  for (let step = 0; step <= steps; step += 1) {
+    const x = Math.round(x1 + (dx * step) / steps);
+    const y = Math.round(y1 + (dy * step) / steps);
+    for (let tx = -thickness; tx <= thickness; tx += 1) {
+      for (let ty = -thickness; ty <= thickness; ty += 1) {
+        if (tx * tx + ty * ty <= thickness * thickness) {
+          blendPixel(image, x + tx, y + ty, color);
+        }
+      }
+    }
+  }
+}
+
+function drawLabel(image: PNG, label: string, centerX: number, centerY: number): void {
+  const compactLabel = label.toUpperCase().slice(0, 30);
+  const charWidth = 4;
+  const charHeight = 5;
+  const scale = 2;
+  const spacing = 1;
+  const labelWidth = compactLabel.length * charWidth * scale + Math.max(0, compactLabel.length - 1) * spacing * scale;
+  const labelHeight = charHeight * scale;
+  const x = Math.round(centerX - labelWidth / 2);
+  const y = Math.round(centerY - labelHeight / 2);
+
+  fillRect(image, x - 3, y - 3, labelWidth + 6, labelHeight + 6, LABEL_BACKGROUND);
+
+  let cursorX = x;
+  for (const char of compactLabel) {
+    drawChar(image, char, cursorX, y, scale, LABEL_TEXT);
+    cursorX += (charWidth + spacing) * scale;
+  }
+}
+
+function drawChar(
+  image: PNG,
+  char: string,
+  x: number,
+  y: number,
+  scale: number,
+  color: typeof LABEL_TEXT
+): void {
+  const pattern = FONT_3X5[char] ?? FONT_3X5['?'];
+  for (let row = 0; row < pattern.length; row += 1) {
+    for (let column = 0; column < pattern[row].length; column += 1) {
+      if (pattern[row][column] === '1') {
+        fillRect(image, x + column * scale, y + row * scale, scale, scale, color);
+      }
+    }
+  }
+}
+
+function fillRect(
+  image: PNG,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  color: typeof LABEL_BACKGROUND
+): void {
+  for (let py = Math.max(0, y); py < Math.min(image.height, y + height); py += 1) {
+    for (let px = Math.max(0, x); px < Math.min(image.width, x + width); px += 1) {
+      blendPixel(image, px, py, color);
+    }
+  }
+}
+
+function blendPixel(
+  image: PNG,
+  x: number,
+  y: number,
+  color: { r: number; g: number; b: number; a: number }
+): void {
+  if (x < 0 || y < 0 || x >= image.width || y >= image.height) {
+    return;
+  }
+  const offset = (Math.floor(y) * image.width + Math.floor(x)) * 4;
+  const sourceAlpha = color.a / 255;
+  const targetAlpha = image.data[offset + 3] / 255;
+  const outAlpha = sourceAlpha + targetAlpha * (1 - sourceAlpha);
+  if (outAlpha <= 0) {
+    return;
+  }
+
+  image.data[offset] = Math.round((color.r * sourceAlpha + image.data[offset] * targetAlpha * (1 - sourceAlpha)) / outAlpha);
+  image.data[offset + 1] = Math.round((color.g * sourceAlpha + image.data[offset + 1] * targetAlpha * (1 - sourceAlpha)) / outAlpha);
+  image.data[offset + 2] = Math.round((color.b * sourceAlpha + image.data[offset + 2] * targetAlpha * (1 - sourceAlpha)) / outAlpha);
+  image.data[offset + 3] = Math.round(outAlpha * 255);
+}
+
+function pointInPolygon(x: number, y: number, points: Array<{ x: number; y: number }>): boolean {
+  let inside = false;
+  for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+    const intersects = ((points[i].y > y) !== (points[j].y > y)) &&
+      (x < ((points[j].x - points[i].x) * (y - points[i].y)) / (points[j].y - points[i].y) + points[i].x);
+    if (intersects) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+function buildCartLookup(cartItems: CartItemLike[]): {
+  byId: Map<string, CartItemLike>;
+  byPositionName: Map<string, CartItemLike>;
+} {
+  const byId = new Map<string, CartItemLike>();
+  const byPositionName = new Map<string, CartItemLike>();
+  for (const item of cartItems) {
+    const itemId = stringifyId(item.id ?? item.aiCartItemId);
+    const positionName = stringifyId(item.positionName);
+    if (itemId) {
+      byId.set(itemId, item);
+    }
+    if (positionName) {
+      byPositionName.set(positionName, item);
+    }
+  }
+  return { byId, byPositionName };
+}
+
+function findMatchingCartItem(
+  placement: PlacementLike,
+  cartLookup: ReturnType<typeof buildCartLookup>
+): CartItemLike | undefined {
+  const placementItemId = stringifyId(placement.aiCartItemId);
+  const positionName = stringifyId(placement.positionName);
+  return (placementItemId ? cartLookup.byId.get(placementItemId) : undefined) ??
+    (positionName ? cartLookup.byPositionName.get(positionName) : undefined);
+}
+
+function isPlinthPlacement(placement: PlacementLike, cartItem: CartItemLike | undefined): boolean {
+  const serialNumber = stringifyId(cartItem?.serialNumber)?.toLowerCase();
+  if (serialNumber && isBaseOrSinkSerial(serialNumber)) {
+    return false;
+  }
+  if (serialNumber && isPlinthSerial(serialNumber)) {
+    return true;
+  }
+
+  const identityValues = getPlacementIdentityStrings(placement, cartItem);
+  if (identityValues.some(isBaseOrSinkIdentityValue)) {
+    return false;
+  }
+
+  return identityValues.some((value) => (
+    value === 'plinth' ||
+    value === 'toekick' ||
+    value === 'toe_kick' ||
+    value === 'toe-kick' ||
+    value.includes('plinth') ||
+    value.includes('toekick') ||
+    value.includes('toe kick') ||
+    value.includes('toe_kick') ||
+    value.includes('toe-kick')
+  ));
+}
+
+function isBaseCabinetPlacement(renderable: RenderablePlacement): boolean {
+  const searchableValues = [
+    ...getPlacementIdentityStrings(renderable.placement, undefined),
+    ...getPlacementSemanticStrings(renderable.placement, undefined),
+  ];
+  return searchableValues.some((value) => (
+    isBaseOrSinkIdentityValue(value) ||
+    value.includes('base cabinet') ||
+    value.includes('sink base') ||
+    value.includes('base_')
+  )) || /BC_/i.test(renderable.label) || /(^|[^a-z])base([^a-z]|$)/i.test(renderable.label);
+}
+
+function getPlacementIdentityStrings(placement: PlacementLike, cartItem: CartItemLike | undefined): string[] {
+  return [
+    stringifyId(placement.objectType),
+    stringifyId(placement.positionName),
+    stringifyId(cartItem?.positionName),
+    stringifyId(cartItem?.serialNumber),
+    stringifyId(cartItem?.displayName),
+    ...getReviewedObjectTypeStrings(placement.drawingClassificationEvidence),
+    ...getReviewedObjectTypeStrings(placement.viewAssociationEvidence),
+    ...getReviewedObjectTypeStrings(cartItem?.drawingClassificationEvidence),
+    ...getReviewedObjectTypeStrings(cartItem?.itemPayload),
+    ...getReviewedObjectTypeStrings(cartItem?.originalItemPayload),
+    ...getReviewedObjectTypeStrings(cartItem?.orderReadyPayload),
+  ]
+    .filter(Boolean)
+    .map((value) => value!.toLowerCase());
+}
+
+function isBaseOrSinkSerial(value: string): boolean {
+  return /^bc[_-]/.test(value) ||
+    /^sb\d*/.test(value) ||
+    /^uc[_-][a-z0-9]+[_-]b\d+/i.test(value) ||
+    /^uc[_-].*[_-]base/i.test(value);
+}
+
+function isPlinthSerial(value: string): boolean {
+  return /^lp[_-]pl[_-]/.test(value) || /^lp[_-].*plinth/.test(value);
+}
+
+function isBaseOrSinkIdentityValue(value: string): boolean {
+  return value === 'base_cabinet' ||
+    value === 'sink_base' ||
+    isBaseOrSinkSerial(value) ||
+    /^uc[_-][a-z0-9]+[_-]b\d+/i.test(value) ||
+    /^base([_\s.-]|$)/.test(value) ||
+    /(^|[^a-z])base([^a-z]|$)/.test(value) ||
+    /(^|[^a-z])sink base([^a-z]|$)/.test(value);
+}
+
+function getPlacementSemanticStrings(placement: PlacementLike, cartItem: CartItemLike | undefined): string[] {
+  return [
+    stringifyId(placement.objectType),
+    stringifyId(placement.positionName),
+    stringifyId(cartItem?.positionName),
+    stringifyId(cartItem?.serialNumber),
+    stringifyId(cartItem?.displayName),
+    ...collectSemanticStrings(placement.drawingClassificationEvidence),
+    ...collectSemanticStrings(placement.viewAssociationEvidence),
+    ...collectSemanticStrings(cartItem?.drawingClassificationEvidence),
+    ...collectSemanticStrings(cartItem?.itemPayload),
+    ...collectSemanticStrings(cartItem?.originalItemPayload),
+    ...collectSemanticStrings(cartItem?.orderReadyPayload),
+  ]
+    .filter(Boolean)
+    .map((value) => value!.toLowerCase());
+}
+
+function getReviewedObjectTypeStrings(value: unknown, depth = 0): string[] {
+  if (value === null || value === undefined || depth > 4) {
+    return [];
+  }
+  if (typeof value === 'string') {
+    const parsed = parseJsonObject(value);
+    return parsed ? getReviewedObjectTypeStrings(parsed, depth + 1) : [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => getReviewedObjectTypeStrings(item, depth + 1));
+  }
+  if (typeof value !== 'object') {
+    return [];
+  }
+
+  const record = value as Record<string, unknown>;
+  const directObjectType = stringifyId(record.objectType);
+  const objectTypeValues = directObjectType ? [directObjectType] : [];
+  return [
+    ...objectTypeValues,
+    ...getReviewedObjectTypeStrings(record.sourceElevationObject, depth + 1),
+    ...getReviewedObjectTypeStrings(record.sourcePlanObject, depth + 1),
+  ];
+}
+
+function collectSemanticStrings(value: unknown, depth = 0): string[] {
+  if (value === null || value === undefined || depth > 4) {
+    return [];
+  }
+  if (typeof value === 'string') {
+    const parsed = parseJsonObject(value);
+    return parsed ? collectSemanticStrings(parsed, depth + 1) : [value];
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return [String(value)];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => collectSemanticStrings(item, depth + 1));
+  }
+  if (typeof value === 'object') {
+    return Object.values(value as Record<string, unknown>).flatMap((item) => collectSemanticStrings(item, depth + 1));
+  }
+  return [];
+}
+
+function parseJsonObject(value: string): Record<string, unknown> | unknown[] | null {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildPlacementLabel(positionName: string, cartItem: CartItemLike | undefined, aiCartItemId: string | undefined): string {
+  const serialNumber = stringifyId(cartItem?.serialNumber);
+  if (serialNumber) {
+    return `${positionName} ${serialNumber}`;
+  }
+  const traceId = aiCartItemId ? shortId(aiCartItemId) : undefined;
+  return traceId ? `${positionName} ${traceId}` : positionName;
+}
+
+function normalizeArray<T>(value: unknown): T[] {
+  if (!value) {
+    return [];
+  }
+  return Array.isArray(value) ? value as T[] : [value as T];
+}
+
+function isCanvasType(value: unknown): value is AiDrawingReviewCanvasType {
+  return typeof value === 'string' && (CANVAS_TYPES as string[]).includes(value);
+}
+
+function stringifyId(value: unknown): string | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  const stringValue = String(value).trim();
+  return stringValue.length > 0 ? stringValue : undefined;
+}
+
+function toFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function shortId(value: string): string {
+  return value.replace(/-/g, '').slice(0, 8);
+}
+
+function sanitizeFilePart(value: string): string {
+  return value.replace(/[^a-z0-9_-]+/gi, '_').slice(0, 80);
+}
+
+const FONT_3X5: Record<string, string[]> = {
+  ' ': ['000', '000', '000', '000', '000'],
+  '?': ['111', '001', '011', '000', '010'],
+  '-': ['000', '000', '111', '000', '000'],
+  '_': ['000', '000', '000', '000', '111'],
+  '0': ['111', '101', '101', '101', '111'],
+  '1': ['010', '110', '010', '010', '111'],
+  '2': ['111', '001', '111', '100', '111'],
+  '3': ['111', '001', '111', '001', '111'],
+  '4': ['101', '101', '111', '001', '001'],
+  '5': ['111', '100', '111', '001', '111'],
+  '6': ['111', '100', '111', '101', '111'],
+  '7': ['111', '001', '010', '010', '010'],
+  '8': ['111', '101', '111', '101', '111'],
+  '9': ['111', '101', '111', '001', '111'],
+  'A': ['010', '101', '111', '101', '101'],
+  'B': ['110', '101', '110', '101', '110'],
+  'C': ['111', '100', '100', '100', '111'],
+  'D': ['110', '101', '101', '101', '110'],
+  'E': ['111', '100', '110', '100', '111'],
+  'F': ['111', '100', '110', '100', '100'],
+  'G': ['111', '100', '101', '101', '111'],
+  'H': ['101', '101', '111', '101', '101'],
+  'I': ['111', '010', '010', '010', '111'],
+  'J': ['001', '001', '001', '101', '111'],
+  'K': ['101', '101', '110', '101', '101'],
+  'L': ['100', '100', '100', '100', '111'],
+  'M': ['101', '111', '111', '101', '101'],
+  'N': ['101', '111', '111', '111', '101'],
+  'O': ['111', '101', '101', '101', '111'],
+  'P': ['111', '101', '111', '100', '100'],
+  'Q': ['111', '101', '101', '111', '001'],
+  'R': ['111', '101', '111', '110', '101'],
+  'S': ['111', '100', '111', '001', '111'],
+  'T': ['111', '010', '010', '010', '010'],
+  'U': ['101', '101', '101', '101', '111'],
+  'V': ['101', '101', '101', '101', '010'],
+  'W': ['101', '101', '111', '111', '101'],
+  'X': ['101', '101', '010', '101', '101'],
+  'Y': ['101', '101', '010', '010', '010'],
+  'Z': ['111', '001', '010', '100', '111'],
+};