BUILD: repo structure normalization (01) staged engine move

- created src/engine/ directory
- copied engine/** to src/engine/** (1:1 mirror)
- no changes to original engine/ directory
- no import path changes
- no engine API changes

notes:
- staged move to allow safe validation before cutover
- follow-up PR will switch imports to src/engine/

next:
- validate mirror integrity
- proceed to import normalization PR

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,2 +1,33 @@
-# No Codex command in this APPLY bundle
-# Code is already reported complete and validated.
+MODEL: GPT-5.3-codex
+REASONING: high
+
+CONSTRAINTS:
+- DO NOT scan repo
+- ONLY modify listed targets
+- NO engine API changes
+- NO new files unless explicitly listed
+
+TASK:
+Staged, non-destructive engine move.
+
+1) Create directory:
+   src/engine/
+
+2) Copy ALL files and folders from:
+   engine/**
+
+   to:
+   src/engine/**
+
+3) Preserve relative structure exactly (1:1 mirror).
+
+RULES:
+- Do NOT delete or modify anything under engine/
+- Do NOT change any import paths
+- Do NOT edit file contents
+- Do NOT create files outside src/engine/**
+- If any ambiguity, STOP and report
+
+OUTPUT:
+Create ZIP at:
+<project folder>/tmp/BUILD_PR_REPO_STRUCTURE_NORMALIZATION_01_ENGINE_MOVE.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,10 +1,15 @@
-APPLY: accept clean Level 11.7 final promotion gate implementation
+BUILD: repo structure normalization (01) staged engine move
 
-- accepted single-file inline promotion gate change in createWorldGameStateSystem.js
-- no new files created
+- created src/engine/ directory
+- copied engine/** to src/engine/** (1:1 mirror)
+- no changes to original engine/ directory
+- no import path changes
 - no engine API changes
-- no public API expansion
-- validation passed for handoff, score, and promotion-gate checks
+
+notes:
+- staged move to allow safe validation before cutover
+- follow-up PR will switch imports to src/engine/
 
 next:
-- continue with roadmap item #1 Repo Structure Normalization after current lane is closed
+- validate mirror integrity
+- proceed to import normalization PR

docs/dev/reports/change_summary.txt

@@ -1,6 +1,5 @@
 CHANGE SUMMARY
 
-- accepted the clean, compliant Level 11.7 single-file retry
-- confirmed no new files were created
-- confirmed no API expansion occurred
-- confirmed validation passed for handoff, score, and promotion-gate checks
+- established src/engine/ as target structure
+- mirrored existing engine/** into src/engine/**
+- performed non-destructive staged move

docs/dev/reports/file_tree.txt

@@ -1,12 +1,8 @@
-FILE TREE
+FILE TREE (expected after BUILD)
 
-docs/
-├── pr/
-│   └── APPLY_PR_LEVEL_11_7_FINAL_PROMOTION_GATE.md
-└── dev/
-    ├── commit_comment.txt
-    ├── codex_commands.md
-    └── reports/
-        ├── change_summary.txt
-        ├── file_tree.txt
-        └── validation_checklist.txt
+src/
+└── engine/
+    └── (mirror of engine/**)
+
+engine/
+└── (unchanged)

docs/dev/reports/validation_checklist.txt

@@ -1,13 +1,7 @@
 VALIDATION CHECKLIST
 
-[x] Single approved file modified
-[x] No new source files created
-[x] No other files modified
-[x] No engine API changes
-[x] No public API expansion
-[x] WorldGameStateAuthoritativeHandoff passed
-[x] WorldGameStateAuthoritativeScore passed
-[x] Stable window promotion check passed
-[x] Divergence block check passed
-[x] Rollback abort check passed
-[x] Ready to commit
+[ ] src/engine/ exists
+[ ] all files from engine/** exist under src/engine/** (1:1)
+[ ] original engine/** remains unchanged
+[ ] no import paths changed
+[ ] application runs as before

docs/pr/BUILD_PR_REPO_STRUCTURE_NORMALIZATION_01_ENGINE_MOVE.md

@@ -0,0 +1,30 @@
+# BUILD PR — Repo Structure Normalization (01) Engine Move (Staged, Non-Destructive)
+
+## Scope
+Create `src/engine/` and copy the contents of the existing `engine/` directory into it.
+DO NOT delete or modify the original `engine/` directory in this PR.
+
+## Rationale
+- Establish target structure without breaking existing imports
+- Allow parallel validation before any cutover
+
+## Constraints
+- DO NOT scan repo
+- ONLY modify listed targets
+- NO engine API changes
+- NO new files unless explicitly listed (only files created under `src/engine/**` that mirror `engine/**`)
+- Do NOT change any import paths in this PR
+
+## Targets
+- Create directory: `src/engine/`
+- Copy: `engine/**` → `src/engine/**` (1:1 mirror)
+
+## Non-Goals
+- No deletions
+- No refactors
+- No import updates
+- No behavior changes
+
+## Validation
+- Project still runs using existing `engine/` paths
+- `src/engine/` contains a complete mirror of `engine/`

src/engine/.keep

@@ -0,0 +1,23 @@
+# Engine
+
+Shared framework used by `samples/` and `games/`. All modules are ES modules and browser-ready; no build step is required.
+
+## Import Policy
+- Bootstrap via `engine/core/Engine.js`.
+- For subsystems, prefer the public barrel `engine/<subsystem>/index.js` when it exists.
+
+## Key Areas
+- `core/` timing, orchestration, metrics
+- `scenes/` scene lifecycle and transitions
+- `render/` canvas renderers and helpers
+- `input/` keyboard, mouse, gamepad, action mapping
+- `audio/` audio services and backends
+- `ui/` shared hub and overlay components
+- `world/`, `ecs/`, `collision/`, `vector/`, `utils/` shared math and world helpers
+- `persistence/` serialization and storage
+- `fx/` effects such as `ParticleSystem`
+- platform and pipelines: `runtime/`, `automation/`, `release/`, `security/`, `pipeline/`, `editor/`
+
+## Validation
+- Automated: `npm test` (81/81 passing as of 03/25/2026)
+- In-repo usage: numbered samples and shipped games (Asteroids, Space Duel, Space Invaders, Pacman Lite/Full AI, AI Target Dummy)

src/engine/README.md

@@ -0,0 +1,41 @@
+/*
+Toolbox Aid
+David Quesenberry
+03/22/2026
+AIStateController.js
+*/
+import { StateMachine } from '../state/index.js';
+
+export default class AIStateController {
+  constructor({ initial = 'idle', states = {} } = {}) {
+    this.states = states;
+    this.machine = new StateMachine({
+      initial,
+      states: Object.fromEntries(Object.entries(states).map(([name, definition]) => ([
+        name,
+        {
+          enter: definition.enter,
+          exit: definition.exit,
+          canTransition: definition.canTransition,
+          update: (context) => {
+            if (typeof definition.act === 'function') {
+              definition.act(context);
+            }
+
+            return typeof definition.transition === 'function'
+              ? (definition.transition(context) || null)
+              : null;
+          },
+        },
+      ]))),
+    });
+  }
+
+  update(context = {}) {
+    this.machine.update(context);
+  }
+
+  getState() {
+    return this.machine.getState();
+  }
+}

src/engine/ai/AIStateController.js

@@ -0,0 +1,77 @@
+/*
+Toolbox Aid
+David Quesenberry
+03/22/2026
+GridPathfinding.js
+*/
+function getNodeKey(x, y) {
+  return `${x},${y}`;
+}
+
+function heuristic(a, b) {
+  return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+}
+
+function isWalkable(grid, x, y) {
+  return y >= 0 && y < grid.length && x >= 0 && x < grid[y].length && grid[y][x] === 0;
+}
+
+export function findGridPath(grid, start, goal) {
+  if (!isWalkable(grid, start.x, start.y) || !isWalkable(grid, goal.x, goal.y)) {
+    return [];
+  }
+
+  const open = [{ x: start.x, y: start.y, g: 0, f: heuristic(start, goal) }];
+  const cameFrom = new Map();
+  const costSoFar = new Map([[getNodeKey(start.x, start.y), 0]]);
+
+  while (open.length > 0) {
+    open.sort((a, b) => a.f - b.f);
+    const current = open.shift();
+
+    if (current.x === goal.x && current.y === goal.y) {
+      const path = [{ x: current.x, y: current.y }];
+      let key = getNodeKey(current.x, current.y);
+
+      while (cameFrom.has(key)) {
+        const previous = cameFrom.get(key);
+        path.unshift(previous);
+        key = getNodeKey(previous.x, previous.y);
+      }
+
+      return path;
+    }
+
+    const neighbors = [
+      { x: current.x + 1, y: current.y },
+      { x: current.x - 1, y: current.y },
+      { x: current.x, y: current.y + 1 },
+      { x: current.x, y: current.y - 1 },
+    ];
+
+    neighbors.forEach((neighbor) => {
+      if (!isWalkable(grid, neighbor.x, neighbor.y)) {
+        return;
+      }
+
+      const nextCost = current.g + 1;
+      const key = getNodeKey(neighbor.x, neighbor.y);
+      const previousCost = costSoFar.get(key);
+
+      if (previousCost !== undefined && nextCost >= previousCost) {
+        return;
+      }
+
+      costSoFar.set(key, nextCost);
+      cameFrom.set(key, { x: current.x, y: current.y });
+      open.push({
+        x: neighbor.x,
+        y: neighbor.y,
+        g: nextCost,
+        f: nextCost + heuristic(neighbor, goal),
+      });
+    });
+  }
+
+  return [];
+}