Flatten asset manifest schema and align sample 1902 workspace loaders - PR 11.96

DavidQ · DavidQ · commit 2f615ee9e30a · 2026-04-29T22:14:15.000-04:00
diff --git a/docs/dev/codex_commands.md b/docs/dev/codex_commands.md
@@ -1,28 +1,8 @@
-# Codex Command — PR 11.95
+# Codex Command — PR 11.96
 
 Model: GPT-5.4
 Reasoning: high
 
-```text
-Run BUILD_PR for PR_11_95_FLATTEN_MANIFEST_ASSETS_AND_FIX_LOADERS.
-
-Read docs/pr/PR_11_95_FLATTEN_MANIFEST_ASSETS_AND_FIX_LOADERS.md.
-
-Implement the smallest complete code change that makes asset-browser.assets the single flat manifest source of truth for all asset kinds.
-
-Fix manifests and code together:
-- Remove nested asset-browser.assets.media usage.
-- Update runtime loaders to read manifest["asset-browser"].assets directly.
-- Update Workspace Manager, Asset Browser, and SVG Asset Studio consumers to list assets from the flat map.
-- Preserve kind-based filtering for image/font/audio/svg.
-- Keep Asteroids bezel path as /games/Asteroids/assets/images/bezel.png.
-- Keep Asteroids background path as /games/Asteroids/assets/images/deluxe.png.
-- Add/keep font.asteroids.vector-battle under the flat assets map.
-- Keep stretchOverride only on image.*.bezel entries.
-- Do not add aliases, shims, fallback paths, or media compatibility layers.
-
-After implementation, run targeted validation commands from the PR doc and write findings to docs/dev/reports/PR_11_95_validation.md.
-
-Package changed files into repo-structured ZIP:
-<project folder>/tmp/PR_11_95_FLATTEN_MANIFEST_ASSETS_AND_FIX_LOADERS.zip
+```bash
+codex exec --model gpt-5.4 --reasoning high "Apply PR 11.96. Update the manifest/schema/workspace contract so asset-browser.assets is a flat asset-id map for all asset kinds. Do not restore media. Fix runtime/tool loaders and sample 1902 workspace usage that still expect media. Update schemas. Preserve Asteroids bezel.png/background/font manifest loading. No aliases, no compatibility shims, no fallback data. Add reports under docs/dev/reports and keep targeted validation only."
 ```
diff --git a/docs/dev/commit_comment.txt b/docs/dev/commit_comment.txt
@@ -1 +1 @@
-Flatten manifest asset contract and fix runtime/tool loaders - PR 11.95
+Flatten asset manifest schema and align sample 1902 workspace loaders - PR 11.96
diff --git a/docs/dev/reports/PR_11_96_validation.md b/docs/dev/reports/PR_11_96_validation.md
@@ -0,0 +1,58 @@
+# PR 11.96 Validation - Flatten Manifest Assets and Loader Contract
+
+## Scope
+Implemented targeted PR 11.96 contract updates to keep `tools["asset-browser"].assets` as the flat source of truth for asset kinds.
+
+## Files Changed
+- `tools/Asset Browser/main.js`
+- `tools/shared/platformShell.js`
+- `src/engine/runtime/gameImageConvention.js`
+- `games/shared/workspaceGameAssetCatalog.js`
+- `tools/schemas/tools/asset-browser.schema.json`
+- `samples/phase-19/1902/sample.1902.workspace-all-tools.json`
+
+## Contract Changes Applied
+- Removed nested manifest asset traversal in Asset Browser (`assets.media`-style nested compatibility no longer consumed).
+- Updated preset catalog extraction to prefer flat `assets` map from:
+  - scoped tool preset root (`payload.assets` when scoped payload is the tool object)
+  - `config.assets`
+  - full manifest `tools["asset-browser"].assets`
+- Updated runtime chrome image resolver to consume only `tools["asset-browser"].assets` for manifest image entries.
+- Updated workspace game asset catalog manifest parsing to consume `tools["asset-browser"].assets` only.
+- Updated workspace shell embedded status summary for Asset Browser to count flat `assets` entries.
+- Updated sample 1902 Asset Browser tool payload from `payload.assetCatalog.entries` to flat root `assets` map.
+- Updated `tools/schemas/tools/asset-browser.schema.json`:
+  - added required root `assets`
+  - removed `payload.assetCatalog`
+  - enforced strict `assetEntry` shape (`path`, `kind`, optional `source`, optional `stretchOverride.uniformEdgeStretchPx`).
+
+## Asteroids Preservation Check
+- `games/Asteroids/game.manifest.json` still declares:
+  - bezel: `/games/Asteroids/assets/images/bezel.png`
+  - background: `/games/Asteroids/assets/images/deluxe.png`
+  - font: `font.asteroids.vector-battle`
+  - stretch override on `image.asteroids.bezel.stretchOverride.uniformEdgeStretchPx`
+
+## Targeted Validation Commands
+- `node --check "tools/Asset Browser/main.js"`
+- `node --check tools/shared/platformShell.js`
+- `node --check src/engine/runtime/gameImageConvention.js`
+- `node --check games/shared/workspaceGameAssetCatalog.js`
+- `node -e "import('./tests/tools/ToolSchemaStrictModeValidation.test.mjs').then(async (m)=>{await m.run(); console.log('ToolSchemaStrictModeValidation: PASS');})"`
+- `npm run test:workspace-manager:games`
+- `npm run test:manifest-payload:games`
+- `node ./tests/runtime/LaunchSmokeAllEntries.test.mjs --samples --sample-range=1902-1902 --tools`
+
+## Validation Results
+- Syntax checks: PASS
+- Workspace schema strict validation: PASS
+- Workspace Manager games open test: PASS
+- Game manifest payload expectations: PASS
+- Sample 1902 + tools launch smoke: PASS (19/19)
+
+## Legacy Contract Search Checks
+- `asset-browser.assets.media`: no matches in `src games tools samples tests`
+- `"media": {` under `games/**/game.manifest.json`: no matches
+
+## Notes
+- Full sample suite intentionally skipped; targeted validations were executed per PR scope.
diff --git a/docs/dev/reports/PR_11_96_validation_checklist.md b/docs/dev/reports/PR_11_96_validation_checklist.md
@@ -0,0 +1,20 @@
+# PR 11.96 Validation Checklist
+
+## Required searches
+- Search for `asset-browser.assets.media`
+- Search for `.assets.media`
+- Search for `media.audio`
+- Search for `media.images`
+- Search for `media.fonts`
+- Search for `media.svg`
+
+Remaining matches must be only historical docs/reports, not runtime/tool/schema/sample 1902 code.
+
+## Manual checks
+- Sample 1902 Workspace Manager loads.
+- SVG Asset Studio asset list is populated and visible.
+- Asteroids loads manifest background/bezel/font.
+- No 404s for guessed chrome assets.
+
+## Test decision
+Full samples suite skipped unless loader changes prove broad enough to require it.
diff --git a/docs/pr/PR_11_96_FLATTENED_ASSET_SCHEMA_AND_SAMPLE_1902_WORKSPACE.md b/docs/pr/PR_11_96_FLATTENED_ASSET_SCHEMA_AND_SAMPLE_1902_WORKSPACE.md
@@ -0,0 +1,70 @@
+# PR 11.96 — Flattened Asset Schema and Sample 1902 Workspace Alignment
+
+## Purpose
+Complete the manifest contract correction started in PR 11.95 by updating the schema and sample 1902 workspace usage to the flattened `asset-browser.assets` model.
+
+## Scope
+- Keep `asset-browser.assets` as the single flat asset map for all asset kinds.
+- Remove reliance on nested `media` asset buckets in runtime/tool/workspace loading code.
+- Update schema definitions/documentation so the flat model is the contract.
+- Update sample 1902 workspace data/code that still expects old workspace/media-shaped asset data.
+- Preserve existing asset IDs such as `image.*`, `font.*`, `audio.*`, `svg.*`.
+
+## Required Contract
+```json
+{
+  "asset-browser": {
+    "assets": {
+      "image.asteroids.bezel": {
+        "path": "/games/Asteroids/assets/images/bezel.png",
+        "kind": "image",
+        "source": "workspace-manager"
+      },
+      "font.asteroids.vector-battle": {
+        "path": "/games/Asteroids/assets/fonts/vector_battle.ttf",
+        "kind": "font",
+        "source": "workspace-manager"
+      },
+      "audio.asteroids.fire": {
+        "path": "/games/Asteroids/assets/audio/fire.mp3",
+        "kind": "audio",
+        "source": "workspace-manager"
+      }
+    }
+  }
+}
+```
+
+## Codex Tasks
+1. Search for old nested media contract usage:
+   - `asset-browser.assets.media`
+   - `.assets.media`
+   - `media.audio`
+   - `media.images`
+   - `media.fonts`
+   - `media.svg`
+2. Update runtime loaders and tool loaders to read the flat `asset-browser.assets` map.
+3. Update sample 1902 workspace JSON/JS so it uses the same flat asset map as games/tools.
+4. Update schema files and schema docs that describe asset manifests.
+5. Keep `stretchOverride` only on `image.*.bezel` entries, not on grouped/browser placeholder nodes.
+6. Do not add compatibility shims, aliases, fallback data, or hidden default assets.
+7. Do not restore `media`.
+
+## Acceptance Criteria
+- No code path requires `asset-browser.assets.media`.
+- Sample 1902 Workspace Manager still loads and lists assets.
+- SVG Asset Studio shows assets from the flat map.
+- Game runtime loads image, font, audio, and SVG entries from the flat map.
+- Asteroids still loads `bezel.png`, `deluxe.png`, and `vector_battle.ttf` from manifest entries.
+- No 404s caused by guessed bezel/background/font paths.
+- Schema validates flat `asset-browser.assets` entries for all asset kinds.
+
+## Targeted Validation
+Run targeted checks only:
+- Open sample 1902 Workspace Manager.
+- Open SVG Asset Studio from Workspace Manager and confirm assets are listed/visible.
+- Open Asteroids and confirm background, bezel, and font load from manifest.
+- Search confirms zero old media contract references remain except historical docs/reports.
+
+## Full Suite
+Skip full samples suite. Reason: changes are targeted to manifest schema/loader/workspace contract and can be validated with sample 1902 plus Asteroids.
diff --git a/games/shared/workspaceGameAssetCatalog.js b/games/shared/workspaceGameAssetCatalog.js
@@ -163,13 +163,10 @@ function normalizeManifestCatalogPayload(payload) {
   const source = toObject(payload);
   const schema = typeof source.schema === "string" ? source.schema.trim() : "";
   const version = Number(source.version);
-  const assetCatalog = toObject(source.assetCatalog);
-  const catalogEntries = normalizeCatalogEntries(assetCatalog.assets || assetCatalog);
   const toolAssetEntries = normalizeCatalogEntries(
     source?.tools?.["asset-browser"]?.assets
   );
   const entries = {
-    ...catalogEntries,
     ...toolAssetEntries
   };
   const isValidSchema = schema === GAME_MANIFEST_SCHEMA;
diff --git a/samples/phase-19/1902/sample.1902.workspace-all-tools.json b/samples/phase-19/1902/sample.1902.workspace-all-tools.json
@@ -531,34 +531,24 @@
       "tool": "asset-browser",
       "version": "1",
       "payload": {
-        "assetCatalog": {
-          "entries": [
-            {
-              "id": "sample-1902-workspace-preset",
-              "label": "1902 Workspace Integration Preset",
-              "type": "data",
-              "category": "Workflow JSON",
-              "kind": "other",
-              "path": "/samples/phase-19/1902/sample.1902.workspace-all-tools.json",
-              "status": "registered"
-            },
-            {
-              "id": "sample-1902-preview",
-              "label": "1902 Preview Art",
-              "type": "image",
-              "category": "Preview Art",
-              "kind": "other",
-              "path": "/samples/phase-19/1902/assets/images/preview.svg",
-              "status": "registered"
-            }
-          ]
-        },
         "assetBrowserPreset": {
           "selectedCategory": "All",
           "selectedAssetId": "sample-1902-workspace-preset",
           "search": "",
           "importCategory": "Workflow JSON"
         }
+      },
+      "assets": {
+        "sample-1902-workspace-preset": {
+          "path": "/samples/phase-19/1902/sample.1902.workspace-all-tools.json",
+          "kind": "other",
+          "source": "workspace-manager"
+        },
+        "sample-1902-preview": {
+          "path": "/samples/phase-19/1902/assets/images/preview.svg",
+          "kind": "image",
+          "source": "workspace-manager"
+        }
       }
     },
     "palette-browser": {
diff --git a/src/engine/runtime/gameImageConvention.js b/src/engine/runtime/gameImageConvention.js
@@ -79,12 +79,6 @@ function collectImageEntriesFromManifest(manifestPayload) {
     entries.push(entry);
   };
 
-  const assetCatalog = toObject(payload.assetCatalog);
-  const catalogEntries = toObject(assetCatalog.assets || assetCatalog.entries || assetCatalog);
-  Object.entries(catalogEntries).forEach(([assetId, rawEntry]) => {
-    pushEntry(normalizeAssetEntry(rawEntry, assetId));
-  });
-
   const assetBrowserAssets = toObject(payload?.tools?.["asset-browser"]?.assets);
   Object.entries(assetBrowserAssets).forEach(([assetId, rawEntry]) => {
     pushEntry(normalizeAssetEntry(rawEntry, assetId));
diff --git a/tools/Asset Browser/main.js b/tools/Asset Browser/main.js
@@ -501,6 +501,19 @@ function extractAssetBrowserCatalogFromPreset(rawPreset) {
   const config = payload.config && typeof payload.config === "object"
     ? payload.config
     : null;
+  if (payload.assets && typeof payload.assets === "object" && !Array.isArray(payload.assets)) {
+    return normalizeManifestAssetEntries(payload.assets);
+  }
+  if (config?.assets && typeof config.assets === "object" && !Array.isArray(config.assets)) {
+    return normalizeManifestAssetEntries(config.assets);
+  }
+  if (
+    payload?.tools?.["asset-browser"]?.assets
+    && typeof payload.tools["asset-browser"].assets === "object"
+    && !Array.isArray(payload.tools["asset-browser"].assets)
+  ) {
+    return normalizeManifestAssetEntries(payload.tools["asset-browser"].assets);
+  }
   return normalizePresetAssetEntries(config?.assetCatalog?.entries);
 }
 
@@ -526,8 +539,8 @@ async function loadSamplePresetCatalogEntries(samplePresetPath) {
       source: safePresetPath,
       entries,
       reason: entries.length > 0
-        ? "Approved assets loaded from sample preset assetCatalog.entries."
-        : "Sample preset loaded but assetCatalog.entries is missing or empty."
+        ? "Approved assets loaded from sample preset tools.asset-browser.assets."
+        : "Sample preset loaded but tools.asset-browser.assets is missing or empty."
     };
   } catch (error) {
     return {
@@ -595,14 +608,6 @@ function normalizeManifestAssetEntries(rawAssets = {}) {
     if (typeof value.path === "string") {
       pushEntry(key, value);
     }
-    Object.entries(value).forEach(([nestedKey, nestedValue]) => {
-      if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) {
-        return;
-      }
-      if (typeof nestedValue.path === "string") {
-        pushEntry(nestedKey, nestedValue);
-      }
-    });
   });
 
   return entries;
@@ -1008,7 +1013,7 @@ function buildApprovedAssetStatusText(approvedCount, info) {
   if (status === APPROVED_ASSET_STATUS.loadedEmpty) {
     return "0 approved assets | source exists and is empty."
       + ` Source checked: ${source}. Result count: 0.`
-      + " Next action: add approved entries in sample preset config.assetCatalog.entries,"
+      + " Next action: add approved entries in sample preset tools.asset-browser.assets,"
       + " tools.asset-browser.assets, or provide a valid assetCatalogPath."
       + ` Checked: ${checkedText}.`;
   }
@@ -1028,7 +1033,7 @@ function buildApprovedAssetStatusText(approvedCount, info) {
   }
   return "0 approved assets | source missing."
     + ` Source checked: ${source}.`
-    + " Next action: add sample preset config.assetCatalog.entries,"
+    + " Next action: add sample preset tools.asset-browser.assets,"
     + " tools.asset-browser.assets in active project manifest, or provide assetCatalogPath."
     + `${reason ? ` Details: ${reason}` : ""}`
     + ` Checked: ${checkedText}.`;
@@ -1040,7 +1045,7 @@ function buildApprovedAssetEmptyStateText(info) {
   const status = String(info?.status || APPROVED_ASSET_STATUS.sourceMissing);
   if (status === APPROVED_ASSET_STATUS.loadedEmpty) {
     return `No approved assets found. Source exists and is empty: ${source}.`
-      + " Next action: add sample preset config.assetCatalog.entries,"
+      + " Next action: add sample preset tools.asset-browser.assets,"
       + " tools.asset-browser.assets, or provide a valid assetCatalogPath.";
   }
   if (status === APPROVED_ASSET_STATUS.sourceLoadFailure) {
@@ -1053,7 +1058,7 @@ function buildApprovedAssetEmptyStateText(info) {
   }
   return "No approved asset source was loaded."
     + ` Checked source: ${source}.`
-    + " Next action: declare sample preset config.assetCatalog.entries,"
+    + " Next action: declare sample preset tools.asset-browser.assets,"
     + ` tools.asset-browser.assets, or launch with assetCatalogPath.${reason ? ` Details: ${reason}` : ""}`;
 }
 
diff --git a/tools/schemas/tools/asset-browser.schema.json b/tools/schemas/tools/asset-browser.schema.json
diff --git a/tools/shared/platformShell.js b/tools/shared/platformShell.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Flatten manifest asset contract and fix runtime/tool loaders - PR 11.95`
	`1`	`+Flatten asset manifest schema and align sample 1902 workspace loaders - PR 11.96`