@auraindustry/aurajs 0.0.7 → 0.1.0

package/templates/create/shared/src/runtime/project-inspector.js

@@ -0,0 +1,105 @@
+import projectRegistry from './project-registry.js';
+
+export const PROJECT_INSPECTOR_SCHEMA = 'aurajs.project-inspector.v1';
+
+const TOGGLE_KEYS = ['f1'];
+const PANEL_X = 12;
+const PANEL_Y = 12;
+const PANEL_WIDTH = 460;
+const LINE_HEIGHT = 16;
+const PANEL_PADDING = 10;
+
+export function createProjectInspector({ toggleKeys = TOGGLE_KEYS } = {}) {
+  let enabled = false;
+
+  function snapshot({ activeSceneId = null } = {}) {
+    return {
+      schema: PROJECT_INSPECTOR_SCHEMA,
+      enabled,
+      activeSceneId: activeSceneId || null,
+      startSceneId: projectRegistry.startSceneId || null,
+      scenes: Array.isArray(projectRegistry.scenes) ? projectRegistry.scenes.map(cloneRegistryEntry) : [],
+      screens: Array.isArray(projectRegistry.screens) ? projectRegistry.screens.map(cloneRegistryEntry) : [],
+      prefabs: Array.isArray(projectRegistry.prefabs) ? projectRegistry.prefabs.map((entry) => ({
+        ...cloneRegistryEntry(entry),
+        role: typeof entry?.role === 'string' ? entry.role : null,
+      })) : [],
+      dataFiles: Array.isArray(projectRegistry.dataFiles) ? [...projectRegistry.dataFiles] : [],
+      sourceOfTruth: 'src/runtime/project-registry.js',
+    };
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    toggle(nextEnabled) {
+      enabled = typeof nextEnabled === 'boolean' ? nextEnabled : !enabled;
+      return enabled;
+    },
+    syncInput(input = null) {
+      if (!input || typeof input.isKeyPressed !== 'function') {
+        return enabled;
+      }
+      for (const key of toggleKeys) {
+        if (input.isKeyPressed(key)) {
+          return this.toggle();
+        }
+      }
+      return enabled;
+    },
+    snapshot,
+    draw({ activeSceneId = null } = {}) {
+      if (!enabled) return false;
+
+      const runtime = globalThis.aura;
+      if (!runtime?.draw2d || typeof runtime.draw2d.rect !== 'function' || typeof runtime.draw2d.text !== 'function') {
+        return false;
+      }
+
+      const lines = formatInspectorLines(snapshot({ activeSceneId }));
+      const panelHeight = (PANEL_PADDING * 2) + (lines.length * LINE_HEIGHT);
+      const background = typeof runtime.rgba === 'function'
+        ? runtime.rgba(0.06, 0.09, 0.14, 0.86)
+        : runtime.rgb(0.06, 0.09, 0.14);
+      const textColor = runtime.Color?.WHITE
+        || (typeof runtime.rgba === 'function' ? runtime.rgba(1, 1, 1, 1) : runtime.rgb(1, 1, 1));
+
+      runtime.draw2d.rect(PANEL_X, PANEL_Y, PANEL_WIDTH, panelHeight, background);
+
+      let y = PANEL_Y + PANEL_PADDING;
+      for (const line of lines) {
+        runtime.draw2d.text(line, PANEL_X + PANEL_PADDING, y, {
+          size: 12,
+          color: textColor,
+        });
+        y += LINE_HEIGHT;
+      }
+      return true;
+    },
+  };
+}
+
+function cloneRegistryEntry(entry) {
+  return {
+    id: typeof entry?.id === 'string' ? entry.id : null,
+    path: typeof entry?.path === 'string' ? entry.path : null,
+  };
+}
+
+function formatInspectorLines(snapshot) {
+  const prefabs = snapshot.prefabs.map((entry) => `${entry.id}${entry.role ? `:${entry.role}` : ''}`);
+  return [
+    'AuraJS Project Inspector [F1]',
+    `Current scene: ${snapshot.activeSceneId || '(none)'}`,
+    `Start scene: ${snapshot.startSceneId || '(none)'}`,
+    `Scenes: ${joinOrNone(snapshot.scenes.map((entry) => entry.id))}`,
+    `Screens: ${joinOrNone(snapshot.screens.map((entry) => entry.id))}`,
+    `Prefabs: ${joinOrNone(prefabs)}`,
+    `Data: ${joinOrNone(snapshot.dataFiles)}`,
+  ];
+}
+
+function joinOrNone(values) {
+  return Array.isArray(values) && values.length > 0 ? values.join(', ') : '(none)';
+}

package/templates/create/shared/src/runtime/scene-flow.js

@@ -0,0 +1,290 @@
+export const SCENE_FLOW_SCHEMA = 'aurajs.scene-flow.v1';
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function normalizeSceneId(sceneId) {
+  if (typeof sceneId !== 'string') return null;
+  const normalized = sceneId.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function snapshotEntry(entry) {
+  if (!entry) return null;
+  return {
+    sceneId: entry.sceneId,
+    data: cloneValue(entry.data),
+    mountId: entry.mountId,
+  };
+}
+
+function exposeEntry(entry) {
+  if (!entry) return null;
+  return {
+    sceneId: entry.sceneId,
+    data: cloneValue(entry.data),
+    mountId: entry.mountId,
+    scene: entry.scene,
+  };
+}
+
+function resultOk(state, extra = {}) {
+  return {
+    ok: true,
+    reasonCode: 'scene_flow_ok',
+    ...extra,
+    state,
+  };
+}
+
+function resultErr(reasonCode) {
+  return {
+    ok: false,
+    reasonCode,
+  };
+}
+
+export function createSceneFlow({
+  resolveScene = null,
+  initialSceneId = null,
+  initialData = null,
+  onEnter = null,
+  onExit = null,
+  onPause = null,
+  onResume = null,
+} = {}) {
+  let stack = [];
+  let nextMountId = 1;
+  let mutationCount = 0;
+
+  function resolveKnownScene(sceneId) {
+    const normalized = normalizeSceneId(sceneId);
+    if (!normalized) return { ok: false, reasonCode: 'scene_flow_invalid_scene_id' };
+    if (typeof resolveScene !== 'function') {
+      return { ok: true, sceneId: normalized, scene: null };
+    }
+    const scene = resolveScene(normalized);
+    if (!scene) return { ok: false, reasonCode: 'scene_flow_unknown_scene' };
+    return { ok: true, sceneId: normalized, scene };
+  }
+
+  function createEntry(resolved, data = null) {
+    return {
+      sceneId: resolved.sceneId,
+      scene: resolved.scene,
+      data: cloneValue(data),
+      mountId: nextMountId++,
+    };
+  }
+
+  function buildState() {
+    const current = stack.length > 0 ? stack[stack.length - 1] : null;
+    return {
+      schema: SCENE_FLOW_SCHEMA,
+      currentSceneId: current ? current.sceneId : null,
+      current: snapshotEntry(current),
+      stack: stack.map((entry) => snapshotEntry(entry)),
+      depth: stack.length,
+      canPop: stack.length > 1,
+      mutationCount,
+    };
+  }
+
+  function invokeLifecycle(callback, payload) {
+    if (typeof callback !== 'function') return;
+    callback(payload);
+  }
+
+  function buildStateFromEntries(entries, nextMutationCount = mutationCount) {
+    const current = entries.length > 0 ? entries[entries.length - 1] : null;
+    return {
+      schema: SCENE_FLOW_SCHEMA,
+      currentSceneId: current ? current.sceneId : null,
+      current: snapshotEntry(current),
+      stack: entries.map((entry) => snapshotEntry(entry)),
+      depth: entries.length,
+      canPop: entries.length > 1,
+      mutationCount: nextMutationCount,
+    };
+  }
+
+  function restoreEntry(snapshot, fallbackMountId) {
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+      return { ok: false, reasonCode: 'scene_flow_invalid_state' };
+    }
+    const resolved = resolveKnownScene(snapshot.sceneId);
+    if (!resolved.ok) {
+      return resultErr(resolved.reasonCode);
+    }
+    return {
+      ok: true,
+      entry: {
+        sceneId: resolved.sceneId,
+        scene: resolved.scene,
+        data: cloneValue(snapshot.data),
+        mountId: Number.isInteger(Number(snapshot.mountId)) && Number(snapshot.mountId) > 0
+          ? Number(snapshot.mountId)
+          : Number(fallbackMountId),
+      },
+    };
+  }
+
+  if (initialSceneId != null) {
+    const resolved = resolveKnownScene(initialSceneId);
+    if (!resolved.ok) {
+      throw new Error(`[scene-flow] invalid initial scene [reason:${resolved.reasonCode}]`);
+    }
+    stack = [createEntry(resolved, initialData)];
+    mutationCount = 1;
+  }
+
+  return {
+    replace(sceneId, data = null) {
+      const resolved = resolveKnownScene(sceneId);
+      if (!resolved.ok) return resultErr(resolved.reasonCode);
+
+      const previous = stack.length > 0 ? stack[stack.length - 1] : null;
+      const next = createEntry(resolved, data);
+
+      if (previous) {
+        invokeLifecycle(onExit, {
+          operation: 'replace',
+          current: exposeEntry(previous),
+          next: exposeEntry(next),
+          result: null,
+        });
+        stack[stack.length - 1] = next;
+      } else {
+        stack.push(next);
+      }
+
+      mutationCount += 1;
+      invokeLifecycle(onEnter, {
+        operation: 'replace',
+        current: exposeEntry(next),
+        previous: exposeEntry(previous),
+      });
+
+      return resultOk(buildState(), {
+        current: exposeEntry(next),
+        previous: snapshotEntry(previous),
+      });
+    },
+    push(sceneId, data = null) {
+      const resolved = resolveKnownScene(sceneId);
+      if (!resolved.ok) return resultErr(resolved.reasonCode);
+
+      const previous = stack.length > 0 ? stack[stack.length - 1] : null;
+      const next = createEntry(resolved, data);
+
+      if (previous) {
+        invokeLifecycle(onPause, {
+          operation: 'push',
+          current: exposeEntry(previous),
+          next: exposeEntry(next),
+        });
+      }
+
+      stack.push(next);
+      mutationCount += 1;
+      invokeLifecycle(onEnter, {
+        operation: 'push',
+        current: exposeEntry(next),
+        previous: exposeEntry(previous),
+      });
+
+      return resultOk(buildState(), {
+        current: exposeEntry(next),
+        previous: snapshotEntry(previous),
+      });
+    },
+    pop(result = null) {
+      if (stack.length <= 1) return resultErr('scene_flow_cannot_pop_root');
+
+      const popped = stack.pop();
+      const current = stack[stack.length - 1] || null;
+      const safeResult = cloneValue(result);
+
+      invokeLifecycle(onExit, {
+        operation: 'pop',
+        current: exposeEntry(popped),
+        next: exposeEntry(current),
+        result: safeResult,
+      });
+
+      mutationCount += 1;
+      invokeLifecycle(onResume, {
+        operation: 'pop',
+        current: exposeEntry(current),
+        popped: exposeEntry(popped),
+        result: safeResult,
+      });
+
+      return resultOk(buildState(), {
+        current: exposeEntry(current),
+        popped: snapshotEntry(popped),
+        result: safeResult,
+      });
+    },
+    current() {
+      return exposeEntry(stack.length > 0 ? stack[stack.length - 1] : null);
+    },
+    canPop() {
+      return stack.length > 1;
+    },
+    applyState(snapshot) {
+      if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        return resultErr('scene_flow_invalid_state');
+      }
+      if (snapshot.schema && snapshot.schema !== SCENE_FLOW_SCHEMA) {
+        return resultErr('scene_flow_invalid_state');
+      }
+
+      const sourceStack = Array.isArray(snapshot.stack)
+        ? snapshot.stack
+        : snapshot.current
+          ? [snapshot.current]
+          : [];
+      if (sourceStack.length <= 0) {
+        return resultErr('scene_flow_invalid_state');
+      }
+
+      const restored = [];
+      for (let index = 0; index < sourceStack.length; index += 1) {
+        const result = restoreEntry(sourceStack[index], nextMountId + index);
+        if (!result.ok) {
+          return result;
+        }
+        restored.push(result.entry);
+      }
+
+      stack = restored;
+      const maxMountId = restored.reduce(
+        (highest, entry) => (entry.mountId > highest ? entry.mountId : highest),
+        0,
+      );
+      nextMountId = maxMountId + 1;
+      mutationCount = Number.isInteger(Number(snapshot.mutationCount)) && Number(snapshot.mutationCount) >= 0
+        ? Number(snapshot.mutationCount)
+        : mutationCount;
+
+      return resultOk(buildStateFromEntries(restored, mutationCount), {
+        current: exposeEntry(restored[restored.length - 1] || null),
+      });
+    },
+    getState() {
+      return buildState();
+    },
+  };
+}

package/templates/create/shared/src/runtime/screen-shell.js

@@ -0,0 +1,222 @@
+export const SCREEN_SHELL_SCHEMA = 'aurajs.screen-shell.v1';
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      output[key] = cloneValue(entry);
+    }
+    return output;
+  }
+  return value;
+}
+
+function normalizeScreenId(screenId) {
+  if (typeof screenId !== 'string') return null;
+  const normalized = screenId.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function snapshotEntry(entry) {
+  if (!entry) return null;
+  return {
+    screenId: entry.screenId,
+    data: cloneValue(entry.data),
+    mountId: entry.mountId,
+  };
+}
+
+function snapshotState({ hud, overlay, modals, mutationCount }) {
+  return {
+    schema: SCREEN_SHELL_SCHEMA,
+    hud: snapshotEntry(hud),
+    overlay: snapshotEntry(overlay),
+    modals: modals.map((entry) => snapshotEntry(entry)),
+    modalDepth: modals.length,
+    mutationCount,
+  };
+}
+
+function resultOk(state, extra = {}) {
+  return {
+    ok: true,
+    reasonCode: 'screen_shell_ok',
+    ...extra,
+    state,
+  };
+}
+
+function resultErr(reasonCode) {
+  return {
+    ok: false,
+    reasonCode,
+  };
+}
+
+export function createScreenShell({ resolveScreen = null } = {}) {
+  let hud = null;
+  let overlay = null;
+  let modals = [];
+  let nextMountId = 1;
+  let mutationCount = 0;
+
+  function resolveKnownScreen(screenId) {
+    const normalized = normalizeScreenId(screenId);
+    if (!normalized) return { ok: false, reasonCode: 'screen_shell_invalid_screen_id' };
+    if (typeof resolveScreen !== 'function') {
+      return { ok: true, screenId: normalized };
+    }
+    const resolved = resolveScreen(normalized);
+    if (!resolved) {
+      return { ok: false, reasonCode: 'screen_shell_unknown_screen' };
+    }
+    return { ok: true, screenId: normalized };
+  }
+
+  function createEntry(screenId, data = null) {
+    return {
+      screenId,
+      data: cloneValue(data),
+      mountId: nextMountId++,
+    };
+  }
+
+  function buildState() {
+    return snapshotState({
+      hud,
+      overlay,
+      modals,
+      mutationCount,
+    });
+  }
+
+  function restoreEntry(snapshot, fallbackMountId) {
+    if (!snapshot) return null;
+    if (typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+      return { ok: false, reasonCode: 'screen_shell_invalid_state' };
+    }
+    const resolved = resolveKnownScreen(snapshot.screenId);
+    if (!resolved.ok) {
+      return resultErr(resolved.reasonCode);
+    }
+    return {
+      ok: true,
+      entry: {
+        screenId: resolved.screenId,
+        data: cloneValue(snapshot.data),
+        mountId: Number.isInteger(Number(snapshot.mountId)) && Number(snapshot.mountId) > 0
+          ? Number(snapshot.mountId)
+          : Number(fallbackMountId),
+      },
+    };
+  }
+
+  return {
+    setHud(screenId, data = null) {
+      const resolved = resolveKnownScreen(screenId);
+      if (!resolved.ok) return resultErr(resolved.reasonCode);
+      hud = createEntry(resolved.screenId, data);
+      mutationCount += 1;
+      return resultOk(buildState(), {
+        slot: 'hud',
+        hud: snapshotEntry(hud),
+      });
+    },
+    clearHud() {
+      hud = null;
+      mutationCount += 1;
+      return resultOk(buildState(), { slot: 'hud', hud: null });
+    },
+    showOverlay(screenId, data = null) {
+      const resolved = resolveKnownScreen(screenId);
+      if (!resolved.ok) return resultErr(resolved.reasonCode);
+      overlay = createEntry(resolved.screenId, data);
+      mutationCount += 1;
+      return resultOk(buildState(), {
+        slot: 'overlay',
+        overlay: snapshotEntry(overlay),
+      });
+    },
+    clearOverlay() {
+      overlay = null;
+      mutationCount += 1;
+      return resultOk(buildState(), {
+        slot: 'overlay',
+        overlay: null,
+      });
+    },
+    pushModal(screenId, data = null) {
+      const resolved = resolveKnownScreen(screenId);
+      if (!resolved.ok) return resultErr(resolved.reasonCode);
+      const entry = createEntry(resolved.screenId, data);
+      modals.push(entry);
+      mutationCount += 1;
+      return resultOk(buildState(), {
+        modal: snapshotEntry(entry),
+        modalDepth: modals.length,
+      });
+    },
+    popModal(result = null) {
+      if (modals.length <= 0) return resultErr('screen_shell_empty_modal_stack');
+      const popped = modals.pop();
+      mutationCount += 1;
+      return resultOk(buildState(), {
+        popped: snapshotEntry(popped),
+        result: cloneValue(result),
+        modalDepth: modals.length,
+      });
+    },
+    applyState(snapshot) {
+      if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        return resultErr('screen_shell_invalid_state');
+      }
+      if (snapshot.schema && snapshot.schema !== SCREEN_SHELL_SCHEMA) {
+        return resultErr('screen_shell_invalid_state');
+      }
+
+      const restoredHud = restoreEntry(snapshot.hud, nextMountId);
+      if (restoredHud && !restoredHud.ok) {
+        return restoredHud;
+      }
+      const restoredOverlay = restoreEntry(snapshot.overlay, nextMountId + 1);
+      if (restoredOverlay && !restoredOverlay.ok) {
+        return restoredOverlay;
+      }
+
+      const restoredModals = [];
+      const sourceModals = Array.isArray(snapshot.modals) ? snapshot.modals : [];
+      for (let index = 0; index < sourceModals.length; index += 1) {
+        const restored = restoreEntry(sourceModals[index], nextMountId + 2 + index);
+        if (!restored.ok) {
+          return restored;
+        }
+        restoredModals.push(restored.entry);
+      }
+
+      hud = restoredHud ? restoredHud.entry : null;
+      overlay = restoredOverlay ? restoredOverlay.entry : null;
+      modals = restoredModals;
+      const maxMountId = [hud, overlay, ...modals].reduce(
+        (highest, entry) => (entry && entry.mountId > highest ? entry.mountId : highest),
+        0,
+      );
+      nextMountId = maxMountId + 1;
+      mutationCount = Number.isInteger(Number(snapshot.mutationCount)) && Number(snapshot.mutationCount) >= 0
+        ? Number(snapshot.mutationCount)
+        : mutationCount;
+
+      return resultOk(buildState(), {
+        slot: 'restore',
+        hud: snapshotEntry(hud),
+        overlay: snapshotEntry(overlay),
+        modalDepth: modals.length,
+      });
+    },
+    getState() {
+      return buildState();
+    },
+  };
+}