Updates to documentation

Author: DavidQ

docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md

@@ -77,7 +77,7 @@
 - [ ] Validate end-to-end parity for the slice (sample load + tool preload + visible content match).
 
 ### Phase 1 - Foundation + One Vertical Slice
-- [.] Add shared adapter guidance document for sample-to-tool loading.
+- [x] Add shared adapter guidance document for sample-to-tool loading.
 - [x] Implement one full reference flow:
 - sample page loads `sample-xxxx.json`
 - same file is passed to tool launch

docs/dev/samples2tools_adapter_guidance.md

@@ -0,0 +1,71 @@
+# Samples2Tools Adapter Guidance
+
+## Purpose
+- Define one shared launch and hydration pattern so a sample preset can load into tools without per-tool URL conventions.
+- Keep the source of truth in sample JSON files (`samples/phase-xx/xxxx/*.json`), not duplicated tool-only payloads.
+
+## Shared Launch Contract
+- Query params:
+- `sampleId=<id>`
+- `samplePresetPath=/samples/phase-xx/xxxx/<tool-or-sample-name>.json`
+- Rules:
+- Reject empty/invalid paths.
+- Normalize path separators to `/`.
+- Reject traversal (`..`) in preset paths.
+- Allow only sample-local/known-safe relative forms.
+
+## Canonical Preset Shape
+- Required:
+- `sampleId`
+- `phase`
+- `title`
+- `description`
+- `toolHints`
+- `payload`
+- Optional:
+- `runtime`
+- `toolState`
+- `provenance`
+
+## Adapter Pattern (Per Tool)
+- Steps:
+1. Read `samplePresetPath` and `sampleId` from `window.location.search`.
+2. Fetch preset JSON with `{ cache: "no-store" }`.
+3. Extract tool-relevant block from `payload` (or fallback to direct tool document shape when intentionally supported).
+4. Validate/minimally sanitize into tool schema.
+5. Apply to tool state.
+6. Emit user status text: `Loaded preset from sample <id>.` (or path fallback).
+
+## Reference Implementations
+- Parallax Scene Studio:
+- `extractParallaxDocumentFromSamplePreset(...)`
+- `tryLoadPresetFromQuery(...)`
+- File: `tools/Parallax Scene Studio/main.js`
+
+- Tilemap Studio:
+- `extractTileMapDocumentFromSamplePreset(...)`
+- `tryLoadPresetFromQuery(...)`
+- File: `tools/Tilemap Studio/main.js`
+
+- Vector Asset Studio:
+- `extractVectorAssetPresetFromSamplePreset(...)`
+- `tryLoadPresetFromQuery(...)`
+- File: `tools/Vector Asset Studio/main.js`
+
+## Data Rules
+- Do not use `imageDataUrl` in persisted sample/tool/workspace JSON.
+- Persist path/file references only (for example `imageName`, `imageSource`, SVG path fields).
+- Keep sample assets local to the sample folder whenever practical.
+
+## Validation Checklist
+- Sample page consumes the same JSON it passes to tools.
+- Tool load succeeds from `samplePresetPath` without manual edits.
+- Tool shows loaded source status with sample id/path.
+- Direct launch (without preset params) still works.
+- No coupling to Phase 20 preset lanes.
+
+## Current Verified Vertical Slice
+- Sample `1208`:
+- shared preset file exists
+- roundtrip links pass `sampleId` + `samplePresetPath`
+- Parallax, Tilemap, and Vector Asset Studio implement query preload adapters