@jigs.design/prompt 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @jigs.design/prompt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 `pickle` blocks.
+
+## Exports
+
+| Export                      | What it is                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `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                |
+| `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                                                                     |
+
+## Source
+
+- `src/system-prompt.ts`: the system prompt.
+- `src/repair.ts`: repair and edit-failure text.
+- `src/types.ts`, `src/shared-types.ts`: schemas as types, and the enums they share.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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 };

package/dist/index.js

@@ -0,0 +1,4 @@
+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 };

package/dist/repair.d.ts

@@ -0,0 +1,49 @@
+import { Diagnostic } from "@jigs.design/runtime";
+//#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;
+/** Advice from a design check the app chose to repair, as the server reports it. */
+interface RepairAdvice {
+  message: string;
+  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 Pickle works and asks for the design change.
+ */
+export declare function repairText(diagnostics: ReadonlyArray<Diagnostic>, advice?: ReadonlyArray<RepairAdvice>): 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. */
+  breakage?: ReadonlyArray<{
+    line: number;
+    message: string;
+  }>;
+  failed: {
+    replace: string;
+    search: string;
+  };
+  /** For `ambiguous`: the line each match of the SEARCH starts on. */
+  lines?: ReadonlyArray<number>;
+  /**
+   * `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.
+   */
+  reason: "ambiguous" | "broken" | "malformed" | "missing";
+}
+/**
+ * Asks for corrected edit blocks after an edit did not apply. It names what
+ * went wrong, repeats what the edit was meant to do, and shows the lines of
+ * the current UI it concerns, so the next edits land where they were meant.
+ */
+export declare function editRepairText(edit: FailedEdit, source: string): string;
+/**
+ * Asks for the whole document after an edit did not apply. It repeats what
+ * the edit was meant to do, and the lines of the current UI closest to its
+ * SEARCH text, so the rewrite makes that change and nothing else.
+ */
+export declare function fullDocumentText(edit: FailedEdit, source: string): string;
+//#endregion
+export {};

package/dist/repair.js

@@ -0,0 +1,140 @@
+//#region src/repair.ts
+const MAX_ISSUES = 12;
+/** Whether a diagnostic is worth a repair round: something the compiler had to change. */
+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 Pickle works and asks for the design change.
+*/
+function repairText(diagnostics, advice = []) {
+	const seen = /* @__PURE__ */ new Set();
+	const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	const issues = [...errors, ...advice].filter((issue) => {
+		const key = `${issue.span.line}:${issue.message}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+	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 Pickle works, but its design can be better. Line numbers refer to your last answer.
+${lines.join("\n")}
+
+Change that and keep everything else as it is. Reply with edit blocks, or with the complete corrected Pickle if the change is large.`;
+	return `Your Pickle has problems. Line numbers refer to your last answer.
+${lines.join("\n")}
+
+Fix them and keep everything that already works. Reply with edit blocks, or with the complete corrected Pickle if the fix is large.`;
+}
+/** Letter pairs of a line without its indentation, for a rough similarity. */
+function pairs(line) {
+	const text = line.trim();
+	const counts = /* @__PURE__ */ new Map();
+	for (let index = 0; index + 1 < text.length; index++) {
+		const pair = text.slice(index, index + 2);
+		counts.set(pair, (counts.get(pair) ?? 0) + 1);
+	}
+	return counts;
+}
+/** How alike two lines are, from 0 to 1 (Dice's coefficient on letter pairs). */
+function likeness(a, b) {
+	let size = 0;
+	let shared = 0;
+	for (const [pair, count] of a) {
+		size += count;
+		shared += Math.min(count, b.get(pair) ?? 0);
+	}
+	for (const count of b.values()) size += count;
+	return size === 0 ? 0 : 2 * shared / size;
+}
+const MAX_CLOSEST_LINES = 12;
+/**
+* The run of `source` lines most like `search`, as long as `search`, so the
+* model sees what the lines it meant actually read now. Null when nothing is
+* alike.
+*/
+function closestLines(source, search) {
+	const lines = source.split("\n");
+	const wanted = search.split("\n").slice(0, MAX_CLOSEST_LINES).map((line) => pairs(line));
+	const have = lines.map((line) => pairs(line));
+	const span = Math.min(wanted.length, lines.length);
+	let best = -1;
+	let bestScore = 0;
+	for (let start = 0; start + span <= lines.length; start++) {
+		let score = 0;
+		for (let offset = 0; offset < span; offset++) score += likeness(wanted[offset] ?? /* @__PURE__ */ new Map(), have[start + offset] ?? /* @__PURE__ */ new Map());
+		if (score > bestScore) {
+			bestScore = score;
+			best = start;
+		}
+	}
+	if (best === -1 || bestScore / span < 1 / 3) return null;
+	return lines.slice(best, best + span).join("\n");
+}
+/** How many lines around an ambiguous match are quoted, to tell the matches apart. */
+const CONTEXT_LINES = 2;
+/** Each match of an ambiguous SEARCH, with the lines around it, numbered. */
+function matchesText(source, search, starts) {
+	const lines = source.split("\n");
+	const length = search.split("\n").length;
+	return starts.map((start) => {
+		const from = Math.max(1, start - CONTEXT_LINES);
+		const to = Math.min(lines.length, start + length - 1 + CONTEXT_LINES);
+		return `Line ${start}:\n${lines.slice(from - 1, to).map((line, index) => `${from + index}: ${line}`).join("\n")}`;
+	}).join("\n\n");
+}
+const list = (items) => items.length <= 2 ? items.join(" and ") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+/** The first lines of the request: what went wrong, the SEARCH, and what it was meant to become. */
+function failureParts(edit, source) {
+	const { failed } = edit;
+	const parts = [];
+	switch (edit.reason) {
+		case "ambiguous": {
+			const lines = (edit.lines ?? []).map(String);
+			parts.push(`Your edit could not be applied: this SEARCH text is in the current UI ${lines.length} times, on lines ${list(lines)}, so it is not clear which one to change:\n${failed.search}`, `It was meant to become:\n${failed.replace}`);
+			if (edit.lines !== void 0 && edit.lines.length > 0) parts.push(`The matches, with the lines around them:\n${matchesText(source, failed.search, edit.lines)}`);
+			return parts;
+		}
+		case "broken": {
+			const repairs = (edit.breakage ?? []).map((repair) => `- Line ${repair.line}: ${repair.message}`);
+			parts.push(`Your edit could not be applied: it leaves the UI's tags unbalanced. With it, the UI would need these repairs:\n${repairs.join("\n")}`, `The edit replaced:\n${failed.search}`, `With:\n${failed.replace}`);
+			return parts;
+		}
+		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 "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);
+			if (closest !== null) parts.push(`The closest lines in the current UI are:\n${closest}`);
+			return parts;
+		}
+	}
+}
+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"
+};
+/**
+* Asks for corrected edit blocks after an edit did not apply. It names what
+* went wrong, repeats what the edit was meant to do, and shows the lines of
+* the current UI it concerns, so the next edits land where they were meant.
+*/
+function editRepairText(edit, source) {
+	return [...failureParts(edit, source), `${EDIT_ADVICE[edit.reason]}, or with the complete updated Pickle if the change is large.`].join("\n\n");
+}
+/**
+* Asks for the whole document after an edit did not apply. It repeats what
+* the edit was meant to do, and the lines of the current UI closest to its
+* SEARCH text, so the rewrite makes that change and nothing else.
+*/
+function fullDocumentText(edit, source) {
+	return [...failureParts(edit, source), "Reply with the complete updated Pickle instead of edits: the current UI with this change made, and everything else kept as it is."].join("\n\n");
+}
+//#endregion
+export { editRepairText, fullDocumentText, needsRepair, repairText };

package/dist/shared-types.js

@@ -0,0 +1,178 @@
+import { declarationText, enumKey } from "./types.js";
+//#region src/shared-types.ts
+/** Names the prompt already uses for something else. */
+const RESERVED = /* @__PURE__ */ new Set([
+	"Array",
+	"Boolean",
+	"Number",
+	"Record",
+	"String"
+]);
+function words(name) {
+	return name.replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter((word) => word !== "").map((word) => word.toLowerCase());
+}
+function pascal(name) {
+	return words(name).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/**
+* A name from the fields that hold an enum: the field name when every use
+* shares it (`textAlign` → `TextAlign`), else the word most of them share
+* (`statusIcon`, `iconStart` → `Icon`).
+*/
+function fieldName(uses) {
+	const fields = new Set(uses.map((use) => use.field));
+	const [only] = fields;
+	if (fields.size === 1 && only !== void 0 && only !== "") return pascal(only);
+	const counts = /* @__PURE__ */ new Map();
+	for (const use of uses) for (const word of new Set(words(use.field))) counts.set(word, (counts.get(word) ?? 0) + 1);
+	let best = "";
+	let bestCount = 0;
+	for (const [word, count] of counts) if (count > bestCount) {
+		best = word;
+		bestCount = count;
+	}
+	return best === "" ? "Choice" : pascal(best);
+}
+function valuesText(values) {
+	return values.map((value) => JSON.stringify(value)).join(" | ");
+}
+/**
+* A name for one of several enums that would share `base`, from its first
+* and last values: `"sm" | "md" | "lg"` → `SizeSmLg`. It says what the
+* values are, not which component listed them first.
+*/
+function qualifiedName(base, values) {
+	return base + (values.length > 1 ? [values[0], values.at(-1)] : values).map((value) => pascal(String(value))).join("");
+}
+/**
+* The enums worth declaring once, by name: those that appear more than once
+* and cost less as a declaration plus a name at each use than written out
+* at each use. A name the catalog gave is used as it is. Other names come
+* from the fields, and those that clash take their first and last values as
+* a suffix, e.g. `SizeSmLg` and `SizeXsXl`. In first-use order.
+*/
+function sharedTypes(uses, reserved = /* @__PURE__ */ new Set()) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const use of uses) {
+		const key = enumKey(use.values);
+		const group = groups.get(key) ?? [];
+		group.push(use);
+		groups.set(key, group);
+	}
+	const kept = [];
+	for (const [key, group] of groups) {
+		if (group.length < 2) continue;
+		const typeName = group.find((use) => use.typeName !== void 0)?.typeName;
+		const base = typeName ?? fieldName(group);
+		const text = valuesText(group[0]?.values ?? []);
+		const inline = group.length * text.length;
+		if (`- ${base}: ${text}`.length + group.length * base.length < inline) kept.push({
+			base,
+			given: typeName !== void 0,
+			key,
+			uses: group
+		});
+	}
+	const clashes = /* @__PURE__ */ new Map();
+	for (const entry of kept) clashes.set(entry.base, (clashes.get(entry.base) ?? 0) + 1);
+	const taken = new Set(reserved);
+	const names = /* @__PURE__ */ new Map();
+	const declarations = [];
+	for (const entry of kept) {
+		const values = entry.uses[0]?.values ?? [];
+		const wanted = !entry.given && (clashes.get(entry.base) ?? 0) > 1 || RESERVED.has(entry.base) ? qualifiedName(entry.base, values) : entry.base;
+		let name = wanted;
+		for (let suffix = 2; taken.has(name); suffix++) name = `${wanted}${suffix}`;
+		taken.add(name);
+		names.set(entry.key, name);
+		declarations.push({
+			name,
+			text: valuesText(values)
+		});
+	}
+	return {
+		declarations,
+		names
+	};
+}
+/**
+* A name for a group of uses of one object: from the fields that hold it,
+* or, for an object that is only ever a procedure's whole input or output,
+* from the procedures' nouns with `Input` or `Data` after them.
+*/
+function objectName(group) {
+	const roots = group.filter((use) => use.root !== null);
+	if (roots.length < group.length) return fieldName(group.filter((use) => use.root === null));
+	const suffix = roots.every((use) => use.root === "input") ? "Input" : "Data";
+	return `${procedureNoun(roots.map((use) => use.field))}${suffix}`;
+}
+/**
+* What procedures that share an input or output are about: the noun every
+* name holds after its verb (`getOrder`, `listRecentOrder` → `Order`), or,
+* when the nouns differ, the verb most of them start with (`listOrder`,
+* `listCustomer` → `List`).
+*/
+function procedureNoun(names) {
+	const split = names.map((name) => words(name));
+	const [first, ...rest] = split;
+	const noun = (first ?? []).slice(1).filter((word) => rest.every((other) => other.slice(1).includes(word))).at(-1);
+	if (noun !== void 0) return pascal(noun);
+	return fieldName(split.map((parts) => ({ field: parts[0] ?? "" })));
+}
+/** The field most of a group's uses sit in, for a name that clashes. */
+function parentName(group) {
+	return fieldName(group.flatMap((use) => use.parent === null ? [] : [{ field: use.parent }]));
+}
+/**
+* The objects worth declaring once, by name: those with the same fields in
+* more than one place, as a generated API surface repeats its money and
+* address types. Each is named from the fields that hold it (`price`,
+* `basePrice` → `Price`; `lines` → `Line`). Names that clash take the field
+* around them first (`OptionSource`, `AdjustmentSource`), then a number. A
+* name in `reserved` is never taken. In first-use order. `names` already
+* holds the enums' names, which the declarations use.
+*/
+function sharedObjects(uses, names, reserved) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const use of uses) {
+		const group = groups.get(use.key) ?? [];
+		group.push(use);
+		groups.set(use.key, group);
+	}
+	const kept = [...groups].flatMap(([key, group]) => {
+		const first = group[0];
+		return group.length < 2 || first === void 0 ? [] : [{
+			base: objectName(group),
+			group,
+			key,
+			node: first.node
+		}];
+	});
+	const clashes = /* @__PURE__ */ new Map();
+	for (const entry of kept) clashes.set(entry.base, (clashes.get(entry.base) ?? 0) + 1);
+	const taken = new Set(reserved);
+	const named = new Map(names);
+	const declared = [];
+	for (const entry of kept) {
+		const base = RESERVED.has(entry.base) ? `${entry.base}Type` : entry.base;
+		const parent = parentName(entry.group);
+		const wanted = (clashes.get(entry.base) ?? 0) > 1 && parent !== "Choice" ? `${parent}${base}` : base;
+		let name = wanted;
+		for (let suffix = 2; taken.has(name); suffix++) name = `${wanted}${suffix}`;
+		taken.add(name);
+		named.set(entry.key, name);
+		declared.push({
+			name,
+			node: entry.node
+		});
+	}
+	return {
+		declarations: declared.map((entry) => ({
+			name: entry.name,
+			text: declarationText(entry.node, named)
+		})),
+		names: named
+	};
+}
+//#endregion
+export { sharedObjects, sharedTypes };

package/dist/system-prompt.d.ts

@@ -0,0 +1,44 @@
+import { Host } from "@jigs.design/host";
+//#region src/system-prompt.d.ts
+/** How a reply is shaped: the whole reply is one UI, or Markdown with UIs in it. */
+export type PromptMode = "chat" | "document";
+export interface PromptOptions {
+  /**
+   * The app's own instructions, such as who the assistant is and what
+   * today's date is. Rendered under their own heading, after the catalog
+   * and before the host's procedures, in both modes.
+   */
+  instructions?: string;
+  /** Default "document". */
+  mode?: PromptMode;
+}
+/**
+ * The system prompt for writing Pickle against `host`. In document mode
+ * (the default) every reply is one UI, as a session expects; in chat mode a
+ * reply is Markdown with UIs in fenced `pickle` blocks. Everything but the
+ * output section and the mode's design guidance is the same in both.
+ *
+ * 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.
+ * 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
+ * named among the procedures alone, so changing them never changes the
+ * prefix.
+ */
+export declare function systemPrompt(host: Host, options?: PromptOptions): string;
+/** The system prompt in two parts: what stays the same from turn to turn, and the rest. */
+export interface SystemPromptParts {
+  /** The output rules, the language and the catalog: the part a provider can cache. */
+  stable: string;
+  /** The app's instructions, the procedures and the images. */
+  variable: string;
+}
+/**
+ * `systemPrompt` split where what a turn may change begins, so a model call
+ * can mark the first part for a provider's prompt cache. `systemPrompt` is
+ * the two joined by a blank line.
+ */
+export declare function systemPromptParts(host: Host, options?: PromptOptions): SystemPromptParts;
+//#endregion

package/dist/system-prompt.js

@@ -0,0 +1,341 @@
+import { enumKey, enumUses, objectUses, typeText } from "./types.js";
+import { sharedObjects, sharedTypes } from "./shared-types.js";
+import { recipeSignature } from "@jigs.design/compiler";
+import { dataSchema } from "@jigs.design/host";
+//#region src/system-prompt.ts
+const PICKLE = `Pickle is Markdown for prose, JSX-like tags for components from a fixed catalog, and \`{@body ...}\` lines of JavaScript for state and logic.`;
+const EDIT_BLOCK = `<<<<<<< SEARCH
+exact lines from the current UI
+=======
+the new lines
+>>>>>>> REPLACE
+- Copy SEARCH lines exactly, indentation included, with enough lines to be unique. Use one block per place you change, in document order. An empty SEARCH appends to the end.`;
+/** Every reply is one UI: the whole document, or edits to the last one. */
+const DOCUMENT_OUTPUT = `You write interactive user interfaces in Pickle. ${PICKLE}
+
+## Output
+- Reply with Pickle only. No code fences, no explanation before or after it.
+
+## Changing an existing UI
+When asked to change a UI you wrote earlier:
+- 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 Pickle instead.`;
+const OUTPUT = {
+	chat: `You reply in Markdown, and you can show interactive user interfaces in your replies by writing Pickle. ${PICKLE}
+
+## Output
+- Answer in Markdown, as in any chat. Most replies need no UI.
+- When a UI helps more than prose (live data, a form, a comparison, a chart, anything to click), write it in Pickle inside a fenced block that opens with \`\`\`pickle and a short kebab-case id, and closes with \`\`\`:
+\`\`\`pickle monthly-spending
+# Spending this month
+...
+\`\`\`
+- 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.
+- 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 Pickle in any other fence, and never put a fence inside a block.
+
+## Changing an earlier UI
+- To change a UI from earlier in the conversation, write a block with the same id. It shows the new version in your reply; the old one stays where it was.
+- For a focused change, the block holds only edit blocks against that UI's latest version:
+${EDIT_BLOCK}
+- If the change rewrites most of the UI, put the complete updated Pickle in the block instead.
+- A new id makes a new UI.`,
+	document: DOCUMENT_OUTPUT
+};
+const LANGUAGE = `## Rules
+- Use the components and props listed below, or one you define. Anything else is removed before rendering.
+- Style only through props. Never write CSS, HTML, class names or colours like "#fff".
+- Your output is rendered while you write it. Put each \`{@body}\` line on its own line, and each opening and closing tag of a block: \`<each>\`, \`<if>\`, \`<define>\` and components whose children are "any". A tag with inline children fits on one line: \`<text>Total: {total}</text>\`.
+- Quotes are for text only. Numbers, booleans and expressions go in braces: \`gap={3}\`, never \`gap="3"\`.
+- Declare state with \`{@body const [value, setValue] = useState(initial)}\` and derived values with \`{@body const total = value * 2}\`, before any markup that uses them.
+- Bind controls to state: \`value={value} onChange={setValue}\`. Prop values in braces are JavaScript expressions.
+- Interpolate values in text with \`{expression}\`.
+- Markdown works anywhere content is allowed: # headings, paragraphs, **bold**, *italic*, \`code\`, - lists, 1. lists and ---.
+- Prefer Markdown for plain prose and use components for layout, grouping and interaction.
+- JavaScript is a subset: no classes, \`this\`, \`var\`, \`let\`, loops, labels, \`try\`, \`function\` declarations, getters or setters, regex literals, \`import()\`, \`__proto__\`, \`constructor\` or \`prototype\`. Use \`const\` and arrow functions. Browser globals such as \`window\`, \`fetch\` and \`navigator\` do not exist. Array methods, \`Math\`, \`JSON\`, \`Date\` and \`Intl\` work: format money with \`Intl.NumberFormat\` (\`{ style: "currency", currency }\`, in the app's currency) or \`toFixed(2)\`, and dates with \`Date\` or \`Intl.DateTimeFormat\`. To drop trailing zeros, write \`String(Number(x.toFixed(2)))\`.
+
+## Repeating and conditional content
+- \`<each of={list} as="item" index="i">...</each>\` repeats its children for every item. \`as\` defaults to "item" and \`index\` is optional. \`of={5}\` counts 0 to 4.
+- \`<if test={condition}>...</if>\` shows its children only when the condition is true. For an else branch, add another \`<if>\` with the opposite condition.
+- Never copy and paste the same markup for each item; keep the data in a \`{@body}\` array and use \`<each>\`.
+- \`{@body}\` lines inside \`<each>\` run once per item, so per-item values can use the item: \`{@body const share = item.votes / total}\`.
+- \`{@body}\` lines inside \`<if>\` run only when its test is true, so they can use what the test checked. Names declared there are visible only inside that block.
+- Declare \`useState\`, \`useQuery\` and \`useMutation\` at the top of the document, before any markup, or at the top of a \`<define>\` body — never inside \`<each>\` or \`<if>\`.
+- Keep per-item state in one object, e.g. \`{@body const [done, setDone] = useState({})}\` and \`onChange={(v) => setDone({ ...done, [item.id]: v })}\`.
+
+## Your own components
+- \`<define name="stat" label value={0}>...</define>\` declares a component, used as \`<stat label="Revenue" value={n}/>\`. Put each define at the top level, just before its first use, and keep it short.
+- Every attribute except \`name\` is a prop. A bare attribute (\`label\`) is required. \`value={0}\` or \`note=""\` gives a default.
+- Put \`<slot/>\` where the instance's children should go. A define with no \`<slot/>\` takes no children.
+- The body sees only its props, its own \`{@body}\` lines and other components. It does not see the document's state; pass values in as props, with a setter if the component should change them.
+- In a list, give each instance a \`key\` (\`<stat key={item.id}/>\`), on the component inside \`<each>\`, not on \`<each>\`, or repeat items that have an \`id\`, so that state stays put when the list changes.`;
+const NO_PROCEDURES = `## Data and actions
+- This app registered no queries or mutations. Do not call \`useQuery\` or \`useMutation\`; keep everything in state.`;
+const HOOKS = `## Data and actions
+- \`{@body const orders = useQuery("orders", { status: "open" })}\` reads a query listed below while rendering. It returns \`{ status, data, error }\`: status is "pending", "success" or "error"; \`data\` is null until "success"; \`error\` is \`{ code, message }\`. Show each status with \`<if>\`. There is no \`isLoading\` and no \`refetch\`.
+- Calls with the same name and input share one request. Pass submitted values, not live keystrokes: keep a text field in state and copy it into the query's input on Enter or a button.
+- A query whose input needs another's data waits for it with a third argument: \`useQuery("orderLines", { orderId: order.data?.id }, { enabled: order.status === "success" })\`. Until \`enabled\` is true it fetches nothing and stays "pending".
+- \`{@body const archive = useMutation("archiveOrder")}\` declares a mutation listed below. It returns \`{ status, data, error, input, mutate }\` with status "idle", "pending", "success" or "error".
+- Call \`archive.mutate({ id: order.id })\` inside an event handler. While it is "pending", more calls do nothing, so disable the controls that call it. \`input\` is the last input sent, so one mutation can serve a list: \`archive.status === "pending" && archive.input.id === order.id\` marks the busy row.
+- 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.
+- 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.
+- boolean: the bare name means true (\`disabled\`), \`disabled={false}\` false, and \`disabled={expression}\` decides at run time. Leaving it out gives its default, or false when none is shown.
+- number: in braces, \`gap={3}\`. A range such as 0–16 bounds it.
+- handler: a function, \`onClick={() => setOpen(true)}\`, or a setter, \`onChange={setValue}\`. A signature such as \`(value: number) => void\` says what it is called with.
+- list: an array of flat objects in braces, such as \`{rows}\`; the description says which fields each object has.
+- Quoted values and named types are text: \`size="md"\`, or \`size={big ? "lg" : "md"}\`.
+- Children: "any" is components, Markdown and text; "inline" is text, {expressions}, bold, italic, code and badges; "none" means the tag closes itself, \`<spacer/>\`.`;
+const CHILDREN = {
+	block: "Children: any",
+	inline: "Children: inline",
+	none: "Children: none"
+};
+function schemaText(schema, names) {
+	switch (schema.kind) {
+		case "boolean":
+		case "handler":
+		case "list":
+		case "string": return schema.kind;
+		case "enum": return names.get(enumKey(schema.values)) ?? schema.values.map((value) => JSON.stringify(value)).join(" | ");
+		case "image": return "image URL (https, on an allowed image host)";
+		case "link": return "URL (http or https)";
+		case "number":
+			if (schema.min !== void 0 && schema.max !== void 0) return `number ${schema.min}–${schema.max}`;
+			if (schema.min !== void 0) return `number, at least ${schema.min}`;
+			if (schema.max !== void 0) return `number, at most ${schema.max}`;
+			return "number";
+	}
+}
+function propLine(name, definition, names) {
+	const fallback = definition.default === void 0 ? "" : ` = ${JSON.stringify(definition.default)}`;
+	const description = definition.description === void 0 ? "" : `. ${definition.description}`;
+	return `- ${name}: ${typeOf(definition, names)}${fallback}${description}`;
+}
+/** A prop's type: its schema, or for a handler with arguments its signature. */
+function typeOf(definition, names) {
+	const args = definition.args ?? [];
+	if (definition.schema.kind !== "handler" || args.length === 0) return schemaText(definition.schema, names);
+	return `(${args.map((arg, index) => `${args.length === 1 ? "value" : `value${index + 1}`}: ${schemaText(arg.schema, names)}`).join(", ")}) => void`;
+}
+/** Below this many characters saved, a component lists its props in full. */
+const MIN_SHARED_SAVING = 60;
+/**
+* Where a component's props repeat those of a component listed earlier,
+* one line names them instead: `- Same as <box>: align, gap, padding`.
+* The earlier component must list them in full, so the model looks one
+* place up, never two.
+*/
+function sharedWith(lines, earlier) {
+	let best = null;
+	for (const component of earlier) {
+		const shared = lines.filter((line) => component.full.has(line.text));
+		const names = shared.map((line) => line.name);
+		const reference = `- Same as <${component.name}>: ${names.join(", ")}`;
+		const saved = shared.reduce((sum, line) => sum + line.text.length + 1, 0) - reference.length;
+		if (saved >= MIN_SHARED_SAVING && (best === null || saved > best.saved)) best = {
+			from: component.name,
+			names,
+			saved
+		};
+	}
+	return best === null ? null : {
+		from: best.from,
+		names: best.names
+	};
+}
+function componentSections(components, names) {
+	const earlier = [];
+	return components.map((component) => {
+		const props = Object.entries(component.props).toSorted(([a], [b]) => a < b ? -1 : 1).map(([name, definition]) => ({
+			name,
+			text: propLine(name, definition, names)
+		}));
+		const shared = sharedWith(props, earlier);
+		const sharedNames = new Set(shared?.names ?? []);
+		const own = props.filter((line) => !sharedNames.has(line.name));
+		earlier.push({
+			full: new Set(own.map((line) => line.text)),
+			name: component.name
+		});
+		const lines = [
+			`### <${component.name}>`,
+			component.description,
+			CHILDREN[component.children]
+		];
+		if (shared !== null) lines.push(`- Same as <${shared.from}>: ${shared.names.join(", ")}`);
+		lines.push(...own.map((line) => line.text));
+		if (props.length === 0) lines.push("No props.");
+		for (const avoid of component.avoid) lines.push(`Not for ${avoid.when}: use ${avoid.useInstead}`);
+		return lines.join("\n");
+	});
+}
+function procedureSection(name, procedure, names) {
+	const call = procedure.kind === "query" ? procedure.input === void 0 ? `useQuery("${name}")` : `useQuery("${name}", input)` : `useMutation("${name}")`;
+	const data = dataSchema(procedure);
+	const lines = [
+		`### ${name}`,
+		procedure.description,
+		`Call: ${call}`,
+		...procedure.input === void 0 ? [] : [`Input: ${typeText(procedure.input, "input", names)}`],
+		data === void 0 ? "Data: null" : `Data: ${typeText(data, "output", names)}`
+	];
+	if (procedure.kind === "mutation" && procedure.invalidates.length > 0) lines.push(`Refreshes: ${procedure.invalidates.join(", ")}`);
+	if (procedure.kind === "mutation" && procedure.policy === "confirm") lines.push("Asks the user to confirm before it runs; don't draw your own confirmation.");
+	return lines.join("\n");
+}
+function actionSection(name, procedure, names) {
+	return [
+		`### ${name}`,
+		procedure.description,
+		`Call: useMutation("${name}")`,
+		...procedure.input === void 0 ? [] : [`Input: ${typeText(procedure.input, "input", names)}`],
+		"Handled by the page, not the server. Refreshes nothing."
+	].join("\n");
+}
+const RECIPES_INTRO = `## Recipes
+Components written in Pickle 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({
+		name: entry.name,
+		source: entry.source
+	})}`, entry.description];
+	if (entry.example !== void 0) lines.push(`Example: \`${entry.example}\``);
+	return lines.join("\n");
+}
+const SITUATIONS_INTRO = `## Situations
+Find the situation whose When matches what the reader will do with this UI. Follow its guidance where it differs from Design. Ignore the others. If none matches, follow Design alone.`;
+/**
+* A fence for `source` that no line of it can close. A plain fence with no
+* info string, so in chat mode it reads as an example, never as a block.
+*/
+function fenceFor(source) {
+	const runs = source.match(/^ {0,3}`{3,}/gm) ?? [];
+	const longest = Math.max(2, ...runs.map((run) => run.trim().length));
+	return "`".repeat(longest + 1);
+}
+function situationSection(entry) {
+	const lines = [
+		`### ${entry.name}`,
+		`When: ${entry.when}`,
+		entry.guidance
+	];
+	if (entry.example !== void 0) {
+		const fence = fenceFor(entry.example);
+		lines.push("Example:", fence, entry.example, fence);
+	}
+	return lines.join("\n");
+}
+/** Shared guidance, then this mode's; empty when there is neither. */
+function designText(host, mode) {
+	return [host.guidance.shared, host.guidance[mode]].filter((part) => part !== void 0).join("\n\n");
+}
+/** Every enum in the host's procedures' inputs and outputs. */
+function procedureEnums(host) {
+	const uses = [];
+	for (const procedure of Object.values(host.procedures)) {
+		if (procedure.input !== void 0) uses.push(...enumUses(procedure.input, "input"));
+		const data = dataSchema(procedure);
+		if (data !== void 0) uses.push(...enumUses(data, "output"));
+	}
+	return uses;
+}
+/** Every object with two or more fields in the procedures' inputs and outputs. */
+function procedureObjects(host) {
+	const uses = [];
+	for (const [name, procedure] of Object.entries(host.procedures)) {
+		if (procedure.input !== void 0) uses.push(...objectUses(procedure.input, "input", name));
+		const data = dataSchema(procedure);
+		if (data !== void 0) uses.push(...objectUses(data, "output", name));
+	}
+	return uses;
+}
+/** Every enum among the catalog's component props. */
+function componentEnums(host) {
+	const uses = [];
+	for (const component of host.components.components) for (const [field, definition] of Object.entries(component.props)) if (definition.schema.kind === "enum") uses.push(definition.typeName === void 0 ? {
+		field,
+		values: definition.schema.values
+	} : {
+		field,
+		typeName: definition.typeName,
+		values: definition.schema.values
+	});
+	return uses;
+}
+/** A `## Types`-style section declaring `declarations`, or nothing. */
+function typesSection(heading, intro, declarations) {
+	return declarations.length === 0 ? [] : [[
+		heading,
+		intro,
+		...declarations.map((declaration) => `- ${declaration.name}: ${declaration.text}`)
+	].join("\n")];
+}
+/**
+* The system prompt for writing Pickle against `host`. In document mode
+* (the default) every reply is one UI, as a session expects; in chat mode a
+* reply is Markdown with UIs in fenced `pickle` blocks. Everything but the
+* output section and the mode's design guidance is the same in both.
+*
+* 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.
+* 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
+* named among the procedures alone, so changing them never changes the
+* prefix.
+*/
+function systemPrompt(host, options) {
+	const parts = systemPromptParts(host, options);
+	return `${parts.stable}\n\n${parts.variable}`;
+}
+/**
+* `systemPrompt` split where what a turn may change begins, so a model call
+* can mark the first part for a provider's prompt cache. `systemPrompt` is
+* the two joined by a blank line.
+*/
+function systemPromptParts(host, options) {
+	const entries = Object.entries(host.procedures);
+	const queries = entries.filter(([, procedure]) => procedure.kind === "query");
+	const mutations = entries.filter(([, procedure]) => procedure.kind === "mutation");
+	const catalogTypes = sharedTypes(componentEnums(host));
+	const dataTypes = sharedTypes(procedureEnums(host).filter((use) => !catalogTypes.names.has(enumKey(use.values))), new Set(catalogTypes.declarations.map((declaration) => declaration.name)));
+	const enumNames = new Map([...catalogTypes.names, ...dataTypes.names]);
+	const objectTypes = sharedObjects(procedureObjects(host), enumNames, new Set([...catalogTypes.declarations, ...dataTypes.declarations].map((declaration) => declaration.name)));
+	const names = objectTypes.names;
+	const mode = options?.mode ?? "document";
+	const sections = [
+		OUTPUT[mode],
+		LANGUAGE,
+		entries.length === 0 ? NO_PROCEDURES : HOOKS,
+		...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 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"));
+	const variable = [];
+	const instructions = options?.instructions?.trim() ?? "";
+	if (instructions !== "") variable.push(`## App instructions\n${instructions}`);
+	variable.push(...typesSection("## Data types", "Named lists of values and objects, used by the queries and mutations below.", [...dataTypes.declarations, ...objectTypes.declarations]));
+	if (queries.length > 0) variable.push(["## Queries", ...queries.map(([name, procedure]) => procedureSection(name, procedure, names))].join("\n\n"));
+	if (mutations.length > 0) variable.push(["## Mutations", ...mutations.map(([name, procedure]) => procedureSection(name, procedure, names))].join("\n\n"));
+	const actions = entries.flatMap(([name, procedure]) => procedure.kind === "action" ? [actionSection(name, procedure, names)] : []);
+	if (actions.length > 0) variable.push(["## Actions", ...actions].join("\n\n"));
+	variable.push(host.imageHosts.length === 0 ? "## Images\n- No image hosts are allowed. Do not use images." : `## Images\n- Images may only load from: ${host.imageHosts.join(", ")}. Any other URL is dropped.`);
+	return {
+		stable: sections.join("\n\n"),
+		variable: variable.join("\n\n")
+	};
+}
+//#endregion
+export { systemPrompt, systemPromptParts };

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/types.d.ts
+/** The enums (by `enumKey`) and objects (by `objectKey`) declared once by name. */
+export type TypeNames = ReadonlyMap<string, string>;
+/**
+ * A TypeScript-like type for a Zod schema, as the model reads it in the
+ * prompt. `io` picks what the spec sends (`input`) or reads (`output`).
+ * Fields keep their `.describe()` text and constraints as `//` comments.
+ * An enum listed in `names` is written as its name.
+ */
+export declare function typeText(schema: z.ZodType, io: "input" | "output", names?: TypeNames): string;
+//#endregion

package/dist/types.js

@@ -0,0 +1,286 @@
+import { z } from "zod";
+//#region src/types.ts
+const literal = z.union([
+	z.boolean(),
+	z.number(),
+	z.string(),
+	z.null()
+]);
+const jsonSchemaNode = z.lazy(() => z.object({
+	additionalProperties: z.union([jsonSchemaNode, z.boolean()]).optional(),
+	anyOf: z.array(jsonSchemaNode).optional(),
+	const: literal.optional(),
+	default: z.unknown().optional(),
+	description: z.string().optional(),
+	enum: z.array(literal).optional(),
+	exclusiveMaximum: z.number().optional(),
+	exclusiveMinimum: z.number().optional(),
+	format: z.string().optional(),
+	items: jsonSchemaNode.optional(),
+	maximum: z.number().optional(),
+	maxItems: z.number().optional(),
+	maxLength: z.number().optional(),
+	minimum: z.number().optional(),
+	minItems: z.number().optional(),
+	minLength: z.number().optional(),
+	oneOf: z.array(jsonSchemaNode).optional(),
+	pattern: z.string().optional(),
+	properties: z.record(z.string(), jsonSchemaNode).optional(),
+	required: z.array(z.string()).optional(),
+	type: z.union([z.string(), z.array(z.string())]).optional()
+}).loose());
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** The deepest a type is ever written; the budget usually stops it sooner. */
+const MAX_DEPTH = 12;
+/**
+* Characters a type may take before its deepest objects are cut to their
+* field names: about 600 tokens, a screenful of fields.
+*/
+const TYPE_BUDGET = 2400;
+/** Field names a cut object lists before saying how many more it has. */
+const CUT_FIELDS = 6;
+const INDENT = "  ";
+/** The key a list of enum values is known by, in `TypeNames`. */
+function enumKey(values) {
+	return JSON.stringify(values);
+}
+const objectKeys = /* @__PURE__ */ new WeakMap();
+/**
+* The key an object type is known by, in `TypeNames`: its JSON Schema as
+* the prompt reads it, so without whether it takes extra fields (output
+* objects say no, input objects say nothing). Cached per node.
+*/
+function objectKey(node) {
+	const cached = objectKeys.get(node);
+	if (cached !== void 0) return cached;
+	const key = `object ${JSON.stringify(node, (field, value) => field === "additionalProperties" && value === false ? void 0 : value)}`;
+	objectKeys.set(node, key);
+	return key;
+}
+/** A list's field as one of its items: `lines` → `line`, `categories` → `category`. */
+function singular(field) {
+	if (field.endsWith("ies")) return `${field.slice(0, -3)}y`;
+	return field.endsWith("s") && !field.endsWith("ss") ? field.slice(0, -1) : field;
+}
+function primitive(type) {
+	return type === "integer" ? "number" : type;
+}
+function typesOf(node) {
+	return node.type === void 0 ? [] : [node.type].flat();
+}
+/** Zod gives `.int()` the safe-integer range; that says nothing to the model. */
+function bound(value) {
+	return value === void 0 || Math.abs(value) >= Number.MAX_SAFE_INTEGER ? void 0 : value;
+}
+/** `unit` is the plural, e.g. "items"; a count of exactly 1 drops the "s". */
+function range(min, max, unit = "") {
+	const of = (count) => count === 1 && unit.endsWith("s") ? `${count}${unit.slice(0, -1)}` : `${count}${unit}`;
+	if (min !== void 0 && max !== void 0) return min === max ? `exactly ${of(min)}` : `${min}–${max}${unit}`;
+	if (min !== void 0) return `at least ${of(min)}`;
+	if (max !== void 0) return `at most ${of(max)}`;
+}
+/** What a node's type text leaves out: integer, bounds, lengths, format, pattern, default. */
+function constraints(node) {
+	const parts = [];
+	if (typesOf(node).includes("integer")) parts.push("integer");
+	const numberRange = range(bound(node.minimum), bound(node.maximum));
+	if (numberRange !== void 0) parts.push(numberRange);
+	if (node.exclusiveMinimum !== void 0) parts.push(`greater than ${node.exclusiveMinimum}`);
+	if (node.exclusiveMaximum !== void 0) parts.push(`less than ${node.exclusiveMaximum}`);
+	const length = range(node.minLength, node.maxLength, " characters");
+	if (length !== void 0) parts.push(length);
+	const items = range(node.minItems, node.maxItems, " items");
+	if (items !== void 0) parts.push(items);
+	if (node.format !== void 0) parts.push(`format ${node.format}`);
+	else if (node.pattern !== void 0) parts.push(`matches /${node.pattern}/`);
+	if (node.default !== void 0) parts.push(`default ${JSON.stringify(node.default)}`);
+	return parts;
+}
+/**
+* The comment for a field: its description, then its constraints, those of
+* its union members (as in `.nullable()`), and those of an array's items.
+*/
+function note(node) {
+	const parts = constraints(node);
+	for (const member of node.anyOf ?? node.oneOf ?? []) {
+		parts.push(...constraints(member));
+		if (member.description !== void 0 && node.description === void 0) parts.unshift(member.description);
+	}
+	const items = node.items;
+	if (items !== void 0) {
+		const inner = [...items.description === void 0 ? [] : [items.description], ...constraints(items)];
+		if (inner.length > 0) parts.push(`each ${inner.join(", ")}`);
+	}
+	const unique = [...new Set(parts)];
+	if (node.description === void 0) return unique.join(", ");
+	return unique.length === 0 ? node.description : `${node.description} (${unique.join(", ")})`;
+}
+/** An object cut to its field names: what was left out, never `unknown`. */
+function cutObject(node) {
+	const fields = Object.keys(node.properties ?? {});
+	const listed = fields.slice(0, CUT_FIELDS).join(", ");
+	const more = fields.length - CUT_FIELDS;
+	return fields.length === 0 ? "{}" : `{ /* ${listed}${more > 0 ? ` and ${more} more` : ""} */ }`;
+}
+function render(node, depth, indent, options) {
+	const names = options.names;
+	if (node.const !== void 0) return JSON.stringify(node.const);
+	if (node.enum !== void 0) return names.get(enumKey(node.enum)) ?? node.enum.map((value) => JSON.stringify(value)).join(" | ");
+	const union = node.anyOf ?? node.oneOf;
+	if (union !== void 0) return union.map((member) => render(member, depth + 1, indent, options)).join(" | ");
+	const types = typesOf(node);
+	if (types.length > 1) return types.map((type) => render({
+		...node,
+		type
+	}, depth + 1, indent, options)).join(" | ");
+	const type = types[0];
+	if (type === "array") return `Array<${node.items === void 0 ? "unknown" : render(node.items, depth + 1, indent, options)}>`;
+	if (type === "object" || node.properties !== void 0) {
+		const key = objectKey(node);
+		const named = key === options.self ? void 0 : names.get(key);
+		if (named !== void 0) return named;
+		const inner = {
+			limit: options.limit,
+			names
+		};
+		return depth > options.limit ? cutObject(node) : renderObject(node, depth, indent, inner);
+	}
+	return type === void 0 ? "unknown" : primitive(type);
+}
+/**
+* An object on one line, or one field per line when a field has a
+* description or a constraint to show beside it.
+*/
+function renderObject(node, depth, indent, options) {
+	const required = new Set(node.required ?? []);
+	const inner = indent + INDENT;
+	const fields = Object.entries(node.properties ?? {}).map(([name, value]) => {
+		const key = IDENTIFIER.test(name) ? name : JSON.stringify(name);
+		const optional = required.has(name) ? "" : "?";
+		return {
+			comment: note(value),
+			text: `${key}${optional}: ${render(value, depth + 1, inner, options)}`
+		};
+	});
+	if (fields.length === 0) {
+		const additional = node.additionalProperties;
+		return additional === void 0 || additional === true || additional === false ? "{}" : `Record<string, ${render(additional, depth + 1, indent, options)}>`;
+	}
+	if (fields.every((field) => field.comment === "" && !field.text.includes("\n"))) return `{ ${fields.map((field) => field.text).join("; ")} }`;
+	return `{\n${fields.map((field) => `${inner}${field.text};${field.comment === "" ? "" : ` // ${field.comment}`}`).join("\n")}\n${indent}}`;
+}
+function collect(node, field, depth, uses) {
+	if (depth > MAX_DEPTH) return;
+	if (node.enum !== void 0) {
+		uses.push({
+			field,
+			values: node.enum
+		});
+		return;
+	}
+	for (const member of node.anyOf ?? node.oneOf ?? []) collect(member, field, depth + 1, uses);
+	if (node.items !== void 0) collect(node.items, field, depth + 1, uses);
+	for (const [name, value] of Object.entries(node.properties ?? {})) collect(value, name, depth + 1, uses);
+	if (node.additionalProperties !== void 0 && node.additionalProperties !== true && node.additionalProperties !== false) collect(node.additionalProperties, field, depth + 1, uses);
+}
+const jsonSchemas = {
+	input: /* @__PURE__ */ new WeakMap(),
+	output: /* @__PURE__ */ new WeakMap()
+};
+/** `schema` as JSON Schema, converted once per schema and direction. */
+function jsonSchema(schema, io) {
+	const cached = jsonSchemas[io].get(schema);
+	if (cached !== void 0) return cached;
+	const node = convert(schema, io);
+	jsonSchemas[io].set(schema, node);
+	return node;
+}
+function convert(schema, io) {
+	const converted = z.toJSONSchema(schema, { io });
+	delete converted.$schema;
+	const parsed = jsonSchemaNode.safeParse(converted);
+	return parsed.success ? parsed.data : null;
+}
+/** Every enum in a schema, with the name of the field that holds it. */
+function enumUses(schema, io) {
+	const node = jsonSchema(schema, io);
+	const uses = [];
+	if (node !== null) collect(node, "", 0, uses);
+	return uses;
+}
+/**
+* A TypeScript-like type for a Zod schema, as the model reads it in the
+* prompt. `io` picks what the spec sends (`input`) or reads (`output`).
+* Fields keep their `.describe()` text and constraints as `//` comments.
+* An enum listed in `names` is written as its name.
+*/
+function typeText(schema, io, names = /* @__PURE__ */ new Map()) {
+	const node = jsonSchema(schema, io);
+	if (node === null) return "unknown";
+	const text = withinBudget(node, {
+		limit: MAX_DEPTH,
+		names
+	});
+	const comment = note(node);
+	return comment === "" ? text : `${text} // ${comment}`;
+}
+/**
+* `node` written as deep as fits `TYPE_BUDGET`: from `MAX_DEPTH` down, until
+* the text fits or only the top level is left. Deeper objects are cut to
+* their field names.
+*/
+function withinBudget(node, options) {
+	let text = render(node, 0, "", options);
+	for (let limit = 11; limit >= 1 && text.length > TYPE_BUDGET; limit--) text = render(node, 0, "", {
+		...options,
+		limit
+	});
+	return text;
+}
+/** An object type's declaration: written out, with other named types by name. */
+function declarationText(node, names) {
+	return withinBudget(node, {
+		limit: MAX_DEPTH,
+		names,
+		self: objectKey(node)
+	});
+}
+function collectObjects(node, place, depth, uses) {
+	if (depth > MAX_DEPTH) return;
+	const properties = Object.entries(node.properties ?? {});
+	if (properties.length >= 2) uses.push({
+		...place,
+		key: objectKey(node),
+		node
+	});
+	for (const member of node.anyOf ?? node.oneOf ?? []) collectObjects(member, place, depth + 1, uses);
+	if (node.items !== void 0) {
+		const item = {
+			...place,
+			field: singular(place.field),
+			root: null
+		};
+		collectObjects(node.items, item, depth + 1, uses);
+	}
+	for (const [name, value] of properties) collectObjects(value, {
+		field: name,
+		parent: place.field,
+		root: null
+	}, depth + 1, uses);
+}
+/**
+* Every object with two or more fields in a schema, nested ones included,
+* with the field that holds it; the root is held by `field`.
+*/
+function objectUses(schema, io, field) {
+	const node = jsonSchema(schema, io);
+	const uses = [];
+	if (node !== null) collectObjects(node, {
+		field,
+		parent: null,
+		root: io
+	}, 0, uses);
+	return uses;
+}
+//#endregion
+export { declarationText, enumKey, enumUses, objectUses, typeText };

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@jigs.design/prompt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The system prompt and the repair text, rendered from a host and from diagnostics.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/prompt"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jigs.design/compiler": "0.1.0",
+    "@jigs.design/host": "0.1.0",
+    "@jigs.design/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
+  }
 }