Skip to content

Commit b094195

Browse files
author
DavidQ
committed
Add deterministic sessionStorage backing for V2 tools with executable validation - PR 11.209
1 parent 9f5e2e4 commit b094195

7 files changed

Lines changed: 360 additions & 10 deletions

File tree

‎docs/dev/reports/PR_11_209_report.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# PR_11_209 Report — V2 Session Storage Backing (Deterministic) + Test
2+
3+
## Files Changed
4+
- `tools/asset-browser-v2/index.js`
5+
- `tools/palette-manager-v2/index.js`
6+
- `tools/svg-asset-studio-v2/index.js`
7+
- `tools/tilemap-studio-v2/index.js`
8+
- `tools/vector-map-editor-v2/index.js`
9+
- `tests/runtime/V2SessionStorage.test.mjs`
10+
11+
## Tools Validated
12+
- `asset-browser-v2`
13+
- `palette-manager-v2`
14+
- `svg-asset-studio-v2`
15+
- `tilemap-studio-v2`
16+
- `vector-map-editor-v2`
17+
18+
## SessionStorage Behavior Results
19+
- All five V2 tools now read storage with direct key lookup: `sessionStorage.getItem(hostContextId)`.
20+
- Legacy prefixed key usage (`toolboxaid.toolHost.context.*`) was removed from all five V2 tool runtimes.
21+
- Fixture-backed positive case passed for all tools:
22+
- Setup: `sessionStorage.setItem(hostContextId, JSON.stringify(sessionContext))`
23+
- Result: classification `VALID`
24+
25+
## Negative Case Results
26+
- Missing storage entry (`hostContextId` present, no key in storage) -> `EMPTY` for all tools.
27+
- Malformed JSON storage value (`"{invalid-json"`) -> `INVALID` for all tools.
28+
29+
## Runtime Test Output
30+
- Result file generated: `tmp/v2-session-storage-results.json`
31+
- Failure count: `0`
32+
33+
## Validation Commands Run
34+
1. `node --check tests/runtime/V2SessionStorage.test.mjs`
35+
- Result: **PASS**
36+
2. `node tests/runtime/V2SessionStorage.test.mjs`
37+
- Result: **PASS**
38+
3. `node --check tools/*-v2/index.js`
39+
- Result: **FAIL** in PowerShell (`*` passed literally to Node module loader)
40+
4. Equivalent per-tool syntax checks:
41+
- `node --check tools/asset-browser-v2/index.js` — **PASS**
42+
- `node --check tools/palette-manager-v2/index.js` — **PASS**
43+
- `node --check tools/svg-asset-studio-v2/index.js` — **PASS**
44+
- `node --check tools/tilemap-studio-v2/index.js` — **PASS**
45+
- `node --check tools/vector-map-editor-v2/index.js` — **PASS**
46+
47+
## Determinism / Fallback Confirmation
48+
- No fallback data or guessed payloads were added.
49+
- No default demo loading was introduced.
50+
- Session resolution remains deterministic and explicit from URL `hostContextId` + `sessionStorage[hostContextId]`.

‎tests/runtime/V2SessionStorage.test.mjs‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
import assert from "node:assert/strict";
2+
import fs from "node:fs";
3+
import path from "node:path";
4+
import { execFileSync } from "node:child_process";
5+
import { fileURLToPath, pathToFileURL } from "node:url";
6+
7+
const __filename = fileURLToPath(import.meta.url);
8+
const __dirname = path.dirname(__filename);
9+
const repoRoot = path.resolve(__dirname, "..", "..");
10+
const toolsRoot = path.join(repoRoot, "tools");
11+
const fixturesRoot = path.join(repoRoot, "tests", "fixtures", "v2-tools");
12+
const resultsPath = path.join(repoRoot, "tmp", "v2-session-storage-results.json");
13+
14+
const TOOLS = [
15+
"asset-browser-v2",
16+
"palette-manager-v2",
17+
"svg-asset-studio-v2",
18+
"tilemap-studio-v2",
19+
"vector-map-editor-v2"
20+
];
21+
22+
function readText(filePath) {
23+
return fs.readFileSync(filePath, "utf8");
24+
}
25+
26+
function readJson(filePath) {
27+
return JSON.parse(readText(filePath));
28+
}
29+
30+
function checkJsSyntax(jsPath) {
31+
try {
32+
execFileSync(process.execPath, ["--check", jsPath], {
33+
cwd: repoRoot,
34+
stdio: ["ignore", "pipe", "pipe"]
35+
});
36+
return { syntaxValid: true, syntaxError: "" };
37+
} catch (error) {
38+
return {
39+
syntaxValid: false,
40+
syntaxError: (error?.stderr || error?.stdout || error?.message || "").toString().trim()
41+
};
42+
}
43+
}
44+
45+
class MemorySessionStorage {
46+
constructor() {
47+
this.values = new Map();
48+
}
49+
50+
setItem(key, value) {
51+
this.values.set(String(key), String(value));
52+
}
53+
54+
getItem(key) {
55+
if (!this.values.has(String(key))) {
56+
return null;
57+
}
58+
return this.values.get(String(key));
59+
}
60+
}
61+
62+
function hostContextIdFromUrl(urlPath) {
63+
const parsedUrl = new URL(urlPath, "http://localhost/");
64+
const hostContextId = parsedUrl.searchParams.get("hostContextId");
65+
return typeof hostContextId === "string" ? hostContextId.trim() : "";
66+
}
67+
68+
function hasValidPayload(toolId, sessionContext) {
69+
if (!sessionContext || typeof sessionContext !== "object" || Array.isArray(sessionContext)) {
70+
return false;
71+
}
72+
73+
if (toolId === "asset-browser-v2") {
74+
const catalog = sessionContext?.payloadJson?.assetCatalog;
75+
if (!catalog || typeof catalog !== "object" || Array.isArray(catalog)) return false;
76+
if (typeof catalog.name !== "string" || !catalog.name.trim()) return false;
77+
if (!Array.isArray(catalog.entries)) return false;
78+
if (catalog.entries.some((entry) =>
79+
!entry ||
80+
typeof entry !== "object" ||
81+
Array.isArray(entry) ||
82+
typeof entry.id !== "string" ||
83+
!entry.id.trim() ||
84+
typeof entry.label !== "string" ||
85+
!entry.label.trim() ||
86+
typeof entry.kind !== "string" ||
87+
!entry.kind.trim() ||
88+
typeof entry.path !== "string" ||
89+
!entry.path.trim()
90+
)) return false;
91+
return true;
92+
}
93+
94+
if (toolId === "palette-manager-v2") {
95+
const palette = sessionContext?.paletteJson;
96+
if (!palette || typeof palette !== "object" || Array.isArray(palette)) return false;
97+
if (typeof palette.name !== "string" || !palette.name.trim()) return false;
98+
if (!Array.isArray(palette.colors)) return false;
99+
for (const colorEntry of palette.colors) {
100+
let colorValue = "";
101+
if (typeof colorEntry === "string") colorValue = colorEntry.trim().toUpperCase();
102+
if (colorEntry && typeof colorEntry === "object" && !Array.isArray(colorEntry) && typeof colorEntry.hex === "string") colorValue = colorEntry.hex.trim().toUpperCase();
103+
if (colorEntry && typeof colorEntry === "object" && !Array.isArray(colorEntry) && typeof colorEntry.color === "string") colorValue = colorEntry.color.trim().toUpperCase();
104+
if (!/^#([0-9A-F]{6}|[0-9A-F]{8})$/.test(colorValue)) return false;
105+
}
106+
return true;
107+
}
108+
109+
if (toolId === "svg-asset-studio-v2") {
110+
const vectorAsset = sessionContext?.payloadJson?.vectorAssetDocument;
111+
if (!vectorAsset || typeof vectorAsset !== "object" || Array.isArray(vectorAsset)) return false;
112+
if (typeof vectorAsset.sourceName !== "string" || !vectorAsset.sourceName.trim()) return false;
113+
if (typeof vectorAsset.svgText !== "string" || !/^\s*<svg[\s>]/i.test(vectorAsset.svgText)) return false;
114+
return true;
115+
}
116+
117+
if (toolId === "tilemap-studio-v2") {
118+
const tileMap = sessionContext?.payloadJson?.tileMapDocument;
119+
if (!tileMap || typeof tileMap !== "object" || Array.isArray(tileMap)) return false;
120+
if (!tileMap.map || typeof tileMap.map !== "object" || Array.isArray(tileMap.map)) return false;
121+
if (typeof tileMap.map.name !== "string" || !tileMap.map.name.trim()) return false;
122+
if (!Number.isFinite(Number(tileMap.map.width)) || Number(tileMap.map.width) <= 0) return false;
123+
if (!Number.isFinite(Number(tileMap.map.height)) || Number(tileMap.map.height) <= 0) return false;
124+
if (!Array.isArray(tileMap.layers)) return false;
125+
if (tileMap.layers.some((entry) =>
126+
!entry ||
127+
typeof entry !== "object" ||
128+
Array.isArray(entry) ||
129+
typeof entry.name !== "string" ||
130+
!entry.name.trim() ||
131+
typeof entry.kind !== "string" ||
132+
!entry.kind.trim() ||
133+
!Array.isArray(entry.data)
134+
)) return false;
135+
return true;
136+
}
137+
138+
if (toolId === "vector-map-editor-v2") {
139+
const map = sessionContext?.payloadJson?.vectorMapDocument;
140+
if (!map || typeof map !== "object" || Array.isArray(map)) return false;
141+
if (typeof map.name !== "string" || !map.name.trim()) return false;
142+
if (!Number.isFinite(Number(map.width)) || Number(map.width) <= 0) return false;
143+
if (!Number.isFinite(Number(map.height)) || Number(map.height) <= 0) return false;
144+
if (typeof map.background !== "string" || !map.background.trim()) return false;
145+
if (!Array.isArray(map.objects)) return false;
146+
if (map.objects.some((entry) =>
147+
!entry ||
148+
typeof entry !== "object" ||
149+
Array.isArray(entry) ||
150+
typeof entry.name !== "string" ||
151+
!entry.name.trim() ||
152+
typeof entry.kind !== "string" ||
153+
!entry.kind.trim() ||
154+
!entry.style ||
155+
typeof entry.style !== "object" ||
156+
Array.isArray(entry.style) ||
157+
typeof entry.style.stroke !== "string" ||
158+
!entry.style.stroke.trim() ||
159+
!Number.isFinite(Number(entry.style.lineWidth)) ||
160+
Number(entry.style.lineWidth) <= 0 ||
161+
!Array.isArray(entry.points) ||
162+
entry.points.length === 0 ||
163+
entry.points.some((point) =>
164+
!point ||
165+
typeof point !== "object" ||
166+
Array.isArray(point) ||
167+
!Number.isFinite(Number(point.x)) ||
168+
!Number.isFinite(Number(point.y))
169+
)
170+
)) return false;
171+
return true;
172+
}
173+
174+
return false;
175+
}
176+
177+
function classifyFromStorage(toolId, urlPath, sessionStorageLike) {
178+
const hostContextId = hostContextIdFromUrl(urlPath);
179+
if (!hostContextId) {
180+
return "EMPTY";
181+
}
182+
183+
const serializedSession = sessionStorageLike.getItem(hostContextId);
184+
if (!serializedSession) {
185+
return "EMPTY";
186+
}
187+
188+
try {
189+
const sessionContext = JSON.parse(serializedSession);
190+
return hasValidPayload(toolId, sessionContext) ? "VALID" : "INVALID";
191+
} catch {
192+
return "INVALID";
193+
}
194+
}
195+
196+
function validateTool(toolId) {
197+
const fixturePath = path.join(fixturesRoot, `${toolId}.json`);
198+
const jsPath = path.join(toolsRoot, toolId, "index.js");
199+
const htmlPath = path.join(toolsRoot, toolId, "index.html");
200+
const fixtureExists = fs.existsSync(fixturePath);
201+
const jsExists = fs.existsSync(jsPath);
202+
const htmlExists = fs.existsSync(htmlPath);
203+
const failures = [];
204+
205+
let fixtureValid = false;
206+
let hostContextId = "";
207+
let sessionContext = null;
208+
if (!fixtureExists) {
209+
failures.push("Missing fixture file.");
210+
} else {
211+
try {
212+
const fixture = readJson(fixturePath);
213+
fixtureValid = true;
214+
hostContextId = typeof fixture.hostContextId === "string" ? fixture.hostContextId.trim() : "";
215+
sessionContext = fixture.sessionContext;
216+
} catch {
217+
fixtureValid = false;
218+
}
219+
if (!fixtureValid) failures.push("Fixture JSON is invalid.");
220+
if (fixtureValid && !hostContextId) failures.push("Fixture hostContextId is missing.");
221+
}
222+
223+
const sessionStorageLike = new MemorySessionStorage();
224+
if (hostContextId && sessionContext) {
225+
sessionStorageLike.setItem(hostContextId, JSON.stringify(sessionContext));
226+
}
227+
228+
const validUrl = `tools/${toolId}/index.html?hostContextId=${encodeURIComponent(hostContextId || "missing")}`;
229+
const validState = classifyFromStorage(toolId, validUrl, sessionStorageLike);
230+
231+
const missingUrl = `tools/${toolId}/index.html?hostContextId=${encodeURIComponent(`${toolId}-missing`)}`;
232+
const missingState = classifyFromStorage(toolId, missingUrl, sessionStorageLike);
233+
234+
const invalidHostContextId = `${toolId}-invalid`;
235+
sessionStorageLike.setItem(invalidHostContextId, "{invalid-json");
236+
const invalidUrl = `tools/${toolId}/index.html?hostContextId=${encodeURIComponent(invalidHostContextId)}`;
237+
const invalidState = classifyFromStorage(toolId, invalidUrl, sessionStorageLike);
238+
239+
const jsText = jsExists ? readText(jsPath) : "";
240+
const usesDirectStorageKey = jsText.includes("sessionStorage.getItem(\n this.urlState.hostContextId\n )") || jsText.includes('sessionStorage.getItem(this.urlState.hostContextId)');
241+
const hasLegacyPrefixedStorageKey = jsText.includes("toolboxaid.toolHost.context.");
242+
const { syntaxValid, syntaxError } = checkJsSyntax(jsPath);
243+
244+
if (!htmlExists) failures.push("Missing tool index.html.");
245+
if (!jsExists) failures.push("Missing tool index.js.");
246+
if (validState !== "VALID") failures.push(`Expected VALID with fixture-backed storage, got ${validState}.`);
247+
if (missingState !== "EMPTY") failures.push(`Expected EMPTY with missing storage key, got ${missingState}.`);
248+
if (invalidState !== "INVALID") failures.push(`Expected INVALID with malformed JSON storage value, got ${invalidState}.`);
249+
if (!usesDirectStorageKey) failures.push("Tool JS is not reading sessionStorage with hostContextId as the direct key.");
250+
if (hasLegacyPrefixedStorageKey) failures.push("Tool JS still contains legacy prefixed sessionStorage key usage.");
251+
if (!syntaxValid) failures.push("Tool JS failed syntax check.");
252+
253+
return {
254+
tool: toolId,
255+
fixturePath: path.relative(repoRoot, fixturePath).replace(/\\/g, "/"),
256+
routePath: path.relative(repoRoot, htmlPath).replace(/\\/g, "/"),
257+
jsPath: path.relative(repoRoot, jsPath).replace(/\\/g, "/"),
258+
fixtureExists,
259+
fixtureValid,
260+
hostContextId,
261+
validUrl,
262+
missingUrl,
263+
invalidUrl,
264+
validState,
265+
missingState,
266+
invalidState,
267+
usesDirectStorageKey,
268+
hasLegacyPrefixedStorageKey,
269+
syntaxValid,
270+
syntaxError,
271+
failures
272+
};
273+
}
274+
275+
export function run() {
276+
const rows = TOOLS.map(validateTool);
277+
const failures = rows.flatMap((row) => row.failures.map((entry) => `${row.tool}: ${entry}`));
278+
279+
fs.mkdirSync(path.dirname(resultsPath), { recursive: true });
280+
fs.writeFileSync(resultsPath, `${JSON.stringify({
281+
generatedAt: new Date().toISOString(),
282+
toolCount: rows.length,
283+
failures,
284+
rows
285+
}, null, 2)}\n`, "utf8");
286+
287+
console.log(`v2 session storage results: ${resultsPath}`);
288+
assert.equal(failures.length, 0, `V2 session storage failures: ${failures.join(" | ")}`);
289+
return { toolCount: rows.length, failures, rows };
290+
}
291+
292+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
293+
try {
294+
const summary = run();
295+
console.log(JSON.stringify(summary, null, 2));
296+
} catch (error) {
297+
console.error(error);
298+
process.exitCode = 1;
299+
}
300+
}

‎tools/asset-browser-v2/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ class AssetBrowserV2 {
4444
}
4545
if (
4646
!window.sessionStorage.getItem(
47-
`toolboxaid.toolHost.context.${this.urlState.hostContextId}`
47+
this.urlState.hostContextId
4848
)
4949
) {
5050
this.renderMissing("No session data was found for the provided hostContextId. Re-open Asset Browser V2 from the tools index or a host flow that creates the session context first.");
@@ -53,7 +53,7 @@ class AssetBrowserV2 {
5353
this.loadContract(
5454
JSON.parse(
5555
window.sessionStorage.getItem(
56-
`toolboxaid.toolHost.context.${this.urlState.hostContextId}`
56+
this.urlState.hostContextId
5757
)
5858
)
5959
);

‎tools/palette-manager-v2/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ class PaletteManagerV2 {
4444
}
4545
if (
4646
!window.sessionStorage.getItem(
47-
`toolboxaid.toolHost.context.${this.urlState.hostContextId}`
47+
this.urlState.hostContextId
4848
)
4949
) {
5050
this.renderMissing("No session data was found for the provided hostContextId. Re-open Palette Manager V2 from the tools index or a host flow that creates the session context first.");
@@ -53,7 +53,7 @@ class PaletteManagerV2 {
5353
this.loadContract(
5454
JSON.parse(
5555
window.sessionStorage.getItem(
56-
`toolboxaid.toolHost.context.${this.urlState.hostContextId}`
56+
this.urlState.hostContextId
5757
)
5858
)
5959
);

0 commit comments

Comments
 (0)