@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/state-dev-reload.mjs

@@ -19,6 +19,9 @@ export function prepareDevStateRestoreEntry({
     projectRoot: resolvedProjectRoot,
     kind: artifactKind,
     name: artifactName,
+    exportDefaults: {
+      mode: 'native',
+    },
   });
 
   if (artifact.envelope.stateSchemaVersion !== GAME_STATE_SCHEMA_VERSION) {
@@ -54,14 +57,82 @@ export function prepareDevStateRestoreEntry({
   };
 }
 
+export function prepareDevStateRestorePayloadEntry({
+  projectRoot,
+  entryFile,
+  payload,
+  reasonCode = 'dev_live_state_restore',
+  label = 'live',
+}) {
+  const resolvedProjectRoot = resolve(projectRoot || process.cwd());
+  const resolvedEntryFile = resolve(resolvedProjectRoot, entryFile || 'src/main.js');
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Live dev-state restore payload must be an object.');
+  }
+  if (payload.schemaVersion !== GAME_STATE_SCHEMA_VERSION) {
+    throw new Error(
+      `Live dev-state restore payload uses schema "${payload.schemaVersion}", expected "${GAME_STATE_SCHEMA_VERSION}".`,
+    );
+  }
+
+  const generatedDir = resolve(resolvedProjectRoot, 'src', '.aurajs-generated');
+  mkdirSync(generatedDir, { recursive: true });
+
+  const safeLabel = String(label || 'live')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .slice(0, 48) || 'live';
+  const generatedFile = resolve(generatedDir, `dev-state-restore-${safeLabel}.js`);
+  const relativeImport = normalizeImportSpecifier(dirname(generatedFile), resolvedEntryFile);
+  const wrapperSource = buildDevStateRestoreWrapperSource({
+    entryImport: relativeImport,
+    payload,
+    artifact: {
+      kind: 'live-session',
+      artifactVersion: null,
+      name: safeLabel,
+      path: relative(resolvedProjectRoot, generatedFile).split(sep).join('/'),
+      stateSchemaVersion: GAME_STATE_SCHEMA_VERSION,
+      payloadFingerprint: payload?.export?.fingerprint || null,
+      migration: null,
+      reasonCode,
+    },
+  });
+
+  const previous = tryReadFile(generatedFile);
+  if (previous !== wrapperSource) {
+    writeFileSync(generatedFile, wrapperSource, 'utf8');
+  }
+
+  return {
+    entryFile: relative(resolvedProjectRoot, generatedFile).split(sep).join('/'),
+    wrapperPath: generatedFile,
+    artifact: {
+      kind: 'live-session',
+      artifactVersion: null,
+      name: safeLabel,
+      path: relative(resolvedProjectRoot, generatedFile).split(sep).join('/'),
+      stateSchemaVersion: GAME_STATE_SCHEMA_VERSION,
+      payloadFingerprint: payload?.export?.fingerprint || null,
+      migration: null,
+      reasonCode,
+    },
+  };
+}
+
 export function buildDevStateRestoreWrapperSource({ entryImport, payload, artifact }) {
   const bootstrapSource = buildStateRestoreRuntimeBootstrapSource();
   const metadata = {
     kind: artifact.kind,
+    artifactVersion: artifact.artifactVersion ?? null,
     name: artifact.name,
     path: artifact.path,
     stateSchemaVersion: artifact.stateSchemaVersion,
     payloadFingerprint: artifact.payloadFingerprint,
+    migration: artifact.migration || null,
+    reasonCode: artifact.reasonCode || null,
   };
 
   return [
@@ -76,26 +147,52 @@ export function buildDevStateRestoreWrapperSource({ entryImport, payload, artifa
     '  if (!stateNs || typeof stateNs.apply !== "function") {',
     '    throw new Error("[aurajs] dev restore failed: aura.state.apply is unavailable");',
     '  }',
+    '  if (aura && typeof aura === "object") {',
+    '    aura.__aurajsPendingDevRestore = { ...__aurajsRestoreMeta };',
+    '  }',
     '  const result = stateNs.apply(__aurajsRestorePayload);',
     '  if (!result || result.ok !== true) {',
     '    const reasonCode = result && typeof result.reasonCode === "string"',
     '      ? result.reasonCode',
     '      : "state_apply_failed";',
+    '    if (aura && typeof aura === "object") {',
+    '      aura.__aurajsDevRestore = {',
+    '        kind: __aurajsRestoreMeta.kind,',
+    '        artifactVersion: __aurajsRestoreMeta.artifactVersion || null,',
+    '        name: __aurajsRestoreMeta.name,',
+    '        path: __aurajsRestoreMeta.path,',
+    '        stateSchemaVersion: __aurajsRestoreMeta.stateSchemaVersion || null,',
+    '        reasonCode,',
+    '        detail: result && typeof result === "object" ? result.detail || null : null,',
+    '        payloadFingerprint: __aurajsRestoreMeta.payloadFingerprint || null,',
+    '        migration: __aurajsRestoreMeta.migration || null,',
+    '        continuity: result && typeof result === "object" ? result.continuity || null : null,',
+    '        ok: false,',
+    '      };',
+    '      delete aura.__aurajsPendingDevRestore;',
+    '    }',
     '    throw new Error(`[aurajs] dev restore failed (${__aurajsRestoreMeta.kind}:${__aurajsRestoreMeta.name}): ${reasonCode}`);',
     '  }',
-    '  return result;',
-    '}',
+  '  return result;',
+  '}',
     'aura.setup = function (...args) {',
     '  const setupResult = __aurajsOriginalSetup ? __aurajsOriginalSetup.apply(this, args) : undefined;',
     '  const restoreResult = __aurajsApplyRestorePayload();',
     '  if (aura && typeof aura === "object") {',
     '    aura.__aurajsDevRestore = {',
     '      kind: __aurajsRestoreMeta.kind,',
+    '      artifactVersion: __aurajsRestoreMeta.artifactVersion || null,',
     '      name: __aurajsRestoreMeta.name,',
     '      path: __aurajsRestoreMeta.path,',
+    '      stateSchemaVersion: __aurajsRestoreMeta.stateSchemaVersion || null,',
     '      reasonCode: restoreResult.reasonCode || null,',
+    '      detail: restoreResult.detail || null,',
     '      payloadFingerprint: __aurajsRestoreMeta.payloadFingerprint || null,',
+    '      migration: __aurajsRestoreMeta.migration || null,',
+    '      continuity: restoreResult.continuity || null,',
+    '      ok: restoreResult.ok === true,',
     '    };',
+    '    delete aura.__aurajsPendingDevRestore;',
     '  }',
     '  return setupResult;',
     '};',

package/src/terminal-ui.mjs

@@ -0,0 +1,245 @@
+import readline from 'node:readline';
+
+const START_BANNER_QUOTES = [
+  'ready to auramaxx and mog prompt peasants?',
+  'you are perfect. never give up your aura',
+  'why jestermaxx when you can auramaxx?',
+  'lock tf in, the aura farm is live.',
+  'we are so back. aura at all-time highs.',
+  'negative motion detected. deploy tera-aura.',
+  'delulu? no. pre-success manifestation engine.',
+  'doomers offline, builders online.',
+  'your aura just hit legendary rarity.',
+  'brainrot but make it productive.',
+  'stack wins, stack aura, stack peace.',
+  'this session is sponsored by unstoppable motion.',
+  'if plan A fails, we auramaxx harder.',
+  'zero cope, pure glow-up execution.',
+  'cooked? nah. we are perfectly seasoned.',
+  'straight gas, no brakes, no bad vibes.',
+  'today forecast: 100% chance of aura gains.',
+  'touch grass, then auramaxx.',
+  'say no to digital slops. say yes to auramaxx.',
+  'if the world goes dark can i still auramaxx with you?',
+  'its me, AI. you are absolutely right. i want to auramaxx as well.',
+];
+
+export const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  fgAccent: '\x1b[38;5;154m',
+  fgWhite: '\x1b[97m',
+  fgGray: '\x1b[90m',
+};
+
+const USE_COLOR = process.stdout.isTTY
+  && !process.env.NO_COLOR
+  && process.env.CI !== 'true'
+  && process.env.TERM !== 'dumb';
+const BANNER_WIDTH = 62;
+
+function wrapText(text, width) {
+  if (text.length <= width) return [text];
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [''];
+  const lines = [];
+  let line = '';
+  for (const word of words) {
+    const next = line ? `${line} ${word}` : word;
+    if (next.length <= width) {
+      line = next;
+      continue;
+    }
+    if (line) lines.push(line);
+    if (word.length <= width) {
+      line = word;
+      continue;
+    }
+    for (let index = 0; index < word.length; index += width) {
+      lines.push(word.slice(index, index + width));
+    }
+    line = '';
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+function getBannerQuote() {
+  const forced = process.env.AURA_START_BANNER_QUOTE_INDEX;
+  if (forced) {
+    const forcedIndex = Number.parseInt(forced, 10);
+    if (Number.isFinite(forcedIndex)) {
+      return START_BANNER_QUOTES[Math.abs(forcedIndex) % START_BANNER_QUOTES.length];
+    }
+  }
+  return START_BANNER_QUOTES[Math.floor(Math.random() * START_BANNER_QUOTES.length)];
+}
+
+export function paint(text, ...codes) {
+  if (!USE_COLOR) return text;
+  return `${codes.join('')}${text}${ANSI.reset}`;
+}
+
+export function canPromptInteractively() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && typeof process.stdin.setRawMode === 'function');
+}
+
+export function printBanner(subtitle = '') {
+  const sub = String(subtitle || '').trim().toUpperCase();
+  const pipe = paint('|', ANSI.fgGray);
+  const logoPipe = paint('|', ANSI.fgGray);
+  const stripe = (value) => paint(value, ANSI.bold);
+  const logoTop = paint('.', ANSI.fgGray) + paint('----------', ANSI.dim) + paint('.', ANSI.fgGray);
+  const logoBottom = paint("'", ANSI.fgGray) + paint('----------', ANSI.dim) + paint("'", ANSI.fgGray);
+
+  console.log('');
+  console.log(`  ${paint('.-', ANSI.fgGray)}${paint(' '.repeat(BANNER_WIDTH - 4), ANSI.dim)}${paint('-.', ANSI.fgGray)}`);
+  console.log(`  ${pipe}   ${logoTop}${' '.repeat(BANNER_WIDTH - 19)}${pipe}`);
+  console.log(`  ${pipe}   ${logoPipe}${stripe('\\\\')}  ${stripe('\\\\')}  ${stripe('\\\\')}${logoPipe}    ${paint('A U R A', ANSI.bold)}${' '.repeat(BANNER_WIDTH - 30)}${pipe}`);
+  console.log(`  ${pipe}   ${logoPipe}${stripe('\\\\')}  ${stripe('\\\\')}  ${stripe('\\\\')}${logoPipe}    ${paint('A U R A J S', ANSI.dim)}${' '.repeat(BANNER_WIDTH - 35)}${pipe}`);
+  console.log(`  ${pipe}   ${logoPipe}${stripe('\\\\')}  ${stripe('\\\\')}  ${stripe('\\\\')}${logoPipe}    ${sub ? paint(sub, ANSI.fgAccent) : ''}${' '.repeat(Math.max(0, BANNER_WIDTH - 23 - sub.length))}${pipe}`);
+  console.log(`  ${pipe}   ${logoBottom}${' '.repeat(BANNER_WIDTH - 19)}${pipe}`);
+  console.log(`  ${paint("'-", ANSI.fgGray)}${paint(' '.repeat(BANNER_WIDTH - 4), ANSI.dim)}${paint("-'", ANSI.fgGray)}`);
+  for (const line of wrapText(getBannerQuote(), BANNER_WIDTH - 2)) {
+    console.log(`  ${paint(line, ANSI.fgWhite, ANSI.italic)}`);
+  }
+  console.log('');
+}
+
+export function printSection(title, subtitle = '') {
+  console.log('');
+  console.log(`  ${'- '.repeat(Math.floor(BANNER_WIDTH / 2))}`);
+  console.log(`  ${paint(`[ ${String(title || '').toUpperCase()} ]`, ANSI.bold)}`);
+  if (subtitle) {
+    console.log(`  ${paint(subtitle, ANSI.dim)}`);
+  }
+  console.log('');
+}
+
+function renderSelectLines(message, options, selectedIndex, defaultValue) {
+  const lines = [
+    message,
+    paint('  Use up/down arrows and Enter to confirm.', ANSI.dim),
+  ];
+
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    const suffix = defaultValue === option.value ? ' [default]' : '';
+    if (index === selectedIndex) {
+      lines.push(`  ${paint('//', ANSI.fgAccent, ANSI.bold)} ${paint(option.label + suffix, ANSI.bold)}`);
+    } else {
+      lines.push(`     ${paint(option.label + suffix, ANSI.dim)}`);
+    }
+  }
+
+  return lines;
+}
+
+export async function promptSelect(message, options, defaultValue) {
+  if (!Array.isArray(options) || options.length === 0) {
+    throw new Error('promptSelect requires at least one option.');
+  }
+  if (!canPromptInteractively()) {
+    return defaultValue || options[0].value;
+  }
+
+  return new Promise((resolvePrompt, rejectPrompt) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const defaultIndex = Math.max(0, options.findIndex((option) => option.value === defaultValue));
+    const previousRawMode = stdin.isRaw ?? false;
+    let selectedIndex = defaultIndex;
+    let renderedLines = 0;
+    let settled = false;
+
+    const cleanup = () => {
+      if (settled) return;
+      settled = true;
+      stdin.removeListener('data', onData);
+      stdin.removeListener('error', onError);
+      if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(previousRawMode);
+      }
+      stdin.pause();
+    };
+
+    const render = () => {
+      const lines = renderSelectLines(message, options, selectedIndex, defaultValue);
+      if (renderedLines > 0) {
+        stdout.write(`\u001b[${renderedLines}A`);
+      }
+      for (const line of lines) {
+        stdout.write('\u001b[2K');
+        stdout.write(`${line}\n`);
+      }
+      renderedLines = lines.length;
+    };
+
+    const onError = (error) => {
+      cleanup();
+      rejectPrompt(error);
+    };
+
+    const onData = (chunk) => {
+      const input = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      let delta = 0;
+
+      for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        if (char === '\u0003') {
+          cleanup();
+          stdout.write('\n');
+          process.exit(1);
+        }
+        if (char === '\r' || char === '\n') {
+          cleanup();
+          stdout.write('\n');
+          resolvePrompt(options[selectedIndex].value);
+          return;
+        }
+        if (input.startsWith('\u001b[A', index)) {
+          delta -= 1;
+          index += 2;
+          continue;
+        }
+        if (input.startsWith('\u001b[B', index)) {
+          delta += 1;
+          index += 2;
+          continue;
+        }
+      }
+
+      if (delta !== 0) {
+        selectedIndex = (selectedIndex + delta + options.length) % options.length;
+        render();
+      }
+    };
+
+    try {
+      if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+      }
+      stdin.resume();
+      stdin.on('data', onData);
+      stdin.on('error', onError);
+      render();
+    } catch (error) {
+      onError(error);
+    }
+  });
+}
+
+export async function promptInput(label) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(`${label}: `, (answer) => {
+      rl.close();
+      resolve(String(answer || '').trim());
+    });
+  });
+}

package/src/web-conformance.mjs

@@ -0,0 +1,219 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = resolve(fileURLToPath(new URL('../../../../..', import.meta.url)));
+const DEFAULT_TEST_FILE = './packages/aurascript/src/cli/test/build-contract.test.mjs';
+
+export const DEFAULT_WEB_SMOKE_CASES = Object.freeze([
+  Object.freeze({
+    id: 'web-supported-browser-surface-2d',
+    bucket: 'supported',
+    expectation: 'supported',
+    title: 'browser loader installs the committed 2d surface',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader installs browser-backed aura surface for 2d examples',
+    examples: [],
+  }),
+  Object.freeze({
+    id: 'web-supported-render-2d-proof-example',
+    bucket: 'supported',
+    expectation: 'supported',
+    title: 'web-render-2d-proof runs on the committed advanced draw2d browser floor',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader browser smoke: web-render-2d-proof runs on the committed advanced draw2d browser floor',
+    examples: ['examples/web-render-2d-proof'],
+  }),
+  Object.freeze({
+    id: 'web-partial-pokemon-style-example',
+    bucket: 'partial',
+    expectation: 'partial',
+    title: 'pokemon-style runs on the current browser-backed subset',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader browser smoke: pokemon-style runs on the supported 2d subset with input and resize evidence',
+    examples: ['examples/pokemon-style'],
+  }),
+  Object.freeze({
+    id: 'web-supported-starter-3d-example',
+    bucket: 'supported',
+    expectation: 'supported',
+    title: 'starter-3d runs on the committed browser 3d floor',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader browser smoke: starter-3d runs on the committed browser 3d floor',
+    examples: ['examples/starter-3d'],
+  }),
+  Object.freeze({
+    id: 'web-unsupported-multiplayer-examples',
+    bucket: 'unsupported',
+    expectation: 'unsupported',
+    title: 'multiplayer examples fail before setup with stable capability diagnostics',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader browser smoke: multiplayer examples fail before setup with stable capability diagnostics',
+    examples: ['examples/multiplayer-room-client', 'examples/multiplayer-room-host'],
+  }),
+  Object.freeze({
+    id: 'web-unsupported-advanced-3d-example',
+    bucket: 'unsupported',
+    expectation: 'unsupported',
+    title: 'advanced 3d examples outside the committed browser floor fail before setup with stable capability diagnostics',
+    file: DEFAULT_TEST_FILE,
+    testName: 'web loader browser smoke: advanced 3d examples still fail before setup with stable capability diagnostics',
+    examples: ['examples/custom-shader-material-proof'],
+  }),
+]);
+
+export class WebConformanceSuiteError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'WebConformanceSuiteError';
+    this.details = details;
+  }
+}
+
+function escapeRegExp(value) {
+  return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function tailLines(value, maxLines = 20) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  return text.split(/\r?\n/).slice(-maxLines).join('\n');
+}
+
+function summarizeBucket(cases, bucket) {
+  const matches = cases.filter((entry) => entry.bucket === bucket);
+  return {
+    total: matches.length,
+    passed: matches.filter((entry) => entry.status === 'passed').length,
+    failed: matches.filter((entry) => entry.status === 'failed').length,
+  };
+}
+
+async function runWebSmokeCase({ cwd, caseDef }) {
+  const args = [
+    '--test',
+    '--test-name-pattern',
+    `^${escapeRegExp(caseDef.testName)}$`,
+    caseDef.file,
+  ];
+
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, args, {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on('error', (error) => {
+      rejectPromise(error);
+    });
+
+    child.on('close', (code, signal) => {
+      resolvePromise({
+        code: Number.isInteger(code) ? code : 1,
+        signal: signal || null,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+export async function runWebConformanceSuite(options = {}) {
+  const startedAt = Date.now();
+  const cwd = resolve(options.cwd || repoRoot);
+  const reportPath = resolve(options.reportPath || cwd, '.aura/web-conformance/report.json');
+  const cases = Array.isArray(options.cases) && options.cases.length > 0
+    ? options.cases
+    : DEFAULT_WEB_SMOKE_CASES;
+  const runner = typeof options.runner === 'function' ? options.runner : runWebSmokeCase;
+  const results = [];
+
+  mkdirSync(dirname(reportPath), { recursive: true });
+
+  for (const caseDef of cases) {
+    const caseStartedAt = Date.now();
+    const execution = await runner({ cwd, caseDef });
+    const durationMs = Date.now() - caseStartedAt;
+    const passed = execution.code === 0;
+
+    results.push({
+      id: caseDef.id,
+      title: caseDef.title,
+      bucket: caseDef.bucket,
+      expectation: caseDef.expectation,
+      file: caseDef.file,
+      testName: caseDef.testName,
+      examples: Array.isArray(caseDef.examples) ? caseDef.examples : [],
+      status: passed ? 'passed' : 'failed',
+      durationMs,
+      stdoutTail: tailLines(execution.stdout),
+      stderrTail: tailLines(execution.stderr),
+      error: passed
+        ? null
+        : {
+          message: `Web smoke case failed: ${caseDef.id}`,
+          exitCode: execution.code,
+          signal: execution.signal,
+        },
+    });
+  }
+
+  const durationMs = Date.now() - startedAt;
+  const summary = {
+    total: results.length,
+    passed: results.filter((entry) => entry.status === 'passed').length,
+    failed: results.filter((entry) => entry.status === 'failed').length,
+    durationMs,
+    byMode: {
+      web: {
+        total: results.length,
+        passed: results.filter((entry) => entry.status === 'passed').length,
+        failed: results.filter((entry) => entry.status === 'failed').length,
+        durationMs,
+      },
+    },
+    byBucket: {
+      supported: summarizeBucket(results, 'supported'),
+      partial: summarizeBucket(results, 'partial'),
+      unsupported: summarizeBucket(results, 'unsupported'),
+    },
+  };
+
+  const report = {
+    schemaVersion: 'aurajs.web-conformance-report.v1',
+    generatedAt: new Date().toISOString(),
+    mode: 'web',
+    cwd,
+    reportPath,
+    summary,
+    cases: results,
+  };
+
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+  if (summary.failed > 0) {
+    throw new WebConformanceSuiteError(
+      `Web conformance failed for ${summary.failed}/${summary.total} browser smoke cases.`,
+      {
+        reportPath,
+        failedCases: results.filter((entry) => entry.status === 'failed'),
+      },
+    );
+  }
+
+  return report;
+}

package/templates/create/2d/config/gameplay/shooter.config.js

@@ -0,0 +1,26 @@
+export const SHOOTER_CONFIG = Object.freeze({
+  playerWidth: 34,
+  playerHeight: 26,
+  playerSpeed: 420,
+  bulletWidth: 6,
+  bulletHeight: 14,
+  bulletSpeed: 640,
+  shootCooldownSeconds: 0.14,
+  playerStartOffsetY: 70,
+  betweenWaveDelaySeconds: 1.0,
+});
+
+export const SHOOTER_WAVES = Object.freeze([
+  Object.freeze({ maxSpawns: 9, spawnEvery: 0.62, archetype: 'scout', speedScale: 1.0 }),
+  Object.freeze({ maxSpawns: 10, spawnEvery: 0.56, archetype: 'striker', speedScale: 1.06 }),
+  Object.freeze({ maxSpawns: 8, spawnEvery: 0.74, archetype: 'tank', speedScale: 1.02 }),
+  Object.freeze({ maxSpawns: 12, spawnEvery: 0.48, archetype: null, speedScale: 1.12 }),
+]);
+
+export const SHOOTER_TEXT = Object.freeze({
+  started: '{{PROJECT_TITLE}} started (2D shooter template)',
+  controls: 'Move: Arrows/WASD  Fire: Space/Z',
+  gameOverTitle: 'GAME OVER',
+  gameOverPrompt: 'Press Enter to restart',
+  waveDone: 'Done',
+});

package/templates/create/2d/content/gameplay/waves.json

@@ -0,0 +1,26 @@
+{
+  "schema": "aurajs.wave-plan.v1",
+  "waves": [
+    {
+      "id": "intro",
+      "maxSpawns": 9,
+      "spawnEvery": 0.62,
+      "archetype": "scout",
+      "speedScale": 1
+    },
+    {
+      "id": "pressure",
+      "maxSpawns": 10,
+      "spawnEvery": 0.56,
+      "archetype": "striker",
+      "speedScale": 1.06
+    },
+    {
+      "id": "anchor",
+      "maxSpawns": 8,
+      "spawnEvery": 0.74,
+      "archetype": "tank",
+      "speedScale": 1.02
+    }
+  ]
+}

package/templates/create/2d/content/registries/.gitkeep

@@ -0,0 +1 @@
+

package/templates/create/2d/docs/design/.gitkeep

@@ -0,0 +1 @@
+

package/templates/create/2d/docs/design/loop.md

@@ -0,0 +1,5 @@
+# 2D Shooter Loop
+
+1. Survive the wave set, clear the arena, and keep the score-and-lives loop readable.
+1. Keep tuning in `config/gameplay/shooter.config.js`, authored wave payloads in `content/gameplay/waves.json`, and reusable combat pieces in `prefabs/`.
+1. Extend from here with enemy families, weapon rules, and HUD beats before layering on heavier meta systems.