tsquare 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.7.1
+
+- **`share_wireframe` returns only the links asked for.** A new `links` option takes the kinds from the playground's Copy link menu, with the same names: `share`, `svg`, `png`, `markdown`, `html`. The default is `["svg", "share"]`, an image link and the link to edit it; before, every call returned four links. Each link carries the whole wireframe (about 1,200 characters for a three-screen board), and the model has to write out every link it passes on, exactly, so fewer links means less to write and fewer chances to break one. A wireframe too long for an image link gets its share link instead, with a note saying why. New exports: `LINK_KINDS`, `DEFAULT_LINKS`, `LinkKind`.
+
+- **Invalid values name the prop and the value.** A wrong `key=value` used to come back as Zod's bare message, which didn't say which prop on the line was wrong: `Input: Invalid option: expected one of "text"|"password"|…`. Now: `Input: type=otp isn't an option; use one of text, password, search, email, date, code`. Likewise `level=4 isn't an option; use one of 1, 2, 3`, `height=tall should be a number`, `columns=Name should be a list like [a, b]`, `range=[1] needs at least 2 items`, `columns=0 is too small (at least 1)`. This matters most in the MCP repair loop, where the model fixes what the messages say.
+- **Fix: the HTML link escapes `&`** (and `<`, `>`) in the board title, in both the playground's Copy link → HTML and the MCP share tool, which now share one helper. A title like `Tom &amp; Jerry` used to show as "Tom & Jerry".
+- **One wrong value is one error.** A check that uses a prop's value is skipped when that value is already invalid: `input type=otp digits=6` no longer also says "digits only applies to type=code". Checks that only notice a prop is set still run (`leadingIcon` on an avatar item is wrong whatever the icon's name).
+
+## 0.7.0
+
+### MCP tools
+
+- **Hosted MCP server at `https://tsquare.dev/mcp`** (in the site repo), with three tools: `wireframe_guide` (the language plus a write → render → fix → share workflow), `render_wireframe` (a PNG for the model to look at, at most 1600px on its longest side, or line-numbered problems) and `share_wireframe` (SVG, PNG, playground and Markdown links). Setup for Claude, Claude Code, Cursor and VS Code is in [Using it with AI](docs/ai.md#connect-over-mcp).
+- **The tools live in the library** as plain functions with no MCP SDK, so a local server can reuse them: `mcpTools` (names, descriptions, Zod input schemas, annotations), `MCP_INSTRUCTIONS`, `wireframeGuide()`, `renderWireframeTool()`, `shareWireframeTool()` and `callMcpTool(name, args)`. Results use the MCP tool-result shape; problems come back as `isError` results, not exceptions, so the model can read and fix them. Share links drop a surrounding code fence.
+- `wireframePrompt()` is unchanged; its language part is now shared with the guide.
+
+### Errors
+
+- **A value under the wrong prop points at the right one:** `image type=map` now says "for an Image, write kind=map (or just map)"; likewise `input kind=date` → `type=date` and `chart type=pie` → `kind=pie`.
+- Grammar: "a Input" → "an Input" in error messages.
+
 ## 0.6.1
 
 - **Fix: the playground opens 0.6.0 share links.** 0.6.0 made share links with the new `y` prefix, but its playground only opened links starting with `z`. Opening a new share link left the editor on whatever it showed before. The prefixes now live in one place that both the library and the playground use, and a test guards it. Links themselves didn't change: every `y` link made by 0.6.0 opens correctly now.

package/dist/chunks/{chunk-HDSKRKDL.js → chunk-ZLVSCEWO.js}

@@ -1892,7 +1892,7 @@ for (const [name, def] of Object.entries(componentDefinitions)) {
   for (const v of ambiguous) enumValues.delete(v);
   COMPONENTS.set(name.toLowerCase(), { name, props: shape, enumValues, ambiguous, booleans: booleans2 });
 }
-function belongsElsewhere(component, word, asProp) {
+function belongsElsewhere(component, word, asProp, value) {
   const info = COMPONENTS.get(component.toLowerCase());
   if (!info) return "";
   const props = [], options = [];
@@ -1903,7 +1903,9 @@ function belongsElsewhere(component, word, asProp) {
   }
   const names = (xs) => xs.length > 3 ? `${xs.slice(0, 3).join(", ")}\u2026` : xs.join(", ").replace(/, ([^,]*)$/, " and $1");
   const a = (name) => /^[AEIOU]/.test(name) ? `an ${name}` : `a ${name}`;
-  let msg = props.length ? `${word} is a ${names(props)} prop, not ${a(info.name)} one` : options.length ? `${word} is a ${names(options)} option, not ${a(info.name)} one` : "";
+  let msg = props.length ? `${word} is ${a(names(props))} prop, not ${a(info.name)} one` : options.length ? `${word} is ${a(names(options))} option, not ${a(info.name)} one` : "";
+  const right = typeof value === "string" ? info.enumValues.get(value) : void 0;
+  if (asProp && right && right !== word) msg += `${msg ? "; " : ""}for ${a(info.name)}, write ${right}=${value} (or just ${value})`;
   const width = info.props.width;
   if (msg && word === "fullWidth" && /fills the space/i.test(width?.description ?? unwrap(width)?.description ?? "")) {
     msg += `; ${a(info.name)} already fills its width (width=\u2026 sets a fixed one), so remove it`;
@@ -2134,11 +2136,12 @@ function parseWireframeText(source) {
             }
             continue;
           }
+          const value = parseValue(c);
           if (!(key in info.props)) {
-            const elsewhere = belongsElsewhere(info.name, key, true);
+            const elsewhere = belongsElsewhere(info.name, key, true, value);
             issues.push({ line: lineNo, message: `${info.name} has no prop "${key}"` + (elsewhere ? `: ${elsewhere}` : "") + ` (its props: ${Object.keys(info.props).join(", ")})` });
           }
-          props[key] = key in info.props ? textWhereExpected(info.props[key], parseValue(c)) : parseValue(c);
+          props[key] = key in info.props ? textWhereExpected(info.props[key], value) : value;
           continue;
         }
         c.next();
@@ -2681,6 +2684,38 @@ function listItemKindHint(el, path) {
   if (value === "icon" || !kinds.includes(value)) return void 0;
   return `${value} is a ${side} kind, not an icon name: write ${side}=${value} instead of ${prop}=${value}`;
 }
+function written(v) {
+  if (typeof v === "string") return /^[^\s"[\]{}=,]+$/.test(v) ? v : JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(written).join(", ")}]`;
+  return JSON.stringify(v) ?? String(v);
+}
+function propIssueMessage(props, issue) {
+  const path = issue.path ?? [];
+  if (!path.length || issue.code === "custom") return issue.message;
+  const key = path.map(String).join(".");
+  const value = path.reduce((v, k) => v == null ? v : v[k], props);
+  const given = `${key}=${written(value)}`;
+  switch (issue.code) {
+    case "invalid_value":
+      return `${given} isn't an option; use one of ${(issue.values ?? []).map(written).join(", ")}`;
+    case "invalid_union": {
+      const options = (issue.errors ?? []).flat().flatMap((e) => e.code === "invalid_value" ? e.values : []);
+      if (options.length) return `${given} isn't an option; use one of ${options.map(written).join(", ")}`;
+      return `${given} isn't a valid value`;
+    }
+    case "invalid_type":
+      return `${given} should be ${issue.expected === "array" ? "a list like [a, b]" : `a ${issue.expected}`}`;
+    case "too_small":
+    case "too_big": {
+      const [bound, n] = issue.code === "too_small" ? ["at least", issue.minimum] : ["at most", issue.maximum];
+      if (issue.origin === "array") return `${given} needs ${bound} ${n} item${n == 1 ? "" : "s"}`;
+      if (issue.origin === "string") return `${given} needs ${bound} ${n} character${n == 1 ? "" : "s"}`;
+      return `${given} is too ${issue.code === "too_small" ? "small" : "large"} (${bound} ${n})`;
+    }
+    default:
+      return `${given}: ${issue.message}`;
+  }
+}
 function checkSpec(spec) {
   upgradeSpec(spec);
   const issues = [];
@@ -2702,13 +2737,16 @@ function checkSpec(spec) {
   if (root.type !== "Board") issues.push(`root must be a Board (got ${root.type})`);
   for (const [id, el] of Object.entries(spec.elements)) {
     const def = componentDefinitions[el.type];
+    const bad = /* @__PURE__ */ new Set();
+    const failed = (...keys) => keys.some((k) => bad.has(k));
     if (!def) {
       issues.push(`${id}: ${unknownComponentMessage(el.type, Object.keys(componentDefinitions))}`);
     } else {
       const parsed = def.props.safeParse(el.props ?? {});
       if (!parsed.success) {
         for (const i of parsed.error.issues) {
-          issues.push(`${id}.props${i.path.length ? "." + i.path.join(".") : ""}: ${listItemKindHint(el, i.path) ?? i.message}`);
+          if (i.path.length) bad.add(String(i.path[0]));
+          issues.push(`${id}.props${i.path.length ? "." + i.path.join(".") : ""}: ${listItemKindHint(el, i.path) ?? propIssueMessage(el.props ?? {}, i)}`);
         }
       }
       for (const key of Object.keys(el.props ?? {})) {
@@ -2726,7 +2764,7 @@ function checkSpec(spec) {
           continue;
         }
         if (!(key in def.props.shape)) {
-          const elsewhere = belongsElsewhere(el.type, key, true);
+          const elsewhere = belongsElsewhere(el.type, key, true, el.props[key]);
           issues.push(`${id}.props: ${el.type} has no prop "${key}"${elsewhere ? `: ${elsewhere}` : ""}`);
         }
       }
@@ -2747,50 +2785,50 @@ function checkSpec(spec) {
       const p = el.props ?? {};
       const { leading, trailing } = listItemEnds(p);
       const conflict = (prop, needs, kind, has) => issues.push(`${id}: ${prop} only shows with ${needs} (this item has ${kind}=${has}); remove one of them`);
-      if (p.leadingIcon && leading !== "icon") conflict("leadingIcon", "leading=icon", "leading", leading);
-      if (p.trailingIcon && trailing !== "icon") conflict("trailingIcon", "trailing=icon", "trailing", trailing);
-      if (p.trailingText && trailing !== "text" && trailing !== "badge") conflict("trailingText", "trailing=text or badge", "trailing", trailing);
+      if (p.leadingIcon && leading !== "icon" && !failed("leading")) conflict("leadingIcon", "leading=icon", "leading", leading);
+      if (p.trailingIcon && trailing !== "icon" && !failed("trailing")) conflict("trailingIcon", "trailing=icon", "trailing", trailing);
+      if (p.trailingText && trailing !== "text" && trailing !== "badge" && !failed("trailing")) conflict("trailingText", "trailing=text or badge", "trailing", trailing);
     }
     {
       const p = el.props ?? {};
-      const say = (msg) => issues.push(`${id}: ${msg}`);
+      const say = (msg, ...reads) => !failed(...reads) && issues.push(`${id}: ${msg}`);
       const backwards = (r) => Array.isArray(r) && r.length === 2 && r[0] > r[1];
       if (el.type === "Progress") {
-        if (p.step != null && p.steps == null) say(`step only shows with steps (e.g. steps=4 step=${p.step})`);
-        if (p.step != null && p.steps != null && p.step > p.steps) say(`step=${p.step} is past the last step (steps=${p.steps})`);
-        if (p.steps != null && p.shape === "circle") say("a stepper (steps) can't also be a circle; remove one of them");
+        if (p.step != null && p.steps == null) say(`step only shows with steps (e.g. steps=4 step=${typeof p.step === "number" ? p.step : 2})`);
+        if (p.step != null && p.steps != null && p.step > p.steps) say(`step=${p.step} is past the last step (steps=${p.steps})`, "step", "steps");
+        if (p.steps != null && p.shape === "circle") say("a stepper (steps) can't also be a circle; remove one of them", "shape");
       }
       if (el.type === "Pagination" && p.current != null && p.pages != null && p.current > p.pages) {
-        say(`current=${p.current} is past the last page (pages=${p.pages})`);
+        say(`current=${p.current} is past the last page (pages=${p.pages})`, "current", "pages");
       }
-      if (el.type === "Slider" && backwards(p.range)) say(`range=[${p.range.join(", ")}] goes backwards; write the smaller number first`);
+      if (el.type === "Slider" && backwards(p.range)) say(`range=[${p.range.join(", ")}] goes backwards; write the smaller number first`, "range");
       if (el.type === "Slider" && p.range && p.value != null) say("a slider has value (one handle) or range (two), not both");
       if (el.type === "Calendar") {
         const { days } = monthGrid(p.month);
         const all = [p.selected, ...p.range ?? [], ...p.marked ?? []].filter((d) => typeof d === "number");
         const late = all.find((d) => d > days);
-        if (late) say(`day ${late} isn't in ${p.month ?? "the month"} (it has ${days} days)`);
-        if (backwards(p.range)) say(`range=[${p.range.join(", ")}] goes backwards; write the earlier day first`);
+        if (late) say(`day ${late} isn't in ${p.month ?? "the month"} (it has ${days} days)`, "month", "selected", "range", "marked");
+        if (backwards(p.range)) say(`range=[${p.range.join(", ")}] goes backwards; write the earlier day first`, "range");
         if (p.range && p.selected != null) say("a calendar has selected (one day) or range (several), not both");
       }
       if (el.type === "Input" && p.type === "code" && p.value != null && String(p.value).length > (p.digits ?? 6)) {
-        say(`value has ${String(p.value).length} characters but the code has ${p.digits ?? 6} boxes (digits)`);
+        say(`value has ${String(p.value).length} characters but the code has ${p.digits ?? 6} boxes (digits)`, "type", "value", "digits");
       }
-      if (el.type === "Input" && p.digits != null && p.type !== "code") say("digits only applies to type=code");
-      if (el.type === "Input" && p.open && p.type !== "date") say("open shows a date picker, so it needs type=date");
-      if ((el.type === "Button" || el.type === "ListItem" || el.type === "NavBar") && p.open && !(Array.isArray(p.menu) && p.menu.length)) say("open shows the menu; add menu=[\u2026] with its items");
-      if (el.type === "Select" && p.open && !(Array.isArray(p.options) && p.options.length)) say("open shows the options list; add options=[\u2026] with the choices");
+      if (el.type === "Input" && p.digits != null && p.type !== "code") say("digits only applies to type=code", "type");
+      if (el.type === "Input" && p.open && p.type !== "date") say("open shows a date picker, so it needs type=date", "type");
+      if ((el.type === "Button" || el.type === "ListItem" || el.type === "NavBar") && p.open && !(Array.isArray(p.menu) && p.menu.length)) say("open shows the menu; add menu=[\u2026] with its items", "menu");
+      if (el.type === "Select" && p.open && !(Array.isArray(p.options) && p.options.length)) say("open shows the options list; add options=[\u2026] with the choices", "options");
     }
     if (el.type === "Table") {
       const { columns, data } = el.props ?? {};
       if (Array.isArray(columns) && Array.isArray(data)) {
-        const bad = data.map((row, i) => ({ row: i + 1, cells: Array.isArray(row) ? row.length : 1 })).filter((r) => r.cells !== columns.length);
-        if (bad.length) {
+        const bad2 = data.map((row, i) => ({ row: i + 1, cells: Array.isArray(row) ? row.length : 1 })).filter((r) => r.cells !== columns.length);
+        if (bad2.length) {
           const cells = (n) => `${n} cell${n === 1 ? "" : "s"}`;
-          const rows = bad.length === 1 ? `data row ${bad[0].row} has ${cells(bad[0].cells)}` : `data rows ${bad.map((r) => `${r.row} (${cells(r.cells)})`).join(", ")} don't match`;
+          const rows = bad2.length === 1 ? `data row ${bad2[0].row} has ${cells(bad2[0].cells)}` : `data rows ${bad2.map((r) => `${r.row} (${cells(r.cells)})`).join(", ")} don't match`;
           const hints = [
-            bad.some((r) => r.cells > columns.length) && `quote cells that contain a comma, e.g. ["$1,200", Paid]`,
-            bad.some((r) => r.cells < columns.length) && `use "" for an empty cell`
+            bad2.some((r) => r.cells > columns.length) && `quote cells that contain a comma, e.g. ["$1,200", Paid]`,
+            bad2.some((r) => r.cells < columns.length) && `use "" for an empty cell`
           ].filter(Boolean);
           issues.push(`${id}: Table has ${columns.length} columns, but ${rows} (${hints.join("; ")})`);
         }
@@ -2805,7 +2843,7 @@ function checkSpec(spec) {
     if (other) issues.push(`${key}: the id #${ref} is also used by ${spec.elements[other.key].type} "${other.key}"${other.id === ref ? "" : ` (as #${other.id}; ids ignore case)`}; ids must be unique`);
     else owners.set(ref.toLowerCase(), { key, id: ref });
   }
-  const written = [...owners.values()].map((o2) => o2.id);
+  const written2 = [...owners.values()].map((o2) => o2.id);
   const parentOf = /* @__PURE__ */ new Map();
   for (const [k, el] of Object.entries(spec.elements)) for (const c of el.children ?? []) parentOf.set(c, k);
   for (const [key, el] of Object.entries(spec.elements)) {
@@ -2825,9 +2863,9 @@ function checkSpec(spec) {
         }
         continue;
       }
-      const close = closeMatches(p[end], written);
+      const close = closeMatches(p[end], written2);
       issues.push(
-        `${key}: no element has the id #${p[end]}` + (close.length ? ` (did you mean ${close.map((c) => "#" + c).join(", ")}?)` : owners.size ? ` (ids on this board: ${written.map((c) => "#" + c).join(", ")})` : "; name an element by writing #name after it")
+        `${key}: no element has the id #${p[end]}` + (close.length ? ` (did you mean ${close.map((c) => "#" + c).join(", ")}?)` : owners.size ? ` (ids on this board: ${written2.map((c) => "#" + c).join(", ")})` : "; name an element by writing #name after it")
       );
     }
     if (typeof p.from === "string" && typeof p.to === "string" && p.from.toLowerCase() === p.to.toLowerCase()) issues.push(`${key}: a flow needs two different ends (both are #${p.from})`);
@@ -3212,6 +3250,11 @@ function wireframePrompt() {
     "You write low-fidelity UI wireframes as specs that a renderer turns into images.",
     "Reply with only the spec in a single code block, with no explanation.",
     "",
+    languageReference()
+  ].join("\n");
+}
+function languageReference() {
+  return [
     TEXT_FORMAT,
     "",
     RULES,
@@ -3263,5 +3306,6 @@ export {
   printWireframeText,
   componentDocs,
   wireframePrompt,
+  languageReference,
   repairPrompt
 };

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   printWireframeText,
   renderWireframe,
   wireframePrompt
-} from "./chunks/chunk-HDSKRKDL.js";
+} from "./chunks/chunk-ZLVSCEWO.js";
 
 // src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";

package/dist/escape.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Escaping for HTML attribute values, shared by the playground's Copy link → HTML and the MCP
+ * share tool, so the two give the same <img> tag. & first, or the entities it adds get escaped again.
+ */
+export declare const escapeAttr: (s: string) => string;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { renderWireframe, compileWireframe, formatIssues, WireframeError, type C
 export { wireframePrompt, repairPrompt } from "./prompt.js";
 export { printWireframeText as formatWireframe } from "./print.js";
 export { encodeWireframe, decodeWireframe, MAX_SHARED_TEXT } from "./share.js";
+export { mcpTools, MCP_INSTRUCTIONS, LINK_KINDS, DEFAULT_LINKS, type LinkKind, wireframeGuide, renderWireframeTool, shareWireframeTool, callMcpTool, type ToolResult, type ToolContent, type ToolOptions, type McpToolName } from "./mcp.js";
 export { upgradeWireframe, upgradeSpec, RENAMED_PROPS, type UpgradeOptions } from "./upgrade.js";
 export { renderWireframeSvg, renderWireframePng, checkSpec, boardSize, boardLayout, type BoardItem, type RenderWireframeOptions } from "./render.js";
 export { parseWireframeText, type TextIssue, type ParseResult } from "./text.js";

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   compileWireframe,
   componentDefinitions,
   formatIssues,
+  languageReference,
   parseWireframeText,
   printWireframeText,
   registry,
@@ -20,7 +21,7 @@ import {
   upgradeSpec,
   upgradeWireframe,
   wireframePrompt
-} from "./chunks/chunk-HDSKRKDL.js";
+} from "./chunks/chunk-ZLVSCEWO.js";
 
 // src/share.ts
 import { deflateRawSync, inflateRawSync } from "node:zlib";
@@ -32,22 +33,145 @@ var isLinkData = (data) => data.startsWith(LINK_PREFIX) || data.startsWith(LEGAC
 
 // src/share.ts
 var MAX_SHARED_TEXT = 64e3;
-function encodeWireframe(text) {
-  return LINK_PREFIX + deflateRawSync(Buffer.from(text, "utf8"), { level: 9 }).toString("base64url");
+function encodeWireframe(text2) {
+  return LINK_PREFIX + deflateRawSync(Buffer.from(text2, "utf8"), { level: 9 }).toString("base64url");
 }
 function decodeWireframe(data) {
   const prefix = data.slice(0, 1);
   if (!isLinkData(data)) throw new Error(`unknown encoding "${prefix}" (expected a "${LINK_PREFIX}" or "${LEGACY_LINK_PREFIX}" prefix)`);
-  const text = inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
-  return upgradeWireframe(text, { fromLink: prefix === LEGACY_LINK_PREFIX });
+  const text2 = inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
+  return upgradeWireframe(text2, { fromLink: prefix === LEGACY_LINK_PREFIX });
+}
+
+// src/mcp.ts
+import { z } from "zod";
+
+// src/escape.ts
+var escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/[\r\n]+/g, " ");
+
+// src/mcp.ts
+var MODEL_IMAGE_MAX = 1600;
+var MAX_IMAGE_LINK_DATA = 16e3;
+var DEFAULT_BASE = "https://tsquare.dev";
+var MCP_INSTRUCTIONS = "tsquare draws low-fidelity UI wireframes from a small text language: multi-screen boards with notes and flow arrows, grayscale by default. Call wireframe_guide once before writing your first wireframe, then render_wireframe to check and see it, and share_wireframe to give the user links.";
+var textInput = z.string().max(MAX_SHARED_TEXT).describe("The wireframe in tsquare text (a ```tsquare code fence around it is fine).");
+var flowsInput = z.boolean().optional().describe("Draw flow arrows (default true). false leaves them out, as if there were no flow lines.");
+var LINK_KINDS = ["share", "svg", "png", "markdown", "html"];
+var DEFAULT_LINKS = ["svg", "share"];
+var LINK_LABELS = {
+  share: "Share link (opens it in the playground to view and edit)",
+  svg: "Image link (SVG)",
+  png: "Image link (PNG)",
+  markdown: "Markdown",
+  html: "HTML"
+};
+var linksInput = z.array(z.enum(LINK_KINDS)).min(1).optional().describe(
+  "Which links to return; ask only for what the user needs, since each link is long. share: open and edit it in the playground. svg: an image link to view or embed (Notion, GitHub, docs). png: an image link for tools that don't show SVG. markdown: an image for READMEs and docs. html: an <img> tag for web pages. Default [svg, share]."
+);
+var GUIDE_HEADER = `# Writing tsquare wireframes
+
+Workflow:
+1. Write the wireframe text for the user's request, following the language below.
+2. Call render_wireframe with it. If it reports problems, fix every line it names and render again.
+3. Look at the image for what the checker can't see: content cut off at the bottom of a screen (make the screen taller with height=\u2026 or remove content), cramped rows, text that wraps badly. Fix and render again.
+4. Call share_wireframe with only the links the user needs (links=[\u2026]; by default an image link and the share link to edit it), and give them to the user exactly as returned: each link carries the whole wireframe, so one changed character breaks it. Show the wireframe text too, in a \`\`\`tsquare code block, so they can keep it.
+`;
+var mcpTools = {
+  wireframe_guide: {
+    title: "tsquare language guide",
+    description: "How to write a tsquare wireframe: the text format, the rules, a worked example and every component with its props. Call it once before writing your first wireframe.",
+    inputSchema: z.object({}),
+    annotations: { readOnlyHint: true, openWorldHint: false }
+  },
+  render_wireframe: {
+    title: "Render a wireframe",
+    description: "Check tsquare wireframe text and render it. Returns a PNG of the board so you can see it, or the problems by line number (with the valid options) if the text isn't valid. Fix every problem and call it again.",
+    inputSchema: z.object({ text: textInput, flows: flowsInput }),
+    annotations: { readOnlyHint: true, openWorldHint: false }
+  },
+  share_wireframe: {
+    title: "Share a wireframe",
+    description: "Links for valid tsquare wireframe text, the same kinds as the playground's Copy link menu: a share link to edit it in the playground, image links (SVG, PNG), Markdown and HTML. Ask only for the links the user needs (default: an SVG image link and the share link). Each link contains the whole wireframe text (compressed), so anyone with a link can read it.",
+    inputSchema: z.object({ text: textInput, flows: flowsInput, links: linksInput }),
+    annotations: { readOnlyHint: true, openWorldHint: false }
+  }
+};
+var text = (t) => ({ type: "text", text: t });
+var problems = (issues) => ({
+  content: [text(`The wireframe has ${issues.length} problem${issues.length === 1 ? "" : "s"}. Fix each line and try again.
+${formatIssues(issues)}`)],
+  isError: true
+});
+function wireframeGuide() {
+  return { content: [text(`${GUIDE_HEADER}
+${languageReference()}`)] };
+}
+async function renderWireframeTool(args) {
+  const { spec, issues } = compileWireframe(args.text);
+  if (!spec || issues.length) return problems(issues);
+  const flows = args.flows !== false;
+  const { width, height } = boardSize(spec, { flows });
+  const scale = Math.min(1, MODEL_IMAGE_MAX / Math.max(width, height));
+  const png = await renderWireframePng(spec, { skipValidation: true, flows, scale });
+  const shown = scale < 1 ? `, shown at ${Math.round(width * scale)}\xD7${Math.round(height * scale)}` : "";
+  return {
+    content: [
+      text(`Valid. The board is ${width}\xD7${height}${shown}. Check the image for clipped or cramped content, then call share_wireframe for links.`),
+      { type: "image", data: Buffer.from(png).toString("base64"), mimeType: "image/png" }
+    ]
+  };
+}
+function shareWireframeTool(args, opts = {}) {
+  const { spec, issues } = compileWireframe(args.text);
+  if (!spec || issues.length) return problems(issues);
+  const base = (opts.base ?? DEFAULT_BASE).replace(/\/+$/, "");
+  const bare = args.text.replace(/^[ \t]*```.*(\r?\n|$)/gm, "").trim() + "\n";
+  if (Buffer.byteLength(bare, "utf8") > MAX_SHARED_TEXT)
+    return { content: [text(`This wireframe is too long to share as a link (over ${MAX_SHARED_TEXT / 1e3} KB of text). Split it into smaller boards.`)], isError: true };
+  const data = encodeWireframe(bare);
+  const query = args.flows === false ? "?flows=0" : "";
+  const title = String(spec.elements[spec.root]?.props?.title ?? "Wireframe");
+  const kinds = [...new Set(args.links?.length ? args.links : DEFAULT_LINKS)];
+  const share = `${base}/playground#${data}`;
+  const lines = [];
+  const notes = ["Give each link exactly as written: it carries the whole wireframe, so anyone with it can read the wireframe, and one changed character breaks it."];
+  if (data.length > MAX_IMAGE_LINK_DATA && kinds.some((k) => k !== "share")) {
+    if (!kinds.includes("share")) kinds.unshift("share");
+    notes.unshift("This wireframe is too long for an image link, so only the share link is included. To get image links, split it into smaller boards.");
+  }
+  const svg = `${base}/svg/${data}${query}`;
+  for (const kind of kinds) {
+    if (kind !== "share" && data.length > MAX_IMAGE_LINK_DATA) continue;
+    const link = {
+      share,
+      svg,
+      png: `${base}/png/${data}${query}`,
+      markdown: `![${title.replace(/[[\]\n]/g, " ")}](${svg})`,
+      html: `<img src="${svg}" alt="${escapeAttr(title)}">`
+    }[kind];
+    lines.push(`${LINK_LABELS[kind]}: ${link}`);
+  }
+  return { content: [text([...lines, "", ...notes].join("\n"))] };
+}
+async function callMcpTool(name, args = {}, opts = {}) {
+  if (name === "wireframe_guide") return wireframeGuide();
+  if (name !== "render_wireframe" && name !== "share_wireframe")
+    return { content: [text(`Unknown tool "${name}". Tools: ${Object.keys(mcpTools).join(", ")}.`)], isError: true };
+  const parsed = mcpTools[name].inputSchema.safeParse(args);
+  if (!parsed.success) return { content: [text(`Invalid arguments: ${z.prettifyError(parsed.error)}`)], isError: true };
+  return name === "render_wireframe" ? renderWireframeTool(parsed.data) : shareWireframeTool(parsed.data, opts);
 }
 export {
+  DEFAULT_LINKS,
   DEVICES,
+  LINK_KINDS,
   MAX_SHARED_TEXT,
+  MCP_INSTRUCTIONS,
   RENAMED_PROPS,
   WireframeError,
   boardLayout,
   boardSize,
+  callMcpTool,
   catalog,
   checkSpec,
   compileWireframe,
@@ -56,14 +180,18 @@ export {
   encodeWireframe,
   formatIssues,
   printWireframeText as formatWireframe,
+  mcpTools,
   parseWireframeText,
   registry,
   renderWireframe,
   renderWireframePng,
   renderWireframeSvg,
+  renderWireframeTool,
   repairPrompt,
+  shareWireframeTool,
   theme,
   upgradeSpec,
   upgradeWireframe,
+  wireframeGuide,
   wireframePrompt
 };

package/dist/mcp.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The MCP tools (guide, render, share) as plain functions, with no MCP SDK: tsquare.dev wraps them
+ * in its hosted endpoint (tsquare.dev/mcp), and a local stdio server can reuse them unchanged.
+ *
+ * Results use the MCP tool-result shape ({ content, isError }), so a server returns them as they are.
+ * Problems come back as a result with isError, not a thrown error, so the model reads them and fixes
+ * its text: the messages are the same line-numbered ones `tsquare check` prints.
+ */
+import { z } from "zod";
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface ToolResult {
+    content: ToolContent[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolOptions {
+    /** Where share and image links point (default https://tsquare.dev). */
+    base?: string;
+}
+/** Longest side of the PNG a model gets back. Models downscale anything bigger, and it keeps the result small. */
+export declare const MODEL_IMAGE_MAX = 1600;
+/** Longest image link the site serves (its render URLs cap the data at this many characters). */
+export declare const MAX_IMAGE_LINK_DATA = 16000;
+/** Short server instructions: what the tools are for and the order to use them in. */
+export declare const MCP_INSTRUCTIONS: string;
+/** The link kinds share_wireframe offers: the playground's Copy link menu, with the same names. */
+export declare const LINK_KINDS: readonly ["share", "svg", "png", "markdown", "html"];
+export type LinkKind = (typeof LINK_KINDS)[number];
+/** What a plain "share it" gets: one image link and the link to edit it. */
+export declare const DEFAULT_LINKS: LinkKind[];
+export declare const mcpTools: {
+    readonly wireframe_guide: {
+        readonly title: "tsquare language guide";
+        readonly description: "How to write a tsquare wireframe: the text format, the rules, a worked example and every component with its props. Call it once before writing your first wireframe.";
+        readonly inputSchema: z.ZodObject<{}, z.core.$strip>;
+        readonly annotations: {
+            readonly readOnlyHint: true;
+            readonly openWorldHint: false;
+        };
+    };
+    readonly render_wireframe: {
+        readonly title: "Render a wireframe";
+        readonly description: "Check tsquare wireframe text and render it. Returns a PNG of the board so you can see it, or the problems by line number (with the valid options) if the text isn't valid. Fix every problem and call it again.";
+        readonly inputSchema: z.ZodObject<{
+            text: z.ZodString;
+            flows: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        readonly annotations: {
+            readonly readOnlyHint: true;
+            readonly openWorldHint: false;
+        };
+    };
+    readonly share_wireframe: {
+        readonly title: "Share a wireframe";
+        readonly description: "Links for valid tsquare wireframe text, the same kinds as the playground's Copy link menu: a share link to edit it in the playground, image links (SVG, PNG), Markdown and HTML. Ask only for the links the user needs (default: an SVG image link and the share link). Each link contains the whole wireframe text (compressed), so anyone with a link can read it.";
+        readonly inputSchema: z.ZodObject<{
+            text: z.ZodString;
+            flows: z.ZodOptional<z.ZodBoolean>;
+            links: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                html: "html";
+                markdown: "markdown";
+                png: "png";
+                share: "share";
+                svg: "svg";
+            }>>>;
+        }, z.core.$strip>;
+        readonly annotations: {
+            readonly readOnlyHint: true;
+            readonly openWorldHint: false;
+        };
+    };
+};
+export type McpToolName = keyof typeof mcpTools;
+/** The wireframe_guide tool: workflow plus the language reference. */
+export declare function wireframeGuide(): ToolResult;
+/** The render_wireframe tool: a PNG sized for a model to look at, or line-numbered problems. */
+export declare function renderWireframeTool(args: {
+    text: string;
+    flows?: boolean;
+}): Promise<ToolResult>;
+/** The share_wireframe tool: image and playground links, computed locally (nothing is sent anywhere). */
+export declare function shareWireframeTool(args: {
+    text: string;
+    flows?: boolean;
+    links?: LinkKind[];
+}, opts?: ToolOptions): ToolResult;
+/** Run a tool by name, for servers that dispatch by name. Unknown names come back as an error result. */
+export declare function callMcpTool(name: string, args?: Record<string, unknown>, opts?: ToolOptions): Promise<ToolResult>;

package/dist/playground/index.js

@@ -13,7 +13,7 @@ import {
   renderWireframeSvg,
   takesUniversalProps,
   wireframePrompt
-} from "../chunks/chunk-HDSKRKDL.js";
+} from "../chunks/chunk-ZLVSCEWO.js";
 
 // src/playground/index.ts
 import { createServer } from "node:http";