@terreno/blocks 57.10.1

package/src/parse.test.ts

@@ -0,0 +1,281 @@
+import {describe, expect, it} from "bun:test";
+import {readdirSync, readFileSync} from "node:fs";
+import {join} from "node:path";
+
+import {parseBlocks} from "./parse";
+import {wrapAsTextDocument} from "./schema";
+import {validateBlocks} from "./validate";
+
+const fixturesDir = join(import.meta.dir, "fixtures");
+
+const expectedInvalid: Record<string, {code: string; path: string}[]> = {
+  "column-not-found.yaml": [{code: "COLUMN_NOT_FOUND", path: "blocks[0].x"}],
+  "column-type.yaml": [{code: "COLUMN_TYPE_MISMATCH", path: "blocks[0].y"}],
+  "dataset-not-found.yaml": [{code: "DATASET_NOT_FOUND", path: "blocks[0].data"}],
+  "dataset-too-large.yaml": [{code: "DATASET_TOO_LARGE", path: "datasets.signups.columns"}],
+  "depth-exceeded.yaml": [{code: "DEPTH_EXCEEDED", path: "blocks[0].children[0]"}],
+  "duplicate-id.yaml": [{code: "DUPLICATE_ID", path: "blocks[1].id"}],
+  "invalid-enum.yaml": [{code: "INVALID_ENUM", path: "blocks[0].size"}],
+  "key-order.yaml": [{code: "KEY_ORDER", path: "blocks"}],
+  "missing-required.yaml": [{code: "MISSING_REQUIRED", path: "blocks[0].markdown"}],
+  "not-a-document.txt": [{code: "NOT_A_DOCUMENT", path: ""}],
+  "row-arity.yaml": [{code: "ROW_ARITY_MISMATCH", path: "datasets.signups.rows[0]"}],
+  "select-target.yaml": [
+    {code: "SELECT_TARGET_INVALID", path: "blocks[0].elements[0].action.target"},
+  ],
+  "table-too-wide.yaml": [{code: "TABLE_TOO_WIDE", path: "blocks[0].columns"}],
+  "too-many-points.yaml": [{code: "TOO_MANY_POINTS", path: "datasets.signups.limit"}],
+  "unknown-key.yaml": [{code: "UNKNOWN_KEY", path: "blocks[0].color"}],
+  "unsupported-version.yaml": [{code: "UNSUPPORTED_VERSION", path: "v"}],
+  "yaml-anchor.yaml": [{code: "YAML_FEATURE_DISALLOWED", path: ""}],
+};
+
+describe("parseBlocks", () => {
+  it("parses a prose-only document and validates it with zero errors", () => {
+    const proseDocument = readFileSync(join(fixturesDir, "valid", "prose.yaml"), "utf8");
+    const parsed = parseBlocks(proseDocument);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) {
+      return;
+    }
+    const validated = validateBlocks(parsed.value);
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) {
+      return;
+    }
+    expect(validated.doc).toEqual({
+      blocks: [
+        {
+          markdown: "I could not find any signups for that range.",
+          type: "text",
+        },
+      ],
+      v: 1,
+    });
+    expect(wrapAsTextDocument("Hello")).toEqual({
+      blocks: [{markdown: "Hello", type: "text"}],
+      v: 1,
+    });
+  });
+
+  it("strips a surrounding fence and accepts JSON", () => {
+    for (const fence of ["yaml", "yml", "json", "YAML"]) {
+      const parsed = parseBlocks(`\`\`\`${fence}\nv: 1\nblocks:\n  - type: divider\n\`\`\``);
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) {
+        return;
+      }
+      expect(validateBlocks(parsed.value).ok).toBe(true);
+    }
+
+    const json = parseBlocks('{"v":1,"blocks":[{"type":"heading","text":"Hi"}]}');
+    expect(json.ok).toBe(true);
+    if (!json.ok) {
+      return;
+    }
+    const validated = validateBlocks(json.value);
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) {
+      return;
+    }
+    expect(validated.doc.blocks).toEqual([{text: "Hi", type: "heading"}]);
+  });
+});
+
+describe("block fixtures", () => {
+  it("validates every valid fixture with zero errors", () => {
+    const dir = join(fixturesDir, "valid");
+    const names = readdirSync(dir).filter((name) => name.endsWith(".yaml"));
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      const parsed = parseBlocks(readFileSync(join(dir, name), "utf8"));
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) {
+        continue;
+      }
+      const validated = validateBlocks(parsed.value);
+      expect(validated.ok).toBe(true);
+    }
+    const layout = parseBlocks(readFileSync(join(dir, "layout.yaml"), "utf8"));
+    expect(layout.ok).toBe(true);
+    if (!layout.ok) {
+      return;
+    }
+    const validated = validateBlocks(layout.value);
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) {
+      return;
+    }
+    expect(validated.doc).toEqual({
+      blocks: [
+        {size: "lg", text: "Signups this quarter", type: "heading"},
+        {markdown: "Signups grew **12%** quarter over quarter.", type: "text"},
+        {
+          children: [
+            {delta: "+12%", label: "Total", trend: "up", type: "metric", value: "403"},
+            {label: "Best month", type: "metric", value: "Feb"},
+          ],
+          type: "columns",
+        },
+        {
+          children: [
+            {status: "info", text: "Draft", type: "badge"},
+            {text: "February was the strongest month.", type: "context"},
+            {type: "divider"},
+          ],
+          title: "Notes",
+          type: "card",
+        },
+      ],
+      v: 1,
+    });
+  });
+
+  it("fails each invalid fixture with the expected path and code", () => {
+    const dir = join(fixturesDir, "invalid");
+    const names = readdirSync(dir);
+    expect(names.sort()).toEqual(Object.keys(expectedInvalid).sort());
+    for (const name of names) {
+      const parsed = parseBlocks(readFileSync(join(dir, name), "utf8"));
+      const errors = parsed.ok
+        ? validateBlocks(parsed.value).ok
+          ? []
+          : validateBlocks(parsed.value).errors
+        : parsed.errors;
+      expect(errors.map((item) => ({code: item.code, path: item.path}))).toEqual(
+        expectedInvalid[name]
+      );
+    }
+  });
+});
+
+const orderedDocument = (blocks: unknown[]): Record<string, unknown> => {
+  const doc: Record<string, unknown> = {};
+  doc.v = 1;
+  doc.blocks = blocks;
+  return doc;
+};
+
+describe("validateBlocks limits", () => {
+  it("accepts 50 blocks and rejects 51, including nested blocks", () => {
+    const fifty = Array.from({length: 50}, () => ({type: "divider"}));
+    expect(validateBlocks(orderedDocument(fifty)).ok).toBe(true);
+
+    const fiftyOne = Array.from({length: 51}, () => ({type: "divider"}));
+    const flat = validateBlocks(orderedDocument(fiftyOne));
+    expect(flat.ok).toBe(false);
+    if (flat.ok) {
+      return;
+    }
+    expect(flat.errors.map((item) => ({code: item.code, path: item.path}))).toEqual([
+      {code: "TOO_MANY_BLOCKS", path: "blocks"},
+    ]);
+
+    const children = Array.from({length: 50}, (_unused, index) => ({
+      text: `note ${index}`,
+      type: "context",
+    }));
+    const nested = validateBlocks(orderedDocument([{children, type: "card"}]));
+    expect(nested.ok).toBe(false);
+    if (nested.ok) {
+      return;
+    }
+    expect(nested.errors.map((item) => ({code: item.code, path: item.path}))).toEqual([
+      {code: "TOO_MANY_BLOCKS", path: "blocks"},
+    ]);
+  });
+
+  it("rejects empty input, a second document, and a mapping without v", () => {
+    expect(parseBlocks("").errors).toEqual([
+      expect.objectContaining({code: "NOT_A_DOCUMENT", path: ""}),
+    ]);
+    expect(parseBlocks("v: 1\n---\nv: 1\n").errors).toEqual([
+      expect.objectContaining({code: "NOT_A_DOCUMENT", path: ""}),
+    ]);
+    expect(parseBlocks("blocks:\n  - type: divider\n").errors).toEqual([
+      expect.objectContaining({code: "NOT_A_DOCUMENT", path: ""}),
+    ]);
+  });
+
+  it("rejects a custom YAML tag", () => {
+    const parsed = parseBlocks("v: 1\nblocks: !foo []\n");
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) {
+      return;
+    }
+    expect(parsed.errors.map((item) => item.code)).toEqual(["YAML_FEATURE_DISALLOWED"]);
+  });
+
+  it("describes a ref id and a zero limit with the rules those fields use", () => {
+    const refDocument: Record<string, unknown> = {v: 1};
+    refDocument.datasets = {signups: {id: "bad.id", source: "ref"}};
+    refDocument.blocks = [{type: "divider"}];
+    const refId = validateBlocks(refDocument);
+    expect(refId.ok).toBe(false);
+    if (!refId.ok) {
+      const idError = refId.errors.find((error) => error.path === "datasets.signups.id");
+      expect(idError?.code).toBe("INVALID_FORMAT");
+      expect(idError?.fix).toContain("hyphens");
+    }
+
+    const limitDocument: Record<string, unknown> = {v: 1};
+    limitDocument.datasets = {signups: {id: "ds_signups", limit: 0, source: "ref"}};
+    limitDocument.blocks = [{type: "divider"}];
+    const limit = validateBlocks(limitDocument);
+    expect(limit.ok).toBe(false);
+    if (!limit.ok) {
+      const limitError = limit.errors.find((error) => error.path === "datasets.signups.limit");
+      expect(limitError?.code).toBe("INVALID_TYPE");
+      expect(limitError?.fix).toContain("integer");
+    }
+  });
+
+  it("maps type, size, format, and union failures onto closed codes", () => {
+    const long = "x".repeat(201);
+    const cases: {code: string; doc: Record<string, unknown>}[] = [
+      {
+        code: "INVALID_TYPE",
+        doc: {blocks: [{size: "md", text: 1, type: "heading"}], v: 1},
+      },
+      {
+        code: "TOO_MANY",
+        doc: {
+          blocks: [{children: Array.from({length: 5}, () => ({type: "divider"})), type: "columns"}],
+          v: 1,
+        },
+      },
+      {
+        code: "TOO_LONG",
+        doc: {blocks: [{text: long, type: "heading"}], v: 1},
+      },
+      {
+        code: "TOO_FEW",
+        doc: {blocks: [{children: [{type: "divider"}], type: "columns"}], v: 1},
+      },
+      {
+        code: "TOO_SHORT",
+        doc: {blocks: [{text: "", type: "heading"}], v: 1},
+      },
+      {
+        code: "TOO_SHORT",
+        doc: {blocks: [{text: "   ", type: "heading"}], v: 1},
+      },
+      {
+        code: "INVALID_FORMAT",
+        doc: {blocks: [{id: "Bad", text: "Hi", type: "heading"}], v: 1},
+      },
+      {
+        code: "INVALID_ENUM",
+        doc: {blocks: [{type: "nope"}], v: 1},
+      },
+    ];
+    for (const {code, doc} of cases) {
+      const validated = validateBlocks(doc);
+      expect(validated.ok).toBe(false);
+      if (validated.ok) {
+        return;
+      }
+      expect(validated.errors.some((error) => error.code === code)).toBe(true);
+    }
+  });
+});

package/src/parse.ts

@@ -0,0 +1,104 @@
+import {type Document, parseAllDocuments, visit} from "yaml";
+
+import {BLOCK_ERROR_CODES, type BlockError} from "./errors";
+
+const FENCE = /^```(?:yaml|yml|json)?[^\n]*\n([\s\S]*?)\n?```$/i;
+
+const notADocument = (): BlockError => ({
+  code: "NOT_A_DOCUMENT",
+  fix: "Reply with one document: v, then optional datasets, then blocks.",
+  message: BLOCK_ERROR_CODES.NOT_A_DOCUMENT,
+  path: "",
+});
+
+const yamlFeatureDisallowed = (): BlockError => ({
+  code: "YAML_FEATURE_DISALLOWED",
+  fix: "Remove YAML anchors, aliases, and custom tags. Use plain mappings and sequences.",
+  message: BLOCK_ERROR_CODES.YAML_FEATURE_DISALLOWED,
+  path: "",
+});
+
+/** Drops one surrounding markdown fence so a model that adds one still parses. */
+export const stripBlocksFence = (text: string): string => {
+  const trimmed = text.trim();
+  const match = FENCE.exec(trimmed);
+  if (match?.[1] !== undefined) {
+    return match[1];
+  }
+  return trimmed;
+};
+
+const hasExplicitTag = (tag: string | null | undefined): boolean =>
+  typeof tag === "string" && tag.length > 0;
+
+const usesDisallowedYaml = (doc: Document): boolean => {
+  const hasTagError = doc.errors.some(
+    (error) => error.code === "TAG_RESOLVE_FAILED" || error.code === "BAD_ALIAS"
+  );
+  if (hasTagError) {
+    return true;
+  }
+  let disallowed = false;
+  visit(doc, {
+    Alias() {
+      disallowed = true;
+    },
+    Map(_key, node) {
+      if (node.anchor || hasExplicitTag(node.tag)) {
+        disallowed = true;
+      }
+    },
+    Scalar(_key, node) {
+      if (node.anchor || hasExplicitTag(node.tag)) {
+        disallowed = true;
+      }
+    },
+    Seq(_key, node) {
+      if (node.anchor || hasExplicitTag(node.tag)) {
+        disallowed = true;
+      }
+    },
+  });
+  return disallowed;
+};
+
+const isPlainMapping = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.getPrototypeOf(value) === Object.prototype;
+};
+
+export type ParseBlocksResult = {errors: BlockError[]; ok: false} | {ok: true; value: unknown};
+
+/**
+ * Parses one assistant reply into a plain value.
+ * A surrounding markdown fence is ignored. Anchors, aliases, and custom tags are rejected.
+ * Anything that is not a mapping with `v` is `NOT_A_DOCUMENT`.
+ */
+export const parseBlocks = (text: string): ParseBlocksResult => {
+  const stripped = stripBlocksFence(text);
+  if (stripped.trim() === "") {
+    return {errors: [notADocument()], ok: false};
+  }
+  const docs = parseAllDocuments(stripped, {
+    schema: "core",
+    strict: true,
+    uniqueKeys: true,
+  });
+  const doc = docs[0];
+  if (docs.length !== 1 || doc === undefined) {
+    return {errors: [notADocument()], ok: false};
+  }
+  if (usesDisallowedYaml(doc)) {
+    return {errors: [yamlFeatureDisallowed()], ok: false};
+  }
+  if (doc.errors.length > 0) {
+    return {errors: [notADocument()], ok: false};
+  }
+  const value: unknown = doc.toJS();
+  if (!isPlainMapping(value) || !Object.hasOwn(value, "v")) {
+    return {errors: [notADocument()], ok: false};
+  }
+  return {ok: true, value};
+};

package/src/parsePartial.test.ts

@@ -0,0 +1,53 @@
+import {describe, expect, it} from "bun:test";
+import {readFileSync} from "node:fs";
+import {join} from "node:path";
+
+import {parseBlocksPartial} from "./parsePartial";
+
+const partialDir = join(import.meta.dir, "fixtures", "partial");
+
+describe("parseBlocksPartial", () => {
+  it("returns every block of a finished document and pending false", () => {
+    const text = "v: 1\nblocks:\n  - type: divider\n  - type: heading\n    text: Done\n";
+    expect(parseBlocksPartial(text)).toEqual({
+      blocks: [{type: "divider"}, {text: "Done", type: "heading"}],
+      datasets: undefined,
+      pending: false,
+    });
+  });
+
+  it("keeps completed top-level blocks and drops a cut tail", () => {
+    const text = readFileSync(join(partialDir, "cut-after-divider.yaml"), "utf8");
+    const result = parseBlocksPartial(text);
+    expect(result.pending).toBe(true);
+    expect(result.blocks).toEqual([{type: "divider"}]);
+  });
+
+  it("returns datasets only after the datasets section has closed", () => {
+    const open = parseBlocksPartial("v: 1\ndatasets:\n  signups:\n    source: ref\n    id: ds_1\n");
+    expect(open).toEqual({blocks: [], pending: true});
+
+    const closed = parseBlocksPartial(
+      [
+        "v: 1",
+        "datasets:",
+        "  signups:",
+        "    source: ref",
+        "    id: ds_1",
+        "blocks:",
+        "  - type: divider",
+        "  - type: text",
+        '    markdown: "still',
+        "",
+      ].join("\n")
+    );
+    expect(closed.pending).toBe(true);
+    expect(closed.blocks).toEqual([{type: "divider"}]);
+    expect(closed.datasets).toEqual({signups: {id: "ds_1", source: "ref"}});
+  });
+
+  it("never throws on garbage", () => {
+    expect(parseBlocksPartial("::: not yaml")).toEqual({blocks: [], pending: true});
+    expect(parseBlocksPartial("")).toEqual({blocks: [], pending: true});
+  });
+});

package/src/parsePartial.ts

@@ -0,0 +1,116 @@
+import {parseBlocks, stripBlocksFence} from "./parse";
+import {validateBlocks} from "./validate";
+
+export interface ParseBlocksPartialResult {
+  blocks: unknown[];
+  datasets?: Record<string, unknown>;
+  pending: boolean;
+}
+
+const emptyPending = (): ParseBlocksPartialResult => ({blocks: [], pending: true});
+
+const isPlainMapping = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.getPrototypeOf(value) === Object.prototype;
+};
+
+const datasetsFrom = (value: unknown): Record<string, unknown> | undefined => {
+  if (!isPlainMapping(value) || !isPlainMapping(value.datasets)) {
+    return undefined;
+  }
+  return value.datasets;
+};
+
+const blocksFrom = (value: unknown): unknown[] | undefined => {
+  if (!isPlainMapping(value) || !Array.isArray(value.blocks)) {
+    return undefined;
+  }
+  return value.blocks;
+};
+
+/**
+ * Top-level block items are the lines indented exactly two spaces that start a sequence entry.
+ * Nested lists sit deeper, so they stay inside the current item.
+ */
+const topLevelItems = (body: string): string[] => {
+  const items: string[] = [];
+  let current: string[] | null = null;
+  for (const line of body.split("\n")) {
+    if (line.startsWith("  - ")) {
+      if (current !== null) {
+        items.push(current.join("\n"));
+      }
+      current = [line];
+      continue;
+    }
+    if (current !== null) {
+      current.push(line);
+    }
+  }
+  if (current !== null) {
+    items.push(current.join("\n"));
+  }
+  return items;
+};
+
+const blockFromItem = (item: string): unknown | undefined => {
+  const parsed = parseBlocks(`v: 1\nblocks:\n${item}\n`);
+  if (!parsed.ok) {
+    return undefined;
+  }
+  const blocks = blocksFrom(parsed.value);
+  return blocks?.[0];
+};
+
+/**
+ * Reads a truncated reply while it is still streaming.
+ * A finished, valid document returns every block with `pending: false`.
+ * A cut reply returns only the top-level blocks that already ended (the next `- ` arrived)
+ * and sets `pending: true`. It never throws.
+ */
+export const parseBlocksPartial = (text: string): ParseBlocksPartialResult => {
+  try {
+    const stripped = stripBlocksFence(text);
+    if (stripped.trim() === "") {
+      return emptyPending();
+    }
+    const parsed = parseBlocks(stripped);
+    if (parsed.ok) {
+      const blocks = blocksFrom(parsed.value);
+      if (blocks !== undefined && validateBlocks(parsed.value).ok) {
+        return {
+          blocks,
+          datasets: datasetsFrom(parsed.value),
+          pending: false,
+        };
+      }
+    }
+
+    const lines = stripped.split("\n");
+    const blocksLine = lines.findIndex((line) => line === "blocks:" || line.startsWith("blocks: "));
+    if (blocksLine < 0) {
+      return emptyPending();
+    }
+
+    const prefix = lines.slice(0, blocksLine).join("\n");
+    let datasets: Record<string, unknown> | undefined;
+    if (prefix.includes("datasets:")) {
+      const closed = parseBlocks(`${prefix}\nblocks:\n  - type: divider\n`);
+      if (closed.ok) {
+        datasets = datasetsFrom(closed.value);
+      }
+    }
+
+    const items = topLevelItems(lines.slice(blocksLine + 1).join("\n"));
+    const completeItems = items.slice(0, -1);
+    const blocks = completeItems.flatMap((item) => {
+      const block = blockFromItem(item);
+      return block === undefined ? [] : [block];
+    });
+    return {blocks, datasets, pending: true};
+  } catch {
+    return emptyPending();
+  }
+};

package/src/prompt.test.ts

@@ -0,0 +1,24 @@
+import {describe, expect, it} from "bun:test";
+
+import {BLOCK_LIMITS} from "./limits";
+import {blocksPromptSection} from "./prompt";
+
+describe("blocksPromptSection", () => {
+  it("embeds the reply rule, the ref rule, both examples, and every limit", () => {
+    const section = blocksPromptSection({hostActions: ["exportDataset"]});
+    expect(section).toContain(
+      "Your entire reply is one document; no prose outside it; no text before tool calls."
+    );
+    expect(section).toContain("Use the datasetId a tool returned; never paste more than 500 rows.");
+    expect(section).toContain("exportDataset");
+    expect(section).toContain("Show weekly signups for this quarter");
+    expect(section).toContain("I could not find any signups for that range.");
+    for (const value of Object.values(BLOCK_LIMITS)) {
+      expect(section).toContain(String(value));
+    }
+  });
+
+  it("says no callbacks are registered when the host passes none", () => {
+    expect(blocksPromptSection()).toContain("No callback names are registered.");
+  });
+});

package/src/prompt.ts

@@ -0,0 +1,104 @@
+import {BLOCK_LIMITS} from "./limits";
+
+const DATA_EXAMPLE = `v: 1
+datasets:
+  signups:
+    columns:
+      - name: month
+        type: string
+      - name: count
+        type: number
+    rows:
+      - [Jan, 120]
+      - [Feb, 180]
+blocks:
+  - type: chart
+    id: signups_chart
+    kind: bar
+    data: signups
+    x: month
+    y: count
+    title: Signups by month
+  - type: actions
+    id: followups
+    elements:
+      - type: button
+        id: weekly
+        text: Show weekly
+        action:
+          kind: reply
+          text: Show weekly signups for this quarter`;
+
+const PROSE_EXAMPLE = `v: 1
+blocks:
+  - type: text
+    markdown: I could not find any signups for that range. Try a wider date window.`;
+
+/**
+ * The system-prompt section a host prepends when a reply must be one block document.
+ * Every cap is read from `BLOCK_LIMITS` so the prompt, the schema, and the reference stay aligned.
+ */
+export const blocksPromptSection = ({
+  allowHtml = false,
+  hostActions = [],
+  imageHosts = [],
+}: {
+  allowHtml?: boolean;
+  hostActions?: readonly string[];
+  imageHosts?: readonly string[];
+} = {}): string => {
+  const callbacks =
+    hostActions.length === 0
+      ? "No callback names are registered. Do not emit kind callback."
+      : `A callback name must be one of: ${hostActions.join(", ")}.`;
+  const imageHostsLine =
+    imageHosts.length === 0
+      ? "Do not emit an https image src. Use a data:image URL or a file: ref."
+      : `An https image src must use one of these hosts: ${imageHosts.join(", ")}.`;
+  return [
+    "Your entire reply is one document; no prose outside it; no text before tool calls.",
+    "The document is YAML or JSON. Keys, when present, are in this order: v, datasets, blocks.",
+    "v is 1.",
+    allowHtml
+      ? "Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, html, callout, image, details."
+      : "Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, callout, image, details. Do not emit type html.",
+    `An html field is at most ${BLOCK_LIMITS.htmlMaxBytes} bytes.`,
+    ...(allowHtml
+      ? [
+          "html requires html and may set title and height (sm, md, or lg). It is a display preview: no scripts, no links, no network.",
+        ]
+      : []),
+    "callout requires text and may set status to info, warning, or alert.",
+    "image requires alt and src. src is a data:image URL, a file: ref, or an https URL on an allowed host.",
+    imageHostsLine,
+    "details requires title and text.",
+    "heading requires text. text requires markdown. metric requires label and value. badge requires text. context requires text.",
+    "chart kind is line, bar, area, or donut. Bind it with data, x, and y, or with points of label and value.",
+    "table requires data, the name of a dataset. actions requires id and elements.",
+    "An element is a button (id, text, action) or a segmented control (id, target, options of label and data).",
+    "action.kind is reply (text), open (url or route, exactly one), select (target and data), or callback (name and optional payload).",
+    "columns has 2 to 4 children. card has children and an optional title. Do not nest columns or card inside columns or card.",
+    `At most ${BLOCK_LIMITS.maxBlocks} blocks, including nested blocks.`,
+    `Depth is at most ${BLOCK_LIMITS.maxDepth}.`,
+    `An actions block has at most ${BLOCK_LIMITS.actionElementsMax} elements.`,
+    `columns has ${BLOCK_LIMITS.columnsMin} to ${BLOCK_LIMITS.columnsMax} children.`,
+    `At most ${BLOCK_LIMITS.maxDatasets} datasets.`,
+    `An inline dataset has at most ${BLOCK_LIMITS.datasetRowMax} rows and ${BLOCK_LIMITS.datasetColumnMax} columns.`,
+    `A ref dataset limit is at most ${BLOCK_LIMITS.refLimitMax}.`,
+    `A text block has at most ${BLOCK_LIMITS.blockTextMaxLength} characters.`,
+    `A document has at most ${BLOCK_LIMITS.documentTextMaxLength} characters of text.`,
+    `Heading text is at most ${BLOCK_LIMITS.headingTextMaxLength} characters.`,
+    `Badge text is at most ${BLOCK_LIMITS.badgeTextMaxLength} characters.`,
+    `Context text is at most ${BLOCK_LIMITS.contextTextMaxLength} characters.`,
+    `A card title is at most ${BLOCK_LIMITS.cardTitleMaxLength} characters.`,
+    `A metric label is at most ${BLOCK_LIMITS.metricLabelMaxLength} characters, its value ${BLOCK_LIMITS.metricValueMaxLength}, its delta ${BLOCK_LIMITS.metricDeltaMaxLength}, and its helper ${BLOCK_LIMITS.metricHelperMaxLength}.`,
+    `A bar chart warns above ${BLOCK_LIMITS.barCategoryWarning} categories.`,
+    `A donut chart warns above ${BLOCK_LIMITS.donutSliceWarning} slices.`,
+    "Use the datasetId a tool returned; never paste more than 500 rows.",
+    callbacks,
+    "Example with data:",
+    DATA_EXAMPLE,
+    "Example with prose only:",
+    PROSE_EXAMPLE,
+  ].join("\n");
+};