Correct Assets MVP source rules for Data, Sprite, Vector, and references - PR_26163_073-assets-source-rules-followup

Author: ToolboxAid

docs_build/dev/reports/PR_26163_073-assets-source-rules-followup.md

@@ -0,0 +1,86 @@
+# PR_26163_073-assets-source-rules-followup
+
+## Branch Validation
+- PASS: current branch is `main`.
+- Expected branch: `main`.
+
+## Impacted Lanes
+- Toolbox Assets runtime lane.
+- Assets mock DB repository lane.
+- Targeted Playwright lane: `tests/playwright/tools/AssetToolMockRepository.spec.mjs`.
+- Workspace contract lane via legacy command `npm run test:workspace-v2`.
+
+## Requirement Checklist
+- PASS: `docs_build/dev/PROJECT_INSTRUCTIONS.md` was read before implementation.
+- PASS: current branch was verified as `main` before changes.
+- PASS: Data assets support Source options `Upload` and `Reference`.
+- PASS: Data Upload file picker accepts `.json`, `.csv`, and `.txt`.
+- PASS: Data Upload uses the selected filename in the File detail and saved row.
+- PASS: Data Upload save without a selected file fails visibly with `Choose an upload file before saving.`
+- PASS: Sprite add/edit rows are Reference-only for MVP and do not show upload file selection.
+- PASS: Vector add/edit rows are Reference-only for MVP and do not show upload file selection.
+- PASS: Palette References remain Reference-only.
+- PASS: Image, Audio, and Font upload filename behavior remains covered and passing.
+- PASS: user-facing source help text appears per asset type in add/edit rows.
+- PASS: no fake filename generator exists; `catalogFileNameForName` is absent.
+- PASS: Source modes change only through explicit Source dropdown selection.
+- PASS: Projectile remains absent from usage values.
+- PASS: shared Tags type-ahead behavior remains covered and passing.
+- PASS: owner-scoped asset records remain covered and passing.
+- PASS: scope stayed limited to Assets source rules, targeted tests, and required reports.
+
+## Changed Files
+- `toolbox/assets/assets.js`
+- `src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js`
+- `tests/playwright/tools/AssetToolMockRepository.spec.mjs`
+- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
+- `docs_build/dev/reports/PR_26163_073-assets-source-rules-followup.md`
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+
+## Validation Performed
+- PASS: `node --check toolbox/assets/assets.js`
+- PASS: `node --check src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js`
+- PASS: `node --check tests/playwright/tools/AssetToolMockRepository.spec.mjs`
+- PASS: `npx playwright test tests/playwright/tools/AssetToolMockRepository.spec.mjs --reporter=line --workers=1`
+  - Result: 3 passed.
+- PASS: `npm run test:workspace-v2`
+  - Result: 5 passed.
+- PASS: `git diff --check`
+
+## Playwright Result
+- PASS: targeted Assets Playwright validates Data Upload/Reference, Data `.json`/`.csv`/`.txt` filename capture, Data upload missing-file failure, Sprite/Vector/Palette Reference-only source rules, Image/Audio/Font upload filename behavior, Projectile absence, shared Tags type-ahead, and owner scope.
+
+## V8 Coverage
+- PASS/WARN: `toolbox/assets/assets.js` browser V8 coverage collected at 96%.
+- WARN: `src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js` is exercised through Node-side repository assertions and API-backed browser behavior, but is not browser-collected V8 runtime code.
+- Details: `docs_build/dev/reports/playwright_v8_coverage_report.txt`.
+
+## Search Evidence
+- PASS: `toolbox/assets/assets.js` contains `const REFERENCE_ONLY_ASSET_TYPES = new Set(["Sprites", "Vectors", "Palette References"]);`.
+- PASS: `toolbox/assets/assets.js` contains `const ALWAYS_MIXED_SOURCE_ASSET_TYPES = new Set(["Data"]);`.
+- PASS: `toolbox/assets/assets.js` contains `Data can upload .json, .csv, or .txt files`.
+- PASS: `toolbox/assets/assets.js` contains `Sprites are Reference-only for MVP.`
+- PASS: `toolbox/assets/assets.js` contains `Vectors are Reference-only for MVP.`
+- PASS: `toolbox/assets/assets.js` contains `Palette References must reference a palette swatch.`
+- PASS: `rg "catalogFileNameForName|fake filename"` returned no active implementation matches.
+- PASS: Projectile appears only in negative Playwright assertions confirming it is absent.
+
+## Skipped Lanes
+- Samples validation: SKIP. Samples are explicitly out of scope; this PR only changes the Assets tool source-rule behavior and its mock repository contract.
+- Full samples smoke: SKIP. The request explicitly says not to run full samples smoke.
+- Broad unrelated toolbox lanes: SKIP. No shared navigation, tool registry, auth, sample JSON, or production runtime behavior changed.
+
+## Manual Validation Steps
+1. Open `toolbox/assets/index.html`.
+2. Reset Asset Library.
+3. Add Data and confirm Source offers Upload and Reference.
+4. Save Data Upload without selecting a file and confirm visible failure.
+5. Select `.json`, `.csv`, then `.txt` files and confirm the File detail updates to the selected filename.
+6. Save Data Upload, then add another Data row and choose Reference to confirm the reference selector appears.
+7. Add Sprites and Vectors and confirm only Reference is available and no Upload File picker appears.
+8. Add Palette References and confirm it remains Reference-only.
+9. Add Images, Audio, and Fonts and confirm Upload filename display still works.
+
+## Samples Decision
+- SKIP: no sample JSON alignment, sample runtime, or sample smoke behavior is in scope for PR_26163_073.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,4 +1,4 @@
-docs_build/dev/reports/PR_26163_072-assets-source-upload-reference-details.md
+docs_build/dev/reports/PR_26163_073-assets-source-rules-followup.md
 docs_build/dev/reports/codex_review.diff
 docs_build/dev/reports/playwright_v8_coverage_report.txt
 src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js

docs_build/dev/reports/codex_review.diff

@@ -1,14 +1,14 @@
 Playwright V8 Coverage Report
 
-PR: PR_26163_072-assets-source-upload-reference-details
+PR: PR_26163_073-assets-source-rules-followup
 Coverage source: targeted Playwright/Chromium V8 coverage from tests/playwright/tools/AssetToolMockRepository.spec.mjs.
 Dependencies: no new npm packages.
 Thresholds: none enforced; coverage is advisory.
-Result: WARN only for dev-runtime code that is exercised by tests but not collectible by browser V8 runtime coverage.
+Result: PASS/WARN. Browser runtime coverage was collected for the changed Assets UI module; dev-runtime repository code is covered by assertions and API behavior but is not browser-collected V8 code.
 
 Changed runtime JavaScript files:
-(94%) toolbox/assets/assets.js - covered by targeted Assets Playwright; V8 reported executed lines 704/704 and executed functions 67/71.
+(96%) toolbox/assets/assets.js - covered by targeted Assets Playwright; V8 reported executed lines 725/725 and executed functions 69/72.
 (0%) src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js - WARN: dev-runtime repository code is exercised by Node-side repository assertions and browser behavior through the API adapter, but it is not browser runtime JavaScript collected by Playwright V8 coverage.
 
 Changed non-runtime validation files:
-(0%) tests/playwright/tools/AssetToolMockRepository.spec.mjs - Playwright spec updated for PR072 behavior; test files are not browser runtime coverage targets.
+(0%) tests/playwright/tools/AssetToolMockRepository.spec.mjs - Playwright spec updated for PR073 behavior; test files are not browser runtime coverage targets.

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -48,11 +48,11 @@ export const ASSET_ROLE_DEFINITIONS = Object.freeze([
     extensions: [".json", ".csv", ".txt"],
     mimeTypes: ["application/json", "text/csv", "text/plain"],
     previewBehavior: "Data/Table Tool managed preview",
-    uploadEnabled: false,
-    inputMode: "managed-tool",
+    uploadEnabled: true,
+    inputMode: "file",
     maxSizeBytes: 5242880,
     usageRoles: ["config", "table"],
-    validationNeeds: ["Data/Table Tool required", "Structured data must declare format"]
+    validationNeeds: ["Data files must use .json, .csv, or .txt", "Structured data must declare format"]
   },
   {
     id: "font",
@@ -228,7 +228,7 @@ function normalizeCatalogUsage(value) {
 }
 
 function isReferenceCatalogType(assetType) {
-  return assetType === "Palette References" || assetType === "Data";
+  return assetType === "Sprites" || assetType === "Vectors" || assetType === "Palette References";
 }
 
 function normalizeCatalogSourceMode(value) {
@@ -277,9 +277,6 @@ export function pickerDiagnosticForRole(role, paletteSnapshot = null) {
   if (!role) {
     return "Choose an approved asset role.";
   }
-  if (role.id === "data") {
-    return "Data/Table Tool required.";
-  }
   return `${role.label} file upload ready.`;
 }
 
@@ -1077,6 +1074,16 @@ export function createAssetToolMockRepository(options = {}) {
         label: "File"
       });
     }
+    if (assetType && source === UPLOAD_SOURCE_MODE && fileName) {
+      const role = roleDefinitionForId(catalogAssetRoleForType(assetType));
+      if (role && !extensionMatchesRole(role, fileName)) {
+        findings.push({
+          action: `Choose an approved ${assetType} file: ${role.extensions.join(", ")}.`,
+          field: "fileName",
+          label: "File"
+        });
+      }
+    }
     if (!usage) {
       findings.push({
         action: `Choose a usage: ${ASSET_USAGE_OPTIONS.join(", ")}.`,

src/dev-runtime/persistence/tool-repositories/assets-mock-repository.js

@@ -29,7 +29,7 @@ const USAGE_VALUES = [
 ];
 const UPLOAD_COLUMNS = ["Source", "File", "Usage", "Tags", "Preview", "Actions"];
 const REFERENCE_COLUMNS = ["Source", "Reference", "Usage", "Tags", "Preview", "Actions"];
-const REFERENCE_ASSET_TYPES = new Set(["Palette References", "Data"]);
+const REFERENCE_ASSET_TYPES = new Set(["Sprites", "Vectors", "Palette References"]);
 
 test.beforeEach(async ({ page }) => {
   await installPlaywrightStorageIsolation(page, {
@@ -218,6 +218,39 @@ test("Assets source controls require real upload filenames and valid references"
     await editRow.getByRole("button", { name: "Save" }).click();
     await expect(page.locator("[data-asset-tool-row]").filter({ hasText: "Reference" })).toBeVisible();
 
+    await page.getByRole("button", { name: "Add Data" }).click();
+    editRow = page.locator("[data-asset-tool-editing-row='__new__:Data']");
+    await expect(editRow.getByLabel("Source").locator("option")).toHaveText(["Upload", "Reference"]);
+    await expect(editRow.locator("[data-asset-tool-source-help]")).toContainText(".json, .csv, or .txt");
+    await expect(editRow.getByLabel("Upload File")).toBeVisible();
+    await expect(editRow.getByLabel("Upload File")).toHaveAttribute("accept", /\.json/);
+    await expect(editRow.getByLabel("Upload File")).toHaveAttribute("accept", /\.csv/);
+    await expect(editRow.getByLabel("Upload File")).toHaveAttribute("accept", /\.txt/);
+    await editRow.getByRole("button", { name: "Save" }).click();
+    await expect(page.locator("[data-asset-tool-log]")).toHaveText("Choose an upload file before saving.");
+    await expect(page.locator("[data-asset-tool-count]")).toHaveText("2");
+    for (const fileName of ["source-data.json", "source-data.csv", "source-data.txt"]) {
+      await editRow.getByLabel("Upload File").setInputFiles({
+        buffer: Buffer.from("mock data"),
+        mimeType: "text/plain",
+        name: fileName
+      });
+      await expect(editRow.locator("[data-asset-tool-selected-file]")).toHaveText(fileName);
+    }
+    await editRow.getByLabel("Usage").selectOption("Theme");
+    await editRow.getByRole("button", { name: "Save" }).click();
+    await expect(page.locator("[data-asset-tool-row]").filter({ hasText: "source-data.txt" })).toBeVisible();
+
+    await page.getByRole("button", { name: "Add Data" }).click();
+    editRow = page.locator("[data-asset-tool-editing-row='__new__:Data']");
+    await editRow.getByLabel("Source").selectOption("Reference");
+    await expect(editRow.getByLabel("Reference")).toBeVisible();
+    await expect(editRow.getByLabel("Upload File")).toHaveCount(0);
+    await editRow.getByLabel("Reference").selectOption({ label: "source-data.txt" });
+    await editRow.getByLabel("Usage").selectOption("Interface");
+    await editRow.getByRole("button", { name: "Save" }).click();
+    await expect(page.locator("[data-asset-tool-row]").filter({ hasText: "Reference" }).filter({ hasText: "Interface" })).toBeVisible();
+
     await page.getByRole("button", { name: "Add Audio" }).click();
     editRow = page.locator("[data-asset-tool-editing-row='__new__:Audio']");
     await expect(editRow.getByLabel("Source")).toHaveValue("Upload");
@@ -242,9 +275,28 @@ test("Assets source controls require real upload filenames and valid references"
     await expect(editRow.locator("[data-asset-tool-selected-file]")).toHaveText("source-font.woff2");
     await editRow.getByRole("button", { name: "Cancel" }).click();
 
+    await page.getByRole("button", { name: "Add Sprites" }).click();
+    editRow = page.locator("[data-asset-tool-editing-row='__new__:Sprites']");
+    await expect(editRow.getByLabel("Source")).toHaveValue("Reference");
+    await expect(editRow.getByLabel("Source").locator("option")).toHaveText(["Reference"]);
+    await expect(editRow.getByLabel("Reference")).toBeVisible();
+    await expect(editRow.getByLabel("Upload File")).toHaveCount(0);
+    await expect(editRow.locator("[data-asset-tool-source-help]")).toContainText("Reference-only");
+    await editRow.getByRole("button", { name: "Cancel" }).click();
+
+    await page.getByRole("button", { name: "Add Vectors" }).click();
+    editRow = page.locator("[data-asset-tool-editing-row='__new__:Vectors']");
+    await expect(editRow.getByLabel("Source")).toHaveValue("Reference");
+    await expect(editRow.getByLabel("Source").locator("option")).toHaveText(["Reference"]);
+    await expect(editRow.getByLabel("Reference")).toBeVisible();
+    await expect(editRow.getByLabel("Upload File")).toHaveCount(0);
+    await expect(editRow.locator("[data-asset-tool-source-help]")).toContainText("Reference-only");
+    await editRow.getByRole("button", { name: "Cancel" }).click();
+
     await page.getByRole("button", { name: "Add Palette References" }).click();
     editRow = page.locator("[data-asset-tool-editing-row='__new__:Palette References']");
     await expect(editRow.getByLabel("Source")).toHaveValue("Reference");
+    await expect(editRow.getByLabel("Source").locator("option")).toHaveText(["Reference"]);
     await expect(editRow.getByLabel("Reference")).toBeVisible();
     await expect(editRow.getByLabel("Upload File")).toHaveCount(0);
     await expect(editRow).toContainText("No valid reference source exists.");

tests/playwright/tools/AssetToolMockRepository.spec.mjs

@@ -39,17 +39,26 @@ let editingAssetType = "";
 let selectedAssetId = "";
 const draftAssetValues = new Map();
 const draftTagKeys = new Map();
-const REFERENCE_ONLY_ASSET_TYPES = new Set(["Palette References", "Data"]);
+const REFERENCE_ONLY_ASSET_TYPES = new Set(["Sprites", "Vectors", "Palette References"]);
+const ALWAYS_MIXED_SOURCE_ASSET_TYPES = new Set(["Data"]);
 const UPLOAD_COLUMNS = Object.freeze(["Source", "File", "Usage", "Tags", "Preview", "Actions"]);
 const REFERENCE_COLUMNS = Object.freeze(["Source", "Reference", "Usage", "Tags", "Preview", "Actions"]);
 const UPLOAD_SOURCE = "Upload";
 const REFERENCE_SOURCE = "Reference";
 const UPLOAD_ACCEPT_BY_ASSET_TYPE = Object.freeze({
   Audio: "audio/*,.mp3,.wav,.ogg,.m4a",
+  Data: ".json,.csv,.txt,application/json,text/csv,text/plain",
   Fonts: ".ttf,.otf,.woff,.woff2",
-  Images: "image/*,.png,.jpg,.jpeg,.webp,.gif,.svg",
-  Sprites: "image/*,.png,.jpg,.jpeg,.webp,.gif",
-  Vectors: ".svg,image/svg+xml"
+  Images: "image/*,.png,.jpg,.jpeg,.webp,.gif,.svg"
+});
+const SOURCE_HELP_BY_ASSET_TYPE = Object.freeze({
+  Audio: "Audio can upload a sound file or reference an existing audio source.",
+  Data: "Data can upload .json, .csv, or .txt files, or reference an existing data source.",
+  Fonts: "Fonts upload font files; Reference appears when a font source exists.",
+  Images: "Images can upload an image file or reference an existing image source.",
+  "Palette References": "Palette References must reference a palette swatch.",
+  Sprites: "Sprites are Reference-only for MVP.",
+  Vectors: "Vectors are Reference-only for MVP."
 });
 
 function normalizeText(value) {
@@ -220,6 +229,9 @@ function sourceOptionsForAssetType(assetType, referenceOptions, selectedSource)
   if (isReferenceAssetType(assetType)) {
     return [REFERENCE_SOURCE];
   }
+  if (ALWAYS_MIXED_SOURCE_ASSET_TYPES.has(assetType)) {
+    return [UPLOAD_SOURCE, REFERENCE_SOURCE];
+  }
   if (referenceOptions.length > 0 || selectedSource === REFERENCE_SOURCE) {
     return [UPLOAD_SOURCE, REFERENCE_SOURCE];
   }
@@ -231,6 +243,16 @@ function createSourceSelect(assetType, selectedSource, referenceOptions) {
   return createSelect("Source", "assetToolSourceInput", options, selectedSource);
 }
 
+function createSourceControl(assetType, selectedSource, referenceOptions) {
+  const wrapper = document.createElement("div");
+  wrapper.className = "content-stack content-stack--compact";
+  const help = document.createElement("span");
+  help.dataset.assetToolSourceHelp = "true";
+  help.textContent = SOURCE_HELP_BY_ASSET_TYPE[assetType] || "Choose how this asset source is created.";
+  wrapper.append(createSourceSelect(assetType, selectedSource, referenceOptions), help);
+  return wrapper;
+}
+
 function createFileUploadControl(assetType, selectedFileName) {
   const wrapper = document.createElement("div");
   wrapper.className = "content-stack content-stack--compact";
@@ -373,7 +395,7 @@ function createEditRow(assetType, asset = null, snapshot = {}) {
   }
 
   const sourceCell = document.createElement("td");
-  sourceCell.append(createSourceSelect(assetType, selectedSource, referenceOptions));
+  sourceCell.append(createSourceControl(assetType, selectedSource, referenceOptions));
 
   const detailCell = document.createElement("td");
   if (selectedSource === REFERENCE_SOURCE) {
@@ -603,8 +625,8 @@ function renderMetadata(snapshot) {
     `Tags: ${assetTags(asset).map((tagKey) => tagNameForKey(snapshot.tags || [], tagKey)).join(", ") || "No tags"}`,
     `Stored path: ${asset.storedPath || asset.path}`,
   ];
-  if (isReferenceAssetType(asset.assetType || asset.type)) {
-    metadataLines.splice(1, 0, `Reference: ${assetReference(asset)}`);
+  if (assetSource(asset) === REFERENCE_SOURCE) {
+    metadataLines.splice(1, 0, `Source: ${REFERENCE_SOURCE}`, `Reference: ${assetReference(asset)}`);
   } else {
     metadataLines.splice(1, 0, `Source: ${assetSource(asset)}`, `File: ${assetFile(asset)}`);
   }