@reqvire-org/ads 0.3.5 → 0.3.6

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 };
   }
@@ -126,7 +131,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 +139,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 +162,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 +185,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.");
@@ -203,7 +218,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 +258,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 +330,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 +420,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;
+}

package/dist/scenarios-compiler.mjs

@@ -4,7 +4,8 @@ import path from "node:path";
 import { loadConfig, isInside } from "./config.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
 import { artifactDigest, createBuildReporter } from "./mcp/build-status.mjs";
-import { readPreviewManifest } from "./preview-resources.mjs";
+import { cachedPreviewPublication, previewArtifactHtml, readPreviewManifest } from "./preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "./preview-scope.mjs";
 
 const digest = value => createHash("sha256").update(value).digest("hex");
 const fileDigest = file => { try { return digest(readFileSync(file)); } catch { return null; } };
@@ -13,7 +14,7 @@ const fileDigest = file => { try { return digest(readFileSync(file)); } catch {
  * Cache state is development output, never proof that a failed build is current. */
 export function createPreviewCache(options, compilerFiles = []) {
   const { root, config } = options;
-  const adapterFiles = [import.meta.filename, path.join(import.meta.dirname, "preview-resources.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
+  const adapterFiles = [import.meta.filename, path.join(import.meta.dirname, "preview-resources.mjs"), path.join(import.meta.dirname, "preview-scope.mjs"), path.join(import.meta.dirname, "scenarios-vite.mjs"), ...compilerFiles,
     ...["package.json", "package-lock.json", "bun.lock", "bun.lockb", "node_modules/.package-lock.json"].map(file => path.join(root, file))];
   const adapterDigest = () => digest(JSON.stringify(adapterFiles.map(file => [file, fileDigest(file)])));
   const loadedAdapter = adapterDigest();
@@ -62,14 +63,17 @@ export function createPreviewCache(options, compilerFiles = []) {
     ["scheduler", fileDigest(import.meta.filename)],
     ["node-runtime", `${process.version}/${process.platform}/${process.arch}`],
   ]));
-  function reusable(entry) {
+  function reusable(entry, expectedHtml) {
     const cached = value.entries[entry.id];
     if (!cached || cached.metadata !== JSON.stringify(entry) || cached.compiler !== compilerDigest()) return false;
     if (!cached.dependencies || !Object.keys(cached.dependencies).length) return false;
     if (Object.entries(cached.dependencies).some(([file, hash]) => fileDigest(path.resolve(root, file)) !== hash)) return false;
-    try { return cached.artifact === artifactDigest(path.join(root, entry.artifact)); } catch { return false; }
+    if (expectedHtml !== undefined && cached.artifact !== `sha256:${digest(expectedHtml)}`) return false;
+    const file = path.join(root, previewArtifactPath(options, entry.artifact));
+    if (expectedHtml !== undefined && !existsSync(file)) return true;
+    try { return cached.artifact === artifactDigest(file); } catch { return false; }
   }
-  return { inputs, reusable, validated: stamp => value.validation === stamp,
+  return { inputs, reusable, graphRevision: () => value.graphRevision, recordGraph(revision) { value.graphRevision = revision; save(); }, validated: stamp => value.validation === stamp,
     assertCompiler() {
       if (adapterDigest() !== loadedAdapter) throw Object.assign(new Error("Preview compiler code or dependencies changed. Invoke the preview again to restart the builder and load current code."), { code: "ADS_PREVIEW_RESTART" });
     },
@@ -78,7 +82,7 @@ export function createPreviewCache(options, compilerFiles = []) {
       value.entries[entry.id] = { metadata: JSON.stringify(entry), compiler: compilerDigest(),
         dependencies: Object.fromEntries([...new Set([path.join(root, entry.file), ...dependencies])]
           .filter(file => isInside(root, file) && !file.includes(`${path.sep}node_modules${path.sep}`)).map(file => [path.relative(root, file), fileDigest(file)])),
-        artifact: artifactDigest(path.join(root, entry.artifact)) };
+        artifact: artifactDigest(path.join(root, previewArtifactPath(options, entry.artifact))) };
       save();
     },
   };
@@ -87,11 +91,11 @@ export function createPreviewCache(options, compilerFiles = []) {
 /** Shared scheduling and cache; the project supplies its own React/Preact build. */
 export async function runScenarioCompiler(directory, { watched = false, validate, build, buildGraph, compilerFiles = [] }) {
   const root = path.resolve(directory);
-  let options = loadConfig(root);
+  let options = withPreviewSession(loadConfig(root), process.env.ADS_MCP_BUILD_SESSION);
   if (buildGraph && (!options.config.mcp.previewManifest || !options.config.framework)) throw new Error("Resource preview builds require an explicit framework and mcp.previewManifest in ds.config.json.");
   const cache = createPreviewCache(options, compilerFiles);
   function registry() {
-    options = loadConfig(root);
+    options = withPreviewSession(loadConfig(root), process.env.ADS_MCP_BUILD_SESSION);
     const result = inspectScenarios(options);
     if (result.diagnostics.length) throw Object.assign(new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n")), { scenarios: result.scenarios });
     mkdirSync(path.join(root, ".ds/scenarios"), { recursive: true });
@@ -104,7 +108,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (!watched) throw error;
     registryFailure = error; entries = error.scenarios ?? [];
   }
-  const reporter = createBuildReporter(root, { apps: entries.map(entry => ({ id: entry.id, file: entry.artifact })) });
+  const buildApps = () => entries.map(entry => ({ id: entry.id, file: previewArtifactPath(options, entry.artifact) }));
+  const reporter = createBuildReporter(root, { apps: buildApps() });
   const requested = new Set();
   const pending = new Set();
   let active;
@@ -202,8 +207,12 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         }
       } };
       cache.assertCompiler();
-      let reusable = entries.every(entry => cache.reusable(entry));
-      if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
+      const cached = cachedPreviewPublication(options, entries, cache.graphRevision());
+      let reusable = cached && entries.every(entry => cache.reusable(entry, previewArtifactHtml(entry.id, cached.revision)));
+      if (reusable) {
+        try { readPreviewManifest(options, { verify: true }); }
+        catch { reusable = false; }
+      }
       const outcomes = await checkedBuild(stamp, () => reusable ? null : buildGraph(entries, options, track));
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
@@ -212,12 +221,10 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const publication = outcomes[1].value;
       if (publication) {
         publication.publish(reporter.session);
-        for (const entry of entries) cache.record(entry, [...dependencies, ...publication.assetFiles]);
+        for (const entry of entries) cache.record(entry, dependencies);
+        cache.recordGraph(publication.revision);
       } else {
-        const file = path.join(root, options.config.mcp.previewManifest);
-        const manifest = readPreviewManifest(options);
-        writeFileSync(`${file}.tmp`, JSON.stringify({ ...manifest, session: reporter.session }));
-        renameSync(`${file}.tmp`, file);
+        cached.publish(reporter.session);
       }
       for (const entry of entries) { pending.delete(entry.id); reporter.ready(entry.id, revisions.get(entry.id)); }
       publishedStamp = stamp;
@@ -281,7 +288,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       try {
         entries = registry();
         registryFailure = undefined;
-        reporter.setApps(entries.map(entry => ({ id: entry.id, file: entry.artifact })));
+        reporter.setApps(buildApps());
         reporter.clearFailure();
         request(false);
         for (const id of requested) if (!entries.some(entry => entry.id === id)) { requested.delete(id); pending.delete(id); }

package/dist/scenarios.mjs

@@ -8,6 +8,7 @@ import { projectCompilerOptions } from "./boundaries.mjs";
 import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { validTokenSamples } from "./token-samples.mjs";
+import { scopedTokens } from "./scoped-tokens.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -39,14 +40,16 @@ export function inspectScenarios(options, suppliedProgram) {
   const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
   const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
-  const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
+  const tokenInventory = inspectTokens(root);
+  const tokenNames = new Set(tokenInventory.tokens.map(token => token.name));
+  const scoped = scopedTokens(options);
   const scenarios = [];
   const diagnostics = [];
   const ids = new Set();
   function report(file, message) { diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: 1, column: 1, message }); }
   for (const file of files) {
     const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-    const kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
+    let kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
     if (!["tokens", "components", "patterns", "composition"].includes(kind)) { report(file, "Scenarios live beside tokens/components/patterns or under composition/, not inside showcase pages."); continue; }
     const id = relative.replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
     if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
@@ -62,6 +65,11 @@ export function inspectScenarios(options, suppliedProgram) {
         for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") metadata = literal(declaration.initializer, checker);
       }
     }
+    if (metadata?.kind !== undefined) {
+      const owner = scoped.inventory.owner(relative);
+      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) { report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview."); continue; }
+      kind = "tokens";
+    }
     if (!entry) report(file, "Export a default independently mountable scenario entrypoint.");
     const module = checker.getSymbolAtLocation(source);
     const defaultExport = module && checker.getExportsOfModule(module).find(item => item.name === "default");
@@ -77,7 +85,7 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+    if (!metadata || Object.keys(metadata).some((key) => !["title", "kind", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
       || Object.hasOwn(metadata, "exercises") && (!Array.isArray(metadata.exercises) || metadata.exercises.some(name => typeof name !== "string" || !behaviorApis.has(name)))
       || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
       || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
@@ -86,7 +94,11 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
     const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
-    for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
+    for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real token from its defining owner.` });
+    if (kind === "tokens") {
+      const owner = scoped.inventory.owner(relative);
+      for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
+    }
     scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(metadata.exercises ? { exercises: [...new Set(metadata.exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
@@ -209,3 +221,33 @@ export function writeScenarioRegistry(options, write) {
   write({ schemaVersion: 1, scenarios: registry.scenarios });
   return registry.scenarios;
 }
+
+/** Locate the actual consumed array, rather than regenerating a whole fixture. */
+export function tokenSampleSource(options, scenario) {
+  const file = path.join(options.root, scenario.file);
+  const program = ts.createProgram([file], { ...projectCompilerOptions(options), allowJs:true, resolveJsonModule:true });
+  const checker = program.getTypeChecker(), source = program.getSourceFile(file);
+  function resolve(node, seen = new Set()) {
+    while (node && (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node))) node = node.expression;
+    if (!node || seen.has(node)) return null;
+    if (ts.isArrayLiteralExpression(node) || ts.isObjectLiteralExpression(node)) return node;
+    let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+    if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    return declaration?.initializer ? resolve(declaration.initializer, new Set([...seen,node])) : null;
+  }
+  for (const statement of source.statements) if (ts.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) {
+    if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "scenario") continue;
+    const metadata = resolve(declaration.initializer);
+    const property = metadata && ts.isObjectLiteralExpression(metadata) && metadata.properties.find(node => ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name)) && node.name.text === "samples");
+    const array = property && resolve(property.initializer);
+    if (array && ts.isArrayLiteralExpression(array)) {
+      const source = array.getSourceFile();
+      const scoped = scopedTokens(options), owner = scoped.inventory.owner(scoped.inventory.relative(scenario.file));
+      const relative = path.relative(options.root, source.fileName).replaceAll("\\", "/");
+      if (!isDevelopmentFile(source.fileName, options) || scoped.inventory.owner(scoped.inventory.relative(relative)) !== owner) throw new Error("The consumed samples array must live in this scenario's own development fixture.");
+      return {file:relative, content:source.text, start:array.getStart(source), end:array.end};
+    }
+  }
+  throw new Error("Cannot locate a literal consumed samples array. Keep fixture.samples statically inspectable; edit other fixture shapes with a normal owner patch.");
+}

package/dist/scoped-tokens.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import postcss from "postcss";
+import ts from "typescript";
+import { inspectUnits } from "./units.mjs";
+import { isDevelopmentFile } from "./config.mjs";
+import { foundationSelector } from "./foundation.mjs";
+import { isSharedToken, tokenContract } from "./token-policy.mjs";
+
+/** An explicit owner contract, never a heuristic based on a token's name. */
+export function scopedTokens(options) {
+  if (options.scopedTokens) return options.scopedTokens;
+  const inventory = inspectUnits(options), definitions = [], diagnostics = [];
+  const report = (file, message, line = 1) => diagnostics.push({rule:"scoped-token", file, message, line, column:1});
+  for (const unit of inventory.units.filter(unit => ["components", "patterns"].includes(unit.kind))) {
+    for (const manifest of unit.files.filter(file => /(?:^|\/)tokens\.json$|\.tokens\.json$/.test(file))) {
+      const absolute = path.join(options.root, manifest);
+      try {
+        if (statSync(absolute).size > 65536 || realpathSync(absolute) !== absolute) throw new Error("Token manifests must be ordinary files no larger than 64 KiB.");
+        const data = JSON.parse(readFileSync(absolute, "utf8"));
+        const stylesheet = manifest.replace(/\.json$/, ".css");
+        if (!data || data.schemaVersion !== 1 || Object.keys(data).some(key => !["schemaVersion", "namespace"].includes(key))
+          || typeof data.namespace !== "string" || !/^--[a-z][a-z0-9-]*-$/.test(data.namespace)
+          || /^(?:--ds-|--ux-|--showcase-)/.test(data.namespace) || isSharedToken(data.namespace + "value")
+          || tokenContract.naming.prefixes.some(prefix => prefix.startsWith(data.namespace))
+          || [...tokenContract.naming.names,...Object.keys(tokenContract.tokens)].some(name => name.startsWith(data.namespace))) throw new Error("Use {schemaVersion:1, namespace:\"--<owner>-\"}; shared and runtime-variable prefixes are reserved.");
+        if (definitions.some(entry => entry.unit === unit.id || entry.namespace.startsWith(data.namespace) || data.namespace.startsWith(entry.namespace))) throw new Error("Each unit has one token namespace; namespaces must not overlap other owners.");
+        if (!unit.files.includes(stylesheet) || !existsSync(path.join(options.root, stylesheet))) throw new Error(`Colocate the definition-only stylesheet ${stylesheet}.`);
+        const file = path.join(options.root, stylesheet);
+        if (realpathSync(file) !== file) throw new Error("Scoped token stylesheets cannot resolve through symlinks.");
+        const css = postcss.parse(readFileSync(file, "utf8"), {from:file});
+        let count = 0;
+        css.walk(node => {
+          if (node.type === "comment" || node.type === "root") return;
+          if (node.type === "atrule" && ["media", "supports", "layer"].includes(node.name) && node.nodes) return;
+          if (node.type === "rule" && node.parent.type !== "rule" && !foundationSelector(node.selector, {definitions:true})) return;
+          if (node.type === "decl" && node.parent.type === "rule" && node.prop.startsWith(data.namespace) && node.prop.length > data.namespace.length && !node.important) { count++; return; }
+          report(stylesheet, "Owner token sheets contain only namespaced custom-property definitions under root/theme conditions. UI selectors, imports, font faces, animations and ordinary declarations belong in their runtime owners.", node.source?.start.line);
+        });
+        if (!count) report(stylesheet, "Define at least one real namespaced token.");
+        const imported = unit.files.filter(file => /\.[cm]?[jt]sx?$/.test(file) && !isDevelopmentFile(path.join(options.root, file), options)).some(source => {
+          const ast = ts.createSourceFile(source, readFileSync(path.join(options.root, source), "utf8"), ts.ScriptTarget.Latest, true);
+          return ast.statements.some(node => ts.isImportDeclaration(node) && !node.importClause && ts.isStringLiteralLike(node.moduleSpecifier) && path.resolve(options.root, path.dirname(source), node.moduleSpecifier.text) === file);
+        });
+        if (!imported) report(manifest, `Import ./${path.basename(stylesheet)} from this owner's runtime source so its real preview and product consume the same definitions.`);
+        definitions.push({unit:unit.id, namespace:data.namespace, manifest, file:stylesheet});
+      } catch (error) { report(manifest, error.reason ?? error.message, error.line); }
+    }
+  }
+  const result = {definitions, diagnostics, inventory};
+  options.scopedTokens = result;
+  return result;
+}
+
+export function scopedTokenOwner(options, name) {
+  return scopedTokens(options).definitions.find(entry => name.startsWith(entry.namespace));
+}

package/dist/skills/ads-break-ui/SKILL.md

@@ -36,8 +36,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 Use `dryRun: true` to
 inspect validation; applying re-runs the gates. Fix rejected patches in their
-owner. Report unsupported coupled changes instead of bypassing a rejection with
-direct source writes. Shared styles/helpers use `foundation`, root guides use
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass a rejection with direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -45,6 +45,8 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
 Controllers are UI behavior owners: private helpers stay with their component or