@reqvire-org/ads 0.3.11 → 0.3.13

package/dist/mcp/server.mjs

@@ -21,12 +21,21 @@ import { GUIDE_URI, projectContext, projectGuide, serverInstructions, workflow }
 import { createMutationController, mutationLimits } from "./mutations.mjs";
 import { prepareUnitPatch, storePreparedPatch } from "./edit-preparation.mjs";
 import { reconcileTokenSamples } from "../token-fixtures.mjs";
+import { createCaptureController } from "../capture.mjs";
+import { CAPTURES_URI, captureSpec, screenshotFields } from "../capture-store.mjs";
+import { previewSourceRevision } from "../preview-inputs.mjs";
 
 const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 class InvalidParamsError extends ProtocolError {
   constructor(message) { super(INVALID_PARAMS, message); }
 }
 const json = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
+function captureResponse(value, resourceLinks = false) {
+  const result = json(value);
+  if (!resourceLinks) return result; // Older protocol clients retain text/structured URI discovery.
+  for (const capture of value.captures ?? value.screenshots?.captures ?? []) for (const slot of ["current", "candidate"]) if (capture[slot]) result.content.push({ type: "resource_link", uri: capture[slot].resourceUri, mimeType: "image/png", name: `${slot === "current" ? "Current" : "Candidate"}: ${capture.scenario}${capture.target ? ` / ${capture.target}` : ""}` });
+  return result;
+}
 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 };
@@ -37,7 +46,8 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const root = path.resolve(directory);
   const cache = inspection ?? {};
   const skills = cache.skills ??= createSkillStore(skillDirectory);
-  const edits = cache.edits ??= createMutationController(root);
+  const captures = cache.captures ??= createCaptureController(root);
+  const edits = cache.edits ??= createMutationController(root, { captures });
   const verification = cache.verification ??= createVerificationController(root);
   let options = loadConfig(root);
   const signature = `${root}:${JSON.stringify(options.config)}`;
@@ -62,6 +72,11 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [APP_MIME] }, ...(era === "modern" ? { [SKILLS_EXTENSION]: { directoryRead: true } } : {}) } },
   });
   const getRegistry = () => cache.registry ??= inspectScenarios(options);
+  function captureInventory() {
+    const current = loadConfig(root), registry = inspectScenarios(current);
+    return { ...registry, revision: previewSourceRevision(current) };
+  }
+  function captureIndex() { const inventory = captureInventory(); return captures.store.list(inventory.scenarios, inventory.revision, { prune: !inventory.diagnostics.length }); }
   const scenarioApps = () => getRegistry().scenarios.map(item => ({ id: item.id, title: item.title, kind: item.kind, ...(item.samples ? { samples: item.samples } : {}), file: item.artifact }));
   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()];
@@ -95,12 +110,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
       { uri: "ads://guides/atomic-styles", name: "Atomic styles: composition conflicts and custom-property extraction", mimeType: "text/markdown" },
       { uri: "ads://guides/scenarios", name: "Scenario coverage and public class-helper contracts", mimeType: "text/markdown" },
+      { uri: "ads://guides/captures", name: "On-demand captures and candidate visual review", 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" },
       { uri: `${PROJECT_URI}/catalog`, name: "Public components and patterns", mimeType: "application/json" },
       { 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: CAPTURES_URI, name: "On-demand current and candidate screenshots", 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 },
@@ -126,6 +143,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       previews: previews(), skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description })),
       scenarios: { count: getRegistry().scenarios.length, diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios`, tool: "ads_show_scenario" },
       behaviors: { resourceUri: BEHAVIOR_URI, discoveryTool: "ads_behaviors", verificationTool: "ads_verify", ...verification.status() },
+      captures: { resourceUri: CAPTURES_URI, tool: "ads_capture", clearTool: "ads_capture_clear", ...captures.status() },
       experimental: { apps: true, nativeSkills: era === "modern", nativeSkillActivation: "host-controlled" } };
   }
   async function read(uri, signal) {
@@ -133,6 +151,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     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 (uri === "ads://guides/scenarios") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/scenarios.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/captures") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/captures.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -142,11 +161,16 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     else if (uri === `${PROJECT_URI}/scenarios`) value = getRegistry();
     else if (uri === `${PROJECT_URI}/checks`) value = checkProject(root);
     else if (uri === BEHAVIOR_URI) value = behaviorStatus(options);
+    else if (uri === CAPTURES_URI) value = captureIndex();
     else if (uri === PREVIEW_MANIFEST_URI && options.config.mcp.previewManifest) {
       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) }] };
+    if (uri.startsWith("ads://captures/")) {
+      try { const inventory = captureInventory(); return { contents: [captures.store.readResource(uri, inventory.scenarios, inventory.revision, { allowUnknownTargets: !!inventory.diagnostics.length })] }; }
+      catch (error) { if (error.code === "ADS_CAPTURE_NOT_FOUND") throw new ResourceNotFoundError(uri, error.message); throw error; }
+    }
     if (uri === TOKENS_APP_URI) return { contents: [{ uri, mimeType: APP_MIME, text: tokensApp(tokenWidgetData(inspectTokens(root))), _meta: appMetadata({ nested: true }) }] };
     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() }] };
@@ -174,8 +198,9 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return build;
   }
 
-  async function applyEdits(args,signal) {
-    const result = await edits.apply(args,signal);
+  async function applyEdits(args,signal,progress) {
+    const result = await edits.apply(args,signal,progress);
+    if (result.screenshots) await refresh();
     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);
@@ -183,11 +208,15 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         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} : {})};
+    return {...captureResponse(result, era === "modern"),...(!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()) },
+      { name: "ads_capture", title: "Capture a design-system scenario", description: "Capture one discovered scenario or its named captureTargets element inside the real MCP App iframe, excluding showcase navigation. Uses project-local Playwright/browser and an isolated host; installs nothing. Returns PNG resource URIs and source/build/settings metadata, never image bytes in text. Successful standalone capture replaces current and clears a prior candidate for that target. No screenshots are created until requested. Inspect ads://project/captures for stale/current evidence. Appearance is not behavior verification.", schema: captureSpec, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, call: async (args, signal, progress) => {
+        const result = await captures.run({ captures: [args] }, signal, progress); await refresh(); return captureResponse(result, era === "modern");
+      } },
+      { name: "ads_capture_clear", description: "Delete generated screenshot slots for one scenario/target. candidateOnly discards a proposal while retaining current. Source is unchanged. No TTL/history is kept; each target has at most current and candidate.", schema: z.object({ scenario: z.string().min(1).max(256), target: z.string().regex(/^[a-zA-Z0-9][\w.-]{0,79}$/).optional(), candidateOnly: z.boolean().default(false) }).strict(), annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, call: async args => { const result = captures.store.clear(args); await refresh(); return json(result); } },
       { name: "ads_catalog", description: "Before creating/changing UI or behavior, find existing public components/patterns/controllers and hooks with a small query/limit. Returns import alias and exact source/guide URIs so you can reuse or edit the owner. Read ads_status first for workspace/workflow. Metadata only; does not render UI.", schema: query.extend({ kind: z.enum(["components", "patterns", "controllers"]).optional() }), call: ({ query: search = "", limit, kind }) => {
         const matches = getCatalog().filter((item) => (!kind || item.kind === kind) && item.name.toLowerCase().includes(search.toLowerCase()));
         const units = edits.units();
@@ -255,14 +284,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
             demonstrations: demonstrations.slice(0, 10), demonstrationCount: demonstrations.length, checkCount: Object.keys(item.checks).length };
         }), diagnostics: inventory.diagnostics.slice(0, 50), resourceUri: BEHAVIOR_URI });
       } },
-      { name: "ads_verify", description: "Run one owner's registered development behavior checks using its configured runner/profile. Executes trusted project commands with bounded output, cancellation and process-tree cleanup; installs nothing. Browser profiles use an isolated managed showcase/MCP App. React StrictMode requires a project development harness, not a production widget. Missing/skipped cases, stale inputs and process exit alone cannot produce passing evidence. Discover exact unit/check IDs with ads_behaviors first.", schema: z.object({ unit: z.string().min(1).max(256), checks: z.array(z.string().min(1).max(100)).min(1).max(100).optional() }).strict(), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, call: async (args, signal) => {
-        const result = await verification.run(args, signal);
+      { name: "ads_verify", description: "Run one owner's registered development behavior checks using its configured runner/profile. Executes trusted project commands with bounded output, cancellation and process-tree cleanup; installs nothing. Progress and per-check timings are available through ads_status; a profile timeout bounds the whole run. Browser profiles use an isolated managed showcase/MCP App. React StrictMode requires a project development harness, not a production widget. Missing/skipped cases, stale inputs and process exit alone cannot produce passing evidence. Discover exact unit/check IDs with ads_behaviors first.", schema: z.object({ unit: z.string().min(1).max(256), checks: z.array(z.string().min(1).max(100)).min(1).max(100).optional() }).strict(), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, call: async (args, signal, progress) => {
+        const result = await verification.run(args, signal, progress);
         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)) },
@@ -270,11 +299,11 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         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."),
+      { 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. Optional screenshot:true plus captures:[{scenario,target?,theme?,viewport?}] captures current/candidate only after gates pass. 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(), ...screenshotFields }).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: 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}] : []),
+      }, {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. Optional screenshot:true with dryRun:true and explicit captures selects current/candidate images. Prefer ads_apply_patch for independent edits.",schema:z.object({patches:z.array(ownerPatch).min(2).max(mutationLimits.units),dryRun:z.boolean(),...screenshotFields}).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);
@@ -295,7 +324,12 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const input = tool.schema.safeParse(args ?? {});
     if (!input.success) throw new InvalidParamsError(input.error.message);
     previewWatch?.start();
-    try { return await tool.call(input.data, context.mcpReq.signal); }
+    let progress = 0;
+    const token = context.mcpReq._meta?.progressToken;
+    const notify = token === undefined ? undefined : value => {
+      void context.mcpReq.notify({ method: "notifications/progress", params: { progressToken: token, progress: ++progress, message: value.message ?? `${value.profile}: ${value.completed}/${value.total} completed; ${value.active.map(item => `${item.unit}#${item.check}`).join(", ") || "no active check reported"}; ${value.elapsedMs} ms elapsed` } }).catch(() => {});
+    };
+    try { return await tool.call(input.data, context.mcpReq.signal, notify); }
     catch (error) { return { isError: true, content: [{ type: "text", text: error.message }], ...(error.build ? { structuredContent: { message: error.message, build: error.build } } : {}) }; }
   });
   server.setRequestHandler("resources/list", ({ params = {} }) => {
@@ -304,10 +338,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const listing = page(resources(), cursor, "resources");
     return { resources: listing.items, ...(listing.nextCursor ? { nextCursor: listing.nextCursor } : {}) };
   });
-  server.setRequestHandler("resources/templates/list", () => ({ resourceTemplates: [] }));
+  server.setRequestHandler("resources/templates/list", () => ({ resourceTemplates: [{ uriTemplate: "ads://captures/{key}/{slot}", name: "Current/candidate screenshot", description: "Exact keys and available slots come from ads://project/captures. Slots are replaced in place, not revision history.", mimeType: "image/png" }] }));
   server.setRequestHandler("resources/read", ({ params: { uri } }, context) => read(uri, context.mcpReq.signal));
   server.setRequestHandler("resources/subscribe", ({ params: { uri } }) => {
-    if (!resources().some((entry) => entry.uri === uri)) throw new ResourceNotFoundError(uri, "Unknown ADS resource subscription.");
+    if (!resources().some((entry) => entry.uri === uri)) {
+      if (!uri.startsWith("ads://captures/")) throw new ResourceNotFoundError(uri, "Unknown ADS resource subscription.");
+      try { const inventory = captureInventory(); captures.store.readResource(uri, inventory.scenarios, inventory.revision, { allowUnknownTargets: !!inventory.diagnostics.length }); } catch { throw new ResourceNotFoundError(uri, "Unknown or absent screenshot slot."); }
+    }
     subscribed.add(uri); return {};
   });
   server.setRequestHandler("resources/unsubscribe", ({ params: { uri } }) => { subscribed.delete(uri); return {}; });
@@ -343,6 +380,8 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   let previousArtifacts = artifactFingerprint();
   let previousAssets = assetFingerprint();
   let previousBuild = JSON.stringify(builds());
+  let previousCaptures = captures.store.fingerprint();
+  let previousCaptureUris = captures.store.resourceUris();
   async function refresh(force = false) {
     // Polling covers replaced files and new directories consistently across OSes.
     cache.documents = undefined;
@@ -354,7 +393,8 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const buildChanged = build !== previousBuild;
     const artifactsChanged = artifacts !== previousArtifacts;
     const assetsChanged = assets !== previousAssets;
-    if (!filesChanged && !buildChanged && !artifactsChanged && !assetsChanged) return false;
+    const capturesChanged = captures.store.fingerprint() !== previousCaptures;
+    if (!filesChanged && !buildChanged && !artifactsChanged && !assetsChanged && !capturesChanged) return false;
     if (filesChanged) {
       const updated = loadConfig(root);
       await previewWatch?.reconfigure?.(updated.config.mcp);
@@ -372,14 +412,20 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     previousBuild = JSON.stringify(builds());
     const targets = filesChanged ? era === "modern" ? resources().map((entry) => entry.uri).filter((uri) => !skills.files.has(uri)) : [...subscribed]
       : [BUILD_URI, BEHAVIOR_URI, `${PROJECT_URI}/status`, ...(options.config.mcp.previewManifest ? [PREVIEW_MANIFEST_URI] : []), ...(artifactsChanged ? allApps().map(app => appUri(app.id)) : [])].filter((uri) => era === "modern" || subscribed.has(uri));
-    for (const uri of targets) { if (notifications) notifications.resourceUpdated(uri); else await server.sendResourceUpdated({ uri }); }
+    if (capturesChanged || filesChanged) {
+      const current = (captures.store.fingerprint() ? captureIndex().captures : []).flatMap(record => [record.current?.resourceUri, record.candidate?.resourceUri].filter(Boolean));
+      targets.push(...[CAPTURES_URI, ...previousCaptureUris, ...current].filter(uri => era === "modern" || subscribed.has(uri)));
+      previousCaptureUris = current;
+      previousCaptures = captures.store.fingerprint();
+    }
+    for (const uri of new Set(targets)) { if (notifications) notifications.resourceUpdated(uri); else await server.sendResourceUpdated({ uri }); }
     return true;
   }
   const timer = pollInterval > 0 ? setInterval(() => { refresh().catch((error) => process.stderr.write(`ads mcp: ${error.message}\n`)); }, pollInterval) : null;
   timer?.unref();
   server.oninitialized = () => previewWatch?.start();
   server.onclose = () => { if (timer) clearInterval(timer); };
-  return { server, refresh, async close() { if (timer) clearInterval(timer); if (!inspection) await verification.close(); await server.close(); } };
+  return { server, refresh, async close() { if (timer) clearInterval(timer); if (!inspection) { await verification.close(); await captures.close(); } await server.close(); } };
 }
 
 export async function startAdsMcp(directory = process.cwd(), { stdio = true, showcase = true, port = 0, mutations = false } = {}) {
@@ -405,6 +451,7 @@ export async function startAdsMcp(directory = process.cwd(), { stdio = true, sho
         Promise.resolve().then(() => host?.close()),
         previewWatch.stop(),
         Promise.resolve().then(() => inspection.verification?.close()),
+        Promise.resolve().then(() => inspection.captures?.close()),
         Promise.resolve().then(() => handle?.close()),
       ]);
       for (const event of ["end", "close", "error"]) process.stdin.removeListener(event, disconnect);

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.mjs

@@ -85,8 +85,9 @@ 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", "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)
+    const fixture = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].map(extension => fixtureBase + extension).find(existsSync);
+    if (!fixture) 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", "kind", "covers", "exercises", "tokens", "samples", "captureTargets"].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, "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"))
       || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
@@ -95,6 +96,11 @@ export function inspectScenarios(options, suppliedProgram) {
     // A bad behavioral entry must fail validation without erasing independent
     // render evidence and manufacturing missing-coverage errors for real UI.
     const exercises = [];
+    let captureTargets;
+    if (Object.hasOwn(metadata, "captureTargets")) {
+      if (!metadata.captureTargets || typeof metadata.captureTargets !== "object" || Array.isArray(metadata.captureTargets) || Object.keys(metadata.captureTargets).length > 20 || Object.entries(metadata.captureTargets).some(([name, selector]) => !/^[a-zA-Z0-9][\w.-]{0,79}$/.test(name) || typeof selector !== "string" || !selector.trim() || selector.length > 500)) report(file, "captureTargets must map up to 20 named targets to nonempty CSS selectors (max 500 characters), scoped to this scenario's App iframe. Each selected target must resolve to exactly one visible element at capture time.");
+      else captureTargets = metadata.captureTargets;
+    }
     if (Object.hasOwn(metadata, "exercises")) {
       if (!Array.isArray(metadata.exercises)) report(file, "Scenario exercises must be a static array naming public behavioral APIs.");
       else for (const [index, name] of metadata.exercises.entries()) {
@@ -111,7 +117,7 @@ export function inspectScenarios(options, suppliedProgram) {
       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.`);
     }
     const stylesheets = kind === "tokens" ? scoped.definitions.filter(entry => entry.unit === scoped.inventory.owner(relative)).map(entry => entry.file) : [];
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    scenarios.push({ id, kind, title: metadata.title, ...(fixture ? { fixture: path.relative(root, fixture).replaceAll("\\", "/") } : {}), covers: [...new Set(metadata.covers)], ...(captureTargets ? { captureTargets } : {}), ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), 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 };
 }