miaoda-game-devkit 0.10.4 → 0.10.5

package/dist/cli/phaser-lint.js

@@ -23,6 +23,22 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+var KNOWN_PER_FRAME_CANVAS_DEPENDENCIES = /* @__PURE__ */ new Set([
+  "ball",
+  "bricks",
+  "enemies",
+  "entities",
+  "entity",
+  "elapsedMs",
+  "elapsedTimeMs",
+  "hoveredCell",
+  "paddle",
+  "particles",
+  "player",
+  "projectiles",
+  "snapshot",
+  "state"
+]);
 function runnableTestFiles(root, directory = (0, import_node_path.join)(root, "tests")) {
   if (!(0, import_node_fs.existsSync)(directory)) return [];
   const files = [];
@@ -116,6 +132,88 @@ function containsAny(values, expected) {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function visitAst(value, visitor) {
+  if (Array.isArray(value)) {
+    for (const item of value) visitAst(item, visitor);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (typeof value.type === "string") visitor(value);
+  for (const child of Object.values(value)) visitAst(child, visitor);
+}
+function identifierName(value) {
+  return isRecord(value) && value.type === "Identifier" && typeof value.name === "string" ? value.name : void 0;
+}
+function memberPath(value) {
+  if (!isRecord(value)) return [];
+  const identifier = identifierName(value);
+  if (identifier) return [identifier];
+  if (value.type !== "MemberExpression") return [];
+  return [...memberPath(value.object), ...identifierName(value.property) ? [identifierName(value.property)] : []];
+}
+function hasRepeatedAnimationFrameCallback(value) {
+  const callbackCounts = /* @__PURE__ */ new Map();
+  visitAst(value, (node) => {
+    if (node.type !== "CallExpression") return;
+    if (identifierName(node.callee) !== "requestAnimationFrame") return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    const callback = identifierName(arguments_[0]);
+    if (!callback) return;
+    callbackCounts.set(callback, (callbackCounts.get(callback) ?? 0) + 1);
+  });
+  return [...callbackCounts.values()].some((count) => count >= 2);
+}
+function reactEffectNames(file, source) {
+  const names = /* @__PURE__ */ new Set(["useEffect"]);
+  for (const declaration of staticImports(file, source)) {
+    if (declaration.moduleRequest.value !== "react") continue;
+    for (const entry of declaration.entries) {
+      if (entry.importName.kind === "Name" && entry.importName.name === "useEffect") {
+        names.add(entry.localName.value);
+      }
+    }
+  }
+  return names;
+}
+function isReactEffectCall(node, effectNames) {
+  if (node.type !== "CallExpression") return false;
+  const directName = identifierName(node.callee);
+  if (directName && effectNames.has(directName)) return true;
+  const path = memberPath(node.callee);
+  return path.length === 2 && path[1] === "useEffect";
+}
+function canvasRafDependencyIssues(file, source, projectRoot2) {
+  const ownsCanvas = /<canvas\b|createElement\s*\(\s*["']canvas["']|getContext\s*\(\s*["']2d["']/.test(
+    source
+  );
+  if (!ownsCanvas) return [];
+  const issues = [];
+  const effectNames = reactEffectNames(file, source);
+  visitAst(parseSource(file, source).program, (node) => {
+    if (!isReactEffectCall(node, effectNames)) return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    if (!hasRepeatedAnimationFrameCallback(arguments_[0])) return;
+    const dependencies = arguments_[1];
+    if (!isRecord(dependencies) || dependencies.type !== "ArrayExpression") return;
+    const elements = Array.isArray(dependencies.elements) ? dependencies.elements : [];
+    const unsafe = elements.filter(
+      (element) => memberPath(element).some((name) => KNOWN_PER_FRAME_CANVAS_DEPENDENCIES.has(name))
+    );
+    if (unsafe.length === 0) return;
+    const labels = unsafe.map((element) => {
+      if (!isRecord(element) || typeof element.start !== "number" || typeof element.end !== "number") {
+        return "dynamic state";
+      }
+      return source.slice(element.start, element.end);
+    });
+    const line = typeof node.start === "number" ? source.slice(0, node.start).split("\n").length : 1;
+    const path = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
+    issues.push(
+      `CANVAS_RAF_DYNAMIC_DEPENDENCY ${path}:${line}: a recurring frame loop depends on ${labels.join(", ")}. React cleanup cancels and recreates the pending frame whenever these values change, which can freeze Canvas while HUD state keeps updating. Keep the loop effect stable and read changing state through a ref; a plain app-owned 2D Canvas may optionally use useGameCanvas from miaoda-game-devkit/react.`
+    );
+  });
+  return issues;
+}
 function containsObserveProperty(value) {
   if (Array.isArray(value)) return value.some(containsObserveProperty);
   if (!isRecord(value)) return false;
@@ -131,17 +229,20 @@ function declaresObserve(file, source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
+  const canvasRafIssues = [];
   const productionFiles = sourceFiles(projectRoot2);
   for (const file of productionFiles) {
+    const source = (0, import_node_fs.readFileSync)(file, "utf8");
     const imports = namedImports(
       file,
-      (0, import_node_fs.readFileSync)(file, "utf8"),
+      source,
       REACT_RUNTIME_ENTRY
     );
     const projectPath = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
     if (containsAny(imports, CONTROLLER_IMPORTS))
       controllerFiles.push(projectPath);
+    canvasRafIssues.push(...canvasRafDependencyIssues(file, source, projectRoot2));
   }
   const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
   const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
@@ -152,6 +253,7 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
     (file) => importsExampleAlias(file, (0, import_node_fs.readFileSync)(file, "utf8"))
   ).map((file) => (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/"));
   const issues = [];
+  issues.push(...canvasRafIssues);
   if (staleExampleTestFiles.length > 0) {
     issues.push(
       `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
@@ -165,7 +267,8 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
       controllerFiles,
       productionEntryExists,
       productionUsesExample,
-      staleExampleTestFiles
+      staleExampleTestFiles,
+      canvasRafIssues
     };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
@@ -193,7 +296,8 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
     controllerFiles,
     productionEntryExists,
     productionUsesExample,
-    staleExampleTestFiles
+    staleExampleTestFiles,
+    canvasRafIssues
   };
 }
 
@@ -304,12 +408,13 @@ function checkVitestConfig(target) {
   }
   return { name, ok: true };
 }
-function checkReactProductTestAlignment() {
-  const name = "react-product-test-alignment";
+function checkReactSourceSafety() {
+  const name = "react-source-safety";
   const audit = auditReactAuthoritativePlaythrough(projectRoot);
-  if (audit.staleExampleTestFiles.length === 0) return { name, ok: true };
-  console.error(`[${name}] ${audit.issues[0]}`);
-  return { name, ok: false };
+  const blockingIssues = (audit.staleExampleTestFiles.length > 0 ? [audit.issues.find((issue) => issue.includes("runnable product tests still do"))] : []).filter((issue) => Boolean(issue));
+  for (const issue of blockingIssues) console.error(`[${name}] ${issue}`);
+  for (const issue of audit.canvasRafIssues) console.warn(`[${name}] WARNING ${issue}`);
+  return { name, ok: blockingIssues.length === 0 };
 }
 function styleLintRoots(target) {
   const sourceRoots = (0, import_node_fs2.readdirSync)((0, import_node_path2.join)(projectRoot, "src"), {
@@ -318,7 +423,7 @@ function styleLintRoots(target) {
   return target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? [...sourceRoots, "tests"] : sourceRoots;
 }
 async function runAllChecks(target) {
-  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactSourceSafety()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
   const lintRoots = styleLintRoots(target);
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),

package/dist/cli/react-lint.js

@@ -23,6 +23,22 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+var KNOWN_PER_FRAME_CANVAS_DEPENDENCIES = /* @__PURE__ */ new Set([
+  "ball",
+  "bricks",
+  "enemies",
+  "entities",
+  "entity",
+  "elapsedMs",
+  "elapsedTimeMs",
+  "hoveredCell",
+  "paddle",
+  "particles",
+  "player",
+  "projectiles",
+  "snapshot",
+  "state"
+]);
 function runnableTestFiles(root, directory = (0, import_node_path.join)(root, "tests")) {
   if (!(0, import_node_fs.existsSync)(directory)) return [];
   const files = [];
@@ -116,6 +132,88 @@ function containsAny(values, expected) {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function visitAst(value, visitor) {
+  if (Array.isArray(value)) {
+    for (const item of value) visitAst(item, visitor);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (typeof value.type === "string") visitor(value);
+  for (const child of Object.values(value)) visitAst(child, visitor);
+}
+function identifierName(value) {
+  return isRecord(value) && value.type === "Identifier" && typeof value.name === "string" ? value.name : void 0;
+}
+function memberPath(value) {
+  if (!isRecord(value)) return [];
+  const identifier = identifierName(value);
+  if (identifier) return [identifier];
+  if (value.type !== "MemberExpression") return [];
+  return [...memberPath(value.object), ...identifierName(value.property) ? [identifierName(value.property)] : []];
+}
+function hasRepeatedAnimationFrameCallback(value) {
+  const callbackCounts = /* @__PURE__ */ new Map();
+  visitAst(value, (node) => {
+    if (node.type !== "CallExpression") return;
+    if (identifierName(node.callee) !== "requestAnimationFrame") return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    const callback = identifierName(arguments_[0]);
+    if (!callback) return;
+    callbackCounts.set(callback, (callbackCounts.get(callback) ?? 0) + 1);
+  });
+  return [...callbackCounts.values()].some((count) => count >= 2);
+}
+function reactEffectNames(file, source) {
+  const names = /* @__PURE__ */ new Set(["useEffect"]);
+  for (const declaration of staticImports(file, source)) {
+    if (declaration.moduleRequest.value !== "react") continue;
+    for (const entry of declaration.entries) {
+      if (entry.importName.kind === "Name" && entry.importName.name === "useEffect") {
+        names.add(entry.localName.value);
+      }
+    }
+  }
+  return names;
+}
+function isReactEffectCall(node, effectNames) {
+  if (node.type !== "CallExpression") return false;
+  const directName = identifierName(node.callee);
+  if (directName && effectNames.has(directName)) return true;
+  const path = memberPath(node.callee);
+  return path.length === 2 && path[1] === "useEffect";
+}
+function canvasRafDependencyIssues(file, source, projectRoot2) {
+  const ownsCanvas = /<canvas\b|createElement\s*\(\s*["']canvas["']|getContext\s*\(\s*["']2d["']/.test(
+    source
+  );
+  if (!ownsCanvas) return [];
+  const issues = [];
+  const effectNames = reactEffectNames(file, source);
+  visitAst(parseSource(file, source).program, (node) => {
+    if (!isReactEffectCall(node, effectNames)) return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    if (!hasRepeatedAnimationFrameCallback(arguments_[0])) return;
+    const dependencies = arguments_[1];
+    if (!isRecord(dependencies) || dependencies.type !== "ArrayExpression") return;
+    const elements = Array.isArray(dependencies.elements) ? dependencies.elements : [];
+    const unsafe = elements.filter(
+      (element) => memberPath(element).some((name) => KNOWN_PER_FRAME_CANVAS_DEPENDENCIES.has(name))
+    );
+    if (unsafe.length === 0) return;
+    const labels = unsafe.map((element) => {
+      if (!isRecord(element) || typeof element.start !== "number" || typeof element.end !== "number") {
+        return "dynamic state";
+      }
+      return source.slice(element.start, element.end);
+    });
+    const line = typeof node.start === "number" ? source.slice(0, node.start).split("\n").length : 1;
+    const path = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
+    issues.push(
+      `CANVAS_RAF_DYNAMIC_DEPENDENCY ${path}:${line}: a recurring frame loop depends on ${labels.join(", ")}. React cleanup cancels and recreates the pending frame whenever these values change, which can freeze Canvas while HUD state keeps updating. Keep the loop effect stable and read changing state through a ref; a plain app-owned 2D Canvas may optionally use useGameCanvas from miaoda-game-devkit/react.`
+    );
+  });
+  return issues;
+}
 function containsObserveProperty(value) {
   if (Array.isArray(value)) return value.some(containsObserveProperty);
   if (!isRecord(value)) return false;
@@ -131,17 +229,20 @@ function declaresObserve(file, source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
+  const canvasRafIssues = [];
   const productionFiles = sourceFiles(projectRoot2);
   for (const file of productionFiles) {
+    const source = (0, import_node_fs.readFileSync)(file, "utf8");
     const imports = namedImports(
       file,
-      (0, import_node_fs.readFileSync)(file, "utf8"),
+      source,
       REACT_RUNTIME_ENTRY
     );
     const projectPath = (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
     if (containsAny(imports, CONTROLLER_IMPORTS))
       controllerFiles.push(projectPath);
+    canvasRafIssues.push(...canvasRafDependencyIssues(file, source, projectRoot2));
   }
   const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
   const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
@@ -152,6 +253,7 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
     (file) => importsExampleAlias(file, (0, import_node_fs.readFileSync)(file, "utf8"))
   ).map((file) => (0, import_node_path.relative)(projectRoot2, file).replaceAll("\\", "/"));
   const issues = [];
+  issues.push(...canvasRafIssues);
   if (staleExampleTestFiles.length > 0) {
     issues.push(
       `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
@@ -165,7 +267,8 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
       controllerFiles,
       productionEntryExists,
       productionUsesExample,
-      staleExampleTestFiles
+      staleExampleTestFiles,
+      canvasRafIssues
     };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
@@ -193,7 +296,8 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
     controllerFiles,
     productionEntryExists,
     productionUsesExample,
-    staleExampleTestFiles
+    staleExampleTestFiles,
+    canvasRafIssues
   };
 }
 
@@ -304,12 +408,13 @@ function checkVitestConfig(target) {
   }
   return { name, ok: true };
 }
-function checkReactProductTestAlignment() {
-  const name = "react-product-test-alignment";
+function checkReactSourceSafety() {
+  const name = "react-source-safety";
   const audit = auditReactAuthoritativePlaythrough(projectRoot);
-  if (audit.staleExampleTestFiles.length === 0) return { name, ok: true };
-  console.error(`[${name}] ${audit.issues[0]}`);
-  return { name, ok: false };
+  const blockingIssues = (audit.staleExampleTestFiles.length > 0 ? [audit.issues.find((issue) => issue.includes("runnable product tests still do"))] : []).filter((issue) => Boolean(issue));
+  for (const issue of blockingIssues) console.error(`[${name}] ${issue}`);
+  for (const issue of audit.canvasRafIssues) console.warn(`[${name}] WARNING ${issue}`);
+  return { name, ok: blockingIssues.length === 0 };
 }
 function styleLintRoots(target) {
   const sourceRoots = (0, import_node_fs2.readdirSync)((0, import_node_path2.join)(projectRoot, "src"), {
@@ -318,7 +423,7 @@ function styleLintRoots(target) {
   return target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? [...sourceRoots, "tests"] : sourceRoots;
 }
 async function runAllChecks(target) {
-  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactSourceSafety()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
   const lintRoots = styleLintRoots(target);
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),

package/dist/lint/setup.mjs

@@ -86,7 +86,27 @@ function getJSDOMWebGLContext(canvas, options) {
 }
 
 // src/testing/jsdom-canvas.ts
-var contexts2 = /* @__PURE__ */ new WeakMap();
+var registryKey = /* @__PURE__ */ Symbol.for("miaoda-game-devkit:jsdom-canvas-registry");
+var registryScope = globalThis;
+var registry = registryScope[registryKey] ??= {
+  contexts: /* @__PURE__ */ new WeakMap(),
+  drawCallCounts: /* @__PURE__ */ new WeakMap()
+};
+var { contexts: contexts2, drawCallCounts } = registry;
+var DRAW_METHODS = /* @__PURE__ */ new Set([
+  "clearRect",
+  "drawImage",
+  "fill",
+  "fillRect",
+  "fillText",
+  "putImageData",
+  "stroke",
+  "strokeRect",
+  "strokeText"
+]);
+function getJSDOMCanvasDrawCallCount(canvas) {
+  return drawCallCounts.get(canvas) ?? 0;
+}
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -127,7 +147,12 @@ function createCanvasContext(canvas) {
         return () => ({ addColorStop() {
         } });
       }
-      return () => void 0;
+      return () => {
+        if (typeof property === "string" && DRAW_METHODS.has(property)) {
+          drawCallCounts.set(canvas, getJSDOMCanvasDrawCallCount(canvas) + 1);
+        }
+        return void 0;
+      };
     }
   });
   return context;
@@ -142,6 +167,7 @@ function installJSDOMCanvasContext() {
     if (existing) return existing;
     const context = createCanvasContext(this);
     contexts2.set(this, context);
+    drawCallCounts.set(this, 0);
     return context;
   };
 }

package/dist/react/index.d.mts

@@ -1,4 +1,6 @@
-export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.mjs';
+import { G as GameClock } from '../game-clock-suUidZdT.mjs';
+export { a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.mjs';
+import { RefObject } from 'react';
 
 interface DisposableGameController {
     destroy(): void;
@@ -31,4 +33,26 @@ declare function useGameController<TController extends SubscribableGameControlle
     state: ReturnType<TController["snapshot"]>;
 };
 
-export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };
+interface GameCanvasFrame<TState> {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+    state: TState;
+    timestamp: number;
+    deltaMs: number;
+}
+interface UseGameCanvasOptions<TState> {
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    read: () => TState;
+    draw: (frame: GameCanvasFrame<TState>) => void;
+    clock?: GameClock;
+    maxDeltaMs?: number;
+}
+/**
+ * Convenience lifecycle for a plain HTML 2D Canvas. This is not the Devkit's renderer
+ * abstraction: WebGL/R3F/Pixi or another tool should use its own lifecycle instead.
+ * The component using this hook must render the attached canvas on the same mount.
+ * Pass the same injected clock used by the game Controller in deterministic tests.
+ */
+declare function useGameCanvas<TState>({ canvasRef, read, draw, clock, maxDeltaMs, }: UseGameCanvasOptions<TState>): void;
+
+export { type DisposableGameController, type GameCanvasFrame, GameClock, type SubscribableGameController, type UseGameCanvasOptions, useGameCanvas, useGameController, useOwnedGameController };

package/dist/react/index.d.ts

@@ -1,4 +1,6 @@
-export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.js';
+import { G as GameClock } from '../game-clock-suUidZdT.js';
+export { a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.js';
+import { RefObject } from 'react';
 
 interface DisposableGameController {
     destroy(): void;
@@ -31,4 +33,26 @@ declare function useGameController<TController extends SubscribableGameControlle
     state: ReturnType<TController["snapshot"]>;
 };
 
-export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };
+interface GameCanvasFrame<TState> {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+    state: TState;
+    timestamp: number;
+    deltaMs: number;
+}
+interface UseGameCanvasOptions<TState> {
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    read: () => TState;
+    draw: (frame: GameCanvasFrame<TState>) => void;
+    clock?: GameClock;
+    maxDeltaMs?: number;
+}
+/**
+ * Convenience lifecycle for a plain HTML 2D Canvas. This is not the Devkit's renderer
+ * abstraction: WebGL/R3F/Pixi or another tool should use its own lifecycle instead.
+ * The component using this hook must render the attached canvas on the same mount.
+ * Pass the same injected clock used by the game Controller in deterministic tests.
+ */
+declare function useGameCanvas<TState>({ canvasRef, read, draw, clock, maxDeltaMs, }: UseGameCanvasOptions<TState>): void;
+
+export { type DisposableGameController, type GameCanvasFrame, GameClock, type SubscribableGameController, type UseGameCanvasOptions, useGameCanvas, useGameController, useOwnedGameController };

package/dist/react/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   browserGameClock: () => browserGameClock,
+  useGameCanvas: () => useGameCanvas,
   useGameController: () => useGameController,
   useOwnedGameController: () => useOwnedGameController
 });
@@ -109,9 +110,59 @@ function useSnapshotIntegrityCheck(game) {
     });
   }, [game]);
 }
+
+// src/react/use-game-canvas.ts
+var import_react3 = require("react");
+function useGameCanvas({
+  canvasRef,
+  read,
+  draw,
+  clock = browserGameClock,
+  maxDeltaMs = 50
+}) {
+  const readRef = (0, import_react3.useRef)(read);
+  const drawRef = (0, import_react3.useRef)(draw);
+  readRef.current = read;
+  drawRef.current = draw;
+  (0, import_react3.useEffect)(() => {
+    const canvas = canvasRef.current;
+    const context = canvas?.getContext("2d");
+    if (!canvas || !context) {
+      throw codedError(
+        "CANVAS_2D_CONTEXT_UNAVAILABLE",
+        "useGameCanvas found no 2D context: the attached <canvas> must be rendered on the same mount as the hook (never conditionally or one tick later). Mount the hook and its <canvas> together in one child component."
+      );
+    }
+    let active = true;
+    let frameId = 0;
+    let previousTimestamp = clock.now();
+    const renderFrame = (timestamp) => {
+      if (!active) return;
+      const deltaMs = Math.max(
+        0,
+        Math.min(maxDeltaMs, timestamp - previousTimestamp)
+      );
+      previousTimestamp = timestamp;
+      drawRef.current({
+        canvas,
+        context,
+        state: readRef.current(),
+        timestamp,
+        deltaMs
+      });
+      frameId = clock.requestFrame(renderFrame);
+    };
+    frameId = clock.requestFrame(renderFrame);
+    return () => {
+      active = false;
+      clock.cancelFrame(frameId);
+    };
+  }, [canvasRef, clock, maxDeltaMs]);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   browserGameClock,
+  useGameCanvas,
   useGameController,
   useOwnedGameController
 });

package/dist/react/index.mjs

@@ -81,8 +81,58 @@ function useSnapshotIntegrityCheck(game) {
     });
   }, [game]);
 }
+
+// src/react/use-game-canvas.ts
+import { useEffect as useEffect3, useRef as useRef3 } from "react";
+function useGameCanvas({
+  canvasRef,
+  read,
+  draw,
+  clock = browserGameClock,
+  maxDeltaMs = 50
+}) {
+  const readRef = useRef3(read);
+  const drawRef = useRef3(draw);
+  readRef.current = read;
+  drawRef.current = draw;
+  useEffect3(() => {
+    const canvas = canvasRef.current;
+    const context = canvas?.getContext("2d");
+    if (!canvas || !context) {
+      throw codedError(
+        "CANVAS_2D_CONTEXT_UNAVAILABLE",
+        "useGameCanvas found no 2D context: the attached <canvas> must be rendered on the same mount as the hook (never conditionally or one tick later). Mount the hook and its <canvas> together in one child component."
+      );
+    }
+    let active = true;
+    let frameId = 0;
+    let previousTimestamp = clock.now();
+    const renderFrame = (timestamp) => {
+      if (!active) return;
+      const deltaMs = Math.max(
+        0,
+        Math.min(maxDeltaMs, timestamp - previousTimestamp)
+      );
+      previousTimestamp = timestamp;
+      drawRef.current({
+        canvas,
+        context,
+        state: readRef.current(),
+        timestamp,
+        deltaMs
+      });
+      frameId = clock.requestFrame(renderFrame);
+    };
+    frameId = clock.requestFrame(renderFrame);
+    return () => {
+      active = false;
+      clock.cancelFrame(frameId);
+    };
+  }, [canvasRef, clock, maxDeltaMs]);
+}
 export {
   browserGameClock,
+  useGameCanvas,
   useGameController,
   useOwnedGameController
 };

package/dist/react/testing.d.mts

@@ -22,6 +22,9 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+/** Return recorded 2D drawing calls in JSDOM; real browser canvases return zero. */
+declare function getJSDOMCanvasDrawCallCount(canvas: HTMLCanvasElement): number;
+
 interface ReactFailureEntry {
     code: string;
     message: string;
@@ -166,4 +169,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, getJSDOMCanvasDrawCallCount, playthroughTest };

package/dist/react/testing.d.ts

@@ -22,6 +22,9 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+/** Return recorded 2D drawing calls in JSDOM; real browser canvases return zero. */
+declare function getJSDOMCanvasDrawCallCount(canvas: HTMLCanvasElement): number;
+
 interface ReactFailureEntry {
     code: string;
     message: string;
@@ -166,4 +169,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, getJSDOMCanvasDrawCallCount, playthroughTest };

package/dist/react/testing.js

@@ -32,6 +32,7 @@ var testing_exports = {};
 __export(testing_exports, {
   ManualGameClock: () => ManualGameClock,
   auditReactPlaythroughRun: () => auditReactPlaythroughRun,
+  getJSDOMCanvasDrawCallCount: () => getJSDOMCanvasDrawCallCount,
   playthroughTest: () => playthroughTest
 });
 module.exports = __toCommonJS(testing_exports);
@@ -91,6 +92,18 @@ var ManualGameClock = class {
   }
 };
 
+// src/testing/jsdom-canvas.ts
+var registryKey = /* @__PURE__ */ Symbol.for("miaoda-game-devkit:jsdom-canvas-registry");
+var registryScope = globalThis;
+var registry = registryScope[registryKey] ??= {
+  contexts: /* @__PURE__ */ new WeakMap(),
+  drawCallCounts: /* @__PURE__ */ new WeakMap()
+};
+var { contexts, drawCallCounts } = registry;
+function getJSDOMCanvasDrawCallCount(canvas) {
+  return drawCallCounts.get(canvas) ?? 0;
+}
+
 // src/react/react-playthrough.ts
 var import_react2 = require("@testing-library/react");
 var import_user_event = __toESM(require("@testing-library/user-event"));
@@ -775,5 +788,6 @@ function auditReactPlaythroughRun(tests) {
 0 && (module.exports = {
   ManualGameClock,
   auditReactPlaythroughRun,
+  getJSDOMCanvasDrawCallCount,
   playthroughTest
 });

package/dist/react/testing.mjs

@@ -53,6 +53,18 @@ var ManualGameClock = class {
   }
 };
 
+// src/testing/jsdom-canvas.ts
+var registryKey = /* @__PURE__ */ Symbol.for("miaoda-game-devkit:jsdom-canvas-registry");
+var registryScope = globalThis;
+var registry = registryScope[registryKey] ??= {
+  contexts: /* @__PURE__ */ new WeakMap(),
+  drawCallCounts: /* @__PURE__ */ new WeakMap()
+};
+var { contexts, drawCallCounts } = registry;
+function getJSDOMCanvasDrawCallCount(canvas) {
+  return drawCallCounts.get(canvas) ?? 0;
+}
+
 // src/react/react-playthrough.ts
 import { render } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
@@ -736,5 +748,6 @@ function auditReactPlaythroughRun(tests) {
 export {
   ManualGameClock,
   auditReactPlaythroughRun,
+  getJSDOMCanvasDrawCallCount,
   playthroughTest
 };

package/dist/react/vitest-config.js

@@ -1059,6 +1059,22 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+var KNOWN_PER_FRAME_CANVAS_DEPENDENCIES = /* @__PURE__ */ new Set([
+  "ball",
+  "bricks",
+  "enemies",
+  "entities",
+  "entity",
+  "elapsedMs",
+  "elapsedTimeMs",
+  "hoveredCell",
+  "paddle",
+  "particles",
+  "player",
+  "projectiles",
+  "snapshot",
+  "state"
+]);
 function runnableTestFiles(root, directory = (0, import_node_path2.join)(root, "tests")) {
   if (!(0, import_node_fs.existsSync)(directory)) return [];
   const files = [];
@@ -1152,6 +1168,88 @@ function containsAny(values, expected) {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function visitAst(value, visitor) {
+  if (Array.isArray(value)) {
+    for (const item of value) visitAst(item, visitor);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (typeof value.type === "string") visitor(value);
+  for (const child of Object.values(value)) visitAst(child, visitor);
+}
+function identifierName(value) {
+  return isRecord(value) && value.type === "Identifier" && typeof value.name === "string" ? value.name : void 0;
+}
+function memberPath(value) {
+  if (!isRecord(value)) return [];
+  const identifier = identifierName(value);
+  if (identifier) return [identifier];
+  if (value.type !== "MemberExpression") return [];
+  return [...memberPath(value.object), ...identifierName(value.property) ? [identifierName(value.property)] : []];
+}
+function hasRepeatedAnimationFrameCallback(value) {
+  const callbackCounts = /* @__PURE__ */ new Map();
+  visitAst(value, (node) => {
+    if (node.type !== "CallExpression") return;
+    if (identifierName(node.callee) !== "requestAnimationFrame") return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    const callback = identifierName(arguments_[0]);
+    if (!callback) return;
+    callbackCounts.set(callback, (callbackCounts.get(callback) ?? 0) + 1);
+  });
+  return [...callbackCounts.values()].some((count) => count >= 2);
+}
+function reactEffectNames(file, source) {
+  const names = /* @__PURE__ */ new Set(["useEffect"]);
+  for (const declaration of staticImports(file, source)) {
+    if (declaration.moduleRequest.value !== "react") continue;
+    for (const entry of declaration.entries) {
+      if (entry.importName.kind === "Name" && entry.importName.name === "useEffect") {
+        names.add(entry.localName.value);
+      }
+    }
+  }
+  return names;
+}
+function isReactEffectCall(node, effectNames) {
+  if (node.type !== "CallExpression") return false;
+  const directName = identifierName(node.callee);
+  if (directName && effectNames.has(directName)) return true;
+  const path = memberPath(node.callee);
+  return path.length === 2 && path[1] === "useEffect";
+}
+function canvasRafDependencyIssues(file, source, projectRoot) {
+  const ownsCanvas = /<canvas\b|createElement\s*\(\s*["']canvas["']|getContext\s*\(\s*["']2d["']/.test(
+    source
+  );
+  if (!ownsCanvas) return [];
+  const issues = [];
+  const effectNames = reactEffectNames(file, source);
+  visitAst(parseSource(file, source).program, (node) => {
+    if (!isReactEffectCall(node, effectNames)) return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    if (!hasRepeatedAnimationFrameCallback(arguments_[0])) return;
+    const dependencies = arguments_[1];
+    if (!isRecord(dependencies) || dependencies.type !== "ArrayExpression") return;
+    const elements = Array.isArray(dependencies.elements) ? dependencies.elements : [];
+    const unsafe = elements.filter(
+      (element) => memberPath(element).some((name) => KNOWN_PER_FRAME_CANVAS_DEPENDENCIES.has(name))
+    );
+    if (unsafe.length === 0) return;
+    const labels = unsafe.map((element) => {
+      if (!isRecord(element) || typeof element.start !== "number" || typeof element.end !== "number") {
+        return "dynamic state";
+      }
+      return source.slice(element.start, element.end);
+    });
+    const line = typeof node.start === "number" ? source.slice(0, node.start).split("\n").length : 1;
+    const path = (0, import_node_path2.relative)(projectRoot, file).replaceAll("\\", "/");
+    issues.push(
+      `CANVAS_RAF_DYNAMIC_DEPENDENCY ${path}:${line}: a recurring frame loop depends on ${labels.join(", ")}. React cleanup cancels and recreates the pending frame whenever these values change, which can freeze Canvas while HUD state keeps updating. Keep the loop effect stable and read changing state through a ref; a plain app-owned 2D Canvas may optionally use useGameCanvas from miaoda-game-devkit/react.`
+    );
+  });
+  return issues;
+}
 function containsObserveProperty(value) {
   if (Array.isArray(value)) return value.some(containsObserveProperty);
   if (!isRecord(value)) return false;
@@ -1167,17 +1265,20 @@ function declaresObserve(file, source) {
 function auditReactAuthoritativePlaythrough(projectRoot) {
   const clockFiles = [];
   const controllerFiles = [];
+  const canvasRafIssues = [];
   const productionFiles = sourceFiles(projectRoot);
   for (const file of productionFiles) {
+    const source = (0, import_node_fs.readFileSync)(file, "utf8");
     const imports = namedImports(
       file,
-      (0, import_node_fs.readFileSync)(file, "utf8"),
+      source,
       REACT_RUNTIME_ENTRY
     );
     const projectPath = (0, import_node_path2.relative)(projectRoot, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
     if (containsAny(imports, CONTROLLER_IMPORTS))
       controllerFiles.push(projectPath);
+    canvasRafIssues.push(...canvasRafDependencyIssues(file, source, projectRoot));
   }
   const appPath = (0, import_node_path2.join)(projectRoot, PRODUCTION_APP);
   const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
@@ -1188,6 +1289,7 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
     (file) => importsExampleAlias(file, (0, import_node_fs.readFileSync)(file, "utf8"))
   ).map((file) => (0, import_node_path2.relative)(projectRoot, file).replaceAll("\\", "/"));
   const issues = [];
+  issues.push(...canvasRafIssues);
   if (staleExampleTestFiles.length > 0) {
     issues.push(
       `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
@@ -1201,7 +1303,8 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
       controllerFiles,
       productionEntryExists,
       productionUsesExample,
-      staleExampleTestFiles
+      staleExampleTestFiles,
+      canvasRafIssues
     };
   }
   const testPath = (0, import_node_path2.join)(projectRoot, PRODUCTION_PLAYTHROUGH);
@@ -1229,7 +1332,8 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
     controllerFiles,
     productionEntryExists,
     productionUsesExample,
-    staleExampleTestFiles
+    staleExampleTestFiles,
+    canvasRafIssues
   };
 }
 

package/dist/react/vitest-config.mjs

@@ -1025,6 +1025,22 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "useOwnedGameController"
 ]);
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+var KNOWN_PER_FRAME_CANVAS_DEPENDENCIES = /* @__PURE__ */ new Set([
+  "ball",
+  "bricks",
+  "enemies",
+  "entities",
+  "entity",
+  "elapsedMs",
+  "elapsedTimeMs",
+  "hoveredCell",
+  "paddle",
+  "particles",
+  "player",
+  "projectiles",
+  "snapshot",
+  "state"
+]);
 function runnableTestFiles(root, directory = join(root, "tests")) {
   if (!existsSync(directory)) return [];
   const files = [];
@@ -1118,6 +1134,88 @@ function containsAny(values, expected) {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function visitAst(value, visitor) {
+  if (Array.isArray(value)) {
+    for (const item of value) visitAst(item, visitor);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (typeof value.type === "string") visitor(value);
+  for (const child of Object.values(value)) visitAst(child, visitor);
+}
+function identifierName(value) {
+  return isRecord(value) && value.type === "Identifier" && typeof value.name === "string" ? value.name : void 0;
+}
+function memberPath(value) {
+  if (!isRecord(value)) return [];
+  const identifier = identifierName(value);
+  if (identifier) return [identifier];
+  if (value.type !== "MemberExpression") return [];
+  return [...memberPath(value.object), ...identifierName(value.property) ? [identifierName(value.property)] : []];
+}
+function hasRepeatedAnimationFrameCallback(value) {
+  const callbackCounts = /* @__PURE__ */ new Map();
+  visitAst(value, (node) => {
+    if (node.type !== "CallExpression") return;
+    if (identifierName(node.callee) !== "requestAnimationFrame") return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    const callback = identifierName(arguments_[0]);
+    if (!callback) return;
+    callbackCounts.set(callback, (callbackCounts.get(callback) ?? 0) + 1);
+  });
+  return [...callbackCounts.values()].some((count) => count >= 2);
+}
+function reactEffectNames(file, source) {
+  const names = /* @__PURE__ */ new Set(["useEffect"]);
+  for (const declaration of staticImports(file, source)) {
+    if (declaration.moduleRequest.value !== "react") continue;
+    for (const entry of declaration.entries) {
+      if (entry.importName.kind === "Name" && entry.importName.name === "useEffect") {
+        names.add(entry.localName.value);
+      }
+    }
+  }
+  return names;
+}
+function isReactEffectCall(node, effectNames) {
+  if (node.type !== "CallExpression") return false;
+  const directName = identifierName(node.callee);
+  if (directName && effectNames.has(directName)) return true;
+  const path = memberPath(node.callee);
+  return path.length === 2 && path[1] === "useEffect";
+}
+function canvasRafDependencyIssues(file, source, projectRoot) {
+  const ownsCanvas = /<canvas\b|createElement\s*\(\s*["']canvas["']|getContext\s*\(\s*["']2d["']/.test(
+    source
+  );
+  if (!ownsCanvas) return [];
+  const issues = [];
+  const effectNames = reactEffectNames(file, source);
+  visitAst(parseSource(file, source).program, (node) => {
+    if (!isReactEffectCall(node, effectNames)) return;
+    const arguments_ = Array.isArray(node.arguments) ? node.arguments : [];
+    if (!hasRepeatedAnimationFrameCallback(arguments_[0])) return;
+    const dependencies = arguments_[1];
+    if (!isRecord(dependencies) || dependencies.type !== "ArrayExpression") return;
+    const elements = Array.isArray(dependencies.elements) ? dependencies.elements : [];
+    const unsafe = elements.filter(
+      (element) => memberPath(element).some((name) => KNOWN_PER_FRAME_CANVAS_DEPENDENCIES.has(name))
+    );
+    if (unsafe.length === 0) return;
+    const labels = unsafe.map((element) => {
+      if (!isRecord(element) || typeof element.start !== "number" || typeof element.end !== "number") {
+        return "dynamic state";
+      }
+      return source.slice(element.start, element.end);
+    });
+    const line = typeof node.start === "number" ? source.slice(0, node.start).split("\n").length : 1;
+    const path = relative2(projectRoot, file).replaceAll("\\", "/");
+    issues.push(
+      `CANVAS_RAF_DYNAMIC_DEPENDENCY ${path}:${line}: a recurring frame loop depends on ${labels.join(", ")}. React cleanup cancels and recreates the pending frame whenever these values change, which can freeze Canvas while HUD state keeps updating. Keep the loop effect stable and read changing state through a ref; a plain app-owned 2D Canvas may optionally use useGameCanvas from miaoda-game-devkit/react.`
+    );
+  });
+  return issues;
+}
 function containsObserveProperty(value) {
   if (Array.isArray(value)) return value.some(containsObserveProperty);
   if (!isRecord(value)) return false;
@@ -1133,17 +1231,20 @@ function declaresObserve(file, source) {
 function auditReactAuthoritativePlaythrough(projectRoot) {
   const clockFiles = [];
   const controllerFiles = [];
+  const canvasRafIssues = [];
   const productionFiles = sourceFiles(projectRoot);
   for (const file of productionFiles) {
+    const source = readFileSync(file, "utf8");
     const imports = namedImports(
       file,
-      readFileSync(file, "utf8"),
+      source,
       REACT_RUNTIME_ENTRY
     );
     const projectPath = relative2(projectRoot, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
     if (containsAny(imports, CONTROLLER_IMPORTS))
       controllerFiles.push(projectPath);
+    canvasRafIssues.push(...canvasRafDependencyIssues(file, source, projectRoot));
   }
   const appPath = join(projectRoot, PRODUCTION_APP);
   const productionEntryExists = existsSync(appPath);
@@ -1154,6 +1255,7 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
     (file) => importsExampleAlias(file, readFileSync(file, "utf8"))
   ).map((file) => relative2(projectRoot, file).replaceAll("\\", "/"));
   const issues = [];
+  issues.push(...canvasRafIssues);
   if (staleExampleTestFiles.length > 0) {
     issues.push(
       `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
@@ -1167,7 +1269,8 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
       controllerFiles,
       productionEntryExists,
       productionUsesExample,
-      staleExampleTestFiles
+      staleExampleTestFiles,
+      canvasRafIssues
     };
   }
   const testPath = join(projectRoot, PRODUCTION_PLAYTHROUGH);
@@ -1195,7 +1298,8 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
     controllerFiles,
     productionEntryExists,
     productionUsesExample,
-    staleExampleTestFiles
+    staleExampleTestFiles,
+    canvasRafIssues
   };
 }
 

package/dist/react/vitest-setup.js

@@ -269,7 +269,27 @@ function getJSDOMWebGLContext(canvas, options) {
 }
 
 // src/testing/jsdom-canvas.ts
-var contexts2 = /* @__PURE__ */ new WeakMap();
+var registryKey = /* @__PURE__ */ Symbol.for("miaoda-game-devkit:jsdom-canvas-registry");
+var registryScope = globalThis;
+var registry = registryScope[registryKey] ??= {
+  contexts: /* @__PURE__ */ new WeakMap(),
+  drawCallCounts: /* @__PURE__ */ new WeakMap()
+};
+var { contexts: contexts2, drawCallCounts } = registry;
+var DRAW_METHODS = /* @__PURE__ */ new Set([
+  "clearRect",
+  "drawImage",
+  "fill",
+  "fillRect",
+  "fillText",
+  "putImageData",
+  "stroke",
+  "strokeRect",
+  "strokeText"
+]);
+function getJSDOMCanvasDrawCallCount(canvas) {
+  return drawCallCounts.get(canvas) ?? 0;
+}
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -310,7 +330,12 @@ function createCanvasContext(canvas) {
         return () => ({ addColorStop() {
         } });
       }
-      return () => void 0;
+      return () => {
+        if (typeof property === "string" && DRAW_METHODS.has(property)) {
+          drawCallCounts.set(canvas, getJSDOMCanvasDrawCallCount(canvas) + 1);
+        }
+        return void 0;
+      };
     }
   });
   return context;
@@ -325,6 +350,7 @@ function installJSDOMCanvasContext() {
     if (existing) return existing;
     const context = createCanvasContext(this);
     contexts2.set(this, context);
+    drawCallCounts.set(this, 0);
     return context;
   };
 }

package/dist/react/vitest-setup.mjs

@@ -267,7 +267,27 @@ function getJSDOMWebGLContext(canvas, options) {
 }
 
 // src/testing/jsdom-canvas.ts
-var contexts2 = /* @__PURE__ */ new WeakMap();
+var registryKey = /* @__PURE__ */ Symbol.for("miaoda-game-devkit:jsdom-canvas-registry");
+var registryScope = globalThis;
+var registry = registryScope[registryKey] ??= {
+  contexts: /* @__PURE__ */ new WeakMap(),
+  drawCallCounts: /* @__PURE__ */ new WeakMap()
+};
+var { contexts: contexts2, drawCallCounts } = registry;
+var DRAW_METHODS = /* @__PURE__ */ new Set([
+  "clearRect",
+  "drawImage",
+  "fill",
+  "fillRect",
+  "fillText",
+  "putImageData",
+  "stroke",
+  "strokeRect",
+  "strokeText"
+]);
+function getJSDOMCanvasDrawCallCount(canvas) {
+  return drawCallCounts.get(canvas) ?? 0;
+}
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -308,7 +328,12 @@ function createCanvasContext(canvas) {
         return () => ({ addColorStop() {
         } });
       }
-      return () => void 0;
+      return () => {
+        if (typeof property === "string" && DRAW_METHODS.has(property)) {
+          drawCallCounts.set(canvas, getJSDOMCanvasDrawCallCount(canvas) + 1);
+        }
+        return void 0;
+      };
     }
   });
   return context;
@@ -323,6 +348,7 @@ function installJSDOMCanvasContext() {
     if (existing) return existing;
     const context = createCanvasContext(this);
     contexts2.set(this, context);
+    drawCallCounts.set(this, 0);
     return context;
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -164,46 +164,8 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@testing-library/jest-dom": "7.0.0",
-    "@testing-library/react": "16.3.2",
-    "@testing-library/user-event": "14.6.1",
-    "@types/eslint": "^9.6.1",
-    "@types/estree": "^1.0.9",
-    "@types/node": "^24.13.3",
-    "@types/react": "19.2.10",
-    "clean-publish": "^6.0.5",
-    "phaser": "4.2.1",
-    "phaser4-rex-plugins": "4.2.0",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vite": "8.2.0"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
-  },
-  "clean-publish": {
-    "fields": [
-      "devDependencies",
-      "scripts"
-    ]
-  },
-  "scripts": {
-    "build": "tsup",
-    "release": "pnpm run test && clean-publish",
-    "release:dry-run": "pnpm run test && clean-publish --dry-run",
-    "release:beta": "pnpm run test && npm version prerelease --preid=beta && clean-publish --tag beta",
-    "release:patch": "pnpm run test && npm version patch && clean-publish",
-    "release:minor": "pnpm run test && npm version minor && clean-publish",
-    "release:major": "pnpm run test && npm version major && clean-publish",
-    "lint": "biome lint --config-path biome-config.json src && node scripts/check-line-length.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "pnpm run build && pnpm run test:contracts && pnpm run test:mechanics && pnpm run test:published",
-    "test:contracts": "vitest run --config dist/lint/contracts.config.mjs",
-    "test:mechanics": "node --test mechanics/materialize-game-mechanics-source.test.mjs",
-    "test:published": "node scripts/test-published-package.mjs"
   }
-}
+}