@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/cutscene.mjs

@@ -34,11 +34,49 @@ function normalizeCues(cues) {
 function collectCueIdsUpTo(cues, time) {
   const ids = new Set();
   for (const cue of cues) {
-    if (cue.time <= time) ids.add(cue.id);
+    if (cue.time > time) break;
+    ids.add(cue.id);
   }
   return ids;
 }
 
+function secondsToMilliseconds(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric * 1000 : fallback;
+}
+
+function normalizeProgress(currentTime, duration) {
+  const current = Number(currentTime);
+  const total = Number(duration);
+  if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0) return 0;
+  return Math.max(0, Math.min(1, current / total));
+}
+
+function findLatestCueAtOrBefore(cues, time, type = null) {
+  let match = null;
+  for (const cue of cues) {
+    if (cue.time > time) break;
+    if (type === null || cue.type === type) {
+      match = cue;
+    }
+  }
+  return match;
+}
+
+function findNextCue(cues, time) {
+  for (const cue of cues) {
+    if (cue.time >= time) return cue;
+  }
+  return null;
+}
+
+function listCueIdsInOrder(cues, firedCueIds) {
+  if (!(firedCueIds instanceof Set) || firedCueIds.size === 0) return [];
+  return cues
+    .filter((cue) => firedCueIds.has(cue.id))
+    .map((cue) => cue.id);
+}
+
 export class VideoCutsceneController {
   constructor(videoApi, handle, options = {}) {
     if (!videoApi || typeof videoApi !== 'object') {
@@ -77,16 +115,32 @@ export class VideoCutsceneController {
 
   getState() {
     const info = this.getInfo();
-    const currentTime = info ? asFiniteNumber(info.currentTime || info.currentTimeSecs, 0) : 0;
+    const currentTime = info ? asFiniteNumber(info.currentTime || info.currentTimeSecs, this.lastTime) : this.lastTime;
     const duration = info ? asFiniteNumber(info.duration || info.durationSecs, 0) : 0;
-    const currentCue = this.options.cues.find((cue) => cue.time >= currentTime) || null;
+    const currentTimeMs = info ? asFiniteNumber(info.currentTimeMs, secondsToMilliseconds(currentTime)) : secondsToMilliseconds(currentTime);
+    const durationMs = info ? asFiniteNumber(info.durationMs, secondsToMilliseconds(duration)) : secondsToMilliseconds(duration);
+    const firedCueIds = listCueIdsInOrder(this.options.cues, this.firedCueIds);
+    const nextCue = findNextCue(this.options.cues, currentTime);
+    const activeSubtitle = findLatestCueAtOrBefore(this.options.cues, currentTime, 'subtitle');
+    const lastCheckpoint = findLatestCueAtOrBefore(this.options.cues, currentTime, 'checkpoint');
+    const playbackProgress = normalizeProgress(currentTime, duration);
     return {
       handle: this.handle,
       info,
       currentTime,
+      currentTimeMs,
       duration,
-      firedCueCount: this.firedCueIds.size,
-      nextCue: currentCue,
+      durationMs,
+      playbackProgress,
+      cueCount: this.options.cues.length,
+      firedCueCount: firedCueIds.length,
+      remainingCueCount: Math.max(0, this.options.cues.length - firedCueIds.length),
+      firedCueIds,
+      nextCue,
+      activeSubtitle,
+      lastCheckpoint,
+      textureReady: info?.textureReady === true,
+      nativeOnly: info?.nativeOnly === true || info?.sourceKind === 'mp4',
     };
   }
 
@@ -202,4 +256,307 @@ export function createVideoCutsceneController(videoApi, handle, options = {}) {
   return new VideoCutsceneController(videoApi, handle, options);
 }
 
+function requireRuntimeFactory(target, method, label) {
+  if (!target || typeof target !== 'object' || typeof target[method] !== 'function') {
+    throw new TypeError(`${label} requires ${method}() on the provided runtime API object.`);
+  }
+}
+
+export function createSpatialAudioEmitter(audioApi, path, options = {}) {
+  requireRuntimeFactory(audioApi, 'createSpatialEmitter', 'createSpatialAudioEmitter(audioApi, path, options)');
+  return audioApi.createSpatialEmitter(path, options);
+}
+
+export function createVideoBillboardSurface(videoApi, source, options = {}) {
+  requireRuntimeFactory(videoApi, 'createBillboardSurface', 'createVideoBillboardSurface(videoApi, source, options)');
+  return videoApi.createBillboardSurface(source, options);
+}
+
+function normalizeAudioSeekMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  switch (normalized) {
+    case 'none':
+    case 'restart':
+    case 'presentation-default':
+      return normalized;
+    default:
+      return 'presentation-default';
+  }
+}
+
+function safePresentationState(presentation, fallback = null) {
+  if (!presentation || typeof presentation.getState !== 'function') return fallback;
+  const state = presentation.getState();
+  return state && typeof state === 'object' ? state : fallback;
+}
+
+function summarizePresentationState(state) {
+  const presentationState = state && typeof state === 'object' ? state : null;
+  const surface = presentationState?.surface && typeof presentationState.surface === 'object'
+    ? presentationState.surface
+    : null;
+  const emitter = presentationState?.emitter && typeof presentationState.emitter === 'object'
+    ? presentationState.emitter
+    : null;
+  const info = surface?.info && typeof surface.info === 'object' ? surface.info : null;
+
+  return {
+    targetAttached: presentationState?.targetAttached === true,
+    hasAudio: !!emitter,
+    audioAttached: emitter?.attached === true,
+    handle: Number.isInteger(surface?.handle) && surface.handle > 0 ? surface.handle : 0,
+    textureHandle: Number.isInteger(surface?.textureHandle) && surface.textureHandle > 0 ? surface.textureHandle : 0,
+    playbackState: typeof info?.state === 'string' ? info.state : null,
+    currentTime: asFiniteNumber(info?.currentTime || info?.currentTimeSecs, 0),
+    currentTimeMs: asFiniteNumber(info?.currentTimeMs, secondsToMilliseconds(info?.currentTime || info?.currentTimeSecs, 0)),
+    duration: asFiniteNumber(info?.duration || info?.durationSecs, 0),
+    durationMs: asFiniteNumber(info?.durationMs, secondsToMilliseconds(info?.duration || info?.durationSecs, 0)),
+    playbackProgress: normalizeProgress(info?.currentTime || info?.currentTimeSecs, info?.duration || info?.durationSecs),
+    sourceKind: typeof info?.sourceKind === 'string' ? info.sourceKind : null,
+    textureReady: typeof info?.textureReady === 'boolean'
+      ? info.textureReady
+      : (Number.isInteger(surface?.textureHandle) && surface.textureHandle > 0),
+    nativeOnly: typeof info?.nativeOnly === 'boolean'
+      ? info.nativeOnly
+      : info?.sourceKind === 'mp4',
+  };
+}
+
+export function createMediaPresentationController(runtime, source, options = {}) {
+  if (!runtime || typeof runtime !== 'object') {
+    throw new TypeError('createMediaPresentationController(runtime, source, options) requires a runtime object.');
+  }
+  requireRuntimeFactory(runtime.video, 'createPresentation', 'createMediaPresentationController(runtime, source, options)');
+
+  const presentation = runtime.video.createPresentation(source, options);
+  const audioSeekMode = normalizeAudioSeekMode(options?.audioSeekMode);
+  const usesCutsceneCues = !!(
+    options
+    && typeof options === 'object'
+    && (
+      Array.isArray(options.cues)
+      || typeof options.onCue === 'function'
+      || typeof options.onSubtitle === 'function'
+      || typeof options.onCheckpoint === 'function'
+      || typeof options.onStateChange === 'function'
+    )
+  );
+  let cutscene = null;
+  let unloaded = false;
+  let lastAction = 'idle';
+  let lastResult = null;
+  let lastAudioResync = null;
+  let lastPresentationState = safePresentationState(presentation);
+
+  function ensureCutsceneController() {
+    if (!usesCutsceneCues) return null;
+    if (cutscene) return cutscene;
+    if (!runtime.video || typeof runtime.video.getInfo !== 'function') return null;
+    const state = safePresentationState(presentation, lastPresentationState);
+    const handle = Number(state?.surface?.handle || 0);
+    if (!Number.isInteger(handle) || handle <= 0) return null;
+    cutscene = createVideoCutsceneController(runtime.video, handle, options);
+    return cutscene;
+  }
+
+  function syncCutsceneAfterExternalSeek(controller, targetTime) {
+    const normalizedTarget = Number(targetTime);
+    if (!Number.isFinite(normalizedTarget) || normalizedTarget < 0) {
+      return controller ? controller.sync() : null;
+    }
+    controller.firedCueIds = collectCueIdsUpTo(controller.options.cues, normalizedTarget);
+    controller.lastTime = normalizedTarget;
+    return controller.sync();
+  }
+
+  function capturePresentationState() {
+    lastPresentationState = safePresentationState(presentation, lastPresentationState);
+    return lastPresentationState;
+  }
+
+  function recordAction(action, result, audioResync = null) {
+    lastAction = action;
+    lastResult = result ?? null;
+    if (audioResync !== null) {
+      lastAudioResync = audioResync;
+    }
+    capturePresentationState();
+    return result;
+  }
+
+  function requestAudioResync(reason, timeSecs) {
+    if (audioSeekMode === 'none') {
+      lastAudioResync = { ok: false, reasonCode: 'audio_seek_mode_disabled', reason, timeSecs };
+      return lastAudioResync;
+    }
+    if (audioSeekMode === 'restart' && typeof presentation.restartAudio === 'function') {
+      const result = presentation.restartAudio({ reason, timeSecs });
+      lastAudioResync = result ?? { ok: true, reasonCode: null, reason, timeSecs };
+      return lastAudioResync;
+    }
+    if (typeof presentation.resyncAudio === 'function') {
+      const result = presentation.resyncAudio({ reason, timeSecs, mode: audioSeekMode });
+      lastAudioResync = result ?? { ok: true, reasonCode: null, reason, timeSecs };
+      return lastAudioResync;
+    }
+    lastAudioResync = { ok: false, reasonCode: 'audio_resync_unavailable', reason, timeSecs };
+    return lastAudioResync;
+  }
+
+  function currentState() {
+    const presentationState = capturePresentationState();
+    const media = summarizePresentationState(presentationState);
+    const cutsceneState = cutscene ? cutscene.getState() : null;
+    const emitterState = presentationState?.emitter || null;
+    return {
+      unloaded,
+      source,
+      audioSeekMode,
+      lastAction,
+      lastResult,
+      lastAudioResync,
+      media,
+      surface: presentationState?.surface || null,
+      emitter: emitterState,
+      presentation: presentationState,
+      cutscene: cutsceneState,
+      observability: {
+        nativeOnly: media.nativeOnly,
+        textureReady: media.textureReady,
+        sourceKind: media.sourceKind,
+        currentTimeMs: media.currentTimeMs,
+        durationMs: media.durationMs,
+        playbackProgress: media.playbackProgress,
+        audioSeekMode,
+        spatialAudioAttached: emitterState?.attached === true,
+        spatialAudioReasonCode: typeof lastAudioResync?.reasonCode === 'string' && lastAudioResync.reasonCode.length > 0
+          ? lastAudioResync.reasonCode
+          : (typeof emitterState?.lastReasonCode === 'string' ? emitterState.lastReasonCode : null),
+        cueCoverage: {
+          total: cutsceneState?.cueCount || 0,
+          fired: cutsceneState?.firedCueCount || 0,
+          remaining: cutsceneState?.remainingCueCount || 0,
+        },
+        activeSubtitle: cutsceneState?.activeSubtitle || null,
+        lastCheckpoint: cutsceneState?.lastCheckpoint || null,
+        portability: {
+          browserParity: 'out_of_scope',
+          muxedAudioGuarantees: 'out_of_scope',
+          cinematicEditor: 'out_of_scope',
+        },
+      },
+    };
+  }
+
+  return {
+    play() {
+      unloaded = false;
+      const result = presentation.play();
+      const controller = ensureCutsceneController();
+      if (controller) controller.sync();
+      return recordAction('play', result);
+    },
+    pause() {
+      const result = presentation.pause();
+      if (cutscene) cutscene.sync();
+      return recordAction('pause', result);
+    },
+    resume() {
+      unloaded = false;
+      const result = presentation.resume();
+      const controller = ensureCutsceneController();
+      if (controller) controller.sync();
+      return recordAction('resume', result);
+    },
+    stop() {
+      const result = presentation.stop();
+      if (cutscene) {
+        cutscene.firedCueIds.clear();
+        cutscene.lastInfo = null;
+        cutscene.lastTime = 0;
+        cutscene.lastState = 'stopped';
+        cutscene.sync();
+      }
+      return recordAction('stop', result);
+    },
+    attach(target, attachOptions = {}) {
+      return recordAction('attach', presentation.attach(target, attachOptions));
+    },
+    update() {
+      const result = presentation.update();
+      const controller = ensureCutsceneController();
+      if (controller) controller.update();
+      return recordAction('update', result);
+    },
+    draw(drawOptions = {}) {
+      return recordAction('draw', presentation.draw(drawOptions));
+    },
+    seek(timeSecs) {
+      const result = presentation.seek(timeSecs);
+      const controller = ensureCutsceneController();
+      if (controller) syncCutsceneAfterExternalSeek(controller, timeSecs);
+      return recordAction('seek', result, requestAudioResync('seek', Number(timeSecs)));
+    },
+    skip(targetTime = null) {
+      const controller = ensureCutsceneController();
+      if (controller) {
+        const info = controller.getInfo();
+        const fallbackDuration = info ? asFiniteNumber(info.duration || info.durationSecs, 0) : 0;
+        const resolvedTarget = targetTime != null && Number.isFinite(Number(targetTime))
+          ? Math.max(0, Number(targetTime))
+          : (controller.options.skipTarget != null ? controller.options.skipTarget : fallbackDuration);
+        if (presentation && typeof presentation.seek === 'function') {
+          const result = presentation.seek(resolvedTarget);
+          const synced = syncCutsceneAfterExternalSeek(controller, resolvedTarget);
+          recordAction('skip', result ?? synced, requestAudioResync('skip', resolvedTarget));
+        }
+        return currentState();
+      }
+      const resolvedTarget = targetTime == null ? 0 : targetTime;
+      return recordAction('skip', presentation.seek(resolvedTarget), requestAudioResync('skip', Number(resolvedTarget)));
+    },
+    exportCheckpointState() {
+      return {
+        source,
+        audioSeekMode,
+        presentation: currentState().media,
+        cutscene: cutscene ? cutscene.exportCheckpointState() : null,
+      };
+    },
+    restoreCheckpointState(snapshot) {
+      if (!snapshot || typeof snapshot !== 'object') {
+        throw new TypeError('createMediaPresentationController(...).restoreCheckpointState(snapshot) requires an object snapshot.');
+      }
+      unloaded = false;
+      const cutsceneSnapshot = snapshot.cutscene && typeof snapshot.cutscene === 'object'
+        ? snapshot.cutscene
+        : snapshot;
+      const targetTime = cutsceneSnapshot && Number.isFinite(Number(cutsceneSnapshot.currentTime))
+        ? Math.max(0, Number(cutsceneSnapshot.currentTime))
+        : asFiniteNumber(snapshot.presentation?.currentTime, 0);
+      let result = null;
+      const controller = ensureCutsceneController();
+      if (controller && cutsceneSnapshot && Number.isFinite(Number(cutsceneSnapshot.currentTime))) {
+        result = controller.restoreCheckpointState(cutsceneSnapshot);
+      } else if (typeof presentation.seek === 'function') {
+        result = presentation.seek(targetTime);
+      }
+      return recordAction(
+        'restoreCheckpointState',
+        result,
+        requestAudioResync('restore-checkpoint', targetTime),
+      );
+    },
+    unload() {
+      const result = presentation.unload();
+      unloaded = true;
+      cutscene = null;
+      return recordAction('unload', result);
+    },
+    getState() {
+      return currentState();
+    },
+  };
+}
+
 export default createVideoCutsceneController;

package/src/dev-cli-action.mjs

@@ -0,0 +1,249 @@
+import {
+  GAME_ACTION_REQUEST_SCHEMA_VERSION,
+  GAME_ACTION_RESULT_SCHEMA_VERSION,
+  GAME_ACTION_SCHEMA_VERSION,
+} from './game-action-runtime.mjs';
+import { GAME_STATE_SCHEMA_VERSION } from './game-state-runtime.mjs';
+
+export class DevCliActionError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'DevCliActionError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+export async function runActionSchemaFlow({
+  parsed,
+  projectRoot,
+  loadConfig,
+  runHeadlessActionSchema,
+}) {
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const file = parsed.file || config.build.entry;
+
+  const schemaRun = await runHeadlessActionSchema({
+    projectRoot,
+    file,
+  });
+
+  if (!schemaRun || typeof schemaRun !== 'object') {
+    throw new DevCliActionError(
+      'action_runtime_failed',
+      'Action schema runtime returned an invalid result.',
+    );
+  }
+
+  const schemaResult = schemaRun.schemaResult;
+  if (!schemaResult || typeof schemaResult !== 'object') {
+    throw new DevCliActionError(
+      'action_runtime_failed',
+      'Action schema runtime returned an invalid schema result.',
+      { schemaRun },
+    );
+  }
+  if (schemaResult.ok !== true) {
+    throw new DevCliActionError(
+      typeof schemaResult.reasonCode === 'string' ? schemaResult.reasonCode : 'action_contract_unavailable',
+      schemaResult.detail
+        ? `Action schema export failed: ${schemaResult.detail}`
+        : 'Action schema export failed.',
+      { schemaRun, schemaResult },
+    );
+  }
+  if (!schemaResult.payload || typeof schemaResult.payload !== 'object') {
+    throw new DevCliActionError(
+      'action_schema_invalid_payload',
+      'Action schema runtime returned an invalid schema payload.',
+      { schemaRun, schemaResult },
+    );
+  }
+  if (schemaResult.payload.schemaVersion !== parsed.schemaVersion) {
+    throw new DevCliActionError(
+      'schema_version_mismatch',
+      `Action schema "${schemaResult.payload.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
+      { exported: schemaResult.payload.schemaVersion, requested: parsed.schemaVersion },
+    );
+  }
+
+  return {
+    file,
+    payload: schemaResult.payload,
+    schemaRun,
+  };
+}
+
+export async function runActionRunFlow({
+  parsed,
+  projectRoot,
+  loadConfig,
+  readJsonInputFile,
+  runHeadlessActionRun,
+}) {
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const file = parsed.file || config.build.entry;
+  const request = readJsonInputFile(parsed.requestPath, 'action request payload', 'action_request_input');
+  const statePayload = parsed.statePath
+    ? readJsonInputFile(parsed.statePath, 'action seed state payload', 'action_seed_state_input')
+    : null;
+
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    throw new DevCliActionError(
+      'invalid_action_request',
+      'Action request payload must be a JSON object.',
+    );
+  }
+  if (request.schemaVersion !== GAME_ACTION_REQUEST_SCHEMA_VERSION) {
+    throw new DevCliActionError(
+      'schema_version_mismatch',
+      `Unsupported action request schema "${request.schemaVersion}". Expected "${GAME_ACTION_REQUEST_SCHEMA_VERSION}".`,
+      { exported: request.schemaVersion, requested: GAME_ACTION_REQUEST_SCHEMA_VERSION },
+    );
+  }
+  if (statePayload != null) {
+    validateSeedStatePayload(statePayload);
+  }
+
+  const actionRun = await runHeadlessActionRun({
+    projectRoot,
+    file,
+    request,
+    statePayload,
+    frames: parsed.frames,
+    mode: parsed.mode,
+    includeState: parsed.includeState,
+    frameIndex: parsed.frames,
+  });
+
+  if (!actionRun || typeof actionRun !== 'object') {
+    throw new DevCliActionError(
+      'action_runtime_failed',
+      'Action run runtime returned an invalid result.',
+    );
+  }
+  if (actionRun.seedStateApplyResult && actionRun.seedStateApplyResult.ok !== true) {
+    throw new DevCliActionError(
+      typeof actionRun.seedStateApplyResult.reasonCode === 'string'
+        ? actionRun.seedStateApplyResult.reasonCode
+        : 'state_apply_failed',
+      actionRun.seedStateApplyResult.detail
+        ? `Action seed state apply failed: ${actionRun.seedStateApplyResult.detail}`
+        : 'Action seed state apply failed.',
+      {
+        actionRun,
+        seedStateApplyResult: actionRun.seedStateApplyResult,
+      },
+    );
+  }
+
+  const actionResult = actionRun.actionResult;
+  if (!actionResult || typeof actionResult !== 'object') {
+    throw new DevCliActionError(
+      'action_runtime_failed',
+      'Action run runtime returned an invalid action result.',
+      { actionRun },
+    );
+  }
+  if (actionResult.schemaVersion !== parsed.schemaVersion) {
+    throw new DevCliActionError(
+      'schema_version_mismatch',
+      `Action result schema "${actionResult.schemaVersion}" does not match requested schema "${parsed.schemaVersion}".`,
+      { exported: actionResult.schemaVersion, requested: parsed.schemaVersion },
+    );
+  }
+  if (actionResult.ok !== true) {
+    throw new DevCliActionError(
+      typeof actionResult.reasonCode === 'string' ? actionResult.reasonCode : 'action_run_failed',
+      actionResult.detail
+        ? `Action run failed: ${actionResult.detail}`
+        : 'Action run failed.',
+      { actionRun, actionResult },
+    );
+  }
+
+  const report = orderActionRunReport({
+    ...actionResult,
+    ...(actionRun.stateResult?.payload
+      ? {
+          followUpFrames: parsed.frames,
+          state: validateExportedStatePayload(actionRun.stateResult.payload),
+        }
+      : {}),
+  });
+
+  return {
+    file,
+    report,
+    actionRun,
+  };
+}
+
+export function serializeActionPayload(payload, compact = false) {
+  return compact
+    ? `${JSON.stringify(payload)}\n`
+    : `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+function validateExportedStatePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new DevCliActionError(
+      'action_runtime_failed',
+      'Action follow-up state export returned an invalid payload.',
+      { payload },
+    );
+  }
+  if (payload.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    throw new DevCliActionError(
+      'schema_version_mismatch',
+      `Action follow-up state schema "${payload.schemaVersion}" does not match expected schema "${GAME_STATE_SCHEMA_VERSION}".`,
+      { payload },
+    );
+  }
+  return payload;
+}
+
+function validateSeedStatePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new DevCliActionError(
+      'invalid_schema_payload',
+      'Action seed state payload must be a JSON object.',
+      { payload },
+    );
+  }
+  if (payload.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    throw new DevCliActionError(
+      'schema_version_mismatch',
+      `Action seed state schema "${payload.schemaVersion}" does not match expected schema "${GAME_STATE_SCHEMA_VERSION}".`,
+      { payload },
+    );
+  }
+  return payload;
+}
+
+function orderActionRunReport(payload) {
+  const ordered = {};
+  const keyOrder = [
+    'schemaVersion',
+    'ok',
+    'reasonCode',
+    'actionId',
+    'detail',
+    'output',
+    'followUpFrames',
+    'state',
+  ];
+
+  for (const key of keyOrder) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) {
+      ordered[key] = payload[key];
+    }
+  }
+
+  return ordered;
+}
+
+export {
+  GAME_ACTION_SCHEMA_VERSION,
+  GAME_ACTION_RESULT_SCHEMA_VERSION,
+};