From d83f2155eb4147fbd68ac9d970098517f233fae6 Mon Sep 17 00:00:00 2001
From: NoisemakerJon <139656120+Noisemaker111@users.noreply.github.com>
Date: Fri, 23 Oct 2026 22:51:03 -0400
Subject: [PATCH 1/2] A drive step can aim: moveMouse, look and aimAt move the
 real crosshair

Proved on Scrap Signal: firing at the spawn crosshair leaves the staged Foreman at 217/420, a 300px look puts the crosshair on it, and the same hold drops it to 208.
---
 .claude/skills/jgengine-verify/SKILL.md       |   1 +
 .../src/templates/captureArgs.test.ts         |  26 +++
 .../jgengine/src/templates/captureArgs.ts     |  33 ++-
 .../jgengine/src/templates/driveAim.test.ts   | 133 +++++++++++
 packages/jgengine/src/templates/driveAim.ts   | 209 ++++++++++++++++++
 packages/jgengine/src/templates/gameFiles.ts  |  21 ++
 scripts/drive-dev.ts                          |  26 +++
 7 files changed, 446 insertions(+), 3 deletions(-)
 create mode 100644 packages/jgengine/src/templates/driveAim.test.ts
 create mode 100644 packages/jgengine/src/templates/driveAim.ts

diff --git a/.claude/skills/jgengine-verify/SKILL.md b/.claude/skills/jgengine-verify/SKILL.md
index 5b92935b6..4db5b741d 100644
--- a/.claude/skills/jgengine-verify/SKILL.md
+++ b/.claude/skills/jgengine-verify/SKILL.md
@@ -41,6 +41,7 @@ Classify each acceptance claim before scheduling proof. A plan that uses screens
 - `GameHost` publishes declared `capture.probe` as `window.__jgProbe` after game initialization and staging. Reads use the live context; replacement/unmount retires the hook. An absent or throwing probe supplies no progress evidence.
 - Placeholder-vs-authored: `debug_snapshot().probes.fallbacks` reports which render seams resolved to fallbacks (green ground, primitive actors, proxy scatter) and why — a non-empty count proves content is unauthored/misconfigured rather than an intended placeholder. `probes.textureErrors` (`{ url, count }[]`) is its twin for the failure `fallbacks` cannot see: a model that resolves but whose GLB textures 404 — a non-empty list is a visibly-broken (untextured) scene, treat it exactly like a model fallback.
 - Portable `drive --click-at x,y` sends trusted native left-click input to a canvas or control in CSS viewport pixels. Steps preserve argument order; coordinates must be finite, nonnegative and strictly inside the selected device or overridden viewport (mobile DPR does not multiply them). Use the game’s visible world target; coordinate clicking does not project an entity id, run a game command directly, or advance fixed simulation time. Older project-owned `scripts/drive.mjs` keep their installed behavior; update the scaffold harness to use this option.
+- Aiming in a step file: `{ "moveMouse": [x, y] }` hovers the pointer at viewport pixels, `{ "look": [dx, dy] }` turns a pointer-locked view by that mouse movement (the step takes pointer lock on the play canvas inside a CDP user gesture, so it never fires the weapon), and `{ "aimAt": "<page expression>" }` turns until the target's `{x,y}` projection sits on the crosshair within `tolerancePx` (default 6), measuring the page's own response instead of assuming a sensitivity. A shooter proof asserts the arrival every time — a shot before the aim that leaves `capture.probe` health flat, then a shot after it that drops it — because "fired six taps" proves only that the trigger works.
 - A route a proof needs once belongs in `<game>/proofs/flows/<name>.json`, not copied into every proof: `bun run drive <game> --flow <name>` runs it, `--flows` lists each name with its step count and asserts, and `{ "flow": "<name>" }` includes it (4 levels deep, a repeated name is a cycle). A flow asserts arrival — the match started, N units present — because a flow that only clicks proves nothing. Every step prints one line and `--log <path>` writes JSONL, so a failed run names the step, the expected and actual value, and stops before the next screenshot.
 - UI-flow logic (a command/intent handler, not its pixels): drive it canvas-free with `createHeadlessRunner(...).ui.invoke("intent.name", input)`, then assert the resulting reactive state off `ctx` (store, stats, scene). No renderer, no pointer simulation — leave pixels to `shoot`; prove the logic headlessly.
 - Play itself, as a script: `bun run simulate <game> <script>` boots the game's real `PlayableGame` in-process with no browser and plays a committed `<game>/scripts/*.play.ts` through `createPlayScript`/`runPlayScript` (`@jgengine/shell/play`). Steps are tick-based (`move`, `aim`, `fire`, `use`, `wait`, `command`) plus optional `setup`/`onTick` hooks; `expect` assertions read world state twice — right after setup and on their own tick — so "the enemy lost health" and "the wave is 2" are both one line. The runner replays the shell's own frame pipeline (held movement through the walk controller, a bound action resolving to its command on press and repeat, `interact` prompts, hotbar), prints a tick timeline, names any failed assertion and exits 1; the timeline digest is the replay comparison (a fresh process with the same script and seed repeats it). Prefer this over playing for minutes to reach a wave, a boss phase, a lap or a shootout; record a clip only for what a script cannot judge (look, feel, camera).
diff --git a/packages/jgengine/src/templates/captureArgs.test.ts b/packages/jgengine/src/templates/captureArgs.test.ts
index 249b9f8eb..875cd5ac4 100644
--- a/packages/jgengine/src/templates/captureArgs.test.ts
+++ b/packages/jgengine/src/templates/captureArgs.test.ts
@@ -100,6 +100,32 @@ describe("parseStepFile", () => {
       .toBe("steps[4].rightClickAt: expected [x, y] numbers, got \"420,220\"");
   });
 
+  test("parses aim steps and lists them in --check with their conditions", () => {
+    const steps = parseStepFile({
+      steps: [
+        { moveMouse: [640, 360], before: { is: "menu.ready" } },
+        { look: [-120, 40] },
+        { aimAt: "crosshair.target()", tolerancePx: 4, after: { is: "aim.onTarget", timeoutMs: 3000 } },
+      ],
+    }, "aim.json");
+    expect(steps[0]).toMatchObject({ kind: "move-mouse", x: 640, y: 360, before: { is: "menu.ready" } });
+    expect(steps[1]).toEqual({ kind: "look", dx: -120, dy: 40 });
+    expect(steps[2]).toMatchObject({ kind: "aim-at", expression: "crosshair.target()", tolerancePx: 4, after: { is: "aim.onTarget", timeoutMs: 3000 } });
+    expect(parseStepFile({ steps: [{ aimAt: "[10, 20]" }] }, "aim.json")[0]).toMatchObject({ tolerancePx: 6 });
+    const listed = describeStepFile(steps, "aim.json");
+    expect(listed).toContain("#1 moveMouse 640,360 before<=15000ms");
+    expect(listed).toContain("#2 look -120,40 px");
+    expect(listed).toContain("#3 aimAt \"crosshair.target()\" within 4px after<=3000ms");
+  });
+
+  test("names the index and the field for a malformed aim coordinate or target", () => {
+    expect(error([{ click: "Start" }, { look: [10, "20"] }])).toBe("steps[1].look: expected [x, y] numbers, got [10,\"20\"]");
+    expect(error([{ moveMouse: [1, 2, 3] }])).toBe("steps[0].moveMouse: expected [x, y] numbers, got [1,2,3]");
+    expect(error([{ aimAt: "" }])).toContain("steps[0].aimAt: expected the page expression");
+    expect(error([{ aimAt: "target()", tolerancePx: 0 }])).toContain("steps[0].tolerancePx: expected a positive number");
+    expect(error([{ look: [1, 2], tolerancePx: 3 }])).toContain("steps[0]: \"tolerancePx\" sizes an aimAt target");
+  });
+
   test("names the index for an unknown key code", () => {
     const message = error([{ click: "Start" }, { wait: 1 }, { key: "KeyHH", ms: 120 }]);
     expect(message).toContain("steps[2].key: unknown key code \"KeyHH\"");
diff --git a/packages/jgengine/src/templates/captureArgs.ts b/packages/jgengine/src/templates/captureArgs.ts
index ef4c0a96f..fbb5b9298 100644
--- a/packages/jgengine/src/templates/captureArgs.ts
+++ b/packages/jgengine/src/templates/captureArgs.ts
@@ -108,6 +108,9 @@ export type CaptureStep = (
   | { kind: "click"; text: string }
   | { kind: "double-click"; text: string }
   | { kind: "click-at"; spec: string; button: "left" | "right" }
+  | { kind: "move-mouse"; x: number; y: number }
+  | { kind: "look"; dx: number; dy: number }
+  | { kind: "aim-at"; expression: string; tolerancePx: number }
   | { kind: "fill"; label: string; value: string }
   | { kind: "key"; code: string; holdMs: number }
   | { kind: "wait"; ms: number }
@@ -128,10 +131,12 @@ export type CaptureStep = (
 export const DRIVE_CONDITION_TIMEOUT_MS = 15_000;
 /** How often a condition is re-evaluated while it is failing. */
 export const DRIVE_CONDITION_POLL_MS = 50;
+/** How close `aimAt` must bring the target to the crosshair before the step counts as aimed. */
+export const AIM_TOLERANCE_PX = 6;
 
 /** The step kinds a JSON step file accepts, in the order the help lists them. */
 export function driveStepKinds(): string[] {
-  return ["click", "doubleClick", "clickAt", "rightClickAt", "fill", "key", "wait", "waitFor", "reload", "shot", "rpc", "probe", "assert", "flow"];
+  return ["click", "doubleClick", "clickAt", "rightClickAt", "moveMouse", "look", "aimAt", "fill", "key", "wait", "waitFor", "reload", "shot", "rpc", "probe", "assert", "flow"];
 }
 
 /** A named flow file's parsed JSON and the path its errors name. */
@@ -358,7 +363,7 @@ export function parseStepFile(input: unknown, source: string, options: ParseStep
   }
   if (!Array.isArray(top.steps)) throw new Error(source + ": expected {\"steps\":[...]}, got " + valueType(top.steps));
   if (top.steps.length === 0) throw new Error(source + ": the steps list is empty, so the run would prove nothing");
-  const modifiers = ["before", "after", "ms", "timeoutMs", "note", "is"];
+  const modifiers = ["before", "after", "ms", "timeoutMs", "tolerancePx", "note", "is"];
   return top.steps.flatMap((raw, index) => {
     const at = "steps[" + index + "]";
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error(at + ": expected a step object, got " + valueType(raw));
@@ -371,6 +376,7 @@ export function parseStepFile(input: unknown, source: string, options: ParseStep
     const kind = actions[0]!;
     const value = step[kind];
     if (step.is !== undefined && kind !== "assert") throw new Error(at + ": \"is\" is the assert expectation, so it cannot sit on a " + kind + " step");
+    if (step.tolerancePx !== undefined && kind !== "aimAt") throw new Error(at + ": \"tolerancePx\" sizes an aimAt target, so it cannot sit on a " + kind + " step");
     if (kind === "flow") return expandFlow(flowNameAt(at + ".flow", value), at, source, options, step);
     const before = step.before === undefined ? undefined : conditionAt(at + ".before", step.before);
     const after = step.after === undefined ? undefined : conditionAt(at + ".after", step.after);
@@ -386,6 +392,24 @@ export function parseStepFile(input: unknown, source: string, options: ParseStep
       case "clickAt":
       case "rightClickAt":
         return [shape({ kind: "click-at", spec: coordinatePair(at + "." + kind, value), button: kind === "rightClickAt" ? "right" : "left" })];
+      case "moveMouse": {
+        const [x, y] = coordinatePair(at + ".moveMouse", value).split(",").map(Number) as [number, number];
+        return [shape({ kind: "move-mouse", x, y })];
+      }
+      case "look": {
+        const [dx, dy] = coordinatePair(at + ".look", value).split(",").map(Number) as [number, number];
+        return [shape({ kind: "look", dx, dy })];
+      }
+      case "aimAt": {
+        if (typeof value !== "string" || value.trim() === "") {
+          throw new Error(at + ".aimAt: expected the page expression that returns the target's screen point { x, y }, got " + JSON.stringify(value));
+        }
+        const tolerance = step.tolerancePx;
+        if (tolerance !== undefined && (typeof tolerance !== "number" || !Number.isFinite(tolerance) || tolerance <= 0)) {
+          throw new Error(at + ".tolerancePx: expected a positive number of CSS pixels, got " + JSON.stringify(tolerance));
+        }
+        return [shape({ kind: "aim-at", expression: value, tolerancePx: tolerance ?? AIM_TOLERANCE_PX })];
+      }
       case "fill": {
         if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(at + ".fill: expected {\"label\": \"<label>\", \"value\": \"<text>\"}, got " + JSON.stringify(value));
         const field = value as Record<string, unknown>;
@@ -442,7 +466,7 @@ function flowNameAt(path: string, value: unknown): string {
 
 /** Resolve one `{ "flow": name }` include into its steps, refusing a cycle or a fifth level. */
 function expandFlow(name: string, at: string, includeSource: string, options: ParseStepOptions, step: Record<string, unknown>): CaptureStep[] {
-  const extra = ["before", "after", "ms", "timeoutMs", "note", "is"].filter((key) => step[key] !== undefined);
+  const extra = ["before", "after", "ms", "timeoutMs", "tolerancePx", "note", "is"].filter((key) => step[key] !== undefined);
   if (extra.length > 0) throw new Error(at + ".flow: an include carries no fields of its own (got " + extra.join(", ") + "); put them on the flow's steps");
   const stack = options.stack ?? [];
   if (stack.includes(name)) throw new Error(at + ".flow: flow cycle by name: " + [...stack, name].join(" -> "));
@@ -474,6 +498,9 @@ export function describeStep(step: CaptureStep): string {
     case "click": return "click \"" + step.text + "\"";
     case "double-click": return "doubleClick \"" + step.text + "\"";
     case "click-at": return (step.button === "right" ? "rightClickAt " : "clickAt ") + step.spec;
+    case "move-mouse": return "moveMouse " + step.x + "," + step.y;
+    case "look": return "look " + step.dx + "," + step.dy + " px";
+    case "aim-at": return "aimAt " + JSON.stringify(step.expression) + " within " + step.tolerancePx + "px";
     case "fill": return "fill \"" + step.label + "\" = \"" + step.value + "\"";
     case "key": return "key " + step.code + " " + step.holdMs + "ms";
     case "wait": return "wait " + step.ms + "ms (last resort: a guessed sleep)";
diff --git a/packages/jgengine/src/templates/driveAim.test.ts b/packages/jgengine/src/templates/driveAim.test.ts
new file mode 100644
index 000000000..ea47bcd19
--- /dev/null
+++ b/packages/jgengine/src/templates/driveAim.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, test } from "bun:test";
+
+import { acquireDrivePointerLock, aimDriveAt, lookDrivePointer, moveDrivePointer, type DriveAimSession } from "./driveAim";
+
+const WIDTH = 1600;
+const HEIGHT = 900;
+const CENTRE = { x: WIDTH / 2, y: HEIGHT / 2 };
+
+/**
+ * A page whose target is the projection of a yaw offset: a pointer-locked view turns by
+ * `movementX / pxPerRad` pixels of projection, so the harness has to learn that cost.
+ */
+function fakePage(options: { pxPerRad?: number; locked?: boolean; deliverMovement?: "cdp" | "none" } = {}) {
+  const pxPerRad = options.pxPerRad ?? 900;
+  const state = { yaw: 0.75, sent: [] as { x: number; y: number }[], synthetic: 0, events: [] as string[], last: { x: 0, y: 0 }, acc: { x: 0, y: 0 } };
+  const session: DriveAimSession = {
+    async send(method, params) {
+      state.events.push(method);
+      if (method === "Input.dispatchMouseEvent") {
+        state.last = { x: Number(params?.x), y: Number(params?.y) };
+        state.sent.push(state.last);
+        if (options.locked === true && options.deliverMovement !== "none") state.yaw -= (state.last.x - CENTRE.x) / pxPerRad;
+      }
+      if (method === "Runtime.evaluate" && JSON.stringify(params).includes("requestPointerLock")) {
+        return { result: { value: options.locked === true ? "locked" : "refused" } };
+      }
+      return {};
+    },
+    async evaluate(expression) {
+      if (expression.includes("pointerLockElement")) return options.locked === true;
+      if (expression.includes("getBoundingClientRect")) return { x: CENTRE.x, y: CENTRE.y };
+      if (expression.includes("__jgAimMove")) {
+        if (expression.includes("state.acc = { x: 0, y: 0 }")) {
+          state.acc = { x: 0, y: 0 };
+          return true;
+        }
+        const delivered = options.deliverMovement === "none" ? state.acc : { x: state.last.x - CENTRE.x + state.acc.x, y: state.last.y - CENTRE.y + state.acc.y };
+        const seen = options.deliverMovement === "none" ? state.synthetic : 1 + state.synthetic;
+        return { x: delivered.x, y: delivered.y, seen };
+      }
+      if (expression.includes("Object.defineProperty")) {
+        state.synthetic += 1;
+        const dx = Number(/movementX', \{ value: (-?[\d.]+)/.exec(expression)?.[1] ?? 0);
+        state.acc.x += dx;
+        state.yaw -= dx / pxPerRad;
+        return true;
+      }
+      if (expression.includes("crosshair.target")) {
+        return { x: CENTRE.x + state.yaw * pxPerRad, y: CENTRE.y };
+      }
+      return null;
+    },
+  };
+  return { session, state };
+}
+
+describe("aim steps", () => {
+  test("moveMouse dispatches an absolute pointer move and no button", async () => {
+    const { session, state } = fakePage();
+    await moveDrivePointer(session, { x: 240, y: 180 });
+    expect(state.sent).toEqual([{ x: 240, y: 180 }]);
+    expect(state.events).toEqual(["Input.dispatchMouseEvent"]);
+  });
+
+  test("look turns a locked view and reports the movement the page saw", async () => {
+    const { session, state } = fakePage({ locked: true });
+    const before = state.yaw;
+    const turned = await lookDrivePointer(session, 300, 0);
+    expect(turned.movement).toEqual({ x: 300, y: 0 });
+    expect(state.yaw).toBeLessThan(before);
+  });
+
+  test("look chunks a long turn from the pinned centre instead of leaving the viewport", async () => {
+    const { session, state } = fakePage({ locked: true });
+    await lookDrivePointer(session, 500, 0);
+    expect(state.sent.map((point) => point.x)).toEqual([CENTRE.x + 200, CENTRE.x + 200, CENTRE.x + 100]);
+  });
+
+  test("look falls back to a page move carrying the deltas when CDP delivers none", async () => {
+    const { session, state } = fakePage({ locked: true, deliverMovement: "none" });
+    const before = state.yaw;
+    await lookDrivePointer(session, 120, 0);
+    expect(state.synthetic).toBe(1);
+    expect(state.yaw).toBeLessThan(before);
+  });
+
+  test("look refuses a page that takes the move and never reports movement", async () => {
+    const { session } = fakePage({ locked: true, deliverMovement: "none" });
+    const silent: DriveAimSession = {
+      async send(method, params) {
+        return session.send(method, params);
+      },
+      async evaluate(expression) {
+        if (expression.includes("__jgAimMove")) {
+          return expression.includes("state.acc = { x: 0, y: 0 }") ? true : { x: 0, y: 0, seen: 0 };
+        }
+        if (expression.includes("Object.defineProperty")) return false;
+        if (expression.includes("getBoundingClientRect")) return { x: CENTRE.x, y: CENTRE.y };
+        return null;
+      },
+    };
+    await expect(lookDrivePointer(silent, 40, 0)).rejects.toThrow("reported no movement");
+  });
+
+  test("acquireDrivePointerLock asks the canvas for the lock, never a mouse button", async () => {
+    const { session, state } = fakePage({ locked: true });
+    expect(await acquireDrivePointerLock(session)).toBe(true);
+    expect(state.events).toEqual([]);
+    const late = fakePage({ locked: true });
+    expect(await acquireDrivePointerLock(late.session)).toBe(true);
+    expect(late.state.events.some((method) => method.includes("MouseEvent"))).toBe(false);
+  });
+
+  test("aimAt learns a fast page's pixel cost and lands inside the tolerance", async () => {
+    const { session } = fakePage({ locked: true, pxPerRad: 2200 });
+    const aimed = await aimDriveAt(session, null, "crosshair.target()", 6);
+    expect(aimed.moves).toBeGreaterThan(0);
+    expect(Math.abs(aimed.point.x - CENTRE.x)).toBeLessThanOrEqual(6);
+  });
+
+  test("aimAt lands on a slow page too, without being told the sensitivity", async () => {
+    const { session } = fakePage({ locked: true, pxPerRad: 400 });
+    const aimed = await aimDriveAt(session, null, "crosshair.target()", 6);
+    expect(Math.abs(aimed.point.x - CENTRE.x)).toBeLessThanOrEqual(6);
+  });
+
+  test("aimAt moves the plain pointer when the page is not pointer-locked", async () => {
+    const { session, state } = fakePage({ locked: false });
+    const aimed = await aimDriveAt(session, null, "crosshair.target()", 6);
+    expect(aimed.moves).toBe(1);
+    expect(state.sent.at(-1)?.x).toBeCloseTo(CENTRE.x + 0.75 * 900, 0);
+  });
+});
diff --git a/packages/jgengine/src/templates/driveAim.ts b/packages/jgengine/src/templates/driveAim.ts
new file mode 100644
index 000000000..10e3e5e72
--- /dev/null
+++ b/packages/jgengine/src/templates/driveAim.ts
@@ -0,0 +1,209 @@
+/**
+ * Pointer-move, look and aim steps shared by the engine's `bun run drive` and the portable
+ * `drive.mjs`. Self-contained by contract: the portable harness embeds these functions with
+ * `Function.prototype.toString`, so nothing here reads a module-scope identifier — page
+ * expressions are inlined in the function that evaluates them.
+ */
+
+/** The CDP calls an aim step makes; both the engine and portable sessions satisfy it. */
+export interface DriveAimSession {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  evaluate(expression: string, options?: { awaitPromise?: boolean }): Promise<unknown>;
+}
+
+/** A CSS viewport point. */
+export interface DrivePoint {
+  x: number;
+  y: number;
+}
+
+/** Where the pointer last was, so a relative look has a position to move from. */
+export type DrivePointerState = DrivePoint;
+
+/**
+ * Acquire pointer lock the way the game does — a lock request on the play canvas — but inside
+ * CDP's user-gesture flag instead of a click, so a look step does not fire the weapon it aims.
+ */
+export async function acquireDrivePointerLock(session: DriveAimSession): Promise<boolean> {
+  const locked = await session.evaluate(
+    "document.pointerLockElement !== null && document.pointerLockElement === document.querySelector('canvas')",
+  );
+  if (locked === true) return true;
+  const sent = (await session.send("Runtime.evaluate", {
+    expression:
+      "(async () => {" +
+      "  const canvas = document.querySelector('canvas');" +
+      "  if (canvas === null) return 'no-canvas';" +
+      "  if (document.pointerLockElement === canvas) return 'locked';" +
+      "  try { await canvas.requestPointerLock({ unadjustedMovement: true }); }" +
+      "  catch { try { await canvas.requestPointerLock(); } catch { return 'refused'; } }" +
+      "  for (let wait = 0; wait < 20 && document.pointerLockElement !== canvas; wait += 1) {" +
+      "    await new Promise((done) => setTimeout(done, 10));" +
+      "  }" +
+      "  return document.pointerLockElement === canvas ? 'locked' : 'refused';" +
+      "})()",
+    returnByValue: true,
+    awaitPromise: true,
+    userGesture: true,
+  })) as { result?: { value?: unknown } } | undefined;
+  const value = sent?.result?.value;
+  if (value === "locked") return true;
+  if (value === "no-canvas") throw new Error("look: this page has no canvas to lock the pointer to; use moveMouse");
+  throw new Error("look: the page refused pointer lock, so a relative look would never reach a pointer-locked camera");
+}
+
+/** Dispatch one absolute pointer move (a plain hover, no button) at CSS pixels. */
+export async function moveDrivePointer(session: DriveAimSession, point: DrivePoint): Promise<void> {
+  await session.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: point.x, y: point.y, button: "none", buttons: 0 });
+}
+
+/**
+ * Turn a pointer-locked view by `dx`,`dy` CSS pixels of mouse movement. Real CDP pointer moves are
+ * tried first; when the browser delivers no movement through them (a locked page whose hardware
+ * cursor never moves), a mousemove carrying the requested deltas is dispatched into the page, so
+ * the game's own look handler still receives the turn. Each dispatch is measured from the locked
+ * cursor, which Chrome pins at the surface centre, so a long turn is sent in centre-anchored
+ * chunks. Returns the movement the page actually saw.
+ */
+export async function lookDrivePointer(
+  session: DriveAimSession,
+  dx: number,
+  dy: number,
+): Promise<{ movement: { x: number; y: number } }> {
+  const centre = (await session.evaluate(
+    "(() => {" +
+      "  const canvas = document.querySelector('canvas');" +
+      "  const rect = canvas === null ? null : canvas.getBoundingClientRect();" +
+      "  if (rect !== null && rect.width > 0 && rect.height > 0) return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };" +
+      "  return { x: innerWidth / 2, y: innerHeight / 2 };" +
+      "})()",
+  )) as DrivePoint;
+  await session.evaluate(
+    "(() => {" +
+      "  const state = globalThis.__jgAimMove ?? (globalThis.__jgAimMove = { acc: { x: 0, y: 0 }, seen: 0 });" +
+      "  state.acc = { x: 0, y: 0 }; state.seen = 0;" +
+      "  if (state.installed === true) return true;" +
+      "  state.installed = true;" +
+      "  window.addEventListener('mousemove', (event) => {" +
+      "    state.seen += 1;" +
+      "    state.acc.x += event.movementX || 0;" +
+      "    state.acc.y += event.movementY || 0;" +
+      "  }, true);" +
+      "  return true;" +
+      "})()",
+  );
+  const read = "(() => { const state = globalThis.__jgAimMove; return state ? { x: state.acc.x, y: state.acc.y, seen: state.seen } : { x: 0, y: 0, seen: 0 }; })()";
+  const total = { x: 0, y: 0 };
+  let remaining = { x: dx, y: dy };
+  const clamp = (value: number) => Math.max(-200, Math.min(200, value));
+  for (let chunk = 0; chunk < 40 && (Math.abs(remaining.x) > 0.5 || Math.abs(remaining.y) > 0.5); chunk += 1) {
+    const send = { x: clamp(Math.trunc(remaining.x)), y: clamp(Math.trunc(remaining.y)) };
+    if (send.x === 0 && send.y === 0) {
+      remaining = { x: remaining.x - send.x, y: remaining.y - send.y };
+      continue;
+    }
+    remaining = { x: remaining.x - send.x, y: remaining.y - send.y };
+    await session.evaluate(
+      "(() => {" +
+        "  const state = globalThis.__jgAimMove ?? (globalThis.__jgAimMove = { acc: { x: 0, y: 0 }, seen: 0 });" +
+        "  state.acc = { x: 0, y: 0 }; state.seen = 0;" +
+        "  if (state.installed === true) return true;" +
+        "  state.installed = true;" +
+        "  window.addEventListener('mousemove', (event) => {" +
+        "    state.seen += 1;" +
+        "    state.acc.x += event.movementX || 0;" +
+        "    state.acc.y += event.movementY || 0;" +
+        "  }, true);" +
+        "  return true;" +
+        "})()",
+    );
+    await moveDrivePointer(session, { x: Math.round(centre.x + send.x), y: Math.round(centre.y + send.y) });
+    let seen = (await session.evaluate(read)) as { x: number; y: number; seen: number } | undefined;
+    if ((seen?.seen ?? 0) === 0) {
+      await session.evaluate(
+        "(() => {" +
+          "  const event = new MouseEvent('mousemove', { bubbles: true, cancelable: true, view: window });" +
+          "  Object.defineProperty(event, 'movementX', { value: " + send.x + " });" +
+          "  Object.defineProperty(event, 'movementY', { value: " + send.y + " });" +
+          "  window.dispatchEvent(event);" +
+          "  return true;" +
+          "})()",
+      );
+      seen = (await session.evaluate(read)) as { x: number; y: number; seen: number } | undefined;
+      if ((seen?.seen ?? 0) === 0) {
+        throw new Error("look: the page took the pointer move but reported no movement (" + dx + "," + dy + " px requested)");
+      }
+    }
+    total.x += seen?.x ?? 0;
+    total.y += seen?.y ?? 0;
+    if ((seen?.x ?? 0) === 0 && (seen?.y ?? 0) === 0) break;
+  }
+  if (Math.max(Math.abs(total.x), Math.abs(total.y)) < 0.5) {
+    throw new Error("look: the page took the pointer move but reported no movement (" + dx + "," + dy + " px requested)");
+  }
+  return { movement: total };
+}
+
+/**
+ * Point the crosshair at a target the page can locate: `expression` evaluates to the target's CSS
+ * screen point ({x,y}), or null while it is not visible. Each correction is measured against the
+ * page's own projected point, so the step learns the game's look response instead of assuming it.
+ */
+export async function aimDriveAt(
+  session: DriveAimSession,
+  from: DrivePointerState | null,
+  expression: string,
+  tolerancePx: number,
+): Promise<{ from: DrivePointerState; point: DrivePoint; moves: number }> {
+  const centre = (await session.evaluate(
+    "(() => {" +
+      "  const canvas = document.querySelector('canvas');" +
+      "  const rect = canvas === null ? null : canvas.getBoundingClientRect();" +
+      "  if (rect !== null && rect.width > 0 && rect.height > 0) return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };" +
+      "  return { x: innerWidth / 2, y: innerHeight / 2 };" +
+      "})()",
+  )) as DrivePoint;
+  const locked = (await session.evaluate(
+    "document.pointerLockElement !== null && document.pointerLockElement === document.querySelector('canvas')",
+  )) === true;
+  const read = async (): Promise<DrivePoint | null> => {
+    const value = (await session.evaluate("(async () => (" + expression + "))()", { awaitPromise: true })) as unknown;
+    if (value === null || value === undefined) return null;
+    const point = Array.isArray(value) ? { x: Number(value[0]), y: Number(value[1]) } : (value as DrivePoint);
+    if (typeof point !== "object") return null;
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return null;
+    return { x: point.x, y: point.y };
+  };
+  let pointer = from;
+  let point = await read();
+  if (point === null) throw new Error("aimAt: the page returned no screen point for " + JSON.stringify(expression));
+  if (!locked) {
+    await moveDrivePointer(session, point);
+    const after = await read();
+    if (after === null || Math.max(Math.abs(after.x - point.x), Math.abs(after.y - point.y)) > tolerancePx) {
+      throw new Error("aimAt: the target moved away from the pointer (" + JSON.stringify(expression) + ")");
+    }
+    return { from: point, point: after, moves: 1 };
+  }
+  const offBy = (target: DrivePoint, pivotPoint: DrivePoint) => ({ x: target.x - pivotPoint.x, y: target.y - pivotPoint.y });
+  let gain = 1;
+  for (let moves = 0; moves < 8; moves += 1) {
+    const error = offBy(point, centre);
+    if (Math.max(Math.abs(error.x), Math.abs(error.y)) <= tolerancePx) return { from: pointer ?? centre, point, moves };
+    const asked = { x: error.x * gain, y: error.y * gain };
+    await lookDrivePointer(session, asked.x, asked.y);
+    const next = await read();
+    if (next === null) throw new Error("aimAt: the target left the page while aiming (" + JSON.stringify(expression) + ")");
+    const useX = Math.abs(asked.x) >= Math.abs(asked.y);
+    const input = useX ? asked.x : asked.y;
+    const removed = useX ? point.x - next.x : point.y - next.y;
+    const scale = Math.abs(input) < 1 ? Number.NaN : removed / input;
+    if (Number.isFinite(scale) && Math.abs(scale) > 0.05 && Math.abs(scale) < 20) gain = 0.8 / scale;
+    point = next;
+  }
+  const error = offBy(point, centre);
+  throw new Error(
+    "aimAt: the crosshair never reached " + JSON.stringify(expression) + " (last point " + JSON.stringify(point) +
+      ", crosshair " + JSON.stringify(centre) + ", off by " + Math.round(error.x) + "," + Math.round(error.y) + "px, tolerance " + tolerancePx + "px)",
+  );
+}
diff --git a/packages/jgengine/src/templates/gameFiles.ts b/packages/jgengine/src/templates/gameFiles.ts
index 2ec596d94..1821be578 100644
--- a/packages/jgengine/src/templates/gameFiles.ts
+++ b/packages/jgengine/src/templates/gameFiles.ts
@@ -3,6 +3,7 @@ import { escapeHtml } from "../escapeHtml";
 import { BROWSER_LAUNCH_BLOCK } from "./browserLaunch";
 import { CAPTURE_FLAGS, captureFlagHelp, parseCaptureArgs, rejectEngineOnlyFlags } from "./captureArgs";
 import { awaitGameView, holdDriveInput } from "./driveSteps";
+import { acquireDrivePointerLock, aimDriveAt, lookDrivePointer, moveDrivePointer } from "./driveAim";
 import { driveInputPointExpr } from "./driveInput";
 import { focusGameSurface, gameSurfaceCenter, holdComplete, mouseButtonForCode } from "./gameSurfaceFocus";
 import type { EditorSceneDoc, TemplateVariant } from "./types";
@@ -280,6 +281,14 @@ export ${holdDriveInput.toString()}
 
 export ${awaitGameView.toString()}
 
+export ${acquireDrivePointerLock.toString()}
+
+export ${moveDrivePointer.toString()}
+
+export ${lookDrivePointer.toString()}
+
+export ${aimDriveAt.toString()}
+
 /** Parse argv for a portable harness: the shared flag table, minus what only the engine runner honors. */
 export function parsePortableArgs(tool, argv) {
   const parsed = parseCaptureArgs(tool, argv, CAPTURE_FLAGS);
@@ -1120,6 +1129,7 @@ async function main() {
   for (const step of args.steps) {
     if (step.kind === "click-at") step.point = parseClickAt(step.spec, width, height);
   }
+  let pointer = null;
   const base = "http://127.0.0.1:" + args.port;
   const target = new URL(args.url ?? base);
   target.searchParams.set("capture", "1");
@@ -1159,6 +1169,17 @@ async function main() {
         if (step.kind === "click" || step.kind === "double-click") await click(session, step.text, step.kind === "double-click" ? 2 : 1);
         else if (step.kind === "fill") await fill(session, step.label, step.value);
         else if (step.kind === "click-at") await dispatchClickAt(session, step.point, step.button);
+        else if (step.kind === "move-mouse") pointer = { x: step.x, y: step.y }, await moveDrivePointer(session, pointer);
+        else if (step.kind === "look") {
+          await acquireDrivePointerLock(session);
+          const turned = await lookDrivePointer(session, step.dx, step.dy);
+          console.error("look: moved " + Math.round(turned.movement.x) + "," + Math.round(turned.movement.y) + "px");
+        } else if (step.kind === "aim-at") {
+          await acquireDrivePointerLock(session).catch(() => false);
+          const aimed = await aimDriveAt(session, pointer, step.expression, step.tolerancePx);
+          pointer = aimed.from;
+          console.error("aimAt: aimed " + Math.round(aimed.point.x) + "," + Math.round(aimed.point.y) + " in " + aimed.moves + " move(s)");
+        }
         else if (step.kind === "key") await holdKey(session, step.code, step.holdMs);
         else if (step.kind === "wait") await sleep(step.ms);
         else if (step.kind === "reload") await navigate(session, url, args.timeoutMs, args.settle);
diff --git a/scripts/drive-dev.ts b/scripts/drive-dev.ts
index 23c120bbd..c44226945 100644
--- a/scripts/drive-dev.ts
+++ b/scripts/drive-dev.ts
@@ -59,6 +59,7 @@ import {
 import { driveInputPointExpr } from "../packages/jgengine/src/templates/driveInput";
 import { CAPTURE_FLAGS, captureFlagHelp, describeFlow, describeStepFile, parseCaptureArgs, parseStepFile, rejectMixedStepFlags, type CaptureStep, type FlowFile, type FlowSource } from "../packages/jgengine/src/templates/captureArgs";
 import { awaitDriveCondition, awaitGameView, holdDriveInput, type DriveConditionClock, type DriveInputDeps, type DriveSession } from "../packages/jgengine/src/templates/driveSteps";
+import { acquireDrivePointerLock, aimDriveAt, lookDrivePointer, moveDrivePointer, type DrivePoint } from "../packages/jgengine/src/templates/driveAim";
 import { driveProjectDir, flowSourceFrom, flowsDirOf, listFlowNames, missingFlowsMessage } from "./driveFlows";
 import { evaluateAssertStep, runDriveSteps, type DriveStepRecord } from "./driveRun";
 import { gameSurfaceCenter, mouseButtonForCode } from "../packages/jgengine/src/templates/gameSurfaceFocus";
@@ -178,6 +179,12 @@ Script a drive:
   "shot" is a bare name: it lands in <game>/docs/<name>.png, never an absolute path,
   and a site target lands in apps/web/docs/. Coordinates are [x, y] numbers.
   "waitFor": "<expression>" is sugar for a step with only a before condition.
+  Aim steps: "moveMouse": [x, y] hovers the pointer at CSS viewport pixels; "look": [dx, dy]
+  turns a pointer-locked view by that many pixels of mouse movement (the step takes pointer
+  lock on the play canvas the way the game does, without clicking, so it cannot fire);
+  "aimAt": "<page expression>" resolves the expression to the target's { x, y } screen point
+  and turns until the crosshair is on it ("tolerancePx", default 6), measuring the game's own
+  look response instead of assuming a sensitivity. A goal is "aimAt", never a guessed "look".
   A fixed "wait" still parses for CI compatibility, but it is the last resort: a guessed
   sleep either wastes the difference or races the frame. Say what must be true instead.
   --steps cannot be mixed with step flags (--click, --key, --wait, --shot, ...).
@@ -888,6 +895,9 @@ async function driveSession(daemon: ShootDaemonState | null): Promise<number> {
           writeFileSync(logPath, "");
         }
 
+        /** Where the pointer was left by the previous aim step, so a relative look has an origin. */
+        let pointer: DrivePoint | null = null;
+
         const done = await runDriveSteps(args.steps, {
           now: () => performance.now(),
           line: (text) => console.error(text),
@@ -929,6 +939,21 @@ async function driveSession(daemon: ShootDaemonState | null): Promise<number> {
               await session.send("Page.bringToFront");
               await dispatchClickAt(session, clickPoints.get(step)!, step.button);
               if (recorder !== null) await recorder.advance(300);
+            } else if (step.kind === "move-mouse") {
+              await moveDrivePointer(session, { x: step.x, y: step.y });
+              pointer = { x: step.x, y: step.y };
+              if (recorder !== null) await recorder.advance(300);
+            } else if (step.kind === "look") {
+              await acquireDrivePointerLock(session);
+              const turned = await lookDrivePointer(session, step.dx, step.dy);
+              timings.push("moved " + Math.round(turned.movement.x) + "," + Math.round(turned.movement.y) + "px");
+              if (recorder !== null) await recorder.advance(300);
+            } else if (step.kind === "aim-at") {
+              await acquireDrivePointerLock(session).catch(() => false);
+              const aimed = await aimDriveAt(session, pointer, step.expression, step.tolerancePx);
+              pointer = aimed.from;
+              timings.push("aimed " + Math.round(aimed.point.x) + "," + Math.round(aimed.point.y) + " in " + aimed.moves + " move(s)");
+              if (recorder !== null) await recorder.advance(300);
             } else if (step.kind === "rpc") {
               await rpc(session, step.json);
               if (step.summarized) console.error(`drive: debug_snapshot printed its summary; pass {"method":"debug_snapshot","detail":"full"} for everything`);
@@ -937,6 +962,7 @@ async function driveSession(daemon: ShootDaemonState | null): Promise<number> {
               const metrics = await readProbe(session);
               console.log(JSON.stringify({ probe: step.name, metrics }));
             } else {
+              if (step.kind !== "shot") throw new Error("drive: steps[" + index + "] is a " + step.kind + " step with no executor");
               // A recording owns the screencast pump; a shot must not start/stop it underneath.
               const path = step.out ?? join(outDir, `${args.game}-${step.name}${sizeSuffix(args.size)}${qualitySuffix(args.quality)}${quickSuffix(args.quick)}.png`);
               const previous = preparedShots.has(path) ? preparedShots.get(path) : clearShotTarget(path);

From ec994c4ba5aa84efc7f46e8575afdf5c00e65e90 Mon Sep 17 00:00:00 2001
From: NoisemakerJon <139656120+Noisemaker111@users.noreply.github.com>
Date: Fri, 23 Oct 2026 22:53:55 -0400
Subject: [PATCH 2/2] Record the driveAim template subpath in the export
 manifest

---
 scripts/export-manifest.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/export-manifest.json b/scripts/export-manifest.json
index 506a3ab99..5149b0471 100644
--- a/scripts/export-manifest.json
+++ b/scripts/export-manifest.json
@@ -1383,6 +1383,7 @@
     "./templates/boardFiles",
     "./templates/browserLaunch",
     "./templates/captureArgs",
+    "./templates/driveAim",
     "./templates/driveInput",
     "./templates/driveSteps",
     "./templates/editorWorkspace",