miaoda-game-devkit 0.9.0 → 0.10.1

package/README.md

@@ -107,12 +107,19 @@ Devkit 发布统一的 `miaoda` 命令。裸 `miaoda-game-*` 包名默认从公
 
 ```bash
 pnpm exec miaoda mechanics --help
+pnpm exec miaoda mechanics list
+pnpm exec miaoda mechanics list --domain=grid --engine=react
 pnpm exec miaoda mechanics add miaoda-game-beam-core
 pnpm exec miaoda mechanics add miaoda-game-beam-core@1.2.3 \
   --source-index=https://public.example.com/game-mechanics/stable.json
 pnpm exec miaoda mechanics status
 ```
 
+`list` 只列出稳定索引中实际可安装的包，并从 Devkit 自带的 capabilities JSON 动态汇总
+domain 的 `owns` 能力；带筛选时会显示包负责和不负责的边界、使用指引及可测试性。它不会安装
+源码，也不会维护另一份容易过时的文字目录。先选择覆盖需求的最小包集合，再单独运行 `add`，
+成功后阅读生成的 `src/game-mechanics/README.md`。
+
 默认索引是 `https://resource-static.bj.bcebos.com/miaoda-game/stable.json`。只有调试、测试或
 私有镜像场景才需要通过 `--source-index` 或 `MIAODA_MECHANICS_INDEX_URL` 覆盖。
 

package/dist/lint/setup.mjs

@@ -1,8 +1,92 @@
 // src/lint/setup.ts
 import { afterEach } from "vitest";
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -49,12 +133,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/dist/react/vitest-config.js

@@ -1452,7 +1452,36 @@ function resolvePhaser3BrowserEntry(projectRoot) {
     return void 0;
   }
 }
+var COVERAGE_INCLUDE = [
+  "src/game/core/**/*.{ts,tsx}",
+  "src/game/runtime/**/*.{ts,tsx}"
+];
+var COVERAGE_EXCLUDE = [
+  "src/game/{core,runtime}/**/*.d.ts",
+  "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
+];
+var GATE_SCAN_EXCLUDE = [
+  "src/**/*.d.ts",
+  "src/**/*.{spec,test}.{ts,tsx}",
+  "src/game/example/**"
+];
+function assertCoverageScopeIsPopulated(projectRoot) {
+  const scan = (pattern) => (0, import_node_fs3.globSync)(pattern, { cwd: projectRoot, exclude: GATE_SCAN_EXCLUDE });
+  if (COVERAGE_INCLUDE.flatMap(scan).length > 0) return;
+  const misplaced = scan("src/**/{core,runtime}/**/*.{ts,tsx}");
+  if (misplaced.length === 0) return;
+  throw new Error(
+    [
+      "The coverage gate matched no source file, so it proves nothing.",
+      "Deterministic rules belong in src/game/core/; the loop, scheduling,",
+      "Controller, and Telemetry belong in src/game/runtime/.",
+      "Move these files under those two directories:",
+      ...misplaced.slice(0, 10).map((file) => `  ${file}`)
+    ].join("\n")
+  );
+}
 function defineReactGameVitestConfig(options) {
+  assertCoverageScopeIsPopulated(options.projectRoot);
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return (0, import_config.defineConfig)({
     // Keep discovery and dependency resolution anchored to the generated app even
@@ -1495,14 +1524,8 @@ function defineReactGameVitestConfig(options) {
       clearMocks: true,
       coverage: {
         provider: "v8",
-        include: [
-          "src/game/core/**/*.{ts,tsx}",
-          "src/game/runtime/**/*.{ts,tsx}"
-        ],
-        exclude: [
-          "src/game/{core,runtime}/**/*.d.ts",
-          "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
-        ],
+        include: COVERAGE_INCLUDE,
+        exclude: COVERAGE_EXCLUDE,
         reporter: ["text-summary"],
         thresholds: {
           perFile: true,

package/dist/react/vitest-config.mjs

@@ -1,5 +1,5 @@
 // src/react-vitest-config.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, globSync, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, resolve as resolve3 } from "path";
 import { defineConfig } from "vitest/config";
 
@@ -1418,7 +1418,36 @@ function resolvePhaser3BrowserEntry(projectRoot) {
     return void 0;
   }
 }
+var COVERAGE_INCLUDE = [
+  "src/game/core/**/*.{ts,tsx}",
+  "src/game/runtime/**/*.{ts,tsx}"
+];
+var COVERAGE_EXCLUDE = [
+  "src/game/{core,runtime}/**/*.d.ts",
+  "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
+];
+var GATE_SCAN_EXCLUDE = [
+  "src/**/*.d.ts",
+  "src/**/*.{spec,test}.{ts,tsx}",
+  "src/game/example/**"
+];
+function assertCoverageScopeIsPopulated(projectRoot) {
+  const scan = (pattern) => globSync(pattern, { cwd: projectRoot, exclude: GATE_SCAN_EXCLUDE });
+  if (COVERAGE_INCLUDE.flatMap(scan).length > 0) return;
+  const misplaced = scan("src/**/{core,runtime}/**/*.{ts,tsx}");
+  if (misplaced.length === 0) return;
+  throw new Error(
+    [
+      "The coverage gate matched no source file, so it proves nothing.",
+      "Deterministic rules belong in src/game/core/; the loop, scheduling,",
+      "Controller, and Telemetry belong in src/game/runtime/.",
+      "Move these files under those two directories:",
+      ...misplaced.slice(0, 10).map((file) => `  ${file}`)
+    ].join("\n")
+  );
+}
 function defineReactGameVitestConfig(options) {
+  assertCoverageScopeIsPopulated(options.projectRoot);
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return defineConfig({
     // Keep discovery and dependency resolution anchored to the generated app even
@@ -1461,14 +1490,8 @@ function defineReactGameVitestConfig(options) {
       clearMocks: true,
       coverage: {
         provider: "v8",
-        include: [
-          "src/game/core/**/*.{ts,tsx}",
-          "src/game/runtime/**/*.{ts,tsx}"
-        ],
-        exclude: [
-          "src/game/{core,runtime}/**/*.d.ts",
-          "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
-        ],
+        include: COVERAGE_INCLUDE,
+        exclude: COVERAGE_EXCLUDE,
         reporter: ["text-summary"],
         thresholds: {
           perFile: true,

package/dist/react/vitest-setup.js

@@ -184,8 +184,92 @@ function runtimeFailureError(code, value) {
   return error;
 }
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -232,12 +316,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/dist/react/vitest-setup.mjs

@@ -182,8 +182,92 @@ function runtimeFailureError(code, value) {
   return error;
 }
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -230,12 +314,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/mechanics/list-game-mechanics-source.mjs

@@ -0,0 +1,254 @@
+import { readFileSync } from 'node:fs';
+import { listIndexedMechanics } from './resolve-game-mechanics-source-index.mjs';
+
+const ENGINES = new Set(['neutral', 'react', 'phaser', 'cocos']);
+const FILTER_NAMES = ['domain', 'engine', 'owns'];
+
+function readCapabilityDocument(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`miaoda mechanics list: cannot read capabilities JSON: ${detail}`);
+  }
+}
+
+function optionValue(argv, name) {
+  const prefix = `--${name}=`;
+  const argument = argv.find((value) => value.startsWith(prefix));
+  return argument?.slice(prefix.length).trim();
+}
+
+export function parseMechanicListArguments(argv, defaultSourceIndexUrl) {
+  const allowed = new Set(['--json', '--help', '-h']);
+  for (const argument of argv.slice(1)) {
+    if (allowed.has(argument)) {
+      continue;
+    }
+    if (['--domain=', '--engine=', '--owns=', '--source-index='].some((prefix) => argument.startsWith(prefix))) {
+      continue;
+    }
+    throw new Error(
+      `miaoda mechanics list: unsupported argument ${JSON.stringify(argument)}. ` +
+        'Use --domain=<domain>, --engine=<engine>, --owns=<capability>, or --json.',
+    );
+  }
+  const filters = Object.fromEntries(
+    FILTER_NAMES.map((name) => [name, optionValue(argv, name)]).filter(([, value]) => Boolean(value)),
+  );
+  if (filters.engine && !ENGINES.has(filters.engine)) {
+    throw new Error(
+      `miaoda mechanics list: engine must be neutral, react, phaser, or cocos; received ${filters.engine}.`,
+    );
+  }
+  return {
+    filters,
+    json: argv.includes('--json'),
+    sourceIndexUrl: optionValue(argv, 'source-index') || defaultSourceIndexUrl,
+  };
+}
+
+function packageMatches(entry, filters) {
+  if (!entry.annotated) {
+    return Object.keys(filters).length === 0;
+  }
+  if (filters.domain && !entry.domains.includes(filters.domain)) {
+    return false;
+  }
+  if (filters.owns && !entry.provides.includes(filters.owns)) {
+    return false;
+  }
+  if (filters.engine) {
+    const compatible =
+      filters.engine === 'neutral'
+        ? entry.engine === 'neutral'
+        : entry.engine === 'neutral' || entry.engine === filters.engine;
+    if (!compatible) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function packageEntry(name, version, capability, installableNames) {
+  if (!capability) {
+    return { name, version, annotated: false };
+  }
+  return {
+    name,
+    version,
+    annotated: true,
+    engine: capability.engine,
+    domains: capability.domains,
+    provides: capability.owns,
+    leavesOutside: capability.doesNotOwn,
+    compatibleWith: capability.compatibleWith.filter((candidate) => installableNames.has(candidate)),
+    useFor: capability.guidance?.useFor ?? [],
+    keepOutside: capability.guidance?.keepOutside ?? [],
+    rules: capability.guidance?.rules ?? [],
+    useInsteadWhen: capability.useInsteadWhen,
+    testability: capability.testability,
+    persistence: capability.persistence,
+  };
+}
+
+function summarizeDomains(packages) {
+  const domains = new Map();
+  for (const entry of packages) {
+    if (!entry.annotated) {
+      continue;
+    }
+    for (const domain of entry.domains) {
+      const summary = domains.get(domain) ?? { name: domain, packageNames: new Set(), provides: new Set() };
+      summary.packageNames.add(entry.name);
+      for (const capability of entry.provides) {
+        summary.provides.add(capability);
+      }
+      domains.set(domain, summary);
+    }
+  }
+  return [...domains.values()]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((summary) => ({
+      name: summary.name,
+      packageCount: summary.packageNames.size,
+      provides: [...summary.provides].sort(),
+    }));
+}
+
+export function createMechanicCatalog(indexedPackages, capabilityDocument, filters = {}, sourceIndexUrl) {
+  const installableNames = new Set(indexedPackages.map((entry) => entry.name));
+  const allPackages = indexedPackages
+    .map(({ name, version }) =>
+      packageEntry(name, version, capabilityDocument.packages?.[name], installableNames),
+    )
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const matchedPackages = allPackages.filter((entry) => packageMatches(entry, filters));
+  const matchedNames = new Set(matchedPackages.map((entry) => entry.name));
+  const packages = matchedPackages.map((entry) => {
+    if (!entry.annotated) {
+      return entry;
+    }
+    return {
+      ...entry,
+      compatibleWith: entry.compatibleWith.filter((candidate) => matchedNames.has(candidate)),
+    };
+  });
+  const filtersActive = Object.keys(filters).length > 0;
+  return {
+    schemaVersion: 1,
+    sourceIndexUrl,
+    filters,
+    installablePackageCount: allPackages.length,
+    unannotatedPackageCount: allPackages.filter((entry) => !entry.annotated).length,
+    domains: summarizeDomains(filtersActive ? packages : allPackages),
+    packages,
+  };
+}
+
+export async function listMechanics({ sourceIndexUrl, capabilityPath, filters }) {
+  const indexed = await listIndexedMechanics(sourceIndexUrl);
+  const capabilityDocument = readCapabilityDocument(capabilityPath);
+  return createMechanicCatalog(indexed.packages, capabilityDocument, filters, indexed.sourceIndexUrl);
+}
+
+function formatList(values) {
+  return values.length > 0 ? values.join(', ') : 'none declared';
+}
+
+function formatTestability(testability) {
+  if (!testability) {
+    return undefined;
+  }
+  return `observation=${testability.observation}; advance=${testability.advance}; ` +
+    `observe: ${testability.methods.observe}; exercise: ${testability.methods.advance}`;
+}
+
+function formatPackage(entry) {
+  if (!entry.annotated) {
+    return `${entry.name}@${entry.version}\n  Capability metadata: unavailable; inspect its README after add.`;
+  }
+  const lines = [
+    `${entry.name}@${entry.version} [${entry.engine}]`,
+    `  Provides: ${formatList(entry.provides)}`,
+    `  Leaves outside: ${formatList(entry.leavesOutside)}`,
+  ];
+  if (entry.useFor.length > 0) {
+    lines.push(`  Use for: ${entry.useFor.join(' ')}`);
+  }
+  if (entry.keepOutside.length > 0) {
+    lines.push(`  Keep outside: ${entry.keepOutside.join(' ')}`);
+  }
+  if (entry.rules.length > 0) {
+    lines.push(`  Rules: ${entry.rules.join(' ')}`);
+  }
+  if (entry.compatibleWith.length > 0) {
+    lines.push(`  Works with: ${entry.compatibleWith.join(', ')}`);
+  }
+  for (const alternative of entry.useInsteadWhen) {
+    lines.push(`  Use ${alternative.package} instead when: ${alternative.condition}`);
+  }
+  const testability = formatTestability(entry.testability);
+  if (testability) {
+    lines.push(`  Testability: ${testability}`);
+  }
+  return lines.join('\n');
+}
+
+function formatFilters(filters) {
+  const values = Object.entries(filters).map(([name, value]) => `${name}=${value}`);
+  return values.length > 0 ? values.join(', ') : 'none';
+}
+
+export function formatMechanicList(catalog, { json = false } = {}) {
+  if (json) {
+    return JSON.stringify(catalog, null, 2);
+  }
+  const filtersActive = Object.keys(catalog.filters).length > 0;
+  if (!filtersActive) {
+    const domainLines = catalog.domains.map((domain) => {
+      const preview = domain.provides.slice(0, 3).join(', ');
+      const remaining = Math.max(0, domain.provides.length - 3);
+      const suffix = remaining > 0 ? `, +${remaining} more` : '';
+      return `  ${domain.name} (${domain.packageCount}) — can provide: ${preview}${suffix}`;
+    });
+    const annotationNote =
+      catalog.unannotatedPackageCount > 0
+        ? `\n${catalog.unannotatedPackageCount} installable packages lack capability annotations.`
+        : '';
+    return `Installable Miaoda mechanic domains (${catalog.domains.length} domains, ` +
+      `${catalog.installablePackageCount} packages):\n${domainLines.join('\n')}${annotationNote}\n\n` +
+      'Next:\n' +
+      '  Rerun with --domain=<domain>, --engine=<react|phaser|cocos|neutral>, or --owns=<capability>.\n' +
+      '  Use --json for complete machine-readable facts. Do not install every match.';
+  }
+  if (catalog.packages.length === 0) {
+    return `No installable mechanics matched ${formatFilters(catalog.filters)}.\n` +
+      'Run "pnpm exec miaoda mechanics list" to inspect available domains and exact capability names.';
+  }
+  return `Matched ${catalog.packages.length} installable mechanic packages (${formatFilters(catalog.filters)}):\n\n` +
+    `${catalog.packages.map(formatPackage).join('\n\n')}\n\n` +
+    'Next:\n' +
+    '  Select the smallest set whose Provides entries own required mechanics, then run:\n' +
+    '  pnpm exec miaoda mechanics add <full miaoda-game-* names>\n' +
+    '  Run add by itself, then read src/game-mechanics/README.md before gameplay edits.';
+}
+
+export const LIST_HELP = `Usage: miaoda mechanics list [filters]
+
+Discover packages that are currently installable through the source index. Package
+meaning comes from the bundled capabilities JSON: owns becomes Provides, doesNotOwn
+becomes Leaves outside, and guidance/testability are shown when annotated. This command
+is read-only and never installs source.
+
+Without filters, list prints domain summaries with real owned-capability previews.
+With filters, it prints package versions and ownership boundaries. An engine filter
+includes engine-neutral cores plus adapters for that engine.
+
+Filters:
+  --domain=<domain>       Match one exact domain from the summary
+  --engine=<engine>       neutral, react, phaser, or cocos
+  --owns=<capability>     Match one exact owned-capability token
+  --json                  Emit complete machine-readable JSON
+  --source-index=<url>    Override the public stable.json URL
+  -h, --help              Show this help`;

package/mechanics/materialize-game-mechanics-source.mjs

@@ -16,6 +16,12 @@ import {
 } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  formatMechanicList,
+  LIST_HELP,
+  listMechanics,
+  parseMechanicListArguments,
+} from './list-game-mechanics-source.mjs';
 import {
   areIndexedPackageSpecs,
   cleanupIndexedMechanics,
@@ -657,6 +663,7 @@ Manage editable Miaoda game-mechanic TypeScript source in src/game-mechanics.
 
 Commands:
   add <package...>  Resolve packages from the source index and add editable source
+  list              Discover installable packages and their ownership boundaries
   status            Show clean, modified, or missing source packages
   help              Show this help
 
@@ -860,10 +867,24 @@ export async function main(argv = process.argv.slice(2)) {
   const mechanicsArguments = argv[0] === 'mechanics' ? argv.slice(1) : argv;
   const command = mechanicsArguments[0];
   const wantsHelp = mechanicsArguments.includes('--help') || mechanicsArguments.includes('-h');
-  if (!command || command === 'help' || (wantsHelp && !['add', 'status'].includes(command))) {
+  if (!command || command === 'help' || (wantsHelp && !['add', 'list', 'status'].includes(command))) {
     console.log(ROOT_HELP);
     return;
   }
+  if (command === 'list') {
+    if (wantsHelp) {
+      console.log(LIST_HELP);
+      return;
+    }
+    const options = parseMechanicListArguments(mechanicsArguments, DEFAULT_SOURCE_INDEX_URL);
+    const catalog = await listMechanics({
+      sourceIndexUrl: options.sourceIndexUrl,
+      capabilityPath,
+      filters: options.filters,
+    });
+    console.log(formatMechanicList(catalog, { json: options.json }));
+    return catalog;
+  }
   if (command === 'add') {
     if (wantsHelp) {
       console.log(ADD_HELP);

package/mechanics/resolve-game-mechanics-source-index.mjs

@@ -312,6 +312,20 @@ export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, sp
   }
 }
 
+export async function listIndexedMechanics(indexUrl) {
+  const loaded = await readIndex(indexUrl);
+  const packages = Object.keys(loaded.index.packages)
+    .sort()
+    .map((name) => {
+      const selected = selectVersion(loaded.index, name, undefined, loaded.indexUrl);
+      return { name: selected.name, version: selected.version };
+    });
+  return {
+    sourceIndexUrl: loaded.indexUrl,
+    packages,
+  };
+}
+
 export function cleanupIndexedMechanics(resolution) {
   if (resolution?.temporaryRoot) {
     rmSync(resolution.temporaryRoot, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",