aurasu 0.1.0 → 0.1.2

package/src/runtime/capabilities.js

@@ -0,0 +1,14 @@
+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]`);
+  }
+}

package/src/runtime/project-inspector.js

@@ -0,0 +1,615 @@
+// Project Inspector overlay for registry-backed authored projects.
+import projectRegistry from './project-registry.js';
+import { ensureUiState } from './app-state.js';
+
+const PROJECT_INSPECTOR_SCHEMA = "aurajs.project-inspector.v1";
+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;
+}
+
+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)
+    ? cloneProjectValue(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,
+        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',
+      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);
+    },
+  };
+}