@astronox/core 0.5.9 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/client/scroll.ts

@@ -1,5 +1,5 @@
 type JumpToElementOptions = {
-  block?: ScrollLogicalPosition;
+  block?: ScrollLogicalPosition | 'auto';
   inline?: ScrollLogicalPosition;
 };
 
@@ -7,6 +7,19 @@ export function jumpToElement(
   element: Element,
   { block = 'center', inline = 'nearest' }: JumpToElementOptions = {},
 ): void {
+  if (block === 'auto') {
+    const header = document.querySelector<HTMLElement>('[data-site-header]');
+    const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+    const availableHeight = Math.max(
+      0,
+      viewportHeight - (header?.getBoundingClientRect().height ?? 0),
+    );
+    block =
+      element.getBoundingClientRect().height <= availableHeight
+        ? 'center'
+        : 'start';
+  }
+
   element.scrollIntoView({
     behavior: 'auto',
     block,

package/src/components/data-display/IconList/IconList.astro

@@ -2,6 +2,7 @@
 import type { HTMLAttributes } from 'astro/types';
 import type { DisplayIconItem } from '../../../display/contracts';
 import type { Tone } from '../../../theme/contracts';
+import Tooltip from '../../feedback/Tooltip/Tooltip.astro';
 
 type Props = HTMLAttributes<'div'> & {
   'data-tone'?: Tone;
@@ -9,6 +10,7 @@ type Props = HTMLAttributes<'div'> & {
   label?: string;
   size?: 'small' | 'medium';
   tone?: Tone;
+  tooltips?: boolean;
 };
 
 const {
@@ -18,6 +20,7 @@ const {
   label,
   size = 'small',
   tone,
+  tooltips = true,
   ...attrs
 }: Props = Astro.props;
 const resolvedTone = tone ?? dataTone;
@@ -34,6 +37,11 @@ const resolvedTone = tone ?? dataTone;
   {
     items.map((item) => {
       const Icon = item.icon;
+      const tooltip = tooltips
+        ? typeof item.tooltip === 'string'
+          ? item.tooltip.trim()
+          : item.tooltip
+        : undefined;
       const icon = (
         <span class="icon-list__icon">
           <Icon />
@@ -44,14 +52,16 @@ const resolvedTone = tone ?? dataTone;
           <span class="icon-list__value">{item.value}</span>
         ) : null;
 
-      return (
+      const content = (
         <span
           class="icon-list__item"
           data-muted={item.muted ? 'true' : undefined}
           data-tone={item.tone}
           role="group"
           aria-label={item.label}
-          title={item.label}
+          title={tooltips && !tooltip ? item.label : undefined}
+          tabindex={tooltip ? '0' : undefined}
+          data-tooltip-trigger={tooltip ? true : undefined}
         >
           <span class="icon-list__visible" aria-hidden="true">
             {item.iconPosition === 'end' ? value : icon}
@@ -59,6 +69,14 @@ const resolvedTone = tone ?? dataTone;
           </span>
         </span>
       );
+
+      return tooltip ? (
+        <Tooltip content={tooltip} activation="hover">
+          {content}
+        </Tooltip>
+      ) : (
+        content
+      );
     })
   }
 </div>

package/src/components/data-display/MetricTile/MetricTileContent.astro

@@ -42,7 +42,12 @@ const ValueIcon = icon?.component;
 <dd class="metric-tile__value">
   {
     items ? (
-      <IconList items={items} label={itemsLabel} size="medium" />
+      <IconList
+        items={items}
+        label={itemsLabel}
+        size="medium"
+        tooltips={!hint}
+      />
     ) : (
       <>
         <strong data-metric-value>{value}</strong>

package/src/components/feedback/Tooltip/Tooltip.css

@@ -26,8 +26,16 @@
   position: fixed;
   z-index: 100;
   inset: auto;
+  box-sizing: border-box;
   inline-size: max-content;
-  max-inline-size: min(22rem, calc(100vw - var(--nox-space-4) * 2));
+  min-inline-size: 0;
+  max-inline-size: min(
+    26rem,
+    var(
+      --tooltip-available-inline-size,
+      calc(100vw - var(--tooltip-viewport-gap) * 2)
+    )
+  );
   max-block-size: calc(100dvh - var(--nox-space-4) * 2);
   margin: 0;
   padding: var(--nox-space-3) var(--nox-space-4);

package/src/components/feedback/Tooltip/tooltipController.ts

@@ -125,17 +125,16 @@ export function initTooltip(root: HTMLElement): () => void {
     const triggerGap = getCssLength(panel, '--tooltip-trigger-gap', 8);
     const triggerRect = trigger.getBoundingClientRect();
     const boundary =
-      root.dataset.tooltipAlignTo === 'boundary'
-        ? root.closest<HTMLElement>('[data-tooltip-boundary]')
-        : null;
-    const boundaryRect = boundary?.getBoundingClientRect();
+      root.closest<HTMLElement>('[data-tooltip-boundary], main, dialog') ??
+      document.body;
+    const boundaryRect = boundary.getBoundingClientRect();
     const horizontalLeft = Math.max(
       viewport.left + viewportGap,
-      boundaryRect?.left ?? viewport.left + viewportGap,
+      boundaryRect.left,
     );
     const horizontalRight = Math.min(
       viewport.right - viewportGap,
-      boundaryRect?.right ?? viewport.right - viewportGap,
+      boundaryRect.right,
     );
     const maximumInlineSize = Math.max(0, horizontalRight - horizontalLeft);
     const maximumBlockSize = Math.max(
@@ -143,7 +142,10 @@ export function initTooltip(root: HTMLElement): () => void {
       viewport.bottom - viewport.top - viewportGap * 2,
     );
 
-    panel.style.maxInlineSize = `${Math.floor(maximumInlineSize)}px`;
+    panel.style.setProperty(
+      '--tooltip-available-inline-size',
+      `${Math.floor(maximumInlineSize)}px`,
+    );
     panel.style.maxBlockSize = `${Math.floor(maximumBlockSize)}px`;
     panel.style.visibility = 'hidden';
     panel.style.left = `${Math.round(horizontalLeft)}px`;
@@ -165,7 +167,8 @@ export function initTooltip(root: HTMLElement): () => void {
 
     panel.style.maxBlockSize = `${Math.floor(availableBlockSize)}px`;
     const panelRect = panel.getBoundingClientRect();
-    const horizontalAnchor = boundaryRect ?? triggerRect;
+    const horizontalAnchor =
+      root.dataset.tooltipAlignTo === 'boundary' ? boundaryRect : triggerRect;
     const centeredLeft =
       horizontalAnchor.left + (horizontalAnchor.width - panelRect.width) / 2;
     const left = Math.min(
@@ -199,7 +202,7 @@ export function initTooltip(root: HTMLElement): () => void {
     panel.hidden = true;
     panel.style.removeProperty('left');
     panel.style.removeProperty('top');
-    panel.style.removeProperty('max-inline-size');
+    panel.style.removeProperty('--tooltip-available-inline-size');
     panel.style.removeProperty('max-block-size');
     panel.style.removeProperty('visibility');
   };

package/src/components/media/EmbedFrame/EmbedFrame.astro

@@ -21,6 +21,9 @@ type Props = Omit<
   loading?: EmbedLoading;
   loadingIndicator?: EmbedLoadingIndicator;
   loadingLabel: string;
+  pageScroll?: 'auto' | 'lock-while-interacting';
+  scrollOnActivate?: boolean;
+  scrollTargetId?: string;
   src: string;
   title: string;
   tone?: Tone;
@@ -45,6 +48,9 @@ const {
   loading = 'lazy',
   loadingIndicator = 'spinner',
   loadingLabel,
+  pageScroll = 'auto',
+  scrollOnActivate = false,
+  scrollTargetId,
   src,
   title,
   tone,
@@ -59,6 +65,9 @@ const resolvedTone = tone ?? dataTone;
   class="embed-frame"
   data-embed-frame-activation={activation}
   data-embed-frame-source={activation === 'manual' ? src : undefined}
+  data-embed-frame-page-scroll={pageScroll}
+  data-embed-frame-scroll-on-activate={scrollOnActivate ? 'true' : undefined}
+  data-embed-frame-scroll-target={scrollTargetId}
   data-aspect-ratio={aspectRatio}
   data-fullscreen-region={fullscreen ? true : undefined}
   data-widget="embed-frame"

package/src/components/media/EmbedFrame/EmbedFrame.css

@@ -6,6 +6,11 @@
   overflow: hidden;
 }
 
+html:has([data-embed-frame-scroll-locked]),
+[data-site-scroll-root]:has([data-embed-frame-scroll-locked]) {
+  overflow: hidden;
+}
+
 .embed-frame[data-aspect-ratio='16/9'] {
   aspect-ratio: 16 / 9;
 }

package/src/components/media/EmbedFrame/embedFrameController.ts

@@ -1,3 +1,5 @@
+import { jumpToElement } from '../../../client/scroll';
+
 const activateEvent = 'nox:embed-frame:activate';
 
 export function activateEmbedFrame(
@@ -27,6 +29,55 @@ export const initEmbedFrame = (root: HTMLElement): (() => void) => {
   let activated =
     root.dataset.embedFrameActivation !== 'manual' ||
     root.dataset.embedFrameActive === 'true';
+  let activationFocusFrame = 0;
+  let focusCheckFrame = 0;
+  let interactionDismissed = false;
+  const lockPageScroll =
+    root.dataset.embedFramePageScroll === 'lock-while-interacting';
+
+  const setScrollLock = (locked: boolean) => {
+    root.toggleAttribute(
+      'data-embed-frame-scroll-locked',
+      lockPageScroll && activated && locked,
+    );
+  };
+
+  const releaseScroll = () => {
+    cancelAnimationFrame(activationFocusFrame);
+    cancelAnimationFrame(focusCheckFrame);
+    activationFocusFrame = 0;
+    focusCheckFrame = 0;
+    interactionDismissed = true;
+    setScrollLock(false);
+  };
+  const enterFrame = () => {
+    cancelAnimationFrame(focusCheckFrame);
+    focusCheckFrame = 0;
+    interactionDismissed = false;
+    setScrollLock(true);
+  };
+  const leaveFrame = (event: PointerEvent) => {
+    if (event.pointerType !== 'touch') releaseScroll();
+  };
+  const updateFocus = () => {
+    cancelAnimationFrame(focusCheckFrame);
+    focusCheckFrame = requestAnimationFrame(() => {
+      focusCheckFrame = 0;
+      setScrollLock(!interactionDismissed && document.activeElement === iframe);
+    });
+  };
+  const interactOutside = (event: Event) => {
+    if (event.target instanceof Node && !root.contains(event.target)) {
+      releaseScroll();
+    }
+  };
+
+  const scrollToFrame = () => {
+    if (root.dataset.embedFrameScrollOnActivate !== 'true') return;
+    const targetId = root.dataset.embedFrameScrollTarget;
+    const target = (targetId && document.getElementById(targetId)) || root;
+    jumpToElement(target, { block: 'auto' });
+  };
 
   const markLoaded = () => {
     if (!activated) return;
@@ -46,19 +97,51 @@ export const initEmbedFrame = (root: HTMLElement): (() => void) => {
     root.setAttribute('aria-busy', loading ? 'true' : 'false');
     root.setAttribute('data-embed-frame-active', 'true');
     iframe.src = src;
+    scrollToFrame();
   };
 
   const activateFromControl = () => {
     activate();
-    requestAnimationFrame(() => iframe.focus({ preventScroll: true }));
+    cancelAnimationFrame(activationFocusFrame);
+    interactionDismissed = false;
+    activationFocusFrame = requestAnimationFrame(() => {
+      activationFocusFrame = 0;
+      iframe.focus({ preventScroll: true });
+      setScrollLock(document.activeElement === iframe);
+    });
   };
 
   if (activated && activationLayer) activationLayer.hidden = true;
   iframe.addEventListener('load', markLoaded);
   root.addEventListener(activateEvent, activate);
   activationControl?.addEventListener('click', activateFromControl);
+  if (lockPageScroll) {
+    root.addEventListener('pointerenter', enterFrame);
+    root.addEventListener('pointerleave', leaveFrame);
+    iframe.addEventListener('focus', enterFrame);
+    iframe.addEventListener('blur', releaseScroll);
+    window.addEventListener('blur', updateFocus);
+    window.addEventListener('focus', updateFocus);
+    window.addEventListener('pagehide', releaseScroll);
+    document.addEventListener('focusin', interactOutside);
+    document.addEventListener('pointerdown', interactOutside, true);
+    document.addEventListener('wheel', interactOutside, { passive: true });
+    document.addEventListener('touchstart', interactOutside, { passive: true });
+  }
 
   return () => {
+    releaseScroll();
+    root.removeEventListener('pointerenter', enterFrame);
+    root.removeEventListener('pointerleave', leaveFrame);
+    iframe.removeEventListener('focus', enterFrame);
+    iframe.removeEventListener('blur', releaseScroll);
+    window.removeEventListener('blur', updateFocus);
+    window.removeEventListener('focus', updateFocus);
+    window.removeEventListener('pagehide', releaseScroll);
+    document.removeEventListener('focusin', interactOutside);
+    document.removeEventListener('pointerdown', interactOutside, true);
+    document.removeEventListener('wheel', interactOutside);
+    document.removeEventListener('touchstart', interactOutside);
     iframe.removeEventListener('load', markLoaded);
     root.removeEventListener(activateEvent, activate);
     activationControl?.removeEventListener('click', activateFromControl);

package/src/display/contracts.ts

@@ -92,6 +92,7 @@ export type DisplayIconItem = {
   label: string;
   muted?: boolean;
   tone?: Tone;
+  tooltip?: string | DisplayTooltip;
   value?: DisplayTextValue;
 };
 

package/src/patterns/CircuitPuzzle/CircuitPuzzle.astro

@@ -58,6 +58,9 @@ const {
                 data-puzzle-cell-interactive={cell.fixed ? undefined : ''}
                 data-puzzle-cell-disabled={cell.fixed ? '' : undefined}
                 data-circuit-cell={cell.id}
+                data-puzzle-control={cell.fixed ? undefined : ''}
+                data-cell-row={cell.row}
+                data-cell-column={cell.column}
                 data-cell-kind={cell.kind}
                 data-cell-label={cellLabel}
                 data-orientation-label={labels.orientation}

package/src/patterns/CircuitPuzzle/circuitPuzzleController.ts

@@ -3,6 +3,11 @@ import {
   setPuzzleGridState,
 } from '../PuzzleGrid/state';
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import {
+  initPuzzleKeyboard,
+  type PuzzleKeyboard,
+} from '../PuzzleGrid/keyboard';
+import type { PuzzleDirection } from '../PuzzleGrid/movement';
 import type {
   CircuitPuzzleChangeDetail,
   CircuitPuzzleEvaluation,
@@ -11,6 +16,7 @@ import type {
 
 type CircuitInstance = {
   activeIndex: number;
+  keyboard?: PuzzleKeyboard;
 };
 
 const rotations: readonly CircuitRotation[] = [0, 90, 180, 270];
@@ -60,6 +66,21 @@ export function initCircuitPuzzle(root: HTMLElement): void {
     setRotation(cell, rotations[nextIndex], visualRotation + 90);
     emitChange(root);
   });
+  instances.get(root)!.keyboard = initPuzzleKeyboard(root, {
+    getPanel: () => getActivePanel(root),
+    getSelected: () =>
+      getActivePanel(root)?.querySelector<HTMLButtonElement>(
+        '[data-circuit-cell][data-puzzle-cell-selected]',
+      ) ?? null,
+    select: (cell) => {
+      const panel = getActivePanel(root);
+      if (panel) selectCell(panel, cell);
+    },
+    move: (cell, direction) => {
+      const panel = getActivePanel(root);
+      if (panel) moveCellFocus(panel, cell, direction);
+    },
+  });
 }
 
 export function selectCircuitPuzzle(root: HTMLElement, index: number): void {
@@ -100,6 +121,7 @@ export function resetCircuitPuzzle(root: HTMLElement): void {
       panel.removeAttribute('data-puzzle-resetting');
     });
   });
+  instances.get(root)?.keyboard?.reset();
   emitChange(root);
 }
 
@@ -132,6 +154,7 @@ export function setCircuitPuzzleEvaluation(
   if (grid) {
     setPuzzleGridState(grid, evaluation.status === 'valid' ? 'valid' : null);
   }
+  if (evaluation.status === 'valid') selectCell(panel, null);
 
   if (evaluation.status === 'valid' && previous !== 'valid') {
     root.dispatchEvent(
@@ -170,6 +193,32 @@ function selectCell(
   }
 }
 
+function moveCellFocus(
+  panel: HTMLElement,
+  origin: HTMLButtonElement,
+  direction: PuzzleDirection,
+): void {
+  const vertical = direction === 'north' || direction === 'south';
+  const sign = direction === 'north' || direction === 'west' ? -1 : 1;
+  const row = Number(origin.dataset.cellRow);
+  const column = Number(origin.dataset.cellColumn);
+  let nearest: HTMLButtonElement | null = null;
+  let nearestDistance = Infinity;
+  for (const cell of panel.querySelectorAll<HTMLButtonElement>(
+    '[data-puzzle-control]:not(:disabled)',
+  )) {
+    const rowDistance = Number(cell.dataset.cellRow) - row;
+    const columnDistance = Number(cell.dataset.cellColumn) - column;
+    if (vertical ? columnDistance !== 0 : rowDistance !== 0) continue;
+    const distance = (vertical ? rowDistance : columnDistance) * sign;
+    if (distance > 0 && distance < nearestDistance) {
+      nearest = cell;
+      nearestDistance = distance;
+    }
+  }
+  nearest?.focus({ preventScroll: true });
+}
+
 function emitChange(root: HTMLElement): void {
   const panel = getActivePanel(root);
   if (!panel?.dataset.puzzleId) return;

package/src/patterns/LightMazePuzzle/LightMazePuzzle.astro

@@ -188,6 +188,7 @@ if (puzzles.some((puzzle) => puzzle.activators?.length) && !media.mechanism)
                 aria-label={labels[piece]}
                 aria-pressed="false"
                 data-light-maze-piece={piece}
+                data-puzzle-control
                 style={`--piece-row: ${initial[piece].row + 1}; --piece-column: ${initial[piece].column + 1};`}
               >
                 <span class="light-maze-puzzle__piece-media" aria-hidden="true">

package/src/patterns/LightMazePuzzle/lightMazePuzzleController.ts

@@ -1,13 +1,19 @@
 import {
   animatePieceMovement,
   cancelDragFrame,
+  clearPuzzleMovementPreview,
   findDirectionalDropDestination,
+  getPuzzleMoveTarget,
   hasLeftOriginCell,
   renderPathStream,
   scheduleDragFrame,
   type PuzzleDrag,
 } from '../PuzzleGrid/movement';
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import {
+  initPuzzleKeyboard,
+  type PuzzleKeyboard,
+} from '../PuzzleGrid/keyboard';
 import { presentLightMazeCell } from './presentation';
 import {
   setPuzzleGridCellState,
@@ -48,15 +54,10 @@ type Instance = {
   clickTimer: number | null;
   controller: AbortController;
   dismiss: () => void;
+  keyboard?: PuzzleKeyboard;
 };
 
 const instances = new WeakMap<HTMLElement, Instance>();
-const arrows: Record<string, LightMazeDirection> = {
-  ArrowUp: 'north',
-  ArrowRight: 'east',
-  ArrowDown: 'south',
-  ArrowLeft: 'west',
-};
 
 export function initLightMazePuzzle(root: HTMLElement): void {
   if (instances.has(root)) return;
@@ -92,15 +93,14 @@ export function initLightMazePuzzle(root: HTMLElement): void {
   instances.set(root, instance);
   instance.dismiss = initPuzzleSelectionDismissal(root, {
     dismiss: () => selectPiece(root, null),
-    isSelectionTarget: (target) => {
+    isSelectionTarget: (target, event) => {
       const panel = active(instance);
       return (
         panel.element.dataset.puzzleStatus !== 'valid' &&
         panel.element.contains(target) &&
         Boolean(
-          target.closest(
-            '[data-light-maze-piece], [data-light-maze-destination]',
-          ),
+          target.closest('[data-light-maze-piece]') ||
+          getPuzzleMoveTarget(panel.element, event),
         )
       );
     },
@@ -128,50 +128,14 @@ export function initLightMazePuzzle(root: HTMLElement): void {
         selectPiece(root, instance.selected === id ? null : id);
         return;
       }
-      const destination = event.target.closest<HTMLButtonElement>(
-        '[data-light-maze-destination]',
-      );
-      if (destination && !destination.disabled) {
-        void move(
-          root,
-          destination.dataset.destinationPiece as LightMazePiece,
-          destination.dataset.destinationDirection as LightMazeDirection,
-        );
+      const movement = getPuzzleMoveTarget(active(instance).element, event);
+      if (movement) {
+        void move(root, movement.pieceId as LightMazePiece, movement.direction);
       } else selectPiece(root, null);
     },
     options,
   );
 
-  root.addEventListener(
-    'keydown',
-    (event) => {
-      if (instance.motion) {
-        if (arrows[event.key] || ['Enter', ' ', 'Escape'].includes(event.key))
-          event.preventDefault();
-        return;
-      }
-      if (event.altKey || event.ctrlKey || event.metaKey || instance.drag)
-        return;
-      if (event.key === 'Escape') {
-        selectPiece(root, null);
-        return;
-      }
-      const direction = arrows[event.key];
-      if (!direction) return;
-      const focused =
-        event.target instanceof Element
-          ? event.target.closest<HTMLElement>('[data-light-maze-piece]')
-          : null;
-      const piece =
-        (focused?.dataset.lightMazePiece as LightMazePiece | undefined) ??
-        instance.selected;
-      if (!piece) return;
-      event.preventDefault();
-      void move(root, piece, direction);
-    },
-    options,
-  );
-
   root.addEventListener(
     'pointerdown',
     (event) => {
@@ -264,6 +228,30 @@ export function initLightMazePuzzle(root: HTMLElement): void {
     options,
   );
   render(root);
+  instance.keyboard = initPuzzleKeyboard(root, {
+    getPanel: () => active(instance).element,
+    getSelected: () =>
+      instance.selected
+        ? active(instance).element.querySelector<HTMLButtonElement>(
+            `[data-light-maze-piece="${instance.selected}"]`,
+          )
+        : null,
+    select: (piece) => {
+      if (!piece) cancelDrag(instance);
+      selectPiece(
+        root,
+        (piece?.dataset.lightMazePiece as LightMazePiece | undefined) ?? null,
+      );
+    },
+    move: (piece, direction) => {
+      void move(
+        root,
+        piece.dataset.lightMazePiece as LightMazePiece,
+        direction,
+      );
+    },
+    isLocked: () => instance.motion !== null || instance.drag !== null,
+  });
 }
 
 export function selectLightMazePuzzle(root: HTMLElement, index: number): void {
@@ -302,6 +290,7 @@ export function resetLightMazePuzzle(root: HTMLElement): void {
     piece.removeAttribute('data-piece-moved');
   }
   render(root);
+  instance.keyboard?.reset();
   emitChange(root, panel);
 }
 
@@ -339,6 +328,7 @@ export function destroyLightMazePuzzle(root: HTMLElement): void {
   cancelMotion(instance);
   instance.controller.abort();
   instance.dismiss();
+  instance.keyboard?.destroy();
   cancelDrag(instance);
   clearClickTimer(instance);
   for (const panel of instance.panels) {
@@ -360,7 +350,7 @@ function selectPiece(root: HTMLElement, piece: LightMazePiece | null): void {
   const instance = instances.get(root);
   if (
     !instance ||
-    instance.motion ||
+    (instance.motion && piece !== null) ||
     active(instance).element.dataset.puzzleStatus === 'valid'
   )
     return;
@@ -570,8 +560,8 @@ function renderSelection(root: HTMLElement): void {
     if (movement.piece !== instance.selected) continue;
     const destination = findCell(panel, movement.to);
     if (!destination) continue;
-    renderPathStream(panel.board, movement);
-    destination.tabIndex = 0;
+    renderPathStream(panel.board, movement, movement.piece);
+    destination.tabIndex = -1;
     destination.setAttribute('data-light-maze-destination', '');
     destination.setAttribute('data-puzzle-cell-interactive', '');
     destination.dataset.destinationPiece = movement.piece;
@@ -587,10 +577,7 @@ function renderSelection(root: HTMLElement): void {
 }
 
 function clearPreviews(panel: Panel): void {
-  for (const stream of panel.element.querySelectorAll(
-    '[data-puzzle-path-stream]',
-  ))
-    stream.remove();
+  clearPuzzleMovementPreview(panel.element);
   for (const cell of panel.element.querySelectorAll<HTMLButtonElement>(
     '[data-light-maze-destination]',
   )) {

package/src/patterns/MagneticFieldPuzzle/MagneticFieldPuzzle.astro

@@ -214,6 +214,7 @@ if (
                 aria-label={`${piece.label} — ${labels.polarities[piece.polarity]}`}
                 aria-pressed="false"
                 data-field-piece={piece.id}
+                data-puzzle-control
                 data-field-piece-media={media ? '' : undefined}
                 data-piece-label={piece.label}
                 data-piece-short-label={piece.shortLabel}

package/src/patterns/MagneticFieldPuzzle/MagneticFieldPuzzle.css

@@ -106,11 +106,11 @@
 }
 
 .magnetic-field-puzzle__identity[data-polarity='north'] {
-  color: var(--nox-source-tone-info);
+  color: var(--nox-source-magnetic-north);
 }
 
 .magnetic-field-puzzle__identity[data-polarity='south'] {
-  color: var(--nox-source-tone-danger);
+  color: var(--nox-source-magnetic-south);
 }
 
 .magnetic-field-puzzle__polarity-icon {