[DX] Ship a one-command starter and compile/run every canonical example #142

Parent: #126
Related: #48, #74

Problem

The README requires users to understand Perry, Rust, native libraries, and wasm-pack, but does not provide one canonical create/build/run path. Several examples have drifted manifests or native-library permissions, native examples use blocking loops that do not translate to web, and compilation is not enforced as a matrix. A simple engine that cannot run its first example simply is not simple.

Outcome

A one-command starter and a compile/run-tested example matrix for native and web, with one lifecycle model and no undocumented manifest edits.

Starter experience

Provide a supported flow equivalent to:

bloom new my-game
cd my-game
bloom run
bloom run --web
bloom build --release --target <target>

The exact CLI/package-runner names may differ, but a new user should not need the engine repository, manual Rust commands, or knowledge of native-library allowlists for the hello-scene path.

The template must include:

• pinned compatible Bloom/Perry versions;
• correct native-library permissions/configuration;
• one source entry with init/update/draw/cleanup lifecycle;
• asset folder and import example;
• hot-reload/dev instructions where supported;
• clear native/web target errors with missing-tool remediation.

Lifecycle

Define one public game loop abstraction used by canonical examples:

• native may drive it from the platform loop;
• web schedules via browser animation frames and never blocks;
• pause/focus/resize/device-loss semantics are documented;
• fixed vs variable update behavior is explicit;
• immediate-mode raylib-style code remains concise.

Do not maintain separate game logic for native and web just to enter the loop.

Example policy

Classify examples:

• canonical: small, documented, compiled on every PR, runtime-smoked where possible;
• feature/stress: compiled in full lane, run in scheduled/hardware lane as appropriate;
• historical/experimental: explicitly labeled and excluded with a reason.

Fix manifests/imports/stale APIs in canonical examples. Ensure pong uses edge-triggered pause semantics and does not demonstrate an accidental toggle-every-frame bug.

Acceptance criteria

• A clean machine following documented prerequisites can create and render the starter natively with one command after dependency install.
• The same starter renders in a browser with one command and no source changes.
• Every canonical example compiles in CI against the repository packages and correct Perry version.
• Native and web runtime smoke capture a known frame/pixel and fail on startup trap; Web: Bloom WASM functions trap with 'unreachable' after FFI bridge fix (#73) #74's class cannot pass compilation-only checks.
• Example manifests contain required permissions/config, with schema/validation preventing drift.
• README's first-run path is self-contained and tested as code/commands in CI.
• Error messages distinguish missing compiler/toolchain, package mismatch, asset error, unsupported adapter, and runtime engine failure.

Likely files

• README and target docs
• examples/*/package.json, canonical example sources
• src/core/ game-loop surface and platform adapters
• native/web/build.sh/web glue as applicable
• new CLI/template package or scripts
• CI example/browser jobs

Non-goals

• A full graphical editor.
• Hiding all platform SDK installation requirements.
• Keeping broken examples in the canonical matrix.

Dependencies

• Coordinate generated template manifests with [API] Generate the FFI surface from one schema and remove pointer-only APIs #141.
• Browser runtime acceptance depends on resolving Web: Bloom WASM functions trap with 'unreachable' after FFI bridge fix (#73) #74.