@terreno/blocks 57.12.0 → 57.13.0

package/src/prompt.test.ts

@@ -3,9 +3,49 @@ import {describe, expect, it} from "bun:test";
 import {BLOCK_LIMITS} from "./limits";
 import {blocksPromptSection} from "./prompt";
 
+/**
+ * The option sets the prompt took before rich blocks existed. Their snapshots were written by
+ * the pre-rich-blocks prompt, so `richBlocks: false` must keep reproducing them byte for byte.
+ */
+const LEGACY_OPTION_SETS = {
+  allowHtml: {allowHtml: true},
+  everything: {
+    allowHtml: true,
+    hostActions: ["approve", "scaleStepper"],
+    imageHosts: ["cdn.example.com"],
+  },
+  hostActions: {hostActions: ["exportDataset"]},
+  imageHosts: {imageHosts: ["cdn.example.com"]},
+  none: {},
+} as const;
+
+const STEPPER_LINE_START = "stepper requires";
+const CHECKLIST_LINE_START = "checklist requires";
+const GALLERY_LINE_START = "gallery requires";
+const LIST_LINE_START = "list requires";
+const COPY_LINE_START = "action.kind may also be copy";
+
+/** Every option that changes the rich prompt, so the full on-case snapshot catches any drift. */
+const FULL_RICH_OPTIONS = {
+  checklistActions: ["toggleChecklist"],
+  hostActions: ["approve", "scaleStepper", "toggleChecklist"],
+  imageHosts: ["images.example.com"],
+  stepperActions: ["scaleStepper"],
+} as const;
+/** Matches the list block by word, so checklist lines do not count. */
+const LIST_WORD = /\blist\b/;
+
+const linesAdded = (section: string, base: string): string[] => {
+  const baseLines = new Set(base.split("\n"));
+  return section.split("\n").filter((line) => !baseLines.has(line));
+};
+
 describe("blocksPromptSection", () => {
   it("embeds the reply rule, the ref rule, both examples, and every limit", () => {
-    const section = blocksPromptSection({hostActions: ["exportDataset"]});
+    const section = blocksPromptSection({
+      hostActions: ["exportDataset", "scaleStepper"],
+      stepperActions: ["scaleStepper"],
+    });
     expect(section).toContain(
       "Your entire reply is one document; no prose outside it; no text before tool calls."
     );
@@ -13,7 +53,7 @@ describe("blocksPromptSection", () => {
     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)) {
+    for (const [, value] of Object.entries(BLOCK_LIMITS)) {
       expect(section).toContain(String(value));
     }
   });
@@ -21,4 +61,287 @@ describe("blocksPromptSection", () => {
   it("says no callbacks are registered when the host passes none", () => {
     expect(blocksPromptSection()).toContain("No callback names are registered.");
   });
+
+  describe("with richBlocks false", () => {
+    for (const [name, options] of Object.entries(LEGACY_OPTION_SETS)) {
+      it(`matches the pre-rich-blocks prompt for ${name}, even with stepper and checklist actions`, () => {
+        const section = blocksPromptSection({
+          ...options,
+          checklistActions: ["toggleChecklist"],
+          richBlocks: false,
+          stepperActions: ["scaleStepper"],
+        });
+        expect(section).toMatchSnapshot();
+        expect(section).not.toContain("stepper");
+        expect(section).not.toContain("checklist");
+        expect(section).not.toContain("gallery");
+        expect(section).not.toMatch(LIST_WORD);
+      });
+    }
+  });
+
+  describe("the stepper line", () => {
+    it("is on by default when the host registers a stepper action", () => {
+      const section = blocksPromptSection({
+        hostActions: ["scaleStepper"],
+        stepperActions: ["scaleStepper"],
+      });
+      expect(section).toContain(STEPPER_LINE_START);
+      expect(section).toBe(
+        blocksPromptSection({
+          hostActions: ["scaleStepper"],
+          richBlocks: true,
+          stepperActions: ["scaleStepper"],
+        })
+      );
+    });
+
+    it("never mentions stepper without a stepper action", () => {
+      expect(blocksPromptSection({hostActions: ["scaleStepper"]})).not.toContain("stepper");
+      expect(
+        blocksPromptSection({hostActions: ["scaleStepper"], stepperActions: []})
+      ).not.toContain("stepper");
+    });
+
+    it("lists stepper as a block type and names every stepper action as its callback", () => {
+      const section = blocksPromptSection({
+        hostActions: ["approve", "scaleStepper", "scalePortions"],
+        stepperActions: ["scaleStepper", "scalePortions"],
+      });
+      const typesLine = section.split("\n").find((line) => line.startsWith("Block types:"));
+      expect(typesLine).toContain(", stepper");
+      expect(section).toContain(
+        "A stepper callback name must be one of: scaleStepper, scalePortions."
+      );
+      expect(section).toContain(
+        "A callback name must be one of: approve, scaleStepper, scalePortions."
+      );
+    });
+
+    it("prints every stepper limit from BLOCK_LIMITS", () => {
+      const withStepper = blocksPromptSection({stepperActions: ["scaleStepper"]});
+      const without = blocksPromptSection();
+      const added = withStepper
+        .split("\n")
+        .filter((line) => !without.split("\n").includes(line))
+        .join("\n");
+      const stepperLimits = Object.entries(BLOCK_LIMITS).filter(([key]) =>
+        key.startsWith("stepper")
+      );
+      expect(stepperLimits.length).toBeGreaterThan(0);
+      for (const [, value] of stepperLimits) {
+        expect(added).toContain(String(value));
+      }
+    });
+  });
+
+  describe("the checklist line", () => {
+    it("is on by default and lists checklist as a block type", () => {
+      const section = blocksPromptSection();
+      expect(section).toContain(CHECKLIST_LINE_START);
+      expect(section).toBe(blocksPromptSection({richBlocks: true}));
+      const typesLine = section.split("\n").find((line) => line.startsWith("Block types:"));
+      expect(typesLine).toContain(", checklist");
+      const allowHtmlTypes = blocksPromptSection({allowHtml: true})
+        .split("\n")
+        .find((line) => line.startsWith("Block types:"));
+      expect(allowHtmlTypes).toContain(", checklist");
+    });
+
+    it("tells the model to leave callback out when no checklist action is registered", () => {
+      const section = blocksPromptSection({hostActions: ["toggleChecklist"]});
+      const added = linesAdded(
+        section,
+        blocksPromptSection({hostActions: ["toggleChecklist"], richBlocks: false})
+      );
+      const callbackLine = added.find(
+        (line) => line.includes("checklist") && line.includes("callback")
+      );
+      expect(callbackLine).toContain("Leave callback out of a checklist");
+      expect(added.join("\n")).not.toContain("toggleChecklist");
+      expect(blocksPromptSection({checklistActions: []})).toBe(blocksPromptSection());
+    });
+
+    it("names every checklist action as the callback to set when the host registers them", () => {
+      const section = blocksPromptSection({
+        checklistActions: ["toggleChecklist", "recordProgress"],
+        hostActions: ["approve", "toggleChecklist", "recordProgress"],
+      });
+      expect(section).toContain(
+        "Set a checklist callback name to one of: toggleChecklist, recordProgress."
+      );
+      expect(section).not.toContain("Leave callback out of a checklist");
+      expect(section).not.toContain("stepper");
+    });
+
+    it("prints every checklist limit from BLOCK_LIMITS in the lines it adds", () => {
+      const added = linesAdded(
+        blocksPromptSection(),
+        blocksPromptSection({richBlocks: false})
+      ).join("\n");
+      const checklistLimits = Object.entries(BLOCK_LIMITS).filter(([key]) =>
+        key.startsWith("checklist")
+      );
+      expect(checklistLimits.length).toBeGreaterThan(0);
+      for (const [, value] of checklistLimits) {
+        expect(added).toContain(String(value));
+      }
+    });
+  });
+
+  describe("the gallery line", () => {
+    it("is on by default and lists gallery as a block type", () => {
+      const section = blocksPromptSection();
+      expect(section).toContain(GALLERY_LINE_START);
+      for (const allowHtml of [false, true]) {
+        const typesLine = blocksPromptSection({allowHtml})
+          .split("\n")
+          .find((line) => line.startsWith("Block types:"));
+        expect(typesLine).toContain(", gallery");
+      }
+    });
+
+    it("sends gallery srcs to the image rules and keeps the https rule tied to imageHosts", () => {
+      const withoutHosts = linesAdded(
+        blocksPromptSection(),
+        blocksPromptSection({richBlocks: false})
+      )
+        .filter((line) => line.includes("gallery"))
+        .join("\n");
+      expect(withoutHosts).toContain("image src rules");
+      expect(withoutHosts).not.toContain("https");
+      const withHosts = blocksPromptSection({imageHosts: ["cdn.example.com"]});
+      expect(withHosts).toContain(
+        "An https image src must use one of these hosts: cdn.example.com."
+      );
+      expect(blocksPromptSection()).toContain(
+        "Do not emit an https image src. Use a data:image URL or a file: ref."
+      );
+    });
+
+    it("prints every gallery limit from BLOCK_LIMITS in the gallery lines", () => {
+      const galleryLines = linesAdded(
+        blocksPromptSection(),
+        blocksPromptSection({richBlocks: false})
+      )
+        .filter((line) => line.includes("gallery"))
+        .join("\n");
+      const galleryLimits = Object.entries(BLOCK_LIMITS).filter(([key]) =>
+        key.startsWith("gallery")
+      );
+      expect(galleryLimits.length).toBe(4);
+      for (const [, value] of galleryLimits) {
+        expect(galleryLines).toContain(String(value));
+      }
+    });
+  });
+
+  describe("the list line", () => {
+    const listLines = (): string =>
+      linesAdded(blocksPromptSection(), blocksPromptSection({richBlocks: false}))
+        .filter((line) => LIST_WORD.test(line))
+        .join("\n");
+
+    it("is on by default and lists list as a block type", () => {
+      expect(blocksPromptSection()).toContain(LIST_LINE_START);
+      for (const allowHtml of [false, true]) {
+        const typesLine = blocksPromptSection({allowHtml})
+          .split("\n")
+          .find((line) => line.startsWith("Block types:"));
+        expect(typesLine).toMatch(/, gallery, list[.,]/);
+      }
+    });
+
+    it("names the list block only in its own lines, never as a generic word", () => {
+      const section = blocksPromptSection({
+        checklistActions: ["toggleChecklist"],
+        stepperActions: ["scaleStepper"],
+      });
+      const mentions = section.split("\n").filter((line) => LIST_WORD.test(line));
+      expect(mentions.length).toBe(4);
+      expect(mentions[0]).toStartWith("Block types:");
+      expect(mentions[1]).toStartWith(LIST_LINE_START);
+      expect(mentions[2]).toStartWith("A list item");
+      expect(mentions[3]).toStartWith(COPY_LINE_START);
+    });
+
+    it("sends item image srcs to the image rules and keeps the https rule tied to imageHosts", () => {
+      const lines = listLines();
+      expect(lines).toContain("image src rules");
+      expect(lines).toContain("plain text");
+      expect(lines).not.toContain("https");
+    });
+
+    it("prints every list limit from BLOCK_LIMITS and the image block's alt limit", () => {
+      const lines = listLines();
+      const listLimits = Object.entries(BLOCK_LIMITS).filter(([key]) => key.startsWith("list"));
+      expect(listLimits.length).toBe(5);
+      for (const [, value] of listLimits) {
+        expect(lines).toContain(String(value));
+      }
+      expect(lines).toContain(`image alt ${BLOCK_LIMITS.headingTextMaxLength}`);
+    });
+  });
+
+  describe("the card eyebrow line", () => {
+    const eyebrowLines = (): string[] =>
+      linesAdded(blocksPromptSection(), blocksPromptSection({richBlocks: false})).filter((line) =>
+        line.includes("eyebrow")
+      );
+
+    it("is offered by default with its limit from BLOCK_LIMITS", () => {
+      const lines = eyebrowLines();
+      expect(lines.length).toBeGreaterThan(0);
+      expect(lines.join("\n")).toContain(`at most ${BLOCK_LIMITS.cardEyebrowMaxLength}`);
+      expect(BLOCK_LIMITS.cardEyebrowMaxLength).toBe(60);
+    });
+
+    it("is absent when richBlocks is false", () => {
+      expect(blocksPromptSection({richBlocks: false})).not.toContain("eyebrow");
+      expect(blocksPromptSection({allowHtml: true, richBlocks: false})).not.toContain("eyebrow");
+    });
+  });
+
+  describe("the copy line", () => {
+    const copyLines = (options: Parameters<typeof blocksPromptSection>[0] = {}): string[] =>
+      linesAdded(
+        blocksPromptSection(options),
+        blocksPromptSection({...options, richBlocks: false})
+      ).filter((line) => line.includes("copy"));
+
+    it("is one line, on by default, with the copy text limit from BLOCK_LIMITS", () => {
+      const lines = copyLines();
+      expect(lines.length).toBe(1);
+      expect(lines[0]).toStartWith(COPY_LINE_START);
+      expect(lines[0]).toContain("exactly one of text");
+      expect(lines[0]).toContain(`at most ${BLOCK_LIMITS.copyTextMaxLength} characters`);
+      expect(lines[0]).toContain("never reaches the host");
+    });
+
+    it("names stepper as a copy target only when the stepper is offered", () => {
+      expect(copyLines()[0]).toContain("a checklist, list, table, or text block");
+      expect(copyLines()[0]).not.toContain("stepper");
+      expect(copyLines({stepperActions: ["scaleStepper"]})[0]).toContain(
+        "a stepper, checklist, list, table, or text block"
+      );
+    });
+
+    it("is absent when richBlocks is false", () => {
+      for (const allowHtml of [false, true]) {
+        expect(blocksPromptSection({allowHtml, richBlocks: false})).not.toContain("copy");
+      }
+    });
+  });
+
+  describe("with richBlocks on", () => {
+    it("matches the full rich-blocks prompt with stepper and checklist actions", () => {
+      const section = blocksPromptSection(FULL_RICH_OPTIONS);
+      expect(section).toBe(blocksPromptSection({...FULL_RICH_OPTIONS, richBlocks: true}));
+      expect(section).toMatchSnapshot();
+    });
+
+    it("matches the full rich-blocks prompt with html allowed", () => {
+      expect(blocksPromptSection({...FULL_RICH_OPTIONS, allowHtml: true})).toMatchSnapshot();
+    });
+  });
 });

package/src/prompt.ts

@@ -1,4 +1,5 @@
 import {BLOCK_LIMITS} from "./limits";
+import {COPY_TARGET_TYPES} from "./schema";
 
 const DATA_EXAMPLE = `v: 1
 datasets:
@@ -34,19 +35,97 @@ blocks:
   - type: text
     markdown: I could not find any signups for that range. Try a wider date window.`;
 
+/**
+ * Stepper instructions, offered only when the host registers an action that handles steppers,
+ * so the model never writes a stepper whose buttons would do nothing.
+ */
+const stepperPromptLines = (stepperActions: readonly string[]): string[] => [
+  "stepper requires id, label, value, min, max, and callback (name and optional payload). It may set step (above 0, default 1), unit, itemsTitle, items, and note. min is below max, and value is between them.",
+  "Its decrease and increase buttons send the callback with payload.value set to the next value. The host returns the updated stepper, so write item amounts for the starting value.",
+  `A stepper callback name must be one of: ${stepperActions.join(", ")}.`,
+  "A stepper item requires label and amount. It may set unit, decimals, and round (nearest or up).",
+  `A stepper id is at most ${BLOCK_LIMITS.stepperIdMaxLength} characters. No other id may be <id>_decrease or <id>_increase.`,
+  `A stepper label and itemsTitle are at most ${BLOCK_LIMITS.stepperLabelMaxLength} characters, its unit ${BLOCK_LIMITS.stepperUnitMaxLength}, and its note ${BLOCK_LIMITS.stepperNoteMaxLength}.`,
+  `A stepper has at most ${BLOCK_LIMITS.stepperItemsMax} items. An item label is at most ${BLOCK_LIMITS.stepperLabelMaxLength} characters, its unit ${BLOCK_LIMITS.stepperItemUnitMaxLength}, and decimals is 0 to ${BLOCK_LIMITS.stepperDecimalsMax}.`,
+];
+
+/**
+ * Checklist instructions, offered with rich blocks. A tick only reaches the host through a
+ * checklist action, so without one the model is told to leave callback out and ticks stay local.
+ */
+const checklistPromptLines = (checklistActions: readonly string[]): string[] => [
+  "checklist requires id and items, and may set title. It shows a done count such as 2 of 8.",
+  "A checklist item requires id and text. It may set meta (a short label such as a time, shown under the text), detail (a muted line under that), and checked (true or false).",
+  checklistActions.length === 0
+    ? "Leave callback out of a checklist. Ticks stay on the device."
+    : `Set a checklist callback name to one of: ${checklistActions.join(", ")}. Its payload is optional. Each tick sends the callback with payload.itemId, payload.checked, and payload.state, and the host returns the updated checklist.`,
+  `A checklist id is at most ${BLOCK_LIMITS.checklistIdMaxLength} characters and an item id ${BLOCK_LIMITS.checklistItemIdMaxLength}. Item ids are unique in the checklist, and no other id may be <id>_<item id>.`,
+  `A checklist has ${BLOCK_LIMITS.checklistItemsMin} to ${BLOCK_LIMITS.checklistItemsMax} items. Its title is at most ${BLOCK_LIMITS.checklistTitleMaxLength} characters, an item text ${BLOCK_LIMITS.checklistItemTextMaxLength}, an item meta ${BLOCK_LIMITS.checklistItemMetaMaxLength}, and an item detail ${BLOCK_LIMITS.checklistItemDetailMaxLength}.`,
+];
+
+/**
+ * Gallery instructions, offered with rich blocks. Tile srcs defer to the image src rules so the
+ * https guidance stays in the one line that knows the host's imageHosts.
+ */
+const galleryPromptLines = (): string[] => [
+  `gallery requires images: ${BLOCK_LIMITS.galleryImagesMin} to ${BLOCK_LIMITS.galleryImagesMax} photos shown together. Each image requires src and alt, and may set caption. Each src follows the image src rules above.`,
+  `A gallery image alt is at most ${BLOCK_LIMITS.galleryAltMaxLength} characters and its caption ${BLOCK_LIMITS.galleryCaptionMaxLength}.`,
+];
+
+/** Card eyebrow instruction, offered with rich blocks. */
+const cardEyebrowPromptLines = (): string[] => [
+  `A card may set eyebrow, a short label shown small above its title. An eyebrow is at most ${BLOCK_LIMITS.cardEyebrowMaxLength} characters.`,
+];
+
+/**
+ * List instructions, offered with rich blocks. The word "list" names only this block in the
+ * prompt, so the model never reads it as a generic instruction. Item image srcs defer to the
+ * image src rules, and the alt cap is the image block's.
+ */
+const listPromptLines = (): string[] => [
+  `list requires items: ${BLOCK_LIMITS.listItemsMin} to ${BLOCK_LIMITS.listItemsMax} entries stacked one under another. Each item requires title, and may set text (plain text, not markdown), meta (a short label such as a time or a price), and image (src and alt, a thumbnail). Each image src follows the image src rules above.`,
+  `A list item title is at most ${BLOCK_LIMITS.listItemTitleMaxLength} characters, its text ${BLOCK_LIMITS.listItemTextMaxLength}, its meta ${BLOCK_LIMITS.listItemMetaMaxLength}, and its image alt ${BLOCK_LIMITS.headingTextMaxLength}.`,
+];
+
+/**
+ * Copy action instruction, offered with rich blocks. The stepper is named as a target only when
+ * the prompt offers it, so the prompt never mentions a stepper without a stepper action.
+ */
+const copyPromptLine = (offersStepper: boolean): string => {
+  const targets = COPY_TARGET_TYPES.filter((type) => offersStepper || type !== "stepper");
+  const named = `${targets.slice(0, -1).join(", ")}, or ${targets.at(-1)}`;
+  return `action.kind may also be copy: it copies to the clipboard on the device and never reaches the host. A copy action sets exactly one of text (at most ${BLOCK_LIMITS.copyTextMaxLength} characters, copied as written) or target (the id of a ${named} block in this document, whose current contents are copied).`;
+};
+
 /**
  * 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.
+ * `richBlocks: false` keeps the prompt as it was before rich blocks, for clients that cannot
+ * render them yet. The stepper is offered only with a `stepperActions` entry, and the checklist
+ * names its callback only with a `checklistActions` entry.
  */
 export const blocksPromptSection = ({
   allowHtml = false,
+  checklistActions = [],
   hostActions = [],
   imageHosts = [],
+  richBlocks = true,
+  stepperActions = [],
 }: {
   allowHtml?: boolean;
+  /** Host actions a checklist callback may name. Empty or omitted means ticks stay local. */
+  checklistActions?: readonly string[];
   hostActions?: readonly string[];
   imageHosts?: readonly string[];
+  /** Default `true`. `false` leaves every rich block out of the prompt. */
+  richBlocks?: boolean;
+  /** Host actions that handle a stepper. Without one, the prompt never mentions stepper. */
+  stepperActions?: readonly string[];
 } = {}): string => {
+  const offersStepper = richBlocks && stepperActions.length > 0;
+  const richTypes = richBlocks
+    ? `${offersStepper ? ", stepper" : ""}, checklist, gallery, list`
+    : "";
   const callbacks =
     hostActions.length === 0
       ? "No callback names are registered. Do not emit kind callback."
@@ -60,8 +139,8 @@ export const blocksPromptSection = ({
     "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.",
+      ? `Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, html, callout, image, details${richTypes}.`
+      : `Block types: heading, text, metric, badge, divider, context, chart, table, actions, columns, card, callout, image, details${richTypes}. Do not emit type html.`,
     `An html field is at most ${BLOCK_LIMITS.htmlMaxBytes} bytes.`,
     ...(allowHtml
       ? [
@@ -72,11 +151,17 @@ export const blocksPromptSection = ({
     "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.",
+    ...(offersStepper ? stepperPromptLines(stepperActions) : []),
+    ...(richBlocks ? checklistPromptLines(checklistActions) : []),
+    ...(richBlocks ? galleryPromptLines() : []),
+    ...(richBlocks ? listPromptLines() : []),
+    ...(richBlocks ? cardEyebrowPromptLines() : []),
     "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).",
+    ...(richBlocks ? [copyPromptLine(offersStepper)] : []),
     "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}.`,