aurasu 0.1.0 → 0.1.2

package/src/runtime/app.js

@@ -0,0 +1,1060 @@
+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 = "aurajs.authored-project-state.v1";
+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 || "blank",
+  });
+  normalizeAppState(appState, {
+    projectTitle,
+    template: projectRegistry.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 || "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 || "blank",
+    });
+    ensureSharedUiPreferences(appState);
+    paused = appState.runtime?.paused === true;
+    return appState;
+  }
+  function syncAppStateRuntime(previousSceneId = null) {
+    normalizeAppState(appState, {
+      projectTitle,
+      template: projectRegistry.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 || "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 || "blank",
+      activeSceneId: currentSceneId(),
+      currentSceneData: sceneFlow?.current?.()?.data ?? null,
+      appState,
+      sceneFlow: sceneFlow.getState(),
+      screenShell: screenShell.getState(),
+      sceneStates: scenes,
+      ownership: projectRegistry.continuity || null,
+    }, projectRegistry.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 || "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 || "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;
+      const setupResult = activeScene()?.setup?.();
+      syncAppStateRuntime();
+      return setupResult;
+    },
+    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;
+}