feat(samples2tools): add Physics Sandbox presets and standardize sample preload status

DavidQ · DavidQ · commit b592255d54e6 · 2026-04-24T10:42:59.000-04:00
- add Physics Sandbox roundtrip integration for samples `0303` and `1606` with canonical preset files
- wire samples metadata + routing + roadmap/report updates for the new physics slice
- standardize all integrated tools to show `Loaded preset from sample &lt;id&gt;.`
- prevent Parallax sample-manifest boot refresh from overwriting preset-loaded status
diff --git a/docs/dev/reports/samples2tools_batch_7_summary.txt b/docs/dev/reports/samples2tools_batch_7_summary.txt
@@ -0,0 +1,9 @@
+Samples2Tools Batch 7 Summary
+Generated: 2026-04-24T14:30:04.422Z
+Scope: phase-01 through phase-19 Phase 2 coverage check for Physics Sandbox
+
+Physics Sandbox mapped samples: 2
+- Phase 03 Sample 0303 | Physics System | preset: /samples/phase-03/0303/sample-0303-physics-sandbox.json
+- Phase 16 Sample 1606 | 3D Physics Playground | preset: /samples/phase-16/1606/sample-1606-physics-sandbox.json
+
+Overall: pass
diff --git a/docs/dev/reports/samples2tools_batch_7_validation.txt b/docs/dev/reports/samples2tools_batch_7_validation.txt
@@ -0,0 +1,14 @@
+Samples2Tools Batch 7 Validation
+Generated: 2026-04-24T14:30:04.422Z
+
+[x] Physics Sandbox has exactly 2 mapped samples (phase-01 through phase-19)
+[x] Mapped Physics Sandbox preset files exist on disk
+[x] Samples index roundtrip logic contains mapped sample ids and tool branch
+[x] Physics Sandbox supports samplePresetPath preload and sets loaded preset status
+
+Execution evidence:
+- Physics Sandbox has exactly 2 mapped samples (phase-01 through phase-19): metadata sampleIds=0303,1606
+- Mapped Physics Sandbox preset files exist on disk: /samples/phase-03/0303/sample-0303-physics-sandbox.json; /samples/phase-16/1606/sample-1606-physics-sandbox.json
+- Samples index roundtrip logic contains mapped sample ids and tool branch: samples/index.render.js:shouldUsePresetRoundtrip
+- Physics Sandbox supports samplePresetPath preload and sets loaded preset status: tools/Physics Sandbox/main.js:tryLoadPresetFromQuery
+- overall: pass
diff --git a/docs/dev/reports/samples2tools_link_map_7.json b/docs/dev/reports/samples2tools_link_map_7.json
@@ -0,0 +1,23 @@
+{
+  "generatedAt": "2026-04-24T14:30:04.422Z",
+  "scope": "phase-01-phase-19",
+  "purpose": "batch-7-physics-sandbox",
+  "links": [
+    {
+      "toolId": "physics-sandbox",
+      "sampleId": "0303",
+      "phase": "03",
+      "title": "Physics System",
+      "href": "./phase-03/0303/index.html",
+      "presetPath": "/samples/phase-03/0303/sample-0303-physics-sandbox.json"
+    },
+    {
+      "toolId": "physics-sandbox",
+      "sampleId": "1606",
+      "phase": "16",
+      "title": "3D Physics Playground",
+      "href": "./phase-16/1606/index.html",
+      "presetPath": "/samples/phase-16/1606/sample-1606-physics-sandbox.json"
+    }
+  ]
+}
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md b/docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md
@@ -91,7 +91,7 @@
 ### Phase 2 - Highest Value Tools (from tools_used.txt)
 - [x] Parallax Scene Studio (4 candidate samples)
 - [x] Performance Profiler (2 candidate samples)
-- [ ] Physics Sandbox (2 candidate samples)
+- [x] Physics Sandbox (2 candidate samples)
 - [ ] Replay Visualizer (3 candidate samples)
 - [x] Vector Asset Studio (1 candidate sample)
 - [ ] Vector Map Editor (1 candidate sample)
@@ -154,6 +154,6 @@
 - [x] `docs/dev/reports/samples2tools_link_map_<n>.json`
 
 ## Current Snapshot (from tools_used.txt)
-- [x] Current tagged samples across active tools: `11` (phase-01 through phase-19)
+- [x] Current tagged samples across active tools: `13` (phase-01 through phase-19)
 - [x] Candidate coverage inventory exists for all active tools
 - [.] Convert candidates into curated, validated sample-to-tool links
diff --git a/samples/index.render.js b/samples/index.render.js
@@ -62,6 +62,10 @@ function shouldUsePresetRoundtrip(sample, toolId) {
     return (sampleId === "0512" && samplePhase === "05")
       || (sampleId === "1407" && samplePhase === "14");
   }
+  if (toolId === "physics-sandbox") {
+    return (sampleId === "0303" && samplePhase === "03")
+      || (sampleId === "1606" && samplePhase === "16");
+  }
   return false;
 }
 
diff --git a/samples/metadata/samples.index.metadata.json b/samples/metadata/samples.index.metadata.json
@@ -2181,6 +2181,9 @@
         "engine/theme/index/ThemeTokens",
         "engine/tilemap/index/renderTilemap",
         "engine/tilemap/index/Tilemap"
+      ],
+      "toolHints": [
+        "physics-sandbox"
       ]
     },
     {
@@ -8054,6 +8057,9 @@
         "engine/scene/index/Scene",
         "engine/theme/index/Theme",
         "engine/theme/index/ThemeTokens"
+      ],
+      "toolHints": [
+        "physics-sandbox"
       ]
     },
     {
diff --git a/samples/phase-03/0303/sample-0303-physics-sandbox.json b/samples/phase-03/0303/sample-0303-physics-sandbox.json
@@ -0,0 +1,35 @@
+{
+  "sampleId": "0303",
+  "phase": "03",
+  "title": "Physics System",
+  "description": "Shared sample preset for Sample 0303 and Physics Sandbox preload.",
+  "toolHints": [
+    "physics-sandbox"
+  ],
+  "payload": {
+    "physicsBody": {
+      "x": 0,
+      "y": 0,
+      "velocityX": 120,
+      "velocityY": -20,
+      "accelerationX": -8,
+      "accelerationY": 18,
+      "dragX": 10,
+      "dragY": 4,
+      "maxSpeedX": 160,
+      "maxSpeedY": 160,
+      "dt": 0.0166666667
+    }
+  },
+  "runtime": {
+    "sampleEntryPoint": "/samples/phase-03/0303/index.html"
+  },
+  "toolState": {
+    "preferredToolId": "physics-sandbox"
+  },
+  "provenance": {
+    "path": "/samples/phase-03/0303/sample-0303-physics-sandbox.json",
+    "createdAt": "2026-04-24T00:00:00.000Z",
+    "version": 1
+  }
+}
diff --git a/samples/phase-16/1606/sample-1606-physics-sandbox.json b/samples/phase-16/1606/sample-1606-physics-sandbox.json
@@ -0,0 +1,35 @@
+{
+  "sampleId": "1606",
+  "phase": "16",
+  "title": "3D Physics Playground",
+  "description": "Shared sample preset for Sample 1606 and Physics Sandbox preload.",
+  "toolHints": [
+    "physics-sandbox"
+  ],
+  "payload": {
+    "physicsBody": {
+      "x": 12,
+      "y": 48,
+      "velocityX": 0,
+      "velocityY": -140,
+      "accelerationX": 0,
+      "accelerationY": 38,
+      "dragX": 2,
+      "dragY": 1,
+      "maxSpeedX": 240,
+      "maxSpeedY": 260,
+      "dt": 0.0166666667
+    }
+  },
+  "runtime": {
+    "sampleEntryPoint": "/samples/phase-16/1606/index.html"
+  },
+  "toolState": {
+    "preferredToolId": "physics-sandbox"
+  },
+  "provenance": {
+    "path": "/samples/phase-16/1606/sample-1606-physics-sandbox.json",
+    "createdAt": "2026-04-24T00:00:00.000Z",
+    "version": 1
+  }
+}
diff --git a/tools/Parallax Scene Studio/main.js b/tools/Parallax Scene Studio/main.js
@@ -58,6 +58,15 @@ function normalizeSamplePresetPath(pathValue) {
   return "";
 }
 
+function buildPresetLoadedStatus(sampleId, samplePresetPath) {
+  const normalizedSampleId = typeof sampleId === "string" ? sampleId.trim() : "";
+  if (normalizedSampleId) {
+    return `Loaded preset from sample ${normalizedSampleId}.`;
+  }
+  const normalizedPath = typeof samplePresetPath === "string" ? samplePresetPath.trim() : "";
+  return normalizedPath ? `Loaded preset from ${normalizedPath}.` : "Loaded preset.";
+}
+
 function clamp(value, min, max, fallback) {
   const number = Number(value);
   if (!Number.isFinite(number)) {
@@ -451,7 +460,8 @@ class ParallaxEditorApp {
     this.renderAll();
     this.bindRuntimeStateSync();
     this.queueLivePreviewSync("init");
-    this.loadSampleManifest();
+    const hasSamplePresetQuery = new URLSearchParams(window.location.search).has("samplePresetPath");
+    this.loadSampleManifest({ quiet: hasSamplePresetQuery });
     void this.tryLoadPresetFromQuery();
   }
 
@@ -1167,8 +1177,7 @@ class ParallaxEditorApp {
       this.skipExternalProjectStateUntil = Date.now() + 3000;
       this.applyParallaxDocument(extractParallaxDocument(toolDocument));
       this.queueLivePreviewSync("sample-preset");
-      const sourceLabel = sampleId ? `sample ${sampleId}` : samplePresetPath;
-      this.updateStatus(`Loaded preset from ${sourceLabel}.`);
+      this.updateStatus(buildPresetLoadedStatus(sampleId, samplePresetPath));
     } catch (error) {
       this.updateStatus(`Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);
     }
diff --git a/tools/Performance Profiler/main.js b/tools/Performance Profiler/main.js
@@ -46,6 +46,15 @@ function normalizeSamplePresetPath(pathValue) {
   return "";
 }
 
+function buildPresetLoadedStatus(sampleId, samplePresetPath) {
+  const normalizedSampleId = typeof sampleId === "string" ? sampleId.trim() : "";
+  if (normalizedSampleId) {
+    return `Loaded preset from sample ${normalizedSampleId}.`;
+  }
+  const normalizedPath = typeof samplePresetPath === "string" ? samplePresetPath.trim() : "";
+  return normalizedPath ? `Loaded preset from ${normalizedPath}.` : "Loaded preset.";
+}
+
 function setStatus(message) {
   if (refs.statusText instanceof HTMLElement) {
     refs.statusText.textContent = message;
@@ -234,8 +243,7 @@ async function tryLoadPresetFromQuery() {
       throw new Error("Preset payload did not include profileSettings.");
     }
     performanceProfilerApi.applyProjectState(presetSettings);
-    const sourceLabel = sampleId ? `sample ${sampleId}` : samplePresetPath;
-    setStatus(`Loaded preset from ${sourceLabel}.`);
+    setStatus(buildPresetLoadedStatus(sampleId, samplePresetPath));
   } catch (error) {
     setStatus(`Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);
   }
diff --git a/tools/Physics Sandbox/main.js b/tools/Physics Sandbox/main.js
@@ -13,6 +13,35 @@ const refs = {
 let disposeInteractionFlow = null;
 let initialized = false;
 
+function normalizeSamplePresetPath(pathValue) {
+  if (typeof pathValue !== "string") {
+    return "";
+  }
+  const trimmed = pathValue.trim().replace(/\\/g, "/");
+  if (!trimmed || trimmed.includes("..")) {
+    return "";
+  }
+  if (trimmed.startsWith("/samples/")) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("./samples/")) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("samples/")) {
+    return `./${trimmed}`;
+  }
+  return "";
+}
+
+function buildPresetLoadedStatus(sampleId, samplePresetPath) {
+  const normalizedSampleId = typeof sampleId === "string" ? sampleId.trim() : "";
+  if (normalizedSampleId) {
+    return `Loaded preset from sample ${normalizedSampleId}.`;
+  }
+  const normalizedPath = typeof samplePresetPath === "string" ? samplePresetPath.trim() : "";
+  return normalizedPath ? `Loaded preset from ${normalizedPath}.` : "Loaded preset.";
+}
+
 function setStatus(message) {
   if (refs.statusText instanceof HTMLElement) {
     refs.statusText.textContent = message;
@@ -30,6 +59,50 @@ function parseBody() {
   return { ...parsed };
 }
 
+function extractPhysicsBodyFromPreset(rawPreset) {
+  if (!rawPreset || typeof rawPreset !== "object") {
+    return null;
+  }
+  const payloadBody = rawPreset?.payload?.physicsBody;
+  if (payloadBody && typeof payloadBody === "object" && !Array.isArray(payloadBody)) {
+    return { ...payloadBody };
+  }
+  const directBody = rawPreset?.physicsBody;
+  if (directBody && typeof directBody === "object" && !Array.isArray(directBody)) {
+    return { ...directBody };
+  }
+  return null;
+}
+
+async function tryLoadPresetFromQuery() {
+  const searchParams = new URLSearchParams(window.location.search);
+  const samplePresetPath = normalizeSamplePresetPath(searchParams.get("samplePresetPath") || "");
+  if (!samplePresetPath) {
+    return;
+  }
+
+  const sampleId = String(searchParams.get("sampleId") || "").trim();
+  try {
+    const presetUrl = new URL(samplePresetPath, window.location.href);
+    const response = await fetch(presetUrl.toString(), { cache: "no-store" });
+    if (!response.ok) {
+      throw new Error(`Preset request failed (${response.status}).`);
+    }
+    const rawPreset = await response.json();
+    const body = extractPhysicsBodyFromPreset(rawPreset);
+    if (!body) {
+      throw new Error("Preset payload did not include physicsBody.");
+    }
+    if (!(refs.input instanceof HTMLTextAreaElement)) {
+      throw new Error("Physics body input is unavailable.");
+    }
+    refs.input.value = toPrettyJson(body);
+    setStatus(buildPresetLoadedStatus(sampleId, samplePresetPath));
+  } catch (error) {
+    setStatus(`Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+}
+
 function runStep() {
   const body = parseBody();
   if (!body) {
@@ -82,6 +155,7 @@ function bootPhysicsSandbox() {
       maxSpeedY: 140
     });
   }
+  void tryLoadPresetFromQuery();
   initialized = true;
   return {
     runStep
diff --git a/tools/Tilemap Studio/main.js b/tools/Tilemap Studio/main.js
@@ -73,6 +73,15 @@ function normalizeSamplePresetPath(pathValue) {
   return "";
 }
 
+function buildPresetLoadedStatus(sampleId, samplePresetPath) {
+  const normalizedSampleId = typeof sampleId === "string" ? sampleId.trim() : "";
+  if (normalizedSampleId) {
+    return `Loaded preset from sample ${normalizedSampleId}.`;
+  }
+  const normalizedPath = typeof samplePresetPath === "string" ? samplePresetPath.trim() : "";
+  return normalizedPath ? `Loaded preset from ${normalizedPath}.` : "Loaded preset.";
+}
+
 function extractTileMapDocumentFromSamplePreset(rawPreset) {
   if (!rawPreset || typeof rawPreset !== "object") {
     return rawPreset;
@@ -2026,8 +2035,7 @@ class TileMapEditorApp {
       this.renderAll();
       void this.reloadTilesetImageFromDocument({ quiet: true });
       void this.preloadIndividualTileImages({ quiet: true });
-      const sourceLabel = sampleId ? `sample ${sampleId}` : samplePresetPath;
-      this.updateStatus(`Loaded preset from ${sourceLabel}.`);
+      this.updateStatus(buildPresetLoadedStatus(sampleId, samplePresetPath));
     } catch (error) {
       this.updateStatus(`Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);
     }
diff --git a/tools/Vector Asset Studio/main.js b/tools/Vector Asset Studio/main.js
@@ -47,6 +47,15 @@ function normalizeSamplePresetPath(pathValue) {
   return "";
 }
 
+function buildPresetLoadedStatus(sampleId, samplePresetPath) {
+  const normalizedSampleId = typeof sampleId === "string" ? sampleId.trim() : "";
+  if (normalizedSampleId) {
+    return `Loaded preset from sample ${normalizedSampleId}.`;
+  }
+  const normalizedPath = typeof samplePresetPath === "string" ? samplePresetPath.trim() : "";
+  return normalizedPath ? `Loaded preset from ${normalizedPath}.` : "Loaded preset.";
+}
+
 const state = {
   documentName: "untitled-background",
   canvasWidth: 1600,
@@ -2556,8 +2565,7 @@ async function tryLoadPresetFromQuery() {
     if (extractedPreset.editorOptions) {
       applySampleEditorOptions(extractedPreset.editorOptions);
     }
-    const sourceLabel = sampleId ? `sample ${sampleId}` : samplePresetPath;
-    setStatus(`Loaded preset from ${sourceLabel}.`);
+    setStatus(buildPresetLoadedStatus(sampleId, samplePresetPath));
     return true;
   } catch (error) {
     setStatus(`Preset load failed: ${error instanceof Error ? error.message : "unknown error"}`);

Original file line number	Diff line number	Diff line change
`@@ -62,6 +62,10 @@ function shouldUsePresetRoundtrip(sample, toolId) {`
`62`	`62`	`return (sampleId === "0512" && samplePhase === "05")`
`63`	`63`	`\|\| (sampleId === "1407" && samplePhase === "14");`
`64`	`64`	`}`
	`65`	`+ if (toolId === "physics-sandbox") {`
	`66`	`+ return (sampleId === "0303" && samplePhase === "03")`
	`67`	`+ \|\| (sampleId === "1606" && samplePhase === "16");`
	`68`	`+ }`
`65`	`69`	`return false;`
`66`	`70`	`}`
`67`	`71`
Original file line number	Diff line number	Diff line change
`@@ -2181,6 +2181,9 @@`
`2181`	`2181`	`"engine/theme/index/ThemeTokens",`
`2182`	`2182`	`"engine/tilemap/index/renderTilemap",`
`2183`	`2183`	`"engine/tilemap/index/Tilemap"`
	`2184`	`+ ],`
	`2185`	`+ "toolHints": [`
	`2186`	`+ "physics-sandbox"`
`2184`	`2187`	`]`
`2185`	`2188`	`},`
`2186`	`2189`	`{`
`@@ -8054,6 +8057,9 @@`
`8054`	`8057`	`"engine/scene/index/Scene",`
`8055`	`8058`	`"engine/theme/index/Theme",`
`8056`	`8059`	`"engine/theme/index/ThemeTokens"`
	`8060`	`+ ],`
	`8061`	`+ "toolHints": [`
	`8062`	`+ "physics-sandbox"`
`8057`	`8063`	`]`
`8058`	`8064`	`},`
`8059`	`8065`	`{`