@astronox/core 0.1.0

package/src/patterns/MagneticFieldPuzzle/magneticFieldPuzzleController.ts

@@ -0,0 +1,802 @@
+import {
+  setPuzzleGridCellState,
+  setPuzzleGridState,
+} from '../PuzzleGrid/state';
+import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import type {
+  MagneticFieldDirection,
+  MagneticFieldMovement,
+  MagneticFieldPolarity,
+  MagneticFieldPupilPosition,
+  MagneticFieldPuzzleChangeDetail,
+  MagneticFieldPuzzleModel,
+  MagneticFieldPuzzleState,
+  MagneticFieldPuzzleStatus,
+} from './contracts';
+import {
+  createMagneticFieldInitialState,
+  getMagneticFieldMoves,
+  isMagneticFieldPuzzleComplete,
+  simulateMagneticFieldMove,
+} from './simulation';
+
+type MagneticFieldDrag = {
+  pointerId: number;
+  pieceId: string;
+  startX: number;
+  startY: number;
+  currentX: number;
+  currentY: number;
+  frameId: number | null;
+  element: HTMLButtonElement;
+  originCellBounds: DOMRect;
+  originCenterX: number;
+  originCenterY: number;
+  destinations: readonly HTMLButtonElement[] | null;
+  moved: boolean;
+};
+
+type MagneticFieldInstance = {
+  activeIndex: number;
+  selectedPieceId: string | null;
+  drag: MagneticFieldDrag | null;
+  ignoreNextClick: boolean;
+};
+
+const dragThreshold = 12;
+const pathChevronsPerCell = 3;
+const pathDurationPerCellMs = 2100;
+const instances = new WeakMap<HTMLElement, MagneticFieldInstance>();
+
+export function initMagneticFieldPuzzle(root: HTMLElement): void {
+  if (instances.has(root)) return;
+  instances.set(root, {
+    activeIndex: 0,
+    selectedPieceId: null,
+    drag: null,
+    ignoreNextClick: false,
+  });
+  initPuzzleSelectionDismissal(root, {
+    dismiss: () => selectPiece(root, null),
+    isSelectionTarget: (target) => {
+      const panel = getActivePanel(root);
+      if (!panel || panel.dataset.puzzleStatus === 'valid') return false;
+
+      const piece = target.closest<HTMLElement>('[data-field-piece]');
+      if (piece && panel.contains(piece)) return true;
+
+      const destination = target.closest<HTMLButtonElement>(
+        '[data-field-destination]',
+      );
+      return Boolean(
+        destination && panel.contains(destination) && !destination.disabled,
+      );
+    },
+  });
+
+  root.addEventListener('click', (event) => {
+    const target = event.target;
+    const instance = instances.get(root);
+    if (!(target instanceof Element) || !instance) return;
+
+    const piece = target.closest<HTMLButtonElement>('[data-field-piece]');
+    if (piece) {
+      if (instance.ignoreNextClick) {
+        instance.ignoreNextClick = false;
+        return;
+      }
+      togglePieceSelection(root, piece.dataset.fieldPiece ?? null);
+      return;
+    }
+
+    const destination = target.closest<HTMLButtonElement>(
+      '[data-field-destination]',
+    );
+    if (destination && !destination.disabled) {
+      const pieceId = destination.dataset.destinationPiece;
+      const direction = destination.dataset.destinationDirection as
+        MagneticFieldDirection | undefined;
+      if (pieceId && direction) movePiece(root, pieceId, direction);
+      return;
+    }
+
+    if (target.closest('[data-field-board]')) selectPiece(root, null);
+  });
+
+  root.addEventListener('pointerdown', (event) => {
+    if (!event.isPrimary || event.button !== 0) return;
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const piece = target.closest<HTMLButtonElement>('[data-field-piece]');
+    const instance = instances.get(root);
+    const pieceId = piece?.dataset.fieldPiece;
+    if (!piece || !pieceId || !instance) return;
+    const panel = getActivePanel(root);
+    const originCell = panel
+      ? findCell(panel, {
+          row: Number(piece.dataset.pieceRow),
+          column: Number(piece.dataset.pieceColumn),
+        })
+      : null;
+    if (!originCell) return;
+    const pieceBounds = piece.getBoundingClientRect();
+
+    piece.setPointerCapture(event.pointerId);
+    instance.drag = {
+      pointerId: event.pointerId,
+      pieceId,
+      startX: event.clientX,
+      startY: event.clientY,
+      currentX: event.clientX,
+      currentY: event.clientY,
+      frameId: null,
+      element: piece,
+      originCellBounds: originCell.getBoundingClientRect(),
+      originCenterX: (pieceBounds.left + pieceBounds.right) / 2,
+      originCenterY: (pieceBounds.top + pieceBounds.bottom) / 2,
+      destinations: null,
+      moved: false,
+    };
+  });
+
+  root.addEventListener('pointermove', (event) => {
+    const drag = instances.get(root)?.drag;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    const deltaX = event.clientX - drag.startX;
+    const deltaY = event.clientY - drag.startY;
+    if (!drag.moved) {
+      drag.moved = Math.hypot(deltaX, deltaY) >= dragThreshold;
+      if (!drag.moved) return;
+      drag.element.setAttribute('data-piece-dragging', '');
+      selectPiece(root, drag.pieceId);
+    }
+
+    event.preventDefault();
+    drag.destinations ??= getDropDestinations(root);
+    drag.currentX = event.clientX;
+    drag.currentY = event.clientY;
+    scheduleDragFrame(root, drag);
+  });
+
+  root.addEventListener('pointerup', (event) => {
+    finishDrag(root, event, true);
+  });
+  root.addEventListener('pointercancel', (event) => {
+    finishDrag(root, event, false);
+  });
+
+  root.addEventListener('keydown', (event) => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const direction = arrowDirections[event.key.toLowerCase()];
+    if (!direction) {
+      if (event.key === 'Escape') selectPiece(root, null);
+      return;
+    }
+
+    const piece = (event.target as Element | null)?.closest<HTMLElement>(
+      '[data-field-piece]',
+    );
+    const pieceId =
+      piece?.dataset.fieldPiece ??
+      instances.get(root)?.selectedPieceId ??
+      undefined;
+    if (!pieceId) return;
+    event.preventDefault();
+    movePiece(root, pieceId, direction);
+  });
+}
+
+export function selectMagneticFieldPuzzle(
+  root: HTMLElement,
+  index: number,
+): void {
+  initMagneticFieldPuzzle(root);
+  const panels = getPanels(root);
+  const selectedIndex = Math.max(0, Math.min(index, panels.length - 1));
+  const instance = instances.get(root);
+  if (instance) instance.activeIndex = selectedIndex;
+
+  panels.forEach((panel, panelIndex) => {
+    panel.hidden = panelIndex !== selectedIndex;
+  });
+  initializeActivePuzzle(root);
+}
+
+export function setMagneticFieldPuzzleStatus(
+  root: HTMLElement,
+  puzzleId: string,
+  status: MagneticFieldPuzzleStatus,
+): void {
+  const panel = getPanels(root).find(
+    (candidate) => candidate.dataset.puzzleId === puzzleId,
+  );
+  if (!panel) return;
+
+  const previous = panel.dataset.puzzleStatus;
+  if (status === 'valid') {
+    const instance = instances.get(root);
+    if (instance && panel === getActivePanel(root)) {
+      instance.selectedPieceId = null;
+    }
+    for (const piece of panel.querySelectorAll<HTMLElement>(
+      '[data-field-piece]',
+    )) {
+      piece.removeAttribute('data-piece-selected');
+      piece.setAttribute('aria-pressed', 'false');
+    }
+    hideMovePreviews(panel);
+  }
+  panel.dataset.puzzleStatus = status;
+  const grid = panel.querySelector<HTMLElement>('[data-puzzle-grid]');
+  if (grid) setPuzzleGridState(grid, status === 'valid' ? 'valid' : null);
+
+  if (status === 'valid' && previous !== 'valid') {
+    root.dispatchEvent(
+      new CustomEvent('puzzle:complete', {
+        bubbles: true,
+        detail: {
+          kind: 'magnetic-field',
+          puzzleId,
+        },
+      }),
+    );
+  }
+}
+
+export function resetMagneticFieldPuzzle(root: HTMLElement): void {
+  initMagneticFieldPuzzle(root);
+  initializeActivePuzzle(root);
+}
+
+function selectPiece(root: HTMLElement, pieceId: string | null): void {
+  const panel = getActivePanel(root);
+  const instance = instances.get(root);
+  if (!panel || !instance || panel.dataset.puzzleStatus === 'valid') return;
+  if (instance.selectedPieceId === pieceId) return;
+
+  instance.selectedPieceId = pieceId;
+  syncPieceSelection(panel, pieceId);
+  updateDestinations(root);
+}
+
+function togglePieceSelection(root: HTMLElement, pieceId: string | null): void {
+  const instance = instances.get(root);
+  if (!instance || !pieceId) {
+    selectPiece(root, null);
+    return;
+  }
+
+  selectPiece(root, instance.selectedPieceId === pieceId ? null : pieceId);
+}
+
+function syncPieceSelection(panel: HTMLElement, pieceId: string | null): void {
+  for (const piece of panel.querySelectorAll<HTMLElement>(
+    '[data-field-piece]',
+  )) {
+    const selected = piece.dataset.fieldPiece === pieceId;
+    piece.toggleAttribute('data-piece-selected', selected);
+    piece.setAttribute('aria-pressed', String(selected));
+  }
+}
+
+function updateDestinations(root: HTMLElement): void {
+  const panel = getActivePanel(root);
+  const instance = instances.get(root);
+  if (!panel || !instance) return;
+  hideMovePreviews(panel);
+  const pieceId = instance.selectedPieceId;
+  if (!pieceId) return;
+
+  const puzzle = readPuzzle(panel);
+  const state = readState(panel, puzzle);
+  const labels = panel.querySelector<HTMLElement>('[data-move-template]');
+  const piece = puzzle.pieces.find((candidate) => candidate.id === pieceId);
+  if (!piece) return;
+
+  for (const movement of getMagneticFieldMoves(puzzle, state, pieceId)) {
+    const directionLabel = readDirectionLabel(labels, movement.direction);
+    renderPathStream(panel, movement);
+
+    const destination = findCell(panel, movement.to);
+    if (!destination) continue;
+    destination.removeAttribute('tabindex');
+    destination.setAttribute('data-field-destination', '');
+    destination.setAttribute('data-puzzle-cell-interactive', '');
+    destination.dataset.destinationPiece = pieceId;
+    destination.dataset.destinationDirection = movement.direction;
+    destination.setAttribute(
+      'aria-label',
+      formatTemplate(labels?.dataset.moveTemplate ?? '', {
+        piece: piece.label,
+        direction: directionLabel,
+      }),
+    );
+  }
+}
+
+function movePiece(
+  root: HTMLElement,
+  pieceId: string,
+  direction: MagneticFieldDirection,
+  retainSelection = true,
+): void {
+  const panel = getActivePanel(root);
+  if (!panel || panel.dataset.puzzleStatus === 'valid') return;
+  const puzzle = readPuzzle(panel);
+  const current = readState(panel, puzzle);
+  const simulation = simulateMagneticFieldMove(puzzle, current, {
+    pieceId,
+    direction,
+  });
+  if (!simulation.movement) return;
+
+  const movingElement = panel.querySelector<HTMLButtonElement>(
+    `[data-field-piece="${CSS.escape(pieceId)}"]`,
+  );
+  const initialBounds = movingElement?.getBoundingClientRect();
+  renderState(panel, puzzle, simulation.state);
+  if (movingElement && initialBounds) {
+    animatePieceMovement(movingElement, initialBounds);
+  }
+  const complete = isMagneticFieldPuzzleComplete(puzzle, simulation.state);
+  const selectedPieceId = retainSelection && !complete ? pieceId : null;
+  const instance = instances.get(root);
+  if (instance) instance.selectedPieceId = selectedPieceId;
+  syncPieceSelection(panel, selectedPieceId);
+  if (selectedPieceId) {
+    updateDestinations(root);
+  } else {
+    hideMovePreviews(panel);
+  }
+  emitChange(root, puzzle.id, simulation.state);
+}
+
+function initializeActivePuzzle(root: HTMLElement): void {
+  const panel = getActivePanel(root);
+  const instance = instances.get(root);
+  if (!panel || !instance) return;
+  const puzzle = readPuzzle(panel);
+  const initial = createMagneticFieldInitialState(puzzle);
+
+  instance.selectedPieceId = null;
+  instance.drag = null;
+  instance.ignoreNextClick = false;
+  panel.dataset.puzzleStatus = 'incomplete';
+  const grid = panel.querySelector<HTMLElement>('[data-puzzle-grid]');
+  if (grid) setPuzzleGridState(grid, null);
+  renderState(panel, puzzle, initial);
+  hideMovePreviews(panel);
+  emitChange(root, puzzle.id, initial);
+}
+
+function renderState(
+  panel: HTMLElement,
+  puzzle: MagneticFieldPuzzleModel,
+  state: MagneticFieldPuzzleState,
+): void {
+  for (const target of panel.querySelectorAll<HTMLElement>(
+    '[data-field-target-cell]',
+  )) {
+    const targetState = target.dataset.puzzleCellState;
+    if (targetState === 'valid' || targetState === 'invalid') {
+      setPuzzleGridCellState(target, null);
+    }
+  }
+
+  for (const target of puzzle.targets) {
+    const targetElement = panel.querySelector<HTMLElement>(
+      `[data-field-target-cell="${CSS.escape(target.id)}"]`,
+    );
+    const occupant = puzzle.pieces.find((piece) => {
+      const position = state[piece.id];
+      return position?.row === target.row && position.column === target.column;
+    });
+    if (!targetElement || !occupant) continue;
+
+    const occupantState = state[occupant.id];
+    const valid =
+      occupant.id === target.pieceId &&
+      occupantState?.polarity === target.polarity;
+    setPuzzleGridCellState(targetElement, valid ? 'valid' : 'invalid');
+  }
+
+  for (const piece of puzzle.pieces) {
+    const current = state[piece.id];
+    const element = panel.querySelector<HTMLButtonElement>(
+      `[data-field-piece="${CSS.escape(piece.id)}"]`,
+    );
+    if (!current || !element) continue;
+
+    element.getAnimations().forEach((animation) => animation.cancel());
+    element.dataset.pieceRow = String(current.row);
+    element.dataset.pieceColumn = String(current.column);
+    element.dataset.piecePolarity = current.polarity;
+    element.style.setProperty('--piece-row', String(current.row + 1));
+    element.style.setProperty('--piece-column', String(current.column + 1));
+    const occupiedTarget = puzzle.targets.find(
+      (target) =>
+        target.row === current.row && target.column === current.column,
+    );
+    const pieceState = occupiedTarget
+      ? isPiecePlaced(puzzle, piece.id, current)
+        ? 'valid'
+        : 'invalid'
+      : null;
+    if (pieceState) {
+      element.dataset.pieceState = pieceState;
+    } else {
+      delete element.dataset.pieceState;
+    }
+    if (pieceState === 'invalid') {
+      element.setAttribute('aria-invalid', 'true');
+    } else {
+      element.removeAttribute('aria-invalid');
+    }
+
+    const polarityIdentity = element.querySelector<HTMLElement>(
+      '[data-piece-polarity-identity]',
+    );
+    if (polarityIdentity) {
+      polarityIdentity.dataset.polarity = current.polarity;
+    }
+    const polarityLabel =
+      current.polarity === 'north'
+        ? element.dataset.polarityLabelNorth
+        : element.dataset.polarityLabelSouth;
+    element.setAttribute(
+      'aria-label',
+      `${piece.label} — ${polarityLabel ?? current.polarity}`,
+    );
+
+    element.removeAttribute('data-piece-moved');
+  }
+}
+
+function animatePieceMovement(
+  element: HTMLButtonElement,
+  initialBounds: DOMRect,
+): void {
+  const finalBounds = element.getBoundingClientRect();
+  element.style.setProperty(
+    '--piece-move-inline-distance',
+    `${initialBounds.left - finalBounds.left}px`,
+  );
+  element.style.setProperty(
+    '--piece-move-block-distance',
+    `${initialBounds.top - finalBounds.top}px`,
+  );
+  element.setAttribute('data-piece-moved', '');
+}
+
+function finishDrag(
+  root: HTMLElement,
+  event: PointerEvent,
+  commit: boolean,
+): void {
+  const instance = instances.get(root);
+  const drag = instance?.drag;
+  if (!instance || !drag || drag.pointerId !== event.pointerId) return;
+  const deltaX = event.clientX - drag.startX;
+  const deltaY = event.clientY - drag.startY;
+  const destination =
+    commit && drag.moved && hasLeftOriginCell(drag, deltaX, deltaY)
+      ? findDirectionalDropDestination(drag, deltaX, deltaY)
+      : null;
+
+  cancelDragFrame(drag);
+  drag.element.removeAttribute('data-piece-dragging');
+  drag.element.style.removeProperty('--piece-drag-x');
+  drag.element.style.removeProperty('--piece-drag-y');
+  if (drag.element.hasPointerCapture(event.pointerId)) {
+    drag.element.releasePointerCapture(event.pointerId);
+  }
+  instance.drag = null;
+
+  if (commit && drag.moved) {
+    instance.ignoreNextClick = true;
+    window.setTimeout(() => {
+      const current = instances.get(root);
+      if (current === instance) current.ignoreNextClick = false;
+    }, 0);
+    const destinationPiece = destination?.dataset.destinationPiece;
+    const direction = destination?.dataset.destinationDirection as
+      MagneticFieldDirection | undefined;
+    if (destinationPiece === drag.pieceId && direction) {
+      movePiece(root, drag.pieceId, direction, false);
+    }
+  }
+  if (drag.moved) selectPiece(root, null);
+}
+
+function hasLeftOriginCell(
+  drag: MagneticFieldDrag,
+  deltaX: number,
+  deltaY: number,
+): boolean {
+  const centerX = drag.originCenterX + deltaX;
+  const centerY = drag.originCenterY + deltaY;
+  const { bottom, left, right, top } = drag.originCellBounds;
+
+  return centerX < left || centerX > right || centerY < top || centerY > bottom;
+}
+
+function scheduleDragFrame(root: HTMLElement, drag: MagneticFieldDrag): void {
+  if (drag.frameId !== null) return;
+  drag.frameId = window.requestAnimationFrame(() => {
+    drag.frameId = null;
+    if (instances.get(root)?.drag !== drag) return;
+
+    drag.element.style.setProperty(
+      '--piece-drag-x',
+      `${drag.currentX - drag.startX}px`,
+    );
+    drag.element.style.setProperty(
+      '--piece-drag-y',
+      `${drag.currentY - drag.startY}px`,
+    );
+  });
+}
+
+function cancelDragFrame(drag: MagneticFieldDrag): void {
+  if (drag.frameId === null) return;
+  window.cancelAnimationFrame(drag.frameId);
+  drag.frameId = null;
+}
+
+function getDropDestinations(root: HTMLElement): HTMLButtonElement[] {
+  const panel = getActivePanel(root);
+  if (!panel) return [];
+
+  return [
+    ...panel.querySelectorAll<HTMLButtonElement>('[data-field-destination]'),
+  ];
+}
+
+function findDirectionalDropDestination(
+  drag: MagneticFieldDrag,
+  deltaX: number,
+  deltaY: number,
+): HTMLButtonElement | null {
+  let direction: MagneticFieldDirection;
+  if (Math.abs(deltaX) >= Math.abs(deltaY)) {
+    direction = deltaX >= 0 ? 'east' : 'west';
+  } else {
+    direction = deltaY >= 0 ? 'south' : 'north';
+  }
+
+  return (
+    (drag.destinations ?? []).find(
+      (destination) =>
+        destination.dataset.destinationDirection === direction &&
+        destination.dataset.destinationPiece === drag.pieceId,
+    ) ?? null
+  );
+}
+
+function hideMovePreviews(panel: HTMLElement): void {
+  for (const stream of panel.querySelectorAll<HTMLElement>(
+    '[data-field-path-stream]',
+  )) {
+    stream.remove();
+  }
+
+  for (const destination of panel.querySelectorAll<HTMLButtonElement>(
+    '[data-field-destination]',
+  )) {
+    destination.tabIndex = -1;
+    destination.removeAttribute('data-field-destination');
+    destination.removeAttribute('data-puzzle-cell-interactive');
+    destination.removeAttribute('data-destination-piece');
+    destination.removeAttribute('data-destination-direction');
+    const cellLabel = destination.dataset.cellLabel;
+    if (cellLabel) {
+      destination.setAttribute('aria-label', cellLabel);
+    } else {
+      destination.removeAttribute('aria-label');
+    }
+  }
+}
+
+function renderPathStream(
+  panel: HTMLElement,
+  movement: MagneticFieldMovement,
+): void {
+  const board = panel.querySelector<HTMLElement>('[data-field-board]');
+  if (!board) return;
+
+  const rowDistance = movement.to.row - movement.from.row;
+  const columnDistance = movement.to.column - movement.from.column;
+  const cellDistance = Math.abs(rowDistance) + Math.abs(columnDistance);
+  const chevronCount = pathChevronsPerCell * cellDistance;
+  const stream = document.createElement('span');
+  stream.className = 'magnetic-field-puzzle__path-stream';
+  stream.dataset.fieldPathStream = '';
+  stream.dataset.fieldPathDirection = movement.direction;
+  stream.setAttribute('aria-hidden', 'true');
+  stream.style.setProperty('--field-path-row', String(movement.from.row + 1));
+  stream.style.setProperty(
+    '--field-path-column',
+    String(movement.from.column + 1),
+  );
+  stream.style.setProperty(
+    '--field-path-target-inline',
+    `${50 + columnDistance * 100}%`,
+  );
+  stream.style.setProperty(
+    '--field-path-target-block',
+    `${50 + rowDistance * 100}%`,
+  );
+  stream.style.setProperty(
+    '--field-path-duration',
+    `${pathDurationPerCellMs * cellDistance}ms`,
+  );
+
+  for (let index = 0; index < chevronCount; index += 1) {
+    const progress = (index + 0.5) / chevronCount;
+    const chevron = document.createElement('span');
+    chevron.className = 'magnetic-field-puzzle__path-chevron';
+    chevron.style.setProperty('--field-path-chevron-index', String(index));
+    chevron.style.setProperty(
+      '--field-path-static-inline',
+      `${50 + columnDistance * progress * 100}%`,
+    );
+    chevron.style.setProperty(
+      '--field-path-static-block',
+      `${50 + rowDistance * progress * 100}%`,
+    );
+    stream.append(chevron);
+  }
+
+  board.append(stream);
+}
+
+function findCell(
+  panel: HTMLElement,
+  position: { row: number; column: number },
+): HTMLButtonElement | null {
+  return panel.querySelector<HTMLButtonElement>(
+    `[data-field-cell][data-cell-row="${position.row}"][data-cell-column="${position.column}"]`,
+  );
+}
+
+function readPuzzle(panel: HTMLElement): MagneticFieldPuzzleModel {
+  const board = panel.querySelector<HTMLElement>('[data-field-board]');
+  const pieces = [...panel.querySelectorAll<HTMLElement>('[data-field-piece]')];
+  return {
+    id: panel.dataset.puzzleId ?? '',
+    label: board?.getAttribute('aria-label') ?? '',
+    rows: Number(board?.dataset.fieldRows),
+    columns: Number(board?.dataset.fieldColumns),
+    pieces: pieces.map((piece) => ({
+      id: piece.dataset.fieldPiece ?? '',
+      label: piece.dataset.pieceLabel ?? '',
+      shortLabel: piece.dataset.pieceShortLabel ?? '',
+      row: Number(piece.dataset.initialRow),
+      column: Number(piece.dataset.initialColumn),
+      polarity: piece.dataset.initialPolarity as MagneticFieldPolarity,
+      pupilPosition: piece.dataset
+        .piecePupilPosition as MagneticFieldPupilPosition,
+    })),
+    targets: [
+      ...panel.querySelectorAll<HTMLElement>('[data-field-target]'),
+    ].map((target) => ({
+      id: target.dataset.fieldTarget ?? '',
+      label: target.dataset.targetLabel ?? '',
+      pieceId: target.dataset.targetPiece ?? '',
+      row: Number(target.dataset.targetRow),
+      column: Number(target.dataset.targetColumn),
+      polarity: target.dataset.targetPolarity as MagneticFieldPolarity,
+    })),
+    blockedCells: [
+      ...panel.querySelectorAll<HTMLElement>('[data-field-blocked-cell]'),
+    ].map((cell) => ({
+      id: cell.dataset.fieldBlockedCell ?? '',
+      label: cell.getAttribute('aria-label') ?? '',
+      row: Number(cell.dataset.cellRow),
+      column: Number(cell.dataset.cellColumn),
+    })),
+    inverters: [
+      ...panel.querySelectorAll<HTMLElement>('[data-field-inverter]'),
+    ].map((inverter) => ({
+      id: inverter.dataset.fieldInverter ?? '',
+      label: inverter.dataset.inverterLabel ?? '',
+      row: Number(inverter.dataset.inverterRow),
+      column: Number(inverter.dataset.inverterColumn),
+    })),
+  };
+}
+
+function readState(
+  panel: HTMLElement,
+  puzzle: MagneticFieldPuzzleModel,
+): MagneticFieldPuzzleState {
+  return Object.fromEntries(
+    puzzle.pieces.map((piece) => {
+      const element = panel.querySelector<HTMLElement>(
+        `[data-field-piece="${CSS.escape(piece.id)}"]`,
+      );
+      return [
+        piece.id,
+        {
+          row: Number(element?.dataset.pieceRow),
+          column: Number(element?.dataset.pieceColumn),
+          polarity: element?.dataset.piecePolarity as MagneticFieldPolarity,
+        },
+      ];
+    }),
+  );
+}
+
+function isPiecePlaced(
+  puzzle: MagneticFieldPuzzleModel,
+  pieceId: string,
+  state: MagneticFieldPuzzleState[string],
+): boolean {
+  const target = puzzle.targets.find(
+    (candidate) => candidate.pieceId === pieceId,
+  );
+  return (
+    target !== undefined &&
+    target.row === state.row &&
+    target.column === state.column &&
+    target.polarity === state.polarity
+  );
+}
+
+function emitChange(
+  root: HTMLElement,
+  puzzleId: string,
+  state: MagneticFieldPuzzleState,
+): void {
+  const detail: MagneticFieldPuzzleChangeDetail = {
+    kind: 'magnetic-field',
+    puzzleId,
+    state,
+  };
+  root.dispatchEvent(
+    new CustomEvent<MagneticFieldPuzzleChangeDetail>('puzzle:change', {
+      bubbles: true,
+      detail,
+    }),
+  );
+}
+
+function getPanels(root: HTMLElement): HTMLElement[] {
+  return [...root.querySelectorAll<HTMLElement>(':scope > [data-puzzle-id]')];
+}
+
+function getActivePanel(root: HTMLElement): HTMLElement | undefined {
+  const index = instances.get(root)?.activeIndex ?? 0;
+  return getPanels(root)[index];
+}
+
+function readDirectionLabel(
+  element: HTMLElement | null,
+  direction: MagneticFieldDirection,
+): string {
+  const key = `directionLabel${capitalize(direction)}` as keyof DOMStringMap;
+  return element?.dataset[key] ?? direction;
+}
+
+function formatTemplate(
+  template: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  return Object.entries(values).reduce(
+    (result, [key, value]) => result.replaceAll(`{${key}}`, value),
+    template,
+  );
+}
+
+function capitalize(value: string): string {
+  return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
+
+const arrowDirections: Readonly<
+  Partial<Record<string, MagneticFieldDirection>>
+> = {
+  arrowup: 'north',
+  arrowright: 'east',
+  arrowdown: 'south',
+  arrowleft: 'west',
+};