jspsych-tangram 0.0.1

package/src/core/components/board/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Board Component Hooks - Individual exports for advanced plugin development
+ * 
+ * This module exports the individual React hooks that power the GameBoard component.
+ * These hooks can be used directly by plugin developers who need more granular
+ * control over board behavior than what GameBoard provides.
+ * 
+ * ## Hook Architecture
+ * 
+ * The board functionality is decomposed into focused hooks that each handle
+ * a specific aspect of the game mechanics:
+ * 
+ * - **usePieceState**: Manages piece data and polygon computation
+ * - **useAnchorGrid**: Computes snap points and validation grids  
+ * - **useDragController**: Handles drag interactions and collision detection
+ * - **useClickController**: Manages click-based interactions
+ * 
+ * ## Usage Patterns
+ * 
+ * ### Option 1: Use GameBoard (Recommended)
+ * Most plugins should use the GameBoard component which internally uses all hooks:
+ * ```typescript
+ * import { GameBoard } from "@/core/components";
+ * <GameBoard sectors={sectors} quickstash={macros} ... />
+ * ```
+ * 
+ * ### Option 2: Use Individual Hooks (Advanced)
+ * For custom board implementations, use hooks directly:
+ * ```typescript
+ * import { usePieceState, useDragController } from "@/core/components/board";
+ * 
+ * function CustomBoard({ controller, layout }) {
+ *   const pieceState = usePieceState(controller);
+ *   const dragController = useDragController(
+ *     controller, layout, pieceState.pieces, // additional params
+ *   );
+ *   
+ *   return <div>Custom UI using hook state</div>;
+ * }
+ * ```
+ * 
+ * ## Hook Dependencies
+ * 
+ * The hooks have dependencies on each other:
+ * - useDragController depends on usePieceState output
+ * - useClickController integrates with useDragController
+ * - useAnchorGrid is independent but used by drag/click controllers
+ * 
+ * @see {@link GameBoard} For the complete integrated component
+ * @see {@link ../README.md} For comprehensive usage documentation
+ */
+
+// Piece state management
+export { usePieceState } from './usePieceState';
+export type { PieceData, PieceStateHook } from './usePieceState';
+
+// Anchor grid computation
+export { useAnchorGrid } from './useAnchorGrid';
+export type { AnchorDots } from './BoardView';
+
+// Drag interaction handling
+export { useDragController } from './useDragController';
+export type { DragControllerHook } from './useDragController';
+
+// Click interaction handling
+export { useClickController } from './useClickController';
+export type { ClickControllerHook } from './useClickController';
+
+// Utility functions
+export { blueprintLocalFromWorld, scalePolys } from './utils';

package/src/core/components/board/useAnchorGrid.ts

@@ -0,0 +1,110 @@
+import React from "react";
+import { BaseGameController } from "@/core/engine/state/BaseGameController";
+import type { CircleLayout } from "@/core/domain/layout";
+import { rectForBand } from "@/core/domain/layout";
+import { placeSilhouetteGridAlignedAsPolys } from "@/core/engine/geometry";
+import {
+  workspaceNodes,
+  silhouetteNodes,
+  silhouetteBandNodes,
+  innerRingNodes
+} from "@/core/engine/collision/grid-snapping";
+
+/**
+ * Anchor dots data for a single sector
+ * 
+ * Represents the valid and invalid snap points for piece placement within
+ * a sector. Valid dots allow piece placement, invalid dots show grid structure
+ * but don't allow snapping.
+ */
+export interface AnchorDots {
+  /** Sector ID these anchor dots belong to */
+  sectorId: string;
+  
+  /** Array of valid snap points where pieces can be placed */
+  valid: { x: number; y: number }[];
+  
+  /** Array of invalid snap points (visual grid, no placement allowed) */
+  invalid: { x: number; y: number }[];
+}
+
+/**
+ * Return interface for useAnchorGrid hook
+ * 
+ * Provides computed anchor grid data for all active sectors in the layout.
+ * Used by rendering components to draw snap points and by interaction hooks
+ * for piece placement validation.
+ */
+export interface AnchorGridHook {
+  /** Array of anchor dot data for all sectors (excludes completed sectors) */
+  anchorDots: AnchorDots[];
+}
+
+/**
+ * Hook for computing anchor grid data for all sectors
+ * 
+ * This hook computes the snap points (anchor dots) for piece placement validation
+ * across all active sectors. It handles both workspace and silhouette target modes,
+ * computing appropriate valid and invalid snap points for each.
+ * 
+ * ## Key Features
+ * - **Workspace mode**: All grid nodes within sector bounds are valid
+ * - **Silhouette mode**: Only nodes within silhouette mask are valid
+ * - **Completion hiding**: Completed sectors don't show anchor dots
+ * - **Scale-aware**: Handles silhouette scaling for proper grid alignment
+ * 
+ * ## Target Mode Behavior
+ * - **Workspace**: `valid` contains all workspace nodes, `invalid` is empty
+ * - **Silhouette**: `valid` contains nodes inside silhouette, `invalid` contains band nodes outside
+ * 
+ * @param controller - BaseGameController instance for accessing game state
+ * @param layout - Computed CircleLayout containing sector geometry
+ * @param scaleS - Scaling factor for silhouette placement (from solveLogicalBox)
+ * @returns Hook interface with anchor dots for all active sectors
+ * 
+ * @example
+ * ```typescript
+ * const { anchorDots } = useAnchorGrid(controller, layout, scaleS);
+ * const sectorAnchors = anchorDots.find(a => a.sectorId === "sector_1");
+ * const snapPoints = sectorAnchors?.valid ?? [];
+ * ```
+ */
+export function useAnchorGrid(
+  controller: BaseGameController,
+  layout: CircleLayout,
+  scaleS: number
+): AnchorGridHook {
+  const cfg = controller.state.cfg;
+
+  const anchorDots: AnchorDots[] = React.useMemo(() => {
+    const out: AnchorDots[] = [];
+
+    // Add inner ring anchors (always valid, shown throughout)
+    out.push({ sectorId: "inner-ring", valid: innerRingNodes(layout), invalid: [] });
+
+    for (const s of layout.sectors) {
+      // Show anchors for ALL sectors, including completed ones
+      if (cfg.target === "workspace") {
+        out.push({ sectorId: s.id, valid: workspaceNodes(layout, s), invalid: [] });
+      } else {
+        const mask = controller.state.cfg.sectors.find(ss => ss.id === s.id)?.silhouette.mask ?? [];
+        if (!mask || mask.length === 0) continue;
+        const rect = rectForBand(layout, s, "silhouette", 1.0); // center only; size was handled in global scale
+        const placedPolys = placeSilhouetteGridAlignedAsPolys(mask, scaleS, { cx: rect.cx, cy: rect.cy });
+        const bandAll = silhouetteBandNodes(layout, s);
+        const valid = silhouetteNodes(layout, s, placedPolys);
+        // invalid = bandAll \ valid (by coordinate)
+        const key = (p: { x: number; y: number }) => `${p.x},${p.y}`;
+        const validSet = new Set(valid.map(key));
+        const invalid = bandAll.filter(p => !validSet.has(key(p)));
+        out.push({ sectorId: s.id, valid, invalid });
+      }
+    }
+    return out;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cfg.target, controller.state.sectors, layout, scaleS]);
+
+  return {
+    anchorDots
+  };
+}

package/src/core/components/board/useClickController.ts

@@ -0,0 +1,436 @@
+import React from "react";
+import { BaseGameController } from "@/core/engine/state/BaseGameController";
+import type { CircleLayout } from "@/core/domain/layout";
+import { sectorAtPoint } from "@/core/domain/layout";
+import { boundsOfBlueprint, computeSupportOffsets, clampTopLeftBySupport, piecePolysAt } from "@/core/engine/geometry";
+import type { PieceData } from "./usePieceState";
+
+// Click controller state is managed internally with React hooks
+
+/**
+ * Return interface for useClickController hook
+ * 
+ * Provides click-based interaction functionality that works alongside
+ * useDragController to support click-and-place interaction patterns.
+ */
+export interface ClickControllerHook {
+  // State
+  /** ID of pending blueprint for placement (from blueprint ring clicks) */
+  pendingBpId: string | null;
+  
+  /** ID of currently selected piece (for click-to-move functionality) */
+  selectedPieceId: string | null;
+  
+  // Handlers  
+  /** 
+   * Handler for root SVG clicks (placement, movement, deletion)
+   * @param e - Pointer event from SVG root element
+   */
+  onRootPointerDown: (e: React.PointerEvent<SVGSVGElement>) => void;
+  
+  // Helper methods for drag controller integration
+  /** Clear all selection state */
+  clearSelection: () => void;
+  
+  /** 
+   * Set pending blueprint ID for placement
+   * @param id - Blueprint ID or null to clear
+   */
+  setPendingBp: (id: string | null) => void;
+  
+  /** 
+   * Set selected piece ID for movement
+   * @param id - Piece ID or null to clear
+   */
+  setSelectedPiece: (id: string | null) => void;
+}
+
+/**
+ * Hook for managing click-based interactions in click input mode
+ * 
+ * This hook works in conjunction with useDragController to provide click-and-place
+ * interaction patterns. It manages the selection state for both blueprint icons and
+ * live pieces, handling placement, movement, and deletion through click interactions.
+ * 
+ * ## Click Interaction Patterns
+ * - **Blueprint click**: Selects blueprint for placement (pendingBpId)
+ * - **Piece click**: Starts "carry" state via drag controller integration
+ * - **Empty click**: Places pending blueprint or moves selected piece
+ * - **Center badge click**: Deletes carried/selected piece
+ * - **Completed sector click**: Deletes pieces (invalid placement)
+ * 
+ * ## State Management
+ * - **pendingBpId**: Blueprint selected from ring, awaiting placement
+ * - **selectedPieceId**: Live piece selected for movement
+ * - **Integration with drag controller**: Uses draggingId for "carry" state
+ * 
+ * ## Dependencies
+ * This hook requires tight integration with useDragController as it uses the
+ * drag controller's carry mechanism for piece movement in click mode.
+ * 
+ * @param controller - BaseGameController for state management
+ * @param layout - Computed CircleLayout for sector geometry
+ * @param pieces - Current piece data from usePieceState
+ * @param clickMode - Whether click input mode is active
+ * @param draggingId - Current dragging piece ID from drag controller
+ * @param setDraggingId - Setter for dragging ID (drag controller integration)
+ * @param dragRef - Drag state ref from drag controller
+ * @param isInsideBadge - Function to check if point is inside center badge
+ * @param isSectorLocked - Function to check if sector is completed
+ * @param maybeCompleteSector - Callback to check sector completion
+ * @param svgPoint - Function to convert screen to SVG coordinates
+ * @param force - Force React re-render function
+ * @returns Hook interface with click state and handlers
+ * 
+ * @example
+ * ```typescript
+ * const clickController = useClickController(
+ *   controller, layout, pieces, clickMode, 
+ *   draggingId, setDraggingId, dragRef,
+ *   isInsideBadge, isSectorLocked, maybeCompleteSector, svgPoint, force
+ * );
+ * 
+ * // Usage in JSX:
+ * <svg onPointerDown={clickController.onRootPointerDown}>
+ *   Game content
+ * </svg>
+ * ```
+ */
+export function useClickController(
+  controller: BaseGameController,
+  layout: CircleLayout,
+  pieces: PieceData[],
+  clickMode: boolean,
+  draggingId: string | null,
+  setDraggingId: (id: string | null) => void,
+  dragRef: React.RefObject<any>,
+  isInsideBadge: (x: number, y: number) => boolean,
+  isSectorLocked: (id: string) => boolean,
+  maybeCompleteSector: (secId: string) => boolean,
+  svgPoint: (clientX: number, clientY: number) => { x: number; y: number },
+  force: () => void,
+  // Interaction tracking
+  tracker?: {
+    recordPlacedown: (
+      outcome: 'placed' | 'deleted',
+      sectorId?: string,
+      position?: { x: number; y: number },
+      vertices?: number[][][],
+      anchorId?: string,
+      wasValid?: boolean,
+      wasOverlapping?: boolean,
+      completedSector?: boolean
+    ) => void;
+    recordClickEvent?: (
+      location: { x: number; y: number },
+      clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt',
+      metadata?: any
+    ) => void;
+  } | null
+): ClickControllerHook {
+  const cfg = controller.state.cfg;
+  const sectorIdAt = (x: number, y: number) => sectorAtPoint(x, y, layout, cfg.target);
+
+  // Helper: Compute piece vertices in world space
+  const getPieceVertices = (pieceId: string): number[][][] => {
+    const piece = controller.findPiece(pieceId);
+    if (!piece) return [];
+    const bp = controller.getBlueprint(piece.blueprintId);
+    if (!bp) return [];
+    const bb = boundsOfBlueprint(bp, controller.getPrimitive);
+    const polys = piecePolysAt(bp, bb, piece.pos);
+    // Convert from {x,y}[][] to number[][][]
+    return polys.map(ring => ring.map(pt => [pt.x, pt.y]));
+  };
+
+  const getCurrentAnchorInfo = () => {
+    const d = dragRef.current;
+    return {
+      anchorId: d?.snapAnchorId ?? d?.pointerAnchorId ?? undefined,
+      wasValid: d?.validSnap !== false,
+      wasOverlapping: d?.overlaps ?? false,
+      anchorX: d?.pointerAnchor?.x,
+      anchorY: d?.pointerAnchor?.y,
+      sectorId: d?.snapAnchorSectorId ?? d?.pointerAnchorSectorId
+    };
+  };
+
+  const emitClickEvent = (
+    location: { x: number; y: number },
+    clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt',
+    metadata?: any
+  ) => {
+    if (!tracker?.recordClickEvent) return;
+    tracker.recordClickEvent(location, clickType, metadata);
+  };
+
+  // Click mode state
+  const [pendingBpId, setPendingBpId] = React.useState<string | null>(null);       // selected icon
+  const [selectedPieceId, setSelectedPieceId] = React.useState<string | null>(null); // selected live piece
+
+  const onRootPointerDown = (e: React.PointerEvent<SVGSVGElement>) => {
+    const { x: px, y: py } = svgPoint(e.clientX, e.clientY);
+
+    // --- CLICK MODE: second-click behaviors (move/delete/place)
+    if (clickMode) {
+      const secId = sectorIdAt(px, py);
+
+      // If we're currently carrying a piece (draggingId set via click), this click commits (or deletes)
+      if (draggingId && dragRef.current) {
+        const d = dragRef.current;
+        const centerX2 = d.tlx + d.aabb.width / 2;
+        const centerY2 = d.tly + d.aabb.height / 2;
+
+        // delete/cancel if clicked center (carry piece is already under pointer)
+        if (isInsideBadge(px, py)) {
+          const piece = controller.findPiece(d.id);
+          const removedFromSector = piece?.sectorId;
+          const anchorInfo = getCurrentAnchorInfo();
+          controller.remove(d.id);
+          // Re-check completion for the sector the piece was removed from
+          if (removedFromSector) maybeCompleteSector(removedFromSector);
+
+          // Record placedown as "deleted"
+          if (tracker) {
+            tracker.recordPlacedown(
+              'deleted',
+              removedFromSector,
+              undefined,
+              undefined,
+              anchorInfo.anchorId,
+              anchorInfo.wasValid,
+              anchorInfo.wasOverlapping
+            );
+          }
+
+          // TODO: Remove dragRef manipulation once drag controller provides proper interface
+          // dragRef.current = null; // Cannot assign to readonly property - drag controller should handle this
+          setDraggingId(null);
+          setSelectedPieceId(null);
+          setPendingBpId(null);
+          force();
+          return; // don't toggle view
+        }
+
+        // Check if piece is in inner ring - if so, delete it
+        const rFromCenter = Math.hypot(centerX2 - layout.cx, centerY2 - layout.cy);
+        if (rFromCenter < layout.innerR) {
+          const piece = controller.findPiece(d.id);
+          const removedFromSector = piece?.sectorId;
+          const anchorInfo = getCurrentAnchorInfo();
+          controller.remove(d.id);
+          if (removedFromSector) maybeCompleteSector(removedFromSector);
+
+          // Record placedown as "deleted"
+          if (tracker) {
+            tracker.recordPlacedown(
+              'deleted',
+              removedFromSector,
+              undefined,
+              undefined,
+              anchorInfo.anchorId,
+              anchorInfo.wasValid,
+              anchorInfo.wasOverlapping
+            );
+          }
+
+          setDraggingId(null);
+          setSelectedPieceId(null);
+          setPendingBpId(null);
+          force();
+          return;
+        }
+
+        const secId2 = sectorIdAt(centerX2, centerY2);
+
+        if (!secId2) {
+          emitClickEvent(
+            { x: centerX2, y: centerY2 },
+            'invalid_placement',
+            { invalidPlacement: { reason: 'outside_bounds' } }
+          );
+          force();
+          return;
+        }
+
+        if (isSectorLocked(secId2)) {
+          emitClickEvent(
+            { x: centerX2, y: centerY2 },
+            'sector_complete_attempt',
+            { invalidPlacement: { reason: 'sector_complete', attemptedSectorId: secId2 } }
+          );
+          force();
+          return;
+        }
+
+        // If the candidate is invalid for any reason (overlap / outside / bad node), keep carrying
+        if (d.validSnap === false) {
+          const anchorInfo = getCurrentAnchorInfo();
+          const invalidReason = anchorInfo.wasOverlapping ? 'overlapping' : 'no_valid_anchor';
+          emitClickEvent(
+            { x: centerX2, y: centerY2 },
+            'invalid_placement',
+            { invalidPlacement: { reason: invalidReason, attemptedSectorId: secId2 } }
+          );
+          force();
+          return;
+        }
+        
+        controller.move(d.id, { x: d.tlx, y: d.tly }); // TL already snapped (valid)
+        controller.drop(d.id, secId2);
+
+        const anchorInfo = getCurrentAnchorInfo();
+        const justCompleted = maybeCompleteSector(secId2);
+
+        // Record placedown as "placed" successfully
+        if (tracker) {
+          tracker.recordPlacedown(
+            'placed',
+            secId2,
+            { x: d.tlx, y: d.tly },
+            getPieceVertices(d.id),
+            anchorInfo.anchorId,
+            anchorInfo.wasValid,
+            anchorInfo.wasOverlapping,
+            justCompleted
+          );
+        }
+        // TODO: Remove dragRef manipulation once drag controller provides proper interface
+        // dragRef.current = null; // Cannot assign to readonly property - drag controller should handle this
+        setDraggingId(null);
+        setSelectedPieceId(null);
+        setPendingBpId(null);
+        // auto-revert AFTER placement completes (click mode)
+        if (controller.state.blueprintView === "primitives") {
+          controller.switchBlueprintView();
+        }
+        force();
+        return;
+      }
+
+      // Selected piece → delete / move / deselect
+      if (selectedPieceId) {
+        if (isInsideBadge(px, py)) {
+          const piece = controller.findPiece(selectedPieceId);
+          const removedFromSector = piece?.sectorId;
+          controller.remove(selectedPieceId);
+          // Re-check completion for the sector the piece was removed from
+          if (removedFromSector) maybeCompleteSector(removedFromSector);
+
+          // Record placedown as "deleted"
+          if (tracker) {
+            tracker.recordPlacedown('deleted');
+          }
+
+          setSelectedPieceId(null);
+          force();
+          return; // DO NOT toggle view after delete
+        }
+        // Completed sector: no-op (do nothing, same as incomplete sector in silhouette mode)
+        if (secId && isSectorLocked(secId)) {
+          setSelectedPieceId(null);
+          force();
+          return;
+        }
+        if (secId) {
+          const p = pieces.find(pp => pp.id === selectedPieceId);
+          setSelectedPieceId(null);
+          if (p) {
+            const bp = controller.getBlueprint(p.blueprintId)!;
+            const bb = boundsOfBlueprint(bp, controller.getPrimitive);
+            const support = computeSupportOffsets(bp, bb);
+            const tl0 = { x: px - bb.width / 2, y: py - bb.height / 2 };
+            const clamped = clampTopLeftBySupport(
+              tl0.x, tl0.y,
+              { aabb: { width: bb.width, height: bb.height }, support },
+              layout,
+              controller.state.cfg.target,
+              false
+            );
+
+            const maxPieces = controller.state.cfg.maxCompositeSize ?? 0;
+            if (controller.state.cfg.mode === "prep" && maxPieces > 0) {
+              const sectorPieces = controller.getPiecesInSector(secId);
+              const effectiveCount = sectorPieces.length - (p.sectorId === secId ? 1 : 0);
+              if (effectiveCount + 1 > maxPieces) {
+                force();
+                return;
+              }
+            }
+
+            controller.move(p.id, { x: clamped.x, y: clamped.y });
+            controller.drop(p.id, secId);
+            maybeCompleteSector(secId);
+            force();
+          }
+          return;
+        }
+        // click outside → deselect only
+        setSelectedPieceId(null);
+        force();
+        return;
+      }
+
+      // Pending icon → place
+      if (pendingBpId) {
+        const secId2 = sectorIdAt(px, py);
+
+        if (isInsideBadge(px, py) || !secId2 || isSectorLocked(secId2)) {
+          setPendingBpId(null); // cancel
+          force();
+          return;
+        }
+
+        const bp = controller.getBlueprint(pendingBpId)!;
+        const bb = boundsOfBlueprint(bp, controller.getPrimitive);
+        const support = computeSupportOffsets(bp, bb);
+        const tl0 = { x: px - bb.width / 2, y: py - bb.height / 2 };
+        const clamped = clampTopLeftBySupport(
+          tl0.x, tl0.y,
+          { aabb: { width: bb.width, height: bb.height }, support },
+          layout,
+          controller.state.cfg.target,
+          false
+        );
+        const id = controller.spawnFromBlueprint(bp, clamped);
+
+        const maxPieces = controller.state.cfg.maxCompositeSize ?? 0;
+        if (controller.state.cfg.mode === "prep" && maxPieces > 0) {
+          const sectorPieces = controller.getPiecesInSector(secId2);
+          if (sectorPieces.length + 1 > maxPieces) {
+            controller.remove(id);
+            setPendingBpId(null);
+            force();
+            return;
+          }
+        }
+
+        controller.drop(id, secId2);
+        setPendingBpId(null);
+        maybeCompleteSector(secId2);
+
+        // auto-revert AFTER placement completes (click mode)
+        if (controller.state.blueprintView === "primitives") controller.switchBlueprintView();
+        force();
+        return;
+      }
+    }
+  };
+
+  return {
+    // State
+    pendingBpId,
+    selectedPieceId,
+    
+    // Handlers
+    onRootPointerDown,
+    
+    // Helper methods for integration
+    clearSelection: () => {
+      setSelectedPieceId(null);
+      setPendingBpId(null);
+    },
+    setPendingBp: setPendingBpId,
+    setSelectedPiece: setSelectedPieceId,
+  };
+}