External Project Workspace and Installed Editor/Runtime Contract v1

Status: Planning only; no implementation or compatibility promise exists.

This roadmap defines the next independent PixelBullet product question: how an external project could use an installed BulletSketch/editor and runtime without being inside the monorepo source graph. It is separate from the graphics roadmap and from Arena feature development.

Goals

Version 1 should define and prove:

1. A versioned external project manifest. The manifest identifies its schema, project identity, required editor/runtime range, entry surfaces, and declared content roots without embedding host-specific absolute paths.
2. Project roots and logical aliases. @assets, @shared, and any additional logical roots have one documented resolution order, ownership rule, and collision policy. External projects do not redefine engine serialization tokens.
3. Source, catalog, and cache ownership. The contract distinguishes authored source, imported/cataloged data, derived caches, invalidation inputs, trust boundaries, and portable cleanup/rebuild behavior.
4. An editor/runtime version handshake. BulletSketch, the generic runner, and project data exchange explicit compatibility identities and produce actionable mismatch diagnostics before execution.
5. An installed bundle and sample project. One supported installed layout includes the editor, matching generic runtime, required support assets, and a minimal external sample that works outside the PixelBullet checkout.
6. A validation, package, and run contract. The design names the commands and closure checks that validate, package, open, preview, and run an external project without relying on workspace runfiles.
7. A compatibility and support posture. Schema, content, tool/runtime, and package compatibility each have an owner, supported range, migration policy, diagnostics, and removal conditions.

Explicit Non-Goals

Version 1 does not promise a frozen C++ SDK, stable ABI, binary plugin ABI, arbitrary third-party native plugins, or indefinite compatibility. Public headers remain curated source-level workspace seams until a separate consumer and support decision says otherwise.

Arena may serve as a first-party compatibility fixture for selected seams, but it is not the external-project format, a parity roadmap, or the reason to export all product internals.

Proposed Evidence Stages

• Contract design: approve manifest, root, identity, handshake, and support semantics with no implementation implied.
• Installed proof: open and run the sample project from a copied installed bundle and arbitrary working directory with exact asset closure.
• Mismatch and migration proof: exercise supported/unsupported versions, corrupt catalogs, cache invalidation, moved projects, and actionable errors.
• Adoption decision: name the intended consumer and maintenance commitment before treating the installed contract as supported distribution.

The roadmap is complete only when those artifacts and acceptance gates are specified by an implementation proposal; this document does not authorize that implementation.