@caperjs/core 0.1.1 → 0.2.0

package/build/internal/ast.mjs

@@ -0,0 +1,255 @@
+/**
+ * Everything caper's build plugins learn by reading source rather than running
+ * it: an oxc parse wrapper, plus the extractors discovery uses to find a file's
+ * exported constants, its default-exported class, and the object passed to
+ * `defineConfig`.
+ *
+ * Source is parsed rather than imported because importing a project's modules
+ * pulls in @caperjs/core, whose @pixi/sound and GSAP dependencies run
+ * browser-only side effects at module top level and throw under plain Node.
+ */
+import { parseSync } from 'oxc-parser';
+
+export const AST_NODE_TYPES = {
+  ArrayExpression: 'ArrayExpression',
+  CallExpression: 'CallExpression',
+  ClassDeclaration: 'ClassDeclaration',
+  ExportDefaultDeclaration: 'ExportDefaultDeclaration',
+  ExportNamedDeclaration: 'ExportNamedDeclaration',
+  Identifier: 'Identifier',
+  ImportDeclaration: 'ImportDeclaration',
+  Literal: 'Literal',
+  ObjectExpression: 'ObjectExpression',
+  Property: 'Property',
+  VariableDeclaration: 'VariableDeclaration',
+};
+
+/**
+ * Thin wrapper around oxc-parser that mirrors the shape we previously got
+ * from `@typescript-eslint/typescript-estree`: it returns the `Program`
+ * node directly, so `ast.body` / `for (const node of ast.body)` keeps working.
+ *
+ * Swapping `typescript-estree` (JS-written TS parser, ~500KB, slow) out for
+ * oxc-parser (Rust, bundled with Vite 8) was the biggest remaining DX win
+ * from the Phase 1b rolldown `PLUGIN_TIMINGS` report: the config/discovery
+ * AST parses are the hottest paths in the dev-server startup and HMR.
+ */
+export function parse(content, _options = {}) {
+  const result = parseSync('caper-discovery.ts', content, {
+    lang: 'ts',
+    sourceType: 'module',
+  });
+  if (result.errors && result.errors.length > 0) {
+    const first = result.errors[0];
+    const msg = first.message || JSON.stringify(first);
+    const err = new Error(`oxc-parser: ${msg}`);
+    throw err;
+  }
+  return result.program;
+}
+
+export function extractConfigReferences(configObject) {
+  const result = { defaultScene: undefined, pluginIds: [] };
+  if (!configObject || configObject.type !== AST_NODE_TYPES.ObjectExpression) return result;
+
+  for (const prop of configObject.properties) {
+    if (prop.type !== AST_NODE_TYPES.Property || prop.key?.type !== AST_NODE_TYPES.Identifier) continue;
+    if (prop.key.name === 'defaultScene' && prop.value?.type === AST_NODE_TYPES.Literal) {
+      result.defaultScene = prop.value.value;
+    }
+    if (prop.key.name === 'plugins' && prop.value?.type === AST_NODE_TYPES.ArrayExpression) {
+      for (const el of prop.value.elements) {
+        if (!el) continue;
+        if (el.type === AST_NODE_TYPES.Literal && typeof el.value === 'string') {
+          result.pluginIds.push(el.value);
+        } else if (el.type === AST_NODE_TYPES.ArrayExpression && el.elements[0]?.type === AST_NODE_TYPES.Literal) {
+          const first = el.elements[0];
+          if (typeof first.value === 'string') result.pluginIds.push(first.value);
+        }
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Locate the `defineConfig({...})` ObjectExpression in a parsed
+ * `caper.config.ts` AST. Handles both the default-export form
+ * (`export default defineConfig({...})`) and the named-const form
+ * (`export const config = defineConfig({...})`).
+ */
+export function findConfigObject(ast) {
+  let configObject;
+  for (const node of ast.body) {
+    if (
+      node.type === AST_NODE_TYPES.ExportDefaultDeclaration &&
+      node.declaration?.type === AST_NODE_TYPES.CallExpression &&
+      node.declaration.callee?.name === 'defineConfig'
+    ) {
+      configObject = node.declaration.arguments[0];
+    } else if (
+      node.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+      node.declaration?.type === AST_NODE_TYPES.VariableDeclaration
+    ) {
+      const decl = node.declaration.declarations.find(
+        (d) => d.init?.type === AST_NODE_TYPES.CallExpression && d.init.callee?.name === 'defineConfig',
+      );
+      if (decl) configObject = decl.init.arguments[0];
+    }
+  }
+  return configObject;
+}
+
+/**
+ * Boolean build-time flags read straight out of `caper.config.ts`.
+ *
+ * Vite fixes a config's plugin list the moment the config object is created — no
+ * plugin hook can add one later, and `caper()` runs while the project's
+ * vite.config is still being evaluated, long before anything could execute
+ * caper.config.ts. So these are pulled with the same oxc AST parse discovery
+ * already uses rather than by importing the file: importing pulls in
+ * @caperjs/core, whose @pixi/sound + GSAP deps run
+ * browser-only top-level side effects that throw under Node (see
+ * `validateCaperConfig` for the gory details).
+ *
+ * Only boolean literals are honoured. A missing, empty, or unparseable
+ * config silently yields the defaults — this runs before the normal config
+ * error reporting, so it must never be the thing that fails the build.
+ */
+
+export const DEFINE_HELPER_NAMES = new Set(['defineScene', 'definePlugin', 'definePopup', 'defineEntity', 'defineUI']);
+
+export function findExportedConstants(ast) {
+  const exports = {};
+
+  function extractValue(node) {
+    switch (node.type) {
+      case AST_NODE_TYPES.Literal:
+        return node.value;
+      case AST_NODE_TYPES.ArrayExpression:
+        return node.elements.map((element) => element && extractValue(element)).filter((value) => value !== undefined);
+      case AST_NODE_TYPES.ObjectExpression: {
+        const obj = {};
+        for (const prop of node.properties) {
+          if (prop.type === AST_NODE_TYPES.Property && prop.key.type === AST_NODE_TYPES.Identifier) {
+            obj[prop.key.name] = extractValue(prop.value);
+          }
+        }
+        return obj;
+      }
+      case AST_NODE_TYPES.CallExpression: {
+        // Unwrap `defineScene({...})` / `definePlugin({...})` / etc.
+        // Other call expressions are opaque to discovery.
+        const calleeName = node.callee?.name;
+        if (calleeName && DEFINE_HELPER_NAMES.has(calleeName) && node.arguments[0]) {
+          return extractValue(node.arguments[0]);
+        }
+        return undefined;
+      }
+      default:
+        return undefined;
+    }
+  }
+
+  // Export names whose value came out of a `define*()` helper, in source order.
+  const wrapperKeys = [];
+
+  for (const node of ast.body) {
+    if (
+      node.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+      node.declaration?.type === AST_NODE_TYPES.VariableDeclaration
+    ) {
+      for (const declarator of node.declaration.declarations) {
+        if (declarator.id.type === AST_NODE_TYPES.Identifier && declarator.init) {
+          exports[declarator.id.name] = extractValue(declarator.init);
+          if (
+            declarator.init.type === AST_NODE_TYPES.CallExpression &&
+            DEFINE_HELPER_NAMES.has(declarator.init.callee?.name)
+          ) {
+            wrapperKeys.push(declarator.id.name);
+          }
+        }
+      }
+    }
+  }
+
+  // Flatten `export const scene = defineScene({...})` / `export const ui =
+  // defineUI({...})` wrappers onto the top level so discovery code can stay
+  // agnostic: `exports.id`, `exports.active`, `exports.assets` etc. work whether
+  // the file used individual exports or the helper form.
+  //
+  // Which exports get flattened is decided by *what they are* — a call to a
+  // define helper — rather than by matching a hardcoded list of export names.
+  // That list read ['scene', 'plugin', 'popup', 'entity'], so `defineUI` was
+  // silently ignored and every UI element registered under its class name
+  // instead of its declared id. Naming the export anything other than the kind
+  // (`export const ui_ = defineUI(...)`) failed the same way.
+  //
+  // Individual file-level exports still take precedence on conflict, and earlier
+  // wrappers win over later ones.
+  for (const wrapperKey of wrapperKeys) {
+    const wrapped = exports[wrapperKey];
+    if (wrapped && typeof wrapped === 'object' && !Array.isArray(wrapped)) {
+      for (const [k, v] of Object.entries(wrapped)) {
+        if (exports[k] === undefined) exports[k] = v;
+      }
+    }
+  }
+
+  return exports;
+}
+
+/**
+ * Finds the file's default-exported class. Handles both common forms:
+ *
+ *   // inline
+ *   export default class Foo extends Bar { ... }
+ *
+ *   // named declaration + separate default export
+ *   export class Foo extends Bar { ... }
+ *   export default Foo;
+ *
+ *   // or unexported named class
+ *   class Foo extends Bar { ... }
+ *   export default Foo;
+ *
+ * The separate-default form requires a second pass to resolve the
+ * identifier back to a matching `ClassDeclaration` in the same file.
+ */
+export function findDefaultExportedClass(ast) {
+  let identifierName = null;
+
+  for (const node of ast.body) {
+    if (node.type !== AST_NODE_TYPES.ExportDefaultDeclaration) continue;
+    // Form 1: `export default class Foo { ... }`
+    if (node.declaration.type === AST_NODE_TYPES.ClassDeclaration) {
+      return node.declaration;
+    }
+    // Form 2/3: `export default Foo;` — remember the name to resolve below.
+    if (node.declaration.type === AST_NODE_TYPES.Identifier) {
+      identifierName = node.declaration.name;
+      break;
+    }
+  }
+  if (!identifierName) return null;
+
+  // Resolve the identifier to a class declaration in the same file. Accept
+  // either a bare `class Foo {}` or an `export class Foo {}` form.
+  for (const node of ast.body) {
+    if (node.type === AST_NODE_TYPES.ClassDeclaration && node.id?.name === identifierName) {
+      return node;
+    }
+    if (
+      node.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+      node.declaration?.type === AST_NODE_TYPES.ClassDeclaration &&
+      node.declaration.id?.name === identifierName
+    ) {
+      return node.declaration;
+    }
+  }
+
+  return null;
+}
+
+// Back-compat alias — scene code historically called `findDefaultExportedScene`.
+export const findDefaultExportedScene = findDefaultExportedClass;

package/build/internal/buildFlags.mjs

@@ -0,0 +1,50 @@
+/**
+ * Boolean build flags read out of `caper.config.ts` before anything can execute
+ * it. See the comment on `readCaperBuildFlags` for why this is an AST parse.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { AST_NODE_TYPES, findConfigObject, parse } from './ast.mjs';
+import { cwd } from './util.mjs';
+
+export function readCaperBuildFlags() {
+  const flags = { useWasm: false };
+  const configPath = path.resolve(cwd, 'caper.config.ts');
+  if (!fs.existsSync(configPath)) return flags;
+
+  let configObject;
+  try {
+    configObject = findConfigObject(parse(fs.readFileSync(configPath, 'utf-8')));
+  } catch {
+    return flags;
+  }
+  if (configObject?.type !== AST_NODE_TYPES.ObjectExpression) return flags;
+
+  for (const prop of configObject.properties) {
+    if (prop.type !== AST_NODE_TYPES.Property || prop.key?.type !== AST_NODE_TYPES.Identifier) continue;
+    if (!(prop.key.name in flags)) continue;
+    if (prop.value?.type === AST_NODE_TYPES.Literal && typeof prop.value.value === 'boolean') {
+      flags[prop.key.name] = prop.value.value;
+    }
+  }
+  return flags;
+}
+
+/**
+ * Cross-reference validation over discovered scenes/plugins/popups/entities
+ * + the parsed `caper.config.ts` AST + the assetpack manifest. Emits
+ * warnings via the project logger; in dev mode also forwards warnings to
+ * the browser error overlay as info so they're impossible to miss.
+ *
+ * Checks:
+ *  1. Scene `assets.preload.bundles` / `assets.background.bundles` entries
+ *     exist in the assetpack manifest.
+ *  2. Plugin IDs in `caper.config.ts` match a discovered plugin
+ *     (npm `@caperjs/plugin-*` OR local `src/plugins/*`).
+ *  3. `defaultScene` in `caper.config.ts` matches a discovered scene ID.
+ *  4. No duplicate scene / plugin / popup / entity IDs across discovery.
+ *
+ * All issues are warnings, not errors — they shouldn't fail the build
+ * (typos are a dev-time problem; the runtime will still start, just with
+ * broken references the user needs to see).
+ */

package/build/internal/discovery.mjs

@@ -0,0 +1,402 @@
+/**
+ * Filesystem discovery: walks the conventional source directories and reads each
+ * file's AST to work out what it declares.
+ *
+ * Split from the list plugins so the plugins are only about emitting virtual
+ * modules, and the crawling can be reasoned about (and fixed) on its own.
+ *
+ * Every entry point takes an explicit `root` — vite's resolved `config.root`,
+ * passed down by the plugin that called it. That is the project root by
+ * definition; `process.cwd()` only happens to be the same one, and differs the
+ * moment anyone runs `vite --root elsewhere` or invokes vite from a parent
+ * directory in a monorepo. It is threaded as a parameter rather than kept in a
+ * module-level variable so nothing depends on load order or on who ran first.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  AST_NODE_TYPES,
+  DEFINE_HELPER_NAMES,
+  findDefaultExportedClass,
+  findDefaultExportedScene,
+  findExportedConstants,
+  parse,
+} from './ast.mjs';
+import { logger } from './util.mjs';
+
+
+export async function findTypeScriptFiles(dir) {
+  const files = [];
+
+  async function scan(directory) {
+    const entries = await fs.promises.readdir(directory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        await scan(fullPath);
+      } else if (entry.isFile() && /\.ts?$/.test(entry.name)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  await scan(dir);
+  return files;
+}
+
+// Callees whose single argument is treated as the entire config object and
+// unwrapped into the exported constant's value. Keep in sync with the
+// identity helpers in src/utils/define.ts.
+
+export async function discoverScenes(server, root) {
+  const scenesDir = path.resolve(root, 'src/scenes');
+  const scenes = [];
+
+  if (!fs.existsSync(scenesDir)) {
+    return [];
+  }
+
+  const files = await findTypeScriptFiles(scenesDir);
+
+  for (const file of files) {
+    try {
+      const content = await fs.promises.readFile(file, 'utf-8');
+      const ast = parse(content, {
+        jsx: false,
+        loc: true,
+        comment: false,
+      });
+
+      const sceneClass = findDefaultExportedScene(ast);
+      if (!sceneClass) continue;
+
+      const exports = findExportedConstants(ast);
+
+      const relativePath = file.replace(root, '').replace(/\\/g, '/').split('/src')[1];
+      // remove /src — the runtime import uses the raw alias (Vite resolves
+      // `.ts` automatically) while the typeof-import codegen needs the
+      // extension stripped so TypeScript's path-alias resolution finds it.
+      const importPath = `@${relativePath}`;
+      const importPathForTypes = importPath.replace(/\.ts$/, '');
+      const id = exports.id || sceneClass.id?.name || path.basename(file, '.ts');
+
+      scenes.push({
+        id,
+        importPath: importPathForTypes,
+        module:
+          exports.dynamic === false
+            ? importPath
+            : {
+                toString: () => `() => import('${importPath}')`,
+                isFunction: true, // Add a flag to identify dynamic imports
+              },
+        active: exports.active === false ? false : true,
+        debugLabel: exports.debug?.label || id,
+        debugGroup: exports.debug?.group || undefined,
+        debugOrder: exports.debug?.order >= 0 ? exports.debug.order : Number.MAX_SAFE_INTEGER,
+        assets: exports.assets ?? undefined,
+        plugins: exports.plugins ?? undefined,
+        autoUnloadAssets: exports.assets?.autoUnload ?? false,
+      });
+    } catch (e) {
+      const errorMessage = `Error parsing scene file ${file}: ${e.message}`;
+      logger.error(errorMessage);
+      if (e.stack) {
+        logger.error(e.stack);
+      }
+      if (server) {
+        server.ws.send({
+          type: 'error',
+          err: {
+            message: e.message,
+            stack: e.stack,
+            id: file,
+            plugin: 'vite-plugin-scenes',
+          },
+        });
+      }
+    }
+  }
+  return scenes;
+}
+
+export async function discoverLocalPlugins(server, root) {
+  const pluginsDir = path.resolve(root, 'src/plugins');
+  const plugins = [];
+
+  if (!fs.existsSync(pluginsDir)) {
+    return [];
+  }
+
+  const files = await findTypeScriptFiles(pluginsDir);
+
+  for (const file of files) {
+    try {
+      const content = await fs.promises.readFile(file, 'utf-8');
+      const ast = parse(content, {
+        jsx: false,
+        loc: true,
+        comment: false,
+      });
+
+      const hasPluginWrapper = ast.body.some(
+        (n) =>
+          n.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+          n.declaration?.type === AST_NODE_TYPES.VariableDeclaration &&
+          n.declaration.declarations.some(
+            (d) => d.init?.type === AST_NODE_TYPES.CallExpression && d.init.callee?.name === 'definePlugin',
+          ),
+      );
+      if (!hasPluginWrapper) continue;
+
+      const pluginClass = findDefaultExportedClass(ast);
+      if (!pluginClass) continue;
+
+      const exports = findExportedConstants(ast);
+
+      const relativePath = file.replace(root, '').replace(/\\/g, '/').split('/src')[1];
+      const importPath = `@${relativePath.replace(/\.ts$/, '')}`;
+      const id = exports.id || pluginClass.id?.name || path.basename(file, '.ts');
+      const name = pluginClass.id?.name || id;
+
+      plugins.push({
+        id,
+        name,
+        isLocal: true,
+        importPath,
+        module:
+          exports.dynamic === false
+            ? importPath
+            : {
+                toString: () => `() => import('${importPath}')`,
+                isFunction: true,
+              },
+        active: exports.active === false ? false : true,
+        requires: Array.isArray(exports.requires) ? exports.requires.filter((r) => typeof r === 'string') : [],
+      });
+    } catch (e) {
+      const errorMessage = `Error parsing plugin file ${file}: ${e.message}`;
+      logger.error(errorMessage);
+      if (e.stack) {
+        logger.error(e.stack);
+      }
+      if (server) {
+        server.ws.send({
+          type: 'error',
+          err: {
+            message: e.message,
+            stack: e.stack,
+            id: file,
+            plugin: 'vite-plugin-plugins',
+          },
+        });
+      }
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * Discovers npm packages prefixed with `@caperjs/plugin-` in the host
+ * project's `package.json`. Always emitted as dynamic imports.
+ */
+
+export function discoverNpmPlugins(root) {
+  const packageJsonPath = path.resolve(root, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) return [];
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  const allDependencies = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+
+  return Object.keys(allDependencies)
+    .filter((dep) => dep.startsWith('@caperjs/plugin-'))
+    .map((packageName) => {
+      const id = packageName.replace('@caperjs/plugin-', '');
+      return {
+        id,
+        name: packageName,
+        isLocal: false,
+        importPath: packageName,
+        module: {
+          toString: () => `() => import('${packageName}')`,
+          isFunction: true,
+        },
+        active: true,
+        // npm plugins can declare `requires` on the class itself
+        // (`public readonly requires = ['firebase']`); the runtime topo-sort
+        // reads from the live instance, so empty here is fine.
+        requires: [],
+      };
+    });
+}
+
+export async function discoverPlugins(server, root) {
+  const [local, npm] = [await discoverLocalPlugins(server, root), discoverNpmPlugins(root)];
+  return [...npm, ...local];
+}
+
+/**
+ * Generic recursive-class-file discoverer. Walks a directory, AST-parses
+ * each .ts file, requires a default-exported class, and reads `id` /
+ * `active` / `dynamic` metadata (either from individual exports or a
+ * `defineX({...})` wrapper). Used for popups and entities — same shape
+ * as scenes/plugins minus the npm-package discovery path.
+ *
+ * `defaultDynamic` sets the emit mode when a file doesn't declare it
+ * explicitly. Entities default to `false` (static import) because the
+ * typed `this.add.entity(id, props)` factory needs sync access to the
+ * constructor; popups default to `true` because `show()` is async.
+ */
+
+export async function discoverLocalClassFiles({ dir, kind, server, root, defaultDynamic = true }) {
+  const rootDir = path.resolve(root, dir);
+  if (!fs.existsSync(rootDir)) return [];
+
+  const files = await findTypeScriptFiles(rootDir);
+  const results = [];
+
+  for (const file of files) {
+    try {
+      const content = await fs.promises.readFile(file, 'utf-8');
+      const ast = parse(content);
+
+      const cls = findDefaultExportedClass(ast);
+      if (!cls) continue;
+
+      const exports = findExportedConstants(ast);
+
+      const relativePath = file.replace(root, '').replace(/\\/g, '/').split('/src')[1];
+      const importPath = `@${relativePath.replace(/\.ts$/, '')}`;
+      const id = exports.id || cls.id?.name || path.basename(file, '.ts');
+      const name = cls.id?.name || id;
+      const isDynamic = exports.dynamic !== undefined ? exports.dynamic : defaultDynamic;
+
+      results.push({
+        id,
+        name,
+        importPath,
+        module: !isDynamic
+          ? importPath
+          : {
+              toString: () => `() => import('${importPath}')`,
+              isFunction: true,
+            },
+        active: exports.active === false ? false : true,
+      });
+    } catch (e) {
+      const errorMessage = `Error parsing ${kind} file ${file}: ${e.message}`;
+      logger.error(errorMessage);
+      if (e.stack) logger.error(e.stack);
+      if (server) {
+        server.ws.send({
+          type: 'error',
+          err: {
+            message: e.message,
+            stack: e.stack,
+            id: file,
+            plugin: `vite-plugin-${kind}s`,
+          },
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+export async function discoverPopups(server, root) {
+  return discoverLocalClassFiles({ dir: 'src/popups', kind: 'popup', server, root });
+}
+
+export async function discoverEntities(server, root) {
+  // Entities default to static imports so `this.add.entity(id, props)` can
+  // synchronously construct without awaiting a dynamic import. Opt into
+  // code-splitting per-entity with `defineEntity({ dynamic: true })`.
+  return discoverLocalClassFiles({ dir: 'src/entities', kind: 'entity', server, root, defaultDynamic: false });
+}
+
+export async function discoverUIs(server, root) {
+  // UI elements default to static imports so `this.add.ui(id, props)` can
+  // synchronously construct. Same rationale as entities.
+  return discoverLocalClassFiles({ dir: 'src/ui', kind: 'ui', server, root, defaultDynamic: false });
+}
+
+/**
+ * Factory for `virtual:caper-popups` / `virtual:caper-entities`.
+ * Thin wrapper around a discover function that generates the static-import
+ * + dynamic-import `() => import(...)` mix, same shape as the scenes/plugins
+ * virtual modules.
+ */
+
+export async function discoverLocaleKeys(server, root) {
+  const localesDir = path.resolve(root, 'src/locales');
+  if (!fs.existsSync(localesDir)) return [];
+
+  const files = (await fs.promises.readdir(localesDir)).filter((f) => /\.ts$/.test(f)).sort();
+  if (files.length === 0) return [];
+
+  // Pick the reference file: en.ts if present, else the first alphabetically.
+  const referenceFile = files.find((f) => f === 'en.ts') || files[0];
+  const filePath = path.join(localesDir, referenceFile);
+
+  try {
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+    if (!content.trim()) return [];
+
+    const ast = parse(content);
+    const defaultExport = ast.body.find((n) => n.type === AST_NODE_TYPES.ExportDefaultDeclaration);
+    if (!defaultExport) return [];
+
+    // Allow either `export default { ... }` or `export default satisfies ...`
+    let obj = defaultExport.declaration;
+    if (obj && obj.type === 'TSSatisfiesExpression') obj = obj.expression;
+    if (!obj || obj.type !== AST_NODE_TYPES.ObjectExpression) return [];
+
+    const keys = [];
+    const walk = (node, prefix) => {
+      if (node.type !== AST_NODE_TYPES.ObjectExpression) return;
+      for (const prop of node.properties) {
+        if (prop.type !== AST_NODE_TYPES.Property) continue;
+        let name;
+        if (prop.key.type === AST_NODE_TYPES.Identifier) name = prop.key.name;
+        else if (prop.key.type === AST_NODE_TYPES.Literal) name = String(prop.key.value);
+        else continue;
+        const dotPath = prefix ? `${prefix}.${name}` : name;
+        if (prop.value.type === AST_NODE_TYPES.ObjectExpression) {
+          walk(prop.value, dotPath);
+        } else if (prop.value.type === AST_NODE_TYPES.Literal) {
+          keys.push(dotPath);
+        }
+      }
+    };
+    walk(obj, '');
+    return keys.sort();
+  } catch (e) {
+    const errorMessage = `Error parsing locale file ${filePath}: ${e.message}`;
+    logger.error(errorMessage);
+    if (server) {
+      server.ws.send({
+        type: 'error',
+        err: {
+          message: e.message,
+          stack: e.stack,
+          id: filePath,
+          plugin: 'vite-plugin-locales',
+        },
+      });
+    }
+    return [];
+  }
+}
+
+/**
+ * Virtual module plugin for `virtual:caper-plugins`. Mirrors
+ * `sceneListPlugin`: supports static + dynamic imports per entry, preserves
+ * the full metadata shape so consumers can filter by `active` / read IDs.
+ */