@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/perf-benchmark.mjs

@@ -217,6 +217,359 @@ export const DEFAULT_PERF_SCENES = [
       };
     `,
   },
+  {
+    id: 'ui_composition_surface_stress',
+    frames: 360,
+    source: `
+      let panelTarget = null;
+      let elapsed = 0;
+
+      aura.setup = function () {
+        panelTarget = aura.draw2d.createRenderTarget(128, 64);
+        aura.draw2d.resizeRenderTarget(panelTarget, 160, 72);
+      };
+
+      aura.update = function (dt) {
+        elapsed += dt;
+      };
+
+      aura.draw = function () {
+        aura.draw2d.clear(6, 8, 14);
+
+        aura.draw2d.withRenderTarget(panelTarget, () => {
+          aura.draw2d.clear(0, 0, 0, 0);
+          aura.draw2d.pushClipRect(4, 4, 152, 64);
+          aura.draw2d.rect(0, 0, 160, 72, aura.rgba(0.12, 0.16, 0.22, 0.92));
+          aura.draw2d.rect(10, 36, 112, 12, aura.rgba(0.35, 0.82, 1, 0.72));
+          aura.draw2d.text('ENERGY 72', 14, 18, { size: 12, color: aura.colors.white });
+          aura.draw2d.popClipRect();
+        });
+
+        aura.draw2d.pushClipRect(0, 0, aura.window.width, aura.window.height);
+        aura.draw2d.tileSprite(panelTarget, 0, 0, aura.window.width, aura.window.height, {
+          tileScaleX: 2,
+          tileScaleY: 2,
+          tileOffsetX: elapsed * 80,
+          tileOffsetY: elapsed * 40,
+          tint: aura.rgba(0.14, 0.18, 0.24, 0.6),
+        });
+        aura.draw2d.popClipRect();
+
+        for (let i = 0; i < 3; i += 1) {
+          const x = 24 + (i * 174);
+          const y = 28 + Math.sin((elapsed * 1.4) + (i * 0.35)) * 8;
+          aura.draw2d.pushClipRect(x, y, 168, 84);
+          aura.draw2d.sprite(panelTarget, x, y, { width: 168, height: 84 });
+          aura.draw2d.nineSlice(panelTarget, x + 8, y + 8, 152, 68, {
+            slice: 4,
+            tint: aura.rgba(0.2, 0.24, 0.32, 0.78),
+          });
+          aura.draw2d.tileSprite(panelTarget, x + 14, y + 50, 120, 10, {
+            tileScaleX: 0.25,
+            tileScaleY: 0.6,
+            tileOffsetX: (elapsed * 120) + (i * 6),
+            tint: aura.rgba(1, 0.82, 0.35, 0.72),
+          });
+          aura.draw2d.popClipRect();
+        }
+      };
+    `,
+  },
+  {
+    id: 'ui_masking_compositor_fx_stress',
+    frames: 360,
+    source: `
+      let maskTarget = null;
+      let stageBase = null;
+      let stageFx = null;
+      let stageFinal = null;
+      let elapsed = 0;
+      let frameIndex = 0;
+      let selectedItemId = 'sword';
+      let menuVolume = 5;
+      let pendingScroll = false;
+      let exportedGraph = false;
+
+      const hasRetainedUi =
+        !!aura.ui
+        && typeof aura.ui.beginContainer === 'function'
+        && typeof aura.ui.region === 'function'
+        && typeof aura.ui.selectOption === 'function'
+        && typeof aura.ui.endContainer === 'function'
+        && typeof aura.ui.getSelectionState === 'function'
+        && typeof aura.ui.getScrollState === 'function'
+        && typeof aura.ui.scrollBy === 'function'
+        && typeof aura.ui.activate === 'function';
+      const hasMask = typeof aura.draw2d.withMask === 'function';
+      const hasOrderedCapture = typeof aura.draw2d.withRenderTargets === 'function';
+      const hasNamedCompositor =
+        typeof aura.draw2d.runCompositorGraph === 'function'
+        && typeof aura.draw2d.exportRenderTarget === 'function';
+      const hasSpriteFx = typeof aura.draw2d.spriteFx === 'function';
+      const hasAnalyticMask = hasNamedCompositor;
+
+      function drawFallbackRows(originX, originY) {
+        const rows = [
+          'INVENTORY',
+          'SWORD',
+          'SHIELD',
+          'POTION',
+        ];
+        for (let i = 0; i < rows.length; i += 1) {
+          const isHeader = i === 0;
+          const rowY = originY + (i * 22);
+          aura.draw2d.rectFill(
+            originX,
+            rowY,
+            184,
+            isHeader ? 18 : 18,
+            isHeader ? aura.rgba(0.08, 0.1, 0.16, 0.96) : aura.rgba(0.16, 0.2, 0.28, 0.9),
+          );
+          aura.draw2d.text(rows[i], originX + 8, rowY + 4, {
+            size: isHeader ? 12 : 11,
+            color: aura.colors.white,
+          });
+        }
+      }
+
+      function drawRetainedWidgets(originX, originY) {
+        if (!hasRetainedUi) {
+          drawFallbackRows(originX, originY);
+          return;
+        }
+
+        if (pendingScroll) {
+          aura.ui.scrollBy('frontier-menu', 0, 14);
+          pendingScroll = false;
+        }
+
+        aura.ui.beginContainer({
+          id: 'frontier-menu',
+          x: originX,
+          y: originY,
+          width: 188,
+          height: 52,
+          direction: 'vertical',
+          gap: 4,
+          padding: 2,
+        });
+        const header = aura.ui.region('header', {
+          width: 180,
+          height: 12,
+        });
+        const sword = aura.ui.selectOption('sword', {
+          label: 'Sword',
+          value: 'sword',
+          width: 180,
+          height: 12,
+          selected: selectedItemId === 'sword',
+        });
+        const shield = aura.ui.selectOption('shield', {
+          label: 'Shield',
+          value: 'shield',
+          width: 180,
+          height: 12,
+          selected: selectedItemId === 'shield',
+        });
+        const potion = aura.ui.selectOption('potion', {
+          label: 'Potion',
+          value: 'potion',
+          width: 180,
+          height: 12,
+          selected: selectedItemId === 'potion',
+        });
+        if ((frameIndex % 72) === 0) {
+          aura.ui.activate(selectedItemId);
+        }
+        aura.ui.endContainer();
+
+        const selection = aura.ui.getSelectionState('frontier-menu');
+        const widgets = [
+          { label: 'INVENTORY', x: header.x, y: header.y, width: header.width, height: header.height, header: true },
+          sword,
+          shield,
+          potion,
+        ];
+        if (selection && selection.selectedRegionId) {
+          selectedItemId = selection.selectedRegionId;
+        }
+
+        for (let i = 0; i < widgets.length; i += 1) {
+          const widget = widgets[i];
+          if (!widget || widget.ok !== true) continue;
+          const isHeader = widget.header === true;
+          aura.draw2d.rectFill(
+            widget.x,
+            widget.y,
+            widget.width,
+            widget.height,
+            isHeader ? aura.rgba(0.08, 0.1, 0.16, 0.9) : aura.rgba(0.14, 0.18, 0.26, 0.84),
+          );
+          aura.draw2d.text(widget.label || widget.itemId || 'widget', widget.x + 8, widget.y + 6, {
+            size: isHeader ? 12 : 11,
+            color: aura.colors.white,
+          });
+        }
+      }
+
+      function stageBaseDraw() {
+        aura.draw2d.clear(0, 0, 0, 0);
+        aura.draw2d.rectFill(0, 0, 224, 128, aura.rgba(0.1, 0.14, 0.22, 0.96));
+        aura.draw2d.nineSlice(maskTarget, 8, 8, 208, 112, {
+          slice: 6,
+          tint: aura.rgba(0.18, 0.22, 0.3, 0.76),
+        });
+        aura.draw2d.tileSprite(maskTarget, 14, 84, 196, 18, {
+          tileScaleX: 0.55,
+          tileScaleY: 0.45,
+          tileOffsetX: elapsed * 72,
+          tileOffsetY: elapsed * 20,
+          tint: aura.rgba(0.94, 0.78, 0.34, 0.6),
+        });
+        drawRetainedWidgets(18, 16);
+        aura.draw2d.text('VOL ' + menuVolume, 146, 96, {
+          size: 11,
+          color: aura.colors.white,
+        });
+      }
+
+      function stageFxDraw(source) {
+        aura.draw2d.clear(0, 0, 0, 0);
+        aura.draw2d.sprite(source, 0, 0, { width: 224, height: 128 });
+        aura.draw2d.tileSprite(source, 8, 92, 188, 18, {
+          tileScaleX: 0.45,
+          tileScaleY: 0.55,
+          tileOffsetX: elapsed * 96,
+          tileOffsetY: elapsed * 28,
+          tint: aura.rgba(0.18, 0.72, 0.98, 0.36),
+        });
+        if (hasSpriteFx) {
+          aura.draw2d.spriteFx(source, 18, 16, {
+            width: 180,
+            height: 84,
+            shadow: { offsetX: 3, offsetY: 4 },
+            outline: {
+              thickness: 1,
+              color: aura.rgba(0.98, 0.88, 0.48, 0.82),
+            },
+          });
+        } else {
+          aura.draw2d.sprite(source, 18, 16, { width: 180, height: 84 });
+        }
+      }
+
+      function stageFinalDraw(source) {
+        aura.draw2d.clear(0, 0, 0, 0);
+        aura.draw2d.sprite(source, 0, 0, { width: 224, height: 128 });
+        aura.draw2d.rectFill(16, 14, 192, 18, aura.rgba(0.07, 0.1, 0.16, 0.84));
+        aura.draw2d.text('UI FRONTIER', 24, 20, { size: 12, color: aura.colors.white });
+        aura.draw2d.text('FRAME ' + frameIndex, 132, 20, { size: 11, color: aura.colors.white });
+      }
+
+      function drawMaskedCard(source, x, y, width, height) {
+        const drawSurface = () => {
+          aura.draw2d.sprite(source, x, y, { width, height });
+          if (hasSpriteFx) {
+            aura.draw2d.spriteFx(source, x + 18, y + 58, {
+              width: 56,
+              height: 30,
+              shadow: { offsetX: 2, offsetY: 3 },
+              outline: {
+                thickness: 1,
+                color: aura.rgba(0.95, 0.82, 0.36, 0.78),
+              },
+            });
+          }
+        };
+
+        if (hasMask && hasAnalyticMask) {
+          aura.draw2d.withMask({ type: 'analytic', shape: 'circle', feather: 0.18 }, x + 10, y + 8, width - 20, height - 16, drawSurface);
+          return;
+        }
+
+        if (hasMask) {
+          aura.draw2d.withMask(maskTarget, x + 10, y + 8, width - 20, height - 16, drawSurface);
+          return;
+        }
+
+        aura.draw2d.pushClipRect(x + 10, y + 8, width - 20, height - 16);
+        drawSurface();
+        aura.draw2d.popClipRect();
+      }
+
+      aura.setup = function () {
+        maskTarget = aura.draw2d.createRenderTarget(96, 96);
+        stageBase = aura.draw2d.createRenderTarget(224, 128);
+        stageFx = aura.draw2d.createRenderTarget(224, 128);
+        stageFinal = aura.draw2d.createRenderTarget(224, 128);
+      };
+
+      aura.update = function (dt) {
+        elapsed += dt;
+        frameIndex += 1;
+        if ((frameIndex % 20) === 0) {
+          menuVolume = (menuVolume + 1) % 11;
+        }
+        if ((frameIndex % 36) === 0) {
+          pendingScroll = true;
+        }
+        if ((frameIndex % 48) === 0) {
+          selectedItemId = selectedItemId === 'sword'
+            ? 'shield'
+            : (selectedItemId === 'shield' ? 'potion' : 'sword');
+        }
+      };
+
+      aura.draw = function () {
+        aura.draw2d.clear(7, 10, 16);
+
+        aura.draw2d.withRenderTarget(maskTarget, () => {
+          aura.draw2d.clear(0, 0, 0, 0);
+          aura.draw2d.circleFill(48, 48, 28, aura.rgba(1, 1, 1, 1));
+          aura.draw2d.rectFill(18, 18, 60, 48, aura.rgba(1, 1, 1, 0.8));
+        });
+
+        let composedSource = stageFinal;
+
+        if (hasNamedCompositor) {
+          const graph = aura.draw2d.runCompositorGraph('perf-frontier', [
+            { id: 'base', target: stageBase, draw: stageBaseDraw },
+            {
+              id: 'fx',
+              target: stageFx,
+              draw: () => stageFxDraw({ type: 'compositorStage', graph: 'perf-frontier', stage: 'base' }),
+            },
+            {
+              id: 'final',
+              target: stageFinal,
+              draw: () => stageFinalDraw({ type: 'compositorStage', graph: 'perf-frontier', stage: 'fx' }),
+            },
+          ]);
+
+          if (graph && graph.ok === true && Array.isArray(graph.stages) && graph.stages.length === 3) {
+            composedSource = graph.stages[2];
+            if (!exportedGraph) {
+              aura.draw2d.exportRenderTarget(graph.stages[2], 'tmp/ui-frontier-perf.png');
+              exportedGraph = true;
+            }
+          }
+        } else if (hasOrderedCapture) {
+          aura.draw2d.withRenderTargets([
+            { target: stageBase, draw: stageBaseDraw },
+            { target: stageFx, draw: () => stageFxDraw(stageBase) },
+            { target: stageFinal, draw: () => stageFinalDraw(stageFx) },
+          ]);
+        }
+
+        for (let i = 0; i < 4; i += 1) {
+          const x = 18 + (i * 156);
+          const y = 22 + Math.sin((elapsed * 1.25) + (i * 0.45)) * 10;
+          drawMaskedCard(composedSource, x, y, 148, 100);
+          aura.draw2d.text('P' + i, x + 10, y + 78, { size: 10, color: aura.colors.white });
+        }
+      };
+    `,
+  },
 ];
 
 function mean(values) {

package/src/postinstall.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 import { readFileSync } from 'node:fs';
-import { resolveAndCacheHostBinary, HostBinaryResolutionError } from './host-binary.mjs';
+import { ensureHostBinaryAvailable, HostBinaryResolutionError } from './host-binary.mjs';
 
-function main() {
+async function main() {
   const pkgPath = new URL('../package.json', import.meta.url);
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
 
   try {
-    const result = resolveAndCacheHostBinary({ packageJsonVersion: pkg.version });
+    const result = await ensureHostBinaryAvailable({ packageJsonVersion: pkg.version });
     console.log(`[aurajs] host binary ready (${result.target}): ${result.binaryPath}`);
     if (result.cacheStatus !== 'hit') {
       console.log(`[aurajs] cache ${result.cacheStatus}: ${result.cacheDir}`);
@@ -16,11 +16,11 @@ function main() {
   } catch (error) {
     if (error instanceof HostBinaryResolutionError) {
       console.error(`[aurajs] postinstall warning: ${error.message}`);
-      console.error('[aurajs] run "npm install" again after optionalDependencies are available.');
+      console.error('[aurajs] the host binary will be downloaded on first successful networked install or first CLI run.');
       process.exit(0);
     }
     throw error;
   }
 }
 
-main();
+await main();

package/src/prefabs/index.mjs

@@ -0,0 +1,34 @@
+import { createSceneComposition } from '../scene-composition/index.mjs';
+import {
+  SCENE_PREFAB_SCHEMA,
+  buildSceneCompositionFromPrefab,
+  createScenePrefab,
+  deserializeScenePrefab,
+  normalizeScenePrefab,
+  readScenePrefabFile,
+  serializeScenePrefab,
+  writeScenePrefabFile,
+} from './scene-serialization.mjs';
+
+export {
+  SCENE_PREFAB_SCHEMA,
+  buildSceneCompositionFromPrefab,
+  createScenePrefab,
+  deserializeScenePrefab,
+  normalizeScenePrefab,
+  readScenePrefabFile,
+  serializeScenePrefab,
+  writeScenePrefabFile,
+};
+
+export function instantiateScenePrefab(aura, prefab, overrides = {}) {
+  const normalizedPrefab = normalizeScenePrefab(prefab);
+  const sceneConfig = buildSceneCompositionFromPrefab(normalizedPrefab, overrides);
+  const scene = createSceneComposition(aura, sceneConfig);
+  if (normalizedPrefab.defaults.autoMount !== false && overrides.autoMount !== false) {
+    scene.mount();
+  }
+  return scene;
+}
+
+export default instantiateScenePrefab;

package/src/prefabs/scene-serialization.mjs

@@ -0,0 +1,184 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { writeCanonicalJsonFile } from '../build-contract.mjs';
+import {
+  SCENE_COMPOSITION_SCHEMA,
+  mergeSceneCompositionConfig,
+  normalizeSceneCompositionConfig,
+  sanitizeSceneCompositionForSerialization,
+} from '../scene-composition/index.mjs';
+
+export const SCENE_PREFAB_SCHEMA = 'aurajs.scene-prefab.v1';
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneValue(value) {
+  return value == null ? value : structuredClone(value);
+}
+
+function normalizeString(value, fallback = null) {
+  if (typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function normalizeVec3(value, fallback = { x: 0, y: 0, z: 0 }) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    x: Number.isFinite(Number(source.x)) ? Number(source.x) : fallback.x,
+    y: Number.isFinite(Number(source.y)) ? Number(source.y) : fallback.y,
+    z: Number.isFinite(Number(source.z)) ? Number(source.z) : fallback.z,
+  };
+}
+
+function looksLikeSceneComposition(value) {
+  if (!isPlainObject(value)) return false;
+  return value.schema === SCENE_COMPOSITION_SCHEMA
+    || Object.prototype.hasOwnProperty.call(value, 'camera')
+    || Object.prototype.hasOwnProperty.call(value, 'nodes')
+    || Object.prototype.hasOwnProperty.call(value, 'meshes')
+    || Object.prototype.hasOwnProperty.call(value, 'avatars');
+}
+
+export function normalizeScenePrefab(prefab = {}) {
+  if (!isPlainObject(prefab)) {
+    throw new TypeError('Scene prefab must be an object.');
+  }
+
+  const sourceScene = looksLikeSceneComposition(prefab.scene)
+    ? prefab.scene
+    : (looksLikeSceneComposition(prefab.composition) ? prefab.composition : prefab);
+
+  return {
+    schema: SCENE_PREFAB_SCHEMA,
+    kind: 'scene-prefab',
+    id: normalizeString(prefab.id, 'scene-prefab'),
+    name: normalizeString(prefab.name, normalizeString(prefab.id, null)),
+    version: Number.isInteger(prefab.version) && prefab.version > 0 ? prefab.version : 1,
+    tags: Array.isArray(prefab.tags)
+      ? [...new Set(prefab.tags.map((entry) => normalizeString(entry, null)).filter(Boolean))]
+        .sort((left, right) => left.localeCompare(right))
+      : [],
+    metadata: isPlainObject(prefab.metadata) ? cloneValue(prefab.metadata) : {},
+    defaults: {
+      autoMount: prefab.defaults?.autoMount !== false,
+    },
+    scene: sanitizeSceneCompositionForSerialization(sourceScene),
+  };
+}
+
+export function createScenePrefab(prefab = {}) {
+  return normalizeScenePrefab(prefab);
+}
+
+export function serializeScenePrefab(prefab, options = {}) {
+  const normalized = normalizeScenePrefab(prefab);
+  return options.pretty === false
+    ? `${JSON.stringify(normalized)}\n`
+    : `${JSON.stringify(normalized, null, 2)}\n`;
+}
+
+export function deserializeScenePrefab(value) {
+  if (typeof value === 'string') {
+    return normalizeScenePrefab(JSON.parse(value));
+  }
+  return normalizeScenePrefab(value);
+}
+
+export function buildSceneCompositionFromPrefab(prefab, overrides = {}) {
+  const normalizedPrefab = normalizeScenePrefab(prefab);
+  const overrideSource = isPlainObject(overrides) ? overrides : {};
+  const sceneOverride = looksLikeSceneComposition(overrideSource.scene)
+    ? overrideSource.scene
+    : (looksLikeSceneComposition(overrideSource) ? overrideSource : {});
+  const baseScene = {
+    ...normalizedPrefab.scene,
+    name: normalizedPrefab.scene.name || normalizedPrefab.name || normalizedPrefab.id,
+  };
+
+  let scene = mergeSceneCompositionConfig(baseScene, sceneOverride);
+  const origin = normalizeVec3(overrideSource.origin, { x: 0, y: 0, z: 0 });
+  const idPrefix = normalizeString(overrideSource.idPrefix, null);
+
+  if (origin.x !== 0 || origin.y !== 0 || origin.z !== 0) {
+    scene = offsetSceneComposition(scene, origin);
+  }
+  if (idPrefix) {
+    scene = prefixSceneCompositionIds(scene, idPrefix);
+  }
+
+  return scene;
+}
+
+export function writeScenePrefabFile(filePath, prefab) {
+  const absolutePath = resolve(filePath);
+  const normalized = normalizeScenePrefab(prefab);
+  writeCanonicalJsonFile(absolutePath, normalized);
+  return normalized;
+}
+
+export function readScenePrefabFile(filePath) {
+  return deserializeScenePrefab(readFileSync(resolve(filePath), 'utf8'));
+}
+
+function offsetSceneComposition(scene, offset) {
+  const normalized = normalizeSceneCompositionConfig(scene);
+  return {
+    ...normalized,
+    nodes: normalized.nodes.map((entry) => ({
+      ...entry,
+      transform: {
+        ...entry.transform,
+        position: {
+          x: entry.transform.position.x + offset.x,
+          y: entry.transform.position.y + offset.y,
+          z: entry.transform.position.z + offset.z,
+        },
+      },
+    })),
+  };
+}
+
+function prefixSceneCompositionIds(scene, prefix) {
+  const normalized = normalizeSceneCompositionConfig(scene);
+  const prefixId = (value) => (value ? `${prefix}/${value}` : value);
+
+  return {
+    ...normalized,
+    name: normalized.name ? `${prefix}/${normalized.name}` : normalized.name,
+    nodes: normalized.nodes.map((entry) => ({
+      ...entry,
+      id: prefixId(entry.id),
+      parentId: prefixId(entry.parentId),
+    })),
+    meshes: normalized.meshes.map((entry) => ({
+      ...entry,
+      id: prefixId(entry.id),
+      nodeId: prefixId(entry.nodeId),
+    })),
+    billboards: normalized.billboards.map((entry) => ({
+      ...entry,
+      id: prefixId(entry.id),
+      nodeId: prefixId(entry.nodeId),
+    })),
+    avatars: normalized.avatars.map((entry) => ({
+      ...entry,
+      id: prefixId(entry.id),
+      nodeId: prefixId(entry.nodeId),
+    })),
+    triggers: normalized.triggers.map((entry) => ({
+      ...entry,
+      id: prefixId(entry.id),
+      nodeId: prefixId(entry.nodeId),
+      watch: entry.watch.map((watcher) => ({
+        ...watcher,
+        id: prefixId(watcher.id),
+        avatarId: prefixId(watcher.avatarId),
+        nodeId: prefixId(watcher.nodeId),
+      })),
+    })),
+  };
+}