tsquare 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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.
+
 ## 0.6.0
 
 ### Flow arrows

package/dist/chunks/{chunk-HDSKRKDL.js → chunk-Z4RBFAOM.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();
@@ -2726,7 +2729,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}` : ""}`);
         }
       }
@@ -3212,6 +3215,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 +3271,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-Z4RBFAOM.js";
 
 // src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";

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, 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,27 +21,138 @@ import {
   upgradeSpec,
   upgradeWireframe,
   wireframePrompt
-} from "./chunks/chunk-HDSKRKDL.js";
+} from "./chunks/chunk-Z4RBFAOM.js";
 
 // src/share.ts
 import { deflateRawSync, inflateRawSync } from "node:zlib";
+
+// src/link-prefix.ts
+var LINK_PREFIX = "y";
+var LEGACY_LINK_PREFIX = "z";
+var isLinkData = (data) => data.startsWith(LINK_PREFIX) || data.startsWith(LEGACY_LINK_PREFIX);
+
+// src/share.ts
 var MAX_SHARED_TEXT = 64e3;
-function encodeWireframe(text) {
-  return "y" + 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 (prefix !== "y" && prefix !== "z") throw new Error(`unknown encoding "${prefix}" (expected a "y" or "z" prefix)`);
-  const text = inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
-  return upgradeWireframe(text, { fromLink: prefix === "z" });
+  if (!isLinkData(data)) throw new Error(`unknown encoding "${prefix}" (expected a "${LINK_PREFIX}" or "${LEGACY_LINK_PREFIX}" 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";
+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 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 and give the user the links: the image link to look at or embed, and the playground link to edit. 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: an image link (SVG or PNG) to show or embed in Markdown, Notion or docs, and a playground link to edit it. The links contain the wireframe text itself (compressed), so anyone with a link can read it.",
+    inputSchema: z.object({ text: textInput, flows: flowsInput }),
+    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").replace(/[[\]\n]/g, " ");
+  const playground = `${base}/playground#${data}`;
+  if (data.length > MAX_IMAGE_LINK_DATA)
+    return { content: [text(`Playground (to view and edit): ${playground}
+
+This wireframe is too long for an image link; the playground link still works. To get image links, split it into smaller boards.`)] };
+  const svg = `${base}/svg/${data}${query}`;
+  const png = `${base}/png/${data}${query}`;
+  return {
+    content: [
+      text(
+        [
+          `Image (SVG): ${svg}`,
+          `Image (PNG): ${png}`,
+          `Playground (to view and edit): ${playground}`,
+          `Markdown: ![${title}](${svg})`,
+          "",
+          "The links contain the wireframe text, so anyone with a link can read it."
+        ].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 {
   DEVICES,
   MAX_SHARED_TEXT,
+  MCP_INSTRUCTIONS,
   RENAMED_PROPS,
   WireframeError,
   boardLayout,
   boardSize,
+  callMcpTool,
   catalog,
   checkSpec,
   compileWireframe,
@@ -49,14 +161,18 @@ export {
   encodeWireframe,
   formatIssues,
   printWireframeText as formatWireframe,
+  mcpTools,
   parseWireframeText,
   registry,
   renderWireframe,
   renderWireframePng,
   renderWireframeSvg,
+  renderWireframeTool,
   repairPrompt,
+  shareWireframeTool,
   theme,
   upgradeSpec,
   upgradeWireframe,
+  wireframeGuide,
   wireframePrompt
 };

package/dist/link-prefix.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Link prefixes (see share.ts): the letter in front of a link's data names the language version
+ * its text was written in. Shared by the library and the playground's browser code, so a new
+ * prefix can't be added to one and missed in the other.
+ */
+/** What links are made with today: 0.6.0 and later. */
+export declare const LINK_PREFIX = "y";
+/** Links made before 0.6.0; decoded with the old rules (upgradeWireframe's fromLink). */
+export declare const LEGACY_LINK_PREFIX = "z";
+/** Whether `data` (a render URL's path segment or a share link's fragment, without "#") is link data. */
+export declare const isLinkData: (data: string) => boolean;

package/dist/mcp.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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;
+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: an image link (SVG or PNG) to show or embed in Markdown, Notion or docs, and a playground link to edit it. The links contain the wireframe text itself (compressed), so anyone with a link can read it.";
+        readonly inputSchema: z.ZodObject<{
+            text: z.ZodString;
+            flows: z.ZodOptional<z.ZodBoolean>;
+        }, 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;
+}, 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-Z4RBFAOM.js";
 
 // src/playground/index.ts
 import { createServer } from "node:http";