docs: add BUILD_PR asset pipeline converters bundle

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,25 +2,16 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_ASSET_PIPELINE_FOUNDATION as the next follow-up to project-level tool integration.
+Create BUILD_PR_ASSET_PIPELINE_CONVERTERS
 
 Scope:
-- establish a minimal shared asset-pipeline foundation
-- target only ingest/normalize/validate/register stages
-- reuse existing tools/shared asset/project helpers first
-- active tools only
-- minimal adapters only
-- no UI/theme work
-- no editor-state redesign
-- no render-pipeline changes
-- no converter suite in this PR
-- do not touch templates/ cleanup in this PR
+- add converter abstraction layer
+- implement minimal converters
+- integrate with pipeline foundation
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- verify touched tools still ingest/load assets
-- report exact files changed
-- report normalized asset rules and adapters
+- verify conversions usable
 
 Output:
-<project folder>/tmp/BUILD_PR_ASSET_PIPELINE_FOUNDATION_delta.zip
+<project>/tmp/BUILD_PR_ASSET_PIPELINE_CONVERTERS_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: add BUILD_PR asset pipeline foundation bundle
+docs: add BUILD_PR asset pipeline converters bundle

docs/dev/reports/BUILD_PR_ASSET_PIPELINE_CONVERTERS_report.md

@@ -0,0 +1,48 @@
+# BUILD_PR_ASSET_PIPELINE_CONVERTERS Report
+
+## Scope Outcome
+- Added a minimal shared converter abstraction layer for the asset pipeline.
+- Implemented conservative converter defaults for:
+  - tile -> vector (basic)
+  - vector -> tile (basic)
+  - sprite normalization
+- Integrated conversion into the shared pipeline foundation between normalize and validate/register stages.
+- Kept scope limited to shared pipeline/converter logic (no UI/theme/editor-state/render changes).
+
+## Converter Layer
+- New shared module: `tools/shared/assetPipelineConverters.js`
+- Introduced:
+  - `createAssetPipelineConverterRegistry(...)`
+  - `listAssetPipelineConverters(...)`
+  - `convertAssetPipelineCandidate(...)`
+  - `DEFAULT_ASSET_PIPELINE_CONVERTERS`
+- Converter behavior is metadata-safe and path/type normalization focused (minimal transforms only).
+
+## Pipeline Integration
+- Updated `tools/shared/assetPipelineFoundation.js` to include `CONVERT` stage.
+- `registerAssetPipelineCandidate(...)` now performs:
+  - normalize -> optional convert -> validate -> register
+- Added `convertNormalizedAssetPipelineCandidate(...)` and `validateNormalizedAssetPipelineCandidate(...)`.
+- Added converter inventory to `summarizeAssetPipelineRules()` output.
+
+## Validation
+- Command: `npm run test:launch-smoke -- --tools`
+- Result: PASS (`9/9` tools)
+- Smoke report: `docs/dev/reports/launch_smoke_report.md`
+
+- Converter usability check:
+  - Verified converter registry exposes expected converter IDs.
+  - Verified tile->vector registration applies conversion and registers converted output.
+  - Verified vector->tile registration applies conversion and registers converted output.
+  - Verified sprite normalization converter produces normalized sprite output.
+  - Result: PASS
+  - Evidence: `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_CONVERTERS_validation.txt`
+
+## Exact Files Changed
+- `docs/pr/BUILD_PR_ASSET_PIPELINE_CONVERTERS.md`
+- `docs/dev/reports/asset_pipeline_converters_targets.txt`
+- `tools/shared/assetPipelineConverters.js`
+- `tools/shared/assetPipelineFoundation.js`
+- `docs/dev/reports/launch_smoke_report.md`
+- `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_CONVERTERS_validation.txt`
+- `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_CONVERTERS_report.md`

docs/dev/reports/BUILD_PR_ASSET_PIPELINE_CONVERTERS_validation.txt

@@ -0,0 +1,9 @@
+ASSET PIPELINE CONVERTER TARGETS
+
+- tile → vector (basic)
+- vector → tile (basic)
+- sprite normalization
+
+Keep:
+- minimal logic
+- no heavy transforms

docs/dev/reports/asset_pipeline_converters_targets.txt

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-12T00:24:06.723Z
+Generated: 2026-04-12T00:31:13.799Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 

docs/dev/reports/launch_smoke_report.md

@@ -0,0 +1,29 @@
+# BUILD_PR_ASSET_PIPELINE_CONVERTERS
+
+## Purpose
+Extend asset pipeline with initial converter layer for transforming assets between formats used by tools.
+
+## Goals
+- introduce converter abstraction
+- enable tile ↔ vector ↔ sprite transformations (basic only)
+- keep converters modular and optional
+
+## Scope
+- converter interface
+- minimal converters (safe/common only)
+- integration with pipeline foundation
+
+## Out of Scope
+- full production-grade converters
+- 3D formats
+- UI redesign
+- rendering changes
+
+## Strategy
+- define converter registry
+- plug into pipeline after normalize stage
+- keep transformations reversible where possible
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- converted assets usable in at least 2 tools