hd-garden 0.3.8 → 0.3.10

package/ui/core/fence.mjs

@@ -0,0 +1,201 @@
+import { parse as parseYaml } from "yaml";
+import { sha256Hex } from "./sha256.mjs";
+
+export const normalizeNewlines = (text) => text.replace(/\r\n?/gu, "\n");
+
+export const shortHash = (text) => sha256Hex(normalizeNewlines(text)).slice(0, 8);
+
+export const intentHash = (intent) => shortHash(normalizeNewlines(String(intent ?? "")).trim());
+
+/** Hash of the whole fence, from the opening backticks to the closing ones. */
+export const fenceHash = (raw) => shortHash(raw);
+
+/**
+ * @typedef {{
+ *   marker: string, lang: string, info: string, start: number, end: number,
+ *   startLine: number, endLine: number, bodyStartLine: number, closed: boolean,
+ *   raw: string, body: string,
+ * }} Fence
+ */
+
+/**
+ * Line scanner shared by build, CLI, admin and editor plugins. Offsets are
+ * character offsets into the original text; lines are 1-based.
+ * @param {string} markdown
+ * @returns {Fence[]}
+ */
+export function scanFences(markdown) {
+  const fences = [];
+  const lineRe = /[^\n]*(?:\n|$)/gu;
+  let offset = 0;
+  let lineNumber = 0;
+  let open = null;
+  for (const match of markdown.matchAll(lineRe)) {
+    const chunk = match[0];
+    if (!chunk && offset >= markdown.length) break;
+    lineNumber += 1;
+    const line = chunk.replace(/\r?\n$/u, "");
+    const lineEnd = offset + line.length;
+    if (open) {
+      const closer = /^ {0,3}(`{3,}|~{3,})\s*$/u.exec(line);
+      if (closer && closer[1][0] === open.marker[0] && closer[1].length >= open.marker.length) {
+        open.endLine = lineNumber;
+        open.end = lineEnd;
+        open.closed = true;
+        open.raw = markdown.slice(open.start, open.end);
+        open.body = open.bodyLines.join("\n");
+        delete open.bodyLines;
+        fences.push(open);
+        open = null;
+      } else {
+        open.bodyLines.push(line);
+      }
+    } else {
+      const opener = /^ {0,3}(`{3,}|~{3,})(.*)$/u.exec(line);
+      if (opener && !(opener[1][0] === "`" && opener[2].includes("`"))) {
+        const info = opener[2].trim();
+        const [lang = "", ...rest] = info.split(/\s+/u);
+        open = {
+          marker: opener[1],
+          lang: lang.toLowerCase(),
+          info: rest.join(" "),
+          start: offset,
+          startLine: lineNumber,
+          bodyStartLine: lineNumber + 1,
+          bodyLines: [],
+        };
+      }
+    }
+    offset += chunk.length;
+    if (offset >= markdown.length && !chunk.endsWith("\n")) break;
+  }
+  if (open) {
+    open.endLine = lineNumber;
+    open.end = markdown.length;
+    open.closed = false;
+    open.raw = markdown.slice(open.start);
+    open.body = open.bodyLines.join("\n");
+    delete open.bodyLines;
+    fences.push(open);
+  }
+  return fences;
+}
+
+export const BLOCK_LANGS = new Set(["ui", "intent", "widget"]);
+
+/** @param {string} markdown @returns {Fence[]} */
+export function findBlocks(markdown) {
+  return scanFences(markdown).filter((fence) => BLOCK_LANGS.has(fence.lang));
+}
+
+/**
+ * Splits a `ui` fence body into the YAML block header and the body. Returns
+ * `bodyLineOffset`, the number of lines before the body inside the fence.
+ */
+export function splitUiBody(body) {
+  const lines = normalizeNewlines(body).split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { error: "块头要以单独一行 --- 开始", header: null, headerText: "", bodyText: body, bodyLineOffset: 0 };
+  }
+  const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (closing < 0) {
+    return { error: "块头缺少结束的 ---", header: null, headerText: "", bodyText: "", bodyLineOffset: 0 };
+  }
+  const headerText = lines.slice(1, closing).join("\n");
+  let header;
+  try {
+    header = parseYaml(headerText) ?? {};
+  } catch (error) {
+    return {
+      error: `块头不是有效的 YAML：${error instanceof Error ? error.message.split("\n")[0] : "解析失败"}`,
+      header: null,
+      headerText,
+      bodyText: lines.slice(closing + 1).join("\n"),
+      bodyLineOffset: closing + 1,
+    };
+  }
+  if (!header || typeof header !== "object" || Array.isArray(header)) {
+    return { error: "块头必须是 YAML 对象", header: null, headerText, bodyText: "", bodyLineOffset: closing + 1 };
+  }
+  return { error: null, header, headerText, bodyText: lines.slice(closing + 1).join("\n"), bodyLineOffset: closing + 1 };
+}
+
+/** Writes `compiled:` by editing only that header line, keeping the author's formatting. */
+export function setCompiled(fenceRaw, hash) {
+  const lines = normalizeNewlines(fenceRaw).split("\n");
+  const headerStart = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (headerStart !== 1) return fenceRaw;
+  const headerEnd = lines.findIndex((line, index) => index > headerStart && line.trim() === "---");
+  if (headerEnd < 0) return fenceRaw;
+  const existing = lines.findIndex((line, index) => index > headerStart && index < headerEnd && /^compiled\s*:/u.test(line));
+  if (existing >= 0) lines[existing] = `compiled: ${hash}`;
+  else lines.splice(headerEnd, 0, `compiled: ${hash}`);
+  return lines.join("\n");
+}
+
+/** Read from the raw header text: YAML would coerce hashes like 12e45678 into numbers. */
+export function compiledOf(headerText) {
+  const match = /^compiled\s*:\s*["']?([^"'\s]*)["']?\s*$/mu.exec(headerText ?? "");
+  return match ? match[1] : undefined;
+}
+
+export function intentOf(fence) {
+  if (fence.lang === "intent") return normalizeNewlines(fence.body);
+  if (fence.lang === "ui") {
+    const { header } = splitUiBody(fence.body);
+    return typeof header?.intent === "string" ? header.intent : null;
+  }
+  if (fence.lang === "widget") {
+    try {
+      const data = parseYaml(fence.body);
+      return typeof data?.intent === "string" ? data.intent : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function idOf(fence) {
+  if (fence.lang === "intent") return fence.info.split(/\s+/u)[0] || null;
+  if (fence.lang === "ui") {
+    const { header } = splitUiBody(fence.body);
+    return typeof header?.id === "string" ? header.id : null;
+  }
+  return null;
+}
+
+export const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+const isExternal = (value) => /^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(value) || /^[a-z][a-z0-9+.-]*:/iu.test(value);
+
+/**
+ * Resolves a path written inside a post against the post's same-name
+ * directory. `markdownPath` is POSIX and relative to content/ or the repo,
+ * e.g. `posts/llm/kv.md`. Returns `{ path }` or `{ error }`.
+ */
+export function resolveSidecarPath(markdownPath, relative) {
+  if (typeof relative !== "string" || !relative.trim()) return { error: "路径不能为空" };
+  const value = relative.trim().replaceAll("\\", "/");
+  if (isExternal(value) || value.startsWith("/")) return { error: "只能使用本文同名目录里的相对路径" };
+  const markdown = markdownPath.replaceAll("\\", "/");
+  if (!markdown.endsWith(".md")) return { error: "稿件路径必须是 .md" };
+  const directory = markdown.includes("/") ? markdown.slice(0, markdown.lastIndexOf("/")) : "";
+  const stem = markdown.slice(markdown.lastIndexOf("/") + 1, -3);
+  const sidecar = directory ? `${directory}/${stem}` : stem;
+  const segments = directory ? directory.split("/") : [];
+  for (const segment of value.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (!segments.length) return { error: "路径越出了内容目录" };
+      segments.pop();
+    } else {
+      segments.push(segment);
+    }
+  }
+  const resolved = segments.join("/");
+  if (!resolved.startsWith(`${sidecar}/`) || resolved.length <= sidecar.length + 1) {
+    return { error: `只能使用同名目录 ${stem}/ 里的文件` };
+  }
+  return { path: resolved };
+}

package/ui/core/fix-prompt.mjs

@@ -0,0 +1,35 @@
+const MAX_BLOCKS = 10;
+
+/**
+ * The prompt the pre-commit hook and the admin hand to an AI. `problems` is a
+ * list of `{ file, block, diagnostics }` where block comes from scanMarkdown.
+ */
+export function buildFixPrompt(problems, { standaloneReference = null } = {}) {
+  const lines = [
+    "请修复下面 Garden 博文里有错误的 ui 块。",
+    "",
+    "要求：",
+    "- 先运行 npx garden ui prompt，读组件目录和规则；仓库里有 garden-ui skill 时按它的流程做。",
+    "- 只改列出的块，用 npx garden ui apply <稿件> --id <id> 写回（没有 id 的 intent 用 --intent-hash），不要直接编辑稿件。",
+    "- 不改 intent 的原意。修好后运行 npx garden ui check <稿件>，直到通过。",
+    "- 如果你不能访问这个仓库，就只回复每块修好后的完整围栏。",
+    "",
+  ];
+  problems.forEach((problem, index) => {
+    const { file, block, diagnostics } = problem;
+    const target = block.id ? `id: ${block.id}` : `intent-hash: ${block.intentHash}`;
+    lines.push(`${index + 1}. ${file}，第 ${block.startLine}–${block.endLine} 行，${target}`);
+    if (block.lang === "intent") {
+      lines.push("   - intent-uncompiled：这段想法还没编译，请按原话编译成 ui 块（或判断后写回正文）。");
+    }
+    for (const item of diagnostics) lines.push(`   - 第 ${item.line} 行 ${item.code}：${item.message}`);
+    if (index < MAX_BLOCKS) {
+      lines.push("", "当前围栏：", "", block.raw, "");
+    } else {
+      lines.push("");
+    }
+  });
+  if (problems.length > MAX_BLOCKS) lines.push(`（只附了前 ${MAX_BLOCKS} 块的原文，其余按上面的位置去稿件里找。）`, "");
+  if (standaloneReference) lines.push("---", "", "以下是 Garden ui 块的完整写作规则、组件参考和配方：", "", standaloneReference);
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/ui/core/format.mjs

@@ -0,0 +1,96 @@
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+
+const significant = (value) => String(Number(value.toPrecision(3)));
+
+export function fixed(value, digits = 0) {
+  if (!isFiniteNumber(value)) return "—";
+  const places = Math.max(0, Math.min(20, Math.trunc(Number(digits) || 0)));
+  return value.toFixed(places);
+}
+
+export function percent(value, digits = 0) {
+  if (!isFiniteNumber(value)) return "—";
+  return `${fixed(value * 100, digits)}%`;
+}
+
+const binaryUnits = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+
+export function bytes(value) {
+  if (!isFiniteNumber(value)) return "—";
+  const sign = value < 0 ? "-" : "";
+  let amount = Math.abs(value);
+  let unit = 0;
+  while (amount >= 1024 && unit < binaryUnits.length - 1) {
+    amount /= 1024;
+    unit += 1;
+  }
+  return `${sign}${significant(amount)} ${binaryUnits[unit]}`;
+}
+
+const decimalUnits = ["", "K", "M", "G", "T"];
+
+export function si(value) {
+  if (!isFiniteNumber(value)) return "—";
+  const sign = value < 0 ? "-" : "";
+  let amount = Math.abs(value);
+  let unit = 0;
+  while (amount >= 1000 && unit < decimalUnits.length - 1) {
+    amount /= 1000;
+    unit += 1;
+  }
+  return `${sign}${significant(amount)}${decimalUnits[unit]}`;
+}
+
+export function thousands(value) {
+  if (!isFiniteNumber(value)) return "—";
+  const [integer, fraction] = String(Math.abs(value)).split(".");
+  if (integer.includes("e")) return String(value);
+  const grouped = integer.replace(/\B(?=(\d{3})+(?!\d))/gu, ",");
+  return `${value < 0 ? "-" : ""}${grouped}${fraction ? `.${fraction}` : ""}`;
+}
+
+export function float32(value) {
+  return typeof value === "number" ? Math.fround(value) : Number.NaN;
+}
+
+function bits(value, byteLength, exponentBits) {
+  if (typeof value !== "number") return "—";
+  const view = new DataView(new ArrayBuffer(byteLength));
+  if (byteLength === 8) view.setFloat64(0, value);
+  else view.setFloat32(0, value);
+  let binary = "";
+  for (let index = 0; index < byteLength; index += 1) {
+    binary += view.getUint8(index).toString(2).padStart(8, "0");
+  }
+  return `${binary[0]} ${binary.slice(1, 1 + exponentBits)} ${binary.slice(1 + exponentBits)}`;
+}
+
+export const bits64 = (value) => bits(value, 8, 11);
+export const bits32 = (value) => bits(value, 4, 8);
+
+const FORMAT_PATTERN = /^(?:number|bytes|si|thousands|percent(?::\d{1,2})?|fixed:\d{1,2})$/u;
+
+export function isValidFormat(format) {
+  return typeof format === "string" && FORMAT_PATTERN.test(format);
+}
+
+/** Display rule shared by props, interpolation and static snapshots. */
+export function formatValue(value, format) {
+  if (value === undefined || value === null) return "—";
+  if (typeof value === "number" && !Number.isFinite(value)) return "—";
+  if (typeof value === "boolean") return value ? "是" : "否";
+  if (typeof value !== "number") {
+    if (Array.isArray(value)) return value.map((item) => formatValue(item)).join("、");
+    if (typeof value === "object") return "—";
+    return String(value);
+  }
+  if (!format || format === "number") return String(value);
+  if (format === "bytes") return bytes(value);
+  if (format === "si") return si(value);
+  if (format === "thousands") return thousands(value);
+  const percentMatch = /^percent(?::(\d{1,2}))?$/u.exec(format);
+  if (percentMatch) return percent(value, Number(percentMatch[1] ?? 0));
+  const fixedMatch = /^fixed:(\d{1,2})$/u.exec(format);
+  if (fixedMatch) return fixed(value, Number(fixedMatch[1]));
+  return String(value);
+}

package/ui/core/index.mjs

@@ -0,0 +1,37 @@
+export { applyBlock, ApplyError, classifyReplacement } from "./apply.mjs";
+export { CATALOG_VERSION, catalogReference, catalogSchema, COMPONENTS, COMPONENT_NAMES, GROUPS, TONES, TONE_LABELS } from "./catalog.mjs";
+export { compileUiBlock, jsonFence, PAYLOAD_VERSION, readPayload } from "./compile.mjs";
+export { analyzeExpr, createBudget, evaluate, ExprError, FUNCTION_NAMES } from "./expr.mjs";
+export {
+  compiledOf,
+  fenceHash,
+  findBlocks,
+  ID_PATTERN,
+  idOf,
+  intentHash,
+  intentOf,
+  normalizeNewlines,
+  resolveSidecarPath,
+  scanFences,
+  setCompiled,
+  splitUiBody,
+} from "./fence.mjs";
+export { bits32, bits64, bytes, fixed, float32, formatValue, isValidFormat, percent, si, thousands } from "./format.mjs";
+export { parseUiBody, parseUiBodyPartial } from "./parse.mjs";
+export { blockStatus, scanMarkdown } from "./scan.mjs";
+export { intentFence, STARTERS } from "./starters.mjs";
+export { docToHtml, docToMarkdown, docToText, renderStatic, toDoc } from "./static.mjs";
+export {
+  collectDecls,
+  computeScope,
+  defaultStateValues,
+  isPowerOfTwo,
+  lookupFrom,
+  orderLets,
+  parseDataFile,
+  runExpect,
+  sampleDomain,
+  sweepSeries,
+} from "./state.mjs";
+export { collectDataSources, contentForDistribution, contentForFeed, contentToSearchText, transformUiContent } from "./transform.mjs";
+export { checkUiBlock, suggestComponent, withRow } from "./validate.mjs";

package/ui/core/parse.mjs

@@ -0,0 +1,229 @@
+import * as acorn from "acorn";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { mdxExpressionFromMarkdown } from "mdast-util-mdx-expression";
+import { mdxJsxFromMarkdown } from "mdast-util-mdx-jsx";
+import { mdxExpression } from "micromark-extension-mdx-expression";
+import { mdxJsx } from "micromark-extension-mdx-jsx";
+import { COMPONENTS } from "./catalog.mjs";
+import { pruneExpr } from "./expr.mjs";
+
+const parseOptions = {
+  extensions: [
+    mdxJsx({ acorn, addResult: true }),
+    mdxExpression({ acorn, addResult: true }),
+    // Same as MDX: indentation inside elements must not become code blocks.
+    { disable: { null: ["autolink", "codeIndented", "htmlFlow", "htmlText"] } },
+  ],
+  mdastExtensions: [mdxJsxFromMarkdown(), mdxExpressionFromMarkdown()],
+};
+
+const lineOf = (node) => node?.position?.start?.line ?? 1;
+
+function errorLine(error) {
+  const place = error?.place;
+  if (place?.line) return place.line;
+  if (place?.start?.line) return place.start.line;
+  if (typeof error?.line === "number") return error.line;
+  const match = /\((\d+):\d+/u.exec(String(error?.message ?? ""));
+  return match ? Number(match[1]) : 1;
+}
+
+const isBlockElement = (node) =>
+  node.t === "el" && !(COMPONENTS[node.n]?.inline);
+
+function expressionFrom(estree) {
+  const statement = estree?.body?.[0];
+  if (!statement || statement.type !== "ExpressionStatement" || estree.body.length !== 1) return null;
+  return pruneExpr(statement.expression);
+}
+
+/**
+ * Parses the body of a `ui` fence. Never executes code: expressions become
+ * pruned ESTree that only `expr.mjs` interprets.
+ */
+export function parseUiBody(text) {
+  const diagnostics = [];
+  const report = (code, line, message) => diagnostics.push({ code, line, message, severity: "error" });
+  let tree;
+  try {
+    tree = fromMarkdown(text, parseOptions);
+  } catch (error) {
+    report("ui-syntax", errorLine(error), String(error?.reason ?? error?.message ?? "无法解析").split("\n")[0]);
+    return { root: null, diagnostics };
+  }
+
+  const convertAttributes = (node) => {
+    const props = {};
+    for (const attribute of node.attributes) {
+      if (attribute.type !== "mdxJsxAttribute") {
+        report("ui-syntax", lineOf(node), `<${node.name}> 不能使用展开属性`);
+        continue;
+      }
+      if (attribute.value === null || attribute.value === undefined) {
+        props[attribute.name] = { k: "lit", v: true };
+      } else if (typeof attribute.value === "string") {
+        props[attribute.name] = { k: "lit", v: attribute.value };
+      } else {
+        const expression = expressionFrom(attribute.value.data?.estree);
+        if (!expression) {
+          report("ui-expr", lineOf(node), `<${node.name}> 的 ${attribute.name} 需要一个表达式`);
+          continue;
+        }
+        if (expression.type === "Literal" && !expression.regex) {
+          props[attribute.name] = { k: "lit", v: expression.value, s: attribute.value.value };
+        } else if (expression.type === "UnaryExpression" && expression.operator === "-" && expression.argument.type === "Literal" && typeof expression.argument.value === "number") {
+          props[attribute.name] = { k: "lit", v: -expression.argument.value, s: attribute.value.value };
+        } else {
+          props[attribute.name] = { k: "expr", e: expression, s: attribute.value.value };
+        }
+      }
+    }
+    return props;
+  };
+
+  const convertInline = (node) => {
+    switch (node.type) {
+      case "text":
+        return [{ t: "text", v: node.value }];
+      case "mdxTextExpression":
+      case "mdxFlowExpression": {
+        const expression = expressionFrom(node.data?.estree);
+        if (!expression) {
+          if (node.value.trim()) report("ui-expr", lineOf(node), "插值需要一个表达式");
+          return [];
+        }
+        return [{ t: "x", e: expression, s: node.value, l: lineOf(node) }];
+      }
+      case "strong":
+        return [{ t: "strong", c: node.children.flatMap(convertInline) }];
+      case "emphasis":
+        return [{ t: "em", c: node.children.flatMap(convertInline) }];
+      case "inlineCode":
+        return [{ t: "code", v: node.value }];
+      case "break":
+        return [{ t: "br" }];
+      case "link": {
+        const url = String(node.url ?? "");
+        if (!/^(?:https:\/\/|\.{0,2}\/|#)/u.test(url) && !/^[\w\u3400-\u9fff./-]+$/u.test(url)) {
+          report("ui-markdown", lineOf(node), "链接只能是相对路径或 https 地址");
+          return node.children.flatMap(convertInline);
+        }
+        return [{ t: "link", u: url, c: node.children.flatMap(convertInline) }];
+      }
+      case "mdxJsxTextElement":
+      case "mdxJsxFlowElement":
+        return [convertElement(node)];
+      case "image":
+      case "imageReference":
+        report("ui-markdown", lineOf(node), "块里不能写图片语法，插图用 <Image>");
+        return [];
+      case "html":
+        report("ui-markdown", lineOf(node), "块里不能写 HTML");
+        return [];
+      case "linkReference":
+      case "footnoteReference":
+        return node.children ? node.children.flatMap(convertInline) : [];
+      default:
+        report("ui-markdown", lineOf(node), `块里不能写 ${node.type}`);
+        return [];
+    }
+  };
+
+  const trimInline = (nodes) => {
+    const output = [...nodes];
+    while (output.length && output[0].t === "text" && !output[0].v.trim()) output.shift();
+    while (output.length && output.at(-1).t === "text" && !output.at(-1).v.trim()) output.pop();
+    if (output[0]?.t === "text") output[0] = { ...output[0], v: output[0].v.replace(/^\s+/u, "") };
+    if (output.at(-1)?.t === "text") output[output.length - 1] = { ...output.at(-1), v: output.at(-1).v.replace(/\s+$/u, "") };
+    return output;
+  };
+
+  /** Block components written inside a paragraph are lifted out of it. */
+  const splitParagraph = (inline) => {
+    const blocks = [];
+    let run = [];
+    const flush = () => {
+      const trimmed = trimInline(run);
+      if (trimmed.length) blocks.push({ t: "p", c: trimmed });
+      run = [];
+    };
+    for (const node of inline) {
+      if (isBlockElement(node)) {
+        flush();
+        blocks.push(node);
+      } else {
+        run.push(node);
+      }
+    }
+    flush();
+    return blocks;
+  };
+
+  const convertBlock = (node) => {
+    switch (node.type) {
+      case "paragraph":
+        return splitParagraph(node.children.flatMap(convertInline));
+      case "mdxJsxFlowElement":
+        return [convertElement(node)];
+      case "mdxFlowExpression":
+        return splitParagraph(convertInline(node));
+      case "list":
+        return [{
+          t: "list",
+          o: Boolean(node.ordered),
+          s: node.start ?? 1,
+          c: node.children.map((item) => ({ t: "li", c: item.children.flatMap(convertBlock) })),
+        }];
+      case "blockquote":
+        return [{ t: "quote", c: node.children.flatMap(convertBlock) }];
+      case "thematicBreak":
+        return [{ t: "hr" }];
+      case "heading":
+        report("ui-markdown", lineOf(node), "块里不能写标题，它会打乱文章目录");
+        return [];
+      case "code":
+        report("ui-markdown", lineOf(node), "块里不能写代码围栏，代码用 <Code>");
+        return [];
+      case "html":
+        report("ui-markdown", lineOf(node), "块里不能写 HTML");
+        return [];
+      case "definition":
+      case "footnoteDefinition":
+        report("ui-markdown", lineOf(node), `块里不能写 ${node.type}`);
+        return [];
+      default:
+        return splitParagraph(convertInline(node));
+    }
+  };
+
+  function convertElement(node) {
+    const name = node.name ?? "";
+    if (!name) report("ui-syntax", lineOf(node), "块里不能写空标签 <>");
+    let children;
+    if (node.type === "mdxJsxTextElement") {
+      const inline = node.children.flatMap(convertInline);
+      // One-line containers such as <Step>…</Step> hold a paragraph, not loose inline nodes.
+      children = COMPONENTS[name]?.children === "text" ? trimInline(inline) : splitParagraph(inline);
+    } else {
+      children = node.children.flatMap(convertBlock);
+    }
+    return { t: "el", n: name, p: convertAttributes(node), c: children, l: lineOf(node) };
+  }
+
+  const root = { t: "root", c: tree.children.flatMap(convertBlock) };
+  if (/^\s*(?:import|export)\s/mu.test(text)) {
+    const line = text.split("\n").findIndex((current) => /^\s*(?:import|export)\s/u.test(current)) + 1;
+    report("ui-markdown", line, "块里不能写 import / export");
+  }
+  return { root, diagnostics };
+}
+
+/** Best-effort parse of half-written input: drops trailing lines until it parses. */
+export function parseUiBodyPartial(text) {
+  const lines = text.split("\n");
+  for (let end = lines.length; end > 0; end -= 1) {
+    const attempt = parseUiBody(lines.slice(0, end).join("\n"));
+    if (attempt.root) return { ...attempt, truncatedAt: end < lines.length ? end : null };
+  }
+  return parseUiBody("");
+}

package/ui/core/scan.mjs

@@ -0,0 +1,53 @@
+import { compiledOf, fenceHash, findBlocks, idOf, intentHash, intentOf, splitUiBody } from "./fence.mjs";
+import { checkUiBlock } from "./validate.mjs";
+
+/** Status of one block: uncompiled / stale / error / ok. */
+export function blockStatus(block, check) {
+  if (block.lang === "intent") return "uncompiled";
+  if (block.lang === "ui") {
+    if (check && !check.ok) return "error";
+    const { header, headerText } = splitUiBody(block.body);
+    const compiled = compiledOf(headerText);
+    if (typeof header?.intent === "string" && compiled !== undefined && compiled !== intentHash(header.intent)) return "stale";
+    return "ok";
+  }
+  return "ok";
+}
+
+function sectionTitle(lines, startLine) {
+  for (let index = startLine - 2; index >= 0; index -= 1) {
+    const heading = /^(#{2,6})\s+(.+?)\s*#*$/u.exec(lines[index]);
+    if (heading) return heading[2].trim();
+  }
+  return null;
+}
+
+/**
+ * Everything `garden ui scan`, the hook, the admin and the editors need to
+ * know about the blocks of one Markdown file.
+ */
+export function scanMarkdown(markdown, options = {}) {
+  const { markdownPath = null, readData = null, skipData = false } = options;
+  const lines = markdown.split(/\r?\n/u);
+  return findBlocks(markdown).map((block) => {
+    const intent = intentOf(block);
+    const check = block.lang === "ui"
+      ? checkUiBlock(block.body, { lineOffset: block.startLine, markdownPath, readData, skipData })
+      : null;
+    const header = block.lang === "ui" ? splitUiBody(block.body).header : null;
+    return {
+      lang: block.lang,
+      id: idOf(block),
+      status: blockStatus(block, check),
+      startLine: block.startLine,
+      endLine: block.endLine,
+      hash: fenceHash(block.raw),
+      intentHash: intent !== null ? intentHash(intent) : null,
+      intent,
+      caption: typeof header?.caption === "string" ? header.caption : null,
+      section: sectionTitle(lines, block.startLine),
+      diagnostics: check ? check.diagnostics : [],
+      raw: block.raw,
+    };
+  });
+}