@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/authored-project.mjs

@@ -0,0 +1,1449 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  PROJECT_MAIN_ENTRY_RELATIVE_PATH,
+  PROJECT_RUNTIME_APP_RELATIVE_PATH,
+  syncRegistryBackedRuntimeFiles,
+} from './authored-runtime.mjs';
+import {
+  listStarterContentRegistries,
+  validateStarterContentRegistries,
+} from './starter-content-registry.mjs';
+import { loadMakeCatalog } from './make-catalog.mjs';
+
+export const PROJECT_REGISTRY_SCHEMA = 'aurajs.project-registry.v1';
+export const PROJECT_EXPLAIN_SCHEMA = 'aurajs.project-explain.v1';
+export const PROJECT_CHECK_SCHEMA = 'aurajs.project-check.v1';
+export const PROJECT_CONTINUITY_SCHEMA = 'aurajs.project-continuity.v1';
+export const CANONICAL_PREFAB_ROLES = Object.freeze(['custom', 'enemy', 'pickup', 'player', 'world']);
+
+const RUNTIME_DIR = 'src/runtime';
+export const PROJECT_REGISTRY_RELATIVE_PATH = `${RUNTIME_DIR}/project-registry.js`;
+export const SCENE_REGISTRY_RELATIVE_PATH = `${RUNTIME_DIR}/scene-registry.js`;
+const RUNTIME_BOOTSTRAP_FILES = [
+  PROJECT_MAIN_ENTRY_RELATIVE_PATH,
+  PROJECT_RUNTIME_APP_RELATIVE_PATH,
+  SCENE_REGISTRY_RELATIVE_PATH,
+];
+const SELF_WIRING_KINDS = new Set(['scene', 'ui-screen', 'prefab']);
+const CANONICAL_PREFAB_ROLE_SET = new Set(CANONICAL_PREFAB_ROLES);
+const POSIX_SEP = '/';
+
+const BASE_PROJECT_CONFIG_FILES = ['config/gameplay/game.config.json'];
+const BASE_PROJECT_CONTENT_FILES = [];
+
+const STARTER_PROJECT_REGISTRY_PRESETS = {
+  blank: {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+    ],
+    configFiles: [],
+    contentFiles: [],
+  },
+  '2d-adventure': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'relic', role: 'pickup', path: 'prefabs/relic.prefab.js', exportName: 'default' },
+      { id: 'world', role: 'world', path: 'prefabs/world.prefab.js', exportName: 'default' },
+    ],
+    configFiles: ['config/gameplay/adventure.config.js'],
+    contentFiles: ['content/gameplay/world.js'],
+  },
+  '2d-shooter': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+      { id: 'menu', path: 'scenes/menu.scene.js', exportName: 'createMenuScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'pause', path: 'ui/pause.screen.js', exportName: 'default' },
+      { id: 'settings', path: 'ui/settings.screen.js', exportName: 'default' },
+      { id: 'title', path: 'ui/title.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'enemy-basic', role: 'enemy', path: 'prefabs/enemy-basic.prefab.js', exportName: 'default' },
+      { id: 'enemies', role: 'enemy', path: 'prefabs/enemies.prefab.js', exportName: 'default' },
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'projectiles', role: 'custom', path: 'prefabs/projectiles.prefab.js', exportName: 'default' },
+    ],
+    configFiles: ['config/gameplay/shooter.config.js'],
+    contentFiles: ['content/gameplay/waves.json'],
+  },
+  '2d-survivor': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+      { id: 'menu', path: 'scenes/menu.scene.js', exportName: 'createMenuScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'title', path: 'ui/title.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'enemies', role: 'enemy', path: 'prefabs/enemies.prefab.js', exportName: 'default' },
+      { id: 'enemy-swarm', role: 'enemy', path: 'prefabs/enemy-swarm.prefab.js', exportName: 'default' },
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'projectiles', role: 'custom', path: 'prefabs/projectiles.prefab.js', exportName: 'default' },
+    ],
+    configFiles: ['config/gameplay/survivor.config.js'],
+    contentFiles: ['content/gameplay/spawn-zones.json'],
+  },
+  '3d-adventure': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'pause', path: 'ui/pause.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'relic', role: 'pickup', path: 'prefabs/relic.prefab.js', exportName: 'default' },
+      { id: 'world', role: 'world', path: 'prefabs/world.prefab.js', exportName: 'default' },
+    ],
+    configFiles: ['config/gameplay/adventure.config.js'],
+    contentFiles: ['content/gameplay/course.js'],
+  },
+  '3d-platformer': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'checkpoint', path: 'scenes/checkpoint.scene.js', exportName: 'createCheckpointScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'pause', path: 'ui/pause.screen.js', exportName: 'default' },
+      { id: 'settings', path: 'ui/settings.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'checkpoint', role: 'world', path: 'prefabs/checkpoint.prefab.js', exportName: 'default' },
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'world', role: 'world', path: 'prefabs/world.prefab.js', exportName: 'default' },
+    ],
+    configFiles: [],
+    contentFiles: ['content/gameplay/checkpoints.json', 'content/gameplay/course.js'],
+  },
+  '3d-collectathon': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'checkpoint', path: 'scenes/checkpoint.scene.js', exportName: 'createCheckpointScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'pause', path: 'ui/pause.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'collectible', role: 'pickup', path: 'prefabs/collectible.prefab.js', exportName: 'default' },
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+      { id: 'world', role: 'world', path: 'prefabs/world.prefab.js', exportName: 'default' },
+    ],
+    configFiles: [],
+    contentFiles: ['content/gameplay/collectibles.json', 'content/gameplay/course.js'],
+  },
+  'local-multiplayer': {
+    startSceneId: 'gameplay',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+    ],
+    prefabs: [
+      { id: 'player', role: 'player', path: 'prefabs/player.prefab.js', exportName: 'default' },
+    ],
+    configFiles: ['config/gameplay/local-multiplayer.config.js'],
+    contentFiles: ['content/gameplay/room-layout.js'],
+  },
+  'deckbuilder-2d': {
+    startSceneId: 'boot',
+    scenes: [
+      { id: 'boot', path: 'scenes/boot.scene.js', exportName: 'createBootScene' },
+      { id: 'gameplay', path: 'scenes/gameplay.scene.js', exportName: 'createGameplayScene' },
+    ],
+    screens: [
+      { id: 'hud', path: 'ui/hud.screen.js', exportName: 'default' },
+      { id: 'pause', path: 'ui/pause.screen.js', exportName: 'default' },
+      { id: 'settings', path: 'ui/settings.screen.js', exportName: 'default' },
+    ],
+    prefabs: [],
+    configFiles: [
+      'config/gameplay/deckbuilder.config.js',
+    ],
+    contentFiles: [
+      'content/cards/guard.card.js',
+      'content/cards/spark.card.js',
+      'content/cards/strike.card.js',
+      'content/cards/survey.card.js',
+      'content/cards/starter.deck.js',
+      'content/enemies/training-automaton.enemy.js',
+      'content/relics/ember-charm.relic.js',
+      'content/encounters/training-battle.encounter.js',
+      'content/encounters/training-battle.js',
+      'content/registries/cards.registry.js',
+      'content/registries/enemies.registry.js',
+      'content/registries/relics.registry.js',
+      'content/registries/encounters.registry.js',
+    ],
+  },
+};
+
+export function isSelfWiringMakeKind(kind) {
+  return SELF_WIRING_KINDS.has(String(kind || '').trim());
+}
+
+export function getProjectRegistryRelativePath() {
+  return PROJECT_REGISTRY_RELATIVE_PATH;
+}
+
+export function getSceneRegistryRelativePath() {
+  return SCENE_REGISTRY_RELATIVE_PATH;
+}
+
+export function createScaffoldProjectRegistryModel({ projectRoot, template, projectTitle }) {
+  const normalizedTemplate = String(template || '').trim() || 'blank';
+  const preset = STARTER_PROJECT_REGISTRY_PRESETS[normalizedTemplate];
+  if (!preset) {
+    return createEmptyProjectRegistryModel({
+      template: normalizedTemplate,
+      projectTitle,
+    });
+  }
+
+  return normalizeProjectRegistryData({
+    schema: PROJECT_REGISTRY_SCHEMA,
+    template: normalizedTemplate,
+    projectTitle,
+    startSceneId: preset.startSceneId,
+    scenes: preset.scenes,
+    screens: preset.screens,
+    prefabs: preset.prefabs,
+    configFiles: [...BASE_PROJECT_CONFIG_FILES, ...(preset.configFiles || [])],
+    contentFiles: [...BASE_PROJECT_CONTENT_FILES, ...(preset.contentFiles || [])],
+  }, { projectRoot, allowMissingStartScene: true });
+}
+
+export function buildStarterRegistryEntries(template) {
+  const preset = STARTER_PROJECT_REGISTRY_PRESETS[String(template || '').trim()];
+  if (!preset) {
+    return {
+      startSceneId: null,
+      scenes: [],
+      screens: [],
+      prefabs: [],
+      configFiles: [...BASE_PROJECT_CONFIG_FILES],
+      contentFiles: [...BASE_PROJECT_CONTENT_FILES],
+      dataFiles: [...BASE_PROJECT_CONFIG_FILES, ...BASE_PROJECT_CONTENT_FILES],
+    };
+  }
+  const mergedConfigFiles = [...BASE_PROJECT_CONFIG_FILES, ...(preset.configFiles || [])];
+  const mergedContentFiles = [...BASE_PROJECT_CONTENT_FILES, ...(preset.contentFiles || [])];
+  return {
+    startSceneId: preset.startSceneId,
+    scenes: preset.scenes,
+    screens: preset.screens,
+    prefabs: preset.prefabs,
+    configFiles: mergedConfigFiles,
+    contentFiles: mergedContentFiles,
+    dataFiles: [...mergedConfigFiles, ...mergedContentFiles],
+  };
+}
+
+export function inferPrefabRole(name) {
+  const normalized = String(name || '').trim().toLowerCase();
+  if (!normalized) return 'custom';
+  if (normalized === 'player' || normalized.endsWith('-player') || normalized.startsWith('player-')) {
+    return 'player';
+  }
+  if (normalized.includes('enemy') || normalized.includes('foe') || normalized.includes('boss')) {
+    return 'enemy';
+  }
+  if (/(pickup|collect|coin|orb|loot|reward)/.test(normalized)) {
+    return 'pickup';
+  }
+  if (/(world|checkpoint|terrain|level|stage|map|environment)/.test(normalized)) {
+    return 'world';
+  }
+  return 'custom';
+}
+
+export function normalizePrefabRole(role, { fallback = null } = {}) {
+  const normalized = String(role || '').trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (!CANONICAL_PREFAB_ROLE_SET.has(normalized)) {
+    throw new Error(`Invalid prefab role "${role}". Expected one of: ${CANONICAL_PREFAB_ROLES.join(', ')}.`);
+  }
+  return normalized;
+}
+
+export function createStarterProjectRegistry({
+  template,
+  projectTitle,
+  startSceneId,
+  scenes,
+  screens,
+  prefabs,
+  configFiles,
+  contentFiles,
+  dataFiles,
+}) {
+  const ownedFiles = normalizeOwnedFiles({
+    configFiles,
+    contentFiles,
+    dataFiles,
+  });
+  return {
+    schema: PROJECT_REGISTRY_SCHEMA,
+    template: String(template || 'blank').trim() || 'blank',
+    projectTitle: String(projectTitle || 'AuraJS Game').trim() || 'AuraJS Game',
+    startSceneId: startSceneId == null ? null : String(startSceneId).trim(),
+    scenes: Array.isArray(scenes) ? scenes : [],
+    screens: Array.isArray(screens) ? screens : [],
+    prefabs: Array.isArray(prefabs) ? prefabs : [],
+    configFiles: ownedFiles.configFiles,
+    contentFiles: ownedFiles.contentFiles,
+    dataFiles: ownedFiles.dataFiles,
+    continuity: createProjectContinuityModel({
+      startSceneId,
+    }),
+  };
+}
+
+export function writeProjectRegistryFiles({ projectRoot, registry }) {
+  const registryPath = resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  const adapterPath = resolve(projectRoot, SCENE_REGISTRY_RELATIVE_PATH);
+  const normalized = normalizeProjectRegistryData(registry, { projectRoot, allowMissingStartScene: true });
+
+  mkdirSync(dirname(registryPath), { recursive: true });
+  writeFileSync(registryPath, renderProjectRegistryModule(normalized, { projectRoot, registryPath }), 'utf8');
+  writeFileSync(
+    adapterPath,
+    renderSceneRegistryAdapterModule({
+      projectRoot,
+      sceneRegistryPath: adapterPath,
+      registry: normalized,
+    }),
+    'utf8',
+  );
+}
+
+export function renderProjectRegistryModule(model, { projectRoot = process.cwd(), registryPath = null } = {}) {
+  const normalized = normalizeProjectRegistryData(model, {
+    projectRoot,
+    allowMissingStartScene: true,
+  });
+  const modulePath = registryPath || resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  const imports = [];
+  const screenLines = [];
+
+  for (const [index, entry] of normalized.screens.entries()) {
+    const binding = `screenModule${index + 1}`;
+    const importPath = toImportPath(relative(dirname(modulePath), resolve(projectRoot, entry.path)));
+    if (entry.exportName === 'default') {
+      imports.push(`import ${binding} from ${JSON.stringify(importPath)};`);
+    } else {
+      imports.push(`import { ${entry.exportName} as ${binding} } from ${JSON.stringify(importPath)};`);
+    }
+    screenLines.push(`  ${JSON.stringify(entry.id)}: ${binding},`);
+  }
+
+  const importBlock = imports.length > 0 ? `${imports.join('\n')}\n\n` : '';
+  const screenFactoriesBlock = screenLines.length > 0
+    ? `const screenModules = {\n${screenLines.join('\n')}\n};`
+    : 'const screenModules = {};';
+
+  return `${importBlock}const projectRegistry = ${serializeValue({
+    schema: PROJECT_REGISTRY_SCHEMA,
+    template: normalized.template,
+    projectTitle: normalized.projectTitle,
+    startSceneId: normalized.startSceneId,
+    scenes: normalized.scenes,
+    screens: normalized.screens,
+    prefabs: normalized.prefabs,
+    configFiles: normalized.configFiles,
+    contentFiles: normalized.contentFiles,
+    continuity: normalized.continuity,
+  }, 0)};
+
+${screenFactoriesBlock}
+
+Object.defineProperty(projectRegistry, 'dataFiles', {
+  enumerable: false,
+  get() {
+    return [...projectRegistry.configFiles, ...projectRegistry.contentFiles];
+  },
+});
+
+export function resolveProjectScreen(screenId) {
+  return screenModules[String(screenId || '')] || null;
+}
+
+export function createProjectRegistry() {
+  return projectRegistry;
+}
+
+export default projectRegistry;
+`;
+}
+
+export function renderSceneRegistryAdapterModule({ projectRoot, sceneRegistryPath, registry }) {
+  const normalized = normalizeProjectRegistryData(registry, { projectRoot, allowMissingStartScene: true });
+  const imports = [`import projectRegistry from './project-registry.js';`];
+  const lines = [];
+
+  for (const [index, entry] of normalized.scenes.entries()) {
+    const binding = `sceneFactory${index + 1}`;
+    const importPath = toImportPath(relative(dirname(sceneRegistryPath), resolve(projectRoot, entry.path)));
+    if (entry.exportName === 'default') {
+      imports.push(`import ${binding} from ${JSON.stringify(importPath)};`);
+    } else {
+      imports.push(`import { ${entry.exportName} as ${binding} } from ${JSON.stringify(importPath)};`);
+    }
+    lines.push(`  ${JSON.stringify(entry.id)}: ${binding},`);
+  }
+
+  return `${imports.join('\n')}
+
+const sceneFactories = {
+${lines.join('\n')}
+};
+
+export function createSceneRegistry(context = {}) {
+  const scenes = {};
+  for (const entry of projectRegistry.scenes || []) {
+    const resolved = sceneFactories[entry.id];
+    if (typeof resolved === 'function') {
+      scenes[entry.id] = resolved(context);
+      continue;
+    }
+    if (typeof resolved !== 'undefined' && resolved !== null) {
+      scenes[entry.id] = resolved;
+    }
+  }
+
+  return {
+    defaultSceneId: projectRegistry.startSceneId || null,
+    scenes,
+  };
+}
+`;
+}
+
+export async function selfWireGeneratedProjectFiles({ projectRoot, kind, name, title, role = null, files = [] }) {
+  const normalizedKind = String(kind || '').trim();
+  const normalizedFiles = Array.isArray(files)
+    ? files.map((entry) => normalizeProjectRelativePath(entry)).filter(Boolean)
+    : [];
+  if (!isSelfWiringMakeKind(normalizedKind) && normalizedKind !== 'config' && normalizedKind !== 'content') {
+    return { wired: false, registryCreated: false, files: [] };
+  }
+
+  assertAuraProjectRoot(projectRoot);
+
+  const template = loadProjectTemplate(projectRoot);
+  const projectTitle = loadProjectTitle(projectRoot);
+  const registryPath = resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  const adapterPath = resolve(projectRoot, SCENE_REGISTRY_RELATIVE_PATH);
+
+  let registryCreated = false;
+  let model = null;
+  if (existsSync(registryPath)) {
+    model = await loadProjectRegistryModel({ projectRoot });
+  } else {
+    model = shouldSeedStarterRegistry({ projectRoot, template })
+      ? createScaffoldProjectRegistryModel({ projectRoot, template, projectTitle })
+      : createEmptyProjectRegistryModel({ template, projectTitle });
+    registryCreated = true;
+  }
+
+  if (normalizedKind === 'scene') {
+    upsertEntry(model.scenes, {
+      id: String(name),
+      path: `scenes/${name}.scene.js`,
+      exportName: 'default',
+    });
+    if (!model.startSceneId) {
+      model.startSceneId = String(name);
+    }
+  } else if (normalizedKind === 'ui-screen') {
+    upsertEntry(model.screens, {
+      id: String(name),
+      path: `ui/${name}.screen.js`,
+      exportName: 'default',
+    });
+  } else if (normalizedKind === 'prefab') {
+    upsertEntry(model.prefabs, {
+      id: String(name),
+      role: normalizePrefabRole(role, { fallback: 'custom' }),
+      path: `prefabs/${name}.prefab.js`,
+      exportName: 'default',
+    });
+  } else if (normalizedKind === 'config' || normalizedKind === 'content') {
+    const targetFiles = normalizedKind === 'config'
+      ? model.configFiles
+      : model.contentFiles;
+    const fallbackFile = normalizedKind === 'config'
+      ? `config/gameplay/${name}.json`
+      : `content/gameplay/${name}.json`;
+    for (const relativePath of normalizedFiles.length > 0 ? normalizedFiles : [fallbackFile]) {
+      upsertOwnedFile(targetFiles, relativePath);
+    }
+  }
+
+  model = normalizeProjectRegistryData(model, { projectRoot, allowMissingStartScene: true });
+
+  mkdirSync(dirname(registryPath), { recursive: true });
+  writeProjectRegistryFiles({
+    projectRoot,
+    registry: model,
+  });
+  const runtimeSync = syncRegistryBackedRuntimeFiles({
+    projectRoot,
+    template,
+    projectTitle,
+  });
+
+  return {
+    wired: true,
+    registryCreated,
+    files: [
+      toProjectRelativePath(projectRoot, registryPath),
+      toProjectRelativePath(projectRoot, adapterPath),
+      ...(Array.isArray(runtimeSync.files) ? runtimeSync.files : []),
+    ],
+    title: title || null,
+  };
+}
+
+export async function explainProject({ projectRoot, catalogRoot = null }) {
+  assertAuraProjectRoot(projectRoot);
+
+  const template = loadProjectTemplate(projectRoot);
+  const registryPath = resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  const mode = existsSync(registryPath) ? 'registry' : 'bootstrap-only';
+  const runtimeBootstrap = RUNTIME_BOOTSTRAP_FILES.filter((relativePath) => existsSync(resolve(projectRoot, relativePath)));
+  const starterContentRegistries = await listStarterContentRegistries({ projectRoot, catalogRoot });
+  const availableMakeKinds = loadMakeCatalog({ projectRoot }).map((entry) => ({
+    id: entry.id,
+    owner: entry.owner,
+    scope: entry.scope,
+  }));
+
+  if (mode === 'bootstrap-only') {
+    return {
+      schema: PROJECT_EXPLAIN_SCHEMA,
+      mode,
+      template,
+      projectRoot,
+      startingSceneId: null,
+      sourceOfTruth: {
+        projectRegistry: null,
+        primary: 'src/main.js',
+        runtimeBootstrap: runtimeBootstrap.length > 0 ? runtimeBootstrap : ['src/main.js'],
+      },
+      scenes: [],
+      screens: [],
+      prefabs: [],
+      configFiles: [],
+      contentFiles: [],
+      dataFiles: [],
+      continuity: createProjectContinuityModel(),
+      starterContentRegistries,
+      availableMakeKinds,
+    };
+  }
+
+  const registry = await loadProjectRegistryModel({ projectRoot });
+  return {
+    schema: PROJECT_EXPLAIN_SCHEMA,
+    mode,
+    template: registry.template || template,
+    projectRoot,
+    startingSceneId: registry.startSceneId || null,
+    sourceOfTruth: {
+      projectRegistry: PROJECT_REGISTRY_RELATIVE_PATH,
+      primary: PROJECT_REGISTRY_RELATIVE_PATH,
+      runtimeBootstrap,
+    },
+    scenes: registry.scenes.map((entry) => ({ id: entry.id, path: entry.path })),
+    screens: registry.screens.map((entry) => ({ id: entry.id, path: entry.path })),
+    prefabs: registry.prefabs.map((entry) => ({
+      id: entry.id,
+      role: entry.role || null,
+      path: entry.path,
+    })),
+    configFiles: [...registry.configFiles],
+    contentFiles: [...registry.contentFiles],
+    dataFiles: [...registry.dataFiles],
+    continuity: registry.continuity,
+    starterContentRegistries,
+    availableMakeKinds,
+  };
+}
+
+export async function checkProject({ projectRoot, catalogRoot = null }) {
+  const errors = [];
+  const warnings = [];
+  const template = loadProjectTemplate(projectRoot);
+  const registryPath = resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  const adapterPath = resolve(projectRoot, SCENE_REGISTRY_RELATIVE_PATH);
+
+  if (!existsSync(resolve(projectRoot, 'aura.config.json'))) {
+    return buildProjectCheckResult({
+      mode: 'invalid',
+      ok: false,
+      reasonCode: 'project_root_missing',
+      errors: [{ reasonCode: 'project_root_missing', message: 'Missing aura.config.json in the current directory.' }],
+      warnings,
+    });
+  }
+
+  if (!existsSync(registryPath)) {
+    if (template === 'blank' && !hasAuthoredProjectFiles(projectRoot)) {
+      return buildProjectCheckResult({
+        mode: 'bootstrap-only',
+        ok: true,
+        reasonCode: 'bootstrap_only_project_ok',
+        errors,
+        warnings,
+      });
+    }
+    return buildProjectCheckResult({
+      mode: 'registry',
+      ok: false,
+      reasonCode: 'project_registry_missing',
+      errors: [{ reasonCode: 'project_registry_missing', message: 'Missing src/runtime/project-registry.js.' }],
+      warnings,
+    });
+  }
+
+  let registry = null;
+  try {
+    registry = await loadProjectRegistryModel({ projectRoot });
+  } catch (error) {
+    return buildProjectCheckResult({
+      mode: 'registry',
+      ok: false,
+      reasonCode: 'project_registry_invalid',
+      errors: [{
+        reasonCode: 'project_registry_invalid',
+        message: error instanceof Error ? error.message : String(error),
+        path: PROJECT_REGISTRY_RELATIVE_PATH,
+      }],
+      warnings,
+    });
+  }
+
+  pushDuplicateErrors(errors, registry.scenes, 'scene');
+  pushDuplicateErrors(errors, registry.screens, 'screen');
+  pushDuplicateErrors(errors, registry.prefabs, 'prefab');
+
+  if (registry.scenes.length > 0 && (!registry.startSceneId || !registry.scenes.some((entry) => entry.id === registry.startSceneId))) {
+    errors.push({
+      reasonCode: 'project_start_scene_missing',
+      message: 'Starting scene id is missing or is not registered in project-registry.js.',
+      path: PROJECT_REGISTRY_RELATIVE_PATH,
+    });
+  }
+
+  pushMissingPathErrors(errors, registry.scenes, projectRoot, 'project_scene_path_missing');
+  pushMissingPathErrors(errors, registry.screens, projectRoot, 'project_screen_path_missing');
+  pushMissingPathErrors(errors, registry.prefabs, projectRoot, 'project_prefab_path_missing');
+  pushMissingOwnedFileErrors(errors, registry.configFiles, projectRoot, 'project_config_path_missing');
+  pushMissingOwnedFileErrors(errors, registry.contentFiles, projectRoot, 'project_content_path_missing');
+
+  const expectedAdapter = renderSceneRegistryAdapterModule({
+    projectRoot,
+    sceneRegistryPath: adapterPath,
+    registry,
+  });
+  if (!existsSync(adapterPath) || readFileSync(adapterPath, 'utf8') !== expectedAdapter) {
+    errors.push({
+      reasonCode: 'project_registry_adapter_drift',
+      message: 'src/runtime/scene-registry.js is missing or has drifted from the canonical project-registry adapter.',
+      path: SCENE_REGISTRY_RELATIVE_PATH,
+    });
+  }
+
+  await pushImportErrors(errors, registry.scenes, projectRoot);
+  await pushImportErrors(errors, registry.screens, projectRoot);
+  await pushPrefabContractErrors(errors, registry.prefabs, projectRoot);
+  const starterContentValidation = await validateStarterContentRegistries({ projectRoot, catalogRoot });
+  errors.push(...starterContentValidation.errors);
+
+  return buildProjectCheckResult({
+    mode: 'registry',
+    ok: errors.length === 0,
+    reasonCode: errors.length === 0 ? 'project_check_ok' : errors[0].reasonCode,
+    errors,
+    warnings,
+    starterContentRegistries: starterContentValidation.registries,
+  });
+}
+
+export async function registerGeneratedProjectFiles({ projectRoot, kind, name, role = null, files = [] }) {
+  const result = await selfWireGeneratedProjectFiles({
+    projectRoot,
+    kind,
+    name,
+    title: name,
+    role,
+    files,
+  });
+
+  return {
+    changed: result.wired === true,
+    registryCreated: result.registryCreated === true,
+    registryPath: result.wired ? PROJECT_REGISTRY_RELATIVE_PATH : null,
+    sceneRegistryPath: result.wired ? SCENE_REGISTRY_RELATIVE_PATH : null,
+    files: Array.isArray(result.files) ? result.files : [],
+  };
+}
+
+export async function runProjectExplain({ projectRoot, json = false }) {
+  const payload = normalizeExplainPayload(await explainProject({ projectRoot }));
+  return {
+    exitCode: 0,
+    text: json ? `${JSON.stringify(payload, null, 2)}\n` : formatExplainReport(payload),
+    payload,
+  };
+}
+
+export async function runProjectCheck({ projectRoot, json = false }) {
+  const payload = normalizeCheckPayload({ projectRoot, checked: await checkProject({ projectRoot }) });
+  return {
+    exitCode: payload.ok ? 0 : 2,
+    text: json ? `${JSON.stringify(payload, null, 2)}\n` : formatCheckReport(payload),
+    payload,
+  };
+}
+
+async function loadProjectRegistryModel({ projectRoot }) {
+  const registryPath = resolve(projectRoot, PROJECT_REGISTRY_RELATIVE_PATH);
+  if (!existsSync(registryPath)) {
+    throw new Error('Missing src/runtime/project-registry.js.');
+  }
+
+  const imported = await import(`${pathToFileURL(registryPath).href}?t=${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  return normalizeProjectRegistryData(imported.default, { projectRoot });
+}
+
+function normalizeProjectRegistryData(data, { projectRoot, allowMissingStartScene = false }) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('Project registry must default-export an object.');
+  }
+
+  const normalized = {
+    schema: typeof data.schema === 'string' ? data.schema : PROJECT_REGISTRY_SCHEMA,
+    template: typeof data.template === 'string' && data.template.trim().length > 0 ? data.template.trim() : loadProjectTemplate(projectRoot),
+    projectTitle: typeof data.projectTitle === 'string' && data.projectTitle.trim().length > 0 ? data.projectTitle.trim() : loadProjectTitle(projectRoot),
+    startSceneId: data.startSceneId == null ? null : String(data.startSceneId).trim(),
+    scenes: normalizeRegistryEntries(data.scenes, { kind: 'scene' }),
+    screens: normalizeRegistryEntries(data.screens, { kind: 'screen' }),
+    prefabs: normalizeRegistryEntries(data.prefabs, { kind: 'prefab' }),
+    ...normalizeOwnedFiles({
+      configFiles: data.configFiles,
+      contentFiles: data.contentFiles,
+      dataFiles: data.dataFiles,
+    }),
+    projectRoot: resolve(projectRoot),
+  };
+  normalized.continuity = createProjectContinuityModel({
+    startSceneId: normalized.startSceneId,
+    continuity: data.continuity,
+  });
+
+  if (normalized.schema !== PROJECT_REGISTRY_SCHEMA) {
+    throw new Error(`Unsupported project registry schema "${normalized.schema}". Expected "${PROJECT_REGISTRY_SCHEMA}".`);
+  }
+
+  if (!allowMissingStartScene && normalized.scenes.length > 0 && !normalized.startSceneId) {
+    throw new Error('Project registry scenes require startSceneId.');
+  }
+
+  normalized.scenes.sort(compareRegistryEntries);
+  normalized.screens.sort(compareRegistryEntries);
+  normalized.prefabs.sort(compareRegistryEntries);
+  normalized.configFiles.sort((a, b) => a.localeCompare(b));
+  normalized.contentFiles.sort((a, b) => a.localeCompare(b));
+  normalized.dataFiles.sort((a, b) => a.localeCompare(b));
+
+  return normalized;
+}
+
+function normalizeRegistryEntries(value, { kind }) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`Project registry ${kind}s must be an array.`);
+  }
+
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`Project registry ${kind} entry at index ${index} must be an object.`);
+    }
+    const id = String(entry.id || '').trim();
+    const path = String(entry.path || '').trim();
+    if (!id) {
+      throw new Error(`Project registry ${kind} entry at index ${index} is missing id.`);
+    }
+    if (!path) {
+      throw new Error(`Project registry ${kind} entry "${id}" is missing path.`);
+    }
+    return {
+      id,
+      path: normalizeProjectRelativePath(path),
+      exportName: typeof entry.exportName === 'string' && entry.exportName.trim().length > 0 ? entry.exportName.trim() : 'default',
+      role: kind === 'prefab'
+        ? normalizePrefabRole(entry.role, { fallback: 'custom' })
+        : null,
+    };
+  });
+}
+
+function normalizeDataFiles(value) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error('Project registry dataFiles must be an array.');
+  }
+  return value.map((entry, index) => {
+    const path = String(entry || '').trim();
+    if (!path) {
+      throw new Error(`Project registry dataFiles entry at index ${index} must be a non-empty string.`);
+    }
+    return normalizeProjectRelativePath(path);
+  });
+}
+
+function normalizeOwnedFiles({ configFiles = null, contentFiles = null, dataFiles = null } = {}) {
+  const normalizedConfigFiles = normalizeDataFiles(configFiles);
+  const normalizedContentFiles = normalizeDataFiles(contentFiles);
+  const legacyDataFiles = normalizeDataFiles(dataFiles);
+  const configFileSet = new Set(normalizedConfigFiles);
+  const contentFileSet = new Set(normalizedContentFiles);
+
+  for (const path of legacyDataFiles) {
+    if (path.startsWith('config/')) {
+      configFileSet.add(path);
+      continue;
+    }
+    contentFileSet.add(path);
+  }
+
+  const ownedConfigFiles = [...configFileSet];
+  const ownedContentFiles = [...contentFileSet];
+  return {
+    configFiles: ownedConfigFiles,
+    contentFiles: ownedContentFiles,
+    dataFiles: [...ownedConfigFiles, ...ownedContentFiles],
+  };
+}
+
+function createProjectContinuityModel({
+  startSceneId = null,
+  continuity = null,
+} = {}) {
+  const normalizedStartSceneId = startSceneId == null ? null : String(startSceneId).trim() || null;
+  const source = continuity && typeof continuity === 'object' && !Array.isArray(continuity)
+    ? continuity
+    : {};
+  const saveRoots = source.saveRoots && typeof source.saveRoots === 'object' && !Array.isArray(source.saveRoots)
+    ? source.saveRoots
+    : {};
+  const devRestore = devRestoreOrFallback(source.devRestore);
+  const runtimeFiles = Array.isArray(source.runtimeFiles)
+    ? source.runtimeFiles.map((entry) => normalizeProjectRelativePath(entry)).filter(Boolean)
+    : [];
+  const restoreFlags = Array.isArray(devRestore.flags)
+    ? devRestore.flags.map((entry) => String(entry || '').trim()).filter(Boolean)
+    : [];
+  const notes = Array.isArray(source.notes)
+    ? source.notes.map((entry) => String(entry || '').trim()).filter(Boolean)
+    : [];
+
+  return {
+    schema: PROJECT_CONTINUITY_SCHEMA,
+    startSceneId: normalizedStartSceneId,
+    sharedAppStatePath: normalizeProjectRelativePath(
+      source.sharedAppStatePath || 'src/runtime/app-state.js',
+    ),
+    sceneFlowPath: normalizeProjectRelativePath(
+      source.sceneFlowPath || 'src/runtime/scene-flow.js',
+    ),
+    screenShellPath: normalizeProjectRelativePath(
+      source.screenShellPath || 'src/runtime/screen-shell.js',
+    ),
+    uiThemePath: normalizeProjectRelativePath(
+      source.uiThemePath || 'src/runtime/ui-theme.js',
+    ),
+    uiSettingsPath: normalizeProjectRelativePath(
+      source.uiSettingsPath || 'src/runtime/ui-settings.js',
+    ),
+    uiFormsPath: normalizeProjectRelativePath(
+      source.uiFormsPath || 'src/runtime/ui-forms.js',
+    ),
+    projectRegistryPath: normalizeProjectRelativePath(
+      source.projectRegistryPath || PROJECT_REGISTRY_RELATIVE_PATH,
+    ),
+    sceneRegistryPath: normalizeProjectRelativePath(
+      source.sceneRegistryPath || SCENE_REGISTRY_RELATIVE_PATH,
+    ),
+    sceneStateOwnerPath: normalizeProjectRelativePath(
+      source.sceneStateOwnerPath || 'scenes',
+    ),
+    runtimeFiles: runtimeFiles.length > 0
+      ? [...new Set(runtimeFiles)].sort((left, right) => left.localeCompare(right))
+      : [
+        'src/runtime/app-state.js',
+        'src/runtime/scene-flow.js',
+        'src/runtime/screen-shell.js',
+        'src/runtime/ui-theme.js',
+        'src/runtime/ui-settings.js',
+        'src/runtime/ui-forms.js',
+        PROJECT_REGISTRY_RELATIVE_PATH,
+        SCENE_REGISTRY_RELATIVE_PATH,
+      ],
+    saveRoots: {
+      slots: normalizeProjectRelativePath(saveRoots.slots || '.aura/state/slots'),
+      checkpoints: normalizeProjectRelativePath(saveRoots.checkpoints || '.aura/state/checkpoints'),
+    },
+    devRestore: {
+      flags: restoreFlags.length > 0
+        ? [...new Set(restoreFlags)]
+        : ['--restore-slot', '--restore-checkpoint'],
+      note: typeof devRestore.note === 'string' && devRestore.note.trim().length > 0
+        ? devRestore.note.trim()
+        : 'Supported native dev restarts reapply slot, checkpoint, or live continuity payloads after setup.',
+    },
+    notes: notes.length > 0
+      ? notes
+      : [
+        'Keep shared continuity in appState.session/ui/runtime through the app-context helpers backed by src/runtime/app-state.js, and keep scene-local restore state JSON-safe inside scene getState/applyState hooks.',
+        'Use src/runtime/scene-flow.js for route-style scene payload continuity read through context.getCurrentScenePayload(), and use src/runtime/screen-shell.js for HUD, overlay, and modal payload continuity instead of ad hoc globals.',
+      ],
+  };
+}
+
+function devRestoreOrFallback(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function buildProjectCheckResult({ mode, ok, reasonCode, errors, warnings, starterContentRegistries = [] }) {
+  return {
+    schema: PROJECT_CHECK_SCHEMA,
+    ok,
+    mode,
+    reasonCode,
+    errors,
+    warnings,
+    starterContentRegistries,
+  };
+}
+
+function formatExplainReport(report) {
+  const sourceOfTruth = report.sourceOfTruth && typeof report.sourceOfTruth === 'object'
+    ? report.sourceOfTruth
+    : null;
+  const lines = [
+    `Project root: ${report.projectRoot}`,
+    `Template: ${report.template || 'unknown'}`,
+    `Mode: ${report.mode}`,
+    `Source of truth: ${sourceOfTruth?.primary || 'src/main.js'}`,
+    `Project registry: ${sourceOfTruth?.projectRegistry || '(none)'}`,
+    `Start scene: ${report.startingSceneId || '(none yet)'}`,
+    '',
+    'Runtime bootstrap:',
+  ];
+
+  for (const entry of report.runtimeBootstrapFiles || []) {
+    lines.push(`  ${entry}`);
+  }
+  if ((report.runtimeBootstrapFiles || []).length === 0) {
+    lines.push('  (none detected)');
+  }
+
+  lines.push('');
+  lines.push('Available make kinds:');
+  if ((report.availableMakeKinds || []).length === 0) {
+    lines.push('  (none detected)');
+  } else {
+    for (const entry of report.availableMakeKinds) {
+      lines.push(`  ${entry.id} [${entry.owner}]`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Scenes:');
+  if ((report.scenes || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const entry of report.scenes) {
+      lines.push(`  ${entry.id} -> ${entry.path}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Screens:');
+  if ((report.screens || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const entry of report.screens) {
+      lines.push(`  ${entry.id} -> ${entry.path}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Prefabs:');
+  if ((report.prefabs || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const entry of report.prefabs) {
+      lines.push(`  ${entry.id}${entry.role ? ` [${entry.role}]` : ''} -> ${entry.path}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Config files:');
+  if ((report.configFiles || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const entry of report.configFiles) {
+      lines.push(`  ${entry.path}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Content files:');
+  if ((report.contentFiles || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const entry of report.contentFiles) {
+      lines.push(`  ${entry.path}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Continuity ownership:');
+  const continuity = report.continuity && typeof report.continuity === 'object'
+    ? report.continuity
+    : null;
+  if (!continuity) {
+    lines.push('  (none detected)');
+  } else {
+    lines.push(`  appState.session/ui/runtime -> ${continuity.sharedAppStatePath || 'src/runtime/app-state.js'}`);
+    lines.push('  app context helpers -> ensureSessionState, ensureUiState, getSessionState, getUiState');
+    lines.push(`  scene flow payloads -> ${continuity.sceneFlowPath || 'src/runtime/scene-flow.js'} (read current payload via getCurrentScenePayload())`);
+    lines.push(`  screen shell payloads -> ${continuity.screenShellPath || 'src/runtime/screen-shell.js'}`);
+    lines.push(`  ui theme module -> ${continuity.uiThemePath || 'src/runtime/ui-theme.js'} (appState.ui.preferences + theme apply/reset)`);
+    lines.push(`  retained settings helpers -> ${continuity.uiSettingsPath || 'src/runtime/ui-settings.js'}`);
+    lines.push(`  retained forms helpers -> ${continuity.uiFormsPath || 'src/runtime/ui-forms.js'}`);
+    lines.push('  screen payloads -> screenShell.hud|overlay|modals[].data');
+    lines.push(`  scene-local state -> ${continuity.sceneStateOwnerPath || 'scenes'} (sceneState)`);
+    lines.push(`  slots -> ${continuity.saveRoots?.slots || '.aura/state/slots'}`);
+    lines.push(`  checkpoints -> ${continuity.saveRoots?.checkpoints || '.aura/state/checkpoints'}`);
+    lines.push(`  dev restore flags -> ${Array.isArray(continuity.devRestore?.flags) && continuity.devRestore.flags.length > 0 ? continuity.devRestore.flags.join(', ') : '(none)'}`);
+  }
+
+  lines.push('');
+  lines.push('Starter content registries:');
+  if ((report.starterContentRegistries || []).length === 0) {
+    lines.push('  (none registered)');
+  } else {
+    for (const registry of report.starterContentRegistries) {
+      lines.push(`  ${registry.family} -> ${registry.registryPath}`);
+      lines.push(`    kinds: ${(registry.kinds || []).join(', ') || '(none)'}`);
+      if (!Array.isArray(registry.entries) || registry.entries.length === 0) {
+        lines.push('    entries: (none registered)');
+        continue;
+      }
+      for (const entry of registry.entries) {
+        lines.push(`    ${entry.id} [${entry.kind}] -> ${entry.path}`);
+      }
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function formatCheckReport(report) {
+  const lines = [
+    `aura check: ${report.ok ? 'ok' : 'failed'}`,
+    `Mode: ${report.mode}`,
+    `Reason code: ${report.reasonCode}`,
+  ];
+
+  if ((report.errors || []).length > 0) {
+    lines.push('');
+    lines.push('Errors:');
+    for (const entry of report.errors) {
+      lines.push(`  - ${entry.reasonCode}: ${entry.message}${entry.path ? ` [${entry.path}]` : ''}`);
+    }
+  }
+
+  if ((report.warnings || []).length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const entry of report.warnings) {
+      lines.push(`  - ${entry.reasonCode}: ${entry.message}${entry.path ? ` [${entry.path}]` : ''}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function pushDuplicateErrors(errors, entries, label) {
+  const seen = new Set();
+  for (const entry of entries) {
+    if (seen.has(entry.id)) {
+      errors.push({
+        reasonCode: 'project_duplicate_id',
+        message: `Duplicate ${label} id "${entry.id}" in project-registry.js.`,
+        path: entry.path,
+      });
+      continue;
+    }
+    seen.add(entry.id);
+  }
+}
+
+function pushMissingPathErrors(errors, entries, projectRoot, reasonCode) {
+  for (const entry of entries) {
+    const absolutePath = resolve(projectRoot, entry.path);
+    if (!existsSync(absolutePath)) {
+      errors.push({
+        reasonCode,
+        message: `Registered path does not exist: ${entry.path}`,
+        path: entry.path,
+      });
+    }
+  }
+}
+
+function pushMissingOwnedFileErrors(errors, entries, projectRoot, reasonCode) {
+  for (const entry of entries) {
+    const filePath = typeof entry === 'string' ? entry : String(entry?.path || '').trim();
+    if (!filePath) continue;
+    const absolutePath = resolve(projectRoot, filePath);
+    if (!existsSync(absolutePath)) {
+      errors.push({
+        reasonCode,
+        message: `Registered authored file is missing: ${filePath}.`,
+        path: filePath,
+      });
+    }
+  }
+}
+
+async function pushImportErrors(errors, entries, projectRoot) {
+  for (const entry of entries) {
+    const absolutePath = resolve(projectRoot, entry.path);
+    if (!existsSync(absolutePath)) continue;
+    try {
+      const imported = await import(`${pathToFileURL(absolutePath).href}?t=${Date.now()}-${Math.random().toString(16).slice(2)}`);
+      if (entry.exportName !== 'default' && typeof imported?.[entry.exportName] === 'undefined') {
+        throw new Error(`Missing export "${entry.exportName}".`);
+      }
+      if (entry.exportName === 'default' && typeof imported?.default === 'undefined') {
+        throw new Error('Missing default export.');
+      }
+    } catch (error) {
+      errors.push({
+        reasonCode: 'project_authored_import_broken',
+        message: `Unable to import ${entry.path}: ${error instanceof Error ? error.message : String(error)}`,
+        path: entry.path,
+      });
+    }
+  }
+}
+
+async function pushPrefabContractErrors(errors, entries, projectRoot) {
+  for (const entry of entries) {
+    const absolutePath = resolve(projectRoot, entry.path);
+    if (!existsSync(absolutePath)) continue;
+
+    let imported = null;
+    try {
+      imported = await import(`${pathToFileURL(absolutePath).href}?t=${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    } catch (error) {
+      errors.push({
+        reasonCode: 'project_authored_import_broken',
+        message: `Unable to import ${entry.path}: ${error instanceof Error ? error.message : String(error)}`,
+        path: entry.path,
+      });
+      continue;
+    }
+
+    const prefab = imported?.default;
+    const issues = [];
+    const prefabId = typeof prefab?.id === 'string' ? prefab.id.trim() : '';
+    const prefabKind = typeof prefab?.kind === 'string' ? prefab.kind.trim() : '';
+    const prefabRole = typeof prefab?.role === 'string' ? prefab.role.trim() : '';
+
+    if (!prefab || typeof prefab !== 'object' || Array.isArray(prefab)) {
+      issues.push('default export must be a prefab descriptor object');
+    } else {
+      if (!prefabId) {
+        issues.push('default export is missing id');
+      } else if (prefabId !== entry.id) {
+        issues.push(`default export id "${prefabId}" does not match registry id "${entry.id}"`);
+      }
+
+      if (prefabKind !== 'prefab') {
+        issues.push(`default export kind must be "prefab" (received "${prefabKind || 'missing'}")`);
+      }
+
+      if (!prefabRole) {
+        issues.push('default export is missing role');
+      } else if (!CANONICAL_PREFAB_ROLE_SET.has(prefabRole)) {
+        issues.push(`default export role "${prefabRole}" is not canonical (${CANONICAL_PREFAB_ROLES.join(', ')})`);
+      }
+
+      if (!entry.role) {
+        issues.push('registry entry is missing a canonical role');
+      } else if (!CANONICAL_PREFAB_ROLE_SET.has(entry.role)) {
+        issues.push(`registry role "${entry.role}" is not canonical (${CANONICAL_PREFAB_ROLES.join(', ')})`);
+      } else if (prefabRole && entry.role !== prefabRole) {
+        issues.push(`registry role "${entry.role}" does not match prefab role "${prefabRole}"`);
+      }
+
+      if (!prefab.view || typeof prefab.view !== 'object' || Array.isArray(prefab.view)) {
+        issues.push('default export is missing a view object');
+      }
+    }
+
+    if (issues.length > 0) {
+      errors.push({
+        reasonCode: 'project_prefab_contract_invalid',
+        message: `Prefab contract invalid: ${issues.join('; ')}.`,
+        path: entry.path,
+      });
+    }
+  }
+}
+
+function createEmptyProjectRegistryModel({ template, projectTitle }) {
+  return {
+    schema: PROJECT_REGISTRY_SCHEMA,
+    template: String(template || 'blank').trim() || 'blank',
+    projectTitle: String(projectTitle || 'AuraJS Game').trim() || 'AuraJS Game',
+    startSceneId: null,
+    scenes: [],
+    screens: [],
+    prefabs: [],
+    configFiles: [],
+    contentFiles: [],
+    dataFiles: [],
+    continuity: createProjectContinuityModel(),
+  };
+}
+
+function upsertEntry(entries, nextEntry) {
+  const index = entries.findIndex((entry) => entry.id === nextEntry.id);
+  if (index === -1) {
+    entries.push(nextEntry);
+    return;
+  }
+  entries[index] = {
+    ...entries[index],
+    ...nextEntry,
+  };
+}
+
+function upsertOwnedFile(entries, nextPath) {
+  const normalizedPath = normalizeProjectRelativePath(nextPath);
+  if (!normalizedPath) return;
+  if (!entries.includes(normalizedPath)) {
+    entries.push(normalizedPath);
+  }
+}
+
+function compareRegistryEntries(left, right) {
+  return left.id.localeCompare(right.id) || left.path.localeCompare(right.path);
+}
+
+function hasAuthoredProjectFiles(projectRoot) {
+  const authoredRoots = ['scenes', 'prefabs', 'ui'];
+  for (const relativePath of authoredRoots) {
+    const absolutePath = resolve(projectRoot, relativePath);
+    if (!existsSync(absolutePath)) continue;
+    if (readdirSync(absolutePath).some((entry) => entry !== '.gitkeep')) {
+      return true;
+    }
+  }
+  return existsSync(resolve(projectRoot, 'config/gameplay/game.config.json'));
+}
+
+function shouldSeedStarterRegistry({ projectRoot, template }) {
+  if (template !== 'blank') {
+    return true;
+  }
+  return [
+    'scenes/boot.scene.js',
+    'scenes/gameplay.scene.js',
+    'prefabs/player.prefab.js',
+    'ui/hud.screen.js',
+  ].every((relativePath) => existsSync(resolve(projectRoot, relativePath)));
+}
+
+function loadProjectTemplate(projectRoot) {
+  const capabilitiesPath = resolve(projectRoot, 'aura.capabilities.json');
+  if (!existsSync(capabilitiesPath)) return 'blank';
+  try {
+    const capabilities = JSON.parse(readFileSync(capabilitiesPath, 'utf8'));
+    if (typeof capabilities?.template === 'string' && capabilities.template.trim().length > 0) {
+      return capabilities.template.trim();
+    }
+  } catch {}
+  return 'blank';
+}
+
+function loadProjectTitle(projectRoot) {
+  const configPath = resolve(projectRoot, 'aura.config.json');
+  if (!existsSync(configPath)) return 'AuraJS Game';
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (typeof config?.identity?.name === 'string' && config.identity.name.trim().length > 0) {
+      return config.identity.name.trim();
+    }
+  } catch {}
+  return 'AuraJS Game';
+}
+
+export function assertAuraProjectRoot(projectRoot, message = 'Missing aura.config.json in the current directory.') {
+  if (!existsSync(resolve(projectRoot, 'aura.config.json'))) {
+    throw new Error(message);
+  }
+}
+
+function toProjectRelativePath(projectRoot, absolutePath) {
+  return normalizeProjectRelativePath(relative(projectRoot, absolutePath));
+}
+
+function normalizeProjectRelativePath(value) {
+  return String(value || '').split(/[/\\]+/g).filter(Boolean).join(POSIX_SEP);
+}
+
+function toImportPath(relativePath) {
+  const normalized = normalizeProjectRelativePath(relativePath);
+  if (normalized.startsWith('.')) return normalized;
+  return `./${normalized}`;
+}
+
+function toPascalCase(value) {
+  return String(value || '')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function serializeValue(value, indent = 0) {
+  return JSON.stringify(value, null, 2)
+    .split('\n')
+    .map((line, index) => (index === 0 ? line : `${' '.repeat(indent)}${line}`))
+    .join('\n');
+}
+
+function normalizeExplainPayload(explained) {
+  const mode = explained.mode === 'registry' ? 'registry' : 'bootstrap-only';
+  const runtimeBootstrapFiles = Array.isArray(explained?.sourceOfTruth?.runtimeBootstrap)
+    ? [...explained.sourceOfTruth.runtimeBootstrap]
+    : [];
+
+  return {
+    schema: PROJECT_EXPLAIN_SCHEMA,
+    projectRoot: explained.projectRoot,
+    template: explained.template || 'blank',
+    mode,
+    sourceOfTruth: {
+      projectRegistry: explained?.sourceOfTruth?.projectRegistry || null,
+      primary: explained?.sourceOfTruth?.primary || explained?.sourceOfTruth?.projectRegistry || 'src/main.js',
+      runtimeBootstrap: runtimeBootstrapFiles,
+    },
+    startingSceneId: explained.startingSceneId || null,
+    runtimeBootstrapFiles,
+    scenes: Array.isArray(explained.scenes) ? explained.scenes : [],
+    screens: Array.isArray(explained.screens) ? explained.screens : [],
+    prefabs: Array.isArray(explained.prefabs) ? explained.prefabs : [],
+    configFiles: Array.isArray(explained.configFiles)
+      ? explained.configFiles.map((entry) => (typeof entry === 'string' ? { path: entry } : entry))
+      : [],
+    contentFiles: Array.isArray(explained.contentFiles)
+      ? explained.contentFiles.map((entry) => (typeof entry === 'string' ? { path: entry } : entry))
+      : [],
+    dataFiles: Array.isArray(explained.dataFiles)
+      ? explained.dataFiles.map((entry) => (typeof entry === 'string' ? { path: entry } : entry))
+      : [],
+    continuity: explained?.continuity && typeof explained.continuity === 'object' && !Array.isArray(explained.continuity)
+      ? explained.continuity
+      : createProjectContinuityModel(),
+    starterContentRegistries: Array.isArray(explained.starterContentRegistries)
+      ? explained.starterContentRegistries.map((registry) => ({
+        family: registry.family,
+        registryPath: registry.registryPath,
+        kinds: Array.isArray(registry.kinds) ? registry.kinds : [],
+        exists: registry.exists === true,
+        title: registry.title || null,
+        entries: Array.isArray(registry.entries) ? registry.entries : [],
+      }))
+      : [],
+    availableMakeKinds: Array.isArray(explained.availableMakeKinds)
+      ? explained.availableMakeKinds.map((entry) => ({
+        id: entry.id,
+        owner: entry.owner || 'core',
+        scope: entry.scope || 'core',
+      }))
+      : [],
+  };
+}
+
+function normalizeCheckPayload({ projectRoot, checked }) {
+  return {
+    schema: PROJECT_CHECK_SCHEMA,
+    ok: checked.ok === true,
+    mode: checked.mode === 'registry' ? 'registry' : checked.mode,
+    projectRoot,
+    reasonCode: checked.reasonCode || (checked.ok ? 'project_check_ok' : 'project_check_failed'),
+    errors: Array.isArray(checked.errors) ? checked.errors : [],
+    warnings: Array.isArray(checked.warnings) ? checked.warnings : [],
+    starterContentRegistries: Array.isArray(checked.starterContentRegistries) ? checked.starterContentRegistries : [],
+  };
+}
+
+function appendExplainLines(lines, title, entries) {
+  lines.push(`  ${title}:`);
+  if (!Array.isArray(entries) || entries.length === 0) {
+    lines.push('    (none registered)');
+  } else {
+    for (const entry of entries) {
+      lines.push(`    ${entry.id} -> ${entry.path}`);
+    }
+  }
+  lines.push('');
+}