refactor(skins): remove default.json fallback, require catalog skin.main, rename real skin files to skin.main.json, and fail fast on missing skin path

DavidQ · DavidQ · commit dab25ebb88b8 · 2026-04-25T14:59:44.000-04:00
diff --git a/games/SolarSystem/assets/presets/game-solarsystem-skin-editor.json b/games/SolarSystem/assets/presets/game-solarsystem-skin-editor.json
@@ -7,7 +7,7 @@
   ],
   "payload": {
     "gameId": "SolarSystem",
-    "skinPath": "/games/SolarSystem/assets/skins/default.json",
+    "skinPath": "/games/SolarSystem/assets/skins/skin.main.json",
     "skin": {
       "documentKind": "game-skin",
       "version": 1,
diff --git a/games/SolarSystem/assets/skins/skin.main.json b/games/SolarSystem/assets/skins/skin.main.json
diff --git a/games/SolarSystem/assets/workspace.asset-catalog.json b/games/SolarSystem/assets/workspace.asset-catalog.json
@@ -9,7 +9,7 @@
       "source": "workspace-manager"
     },
     "skin.main": {
-      "path": "/games/SolarSystem/assets/skins/default.json",
+      "path": "/games/SolarSystem/assets/skins/skin.main.json",
       "kind": "skin",
       "source": "workspace-manager"
     }
diff --git a/games/SolarSystem/main.js b/games/SolarSystem/main.js
@@ -11,7 +11,6 @@ import SolarSystemScene from './game/SolarSystemScene.js';
 import { loadGameSkin } from '/games/shared/gameSkinLoader.js';
 
 const theme = new Theme(ThemeTokens);
-const SOLAR_DEFAULT_SKIN_PATH = '/games/SolarSystem/assets/skins/default.json';
 
 export function bootSolarSystem({
   documentRef = globalThis.document ?? null,
@@ -43,7 +42,6 @@ export function bootSolarSystem({
 
   void loadGameSkin({
     gameId: 'SolarSystem',
-    defaultSkinPath: SOLAR_DEFAULT_SKIN_PATH,
     fallbackSchema: 'games.solar-system.skin/1'
   }).then(({ skin }) => {
     const scene = new SceneClass({ skin });
diff --git a/games/bouncing-ball/assets/presets/game-bouncing-ball-skin-editor.json b/games/bouncing-ball/assets/presets/game-bouncing-ball-skin-editor.json
@@ -7,7 +7,7 @@
   ],
   "payload": {
     "gameId": "Bouncing-ball",
-    "skinPath": "/games/Bouncing-ball/assets/skins/default.json",
+    "skinPath": "/games/Bouncing-ball/assets/skins/skin.main.json",
     "skin": {
       "documentKind": "game-skin",
       "version": 1,
@@ -19,10 +19,10 @@
           "color": "#05070a",
           "shape": "hud-color"
         },
-        "wall": {
+        "walls": {
           "color": "#f4f4ef",
           "thickness": 18,
-          "shape": "wall"
+          "shape": "walls"
         },
         "ball": {
           "color": "#f4f4ef",
diff --git a/games/bouncing-ball/assets/skins/skin.main.json b/games/bouncing-ball/assets/skins/skin.main.json
diff --git a/games/bouncing-ball/assets/workspace.asset-catalog.json b/games/bouncing-ball/assets/workspace.asset-catalog.json
@@ -9,7 +9,7 @@
       "source": "workspace-manager"
     },
     "skin.main": {
-      "path": "/games/bouncing-ball/assets/skins/default.json",
+      "path": "/games/bouncing-ball/assets/skins/skin.main.json",
       "kind": "skin",
       "source": "workspace-manager"
     }
diff --git a/games/bouncing-ball/main.js b/games/bouncing-ball/main.js
@@ -11,7 +11,6 @@ import BouncingBallScene from './game/BouncingBallScene.js';
 import { loadGameSkin } from '/games/shared/gameSkinLoader.js';
 
 const theme = new Theme(ThemeTokens);
-const BOUNCING_BALL_DEFAULT_SKIN_PATH = '/games/Bouncing-ball/assets/skins/default.json';
 
 export function bootBouncingBall({
   documentRef = globalThis.document ?? null,
@@ -43,7 +42,6 @@ export function bootBouncingBall({
 
   void loadGameSkin({
     gameId: 'Bouncing-ball',
-    defaultSkinPath: BOUNCING_BALL_DEFAULT_SKIN_PATH,
     fallbackSchema: 'games.bouncing-ball.skin/1'
   }).then(({ skin }) => {
     const scene = new SceneClass({ skin });
diff --git a/games/breakout/assets/presets/game-breakout-skin-editor.json b/games/breakout/assets/presets/game-breakout-skin-editor.json
@@ -7,7 +7,7 @@
   ],
   "payload": {
     "gameId": "Breakout",
-    "skinPath": "/games/Breakout/assets/skins/default.json",
+    "skinPath": "/games/Breakout/assets/skins/skin.main.json",
     "skin": {
       "documentKind": "game-skin",
       "version": 1,
diff --git a/games/breakout/assets/skins/skin.main.json b/games/breakout/assets/skins/skin.main.json
diff --git a/games/breakout/assets/workspace.asset-catalog.json b/games/breakout/assets/workspace.asset-catalog.json
@@ -9,7 +9,7 @@
       "source": "workspace-manager"
     },
     "skin.main": {
-      "path": "/games/Breakout/assets/skins/default.json",
+      "path": "/games/Breakout/assets/skins/skin.main.json",
       "kind": "skin",
       "source": "workspace-manager"
     }
diff --git a/games/breakout/main.js b/games/breakout/main.js
@@ -23,7 +23,6 @@ const theme = new Theme(ThemeTokens);
 const BUILD_DEBUG_MODE = 'prod';
 const BUILD_DEBUG_ENABLED = false;
 const DEBUG_STATE_STORAGE_KEY = 'toolbox.sample.breakout.debug.enabled';
-const BREAKOUT_DEFAULT_SKIN_PATH = '/games/Breakout/assets/skins/default.json';
 
 function sanitizeText(value) {
   return typeof value === 'string' ? value.trim() : '';
@@ -140,7 +139,6 @@ export function bootBreakout({
 
   void loadGameSkin({
     gameId: 'Breakout',
-    defaultSkinPath: BREAKOUT_DEFAULT_SKIN_PATH,
     fallbackSchema: 'games.breakout.skin/1'
   }).then(({ skin }) => {
     const scene = new SceneClass({
diff --git a/games/pong/assets/presets/game-pong-skin-editor.json b/games/pong/assets/presets/game-pong-skin-editor.json
@@ -7,7 +7,7 @@
   ],
   "payload": {
     "gameId": "Pong",
-    "skinPath": "/games/Pong/assets/skins/default.json",
+    "skinPath": "/games/Pong/assets/skins/skin.main.json",
     "skin": {
       "documentKind": "game-skin",
       "version": 1,
diff --git a/games/pong/assets/skins/skin.main.json b/games/pong/assets/skins/skin.main.json
diff --git a/games/pong/assets/workspace.asset-catalog.json b/games/pong/assets/workspace.asset-catalog.json
@@ -9,7 +9,7 @@
       "source": "workspace-manager"
     },
     "skin.main": {
-      "path": "/games/pong/assets/skins/default.json",
+      "path": "/games/pong/assets/skins/skin.main.json",
       "kind": "skin",
       "source": "workspace-manager"
     }
diff --git a/games/pong/main.js b/games/pong/main.js
@@ -11,7 +11,6 @@ import PongScene from './game/PongScene.js';
 import { loadGameSkin } from '/games/shared/gameSkinLoader.js';
 
 const theme = new Theme(ThemeTokens);
-const PONG_DEFAULT_SKIN_PATH = '/games/Pong/assets/skins/default.json';
 
 export function bootPong({
   documentRef = globalThis.document ?? null,
@@ -43,7 +42,6 @@ export function bootPong({
 
   void loadGameSkin({
     gameId: 'Pong',
-    defaultSkinPath: PONG_DEFAULT_SKIN_PATH,
     fallbackSchema: 'games.pong.skin/1'
   }).then(({ skin }) => {
     const scene = new SceneClass({ skin });
diff --git a/games/shared/gameSkinLoader.js b/games/shared/gameSkinLoader.js
@@ -855,13 +855,8 @@ async function fetchSkinDocumentFromPath(path, expectedGameId, fallbackSchema) {
   }
 }
 
-function resolveSkinAssetPath(gameId, fallbackPath) {
-  const safeFallbackPath = normalizePath(fallbackPath);
-  const primary = resolveWorkspaceGameAssetPath(gameId, "skin.main", safeFallbackPath);
-  if (primary) {
-    return primary;
-  }
-  return resolveWorkspaceGameAssetPath(gameId, "skin", safeFallbackPath);
+function resolveSkinAssetPath(gameId) {
+  return resolveWorkspaceGameAssetPath(gameId, "skin.main", "");
 }
 
 export async function loadGameSkin(options = {}) {
@@ -882,9 +877,9 @@ export async function loadGameSkin(options = {}) {
 
   await preloadWorkspaceGameAssetCatalog(expectedGameId);
 
-  const skinPath = resolveSkinAssetPath(expectedGameId, options.defaultSkinPath);
+  const skinPath = resolveSkinAssetPath(expectedGameId);
   if (!skinPath) {
-    throw new Error(`No skin path resolved for ${expectedGameId}.`);
+    throw new Error(`No skin.main asset path resolved for ${expectedGameId}.`);
   }
   const loadedSkin = await fetchSkinDocumentFromPath(skinPath, expectedGameId, fallbackSchema);
   return {
diff --git a/tools/Skin Editor/README.md b/tools/Skin Editor/README.md
@@ -7,13 +7,13 @@ Skin Editor is a visual-plus-JSON skin workflow tool for:
 - Solar System
 - Bouncing Ball
 
-It supports loading active skin payloads, editing via visual controls (colors, sizing, entities), importing/exporting JSON, applying browser-local overrides for live game previews, and clearing overrides to return to default game skin files.
+It supports loading active skin payloads, editing via visual controls (colors, sizing, entities), importing/exporting JSON, applying browser-local overrides for live game previews, and clearing overrides to return to the catalog-defined skin file.
 
 ## Runtime Behavior
 
 - Games load skin from local override first (if present).
-- If no override exists, games load the default skin file under `games/<Game>/assets/skins/default.json`.
-- Workspace mode can resolve skin file paths via each game's `workspace.asset-catalog.json`.
+- If no override exists, games load `skin.main` from each game's `workspace.asset-catalog.json`.
+- Missing or invalid `skin.main` now fails load with an explicit error.
 
 ## Typical Flow
 
diff --git a/tools/Skin Editor/main.js b/tools/Skin Editor/main.js
@@ -13,28 +13,24 @@ const GAME_OPTIONS = Object.freeze([
     id: "Breakout",
     label: "Breakout",
     gameHref: "/games/Breakout/index.html",
-    defaultSkinPath: "/games/Breakout/assets/skins/default.json",
     fallbackSchema: "games.breakout.skin/1"
   },
   {
     id: "Pong",
     label: "Pong",
     gameHref: "/games/Pong/index.html",
-    defaultSkinPath: "/games/Pong/assets/skins/default.json",
     fallbackSchema: "games.pong.skin/1"
   },
   {
     id: "SolarSystem",
     label: "Solar System",
     gameHref: "/games/SolarSystem/index.html",
-    defaultSkinPath: "/games/SolarSystem/assets/skins/default.json",
     fallbackSchema: "games.solar-system.skin/1"
   },
   {
     id: "Bouncing-ball",
     label: "Bouncing Ball",
     gameHref: "/games/Bouncing-ball/index.html",
-    defaultSkinPath: "/games/Bouncing-ball/assets/skins/default.json",
     fallbackSchema: "games.bouncing-ball.skin/1"
   }
 ]);
@@ -75,7 +71,6 @@ const state = {
   activeGameId: "",
   activeSkin: null,
   activeSource: "n/a",
-  presetSkinPath: "",
   presetSkin: null,
   selectedObjectKey: "",
   selectedObjectKeys: [],
@@ -1429,40 +1424,31 @@ async function loadActiveSkinForSelectedGame() {
     setStatus("Missing game context. Launch Skin Editor from a game/workspace link that includes a valid gameId.");
     return;
   }
-  const fallbackSkin = {
-    documentKind: "game-skin",
-    version: 1,
-    schema: game.fallbackSchema,
-    gameId: game.id,
-    name: `${game.label} Skin`,
-    objects: {},
-    entities: {}
-  };
+  const shouldUsePreset = state.presetSkin
+    && normalizeText(state.presetSkin.gameId).toLowerCase() === game.id.toLowerCase();
+  if (shouldUsePreset) {
+    const loadedPresetSkin = buildNormalizedSkinDocument(game, state.presetSkin);
+    state.presetSkin = null;
+    if (!setCurrentSkinDocument(loadedPresetSkin, "preset")) {
+      return;
+    }
+    setStatus(`Loaded preset skin for ${game.label}.`);
+    return;
+  }
 
   let result;
   try {
     result = await loadGameSkin({
       gameId: game.id,
-      defaultSkinPath: state.presetSkinPath || game.defaultSkinPath,
-      fallbackSkin,
       fallbackSchema: game.fallbackSchema
     });
   } catch (error) {
     setStatus(`Skin load failed: ${error instanceof Error ? error.message : "unknown error"}`);
     return;
   }
 
-  const shouldUsePreset = state.presetSkin
-    && normalizeText(state.presetSkin.gameId).toLowerCase() === game.id.toLowerCase();
-  const skinSource = shouldUsePreset ? "preset" : result.source;
-  const loadedSkin = shouldUsePreset
-    ? buildNormalizedSkinDocument(game, state.presetSkin)
-    : buildNormalizedSkinDocument(game, result.skin);
-  if (shouldUsePreset) {
-    state.presetSkin = null;
-  }
-
-  if (!setCurrentSkinDocument(loadedSkin, skinSource)) {
+  const loadedSkin = buildNormalizedSkinDocument(game, result.skin);
+  if (!setCurrentSkinDocument(loadedSkin, result.source)) {
     return;
   }
   setStatus(`Loaded active skin for ${game.label}.`);
@@ -1798,7 +1784,6 @@ async function loadPresetFromQuery() {
     }
     const rawPreset = await response.json();
     const payload = extractPresetPayload(rawPreset);
-    state.presetSkinPath = normalizeSamplePresetPath(payload.skinPath);
     state.presetSkin = payload.skin && typeof payload.skin === "object" ? payload.skin : null;
     const gameId = normalizeText(payload.gameId || searchParams.get("gameId"));
     return {

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`"source": "workspace-manager"`
`10`	`10`	`},`
`11`	`11`	`"skin.main": {`
`12`		`- "path": "/games/SolarSystem/assets/skins/default.json",`
	`12`	`+ "path": "/games/SolarSystem/assets/skins/skin.main.json",`
`13`	`13`	`"kind": "skin",`
`14`	`14`	`"source": "workspace-manager"`
`15`	`15`	`}`