@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/authored-runtime.mjs

@@ -0,0 +1,2016 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+const SHARED_RUNTIME_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/create/shared/src/runtime');
+
+export const PROJECT_MAIN_ENTRY_RELATIVE_PATH = 'src/main.js';
+export const PROJECT_RUNTIME_APP_RELATIVE_PATH = 'src/runtime/app.js';
+export const PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH = 'src/runtime/app-state.js';
+export const PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH = 'src/runtime/capabilities.js';
+export const PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH = 'src/runtime/project-inspector.js';
+export const PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH = 'src/runtime/scene-flow.js';
+export const PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH = 'src/runtime/screen-shell.js';
+export const PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH = 'src/runtime/ui-theme.js';
+export const PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH = 'src/runtime/ui-settings.js';
+export const PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH = 'src/runtime/ui-forms.js';
+export const PROJECT_INSPECTOR_SCHEMA = 'aurajs.project-inspector.v1';
+export const PROJECT_STATE_SCHEMA = 'aurajs.authored-project-state.v1';
+export const APP_STATE_SCHEMA = 'aurajs.app-state.v1';
+
+function readSharedRuntimeTemplate(relativePath) {
+  return readFileSync(resolve(SHARED_RUNTIME_TEMPLATE_DIR, relativePath), 'utf8');
+}
+
+export function renderSceneFlowModule() {
+  return readSharedRuntimeTemplate('scene-flow.js');
+}
+
+export function renderScreenShellModule() {
+  return readSharedRuntimeTemplate('screen-shell.js');
+}
+
+export function renderUiThemeModule() {
+  return readSharedRuntimeTemplate('ui-theme.js');
+}
+
+export function renderUiSettingsModule() {
+  return readSharedRuntimeTemplate('ui-settings.js');
+}
+
+export function renderUiFormsModule() {
+  return readSharedRuntimeTemplate('ui-forms.js');
+}
+
+export function renderAppStateModule() {
+  return `export const APP_STATE_SCHEMA = ${JSON.stringify(APP_STATE_SCHEMA)};
+
+function cloneAppStateValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneAppStateValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneAppStateValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function createStoreSection() {
+  return {};
+}
+
+export function createAppState({ projectTitle = 'AuraJS Game', template = 'blank' } = {}) {
+  return {
+    schema: APP_STATE_SCHEMA,
+    projectTitle,
+    template,
+    session: createStoreSection(),
+    ui: createStoreSection(),
+    runtime: {
+      startSceneId: null,
+      currentSceneId: null,
+      previousSceneId: null,
+      hudScreenId: null,
+      overlayScreenId: null,
+      modalScreenIds: [],
+    },
+  };
+}
+
+function ensureStoreBucket(appState, bucketName) {
+  if (!appState || typeof appState !== 'object' || Array.isArray(appState)) {
+    throw new Error('Expected appState to be a mutable object.');
+  }
+  if (!appState[bucketName] || typeof appState[bucketName] !== 'object' || Array.isArray(appState[bucketName])) {
+    appState[bucketName] = createStoreSection();
+  }
+  return appState[bucketName];
+}
+
+export function ensureSessionState(appState, featureKey, seed = {}) {
+  const key = typeof featureKey === 'string' ? featureKey.trim() : '';
+  if (!key) {
+    throw new Error('Expected a non-empty session feature key.');
+  }
+  const session = ensureStoreBucket(appState, 'session');
+  if (!session[key] || typeof session[key] !== 'object' || Array.isArray(session[key])) {
+    session[key] = cloneAppStateValue(seed);
+  }
+  return session[key];
+}
+
+export function ensureUiState(appState, featureKey, seed = {}) {
+  const key = typeof featureKey === 'string' ? featureKey.trim() : '';
+  if (!key) {
+    throw new Error('Expected a non-empty UI feature key.');
+  }
+  const ui = ensureStoreBucket(appState, 'ui');
+  if (!ui[key] || typeof ui[key] !== 'object' || Array.isArray(ui[key])) {
+    ui[key] = cloneAppStateValue(seed);
+  }
+  return ui[key];
+}
+
+export function normalizeAppState(appState, { projectTitle = 'AuraJS Game', template = 'blank' } = {}) {
+  const normalized = appState && typeof appState === 'object' && !Array.isArray(appState)
+    ? appState
+    : createAppState({ projectTitle, template });
+  normalized.schema = APP_STATE_SCHEMA;
+  normalized.projectTitle = projectTitle;
+  normalized.template = template;
+  ensureStoreBucket(normalized, 'session');
+  ensureStoreBucket(normalized, 'ui');
+  const runtimeState = normalized.runtime && typeof normalized.runtime === 'object' && !Array.isArray(normalized.runtime)
+    ? normalized.runtime
+    : {};
+  normalized.runtime = {
+    startSceneId: null,
+    currentSceneId: null,
+    previousSceneId: null,
+    hudScreenId: null,
+    overlayScreenId: null,
+    modalScreenIds: [],
+    ...runtimeState,
+    modalScreenIds: Array.isArray(runtimeState.modalScreenIds)
+      ? runtimeState.modalScreenIds
+        .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+        .filter((entry) => entry.length > 0)
+      : [],
+  };
+  return normalized;
+}
+`;
+}
+
+export function renderProjectInspectorModule() {
+  return `// Project Inspector overlay for registry-backed authored projects.
+import projectRegistry from './project-registry.js';
+import { ensureUiState } from './app-state.js';
+
+const PROJECT_INSPECTOR_SCHEMA = ${JSON.stringify(PROJECT_INSPECTOR_SCHEMA)};
+const PROJECT_INSPECTOR_TOGGLE_KEY = 'F1';
+const HUD_MARGIN = 12;
+const HUD_PADDING = 10;
+const HUD_ROW_GAP = 8;
+const HUD_SCENE_ROW_HEIGHT = 28;
+const HUD_TOOLBAR_ROW_HEIGHT = 28;
+const HUD_CHIP_GAP = 8;
+const HUD_MINIMIZED_HEIGHT = 30;
+const HUD_MINIMIZED_WIDTH = 260;
+const HUD_MINIMIZED_MAX_WIDTH = 420;
+
+function summarizeEntries(entries, formatter) {
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length === 0) return '(none)';
+  return list.map((entry) => formatter(entry)).join(', ');
+}
+
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function getRuntime() {
+  return globalThis.aura || null;
+}
+
+function getWindowSize() {
+  const runtime = getRuntime();
+  if (hasMethod(runtime?.window, 'getSize')) {
+    return runtime.window.getSize();
+  }
+  return { width: 1280, height: 720 };
+}
+
+function inputIsKeyPressed(input, key) {
+  return hasMethod(input, 'isKeyPressed') && input.isKeyPressed(String(key || '').toLowerCase());
+}
+
+function mousePressed(input, name = 'left', fallbackIndex = 0) {
+  if (hasMethod(input?.mouse, 'isPressed')) {
+    return input.mouse.isPressed(name);
+  }
+  if (hasMethod(input, 'isMousePressed')) {
+    return input.isMousePressed(fallbackIndex);
+  }
+  return false;
+}
+
+function mousePosition(input) {
+  if (hasMethod(input, 'getMousePosition')) {
+    const point = input.getMousePosition();
+    return {
+      x: Number.isFinite(point?.x) ? Number(point.x) : 0,
+      y: Number.isFinite(point?.y) ? Number(point.y) : 0,
+    };
+  }
+  return {
+    x: Number.isFinite(input?.mouse?.x) ? Number(input.mouse.x) : 0,
+    y: Number.isFinite(input?.mouse?.y) ? Number(input.mouse.y) : 0,
+  };
+}
+
+function pointInRect(point, rect) {
+  if (!point || !rect) return false;
+  return point.x >= rect.x
+    && point.x <= rect.x + rect.width
+    && point.y >= rect.y
+    && point.y <= rect.y + rect.height;
+}
+
+function approximateChipWidth(label) {
+  return Math.max(76, 18 + (String(label || '').length * 8));
+}
+
+function hudStatusFlags(snapshot) {
+  const flags = [];
+  if (snapshot.recording?.active === true) {
+    flags.push('REC');
+  }
+  if (snapshot.paused === true) {
+    flags.push('PAUSED');
+  }
+  return flags;
+}
+
+function buildMinimizedHudLabel(snapshot) {
+  const parts = [
+    \`\${PROJECT_INSPECTOR_TOGGLE_KEY} Play HUD\`,
+    snapshot.activeSceneId || '(none)',
+    ...hudStatusFlags(snapshot),
+  ];
+  return parts.join('  •  ');
+}
+
+function buildExpandedHudStatusLabel(snapshot) {
+  const parts = [
+    \`Scene \${snapshot.activeSceneId || '(none)'}\`,
+    snapshot.theme?.presetId ? \`Theme \${snapshot.theme.presetId}\` : null,
+    ...hudStatusFlags(snapshot),
+  ].filter(Boolean);
+  return parts.join('  •  ');
+}
+
+function buildToolbarActions({
+  canRecord = false,
+  recordingActive = false,
+  canScreenshot = false,
+  canRestartScene = false,
+  canRestartApp = false,
+  canPause = false,
+  paused = false,
+} = {}) {
+  return [
+    {
+      id: 'record',
+      label: recordingActive ? 'Stop Rec' : 'Record',
+      enabled: canRecord,
+      active: recordingActive,
+    },
+    {
+      id: 'screenshot',
+      label: 'Screenshot',
+      enabled: canScreenshot,
+      active: false,
+    },
+    {
+      id: 'restart-scene',
+      label: 'Restart Scene',
+      enabled: canRestartScene,
+      active: false,
+    },
+    {
+      id: 'restart-app',
+      label: 'Restart App',
+      enabled: canRestartApp,
+      active: false,
+    },
+    {
+      id: 'pause',
+      label: paused ? 'Resume' : 'Pause',
+      enabled: canPause,
+      active: paused,
+    },
+    {
+      id: 'minimize',
+      label: 'Minimize',
+      enabled: true,
+      active: false,
+    },
+  ];
+}
+
+function drawChip(draw2d, colorFactory, chip, options = {}) {
+  const enabled = chip.enabled !== false;
+  const active = options.active === true;
+  const background = !enabled
+    ? colorFactory(0.18, 0.2, 0.24, 0.72)
+    : active
+      ? colorFactory(0.28, 0.54, 0.92, 0.94)
+      : colorFactory(0.11, 0.15, 0.2, 0.92);
+  const border = !enabled
+    ? colorFactory(0.28, 0.3, 0.34, 0.94)
+    : active
+      ? colorFactory(0.94, 0.82, 0.32, 0.96)
+      : colorFactory(0.38, 0.76, 1, 0.82);
+  const textColor = !enabled
+    ? colorFactory(0.62, 0.66, 0.72, 0.92)
+    : colorFactory(0.96, 0.98, 1, 1);
+
+  draw2d.rect(chip.x, chip.y, chip.width, chip.height, background);
+  draw2d.rect(chip.x, chip.y, chip.width, 2, border);
+  draw2d.text(chip.label, chip.x + 10, chip.y + 7, {
+    size: 12,
+    color: textColor,
+  });
+}
+
+function drawSceneStrip(draw2d, colorFactory, snapshot, panelX, panelY, panelWidth, uiState = null) {
+  const chips = [];
+  let x = panelX + HUD_PADDING;
+  const y = panelY + 22;
+  const maxX = panelX + panelWidth - HUD_PADDING;
+  const scenes = Array.isArray(snapshot.scenes) ? snapshot.scenes : [];
+  for (const scene of scenes) {
+    const label = scene.id || '(scene)';
+    const width = approximateChipWidth(label);
+    if (x + width > maxX) {
+      const remaining = scenes.length - chips.length;
+      if (remaining > 0) {
+        const overflowLabel = '+' + String(remaining);
+        const overflowWidth = approximateChipWidth(overflowLabel);
+        chips.push({
+          id: '__overflow__',
+          label: overflowLabel,
+          x,
+          y,
+          width: Math.min(overflowWidth, Math.max(60, maxX - x)),
+          height: HUD_SCENE_ROW_HEIGHT,
+          enabled: false,
+          active: false,
+        });
+      }
+      break;
+    }
+    chips.push({
+      id: scene.id,
+      label,
+      x,
+      y,
+      width,
+      height: HUD_SCENE_ROW_HEIGHT,
+      enabled: true,
+      active: scene.active === true,
+    });
+    x += width + HUD_CHIP_GAP;
+  }
+
+  for (const chip of chips) {
+    drawChip(draw2d, colorFactory, chip, { active: chip.active });
+  }
+  if (uiState) {
+    uiState.sceneChips = chips.map((chip) => ({ ...chip }));
+  }
+}
+
+function layoutToolbar(snapshot, panelX, panelY, panelWidth) {
+  const buttons = [];
+  let x = panelX + HUD_PADDING;
+  const y = panelY + 22 + HUD_SCENE_ROW_HEIGHT + HUD_ROW_GAP;
+  const maxX = panelX + panelWidth - HUD_PADDING;
+  const actions = Array.isArray(snapshot.toolbarActions) ? snapshot.toolbarActions : [];
+  for (const action of actions) {
+    const width = approximateChipWidth(action.label);
+    if (x + width > maxX) break;
+    buttons.push({
+      id: action.id,
+      label: action.label,
+      enabled: action.enabled !== false,
+      active: action.active === true,
+      x,
+      y,
+      width,
+      height: HUD_TOOLBAR_ROW_HEIGHT,
+    });
+    x += width + HUD_CHIP_GAP;
+  }
+  return buttons;
+}
+
+function drawProjectInspectorOverlay(snapshot, uiState) {
+  const runtime = getRuntime();
+  if (!runtime?.draw2d || typeof runtime.draw2d.rect !== 'function' || typeof runtime.draw2d.text !== 'function' || typeof runtime.rgba !== 'function') {
+    return;
+  }
+
+  const windowSize = getWindowSize();
+  const panelX = HUD_MARGIN;
+  const panelY = HUD_MARGIN;
+  const panelWidth = Math.max(420, Math.min(1240, Number(windowSize?.width || 1280) - (HUD_MARGIN * 2)));
+
+  if (snapshot.presentation === 'minimized') {
+    const label = buildMinimizedHudLabel(snapshot);
+    const chip = {
+      x: panelX,
+      y: panelY,
+      width: Math.min(HUD_MINIMIZED_MAX_WIDTH, Math.max(HUD_MINIMIZED_WIDTH, approximateChipWidth(label) + 22)),
+      height: HUD_MINIMIZED_HEIGHT,
+      label,
+      enabled: true,
+      active: snapshot.paused === true || snapshot.recording?.active === true,
+    };
+    drawChip(runtime.draw2d, runtime.rgba, chip, { active: chip.active });
+    uiState.minimizedChip = chip;
+    uiState.toolbarButtons = [];
+    uiState.sceneChips = [];
+    return;
+  }
+
+  const panelHeight = 22 + HUD_SCENE_ROW_HEIGHT + HUD_ROW_GAP + HUD_TOOLBAR_ROW_HEIGHT + HUD_PADDING;
+
+  runtime.draw2d.rect(panelX, panelY, panelWidth, panelHeight, runtime.rgba(0.03, 0.05, 0.08, 0.92));
+  runtime.draw2d.rect(panelX, panelY, panelWidth, 3, runtime.rgba(0.38, 0.76, 1.0, 0.92));
+  runtime.draw2d.text(\`\${PROJECT_INSPECTOR_TOGGLE_KEY} Play HUD\`, panelX + HUD_PADDING, panelY + 6, {
+    size: 13,
+    color: runtime.rgba(1, 0.97, 0.86, 1),
+  });
+  runtime.draw2d.text(buildExpandedHudStatusLabel(snapshot), panelX + panelWidth - 240, panelY + 6, {
+    size: 12,
+    color: runtime.rgba(0.88, 0.94, 1, 1),
+  });
+
+  drawSceneStrip(runtime.draw2d, runtime.rgba, snapshot, panelX, panelY, panelWidth, uiState);
+  uiState.toolbarButtons = layoutToolbar(snapshot, panelX, panelY, panelWidth);
+  for (const button of uiState.toolbarButtons) {
+    drawChip(runtime.draw2d, runtime.rgba, button, { active: button.active });
+  }
+  uiState.minimizedChip = null;
+}
+
+function cloneInspectorValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneInspectorValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneInspectorValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+export function buildProjectInspectorSnapshot({
+  projectTitle = null,
+  sceneRegistry = null,
+  getActiveSceneId = null,
+  appState = null,
+  getUiThemeState = null,
+  enabled = false,
+  minimized = false,
+  paused = false,
+  recording = null,
+  actions = null,
+} = {}) {
+  const activeSceneId = typeof getActiveSceneId === 'function' ? getActiveSceneId() : null;
+  const registryScenes = Array.isArray(projectRegistry.scenes) ? projectRegistry.scenes : [];
+  const registryScreens = Array.isArray(projectRegistry.screens) ? projectRegistry.screens : [];
+  const registryPrefabs = Array.isArray(projectRegistry.prefabs) ? projectRegistry.prefabs : [];
+  const registryDataFiles = Array.isArray(projectRegistry.dataFiles) ? projectRegistry.dataFiles : [];
+  const runtimeSceneIds = sceneRegistry && typeof sceneRegistry === 'object' && sceneRegistry.scenes
+    ? Object.keys(sceneRegistry.scenes)
+    : [];
+  const sessionState = appState && typeof appState?.session === 'object' && !Array.isArray(appState.session)
+    ? appState.session
+    : {};
+  const uiState = appState && typeof appState?.ui === 'object' && !Array.isArray(appState.ui)
+    ? appState.ui
+    : {};
+  const runtimeState = appState && typeof appState?.runtime === 'object' && !Array.isArray(appState.runtime)
+    ? appState.runtime
+    : {};
+  const themeState = typeof getUiThemeState === 'function' ? getUiThemeState() : null;
+  const uiPreferences = uiState.preferences && typeof uiState.preferences === 'object' && !Array.isArray(uiState.preferences)
+    ? cloneInspectorValue(uiState.preferences)
+    : null;
+
+  return {
+    schema: PROJECT_INSPECTOR_SCHEMA,
+    template: projectRegistry.template || 'blank',
+    projectTitle: projectTitle || projectRegistry.projectTitle || 'AuraJS Game',
+    enabled: enabled === true,
+    presentation: minimized === true ? 'minimized' : 'expanded',
+    toggleKey: PROJECT_INSPECTOR_TOGGLE_KEY,
+    sourceOfTruth: 'src/runtime/project-registry.js',
+    startSceneId: projectRegistry.startSceneId || null,
+    activeSceneId: activeSceneId || null,
+    paused: paused === true,
+    recording: recording && typeof recording === 'object'
+      ? {
+        supported: recording.supported === true,
+        active: recording.active === true,
+      }
+      : {
+        supported: false,
+        active: false,
+      },
+    runtimeSceneIds,
+    appStateKeys: appState && typeof appState === 'object' && !Array.isArray(appState)
+      ? Object.keys(appState).sort()
+      : [],
+    appStateBuckets: ['session', 'ui', 'runtime'],
+    sessionKeys: Object.keys(sessionState).sort(),
+    uiKeys: Object.keys(uiState).sort(),
+    runtimeKeys: Object.keys(runtimeState).sort(),
+    uiPreferencesPath: 'appState.ui.preferences',
+    uiPreferences,
+    theme: themeState && typeof themeState === 'object'
+      ? {
+        presetId: typeof themeState.presetId === 'string' ? themeState.presetId : null,
+        presetLabel: typeof themeState.presetLabel === 'string' ? themeState.presetLabel : null,
+        density: typeof themeState.density === 'string' ? themeState.density : null,
+        contrast: typeof themeState.contrast === 'string' ? themeState.contrast : null,
+        textScale: typeof themeState.textScale === 'string' ? themeState.textScale : null,
+        focusVisibility: typeof themeState.focusVisibility === 'string' ? themeState.focusVisibility : null,
+        availableThemeIds: Array.isArray(themeState.availableThemeIds) ? [...themeState.availableThemeIds] : [],
+      }
+      : null,
+    mountedScreens: {
+      hud: typeof runtimeState.hudScreenId === 'string' ? runtimeState.hudScreenId : null,
+      overlay: typeof runtimeState.overlayScreenId === 'string' ? runtimeState.overlayScreenId : null,
+      modals: Array.isArray(runtimeState.modalScreenIds) ? [...runtimeState.modalScreenIds] : [],
+    },
+    stateOwnership: {
+      engineApi: 'aura',
+      sharedSession: 'appState.session',
+      sharedUi: 'appState.ui',
+      sharedUiPreferences: 'appState.ui.preferences',
+      runtimeFacts: 'appState.runtime',
+      sceneLocal: 'sceneState',
+      sceneEntryPayload: 'sceneFlow.current.data',
+      screenPayloads: 'screenShell.hud|overlay|modals[].data',
+      themeModule: 'src/runtime/ui-theme.js',
+      retainedSettingsHelpers: 'src/runtime/ui-settings.js',
+      retainedFormsHelpers: 'src/runtime/ui-forms.js',
+      authoredInput: 'config/* and content/*',
+    },
+    scenes: registryScenes.map((entry) => ({
+      id: entry.id,
+      path: entry.path,
+      active: entry.id === activeSceneId,
+    })),
+    screens: registryScreens.map((entry) => ({
+      id: entry.id,
+      path: entry.path,
+    })),
+    prefabs: registryPrefabs.map((entry) => ({
+      id: entry.id,
+      role: entry.role || null,
+      path: entry.path,
+    })),
+    dataFiles: [...registryDataFiles],
+    toolbarActions: Array.isArray(actions) ? actions.map((entry) => ({ ...entry })) : [],
+  };
+}
+
+export function createProjectInspector({
+  projectTitle = null,
+  sceneRegistry = null,
+  getActiveSceneId = null,
+  appState = null,
+  getUiThemeState = null,
+  onSelectScene = null,
+  onRestartScene = null,
+  onRestartApp = null,
+  getPaused = null,
+  togglePaused = null,
+  getRecordingState = null,
+  toggleRecording = null,
+} = {}) {
+  const playHudState = ensureUiState(appState, 'playHud', {
+    enabled: false,
+    minimized: false,
+  });
+  let enabled = playHudState.enabled === true;
+  let minimized = playHudState.minimized === true;
+  let pointerPressedLastFrame = false;
+  const uiState = {
+    sceneChips: [],
+    toolbarButtons: [],
+    minimizedChip: null,
+  };
+
+  function syncPlayHudState() {
+    playHudState.enabled = enabled === true;
+    playHudState.minimized = minimized === true;
+  }
+
+  function recordingState() {
+    if (typeof getRecordingState !== 'function') {
+      return { supported: false, active: false };
+    }
+    const state = getRecordingState();
+    return {
+      supported: state?.supported === true,
+      active: state?.active === true,
+    };
+  }
+
+  function currentActions() {
+    const runtime = getRuntime();
+    return buildToolbarActions({
+      canRecord: typeof toggleRecording === 'function' && recordingState().supported === true,
+      recordingActive: recordingState().active === true,
+      canScreenshot: hasMethod(runtime?.window, 'screenshot'),
+      canRestartScene: typeof onRestartScene === 'function',
+      canRestartApp: typeof onRestartApp === 'function',
+      canPause: typeof togglePaused === 'function',
+      paused: typeof getPaused === 'function' ? getPaused() === true : false,
+    });
+  }
+
+  function runToolbarAction(actionId) {
+    const runtime = getRuntime();
+    switch (actionId) {
+      case 'record':
+        if (typeof toggleRecording === 'function') {
+          toggleRecording();
+        }
+        return true;
+      case 'screenshot':
+        if (hasMethod(runtime?.window, 'screenshot')) {
+          runtime.window.screenshot();
+          return true;
+        }
+        return false;
+      case 'restart-scene':
+        if (typeof onRestartScene === 'function') {
+          onRestartScene();
+          return true;
+        }
+        return false;
+      case 'restart-app':
+        if (typeof onRestartApp === 'function') {
+          onRestartApp();
+          return true;
+        }
+        return false;
+      case 'pause':
+        if (typeof togglePaused === 'function') {
+          togglePaused();
+          return true;
+        }
+        return false;
+      case 'minimize':
+        minimized = !minimized;
+        syncPlayHudState();
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  function runSceneSelection(sceneId) {
+    if (typeof onSelectScene !== 'function' || sceneId === '__overflow__') {
+      return false;
+    }
+    const result = onSelectScene(sceneId);
+    return result !== false && result?.ok !== false;
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    get minimized() {
+      return minimized;
+    },
+    show() {
+      enabled = true;
+      syncPlayHudState();
+      return enabled;
+    },
+    hide() {
+      enabled = false;
+      syncPlayHudState();
+      return enabled;
+    },
+    setEnabled(nextValue) {
+      enabled = nextValue === true;
+      syncPlayHudState();
+      return enabled;
+    },
+    toggle() {
+      enabled = !enabled;
+      syncPlayHudState();
+      return enabled;
+    },
+    setMinimized(nextValue) {
+      minimized = nextValue === true;
+      syncPlayHudState();
+      return minimized;
+    },
+    toggleMinimized() {
+      minimized = !minimized;
+      syncPlayHudState();
+      return minimized;
+    },
+    update(input = getRuntime()?.input || null) {
+      const pointerPressed = mousePressed(input, 'left', 0);
+      const pointerJustPressed = pointerPressed && !pointerPressedLastFrame;
+      pointerPressedLastFrame = pointerPressed;
+      if (inputIsKeyPressed(input, 'f1')) {
+        enabled = !enabled;
+        syncPlayHudState();
+        return enabled;
+      }
+      if (!enabled) {
+        return enabled;
+      }
+      if (inputIsKeyPressed(input, 'f2')) {
+        runToolbarAction('screenshot');
+      }
+      if (inputIsKeyPressed(input, 'p')) {
+        runToolbarAction('pause');
+      }
+      if (pointerJustPressed) {
+        const point = mousePosition(input);
+        if (minimized && pointInRect(point, uiState.minimizedChip)) {
+          minimized = false;
+          syncPlayHudState();
+          return enabled;
+        }
+        for (const chip of uiState.sceneChips) {
+          if (chip.enabled !== false && chip.active !== true && pointInRect(point, chip)) {
+            runSceneSelection(chip.id);
+            return enabled;
+          }
+        }
+        for (const button of uiState.toolbarButtons) {
+          if (button.enabled !== false && pointInRect(point, button)) {
+            runToolbarAction(button.id);
+            break;
+          }
+        }
+      }
+      return enabled;
+    },
+    snapshot() {
+      return buildProjectInspectorSnapshot({
+        projectTitle,
+        sceneRegistry,
+        getActiveSceneId,
+        appState,
+        getUiThemeState,
+        enabled,
+        minimized,
+        paused: typeof getPaused === 'function' ? getPaused() === true : false,
+        recording: recordingState(),
+        actions: currentActions(),
+      });
+    },
+    draw() {
+      if (!enabled) return;
+      drawProjectInspectorOverlay(this.snapshot(), uiState);
+    },
+  };
+}
+`;
+}
+
+export function renderRegistryBackedRuntimeApp({ template }) {
+  return `import {
+  createAppState,
+  ensureSessionState,
+  ensureUiState,
+  normalizeAppState,
+} from './app-state.js';
+import {
+  applyUiTheme as applySharedUiTheme,
+  ensureUiPreferences as ensureSharedUiPreferences,
+  inspectUiTheme as inspectSharedUiTheme,
+  resetUiPreferences as resetSharedUiPreferences,
+  updateUiPreferences as updateSharedUiPreferences,
+} from './ui-theme.js';
+import projectRegistry, { resolveProjectScreen } from './project-registry.js';
+import { createProjectInspector } from './project-inspector.js';
+import { createSceneRegistry } from './scene-registry.js';
+import { createSceneFlow } from './scene-flow.js';
+import { createScreenShell } from './screen-shell.js';
+import { assertRuntimeCapabilities } from './capabilities.js';
+
+const PROJECT_STATE_SCHEMA = ${JSON.stringify(PROJECT_STATE_SCHEMA)};
+const PROJECT_CONTINUITY_STATE_SCHEMA = 'aurajs.project-continuity-state.v1';
+const PROJECT_CONTINUITY_STATE_VERSION = 1;
+
+function cloneProjectValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneProjectValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneProjectValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function captureSceneSnapshot(scene, sceneId = null) {
+  if (!scene || typeof scene !== 'object') {
+    return {
+      ok: false,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_missing',
+      detail: null,
+      hasSnapshot: false,
+      snapshot: null,
+    };
+  }
+  const exportFn = typeof scene.exportState === 'function'
+    ? scene.exportState
+    : typeof scene.getState === 'function'
+      ? scene.getState
+      : null;
+  if (!exportFn) {
+    return {
+      ok: true,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_skipped',
+      detail: null,
+      hasSnapshot: false,
+      snapshot: null,
+    };
+  }
+  try {
+    const snapshot = exportFn.call(scene);
+    return {
+      ok: true,
+      sceneId: sceneId || null,
+      reasonCode: snapshot == null ? 'project_state_scene_empty' : 'project_state_scene_capture_ok',
+      detail: null,
+      hasSnapshot: snapshot != null,
+      snapshot: snapshot == null ? null : cloneProjectValue(snapshot),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_capture_failed',
+      detail: error instanceof Error ? error.message : String(error),
+      hasSnapshot: false,
+      snapshot: null,
+    };
+  }
+}
+
+function applySceneSnapshot(scene, snapshot, sceneId = null) {
+  if (!scene || snapshot == null) {
+    return {
+      ok: true,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_skipped',
+      detail: null,
+      restored: false,
+    };
+  }
+  const applyFn = typeof scene.applyState === 'function'
+    ? scene.applyState
+    : typeof scene.importState === 'function'
+      ? scene.importState
+      : null;
+  if (!applyFn) {
+    return {
+      ok: true,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_skipped',
+      detail: null,
+      restored: false,
+    };
+  }
+  try {
+    const result = applyFn.call(scene, cloneProjectValue(snapshot));
+    if (result === false) {
+      return {
+        ok: false,
+        sceneId: sceneId || null,
+        reasonCode: 'project_state_scene_apply_failed',
+        detail: null,
+        restored: false,
+      };
+    }
+    if (result && typeof result === 'object' && result.ok === false) {
+      return {
+        ok: false,
+        sceneId: sceneId || null,
+        reasonCode: typeof result.reasonCode === 'string' ? result.reasonCode : 'project_state_scene_apply_failed',
+        detail: result.detail || null,
+        restored: false,
+      };
+    }
+    return {
+      ok: true,
+      sceneId: sceneId || null,
+      reasonCode: result && typeof result.reasonCode === 'string'
+        ? result.reasonCode
+        : 'project_state_scene_apply_ok',
+      detail: result && typeof result === 'object' ? result.detail || null : null,
+      restored: true,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      sceneId: sceneId || null,
+      reasonCode: 'project_state_scene_apply_failed',
+      detail: error instanceof Error ? error.message : String(error),
+      restored: false,
+    };
+  }
+}
+
+function normalizeProjectContinuityState(snapshot, fallbackTemplate) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    return null;
+  }
+
+  const source = snapshot.continuity && typeof snapshot.continuity === 'object' && !Array.isArray(snapshot.continuity)
+    ? snapshot.continuity
+    : snapshot;
+  const sceneStateSource = source.sceneStates && typeof source.sceneStates === 'object' && !Array.isArray(source.sceneStates)
+    ? source.sceneStates
+    : source.scenes && typeof source.scenes === 'object' && !Array.isArray(source.scenes)
+      ? source.scenes
+      : {};
+  const sceneStates = {};
+  for (const sceneId of Object.keys(sceneStateSource).sort()) {
+    sceneStates[sceneId] = cloneProjectValue(sceneStateSource[sceneId]);
+  }
+
+  return {
+    schema: PROJECT_CONTINUITY_STATE_SCHEMA,
+    version: Number.isInteger(Number(source.version)) && Number(source.version) > 0
+      ? Number(source.version)
+      : PROJECT_CONTINUITY_STATE_VERSION,
+    template: typeof source.template === 'string' && source.template.trim()
+      ? source.template.trim()
+      : fallbackTemplate,
+    activeSceneId: typeof source.activeSceneId === 'string' && source.activeSceneId.trim()
+      ? source.activeSceneId.trim()
+      : null,
+    currentSceneData: cloneProjectValue(source.currentSceneData ?? null),
+    appState: source.appState && typeof source.appState === 'object' && !Array.isArray(source.appState)
+      ? cloneProjectValue(source.appState)
+      : null,
+    sceneFlow: source.sceneFlow && typeof source.sceneFlow === 'object' && !Array.isArray(source.sceneFlow)
+      ? cloneProjectValue(source.sceneFlow)
+      : null,
+    screenShell: source.screenShell && typeof source.screenShell === 'object' && !Array.isArray(source.screenShell)
+      ? cloneProjectValue(source.screenShell)
+      : null,
+    sceneStates,
+    ownership: source.ownership && typeof source.ownership === 'object' && !Array.isArray(source.ownership)
+      ? cloneProjectValue(source.ownership)
+      : null,
+  };
+}
+
+function normalizeContinuitySource(source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    return null;
+  }
+  return {
+    kind: typeof source.kind === 'string' && source.kind.trim() ? source.kind.trim() : null,
+    name: typeof source.name === 'string' && source.name.trim() ? source.name.trim() : null,
+    path: typeof source.path === 'string' && source.path.trim() ? source.path.trim() : null,
+    stateSchemaVersion: typeof source.stateSchemaVersion === 'string' && source.stateSchemaVersion.trim()
+      ? source.stateSchemaVersion.trim()
+      : null,
+    payloadFingerprint: typeof source.payloadFingerprint === 'string' && source.payloadFingerprint.trim()
+      ? source.payloadFingerprint.trim()
+      : null,
+    reasonCode: typeof source.reasonCode === 'string' && source.reasonCode.trim()
+      ? source.reasonCode.trim()
+      : null,
+    migration: source.migration && typeof source.migration === 'object' && !Array.isArray(source.migration)
+      ? cloneProjectValue(source.migration)
+      : null,
+  };
+}
+
+function createContinuitySummary(
+  sceneResults,
+  {
+    phase = 'restore',
+    reasonCode = phase === 'capture' ? 'project_state_capture_ok' : 'project_state_apply_ok',
+    activeSceneId = null,
+    continuityVersion = PROJECT_CONTINUITY_STATE_VERSION,
+    detail = null,
+    source = null,
+  } = {},
+) {
+  const normalizedSceneResults = Array.isArray(sceneResults)
+    ? sceneResults.map((entry) => cloneProjectValue(entry))
+    : [];
+  const skippedSceneIds = normalizedSceneResults
+    .filter((entry) => entry?.reasonCode === 'project_state_scene_skipped')
+    .map((entry) => entry.sceneId)
+    .filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+  const failedSceneIds = normalizedSceneResults
+    .filter((entry) => entry?.ok === false)
+    .map((entry) => entry.sceneId)
+    .filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+  const capturedSceneIds = normalizedSceneResults
+    .filter((entry) => entry?.hasSnapshot === true)
+    .map((entry) => entry.sceneId)
+    .filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+  const restoredSceneIds = normalizedSceneResults
+    .filter((entry) => entry?.restored === true)
+    .map((entry) => entry.sceneId)
+    .filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+  return {
+    phase,
+    reasonCode,
+    activeSceneId: typeof activeSceneId === 'string' && activeSceneId.trim() ? activeSceneId.trim() : null,
+    continuityVersion: Number.isInteger(Number(continuityVersion)) && Number(continuityVersion) > 0
+      ? Number(continuityVersion)
+      : PROJECT_CONTINUITY_STATE_VERSION,
+    totalScenes: normalizedSceneResults.length,
+    capturedSceneIds,
+    restoredSceneIds,
+    skippedSceneIds,
+    failedSceneIds,
+    detail: typeof detail === 'string' && detail.trim() ? detail.trim() : null,
+    source: normalizeContinuitySource(source),
+    sceneResults: normalizedSceneResults,
+  };
+}
+
+export function createApp() {
+  const projectTitle = projectRegistry.projectTitle || 'AuraJS Game';
+  const appState = createAppState({
+    projectTitle,
+    template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+  });
+  normalizeAppState(appState, {
+    projectTitle,
+    template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+  });
+  ensureSharedUiPreferences(appState);
+  let sceneRegistry = null;
+  let sceneFlow = null;
+  let screenShell = null;
+  let seededSceneId = null;
+  let runtimeStarted = false;
+  let paused = false;
+  const recordingState = {
+    supported: false,
+    active: false,
+    audioSupported: false,
+    path: null,
+    reasonCode: null,
+  };
+  const currentSceneId = () => sceneFlow?.getState().currentSceneId || seededSceneId || null;
+  function readPendingDevRestoreMeta() {
+    const runtime = globalThis.aura;
+    return normalizeContinuitySource(
+      runtime?.__aurajsPendingDevRestore && typeof runtime.__aurajsPendingDevRestore === 'object'
+        ? runtime.__aurajsPendingDevRestore
+        : runtime?.__aurajsDevRestore,
+    );
+  }
+  function ensureRuntimeContinuityState() {
+    normalizeAppState(appState, {
+      projectTitle,
+      template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+    });
+    const runtimeState = appState.runtime && typeof appState.runtime === 'object' && !Array.isArray(appState.runtime)
+      ? appState.runtime
+      : {};
+    const continuityState = runtimeState.continuity && typeof runtimeState.continuity === 'object' && !Array.isArray(runtimeState.continuity)
+      ? runtimeState.continuity
+      : {
+        lastCapture: null,
+        lastRestore: null,
+      };
+    runtimeState.continuity = continuityState;
+    appState.runtime = runtimeState;
+    return continuityState;
+  }
+  function recordContinuityCapture(summary) {
+    const continuityState = ensureRuntimeContinuityState();
+    continuityState.lastCapture = summary ? cloneProjectValue(summary) : null;
+    return continuityState.lastCapture;
+  }
+  function recordContinuityRestore(summary) {
+    const continuityState = ensureRuntimeContinuityState();
+    continuityState.lastRestore = summary ? cloneProjectValue(summary) : null;
+    return continuityState.lastRestore;
+  }
+  function replaceAppState(nextValue) {
+    if (!nextValue || typeof nextValue !== 'object' || Array.isArray(nextValue)) {
+      return appState;
+    }
+    for (const key of Object.keys(appState)) {
+      delete appState[key];
+    }
+    for (const [key, value] of Object.entries(cloneProjectValue(nextValue))) {
+      appState[key] = value;
+    }
+    normalizeAppState(appState, {
+      projectTitle,
+      template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+    });
+    ensureSharedUiPreferences(appState);
+    paused = appState.runtime?.paused === true;
+    return appState;
+  }
+  function syncAppStateRuntime(previousSceneId = null) {
+    normalizeAppState(appState, {
+      projectTitle,
+      template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+    });
+    const recordingSnapshot = getRecordingState();
+    const runtimeState = appState.runtime && typeof appState.runtime === 'object' && !Array.isArray(appState.runtime)
+      ? appState.runtime
+      : {};
+    const continuityState = runtimeState.continuity && typeof runtimeState.continuity === 'object' && !Array.isArray(runtimeState.continuity)
+      ? cloneProjectValue(runtimeState.continuity)
+      : {
+        lastCapture: null,
+        lastRestore: null,
+      };
+    const shellState = typeof screenShell?.getState === 'function'
+      ? screenShell.getState()
+      : null;
+    appState.projectTitle = projectTitle;
+    appState.template = projectRegistry.template || ${JSON.stringify(template || 'blank')};
+    appState.runtime = {
+      ...runtimeState,
+      startSceneId: projectRegistry.startSceneId || null,
+      currentSceneId: currentSceneId(),
+      previousSceneId: previousSceneId ?? runtimeState.previousSceneId ?? null,
+      hudScreenId: shellState?.hud?.screenId || null,
+      overlayScreenId: shellState?.overlay?.screenId || null,
+      modalScreenIds: Array.isArray(shellState?.modals) ? shellState.modals.map((entry) => entry.screenId) : [],
+      paused,
+      recordingSupported: recordingSnapshot.supported === true,
+      recordingActive: recordingSnapshot.active === true,
+      continuity: continuityState,
+    };
+  }
+  const appContext = {
+    projectTitle,
+    projectRegistry,
+    appState,
+    replaceAppState,
+    getAppState() {
+      return appState;
+    },
+    ensureSessionState(featureKey, seed = {}) {
+      return ensureSessionState(appState, featureKey, seed);
+    },
+    ensureUiState(featureKey, seed = {}) {
+      return ensureUiState(appState, featureKey, seed);
+    },
+    ensureUiPreferences(seed = null) {
+      return ensureSharedUiPreferences(appState, seed);
+    },
+    getSessionState(featureKey, fallback = null) {
+      const key = typeof featureKey === 'string' ? featureKey.trim() : '';
+      if (!key) return fallback;
+      return appState.session?.[key] ?? fallback;
+    },
+    getUiState(featureKey, fallback = null) {
+      const key = typeof featureKey === 'string' ? featureKey.trim() : '';
+      if (!key) return fallback;
+      return appState.ui?.[key] ?? fallback;
+    },
+    getUiPreferences() {
+      return ensureSharedUiPreferences(appState);
+    },
+    updateUiPreferences(patch = {}) {
+      return updateSharedUiPreferences(appState, patch);
+    },
+    resetUiPreferences(seed = null) {
+      return resetSharedUiPreferences(appState, seed);
+    },
+    applyUiTheme(options = {}) {
+      return applySharedUiTheme(appState, options);
+    },
+    getUiThemeState() {
+      return inspectSharedUiTheme(appState);
+    },
+    getActiveSceneId: currentSceneId,
+    getCurrentScenePayload() {
+      return sceneFlow?.current?.()?.data ?? null;
+    },
+    getSceneFlowState() {
+      return sceneFlow?.getState() || null;
+    },
+    getScreenShellState() {
+      return screenShell?.getState() || null;
+    },
+    replaceScene(sceneId, data = null) {
+      const previousSceneId = currentSceneId();
+      const result = sceneFlow?.replace(sceneId, data);
+      if (!result?.ok) {
+        throw new Error(\`Unknown scene "\${sceneId}". [reason:\${result?.reasonCode || 'scene_flow_unavailable'}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return result;
+    },
+    pushScene(sceneId, data = null) {
+      const previousSceneId = currentSceneId();
+      const result = sceneFlow?.push(sceneId, data);
+      if (!result?.ok) {
+        throw new Error(\`Unable to push scene "\${sceneId}". [reason:\${result?.reasonCode || 'scene_flow_unavailable'}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return result;
+    },
+    popScene(result = null) {
+      const previousSceneId = currentSceneId();
+      const outcome = sceneFlow?.pop(result);
+      if (!outcome?.ok) {
+        throw new Error(\`Unable to pop scene. [reason:\${outcome?.reasonCode || 'scene_flow_unavailable'}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return outcome;
+    },
+    canPopScene() {
+      return sceneFlow?.canPop() === true;
+    },
+    setHudScreen(screenId, data = null) {
+      const result = screenShell?.setHud(screenId, data) || null;
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    clearHudScreen() {
+      const result = screenShell?.clearHud() || null;
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    showOverlayScreen(screenId, data = null) {
+      const result = screenShell?.showOverlay(screenId, data) || null;
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    clearOverlayScreen() {
+      const result = screenShell?.clearOverlay() || null;
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    pushModalScreen(screenId, data = null) {
+      const result = screenShell?.pushModal(screenId, data) || null;
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    popModalScreen(result = null) {
+      const outcome = screenShell?.popModal(result) || null;
+      syncAppStateRuntime(currentSceneId());
+      return outcome;
+    },
+    jumpToScene(sceneId, data = null) {
+      return jumpToScene(sceneId, data);
+    },
+    swapScene(sceneId, data = null) {
+      return this.replaceScene(sceneId, data);
+    },
+    setPaused(nextValue = true) {
+      return setPaused(nextValue);
+    },
+    togglePaused() {
+      return togglePaused();
+    },
+    restartCurrentScene() {
+      return restartCurrentScene();
+    },
+    restartStartScene() {
+      return restartStartScene();
+    },
+    get sceneRegistry() {
+      return sceneRegistry;
+    },
+    get sceneFlow() {
+      return sceneFlow;
+    },
+    get screenShell() {
+      return screenShell;
+    },
+  };
+  sceneRegistry = createSceneRegistry(appContext);
+  seededSceneId = sceneRegistry.defaultSceneId || Object.keys(sceneRegistry.scenes || {})[0] || null;
+  const resolveScene = (sceneId) => sceneRegistry.scenes[sceneId] || null;
+  screenShell = createScreenShell({ resolveScreen: resolveProjectScreen });
+  sceneFlow = createSceneFlow({
+    initialSceneId: seededSceneId,
+    resolveScene,
+    onEnter(info) {
+      if (!runtimeStarted) return;
+      info.current?.scene?.setup?.(info.current.data);
+      info.current?.scene?.onEnter?.(info);
+    },
+    onExit(info) {
+      info.current?.scene?.onExit?.(info);
+      info.current?.scene?.shutdown?.(info);
+    },
+    onPause(info) {
+      info.current?.scene?.onPause?.(info);
+    },
+    onResume(info) {
+      info.current?.scene?.onResume?.(info);
+    },
+  });
+  syncAppStateRuntime();
+  const activeScene = () => {
+    const sceneId = currentSceneId();
+    return sceneId ? sceneRegistry.scenes[sceneId] || null : null;
+  };
+  function clearPlaytestScreens() {
+    const shellState = typeof screenShell?.getState === 'function' ? screenShell.getState() : null;
+    if (!shellState || typeof screenShell?.applyState !== 'function') {
+      return null;
+    }
+    return screenShell.applyState({
+      schema: shellState.schema || 'aurajs.screen-shell.v1',
+      hud: shellState.hud || null,
+      overlay: null,
+      modals: [],
+      mutationCount: Number.isInteger(Number(shellState.mutationCount))
+        ? Number(shellState.mutationCount) + 1
+        : 1,
+    });
+  }
+  function setPaused(nextValue = false) {
+    paused = nextValue === true;
+    syncAppStateRuntime();
+    return paused;
+  }
+  function togglePaused() {
+    return setPaused(!paused);
+  }
+  function getPaused() {
+    return paused === true;
+  }
+  function getRecordingState() {
+    const runtime = globalThis.aura;
+    const state = runtime?.window && typeof runtime.window.getRecordingState === 'function'
+      ? runtime.window.getRecordingState()
+      : null;
+    recordingState.supported = state?.supported === true;
+    recordingState.active = state?.active === true;
+    recordingState.audioSupported = state?.audioSupported === true;
+    recordingState.path = typeof state?.path === 'string' ? state.path : null;
+    recordingState.reasonCode = typeof state?.reasonCode === 'string' ? state.reasonCode : null;
+    return {
+      supported: recordingState.supported === true,
+      active: recordingState.active === true,
+      audioSupported: recordingState.audioSupported === true,
+      path: recordingState.path || null,
+      reasonCode: recordingState.reasonCode || null,
+    };
+  }
+  function toggleRecording() {
+    const runtime = globalThis.aura;
+    if (!runtime?.window || typeof runtime.window.toggleRecording !== 'function') {
+      return {
+        ok: false,
+        reasonCode: 'recording_unavailable',
+      };
+    }
+    runtime.window.toggleRecording();
+    return {
+      ok: true,
+      reasonCode: 'recording_toggle_requested',
+    };
+  }
+  function restartCurrentScene() {
+    const current = sceneFlow?.current?.();
+    if (!current?.sceneId) {
+      return {
+        ok: false,
+        reasonCode: 'scene_flow_unavailable',
+      };
+    }
+    clearPlaytestScreens();
+    paused = false;
+    const result = sceneFlow.replace(current.sceneId, cloneProjectValue(current.data));
+    if (result?.ok) {
+      syncAppStateRuntime(current.sceneId);
+    }
+    return result;
+  }
+  function jumpToScene(sceneId, data = null) {
+    const targetSceneId = typeof sceneId === 'string' ? sceneId.trim() : '';
+    if (!targetSceneId) {
+      return {
+        ok: false,
+        reasonCode: 'scene_flow_invalid_scene_id',
+      };
+    }
+    if (!sceneRegistry?.scenes?.[targetSceneId]) {
+      return {
+        ok: false,
+        reasonCode: 'scene_flow_unknown_scene',
+      };
+    }
+    const previousSceneId = currentSceneId();
+    clearPlaytestScreens();
+    while (sceneFlow?.canPop?.()) {
+      const popped = sceneFlow.pop();
+      if (!popped?.ok) {
+        syncAppStateRuntime(previousSceneId);
+        return popped;
+      }
+    }
+    paused = false;
+    const result = sceneFlow.replace(targetSceneId, cloneProjectValue(data));
+    if (result?.ok) {
+      syncAppStateRuntime(previousSceneId);
+    }
+    return result;
+  }
+  function restartStartScene() {
+    const startSceneId = projectRegistry.startSceneId || seededSceneId || currentSceneId();
+    if (!startSceneId) {
+      return {
+        ok: false,
+        reasonCode: 'scene_flow_unavailable',
+      };
+    }
+    return jumpToScene(startSceneId, null);
+  }
+  function exportProjectState() {
+    const scenes = {};
+    const sceneCaptureResults = [];
+    for (const sceneId of Object.keys(sceneRegistry.scenes || {}).sort()) {
+      const captureResult = captureSceneSnapshot(sceneRegistry.scenes[sceneId], sceneId);
+      sceneCaptureResults.push({
+        sceneId,
+        ok: captureResult.ok === true,
+        reasonCode: captureResult.reasonCode || null,
+        detail: captureResult.detail || null,
+        hasSnapshot: captureResult.hasSnapshot === true,
+      });
+      if (captureResult.snapshot != null) {
+        scenes[sceneId] = captureResult.snapshot;
+      }
+    }
+    const captureReasonCode = sceneCaptureResults.some((entry) => entry.ok !== true || entry.reasonCode === 'project_state_scene_skipped')
+      ? 'project_state_capture_partial'
+      : 'project_state_capture_ok';
+    recordContinuityCapture(createContinuitySummary(sceneCaptureResults, {
+      phase: 'capture',
+      reasonCode: captureReasonCode,
+      activeSceneId: currentSceneId(),
+    }));
+    syncAppStateRuntime();
+    const continuity = normalizeProjectContinuityState({
+      schema: PROJECT_CONTINUITY_STATE_SCHEMA,
+      version: PROJECT_CONTINUITY_STATE_VERSION,
+      template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+      activeSceneId: currentSceneId(),
+      currentSceneData: sceneFlow?.current?.()?.data ?? null,
+      appState,
+      sceneFlow: sceneFlow.getState(),
+      screenShell: screenShell.getState(),
+      sceneStates: scenes,
+      ownership: projectRegistry.continuity || null,
+    }, projectRegistry.template || ${JSON.stringify(template || 'blank')});
+    return {
+      schema: PROJECT_STATE_SCHEMA,
+      template: continuity.template,
+      activeSceneId: continuity.activeSceneId,
+      currentSceneData: continuity.currentSceneData,
+      appState: continuity.appState,
+      sceneFlow: continuity.sceneFlow,
+      screenShell: continuity.screenShell,
+      scenes: continuity.sceneStates,
+      continuity,
+    };
+  }
+  function applyProjectState(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+      return { ok: false, reasonCode: 'project_state_invalid' };
+    }
+    if (snapshot.schema && snapshot.schema !== PROJECT_STATE_SCHEMA) {
+      return { ok: false, reasonCode: 'project_state_invalid' };
+    }
+    const continuity = normalizeProjectContinuityState(
+      snapshot,
+      projectRegistry.template || ${JSON.stringify(template || 'blank')},
+    );
+    if (!continuity) {
+      return { ok: false, reasonCode: 'project_state_invalid' };
+    }
+
+    const beforeSceneId = currentSceneId();
+    const restoreSource = readPendingDevRestoreMeta();
+    if (continuity.appState) {
+      replaceAppState(continuity.appState);
+    }
+    const flowResult = sceneFlow.applyState(continuity.sceneFlow || null);
+    if (!flowResult?.ok) {
+      const continuitySummary = createContinuitySummary([], {
+        phase: 'restore',
+        reasonCode: flowResult?.reasonCode || 'project_state_apply_failed',
+        activeSceneId: beforeSceneId,
+        continuityVersion: continuity.version,
+        detail: flowResult?.detail || null,
+        source: restoreSource,
+      });
+      recordContinuityRestore(continuitySummary);
+      syncAppStateRuntime(beforeSceneId);
+      return {
+        ok: false,
+        reasonCode: flowResult?.reasonCode || 'project_state_apply_failed',
+        detail: flowResult?.detail || null,
+        continuity: continuitySummary,
+      };
+    }
+
+    const shellResult = screenShell.applyState(continuity.screenShell || {
+      schema: 'aurajs.screen-shell.v1',
+      hud: null,
+      overlay: null,
+      modals: [],
+      mutationCount: 0,
+    });
+    if (!shellResult?.ok) {
+      const continuitySummary = createContinuitySummary([], {
+        phase: 'restore',
+        reasonCode: shellResult?.reasonCode || 'project_state_apply_failed',
+        activeSceneId: currentSceneId(),
+        continuityVersion: continuity.version,
+        detail: shellResult?.detail || null,
+        source: restoreSource,
+      });
+      recordContinuityRestore(continuitySummary);
+      syncAppStateRuntime(beforeSceneId);
+      return {
+        ok: false,
+        reasonCode: shellResult?.reasonCode || 'project_state_apply_failed',
+        detail: shellResult?.detail || null,
+        continuity: continuitySummary,
+      };
+    }
+
+    const sceneSnapshots = continuity.sceneStates;
+    const sceneRestoreResults = [];
+    for (const [sceneId, sceneSnapshot] of Object.entries(sceneSnapshots)) {
+      const result = applySceneSnapshot(sceneRegistry.scenes[sceneId] || null, sceneSnapshot, sceneId);
+      sceneRestoreResults.push({
+        sceneId,
+        ok: result.ok === true,
+        reasonCode: result.reasonCode || null,
+        detail: result.detail || null,
+        restored: result.restored === true,
+      });
+      if (!result.ok) {
+        const continuitySummary = createContinuitySummary(sceneRestoreResults, {
+          phase: 'restore',
+          reasonCode: result.reasonCode || 'project_state_scene_apply_failed',
+          activeSceneId: currentSceneId(),
+          continuityVersion: continuity.version,
+          detail: result.detail || null,
+          source: restoreSource,
+        });
+        recordContinuityRestore(continuitySummary);
+        syncAppStateRuntime(beforeSceneId);
+        return {
+          ok: false,
+          reasonCode: result.reasonCode || 'project_state_scene_apply_failed',
+          failedSceneId: sceneId,
+          detail: result.detail || null,
+          continuity: continuitySummary,
+        };
+      }
+    }
+
+    const afterSceneId = currentSceneId();
+    if (runtimeStarted && afterSceneId && afterSceneId !== beforeSceneId) {
+      const scene = activeScene();
+      scene?.setup?.(sceneFlow.current()?.data);
+    }
+    const restoreReasonCode = sceneRestoreResults.some((entry) => entry.reasonCode === 'project_state_scene_skipped')
+      ? 'project_state_apply_partial'
+      : 'project_state_apply_ok';
+    const continuitySummary = createContinuitySummary(sceneRestoreResults, {
+      phase: 'restore',
+      reasonCode: restoreReasonCode,
+      activeSceneId: afterSceneId || null,
+      continuityVersion: continuity.version,
+      source: restoreSource,
+    });
+    recordContinuityRestore(continuitySummary);
+    syncAppStateRuntime(beforeSceneId);
+
+    return {
+      ok: true,
+      reasonCode: restoreReasonCode,
+      activeSceneId: afterSceneId || null,
+      continuityVersion: continuity.version,
+      continuity: continuitySummary,
+    };
+  }
+  function installProjectStateBridge(app) {
+    const auraRef = globalThis.aura;
+    if (!auraRef || typeof auraRef !== 'object') {
+      return;
+    }
+    auraRef.project = {
+      schemaVersion: PROJECT_STATE_SCHEMA,
+      continuitySchemaVersion: PROJECT_CONTINUITY_STATE_SCHEMA,
+      getState: () => app.getState(),
+      exportState: () => app.getState(),
+      getContinuityState: () => app.appState?.runtime?.continuity || null,
+      applyState: (snapshot) => app.applyState(snapshot),
+      apply: (snapshot) => app.applyState(snapshot),
+    };
+  }
+  const projectInspector = createProjectInspector({
+    projectTitle,
+    sceneRegistry,
+    getActiveSceneId: currentSceneId,
+    appState,
+    getUiThemeState: () => inspectSharedUiTheme(appState),
+    onSelectScene: jumpToScene,
+    onRestartScene: restartCurrentScene,
+    onRestartApp: restartStartScene,
+    getPaused,
+    togglePaused,
+    getRecordingState,
+    toggleRecording,
+  });
+
+  function renderScreenEntry(entry) {
+    if (!entry) return;
+    const screen = resolveProjectScreen(entry.screenId);
+    if (typeof screen === 'function') {
+      screen(entry.data || {}, appContext);
+      return;
+    }
+    const drawScreen = typeof screen?.draw === 'function'
+      ? screen.draw
+      : typeof screen?.render === 'function'
+        ? screen.render
+        : null;
+    if (drawScreen) {
+      drawScreen(entry.data || {}, appContext);
+    }
+  }
+
+  const app = {
+    ...appContext,
+    template: projectRegistry.template || ${JSON.stringify(template || 'blank')},
+    projectInspector,
+    get projectInspectorEnabled() {
+      return projectInspector.enabled;
+    },
+    get projectInspectorMinimized() {
+      return projectInspector.minimized;
+    },
+    get paused() {
+      return paused;
+    },
+    get activeSceneId() {
+      return currentSceneId();
+    },
+    get sceneRegistry() {
+      return sceneRegistry;
+    },
+    get sceneFlow() {
+      return sceneFlow;
+    },
+    get screenShell() {
+      return screenShell;
+    },
+    inspectProject() {
+      return projectInspector.snapshot();
+    },
+    get appState() {
+      return appState;
+    },
+    getProjectInspectorState() {
+      return projectInspector.snapshot();
+    },
+    getSceneFlowState() {
+      return sceneFlow.getState();
+    },
+    getScreenShellState() {
+      return screenShell.getState();
+    },
+    getState() {
+      return exportProjectState();
+    },
+    exportState() {
+      return exportProjectState();
+    },
+    applyState(snapshot) {
+      return applyProjectState(snapshot);
+    },
+    replaceScene(sceneId, data = null) {
+      const previousSceneId = currentSceneId();
+      const result = sceneFlow.replace(sceneId, data);
+      if (!result.ok) {
+        throw new Error(\`Unknown scene "\${sceneId}". [reason:\${result.reasonCode}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return result;
+    },
+    pushScene(sceneId, data = null) {
+      const previousSceneId = currentSceneId();
+      const result = sceneFlow.push(sceneId, data);
+      if (!result.ok) {
+        throw new Error(\`Unable to push scene "\${sceneId}". [reason:\${result.reasonCode}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return result;
+    },
+    popScene(result = null) {
+      const previousSceneId = currentSceneId();
+      const outcome = sceneFlow.pop(result);
+      if (!outcome.ok) {
+        throw new Error(\`Unable to pop scene. [reason:\${outcome.reasonCode}]\`);
+      }
+      syncAppStateRuntime(previousSceneId);
+      return outcome;
+    },
+    jumpToScene(sceneId, data = null) {
+      return jumpToScene(sceneId, data);
+    },
+    canPopScene() {
+      return sceneFlow.canPop();
+    },
+    setHudScreen(screenId, data = null) {
+      const result = screenShell.setHud(screenId, data);
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    clearHudScreen() {
+      const result = screenShell.clearHud();
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    showOverlayScreen(screenId, data = null) {
+      const result = screenShell.showOverlay(screenId, data);
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    clearOverlayScreen() {
+      const result = screenShell.clearOverlay();
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    pushModalScreen(screenId, data = null) {
+      const result = screenShell.pushModal(screenId, data);
+      syncAppStateRuntime(currentSceneId());
+      return result;
+    },
+    popModalScreen(result = null) {
+      const outcome = screenShell.popModal(result);
+      syncAppStateRuntime(currentSceneId());
+      return outcome;
+    },
+    toggleProjectInspector(nextValue = null) {
+      if (typeof nextValue === 'boolean') {
+        return projectInspector.setEnabled(nextValue);
+      }
+      return projectInspector.toggle();
+    },
+    setProjectInspectorMinimized(nextValue = null) {
+      if (typeof nextValue === 'boolean') {
+        return projectInspector.setMinimized(nextValue);
+      }
+      return projectInspector.setMinimized(false);
+    },
+    toggleProjectInspectorMinimized() {
+      return projectInspector.toggleMinimized();
+    },
+    setPaused(nextValue = true) {
+      return setPaused(nextValue);
+    },
+    togglePaused() {
+      return togglePaused();
+    },
+    getRecordingState() {
+      return getRecordingState();
+    },
+    toggleRecording() {
+      return toggleRecording();
+    },
+    restartCurrentScene() {
+      return restartCurrentScene();
+    },
+    restartStartScene() {
+      return restartStartScene();
+    },
+    setup() {
+      assertRuntimeCapabilities();
+      runtimeStarted = true;
+      paused = false;
+      activeScene()?.setup?.();
+      syncAppStateRuntime();
+    },
+    update(dt) {
+      projectInspector.update();
+      if (!paused) {
+        activeScene()?.update?.(dt);
+      }
+      syncAppStateRuntime();
+    },
+    draw() {
+      applySharedUiTheme(appState);
+      activeScene()?.draw?.();
+      const shellState = screenShell.getState();
+      renderScreenEntry(shellState.hud);
+      renderScreenEntry(shellState.overlay);
+      for (const modal of shellState.modals) {
+        renderScreenEntry(modal);
+      }
+      projectInspector.draw();
+    },
+    swapScene(nextSceneId, data = null) {
+      return appContext.replaceScene(nextSceneId, data);
+    },
+  };
+  installProjectStateBridge(app);
+  return app;
+}
+`;
+}
+
+export function renderRegistryBackedMainEntry({ projectTitle, starterLabel = null }) {
+  const bootstrapLabel = starterLabel
+    ? `AuraJS ${starterLabel} starter`
+    : 'AuraJS authored project';
+  return `// ${projectTitle} - ${bootstrapLabel} bootstrap
+
+import { createApp } from './runtime/app.js';
+
+const app = createApp();
+
+aura.setup = function () {
+  app.setup();
+};
+
+aura.update = function (dt) {
+  app.update(dt);
+};
+
+aura.draw = function () {
+  app.draw();
+};
+`;
+}
+
+export function renderBlankRuntimeCapabilitiesModule() {
+  return `function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+export function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.draw2d, 'clear')) missing.push('aura.draw2d.clear');
+  if (!hasMethod(aura.draw2d, 'rect')) missing.push('aura.draw2d.rect');
+  if (typeof aura.rgba !== 'function') missing.push('aura.rgba');
+
+  if (missing.length > 0) {
+    throw new Error(\`[authored-project] runtime missing required APIs: \${missing.join(', ')} [reason:missing_runtime_api]\`);
+  }
+}
+`;
+}
+
+export function renderBlankBootstrapEntry({ projectTitle }) {
+  return `// ${projectTitle} — AuraJS blank starter
+
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.draw2d, 'clear')) missing.push('aura.draw2d.clear');
+  if (typeof aura.rgba !== 'function') missing.push('aura.rgba');
+
+  if (missing.length > 0) {
+    throw new Error(\`[blank-template] runtime missing required APIs: \${missing.join(', ')} [reason:missing_runtime_api]\`);
+  }
+}
+
+aura.setup = function () {
+  assertRuntimeCapabilities();
+  console.log(${JSON.stringify(`${projectTitle} ready`)});
+};
+
+aura.update = function (_dt) {
+  // game logic
+};
+
+aura.draw = function () {
+  aura.draw2d.clear(aura.rgba(0.06, 0.06, 0.08, 1.0));
+};
+`;
+}
+
+export function syncRegistryBackedRuntimeFiles({ projectRoot, template, projectTitle }) {
+  const appPath = resolve(projectRoot, PROJECT_RUNTIME_APP_RELATIVE_PATH);
+  const appStatePath = resolve(projectRoot, PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH);
+  const capabilitiesPath = resolve(projectRoot, PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH);
+  const inspectorPath = resolve(projectRoot, PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH);
+  const sceneFlowPath = resolve(projectRoot, PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH);
+  const screenShellPath = resolve(projectRoot, PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH);
+  const uiThemePath = resolve(projectRoot, PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH);
+  const uiSettingsPath = resolve(projectRoot, PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH);
+  const uiFormsPath = resolve(projectRoot, PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH);
+  const mainPath = resolve(projectRoot, PROJECT_MAIN_ENTRY_RELATIVE_PATH);
+  const written = [];
+  const appStateModule = renderAppStateModule();
+  const inspectorModule = renderProjectInspectorModule();
+  const sceneFlowModule = renderSceneFlowModule();
+  const screenShellModule = renderScreenShellModule();
+  const uiThemeModule = renderUiThemeModule();
+  const uiSettingsModule = renderUiSettingsModule();
+  const uiFormsModule = renderUiFormsModule();
+
+  if (!existsSync(appStatePath) || readFileSync(appStatePath, 'utf8') !== appStateModule) {
+    mkdirSync(dirname(appStatePath), { recursive: true });
+    writeFileSync(appStatePath, appStateModule, 'utf8');
+    written.push(PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH);
+  }
+
+  if (!existsSync(inspectorPath) || readFileSync(inspectorPath, 'utf8') !== inspectorModule) {
+    mkdirSync(dirname(inspectorPath), { recursive: true });
+    writeFileSync(inspectorPath, inspectorModule, 'utf8');
+    written.push(PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH);
+  }
+
+  if (!existsSync(screenShellPath) || readFileSync(screenShellPath, 'utf8') !== screenShellModule) {
+    mkdirSync(dirname(screenShellPath), { recursive: true });
+    writeFileSync(screenShellPath, screenShellModule, 'utf8');
+    written.push(PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH);
+  }
+
+  if (!existsSync(uiThemePath) || readFileSync(uiThemePath, 'utf8') !== uiThemeModule) {
+    mkdirSync(dirname(uiThemePath), { recursive: true });
+    writeFileSync(uiThemePath, uiThemeModule, 'utf8');
+    written.push(PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH);
+  }
+
+  if (!existsSync(uiSettingsPath) || readFileSync(uiSettingsPath, 'utf8') !== uiSettingsModule) {
+    mkdirSync(dirname(uiSettingsPath), { recursive: true });
+    writeFileSync(uiSettingsPath, uiSettingsModule, 'utf8');
+    written.push(PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH);
+  }
+
+  if (!existsSync(uiFormsPath) || readFileSync(uiFormsPath, 'utf8') !== uiFormsModule) {
+    mkdirSync(dirname(uiFormsPath), { recursive: true });
+    writeFileSync(uiFormsPath, uiFormsModule, 'utf8');
+    written.push(PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH);
+  }
+
+  if (!existsSync(sceneFlowPath) || readFileSync(sceneFlowPath, 'utf8') !== sceneFlowModule) {
+    mkdirSync(dirname(sceneFlowPath), { recursive: true });
+    writeFileSync(sceneFlowPath, sceneFlowModule, 'utf8');
+    written.push(PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH);
+  }
+
+  if (!existsSync(appPath)) {
+    mkdirSync(dirname(appPath), { recursive: true });
+    writeFileSync(appPath, renderRegistryBackedRuntimeApp({ template }), 'utf8');
+    written.push(PROJECT_RUNTIME_APP_RELATIVE_PATH);
+  }
+
+  if (String(template || '').trim() === 'blank' && !existsSync(capabilitiesPath)) {
+    mkdirSync(dirname(capabilitiesPath), { recursive: true });
+    writeFileSync(capabilitiesPath, renderBlankRuntimeCapabilitiesModule(), 'utf8');
+    written.push(PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH);
+  }
+
+  const blankBootstrap = renderBlankBootstrapEntry({ projectTitle });
+  const existingMainSource = existsSync(mainPath) ? readFileSync(mainPath, 'utf8') : null;
+  const shouldReplaceBlankMain = !existsSync(mainPath)
+    || existingMainSource === blankBootstrap
+    || (
+      typeof existingMainSource === 'string'
+      && existingMainSource.includes('AuraJS blank starter')
+      && !existingMainSource.includes('createApp')
+    );
+  if (String(template || '').trim() === 'blank' && shouldReplaceBlankMain) {
+    mkdirSync(dirname(mainPath), { recursive: true });
+    writeFileSync(mainPath, renderRegistryBackedMainEntry({ projectTitle }), 'utf8');
+    written.push(PROJECT_MAIN_ENTRY_RELATIVE_PATH);
+  }
+
+  return {
+    files: written,
+    mainAdopted: written.includes(PROJECT_MAIN_ENTRY_RELATIVE_PATH),
+  };
+}