@auraindustry/aurajs 0.0.1 → 0.0.3

package/src/build-contract.mjs

@@ -1,7 +1,19 @@
-import { relative, resolve, sep } from 'node:path';
-import { writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { extname, relative, resolve, sep } from 'node:path';
 
 export const BUILD_MANIFEST_SCHEMA = 'aurajs.build-manifest.v1';
+export const WEB_BUILD_MANIFEST_SCHEMA = 'aurajs.web-build-manifest.v1';
+export const WEB_RUNTIME_CONFIG_SCHEMA = 'aurajs.web-runtime-config.v1';
 
 export function writeBuildManifest(options = {}) {
   const outRoot = resolve(options.outRoot || process.cwd());
@@ -45,6 +57,73 @@ export function writeBuildManifest(options = {}) {
   return manifestPath;
 }
 
+export function writeWebBuildArtifacts(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const outRoot = resolve(options.outRoot || resolve(projectRoot, 'build', 'web'));
+  const bundlePath = resolveRequiredPath(options.bundlePath, 'bundlePath');
+  const runtimeApiVersion = Number.isInteger(options.runtimeApiVersion)
+    ? options.runtimeApiVersion
+    : 1;
+  if (runtimeApiVersion <= 0) {
+    throw new Error('web build contract requires runtimeApiVersion to be a positive integer.');
+  }
+
+  mkdirSync(resolve(outRoot, 'js'), { recursive: true });
+  mkdirSync(resolve(outRoot, 'assets'), { recursive: true });
+
+  const assets = emitWebAssets({
+    projectRoot,
+    outRoot,
+  });
+
+  const runtimeConfig = buildRuntimeConfig({
+    windowConfig: options.windowConfig || {},
+    modules: options.modules || {},
+  });
+  const runtimeConfigPath = resolve(outRoot, 'runtime-config.json');
+  writeCanonicalJson(runtimeConfigPath, runtimeConfig);
+
+  const loaderPath = resolve(outRoot, 'js', 'aura-web-loader.js');
+  writeFileSync(loaderPath, `${WEB_LOADER_SOURCE}\n`, 'utf8');
+
+  const indexPath = resolve(outRoot, 'index.html');
+  writeFileSync(indexPath, `${WEB_INDEX_HTML}\n`, 'utf8');
+
+  const manifestBody = {
+    schema: WEB_BUILD_MANIFEST_SCHEMA,
+    schemaVersion: '1.0.0',
+    buildTarget: 'web',
+    runtimeApiVersion,
+    entrypoints: {
+      html: toPosix(relative(outRoot, indexPath)),
+      loader: toPosix(relative(outRoot, loaderPath)),
+      bundle: toPosix(relative(outRoot, bundlePath)),
+      runtimeConfig: toPosix(relative(outRoot, runtimeConfigPath)),
+    },
+    assets: assets.entries,
+  };
+  const manifestHash = sha256(Buffer.from(JSON.stringify(manifestBody)));
+  const manifest = {
+    ...manifestBody,
+    integrity: {
+      manifestSha256: manifestHash,
+    },
+  };
+
+  const manifestPath = resolve(outRoot, 'web-build-manifest.json');
+  writeCanonicalJson(manifestPath, manifest);
+
+  return {
+    outRoot,
+    manifestPath,
+    runtimeConfigPath,
+    loaderPath,
+    indexPath,
+    assetCount: assets.entries.length,
+    assetsRoot: assets.assetsOutRoot,
+  };
+}
+
 function resolveRequiredPath(pathLike, fieldName) {
   if (typeof pathLike !== 'string' || pathLike.length === 0) {
     throw new Error(`build contract requires a non-empty "${fieldName}" path.`);
@@ -69,3 +148,630 @@ function resolveOptionalRelative(outRoot, pathLike) {
   }
   return toPosix(relative(outRoot, resolve(pathLike)));
 }
+
+function buildRuntimeConfig(options = {}) {
+  const windowConfig = options.windowConfig && typeof options.windowConfig === 'object'
+    ? options.windowConfig
+    : {};
+  const modules = options.modules && typeof options.modules === 'object'
+    ? options.modules
+    : {};
+
+  return {
+    schema: WEB_RUNTIME_CONFIG_SCHEMA,
+    schemaVersion: '1.0.0',
+    canvas: {
+      id: 'aura-canvas',
+      resizeMode: 'fit-container',
+      width: normalizePositiveInt(windowConfig.width, 1280),
+      height: normalizePositiveInt(windowConfig.height, 720),
+      devicePixelRatioMode: 'clamped',
+    },
+    loop: {
+      tickMode: 'raf',
+      maxDeltaMs: 50,
+    },
+    modules: {
+      physics: modules.physics === true,
+      network: modules.network === true,
+      multiplayer: modules.multiplayer === true,
+    },
+  };
+}
+
+function emitWebAssets({ projectRoot, outRoot }) {
+  const sourceRoot = resolve(projectRoot, 'assets');
+  const assetsOutRoot = resolve(outRoot, 'assets');
+  rmSync(assetsOutRoot, { recursive: true, force: true });
+  mkdirSync(assetsOutRoot, { recursive: true });
+
+  const sourceFiles = collectFiles(sourceRoot);
+  const entries = [];
+  for (const sourcePath of sourceFiles) {
+    const sourceRelative = toPosix(relative(sourceRoot, sourcePath));
+    const sourceBytes = readFileSync(sourcePath);
+    const contentHash = sha256(sourceBytes);
+    const relativeHash = sha256(Buffer.from(sourceRelative, 'utf8')).slice(0, 8);
+    const extension = extname(sourceRelative).toLowerCase();
+    const stemSource = extension.length > 0
+      ? sourceRelative.slice(0, sourceRelative.length - extension.length)
+      : sourceRelative;
+    const stem = sanitizeAssetStem(stemSource);
+    const outputName = `${stem}.${relativeHash}.${contentHash.slice(0, 12)}${extension}`;
+    const outputPath = resolve(assetsOutRoot, outputName);
+
+    copyFileSync(sourcePath, outputPath);
+    entries.push({
+      path: `assets/${outputName}`,
+      bytes: sourceBytes.length,
+      sha256: contentHash,
+      mediaType: mediaTypeForExtension(extension),
+    });
+  }
+
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  removeUnexpectedFiles(assetsOutRoot, new Set(entries.map((entry) => entry.path.slice('assets/'.length))));
+  return { entries, assetsOutRoot };
+}
+
+function collectFiles(rootPath) {
+  if (!existsSync(rootPath)) {
+    return [];
+  }
+  const output = [];
+  walkFiles(rootPath, output);
+  output.sort((a, b) => toPosix(a).localeCompare(toPosix(b)));
+  return output;
+}
+
+function walkFiles(dirPath, output) {
+  const names = readdirSync(dirPath).sort((a, b) => a.localeCompare(b));
+  for (const name of names) {
+    const fullPath = resolve(dirPath, name);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkFiles(fullPath, output);
+      continue;
+    }
+    output.push(fullPath);
+  }
+}
+
+function sanitizeAssetStem(value) {
+  const normalized = String(value || '')
+    .replace(/[\\/]+/g, '-')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '');
+  return normalized.length > 0 ? normalized : 'asset';
+}
+
+function mediaTypeForExtension(extension) {
+  switch (extension) {
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    case '.wav':
+      return 'audio/wav';
+    case '.ogg':
+      return 'audio/ogg';
+    case '.mp3':
+      return 'audio/mpeg';
+    case '.json':
+      return 'application/json';
+    case '.txt':
+    case '.md':
+    case '.csv':
+      return 'text/plain; charset=utf-8';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function normalizePositiveInt(value, fallback) {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.floor(value);
+  return normalized > 0 ? normalized : fallback;
+}
+
+function writeCanonicalJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function removeUnexpectedFiles(rootPath, allowedNames) {
+  if (!existsSync(rootPath)) {
+    return;
+  }
+  for (const name of readdirSync(rootPath)) {
+    if (allowedNames.has(name)) {
+      continue;
+    }
+    rmSync(resolve(rootPath, name), { recursive: true, force: true });
+  }
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+const WEB_INDEX_HTML = [
+  '<!doctype html>',
+  '<html lang="en">',
+  '<head>',
+  '  <meta charset="utf-8" />',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1" />',
+  '  <title>AuraJS Web Build</title>',
+  '</head>',
+  '<body>',
+  '  <div id="aura-root">',
+  '    <canvas id="aura-canvas"></canvas>',
+  '  </div>',
+  '  <script src="./js/aura-web-loader.js"></script>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+const WEB_LOADER_SOURCE = `
+(function (globalRef) {
+  const state = {
+    phase: 'idle',
+    reasonCode: null,
+    lastError: null,
+    lifecycle: {
+      running: false,
+      setupCalls: 0,
+      updateCalls: 0,
+      drawCalls: 0,
+      frameCount: 0,
+      lastDeltaSeconds: 0
+    }
+  };
+  let cachedManifest = null;
+  let cachedRuntimeConfig = null;
+  let mountedRuntime = null;
+
+  function normalizeCount(value) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0) return 0;
+    return Math.floor(numeric);
+  }
+
+  function normalizeDeltaSeconds(value) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0) return 0;
+    return Number(numeric.toFixed(6));
+  }
+
+  function cloneLifecycle(lifecycle) {
+    const source = lifecycle && typeof lifecycle === 'object' ? lifecycle : {};
+    return {
+      running: source.running === true,
+      setupCalls: normalizeCount(source.setupCalls),
+      updateCalls: normalizeCount(source.updateCalls),
+      drawCalls: normalizeCount(source.drawCalls),
+      frameCount: normalizeCount(source.frameCount),
+      lastDeltaSeconds: normalizeDeltaSeconds(source.lastDeltaSeconds)
+    };
+  }
+
+  function setState(phase, reasonCode, error) {
+    state.phase = phase;
+    state.reasonCode = reasonCode || null;
+    state.lastError = error || null;
+  }
+
+  function createError(reasonCode, message, layer, retryable, details) {
+    const error = new Error(message);
+    error.ok = false;
+    error.reasonCode = reasonCode;
+    error.layer = layer;
+    error.retryable = Boolean(retryable);
+    error.details = details || {};
+    return error;
+  }
+
+  function normalizeError(error, fallbackReasonCode, fallbackMessage, fallbackLayer, fallbackRetryable) {
+    if (error && typeof error === 'object' && typeof error.reasonCode === 'string') {
+      return error;
+    }
+    return createError(
+      fallbackReasonCode,
+      fallbackMessage,
+      fallbackLayer,
+      fallbackRetryable,
+      { cause: String(error && error.message ? error.message : error) }
+    );
+  }
+
+  async function captureFailure(fallback, operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      const normalized = normalizeError(
+        error,
+        fallback.reasonCode,
+        fallback.message,
+        fallback.layer,
+        fallback.retryable
+      );
+      setState('error', normalized.reasonCode, {
+        reasonCode: normalized.reasonCode,
+        layer: normalized.layer || fallback.layer,
+        retryable: normalized.retryable === true,
+        details: normalized.details || {}
+      });
+      throw normalized;
+    }
+  }
+
+  async function readJson(path, missingCode, parseCode) {
+    let response;
+    try {
+      response = await fetch(path, { cache: 'no-store' });
+    } catch (error) {
+      throw createError(missingCode, 'Failed to fetch ' + path + '.', 'loader', false, { cause: String(error) });
+    }
+    if (!response || response.ok !== true) {
+      throw createError(missingCode, path + ' not found.', 'loader', false, { status: response ? response.status : null });
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw createError(parseCode, path + ' is not valid JSON.', 'loader', false, { cause: String(error) });
+    }
+  }
+
+  function normalizePath(path) {
+    if (typeof path !== 'string') return '';
+    return path.replace(/\\\\/g, '/').replace(/^\\.\\//, '');
+  }
+
+  function resolveTarget(target) {
+    if (typeof target === 'string') {
+      return document.querySelector(target);
+    }
+    if (target && typeof target.appendChild === 'function') {
+      return target;
+    }
+    return document.getElementById('aura-root') || document.body;
+  }
+
+  function ensureManifestValid(manifest) {
+    if (!manifest || manifest.schema !== 'aurajs.web-build-manifest.v1') {
+      throw createError(
+        'web_manifest_schema_unsupported',
+        'Manifest schema major version is unsupported.',
+        'loader',
+        false,
+        { schema: manifest && manifest.schema }
+      );
+    }
+    if (!manifest.entrypoints || typeof manifest.entrypoints.bundle !== 'string' || manifest.entrypoints.bundle.length === 0) {
+      throw createError('web_manifest_validation_failed', 'Manifest bundle entrypoint is missing.', 'loader', false, {});
+    }
+  }
+
+  function ensureRuntimeConfigValid(runtimeConfig) {
+    if (!runtimeConfig || runtimeConfig.schema !== 'aurajs.web-runtime-config.v1') {
+      throw createError(
+        'web_runtime_config_validation_failed',
+        'Runtime config schema major version is unsupported.',
+        'loader',
+        false,
+        { schema: runtimeConfig && runtimeConfig.schema }
+      );
+    }
+  }
+
+  function loadScript(path) {
+    return new Promise((resolvePromise, rejectPromise) => {
+      const script = document.createElement('script');
+      script.src = path;
+      script.async = false;
+      script.onload = function () { resolvePromise(); };
+      script.onerror = function () {
+        rejectPromise(createError('web_bundle_load_failed', 'Failed to load ' + path + '.', 'loader', true, { path }));
+      };
+      document.head.appendChild(script);
+    });
+  }
+
+  function normalizePositiveNumber(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+    return numeric;
+  }
+
+  function createDeterministicBootstrap() {
+    return async function bootstrap(input) {
+      const auraRef = globalRef.aura && typeof globalRef.aura === 'object'
+        ? globalRef.aura
+        : (globalRef.aura = {});
+      const runtimeConfig = input && typeof input.runtimeConfig === 'object' && input.runtimeConfig
+        ? input.runtimeConfig
+        : {};
+      const loopConfig = runtimeConfig.loop && typeof runtimeConfig.loop === 'object'
+        ? runtimeConfig.loop
+        : {};
+      const maxDeltaSeconds = normalizePositiveNumber(loopConfig.maxDeltaMs, 50) / 1000;
+      const fixedDeltaSeconds = Math.min(maxDeltaSeconds, 1 / 60);
+      const requestFrame = typeof globalRef.requestAnimationFrame === 'function'
+        ? globalRef.requestAnimationFrame.bind(globalRef)
+        : function (callback) {
+          return globalRef.setTimeout(function () {
+            callback(Date.now());
+          }, 16);
+        };
+      const cancelFrame = typeof globalRef.cancelAnimationFrame === 'function'
+        ? globalRef.cancelAnimationFrame.bind(globalRef)
+        : function (handle) {
+          globalRef.clearTimeout(handle);
+        };
+
+      const runtimeState = {
+        disposed: false,
+        running: false,
+        setupCalls: 0,
+        updateCalls: 0,
+        drawCalls: 0,
+        frameCount: 0,
+        lastDeltaSeconds: 0,
+        rafHandle: null
+      };
+
+      function getLifecycle() {
+        return {
+          running: runtimeState.running && runtimeState.disposed === false,
+          setupCalls: runtimeState.setupCalls,
+          updateCalls: runtimeState.updateCalls,
+          drawCalls: runtimeState.drawCalls,
+          frameCount: runtimeState.frameCount,
+          lastDeltaSeconds: runtimeState.lastDeltaSeconds
+        };
+      }
+
+      function syncLifecycle() {
+        state.lifecycle = cloneLifecycle(getLifecycle());
+      }
+
+      try {
+        if (typeof auraRef.setup === 'function') {
+          const setupResult = auraRef.setup();
+          if (setupResult && typeof setupResult.then === 'function') {
+            await setupResult;
+          }
+          runtimeState.setupCalls += 1;
+        }
+      } catch (error) {
+        throw createError(
+          'web_runtime_bootstrap_failed',
+          'Runtime setup failed.',
+          'runtime',
+          true,
+          { stage: 'setup', cause: String(error && error.message ? error.message : error) }
+        );
+      }
+
+      runtimeState.running = true;
+      syncLifecycle();
+
+      function step() {
+        if (runtimeState.running === false || runtimeState.disposed === true) {
+          return;
+        }
+        runtimeState.frameCount += 1;
+        runtimeState.lastDeltaSeconds = fixedDeltaSeconds;
+
+        try {
+          if (typeof auraRef.update === 'function') {
+            auraRef.update(fixedDeltaSeconds);
+            runtimeState.updateCalls += 1;
+          }
+          if (typeof auraRef.draw === 'function') {
+            auraRef.draw();
+            runtimeState.drawCalls += 1;
+          }
+        } catch (error) {
+          runtimeState.running = false;
+          syncLifecycle();
+          const normalized = normalizeError(
+            error,
+            'web_runtime_bootstrap_failed',
+            'Runtime lifecycle callback failed.',
+            'runtime',
+            true
+          );
+          setState('error', normalized.reasonCode, {
+            reasonCode: normalized.reasonCode,
+            layer: normalized.layer || 'runtime',
+            retryable: normalized.retryable === true,
+            details: normalized.details || {}
+          });
+          return;
+        }
+
+        syncLifecycle();
+        runtimeState.rafHandle = requestFrame(step);
+      }
+
+      runtimeState.rafHandle = requestFrame(step);
+
+      return {
+        getLifecycle,
+        async unmount() {
+          if (runtimeState.disposed === true) {
+            return true;
+          }
+          runtimeState.disposed = true;
+          runtimeState.running = false;
+          if (runtimeState.rafHandle != null) {
+            cancelFrame(runtimeState.rafHandle);
+            runtimeState.rafHandle = null;
+          }
+          syncLifecycle();
+          return true;
+        }
+      };
+    };
+  }
+
+  function resolveBootstrap() {
+    if (typeof globalRef.__AURA_WEB_BOOTSTRAP__ === 'function') {
+      return globalRef.__AURA_WEB_BOOTSTRAP__;
+    }
+    return createDeterministicBootstrap();
+  }
+
+  function getLifecycleSnapshot() {
+    if (mountedRuntime && typeof mountedRuntime.getLifecycle === 'function') {
+      try {
+        return cloneLifecycle(mountedRuntime.getLifecycle());
+      } catch (_) {
+        return cloneLifecycle(state.lifecycle);
+      }
+    }
+    return cloneLifecycle(state.lifecycle);
+  }
+
+  const loader = {
+    async load(options) {
+      return captureFailure(
+        {
+          reasonCode: 'web_loader_load_failed',
+          message: 'Loader failed to initialize web runtime assets.',
+          layer: 'loader',
+          retryable: true
+        },
+        async function () {
+          const opts = options || {};
+          const rootUrl = typeof opts.rootUrl === 'string' && opts.rootUrl.length > 0
+            ? opts.rootUrl.replace(/\\/$/, '')
+            : '.';
+          setState('loading', null, null);
+
+          cachedManifest = await readJson(rootUrl + '/web-build-manifest.json', 'web_manifest_missing', 'web_manifest_parse_failed');
+          cachedRuntimeConfig = await readJson(rootUrl + '/runtime-config.json', 'web_runtime_config_missing', 'web_runtime_config_parse_failed');
+          ensureManifestValid(cachedManifest);
+          ensureRuntimeConfigValid(cachedRuntimeConfig);
+
+          const bundleEntry = normalizePath(cachedManifest.entrypoints.bundle);
+          if (bundleEntry.length === 0) {
+            throw createError('web_entrypoint_missing', 'Bundle entrypoint is empty.', 'loader', false, {});
+          }
+          await loadScript(rootUrl + '/' + bundleEntry);
+          setState('loaded', null, null);
+          return true;
+        }
+      );
+    },
+    async mount(target, options) {
+      return captureFailure(
+        {
+          reasonCode: 'web_loader_mount_failed',
+          message: 'Loader mount sequence failed.',
+          layer: 'loader',
+          retryable: true
+        },
+        async function () {
+          if (!cachedManifest || !cachedRuntimeConfig) {
+            await loader.load(options || {});
+          }
+
+          if (mountedRuntime && typeof mountedRuntime.unmount === 'function') {
+            await mountedRuntime.unmount();
+            mountedRuntime = null;
+          }
+
+          setState('mounting', null, null);
+          const opts = options && typeof options === 'object' ? options : {};
+          const targetNode = resolveTarget(target == null ? opts.mount : target);
+          if (!targetNode) {
+            throw createError('web_loader_mount_target_invalid', 'Mount target was not found.', 'loader', false, {});
+          }
+          const canvas = targetNode.querySelector && targetNode.querySelector('canvas')
+            ? targetNode.querySelector('canvas')
+            : document.getElementById('aura-canvas');
+          if (!canvas) {
+            throw createError('web_loader_mount_failed', 'Canvas target was not found.', 'loader', true, {});
+          }
+
+          const bootstrap = resolveBootstrap();
+          if (typeof bootstrap !== 'function') {
+            throw createError('web_runtime_bootstrap_missing', 'Bundle did not expose required bootstrap function.', 'runtime', false, {});
+          }
+
+          let runtimeResult;
+          try {
+            runtimeResult = await bootstrap({
+              canvas: canvas,
+              runtimeConfig: cachedRuntimeConfig || {},
+              manifest: cachedManifest || {}
+            });
+          } catch (error) {
+            throw normalizeError(
+              error,
+              'web_runtime_bootstrap_failed',
+              'Runtime bootstrap threw an exception.',
+              'runtime',
+              true
+            );
+          }
+
+          if (!runtimeResult || typeof runtimeResult !== 'object') {
+            throw createError('web_runtime_bootstrap_failed', 'Runtime bootstrap returned invalid payload.', 'runtime', false, {});
+          }
+          if (typeof runtimeResult.unmount !== 'function') {
+            runtimeResult.unmount = async function () {
+              return true;
+            };
+          }
+
+          mountedRuntime = runtimeResult;
+          state.lifecycle = getLifecycleSnapshot();
+          setState('mounted', null, null);
+          return true;
+        }
+      );
+    },
+    async unmount() {
+      return captureFailure(
+        {
+          reasonCode: 'web_loader_unmount_failed',
+          message: 'Loader unmount sequence failed.',
+          layer: 'loader',
+          retryable: true
+        },
+        async function () {
+          setState('unmounting', null, null);
+          if (mountedRuntime && typeof mountedRuntime.unmount === 'function') {
+            await mountedRuntime.unmount();
+          }
+          mountedRuntime = null;
+          state.lifecycle = cloneLifecycle(state.lifecycle);
+          state.lifecycle.running = false;
+          setState('unmounted', null, null);
+          return true;
+        }
+      );
+    },
+    getState() {
+      return {
+        phase: state.phase,
+        reasonCode: state.reasonCode,
+        lastError: state.lastError ? { ...state.lastError } : null,
+        lifecycle: getLifecycleSnapshot()
+      };
+    }
+  };
+
+  globalRef.AuraWebLoader = loader;
+})(typeof window !== 'undefined' ? window : globalThis);
+`.trim();