@reqvire-org/ads 0.3.3 → 0.3.6

package/dist/mcp/server.mjs

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { Server, ProtocolError, INVALID_PARAMS, ResourceNotFoundError } from "@modelcontextprotocol/server";
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { checkProject } from "../check.mjs";
 import { loadConfig, sourceFiles } from "../config.mjs";
+import { behaviorStatus, createVerificationController, BEHAVIOR_URI } from "../verification.mjs";
 import { inspectTokens } from "../tokens.mjs";
 import { inspectScenarios } from "../scenarios.mjs";
 import { startShowcaseHost } from "./showcase-host.mjs";
@@ -12,11 +13,14 @@ import { createSkillStore, page, SKILLS_EXTENSION } from "./skills.mjs";
 import { inspectCatalog, projectDocuments, PROJECT_URI, readProjectDocument } from "./catalog.mjs";
 import { APP_MIME, appMetadata, appUri, projectApp, TOKENS_APP_URI, tokensApp, tokenWidgetData, SCENARIO_APP_URI, scenarioApp, previewApp, PREVIEW_APP_URI } from "./apps.mjs";
 import { PREVIEW_MANIFEST_URI, readPreviewManifest, readPreviewAsset } from "../preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 import { getWorkflowPrompt, promptDefinitions } from "./prompts.mjs";
 import { createReconfigurablePreviewWatch } from "./preview-watch.mjs";
 import { BUILD_URI, buildFailure, inspectBuildStatus, summarizeBuild } from "./build-status.mjs";
 import { GUIDE_URI, projectContext, projectGuide, serverInstructions, workflow } from "./context.mjs";
 import { createMutationController, mutationLimits } from "./mutations.mjs";
+import { prepareUnitPatch, storePreparedPatch } from "./edit-preparation.mjs";
+import { reconcileTokenSamples } from "../token-fixtures.mjs";
 
 const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
 class InvalidParamsError extends ProtocolError {
@@ -27,12 +31,14 @@ const empty = z.object({}).strict();
 const query = z.object({ query: z.string().max(200).optional(), limit: z.number().int().min(1).max(50).default(20) }).strict();
 const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 const schemas = { params: z.object({ cursor: z.string().optional() }).passthrough(), result: z.object({ resultType: z.literal("complete") }).passthrough() };
+const ownerPatch = z.object({ unit: z.string().min(1).max(256), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile.");
 
 export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollInterval = 1000, previewWatch, showcaseUrl, notifications, inspection, mutations = false } = {}) {
   const root = path.resolve(directory);
   const cache = inspection ?? {};
   const skills = cache.skills ??= createSkillStore(skillDirectory);
   const edits = cache.edits ??= createMutationController(root);
+  const verification = cache.verification ??= createVerificationController(root);
   let options = loadConfig(root);
   const signature = `${root}:${JSON.stringify(options.config)}`;
   if (cache.signature !== signature) {
@@ -52,13 +58,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const tokenScenarios = () => getRegistry().scenarios.filter(item => item.kind === "tokens").map(item => ({ id: item.id, title: item.title, count: item.tokens.length }));
   const allApps = () => [...options.config.mcp.apps, ...scenarioApps()];
   const scenarioWidget = () => options.config.mcp.previewManifest ? PREVIEW_APP_URI : SCENARIO_APP_URI;
+  const previewOptions = () => withPreviewSession(options, previewWatch?.resourceSession?.());
   const resourceAssets = () => {
-    try { return Object.entries(readPreviewManifest(options)?.assets ?? {}).map(([uri, record]) => ({ uri, name: `Preview asset ${uri.slice("ads://assets/".length)}`, mimeType: record.mimeType, size: record.size })); }
+    try { return Object.entries(readPreviewManifest(previewOptions())?.assets ?? {}).map(([uri, record]) => ({ uri, name: `Preview asset ${uri.slice("ads://assets/".length)}`, mimeType: record.mimeType, size: record.size })); }
     catch { return []; } // Discovery and diagnostics remain usable after a failed graph.
   };
   function graphSelection(id) {
     if (!options.config.mcp.previewManifest) return {};
-    const manifest = readPreviewManifest(options);
+    const manifest = readPreviewManifest(previewOptions());
     if (!manifest?.scenarios.some(entry => entry.id === id)) throw new Error("The preview resource graph is not ready for this scenario. Rebuild previews.");
     return { manifestUri: PREVIEW_MANIFEST_URI, manifestRevision: manifest.revision };
   }
@@ -77,11 +84,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const skillEntries = new Set(skills.skills.map((skill) => skill.uri));
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
+      { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
       { uri: `${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: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
       { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
       { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
@@ -98,18 +107,20 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const context = project();
     return { projectRoot: root, workflow: workflow([...previews(), ...scenarioApps()]), project: context,
       package: pkg.name, version: pkg.version, dsDir: options.config.dsDir, publicAlias: options.config.publicAlias,
-      components: getCatalog().filter((item) => item.kind === "components").length,
-      patterns: getCatalog().filter((item) => item.kind === "patterns").length,
+      components: getCatalog().filter((item) => item.kind === "components" && item.apiKind === "ui").length,
+      patterns: getCatalog().filter((item) => item.kind === "patterns" && item.apiKind === "ui").length,
       tokenCount: inspectTokens(root).tokens.length, showcaseUrl: getShowcaseUrl(),
       previewWatch: previewWatch?.status() ?? { state: "disabled" },
       mutations: mutations ? edits.status() : { enabled: false },
       build: summarizeBuild(builds()),
       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() },
       experimental: { apps: true, nativeSkills: era === "modern", nativeSkillActivation: "host-controlled" } };
   }
   async function read(uri, signal) {
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
+    if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -118,8 +129,9 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     else if (uri === `${PROJECT_URI}/catalog`) value = { items: getCatalog() };
     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 === PREVIEW_MANIFEST_URI && options.config.mcp.previewManifest) {
-      value = readPreviewManifest(options);
+      value = readPreviewManifest(previewOptions());
       if (!value) throw new Error("Preview resources are not built yet. Invoke ads_show_scenario to start the managed compiler.");
     }
     if (value !== undefined) return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(value) }] };
@@ -127,7 +139,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     if (uri === SCENARIO_APP_URI) return { contents: [{ uri, mimeType: APP_MIME, text: scenarioApp(), _meta: appMetadata({ nested: true }) }] };
     if (uri === PREVIEW_APP_URI && options.config.mcp.previewManifest) return { contents: [{ uri, mimeType: APP_MIME, text: previewApp(), _meta: appMetadata() }] };
     if (uri.startsWith("ads://assets/") && options.config.mcp.previewManifest) {
-      try { return { contents: [readPreviewAsset(options, uri)] }; }
+      try { return { contents: [readPreviewAsset(previewOptions(), uri)] }; }
       catch (error) { if (error.code === "ADS_PREVIEW_NOT_FOUND") throw new ResourceNotFoundError(uri, error.message); throw error; }
     }
     const app = allApps().find((entry) => appUri(entry.id) === uri);
@@ -150,20 +162,30 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return build;
   }
 
+  async function applyEdits(args,signal) {
+    const result = await edits.apply(args,signal);
+    if (result.applied) {
+      try {
+        if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration" || result.units?.includes("configuration")) await previewWatch?.reconfigure?.(loadConfig(root).config.mcp,true);
+        await refresh(true);
+      } catch (error) {result.warnings=[...(result.warnings ?? []),{rule:"mutation-notification",message:`Changes were applied, but preview refresh failed: ${error.message.slice(0,2000)}. Recheck ads_status and reopen the scenario.`}];}
+    }
+    return {...json(result),...(!result.ok ? {isError:true} : {})};
+  }
   function tools() {
     return [
       { name: "ads_status", description: "Start here for UI/ADS work: components, patterns, tokens/themes/branding, layout, behavior, motion and showcase review. Returns the exact project root/public API, workflow, project commands, editing mode and build diagnostics. When mutations.enabled, use guarded ads_apply_patch for ADS edits; otherwise use local editing tools.", schema: empty, call: () => json(status()) },
-      { name: "ads_catalog", description: "Before creating/changing UI, find existing public components/patterns 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"]).optional() }), call: ({ query: search = "", limit, kind }) => {
+      { 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();
         return json({ total: matches.length, items: matches.slice(0, limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), resourceUri: `${PROJECT_URI}/catalog` });
       } },
-      { name: "ads_scenarios", description: "Find an independently mountable token, component, pattern or composition preview. IDs derive from source filenames; covers lists public UI and tokens lists the real token inputs. Use ads_show_scenario with an exact returned id. Showcase and MCP use this same registry.", schema: query.extend({ kind: z.enum(["tokens", "components", "patterns", "composition"]).optional(), offset: z.number().int().min(0).default(0) }), call: ({ query: search = "", limit, kind, offset }) => {
-        const matches = getRegistry().scenarios.filter(item => (!kind || item.kind === kind) && `${item.id} ${item.title} ${item.covers.join(" ")} ${item.tokens.join(" ")}`.toLowerCase().includes(search.toLowerCase()));
+      { name: "ads_scenarios", description: "Find an independently mountable token, component, pattern or composition preview. IDs derive from source filenames; covers lists rendered public UI, exercises lists behavioral APIs and tokens lists the real token inputs. Use ads_show_scenario with an exact returned id. Showcase and MCP use this same registry.", schema: query.extend({ kind: z.enum(["tokens", "components", "patterns", "composition"]).optional(), offset: z.number().int().min(0).default(0) }), call: ({ query: search = "", limit, kind, offset }) => {
+        const matches = getRegistry().scenarios.filter(item => (!kind || item.kind === kind) && `${item.id} ${item.title} ${item.covers.join(" ")} ${(item.exercises ?? []).join(" ")} ${item.tokens.join(" ")}`.toLowerCase().includes(search.toLowerCase()));
         const units = edits.units();
         return json({ total: matches.length, scenarios: matches.slice(offset, offset + limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), ...(offset + limit < matches.length ? { nextOffset: offset + limit } : {}), diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios` });
       } },
-      { name: "ads_show_scenario", description: "Render one real token, component, pattern or composition scenario with its colocated fixtures and state adapter. First get an exact id from ads_scenarios or ads_catalog.previews. The managed compiler builds it on demand; errors return diagnostics instead of falsely current output. Requires MCP Apps plus host resource forwarding; fallback links to the same scenario in the project showcase.", schema: z.object({ id: z.string().min(1).max(256) }).strict(), _meta: { ui: { resourceUri: scenarioWidget() } }, call: async ({ id }, signal) => {
+      { name: "ads_show_scenario", title: "Scenario preview", description: "Render one real token, component, pattern or composition scenario with its colocated fixtures and state adapter. First get an exact id from ads_scenarios or ads_catalog.previews. The managed compiler builds it on demand; errors return diagnostics instead of falsely current output. Requires MCP Apps plus host resource forwarding; fallback links to the same scenario in the project showcase.", schema: z.object({ id: z.string().min(1).max(256) }).strict(), _meta: { ui: { resourceUri: scenarioWidget() } }, call: async ({ id }, signal) => {
         const entry = getRegistry().scenarios.find(item => item.id === id);
         if (!entry) throw new Error("Unknown scenario id. Read ads_scenarios; IDs must match discovered source entries.");
         if (getRegistry().diagnostics.length) throw new Error("Scenario registry has errors. Read ads://project/scenarios and fix its diagnostics.");
@@ -185,7 +207,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const result = checkProject(root);
         return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },
-      { name: "ads_skills", description: "Select one ADS workflow after ads_status: ads-designer for building/refining/debugging UI; ads-assimilate for a library reference; ads-import for another project's ADS; ads-motion for animation; ads-break-ui for stress testing. Then read that workflow with ads_read_skill. Listing does not activate a native skill.", schema: empty, call: () => json({ skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, ...frontmatter })) }) },
+      { name: "ads_skills", description: "Select one ADS workflow after ads_status: ads-designer for building/refining/debugging UI; ads-migrate for a library reference; ads-import for another project's ADS; ads-motion for animation; ads-break-ui for stress testing. Then read that workflow with ads_read_skill. Listing does not activate a native skill.", schema: empty, call: () => json({ skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, ...frontmatter })) }) },
       { name: "ads_read_skill", description: "Read a selected skill or relative supporting text file in bounded chunks. This is explicit instruction access, not automatic native skill activation/install.", schema: z.object({ name: z.string().max(64), file: z.string().max(300).default("SKILL.md"), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(8000).default(6000) }).strict(), call: ({ name, file, offset, limit }) => {
         const skill = skills.skills.find((entry) => entry.frontmatter.name === name);
         if (!skill) throw new Error("Unknown ADS skill name.");
@@ -196,7 +218,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         if (!("text" in content)) return json({ ...manifest, mimeType: content.mimeType, binary: true, note: "Read binary bytes via resources/read; this tool does not embed them." });
         return json({ ...manifest, text: content.text.slice(offset, offset + limit), offset, ...(offset + limit < content.text.length ? { nextOffset: offset + limit } : {}) });
       } },
-      { name: "ads_show_tokens", description: "Render an exact discovered token scenario with its project-owned templates and fixtures. Pass its id as category, discovered through ads_tokens.categories or ads_scenarios(kind: tokens). Omit category for the first project token scenario, or a generic definition inspector for older compilers.", schema: z.object({ category: z.string().max(256).optional() }).strict(), _meta: { ui: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI } }, call: async ({ category }, signal) => {
+      { name: "ads_show_tokens", title: "Token previews", description: "Render an exact discovered token scenario with its project-owned templates and fixtures. Pass its id as category, discovered through ads_tokens.categories or ads_scenarios(kind: tokens). Omit category for the first project token scenario, or a generic definition inspector for older compilers.", schema: z.object({ category: z.string().max(256).optional() }).strict(), _meta: { ui: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI } }, call: async ({ category }, signal) => {
         if (!category && options.config.mcp.previewManifest) category = tokenScenarios()[0]?.id;
         if (!category && options.config.mcp.previewManifest) throw new Error("No token scenario is registered. Colocate a token scenario and fixture before opening the preview; ads_tokens still inspects definitions.");
         if (category) {
@@ -214,27 +236,39 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         }
         return json({ widget: { resourceUri: TOKENS_APP_URI }, category: null, tokenCount: inspectTokens(root).tokens.length, dataUri: `${PROJECT_URI}/tokens`, showcaseUrl: getShowcaseUrl() });
       } },
-      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; 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_behaviors", description: "Discover owner-local behavioral guarantees for public hooks/APIs or private controllers, their scenario demonstrations, registered checks/profiles and fresh or stale execution evidence. Optional exercises links behavioral APIs to scenarios; covers remains rendered UI. Metadata and reachable calls do not prove a guarantee passed. Use ads_verify for selected registered checks.", schema: query.extend({ unit: z.string().max(256).optional(), api: z.string().max(200).optional() }), call: ({ query: search = "", limit, unit, api }) => {
+        const inventory = behaviorStatus(options);
+        const matches = inventory.contracts.filter(item => (!unit || item.unit === unit) && (!api || Object.values(item.subjects).some(subject => subject.api === api)) && JSON.stringify(item).toLowerCase().includes(search.toLowerCase()));
+        return json({ total: matches.length, contracts: matches.slice(0, limit).map(item => {
+          if (unit) return item;
+          const apis = Object.values(item.subjects).filter(subject => subject.api).map(subject => subject.api);
+          const demonstrations = [...new Set(Object.values(item.demonstrations).flat())];
+          return { unit: item.unit, file: item.file, apis: apis.slice(0, 20), apiCount: apis.length,
+            guarantees: item.guarantees.slice(0, 5).map(guarantee => ({ id: guarantee.id, result: guarantee.result })), guaranteeCount: item.guarantees.length,
+            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);
+        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 }) => {
         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 } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
-      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements. A real selected-unit re-export may remove a redundant export {}; placeholder. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. A runtime owner patch may also include its ds.config.json companion solely for that owner's inlineStyleFiles/styleWrites entries alongside its source. Unused permissions fail validation. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
+      ...(mutations ? [{ name: "ads_prepare_patch", description: "Prepare a Git patch without a separate project mirror. Create copies only one owner plus its declared companions into a local draft; edit that directory with local file tools. Diff checks baseline/source freshness and owner paths, then writes a patchFile under .ds/patches. Discard removes the draft. Live source is never changed; ads_apply_patch still validates all gates. Remote clients can continue sending inline Git diffs instead.", schema:z.object({unit:z.string().min(1).max(256),action:z.enum(["create","diff","discard"]).default("create"),draft:z.string().max(100).optional()}).strict(), call:args=>json(prepareUnitPatch(options,args)) },
+      {name:"ads_prepare_token_samples",description:"Reconcile a token scenario's consumed literal fixture samples. Removes undeclared tokens, preserves existing project bindings, and accepts explicit real-token/property/probe bindings. Reports unresolved token names; never guesses CSS meaning from token names. Returns an owner patchFile without changing source. Apply it through ads_apply_patch and review the real preview.",schema:z.object({id:z.string().min(1).max(256),bindings:z.array(z.object({token:z.string().max(256),property:z.string().max(100),probe:z.string().max(1000)}).passthrough()).max(1000).optional()}).strict(),call:args=>{
+        const {patch,...result}=reconcileTokenSamples(options,args);
+        return json({...result,removed:result.removed.slice(0,50),unresolved:result.unresolved.slice(0,50),unresolvedCount:result.unresolved.length,...storePreparedPatch(options,patch)});
+      }},
+      { name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements. A real selected-unit re-export may remove a redundant export {}; placeholder. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. A runtime owner patch may also include its ds.config.json companion solely for that owner's inlineStyleFiles/styleWrites entries alongside its source. Unused permissions fail validation. Set dryRun true to validate without writing. For genuinely coupled owner changes use ads_apply_transaction with one patch per owner. Fix rejected patches and inspect current previews after acceptance.",
         schema: z.object({ unit: z.string().min(1).max(256), dryRun: z.boolean(), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile."),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, _meta: { ui: { visibility: ["model"] } },
-        call: async (args, signal) => {
-          const result = await edits.apply(args, signal);
-          if (result.applied) {
-            try {
-              if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration") await previewWatch?.reconfigure?.(loadConfig(root).config.mcp, true);
-              await refresh(true);
-            }
-            catch (error) { result.warnings = [...(result.warnings ?? []), { rule: "mutation-notification", message: `Changes were applied, but preview refresh failed: ${error.message.slice(0, 2000)}. Recheck ads_status and reopen the scenario.` }]; }
-          }
-          return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
-        },
-      }] : []),
-      ...options.config.mcp.apps.map((app) => ({ name: `ads_show_${app.id.replaceAll("-", "_")}`, description: `${app.description ?? app.title}. Renders the project's built ${app.kind} examples through MCP Apps; text fallback provides the showcase URL.`, schema: empty, _meta: { ui: { resourceUri: appUri(app.id) } }, call: async (_args, signal) => {
+        call: applyEdits,
+      }, {name:"ads_apply_transaction",description:"Apply genuinely coupled ADS changes as 2–8 distinct owner Git patches. Each patch must obey its unit and narrow companion rules. Patches run in order; later patches use the earlier candidate's shared-entry content. Core guards, registered Oxlint/project checks and affected behavior checks validate the complete final candidate before any live source is written. Maximum 32 distinct files/16 MiB combined. Dry runs, failures and cancellation publish nothing; publication rolls back on write failure. Prefer ads_apply_patch for independent edits.",schema:z.object({patches:z.array(ownerPatch).min(2).max(mutationLimits.units),dryRun:z.boolean()}).strict(),annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:false,openWorldHint:false},_meta:{ui:{visibility:["model"]}},call:applyEdits}] : []),
+      ...options.config.mcp.apps.map((app) => ({ name: `ads_show_${app.id.replaceAll("-", "_")}`, title: app.title, description: `${app.description ?? app.title}. Renders the project's built ${app.kind} examples through MCP Apps; text fallback provides the showcase URL.`, schema: empty, _meta: { ui: { resourceUri: appUri(app.id) } }, call: async (_args, signal) => {
         // Validate readiness without embedding executable HTML in model results.
         const build = await previewBuild(app, signal);
         projectApp(options, app);
@@ -295,8 +329,8 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       try { const stat = statSync(file); return `${file}:${stat.mtimeMs}:${stat.size}`; } catch { return `${file}:missing`; }
     }).join("\n");
   }
-  const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json")]);
-  const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, app.file)));
+  const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json"), path.join(root, ".ds/behavior-results.json")]);
+  const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, previewArtifactPath(previewOptions(), app.file))));
   const assetFingerprint = () => resourceAssets().map(asset => asset.uri).sort().join("\n");
   let previous = fingerprint();
   let previousArtifacts = artifactFingerprint();
@@ -330,7 +364,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     previousAssets = assetFingerprint();
     previousBuild = JSON.stringify(builds());
     const targets = filesChanged ? era === "modern" ? resources().map((entry) => entry.uri).filter((uri) => !skills.files.has(uri)) : [...subscribed]
-      : [BUILD_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));
+      : [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 }); }
     return true;
   }
@@ -338,7 +372,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   timer?.unref();
   server.oninitialized = () => previewWatch?.start();
   server.onclose = () => { if (timer) clearInterval(timer); };
-  return { server, refresh, async close() { if (timer) clearInterval(timer); await server.close(); } };
+  return { server, refresh, async close() { if (timer) clearInterval(timer); if (!inspection) await verification.close(); await server.close(); } };
 }
 
 export async function startAdsMcp(directory = process.cwd(), { stdio = true, showcase = true, port = 0, mutations = false } = {}) {
@@ -353,25 +387,38 @@ export async function startAdsMcp(directory = process.cwd(), { stdio = true, sho
       { port, observe: notifications => createAdsMcp(directory, { era: "modern", previewWatch, showcaseUrl, inspection, mutations, notifications }) });
     process.stderr.write(`ADS showcase: ${host.url}\n`);
   }
-  const handle = stdio ? serveStdio(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations }).server, { legacy: "serve", onerror: (error) => process.stderr.write(`ads mcp: ${error.message}\n`) }) : null;
+  const transport = stdio ? new StdioServerTransport() : null;
+  const handle = stdio ? serveStdio(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations }).server, { transport, legacy: "serve", onerror: (error) => process.stderr.write(`ads mcp: ${error.message}\n`) }) : null;
   let closing;
   function close() {
     return closing ??= (async () => {
       inspection.edits?.cancel();
-      await host?.close();
-      await previewWatch.stop();
-      await handle?.close();
-      process.stdin.removeListener("end", disconnect);
+      // Stop every owned resource even if another close fails or has in-flight RPCs.
+      const results = await Promise.allSettled([
+        Promise.resolve().then(() => host?.close()),
+        previewWatch.stop(),
+        Promise.resolve().then(() => inspection.verification?.close()),
+        Promise.resolve().then(() => handle?.close()),
+      ]);
+      for (const event of ["end", "close", "error"]) process.stdin.removeListener(event, disconnect);
       for (const signal of ["SIGINT", "SIGTERM"]) process.removeListener(signal, disconnect);
       process.removeListener("exit", forceCleanup);
+      const errors = results.filter(result => result.status === "rejected").map(result => result.reason);
+      if (errors.length) throw new AggregateError(errors, "ADS shutdown failed");
     })();
   }
-  function disconnect() { void close(); }
+  function disconnect() { void close().catch(error => { process.stderr.write(`ads mcp: ${error.message}\n`); process.exitCode = 1; }); }
   function forceCleanup() { previewWatch.kill(); }
   // Probe instances have no managed child; a real connection activates it.
-  // stdin EOF also cleans up the compiler when the host drops the transport.
-  if (stdio) process.stdin.once("end", disconnect);
+  // The SDK also closes its wire on stdout failure. Closing a probe instance
+  // must not shut the runtime down, so observe the wire, not server.onclose.
+  if (transport) {
+    const wireClosed = transport.onclose;
+    transport.onclose = () => { try { wireClosed?.(); } finally { disconnect(); } };
+    for (const event of ["end", "close", "error"]) process.stdin.once(event, disconnect);
+    if (process.stdin.readableEnded || process.stdin.destroyed) disconnect();
+  }
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, disconnect);
   process.once("exit", forceCleanup);
-  return { close, url: host?.url };
+  return { close, url: host?.url, previewRevision: () => readPreviewManifest(withPreviewSession(loadConfig(root), previewWatch.resourceSession()))?.revision ?? null };
 }

package/dist/mcp/showcase-host.mjs

@@ -56,13 +56,17 @@ export async function startShowcaseHost(factory, { port = 0, observe } = {}) {
   let closing;
   return { url: `http://127.0.0.1:${web.address().port}/`, close() {
     return closing ??= (async () => {
-      for (const request of requests) request.abort();
-      await observer?.close();
-      await handler.close();
-      await sandbox?.close();
+      // Close sockets first: live subscriptions and preview requests must not
+      // hold shutdown open while protocol instances wait for cancellation.
       const stopped = new Promise(resolve => web.close(resolve));
+      for (const request of requests) request.abort();
       web.closeAllConnections();
-      await stopped;
+      const results = await Promise.allSettled([stopped,
+        Promise.resolve().then(() => observer?.close()),
+        handler.close(), sandbox?.close(),
+      ]);
+      const errors = results.filter(result => result.status === "rejected").map(result => result.reason);
+      if (errors.length) throw new AggregateError(errors, "Showcase shutdown failed");
     })();
   } };
 }

package/dist/mcp/text-diff.mjs

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

package/dist/preview-resources.mjs

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

package/dist/preview-scope.mjs

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

package/dist/public-api.mjs

@@ -0,0 +1,39 @@
+import path from "node:path";
+import ts from "typescript";
+import { isDevelopmentFile, isInside } from "./config.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+export function publicApi(program, options) {
+  const checker = program.getTypeChecker();
+  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
+  const module = entry && checker.getSymbolAtLocation(entry);
+  const items = [];
+  for (const exported of module ? checker.getExportsOfModule(module) : []) {
+    let symbol = exported;
+    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+    const file = declaration.getSourceFile().fileName;
+    if (isDevelopmentFile(file, options)) continue;
+    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : isInside(path.join(options.dsRoot, "controllers"), file) ? "controllers" : null;
+    if (!kind) continue;
+    let renderable = false;
+    function visit(node) {
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
+      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
+      if (ts.isTaggedTemplateExpression(node)) {
+        let tag = node.tag;
+        if (ts.isCallExpression(tag)) tag = tag.expression;
+        let base = tag;
+        while (ts.isPropertyAccessExpression(base)) base = base.expression;
+        const symbol = checker.getSymbolAtLocation(base);
+        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(declaration);
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral: !!(type.getCallSignatures().length || type.getConstructSignatures().length) });
+  }
+  return items;
+}