@jigs.design/prompt 0.1.2 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Renders the text the model reads: the system prompt from a host, and the repair text from diagnostics. `@jigs.design/server` uses it; you import it to read or test the prompt a host produces.
 
-The system prompt carries the app's `instructions`, then lists the host's procedures, components and recipes, and ends with the host's design guidance (`## Design`: shared, then the mode's) and situations (`## Situations`: how to choose, then each with its When line, guidance and example). It writes each procedure's input and output out as types, with each field's `.describe()` text and constraints as a comment, and shared enums declared once. It has two modes: `document`, where the whole reply is one UI, and `chat`, where the reply is Markdown with fenced `jigs` blocks.
+The system prompt opens with the output rules and the language, then the host's types, components and tags (`## App tags`, tag jigs only), its design guidance (`## Design`: shared, then the mode's) and situations (`## Situations`: how to choose, then each with its When line, guidance and example); after that come the app's `instructions`, the host's data types, procedures and image hosts, the part of the prompt that may change between turns. It writes each procedure's input and output out as types, with each field's `.describe()` text and constraints as a comment, and shared enums declared once. It has two modes: `document`, where the whole reply is one UI, and `chat`, where the reply is Markdown with fenced `jigs` blocks.
 
 ## Exports
 
@@ -10,7 +10,7 @@ The system prompt carries the app's `instructions`, then lists the host's proced
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `systemPrompt`              | The system prompt for a host: `{ mode, instructions }`                                                                        |
 | `needsRepair`, `repairText` | Whether diagnostics call for a repair round, and the message that asks for it, with any design advice the app chose to repair |
-| `editRepairText`            | Asks for corrected edit blocks when an edit did not apply, naming why: missing, ambiguous, malformed or broken                |
+| `editRepairText`            | Asks for corrected edit blocks when an edit did not apply, naming why: missing, ambiguous, overlapping, malformed or broken   |
 | `fullDocumentText`          | Asks for the whole document when a second edit did not apply either                                                           |
 | `typeText`                  | A Zod schema as the TypeScript-like type the prompt shows                                                                     |
 

package/dist/document.d.ts

@@ -0,0 +1,12 @@
+//#region src/document.d.ts
+/**
+ * The last user message of a turn about a document: the current UI, then
+ * the ask. The server sends it in place of the ask, on every model call, so
+ * the UI is the last thing before the request and never in `system`.
+ */
+export declare function withDocument(ask: string, source: string): string;
+/** The ask of a message `withDocument` built, or the message itself. */
+export declare function askOf(content: string): string;
+/** The document of a message `withDocument` built, or null for any other message. */
+export declare function documentOf(content: string): string | null;
+//#endregion

package/dist/document.js

@@ -0,0 +1,35 @@
+//#region src/document.ts
+const DOCUMENT_MARK = "The current UI, which your reply changes or replaces:";
+const ASK_MARK = "The request:";
+const DOCUMENT_START = `${DOCUMENT_MARK}\n\n`;
+const ASK_START = `\n\n${ASK_MARK}\n\n`;
+/**
+* The last user message of a turn about a document: the current UI, then
+* the ask. The server sends it in place of the ask, on every model call, so
+* the UI is the last thing before the request and never in `system`.
+*/
+function withDocument(ask, source) {
+	return `${DOCUMENT_START}${source}${ASK_START}${ask}`;
+}
+/**
+* Where the ask starts in a message `withDocument` built, or null for any
+* other message. The first ask mark after the document ends it, so an ask
+* may contain the marks; a document that contains one is read short.
+*/
+function askStart(content) {
+	if (!content.startsWith(DOCUMENT_START)) return null;
+	const index = content.indexOf(ASK_START, DOCUMENT_START.length - 2);
+	return index === -1 ? null : index;
+}
+/** The ask of a message `withDocument` built, or the message itself. */
+function askOf(content) {
+	const index = askStart(content);
+	return index === null ? content : content.slice(index + ASK_START.length);
+}
+/** The document of a message `withDocument` built, or null for any other message. */
+function documentOf(content) {
+	const index = askStart(content);
+	return index === null ? null : content.slice(DOCUMENT_START.length, Math.max(index, DOCUMENT_START.length));
+}
+//#endregion
+export { askOf, documentOf, withDocument };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
+import { askOf, documentOf, withDocument } from "./document.js";
 import { editRepairText, fullDocumentText, needsRepair, repairText } from "./repair.js";
 import { PromptMode, PromptOptions, SystemPromptParts, systemPrompt, systemPromptParts } from "./system-prompt.js";
 import { typeText } from "./types.js";
-export { type PromptMode, type PromptOptions, type SystemPromptParts, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText };
+export { type PromptMode, type PromptOptions, type SystemPromptParts, askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText, withDocument };

package/dist/index.js

@@ -1,4 +1,5 @@
+import { askOf, documentOf, withDocument } from "./document.js";
 import { editRepairText, fullDocumentText, needsRepair, repairText } from "./repair.js";
 import { typeText } from "./types.js";
 import { systemPrompt, systemPromptParts } from "./system-prompt.js";
-export { editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText };
+export { askOf, documentOf, editRepairText, fullDocumentText, needsRepair, repairText, systemPrompt, systemPromptParts, typeText, withDocument };

package/dist/repair.d.ts

@@ -1,4 +1,4 @@
-import { Diagnostic } from "@jigs.design/runtime";
+import { Diagnostic } from "@jigs.design/protocol";
 //#region src/repair.d.ts
 /** Whether a diagnostic is worth a repair round: something the compiler had to change. */
 export declare function needsRepair(diagnostics: ReadonlyArray<Diagnostic>): boolean;
@@ -8,11 +8,17 @@ interface RepairAdvice {
   span: Diagnostic["span"];
 }
 /**
- * The follow-up turn asking the model to fix the errors in its last answer,
- * and any design advice the app chose to repair. With advice alone, it says
+ * The follow-up turn asking the model to fix the errors in its UI, and any
+ * design advice the app chose to repair. With advice alone, it says
  * the Jigs works and asks for the design change.
  */
-export declare function repairText(diagnostics: ReadonlyArray<Diagnostic>, advice?: ReadonlyArray<RepairAdvice>): string;
+export declare function repairText(diagnostics: ReadonlyArray<Diagnostic>, advice?: ReadonlyArray<RepairAdvice>,
+/**
+ * What the line numbers count: the current UI the server shows with this
+ * message (a session), or the assistant's answer just before it (a chat
+ * block's repair, which shows no document).
+ */
+numbered?: "answer" | "shown"): string;
 /** An edit block that did not apply, as `applyEdits` and the server report it. */
 interface FailedEdit {
   /** For `broken`: the parser repairs the edited UI needs and the current one does not. */
@@ -24,14 +30,23 @@ interface FailedEdit {
     replace: string;
     search: string;
   };
-  /** For `ambiguous`: the line each match of the SEARCH starts on. */
+  /**
+   * For `ambiguous`: the line each match of the SEARCH starts on. For
+   * `overlapping`: the line the earlier edit's SEARCH starts on, then this one's.
+   */
   lines?: ReadonlyArray<number>;
+  /** For `overlapping`: the earlier edit whose lines this one also changes. */
+  overlaps?: {
+    replace: string;
+    search: string;
+  };
   /**
    * `missing`: SEARCH is not in the source; `ambiguous`: it is there more
-   * than once; `malformed`: the block has stray markers; `broken`: the
-   * edit left a tag unclosed or closed one twice.
+   * than once; `overlapping`: an earlier edit changes some of its lines;
+   * `malformed`: the block has stray markers; `broken`: the edit left a
+   * tag unclosed or closed one twice.
    */
-  reason: "ambiguous" | "broken" | "malformed" | "missing";
+  reason: "ambiguous" | "broken" | "malformed" | "missing" | "overlapping";
 }
 /**
  * Asks for corrected edit blocks after an edit did not apply. It names what

package/dist/repair.js

@@ -5,11 +5,11 @@ function needsRepair(diagnostics) {
 	return diagnostics.some((diagnostic) => diagnostic.severity === "error");
 }
 /**
-* The follow-up turn asking the model to fix the errors in its last answer,
-* and any design advice the app chose to repair. With advice alone, it says
+* The follow-up turn asking the model to fix the errors in its UI, and any
+* design advice the app chose to repair. With advice alone, it says
 * the Jigs works and asks for the design change.
 */
-function repairText(diagnostics, advice = []) {
+function repairText(diagnostics, advice = [], numbered = "shown") {
 	const seen = /* @__PURE__ */ new Set();
 	const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
 	const issues = [...errors, ...advice].filter((issue) => {
@@ -18,13 +18,14 @@ function repairText(diagnostics, advice = []) {
 		seen.add(key);
 		return true;
 	});
+	const where = numbered === "shown" ? "Line numbers refer to the current UI shown above." : "Line numbers refer to your last answer.";
 	const lines = issues.slice(0, MAX_ISSUES).map((issue) => `- Line ${issue.span.line}: ${issue.message}`);
 	if (issues.length > MAX_ISSUES) lines.push(`- ...and ${issues.length - MAX_ISSUES} more`);
-	if (errors.length === 0) return `Your jig works, but its design can be better. Line numbers refer to your last answer.
+	if (errors.length === 0) return `Your jig works, but its design can be better. ${where}
 ${lines.join("\n")}
 
 Change that and keep everything else as it is. Reply with edit blocks, or with the complete corrected Jigs if the change is large.`;
-	return `Your jig has problems. Line numbers refer to your last answer.
+	return `Your jig has problems. ${where}
 ${lines.join("\n")}
 
 Fix them and keep everything that already works. Reply with edit blocks, or with the complete corrected Jigs if the fix is large.`;
@@ -106,6 +107,12 @@ function failureParts(edit, source) {
 		case "malformed":
 			parts.push(`Your edit could not be applied: this edit block has an extra marker line inside it:\n${failed.search}`, `It was meant to become:\n${failed.replace}`);
 			return parts;
+		case "overlapping": {
+			const [first, second] = edit.lines ?? [];
+			const where = first === void 0 || second === void 0 ? "" : first === second ? ` (both start on line ${first})` : ` (lines ${first} and ${second})`;
+			parts.push(`Your edits could not be applied: these edits change the same lines of the current UI${where}. Each edit is matched against the current UI as shown, so one cannot change lines another one also changes.`, `The first edit replaced:\n${edit.overlaps?.search ?? ""}`, `The second edit replaced:\n${failed.search}`, `It was meant to become:\n${failed.replace}`);
+			return parts;
+		}
 		case "missing": {
 			parts.push(`Your edit could not be applied: this SEARCH text is not in the current UI:\n${failed.search}`, `It was meant to become:\n${failed.replace}`);
 			const closest = closestLines(source, failed.search);
@@ -118,7 +125,8 @@ const EDIT_ADVICE = {
 	ambiguous: "Reply with corrected edit blocks whose SEARCH includes enough of the surrounding lines to match only the place you mean",
 	broken: "Reply with corrected edit blocks that open and close every tag within the same block",
 	malformed: "Reply with corrected edit blocks, with one SEARCH, one divider and one REPLACE marker each",
-	missing: "Reply with corrected edit blocks whose SEARCH copies the current UI exactly, indentation included"
+	missing: "Reply with corrected edit blocks whose SEARCH copies the current UI exactly, indentation included",
+	overlapping: "Reply with corrected edit blocks that send one edit for that region, written against the current UI"
 };
 /**
 * Asks for corrected edit blocks after an edit did not apply. It names what

package/dist/system-prompt.d.ts

@@ -20,7 +20,7 @@ export interface PromptOptions {
  *
  * What stays the same from turn to turn comes first, so a provider can
  * cache it as a prefix: the output rules, the language, the catalog's
- * types and components, the recipes, the design guidance and situations.
+ * types and components, the app's tags, the design guidance and situations.
  * What a turn may change comes last: the app's `instructions`, the
  * procedures' own types, the queries, mutations and actions, and images. A
  * procedure enum the catalog already names keeps that name; the others are

package/dist/system-prompt.js

@@ -1,6 +1,6 @@
 import { enumKey, enumUses, objectUses, typeText } from "./types.js";
 import { sharedObjects, sharedTypes } from "./shared-types.js";
-import { recipeSignature } from "@jigs.design/compiler";
+import { jigSignature } from "@jigs.design/compiler";
 import { dataSchema } from "@jigs.design/host";
 //#region src/system-prompt.ts
 const JIGS = `Jigs is Markdown for prose, JSX-like tags for components from a fixed catalog, and \`{@body ...}\` lines of JavaScript for state and logic.`;
@@ -17,10 +17,12 @@ const DOCUMENT_OUTPUT = `You write interactive user interfaces in Jigs. ${JIGS}
 - Reply with Jigs only. No code fences, no explanation before or after it.
 
 ## Changing an existing UI
-When asked to change a UI you wrote earlier:
+When the request shows the current UI:
 - For a focused change, reply with edit blocks only, no other text:
 ${EDIT_BLOCK}
-- If the change rewrites most of the UI, reply with the complete updated Jigs instead.`;
+- If the change rewrites most of the UI, reply with the complete updated Jigs instead.
+- A complete reply includes every \`{@body}\` line it needs; the lines shown with the request are not kept unless you repeat them.
+- SEARCH lines come from the current UI shown with the request, not from an earlier reply.`;
 const OUTPUT = {
 	chat: `You reply in Markdown, and you can show interactive user interfaces in your replies by writing Jigs. ${JIGS}
 
@@ -33,7 +35,8 @@ const OUTPUT = {
 \`\`\`
 - Keep explanation outside the block, in Markdown. Do not repeat in prose what the UI shows.
 - You never see what a query returns: the UI reads it when it runs, after your reply. So your prose must not state figures, totals or conclusions about the user's data; say what the UI shows instead.
-- Tags, recipes and \`{@body}\` lines work only inside a block. Outside one, write plain Markdown: no tags, no HTML and no tool-call markup, which would show as text.
+- When the user's data would answer the ask, the block that reads it goes in this reply. Never reply with a promise to check, compare or look something up: there is no later turn to do it in.
+- Tags and \`{@body}\` lines work only inside a block. Outside one, write plain Markdown: no tags, no HTML and no tool-call markup, which would show as text.
 - A reply may hold several blocks, each with its own id. Each block is a separate UI: it cannot see another block's state.
 - Never put Jigs in any other fence, and never put a fence inside a block.
 
@@ -83,7 +86,7 @@ const HOOKS = `## Data and actions
 - After a mutation succeeds, the queries listed under "Refreshes" reload by themselves. Write nothing to make that happen.
 - An action listed below is called the same way, with \`useMutation("name")\` and \`mutate(input)\` in a handler. The page handles it instead of the server, for example by sending a message; its handle has the same \`status\`, \`data\` and \`error\`.
 - The first argument is always the name as a string literal. Never write \`useQuery({ queryKey, queryFn })\`.
-- Only use the queries and mutations listed below. Never invent data the user asked to see live.
+- Only use the queries and mutations listed below. When one returns data the ask needs, read it with \`useQuery\` and show what it returns. Never write those values into the UI yourself, not even as an example.
 - Inputs and data are TypeScript-like types. A \`//\` comment gives a field's meaning and limits; follow them when you build an input.`;
 const COMPONENTS_INTRO = `## Components
 Each prop is \`name: type = default\`, then what it does. Leave a prop out to get its default.
@@ -200,13 +203,13 @@ function actionSection(name, procedure, names) {
 		"Handled by the page, not the server. Refreshes nothing."
 	].join("\n");
 }
-const RECIPES_INTRO = `## Recipes
-Components written in Jigs for this app. Use them like any tag, with the props shown; a bare prop is required. They are already defined: never write their <define>. Prefer a recipe over building the same thing from components.`;
-function recipeSection(entry) {
-	const lines = [`### ${recipeSignature({
+const TAGS_INTRO = `## App tags
+Tags this app wrote in Jigs. Use them like any tag, with the props shown; a bare prop is required. They are already defined: never write their <define>. Prefer one over building the same thing from components. When one of them alone answers the ask, the UI is that one tag and nothing else.`;
+function tagSection(entry) {
+	const lines = [`### ${jigSignature({
 		name: entry.name,
 		source: entry.source
-	})}`, entry.description];
+	})}`, entry.description ?? ""];
 	if (entry.example !== void 0) lines.push(`Example: \`${entry.example}\``);
 	return lines.join("\n");
 }
@@ -286,7 +289,7 @@ function typesSection(heading, intro, declarations) {
 *
 * What stays the same from turn to turn comes first, so a provider can
 * cache it as a prefix: the output rules, the language, the catalog's
-* types and components, the recipes, the design guidance and situations.
+* types and components, the app's tags, the design guidance and situations.
 * What a turn may change comes last: the app's `instructions`, the
 * procedures' own types, the queries, mutations and actions, and images. A
 * procedure enum the catalog already names keeps that name; the others are
@@ -319,7 +322,8 @@ function systemPromptParts(host, options) {
 		...typesSection("## Types", "Named lists of values, used by the props below and by the data the queries return.", catalogTypes.declarations),
 		[COMPONENTS_INTRO, ...componentSections(host.components.components, catalogTypes.names)].join("\n\n")
 	];
-	if (host.recipes.length > 0) sections.push([RECIPES_INTRO, ...host.recipes.map((entry) => recipeSection(entry))].join("\n\n"));
+	const tags = host.jigs.filter((entry) => entry.tag);
+	if (tags.length > 0) sections.push([TAGS_INTRO, ...tags.map((entry) => tagSection(entry))].join("\n\n"));
 	const design = designText(host, mode);
 	if (design !== "") sections.push(`## Design\n${design}`);
 	if (host.situations.length > 0) sections.push([SITUATIONS_INTRO, ...host.situations.map((entry) => situationSection(entry))].join("\n\n"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/prompt",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "The system prompt and the repair text, rendered from a host and from diagnostics.",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/compiler": "0.1.2",
-    "@jigs.design/host": "0.1.2",
-    "@jigs.design/runtime": "0.1.2"
+    "@jigs.design/compiler": "0.3.0",
+    "@jigs.design/host": "0.3.0",
+    "@jigs.design/protocol": "0.3.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0"