jspsych-tangram 0.0.1

package/src/core/engine/state/BaseGameController.ts

@@ -0,0 +1,368 @@
+/**
+ * BaseGameController with dependency injection - PHASE 2 MILESTONE
+ * 
+ * Maintains compatibility with existing RoundController API while implementing
+ * clean separation between configuration and data. All game content is injected
+ * via constructor parameters, no hardcoded defaults.
+ */
+
+import type { 
+  Blueprint, 
+  Sector, 
+  LayoutMode,
+  PlacementTarget,
+  InputMode,
+  RoundState,
+  SectorState,
+  TanKind,
+  PrimitiveBlueprint
+} from '../../domain/types';
+import { CONFIG } from '../../config/config';
+import { BlueprintRegistry } from '../../domain/blueprints';
+
+export interface GameConfig {
+  n: number;
+  layout: LayoutMode;
+  target: PlacementTarget;     // CRITICAL: "workspace" | "silhouette"
+  input: InputMode;            // CRITICAL: "click" | "drag"
+  timeLimitMs: number;
+  maxQuickstashSlots: number;
+  maxCompositeSize?: number;   // Optional - only used in prep mode
+  mode: "construction" | "prep"; // NEW: Distinguishes prep vs construction behavior
+  minPiecesPerMacro?: number;   // NEW: Minimum pieces required per macro (prep mode)
+  requireAllSlots?: boolean;    // NEW: Whether all slots must be filled (prep mode)
+}
+
+let PID = 0;
+const newId = () => `p_${++PID}`;
+const NOW = () => performance.now();
+
+// Event tracking callbacks (optional - set by InteractionTracker)
+export interface TrackingCallbacks {
+  onPiecePickup?: (pieceId: string, blueprintId: string, blueprintType: 'primitive' | 'composite', source: 'blueprint' | 'sector', position: { x: number; y: number }, vertices: number[][][], sectorId?: string) => void;
+  onPiecePlacedown?: (outcome: 'placed' | 'deleted', sectorId?: string, position?: { x: number; y: number }, vertices?: number[][][], anchorId?: string, wasValid?: boolean, wasOverlapping?: boolean) => void;
+  onClickEvent?: (location: { x: number; y: number }, anchorX: number, anchorY: number, clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt', metadata?: any) => void;
+  onMouseMove?: (anchorX: number, anchorY: number, sectorId?: string) => void;
+  onSectorCompleted?: (sectorId: string) => void;
+}
+
+export class BaseGameController {
+  // Core data - injected, not hardcoded
+  private sectors: Sector[];
+  private quickstash: Blueprint[];
+  private primitives: PrimitiveBlueprint[];
+
+  // Configuration
+  private config: GameConfig;
+
+  // State and registry
+  public state: RoundState;
+  private t0: number;
+  private registry = new BlueprintRegistry();
+
+  // React state update tracking
+  private _updateCount = 0;
+  public get updateCount() { return this._updateCount; }
+  private notifyStateChange() { this._updateCount++; }
+
+  // Event tracking (optional)
+  private trackingCallbacks: TrackingCallbacks | null = null;
+  
+  constructor(
+    sectors: Sector[],
+    quickstash: Blueprint[],
+    primitives: PrimitiveBlueprint[],
+    config: GameConfig
+  ) {
+    // Validate required inputs - fail fast
+    if (!sectors || sectors.length === 0) {
+      throw new Error("BaseGameController: sectors array is required and cannot be empty");
+    }
+    if (!primitives || primitives.length === 0) {
+      throw new Error("BaseGameController: primitives array is required and cannot be empty");
+    }
+    if (!config) {
+      throw new Error("BaseGameController: config is required");
+    }
+
+    // CRITICAL: All data is injected, no defaults
+    this.sectors = sectors;
+    this.quickstash = quickstash || [];
+    this.primitives = primitives;
+    this.config = config;
+    
+    // Initialize registry
+    this.registry.registerAll(primitives);
+    this.registry.registerAll(quickstash);
+    
+    // Initialize state
+    this.t0 = NOW();
+    this.state = this.initializeState();
+  }
+  
+  private initializeState(): RoundState {
+    // Create state that matches existing RoundController structure
+    const sectors: Record<string, SectorState> = {};
+    for (const s of this.sectors) {
+      sectors[s.id] = { sectorId: s.id, pieces: [] };
+    }
+
+    return {
+      cfg: {
+        n: this.config.n,
+        layout: this.config.layout,
+        target: this.config.target,
+        input: this.config.input,
+        maxQuickstashSlots: this.config.maxQuickstashSlots,
+        timeLimitMs: this.config.timeLimitMs,
+        snapRadiusPx: CONFIG.game.snapRadiusPx,
+        maxCompositeSize: this.config.maxCompositeSize ?? 0, // Default to 0 for legacy compatibility
+        sectors: this.sectors,
+        mode: this.config.mode
+      },
+      blueprintView: this.config.mode === "prep" ? "primitives" : "quickstash", // Start with primitives in prep mode
+      primitives: this.primitives,
+      quickstash: this.quickstash,
+      sectors,
+      startedAt: this.t0
+    };
+  }
+
+  // ===== Event Tracking =====
+  // Methods for InteractionTracker integration
+
+  /**
+   * Set tracking callbacks for data collection
+   * Called by InteractionTracker to register itself
+   */
+  setTrackingCallbacks(callbacks: TrackingCallbacks | null): void {
+    this.trackingCallbacks = callbacks;
+  }
+
+  // ===== RoundController Compatibility Interface =====
+  // These methods maintain compatibility with Board.tsx expectations
+
+  getState(): RoundState {
+    return this.state;
+  }
+
+  getSnapRadius(): number {
+    return CONFIG.game.snapRadiusPx;
+  }
+
+  // CRITICAL: Preserve target and input mode access
+  getTarget(): PlacementTarget {
+    return this.config.target;
+  }
+
+  getInputMode(): InputMode {
+    return this.config.input;
+  }
+
+  // ===== Blueprint and Piece Management =====
+  // Methods that Board.tsx expects
+
+  getBlueprint(id: string): Blueprint | undefined {
+    return this.registry.get(id);
+  }
+
+  getPrimitive(kind: TanKind | string): PrimitiveBlueprint | undefined {
+    return this.registry.getPrimitive(kind);
+  }
+
+  getPiecesInSector(sectorId: string): any[] {
+    const sectorState = this.state.sectors[sectorId];
+    return sectorState ? sectorState.pieces : [];
+  }
+
+  // ===== Completion Management =====
+  // Critical for Board.tsx validation
+
+  isSectorCompleted(sectorId: string): boolean {
+    return !!this.state.sectors[sectorId]?.completedAt;
+  }
+
+  markSectorCompleted(sectorId: string): void {
+    const ss = this.state.sectors[sectorId];
+    if (!ss || ss.completedAt) return;
+
+    ss.completedAt = NOW();
+
+    // Notify tracking system
+    if (this.trackingCallbacks?.onSectorCompleted) {
+      this.trackingCallbacks.onSectorCompleted(sectorId);
+    }
+
+    const allDone = Object.values(this.state.sectors).every((s: SectorState) => !!s.completedAt);
+    if (allDone && !this.state.endedAt) {
+      this.state.endedAt = NOW();
+      console.log("[BaseGameController] all sectors complete");
+    }
+  }
+
+  // ===== Piece Operations =====
+  // Methods that Board.tsx uses for drag/drop
+
+  spawnFromBlueprint(bp: Blueprint, at: { x: number; y: number }): string {
+    const id = newId();
+    const piece = { id, blueprintId: bp.id, pos: { ...at } };
+    this.getFloating().pieces.push(piece);
+    this.notifyStateChange();
+    return id;
+  }
+
+  move(id: string, to: { x: number; y: number }): void {
+    const p = this.findPiece(id);
+    if (!p) {
+      return;
+    }
+    p.pos = { ...to };
+    this.notifyStateChange();
+  }
+
+  drop(id: string, sectorId?: string): void {
+    const p = this.findPiece(id);
+    if (!p) {
+      return;
+    }
+
+    // Remove from current location
+    const where = this.findPieceLocation(id);
+    this.removeFromCurrent(id);
+    if (where?.sectorId) delete p.sectorId;
+
+    // Inner-hole or no sector → float
+    if (!sectorId) {
+      this.getFloating().pieces.push(p);
+      this.notifyStateChange();
+      return;
+    }
+
+    // Completed sector → delete (already removed above)
+    if (this.isSectorCompleted(sectorId)) {
+      this.notifyStateChange();
+      return;
+    }
+
+    // Place in sector
+    const sector = this.state.sectors[sectorId];
+    if (!sector) {
+      return;
+    }
+    
+    sector.pieces.push(p);
+    p.sectorId = sectorId;
+    this.notifyStateChange();
+  }
+
+  remove(id: string): void {
+    const loc = this.findPieceLocation(id);
+    if (!loc) return;
+    loc.array.splice(loc.index, 1);
+    this.notifyStateChange();
+  }
+
+  // ===== Helper Methods =====
+  // Internal methods that support the public API
+
+  findPiece(id: string): any {
+    for (const s of Object.values(this.state.sectors)) {
+      const sectorState = s as SectorState;
+      const p = sectorState.pieces.find((pp) => pp.id === id);
+      if (p) return p;
+    }
+    return this.getFloating().pieces.find((pp) => pp.id === id) ?? null;
+  }
+
+  private getFloating(): SectorState {
+    if (!(this as any)._floating) {
+      (this as any)._floating = { sectorId: "-floating-", pieces: [] } as SectorState;
+    }
+    return (this as any)._floating;
+  }
+
+  private findPieceLocation(id: string): 
+    | { sectorId?: string; array: SectorState["pieces"]; index: number }
+    | null {
+    for (const s of Object.values(this.state.sectors)) {
+      const sectorState = s as SectorState;
+      const idx = sectorState.pieces.findIndex((pp) => pp.id === id);
+      if (idx >= 0) return { sectorId: sectorState.sectorId, array: sectorState.pieces, index: idx };
+    }
+    const f = this.getFloating();
+    const i = f.pieces.findIndex((pp) => pp.id === id);
+    return i >= 0 ? { array: f.pieces, index: i } : null;
+  }
+
+  private removeFromCurrent(id: string): void {
+    const loc = this.findPieceLocation(id);
+    if (!loc) return;
+    loc.array.splice(loc.index, 1);
+  }
+
+  // ===== Additional Compatibility Methods =====
+
+  switchBlueprintView(): void {
+    // Disable toggle in prep mode - keep primitives always visible
+    if (this.config.mode === "prep") return;
+    
+    const to = this.state.blueprintView === "primitives" ? "quickstash" : "primitives";
+    this.state.blueprintView = to;
+  }
+
+  /**
+   * Check if submit button should be enabled in prep mode
+   * Validates macro completion based on piece count and slot requirements
+   */
+  isSubmitEnabled(): boolean {
+    if (this.config.mode !== "prep") return true; // Not applicable to construction mode
+    
+    const minPieces = this.config.minPiecesPerMacro ?? 2;
+    const maxPieces = this.config.maxCompositeSize ?? Infinity; // No upper limit if not specified
+    const requireAll = this.config.requireAllSlots ?? false;
+    
+    // Get all sectors (macro slots)
+    const allSectors = Object.values(this.state.sectors);
+    
+    // Check each sector for valid piece count
+    let validSectorCount = 0;
+    for (const sector of allSectors) {
+      const pieceCount = sector.pieces.length;
+      
+      // Valid if between min and max pieces (inclusive)
+      if (pieceCount >= minPieces && pieceCount <= maxPieces) {
+        validSectorCount++;
+      }
+      // Invalid if has pieces but not enough or too many
+      else if (pieceCount > 0) {
+        return false; // Has pieces but invalid count
+      }
+      // Empty sector (pieceCount === 0) is allowed, will be checked below
+    }
+    
+    if (requireAll) {
+      // All slots must have valid macros
+      return validSectorCount === allSectors.length;
+    } else {
+      // At least 0 valid macros (can submit nothing)
+      return true; // No invalid sectors found above, so can submit
+    }
+  }
+
+  snapshot(): any {
+    const perSector = Object.values(this.state.sectors).map((s) => {
+      const sectorState = s as SectorState;
+      const base = {
+        sectorId: sectorState.sectorId,
+        pieceCount: sectorState.pieces.length,
+      };
+      return sectorState.completedAt ? { ...base, completedAt: sectorState.completedAt } : base;
+    });
+    return {
+      perSector,
+      events: [], // TODO: Will be implemented in validation separation phase
+      timeMs: NOW() - this.t0,
+      completed: !!this.state.endedAt,
+    };
+  }
+}

package/src/core/engine/validation/border-rendering.ts

@@ -0,0 +1,318 @@
+/**
+ * Border Rendering Utilities for Edge-Aware Piece Borders
+ * 
+ * This module provides utilities for rendering piece borders with edge-aware logic.
+ * Uses the same coordinate system and approach as face-to-face.ts for consistency.
+ * Visual polish - hides borders between touching pieces
+ */
+
+import type { Vec, Piece, Blueprint } from "../../domain/types";
+import { CONFIG } from "../../config/config";
+import { boundsOfBlueprint } from "../geometry";
+
+export interface UnitSegment {
+  a: Vec;
+  b: Vec;
+}
+
+/**
+ * Generate SVG path data for individual edge strokes
+ * Each edge becomes a separate path element for selective rendering
+ */
+export function generateEdgeStrokePaths(poly: Vec[]): string[] {
+  const strokePaths: string[] = [];
+  
+  for (let i = 0; i < poly.length; i++) {
+    const current = poly[i];
+    const next = poly[(i + 1) % poly.length];
+    
+    if (current && next) {
+      strokePaths.push(`M ${current.x} ${current.y} L ${next.x} ${next.y}`);
+    }
+  }
+  
+  return strokePaths;
+}
+
+/**
+ * Convert a polygon edge into unit-length segments
+ * Uses the same logic as face-to-face.ts for consistency
+ */
+function edgeToUnitSegments(start: Vec, end: Vec, gridSize: number): UnitSegment[] {
+  const segments: UnitSegment[] = [];
+  
+  // Convert to grid coordinates
+  const startGrid = {
+    x: Math.round(start.x / gridSize),
+    y: Math.round(start.y / gridSize)
+  };
+  const endGrid = {
+    x: Math.round(end.x / gridSize),
+    y: Math.round(end.y / gridSize)
+  };
+  
+  const dx = endGrid.x - startGrid.x;
+  const dy = endGrid.y - startGrid.y;
+  
+  if (dx === 0 && dy === 0) return []; // Zero-length edge
+  
+  const steps = Math.max(Math.abs(dx), Math.abs(dy));
+  const stepX = dx / steps;
+  const stepY = dy / steps;
+  
+  for (let i = 0; i < steps; i++) {
+    const aX = Math.round(startGrid.x + i * stepX);
+    const aY = Math.round(startGrid.y + i * stepY);
+    const bX = Math.round(startGrid.x + (i + 1) * stepX);
+    const bY = Math.round(startGrid.y + (i + 1) * stepY);
+    segments.push({ 
+      a: { x: aX, y: aY }, 
+      b: { x: bX, y: bY } 
+    });
+  }
+  
+  return segments;
+}
+
+/**
+ * Get all unit segments for a piece (same logic as face-to-face.ts)
+ * Currently unused - kept for reference
+ */
+/*
+function getPieceUnitSegments(
+  piece: Piece, 
+  getBlueprint: (id: string) => Blueprint | undefined,
+  getPrimitive: (kind: string) => any,
+  gridSize: number
+): UnitSegment[] {
+  // Defensive check: if getBlueprint fails, return empty segments
+  let blueprint: Blueprint | undefined;
+  try {
+    blueprint = getBlueprint(piece.blueprintId);
+  } catch (error) {
+    console.warn('getBlueprint failed in getPieceUnitSegments:', error);
+    return [];
+  }
+
+  if (!blueprint?.shape) return [];
+  
+  // Calculate offset using same logic as piecePolysAt
+  const bb = boundsOfBlueprint(blueprint, getPrimitive);
+  const ox = piece.pos.x - bb.min.x;
+  const oy = piece.pos.y - bb.min.y;
+  
+  const allSegments: UnitSegment[] = [];
+  
+  // Translate polygons and convert edges to unit segments
+  for (const poly of blueprint.shape) {
+    const translatedPoly = poly.map((vertex: Vec) => ({
+      x: vertex.x + ox,
+      y: vertex.y + oy
+    }));
+    
+    for (let i = 0; i < translatedPoly.length; i++) {
+      const current = translatedPoly[i];
+      const next = translatedPoly[(i + 1) % translatedPoly.length];
+      
+      if (!current || !next) continue;
+      
+      allSegments.push(...edgeToUnitSegments(current, next, gridSize));
+    }
+  }
+  
+  return allSegments;
+}
+*/
+
+/**
+ * Check which edges should be hidden for a specific polygon within a piece
+ * Handles both internal composite edges and external touching between pieces
+ */
+export function getHiddenEdgesForPolygon(
+  piece: Piece,
+  polyIndex: number,
+  allPiecesInSector: Piece[],
+  getBlueprint: (id: string) => Blueprint | undefined,
+  getPrimitive: (kind: string) => any
+): boolean[] {
+  // Defensive check: if getBlueprint fails, return no hidden edges
+  let blueprint: Blueprint | undefined;
+  try {
+    blueprint = getBlueprint(piece.blueprintId);
+  } catch (error) {
+    console.warn('getBlueprint failed in getHiddenEdgesForPolygon:', error);
+    return [];
+  }
+
+  if (!blueprint?.shape) {
+    return [];
+  }
+
+  const poly = blueprint.shape[polyIndex];
+  if (!poly) return [];
+
+  const gridSize = CONFIG.layout.grid.stepPx;
+  const bb = boundsOfBlueprint(blueprint, getPrimitive);
+  const ox = piece.pos.x - bb.min.x;
+  const oy = piece.pos.y - bb.min.y;
+  
+  const translatedPoly = poly.map((vertex: Vec) => ({
+    x: vertex.x + ox,
+    y: vertex.y + oy
+  }));
+
+  const hiddenEdges: boolean[] = [];
+
+  // For each edge in this polygon
+  for (let i = 0; i < translatedPoly.length; i++) {
+    const current = translatedPoly[i];
+    const next = translatedPoly[(i + 1) % translatedPoly.length];
+    
+    if (!current || !next) {
+      hiddenEdges.push(false);
+      continue;
+    }
+
+    // Get segments for this edge
+    const edgeSegments = edgeToUnitSegments(current, next, gridSize);
+    
+    // Check if any of these segments are touching other pieces
+    let isTouching = false;
+    
+    // 1. Check internal composite edges (if this is a composite)
+    if (piece.blueprintId.startsWith('comp:')) {
+      // Check against other polygons in the same composite
+      for (let otherPolyIndex = 0; otherPolyIndex < blueprint.shape.length; otherPolyIndex++) {
+        if (otherPolyIndex === polyIndex) continue; // Skip self
+        
+        const otherPoly = blueprint.shape[otherPolyIndex];
+        if (!otherPoly) continue;
+        
+        const otherTranslatedPoly = otherPoly.map((vertex: Vec) => ({
+          x: vertex.x + ox,
+          y: vertex.y + oy
+        }));
+
+        // Check if this edge touches any edge of the other polygon
+        for (let j = 0; j < otherTranslatedPoly.length; j++) {
+          const otherCurrent = otherTranslatedPoly[j];
+          const otherNext = otherTranslatedPoly[(j + 1) % otherTranslatedPoly.length];
+          
+          if (!otherCurrent || !otherNext) continue;
+
+          const otherEdgeSegments = edgeToUnitSegments(otherCurrent, otherNext, gridSize);
+          
+          // Check if any segments are shared
+          for (const edgeSeg of edgeSegments) {
+            const isShared = otherEdgeSegments.some(otherSeg => 
+              // Check if segments share the same endpoints (identical or reversed)
+              (edgeSeg.a.x === otherSeg.a.x && edgeSeg.a.y === otherSeg.a.y &&
+               edgeSeg.b.x === otherSeg.b.x && edgeSeg.b.y === otherSeg.b.y) ||
+              (edgeSeg.a.x === otherSeg.b.x && edgeSeg.a.y === otherSeg.b.y &&
+               edgeSeg.b.x === otherSeg.a.x && edgeSeg.b.y === otherSeg.a.y)
+            );
+            
+            if (isShared) {
+              isTouching = true;
+              break;
+            }
+          }
+          
+          if (isTouching) break;
+        }
+        
+        if (isTouching) break;
+      }
+    }
+    
+    // 2. Check external touching between different pieces (if not already touching internally)
+    // Only check external touching when hideTouchingBorders is true
+    if (!isTouching && CONFIG.game.hideTouchingBorders) {
+      for (const otherPiece of allPiecesInSector) {
+        if (otherPiece.id === piece.id) continue; // Skip self
+        
+        const otherBlueprint = getBlueprint(otherPiece.blueprintId);
+        if (!otherBlueprint?.shape) continue;
+
+        const otherBb = boundsOfBlueprint(otherBlueprint, getPrimitive);
+        const otherOx = otherPiece.pos.x - otherBb.min.x;
+        const otherOy = otherPiece.pos.y - otherBb.min.y;
+
+        // Check if this edge touches any edge of the other piece
+        for (const otherPoly of otherBlueprint.shape) {
+          const otherTranslatedPoly = otherPoly.map((vertex: Vec) => ({
+            x: vertex.x + otherOx,
+            y: vertex.y + otherOy
+          }));
+
+          for (let j = 0; j < otherTranslatedPoly.length; j++) {
+            const otherCurrent = otherTranslatedPoly[j];
+            const otherNext = otherTranslatedPoly[(j + 1) % otherTranslatedPoly.length];
+            
+            if (!otherCurrent || !otherNext) continue;
+
+            const otherEdgeSegments = edgeToUnitSegments(otherCurrent, otherNext, gridSize);
+            
+            // Check if any segments are shared
+            for (const edgeSeg of edgeSegments) {
+              const isShared = otherEdgeSegments.some(otherSeg => 
+                // Check if segments share the same endpoints (identical or reversed)
+                (edgeSeg.a.x === otherSeg.a.x && edgeSeg.a.y === otherSeg.a.y &&
+                 edgeSeg.b.x === otherSeg.b.x && edgeSeg.b.y === otherSeg.b.y) ||
+                (edgeSeg.a.x === otherSeg.b.x && edgeSeg.a.y === otherSeg.b.y &&
+                 edgeSeg.b.x === otherSeg.a.x && edgeSeg.b.y === otherSeg.a.y)
+              );
+              
+              if (isShared) {
+                isTouching = true;
+                break;
+              }
+            }
+            
+            if (isTouching) break;
+          }
+          
+          if (isTouching) break;
+        }
+        
+        if (isTouching) break;
+      }
+    }
+
+    hiddenEdges.push(isTouching);
+  }
+
+  return hiddenEdges;
+}
+
+/**
+ * Check if borders should be shown at all
+ * If false, neither primitives nor composites have borders
+ */
+export function shouldShowBorders(): boolean {
+  return CONFIG.game.showBorders;
+}
+
+/**
+ * Check if touching borders should be hidden
+ * Only relevant when showBorders is true
+ * - true: All pieces use selective border rendering
+ * - false: Only composites use selective border rendering
+ */
+export function shouldHideTouchingBorders(): boolean {
+  return CONFIG.game.hideTouchingBorders;
+}
+
+/**
+ * Check if a piece should have selective border rendering
+ * This determines whether to use edge-aware borders or full borders
+ */
+export function shouldUseSelectiveBorders(blueprintId: string): boolean {
+  // Use selective borders if:
+  // 1. Borders are enabled globally AND
+  // 2. Either hideTouchingBorders is true (ALL pieces) OR this is a composite piece
+  return CONFIG.game.showBorders && (
+         CONFIG.game.hideTouchingBorders ||     // If true, ALL pieces use selective borders
+         blueprintId.startsWith('comp:')        // If false, only composites use selective borders
+         );
+}