@auraindustry/aurajs 0.0.1

package/benchmarks/perf-thresholds.json

@@ -0,0 +1,102 @@
+{
+  "schemaVersion": 2,
+  "description": "AuraJS headless performance regression guardrails (cold-start + warm-cache)",
+  "scenePolicy": {
+    "requireAllConfiguredScenes": true
+  },
+  "scenes": {
+    "draw2d_primitives": {
+      "maxAvgFrameTimeMs": 20,
+      "maxJitterMs": 8,
+      "minFps": 30,
+      "maxP50FrameTimeMs": 20,
+      "maxP95FrameTimeMs": 30,
+      "maxP99FrameTimeMs": 40,
+      "maxStutterBurstCount": 10
+    },
+    "sprite_transform_swarm": {
+      "maxAvgFrameTimeMs": 20,
+      "maxJitterMs": 8,
+      "minFps": 30,
+      "maxP50FrameTimeMs": 20,
+      "maxP95FrameTimeMs": 30,
+      "maxP99FrameTimeMs": 40,
+      "maxStutterBurstCount": 10
+    },
+    "math_collision": {
+      "maxAvgFrameTimeMs": 20,
+      "maxJitterMs": 8,
+      "minFps": 30,
+      "maxP50FrameTimeMs": 20,
+      "maxP95FrameTimeMs": 30,
+      "maxP99FrameTimeMs": 40,
+      "maxStutterBurstCount": 10
+    }
+  },
+  "coldStart": {
+    "scenes": {
+      "draw2d_primitives": {
+        "maxAvgFrameTimeMs": 28,
+        "maxJitterMs": 10,
+        "minFps": 24,
+        "maxP50FrameTimeMs": 28,
+        "maxP95FrameTimeMs": 40,
+        "maxP99FrameTimeMs": 50,
+        "maxStutterBurstCount": 2
+      },
+      "sprite_transform_swarm": {
+        "maxAvgFrameTimeMs": 28,
+        "maxJitterMs": 10,
+        "minFps": 24,
+        "maxP50FrameTimeMs": 28,
+        "maxP95FrameTimeMs": 40,
+        "maxP99FrameTimeMs": 50,
+        "maxStutterBurstCount": 2
+      },
+      "math_collision": {
+        "maxAvgFrameTimeMs": 28,
+        "maxJitterMs": 10,
+        "minFps": 24,
+        "maxP50FrameTimeMs": 28,
+        "maxP95FrameTimeMs": 40,
+        "maxP99FrameTimeMs": 50,
+        "maxStutterBurstCount": 2
+      }
+    }
+  },
+  "warmCache": {
+    "scenes": {
+      "draw2d_primitives": {
+        "maxAvgFrameTimeMs": 18,
+        "maxJitterMs": 6,
+        "minFps": 40,
+        "maxP50FrameTimeMs": 18,
+        "maxP95FrameTimeMs": 28,
+        "maxP99FrameTimeMs": 36,
+        "maxStutterBurstCount": 8
+      },
+      "sprite_transform_swarm": {
+        "maxAvgFrameTimeMs": 18,
+        "maxJitterMs": 6,
+        "minFps": 40,
+        "maxP50FrameTimeMs": 18,
+        "maxP95FrameTimeMs": 28,
+        "maxP99FrameTimeMs": 36,
+        "maxStutterBurstCount": 8
+      },
+      "math_collision": {
+        "maxAvgFrameTimeMs": 18,
+        "maxJitterMs": 6,
+        "minFps": 40,
+        "maxP50FrameTimeMs": 18,
+        "maxP95FrameTimeMs": 28,
+        "maxP99FrameTimeMs": 36,
+        "maxStutterBurstCount": 8
+      }
+    }
+  },
+  "latency": {
+    "maxInputQueryMs": 0.05,
+    "maxAudioCallMs": 0.05
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@auraindustry/aurajs",
+  "version": "0.0.1",
+  "description": "Write games in JavaScript, build native binaries.",
+  "type": "module",
+  "bin": {
+    "aura": "./src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src/",
+    "benchmarks/perf-thresholds.json",
+    "templates/"
+  ],
+  "scripts": {
+    "postinstall": "node ./src/postinstall.mjs",
+    "conformance": "node ./src/conformance-runner.mjs",
+    "test:conformance": "node --test ./test/conformance.test.mjs",
+    "test:distribution": "node --test ./test/distribution-contract.test.mjs",
+    "benchmark": "node ./src/perf-benchmark-runner.mjs",
+    "benchmark:strict": "node ./src/perf-benchmark-runner.mjs --strict",
+    "test:benchmark": "node --test ./test/perf-benchmark.test.mjs",
+    "test:e2e": "node --test ./test/e2e-flow.test.mjs"
+  },
+  "optionalDependencies": {
+    "@aurajs/darwin-arm64": "github:Aura-Industry/aurajs-darwin-arm64",
+    "@aurajs/darwin-x64": "github:Aura-Industry/aurajs-darwin-x64",
+    "@aurajs/linux-x64": "github:Aura-Industry/aurajs-linux-x64",
+    "@aurajs/win32-x64": "github:Aura-Industry/aurajs-win32-x64"
+  },
+  "keywords": [
+    "game",
+    "gamedev",
+    "native",
+    "binary",
+    "2d",
+    "sdl2",
+    "wgpu",
+    "v8"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/asset-pack.mjs

@@ -0,0 +1,316 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+
+const SUPPORTED = {
+  png: 'image',
+  jpg: 'image',
+  jpeg: 'image',
+  wav: 'audio',
+  ogg: 'audio',
+  mp3: 'audio',
+  ttf: 'font',
+  otf: 'font',
+  json: 'json',
+  txt: 'text',
+  csv: 'text',
+  xml: 'text',
+  toml: 'text',
+  yaml: 'text',
+  yml: 'text',
+  ini: 'text',
+  cfg: 'text',
+  log: 'text',
+  md: 'text',
+  bin: 'bytes',
+  dat: 'bytes',
+  raw: 'bytes',
+};
+
+const APPROVED_FORMATS = [
+  '.png', '.jpg', '.jpeg',
+  '.wav', '.ogg', '.mp3',
+  '.ttf', '.otf',
+  '.json',
+  '.txt', '.csv', '.xml', '.toml', '.yaml', '.yml', '.ini', '.cfg', '.log', '.md',
+  '.bin', '.dat', '.raw',
+].join(', ');
+
+export function packageAssets(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const outRoot = resolve(options.outRoot || join(projectRoot, 'build'));
+  const mode = options.mode || 'embed';
+
+  if (mode !== 'embed' && mode !== 'sibling') {
+    throw new Error(`AURA_ASSET_002: unsupported --asset-mode \"${mode}\". Use \"embed\" or \"sibling\".`);
+  }
+
+  const assetsRoot = resolve(projectRoot, 'assets');
+  const assets = collectAssets(assetsRoot);
+  const indexed = assets.map((absPath) => {
+    const rel = toPosix(relative(assetsRoot, absPath));
+    const ext = extensionOf(rel);
+    const kind = SUPPORTED[ext];
+
+    if (!kind) {
+      throw new Error(
+        `AURA_ASSET_001: unsupported asset format for \"assets/${rel}\" (.${ext || 'none'}). ` +
+          `Approved AS-005 formats: ${APPROVED_FORMATS}`,
+      );
+    }
+
+    const bytes = readFileSync(absPath);
+    return {
+      path: rel,
+      absolutePath: absPath,
+      kind,
+      bytes,
+      sizeBytes: bytes.length,
+      sha1: sha1(bytes),
+    };
+  });
+
+  const canonicalEntries = indexed
+    .map((entry) => ({
+      path: entry.path,
+      kind: entry.kind,
+      sizeBytes: entry.sizeBytes,
+      sha1: entry.sha1,
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const manifestHash = sha1(Buffer.from(JSON.stringify(canonicalEntries)));
+  const manifestPath = join(outRoot, 'assets-manifest.json');
+  const previousManifest = readJsonIfExists(manifestPath);
+
+  const manifest = {
+    schema: 'aurajs.asset-manifest.v1',
+    runtimeResolver: mode === 'embed' ? 'embedded' : 'disk',
+    mode,
+    manifestHash,
+    pack: null,
+    entries: [],
+  };
+
+  const incremental = {
+    copied: 0,
+    skipped: 0,
+    removed: 0,
+    reusedPack: false,
+  };
+
+  if (mode === 'embed') {
+    const packRel = 'assets/asset-pack.pak';
+    const packPath = join(outRoot, packRel);
+    const canReusePack = (
+      previousManifest
+      && previousManifest.mode === 'embed'
+      && previousManifest.manifestHash === manifestHash
+      && previousManifest.pack
+      && existsSync(packPath)
+    );
+
+    if (canReusePack) {
+      manifest.pack = previousManifest.pack;
+      manifest.entries = Array.isArray(previousManifest.entries) ? previousManifest.entries : [];
+      incremental.reusedPack = true;
+      incremental.skipped = indexed.length;
+    } else {
+      const pack = buildPak(indexed);
+      mkdirSync(join(outRoot, 'assets'), { recursive: true });
+      writeFileSync(packPath, pack.buffer);
+
+      manifest.pack = {
+        format: 'aurajs-pak-v1',
+        file: packRel,
+        sha1: sha1(pack.buffer),
+        sizeBytes: pack.buffer.length,
+        entryCount: indexed.length,
+      };
+
+      manifest.entries = pack.entries.map((entry) => ({
+        path: entry.path,
+        kind: entry.kind,
+        sizeBytes: entry.size,
+        sha1: entry.sha1,
+        offset: entry.offset,
+        packSize: entry.size,
+      }));
+      incremental.copied = indexed.length;
+    }
+
+    const siblingAssets = join(outRoot, 'assets');
+    if (existsSync(siblingAssets)) {
+      for (const child of readdirSync(siblingAssets)) {
+        if (child === 'asset-pack.pak') continue;
+        rmSync(join(siblingAssets, child), { recursive: true, force: true });
+        incremental.removed += 1;
+      }
+    }
+  } else {
+    const siblingRoot = join(outRoot, 'assets');
+    mkdirSync(siblingRoot, { recursive: true });
+
+    const previousEntriesByPath = new Map();
+    if (previousManifest && Array.isArray(previousManifest.entries)) {
+      for (const entry of previousManifest.entries) {
+        if (entry && typeof entry.path === 'string' && typeof entry.sha1 === 'string') {
+          previousEntriesByPath.set(entry.path, entry.sha1);
+        }
+      }
+    }
+
+    const expectedPaths = new Set(indexed.map((entry) => entry.path));
+    for (const existing of collectAssets(siblingRoot)) {
+      const rel = toPosix(relative(siblingRoot, existing));
+      if (!expectedPaths.has(rel)) {
+        rmSync(existing, { force: true });
+        incremental.removed += 1;
+      }
+    }
+
+    for (const entry of indexed) {
+      const dest = join(siblingRoot, ...entry.path.split('/'));
+      mkdirSync(resolve(dest, '..'), { recursive: true });
+      const previousSha = previousEntriesByPath.get(entry.path);
+      if (previousManifest?.mode === 'sibling' && previousSha === entry.sha1 && existsSync(dest)) {
+        incremental.skipped += 1;
+      } else {
+        copyFileSync(entry.absolutePath, dest);
+        incremental.copied += 1;
+      }
+    }
+    manifest.entries = indexed.map((entry) => ({
+      path: entry.path,
+      kind: entry.kind,
+      sizeBytes: entry.sizeBytes,
+      sha1: entry.sha1,
+      file: `assets/${entry.path}`,
+    }));
+  }
+
+  writeManifest(manifestPath, manifest);
+
+  return {
+    mode,
+    assetCount: indexed.length,
+    manifestHash,
+    incremental,
+    manifestPath,
+    packPath: manifest.pack ? join(outRoot, manifest.pack.file) : null,
+  };
+}
+
+function buildPak(entries) {
+  const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+
+  let tocSize = 4;
+  for (const entry of sorted) {
+    tocSize += 4 + Buffer.byteLength(entry.path, 'utf8') + 4 + 4;
+  }
+
+  let cursor = tocSize;
+  const rows = sorted.map((entry) => {
+    const size = entry.bytes.length;
+    const row = {
+      path: entry.path,
+      kind: entry.kind,
+      sha1: entry.sha1,
+      offset: cursor,
+      size,
+      bytes: entry.bytes,
+    };
+    cursor += size;
+    return row;
+  });
+
+  const totalSize = cursor;
+  const out = Buffer.alloc(totalSize);
+  let offset = 0;
+
+  out.writeUInt32LE(rows.length, offset);
+  offset += 4;
+
+  for (const row of rows) {
+    const pathBytes = Buffer.from(row.path, 'utf8');
+    out.writeUInt32LE(pathBytes.length, offset);
+    offset += 4;
+    pathBytes.copy(out, offset);
+    offset += pathBytes.length;
+    out.writeUInt32LE(row.offset, offset);
+    offset += 4;
+    out.writeUInt32LE(row.size, offset);
+    offset += 4;
+  }
+
+  for (const row of rows) {
+    row.bytes.copy(out, row.offset);
+  }
+
+  return { buffer: out, entries: rows };
+}
+
+function collectAssets(assetsRoot) {
+  if (!existsSync(assetsRoot)) {
+    return [];
+  }
+
+  const out = [];
+  walkDir(assetsRoot, out);
+  out.sort((a, b) => toPosix(a).localeCompare(toPosix(b)));
+  return out;
+}
+
+function walkDir(dir, out) {
+  const items = readdirSync(dir).sort((a, b) => a.localeCompare(b));
+  for (const item of items) {
+    const full = join(dir, item);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+      continue;
+    }
+    out.push(full);
+  }
+}
+
+function extensionOf(path) {
+  const idx = path.lastIndexOf('.');
+  if (idx < 0 || idx === path.length - 1) return '';
+  return path.slice(idx + 1).toLowerCase();
+}
+
+function writeManifest(path, manifest) {
+  const normalized = {
+    ...manifest,
+    entries: [...manifest.entries].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+  writeFileSync(path, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+}
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function toPosix(input) {
+  return input.split(sep).join('/');
+}
+
+function sha1(value) {
+  return createHash('sha1').update(value).digest('hex');
+}

package/src/build-contract.mjs

@@ -0,0 +1,71 @@
+import { relative, resolve, sep } from 'node:path';
+import { writeFileSync } from 'node:fs';
+
+export const BUILD_MANIFEST_SCHEMA = 'aurajs.build-manifest.v1';
+
+export function writeBuildManifest(options = {}) {
+  const outRoot = resolve(options.outRoot || process.cwd());
+  const bundlePath = resolveRequiredPath(options.bundlePath, 'bundlePath');
+  const assetsManifestPath = resolveRequiredPath(options.assetsManifestPath, 'assetsManifestPath');
+  const executablePath = options.executablePath
+    ? resolveRequiredPath(options.executablePath, 'executablePath')
+    : null;
+  const assetMode = normalizeAssetMode(options.assetMode || 'embed');
+  const runtimeResolver = assetMode === 'embed' ? 'embedded' : 'disk';
+  const icon = options.icon && typeof options.icon === 'object' ? options.icon : null;
+  const identity = options.identity && typeof options.identity === 'object' ? options.identity : null;
+  const iconStatus = typeof icon?.status === 'string' ? icon.status : 'not_configured';
+  const iconReasonCode = typeof icon?.reasonCode === 'string' ? icon.reasonCode : null;
+
+  const manifest = {
+    schema: BUILD_MANIFEST_SCHEMA,
+    entrypoint: toPosix(relative(outRoot, bundlePath)),
+    assetsManifest: toPosix(relative(outRoot, assetsManifestPath)),
+    executable: executablePath ? toPosix(relative(outRoot, executablePath)) : null,
+    assetMode,
+    runtimeResolver,
+    identity: {
+      name: typeof identity?.name === 'string' ? identity.name : null,
+      version: typeof identity?.version === 'string' ? identity.version : null,
+      windowTitle: typeof identity?.windowTitle === 'string' ? identity.windowTitle : null,
+      executableBaseName: typeof identity?.executableBaseName === 'string' ? identity.executableBaseName : null,
+      executableFileName: typeof identity?.executableFileName === 'string' ? identity.executableFileName : null,
+    },
+    icon: {
+      configuredPath: typeof icon?.configuredPath === 'string' ? icon.configuredPath : null,
+      sourcePath: resolveOptionalRelative(outRoot, icon?.sourcePath),
+      outputPath: resolveOptionalRelative(outRoot, icon?.outputPath),
+      status: iconStatus,
+      reasonCode: iconReasonCode,
+    },
+  };
+
+  const manifestPath = resolve(outRoot, 'build-manifest.json');
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return manifestPath;
+}
+
+function resolveRequiredPath(pathLike, fieldName) {
+  if (typeof pathLike !== 'string' || pathLike.length === 0) {
+    throw new Error(`build contract requires a non-empty "${fieldName}" path.`);
+  }
+  return resolve(pathLike);
+}
+
+function normalizeAssetMode(value) {
+  if (value !== 'embed' && value !== 'sibling') {
+    throw new Error(`unsupported asset mode "${value}" for build contract.`);
+  }
+  return value;
+}
+
+function toPosix(input) {
+  return input.split(sep).join('/');
+}
+
+function resolveOptionalRelative(outRoot, pathLike) {
+  if (typeof pathLike !== 'string' || pathLike.length === 0) {
+    return null;
+  }
+  return toPosix(relative(outRoot, resolve(pathLike)));
+}