@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/scaffold/project-docs.mjs

@@ -0,0 +1,438 @@
+export function renderProjectReadme({ name, projectTitle, template, templateMetadata }) {
+  if (templateMetadata?.runtimeFamily === 'retro') {
+    return 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);
+  const projectMap = renderProjectMapSection(template);
+  const generateFilesSection = renderGenerateFilesSection(template);
+  const stateOwnershipSection = renderStateOwnershipSection();
+  const continuityOwnershipSection = renderContinuityOwnershipSection();
+  const largeAssetSection = renderLargeAssetSection();
+
+  const optionalCommands = [
+    'npm run build',
+    'npm run play',
+    templateMetadata?.optionalModules?.multiplayer === true ? 'npm run join -- AURA2P' : null,
+    'npm run publish',
+    'npm run session -- start',
+  ].filter(Boolean).join('\n');
+
+  return `# ${projectTitle}
+
+Scaffolded with \`aura create ${name} --template ${template}\`.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+Optional commands:
+
+\`\`\`bash
+${optionalCommands}
+npx aura explain
+npx aura 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\`.
+
+${largeAssetSection}
+${workflowSection}
+${generateFilesSection}
+${stateOwnershipSection}
+${continuityOwnershipSection}
+
+## Template Summary
+
+${templateMetadata.summary}
+
+## Controls
+
+${controls}
+
+## Project Map
+
+${projectMap}
+
+## First Edits
+
+${firstEdits}
+`;
+}
+
+export function renderProjectRunbook({ projectTitle, template, templateMetadata }) {
+  if (templateMetadata?.runtimeFamily === 'retro') {
+    return renderRetroProjectRunbook({ projectTitle, template, templateMetadata });
+  }
+  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
+  const requiredApis = templateMetadata.requiredApis.map((entry) => `- \`${entry}\``).join('\n');
+  const workflowSection = renderTemplateWorkflowSection(templateMetadata);
+  const firstThirtyMinutes = renderFirstThirtyMinutesSteps(template);
+  const generateFilesSection = renderGenerateFilesSection(template);
+  const stateOwnershipSection = renderStateOwnershipSection();
+  const continuityOwnershipSection = renderContinuityOwnershipSection();
+  const largeAssetSection = renderLargeAssetSection();
+
+  return `# ${projectTitle} Runbook
+
+Template: \`${template}\`
+
+## First 30 Minutes
+
+${firstThirtyMinutes}
+
+${stateOwnershipSection}
+${continuityOwnershipSection}
+
+${workflowSection}
+${generateFilesSection}
+
+## First-Hour Implementation Pass
+
+${firstEdits}
+
+## Capability Contract
+
+The scaffold assumes the runtime APIs below:
+
+${requiredApis}
+
+If any are unavailable at runtime, fail fast and capture the reason code before adding fallback behavior.
+
+## Build + Share
+
+1. \`npm run build\` to emit native/web artifacts.
+1. \`npm run play\` to launch through the generated game CLI wrapper.
+${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. If you are not publishing under \`@aurajs\`, update \`package.json -> name\` first.
+
+${largeAssetSection}
+`;
+}
+
+export function renderTemplateWorkflowSection(templateMetadata) {
+  const title = String(templateMetadata?.workflowTitle || '').trim();
+  const steps = Array.isArray(templateMetadata?.workflowSteps)
+    ? templateMetadata.workflowSteps.filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+    : [];
+  if (!title || steps.length === 0) return '';
+  return `## ${title}
+
+${steps.map((line) => `1. ${line}`).join('\n')}
+`;
+}
+
+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}\`.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run retro:check
+npm run build:gbc
+\`\`\`
+
+Optional build targets:
+
+\`\`\`bash
+npm run build:gb
+npm run build:gba
+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.
+
+${workflowSection}
+## Template Summary
+
+${templateMetadata.summary}
+
+## Controls
+
+${controls}
+
+## First Edits
+
+${firstEdits}
+`;
+}
+
+function renderRetroProjectRunbook({ projectTitle, template, templateMetadata }) {
+  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
+  const requiredApis = templateMetadata.requiredApis.map((entry) => `- \`${entry}\``).join('\n');
+  const workflowSection = renderTemplateWorkflowSection(templateMetadata);
+  return `# ${projectTitle} Runbook
+
+Template: \`${template}\`
+
+## First 30 Minutes
+
+1. Run \`npm run retro:check\` from the project root and make sure the initial template is clean.
+1. Build the default color target with \`npm run build:gbc\`.
+1. If you want the stricter mono profile, rerun with \`npm run build:gb\`.
+1. Keep edits inside \`src/main.js\` and \`assets/retro/assets.json\` until the core loop feels right.
+
+${workflowSection}
+## First-Hour Implementation Pass
+
+${firstEdits}
+
+## Capability Contract
+
+The current template assumes the retro-safe API surface below:
+
+${requiredApis}
+
+## Build Targets
+
+1. \`npm run retro:check\` validates the current project against the shipped retro checks.
+1. \`npm run build:gbc\` emits the default Game Boy Color ROM artifact bundle.
+1. \`npm run build:gb\` reruns the stricter original Game Boy profile.
+1. \`npm run build:gba\` emits a \`.gba\` ROM plus the Retro IR, asset manifest, and generated preview source bundle.
+`;
+}
+
+export function renderStateOwnershipSection() {
+  return `## State Ownership TL;DR
+
+- \`aura\` is the runtime API.
+- \`src/runtime/app-state.js\` owns shared mutable \`appState\` and normalizes the \`session\`, \`ui\`, and \`runtime\` buckets.
+- \`context.ensureSessionState(...)\` / \`context.getSessionState(...)\` own shared gameplay/session state in \`appState.session\`.
+- \`context.ensureUiState(...)\` / \`context.getUiState(...)\` own shared UI/presentation state in \`appState.ui\`.
+- \`src/runtime/ui-theme.js\` owns the canonical \`appState.ui.preferences\` seed plus theme apply/reset helpers.
+- \`src/runtime/ui-settings.js\` packages the retained settings and action-strip helpers used by starter pause/options flows.
+- \`src/runtime/ui-forms.js\` packages retained text-field and menu-list helpers used by starter profile, save-slot, and modal flows.
+- \`appState.runtime\` is engine-owned scene/screen-shell metadata and should stay runtime-driven.
+- \`sceneState\` is local mutable state owned by one scene while it is active.
+- \`context.getCurrentScenePayload()\` reads the route-style payload used to enter the current scene.
+- \`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.
+`;
+}
+
+export function renderContinuityOwnershipSection() {
+  return `## Continuity Ownership TL;DR
+
+- \`src/runtime/app-state.js\` owns shared save/reload continuity for \`appState.session\`, \`appState.ui\`, and \`appState.runtime\`.
+- \`src/runtime/scene-flow.js\` owns active-scene stack continuity and route payload restart handoff.
+- \`src/runtime/screen-shell.js\` owns HUD, overlay, and modal payload continuity.
+- \`src/runtime/ui-theme.js\` owns the scaffolded theme/preferences seam under \`appState.ui.preferences\`.
+- \`src/runtime/ui-settings.js\` owns the shared retained settings helpers reused by starter pause/options flows.
+- \`src/runtime/ui-forms.js\` owns the shared retained form and menu helpers reused by starter modal flows.
+- \`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>\`.
+`;
+}
+
+export function renderLargeAssetSection() {
+  return `## Publish and Large Assets
+
+- \`npm run publish\` delegates to the engine-owned \`aura publish\` lane.
+- 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>\`.
+- 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.
+`;
+}
+
+export function renderGenerateFilesSection(template) {
+  if (template === 'blank') {
+    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
+\`\`\`
+
+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\`.
+`;
+  }
+
+  if (template === 'deckbuilder-2d') {
+    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
+\`\`\`
+`;
+  }
+
+  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
+\`\`\`
+`;
+}
+
+export function renderProjectMapSection(template) {
+  if (template === 'blank') {
+    return `- \`src/main.js\` - the authored-project bootstrap into the runtime app.
+- \`assets/\` - imported art, audio, and starter notes.
+- \`bin/\` - generated wrapper entrypoint.
+- \`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.
+- \`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.
+- \`src/runtime/screen-shell.js\` - HUD, overlay, and modal payload continuity.
+- \`src/runtime/ui-theme.js\` - shared theme presets plus \`appState.ui.preferences\` apply/reset helpers.
+- \`src/runtime/ui-settings.js\` - retained settings and action-strip helpers reused by starter pause/settings screens.
+- \`src/runtime/ui-forms.js\` - retained text-field and menu-list helpers reused by starter form/menu screens.
+- \`scenes/\` - top-level authored scenes.
+- \`prefabs/\` - reusable gameplay blueprints and spawn descriptors.
+- \`ui/\` - authored HUD and screen layout modules.
+- \`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.`;
+  }
+
+  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/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.
+- \`src/runtime/ui-settings.js\` - retained settings and action-strip helpers for pause/options screens.
+- \`src/runtime/ui-forms.js\` - retained text-field and menu-list helpers for profile, save-slot, and modal workflows.
+- \`src/runtime/project-inspector.js\` - F1 playtest HUD for scene jumps, capture controls, and authored-runtime visibility.
+- \`scenes/\` - top-level authored scenes.
+- \`prefabs/\` - reusable gameplay blueprints and spawn descriptors.
+- \`ui/\` - authored HUD and screen layout modules.
+- \`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.
+- \`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.
+- \`RUNBOOK.md\` - first-hour implementation and triage checklist.`;
+}
+
+export function renderFirstThirtyMinutesSteps(template) {
+  if (template === 'blank') {
+    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.`;
+  }
+
+  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. Only then move into battle polish, rewards, or meta-progression.`;
+  }
+
+  return `1. Run \`npm install\` then \`npm run dev\` and confirm the starter loop is playable.
+1. Read \`src/main.js\`, \`src/runtime/\`, and \`scenes/\` once end-to-end before moving code around.
+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. 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.`;
+}
+
+export function renderContentMapDoc({ template }) {
+  return `# Content Map
+
+Template: \`${template}\`
+
+## Authored Roots
+
+- \`scenes/\` owns top-level app and gameplay flow.
+- \`prefabs/\` owns reusable game object blueprints.
+- \`ui/\` owns HUD and full-screen UI modules.
+- \`config/gameplay/\` owns tunable gameplay payloads.
+- \`content/gameplay/\` owns authored progression and encounter payloads.
+- \`content/registries/\` owns starter and generator registries.
+- \`src/runtime/\` owns bootstrap and registry adapter code.
+- \`src/runtime/project-registry.js\` is the authored source of truth for scenes, screens, prefabs, \`configFiles\`, and \`contentFiles\`.
+- \`src/runtime/app-state.js\` owns shared \`appState.session\`, \`appState.ui\`, and \`appState.runtime\`.
+- \`src/runtime/scene-flow.js\` owns active-scene continuity and route payload handoff.
+- \`src/runtime/screen-shell.js\` owns HUD, overlay, and modal payload continuity.
+- \`src/runtime/ui-theme.js\` owns shared theme presets and \`appState.ui.preferences\`.
+- \`src/runtime/ui-settings.js\` owns retained settings and action-strip helpers for pause/options flows.
+- \`src/runtime/ui-forms.js\` owns retained text-field and menu-list helpers for starter form/menu flows.
+- \`src/runtime/scene-registry.js\` adapts authored scene registration for runtime use.
+- \`src/runtime/project-inspector.js\` exposes the live F1 playtest HUD.
+- authored scenes read shared state with \`ensureSessionState\`, \`ensureUiState\`, and \`getCurrentScenePayload()\`.
+
+## Current Starter Inventory
+
+- \`scenes/boot.scene.js\`
+- \`scenes/gameplay.scene.js\`
+- \`prefabs/player.prefab.js\`
+- \`ui/hud.screen.js\`
+- \`ui/settings.screen.js\` when the starter ships retained settings flow
+- \`config/gameplay/game.config.json\`
+- \`src/runtime/project-registry.js\`
+- \`src/runtime/project-inspector.js\`
+`;
+}
+
+export function renderGamePillarsDoc({ projectTitle, templateMetadata }) {
+  return `# Game Pillars
+
+## Project
+
+- Title: ${projectTitle}
+- Starter summary: ${templateMetadata.summary}
+
+## Pillars
+
+1. Tight core loop with fast iteration on tuning values.
+1. Clear ownership between \`appState.session/ui/runtime\`, \`sceneState\`, route/UI payloads, config, and content.
+1. Plain-JS files that stay easy to edit with agents and code review.
+
+## First Questions
+
+- What should the player accomplish in the first 60 seconds?
+- Which starter constant should become config first?
+- Which authored file should become the team's daily home base?
+`;
+}