aurasu 0.1.0 → 0.1.2

package/src/runtime/project-registry.js

@@ -0,0 +1,91 @@
+import screenModule1 from "../../ui/hud.screen.js";
+
+const projectRegistry = {
+  "schema": "aurajs.project-registry.v1",
+  "template": "example-aurasu",
+  "projectTitle": "Aurasu",
+  "startSceneId": "gameplay",
+  "scenes": [
+    {
+      "id": "gameplay",
+      "path": "scenes/gameplay.scene.js",
+      "exportName": "createGameplayScene",
+      "role": null
+    }
+  ],
+  "screens": [
+    {
+      "id": "hud",
+      "path": "ui/hud.screen.js",
+      "exportName": "default",
+      "role": "hud"
+    }
+  ],
+  "prefabs": [
+    {
+      "id": "playfield",
+      "path": "prefabs/playfield.prefab.js",
+      "exportName": "default",
+      "role": "world"
+    }
+  ],
+  "configFiles": [
+    "config/gameplay/game.config.js"
+  ],
+  "contentFiles": [
+    "content/gameplay/beatmap.content.js"
+  ],
+  "continuity": {
+    "schema": "aurajs.project-continuity.v1",
+    "startSceneId": "gameplay",
+    "sharedAppStatePath": "src/runtime/app-state.js",
+    "sceneFlowPath": "src/runtime/scene-flow.js",
+    "screenShellPath": "src/runtime/screen-shell.js",
+    "projectRegistryPath": "src/runtime/project-registry.js",
+    "sceneRegistryPath": "src/runtime/scene-registry.js",
+    "sceneStateOwnerPath": "scenes",
+    "runtimeFiles": [
+      "src/runtime/app-state.js",
+      "src/runtime/project-registry.js",
+      "src/runtime/scene-flow.js",
+      "src/runtime/scene-registry.js",
+      "src/runtime/screen-shell.js"
+    ],
+    "saveRoots": {
+      "slots": ".aura/state/slots",
+      "checkpoints": ".aura/state/checkpoints"
+    },
+    "devRestore": {
+      "flags": [
+        "--restore-slot",
+        "--restore-checkpoint"
+      ],
+      "note": "Supported native dev restarts reapply slot, checkpoint, or live continuity payloads after setup."
+    },
+    "notes": [
+      "Keep shared continuity in appState.session/ui/runtime through the app-context helpers backed by src/runtime/app-state.js, and keep scene-local restore state JSON-safe inside scene getState/applyState hooks.",
+      "Use src/runtime/scene-flow.js for route-style scene payload continuity read through context.getCurrentScenePayload(), and use src/runtime/screen-shell.js for HUD, overlay, and modal payload continuity instead of ad hoc globals."
+    ]
+  }
+};
+
+const screenModules = {
+  "hud": screenModule1,
+};
+
+Object.defineProperty(projectRegistry, 'dataFiles', {
+  enumerable: false,
+  get() {
+    return [...projectRegistry.configFiles, ...projectRegistry.contentFiles];
+  },
+});
+
+export function resolveProjectScreen(screenId) {
+  return screenModules[String(screenId || '')] || null;
+}
+
+export function createProjectRegistry() {
+  return projectRegistry;
+}
+
+export default projectRegistry;

package/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/src/runtime/scene-registry.js

@@ -0,0 +1,25 @@
+import projectRegistry from './project-registry.js';
+import { createGameplayScene as sceneFactory1 } from "../../scenes/gameplay.scene.js";
+
+const sceneFactories = {
+  "gameplay": sceneFactory1,
+};
+
+export function createSceneRegistry(context = {}) {
+  const scenes = {};
+  for (const entry of projectRegistry.scenes || []) {
+    const resolved = sceneFactories[entry.id];
+    if (typeof resolved === 'function') {
+      scenes[entry.id] = resolved(context);
+      continue;
+    }
+    if (typeof resolved !== 'undefined' && resolved !== null) {
+      scenes[entry.id] = resolved;
+    }
+  }
+
+  return {
+    defaultSceneId: projectRegistry.startSceneId || null,
+    scenes,
+  };
+}

package/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();
+    },
+  };
+}