Skip to content

Commit f394259

Browse files
author
DavidQ
committed
docs: add BUILD_PR asset pipeline foundation bundle
1 parent 1cfc4cb commit f394259

12 files changed

+484
-45
lines changed

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,25 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_PROJECT_TOOL_INTEGRATION
5+
Create BUILD_PR_ASSET_PIPELINE_FOUNDATION as the next follow-up to project-level tool integration.
66

77
Scope:
8-
- unify project model across tools
9-
- normalize asset references
10-
- minimal adapters
8+
- establish a minimal shared asset-pipeline foundation
9+
- target only ingest/normalize/validate/register stages
10+
- reuse existing tools/shared asset/project helpers first
11+
- active tools only
12+
- minimal adapters only
13+
- no UI/theme work
14+
- no editor-state redesign
15+
- no render-pipeline changes
16+
- no converter suite in this PR
17+
- do not touch templates/ cleanup in this PR
1118

1219
Validation:
1320
- npm run test:launch-smoke -- --tools
14-
- verify project works across tools
21+
- verify touched tools still ingest/load assets
22+
- report exact files changed
23+
- report normalized asset rules and adapters
1524

1625
Output:
17-
<project>/tmp/BUILD_PR_PROJECT_TOOL_INTEGRATION_delta.zip
26+
<project folder>/tmp/BUILD_PR_ASSET_PIPELINE_FOUNDATION_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: add BUILD_PR project-level tool integration bundle
1+
docs: add BUILD_PR asset pipeline foundation bundle

‎docs/dev/reports/BUILD_PR_ASSET_PIPELINE_FOUNDATION_report.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# BUILD_PR_ASSET_PIPELINE_FOUNDATION Report
2+
3+
## Scope Outcome
4+
- Established a minimal shared asset-pipeline foundation with explicit stages:
5+
- ingest
6+
- normalize
7+
- validate
8+
- register
9+
- Reused existing `tools/shared` asset/project helpers for ID/path normalization and registry upsert.
10+
- Added only minimal adapters in active-tool ingest paths (Tilemap, Parallax, Sprite).
11+
- No UI/theme changes, no editor-state redesign, no render-pipeline changes, no converter suite work.
12+
13+
## Normalized Asset Rules
14+
- Section rules:
15+
- `palettes` (`type=palette`, `requiresPath=false`)
16+
- `sprites` (`type=sprite`, `requiresPath=true`)
17+
- `vectors` (`type=vector`, `requiresPath=true`)
18+
- `tilesets` (`type=tileset`, `requiresPath=true`)
19+
- `tilemaps` (`type=tilemap`, `requiresPath=true`)
20+
- `images` (`type=image`, `requiresPath=true`)
21+
- `parallaxSources` (`type=parallaxSource`, `requiresPath=true`)
22+
- ID normalization:
23+
- keep provided ID when valid; otherwise generate via `createAssetId(...)`.
24+
- Path normalization:
25+
- use `normalizeProjectRelativePath(...)` for all path-required sections.
26+
- Validation:
27+
- reject unsupported/missing section
28+
- require normalized ID/type
29+
- enforce path presence for path-required sections
30+
- preserve warning when `sourceTool` is empty
31+
32+
## Adapters Added (Minimal)
33+
- Tilemap Studio ingest adapter:
34+
- `syncAssetRegistryFromDocument` now registers `tilesets` and `tilemaps` through `registerAssetPipelineCandidate(...)`.
35+
- Parallax Scene Studio ingest adapter:
36+
- `syncAssetRegistryFromDocument` now registers `images` and `parallaxSources` through `registerAssetPipelineCandidate(...)`.
37+
- Sprite Editor ingest adapter:
38+
- `syncSpriteAssetsToRegistry` now registers `palettes` and `sprites` through `registerAssetPipelineCandidate(...)`.
39+
40+
## Validation
41+
- `npm run test:launch-smoke -- --tools`
42+
- PASS (`9/9` tools)
43+
- Asset ingest/load verification for touched tools:
44+
- Confirmed adapter wiring exists in touched ingest paths (`Tilemap`, `Parallax`, `Sprite`).
45+
- Ran module-level pipeline registration check for touched tool sections:
46+
- `tilesets`, `tilemaps`, `images`, `parallaxSources`, `palettes`, `sprites`
47+
- all registrations succeeded and resolved in registry lookup.
48+
- Result: PASS (no runtime/console regressions observed in smoke run).
49+
50+
## Exact Files Changed
51+
- `tools/shared/assetPipelineFoundation.js`
52+
- `tools/Tilemap Studio/main.js`
53+
- `tools/Parallax Scene Studio/main.js`
54+
- `tools/Sprite Editor/modules/spriteEditorApp.js`
55+
- `docs/dev/reports/launch_smoke_report.md`
56+
- `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_FOUNDATION_report.md`
57+
58+
## Phase 2 Follow-up Candidates
59+
- optional converter suite stages (out of scope here)
60+
- deeper per-tool import UI harmonization (out of scope here)

‎docs/dev/reports/BUILD_PR_ASSET_PIPELINE_FOUNDATION_validation_checklist.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
VALIDATION CHECKLIST — BUILD_PR_ASSET_PIPELINE_FOUNDATION
2+
3+
Required:
4+
- [ ] touched tools still load
5+
- [ ] npm run test:launch-smoke -- --tools executed
6+
- [ ] no new console errors
7+
- [ ] asset ingest still works for touched tools
8+
- [ ] normalized ID/path/type rules reported
9+
- [ ] exact files changed reported
10+
- [ ] adapters added reported
11+
- [ ] no style/theme churn
12+
- [ ] no editor-state rewrite slipped in
13+
14+
Nice to have:
15+
- [ ] phase-2 converter/pipeline follow-up candidates listed

‎docs/dev/reports/asset_pipeline_foundation_read_set.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
READ SET — ASSET PIPELINE FOUNDATION
2+
3+
Read shared targets first:
4+
- tools/shared/projectSystem.js
5+
- tools/shared/projectSystemAdapters.js
6+
- tools/shared/projectSystemValueUtils.js
7+
- tools/shared/runtimeAssetLoader.js
8+
- tools/shared/runtimeAssetValidationUtils.js
9+
10+
Then inspect only active tool import/load paths as needed:
11+
- tools/Asset Browser/*
12+
- tools/Palette Browser/*
13+
- tools/Parallax Scene Studio/*
14+
- tools/Sprite Editor/*
15+
- tools/Tilemap Studio/*
16+
- tools/Vector Asset Studio/*
17+
- tools/Vector Map Editor/*
18+
19+
Constraint:
20+
- do not scan full repo
21+
- do not read games/samples unless a touched shared helper requires a narrow validation check
22+
- do not broaden into converter or 3D tool lanes

‎docs/dev/reports/asset_pipeline_foundation_targets.txt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
ASSET PIPELINE FOUNDATION TARGETS
2+
3+
Primary target cluster:
4+
1. asset ingest baseline
5+
2. asset identity normalization
6+
3. asset validation at import boundary
7+
4. project registration/handoff
8+
9+
Do first:
10+
- reuse existing tools/shared asset/project helpers
11+
- normalize IDs/paths/types
12+
- introduce only minimal adapters per touched tool
13+
14+
Do not do in this phase:
15+
- full converter implementations
16+
- 3D asset handling
17+
- render-pipeline rewrites
18+
- editor-state changes
19+
- broad import UI redesign

‎docs/dev/reports/launch_smoke_report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Launch Smoke Report
22

3-
Generated: 2026-04-12T00:01:45.164Z
3+
Generated: 2026-04-12T00:24:06.723Z
44

55
Filters: games=false, samples=false, tools=true, sampleRange=all
66

‎docs/pr/BUILD_PR_ASSET_PIPELINE_FOUNDATION.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# BUILD_PR_ASSET_PIPELINE_FOUNDATION
2+
3+
## Purpose
4+
Establish the first asset-pipeline foundation for tools so project assets can be imported, normalized, validated, and handed off consistently across the active authoring tools.
5+
6+
## Why This PR Now
7+
The previous lane unified project-level tool integration. The next highest-leverage step is to create a minimal, shared asset-pipeline foundation before adding larger converter or content-pipeline tools.
8+
9+
## Goals
10+
- shared asset ingest baseline
11+
- normalized asset metadata/IDs
12+
- validation at import boundary
13+
- repeatable handoff into the unified project model
14+
- no tool-specific workflow rewrites
15+
16+
## Scope
17+
- shared asset pipeline foundation only
18+
- import/normalize/validate handoff path
19+
- adapters for current active tools where needed
20+
- exact-cluster only
21+
22+
## In Scope
23+
- asset import baseline for current active tools
24+
- shared normalization rules for asset IDs/paths/types
25+
- validation hooks at asset-ingest boundary
26+
- manifest/project integration for imported assets
27+
- minimal adapters required by active tools
28+
29+
## Out of Scope
30+
- full converter suite
31+
- 3D asset tooling
32+
- render-pipeline rewrites
33+
- editor-state redesign
34+
- UI/theme restyling
35+
- templates/ cleanup
36+
- broad repo structure cleanup
37+
- deleting legacy assets or folders
38+
39+
## Active Tool Targets
40+
- tools/Asset Browser
41+
- tools/Palette Browser
42+
- tools/Parallax Scene Studio
43+
- tools/Sprite Editor
44+
- tools/Tilemap Studio
45+
- tools/Vector Asset Studio
46+
- tools/Vector Map Editor
47+
48+
## Shared Reuse Priority
49+
Reuse current shared layers first:
50+
- tools/shared/projectSystem.js
51+
- tools/shared/projectSystemAdapters.js
52+
- tools/shared/projectSystemValueUtils.js
53+
- tools/shared/runtimeAssetLoader.js
54+
- tools/shared/runtimeAssetValidationUtils.js
55+
- any current tools/shared asset/registry helpers already proven in prior lanes
56+
57+
## Build Strategy
58+
59+
### Step 1 — Inventory Existing Asset Ingest Paths
60+
Read only the active tool import/load paths and current tools/shared asset/project helpers.
61+
62+
### Step 2 — Define Minimal Shared Pipeline Stages
63+
Converge only on the first safe shared stages:
64+
1. ingest
65+
2. normalize
66+
3. validate
67+
4. register into project model
68+
69+
### Step 3 — Normalize Asset Identity Rules
70+
Standardize:
71+
- asset IDs
72+
- asset path normalization
73+
- type/category metadata
74+
- validation failure reporting
75+
76+
### Step 4 — Add Minimal Tool Adapters
77+
Only where needed to map current tool import paths into the shared pipeline foundation.
78+
79+
### Step 5 — Preserve Existing Tool Behavior
80+
Do not redesign how tools author content; only normalize the shared asset handoff boundary.
81+
82+
## Validation Requirements
83+
- npm run test:launch-smoke -- --tools
84+
- imported assets still appear in the tools that were touched
85+
- no console regressions
86+
- exact files changed reported
87+
- report normalized rules and adapters added
88+
89+
## Stop Conditions
90+
Stop and report if:
91+
- a touched tool needs editor-state redesign to adopt the pipeline
92+
- asset normalization requires render-pipeline changes
93+
- scope expands toward converters or 3D tooling
94+
- touched-file count grows beyond the named asset-ingest cluster
95+
96+
## Expected Output
97+
- repo-structured delta ZIP under <project folder>/tmp/
98+
- implementation kept to the first shared pipeline foundation only
99+
- reports identifying what remains for converters/pipeline phase 2

‎tools/Parallax Scene Studio/main.js‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import {
1515
sanitizeAssetRegistry,
1616
upsertRegistryEntry
1717
} from "../shared/projectAssetRegistry.js";
18+
import { registerAssetPipelineCandidate } from "../shared/assetPipelineFoundation.js";
1819
import {
1920
getBlockingAssetValidationMessage,
2021
hasBlockingAssetValidationFindings,
@@ -966,20 +967,32 @@ class ParallaxEditorApp {
966967
const sourceId = layer.parallaxSourceId || createAssetId("parallax", layer.id || layer.name || `source-${index + 1}`, `source-${index + 1}`);
967968
layer.parallaxSourceId = sourceId;
968969

969-
this.assetRegistry = upsertRegistryEntry(this.assetRegistry, "images", {
970-
id: imageId,
971-
name: layer.name || `Parallax Layer ${index + 1}`,
972-
path: layerPath,
973-
sourceTool: "parallax-editor"
970+
const imageRegistration = registerAssetPipelineCandidate({
971+
registry: this.assetRegistry,
972+
section: "images",
973+
ingest: {
974+
id: imageId,
975+
name: layer.name || `Parallax Layer ${index + 1}`,
976+
path: layerPath,
977+
sourceTool: "parallax-editor"
978+
}
974979
});
980+
this.assetRegistry = imageRegistration.registry;
975981

976-
this.assetRegistry = upsertRegistryEntry(this.assetRegistry, "parallaxSources", {
977-
id: sourceId,
978-
name: layer.name || `Parallax Layer ${index + 1}`,
979-
path: layerPath,
980-
imageId,
981-
sourceTool: "parallax-editor"
982+
const sourceRegistration = registerAssetPipelineCandidate({
983+
registry: this.assetRegistry,
984+
section: "parallaxSources",
985+
ingest: {
986+
id: sourceId,
987+
name: layer.name || `Parallax Layer ${index + 1}`,
988+
path: layerPath,
989+
sourceTool: "parallax-editor"
990+
},
991+
entryFields: {
992+
imageId
993+
}
982994
});
995+
this.assetRegistry = sourceRegistration.registry;
983996

984997
sourceIds.push(sourceId);
985998
});

‎tools/Sprite Editor/modules/spriteEditorApp.js‎

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import {
3636
sanitizeAssetRegistry,
3737
upsertRegistryEntry
3838
} from "../../shared/projectAssetRegistry.js";
39+
import { registerAssetPipelineCandidate } from "../../shared/assetPipelineFoundation.js";
3940
import {
4041
getBlockingAssetValidationMessage,
4142
hasBlockingAssetValidationFindings,
@@ -169,22 +170,36 @@ function syncSpriteAssetsToRegistry(state, options = {}) {
169170

170171
if (isPaletteLocked(state.project) && state.project.paletteRef?.id && state.project.paletteRef.id !== NO_PALETTE_ID) {
171172
paletteAssetId = createAssetId("palette", state.project.paletteRef.id, "palette");
172-
nextRegistry = upsertRegistryEntry(nextRegistry, "palettes", {
173-
id: paletteAssetId,
174-
name: state.project.paletteRef.id,
175-
enginePaletteId: state.project.paletteRef.id,
176-
colors: state.project.palette.slice(),
177-
sourceTool: "sprite-editor"
173+
const paletteRegistration = registerAssetPipelineCandidate({
174+
registry: nextRegistry,
175+
section: "palettes",
176+
ingest: {
177+
id: paletteAssetId,
178+
name: state.project.paletteRef.id,
179+
sourceTool: "sprite-editor"
180+
},
181+
entryFields: {
182+
enginePaletteId: state.project.paletteRef.id,
183+
colors: state.project.palette.slice()
184+
}
178185
});
186+
nextRegistry = paletteRegistration.registry;
179187
}
180188

181-
nextRegistry = upsertRegistryEntry(nextRegistry, "sprites", {
182-
id: spriteAssetId,
183-
name: spriteName,
184-
path: spritePath,
185-
paletteId: paletteAssetId,
186-
sourceTool: "sprite-editor"
189+
const spriteRegistration = registerAssetPipelineCandidate({
190+
registry: nextRegistry,
191+
section: "sprites",
192+
ingest: {
193+
id: spriteAssetId,
194+
name: spriteName,
195+
path: spritePath,
196+
sourceTool: "sprite-editor"
197+
},
198+
entryFields: {
199+
paletteId: paletteAssetId
200+
}
187201
});
202+
nextRegistry = spriteRegistration.registry;
188203

189204
state.assetRegistry = sanitizeAssetRegistry(nextRegistry);
190205
state.project.assetRefs = {

0 commit comments

Comments
 (0)