Normalize Workspace Manager tool session keys and split Session Inspector V2 JSON and Schema views - PR_26128_018-session-inspector-v2-normalized-tool-keys

Author: DavidQ

docs/dev/reports/playwright_session_inspector_v2_normalized_tool_keys.md

@@ -0,0 +1,27 @@
+# Playwright Session Inspector V2 Normalized Tool Keys
+
+## Command
+`npm run test:workspace-v2`
+
+## Result
+- Passed: 15/15
+- Runtime: about 1.3 minutes
+
+## Targeted Coverage
+- Workspace Manager V2 hydrates one session key per tool:
+  - `workspace.tools.templates-v2`
+  - `workspace.tools.asset-manager-v2`
+  - `workspace.tools.palette-manager-v2`
+  - `workspace.tools.preview-generator-v2`
+  - `workspace.tools.session-inspector-v2`
+- Workspace Manager V2 does not create old split `.schema` or `.state` per-tool keys.
+- Session Inspector V2 shows normalized tool session values as one tile per tool.
+- JSON section shows the full combined object.
+- Schema section shows only schema data.
+- Schema section shows a visible empty-state message when the selected entry has no schema.
+- Per-tile Delete removes the normalized key.
+- Delete All still clears displayed entries.
+- Preview Generator V2 reads repo/game context from the normalized session key and remains able to generate a preview.
+
+## Skipped
+- Full samples smoke test was skipped by request. The changed surface is covered by targeted Workspace Manager V2, Session Inspector V2, and Preview Generator V2 workspace-launch validation in `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`.

docs/dev/reports/session_inspector_v2_normalized_tool_keys.md

@@ -0,0 +1,37 @@
+# Session Inspector V2 Normalized Tool Keys
+
+## Scope
+- Normalized Workspace Manager V2 tool hydration from split `workspace.tools.<tool-id>.schema` and `workspace.tools.<tool-id>.state` keys into one `workspace.tools.<tool-id>` key per tool.
+- Preserved `workspace.repo.reference`.
+- Updated Preview Generator V2 to read its nested `state` from `workspace.tools.preview-generator-v2` so workspace launch repo/game context still resolves through session storage.
+- Renamed the Session Inspector V2 Details section/control to JSON.
+- Added a Schema section/control that renders only the selected entry's top-level `schema` data.
+
+## Implementation Notes
+- Each Workspace Manager V2 tool session value is now a combined object with:
+  - `schema`
+  - `state`
+- Session Inspector V2 now renders normalized tool hydration as one tile per tool because the writer no longer creates split schema/state keys.
+- JSON renders the full stored value for the selected tile.
+- Schema renders only `value.schema` when present.
+- Schema shows an actionable empty state when the selected value has no top-level `schema` section.
+- Per-tile Delete still removes the selected storage key. For normalized tool tiles, that removes the single `workspace.tools.<tool-id>` key.
+- Delete All still clears all currently displayed storage entries.
+
+## Guardrails
+- No cross-tool direct communication was added.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- Game manifest SSoT semantics were not changed.
+
+## Validation
+- Passed `npm run test:workspace-v2` with 15/15 tests.
+- Verified Workspace Manager V2 creates normalized per-tool keys only.
+- Verified old `.schema` and `.state` per-tool keys are not created by Workspace Manager V2 hydration.
+- Verified Session Inspector V2 JSON and Schema sections.
+- Verified Schema empty state for a selected entry without `schema`.
+- Verified per-tile Delete and Delete All behavior.
+- Verified Preview Generator V2 still resolves repo/game context and can generate a preview from workspace launch.
+
+## Skipped
+- Full samples smoke test was skipped because this PR is limited to Workspace Manager V2 session hydration, Session Inspector V2 storage display, and the Preview Generator V2 workspace session read path. The requested targeted Workspace V2 Playwright validation covers the changed behavior.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -9,7 +9,7 @@ const ASSET_MANAGER_V2_TOOL_KEY = "asset-manager-v2";
 const PALETTE_MANAGER_V2_TOOL_KEY = "palette-manager-v2";
 const PREVIEW_GENERATOR_V2_TOOL_KEY = "preview-generator-v2";
 const WORKSPACE_REPO_REFERENCE_SESSION_KEY = "workspace.repo.reference";
-const WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY = `workspace.tools.${PREVIEW_GENERATOR_V2_TOOL_KEY}.state`;
+const WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY = `workspace.tools.${PREVIEW_GENERATOR_V2_TOOL_KEY}`;
 const BACKGROUND_ROLE = "background";
 const PREVIEW_ROLE = "preview";
 
@@ -127,25 +127,28 @@ function readWorkspaceRepoReference() {
 }
 
 function readWorkspacePreviewGeneratorState(manifest) {
-  const result = readSessionJson(WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY);
+  const result = readSessionJson(WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY);
   if (!result.ok) {
     return result;
   }
-  const state = result.value;
+  if (!isPlainObject(result.value.state)) {
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state must contain a JSON object.` };
+  }
+  const state = result.value.state;
   if (state.source !== "workspace-manager-v2") {
-    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY}.source must be workspace-manager-v2.` };
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state.source must be workspace-manager-v2.` };
   }
   if (state.toolId !== PREVIEW_GENERATOR_V2_TOOL_KEY) {
-    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY}.toolId must be ${PREVIEW_GENERATOR_V2_TOOL_KEY}.` };
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state.toolId must be ${PREVIEW_GENERATOR_V2_TOOL_KEY}.` };
   }
   if (state.repoReferenceKey !== WORKSPACE_REPO_REFERENCE_SESSION_KEY) {
-    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY}.repoReferenceKey must be ${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.` };
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state.repoReferenceKey must be ${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.` };
   }
   if (state.gameId !== manifest.gameId) {
-    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY}.gameId must match manifest.gameId ${manifest.gameId}.` };
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state.gameId must match manifest.gameId ${manifest.gameId}.` };
   }
   if (state.gameRoot !== manifest.gameRoot || state.assetsPath !== manifest.assetsPath) {
-    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY} gameRoot/assetsPath must match the workspace manifest.` };
+    return { ok: false, message: `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.state gameRoot/assetsPath must match the workspace manifest.` };
   }
   return { ok: true, state };
 }
@@ -1115,7 +1118,7 @@ class PreviewGeneratorV2App {
     ui.setRepoDestinationDisplayName(repoDisplayName);
     workspaceLaunchHydrated = true;
     logger.log(`OK Workspace repo session reference loaded from ${WORKSPACE_REPO_REFERENCE_SESSION_KEY} for ${repoDisplayName}.`);
-    logger.log(`OK Workspace tool session state loaded from ${WORKSPACE_PREVIEW_GENERATOR_STATE_SESSION_KEY}.`);
+    logger.log(`OK Workspace tool session state loaded from ${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.`);
     logger.log("Workspace launch repo context resolved from session storage; independent repo selection is not required.");
     this.syncGeneratePreviewButton();
   }

tools/preview-generator-v2/PreviewGeneratorV2App.js

@@ -12,5 +12,6 @@ Session Inspector V2 is a first-class tool for inspecting and clearing current-o
 - Open `tools/session-inspector-v2/index.html`.
 - Seed a storage key in the current origin.
 - Refresh the tool and verify the key appears in the Entries list.
-- Select an entry and confirm the Details panel shows raw value, parsed value, parse status, and byte size.
+- Select an entry and confirm the JSON panel shows the full stored value.
+- Select a normalized workspace tool entry and confirm the Schema panel shows only its schema section.
 - Use per-entry Delete or Delete All and verify the Entries list and status log update immediately.

tools/session-inspector-v2/README.md

@@ -95,17 +95,27 @@ <h2 class="tools-platform-frame__eyebrow">Session storage visibility</h2>
         </section>
       </section>
 
-      <aside class="session-inspector-v2__panel session-inspector-v2__panel--right tool-shell-common__fullscreen-panel tool-shell-common__fullscreen-side-panel tool-shell-common__fullscreen-panel-right" aria-label="Session details">
+      <aside class="session-inspector-v2__panel session-inspector-v2__panel--right tool-shell-common__fullscreen-panel tool-shell-common__fullscreen-side-panel tool-shell-common__fullscreen-panel-right" aria-label="Session JSON and schema">
         <section class="accordion-v2 session-inspector-v2__accordion session-inspector-v2__accordion--fill is-open" data-accordion-v2-open="true">
-          <div class="accordion-v2__header session-inspector-v2__details-accordion-header" role="button" tabindex="0" aria-expanded="true" aria-controls="sessionInspectorV2DetailsContent">
-            <span>Details</span>
-            <div class="session-inspector-v2__details-header-actions">
+          <div class="accordion-v2__header session-inspector-v2__json-accordion-header" role="button" tabindex="0" aria-expanded="true" aria-controls="sessionInspectorV2JsonContent">
+            <span>JSON</span>
+            <div class="session-inspector-v2__json-header-actions">
               <span class="accordion-v2__icon" aria-hidden="true">+</span>
-              <button id="copySessionInspectorV2DetailsButton" type="button">Copy</button>
+              <button id="copySessionInspectorV2JsonButton" type="button">Copy</button>
             </div>
           </div>
-          <div id="sessionInspectorV2DetailsContent" class="accordion-v2__content">
-            <pre id="sessionInspectorV2DetailsOutput" class="session-inspector-v2__output">{}</pre>
+          <div id="sessionInspectorV2JsonContent" class="accordion-v2__content">
+            <pre id="sessionInspectorV2JsonOutput" class="session-inspector-v2__output">{}</pre>
+          </div>
+        </section>
+
+        <section class="accordion-v2 session-inspector-v2__accordion session-inspector-v2__accordion--fill is-open" data-accordion-v2-open="true">
+          <div class="accordion-v2__header session-inspector-v2__schema-accordion-header" role="button" tabindex="0" aria-expanded="true" aria-controls="sessionInspectorV2SchemaContent">
+            <span>Schema</span>
+            <span class="accordion-v2__icon" aria-hidden="true">+</span>
+          </div>
+          <div id="sessionInspectorV2SchemaContent" class="accordion-v2__content">
+            <pre id="sessionInspectorV2SchemaOutput" class="session-inspector-v2__output">Select a storage entry with a top-level schema section.</pre>
           </div>
         </section>
 

tools/session-inspector-v2/index.html

@@ -1,28 +1,30 @@
 export class SessionInspectorV2App {
   constructor({
     accordions,
-    copyDetailsButton,
+    copyJsonButton,
     deleteAllButton,
-    details,
     entryList,
     filters,
+    json,
     refreshButton,
     returnToWorkspaceButton,
     runtimeContract,
+    schema,
     statusLog,
     storageService,
     windowRef = window
   }) {
     this.accordions = accordions;
-    this.copyDetailsButton = copyDetailsButton;
+    this.copyJsonButton = copyJsonButton;
     this.deleteAllButton = deleteAllButton;
-    this.details = details;
     this.entries = [];
     this.entryList = entryList;
     this.filters = filters;
+    this.json = json;
     this.refreshButton = refreshButton;
     this.returnToWorkspaceButton = returnToWorkspaceButton;
     this.runtimeContract = runtimeContract || { storageAccess: "read-only" };
+    this.schema = schema;
     this.statusLog = statusLog;
     this.storageService = storageService;
     this.selectedId = "";
@@ -44,8 +46,8 @@ export class SessionInspectorV2App {
       onSelected: (entryId) => this.selectEntry(entryId)
     });
     this.refreshButton.addEventListener("click", () => this.refresh());
-    this.copyDetailsButton.addEventListener("click", () => {
-      void this.copyDetails();
+    this.copyJsonButton.addEventListener("click", () => {
+      void this.copyJson();
     });
     this.deleteAllButton.addEventListener("click", () => this.deleteAllShownEntries());
     this.returnToWorkspaceButton.addEventListener("click", () => this.returnToWorkspace());
@@ -62,7 +64,9 @@ export class SessionInspectorV2App {
       this.selectedId = this.entries[0]?.id || "";
     }
     this.entryList.render(this.entries, this.selectedId);
-    this.details.render(this.entries.find((entry) => entry.id === this.selectedId));
+    const selectedEntry = this.entries.find((entry) => entry.id === this.selectedId);
+    this.json.render(selectedEntry);
+    this.schema.render(selectedEntry);
     this.filters.setSummary(this.summaryCounts());
     if (!silent) {
       this.statusLog.ok(`Loaded ${this.entries.length} matching storage entries.`);
@@ -80,7 +84,8 @@ export class SessionInspectorV2App {
     this.selectedId = entryId;
     this.entryList.render(this.entries, this.selectedId);
     const entry = this.entries.find((candidate) => candidate.id === entryId);
-    this.details.render(entry);
+    this.json.render(entry);
+    this.schema.render(entry);
     if (entry) {
       this.statusLog.info(`Selected ${entry.storageType}:${entry.key}.`);
     }
@@ -122,19 +127,19 @@ export class SessionInspectorV2App {
     this.refresh({ silent: true });
   }
 
-  async copyDetails() {
-    const detailsText = this.details.text().trim();
-    if (!detailsText || detailsText === "{}") {
-      this.statusLog.warn("Copy skipped: no Details content is shown.");
+  async copyJson() {
+    const jsonText = this.json.text().trim();
+    if (!jsonText || jsonText === "{}") {
+      this.statusLog.warn("Copy skipped: no JSON content is shown.");
       return;
     }
     if (typeof this.window.navigator?.clipboard?.writeText !== "function") {
       this.statusLog.fail("Copy failed: clipboard API is unavailable.");
       return;
     }
     try {
-      await this.window.navigator.clipboard.writeText(detailsText);
-      this.statusLog.ok("Copied Details content to clipboard.");
+      await this.window.navigator.clipboard.writeText(jsonText);
+      this.statusLog.ok("Copied JSON content to clipboard.");
     } catch (error) {
       this.statusLog.fail(`Copy failed: ${error.message}`);
     }

tools/session-inspector-v2/js/SessionInspectorV2App.js

@@ -1,8 +1,9 @@
 import { SessionInspectorV2App } from "./SessionInspectorV2App.js";
 import { AccordionSection } from "./controls/AccordionSection.js";
-import { DetailsControl } from "./controls/DetailsControl.js";
 import { EntryListControl } from "./controls/EntryListControl.js";
 import { FilterControl } from "./controls/FilterControl.js";
+import { JsonControl } from "./controls/JsonControl.js";
+import { SchemaControl } from "./controls/SchemaControl.js";
 import { StatusLogControl } from "./controls/StatusLogControl.js";
 import { sessionInspectorV2RuntimeContract } from "./services/SessionInspectorV2RuntimeContract.js";
 import { SessionInspectorV2StorageService } from "./services/SessionInspectorV2StorageService.js";
@@ -18,9 +19,9 @@ function requireElement(selector) {
 window.addEventListener("DOMContentLoaded", () => {
   const app = new SessionInspectorV2App({
     accordions: Array.from(document.querySelectorAll(".accordion-v2"), (section) => new AccordionSection(section)),
-    copyDetailsButton: requireElement("#copySessionInspectorV2DetailsButton"),
-    details: new DetailsControl({
-      output: requireElement("#sessionInspectorV2DetailsOutput")
+    copyJsonButton: requireElement("#copySessionInspectorV2JsonButton"),
+    json: new JsonControl({
+      output: requireElement("#sessionInspectorV2JsonOutput")
     }),
     deleteAllButton: requireElement("#deleteAllSessionInspectorV2Button"),
     entryList: new EntryListControl({
@@ -34,6 +35,9 @@ window.addEventListener("DOMContentLoaded", () => {
     refreshButton: requireElement("#refreshSessionInspectorV2Button"),
     returnToWorkspaceButton: requireElement("#returnToWorkspaceButton"),
     runtimeContract: sessionInspectorV2RuntimeContract(),
+    schema: new SchemaControl({
+      output: requireElement("#sessionInspectorV2SchemaOutput")
+    }),
     statusLog: new StatusLogControl({
       clearButton: requireElement("#clearSessionInspectorV2StatusButton"),
       output: requireElement("#statusLog")

tools/session-inspector-v2/js/bootstrap.js

@@ -0,0 +1,22 @@
+export class JsonControl {
+  constructor({ output }) {
+    this.output = output;
+  }
+
+  clear() {
+    this.output.textContent = "{}";
+  }
+
+  text() {
+    return String(this.output.textContent || "");
+  }
+
+  render(entry) {
+    if (!entry) {
+      this.clear();
+      return;
+    }
+    const value = entry.parseOk ? entry.parsedValue : entry.rawValue;
+    this.output.textContent = JSON.stringify(value, null, 2);
+  }
+}