Blueprint Lifecycle, Testing Standards & Reverse-Syncing

Multi-blueprint workspace decomposition, singular test harness manifests (.airbpt), dev log telemetry assertions, and air bp sync reverse-syncing.
Published: 7/10/2026

Aircada Blueprints (.airbp) represent portable, encapsulated building blocks of interactive 3D logic, React UI components, and option datasets.

1. Multi-Blueprint Workspace Decomposition

When building a comprehensive product configurator with multiple distinct building blocks (e.g. Sizing Selector, Finish Swatches, Strap Picker, Monogram Engraving), author separate modular source files in src/ and export co-located public blueprints in blueprints/*.airbp. Never lump granular components into a single monolithic file.

2. Singular Internal Test Harness (.airbpt)

Each project workspace MUST contain EXACTLY ONE singular test harness blueprint manifest (scripts/testing/<name>-test.airbpt) that extends the primary blueprint and encapsulates automated assertions for all sub-components.

3. Strict SDK Decoupling in CLI Test Scripts

Node CLI testing scripts (scripts/testing/test-blueprint.ts, query-dev-logs.ts, verify-dev-logs.ts) must NEVER import @aircada/spec or @aircada/react SDK types directly. They must remain pure Node.js scripts querying structured telemetry logs in .aircada/logging/dev-logs/.

4. Reverse-Syncing to AIR_Library (air bp sync)

Executing 'air bp sync' in the project workspace copies modified files directly into AIR_Library/src/examples/<category>/<name>/, triggering dual-pass catalog compilation and embedding the project into the global knowledge graph.

  • ### 1. Multi-Blueprint Workspace Decomposition
  • When building a comprehensive product configurator with multiple distinct building blocks (e.g. Sizing Selector, Finish Swatches, Strap Picker, Monogram Engraving), author separate modular source files in src/ and export co-located public blueprints in blueprints/*.airbp. Never lump granular components into a single monolithic file.
  • ### 2. Singular Internal Test Harness Manifest (.airbpt)
  • Each project workspace MUST contain EXACTLY ONE singular test harness blueprint manifest (scripts/testing/<name>-test.airbpt) that extends the primary blueprint and encapsulates automated assertions for all sub-components.
  • ### 3. Applying Library Blueprints to Existing Projects (air bp apply)
  • To apply a library blueprint foundation to an existing project workspace, execute 'air bp apply <blueprintId> -d . -o -v --no-install'. This automatically deploys source files into src/systems/, src/operators/, or src/components/, merges package.json dependencies, and updates air.config.json. If CLI is unavailable, agents use aircada-mcp getblueprintby_id to inspect and write the blueprint templates directly.
  • ### 4. Contextual Blueprint Adaptation
  • After applying blueprint foundations, agents adapt the code to match project-specific store keys (src/schemas/<Name>Schemas.ts), mesh slot abstractions (slot*mesh), and dataset IDs according to notesForUsage in the planner architecture.
  • ### 5. Node CLI Test Script Decoupling
  • Node CLI testing scripts (scripts/testing/test-blueprint.ts, query-dev-logs.ts, verify-dev-logs.ts) must NEVER import @aircada/spec or @aircada/react SDK types directly. They must remain pure Node.js scripts querying structured telemetry logs in .aircada/logging/dev-logs/.
  • ### 6. Reverse-Syncing to AIR_Library (air bp sync)
  • Executing 'air bp sync' copies modified blueprint files directly to AIR_Library/src/examples/<category>/<name>/, preserving subfolder structure, and triggers dual-pass catalog compilation.