@abuswami1996/agent-md 0.1.0

package/dist/index.js

@@ -0,0 +1,932 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+import http from "http";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import pc from "picocolors";
+import fg from "fast-glob";
+import chokidar from "chokidar";
+import { WebSocketServer } from "ws";
+
+// ../schema/src/index.ts
+import { z } from "zod";
+var defaultConfig = {
+  version: "0.1",
+  include: ["**/*.agent.md", "**/*.amd.md"],
+  exclude: ["node_modules/**", ".git/**", "dist/**", "build/**"],
+  server: { port: 3847, host: "localhost", open: true },
+  security: { allowRawHtml: false, allowRemoteData: false, allowHtmlEmbeds: false, allowCustomComponents: false, projectRootOnly: true, maxEmbedSizeMb: 25 },
+  components: { registry: ".agent-md/components.json" },
+  limits: { maxMarkdownSizeMb: 2, maxDataSizeMb: 10, maxEmbedSizeMb: 25, maxChartRows: 1e4 }
+};
+var positiveNumber = z.number().positive();
+var stringArray = z.array(z.string());
+var chartBase = z.object({ type: z.enum(["line", "bar", "area", "scatter", "pie"]), title: z.string().optional(), description: z.string().optional(), data: z.string(), x: z.string().optional(), y: z.union([z.string(), stringArray]).optional(), label: z.string().optional(), value: z.string().optional(), series: z.string().optional(), xLabel: z.string().optional(), yLabel: z.string().optional(), height: positiveNumber.optional(), width: positiveNumber.optional(), stacked: z.boolean().optional(), legend: z.boolean().optional(), tooltip: z.boolean().optional() }).strict();
+var metricSchema = z.object({ label: z.string(), value: z.union([z.string(), z.number()]).optional(), delta: z.union([z.string(), z.number()]).optional(), trend: z.enum(["up", "down", "neutral"]).optional(), description: z.string().optional(), data: z.string().optional(), field: z.string().optional(), format: z.string().optional(), aggregate: z.enum(["sum", "avg", "min", "max", "count"]).optional() }).strict();
+var tableSchema = z.object({ title: z.string().optional(), data: z.string(), columns: stringArray.optional(), sortable: z.boolean().optional(), filterable: z.boolean().optional(), pagination: z.boolean().optional(), pageSize: positiveNumber.optional(), search: z.boolean().optional() }).strict();
+var diagramSchema = z.object({ type: z.enum(["flowchart", "sequence", "tree"]), title: z.string().optional(), source: z.string().optional(), src: z.string().optional(), direction: z.enum(["TB", "LR", "BT", "RL"]).optional(), height: positiveNumber.optional() }).strict();
+var mapSchema = z.object({ title: z.string().optional(), data: z.string(), lat: z.string().optional(), lon: z.string().optional(), label: z.string().optional(), value: z.string().optional(), height: positiveNumber.optional(), zoom: z.number().optional(), center: z.tuple([z.number(), z.number()]).optional() }).strict();
+var timelineSchema = z.object({ data: z.string().optional(), date: z.string().optional(), title: z.string().optional(), description: z.string().optional(), group: z.string().optional(), sort: z.enum(["asc", "desc"]).optional(), layout: z.enum(["vertical", "horizontal"]).optional(), events: z.array(z.object({ date: z.string(), title: z.string(), description: z.string().optional(), group: z.string().optional() })).optional() }).strict();
+var tabsSchema = z.object({ default: z.string().optional(), variant: z.enum(["line", "pill", "card"]).optional() }).strict();
+var calloutSchema = z.object({ type: z.enum(["note", "info", "warning", "error", "success", "decision", "risk", "tip"]).optional(), title: z.string().optional(), body: z.string().optional() }).strict();
+var embedSchema = z.object({ src: z.string(), title: z.string().optional(), height: positiveNumber.optional(), width: positiveNumber.optional(), caption: z.string().optional(), mode: z.enum(["preview", "link", "inline"]).optional() }).strict();
+var formFieldSchema = z.object({ name: z.string(), label: z.string().optional(), type: z.enum(["text", "number", "select", "checkbox", "date"]), default: z.unknown().optional(), placeholder: z.string().optional(), required: z.boolean().optional(), options: stringArray.optional(), min: z.number().optional(), max: z.number().optional(), step: z.number().optional() }).strict();
+var formSchema = z.object({ title: z.string().optional(), description: z.string().optional(), submitLabel: z.string().optional(), fields: z.array(formFieldSchema) }).strict();
+var queryPredicateSchema = z.union([z.string(), z.number(), z.boolean(), z.object({ eq: z.unknown().optional(), neq: z.unknown().optional(), gt: z.number().optional(), gte: z.number().optional(), lt: z.number().optional(), lte: z.number().optional(), contains: z.string().optional(), in: z.array(z.unknown()).optional() }).strict()]);
+var querySchema = z.object({ data: z.string(), where: z.record(z.string(), queryPredicateSchema).optional(), select: stringArray.optional(), sort: z.object({ by: z.string(), direction: z.enum(["asc", "desc"]).optional() }).strict().optional(), limit: positiveNumber.optional(), view: z.enum(["table", "json", "cards"]).optional() }).strict();
+var componentSchema = z.object({ name: z.string(), props: z.record(z.string(), z.unknown()).optional() }).strict();
+var schemas = { chart: chartBase, metric: metricSchema, table: tableSchema, diagram: diagramSchema, map: mapSchema, timeline: timelineSchema, tabs: tabsSchema, callout: calloutSchema, embed: embedSchema, form: formSchema, query: querySchema, component: componentSchema };
+var primitiveNames = Object.keys(schemas);
+function issueToDiagnostic(issue, sourcePath, blockType, line) {
+  const unknown = issue.code === "unrecognized_keys";
+  const keys = unknown && "keys" in issue ? issue.keys.join(", ") : issue.path.join(".");
+  return { severity: unknown ? "warning" : "error", code: unknown ? "unknown_field" : "invalid_field", message: unknown ? `Unknown field "${keys}" on ::${blockType}.` : `${issue.path.join(".") || blockType}: ${issue.message}`, sourcePath, line, blockType };
+}
+function validatePrimitive(name, attrs, sourcePath, line) {
+  if (!primitiveNames.includes(name)) {
+    return { diagnostics: [{ severity: "error", code: "unknown_primitive", message: `Unknown directive ::${name}.`, sourcePath, line, blockType: name }] };
+  }
+  const result = schemas[name].safeParse(attrs);
+  if (result.success) return { attrs: result.data, diagnostics: [] };
+  return { attrs, diagnostics: result.error.issues.map((issue) => issueToDiagnostic(issue, sourcePath, name, line)) };
+}
+function normalizePrimitive(name, attrs, children, raw, sourcePath, line) {
+  const validation = validatePrimitive(name, attrs, sourcePath, line);
+  const hasError = validation.diagnostics.some((diagnostic) => diagnostic.severity === "error");
+  if (hasError || !validation.attrs) return { node: { type: "error", message: `Invalid ::${name} directive`, raw, line }, diagnostics: validation.diagnostics };
+  const data = validation.attrs;
+  switch (name) {
+    case "chart":
+      return { node: { ...data, type: "chart", chartType: data.type }, diagnostics: validation.diagnostics };
+    case "metric":
+      return { node: { ...data, type: "metric" }, diagnostics: validation.diagnostics };
+    case "table":
+      return { node: { ...data, type: "table" }, diagnostics: validation.diagnostics };
+    case "diagram":
+      return { node: { ...data, type: "diagram", diagramType: data.type }, diagnostics: validation.diagnostics };
+    case "map":
+      return { node: { ...data, type: "map" }, diagnostics: validation.diagnostics };
+    case "timeline":
+      return { node: { ...data, type: "timeline" }, diagnostics: validation.diagnostics };
+    case "tabs": {
+      const tabs = children.filter((child) => child.type === "component" && child.name === "__tab");
+      const tabNodes = tabs.map((tab) => ({ label: String(tab.props?.label ?? ""), value: tab.props?.value ? String(tab.props.value) : void 0, children: Array.isArray(tab.props?.children) ? tab.props.children : [] }));
+      const diagnostics = [...validation.diagnostics];
+      if (tabNodes.length === 0) diagnostics.push({ severity: "error", code: "tabs_empty", message: "::tabs requires at least one child ::tab.", sourcePath, line, blockType: "tabs" });
+      const labels = /* @__PURE__ */ new Set();
+      for (const tab of tabNodes) {
+        if (!tab.label) diagnostics.push({ severity: "error", code: "tab_label_required", message: "Each ::tab requires a label.", sourcePath, line, blockType: "tabs" });
+        if (labels.has(tab.label)) diagnostics.push({ severity: "error", code: "tab_label_duplicate", message: `Duplicate tab label "${tab.label}".`, sourcePath, line, blockType: "tabs" });
+        labels.add(tab.label);
+      }
+      if (typeof data.default === "string" && !labels.has(data.default)) diagnostics.push({ severity: "error", code: "tab_default_missing", message: `Default tab "${data.default}" does not exist.`, sourcePath, line, blockType: "tabs" });
+      return { node: { type: "tabs", default: data.default, variant: data.variant, tabs: tabNodes }, diagnostics };
+    }
+    case "callout":
+      return { node: { type: "callout", calloutType: data.type ?? "note", title: data.title, body: data.body, children }, diagnostics: validation.diagnostics };
+    case "embed":
+      return { node: { ...data, type: "embed" }, diagnostics: validation.diagnostics };
+    case "form":
+      return { node: { type: "form", title: data.title, description: data.description, submitLabel: data.submitLabel, fields: data.fields.map((field) => ({ ...field, fieldType: field.type })) }, diagnostics: validation.diagnostics };
+    case "query":
+      return { node: { ...data, type: "query" }, diagnostics: validation.diagnostics };
+    case "component":
+      return { node: { ...data, type: "component" }, diagnostics: validation.diagnostics };
+    default:
+      return { node: { type: "error", message: `Unsupported directive ::${name}`, raw, line }, diagnostics: validation.diagnostics };
+  }
+}
+function collectNodeDataRefs(node) {
+  switch (node.type) {
+    case "chart":
+      return [node.data];
+    case "metric":
+      return node.data ? [node.data] : [];
+    case "table":
+      return [node.data];
+    case "map":
+      return [node.data];
+    case "timeline":
+      return node.data ? [node.data] : [];
+    case "query":
+      return [node.data];
+    case "tabs":
+      return node.tabs.flatMap((tab) => tab.children.flatMap(collectNodeDataRefs));
+    case "callout":
+      return node.children?.flatMap(collectNodeDataRefs) ?? [];
+    default:
+      return [];
+  }
+}
+function getReferencedColumns(node) {
+  if (node.type === "chart") return { [node.data]: [node.x, ...Array.isArray(node.y) ? node.y : [node.y], node.label, node.value, node.series].filter(Boolean) };
+  if (node.type === "metric" && node.data) return { [node.data]: [node.field].filter(Boolean) };
+  if (node.type === "table") return { [node.data]: node.columns ?? [] };
+  if (node.type === "map") return { [node.data]: [node.lat, node.lon, node.label, node.value].filter(Boolean) };
+  if (node.type === "timeline" && node.data) return { [node.data]: [node.date, node.title, node.description, node.group].filter(Boolean) };
+  if (node.type === "query") return { [node.data]: [...node.select ?? [], ...Object.keys(node.where ?? {}), node.sort?.by].filter(Boolean) };
+  return {};
+}
+
+// ../parser/src/index.ts
+import YAML from "yaml";
+function parseAgentMarkdown({ source, sourcePath }) {
+  const diagnostics = [];
+  const { frontmatter, body } = extractFrontmatter(source, sourcePath, diagnostics);
+  if (/<script[\s>]/i.test(body)) diagnostics.push({ severity: "error", code: "script_blocked", message: "Scripts must never execute from Markdown content.", sourcePath });
+  const { body: withoutData, dataSources } = extractDataBlocks(body, sourcePath, diagnostics);
+  const nodes = parseDocumentBlocks(withoutData.split(/\r?\n/), sourcePath, diagnostics, 0, 1);
+  return { format: "agent-md", version: String(frontmatter?.version ?? "0.1"), sourcePath, frontmatter, nodes, dataSources, diagnostics };
+}
+function extractFrontmatter(source, sourcePath, diagnostics) {
+  if (!source.startsWith("---\n")) return { frontmatter: void 0, body: source };
+  const end = source.indexOf("\n---", 4);
+  if (end === -1) return { frontmatter: void 0, body: source };
+  const raw = source.slice(4, end);
+  try {
+    const parsed = YAML.parse(raw) ?? {};
+    return { frontmatter: typeof parsed === "object" ? parsed : {}, body: source.slice(end + 5).replace(/^\r?\n/, "") };
+  } catch (error) {
+    diagnostics.push({ severity: "error", code: "frontmatter_parse_error", message: error instanceof Error ? error.message : "Invalid frontmatter", sourcePath, line: 1 });
+    return { frontmatter: void 0, body: source.slice(end + 5).replace(/^\r?\n/, "") };
+  }
+}
+function extractDataBlocks(source, sourcePath, diagnostics) {
+  const dataSources = {};
+  const lines = source.split(/\r?\n/);
+  const kept = [];
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const match = line.match(/^```(?:(data)\s+([A-Za-z0-9_-]+)|(?:(json|yaml|yml|csv|tsv)\s+data=([A-Za-z0-9_-]+)))\s*$/);
+    if (!match) {
+      kept.push(line);
+      continue;
+    }
+    const format = match[3] === "yml" ? "yaml" : match[3] || "csv";
+    const id = match[2] || match[4];
+    const startLine = index + 1;
+    const content = [];
+    index++;
+    while (index < lines.length && !lines[index].startsWith("```")) content.push(lines[index++]);
+    try {
+      dataSources[id] = parseInlineData(id, format, content.join("\n"));
+    } catch (error) {
+      diagnostics.push({ severity: "error", code: "data_parse_error", message: error instanceof Error ? error.message : `Unable to parse data source ${id}`, sourcePath, line: startLine, blockType: "data" });
+    }
+  }
+  return { body: kept.join("\n"), dataSources };
+}
+function parseInlineData(id, format, raw) {
+  if (format === "json") {
+    const object = JSON.parse(raw);
+    return { id, origin: "inline", format, rows: Array.isArray(object) && object.every((row) => row && typeof row === "object" && !Array.isArray(row)) ? object : void 0, object, diagnostics: [] };
+  }
+  if (format === "yaml") {
+    const object = YAML.parse(raw);
+    return { id, origin: "inline", format, rows: Array.isArray(object) && object.every((row) => row && typeof row === "object" && !Array.isArray(row)) ? object : void 0, object, diagnostics: [] };
+  }
+  const delimiter = format === "tsv" ? "	" : ",";
+  const [headerLine, ...rowLines] = raw.trim().split(/\r?\n/).filter(Boolean);
+  const headers = headerLine.split(delimiter).map((value) => value.trim());
+  const rows = rowLines.map((row) => Object.fromEntries(row.split(delimiter).map((value, index) => [headers[index], coerceScalar(value.trim())])));
+  return { id, origin: "inline", format, rows, columns: inferInlineColumns(rows), diagnostics: [] };
+}
+function inferInlineColumns(rows) {
+  const names = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  return names.map((name) => {
+    const values = rows.map((row) => row[name]);
+    const nonNull = values.filter((value) => value !== null && value !== void 0 && value !== "");
+    return { name, type: inferInlineType(nonNull), nullable: nonNull.length !== values.length, sampleValues: nonNull.slice(0, 5) };
+  });
+}
+function inferInlineType(values) {
+  if (values.length === 0) return "unknown";
+  if (values.every((value) => typeof value === "number")) return "number";
+  if (values.every((value) => typeof value === "boolean")) return "boolean";
+  if (values.every((value) => typeof value === "string" && !Number.isNaN(Date.parse(value)))) return "date";
+  if (values.every((value) => typeof value === "string")) return "string";
+  return "unknown";
+}
+function coerceScalar(value) {
+  if (value === "") return null;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && value.trim() !== "" ? numeric : value;
+}
+function parseDocumentBlocks(lines, sourcePath, diagnostics, depth, baseLine) {
+  const nodes = [];
+  let markdown = [];
+  let markdownStart = baseLine;
+  const flushMarkdown = (nextLine) => {
+    const value = markdown.join("\n").trim();
+    if (value) nodes.push({ type: "markdown", value, line: markdownStart });
+    markdown = [];
+    markdownStart = nextLine;
+  };
+  for (let index = 0; index < lines.length; index++) {
+    const start = lines[index].match(/^(::{1,})([A-Za-z][A-Za-z0-9_-]*)\s*$/);
+    if (!start) {
+      if (markdown.length === 0) markdownStart = baseLine + index;
+      markdown.push(lines[index]);
+      continue;
+    }
+    flushMarkdown(baseLine + index);
+    const marker = start[1];
+    const name = start[2];
+    const block = { name, marker, startLine: baseLine + index, raw: [lines[index]], content: [] };
+    index++;
+    let nested = 0;
+    for (; index < lines.length; index++) {
+      const current = lines[index];
+      if (current.match(/^(::{1,})[A-Za-z][A-Za-z0-9_-]*\s*$/)) nested++;
+      if (isClosingFence(current, marker) && nested === 0) {
+        block.raw.push(current);
+        break;
+      }
+      if (current.trim().match(/^::{1,}$/) && nested > 0) nested--;
+      block.raw.push(current);
+      block.content.push(current);
+    }
+    if (depth >= 5) {
+      diagnostics.push({ severity: "error", code: "max_nesting_depth", message: "Directive nesting depth exceeds 5.", sourcePath, line: block.startLine, blockType: name });
+      nodes.push({ type: "error", message: "Directive nesting depth exceeds 5.", raw: block.raw.join("\n"), line: block.startLine });
+      continue;
+    }
+    nodes.push(parseDirective(block, sourcePath, diagnostics, depth));
+  }
+  flushMarkdown(baseLine + lines.length);
+  return nodes;
+}
+function isClosingFence(line, marker) {
+  const trimmed = line.trim();
+  return /^::{1,}$/.test(trimmed) && trimmed.length >= marker.length;
+}
+function parseDirective(block, sourcePath, diagnostics, depth) {
+  if (block.name === "tab") {
+    const parsed2 = splitPropsAndBody(block.content, sourcePath, block.startLine, diagnostics);
+    const children2 = parseDocumentBlocks(parsed2.body.split(/\r?\n/), sourcePath, diagnostics, depth + 1, block.startLine + parsed2.bodyOffset);
+    return { type: "component", name: "__tab", props: { ...parsed2.attrs, children: children2 } };
+  }
+  const parsed = splitPropsAndBody(block.content, sourcePath, block.startLine, diagnostics);
+  const childLines = parsed.body.trim() ? parsed.body.split(/\r?\n/) : [];
+  const children = childLines.length ? parseDocumentBlocks(childLines, sourcePath, diagnostics, depth + 1, block.startLine + parsed.bodyOffset) : [];
+  if (block.name === "callout" && parsed.body.trim() && parsed.attrs.body == null && children.every((node) => node.type === "markdown")) parsed.attrs.body = parsed.body.trim();
+  const normalized = normalizePrimitive(block.name, parsed.attrs, children, block.raw.join("\n"), sourcePath, block.startLine);
+  diagnostics.push(...normalized.diagnostics);
+  return normalized.node;
+}
+function splitPropsAndBody(lines, sourcePath, startLine, diagnostics) {
+  let splitAt = 0;
+  const propLines = [];
+  for (; splitAt < lines.length; splitAt++) {
+    const line = lines[splitAt];
+    if (line.trim() === "") {
+      propLines.push(line);
+      continue;
+    }
+    if (/^\s+[\w-]+:/.test(line) || /^\s*-\s+/.test(line) || /^[A-Za-z_][\w-]*\s*:/.test(line) || /^\s+/.test(line)) {
+      propLines.push(line);
+      continue;
+    }
+    break;
+  }
+  let attrs = {};
+  const yamlText = propLines.join("\n").trim();
+  if (yamlText) {
+    try {
+      const parsed = YAML.parse(yamlText);
+      attrs = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch (error) {
+      diagnostics.push({ severity: "error", code: "directive_yaml_error", message: error instanceof Error ? error.message : "Invalid directive YAML", sourcePath, line: startLine });
+    }
+  }
+  return { attrs, body: lines.slice(splitAt).join("\n"), bodyOffset: splitAt + 1 };
+}
+
+// ../skill/src/index.ts
+var skillMarkdown = `# Agent Markdown Skill
+
+Use Agent Markdown when the user asks for interactive reports, dashboards, visual analysis, charts or tables in Markdown, or local visualization documents.
+
+Do not use Agent Markdown for ordinary README files, simple notes, documents that must render on GitHub without a viewer, or cases where the user asks for plain Markdown.
+
+Rules:
+- Use normal Markdown for prose.
+- Use directives for interactive primitives.
+- Do not emit raw HTML.
+- Do not emit JavaScript.
+- Prefer named data blocks or local files.
+- Add frontmatter with format: agent-md and version: 0.1.
+- Run agent-md validate before considering a document complete.
+
+Supported MVP primitives:
+- ::metric for KPI cards.
+- ::chart for line, bar, area, scatter, and pie charts.
+- ::table for sortable/filterable local data tables.
+- ::callout for notes, warnings, decisions, risks, and tips.
+- ::tabs for grouped alternative views.
+- ::diagram, ::timeline, ::query, ::embed, ::form, ::map, and ::component are supported with conservative validation and graceful fallbacks.
+`;
+var exampleAgentMarkdown = `---
+format: agent-md
+version: 0.1
+---
+# Q4 Revenue Dashboard
+
+::callout
+type: decision
+title: Local-only MVP
+This dashboard uses only local inline data and local files.
+:::
+
+::metric
+label: Total revenue
+data: revenue
+field: amount
+aggregate: sum
+format: currency
+:::
+
+::chart
+type: line
+title: Revenue by month
+data: revenue
+x: month
+y: amount
+:::
+
+::tabs
+::::tab
+label: Table
+::table
+data: revenue
+columns: [month, segment, amount]
+sortable: true
+filterable: true
+:::
+::::
+::::tab
+label: Enterprise only
+::query
+data: revenue
+where:
+  segment: Enterprise
+select: [month, amount]
+sort:
+  by: amount
+  direction: desc
+view: table
+:::
+::::
+:::
+
+\`\`\`data revenue
+month,segment,amount
+Oct,SMB,100000
+Oct,Enterprise,400000
+Nov,SMB,120000
+Nov,Enterprise,450000
+Dec,SMB,140000
+Dec,Enterprise,550000
+\`\`\`
+`;
+function configJson() {
+  return JSON.stringify(defaultConfig, null, 2) + "\n";
+}
+function componentsJson() {
+  return JSON.stringify({ components: { Funnel: { module: "./components/Funnel.js", schema: "./components/Funnel.schema.json", description: "Renders a funnel conversion chart" } } }, null, 2) + "\n";
+}
+function schemaJson() {
+  return JSON.stringify({ $schema: "https://json-schema.org/draft/2020-12/schema", title: "Agent Markdown", version: "0.1", primitives: ["chart", "metric", "table", "diagram", "map", "timeline", "tabs", "callout", "embed", "form", "query", "component"] }, null, 2) + "\n";
+}
+
+// ../resolver/src/index.ts
+import fs from "fs/promises";
+import path from "path";
+import YAML2 from "yaml";
+import Papa from "papaparse";
+var dataExtensions = /* @__PURE__ */ new Set([".csv", ".tsv", ".json", ".yaml", ".yml", ".geojson"]);
+var artifactExtensions = /* @__PURE__ */ new Set([".pdf", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webm", ".mp4", ".html", ".txt", ".md", ".mmd", ".mermaid", ".csv", ".json"]);
+function isRemoteRef(ref) {
+  return /^https?:\/\//i.test(ref);
+}
+function resolveSafePath(projectRoot, sourcePath, ref) {
+  if (isRemoteRef(ref)) throw new Error("Remote references are disabled in the MVP");
+  if (ref.startsWith("~")) throw new Error("Home-directory references are not allowed");
+  const root = path.resolve(projectRoot);
+  const absolute = path.resolve(path.dirname(sourcePath), ref);
+  const relative = path.relative(root, absolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Path escapes project root");
+  return absolute;
+}
+async function resolveSafeRealPath(projectRoot, sourcePath, ref) {
+  const absolute = resolveSafePath(projectRoot, sourcePath, ref);
+  const [realRoot, realAbsolute] = await Promise.all([fs.realpath(projectRoot), fs.realpath(absolute)]);
+  const relative = path.relative(realRoot, realAbsolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Path escapes project root");
+  return realAbsolute;
+}
+async function loadConfig(projectRoot, configPath = "agent-md.config.json") {
+  const absolute = path.resolve(projectRoot, configPath);
+  try {
+    const raw = await fs.readFile(absolute, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      ...defaultConfig,
+      ...parsed,
+      server: { ...defaultConfig.server, ...parsed.server },
+      security: { ...defaultConfig.security, ...parsed.security },
+      components: { ...defaultConfig.components, ...parsed.components },
+      limits: { ...defaultConfig.limits, ...parsed.limits }
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return defaultConfig;
+    throw error;
+  }
+}
+async function loadDataFile(projectRoot, sourcePath, ref, limits = defaultConfig.limits) {
+  const absolute = await resolveSafeRealPath(projectRoot, sourcePath, ref);
+  const ext = path.extname(absolute).toLowerCase();
+  if (!dataExtensions.has(ext)) throw new Error(`Unsupported data file extension: ${ext}`);
+  const stat = await fs.stat(absolute);
+  if (stat.size > limits.maxDataSizeMb * 1024 * 1024) throw new Error(`Data file exceeds ${limits.maxDataSizeMb} MB limit`);
+  const raw = await fs.readFile(absolute, "utf8");
+  const format = ext === ".yml" ? "yaml" : ext.slice(1);
+  let rows;
+  let object;
+  if (format === "csv" || format === "tsv") {
+    const parsed = Papa.parse(raw, { header: true, dynamicTyping: true, skipEmptyLines: true, delimiter: format === "tsv" ? "	" : void 0 });
+    rows = parsed.data;
+    object = parsed.data;
+  } else if (format === "json" || format === "geojson") {
+    object = JSON.parse(raw);
+    rows = Array.isArray(object) && object.every(isRecord) ? object : void 0;
+  } else {
+    object = YAML2.parse(raw);
+    rows = Array.isArray(object) && object.every(isRecord) ? object : void 0;
+  }
+  return { id: ref, origin: "file", source: absolute, format, rows, object, columns: rows ? inferColumns(rows) : void 0, diagnostics: [] };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function inferColumns(rows) {
+  const names = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  return names.map((name) => {
+    const values = rows.map((row) => row[name]);
+    const nonNull = values.filter((value) => value !== null && value !== void 0 && value !== "");
+    return { name, type: inferType(nonNull), nullable: nonNull.length !== values.length, sampleValues: nonNull.slice(0, 5) };
+  });
+}
+function inferType(values) {
+  if (values.length === 0) return "unknown";
+  if (values.every((value) => typeof value === "number")) return "number";
+  if (values.every((value) => typeof value === "boolean")) return "boolean";
+  if (values.every((value) => typeof value === "string" && !Number.isNaN(Date.parse(value)))) return "date";
+  if (values.every((value) => typeof value === "string")) return "string";
+  return "unknown";
+}
+async function resolveDocumentData(document, projectRoot, config = defaultConfig) {
+  const diagnostics = [...document.diagnostics];
+  const dataSources = { ...document.dataSources };
+  for (const source of Object.values(dataSources)) if (source.rows && !source.columns) source.columns = inferColumns(source.rows);
+  const refs = [...new Set(document.nodes.flatMap(collectNodeDataRefs))];
+  for (const ref of refs) {
+    if (dataSources[ref]) continue;
+    if (isRemoteRef(ref)) {
+      diagnostics.push({ severity: "error", code: "remote_data_blocked", message: `Remote data reference is blocked: ${ref}`, sourcePath: document.sourcePath });
+      continue;
+    }
+    if (dataExtensions.has(path.extname(ref).toLowerCase())) {
+      try {
+        const loaded = await loadDataFile(projectRoot, document.sourcePath, ref, config.limits);
+        dataSources[ref] = loaded;
+      } catch (error) {
+        diagnostics.push({ severity: "error", code: "data_file_error", message: error instanceof Error ? error.message : `Unable to load data source ${ref}`, sourcePath: document.sourcePath });
+      }
+    }
+  }
+  diagnostics.push(...validateReferences(document.nodes, dataSources, document.sourcePath, config));
+  diagnostics.push(...await validateLocalArtifacts(document.nodes, projectRoot, document.sourcePath, config));
+  return { ...document, dataSources, diagnostics };
+}
+function validateReferences(nodes, dataSources, sourcePath, config = defaultConfig) {
+  const diagnostics = [];
+  const visit = (node) => {
+    const refs = collectNodeDataRefs(node);
+    for (const ref of refs) if (!dataSources[ref] && !dataExtensions.has(path.extname(ref).toLowerCase())) diagnostics.push({ severity: "error", code: "data_not_found", message: `Data source "${ref}" was not found.`, sourcePath, blockType: node.type });
+    const columnsByData = getReferencedColumns(node);
+    for (const [data, columns] of Object.entries(columnsByData)) {
+      const source = dataSources[data];
+      if (!source?.columns || columns.length === 0) continue;
+      const known = new Set(source.columns.map((column) => column.name));
+      for (const column of columns) if (!known.has(column)) diagnostics.push({ severity: "error", code: "column_not_found", message: `Column "${column}" was not found in data source "${data}".`, sourcePath, blockType: node.type });
+    }
+    if (node.type === "chart") {
+      const rows = dataSources[node.data]?.rows?.length ?? 0;
+      if (rows > config.limits.maxChartRows) diagnostics.push({ severity: "warning", code: "chart_row_limit", message: `Chart uses ${rows} rows, above the ${config.limits.maxChartRows} row target.`, sourcePath, blockType: "chart" });
+    }
+    if (node.type === "table") {
+      const rows = dataSources[node.data]?.rows?.length ?? 0;
+      if (rows > 500 && node.pagination !== false) diagnostics.push({ severity: "info", code: "table_paginated", message: "Tables over 500 rows are paginated by default.", sourcePath, blockType: "table" });
+    }
+    if (node.type === "component" && !config.security.allowCustomComponents) diagnostics.push({ severity: "warning", code: "custom_component_disabled", message: `Registered component "${node.name}" will render as a placeholder because custom components are disabled.`, sourcePath, blockType: "component" });
+    diagnostics.push(...validatePrimitiveSemantics(node, dataSources, sourcePath));
+    if (node.type === "tabs") node.tabs.forEach((tab) => tab.children.forEach(visit));
+    if (node.type === "callout") node.children?.forEach(visit);
+  };
+  nodes.forEach(visit);
+  return diagnostics;
+}
+async function validateLocalArtifacts(nodes, projectRoot, sourcePath, config) {
+  const diagnostics = [];
+  const visit = async (node) => {
+    if (node.type === "embed") await validateArtifactRef(node.src, "embed", projectRoot, sourcePath, config, diagnostics);
+    if (node.type === "diagram" && node.src) await validateArtifactRef(node.src, "diagram", projectRoot, sourcePath, config, diagnostics);
+    if (node.type === "tabs") for (const tab of node.tabs) for (const child of tab.children) await visit(child);
+    if (node.type === "callout") for (const child of node.children ?? []) await visit(child);
+  };
+  for (const node of nodes) await visit(node);
+  return diagnostics;
+}
+async function validateArtifactRef(ref, blockType, projectRoot, sourcePath, config, diagnostics) {
+  if (isRemoteRef(ref)) {
+    diagnostics.push({ severity: "error", code: "remote_artifact_blocked", message: `Remote artifact reference is blocked: ${ref}`, sourcePath, blockType });
+    return;
+  }
+  try {
+    const absolute = await resolveSafeRealPath(projectRoot, sourcePath, ref);
+    const ext = path.extname(absolute).toLowerCase();
+    if (!artifactExtensions.has(ext) && blockType === "embed") diagnostics.push({ severity: "error", code: "unsupported_artifact", message: `Unsupported artifact extension: ${ext}`, sourcePath, blockType });
+    if (ext === ".html" && !config.security.allowHtmlEmbeds) diagnostics.push({ severity: "error", code: "html_embed_blocked", message: "HTML embeds are blocked by default.", sourcePath, blockType });
+    const stat = await fs.stat(absolute);
+    if (stat.size > config.limits.maxEmbedSizeMb * 1024 * 1024) diagnostics.push({ severity: "error", code: "embed_size_limit", message: `Artifact exceeds ${config.limits.maxEmbedSizeMb} MB limit.`, sourcePath, blockType });
+  } catch (error) {
+    diagnostics.push({ severity: "error", code: "artifact_file_error", message: error instanceof Error ? error.message : `Unable to access artifact ${ref}`, sourcePath, blockType });
+  }
+}
+function validatePrimitiveSemantics(node, dataSources, sourcePath) {
+  const diagnostics = [];
+  if (node.type === "chart") {
+    const source = dataSources[node.data];
+    const numericColumns = Array.isArray(node.y) ? node.y : node.y ? [node.y] : [];
+    if (node.chartType === "pie" && node.value) numericColumns.push(node.value);
+    for (const column of numericColumns) {
+      if (columnType(source, column) && columnType(source, column) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${column}" must be numeric for ::chart.`, sourcePath, blockType: "chart" });
+    }
+  }
+  if (node.type === "metric" && node.data && node.field && node.aggregate && node.aggregate !== "count") {
+    if (columnType(dataSources[node.data], node.field) && columnType(dataSources[node.data], node.field) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${node.field}" must be numeric for metric aggregation.`, sourcePath, blockType: "metric" });
+  }
+  if (node.type === "map") {
+    const rows = dataSources[node.data]?.rows ?? [];
+    if (node.lat && columnType(dataSources[node.data], node.lat) !== "number") diagnostics.push({ severity: "error", code: "lat_not_numeric", message: `Latitude column "${node.lat}" must be numeric.`, sourcePath, blockType: "map" });
+    if (node.lon && columnType(dataSources[node.data], node.lon) !== "number") diagnostics.push({ severity: "error", code: "lon_not_numeric", message: `Longitude column "${node.lon}" must be numeric.`, sourcePath, blockType: "map" });
+    for (const row of rows) {
+      const lat = node.lat ? Number(row[node.lat]) : void 0;
+      const lon = node.lon ? Number(row[node.lon]) : void 0;
+      if (lat != null && Number.isFinite(lat) && (lat < -90 || lat > 90)) diagnostics.push({ severity: "error", code: "lat_out_of_range", message: "Latitude values must be between -90 and 90.", sourcePath, blockType: "map" });
+      if (lon != null && Number.isFinite(lon) && (lon < -180 || lon > 180)) diagnostics.push({ severity: "error", code: "lon_out_of_range", message: "Longitude values must be between -180 and 180.", sourcePath, blockType: "map" });
+    }
+  }
+  if (node.type === "timeline") {
+    for (const event of node.events ?? []) if (Number.isNaN(Date.parse(event.date))) diagnostics.push({ severity: "error", code: "invalid_date", message: `Timeline event date "${event.date}" is invalid.`, sourcePath, blockType: "timeline" });
+  }
+  if (node.type === "form") {
+    const names = /* @__PURE__ */ new Set();
+    for (const field of node.fields) {
+      if (names.has(field.name)) diagnostics.push({ severity: "error", code: "duplicate_field", message: `Duplicate form field "${field.name}".`, sourcePath, blockType: "form" });
+      names.add(field.name);
+      if (field.fieldType === "select" && (!field.options || field.options.length === 0)) diagnostics.push({ severity: "error", code: "select_options_required", message: `Select field "${field.name}" requires options.`, sourcePath, blockType: "form" });
+      if (field.fieldType === "number" && field.default != null && typeof field.default !== "number") diagnostics.push({ severity: "error", code: "default_type_mismatch", message: `Default for "${field.name}" must be a number.`, sourcePath, blockType: "form" });
+    }
+  }
+  return diagnostics;
+}
+function columnType(source, column) {
+  return source?.columns?.find((item) => item.name === column)?.type;
+}
+
+// src/index.ts
+var program = new Command();
+var cliDir = path2.dirname(fileURLToPath(import.meta.url));
+var extensionId = "AbhinavSwaminathan.agent-md-preview";
+var viewerDistCandidates = [
+  path2.resolve(cliDir, "../viewer-dist"),
+  path2.resolve(cliDir, "../../viewer/dist")
+];
+var vsixCandidates = [
+  path2.resolve(cliDir, "../agent-md-preview.vsix"),
+  path2.resolve(cliDir, "../../vscode-extension/dist/agent-md-preview.vsix")
+];
+program.name("agent-md").description("Local-first Agent Markdown runtime").version("0.1.0");
+program.command("init").option("--agent <agent>", "agent skill flavor", "generic").action(async (options) => {
+  const root = process.cwd();
+  await writeIfMissing(path2.join(root, "agent-md.config.json"), configJson());
+  await fs2.mkdir(path2.join(root, ".agent-md"), { recursive: true });
+  await fs2.mkdir(path2.join(root, "examples"), { recursive: true });
+  await writeIfMissing(path2.join(root, ".agent-md", "skill.md"), skillMarkdown);
+  await writeIfMissing(path2.join(root, ".agent-md", "schema.json"), schemaJson());
+  await writeIfMissing(path2.join(root, ".agent-md", "components.json"), componentsJson());
+  await writeIfMissing(path2.join(root, "examples", "example.agent.md"), exampleAgentMarkdown);
+  if (["cursor", "vscode"].includes(String(options.agent).toLowerCase())) await mergeVsCodeRecommendation(root);
+  console.log(pc.green("Agent Markdown project initialized."));
+  if (["cursor", "vscode"].includes(String(options.agent).toLowerCase())) {
+    console.log(pc.gray(`Recommended extension added: ${extensionId}`));
+    console.log(pc.gray("Open an .agent.md file and run: Agent Markdown: Open Preview"));
+    console.log(pc.gray("Browser fallback: npx agent-md serve"));
+  }
+});
+program.command("validate").option("--file <file>", "validate a single file").option("--json", "print JSON diagnostics").option("--strict", "treat warnings as failures").option("--root <root>", "project root", ".").option("--config <config>", "config path", "agent-md.config.json").action(async (options) => {
+  const root = path2.resolve(options.root);
+  const config = await loadConfig(root, options.config);
+  const files = options.file ? [path2.resolve(root, options.file)] : await scanMarkdownFiles(root, config, false);
+  const results = await Promise.all(files.map((file) => parseAndResolve(file, root, config)));
+  const diagnostics = results.flatMap((result) => result.diagnostics);
+  if (options.json) {
+    console.log(JSON.stringify({ files: results, diagnostics }, null, 2));
+  } else {
+    printDiagnostics(results);
+  }
+  const hasFailure = diagnostics.some((diagnostic) => diagnostic.severity === "error" || options.strict && diagnostic.severity === "warning");
+  process.exitCode = hasFailure ? 1 : 0;
+});
+program.command("serve").option("--port <port>", "port", String(defaultConfig.server.port)).option("--host <host>", "host", defaultConfig.server.host).option("--root <root>", "project root", ".").option("--open", "open browser").option("--no-open", "do not open browser").option("--all-md", "include all Markdown files").option("--config <config>", "config path", "agent-md.config.json").action(async (options) => {
+  const root = path2.resolve(options.root);
+  const config = await loadConfig(root, options.config);
+  const port = Number(options.port ?? config.server.port);
+  const host = String(options.host ?? config.server.host);
+  const server = http.createServer(async (req, res) => {
+    try {
+      await handleRequest(req, res, root, config, Boolean(options.allMd));
+    } catch (error) {
+      sendJson(res, 500, { error: error instanceof Error ? error.message : "Unknown error" });
+    }
+  });
+  const wss = new WebSocketServer({ server, path: "/ws" });
+  const watcher = chokidar.watch([...config.include ?? [], "agent-md.config.json", ".agent-md/components.json"], { cwd: root, ignored: config.exclude, ignoreInitial: true });
+  watcher.on("all", () => {
+    for (const client of wss.clients) client.send(JSON.stringify({ type: "reload" }));
+  });
+  server.listen(port, host, () => {
+    const url = `http://${host}:${port}`;
+    console.log(pc.green(`Agent Markdown running at ${url}`));
+    const shouldOpen = options.open === true || options.open !== false && config.server.open;
+    if (shouldOpen) openBrowser(url).catch(() => void 0);
+  });
+});
+program.command("export").argument("file").option("--format <format>", "html | json | markdown-fallback", "json").option("--root <root>", "project root", ".").action(async (file, options) => {
+  const root = path2.resolve(options.root);
+  const config = await loadConfig(root);
+  const document = await parseAndResolve(path2.resolve(root, file), root, config);
+  if (options.format === "json") console.log(JSON.stringify(document, null, 2));
+  else if (options.format === "markdown-fallback") console.log(renderFallback(document));
+  else console.log(renderStaticHtml(document));
+});
+program.command("vscode-extension").description("Print or run local VSCode/Cursor extension install instructions").option("--editor <editor>", "editor CLI to use: cursor or code", "cursor").option("--install", "install the bundled VSIX with the editor CLI").option("--force", "force reinstall when using --install", true).action(async (options) => {
+  const vsix = await findVsix();
+  if (!vsix) {
+    console.log(pc.yellow("No bundled Agent Markdown VSIX was found."));
+    console.log("Build it with: npm run package -w agent-md-preview");
+    console.log(`Then install it with: ${options.editor} --install-extension packages/vscode-extension/dist/agent-md-preview.vsix --force`);
+    return;
+  }
+  if (options.install) {
+    await installVsix(String(options.editor), vsix, Boolean(options.force));
+    return;
+  }
+  console.log(`Agent Markdown VSIX: ${vsix}`);
+  console.log(`Install with: ${options.editor} --install-extension "${vsix}" --force`);
+});
+program.parseAsync(process.argv);
+async function writeIfMissing(file, content) {
+  try {
+    await fs2.writeFile(file, content, { flag: "wx" });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+}
+async function mergeVsCodeRecommendation(root) {
+  const vscodeDir = path2.join(root, ".vscode");
+  const extensionsPath = path2.join(vscodeDir, "extensions.json");
+  await fs2.mkdir(vscodeDir, { recursive: true });
+  let data = {};
+  try {
+    data = JSON.parse(await fs2.readFile(extensionsPath, "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const recommendations = new Set(data.recommendations ?? []);
+  recommendations.add(extensionId);
+  await fs2.writeFile(extensionsPath, JSON.stringify({ ...data, recommendations: [...recommendations].sort() }, null, 2) + "\n");
+}
+async function findVsix() {
+  for (const candidate of vsixCandidates) {
+    try {
+      await fs2.access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function installVsix(editor, vsix, force) {
+  const { execFile } = await import("child_process");
+  const args = ["--install-extension", vsix, ...force ? ["--force"] : []];
+  await new Promise((resolve, reject) => {
+    execFile(editor, args, (error, stdout, stderr) => {
+      if (stdout) process.stdout.write(stdout);
+      if (stderr) process.stderr.write(stderr);
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+  console.log(pc.green(`Installed Agent Markdown extension with ${editor}.`));
+}
+async function scanMarkdownFiles(root, config, allMd) {
+  const include = allMd ? ["**/*.md"] : config.include;
+  const files = await fg(include, { cwd: root, ignore: config.exclude, absolute: true, onlyFiles: true });
+  const safeFiles = [];
+  for (const file of files) {
+    try {
+      safeFiles.push(await resolveSafeRealPath(root, path2.join(root, "agent-md.config.json"), file));
+    } catch {
+    }
+  }
+  if (!allMd) return safeFiles;
+  const matching = [];
+  for (const file of safeFiles) if ((await fs2.readFile(file, "utf8")).includes("format: agent-md")) matching.push(file);
+  return matching;
+}
+async function parseAndResolve(file, root, config) {
+  const safeFile = await resolveSafeRealPath(root, path2.join(root, "agent-md.config.json"), file);
+  const stat = await fs2.stat(safeFile);
+  const diagnostics = [];
+  if (stat.size > config.limits.maxMarkdownSizeMb * 1024 * 1024) diagnostics.push({ severity: "warning", code: "markdown_size", message: `Markdown file exceeds ${config.limits.maxMarkdownSizeMb} MB target.`, sourcePath: safeFile });
+  const source = await fs2.readFile(safeFile, "utf8");
+  const parsed = parseAgentMarkdown({ source, sourcePath: safeFile });
+  const resolved = await resolveDocumentData(parsed, root, config);
+  return { ...resolved, diagnostics: [...diagnostics, ...resolved.diagnostics] };
+}
+function printDiagnostics(results) {
+  for (const result of results) {
+    console.log(pc.bold(path2.relative(process.cwd(), result.sourcePath)));
+    if (result.diagnostics.length === 0) {
+      console.log(pc.green("  OK"));
+      continue;
+    }
+    for (const diagnostic of result.diagnostics) {
+      const color = diagnostic.severity === "error" ? pc.red : diagnostic.severity === "warning" ? pc.yellow : pc.blue;
+      console.log(color(`  ${diagnostic.severity.toUpperCase()}: ${diagnostic.message}`));
+      if (diagnostic.line) console.log(`    Line: ${diagnostic.line}`);
+      if (diagnostic.blockType) console.log(`    Block: ::${diagnostic.blockType}`);
+      if (diagnostic.suggestion) console.log(`    Suggestion: ${diagnostic.suggestion}`);
+    }
+  }
+}
+async function resolveRequestedDocument(root, config, allMd, file) {
+  const requested = await resolveSafeRealPath(root, path2.join(root, "agent-md.config.json"), file);
+  const allowed = await scanMarkdownFiles(root, config, allMd);
+  const allowedRealPaths = new Set(await Promise.all(allowed.map((item) => fs2.realpath(item))));
+  if (!allowedRealPaths.has(requested)) throw new Error("Requested file is not an Agent Markdown document");
+  return requested;
+}
+function collectArtifactRefs(nodes) {
+  const refs = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if ((node.type === "embed" || node.type === "diagram") && node.src) refs.add(node.src);
+    if (node.type === "tabs") node.tabs.forEach((tab) => tab.children.forEach(visit));
+    if (node.type === "callout") node.children?.forEach(visit);
+  };
+  nodes.forEach(visit);
+  return refs;
+}
+async function handleRequest(req, res, root, config, allMd) {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+  if (url.pathname === "/api/files") {
+    const files = await scanMarkdownFiles(root, config, allMd);
+    const items = await Promise.all(files.map(async (file) => {
+      const document = await parseAndResolve(file, root, config).catch((error) => ({ diagnostics: [{ severity: "error", code: "parse_error", message: error instanceof Error ? error.message : "Unable to parse", sourcePath: file }] }));
+      return { path: path2.relative(root, file), diagnostics: document.diagnostics };
+    }));
+    return sendJson(res, 200, { files: items });
+  }
+  if (url.pathname === "/api/document") {
+    const file = url.searchParams.get("file");
+    if (!file) return sendJson(res, 400, { error: "file is required" });
+    const absolute = await resolveRequestedDocument(root, config, allMd, file);
+    return sendJson(res, 200, await parseAndResolve(absolute, root, config));
+  }
+  if (url.pathname === "/api/source") {
+    const file = url.searchParams.get("file");
+    if (!file) return sendJson(res, 400, { error: "file is required" });
+    const absolute = await resolveRequestedDocument(root, config, allMd, file);
+    return sendJson(res, 200, { source: await fs2.readFile(absolute, "utf8") });
+  }
+  if (url.pathname === "/artifact") {
+    const file = url.searchParams.get("file");
+    const src = url.searchParams.get("src");
+    if (!file || !src) return sendJson(res, 400, { error: "file and src are required" });
+    const sourceFile = await resolveRequestedDocument(root, config, allMd, file);
+    const document = await parseAndResolve(sourceFile, root, config);
+    if (!collectArtifactRefs(document.nodes).has(src)) return sendJson(res, 403, { error: "artifact is not referenced by document" });
+    const artifact = await resolveSafeRealPath(root, sourceFile, src);
+    const ext = path2.extname(artifact).toLowerCase();
+    if (!artifactExtensions.has(ext) && !dataExtensions.has(ext)) return sendJson(res, 400, { error: "unsupported artifact" });
+    if (ext === ".html" && !config.security.allowHtmlEmbeds) return sendJson(res, 403, { error: "HTML embeds are blocked" });
+    return fs2.readFile(artifact).then((buffer) => {
+      res.statusCode = 200;
+      res.setHeader("content-type", contentType(artifact));
+      res.end(buffer);
+    });
+  }
+  return serveViewerAsset(url.pathname, res);
+}
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+function sendHtml(res, body) {
+  res.statusCode = 200;
+  res.setHeader("content-type", "text/html; charset=utf8");
+  res.end(body);
+}
+async function serveViewerAsset(pathname, res) {
+  const viewerDistDir = await findViewerDistDir();
+  if (!viewerDistDir) {
+    if (pathname === "/") return sendHtml(res, viewerHtml());
+    return sendJson(res, 404, { error: "Viewer assets have not been built. Run npm run build." });
+  }
+  const relative = pathname === "/" ? "index.html" : decodeURIComponent(pathname.replace(/^\/+/, ""));
+  const absolute = path2.resolve(viewerDistDir, relative);
+  const insideViewer = !path2.relative(viewerDistDir, absolute).startsWith("..") && !path2.isAbsolute(path2.relative(viewerDistDir, absolute));
+  if (!insideViewer) return sendJson(res, 403, { error: "Forbidden" });
+  try {
+    const body = await fs2.readFile(absolute);
+    res.statusCode = 200;
+    res.setHeader("content-type", contentType(absolute));
+    res.end(body);
+  } catch (error) {
+    if (pathname === "/" && error.code === "ENOENT") return sendHtml(res, viewerHtml());
+    sendJson(res, 404, { error: "Not found" });
+  }
+}
+async function findViewerDistDir() {
+  for (const candidate of viewerDistCandidates) {
+    try {
+      await fs2.access(path2.join(candidate, "index.html"));
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function contentType(file) {
+  const ext = path2.extname(file);
+  if (ext === ".html") return "text/html; charset=utf8";
+  if (ext === ".js") return "text/javascript; charset=utf8";
+  if (ext === ".css") return "text/css; charset=utf8";
+  if (ext === ".svg") return "image/svg+xml";
+  if (ext === ".json") return "application/json";
+  return "application/octet-stream";
+}
+function renderFallback(document) {
+  return document.nodes.map((node) => node.type === "markdown" ? node.value : `[${node.type}]`).join("\n\n");
+}
+function renderStaticHtml(document) {
+  return `<!doctype html><meta charset="utf8"><title>Agent Markdown</title><pre>${escapeHtml(JSON.stringify(document, null, 2))}</pre>`;
+}
+function escapeHtml(value) {
+  return value.replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char]);
+}
+async function openBrowser(url) {
+  await import("child_process").then(({ execFile }) => execFile(process.platform === "darwin" ? "open" : "xdg-open", [url]));
+}
+function viewerHtml() {
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Agent Markdown</title>
+<style>
+:root{font-family:Inter,ui-sans-serif,system-ui,sans-serif;color:#111;background:#f8fafc}body{margin:0}.app{display:grid;grid-template-columns:300px 1fr;min-height:100vh}.top{grid-column:1/3;padding:12px 18px;background:#111827;color:white;font-weight:700}.side{border-right:1px solid #e5e7eb;padding:16px;background:white}.main{padding:24px;max-width:1100px}.file{display:block;width:100%;text-align:left;border:1px solid #e5e7eb;background:#fff;padding:8px;margin:6px 0;border-radius:8px;cursor:pointer}.file.active{border-color:#2563eb;background:#eff6ff}.card{border:1px solid #e5e7eb;border-radius:12px;background:#fff;padding:16px;margin:12px 0;box-shadow:0 1px 2px #0001}.error{border-color:#ef4444;background:#fef2f2}.warning{border-color:#f59e0b;background:#fffbeb}.grid{display:grid;gap:12px}.tabs button{margin-right:8px}.diag{font-size:13px;margin:8px 0;padding:8px;border-radius:8px;background:#f3f4f6}pre{white-space:pre-wrap;background:#111827;color:#e5e7eb;padding:16px;border-radius:12px;overflow:auto}table{border-collapse:collapse;width:100%;background:white}th,td{border:1px solid #e5e7eb;padding:8px;text-align:left}th{background:#f9fafb}input,select{padding:8px;border:1px solid #d1d5db;border-radius:8px}</style>
+</head><body><div id="app" class="app"><div class="top">Agent Markdown</div><aside class="side"><h3>Project files</h3><div id="files">Loading...</div><h3>Diagnostics</h3><div id="diagnostics"></div></aside><main class="main"><button id="toggle">Source</button><div id="document"></div></main></div>
+<script>
+let selected=null, doc=null, showSource=false;
+const ws = new WebSocket('ws://' + location.host + '/ws'); ws.onmessage = () => loadFiles().then(()=> selected && loadDoc(selected));
+document.getElementById('toggle').onclick=()=>{showSource=!showSource; renderDoc();};
+async function loadFiles(){const data=await fetch('/api/files').then(r=>r.json()); const el=document.getElementById('files'); el.innerHTML=''; data.files.forEach(f=>{const b=document.createElement('button'); b.className='file'+(f.path===selected?' active':''); b.textContent=f.path+' '+(f.diagnostics.some(d=>d.severity==='error')?'\u2715':'\u2713'); b.onclick=()=>loadDoc(f.path); el.appendChild(b);}); if(!selected && data.files[0]) await loadDoc(data.files[0].path);}
+async function loadDoc(file){selected=file; doc=await fetch('/api/document?file='+encodeURIComponent(file)).then(r=>r.json()); showSource=false; await renderDoc(); loadFiles();}
+function diagnostics(){const el=document.getElementById('diagnostics'); el.innerHTML=''; (doc?.diagnostics||[]).forEach(d=>{const x=document.createElement('div'); x.className='diag '+d.severity; x.textContent=d.severity.toUpperCase()+': '+d.message+(d.line?' line '+d.line:''); el.appendChild(x);});}
+async function renderDoc(){diagnostics(); const el=document.getElementById('document'); if(!doc){el.textContent='Select a file';return;} if(showSource){const src=await fetch('/api/source?file='+encodeURIComponent(selected)).then(r=>r.json()); el.innerHTML='<pre></pre>'; el.querySelector('pre').textContent=src.source; return;} el.innerHTML=''; doc.nodes.forEach(n=>el.appendChild(renderNode(n)));}
+function renderNode(n){const d=document.createElement('div'); if(n.type==='markdown'){d.innerHTML=md(n.value); return d;} d.className='card'; if(n.type==='error'){d.className='card error'; d.textContent=n.message; return d;} if(n.type==='metric'){d.innerHTML='<strong>'+esc(n.label)+'</strong><h2>'+esc(metricValue(n))+'</h2>'+(n.delta?'<p>'+esc(n.delta)+'</p>':''); return d;} if(n.type==='chart'){d.innerHTML='<strong>'+esc(n.title||'Chart')+'</strong><pre>'+esc('[Chart: '+n.chartType+' chart of '+(n.y||n.value||'value')+' by '+(n.x||n.label||'label')+']')+'</pre>'; return d;} if(n.type==='table'||n.type==='query'){const rows=rowsFor(n); d.innerHTML='<strong>'+esc(n.title||n.type)+'</strong>'+table(rows,n.columns||n.select); return d;} if(n.type==='callout'){d.className='card '+n.calloutType; d.innerHTML='<strong>'+esc(n.title||n.calloutType)+'</strong><div>'+md(n.body||'')+'</div>'; return d;} if(n.type==='tabs'){d.className='card tabs'; let active=0; const nav=document.createElement('div'), body=document.createElement('div'); const show=i=>{active=i; body.innerHTML=''; n.tabs[i].children.forEach(c=>body.appendChild(renderNode(c)));}; n.tabs.forEach((t,i)=>{const b=document.createElement('button'); b.textContent=t.label; b.onclick=()=>show(i); nav.appendChild(b);}); d.append(nav,body); show(0); return d;} if(n.type==='timeline'){d.innerHTML='<strong>Timeline</strong>'+((n.events||[]).map(e=>'<p><b>'+esc(e.date)+'</b> '+esc(e.title)+'</p>').join('')); return d;} if(n.type==='form'){d.innerHTML='<strong>'+esc(n.title||'Form')+'</strong>'+n.fields.map(f=>'<label><p>'+esc(f.label||f.name)+'</p><input type="'+(f.fieldType==='number'?'number':f.fieldType==='date'?'date':'text')+'" value="'+esc(f.default||'')+'"></label>').join(''); return d;} if(n.type==='embed'){d.innerHTML='<strong>'+esc(n.title||n.src)+'</strong><p><a href="/artifact?file='+encodeURIComponent(selected)+'&src='+encodeURIComponent(n.src)+'">Open artifact</a></p>'; return d;} d.innerHTML='<pre>'+esc('['+n.type+']')+'</pre>'; return d;}
+function rowsFor(n){const ds=doc.dataSources[n.data]; if(!ds?.rows)return[]; let rows=[...ds.rows]; if(n.where) rows=rows.filter(r=>Object.entries(n.where).every(([k,v])=>typeof v==='object'?true:r[k]===v)); if(n.sort) rows.sort((a,b)=>a[n.sort.by]>b[n.sort.by]?1:-1); if(n.limit) rows=rows.slice(0,n.limit); return rows;}
+function metricValue(n){if(n.value!=null)return n.value; const rows=doc.dataSources[n.data]?.rows||[]; const vals=rows.map(r=>Number(r[n.field])).filter(Number.isFinite); if(n.aggregate==='count')return rows.length; if(n.aggregate==='avg')return vals.reduce((a,b)=>a+b,0)/Math.max(vals.length,1); if(n.aggregate==='min')return Math.min(...vals); if(n.aggregate==='max')return Math.max(...vals); return vals.reduce((a,b)=>a+b,0);}
+function table(rows, cols){cols=cols||Object.keys(rows[0]||{}); return '<table><thead><tr>'+cols.map(c=>'<th>'+esc(c)+'</th>').join('')+'</tr></thead><tbody>'+rows.slice(0,500).map(r=>'<tr>'+cols.map(c=>'<td>'+esc(r[c])+'</td>').join('')+'</tr>').join('')+'</tbody></table>';}
+function md(s){return esc(s).replace(/^# (.*)$/gm,'<h1>$1</h1>').replace(/^## (.*)$/gm,'<h2>$1</h2>').replace(/\\n/g,'<br>');}
+function esc(s){return String(s??'').replace(/[&<>"]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));}
+loadFiles();
+</script></body></html>`;
+}