@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/replay-runtime.mjs

@@ -0,0 +1,257 @@
+import { resolve } from 'node:path';
+
+import { executeFrame } from './headless-test.mjs';
+import {
+  applySessionState,
+  bootSessionRuntime,
+  exportSessionState,
+} from './session-runtime.mjs';
+
+export const GAME_REPLAY_SCHEMA_VERSION = 'aurajs.game-replay.v1';
+export const GAME_REPLAY_REPORT_SCHEMA_VERSION = 'aurajs.game-replay-report.v1';
+
+export class ReplayError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'ReplayError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+function parseReplayFrames(value, fallback = 1) {
+  if (value == null) return fallback;
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1) {
+    throw new ReplayError('invalid_replay_frames', 'Replay step frames must be a positive integer.');
+  }
+  return numeric;
+}
+
+function normalizeReplayPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new ReplayError('invalid_replay_payload', 'Replay payload must be an object.');
+  }
+  if (payload.schemaVersion !== GAME_REPLAY_SCHEMA_VERSION) {
+    throw new ReplayError(
+      'schema_version_mismatch',
+      `Unsupported replay schema "${payload.schemaVersion}". Expected "${GAME_REPLAY_SCHEMA_VERSION}".`,
+    );
+  }
+  if (!Array.isArray(payload.steps) || payload.steps.length === 0) {
+    throw new ReplayError('invalid_replay_payload', 'Replay payload requires a non-empty steps array.');
+  }
+
+  return {
+    schemaVersion: GAME_REPLAY_SCHEMA_VERSION,
+    seed: payload.seed == null ? null : String(payload.seed),
+    stopOnDivergence: payload.stopOnDivergence !== false,
+    initialState: payload.initialState ?? null,
+    steps: payload.steps.map((step, index) => {
+      if (!step || typeof step !== 'object' || Array.isArray(step)) {
+        throw new ReplayError('invalid_replay_step', `Replay step at index ${index} must be an object.`);
+      }
+      return {
+        label: typeof step.label === 'string' && step.label.trim().length > 0 ? step.label.trim() : null,
+        checkpointId: typeof step.checkpointId === 'string' && step.checkpointId.trim().length > 0 ? step.checkpointId.trim() : null,
+        expectFingerprint: typeof step.expectFingerprint === 'string' && step.expectFingerprint.trim().length > 0
+          ? step.expectFingerprint.trim()
+          : null,
+        frames: parseReplayFrames(step.frames, 1),
+        input: step.input && typeof step.input === 'object' && !Array.isArray(step.input)
+          ? step.input
+          : null,
+      };
+    }),
+  };
+}
+
+function hashReplaySeed(seed) {
+  const text = String(seed || '');
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function createSeededMath(seed) {
+  if (seed == null) return Math;
+  let state = hashReplaySeed(seed);
+  if (state === 0) state = 0x6d2b79f5;
+  const nextRandom = () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const math = Object.create(Math);
+  math.random = nextRandom;
+  return math;
+}
+
+function captureStateOrThrow(runtime, seed, capturedAt = null) {
+  const result = exportSessionState(runtime, {
+    mode: 'headless',
+    seed,
+    capturedAt,
+  });
+  if (!result || typeof result !== 'object' || result.ok !== true || !result.payload) {
+    throw new ReplayError(
+      typeof result?.reasonCode === 'string' ? result.reasonCode : 'replay_state_export_failed',
+      result?.detail
+        ? `Replay state export failed: ${result.detail}`
+        : 'Replay state export failed.',
+      { stateResult: result || null },
+    );
+  }
+  return result.payload;
+}
+
+function buildCheckpoint({ step, stepIndex, runtime, payload, matchedExpectation }) {
+  return {
+    checkpointId: step.checkpointId || null,
+    label: step.label || null,
+    stepIndex,
+    frameIndex: runtime.frameIndex,
+    elapsedSeconds: runtime.elapsedSeconds,
+    fingerprint: payload.export?.fingerprint || null,
+    matchedExpectation,
+  };
+}
+
+export async function runHeadlessReplay(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const replay = normalizeReplayPayload(options.payload);
+  const runtime = await bootSessionRuntime({
+    projectRoot,
+    file: options.file,
+    width: options.width,
+    height: options.height,
+    math: createSeededMath(replay.seed),
+  });
+
+  const inputController = runtime.aura?.input?.__headless;
+  if (!inputController || typeof inputController.applyFrame !== 'function' || typeof inputController.clearFrameTransitions !== 'function') {
+    throw new ReplayError(
+      'replay_input_unavailable',
+      'Headless replay requires the headless input controller.',
+    );
+  }
+
+  let initialStateApplied = false;
+  if (replay.initialState) {
+    const applyResult = applySessionState(runtime, replay.initialState);
+    if (!applyResult || typeof applyResult !== 'object' || applyResult.ok !== true) {
+      throw new ReplayError(
+        typeof applyResult?.reasonCode === 'string' ? applyResult.reasonCode : 'replay_initial_state_apply_failed',
+        applyResult?.detail
+          ? `Replay initial state apply failed: ${applyResult.detail}`
+          : 'Replay initial state apply failed.',
+        { applyResult: applyResult || null },
+      );
+    }
+    initialStateApplied = true;
+  }
+
+  const checkpoints = [];
+  let divergence = null;
+
+  for (let index = 0; index < replay.steps.length; index += 1) {
+    const step = replay.steps[index];
+    if (step.input) {
+      inputController.applyFrame(step.input);
+    } else {
+      inputController.clearFrameTransitions();
+    }
+
+    for (let frame = 0; frame < step.frames; frame += 1) {
+      await executeFrame(runtime.aura, 1 / 60);
+      runtime.frameIndex += 1;
+      runtime.elapsedSeconds += 1 / 60;
+      if (frame < step.frames - 1) {
+        inputController.clearFrameTransitions();
+      }
+    }
+
+    const needsCheckpoint = step.checkpointId || step.expectFingerprint;
+    if (!needsCheckpoint) {
+      inputController.clearFrameTransitions();
+      continue;
+    }
+
+    const payload = captureStateOrThrow(runtime, replay.seed, null);
+    const actualFingerprint = payload.export?.fingerprint || null;
+    const matchedExpectation = step.expectFingerprint == null || step.expectFingerprint === actualFingerprint;
+    checkpoints.push(buildCheckpoint({
+      step,
+      stepIndex: index,
+      runtime,
+      payload,
+      matchedExpectation,
+    }));
+
+    if (!matchedExpectation) {
+      divergence = {
+        stepIndex: index,
+        label: step.label || null,
+        checkpointId: step.checkpointId || null,
+        expectedFingerprint: step.expectFingerprint,
+        actualFingerprint,
+        frameIndex: runtime.frameIndex,
+        elapsedSeconds: runtime.elapsedSeconds,
+      };
+      if (replay.stopOnDivergence) {
+        break;
+      }
+    }
+
+    inputController.clearFrameTransitions();
+  }
+
+  const finalState = captureStateOrThrow(runtime, replay.seed, null);
+  const completed = divergence == null;
+  const report = {
+    schemaVersion: GAME_REPLAY_REPORT_SCHEMA_VERSION,
+    ok: completed,
+    reasonCode: completed ? 'replay_ok' : 'replay_diverged',
+    replaySchemaVersion: GAME_REPLAY_SCHEMA_VERSION,
+    mode: 'headless',
+    projectRoot,
+    entryFile: runtime.entryFile,
+    seed: replay.seed,
+    initialStateApplied,
+    totalSteps: replay.steps.length,
+    executedFrames: runtime.frameIndex,
+    elapsedSeconds: runtime.elapsedSeconds,
+    finalFingerprint: finalState.export?.fingerprint || null,
+    checkpoints,
+    divergence,
+  };
+
+  return {
+    replay,
+    report,
+    finalState,
+    runtime,
+    runtimeSummary: {
+      width: runtime.width,
+      height: runtime.height,
+      framesExecuted: runtime.frameIndex,
+      elapsedSeconds: runtime.elapsedSeconds,
+      bundleOutFile: runtime.bundle.outFile,
+      moduleCount: runtime.bundle.moduleCount,
+      assertionsPassed: runtime.testState.passes,
+      drawCalls: runtime.testState.drawCalls,
+      audioCalls: runtime.testState.audioCalls,
+    },
+  };
+}
+
+export function serializeReplayReport(payload, compact = false) {
+  return compact
+    ? `${JSON.stringify(payload)}\n`
+    : `${JSON.stringify(payload, null, 2)}\n`;
+}

package/src/scaffold/config.mjs

@@ -4,9 +4,11 @@ import { fileURLToPath } from 'node:url';
 const SCAFFOLD_DIR = dirname(fileURLToPath(import.meta.url));
 const CLI_SRC_DIR = resolve(SCAFFOLD_DIR, '..');
 const CLI_PACKAGE = JSON.parse(readFileSync(resolve(CLI_SRC_DIR, '../package.json'), 'utf8'));
+export const CLI_PACKAGE_NAME = CLI_PACKAGE.name;
 const CLI_PACKAGE_VERSION = CLI_PACKAGE.version;
 
 export const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter');
+export const PACKAGED_STARTER_UTILS_DIR = resolve(CLI_SRC_DIR, './helpers/starter-utils');
 
 export const CREATE_TEMPLATE_DIRS = {
   '2d-adventure': resolve(CLI_SRC_DIR, '../templates/create/2d-adventure'),

package/src/scaffold/fs.mjs

@@ -1,3 +1,4 @@
+import { isUtf8 } from 'node:buffer';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
@@ -33,7 +34,13 @@ export function copyTree(src, dest, replacements) {
       continue;
     }
 
-    let content = readFileSync(srcPath, 'utf8');
+    const sourceBytes = readFileSync(srcPath);
+    if (!isUtf8(sourceBytes)) {
+      writeFileSync(destPath, sourceBytes);
+      continue;
+    }
+
+    let content = sourceBytes.toString('utf8');
     for (const [key, value] of Object.entries(replacements)) {
       content = content.replaceAll(`{{${key}}}`, value);
     }

package/src/scaffold/project-docs.mjs

@@ -1,3 +1,5 @@
+import { describeProjectAiGuidance } from '../ai-guidance.mjs';
+
 export function renderProjectReadme({ name, projectTitle, template, templateMetadata }) {
   if (templateMetadata?.runtimeFamily === 'retro') {
     return renderRetroProjectReadme({ name, projectTitle, template, templateMetadata });
@@ -7,6 +9,7 @@ export function renderProjectReadme({ name, projectTitle, template, templateMeta
   const workflowSection = renderTemplateWorkflowSection(templateMetadata);
   const projectMap = renderProjectMapSection(template);
   const generateFilesSection = renderGenerateFilesSection(template);
+  const aiWorkflowSection = renderAiWorkflowSection(template);
   const stateOwnershipSection = renderStateOwnershipSection();
   const continuityOwnershipSection = renderContinuityOwnershipSection();
   const largeAssetSection = renderLargeAssetSection();
@@ -22,7 +25,7 @@ export function renderProjectReadme({ name, projectTitle, template, templateMeta
 
   return `# ${projectTitle}
 
-Scaffolded with \`aura create ${name} --template ${template}\`.
+Scaffolded with \`auramaxx create ${name} --template ${template}\`.
 
 ## Quick Start
 
@@ -35,17 +38,18 @@ Optional commands:
 
 \`\`\`bash
 ${optionalCommands}
-npx aura explain
-npx aura check
+auramaxx explain
+auramaxx check
 \`\`\`
 
 ${template === 'blank' ? '' : 'Press `F1` while the starter is running to toggle the development-only playtest HUD. Use the top scene strip to jump between scenes and the toolbar to record, capture screenshots, restart, pause, or minimize the HUD.\n\n'}
 
 If you are publishing outside the \`@aurajs\` scope, update \`package.json -> name\`
-before the first \`npm run publish\`.
+before the first \`auramaxx publish\`.
 
 ${largeAssetSection}
 ${workflowSection}
+${aiWorkflowSection}
 ${generateFilesSection}
 ${stateOwnershipSection}
 ${continuityOwnershipSection}
@@ -77,6 +81,7 @@ export function renderProjectRunbook({ projectTitle, template, templateMetadata
   const workflowSection = renderTemplateWorkflowSection(templateMetadata);
   const firstThirtyMinutes = renderFirstThirtyMinutesSteps(template);
   const generateFilesSection = renderGenerateFilesSection(template);
+  const aiWorkflowSection = renderAiWorkflowSection(template);
   const stateOwnershipSection = renderStateOwnershipSection();
   const continuityOwnershipSection = renderContinuityOwnershipSection();
   const largeAssetSection = renderLargeAssetSection();
@@ -93,6 +98,7 @@ ${stateOwnershipSection}
 ${continuityOwnershipSection}
 
 ${workflowSection}
+${aiWorkflowSection}
 ${generateFilesSection}
 
 ## First-Hour Implementation Pass
@@ -112,7 +118,7 @@ If any are unavailable at runtime, fail fast and capture the reason code before
 1. \`npm run build\` to emit native/web artifacts.
 1. \`npm run play\` to sanity-check the packaged local wrapper path.
 ${templateMetadata?.optionalModules?.multiplayer === true ? '1. `npm run join -- AURA2P` to join a room-code multiplayer session through the generated wrapper.\n' : ''}1. \`npm run session -- start\` to open a persistent local developer session.
-1. \`npm run publish\` once metadata and binaries are ready.
+1. \`auramaxx publish\` once metadata and binaries are ready.
 1. If you are not publishing under \`@aurajs\`, update \`package.json -> name\` first.
 
 ${largeAssetSection}
@@ -131,13 +137,43 @@ ${steps.map((line) => `1. ${line}`).join('\n')}
 `;
 }
 
+function renderAiWorkflowSection(template) {
+  const aiGuidance = describeProjectAiGuidance({
+    template,
+    starterUtils: template === 'blank'
+      ? null
+      : {
+        available: true,
+        recommendedImportPath: './src/starter-utils/index.js',
+      },
+  });
+
+  const importHint = aiGuidance.recommendedImportPath || aiGuidance.preferredPackageSpecifier || '(none)';
+  const modules = Array.isArray(aiGuidance.recommendedModules) && aiGuidance.recommendedModules.length > 0
+    ? aiGuidance.recommendedModules.map((entry) => `- \`${entry.id}\` via \`${importHint}\``).join('\n')
+    : '- no starter helper lane is preselected; build outward from `src/runtime/`, `scenes/`, and `content/`';
+
+  return `## AI Workflow
+
+- run \`auramaxx explain --json\` before moving files so the current source boundary, starter helper lane, and paved-road guidance stay explicit
+- run \`auramaxx check --json\` after edits when you want machine-readable import and registry validation
+- keep authored gameplay code inside \`src/\`, \`scenes/\`, \`ui/\`, \`prefabs/\`, \`config/\`, and \`content/\`
+- preferred helper import: \`${importHint}\`
+- AI paved road lane: \`${aiGuidance.laneId}\`
+
+Recommended starter modules:
+
+${modules}
+`;
+}
+
 function renderRetroProjectReadme({ name, projectTitle, template, templateMetadata }) {
   const controls = templateMetadata.controls.map((line) => `- ${line}`).join('\n');
   const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
   const workflowSection = renderTemplateWorkflowSection(templateMetadata);
   return `# ${projectTitle}
 
-Scaffolded with \`aura create ${name} --template ${template}\`.
+Scaffolded with \`auramaxx create ${name} --template ${template}\`.
 
 ## Quick Start
 
@@ -156,8 +192,8 @@ npm run retro:explain
 \`\`\`
 
 Aura Retro projects build through the main AuraScript CLI, but they do not use
-the default desktop play/dev wrapper flow. Treat \`aura retro check\` and
-\`aura build --target <retro-target>\` as the primary development loop.
+the default desktop play/dev wrapper flow. Treat \`npm run retro:check\` and
+\`auramaxx build --target <retro-target>\` as the primary development loop.
 
 ${workflowSection}
 ## Template Summary
@@ -225,6 +261,15 @@ export function renderStateOwnershipSection() {
 - \`screenShell\` payloads are only the data passed into HUD, overlay, and modal screens.
 - \`config/\` is for defaults and tuning.
 - \`content/\` is for authored definitions and registries.
+
+Example shared session state:
+
+\`\`\`js
+const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
+if (!runFlags.DID_START) {
+  runFlags.DID_START = true;
+}
+\`\`\`
 `;
 }
 
@@ -240,16 +285,16 @@ export function renderContinuityOwnershipSection() {
 - \`scenes/*.scene.js\` should keep \`sceneState\` JSON-safe when it must survive restore.
 - \`context.getCurrentScenePayload()\` is the read seam for payloads restored through \`sceneFlow\`.
 - saved slots live under \`.aura/state/slots/\` and checkpoints live under \`.aura/state/checkpoints/\`.
-- native dev restore hooks use \`aura dev --restore-slot <name>\` or \`aura dev --restore-checkpoint <name>\`.
+- native dev restore hooks use \`auramaxx dev --restore-slot <name>\` or \`auramaxx dev --restore-checkpoint <name>\`.
 `;
 }
 
 export function renderLargeAssetSection() {
   return `## Publish and Large Assets
 
-- \`npm run publish\` delegates to the engine-owned \`aura publish\` lane.
+- \`auramaxx publish\` is the public publish command inside an AuraJS project.
 - AuraJS measures built asset payload size before publish. The default npm-first threshold is 50 MiB; operators can override it with \`AURA_PUBLISH_ASSET_THRESHOLD_BYTES\`.
-- If the payload is too large, use your own HTTPS host for the heavy assets and run \`aura external-assets generate --public-base-url <url>\`.
+- If the payload is too large, use your own HTTPS host for the heavy assets and run \`auramaxx external-assets generate --public-base-url <url>\`.
 - That command writes \`aura.external-assets.json\` in the project root and stages manifests plus upload records under \`.aura/external-assets/\`.
 - Packaged \`npx <game> play\` and \`join\` hydrate self-hosted assets into a local cache before launch.
 - Cloudflare R2 and S3 are examples only. AuraPM and \`publishv2\` remain preview-only.
@@ -261,16 +306,16 @@ export function renderGenerateFilesSection(template) {
     return `## Generate Files
 
 \`\`\`bash
-npx aura make scene MainMenu
-npx aura make ui-screen PauseMenu
-npx aura make config EnemyTable
-npx aura make content SpawnTable
-npx aura explain
-npx aura check
+auramaxx make scene MainMenu
+auramaxx make ui-screen PauseMenu
+auramaxx make config EnemyTable
+auramaxx make content SpawnTable
+auramaxx explain
+auramaxx check
 \`\`\`
 
 Blank now ships the same authored roots as the other starters. Use the seeded
-files as the reference structure, then grow the project with \`npx aura make\`.
+files as the reference structure, then grow the project with \`auramaxx make\`.
 `;
   }
 
@@ -278,12 +323,12 @@ files as the reference structure, then grow the project with \`npx aura make\`.
     return `## Generate Files
 
 \`\`\`bash
-npx aura make card StrikePlus
-npx aura make enemy JawWorm
-npx aura make relic BurningBlood
-npx aura make encounter Act1Hallway
-npx aura explain
-npx aura check
+auramaxx make card StrikePlus
+auramaxx make enemy JawWorm
+auramaxx make relic BurningBlood
+auramaxx make encounter Act1Hallway
+auramaxx explain
+auramaxx check
 \`\`\`
 `;
   }
@@ -291,12 +336,12 @@ npx aura check
   return `## Generate Files
 
 \`\`\`bash
-npx aura make scene MainMenu
-npx aura make ui-screen PauseMenu
-npx aura make config EnemyTable
-npx aura make content SpawnTable
-npx aura explain
-npx aura check
+auramaxx make scene MainMenu
+auramaxx make ui-screen PauseMenu
+auramaxx make config EnemyTable
+auramaxx make content SpawnTable
+auramaxx explain
+auramaxx check
 \`\`\`
 `;
 }
@@ -309,8 +354,8 @@ export function renderProjectMapSection(template) {
 - \`aura.config.json\` - identity/window/build/modules.
 - \`aura.capabilities.json\` - canonical runtime API declaration for this scaffold.
 - \`RUNBOOK.md\` - first-hour implementation and triage checklist.
-- \`npx aura explain\` - inspect how the current project is wired.
-- \`npx aura check\` - validate authored wiring before runtime.
+- \`auramaxx explain\` - inspect how the current project is wired.
+- \`auramaxx check\` - validate authored wiring before runtime.
 - \`src/runtime/\` - runtime/bootstrap helpers plus the project and scene registries.
 - \`src/runtime/project-registry.js\` - authored source of truth for scenes, screens, prefabs, \`configFiles\`, and \`contentFiles\`.
 - \`src/runtime/scene-flow.js\` - active-scene continuity, stack state, and route payload handoff.
@@ -324,13 +369,13 @@ export function renderProjectMapSection(template) {
 - \`config/\` - defaults and tunables.
 - \`content/\` - authored game definitions, progression payloads, and starter-owned registries.
 - \`content/registries/\` - starter-owned registries and future generator-owned indexes.
-- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes.`;
+- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes. Starter example: \`context.ensureSessionState('runFlags', { DID_START: false })\`.`;
   }
 
   return `- \`src/main.js\` - stable bootstrap seam into the authored project layout.
 - \`src/runtime/\` - runtime/bootstrap helpers plus the project and scene registries.
 - \`src/runtime/project-registry.js\` - authored source of truth for scenes, screens, prefabs, \`configFiles\`, and \`contentFiles\`.
-- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes.
+- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes. Starter example: \`context.ensureSessionState('runFlags', { DID_START: false })\`.
 - \`src/runtime/scene-flow.js\` - active-scene continuity, scene-stack restore ownership, and route payload handoff.
 - \`src/runtime/screen-shell.js\` - HUD, overlay, and modal payload continuity ownership.
 - \`src/runtime/ui-theme.js\` - shared theme presets plus \`appState.ui.preferences\` apply/reset helpers.
@@ -343,7 +388,13 @@ export function renderProjectMapSection(template) {
 - \`config/\` - editable defaults and tuning payloads.
 - \`content/\` - authored definitions, levels, registries, and progression content.
 - \`content/registries/\` - starter-owned registry files for cards, enemies, relics, and encounters.
-- \`src/starter-utils/\` - reusable helpers copied for non-blank templates.
+- \`src/starter-utils/\` - local copies of reusable authored helper modules
+  shipped with AuraJS for non-blank templates. Keep imports local here for
+  starter-facing gameplay code; use the published
+  \`@auraindustry/aurajs/helpers\` lane only when you want the shared
+  package-backed helper surface directly. Run \`auramaxx vendor helpers\` when
+  you want to seed or resync the local helper lane in a project that does not
+  already have it.
 - \`assets/starter/\` - starter asset pack and editable design payloads.
 - \`aura.config.json\` - identity/window/build/modules.
 - \`aura.capabilities.json\` - canonical runtime API declaration for this scaffold.
@@ -355,16 +406,16 @@ export function renderFirstThirtyMinutesSteps(template) {
     return `1. Run \`npm install\` then \`npm run dev\` and confirm the starter loop is playable.
 1. Read \`src/main.js\`, \`src/runtime/app.js\`, \`src/runtime/app-state.js\`, \`scenes/\`, \`config/\`, \`content/\`, and \`docs/design/\` once before adding new structure.
 1. Decide whether your next change belongs in \`appState.session\`, \`appState.ui\`, \`appState.runtime\`, \`sceneState\`, \`config/\`, or \`content/\`, and whether it must survive save or restart continuity.
-1. Run \`npx aura explain\` once so the bootstrap stays obvious before the project grows.
-1. Use \`npx aura make\` when you want more authored files without inventing paths.`;
+1. Run \`auramaxx explain\` once so the bootstrap stays obvious before the project grows.
+1. Use \`auramaxx make\` when you want more authored files without inventing paths.`;
   }
 
   if (template === 'deckbuilder-2d') {
     return `1. Run \`npm install\` then \`npm run dev\` and finish one starter battle end to end.
 1. Read \`content/registries/\`, \`content/cards/\`, \`content/enemies/\`, and \`content/encounters/\` before changing scene flow.
 1. Open \`src/runtime/ui-theme.js\`, \`src/runtime/ui-settings.js\`, and \`src/runtime/ui-forms.js\` before adding pause/settings or form glue of your own.
-1. Generate one extra card or encounter with \`npx aura make\` instead of hand-creating files.
-1. Run \`npx aura explain\` or \`npx aura check\` once so the starter-owned registries stay obvious as the project grows.
+1. Generate one extra card or encounter with \`auramaxx make\` instead of hand-creating files.
+1. Run \`auramaxx explain\` or \`auramaxx check\` once so the starter-owned registries stay obvious as the project grows.
 1. Only then move into battle polish, rewards, or meta-progression.`;
   }
 
@@ -373,9 +424,9 @@ export function renderFirstThirtyMinutesSteps(template) {
 1. Open \`src/runtime/ui-theme.js\`, \`src/runtime/ui-settings.js\`, and \`src/runtime/ui-forms.js\` before inventing starter-local theme, settings, or form plumbing.
 1. Review \`assets/starter/\`, \`config/gameplay/\`, \`content/gameplay/\`, and \`docs/design/\` and rewrite the seed content so it matches your game's nouns, tuning, and milestone goals.
 1. Keep shared state in \`appState.session\` / \`appState.ui\`, keep route payloads in \`sceneFlow\`, and keep scene-only state inside \`sceneState\`.
-1. Run \`npx aura explain\` or \`npx aura check\` when you want a fast map of the authored project wiring.
+1. Run \`auramaxx explain\` or \`auramaxx check\` when you want a fast map of the authored project wiring.
 1. Press \`F1\` in the running starter to open the playtest HUD, jump between authored scenes, and use the compact capture/restart toolbar.
-1. Use \`npx aura make scene MainMenu\` or \`npx aura make ui-screen PauseMenu\` instead of hand-making new authored file paths.`;
+1. Use \`auramaxx make scene MainMenu\` or \`auramaxx make ui-screen PauseMenu\` instead of hand-making new authored file paths.`;
 }
 
 export function renderContentMapDoc({ template }) {
@@ -403,6 +454,15 @@ Template: \`${template}\`
 - \`src/runtime/project-inspector.js\` exposes the live F1 playtest HUD.
 - authored scenes read shared state with \`ensureSessionState\`, \`ensureUiState\`, and \`getCurrentScenePayload()\`.
 
+## Shared State Example
+
+\`\`\`js
+const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
+if (!runFlags.DID_START) {
+  runFlags.DID_START = true;
+}
+\`\`\`
+
 ## Current Starter Inventory
 
 - \`scenes/boot.scene.js\`

package/src/scaffold.mjs

@@ -7,6 +7,7 @@ import {
   CREATE_TEMPLATE_DIRS,
   GITIGNORE_TEMPLATE,
   LEGACY_STARTER_TEMPLATE_DIR,
+  PACKAGED_STARTER_UTILS_DIR,
   PLAY_BIN_TEMPLATE,
   applyTemplateConfigOverrides,
   buildCapabilitiesDeclaration,
@@ -106,6 +107,9 @@ export function scaffoldGame(options) {
   copyTree(templateDir, dest, replacements);
   if (shouldCopyCreateSharedTemplate(normalizedTemplate, templateMetadata) && existsSync(CREATE_SHARED_TEMPLATE_DIR)) {
     copyTree(CREATE_SHARED_TEMPLATE_DIR, dest, replacements);
+    if (existsSync(PACKAGED_STARTER_UTILS_DIR)) {
+      copyTree(PACKAGED_STARTER_UTILS_DIR, join(dest, 'src', 'starter-utils'), replacements);
+    }
   }
 
   mkdirSync(join(dest, 'assets'), { recursive: true });

package/src/session-runtime.mjs

@@ -74,8 +74,10 @@ export async function bootSessionRuntime(options = {}) {
   });
 
   const testState = createSessionTestState();
-  const aura = createHeadlessAura({ width, height, testState });
-  const context = vm.createContext(createRuntimeContext(aura, testState));
+  const aura = createHeadlessAura({ width, height, testState, projectRoot });
+  const context = vm.createContext(createRuntimeContext(aura, testState, {
+    math: options.math,
+  }));
 
   const source = readFileSync(bundle.outFile, 'utf8');
   const script = new vm.Script(source, {
@@ -318,4 +320,3 @@ export async function exportSessionInspect(runtime, options = {}) {
     };
   }
 }
-