@reqvire-org/ads 0.3.10 → 0.3.12

package/dist/mcp/build-status.mjs

@@ -2,7 +2,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { isInside, projectPath } from "../config.mjs";
+import { isInside, projectPath, loadConfig } from "../config.mjs";
+import { previewSourceRevision } from "../preview-inputs.mjs";
 import { readPreviewManifest } from "../preview-resources.mjs";
 import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 
@@ -10,7 +11,7 @@ export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
 const maxBytes = 256 * 1024;
 const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
-const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
+const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), sourceRevision:z.string().regex(/^[a-f0-9]{64}$/).optional(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
 const progressSchema = z.object({ phase: z.enum(["queued", "validation", "compilation", "validation-and-compilation", "publication", "idle"]), startedAt: z.string().datetime(), updatedAt: z.string().datetime() }).strict();
 const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), progress: progressSchema.optional(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
@@ -93,8 +94,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
       apps = next;
       save();
     },
-    begin(id) {
+    begin(id,{sourceRevision = previewSourceRevision(loadConfig(root),apps)} = {}) {
       const value = entry(id);
+      value.sourceRevision = sourceRevision;
       value.state = "building";
       value.revision++;
       value.diagnostics = [];
@@ -137,6 +139,11 @@ export function inspectBuildStatus(root, config, { session, previewSession, proc
     }
   } catch (error) { reportError = `Invalid preview build status: ${error.message.slice(0, 500)}`; }
   let graphError;
+  let sourceRevision, sourceError;
+  if (report?.previews.some(entry=>entry.state==="ready")) {
+    try { sourceRevision = previewSourceRevision(loadConfig(root),config.apps); }
+    catch (error) { sourceError = `Cannot verify preview inputs: ${error.message}`; }
+  }
   if (config.previewManifest && report?.previews.some(entry => entry.state === "ready")) {
     try {
       if (!readPreviewManifest(options, { verify: true })) throw new Error("Preview resource manifest is missing.");
@@ -154,13 +161,16 @@ export function inspectBuildStatus(root, config, { session, previewSession, proc
     if (state === "ready") {
       try {
         if (value.lastSuccessfulRevision !== value.revision || artifactDigest(artifact) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
+        if (sourceError) throw new Error(sourceError);
+        if (!value.sourceRevision) throw new Error("Preview builder did not record its source revision. Rebuild using the current ADS build reporter.");
+        if (value.sourceRevision !== sourceRevision) { state = "idle"; diagnostics = [{code:"ADS_PREVIEW_STALE_SOURCE",message:"Project inputs changed after this preview was built. Waiting for a build of the current source."}]; }
       } catch (error) { state = "error"; diagnostics = [{ message: error.message }]; }
     }
     if (processState?.state === "failed") { state = "error"; diagnostics = [{ message: processState.error ?? "Preview watcher exited." }, ...diagnostics].slice(0, 20); }
     if (["stopped", "stopping", "idle"].includes(processState?.state)) state = "unreported";
     const current = state === "ready";
     return { id: app.id, state, session: report?.session ?? null, revision: value?.revision ?? null, lastSuccessfulRevision: value?.lastSuccessfulRevision ?? null,
-      current, stale: state === "unreported" ? null : !current, available, diagnostics };
+      current, stale: state === "unreported" ? null : !current, available, ...(value?.sourceRevision ? {sourceRevision:value.sourceRevision} : {}), diagnostics };
   });
   const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
   return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, ...(report?.progress ? { progress: report.progress } : {}), previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };

package/dist/mcp/catalog.mjs

@@ -4,7 +4,7 @@ import ts from "typescript";
 import { isInside, sourceFiles } from "../config.mjs";
 import { projectCompilerOptions } from "../boundaries.mjs";
 import { publicApi } from "../public-api.mjs";
-import { projectGuideFiles } from "../project-documents.mjs";
+import { projectDocumentFiles } from "../project-documents.mjs";
 
 export const PROJECT_URI = "ads://project";
 export const sourceUri = (file) => `${PROJECT_URI}/files/${file.split("/").map(encodeURIComponent).join("/")}`;
@@ -21,10 +21,10 @@ export function projectDocuments(options) {
   }
   for (const directory of new Set(files.map((file) => path.dirname(file)))) docs(directory);
   docs(dsRoot);
-  for (const name of projectGuideFiles(root)) files.push(path.join(root, name));
+  for (const directory of new Set([root,dsRoot])) for (const name of projectDocumentFiles(directory)) files.push(path.join(directory, name));
   return [...new Set(files)].filter((file) => isInside(root, realpathSync(file))).sort().map((file) => {
     const relative = path.relative(root, file).replaceAll("\\", "/");
-    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
+    return { uri: sourceUri(relative), name: relative, mimeType: /\.md$/i.test(file) ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
   });
 }
 

package/dist/mcp/mutations.mjs

@@ -65,7 +65,7 @@ function validateContent(change, unit) {
   if (change.content === null) return;
   const bytes = Buffer.from(change.content);
   if (bytes.length > mutationLimits.fileBytes) throw fail("mutation-content", "The patched file exceeds 16 MiB.", change.path);
-  if (textFile(change.path) && (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes))) throw fail("mutation-content", "Text source must contain valid UTF-8 without NUL bytes.", change.path);
+  if ((unit === "documentation" || textFile(change.path)) && (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes))) throw fail("mutation-content", "Text source and documentation must contain valid UTF-8 without NUL bytes.", change.path);
   if (/\.jsonc?$/.test(change.path)) {
     const content=bytes.toString("utf8");
     if (unit === "configuration" && !["package.json","ds.config.json"].includes(path.basename(change.path))) {

package/dist/mcp/preview-watch.mjs

@@ -31,16 +31,17 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   const ready = new Set();
   const requests = new Set();
   let active;
+  let invalidation;
   let requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
   let reportFile = path.join(root, ".ds", `build-status-${session}.json`);
-  function request(file) {
-    if (!command || requests.has(file) && active === file) return;
+  function request(file,force = false) {
+    if (!command || !force && requests.has(file) && active === file) return;
     requests.add(file);
     active = file;
     mkdirSync(path.dirname(requestFile), { recursive: true });
     if (realpathSync(path.dirname(requestFile)) !== path.dirname(requestFile)) throw new Error("Preview requests cannot resolve through a symlink.");
     const temporary = `${requestFile}.tmp`;
-    writeFileSync(temporary, JSON.stringify({ session, active: path.relative(root, active).replaceAll("\\", "/"), files: [...requests].map((file) => path.relative(root, file).replaceAll("\\", "/")) }));
+    writeFileSync(temporary, JSON.stringify({ session, active: path.relative(root, active).replaceAll("\\", "/"), files: [...requests].map((file) => path.relative(root, file).replaceAll("\\", "/")), ...(invalidation ? {invalidation} : {}) }));
     renameSync(temporary, requestFile);
   }
 
@@ -135,7 +136,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     if (state === "failed" || restarting || stalled) await restart();
     if (disposed) throw new Error("Preview watcher is stopped.");
     start();
-    request(file);
+    request(file,buildStatus().previews.some(entry=>entry.diagnostics.some(item=>item.code==="ADS_PREVIEW_STALE_SOURCE")));
     if (signal?.aborted) throw new Error("Preview request cancelled.");
     const app = config.apps.find((entry) => path.resolve(root, entry.file) === file);
     let baseline = baselines.get(file) ?? null;
@@ -181,7 +182,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     })();
     return stopping;
   }
-  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, resourceSession, buildStatus, setApps(apps) {
+  return { start, ensure, invalidate() { invalidation = randomUUID(); if (active) request(active,true); }, 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));
@@ -202,6 +203,7 @@ export function createReconfigurablePreviewWatch(root, config, options) {
     status() { return replacing ? { state: "reconfiguring" } : current.status(); },
     resourceSession() { return current.resourceSession(); },
     buildStatus() { return current.buildStatus(); },
+    async invalidate() { await pending; if (!stopped) current.invalidate(); },
     setApps(next) { apps = next; current.setApps(next); },
     kill() { current.kill(); },
     reconfigure(next, force = false) {

package/dist/mcp/server.mjs

@@ -46,6 +46,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     cache.registry = cache.catalog = cache.documents = undefined;
   }
   const getShowcaseUrl = () => showcaseUrl?.() ?? options.config.mcp.showcaseUrl;
+  function scenarioUrl(id) {
+    const base = getShowcaseUrl();
+    if (!base) return null;
+    const url = new URL(base);
+    url.searchParams.delete("category");
+    url.searchParams.set("scenario", id);
+    return url.href;
+  }
   const project = () => { const context = projectContext(options); context.showcase.url = getShowcaseUrl(); return context; };
   const subscribed = new Set();
   const server = new Server({ name: "reqvire-ads", version: pkg.version }, {
@@ -171,6 +179,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     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 previewWatch?.invalidate?.();
         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.`}];}
     }
@@ -197,10 +206,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const build = await previewBuild(app, signal);
         const graph = graphSelection(id);
         if (!options.config.mcp.previewManifest) projectApp(options, app, build);
-        const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
-        url?.searchParams.delete("category");
-        url?.searchParams.set("scenario", id);
-        return json({ widget: { resourceUri: scenarioWidget() }, scenario: { ...entry, resourceUri: appUri(id) }, ...graph, build, showcaseUrl: url?.href ?? null });
+        return json({ widget: { resourceUri: scenarioWidget() }, scenario: { ...entry, resourceUri: appUri(id) }, ...graph, build, showcaseUrl: scenarioUrl(id) });
       } },
       { name: "ads_tokens", description: "Use before styling, theme, brand or motion-token changes to inspect existing semantic definitions/values. Query specific token names with a small limit. ads_show_tokens renders project token scenarios; definition inspection does not validate component layout.", schema: query, call: ({ query: search = "", limit }) => {
         const inventory = inspectTokens(root);
@@ -233,10 +239,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
           const build = await previewBuild(app, signal);
           const graph = graphSelection(category);
           if (!options.config.mcp.previewManifest) projectApp(options, app, build);
-          const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
-          url?.searchParams.delete("scenario");
-          url?.searchParams.set("category", category);
-          return json({ widget: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI }, category, scenario: { ...entry, resourceUri: appUri(category) }, ...graph, build, showcaseUrl: url?.href ?? null });
+          return json({ widget: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI }, category, scenario: { ...entry, resourceUri: appUri(category) }, ...graph, build, showcaseUrl: scenarioUrl(category) });
         }
         return json({ widget: { resourceUri: TOKENS_APP_URI }, category: null, tokenCount: inspectTokens(root).tokens.length, dataUri: `${PROJECT_URI}/tokens`, showcaseUrl: getShowcaseUrl() });
       } },
@@ -257,9 +260,9 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         await refresh();
         return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
       } },
-      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; shared controllers; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Manifests include companionFiles with permitted shared-entry or owner-only style-boundary bookkeeping; preserve peer permissions and unrelated configuration. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
+      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; shared controllers; composition; tokens; foundation shared files; documentation including shared credits/license notices; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Manifests include filePolicy for supported new documentation paths and companionFiles with permitted shared-entry or owner-only style-boundary bookkeeping; preserve peer permissions and unrelated configuration. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
         const matches = edits.units().filter(item => unit ? item.id === unit : item.id.toLowerCase().includes(search.toLowerCase()));
-        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 } : {}) } : {}) })) });
+        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 } : {}), ...(item.filePolicy ? { filePolicy: item.filePolicy } : {}) } : {}) })) });
       } },
       { 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_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)) },

package/dist/preview-inputs.mjs

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { isInside } from "./config.mjs";
+
+/** Shared source evidence for compilation, watch recovery and status reads. */
+export function previewSourceRevision({root,config}, apps = config.mcp.apps ?? []) {
+  const rows = [], generated = config.assets.generatedPaths.map(file => path.resolve(root,file));
+  const outputs = new Set(apps.map(app => path.resolve(root,app.file)));
+  function digest(file) { return createHash("sha256").update(readFileSync(file)).digest("hex"); }
+  function visit(directory) {
+    for (const entry of readdirSync(directory,{withFileTypes:true})) {
+      if (entry.isSymbolicLink() || ["node_modules",".git",".ds",".vite","coverage"].includes(entry.name)) continue;
+      const file = path.join(directory,entry.name);
+      if (outputs.has(file) || generated.some(base => isInside(base,file))) continue;
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) rows.push([path.relative(root,file),digest(file)]);
+    }
+  }
+  visit(root);
+  const installed = path.join(root,"node_modules/.package-lock.json");
+  rows.push(["installed-packages",existsSync(installed) ? digest(installed) : null]);
+  return createHash("sha256").update(JSON.stringify(rows.sort((a,b)=>a[0].localeCompare(b[0])))).digest("hex");
+}

package/dist/project-documents.mjs

@@ -2,15 +2,31 @@ import { existsSync, lstatSync, readdirSync } from "node:fs";
 import path from "node:path";
 
 const rootNames = ["README.md", "ADS.md", "DS.md", "ARCHITECTURE.md", "Architecture.md", "GUIDE.md", "MCP.md", "CHANGELOG.md"];
+const noticeStem = /^(?:CREDITS|LICEN[CS]ES?|NOTICES?|COPYING|COPYRIGHT)(?:[-_][A-Za-z0-9][A-Za-z0-9._-]*)?$/i;
+const textExtension = /\.(?:md|txt)$/i;
+
+export const documentationFilePolicy = "Project guides; root CREDITS, LICENSE/LICENCE, NOTICE, COPYING and COPYRIGHT notices (optional -/_ qualifiers); licenses/ collections, also under docs/ or doc/. Notices use .md, .txt, or conventional extensionless names and valid UTF-8. The same document paths may live at the ADS root. Component-local notices remain with their owner; code, configuration, hidden and generated paths are excluded.";
+
+function noticeName(name) {
+  const extension = path.posix.extname(name);
+  return (!extension || textExtension.test(name)) && noticeStem.test(extension ? name.slice(0,-extension.length) : name);
+}
+
+function isProjectNotice(file) {
+  if (!file.includes("/")) return noticeName(file);
+  return /^(?:(?:docs|doc)\/)?licenses\/.+$/i.test(file) && (textExtension.test(file) || noticeName(path.posix.basename(file)));
+}
 
 /** Recognize documentation ownership even before a new guide exists. */
 export function isProjectDocument(file) {
-  return rootNames.includes(file) || /^(?:docs|doc)\/.+\.md$/i.test(file) && !file.split("/").some(part => part.startsWith("."));
+  if (file.includes("\\") || file.includes("\0") || file.split("/").some(part => !part || part.startsWith("."))) return false;
+  return rootNames.includes(file) || isProjectNotice(file) || /^(?:docs|doc)\/.+\.md$/i.test(file);
 }
 
-/** Shared guide discovery for MCP resources, workflow context and editable units. */
-export function projectGuideFiles(root) {
-  const files = rootNames.filter(file => existsSync(path.join(root, file)) && lstatSync(path.join(root, file)).isFile());
+/** Shared document discovery for MCP resources and editable units. */
+export function projectDocumentFiles(root) {
+  if (!existsSync(root) || !lstatSync(root).isDirectory()) return [];
+  const files = [];
   function walk(relative) {
     const directory = path.join(root, relative);
     if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return;
@@ -21,7 +37,14 @@ export function projectGuideFiles(root) {
       else if (entry.isFile() && isProjectDocument(file)) files.push(file);
     }
   }
-  walk("docs");
-  walk("doc");
+  for (const entry of readdirSync(root,{withFileTypes:true})) {
+    if (entry.isFile() && isProjectDocument(entry.name)) files.push(entry.name);
+    else if (entry.isDirectory() && /^(?:docs|doc|licenses)$/i.test(entry.name)) walk(entry.name);
+  }
   return files.sort();
 }
+
+/** Provenance stays discoverable without loading notice inventories as workflow guides. */
+export function projectGuideFiles(root) {
+  return projectDocumentFiles(root).filter(file => !isProjectNotice(file));
+}

package/dist/scenarios-compiler.mjs

@@ -6,6 +6,7 @@ import { inspectScenarios } from "./scenarios.mjs";
 import { artifactDigest, createBuildReporter } from "./mcp/build-status.mjs";
 import { cachedPreviewPublication, previewArtifactHtml, readPreviewManifest } from "./preview-resources.mjs";
 import { previewArtifactPath, withPreviewSession } from "./preview-scope.mjs";
+import { previewSourceRevision } from "./preview-inputs.mjs";
 
 const digest = value => createHash("sha256").update(value).digest("hex");
 const fileDigest = file => { try { return digest(readFileSync(file)); } catch { return null; } };
@@ -13,8 +14,8 @@ const fileDigest = file => { try { return digest(readFileSync(file)); } catch {
 /** Cache only successful validation + matching source/dependency/output content.
  * 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, ...["preview-resources.mjs", "preview-scope.mjs", "scenarios-vite.mjs", "linaria.mjs", "linaria/atomic-css.cjs", "linaria/atomic-styled.cjs", "linaria/preserve-values.cjs"].map(file => path.join(import.meta.dirname, file)), ...compilerFiles,
+  const { root } = options;
+  const adapterFiles = [import.meta.filename, ...["preview-inputs.mjs", "preview-resources.mjs", "preview-scope.mjs", "scenarios-vite.mjs", "linaria.mjs", "linaria/atomic-css.cjs", "linaria/atomic-styled.cjs", "linaria/preserve-values.cjs"].map(file => path.join(import.meta.dirname, file)), ...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();
@@ -27,20 +28,7 @@ export function createPreviewCache(options, compilerFiles = []) {
     }
   } catch { /* Missing or corrupt cache means validate and rebuild. */ }
   function inputs() {
-    const rows = [];
-    const generated = config.assets.generatedPaths.map(file => path.resolve(root, file));
-    function visit(directory) {
-      for (const entry of readdirSync(directory, { withFileTypes: true })) {
-        if (entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)) continue;
-        const file = path.join(directory, entry.name);
-        if (generated.some(base => isInside(base, file))) continue;
-        if (entry.isDirectory()) visit(file);
-        else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) rows.push([path.relative(root, file), fileDigest(file)]);
-      }
-    }
-    visit(root);
-    rows.push(["installed-packages", fileDigest(path.join(root, "node_modules/.package-lock.json"))]);
-    rows.push(["node-runtime", `${process.version}/${process.platform}/${process.arch}`]);
+    const rows = [["project-inputs",previewSourceRevision(options)],["node-runtime",`${process.version}/${process.platform}/${process.arch}`]];
     for (const file of compilerFiles) rows.push([file, fileDigest(file)]);
     // Tool upgrades invalidate validation even when the project's lockfile is unchanged.
     for (const name of readdirSync(import.meta.dirname).filter(name => name.endsWith(".mjs"))) {
@@ -119,6 +107,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   let generation = 0;
   let publishedStamp;
   let validation;
+  let observedSourceRevision = previewSourceRevision(options);
+  let invalidation;
   function failure(error) {
     try { reporter.failure(error); } catch (reportError) { console.error(reportError); }
     console.error(error);
@@ -144,7 +134,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   }
   async function compile(entry) {
     if (buildGraph) return compileGraph();
-    const revision = reporter.begin(entry.id);
+    const revision = reporter.begin(entry.id,{sourceRevision:previewSourceRevision(options)});
     const started = generation;
     try {
       const stamp = cache.inputs();
@@ -187,7 +177,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     }
   }
   async function compileGraph() {
-    const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id)]));
+    const sourceRevision = previewSourceRevision(options);
+    const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id,{sourceRevision})]));
     const started = generation;
     try {
       const stamp = cache.inputs();
@@ -257,6 +248,10 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     try {
       const value = JSON.parse(readFileSync(file, "utf8"));
       if (value.session !== process.env.ADS_MCP_BUILD_SESSION) return;
+      if (value.invalidation !== invalidation) {
+        invalidation = value.invalidation;
+        if (requested.size) sourceChanged("invalidate",options.config.dsDir,true);
+      }
       active = entries.find(entry => entry.artifact === value.active)?.id;
       for (const file of value.files) {
         const entry = entries.find(entry => entry.artifact === file);
@@ -288,6 +283,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const changes = [...changed]; changed.clear();
       try {
         entries = registry();
+        observedSourceRevision = previewSourceRevision(options);
         registryFailure = undefined;
         reporter.setApps(buildApps());
         reporter.clearFailure();
@@ -297,7 +293,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         // compilation. Check active first, then rebuild only changed dependencies.
         for (const id of requested) {
           const entry = entries.find(entry => entry.id === id);
-          if (entry) { reporter.begin(id); pending.add(id); }
+          if (entry) { reporter.begin(id,{sourceRevision:observedSourceRevision}); pending.add(id); }
         }
         if (changes.length) void drain();
       } catch (error) {
@@ -344,7 +340,17 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     } catch (error) { failure(error); }
   }
   reconcileWatches(true);
-  const reconcileTimer = setInterval(reconcileWatches, 1000);
+  const reconcileTimer = setInterval(() => {
+    reconcileWatches();
+    try {
+      const current = previewSourceRevision(options);
+      if (current !== observedSourceRevision) {
+        observedSourceRevision = current;
+        sourceChanged("reconcile",options.config.dsDir,true);
+      }
+      request();
+    } catch (error) { failure(error); }
+  }, 1000);
   request();
   console.log(`Scenario compiler ready: ${entries.length} entries; builds are requested on demand.`);
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {