Schema-backed tool/workspace manifest boundary cleanup

- Adds explicit schema contracts for tool/sample/workspace payloads
- Locks sample palette behavior to named palettes
- Keeps workspace-owned assets inside workspace.manifest
- Gates valid UI actions by loaded context

Author: DavidQ

docs/dev/bundle_readme.md

@@ -0,0 +1,12 @@
+# Bundle Contents
+
+This ZIP is repo-structured and contains docs-first PR instructions only.
+
+Files:
+
+- `docs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+- `docs/dev/next_command.txt`
+
+No implementation code is included.

docs/dev/codex_commands.md

@@ -1 +1,73 @@
-Run via your standard injected rules workflow.
+# BUILD_PR: Codex Execution Notes
+
+## Model
+
+GPT-5.4 or GPT-5.3-codex
+
+## Reasoning
+
+High
+
+## Codex Command
+
+```bash
+codex
+```
+
+## Task
+
+Implement the PLAN_PR in `docs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md`.
+
+## Constraints
+
+- Smallest valid change.
+- One PR purpose only.
+- Docs-first schema/manifest boundary cleanup.
+- Do not modify `start_of_day`.
+- Do not delete preserved legacy folders.
+- Do not write broad custom validation code where `*.schema` files can define the contract.
+- Preserve existing sample behavior.
+- Samples must use named palettes only and remain locked.
+- Workspaces must use duplicated palettes and enforce used-palette replacement restrictions.
+- Workspace assets must live in `workspace.manifest`; only rendered/exportable artifacts such as PNG files may be saved separately.
+
+## Suggested Implementation Order
+
+1. Inventory only the specific files referencing:
+   - `buildDefaultPayload`
+   - 3D camera path editor payload setup
+   - 3D JSON payload normalizer
+   - viewer asset save/export paths
+   - workspace/sample manifest loading
+   - palette mutation rules
+2. Add schema files near the owning tool or manifest contract.
+3. Wire sample tool payloads to validate/load through the same tool schema.
+4. Wire workspace manifest validation through `workspace.manifest` schema.
+5. Centralize button/action enablement by loaded context:
+   - tool context
+   - workspace context
+6. Add/update minimal tests or fixtures proving:
+   - sample palette lock
+   - workspace palette duplication
+   - used swatch replacement protection
+   - workspace-owned assets persisted in manifest
+   - PNG export still works
+7. Update roadmap/status markers only if the repo has an active roadmap file for this phase.
+
+## Test Commands
+
+Use the repo’s existing test commands. If none exist, run the smallest available smoke checks:
+
+```bash
+npm test
+npm run build
+```
+
+If the repo does not use npm for this area, document the actual commands run in the PR notes.
+
+## Required Output From Codex
+
+- List changed files.
+- List tests run.
+- Note any compatibility shims left in place.
+- Note any old references that were intentionally preserved.

docs/dev/commit_comment.txt

@@ -1 +1,6 @@
-Enforce extended anti-pattern rules in codex_rules.md
+Schema-backed tool/workspace manifest boundary cleanup
+
+- Adds explicit schema contracts for tool/sample/workspace payloads
+- Locks sample palette behavior to named palettes
+- Keeps workspace-owned assets inside workspace.manifest
+- Gates valid UI actions by loaded context

docs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md

@@ -0,0 +1,78 @@
+# PLAN_PR: Tool / Workspace Schema + Manifest Boundary Cleanup
+
+## Purpose
+
+Make tool data, sample data, workspace data, palette rules, and valid UI actions explicit through schemas and manifests instead of scattered validation code or hidden payload builders.
+
+## Scope
+
+One PR only:
+
+- Remove/replace remaining dependency paths around:
+  - `buildDefaultPayload`
+  - 3D Camera Path Editor legacy payload assumptions
+  - 3D JSON payload normalizer legacy assumptions
+  - Viewer assets being separately saved/exported outside manifests
+- Introduce actual `*.schema` files for tool/workspace/sample payload validation.
+- Clarify palette behavior:
+  - Samples use named palettes only.
+  - Samples are locked and cannot mutate palettes.
+  - Workspaces use duplicated palettes.
+  - Once a workspace palette swatch is used, that palette cannot be replaced with a different palette.
+  - Used workspace palettes may allow swatch edits only.
+  - Other palettes may be viewed for reference/copying swatches into the selected workspace palette.
+- Put all workspace-owned assets in `workspace.manifest`.
+- Allow only exportable/rendered artifacts such as PNG files to be saved/exported outside the manifest.
+- Ensure UI buttons/actions are enabled by loaded context:
+  - Tool-loaded context enables only tool-valid actions.
+  - Workspace-loaded context enables only workspace-valid actions.
+
+## Non-Goals
+
+- Do not rewrite tool implementations.
+- Do not change sample runtime behavior except where required to load schema-backed data.
+- Do not modify `start_of_day` folders.
+- Do not delete legacy folders unless explicitly approved.
+- Do not add repo-wide validation frameworks if smaller local schema files are enough.
+- Do not implement new editor features beyond the boundary cleanup.
+
+## Desired Manifest Shape
+
+Workspace:
+
+```json
+{
+  "palette": {},
+  "tools": {
+    "<tool>": {
+      "tool data": {}
+    }
+  }
+}
+```
+
+Sample tool payload files:
+
+```json
+{
+  "<tool>": {
+    "tool data": {}
+  }
+}
+```
+
+The sample payload shape should match the same tool schema used by the tool manifest loader.
+
+## Acceptance Criteria
+
+- `buildDefaultPayload` is no longer required for current tool/sample/workspace loading paths, or it is reduced to a compatibility shim with clear deprecation comments.
+- Each active tool has a dedicated schema file.
+- Workspace manifest has a schema file.
+- Sample tool payloads validate against the same schema used by the corresponding tool.
+- Viewer/vector assets that belong to a workspace are stored inside `workspace.manifest`.
+- PNG or rendered output remains exportable outside the manifest.
+- Samples are locked to named palettes and cannot mutate palette data.
+- Workspaces duplicate palettes and enforce swatch-use locking rules.
+- UI action availability is derived from loaded context and schema capabilities, not hard-coded workspace/tool assumptions.
+- Existing samples continue to load.
+- `samples/index.html` is updated only if sample entries are changed.

tests/run-tests.mjs

@@ -96,6 +96,7 @@ import { run as runAssetUsageIntegration } from './tools/AssetUsageIntegration.t
 import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem.test.mjs';
 import { run as runToolBoundaryEnforcement } from './tools/ToolBoundaryEnforcement.test.mjs';
 import { run as runProjectToolDataContracts } from './tools/ProjectToolDataContracts.test.mjs';
+import { run as runToolWorkspaceSchemaManifestBoundaries } from './tools/ToolWorkspaceSchemaManifestBoundaries.test.mjs';
 import { run as runAssetPipelineTooling } from './tools/AssetPipelineTooling.test.mjs';
 import { run as runAssetOwnershipStrategyCloseout } from './tools/AssetOwnershipStrategyCloseout.test.mjs';
 import { run as runAssetErrorHandlingStandard } from './tools/AssetErrorHandlingStandard.test.mjs';
@@ -234,6 +235,7 @@ const tests = [
     ['AssetRemediationSystem', runAssetRemediationSystem],
     ['ToolBoundaryEnforcement', runToolBoundaryEnforcement],
     ['ProjectToolDataContracts', runProjectToolDataContracts],
+    ['ToolWorkspaceSchemaManifestBoundaries', runToolWorkspaceSchemaManifestBoundaries],
     ['AssetPipelineTooling', runAssetPipelineTooling],
     ['AssetOwnershipStrategyCloseout', runAssetOwnershipStrategyCloseout],
     ['AssetErrorHandlingStandard', runAssetErrorHandlingStandard],

tests/tools/ToolWorkspaceSchemaManifestBoundaries.test.mjs

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import {
+  createDefaultCameraPathPayload,
+  validateCameraPathPayload
+} from "../../tools/3D Camera Path Editor/cameraPathPayload.schema.js";
+import {
+  createDefaultMapPayload,
+  validateMapPayload
+} from "../../tools/3D JSON Payload Normalizer/mapPayload.schema.js";
+import {
+  createDefaultAssetPayload,
+  validateAssetPayload
+} from "../../tools/3D Asset Viewer/assetPayload.schema.js";
+import {
+  validateWorkspaceManifestSchema,
+  WORKSPACE_MANIFEST_SCHEMA,
+  WORKSPACE_MANIFEST_VERSION,
+  WORKSPACE_DOCUMENT_KIND
+} from "../../tools/shared/workspaceManifest.schema.js";
+
+export async function run() {
+  const cameraValidation = validateCameraPathPayload(createDefaultCameraPathPayload(), {
+    requireSchema: true,
+    requireWaypoints: true
+  });
+  assert.equal(cameraValidation.valid, true, cameraValidation.issues.join(" "));
+
+  const mapValidation = validateMapPayload(createDefaultMapPayload(), {
+    requireSchema: true,
+    requirePoints: true
+  });
+  assert.equal(mapValidation.valid, true, mapValidation.issues.join(" "));
+
+  const assetValidation = validateAssetPayload(createDefaultAssetPayload(), {
+    requireSchema: true,
+    requireVertices: true
+  });
+  assert.equal(assetValidation.valid, true, assetValidation.issues.join(" "));
+
+  const workspaceManifest = {
+    documentKind: WORKSPACE_DOCUMENT_KIND,
+    schema: WORKSPACE_MANIFEST_SCHEMA,
+    version: WORKSPACE_MANIFEST_VERSION,
+    id: "workspace-test",
+    name: "Workspace Test",
+    tools: {
+      "3d-asset-viewer": {
+        schema: "tools.3d-asset-viewer.asset/1",
+        assetId: "asset-test",
+        vertices: [{ x: 0, y: 0, z: 0 }]
+      }
+    },
+    sharedLibrary: {
+      assets: [
+        {
+          id: "asset-test",
+          type: "vector",
+          displayName: "Asset Test",
+          sourcePath: "/games/Test/assets/vectors/asset-test.vector.json",
+          sourceToolId: "3d-asset-viewer"
+        }
+      ],
+      palettes: []
+    },
+    exportArtifacts: [
+      {
+        kind: "png",
+        path: "/games/Test/exports/asset-preview.png",
+        sourceToolId: "3d-asset-viewer"
+      }
+    ]
+  };
+  const workspaceValidation = validateWorkspaceManifestSchema(workspaceManifest);
+  assert.equal(workspaceValidation.valid, true, workspaceValidation.issues.join(" "));
+
+  const invalidWorkspaceValidation = validateWorkspaceManifestSchema({
+    ...workspaceManifest,
+    externalAssets: ["/games/Test/assets/outside-manifest.asset.json"],
+    exportArtifacts: [{ kind: "jpg", path: "/games/Test/exports/asset-preview.jpg" }]
+  });
+  assert.equal(invalidWorkspaceValidation.valid, false);
+  assert.equal(
+    invalidWorkspaceValidation.issues.some((issue) => issue.includes("workspace.manifest")),
+    true
+  );
+  assert.equal(
+    invalidWorkspaceValidation.issues.some((issue) => issue.includes(".png")),
+    true
+  );
+
+  const paletteBrowserSource = readFileSync(new URL("../../tools/Palette Browser/main.js", import.meta.url), "utf8");
+  assert.match(paletteBrowserSource, /function duplicateSelectedPalette\(/);
+  assert.match(paletteBrowserSource, /createCustomPalette\(nextName, palette\.entries\)/);
+  assert.match(paletteBrowserSource, /Duplicate a built-in palette before editing swatches\./);
+  assert.match(paletteBrowserSource, /Shared palette is locked to .*Edit swatches instead\./);
+  assert.match(paletteBrowserSource, /if \(isReadOnlyPalette\(palette\)\) \{\s*return;\s*\}/s);
+
+  const spriteEditorSource = readFileSync(new URL("../../tools/Sprite Editor/modules/spriteEditorApp.js", import.meta.url), "utf8");
+  assert.match(spriteEditorSource, /image\/png/);
+  assert.match(spriteEditorSource, /sprite-frame-.*\.png/);
+  assert.match(spriteEditorSource, /sprite-sheet-.*\.png/);
+}

tools/3D Asset Viewer/assetPayload.schema.js

@@ -0,0 +1,87 @@
+export const ASSET_VIEWER_PAYLOAD_SCHEMA = "tools.3d-asset-viewer.asset/1";
+export const ASSET_VIEWER_REPORT_SCHEMA = "tools.3d-asset-viewer.report/1";
+
+function sanitizeNumber(value, fallback = 0) {
+  const numeric = Number(value);
+  if (Number.isNaN(numeric) || numeric === Infinity || numeric === -Infinity) {
+    return fallback;
+  }
+  return numeric;
+}
+
+function toObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeVertex(rawVertex) {
+  const vertex = toObject(rawVertex);
+  return {
+    x: sanitizeNumber(vertex.x),
+    y: sanitizeNumber(vertex.y),
+    z: sanitizeNumber(vertex.z)
+  };
+}
+
+export function createDefaultAssetPayload() {
+  return {
+    schema: ASSET_VIEWER_PAYLOAD_SCHEMA,
+    assetId: "ship-hull",
+    vertices: [
+      { x: -1, y: -0.5, z: -2 },
+      { x: 1, y: -0.5, z: -2 },
+      { x: 0, y: 0.75, z: 2 }
+    ],
+    metadata: {
+      sourceToolId: "vector-asset-studio"
+    }
+  };
+}
+
+export function normalizeAssetPayload(rawPayload, options = {}) {
+  const source = toObject(rawPayload);
+  const fallbackAssetId = typeof options.fallbackAssetId === "string" && options.fallbackAssetId.trim()
+    ? options.fallbackAssetId.trim()
+    : "asset-3d";
+  const vertices = Array.isArray(source.vertices)
+    ? source.vertices.map((vertex) => normalizeVertex(vertex))
+    : [];
+  return {
+    schema: ASSET_VIEWER_PAYLOAD_SCHEMA,
+    assetId: typeof source.assetId === "string" && source.assetId.trim() ? source.assetId.trim() : fallbackAssetId,
+    vertices,
+    metadata: source.metadata && typeof source.metadata === "object" ? { ...source.metadata } : {}
+  };
+}
+
+export function validateAssetPayload(rawPayload, options = {}) {
+  const source = toObject(rawPayload);
+  const issues = [];
+  const requireSchema = options.requireSchema !== false;
+  const requireVertices = options.requireVertices === true;
+  const payload = normalizeAssetPayload(source, options);
+
+  if (requireSchema) {
+    const schemaValue = typeof source.schema === "string" ? source.schema.trim() : "";
+    if (!schemaValue) {
+      issues.push(`3D asset schema is required (${ASSET_VIEWER_PAYLOAD_SCHEMA}).`);
+    } else if (schemaValue !== ASSET_VIEWER_PAYLOAD_SCHEMA) {
+      issues.push(`3D asset schema must be ${ASSET_VIEWER_PAYLOAD_SCHEMA}.`);
+    }
+  }
+
+  if (!Array.isArray(source.vertices)) {
+    issues.push("3D asset vertices must be an array.");
+  } else if (requireVertices && source.vertices.length === 0) {
+    issues.push("3D asset payload requires at least one vertex.");
+  }
+
+  if (!payload.assetId) {
+    issues.push("3D asset assetId is required.");
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    payload
+  };
+}