@jay-framework/aiditor 0.19.7 → 0.20.0

package/dist/index.js

@@ -5,11 +5,13 @@ import path, { extname } from "path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import fs$1 from "fs";
 import crypto from "crypto";
-import { load } from "js-yaml";
+import yaml, { load } from "js-yaml";
 import { getLogger } from "@jay-framework/logger";
 import { fileURLToPath } from "url";
 import { spawn } from "child_process";
 import { scanRoutes } from "@jay-framework/stack-route-scanner";
+import { parseContract, ContractTagType } from "@jay-framework/compiler-jay-html";
+import { checkValidationErrors } from "@jay-framework/compiler-shared";
 import { setActionCallerOptions } from "@jay-framework/stack-client-runtime";
 const getAiditorBootstrap = makeJayQuery(
   "aiditor.getAiditorBootstrap"
@@ -20,7 +22,7 @@ const getAiditorBootstrap = makeJayQuery(
   };
 });
 const getProjectInfoAction = makeJayQuery("aditor.getProjectInfo").withServices(DEV_SERVER_SERVICE).withHandler(async (input, devServer) => {
-  const routes = devServer.listRoutes();
+  const routes = await devServer.refreshRoutes();
   return { routes, httpBaseUrl: input.jayDevUrl };
 });
 const getPageParamsAction = makeJayStream("aditor.getPageParams").withServices(DEV_SERVER_SERVICE).withHandler(async function* (input, devServer) {
@@ -367,6 +369,30 @@ function optionalString(obj, field) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
+function optionalBoolean(obj, field) {
+  const value = obj[field];
+  return typeof value === "boolean" ? value : void 0;
+}
+function validateInteraction(raw, path2, errors) {
+  if (raw === void 0) return void 0;
+  if (!isRecord(raw)) {
+    errors.push({ path: path2, message: "interaction must be an object" });
+    return void 0;
+  }
+  const mode = raw.mode;
+  if (mode !== "reference" && mode !== "stage-place") {
+    errors.push({
+      path: `${path2}.mode`,
+      message: 'mode must be "reference" or "stage-place"'
+    });
+    return void 0;
+  }
+  return {
+    mode,
+    persistOnPage: optionalBoolean(raw, "persistOnPage"),
+    stagePromptTemplate: optionalString(raw, "stagePromptTemplate")
+  };
+}
 function validateAddMenuItem(raw, path2) {
   const errors = [];
   if (!isRecord(raw)) {
@@ -390,6 +416,11 @@ function validateAddMenuItem(raw, path2) {
   if (errors.length > 0 || !id || !title || !category || !prompt) {
     return { item: null, errors };
   }
+  const interaction = validateInteraction(
+    raw.interaction,
+    `${path2}.interaction`,
+    errors
+  );
   return {
     item: {
       id,
@@ -399,7 +430,8 @@ function validateAddMenuItem(raw, path2) {
       pluginName: optionalString(raw, "pluginName"),
       packageName: optionalString(raw, "packageName"),
       subCategory: optionalString(raw, "subCategory"),
-      thumbnail: optionalString(raw, "thumbnail")
+      thumbnail: optionalString(raw, "thumbnail"),
+      ...interaction ? { interaction } : {}
     },
     errors
   };
@@ -431,11 +463,11 @@ function validateAddMenuCatalogFile(raw, sourcePath) {
   }
   return { file: { items }, errors };
 }
-function parsePluginsIndexYaml(yaml) {
+function parsePluginsIndexYaml(yaml2) {
   const entries = [];
   let currentPlugin = null;
   let inContracts = false;
-  for (const line of yaml.split("\n")) {
+  for (const line of yaml2.split("\n")) {
     const pluginMatch = line.match(/^  - name:\s*(.+)$/);
     if (pluginMatch && !line.startsWith("      ")) {
       currentPlugin = pluginMatch[1].trim();
@@ -512,8 +544,8 @@ async function isPluginInstalled(projectRoot, pluginName) {
 async function parsePluginsIndexContracts(projectRoot) {
   const indexPath = path.join(projectRoot, "agent-kit", "plugins-index.yaml");
   try {
-    const yaml = await fs.readFile(indexPath, "utf-8");
-    return parsePluginsIndexYaml(yaml);
+    const yaml2 = await fs.readFile(indexPath, "utf-8");
+    return parsePluginsIndexYaml(yaml2);
   } catch (e) {
     const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
     if (code === "ENOENT") return [];
@@ -529,10 +561,10 @@ async function parsePluginYamlContracts(projectRoot, pluginName) {
     "plugin.yaml"
   );
   try {
-    const yaml = await fs.readFile(pluginYamlPath, "utf-8");
+    const yaml2 = await fs.readFile(pluginYamlPath, "utf-8");
     const entries = [];
     let inContracts = false;
-    for (const line of yaml.split("\n")) {
+    for (const line of yaml2.split("\n")) {
       if (line.trim() === "contracts:") {
         inContracts = true;
         continue;
@@ -638,6 +670,65 @@ async function listAddMenuItems(projectRoot) {
     warnings
   };
 }
+const DEFAULT_PUBLIC_FOLDER = "./public";
+function resolveProjectPublicDir(projectDir) {
+  const configPath = path.join(projectDir, ".jay");
+  let publicFolder = DEFAULT_PUBLIC_FOLDER;
+  if (fs$1.existsSync(configPath)) {
+    try {
+      const parsed = yaml.load(fs$1.readFileSync(configPath, "utf-8"));
+      if (parsed?.devServer?.publicFolder) {
+        publicFolder = parsed.devServer.publicFolder;
+      }
+    } catch {
+    }
+  }
+  return path.resolve(projectDir, publicFolder);
+}
+function sanitizeAttachmentFileName(name) {
+  const base = path.basename(name).replace(/[^\w.\-]+/g, "_");
+  return base.length > 0 ? base : "attachment";
+}
+function projectHasWixMediaPlugin(projectDir) {
+  const indexPath = path.join(projectDir, "agent-kit", "plugins-index.yaml");
+  if (!fs$1.existsSync(indexPath)) return false;
+  try {
+    const parsed = yaml.load(fs$1.readFileSync(indexPath, "utf-8"));
+    return parsed.plugins?.some((plugin) => plugin.name === "wix-media") ?? false;
+  } catch {
+    return false;
+  }
+}
+function buildVisualAttachmentRules(projectDir) {
+  const publicDir = resolveProjectPublicDir(projectDir);
+  const publicFolderLabel = path.relative(projectDir, publicDir) || "public";
+  const lines = [
+    "User-uploaded file attachments (per marker):",
+    "- Each attachment is on disk at the listed path — Read it for context (layout, colors, dimensions, inspiration).",
+    "- Use the marker instruction to decide whether to place the file in the project:",
+    "  - Instruction asks to display, embed, show, use, set as image/background, or otherwise wire the attachment into the page → copy the file from the attachment path into the project before adding src/href in jay-html. Do not reference build/aditor paths in templates.",
+    '  - Attachment is reference or inspiration only (mood, "like this", layout reference) and the instruction does not ask to embed it → read for context only; do not copy into the project.',
+    `- Local static hosting: copy into \`${publicFolderLabel}/\` (keep the original filename when safe). Reference in jay-html as \`/{filename}\` (e.g. \`src="/photo.png"\`).`,
+    "- Never invent placeholder image URLs."
+  ];
+  if (projectHasWixMediaPlugin(projectDir)) {
+    lines.push(
+      "- Wix Media Manager (`@jay-framework/wix-media` is installed): when the user wants this image as a live site asset, run `jay-stack run wix-media/upload-public` on the attachment file (or copy to public first if the command expects a project path), then use the returned Wix CDN URL in jay-html. Do not duplicate Wix CDN assets into public/. Read agent-kit/designer/wix-media.md for URL patterns."
+    );
+  }
+  return lines.join("\n");
+}
+function persistFile$1(file, destDir, fileName) {
+  fs$1.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, fileName);
+  fs$1.copyFileSync(file.path, dest);
+  return dest;
+}
+function persistVisualTaskAttachment(file, taskAttDir) {
+  const originalFileName = sanitizeAttachmentFileName(file.name);
+  const taskCopyPath = persistFile$1(file, taskAttDir, originalFileName);
+  return { taskCopyPath, originalFileName };
+}
 const CATALOG = [
   {
     pluginName: "wix-server-client",
@@ -814,6 +905,26 @@ function buildLegacyPluginManifestPromptSection(selectedPlugins) {
 }
 function buildRouteMigrationPromptSection(routeMigration) {
   if (!routeMigration) return "";
+  if (routeMigration.reason === "page-info-route-edit") {
+    return [
+      "",
+      "## Page route change (required — apply now)",
+      "",
+      `- Current route: \`${routeMigration.currentRoute}\``,
+      `- New route: \`${routeMigration.plannedRoute}\``,
+      "",
+      "The user approved changing this page's URL. Implement the migration now:",
+      "- Move or rename `src/pages/` files and directories so the page is served at the new route.",
+      "- Jay Stack directory mapping (URL → folder under `src/pages/`):",
+      "  - `/segment/:param` → `segment/[param]/`",
+      "  - optional `/{/:param}` (Express) → `segment/[[param]]/` (double brackets)",
+      "  - catch-all `/*param` → `segment/[...param]/`",
+      "- After moving, remove the old `page.jay-html` (and empty parent dirs if safe).",
+      "- Update all internal links, navigation, breadcrumbs, and dynamic links across the site that reference the old route.",
+      "- Keep headless component bindings and jay-params consistent with the new route shape.",
+      ""
+    ].join("\n");
+  }
   return [
     "",
     "## Planned route migration (apply only if user request requires it)",
@@ -826,6 +937,35 @@ function buildRouteMigrationPromptSection(routeMigration) {
     ""
   ].join("\n");
 }
+function buildPageAssetsPromptSection(assets) {
+  const active = assets.filter((a) => a.persistOnPage && !a.userRemoved);
+  if (active.length === 0) return "";
+  const lines = [
+    "Page assets (in scope for this page — use when referenced in marker instructions or @mentions):"
+  ];
+  for (const asset of active) {
+    lines.push(`- ${asset.title} (id: ${asset.id})`);
+    for (const line of asset.prompt.trim().split("\n")) {
+      lines.push(`  ${line}`);
+    }
+  }
+  return lines.join("\n");
+}
+function buildPageComponentsPromptSection(components) {
+  if (components.length === 0) return "";
+  const lines = [
+    "Page components (from page.jay-html — use when referenced in marker instructions or @mentions):"
+  ];
+  for (const component of components) {
+    lines.push(
+      `- ${component.title}${component.componentKey ? ` (key: ${component.componentKey})` : ""}`
+    );
+    for (const line of component.prompt.trim().split("\n")) {
+      lines.push(`  ${line}`);
+    }
+  }
+  return lines.join("\n");
+}
 function buildNonVisualPrompt(config, notes, imagePath) {
   const lines = [
     `Project directory: ${config.projectDir}`,
@@ -914,6 +1054,8 @@ function parseNotesField(notes) {
           annotations: j.annotations,
           previewNavLog,
           addMenuAttachments: j.addMenuAttachments,
+          pageAssets: j.pageAssets,
+          pageComponents: j.pageComponents,
           routeMigration: j.routeMigration
         },
         plain: ""
@@ -926,6 +1068,8 @@ function parseNotesField(notes) {
         structured: {
           annotations: j.annotations,
           addMenuAttachments: j.addMenuAttachments,
+          pageAssets: j.pageAssets,
+          pageComponents: j.pageComponents,
           routeMigration: j.routeMigration
         },
         structuredVideo: null,
@@ -936,6 +1080,26 @@ function parseNotesField(notes) {
   }
   return empty();
 }
+function appendVisualAttachmentLines(body, attachments, indent = "") {
+  if (attachments.length === 0) {
+    body.push(`${indent}Attachments: (none)`);
+    return;
+  }
+  body.push(
+    `${indent}Attachments (read from disk; belong to this annotation only):`
+  );
+  for (const att of attachments) {
+    body.push(
+      `${indent}- ${att.taskCopyPath} (filename: ${att.originalFileName})`
+    );
+  }
+}
+function visualPromptHasAttachments(attachmentMap) {
+  for (const list of attachmentMap.values()) {
+    if (list.length > 0) return true;
+  }
+  return false;
+}
 function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, attachmentPathsByAnnotationId, addMenu = { itemById: /* @__PURE__ */ new Map() }) {
   const preamble = [
     `Project directory: ${config.projectDir}`,
@@ -952,9 +1116,20 @@ function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, att
     "- The annotation instructions and attachments are listed below in text — do NOT rely on screenshot text.",
     "",
     ANNOTATION_TARGETING_RULES,
-    ""
+    "",
+    ...visualPromptHasAttachments(attachmentPathsByAnnotationId) ? [buildVisualAttachmentRules(config.projectDir), ""] : []
   ];
   const body = [];
+  const pageComponents = parsed.structured?.pageComponents ?? addMenu.pageComponents ?? [];
+  if (pageComponents.length > 0) {
+    const section = buildPageComponentsPromptSection(pageComponents);
+    if (section.trim()) body.push(section.trim(), "");
+  }
+  const pageAssets = parsed.structured?.pageAssets ?? addMenu.pageAssets ?? [];
+  if (pageAssets.length > 0) {
+    const section = buildPageAssetsPromptSection(pageAssets);
+    if (section.trim()) body.push(section.trim(), "");
+  }
   const routeMigration = parsed.structured?.routeMigration ?? void 0;
   const requestAddMenu = parsed.structured?.addMenuAttachments ?? [];
   if (requestAddMenu.length > 0) {
@@ -981,16 +1156,7 @@ function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, att
         appendLegacyBindingLines(body, ann, ann.id);
       }
       body.push(`Instruction: ${ann.instruction.trim()}`);
-      if (paths.length > 0) {
-        body.push(
-          "Attachments (read these files; they belong to this annotation only):"
-        );
-        for (const p of paths) {
-          body.push(`- ${p}`);
-        }
-      } else {
-        body.push("Attachments: (none)");
-      }
+      appendVisualAttachmentLines(body, paths);
       body.push("");
     }
   } else {
@@ -1025,7 +1191,8 @@ function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frame
     "",
     ...navLines,
     ANNOTATION_TARGETING_RULES,
-    ""
+    "",
+    ...visualPromptHasAttachments(attachmentPathsByPin) ? [buildVisualAttachmentRules(config.projectDir), ""] : []
   ];
   if (!sv || sv.annotations.length === 0) {
     return [
@@ -1039,6 +1206,16 @@ function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frame
     pinById.set(a.id, String(i + 1));
   }
   const body = [];
+  const pageComponents = sv.pageComponents ?? addMenu.pageComponents ?? [];
+  if (pageComponents.length > 0) {
+    const section = buildPageComponentsPromptSection(pageComponents);
+    if (section.trim()) body.push(section.trim(), "");
+  }
+  const pageAssets = sv.pageAssets ?? addMenu.pageAssets ?? [];
+  if (pageAssets.length > 0) {
+    const section = buildPageAssetsPromptSection(pageAssets);
+    if (section.trim()) body.push(section.trim(), "");
+  }
   const routeMigration = sv.routeMigration;
   const requestAddMenu = sv.addMenuAttachments ?? [];
   if (requestAddMenu.length > 0) {
@@ -1079,10 +1256,7 @@ function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frame
         body.push(`  Page path at this pin: ${ann.pagePathAtTime}`);
       }
       if (paths.length > 0) {
-        body.push(
-          "  Attachments (read these files; they belong to this pin only):"
-        );
-        for (const p of paths) body.push(`  - ${p}`);
+        appendVisualAttachmentLines(body, paths, "  ");
       } else {
         body.push("  Attachments: (none)");
       }
@@ -1097,6 +1271,19 @@ function persistFile(file, destDir, fileName) {
   fs$1.copyFileSync(file.path, dest);
   return dest;
 }
+function persistExtraFileAttachments(taskDir, extraFiles) {
+  const attachmentPaths = /* @__PURE__ */ new Map();
+  for (const [key, file] of Object.entries(extraFiles)) {
+    if (!key.startsWith("attachment_")) continue;
+    const pinId = key.split("_")[1];
+    const attDir = path.join(taskDir, `annotation-${pinId}`);
+    const persisted = persistVisualTaskAttachment(file, attDir);
+    const existing = attachmentPaths.get(pinId) ?? [];
+    existing.push(persisted);
+    attachmentPaths.set(pinId, existing);
+  }
+  return attachmentPaths;
+}
 const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHandler(async function* (input) {
   const projectDir = process.cwd();
   const buildFolder = path.join(projectDir, "build");
@@ -1110,7 +1297,8 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
   const isVisual = !!input.visualTask;
   const catalog = await listAddMenuItems(projectDir);
   const addMenu = {
-    itemById: new Map(catalog.items.map((item) => [item.id, item]))
+    itemById: new Map(catalog.items.map((item) => [item.id, item])),
+    pageAssets: parsed.structured?.pageAssets ?? parsed.structuredVideo?.pageAssets ?? void 0
   };
   let promptContent;
   if (isVideo) {
@@ -1136,16 +1324,7 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
         markersOnly: markers ? persistFile(markers, frameDir, "markers-only.png") : ""
       });
     }
-    const attachmentPathsByPin = /* @__PURE__ */ new Map();
-    for (const [key, file] of Object.entries(extra)) {
-      if (!key.startsWith("attachment_")) continue;
-      const pinId = key.split("_")[1];
-      const attDir = path.join(taskDir, `annotation-${pinId}`);
-      const filePath = persistFile(file, attDir);
-      const existing = attachmentPathsByPin.get(pinId) ?? [];
-      existing.push(filePath);
-      attachmentPathsByPin.set(pinId, existing);
-    }
+    const attachmentPathsByPin = persistExtraFileAttachments(taskDir, extra);
     promptContent = buildVisualPromptVideo(
       config,
       input.pageRoute ?? "/",
@@ -1167,16 +1346,10 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
       )
     };
     const extraFiles = input.extraFiles ?? {};
-    const attachmentPathsByAnnotationId = /* @__PURE__ */ new Map();
-    for (const [key, file] of Object.entries(extraFiles)) {
-      if (!key.startsWith("attachment_")) continue;
-      const pinId = key.split("_")[1];
-      const attDir = path.join(taskDir, `annotation-${pinId}`);
-      const filePath = persistFile(file, attDir);
-      const existing = attachmentPathsByAnnotationId.get(pinId) ?? [];
-      existing.push(filePath);
-      attachmentPathsByAnnotationId.set(pinId, existing);
-    }
+    const attachmentPathsByAnnotationId = persistExtraFileAttachments(
+      taskDir,
+      extraFiles
+    );
     promptContent = buildVisualPromptDual(
       config,
       input.pageRoute ?? "/",
@@ -2712,10 +2885,10 @@ function isValidInstallSpec(spec) {
 function getPluginSourcesPath(projectRoot) {
   return path.join(projectRoot, ".aiditor", "plugin-sources.yaml");
 }
-function parsePluginSourcesYaml(yaml) {
+function parsePluginSourcesYaml(yaml2) {
   const sources = [];
   let current = null;
-  for (const line of yaml.split("\n")) {
+  for (const line of yaml2.split("\n")) {
     const itemMatch = line.match(/^  - pluginName:\s*(.+)$/);
     if (itemMatch) {
       if (current?.pluginName && current.packageName && current.installSpec) {
@@ -3443,24 +3616,61 @@ function pluginNameFromItemId(itemId) {
   if (colon <= 0) return null;
   return itemId.slice(0, colon);
 }
-async function resolveContractParamsForItem(projectRoot, item) {
-  const pluginName = item.pluginName ?? pluginNameFromItemId(item.id);
-  const contractName = contractNameFromItemId(item.id);
-  if (!pluginName || !contractName) return null;
-  const contractPath = path.join(
+async function resolveContractFilePath(projectRoot, input) {
+  const materializedPath = path.join(
     projectRoot,
     "agent-kit",
     "materialized-contracts",
-    pluginName,
-    `${contractName}.jay-contract`
+    input.pluginName,
+    `${input.contractName}.jay-contract`
   );
-  let yaml;
+  const indexPath = path.join(projectRoot, "agent-kit", "plugins-index.yaml");
+  try {
+    const indexYaml = await fs.readFile(indexPath, "utf-8");
+    const index = load(indexYaml);
+    const plugin = index.plugins?.find((p) => p.name === input.pluginName);
+    const contract = plugin?.contracts?.find(
+      (c) => c.name === input.contractName
+    );
+    if (contract?.path) {
+      const resolved = path.resolve(
+        projectRoot,
+        contract.path.replace(/^\.\//, "")
+      );
+      try {
+        await fs.access(resolved);
+        return resolved;
+      } catch {
+      }
+    }
+  } catch (e) {
+    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+    if (code !== "ENOENT") throw e;
+  }
+  try {
+    await fs.access(materializedPath);
+    return materializedPath;
+  } catch {
+    throw new Error(
+      `Contract "${input.contractName}" not found for plugin "${input.pluginName}". Check agent-kit/plugins-index.yaml or run \`yarn agent-kit\`.`
+    );
+  }
+}
+async function resolveContractParamsForItem(projectRoot, item) {
+  const pluginName = item.pluginName ?? pluginNameFromItemId(item.id);
+  const contractName = contractNameFromItemId(item.id);
+  if (!pluginName || !contractName) return null;
+  let yaml2;
   try {
-    yaml = await fs.readFile(contractPath, "utf-8");
+    const contractPath = await resolveContractFilePath(projectRoot, {
+      pluginName,
+      contractName
+    });
+    yaml2 = await fs.readFile(contractPath, "utf-8");
   } catch {
     return null;
   }
-  return parseContractParamsFromYaml(yaml, contractName, pluginName);
+  return parseContractParamsFromYaml(yaml2, contractName, pluginName);
 }
 const listAddMenuItemsAction = makeJayQuery("aiditor.listAddMenuItems").withServices(DEV_SERVER_SERVICE).withHandler(async () => {
   const projectRoot = process.cwd();
@@ -3792,6 +4002,460 @@ const writePluginSourceAction = makeJayQuery("aiditor.writePluginSource").withSe
   await writePluginSource(projectRoot, input);
   return { ok: true };
 });
+const PAGE_ASSETS_VERSION = 1;
+function pageAssetsDirSegment(contextKey) {
+  const trimmed = contextKey.replace(/^\//, "").replace(/\/$/, "");
+  return trimmed === "" ? "_root" : trimmed.replace(/\//g, "--");
+}
+function emptyPageAssetsFile(input) {
+  return {
+    version: PAGE_ASSETS_VERSION,
+    contextKey: input.contextKey,
+    pageRoute: input.pageRoute,
+    renderedUrl: input.renderedUrl,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    assets: [],
+    suppressedDetectedKeys: []
+  };
+}
+function getPageAssetsFilePath(projectDir, contextKey) {
+  const segment = pageAssetsDirSegment(contextKey);
+  return path.join(
+    projectDir,
+    ".aiditor",
+    "page-assets",
+    segment,
+    "page-assets.json"
+  );
+}
+const fileMutexChains$1 = /* @__PURE__ */ new Map();
+async function withPageAssetsFileLock(filePath, fn) {
+  const previous = fileMutexChains$1.get(filePath) ?? Promise.resolve();
+  let release;
+  const next = new Promise((resolve) => {
+    release = resolve;
+  });
+  fileMutexChains$1.set(filePath, next);
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (fileMutexChains$1.get(filePath) === next) {
+      fileMutexChains$1.delete(filePath);
+    }
+  }
+}
+async function readPageAssetsFile(filePath, fallback) {
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== PAGE_ASSETS_VERSION || typeof parsed.contextKey !== "string" || typeof parsed.pageRoute !== "string" || !Array.isArray(parsed.assets)) {
+      return fallback;
+    }
+    return {
+      version: PAGE_ASSETS_VERSION,
+      contextKey: parsed.contextKey,
+      pageRoute: parsed.pageRoute,
+      renderedUrl: typeof parsed.renderedUrl === "string" ? parsed.renderedUrl : void 0,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      assets: parsed.assets.filter(
+        (a) => !!a && typeof a === "object" && typeof a.id === "string" && typeof a.title === "string" && typeof a.prompt === "string"
+      ),
+      suppressedDetectedKeys: Array.isArray(parsed.suppressedDetectedKeys) ? parsed.suppressedDetectedKeys.filter(
+        (k) => typeof k === "string"
+      ) : [],
+      routeMigration: parsed.routeMigration
+    };
+  } catch (e) {
+    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+    if (code === "ENOENT") {
+      return fallback;
+    }
+    throw e;
+  }
+}
+async function writePageAssetsFileAtomic(filePath, file) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  const body = `${JSON.stringify(file, null, 2)}
+`;
+  await fs.writeFile(tmp, body, "utf-8");
+  await fs.rename(tmp, filePath);
+}
+async function getPageAssets(projectDir, input) {
+  const filePath = getPageAssetsFilePath(projectDir, input.contextKey);
+  const fallback = emptyPageAssetsFile(input);
+  return withPageAssetsFileLock(
+    filePath,
+    async () => readPageAssetsFile(filePath, fallback)
+  );
+}
+async function savePageAssets(projectDir, file) {
+  const filePath = getPageAssetsFilePath(projectDir, file.contextKey);
+  const next = {
+    ...file,
+    version: PAGE_ASSETS_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await withPageAssetsFileLock(filePath, async () => {
+    await writePageAssetsFileAtomic(filePath, next);
+  });
+}
+const PAGE_META_VERSION = 1;
+function pageMetaDirSegment(contextKey) {
+  const trimmed = contextKey.replace(/^\//, "").replace(/\/$/, "");
+  return trimmed === "" ? "_root" : trimmed.replace(/\//g, "--");
+}
+function emptyPageMetaFile(input) {
+  return {
+    version: PAGE_META_VERSION,
+    contextKey: input.contextKey,
+    pageRoute: input.pageRoute,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getPageMetaFilePath(projectDir, contextKey) {
+  const segment = pageMetaDirSegment(contextKey);
+  return path.join(
+    projectDir,
+    ".aiditor",
+    "page-meta",
+    segment,
+    "page-meta.json"
+  );
+}
+const fileMutexChains = /* @__PURE__ */ new Map();
+async function withPageMetaFileLock(filePath, fn) {
+  const previous = fileMutexChains.get(filePath) ?? Promise.resolve();
+  let release;
+  const next = new Promise((resolve) => {
+    release = resolve;
+  });
+  fileMutexChains.set(filePath, next);
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (fileMutexChains.get(filePath) === next) {
+      fileMutexChains.delete(filePath);
+    }
+  }
+}
+async function readPageMetaFile(filePath, fallback) {
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== PAGE_META_VERSION || typeof parsed.contextKey !== "string" || typeof parsed.pageRoute !== "string") {
+      return fallback;
+    }
+    return {
+      version: PAGE_META_VERSION,
+      contextKey: parsed.contextKey,
+      pageRoute: parsed.pageRoute,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      plannedRoute: typeof parsed.plannedRoute === "string" ? parsed.plannedRoute : void 0,
+      routeMigration: parsed.routeMigration
+    };
+  } catch (e) {
+    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+    if (code === "ENOENT") {
+      return fallback;
+    }
+    throw e;
+  }
+}
+async function readLegacyPageAssets(projectDir, contextKey) {
+  const filePath = getPageAssetsFilePath(projectDir, contextKey);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.contextKey !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function writePageMetaFileAtomic(filePath, file) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  const body = `${JSON.stringify(file, null, 2)}
+`;
+  await fs.writeFile(tmp, body, "utf-8");
+  await fs.rename(tmp, filePath);
+}
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getPageMeta(projectDir, input) {
+  const filePath = getPageMetaFilePath(projectDir, input.contextKey);
+  const fallback = emptyPageMetaFile(input);
+  return withPageMetaFileLock(filePath, async () => {
+    if (await fileExists(filePath)) {
+      return readPageMetaFile(filePath, fallback);
+    }
+    const legacy = await readLegacyPageAssets(projectDir, input.contextKey);
+    if (!legacy) return fallback;
+    const migrated = {
+      ...fallback,
+      contextKey: input.contextKey,
+      pageRoute: input.pageRoute,
+      plannedRoute: legacy.routeMigration?.plannedRoute,
+      routeMigration: legacy.routeMigration,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writePageMetaFileAtomic(filePath, migrated);
+    return migrated;
+  });
+}
+async function savePageMeta(projectDir, file) {
+  const filePath = getPageMetaFilePath(projectDir, file.contextKey);
+  const next = {
+    ...file,
+    version: PAGE_META_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await withPageMetaFileLock(filePath, async () => {
+    await writePageMetaFileAtomic(filePath, next);
+  });
+}
+function formatTagDescription(description) {
+  if (!description?.length) return void 0;
+  return description.join(" ");
+}
+function tagKindFromTypes(types) {
+  if (types.includes(ContractTagType.subContract)) return "sub-contract";
+  if (types.includes(ContractTagType.interactive)) return "interactive";
+  if (types.includes(ContractTagType.variant)) return "variant";
+  return "data";
+}
+function flattenTags(tags, parentPath = "") {
+  const results = [];
+  for (const tag of tags) {
+    const tagPath = parentPath ? `${parentPath}.${tag.tag}` : tag.tag;
+    results.push({
+      tagPath,
+      tagKind: tagKindFromTypes(tag.type),
+      linkedContract: tag.link,
+      description: formatTagDescription(tag.description)
+    });
+    if (tag.tags?.length) {
+      for (const child of tag.tags) {
+        const childPath = `${tagPath}.${child.tag}`;
+        results.push({
+          tagPath: childPath,
+          tagKind: tagKindFromTypes(child.type),
+          linkedContract: child.link,
+          description: formatTagDescription(child.description)
+        });
+      }
+    }
+  }
+  return results;
+}
+async function resolveContractTagsForComponent(projectRoot, input) {
+  const contractPath = await resolveContractFilePath(projectRoot, input);
+  const yaml2 = await fs.readFile(contractPath, "utf-8");
+  const fileName = path.basename(contractPath);
+  const contract = checkValidationErrors(
+    parseContract(yaml2, fileName)
+  );
+  return flattenTags(contract.tags);
+}
+const getPageMetaAction = makeJayQuery("aiditor.getPageMeta").withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  const file = await getPageMeta(projectRoot, input);
+  return { file };
+});
+const savePageMetaAction = makeJayQuery("aiditor.savePageMeta").withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  await savePageMeta(projectRoot, input.file);
+  return { ok: true };
+});
+const getContractInspectorTagsAction = makeJayQuery(
+  "aiditor.getContractInspectorTags"
+).withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  const tags = await resolveContractTagsForComponent(projectRoot, input);
+  return { tags };
+});
+function pluginNameFromPackageAttr(pluginAttr) {
+  const prefix = "@jay-framework/";
+  if (pluginAttr.startsWith(prefix)) {
+    return pluginAttr.slice(prefix.length);
+  }
+  return pluginAttr;
+}
+const HEADLESS_SCRIPT_RE = /<script[^>]*type\s*=\s*["']application\/jay-headless["'][^>]*>/gi;
+const JAY_TAG_RE = /<jay:([a-zA-Z][\w-]*)\b/g;
+function readScriptAttr(tag, attr) {
+  const re = new RegExp(`${attr}\\s*=\\s*["']([^"']+)["']`, "i");
+  const m = tag.match(re);
+  return m?.[1]?.trim();
+}
+function humanizeContractName(contract) {
+  return contract.split(/[-_]/u).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function catalogItemForDetection(pluginName, contract, catalogByPluginContract) {
+  return catalogByPluginContract.get(`${pluginName}:${contract}`);
+}
+function buildCatalogLookup(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (item.pluginName && item.id.includes(":")) {
+      const contract = item.id.split(":").slice(1).join(":");
+      map.set(`${item.pluginName}:${contract}`, item);
+    }
+  }
+  return map;
+}
+function detectPageComponentsFromHtml(pageHtml, catalogItems = []) {
+  const catalogByPluginContract = buildCatalogLookup(catalogItems);
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  const headlessTags = pageHtml.match(HEADLESS_SCRIPT_RE) ?? [];
+  for (const tag of headlessTags) {
+    const pluginAttr = readScriptAttr(tag, "plugin");
+    const contract = readScriptAttr(tag, "contract");
+    const key = readScriptAttr(tag, "key");
+    if (!pluginAttr || !contract) continue;
+    const pluginName = pluginNameFromPackageAttr(pluginAttr);
+    const detectedKey = key ? `headless:${pluginName}:${contract}:${key}` : `headless:${pluginName}:${contract}`;
+    if (seen.has(detectedKey)) continue;
+    seen.add(detectedKey);
+    const catalogItem = catalogItemForDetection(
+      pluginName,
+      contract,
+      catalogByPluginContract
+    );
+    results.push({
+      detectedKey,
+      title: catalogItem?.title ?? humanizeContractName(contract),
+      prompt: catalogItem?.prompt ?? `Use headless component @jay-framework/${pluginName} / contract ${contract}.${key ? ` Script key: ${key}.` : ""}`,
+      pluginName,
+      contractName: contract,
+      componentKey: key
+    });
+  }
+  let jayMatch;
+  const jayRe = new RegExp(JAY_TAG_RE.source, "g");
+  while ((jayMatch = jayRe.exec(pageHtml)) !== null) {
+    const rawTag = jayMatch[1];
+    if (!rawTag) continue;
+    const tagName = rawTag.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+    const detectedKey = `jay:${tagName}`;
+    if (seen.has(detectedKey)) continue;
+    seen.add(detectedKey);
+    const contractGuess = tagName;
+    const catalogItem = [...catalogItems].find((item) => {
+      const idSuffix = item.id.split(":").slice(1).join(":");
+      return idSuffix === contractGuess || idSuffix === tagName;
+    });
+    results.push({
+      detectedKey,
+      title: catalogItem?.title ?? humanizeContractName(tagName),
+      prompt: catalogItem?.prompt ?? `Use <jay:${rawTag}> component on this page per agent-kit designer docs.`,
+      pluginName: catalogItem?.pluginName,
+      contractName: contractGuess
+    });
+  }
+  return results;
+}
+function detectedToPageAssetEntry(detected) {
+  return {
+    id: crypto.randomUUID(),
+    title: detected.title,
+    prompt: detected.prompt,
+    source: "detected",
+    itemId: detected.pluginName ? `${detected.pluginName}:${detected.contractName ?? ""}` : void 0,
+    persistOnPage: true,
+    addedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    detectedKey: detected.detectedKey,
+    detectedMeta: {
+      contractName: detected.contractName,
+      pluginName: detected.pluginName,
+      componentKey: detected.componentKey
+    }
+  };
+}
+function mergeDetectedPageAssets(existingAssets, detected, suppressedDetectedKeys = []) {
+  const suppressed = new Set(suppressedDetectedKeys);
+  const activeDetectedKeys = new Set(
+    existingAssets.filter((a) => a.source === "detected" && !a.userRemoved && a.detectedKey).map((a) => a.detectedKey)
+  );
+  const detectedKeySet = new Set(detected.map((d) => d.detectedKey));
+  const nextAssets = existingAssets.filter((asset) => {
+    if (asset.source !== "detected" || asset.userRemoved) return true;
+    if (!asset.detectedKey) return true;
+    return detectedKeySet.has(asset.detectedKey);
+  });
+  for (const component of detected) {
+    if (suppressed.has(component.detectedKey)) continue;
+    const tombstoned = nextAssets.some(
+      (a) => a.source === "detected" && a.detectedKey === component.detectedKey && a.userRemoved
+    );
+    if (tombstoned) continue;
+    if (activeDetectedKeys.has(component.detectedKey)) continue;
+    nextAssets.push(detectedToPageAssetEntry(component));
+    activeDetectedKeys.add(component.detectedKey);
+  }
+  return {
+    assets: nextAssets,
+    suppressedDetectedKeys: [...suppressed]
+  };
+}
+const getPageAssetsAction = makeJayQuery("aiditor.getPageAssets").withServices(DEV_SERVER_SERVICE).withHandler(
+  async (input) => {
+    const projectRoot = process.cwd();
+    const file = await getPageAssets(projectRoot, input);
+    return { file };
+  }
+);
+const savePageAssetsAction = makeJayQuery("aiditor.savePageAssets").withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  await savePageAssets(projectRoot, input.file);
+  return { ok: true };
+});
+const syncDetectedPageAssetsAction = makeJayQuery(
+  "aiditor.syncDetectedPageAssets"
+).withServices(DEV_SERVER_SERVICE).withHandler(
+  async (input) => {
+    const projectRoot = process.cwd();
+    const file = await getPageAssets(projectRoot, input);
+    let pageHtml = "";
+    const jayHtmlPath = input.jayHtmlPath ?? await resolveJayHtmlPathForPageRoute(projectRoot, input.pageRoute);
+    if (jayHtmlPath) {
+      try {
+        pageHtml = await fs.readFile(jayHtmlPath, "utf-8");
+      } catch {
+        pageHtml = "";
+      }
+    }
+    const catalog = await listAddMenuItems(projectRoot);
+    const detected = detectPageComponentsFromHtml(pageHtml, catalog.items);
+    const merged = mergeDetectedPageAssets(
+      file.assets,
+      detected,
+      file.suppressedDetectedKeys ?? []
+    );
+    const next = {
+      ...file,
+      contextKey: input.contextKey,
+      pageRoute: input.pageRoute,
+      renderedUrl: input.renderedUrl ?? file.renderedUrl,
+      assets: merged.assets,
+      suppressedDetectedKeys: merged.suppressedDetectedKeys
+    };
+    await savePageAssets(projectRoot, next);
+    return { file: next, detectedCount: detected.length };
+  }
+);
 const AIDITOR_PUBLISH_SCRIPT = "aiditor:publish";
 async function projectHasAiditorPublishScript(projectRoot) {
   try {
@@ -3956,6 +4620,9 @@ export {
   ensureProjectPluginAction,
   generateAddPageBriefFromImageAction,
   getAiditorBootstrap,
+  getContractInspectorTagsAction,
+  getPageAssetsAction,
+  getPageMetaAction,
   getPageParamsAction,
   getPluginSetupStatusAction,
   getProjectInfoAction,
@@ -3970,12 +4637,15 @@ export {
   resolveAddMenuContractParamsAction,
   runAiditorPublishAction,
   saveAddPageDraftAction,
+  savePageAssetsAction,
+  savePageMetaAction,
   setupAiditor,
   startAddPageRequestAction,
   submitAddPageAction,
   submitTaskAction,
   syncAddMenuAttachmentsAction,
   syncAddPagePluginManifestAction,
+  syncDetectedPageAssetsAction,
   uploadAddPageAssetAction,
   writePluginSourceAction
 };