@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/game-state-runtime.mjs

@@ -4,7 +4,7 @@ export const GAME_STATE_SCHEMA_VERSION = 'aurajs.game-state.v1';
 
 const CANONICAL_TOP_LEVEL_ORDER = ['schemaVersion', 'export', 'state'];
 const CANONICAL_EXPORT_ORDER = ['mode', 'seed', 'frameIndex', 'elapsedSeconds', 'fingerprint', 'capturedAt'];
-const CANONICAL_STATE_SECTION_ORDER = ['globals', 'camera', 'scene3d', 'physics', 'ecs', 'tilemap'];
+const CANONICAL_STATE_SECTION_ORDER = ['globals', 'camera', 'project', 'scene3d', 'physics', 'ecs', 'tilemap'];
 const SUPPORTED_TOP_LEVEL_KEYS = new Set(CANONICAL_TOP_LEVEL_ORDER);
 const SUPPORTED_STATE_SECTION_KEYS = new Set(CANONICAL_STATE_SECTION_ORDER);
 const SUPPORTED_PATCH_MUTATION_OPS = new Set(['set', 'delete']);
@@ -15,6 +15,7 @@ const DEFAULT_MUTATION_MAX_RUNTIME_MS = 200;
 export const STATE_MUTATION_ALLOWLIST_PREFIXES = Object.freeze([
   '/state/globals',
   '/state/camera',
+  '/state/project',
   '/state/scene3d',
   '/state/physics',
   '/state/ecs',
@@ -31,7 +32,7 @@ export const DEFAULT_STATE_MUTATION_GUARDRAILS = Object.freeze({
 export function installStateRestoreRuntimeBootstrap(aura) {
   const schemaVersion = 'aurajs.game-state.v1';
   const knownTopLevel = Object.freeze(['schemaVersion', 'export', 'state']);
-  const knownStateSections = Object.freeze(['globals', 'camera', 'scene3d', 'physics', 'ecs', 'tilemap']);
+  const knownStateSections = Object.freeze(['globals', 'camera', 'project', 'scene3d', 'physics', 'ecs', 'tilemap']);
 
   const isObject = (value) => (
     !!value
@@ -49,7 +50,7 @@ export function installStateRestoreRuntimeBootstrap(aura) {
     }
     if (isObject(value)) {
       const out = {};
-      for (const key of Object.keys(value).sort((a, b) => a.localeCompare(b))) {
+      for (const key of Object.keys(value).sort()) {
         const next = sanitizeJsonValueLocal(value[key]);
         if (next === undefined) continue;
         out[key] = next;
@@ -61,7 +62,7 @@ export function installStateRestoreRuntimeBootstrap(aura) {
   const sanitizeObjectLocal = (value) => {
     const out = {};
     const source = isObject(value) ? value : {};
-    for (const key of Object.keys(source).sort((a, b) => a.localeCompare(b))) {
+    for (const key of Object.keys(source).sort()) {
       const next = sanitizeJsonValueLocal(source[key]);
       if (next === undefined) continue;
       out[key] = next;
@@ -82,9 +83,33 @@ export function installStateRestoreRuntimeBootstrap(aura) {
   };
   const resolveGlobalsMapLocal = () => {
     const storage = aura?.storage && typeof aura.storage === 'object' ? aura.storage : null;
+    if (storage && typeof storage.save === 'function' && typeof storage.set !== 'function') {
+      storage.set = (key, value) => storage.save(key, value);
+    }
+    if (storage && typeof storage.load === 'function' && typeof storage.get !== 'function') {
+      storage.get = (key, fallback = null) => {
+        const value = storage.load(key);
+        return value == null ? fallback : value;
+      };
+    }
     if (storage && storage._store instanceof Map) {
       return storage._store;
     }
+    if (storage && typeof storage.keys === 'function' && typeof storage.load === 'function') {
+      const map = new Map();
+      try {
+        const keys = storage.keys();
+        if (Array.isArray(keys)) {
+          for (const key of [...keys].map((entry) => String(entry)).sort()) {
+            map.set(key, sanitizeJsonValueLocal(storage.load(key)));
+          }
+        }
+      } catch {}
+      if (aura && typeof aura === 'object') {
+        aura.__gameStateGlobals = map;
+      }
+      return map;
+    }
     if (aura && aura.__gameStateGlobals instanceof Map) {
       return aura.__gameStateGlobals;
     }
@@ -101,10 +126,20 @@ export function installStateRestoreRuntimeBootstrap(aura) {
     const globalsMap = resolveGlobalsMapLocal();
     globalsMap.clear();
     const normalized = sanitizeObjectLocal(sectionValue);
+    const storage = aura?.storage && typeof aura.storage === 'object' ? aura.storage : null;
+    if (storage && typeof storage.keys === 'function' && typeof storage.delete === 'function') {
+      try {
+        const existingKeys = storage.keys();
+        if (Array.isArray(existingKeys)) {
+          for (const key of existingKeys) {
+            storage.delete(key);
+          }
+        }
+      } catch {}
+    }
     for (const [key, value] of Object.entries(normalized)) {
       globalsMap.set(key, value);
     }
-    const storage = aura?.storage && typeof aura.storage === 'object' ? aura.storage : null;
     if (storage && typeof storage.set === 'function') {
       for (const [key, value] of globalsMap.entries()) {
         storage.set(key, value);
@@ -222,17 +257,175 @@ export function installStateRestoreRuntimeBootstrap(aura) {
       state: collectCanonicalStateFromPayloadLocal(payload.state),
     };
   };
+  const mapToObjectLocal = (map) => {
+    const out = {};
+    const rows = [...map.entries()].map(([key, value]) => [String(key), sanitizeJsonValueLocal(value)]);
+    rows.sort((a, b) => (
+      a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0
+    ));
+    for (const [key, value] of rows) {
+      out[key] = value;
+    }
+    return out;
+  };
+  const collectCameraSnapshotLocal = () => {
+    if (!aura?.camera || typeof aura.camera !== 'object') {
+      return null;
+    }
+
+    let source = null;
+    if (typeof aura.camera.getState === 'function') {
+      try {
+        source = aura.camera.getState();
+      } catch {
+        source = null;
+      }
+    }
+
+    if (!isObject(source)) {
+      source = {
+        x: aura.camera.x,
+        y: aura.camera.y,
+        zoom: aura.camera.zoom,
+        rotation: aura.camera.rotation,
+      };
+    }
+
+    if (!isObject(source)) {
+      return null;
+    }
+
+    const camera = {};
+    if (Number.isFinite(source.x)) camera.x = Number(source.x);
+    if (Number.isFinite(source.y)) camera.y = Number(source.y);
+    if (Number.isFinite(source.zoom) && source.zoom > 0) camera.zoom = Number(source.zoom);
+    if (Number.isFinite(source.rotation)) camera.rotation = Number(source.rotation);
+    if (typeof source.following === 'boolean') camera.following = source.following;
+    if (Number.isInteger(source.activeEffects) && source.activeEffects >= 0) {
+      camera.activeEffects = Number(source.activeEffects);
+    }
+
+    return Object.keys(camera).length > 0 ? camera : null;
+  };
+  const collectObjectSectionLocal = (section) => {
+    if (!section || typeof section !== 'object') {
+      return null;
+    }
+    if (typeof section.getState === 'function') {
+      try {
+        const state = section.getState();
+        if (state && typeof state === 'object') {
+          return state;
+        }
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  };
+  const collectStateSectionsLocal = () => collectCanonicalStateFromPayloadLocal({
+    globals: mapToObjectLocal(resolveGlobalsMapLocal()),
+    camera: collectCameraSnapshotLocal(),
+    project: collectObjectSectionLocal(aura?.project),
+    scene3d: collectObjectSectionLocal(aura?.scene3d),
+    physics: collectObjectSectionLocal(aura?.physics),
+    ecs: collectObjectSectionLocal(aura?.ecs),
+    tilemap: collectObjectSectionLocal(aura?.tilemap),
+  });
+  const normalizeIntLocal = (value, fallback = 0) => (
+    Number.isInteger(Number(value)) && Number(value) >= 0
+      ? Number(value)
+      : Number(fallback)
+  );
+  const normalizeModeLocal = (value) => {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (normalized === 'headless' || normalized === 'shim') {
+      return normalized;
+    }
+    return 'native';
+  };
+  const normalizeElapsedSecondsLocal = (value) => (
+    Number.isFinite(Number(value)) && Number(value) >= 0
+      ? Number(value)
+      : 0
+  );
+  const normalizeCapturedAtLocal = (value) => (
+    typeof value === 'string' && value.trim()
+      ? value.trim()
+      : new Date().toISOString()
+  );
+  const stableStringifyLocal = (value) => JSON.stringify(sanitizeJsonValueLocal(value));
+  const hashHex64Local = (value) => {
+    const text = String(value || '');
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i += 1) {
+      hash ^= text.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+    const chunk = (hash >>> 0).toString(16).padStart(8, '0');
+    return chunk.repeat(8);
+  };
+  const orderExportPayloadLocal = (payload) => {
+    const orderedExport = {
+      mode: payload.export.mode,
+      seed: payload.export.seed,
+      frameIndex: payload.export.frameIndex,
+      elapsedSeconds: payload.export.elapsedSeconds,
+      fingerprint: payload.export.fingerprint,
+      capturedAt: payload.export.capturedAt,
+    };
+    return {
+      schemaVersion: payload.schemaVersion,
+      export: orderedExport,
+      state: payload.state,
+    };
+  };
+  const exportPayload = (options = {}) => {
+    const state = collectStateSectionsLocal();
+    const payload = {
+      schemaVersion,
+      export: {
+        mode: normalizeModeLocal(options.mode),
+        seed: normalizeIntLocal(options.seed, 0),
+        frameIndex: normalizeIntLocal(options.frameIndex, 0),
+        elapsedSeconds: normalizeElapsedSecondsLocal(options.elapsedSeconds),
+        fingerprint: hashHex64Local(stableStringifyLocal(state)),
+        capturedAt: normalizeCapturedAtLocal(options.capturedAt),
+      },
+      state,
+    };
+
+    return {
+      ok: true,
+      reasonCode: 'state_export_ok',
+      payload: orderExportPayloadLocal(payload),
+    };
+  };
 
   if (!aura || typeof aura !== 'object') {
     return {
+      export() {
+        return { ok: false, reasonCode: 'state_export_failed', detail: 'aura runtime unavailable' };
+      },
+      exportState() {
+        return { ok: false, reasonCode: 'state_export_failed', detail: 'aura runtime unavailable' };
+      },
       apply() {
         return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'aura runtime unavailable' };
       },
+      applyState() {
+        return { ok: false, reasonCode: 'invalid_schema_payload', detail: 'aura runtime unavailable' };
+      },
     };
   }
 
   const stateNamespace = aura.state && typeof aura.state === 'object' ? aura.state : {};
-  if (typeof stateNamespace.apply === 'function' && typeof stateNamespace.applyState === 'function') {
+  if (
+    typeof stateNamespace.apply === 'function'
+    && typeof stateNamespace.applyState === 'function'
+    && typeof stateNamespace.export === 'function'
+    && typeof stateNamespace.exportState === 'function'
+  ) {
     stateNamespace.schemaVersion = schemaVersion;
     aura.state = stateNamespace;
     return stateNamespace;
@@ -274,6 +467,12 @@ export function installStateRestoreRuntimeBootstrap(aura) {
   };
 
   stateNamespace.schemaVersion = schemaVersion;
+  if (typeof stateNamespace.export !== 'function') {
+    stateNamespace.export = exportPayload;
+  }
+  if (typeof stateNamespace.exportState !== 'function') {
+    stateNamespace.exportState = exportPayload;
+  }
   if (typeof stateNamespace.apply !== 'function') {
     stateNamespace.apply = applyPayload;
   }
@@ -665,6 +864,7 @@ function collectStateSections(aura) {
   const raw = {
     globals,
     camera,
+    project: collectObjectSection(aura.project),
     scene3d: collectObjectSection(aura.scene3d),
     physics: collectObjectSection(aura.physics),
     ecs: collectObjectSection(aura.ecs),

package/src/headless-action.mjs

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+
+import { bundleProject } from './bundler.mjs';
+import {
+  HeadlessTestError,
+  createHeadlessAura,
+  createRuntimeContext,
+  executeSetup,
+  executeFrameSteps,
+} from './headless-test.mjs';
+
+function createHeadlessActionTestState() {
+  return {
+    failures: [],
+    passes: 0,
+    drawCalls: 0,
+    audioCalls: 0,
+    logs: [],
+  };
+}
+
+export async function runHeadlessActionSchema(options = {}) {
+  const runtime = await bootHeadlessActionRuntime(options, '.aura/test/action-schema.bundle.js');
+  const schemaResult = resolveActionSchemaResult(runtime.aura);
+
+  return {
+    ok: true,
+    entryFile: runtime.entryFile,
+    bundle: runtime.bundle,
+    frames: 0,
+    width: runtime.width,
+    height: runtime.height,
+    schemaResult,
+    passes: runtime.testState.passes,
+    drawCalls: runtime.testState.drawCalls,
+    audioCalls: runtime.testState.audioCalls,
+  };
+}
+
+export async function runHeadlessActionRun(options = {}) {
+  const runtime = await bootHeadlessActionRuntime(options, '.aura/test/action-run.bundle.js');
+  const frames = options.frames ?? 0;
+  const request = options.request;
+  let seedStateApplyResult = null;
+
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    throw new HeadlessTestError('Headless action run failed: request must be an object.');
+  }
+
+  if (options.statePayload != null) {
+    if (!runtime.aura.state || typeof runtime.aura.state.apply !== 'function') {
+      throw new HeadlessTestError('Headless action run failed: aura.state.apply hook is unavailable.');
+    }
+    seedStateApplyResult = runtime.aura.state.apply(options.statePayload);
+    if (!seedStateApplyResult || typeof seedStateApplyResult !== 'object') {
+      throw new HeadlessTestError('Headless action run failed: aura.state.apply returned invalid result.');
+    }
+    if (seedStateApplyResult.ok !== true) {
+      return {
+        ok: true,
+        entryFile: runtime.entryFile,
+        bundle: runtime.bundle,
+        frames,
+        width: runtime.width,
+        height: runtime.height,
+        actionResult: null,
+        stateResult: null,
+        seedStateApplyResult,
+        passes: runtime.testState.passes,
+        drawCalls: runtime.testState.drawCalls,
+        audioCalls: runtime.testState.audioCalls,
+      };
+    }
+  }
+
+  const actionNs = runtime.aura.action && typeof runtime.aura.action === 'object'
+    ? runtime.aura.action
+    : null;
+  if (!actionNs || typeof actionNs.run !== 'function') {
+    throw new HeadlessTestError('Headless action run failed: aura.action.run hook is unavailable.');
+  }
+
+  let actionResult;
+  try {
+    actionResult = await Promise.resolve(actionNs.run(request));
+  } catch (error) {
+    throw new HeadlessTestError(`Headless action run failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  let stateResult = null;
+  if (options.includeState === true || frames > 0) {
+    if (!runtime.aura.state || typeof runtime.aura.state.exportState !== 'function') {
+      throw new HeadlessTestError('Headless action run failed: aura.state.exportState hook is unavailable.');
+    }
+
+    await executeFrameSteps(runtime.aura, frames);
+
+    stateResult = runtime.aura.state.exportState({
+      mode: options.mode,
+      seed: options.seed,
+      frameIndex: options.frameIndex ?? frames,
+      elapsedSeconds: options.elapsedSeconds,
+      capturedAt: options.capturedAt ?? null,
+    });
+  }
+
+  return {
+    ok: true,
+    entryFile: runtime.entryFile,
+    bundle: runtime.bundle,
+    frames,
+    width: runtime.width,
+    height: runtime.height,
+    actionResult,
+    stateResult,
+    seedStateApplyResult,
+    passes: runtime.testState.passes,
+    drawCalls: runtime.testState.drawCalls,
+    audioCalls: runtime.testState.audioCalls,
+  };
+}
+
+async function bootHeadlessActionRuntime(options, outFile) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const entryFile = resolve(projectRoot, options.file || 'src/main.js');
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+
+  if (!existsSync(entryFile)) {
+    throw new HeadlessTestError(`Action entry file not found: ${entryFile}`);
+  }
+
+  const bundle = bundleProject({
+    projectRoot,
+    mode: 'test',
+    entryFile,
+    outFile: resolve(projectRoot, outFile),
+  });
+
+  const testState = createHeadlessActionTestState();
+  const aura = createHeadlessAura({ width, height, testState });
+  const context = vm.createContext(createRuntimeContext(aura, testState));
+
+  const source = readFileSync(bundle.outFile, 'utf8');
+  const script = new vm.Script(source, {
+    filename: bundle.outFile,
+    displayErrors: true,
+  });
+
+  try {
+    script.runInContext(context, { timeout: 5000 });
+    await executeSetup(aura);
+  } catch (error) {
+    throw new HeadlessTestError(`Headless action execution failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  return {
+    aura,
+    bundle,
+    entryFile,
+    width,
+    height,
+    testState,
+  };
+}
+
+function resolveActionSchemaResult(aura) {
+  const actionNs = aura.action && typeof aura.action === 'object' ? aura.action : null;
+  if (!actionNs || typeof actionNs.getSchema !== 'function') {
+    throw new HeadlessTestError('Headless action schema failed: aura.action.getSchema hook is unavailable.');
+  }
+
+  try {
+    return actionNs.getSchema();
+  } catch (error) {
+    throw new HeadlessTestError(`Headless action schema failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+}