@reqvire-org/ads 0.3.5 → 0.3.7

package/dist/mcp/mutations.mjs

@@ -13,7 +13,7 @@ import { projectContext } from "./context.mjs";
 import { applyFilePatch, parseUnifiedPatch } from "./patch.mjs";
 import { checkUnitCandidate, checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
 
-export const mutationLimits = { files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
+export const mutationLimits = { units: 8, files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
 const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 const ignored = new Set([".git", ".ds", "node_modules", ".vite", "coverage", ".playwright-cli", "test-results", "output"]);
 const textFile = file => /\.(?:[cm]?[jt]sx?|css|html|jsonc?|md|txt|svg)$/.test(file);
@@ -29,7 +29,7 @@ function address(options, file) {
   if (!isInside(options.root, target) || target === options.root) throw fail("mutation-path", "Mutation paths must stay inside the project.", file);
   for (let current = options.root; ; ) {
     const relative = path.relative(current, target).split(path.sep);
-    if (relative.some(part => ignored.has(part) || part.startsWith(".") && !setupDotfile(part))) throw fail("mutation-path", "Hidden, dependency and generated paths are not editable.", file);
+    if (relative.some(part => ignored.has(part) || part.startsWith(".") && !setupDotfile(part) && !(part === ".gitkeep" && path.basename(target) === part && isInside(options.dsRoot, target)))) throw fail("mutation-path", "Hidden, dependency and generated paths are not editable.", file);
     current = path.join(current, relative[0]);
     const stat = lstatSync(current, { throwIfNoEntry: false });
     if (stat?.isSymbolicLink() || stat && current !== target && !stat.isDirectory() || stat && current === target && (!stat.isFile() || stat.nlink !== 1)) throw fail("mutation-path", "Mutation paths must contain ordinary directories and unlinked regular files.", file);
@@ -154,7 +154,7 @@ export function createMutationController(directory) {
       let commands = [], diagnostics = [];
       try { commands = checks(options).map(check => [check.command, ...check.args].join(" ")); }
       catch (error) { diagnostics = [error.diagnostic ?? { rule: "mutation-check", message: error.message }]; }
-      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
+      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", transactions:{tool:"ads_apply_transaction",maxUnits:mutationLimits.units,finalCandidateChecks:true}, preparation:{owner:"ads_prepare_patch",tokenSamples:"ads_prepare_token_samples"}, dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
     },
     cancel() { active?.abort(); },
     units() { return inspectUnits(loadConfig(root)).units; },
@@ -170,7 +170,7 @@ export function createMutationController(directory) {
       return { ...source, unit, content, offset, nextOffset: end < source.content.length ? end : null, totalChars: source.content.length,
         startLine: source.content.slice(0, offset).split("\n").length };
     },
-    async apply({ unit, patch, patchFile, dryRun = false }, signal) {
+    async apply({ unit, patch, patchFile, patches, dryRun = false }, signal) {
       if (busy) return { ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes." }] };
       busy = true;
       active = new AbortController();
@@ -179,26 +179,22 @@ export function createMutationController(directory) {
       const verified = [];
       try {
         const options = loadConfig(root);
-        validateUnitId(unit);
-        if ((typeof patch === "string") === (typeof patchFile === "string")) throw fail("mutation-patch", "Provide exactly one of patch or patchFile.");
-        const maxPatch = patchFile === undefined ? mutationLimits.patchBytes : mutationLimits.patchFileBytes;
-        if (patchFile !== undefined) patch = readPatchFile(options, patchFile);
-        if (typeof patch !== "string" || patch.includes("\0") || Buffer.from(patch).toString("utf8") !== patch || Buffer.byteLength(patch) > maxPatch) throw fail("mutation-patch", "Patch exceeds its UTF-8 Git diff size limit.");
-        const entries = parseUnifiedPatch(patch, mutationLimits.files), changes = [];
-        const originals = entries.map(entry => {
-          const change = { path: entry.path };
-          const target = address(options, change.path);
-          const before = read(options, change.path);
-          if (!entry.binary && before.binary) throw fail("mutation-patch", "Binary assets require a git diff --binary patch.", change.path);
-          change.content = entry.binary ? entry.operation === "delete" ? null : before.content ?? Buffer.alloc(0) : applyFilePatch(entry, before.content);
-          if (entry.binary) change.binaryPatch = entry.patch;
-          change.expectedDigest = before.digest;
-          change.originalContent = before.content;
-          if (!entry.binary) validateContent(change, unit);
-          changes.push(change);
-          return { ...before, mode: before.exists ? lstatSync(target).mode : undefined };
+        if (patches !== undefined && (unit !== undefined || patch !== undefined || patchFile !== undefined || !Array.isArray(patches) || patches.length < 2 || patches.length > mutationLimits.units)) throw fail("mutation-batch", "A transaction requires 2–8 distinct owner patches, without a top-level unit/patch.");
+        const groups = patches ?? [{unit,patch,patchFile}];
+        if (new Set(groups.map(group => group.unit)).size !== groups.length) throw fail("mutation-batch", "Use one patch per distinct unit in a transaction.");
+        let patchBytes = 0;
+        const plans = groups.map(group => {
+          validateUnitId(group.unit);
+          if ((typeof group.patch === "string") === (typeof group.patchFile === "string")) throw fail("mutation-patch", "Provide exactly one of patch or patchFile for each owner.");
+          const value = group.patchFile === undefined ? group.patch : readPatchFile(options,group.patchFile);
+          const maxPatch = group.patchFile === undefined ? mutationLimits.patchBytes : mutationLimits.patchFileBytes;
+          patchBytes += Buffer.byteLength(value ?? "");
+          if (typeof value !== "string" || value.includes("\0") || Buffer.from(value).toString("utf8") !== value || Buffer.byteLength(value) > maxPatch || patchBytes > mutationLimits.patchFileBytes) throw fail("mutation-patch", "Patch exceeds its UTF-8 Git diff size limit.");
+          return {unit:group.unit,entries:parseUnifiedPatch(value,mutationLimits.files)};
         });
-        const inventory = checkUnitFiles(options, unit, changes, inspectUnits(options), true);
+        const units = groups.map(group => group.unit), configuration = units.includes("configuration"), assets = units.some(unit => unit.startsWith("assets"));
+        for (const plan of plans) for (const entry of plan.entries) address(options,entry.path);
+        const changes = [], originals = [], byPath = new Map();
         const cache = path.join(root, ".ds");
         mkdirSync(cache, { recursive: true });
         if (realpathSync(cache) !== path.join(realpathSync(root), ".ds")) throw fail("mutation-path", "The .ds directory cannot resolve through a symlink.");
@@ -206,7 +202,6 @@ export function createMutationController(directory) {
         const candidate = path.join(temporary, "project");
         mkdirSync(candidate);
         const before = snapshot(options, candidate);
-        for (const original of originals) if (read(options, original.path).digest !== original.digest) throw fail("mutation-conflict", "Source changed while preparing the validation copy. Read the affected range and regenerate the patch.", original.path);
         const dependencies = path.join(root, "node_modules");
         if (!existsSync(dependencies)) throw fail("mutation-check", "Install project dependencies before using guarded mutations.");
         symlinkSync(realpathSync(dependencies), path.join(candidate, "node_modules"), process.platform === "win32" ? "junction" : "dir");
@@ -222,24 +217,45 @@ export function createMutationController(directory) {
             return true;
           } });
         }
+        const entries = plans.flatMap(plan => plan.entries);
         if (entries.some(entry => entry.binary)) {
           const formats = new Set(entries.filter(entry=>entry.binary).map(entry=>entry.objectFormat));
           if (formats.size !== 1) throw fail("mutation-patch", "Binary blocks in one Git diff must use the same object format.");
           await checkCommand("git", ["init", "--quiet", `--object-format=${[...formats][0]}`, candidate], root, signal);
         }
-        for (const change of changes) {
-          const file = path.join(candidate, change.path);
-          if (change.binaryPatch) {
-            for (const match of change.binaryPatch.matchAll(/^(?:literal|delta) (\d+)$/gm)) if (Number(match[1]) > mutationLimits.fileBytes) throw fail("mutation-content", "Binary patch blocks exceed 16 MiB.", change.path);
-            await checkCommand("git", ["apply", "--binary", "--whitespace=nowarn", "-"], candidate, signal, change.binaryPatch);
-            change.content = existsSync(file) ? readFileSync(file) : null;
-            validateContent(change, unit);
+        for (const plan of plans) {
+          const current = loadConfig(candidate), selected = plan.entries.map(entry => {
+            address(options,entry.path);
+            const before = read(current,entry.path);
+            if (!entry.binary && before.binary) throw fail("mutation-patch", "Binary assets require a git diff --binary patch.", entry.path);
+            const change = {path:entry.path, originalContent:before.content, content:entry.binary ? entry.operation === "delete" ? null : before.content ?? Buffer.alloc(0) : applyFilePatch(entry,before.content), ...(entry.binary ? {binaryPatch:entry.patch} : {})};
+            if (!entry.binary) validateContent(change,plan.unit);
+            if (!byPath.has(entry.path)) {
+              const original = read(options,entry.path);
+              // The candidate copy and live inputs must agree before any changes.
+              if (original.digest !== before.digest) throw fail("mutation-conflict", "Source changed while preparing validation; regenerate the patch.", entry.path);
+              originals.push({...original,mode:original.exists ? lstatSync(address(options,entry.path)).mode : undefined});
+              byPath.set(entry.path,changes.length);
+              changes.push({...change,expectedDigest:original.digest});
+              if (changes.length > mutationLimits.files) throw fail("mutation-batch", "A transaction may change at most 32 distinct files.");
+            }
+            return change;
+          });
+          const inventory = checkUnitFiles(current,plan.unit,selected,inspectUnits(current),true);
+          for (const change of selected) {
+            const file = path.join(candidate,change.path);
+            if (change.binaryPatch) {
+              for (const match of change.binaryPatch.matchAll(/^(?:literal|delta) (\d+)$/gm)) if (Number(match[1]) > mutationLimits.fileBytes) throw fail("mutation-content", "Binary patch blocks exceed 16 MiB.", change.path);
+              await checkCommand("git",["apply","--binary","--whitespace=nowarn","-"],candidate,signal,change.binaryPatch);
+              change.content = existsSync(file) ? readFileSync(file) : null;
+              validateContent(change,plan.unit);
+            } else if (change.content === null) rmSync(file);
+            else {mkdirSync(path.dirname(file),{recursive:true});writeFileSync(file,change.content);}
+            changes[byPath.get(change.path)].content = change.content;
           }
-          else if (change.content === null) rmSync(file);
-          else { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, change.content); }
+          checkUnitCandidate(loadConfig(candidate),plan.unit,selected,inventory);
         }
         const candidateOptions = loadConfig(candidate);
-        checkUnitCandidate(candidateOptions, unit, changes, inventory);
         const extraChecks = checks(candidateOptions);
         const expected = snapshot(candidateOptions);
         const result = checkProject(candidate, { trackingRoot: root });
@@ -251,12 +267,12 @@ export function createMutationController(directory) {
         const bin = JSON.parse(readFileSync(oxlintPackage, "utf8")).bin;
         const executable = path.resolve(path.dirname(oxlintPackage), typeof bin === "string" ? bin : bin.oxlint);
         const lintPaths = [candidateOptions.config.sourceDir, candidateOptions.config.dsDir].filter(file => existsSync(path.join(candidate, file)));
-        if (unit === "configuration") for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
+        if (configuration) for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
           if (/\.[cm]?[jt]sx?$/.test(file) && !lintPaths.some(directory => isInside(path.resolve(candidate, directory), path.resolve(candidate, file)))) lintPaths.push(file);
         }
         await checkCommand(process.execPath, [executable, "--deny-warnings", "--config", lintConfig, ...lintPaths], candidate, signal);
         verified.push({ name: "registered Oxlint rules", passed: true });
-        if (unit.startsWith("assets") || unit === "configuration") {
+        if (assets || configuration) {
           const brand = await generateBrandAssets(candidate);
           verified.push({ name: "brand assets", passed: true, skipped: !!brand.skipped });
         }
@@ -300,8 +316,8 @@ export function createMutationController(directory) {
           }
         }
         const warnings = [];
-        if (!dryRun && (unit.startsWith("assets") || unit === "configuration")) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
-        return lastResult = { ok: true, unit, applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
+        if (!dryRun && (assets || configuration)) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
+        return lastResult = { ok: true, ...(patches ? {units,transaction:true} : {unit}), applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
           preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
       } catch (error) {
         return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };

package/dist/mcp/preview-watch.mjs

@@ -4,6 +4,7 @@ import { statSync, mkdirSync, writeFileSync, renameSync, rmSync, realpathSync }
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildFailure, inspectBuildStatus } from "./build-status.mjs";
+import { previewSessionDirectories, withPreviewSession } from "../preview-scope.mjs";
 
 function stamp(file) {
   try { const stat = statSync(file); return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`; }
@@ -160,23 +161,27 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   }
 
   const status = () => ({ state, ...(stalled ? { stalled: true } : {}), ...(child?.pid ? { pid: child.pid } : {}), ...(ownerGuard?.pid ? { guardPid: ownerGuard.pid } : {}), ...(error ? { error } : {}) });
-  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, file: reportFile, processState: status() } : {});
+  const resourceSession = () => command && config.previewManifest ? session : undefined;
+  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, previewSession: resourceSession(), file: reportFile, processState: status() } : {});
+  function clearOutput() {
+    for (const directory of previewSessionDirectories(withPreviewSession({ root, config: { mcp: config } }, resourceSession()))) rmSync(directory, { recursive: true, force: true });
+  }
 
   async function stopChild() {
     rmSync(requestFile, { force: true });
     if (stopping) return stopping;
-    if (!child || childClosed) { if (command) state = "stopped"; rmSync(reportFile, { force: true }); return; }
+    if (!child || childClosed) { if (command) state = "stopped"; rmSync(reportFile, { force: true }); clearOutput(); return; }
     if (state === "stopped") return;
     state = "stopping";
     stopping = (async () => {
       kill("SIGTERM");
       clearTimeout(killTimer);
       const timer = setTimeout(() => kill("SIGKILL"), 1500);
-      try { await closed; } finally { clearTimeout(timer); rmSync(reportFile, { force: true }); }
+      try { await closed; } finally { clearTimeout(timer); rmSync(reportFile, { force: true }); clearOutput(); }
     })();
     return stopping;
   }
-  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
+  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, resourceSession, buildStatus, setApps(apps) {
     for (const app of apps) {
       const file = path.resolve(root, app.file);
       if (!baselines.has(file)) baselines.set(file, stamp(file));
@@ -195,6 +200,7 @@ export function createReconfigurablePreviewWatch(root, config, options) {
     start() { if (!stopped && !replacing) current.start(); },
     async ensure(file, signal) { await pending; if (stopped) throw new Error("Preview watcher is stopped."); return current.ensure(file, signal); },
     status() { return replacing ? { state: "reconfiguring" } : current.status(); },
+    resourceSession() { return current.resourceSession(); },
     buildStatus() { return current.buildStatus(); },
     setApps(next) { apps = next; current.setApps(next); },
     kill() { current.kill(); },

package/dist/mcp/server.mjs

@@ -13,11 +13,14 @@ import { createSkillStore, page, SKILLS_EXTENSION } from "./skills.mjs";
 import { inspectCatalog, projectDocuments, PROJECT_URI, readProjectDocument } from "./catalog.mjs";
 import { APP_MIME, appMetadata, appUri, projectApp, TOKENS_APP_URI, tokensApp, tokenWidgetData, SCENARIO_APP_URI, scenarioApp, previewApp, PREVIEW_APP_URI } from "./apps.mjs";
 import { PREVIEW_MANIFEST_URI, readPreviewManifest, readPreviewAsset } from "../preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 import { getWorkflowPrompt, promptDefinitions } from "./prompts.mjs";
 import { createReconfigurablePreviewWatch } from "./preview-watch.mjs";
 import { BUILD_URI, buildFailure, inspectBuildStatus, summarizeBuild } from "./build-status.mjs";
 import { GUIDE_URI, projectContext, projectGuide, serverInstructions, workflow } from "./context.mjs";
 import { createMutationController, mutationLimits } from "./mutations.mjs";
+import { prepareUnitPatch, storePreparedPatch } from "./edit-preparation.mjs";
+import { reconcileTokenSamples } from "../token-fixtures.mjs";
 
 const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 class InvalidParamsError extends ProtocolError {
@@ -28,6 +31,7 @@ const empty = z.object({}).strict();
 const query = z.object({ query: z.string().max(200).optional(), limit: z.number().int().min(1).max(50).default(20) }).strict();
 const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 const schemas = { params: z.object({ cursor: z.string().optional() }).passthrough(), result: z.object({ resultType: z.literal("complete") }).passthrough() };
+const ownerPatch = z.object({ unit: z.string().min(1).max(256), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile.");
 
 export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollInterval = 1000, previewWatch, showcaseUrl, notifications, inspection, mutations = false } = {}) {
   const root = path.resolve(directory);
@@ -54,13 +58,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const tokenScenarios = () => getRegistry().scenarios.filter(item => item.kind === "tokens").map(item => ({ id: item.id, title: item.title, count: item.tokens.length }));
   const allApps = () => [...options.config.mcp.apps, ...scenarioApps()];
   const scenarioWidget = () => options.config.mcp.previewManifest ? PREVIEW_APP_URI : SCENARIO_APP_URI;
+  const previewOptions = () => withPreviewSession(options, previewWatch?.resourceSession?.());
   const resourceAssets = () => {
-    try { return Object.entries(readPreviewManifest(options)?.assets ?? {}).map(([uri, record]) => ({ uri, name: `Preview asset ${uri.slice("ads://assets/".length)}`, mimeType: record.mimeType, size: record.size })); }
+    try { return Object.entries(readPreviewManifest(previewOptions())?.assets ?? {}).map(([uri, record]) => ({ uri, name: `Preview asset ${uri.slice("ads://assets/".length)}`, mimeType: record.mimeType, size: record.size })); }
     catch { return []; } // Discovery and diagnostics remain usable after a failed graph.
   };
   function graphSelection(id) {
     if (!options.config.mcp.previewManifest) return {};
-    const manifest = readPreviewManifest(options);
+    const manifest = readPreviewManifest(previewOptions());
     if (!manifest?.scenarios.some(entry => entry.id === id)) throw new Error("The preview resource graph is not ready for this scenario. Rebuild previews.");
     return { manifestUri: PREVIEW_MANIFEST_URI, manifestRevision: manifest.revision };
   }
@@ -80,6 +85,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
       { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
+      { uri: "ads://guides/atomic-styles", name: "Atomic style composition: conflicts, prevention and fixes", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
       { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
@@ -87,13 +93,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       { uri: `${PROJECT_URI}/scenarios`, name: "Independently mountable scenarios", mimeType: "application/json" },
       { uri: BEHAVIOR_URI, name: "Behavior contracts, demonstrations and current verification evidence", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
+      ...documents.filter(document => promoted.has(document.uri)).sort((a, b) => Number(b.uri === context.publicEntryUri) - Number(a.uri === context.publicEntryUri)).map(({ file: _file, ...document }) => document),
       { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
       { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
       ...(options.config.mcp.previewManifest ? [{ uri: PREVIEW_APP_URI, name: "Shared-resource preview App", mimeType: APP_MIME }, { uri: PREVIEW_MANIFEST_URI, name: "Preview dependency graph", mimeType: "application/json" }] : []),
       ...(options.config.mcp.previewManifest ? resourceAssets() : []),
       ...allApps().map((app) => ({ uri: appUri(app.id), name: app.title, description: app.description, mimeType: APP_MIME })),
       ...skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description, mimeType: "text/markdown" })),
-      ...documents.filter((document) => promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...documents.filter((document) => !promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...[...skills.files.values()].filter((file) => !skillEntries.has(file.uri)).map(({ uri, name, mimeType }) => ({ uri, name, mimeType })),
     ];
@@ -116,6 +122,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   async function read(uri, signal) {
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
     if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/atomic-styles") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/atomic-styles.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -126,7 +133,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     else if (uri === `${PROJECT_URI}/checks`) value = checkProject(root);
     else if (uri === BEHAVIOR_URI) value = behaviorStatus(options);
     else if (uri === PREVIEW_MANIFEST_URI && options.config.mcp.previewManifest) {
-      value = readPreviewManifest(options);
+      value = readPreviewManifest(previewOptions());
       if (!value) throw new Error("Preview resources are not built yet. Invoke ads_show_scenario to start the managed compiler.");
     }
     if (value !== undefined) return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(value) }] };
@@ -134,7 +141,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     if (uri === SCENARIO_APP_URI) return { contents: [{ uri, mimeType: APP_MIME, text: scenarioApp(), _meta: appMetadata({ nested: true }) }] };
     if (uri === PREVIEW_APP_URI && options.config.mcp.previewManifest) return { contents: [{ uri, mimeType: APP_MIME, text: previewApp(), _meta: appMetadata() }] };
     if (uri.startsWith("ads://assets/") && options.config.mcp.previewManifest) {
-      try { return { contents: [readPreviewAsset(options, uri)] }; }
+      try { return { contents: [readPreviewAsset(previewOptions(), uri)] }; }
       catch (error) { if (error.code === "ADS_PREVIEW_NOT_FOUND") throw new ResourceNotFoundError(uri, error.message); throw error; }
     }
     const app = allApps().find((entry) => appUri(entry.id) === uri);
@@ -157,6 +164,16 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return build;
   }
 
+  async function applyEdits(args,signal) {
+    const result = await edits.apply(args,signal);
+    if (result.applied) {
+      try {
+        if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration" || result.units?.includes("configuration")) await previewWatch?.reconfigure?.(loadConfig(root).config.mcp,true);
+        await refresh(true);
+      } catch (error) {result.warnings=[...(result.warnings ?? []),{rule:"mutation-notification",message:`Changes were applied, but preview refresh failed: ${error.message.slice(0,2000)}. Recheck ads_status and reopen the scenario.`}];}
+    }
+    return {...json(result),...(!result.ok ? {isError:true} : {})};
+  }
   function tools() {
     return [
       { name: "ads_status", description: "Start here for UI/ADS work: components, patterns, tokens/themes/branding, layout, behavior, motion and showcase review. Returns the exact project root/public API, workflow, project commands, editing mode and build diagnostics. When mutations.enabled, use guarded ads_apply_patch for ADS edits; otherwise use local editing tools.", schema: empty, call: () => json(status()) },
@@ -170,7 +187,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const units = edits.units();
         return json({ total: matches.length, scenarios: matches.slice(offset, offset + limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), ...(offset + limit < matches.length ? { nextOffset: offset + limit } : {}), diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios` });
       } },
-      { name: "ads_show_scenario", description: "Render one real token, component, pattern or composition scenario with its colocated fixtures and state adapter. First get an exact id from ads_scenarios or ads_catalog.previews. The managed compiler builds it on demand; errors return diagnostics instead of falsely current output. Requires MCP Apps plus host resource forwarding; fallback links to the same scenario in the project showcase.", schema: z.object({ id: z.string().min(1).max(256) }).strict(), _meta: { ui: { resourceUri: scenarioWidget() } }, call: async ({ id }, signal) => {
+      { name: "ads_show_scenario", title: "Scenario preview", description: "Render one real token, component, pattern or composition scenario with its colocated fixtures and state adapter. First get an exact id from ads_scenarios or ads_catalog.previews. The managed compiler builds it on demand; errors return diagnostics instead of falsely current output. Requires MCP Apps plus host resource forwarding; fallback links to the same scenario in the project showcase.", schema: z.object({ id: z.string().min(1).max(256) }).strict(), _meta: { ui: { resourceUri: scenarioWidget() } }, call: async ({ id }, signal) => {
         const entry = getRegistry().scenarios.find(item => item.id === id);
         if (!entry) throw new Error("Unknown scenario id. Read ads_scenarios; IDs must match discovered source entries.");
         if (getRegistry().diagnostics.length) throw new Error("Scenario registry has errors. Read ads://project/scenarios and fix its diagnostics.");
@@ -188,7 +205,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
       } },
-      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Atomic composition warnings identify overlapping properties and link ads://guides/atomic-styles for causes and fixes. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
         const result = checkProject(root);
         return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },
@@ -203,7 +220,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         if (!("text" in content)) return json({ ...manifest, mimeType: content.mimeType, binary: true, note: "Read binary bytes via resources/read; this tool does not embed them." });
         return json({ ...manifest, text: content.text.slice(offset, offset + limit), offset, ...(offset + limit < content.text.length ? { nextOffset: offset + limit } : {}) });
       } },
-      { name: "ads_show_tokens", description: "Render an exact discovered token scenario with its project-owned templates and fixtures. Pass its id as category, discovered through ads_tokens.categories or ads_scenarios(kind: tokens). Omit category for the first project token scenario, or a generic definition inspector for older compilers.", schema: z.object({ category: z.string().max(256).optional() }).strict(), _meta: { ui: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI } }, call: async ({ category }, signal) => {
+      { name: "ads_show_tokens", title: "Token previews", description: "Render an exact discovered token scenario with its project-owned templates and fixtures. Pass its id as category, discovered through ads_tokens.categories or ads_scenarios(kind: tokens). Omit category for the first project token scenario, or a generic definition inspector for older compilers.", schema: z.object({ category: z.string().max(256).optional() }).strict(), _meta: { ui: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI } }, call: async ({ category }, signal) => {
         if (!category && options.config.mcp.previewManifest) category = tokenScenarios()[0]?.id;
         if (!category && options.config.mcp.previewManifest) throw new Error("No token scenario is registered. Colocate a token scenario and fixture before opening the preview; ads_tokens still inspects definitions.");
         if (category) {
@@ -243,22 +260,17 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
-      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements. A real selected-unit re-export may remove a redundant export {}; placeholder. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. A runtime owner patch may also include its ds.config.json companion solely for that owner's inlineStyleFiles/styleWrites entries alongside its source. Unused permissions fail validation. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
+      ...(mutations ? [{ name: "ads_prepare_patch", description: "Prepare a Git patch without a separate project mirror. Create copies only one owner plus its declared companions into a local draft; edit that directory with local file tools. Diff checks baseline/source freshness and owner paths, then writes a patchFile under .ds/patches. Discard removes the draft. Live source is never changed; ads_apply_patch still validates all gates. Remote clients can continue sending inline Git diffs instead.", schema:z.object({unit:z.string().min(1).max(256),action:z.enum(["create","diff","discard"]).default("create"),draft:z.string().max(100).optional()}).strict(), call:args=>json(prepareUnitPatch(options,args)) },
+      {name:"ads_prepare_token_samples",description:"Reconcile a token scenario's consumed literal fixture samples. Removes undeclared tokens, preserves existing project bindings, and accepts explicit real-token/property/probe bindings. Reports unresolved token names; never guesses CSS meaning from token names. Returns an owner patchFile without changing source. Apply it through ads_apply_patch and review the real preview.",schema:z.object({id:z.string().min(1).max(256),bindings:z.array(z.object({token:z.string().max(256),property:z.string().max(100),probe:z.string().max(1000)}).passthrough()).max(1000).optional()}).strict(),call:args=>{
+        const {patch,...result}=reconcileTokenSamples(options,args);
+        return json({...result,removed:result.removed.slice(0,50),unresolved:result.unresolved.slice(0,50),unresolvedCount:result.unresolved.length,...storePreparedPatch(options,patch)});
+      }},
+      { name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements. A real selected-unit re-export may remove a redundant export {}; placeholder. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. A runtime owner patch may also include its ds.config.json companion solely for that owner's inlineStyleFiles/styleWrites entries alongside its source. Unused permissions fail validation. Set dryRun true to validate without writing. For genuinely coupled owner changes use ads_apply_transaction with one patch per owner. Fix rejected patches and inspect current previews after acceptance.",
         schema: z.object({ unit: z.string().min(1).max(256), dryRun: z.boolean(), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile."),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, _meta: { ui: { visibility: ["model"] } },
-        call: async (args, signal) => {
-          const result = await edits.apply(args, signal);
-          if (result.applied) {
-            try {
-              if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration") await previewWatch?.reconfigure?.(loadConfig(root).config.mcp, true);
-              await refresh(true);
-            }
-            catch (error) { result.warnings = [...(result.warnings ?? []), { rule: "mutation-notification", message: `Changes were applied, but preview refresh failed: ${error.message.slice(0, 2000)}. Recheck ads_status and reopen the scenario.` }]; }
-          }
-          return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
-        },
-      }] : []),
-      ...options.config.mcp.apps.map((app) => ({ name: `ads_show_${app.id.replaceAll("-", "_")}`, description: `${app.description ?? app.title}. Renders the project's built ${app.kind} examples through MCP Apps; text fallback provides the showcase URL.`, schema: empty, _meta: { ui: { resourceUri: appUri(app.id) } }, call: async (_args, signal) => {
+        call: applyEdits,
+      }, {name:"ads_apply_transaction",description:"Apply genuinely coupled ADS changes as 2–8 distinct owner Git patches. Each patch must obey its unit and narrow companion rules. Patches run in order; later patches use the earlier candidate's shared-entry content. Core guards, registered Oxlint/project checks and affected behavior checks validate the complete final candidate before any live source is written. Maximum 32 distinct files/16 MiB combined. Dry runs, failures and cancellation publish nothing; publication rolls back on write failure. Prefer ads_apply_patch for independent edits.",schema:z.object({patches:z.array(ownerPatch).min(2).max(mutationLimits.units),dryRun:z.boolean()}).strict(),annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:false,openWorldHint:false},_meta:{ui:{visibility:["model"]}},call:applyEdits}] : []),
+      ...options.config.mcp.apps.map((app) => ({ name: `ads_show_${app.id.replaceAll("-", "_")}`, title: app.title, description: `${app.description ?? app.title}. Renders the project's built ${app.kind} examples through MCP Apps; text fallback provides the showcase URL.`, schema: empty, _meta: { ui: { resourceUri: appUri(app.id) } }, call: async (_args, signal) => {
         // Validate readiness without embedding executable HTML in model results.
         const build = await previewBuild(app, signal);
         projectApp(options, app);
@@ -320,7 +332,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     }).join("\n");
   }
   const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json"), path.join(root, ".ds/behavior-results.json")]);
-  const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, app.file)));
+  const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, previewArtifactPath(previewOptions(), app.file))));
   const assetFingerprint = () => resourceAssets().map(asset => asset.uri).sort().join("\n");
   let previous = fingerprint();
   let previousArtifacts = artifactFingerprint();
@@ -410,5 +422,5 @@ export async function startAdsMcp(directory = process.cwd(), { stdio = true, sho
   }
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, disconnect);
   process.once("exit", forceCleanup);
-  return { close, url: host?.url };
+  return { close, url: host?.url, previewRevision: () => readPreviewManifest(withPreviewSession(loadConfig(root), previewWatch.resourceSession()))?.revision ?? null };
 }

package/dist/mcp/text-diff.mjs

@@ -0,0 +1,19 @@
+/** One exact Git-style hunk, retaining only shared context around the change. */
+export function textDiff(file, before, after) {
+  if (before === after) return "";
+  const lines = value => value?.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  const emit = (prefix, line) => prefix + line.replace(/\n$/, "") + "\n" + (line.endsWith("\n") ? "" : "\\n");
+  const left = lines(before), right = lines(after);
+  let common = 0, suffix = 0;
+  while (common < left.length && common < right.length && left[common] === right[common]) common++;
+  while (suffix < left.length - common && suffix < right.length - common && left.at(-suffix - 1) === right.at(-suffix - 1)) suffix++;
+  const start = Math.max(0, common - 3), tail = Math.min(3, suffix);
+  const oldCount = left.length - suffix + tail - start, newCount = right.length - suffix + tail - start;
+  const headers = `--- ${before === null ? "/dev/null" : "a/" + file}\n+++ ${after === null ? "/dev/null" : "b/" + file}\n`;
+  if (!oldCount && !newCount) return headers;
+  return headers + `@@ -${oldCount ? start + 1 : start},${oldCount} +${newCount ? start + 1 : start},${newCount} @@\n`
+    + left.slice(start, common).map(line => emit(" ", line)).join("")
+    + left.slice(common, left.length - suffix).map(line => emit("-", line)).join("")
+    + right.slice(common, right.length - suffix).map(line => emit("+", line)).join("")
+    + left.slice(left.length - suffix, left.length - suffix + tail).map(line => emit(" ", line)).join("");
+}

package/dist/preview-resources.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import ts from "typescript";
 import valueParser from "postcss-value-parser";
 import { isInside } from "./config.mjs";
+import { previewArtifactPath, previewManifestPath } from "./preview-scope.mjs";
 
 export const PREVIEW_APP_URI = "ui://ads/preview";
 export const PREVIEW_MANIFEST_URI = "ads://preview/manifest";
@@ -118,11 +119,41 @@ export function createPreviewResources(output, options, entries) {
   const graph = { schemaVersion: 1, framework: options.config.framework, assets: records, scenarios };
   const revision = hash(JSON.stringify(graph));
   validateManifest({ ...graph, revision });
-  const target = path.resolve(options.root, options.config.mcp.previewManifest ?? ".ds/preview/manifest.json");
+  return publication(options, entries, { ...graph, revision }, contents);
+}
+
+export function previewArtifactHtml(id, revision) {
+  const descriptor = JSON.stringify({ schemaVersion: 1, manifestUri: PREVIEW_MANIFEST_URI, revision, id });
+  return `<!doctype html><html><head></head><body><script type="application/json" id="ads-preview-resource">${descriptor.replaceAll("<", "\\u003c")}</script></body></html>`;
+}
+
+function cacheOptions(options, revision) {
+  return { ...options, previewSession: undefined, config: { ...options.config, mcp: { ...options.config.mcp, previewManifest: `.ds/preview-graphs/${revision}/manifest.json` } } };
+}
+
+/** A cache hit still verifies every compiled byte before republishing it. */
+export function cachedPreviewPublication(options, entries, revision) {
+  if (!/^[a-f0-9]{64}$/.test(revision ?? "")) return null;
+  try {
+    const cached = cacheOptions(options, revision), manifest = readPreviewManifest(cached, { verify: true });
+    if (!manifest || manifest.revision !== revision || manifest.framework !== options.config.framework
+      || JSON.stringify(manifest.scenarios.map(entry => entry.id)) !== JSON.stringify(entries.map(entry => entry.id))) return null;
+    const contents = new Map(Object.keys(manifest.assets).map(uri => {
+      const value = readPreviewAsset(cached, uri, manifest);
+      return [uri, "text" in value ? Buffer.from(value.text) : Buffer.from(value.blob, "base64")];
+    }));
+    const { session: _session, ...graph } = manifest;
+    return publication(options, entries, graph, contents);
+  } catch { return null; } // Missing, pruned or corrupt cache means a real build.
+}
+
+function publication(options, entries, manifest, contents, saveCache = true) {
+  const { revision } = manifest;
+  const target = previewManifestPath(options);
   const assetsRoot = path.join(path.dirname(target), "assets");
   const assetFiles = [...contents.keys()].map(uri => path.join(assetsRoot, uri.slice("ads://assets/".length)));
-  return { assetFiles, publish(session) {
-    const encoded = JSON.stringify({ ...graph, revision, session });
+  return { assetFiles, revision, publish(session) {
+    const encoded = JSON.stringify({ ...manifest, session });
     if (Buffer.byteLength(encoded) > 2 * 1024 * 1024) throw new Error("Preview manifest exceeds the 2 MiB resource limit.");
     const history = path.join(path.dirname(target), "history");
     if (existsSync(target)) {
@@ -133,8 +164,7 @@ export function createPreviewResources(output, options, entries) {
     }
     for (const [uri, bytes] of contents) atomic(path.join(assetsRoot, uri.slice("ads://assets/".length)), bytes);
     for (const entry of entries) {
-      const descriptor = JSON.stringify({ schemaVersion: 1, manifestUri: PREVIEW_MANIFEST_URI, revision, id: entry.id });
-      atomic(path.join(options.root, entry.artifact), `<!doctype html><html><head></head><body><script type="application/json" id="ads-preview-resource">${descriptor.replaceAll("<", "\\u003c")}</script></body></html>`);
+      atomic(path.join(options.root, previewArtifactPath(options, entry.artifact)), previewArtifactHtml(entry.id, revision));
     }
     atomic(target, encoded);
     const retained = existsSync(history) ? readdirSync(history).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).sort((a, b) => statSync(path.join(history, b)).mtimeMs - statSync(path.join(history, a)).mtimeMs) : [];
@@ -145,13 +175,20 @@ export function createPreviewResources(output, options, entries) {
     }
     for (const file of retained.slice(6)) rmSync(path.join(history, file));
     for (const file of readdirSync(assetsRoot)) if (/^[a-f0-9]{64}\.[a-z0-9]+$/.test(file) && !keep.has(`ads://assets/${file}`)) rmSync(path.join(assetsRoot, file));
+    if (saveCache) try {
+      publication(cacheOptions(options, revision), [], manifest, contents, false).publish("cache");
+      const directory = path.join(options.root, ".ds/preview-graphs");
+      const snapshots = readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isDirectory() && /^[a-f0-9]{64}$/.test(entry.name))
+        .sort((a, b) => statSync(path.join(directory, b.name)).mtimeMs - statSync(path.join(directory, a.name)).mtimeMs);
+      for (const entry of snapshots.slice(6)) rmSync(path.join(directory, entry.name), { recursive: true, force: true });
+    } catch { /* Cache races/storage failures never invalidate published output. */ }
   } };
 }
 
 export function readPreviewManifest(options, { verify = false } = {}) {
   const relative = options.config.mcp.previewManifest;
   if (!relative) return null;
-  const file = path.resolve(options.root, relative);
+  const file = previewManifestPath(options);
   if (!existsSync(file)) return null;
   const manifest = readManifestFile(file);
   if (verify) for (const uri of Object.keys(manifest.assets)) readPreviewAsset(options, uri, manifest);
@@ -180,7 +217,7 @@ export function readPreviewAsset(options, uri, manifest = readPreviewManifest(op
   if (!assetUriPattern.test(uri)) throw unknownResource("Unknown preview asset resource.");
   let record = manifest?.assets?.[uri];
   if (!record) {
-    const history = path.join(path.dirname(path.resolve(options.root, options.config.mcp.previewManifest)), "history");
+    const history = path.join(path.dirname(previewManifestPath(options)), "history");
     for (const file of existsSync(history) ? readdirSync(history).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).slice(0, 6) : []) {
       const candidate = path.join(history, file);
       try { record = readManifestFile(candidate).assets[uri]; }
@@ -189,7 +226,7 @@ export function readPreviewAsset(options, uri, manifest = readPreviewManifest(op
     }
   }
   if (!record) throw unknownResource("Unknown or expired preview asset resource. Refresh the manifest.");
-  const directory = path.join(path.dirname(path.resolve(options.root, options.config.mcp.previewManifest)), "assets");
+  const directory = path.join(path.dirname(previewManifestPath(options)), "assets");
   const file = path.join(directory, uri.slice("ads://assets/".length));
   if (!isInside(directory, file) || realpathSync(file) !== file || statSync(file).size > 16 * 1024 * 1024) throw new Error("Invalid preview asset file.");
   const bytes = readFileSync(file);

package/dist/preview-scope.mjs

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { isInside } from "./config.mjs";
+
+/** Logical resource names stay stable; managed builders own physical output. */
+export function withPreviewSession(options, session) {
+  if (!options.config.mcp.previewManifest || !session) return options;
+  if (!/^[\w-]{1,100}$/.test(session)) throw new Error("Invalid preview build session.");
+  return { ...options, previewSession: session };
+}
+
+export function previewManifestPath(options) {
+  const configured = path.resolve(options.root, options.config.mcp.previewManifest);
+  return options.previewSession ? path.join(path.dirname(configured), "sessions", options.previewSession, "manifest.json") : configured;
+}
+
+export function previewArtifactPath(options, file) {
+  if (!options.previewSession || !file.replaceAll("\\", "/").startsWith(".ds/scenarios/")) return file;
+  return path.join(".ds/preview-sessions", options.previewSession, path.relative(".ds", file)).replaceAll("\\", "/");
+}
+
+export function previewSessionDirectories(options) {
+  if (!options.previewSession) return [];
+  const directories = [path.dirname(previewManifestPath(options)), path.join(options.root, ".ds/preview-sessions", options.previewSession)];
+  if (directories.some(directory => !isInside(path.join(options.root, ".ds"), directory))) throw new Error("Preview session output must stay inside .ds/.");
+  for (const directory of directories) for (let current = directory; isInside(path.join(options.root, ".ds"), current); current = path.dirname(current)) {
+    if (existsSync(current) && realpathSync(current) !== current) throw new Error("Preview session output cannot resolve through a symlink.");
+  }
+  return directories;
+}