@reqvire-org/ads 0.3.12 → 0.3.14

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,8 +284,8 @@ 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 } : {}) };
       } },
@@ -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/scenario-slots.mjs

@@ -0,0 +1,124 @@
+import ts from "typescript";
+import { isDevelopmentFile } from "./config.mjs";
+import { publicApi } from "./public-api.mjs";
+import { createSourceValues, isFunction, reference, unwrap } from "./source-values.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+/** A native scenario child may supply semantics to a public runtime slot. The
+ * proof follows actual child cloning, never a prop/component/helper spelling. */
+export function createScenarioSlots(program, options) {
+  const checker = program.getTypeChecker(), cache = new WeakMap();
+  const operation = node => uiOperation(node, checker);
+  const values = createSourceValues(program, options, { strict: true, preserveCall: node => ["createElement", "cloneElement", "Children.only"].includes(operation(node)) });
+  const { state, next, resolve, get, keys, props, returns, declaration } = values;
+  const publicNodes = new Set(publicApi(program, options).filter(item => item.renderable).map(item => resolve(reference(item.declaration.name ?? item.declaration), state())).filter(value => value.kind === "node").map(value => value.node));
+
+  function element(node, env = new Map(), via = []) {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const attributes = props(opening, env, via);
+      const children = ts.isJsxElement(node) ? node.children.filter(child => !ts.isJsxText(child) || child.text.trim()).filter(child => !ts.isJsxExpression(child) || child.expression) : [];
+      if (children.length) attributes.layers.push(new Map([["children", children.length === 1 ? reference(children[0], env, via) : { kind: "array", values: children.map(child => reference(child, env, via)) }]]));
+      return { tag: reference(opening.tagName, env, via), attributes, intrinsic: ts.isIdentifier(opening.tagName) && /^[a-z]/.test(opening.tagName.text) };
+    }
+    if (ts.isCallExpression(node) && operation(node.expression) === "createElement") {
+      const attributes = { kind: "object", layers: node.arguments[1] && node.arguments[1].kind !== ts.SyntaxKind.NullKeyword ? [reference(node.arguments[1], env, via)] : [] };
+      const children = node.arguments.slice(2).map(child => reference(child, env, via));
+      if (children.length) attributes.layers.push(new Map([["children", children.length === 1 ? children[0] : { kind: "array", values: children }]]));
+      return { tag: reference(node.arguments[0], env, via), attributes, intrinsic: !!node.arguments[0] && ts.isStringLiteralLike(node.arguments[0]) };
+    }
+    return null;
+  }
+
+  return function nativeSlot(site) {
+    if (cache.has(site)) return cache.get(site);
+    const reasons = new Set(); let cloned = false, exposed = false, uncertain = false, steps = 0;
+    const fail = reason => { uncertain = true; reasons.add(reason); };
+    function childValue(input, context) {
+      const value = resolve(input, next(context));
+      if (value.kind === "node" && ts.isJsxExpression(value.node)) return childValue(reference(value.node.expression, value.env, value.via), next(context));
+      if (value.kind === "node" && ts.isCallExpression(value.node) && operation(value.node.expression) === "Children.only") return childValue(reference(value.node.arguments[0], value.env, value.via), next(context));
+      return value;
+    }
+    function ownedProps(input, context, seen = new Set()) {
+      if (context.depth > 40) return false;
+      const value = resolve(input, next(context));
+      const opaque = value.kind === "unknown" || value.kind === "union" && value.values.length <= 32 && value.values.every(branch => resolve(branch, next(context)).kind === "unknown");
+      if (value.kind === "union" && !opaque) return value.values.length <= 32 && value.values.every(branch => ownedProps(branch, next(context), new Set(seen)));
+      if (keys(value, next(context)).some(key => key !== "children")) return true;
+      // Local prop mergers may use loops and a ref assignment, beyond the value
+      // evaluator. Retain runtime ownership through their actual input props;
+      // a known empty result, external call or arbitrary identifier cannot qualify.
+      if (!opaque || input.kind !== "node") return false;
+      const node = unwrap(input.node), { env, via } = input;
+      if (seen.has(node)) return false;
+      seen.add(node);
+      if (ts.isIdentifier(node)) {
+        if (env.has(checker.getSymbolAtLocation(node))) return ownedProps(env.get(checker.getSymbolAtLocation(node)), next(context), seen);
+        const binding = declaration(node);
+        return !!(binding && ts.isVariableDeclaration(binding) && binding.parent.flags & ts.NodeFlags.Const && binding.initializer && !isDevelopmentFile(binding.getSourceFile().fileName, options) && ownedProps(reference(binding.initializer, env, via), next(context), seen));
+      }
+      if (ts.isCallExpression(node)) {
+        const target = resolve(reference(node.expression, env, via), next(context));
+        return target.kind === "node" && isFunction(target.node) && !isDevelopmentFile(target.node.getSourceFile().fileName, options) && node.arguments.some(argument => ownedProps(reference(argument, env, via), next(context), new Set(seen)));
+      }
+      return false;
+    }
+    function render(input, context) {
+      if (++steps > 500 || context.depth > 48) { fail("Slot tracing reached its source work limit."); return; }
+      const value = childValue(input, context);
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "slot-child") { exposed = true; return; }
+      if (["union", "array"].includes(value.kind)) {
+        if (value.values.length > 32) { fail("Slot tracing reached its alternative limit."); return; }
+        for (const child of value.values) render(child, next(context));
+        return;
+      }
+      if (value.kind === "unknown") { fail(value.reason || "The runtime slot's render path could not be traced."); return; }
+      if (value.kind !== "node") return;
+      const { node, env, via } = value;
+      if (ts.isJsxFragment(node)) { for (const child of node.children) render(reference(child, env, via), next(context)); return; }
+      if (ts.isArrayLiteralExpression(node)) { for (const child of node.elements) render(reference(ts.isSpreadElement(child) ? child.expression : child, env, via), next(context)); return; }
+      if (ts.isCallExpression(node) && operation(node.expression) === "cloneElement") {
+        const child = childValue(reference(node.arguments[0], env, via), next(context));
+        if (child.kind === "slot-child") {
+          if (!node.arguments[1] || !ownedProps(reference(node.arguments[1], env, via), state())) fail("A slot must clone its child with runtime-owned props.");
+          else cloned = true;
+        } else render(child, next(context));
+        return;
+      }
+      const view = element(node, env, via);
+      if (!view) return;
+      function component(input) {
+        const target = resolve(input, next(context));
+        if (target.kind === "union") {
+          if (target.values.length > 32) { fail("Slot tracing reached its alternative limit."); return; }
+          for (const branch of target.values) component(branch);
+        } else if (view.intrinsic || ["provider", "context"].includes(target.kind) || target.kind === "literal" && typeof target.value === "string") render(get(view.attributes, "children", next(context)), next(context));
+        else if (target.kind === "node" && isFunction(target.node) && !isDevelopmentFile(target.node.getSourceFile().fileName, options)) {
+          for (const output of returns(target, [view.attributes], next(context), "component")) render(output, next(context));
+        } else fail("The runtime slot's component target could not be traced.");
+      }
+      component(view.tag);
+    }
+
+    const native = ts.isJsxOpeningElement(site) ? site.parent : site;
+    let child = native;
+    while (child.parent && (ts.isJsxExpression(child.parent) || ts.isParenthesizedExpression(child.parent) || ts.isAsExpression(child.parent) || ts.isSatisfiesExpression(child.parent) || ts.isNonNullExpression(child.parent))) child = child.parent;
+    let parent = child.parent;
+    if (parent && ts.isJsxAttribute(parent) && parent.name.text === "children") parent = parent.parent.parent;
+    if (parent && ts.isPropertyAssignment(parent) && parent.name.getText().replace(/^["']|["']$/g, "") === "children" && ts.isObjectLiteralExpression(parent.parent) && ts.isCallExpression(parent.parent.parent) && parent.parent.parent.arguments[1] === parent.parent) parent = parent.parent.parent;
+    const view = parent && element(parent), context = state();
+    if (view) {
+      const target = resolve(view.tag, next(context));
+      const original = childValue(get(view.attributes, "children", next(context)), next(context));
+      if (target.kind === "node" && publicNodes.has(target.node) && original.kind === "node" && original.node === native) {
+        view.attributes.layers.push(new Map([["children", { kind: "slot-child" }]]));
+        for (const output of returns(target, [view.attributes], next(context), "component")) render(output, next(context));
+      }
+    }
+    const result = { ok: cloned && !exposed && !uncertain, reasons: [...reasons].slice(0, 2) };
+    cache.set(site, result);
+    return result;
+  };
+}

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 };
 }