@astronox/core 0.5.7 → 0.5.8

package/package.json

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

package/src/patterns/LightMazePuzzle/LightMazePuzzle.astro

@@ -0,0 +1,210 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import Media from '../../primitives/media/Media/Media.astro';
+import PuzzleGrid from '../PuzzleGrid/PuzzleGrid.astro';
+import { presentLightMazeCell } from './presentation';
+import type {
+  LightMazePuzzleLabels,
+  LightMazePuzzleMedia,
+  LightMazePuzzleModel,
+} from './contracts';
+import {
+  createLightMazePuzzleState,
+  evaluateLightMazeMechanism,
+} from './simulation';
+
+type Props = HTMLAttributes<'section'> & {
+  label: string;
+  labels: LightMazePuzzleLabels;
+  media: LightMazePuzzleMedia;
+  puzzles: readonly LightMazePuzzleModel[];
+};
+
+const {
+  class: className,
+  label,
+  labels,
+  media,
+  puzzles,
+  ...attrs
+} = Astro.props;
+
+if (puzzles.some((puzzle) => puzzle.activators?.length) && !media.mechanism)
+  throw new Error('Light maze mechanisms require display media.');
+---
+
+<section
+  {...attrs}
+  class:list={['light-maze-puzzle', className]}
+  aria-label={label}
+  data-light-maze-puzzle
+>
+  {
+    puzzles.map((puzzle, index) => {
+      const initial = createLightMazePuzzleState(puzzle);
+      const mechanism = evaluateLightMazeMechanism(puzzle, initial);
+      return (
+        <div
+          class="light-maze-puzzle__instance"
+          data-puzzle-id={puzzle.id}
+          data-puzzle-status="incomplete"
+          data-light-maze-model={JSON.stringify(puzzle)}
+          data-light-maze-labels={JSON.stringify(labels)}
+          hidden={index !== 0}
+          style={`--piece-selection-filter: url(#light-maze-outline-${encodeURIComponent(puzzle.id)}); --piece-hover-filter: url(#light-maze-hover-${encodeURIComponent(puzzle.id)});`}
+        >
+          <svg
+            class="light-maze-puzzle__filters"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <defs>
+              <filter
+                id={`light-maze-hover-${encodeURIComponent(puzzle.id)}`}
+                color-interpolation-filters="sRGB"
+              >
+                <feFlood
+                  class="light-maze-puzzle__hover-color"
+                  flood-opacity="0.1"
+                />
+                <feComposite operator="in" in2="SourceAlpha" />
+                <feMerge>
+                  <feMergeNode in="SourceGraphic" />
+                  <feMergeNode />
+                </feMerge>
+              </filter>
+              <filter
+                id={`light-maze-outline-${encodeURIComponent(puzzle.id)}`}
+                x="-25%"
+                y="-25%"
+                width="150%"
+                height="150%"
+                color-interpolation-filters="sRGB"
+              >
+                <feMorphology in="SourceAlpha" operator="dilate" radius="2" />
+                <feGaussianBlur stdDeviation="0.5" result="outline" />
+                <feFlood class="light-maze-puzzle__ring-color" />
+                <feComposite operator="in" in2="outline" />
+                <feMerge>
+                  <feMergeNode />
+                  <feMergeNode in="SourceGraphic" />
+                </feMerge>
+              </filter>
+            </defs>
+          </svg>
+          <PuzzleGrid
+            class="light-maze-puzzle__board"
+            label={puzzle.label}
+            rows={puzzle.rows}
+            columns={puzzle.columns}
+          >
+            {Array.from(
+              { length: puzzle.rows * puzzle.columns },
+              (_, cellIndex) => {
+                const row = Math.floor(cellIndex / puzzle.columns);
+                const column = cellIndex % puzzle.columns;
+                const {
+                  disabled: blocked,
+                  target,
+                  lit,
+                  activator,
+                  consumed,
+                  removableWall,
+                  releasedWall,
+                  label: cellLabel,
+                } = presentLightMazeCell(puzzle, mechanism, labels, {
+                  row,
+                  column,
+                });
+                return (
+                  <button
+                    type="button"
+                    class="puzzle-grid__cell light-maze-puzzle__cell"
+                    disabled={blocked}
+                    tabindex={-1}
+                    aria-label={cellLabel}
+                    data-puzzle-cell
+                    data-puzzle-cell-disabled={blocked ? '' : undefined}
+                    data-light-maze-cell
+                    data-light-maze-lit={lit ? '' : undefined}
+                    data-light-maze-target={target ? '' : undefined}
+                    data-light-maze-wall={removableWall ? '' : undefined}
+                    data-light-maze-wall-released={
+                      releasedWall ? '' : undefined
+                    }
+                    data-light-maze-activator={activator ? '' : undefined}
+                    data-light-maze-activator-consumed={
+                      consumed ? '' : undefined
+                    }
+                    data-cell-row={row}
+                    data-cell-column={column}
+                    data-cell-label={cellLabel}
+                    style={`--cell-row: ${row + 1}; --cell-column: ${column + 1};`}
+                  >
+                    {activator && media.mechanism && (
+                      <span
+                        class="light-maze-puzzle__activator"
+                        aria-hidden="true"
+                      >
+                        <span data-activator-inactive>
+                          <Media
+                            media={media.mechanism.activatorInactive}
+                            size="fill"
+                          />
+                        </span>
+                        <span data-activator-active>
+                          <Media
+                            media={media.mechanism.activatorActive}
+                            size="fill"
+                          />
+                        </span>
+                      </span>
+                    )}
+                    {removableWall && (
+                      <span
+                        class="light-maze-puzzle__wall-fill"
+                        data-wall-fill
+                        aria-hidden="true"
+                      >
+                        <svg
+                          class="light-maze-puzzle__wall-cracks"
+                          viewBox="0 0 100 100"
+                          focusable="false"
+                        >
+                          <path d="M29 0L34 17L27 29L40 39L37 56M27 29L15 34L9 46" />
+                          <path d="M100 31L82 37L78 49L63 55L58 69M78 49L85 59L83 70" />
+                          <path d="M24 100L32 84L29 75L43 67M32 84L47 89" />
+                        </svg>
+                      </span>
+                    )}
+                  </button>
+                );
+              },
+            )}
+            {(['walker', 'light'] as const).map((piece) => (
+              <button
+                type="button"
+                class="light-maze-puzzle__piece"
+                aria-label={labels[piece]}
+                aria-pressed="false"
+                data-light-maze-piece={piece}
+                style={`--piece-row: ${initial[piece].row + 1}; --piece-column: ${initial[piece].column + 1};`}
+              >
+                <span class="light-maze-puzzle__piece-media" aria-hidden="true">
+                  <Media media={media[piece]} size="fill" />
+                </span>
+              </button>
+            ))}
+          </PuzzleGrid>
+        </div>
+      );
+    })
+  }
+</section>
+
+<script>
+  import { initLightMazePuzzle } from './lightMazePuzzleController';
+  for (const root of document.querySelectorAll('[data-light-maze-puzzle]')) {
+    if (root instanceof HTMLElement) initLightMazePuzzle(root);
+  }
+</script>

package/src/patterns/LightMazePuzzle/LightMazePuzzle.css

@@ -0,0 +1,189 @@
+.light-maze-puzzle,
+.light-maze-puzzle__instance {
+  display: grid;
+  min-inline-size: 0;
+}
+
+.light-maze-puzzle__instance[hidden] {
+  display: none;
+}
+
+.light-maze-puzzle__filters {
+  position: absolute;
+  inline-size: 0;
+  block-size: 0;
+  pointer-events: none;
+}
+
+.light-maze-puzzle__ring-color {
+  flood-color: var(--nox-source-tone-info);
+}
+.light-maze-puzzle__hover-color {
+  flood-color: var(--nox-tone-color);
+}
+
+.light-maze-puzzle__board {
+  isolation: isolate;
+  touch-action: manipulation;
+}
+
+.light-maze-puzzle__cell {
+  appearance: none;
+}
+
+.light-maze-puzzle__activator {
+  position: absolute;
+  inset: 18%;
+  display: grid;
+  pointer-events: none;
+}
+
+.light-maze-puzzle__activator > span {
+  display: grid;
+  grid-area: 1 / 1;
+}
+
+.light-maze-puzzle__cell:not([data-light-maze-activator-consumed])
+  [data-activator-active],
+.light-maze-puzzle__cell[data-light-maze-activator-consumed]
+  [data-activator-inactive] {
+  display: none;
+}
+
+.light-maze-puzzle__wall-fill {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  border-radius: inherit;
+  overflow: hidden;
+  background: var(--nox-surface-strong);
+  pointer-events: none;
+}
+
+.light-maze-puzzle__wall-cracks {
+  position: absolute;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  fill: none;
+  stroke: var(--nox-text-muted);
+  stroke-width: 1.5;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.light-maze-puzzle__cell[data-light-maze-wall-released]:not(
+    [data-wall-removing]
+  )
+  .light-maze-puzzle__wall-fill {
+  display: none;
+}
+
+.light-maze-puzzle__cell[data-light-maze-lit]:not([data-puzzle-cell-disabled]) {
+  --puzzle-cell-base-background: color-mix(
+    in srgb,
+    var(--nox-source-tone-warning) 12%,
+    var(--nox-surface)
+  );
+}
+
+.light-maze-puzzle__cell[data-light-maze-target] {
+  --puzzle-cell-base-border: var(--nox-source-tone-success);
+  border-style: dashed;
+}
+
+.light-maze-puzzle__cell[data-light-maze-destination] {
+  --puzzle-cell-ring-width: var(--nox-focus-ring-width);
+  --puzzle-cell-ring-color: var(--nox-source-tone-info);
+  z-index: 3;
+  overflow: visible;
+}
+
+.light-maze-puzzle__piece {
+  position: relative;
+  z-index: 4;
+  display: grid;
+  grid-row: var(--piece-row);
+  grid-column: var(--piece-column);
+  min-inline-size: 0;
+  min-block-size: 0;
+  margin: var(--nox-space-1);
+  padding: 0;
+  place-items: center;
+  border: 0;
+  border-radius: var(--nox-radius-sm);
+  background: transparent;
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+}
+
+.light-maze-puzzle__piece-media {
+  display: grid;
+  inline-size: 80%;
+  aspect-ratio: 1;
+  pointer-events: none;
+}
+
+.light-maze-puzzle__piece:focus-visible {
+  outline: none;
+}
+.light-maze-puzzle__piece:is([data-piece-selected], :focus-visible)
+  .light-maze-puzzle__piece-media {
+  filter: var(--piece-selection-filter);
+}
+
+@media (hover: hover) {
+  .light-maze-puzzle__piece:hover .light-maze-puzzle__piece-media {
+    filter: var(--piece-hover-filter);
+  }
+  .light-maze-puzzle__piece:is([data-piece-selected], :focus-visible):hover
+    .light-maze-puzzle__piece-media {
+    filter: var(--piece-hover-filter) var(--piece-selection-filter);
+  }
+}
+
+.light-maze-puzzle__piece[data-piece-dragging] {
+  z-index: 6;
+  cursor: grabbing;
+}
+.light-maze-puzzle__piece[data-piece-dragging] .light-maze-puzzle__piece-media {
+  transform: translate3d(var(--piece-drag-x, 0px), var(--piece-drag-y, 0px), 0)
+    scale(1.04);
+  will-change: transform;
+}
+.light-maze-puzzle__instance[data-puzzle-status='valid']
+  .light-maze-puzzle__piece {
+  cursor: default;
+}
+
+.light-maze-puzzle__instance[data-light-maze-transitioning]
+  .light-maze-puzzle__piece {
+  cursor: default;
+}
+
+.light-maze-puzzle__instance[data-light-maze-transitioning]
+  .light-maze-puzzle__piece
+  .light-maze-puzzle__piece-media {
+  filter: none;
+}
+
+.light-maze-puzzle__instance[data-light-maze-transitioning]
+  .light-maze-puzzle__cell[data-puzzle-cell] {
+  --puzzle-cell-ring-width: 0px;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .light-maze-puzzle__piece[data-piece-moved] {
+    animation: light-maze-puzzle-move 260ms var(--nox-motion-easing-standard);
+  }
+}
+@keyframes light-maze-puzzle-move {
+  from {
+    transform: translate3d(
+      var(--piece-move-inline-distance),
+      var(--piece-move-block-distance),
+      0
+    );
+  }
+}

package/src/patterns/LightMazePuzzle/contracts.ts

@@ -0,0 +1,75 @@
+import type { DisplayMedia } from '../../display/contracts';
+
+export type LightMazePosition = { row: number; column: number };
+export type LightMazeDirection = 'north' | 'east' | 'south' | 'west';
+export type LightMazePiece = 'walker' | 'light';
+export type LightMazePuzzleStatus = 'incomplete' | 'valid';
+
+export type LightMazePuzzleModel = {
+  id: string;
+  label: string;
+  rows: number;
+  columns: number;
+  start: LightMazePosition;
+  light: LightMazePosition;
+  target: LightMazePosition;
+  blockedCells: readonly LightMazePosition[];
+  activators?: readonly {
+    position: LightMazePosition;
+    walls: readonly LightMazePosition[];
+  }[];
+};
+
+export type LightMazeMechanism = {
+  illuminatedCells: readonly LightMazePosition[];
+  blockedCells: readonly LightMazePosition[];
+  activatedCells: readonly LightMazePosition[];
+};
+
+export type LightMazePuzzleState = {
+  walker: LightMazePosition;
+  light: LightMazePosition;
+  activated: readonly number[];
+};
+
+export type LightMazeAction = {
+  piece: LightMazePiece;
+  direction: LightMazeDirection;
+};
+
+export type LightMazeMovement = LightMazeAction & {
+  from: LightMazePosition;
+  to: LightMazePosition;
+  stoppedByWalker: boolean;
+  state: LightMazePuzzleState;
+};
+
+export type LightMazePuzzleLabels = {
+  walker: string;
+  light: string;
+  target: string;
+  blockedCell: string;
+  litCell: string;
+  darkCell: string;
+  directions: Readonly<Record<LightMazeDirection, string>>;
+  moveTemplate: string;
+  mechanism?: {
+    activatorAvailable: string;
+    activatorConsumed: string;
+    removableWall: string;
+    releasedWall: string;
+  };
+};
+
+export type LightMazePuzzleMedia = Record<LightMazePiece, DisplayMedia> & {
+  mechanism?: {
+    activatorInactive: DisplayMedia;
+    activatorActive: DisplayMedia;
+  };
+};
+
+export type LightMazePuzzleChangeDetail = {
+  kind: 'light-maze';
+  puzzleId: string;
+  state: LightMazePuzzleState;
+};

package/src/patterns/LightMazePuzzle/lightMazePuzzleController.ts

@@ -0,0 +1,684 @@
+import {
+  animatePieceMovement,
+  cancelDragFrame,
+  findDirectionalDropDestination,
+  hasLeftOriginCell,
+  renderPathStream,
+  scheduleDragFrame,
+  type PuzzleDrag,
+} from '../PuzzleGrid/movement';
+import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import { presentLightMazeCell } from './presentation';
+import {
+  setPuzzleGridCellState,
+  setPuzzleGridState,
+} from '../PuzzleGrid/state';
+import type {
+  LightMazeDirection,
+  LightMazePiece,
+  LightMazePosition,
+  LightMazePuzzleChangeDetail,
+  LightMazePuzzleLabels,
+  LightMazePuzzleModel,
+  LightMazePuzzleState,
+  LightMazePuzzleStatus,
+} from './contracts';
+import {
+  createLightMazePuzzleState,
+  evaluateLightMazeMechanism,
+  getLightMazeMoves,
+  isLightMazePuzzleComplete,
+  simulateLightMazeMove,
+} from './simulation';
+
+type Panel = {
+  element: HTMLElement;
+  board: HTMLElement;
+  model: LightMazePuzzleModel;
+  labels: LightMazePuzzleLabels;
+  state: LightMazePuzzleState;
+};
+type Instance = {
+  panels: Panel[];
+  activeIndex: number;
+  selected: LightMazePiece | null;
+  motion: AbortController | null;
+  drag: PuzzleDrag | null;
+  ignoreClick: boolean;
+  clickTimer: number | null;
+  controller: AbortController;
+  dismiss: () => void;
+};
+
+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;
+  const panels = [
+    ...root.querySelectorAll<HTMLElement>('[data-light-maze-model]'),
+  ].map((element) => {
+    const model = JSON.parse(
+      element.dataset.lightMazeModel!,
+    ) as LightMazePuzzleModel;
+    return {
+      element,
+      board: element.querySelector<HTMLElement>('[data-puzzle-grid]')!,
+      model,
+      labels: JSON.parse(
+        element.dataset.lightMazeLabels!,
+      ) as LightMazePuzzleLabels,
+      state: createLightMazePuzzleState(model),
+    };
+  });
+  if (!panels.length) return;
+  const controller = new AbortController();
+  const instance: Instance = {
+    panels,
+    activeIndex: 0,
+    selected: null,
+    motion: null,
+    drag: null,
+    ignoreClick: false,
+    clickTimer: null,
+    controller,
+    dismiss: () => undefined,
+  };
+  instances.set(root, instance);
+  instance.dismiss = initPuzzleSelectionDismissal(root, {
+    dismiss: () => selectPiece(root, null),
+    isSelectionTarget: (target) => {
+      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]',
+          ),
+        )
+      );
+    },
+  });
+  const options = { signal: controller.signal };
+  root.addEventListener(
+    'click',
+    (event) => {
+      if (!(event.target instanceof Element)) return;
+      if (instance.motion) {
+        event.preventDefault();
+        return;
+      }
+      if (instance.ignoreClick && event.detail !== 0) {
+        instance.ignoreClick = false;
+        event.preventDefault();
+        return;
+      }
+      instance.ignoreClick = false;
+      const piece = event.target.closest<HTMLButtonElement>(
+        '[data-light-maze-piece]',
+      );
+      if (piece) {
+        const id = piece.dataset.lightMazePiece as LightMazePiece;
+        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,
+        );
+      } 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) => {
+      if (instance.motion) {
+        event.preventDefault();
+        clearClickTimer(instance);
+        instance.ignoreClick = true;
+        return;
+      }
+      instance.ignoreClick = false;
+      if (
+        !event.isPrimary ||
+        event.button !== 0 ||
+        instance.drag ||
+        active(instance).element.dataset.puzzleStatus === 'valid'
+      )
+        return;
+      if (!(event.target instanceof Element)) return;
+      const element = event.target.closest<HTMLButtonElement>(
+        '[data-light-maze-piece]',
+      );
+      if (!element) return;
+      const pieceId = element.dataset.lightMazePiece as LightMazePiece;
+      const origin = findCell(
+        active(instance),
+        active(instance).state[pieceId],
+      );
+      if (!origin) return;
+      const bounds = element.getBoundingClientRect();
+      element.setPointerCapture(event.pointerId);
+      instance.drag = {
+        pointerId: event.pointerId,
+        pieceId,
+        startX: event.clientX,
+        startY: event.clientY,
+        currentX: event.clientX,
+        currentY: event.clientY,
+        frameId: null,
+        element,
+        originCellBounds: origin.getBoundingClientRect(),
+        originCenterX: (bounds.left + bounds.right) / 2,
+        originCenterY: (bounds.top + bounds.bottom) / 2,
+        destinations: null,
+        moved: false,
+      };
+    },
+    options,
+  );
+
+  root.addEventListener(
+    'pointermove',
+    (event) => {
+      const drag = instance.drag;
+      if (!drag || drag.pointerId !== event.pointerId) return;
+      if (!drag.moved) {
+        if (
+          Math.hypot(event.clientX - drag.startX, event.clientY - drag.startY) <
+          12
+        )
+          return;
+        drag.moved = true;
+        drag.element.setAttribute('data-piece-dragging', '');
+        selectPiece(root, drag.pieceId as LightMazePiece);
+        drag.destinations = [
+          ...active(instance).element.querySelectorAll<HTMLButtonElement>(
+            '[data-light-maze-destination]',
+          ),
+        ];
+      }
+      event.preventDefault();
+      drag.currentX = event.clientX;
+      drag.currentY = event.clientY;
+      scheduleDragFrame(drag, () => instance.drag === drag);
+    },
+    options,
+  );
+  root.addEventListener(
+    'pointerup',
+    (event) => finishDrag(root, event, true),
+    options,
+  );
+  root.addEventListener(
+    'pointercancel',
+    (event) => finishDrag(root, event, false),
+    options,
+  );
+  root.addEventListener(
+    'lostpointercapture',
+    (event) => finishDrag(root, event, false),
+    options,
+  );
+  render(root);
+}
+
+export function selectLightMazePuzzle(root: HTMLElement, index: number): void {
+  initLightMazePuzzle(root);
+  const instance = instances.get(root);
+  if (!instance) return;
+  cancelMotion(instance);
+  cancelDrag(instance);
+  instance.activeIndex = Math.max(
+    0,
+    Math.min(index, instance.panels.length - 1),
+  );
+  instance.panels.forEach((panel, i) => {
+    panel.element.hidden = i !== instance.activeIndex;
+  });
+  resetLightMazePuzzle(root);
+}
+
+export function resetLightMazePuzzle(root: HTMLElement): void {
+  initLightMazePuzzle(root);
+  const instance = instances.get(root);
+  if (!instance) return;
+  cancelMotion(instance);
+  cancelDrag(instance);
+  clearClickTimer(instance);
+  instance.ignoreClick = false;
+  instance.selected = null;
+  const panel = active(instance);
+  panel.state = createLightMazePuzzleState(panel.model);
+  panel.element.dataset.puzzleStatus = 'incomplete';
+  setPuzzleGridState(panel.board, null);
+  for (const piece of panel.element.querySelectorAll<HTMLElement>(
+    '[data-light-maze-piece]',
+  )) {
+    piece.getAnimations().forEach((animation) => animation.cancel());
+    piece.removeAttribute('data-piece-moved');
+  }
+  render(root);
+  emitChange(root, panel);
+}
+
+export function setLightMazePuzzleStatus(
+  root: HTMLElement,
+  puzzleId: string,
+  status: LightMazePuzzleStatus,
+): void {
+  const instance = instances.get(root);
+  const panel = instance?.panels.find(
+    (candidate) => candidate.model.id === puzzleId,
+  );
+  if (!instance || !panel) return;
+  const previous = panel.element.dataset.puzzleStatus;
+  panel.element.dataset.puzzleStatus = status;
+  setPuzzleGridState(panel.board, status === 'valid' ? 'valid' : null);
+  if (status === 'valid' && panel === active(instance)) {
+    cancelDrag(instance);
+    instance.selected = null;
+    renderSelection(root);
+  }
+  if (status === 'valid' && previous !== 'valid') {
+    root.dispatchEvent(
+      new CustomEvent('puzzle:complete', {
+        bubbles: true,
+        detail: { kind: 'light-maze', puzzleId },
+      }),
+    );
+  }
+}
+
+export function destroyLightMazePuzzle(root: HTMLElement): void {
+  const instance = instances.get(root);
+  if (!instance) return;
+  cancelMotion(instance);
+  instance.controller.abort();
+  instance.dismiss();
+  cancelDrag(instance);
+  clearClickTimer(instance);
+  for (const panel of instance.panels) {
+    clearPreviews(panel);
+    for (const piece of panel.element.querySelectorAll<HTMLElement>(
+      '[data-light-maze-piece]',
+    )) {
+      piece.getAnimations().forEach((animation) => animation.cancel());
+    }
+  }
+  instances.delete(root);
+}
+
+function active(instance: Instance): Panel {
+  return instance.panels[instance.activeIndex]!;
+}
+
+function selectPiece(root: HTMLElement, piece: LightMazePiece | null): void {
+  const instance = instances.get(root);
+  if (
+    !instance ||
+    instance.motion ||
+    active(instance).element.dataset.puzzleStatus === 'valid'
+  )
+    return;
+  instance.selected = piece;
+  renderSelection(root);
+}
+
+async function move(
+  root: HTMLElement,
+  piece: LightMazePiece,
+  direction: LightMazeDirection,
+  retainSelection = true,
+): Promise<void> {
+  const instance = instances.get(root);
+  if (!instance || instance.motion) return;
+  const panel = active(instance);
+  if (panel.element.dataset.puzzleStatus === 'valid') return;
+  const movement = simulateLightMazeMove(panel.model, panel.state, {
+    piece,
+    direction,
+  });
+  if (!movement) return;
+  const element = panel.element.querySelector<HTMLButtonElement>(
+    `[data-light-maze-piece="${piece}"]`,
+  )!;
+  const bounds = element.getBoundingClientRect();
+  element.getAnimations().forEach((animation) => animation.cancel());
+  element.removeAttribute('data-piece-moved');
+  const walls = (panel.model.activators ?? []).flatMap((activator, index) =>
+    movement.state.activated.includes(index) &&
+    !panel.state.activated.includes(index)
+      ? activator.walls
+      : [],
+  );
+  const motion =
+    walls.length && !reducedMotion() ? new AbortController() : null;
+  if (motion) {
+    instance.motion = motion;
+    panel.element.setAttribute('data-light-maze-transitioning', '');
+    panel.board.setAttribute('aria-busy', 'true');
+  }
+  panel.state = motion
+    ? { ...movement.state, activated: panel.state.activated }
+    : movement.state;
+  instance.selected =
+    (retainSelection || walls.length > 0) &&
+    !isLightMazePuzzleComplete(panel.model, panel.state)
+      ? piece
+      : null;
+  render(root);
+  animatePieceMovement(element, bounds);
+  if (!motion) {
+    emitChange(root, panel);
+    return;
+  }
+  try {
+    if (!(await waitForAnimations(element.getAnimations(), motion.signal)))
+      return;
+    const cells = walls.flatMap((position) => {
+      const cell = findCell(panel, position);
+      return cell ? [cell] : [];
+    });
+    for (const cell of cells) cell.setAttribute('data-wall-removing', '');
+    panel.state = movement.state;
+    render(root);
+    if (!reducedMotion()) await animateWallRemoval(cells, motion.signal);
+  } finally {
+    if (instance.motion === motion) {
+      instance.motion = null;
+      clearMotionPresentation(panel);
+      if (!motion.signal.aborted) {
+        panel.state = movement.state;
+        render(root);
+        emitChange(root, panel);
+      }
+    }
+  }
+}
+
+function reducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function animateWallRemoval(
+  cells: HTMLButtonElement[],
+  signal: AbortSignal,
+): Promise<boolean> {
+  const timing: KeyframeAnimationOptions = {
+    duration: 590,
+    easing: 'ease-out',
+    fill: 'forwards',
+  };
+  const animations = cells.flatMap((cell) => {
+    const fill = cell.querySelector<HTMLElement>('[data-wall-fill]');
+    if (!fill) return [];
+    return [fill.animate([{ opacity: 1 }, { opacity: 0 }], timing)];
+  });
+  return waitForAnimations(animations, signal);
+}
+
+async function waitForAnimations(
+  animations: Animation[],
+  signal: AbortSignal,
+): Promise<boolean> {
+  const cancel = (): void =>
+    animations.forEach((animation) => animation.cancel());
+  if (signal.aborted) {
+    cancel();
+    return false;
+  }
+  signal.addEventListener('abort', cancel, { once: true });
+  try {
+    await Promise.all(
+      animations.map((animation) => animation.finished.catch(() => undefined)),
+    );
+    return !signal.aborted;
+  } finally {
+    signal.removeEventListener('abort', cancel);
+    cancel();
+  }
+}
+
+function clearMotionPresentation(panel: Panel): void {
+  panel.element.removeAttribute('data-light-maze-transitioning');
+  panel.board.removeAttribute('aria-busy');
+  for (const cell of panel.element.querySelectorAll('[data-wall-removing]'))
+    cell.removeAttribute('data-wall-removing');
+  for (const piece of panel.element.querySelectorAll('[data-light-maze-piece]'))
+    piece.removeAttribute('aria-disabled');
+}
+
+function cancelMotion(instance: Instance): void {
+  instance.motion?.abort();
+  instance.motion = null;
+  for (const panel of instance.panels) clearMotionPresentation(panel);
+}
+
+function render(root: HTMLElement): void {
+  const instance = instances.get(root);
+  if (!instance) return;
+  const panel = active(instance);
+  clearPreviews(panel);
+  const mechanism = evaluateLightMazeMechanism(panel.model, panel.state);
+  const lit = new Set(
+    mechanism.illuminatedCells.map((p) => `${p.row}:${p.column}`),
+  );
+  for (const cell of panel.element.querySelectorAll<HTMLButtonElement>(
+    '[data-light-maze-cell]',
+  )) {
+    const display = presentLightMazeCell(panel.model, mechanism, panel.labels, {
+      row: Number(cell.dataset.cellRow),
+      column: Number(cell.dataset.cellColumn),
+    });
+    cell.disabled = display.disabled;
+    cell.toggleAttribute('data-puzzle-cell-disabled', cell.disabled);
+    cell.toggleAttribute(
+      'data-light-maze-activator-consumed',
+      display.consumed,
+    );
+    cell.toggleAttribute('data-light-maze-lit', display.lit);
+    cell.toggleAttribute('data-light-maze-wall-released', display.releasedWall);
+    cell.dataset.cellLabel = display.label;
+    cell.setAttribute('aria-label', display.label);
+    if (display.target)
+      setPuzzleGridCellState(
+        cell,
+        isLightMazePuzzleComplete(panel.model, panel.state) ? 'valid' : null,
+      );
+  }
+  for (const piece of ['walker', 'light'] as const) {
+    const element = panel.element.querySelector<HTMLElement>(
+      `[data-light-maze-piece="${piece}"]`,
+    )!;
+    const position = panel.state[piece];
+    element.style.setProperty('--piece-row', String(position.row + 1));
+    element.style.setProperty('--piece-column', String(position.column + 1));
+    element.setAttribute(
+      'aria-label',
+      `${panel.labels[piece]} — ${lit.has(`${position.row}:${position.column}`) ? panel.labels.litCell : panel.labels.darkCell}`,
+    );
+  }
+  renderSelection(root);
+}
+
+function renderSelection(root: HTMLElement): void {
+  const instance = instances.get(root);
+  if (!instance) return;
+  const panel = active(instance);
+  clearPreviews(panel);
+  for (const piece of panel.element.querySelectorAll<HTMLElement>(
+    '[data-light-maze-piece]',
+  )) {
+    const selected =
+      !instance.motion && piece.dataset.lightMazePiece === instance.selected;
+    piece.toggleAttribute('data-piece-selected', selected);
+    piece.setAttribute('aria-pressed', String(selected));
+    if (instance.motion) piece.setAttribute('aria-disabled', 'true');
+    else piece.removeAttribute('aria-disabled');
+  }
+  if (
+    instance.motion ||
+    !instance.selected ||
+    panel.element.dataset.puzzleStatus === 'valid'
+  )
+    return;
+  for (const movement of getLightMazeMoves(panel.model, panel.state)) {
+    if (movement.piece !== instance.selected) continue;
+    const destination = findCell(panel, movement.to);
+    if (!destination) continue;
+    renderPathStream(panel.board, movement);
+    destination.tabIndex = 0;
+    destination.setAttribute('data-light-maze-destination', '');
+    destination.setAttribute('data-puzzle-cell-interactive', '');
+    destination.dataset.destinationPiece = movement.piece;
+    destination.dataset.destinationDirection = movement.direction;
+    const label = panel.labels.moveTemplate
+      .replaceAll('{piece}', panel.labels[movement.piece])
+      .replaceAll('{direction}', panel.labels.directions[movement.direction]);
+    destination.setAttribute(
+      'aria-label',
+      `${label} — ${destination.dataset.cellLabel}`,
+    );
+  }
+}
+
+function clearPreviews(panel: Panel): void {
+  for (const stream of panel.element.querySelectorAll(
+    '[data-puzzle-path-stream]',
+  ))
+    stream.remove();
+  for (const cell of panel.element.querySelectorAll<HTMLButtonElement>(
+    '[data-light-maze-destination]',
+  )) {
+    cell.tabIndex = -1;
+    for (const attribute of [
+      'data-light-maze-destination',
+      'data-puzzle-cell-interactive',
+      'data-destination-piece',
+      'data-destination-direction',
+    ])
+      cell.removeAttribute(attribute);
+    cell.setAttribute('aria-label', cell.dataset.cellLabel ?? '');
+  }
+}
+
+function findCell(
+  panel: Panel,
+  position: LightMazePosition,
+): HTMLButtonElement | null {
+  return panel.element.querySelector(
+    `[data-light-maze-cell][data-cell-row="${position.row}"][data-cell-column="${position.column}"]`,
+  );
+}
+
+function cancelDrag(instance: Instance): void {
+  const drag = instance.drag;
+  if (!drag) return;
+  instance.drag = 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(drag.pointerId))
+    drag.element.releasePointerCapture(drag.pointerId);
+}
+
+function finishDrag(
+  root: HTMLElement,
+  event: PointerEvent,
+  commit: boolean,
+): void {
+  const instance = instances.get(root);
+  const drag = instance?.drag;
+  if (!instance || !drag || event.pointerId !== drag.pointerId) return;
+  const dx = event.clientX - drag.startX,
+    dy = event.clientY - drag.startY;
+  const destination =
+    commit && drag.moved && hasLeftOriginCell(drag, dx, dy)
+      ? findDirectionalDropDestination(drag, dx, dy)
+      : null;
+  cancelDrag(instance);
+  if (!drag.moved) return;
+  if (commit) {
+    clearClickTimer(instance);
+    instance.ignoreClick = true;
+    instance.clickTimer = window.setTimeout(() => {
+      instance.ignoreClick = false;
+      instance.clickTimer = null;
+    }, 0);
+    if (destination) {
+      void move(
+        root,
+        drag.pieceId as LightMazePiece,
+        destination.dataset.destinationDirection as LightMazeDirection,
+        false,
+      );
+      return;
+    }
+  }
+  selectPiece(root, null);
+}
+
+function clearClickTimer(instance: Instance): void {
+  if (instance.clickTimer !== null) window.clearTimeout(instance.clickTimer);
+  instance.clickTimer = null;
+}
+
+function emitChange(root: HTMLElement, panel: Panel): void {
+  const detail: LightMazePuzzleChangeDetail = {
+    kind: 'light-maze',
+    puzzleId: panel.model.id,
+    state: {
+      walker: { ...panel.state.walker },
+      light: { ...panel.state.light },
+      activated: [...panel.state.activated],
+    },
+  };
+  root.dispatchEvent(
+    new CustomEvent('puzzle:change', { bubbles: true, detail }),
+  );
+}

package/src/patterns/LightMazePuzzle/presentation.ts

@@ -0,0 +1,55 @@
+import type {
+  LightMazeMechanism,
+  LightMazePosition,
+  LightMazePuzzleLabels,
+  LightMazePuzzleModel,
+} from './contracts';
+
+export function presentLightMazeCell(
+  puzzle: LightMazePuzzleModel,
+  mechanism: LightMazeMechanism,
+  labels: LightMazePuzzleLabels,
+  position: LightMazePosition,
+) {
+  const matches = (cell: LightMazePosition): boolean =>
+    cell.row === position.row && cell.column === position.column;
+  const activator =
+    puzzle.activators?.some((entry) => matches(entry.position)) ?? false;
+  const consumed = mechanism.activatedCells.some(matches);
+  const disabled = mechanism.blockedCells.some(matches);
+  const removableWall =
+    puzzle.activators?.some((entry) => entry.walls.some(matches)) ?? false;
+  const releasedWall = removableWall && !disabled;
+  const target = matches(puzzle.target);
+  const lit = mechanism.illuminatedCells.some(matches);
+  if ((activator || removableWall) && !labels.mechanism)
+    throw new Error('Light maze mechanisms require accessible labels.');
+  let activationLabel = '';
+  if (activator) {
+    activationLabel = consumed
+      ? labels.mechanism!.activatorConsumed
+      : labels.mechanism!.activatorAvailable;
+  }
+  const label = disabled
+    ? removableWall
+      ? labels.mechanism!.removableWall
+      : labels.blockedCell
+    : [
+        target ? labels.target : '',
+        activationLabel,
+        releasedWall ? labels.mechanism!.releasedWall : '',
+        lit ? labels.litCell : labels.darkCell,
+      ]
+        .filter(Boolean)
+        .join(' — ');
+  return {
+    disabled,
+    target,
+    lit,
+    activator,
+    consumed,
+    removableWall,
+    releasedWall,
+    label,
+  };
+}

package/src/patterns/LightMazePuzzle/simulation.ts

@@ -0,0 +1,164 @@
+import type {
+  LightMazeAction,
+  LightMazeDirection,
+  LightMazeMovement,
+  LightMazeMechanism,
+  LightMazePosition,
+  LightMazePuzzleModel,
+  LightMazePuzzleState,
+} from './contracts';
+
+const deltas = {
+  north: [-1, 0],
+  east: [0, 1],
+  south: [1, 0],
+  west: [0, -1],
+} as const;
+
+function same(a: LightMazePosition, b: LightMazePosition): boolean {
+  return a.row === b.row && a.column === b.column;
+}
+
+function free(
+  puzzle: LightMazePuzzleModel,
+  position: LightMazePosition,
+  blockedCells: readonly LightMazePosition[],
+): boolean {
+  return (
+    position.row >= 0 &&
+    position.row < puzzle.rows &&
+    position.column >= 0 &&
+    position.column < puzzle.columns &&
+    !blockedCells.some((cell) => same(cell, position))
+  );
+}
+
+export function createLightMazePuzzleState(
+  puzzle: LightMazePuzzleModel,
+): LightMazePuzzleState {
+  return {
+    walker: { ...puzzle.start },
+    light: { ...puzzle.light },
+    activated: [],
+  };
+}
+
+function blockedCells(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+): LightMazePosition[] {
+  return [
+    ...puzzle.blockedCells,
+    ...(puzzle.activators ?? []).flatMap((activator, index) =>
+      state.activated.includes(index) ? [] : activator.walls,
+    ),
+  ];
+}
+
+export function isLightMazePuzzleComplete(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+): boolean {
+  return same(state.walker, puzzle.target);
+}
+
+export function getLightMazeIllumination(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+): LightMazePosition[] {
+  const cells = [{ ...state.light }];
+  const blocked = blockedCells(puzzle, state);
+  for (const [dr, dc] of Object.values(deltas)) {
+    for (let distance = 1; distance <= 2; distance += 1) {
+      const cell = {
+        row: state.light.row + dr * distance,
+        column: state.light.column + dc * distance,
+      };
+      if (!free(puzzle, cell, blocked)) break;
+      cells.push(cell);
+    }
+  }
+  return cells;
+}
+
+export function evaluateLightMazeMechanism(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+): LightMazeMechanism {
+  const illuminatedCells = getLightMazeIllumination(puzzle, state);
+  return {
+    illuminatedCells,
+    blockedCells: blockedCells(puzzle, state),
+    activatedCells: (puzzle.activators ?? []).flatMap((activator, index) =>
+      state.activated.includes(index) ? [activator.position] : [],
+    ),
+  };
+}
+
+export function simulateLightMazeMove(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+  action: LightMazeAction,
+): LightMazeMovement | null {
+  if (isLightMazePuzzleComplete(puzzle, state)) return null;
+  const mechanism = evaluateLightMazeMechanism(puzzle, state);
+  const traversable = (position: LightMazePosition): boolean =>
+    free(puzzle, position, mechanism.blockedCells);
+  const [dr, dc] = deltas[action.direction];
+  const from = state[action.piece];
+  let to = { ...from };
+  let stoppedByWalker = false;
+  const crossed: LightMazePosition[] = [];
+  if (action.piece === 'walker') {
+    to = { row: from.row + dr, column: from.column + dc };
+    if (
+      !traversable(to) ||
+      same(to, state.light) ||
+      puzzle.activators?.some((activator) => same(activator.position, to)) ||
+      !mechanism.illuminatedCells.some((cell) => same(cell, to))
+    )
+      return null;
+  } else {
+    while (true) {
+      const next = { row: to.row + dr, column: to.column + dc };
+      if (!traversable(next)) break;
+      if (same(next, state.walker)) {
+        stoppedByWalker = true;
+        break;
+      }
+      to = next;
+      crossed.push(next);
+    }
+    if (same(from, to)) return null;
+  }
+  const activated = (puzzle.activators ?? []).flatMap((activator, index) =>
+    state.activated.includes(index) ||
+    crossed.some((position) => same(activator.position, position))
+      ? [index]
+      : [],
+  );
+  return {
+    ...action,
+    from: { ...from },
+    to,
+    stoppedByWalker,
+    state: {
+      walker: { ...state.walker },
+      light: { ...state.light },
+      [action.piece]: to,
+      activated,
+    },
+  };
+}
+
+export function getLightMazeMoves(
+  puzzle: LightMazePuzzleModel,
+  state: LightMazePuzzleState,
+): LightMazeMovement[] {
+  return (['walker', 'light'] as const).flatMap((piece) =>
+    (Object.keys(deltas) as LightMazeDirection[]).flatMap((direction) => {
+      const move = simulateLightMazeMove(puzzle, state, { piece, direction });
+      return move ? [move] : [];
+    }),
+  );
+}

package/src/patterns/index.ts

@@ -11,6 +11,10 @@ export { default as ModalClose } from './Modal/ModalClose.astro';
 export { default as ModalOpen } from './Modal/ModalOpen.astro';
 export { default as PuzzleGrid } from './PuzzleGrid/PuzzleGrid.astro';
 export { default as SlidingPuzzle } from './SlidingPuzzle/SlidingPuzzle.astro';
+export { default as LightMazePuzzle } from './LightMazePuzzle/LightMazePuzzle.astro';
+export * from './LightMazePuzzle/contracts';
+export * from './LightMazePuzzle/simulation';
+export * from './LightMazePuzzle/lightMazePuzzleController';
 export * from './SlidingPuzzle/contracts';
 export * from './SlidingPuzzle/simulation';
 export * from './SlidingPuzzle/slidingPuzzleController';

package/src/styles/style.css

@@ -65,6 +65,7 @@
 @import '../patterns/PuzzleGrid/PuzzleGrid.css' layer(patterns);
 @import '../patterns/PuzzleGrid/movement.css' layer(patterns);
 @import '../patterns/SlidingPuzzle/SlidingPuzzle.css' layer(patterns);
+@import '../patterns/LightMazePuzzle/LightMazePuzzle.css' layer(patterns);
 @import '../patterns/CircuitPuzzle/CircuitPuzzle.css' layer(patterns);
 @import '../patterns/Combobox/Combobox.css' layer(patterns);
 @import '../patterns/Dropdown/Dropdown.css' layer(patterns);