better-design 0.11.0 → 0.12.0

package/README.md

@@ -25,8 +25,7 @@ The server exposes MCP tools only; it does not register prompts.
 | `find-design-system` | Start any UI build by searching the catalog for visual foundations, or browse and compare existing systems. Returns IDs and the build/review guardrails needed for the next step. |
 | `create-design-system` | Start a custom design system generation job. |
 | `get-design-system-status` | Poll a generated design system and return the install command when ready. |
-| `draw-illustration` | Draw an original SVG illustration for a screen: an empty state, a hero object, a container something drops into. Uses the caller's brand colours when a `projectId` is passed, and returns named layers so parts can animate. Drawing runs in the background. |
-| `get-illustration-status` | Collect a drawing started by `draw-illustration`. Returns the complete svg and its layer names once ready. |
+| `review-illustration` | Render an SVG illustration you drew, look at it, and report what is visibly wrong |
 | `get-design-system-kit` | Return the correct implementation kit through one entry point. Use `target: "react"` in coding hosts for shadcn install commands and real components; use `target: "html"` only in inline canvases/artifacts for the framework-free HTML/CSS kit. Accepts a catalog `designSystemId`, or a generated `projectId` for the HTML target. Base UI is the default React flavor; pass `library: "radix"` when the project already uses Radix. |
 | `preview-design-system` | Return a token-true visual preview for a catalog design system. |
 | `get-ui-principle` | Load or search visual UI principles. |

package/dist/index.js

@@ -6673,6 +6673,19 @@ var init_extract_tools = __esm({
 
 // ../shared/src/mcp/tools/illustration-tools.ts
 import { z as z7 } from "zod";
+function fail(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    structuredContent: {
+      faults: [message],
+      layers: [],
+      reviewed: false,
+      unseen: true,
+      reviewToken: "",
+      message
+    }
+  };
+}
 function registerIllustrationTools({ server, track, tracked, authContext }) {
   const authHeaders2 = () => {
     const headers = { "Content-Type": "application/json" };
@@ -6683,215 +6696,104 @@ function registerIllustrationTools({ server, track, tracked, authContext }) {
     return headers;
   };
   server.registerTool(
-    "draw-illustration",
+    "review-illustration",
     {
-      title: "Draw an Illustration",
-      description: `Draw an original SVG illustration for a UI surface: an empty state, a hero object, a container something drops into.
+      title: "Review an Illustration",
+      description: `Look at an SVG illustration you drew and get back what is visibly wrong with it.
 
-Use this whenever a screen needs a picture and you would otherwise leave a placeholder box, an emoji, or a stock icon standing in for artwork.
+You write SVG blind. This renders it in a real browser and judges it against this project's illustration principles, so you find out that a shape does not close, a part floats unattached, the light comes from two directions, or contents sit outside the container meant to hold them.
 
-The drawing is original, follows this project's illustration principles (light from one direction, seated shadows, containers split into back and front layers), and arrives in named layers so you can animate its parts.
+Use it whenever you have drawn an illustration, before you hand it to anyone. Drawing something worth shipping usually takes 2 or 3 rounds.
 
 How to call it:
-1. \`draw-illustration({ prompt: "something for the empty inbox screen" })\`. Write the prompt the way a person would ask; it does not need art direction.
-2. Pass \`projectId\` when the caller has a generated design system, and the drawing uses their brand colours. Without it the drawing uses neutral colours.
-3. Wait about a minute, then call \`get-illustration-status\` with the returned id to collect the finished svg.
+1. Get the rules first with \`get-ui-principle({ topic: "svg-illustration" })\` and draw against them.
+2. \`review-illustration({ svg, intent: "an open inbox tray with letters" })\`. Say what the drawing is meant to be, in your own words.
+3. Fix what \`faults\` names, then call again passing \`reviewToken\` back. Reviewing the same drawing again costs nothing while that token is valid.
+4. Stop when \`faults\` is empty.
 
-Subjects: objects, tools, containers and scenes. People and faces are declined, because the principles this draws from do not cover them.`,
+Markup carrying script, event handlers, remote references, or styles that reach outside the drawing is refused rather than cleaned, so the drawing you fix is the drawing you sent.`,
       inputSchema: z7.object({
-        prompt: z7.string().min(1).describe('What the screen needs, in plain words. For example "something for the empty inbox screen".'),
-        projectId: z7.string().optional().describe("Generated project id from create-design-system. Supplies the brand palette."),
-        style: z7.enum(STYLES).optional().describe("flat, soft-depth or glossy. Defaults to the design system's character, or soft-depth."),
-        animated: z7.boolean().optional().describe("When true, the svg ships with entrance and ambient motion, and a reduced-motion off switch.")
+        svg: z7.string().min(1).describe("The complete svg element you drew."),
+        intent: z7.string().min(1).describe('What it is meant to be, in plain words. For example "an open inbox tray with letters".'),
+        animated: z7.boolean().optional().describe("Set when the drawing was meant to move, so the motion checks apply."),
+        reviewToken: z7.string().optional().describe("The token from a previous review of this drawing. Reviews it again free.")
       }),
-      outputSchema: DRAW_OUTPUT_SCHEMA
+      outputSchema: REVIEW_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true }
     },
-    async ({ prompt, projectId, style, animated }) => tracked("draw-illustration", { query: prompt, hasProject: Boolean(projectId), style, animated }, async () => {
-      const startUrl = `${APP_BASE_URL}/api/illustrations`;
-      try {
-        const res = await fetch(startUrl, {
-          method: "POST",
-          headers: authHeaders2(),
-          signal: AbortSignal.timeout(15e3),
-          body: JSON.stringify({ prompt, projectId, style, animated: animated ?? false })
-        });
-        if (!res.ok) {
-          const detail = await res.text().catch(() => "");
+    async ({
+      svg,
+      intent,
+      animated,
+      reviewToken
+    }) => tracked(
+      "review-illustration",
+      { query: intent, animated, repeat: Boolean(reviewToken) },
+      async () => {
+        try {
+          const res = await fetch(`${APP_BASE_URL}/api/illustrations/review`, {
+            method: "POST",
+            headers: authHeaders2(),
+            signal: AbortSignal.timeout(6e4),
+            body: JSON.stringify({ svg, intent, animated: animated ?? false, reviewToken })
+          });
+          if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            return fail(`Could not review that drawing (HTTP ${res.status}). ${detail.slice(0, 300)}`);
+          }
+          const body = await res.json();
+          const faults = body.faults ?? [];
+          const layers = body.layers ?? [];
+          const message = !body.reviewed ? faults[0] ?? "That drawing was not reviewed." : faults.length === 0 ? "Nothing visibly wrong. The drawing is ready to use." : [
+            `${faults.length} thing${faults.length === 1 ? "" : "s"} to fix:`,
+            ...faults.map((f) => `- ${f}`),
+            body.unseen ? "The drawing could not be rendered, so only its structure was checked." : "",
+            body.reviewToken ? "Fix these and call again with the same reviewToken, which costs nothing." : "Fix these and call again."
+          ].filter(Boolean).join("\n");
           return {
             content: [
               {
                 type: "text",
-                text: `Could not start the drawing (HTTP ${res.status}). ${detail.slice(0, 400)}`
+                text: layers.length ? `${message}
+
+Layers, in paint order: ${layers.join(", ")}.` : message
               }
             ],
             structuredContent: {
-              status: "error",
-              illustrationId: "",
-              svg: "",
-              layers: [],
-              subject: "",
-              message: `Could not start the drawing (HTTP ${res.status}).`
-            }
-          };
-        }
-        const body = await res.json();
-        if (!body.id) {
-          return {
-            content: [{ type: "text", text: "The drawing service did not return an id." }],
-            structuredContent: {
-              status: "error",
-              illustrationId: "",
-              svg: "",
-              layers: [],
-              subject: "",
-              message: "The drawing service did not return an id."
-            }
-          };
-        }
-        const next = `Drawing started. Wait about a minute, then call get-illustration-status with id ${body.id}.`;
-        return {
-          content: [{ type: "text", text: next }],
-          structuredContent: {
-            status: "drawing",
-            illustrationId: body.id,
-            svg: "",
-            layers: [],
-            subject: "",
-            message: next
-          }
-        };
-      } catch (err) {
-        const message = `Could not reach the drawing service: ${err instanceof Error ? err.message : String(err)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          structuredContent: {
-            status: "error",
-            illustrationId: "",
-            svg: "",
-            layers: [],
-            subject: "",
-            message
-          }
-        };
-      }
-    })
-  );
-  server.registerTool(
-    "get-illustration-status",
-    {
-      title: "Get Illustration Status",
-      description: `Collect a drawing started by draw-illustration.
-
-Call this about a minute after starting. While it is still drawing, wait and call again rather than starting a second drawing.
-
-When ready, \`svg\` holds the complete element: paste it into a component as it is. \`layers\` names the groups in paint order, so you know which part to animate. For a container, the back group renders behind whatever falls in and the front group in front of it, which is what makes something look like it landed inside.`,
-      inputSchema: z7.object({
-        illustrationId: z7.string().min(1).describe("The id returned by draw-illustration.")
-      }),
-      outputSchema: DRAW_OUTPUT_SCHEMA,
-      annotations: { readOnlyHint: true }
-    },
-    async ({ illustrationId }) => tracked("get-illustration-status", { illustrationId }, async () => {
-      try {
-        const res = await fetch(`${APP_BASE_URL}/api/illustrations/${illustrationId}`, {
-          headers: authHeaders2(),
-          signal: AbortSignal.timeout(15e3)
-        });
-        if (!res.ok) {
-          const message = `Could not read that drawing (HTTP ${res.status}).`;
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: {
-              status: "error",
-              illustrationId,
-              svg: "",
-              layers: [],
-              subject: "",
-              message
-            }
-          };
-        }
-        const body = await res.json();
-        if ((body.status === "ready" || body.status === "partial") && body.svg) {
-          const layers = body.layers ?? [];
-          const partial = body.status === "partial";
-          const summary = [
-            partial ? `Drawing done, with reservations: ${body.subject ?? "illustration"}. It ran out of correction passes, so look it over before shipping it.` : `Drawing ready: ${body.subject ?? "illustration"}.`,
-            layers.length ? `Layers, in paint order: ${layers.join(", ")}.` : "",
-            "Paste the svg into a component. Keep the group ids so parts stay animatable."
-          ].filter(Boolean).join(" ");
-          return {
-            content: [{ type: "text", text: `${summary}
-
-${body.svg}` }],
-            structuredContent: {
-              status: partial ? "partial" : "ready",
-              illustrationId,
-              svg: body.svg,
+              faults,
               layers,
-              subject: body.subject ?? "",
-              message: summary
-            }
-          };
-        }
-        if (body.status === "error") {
-          const message = body.error ?? "The drawing failed.";
-          return {
-            content: [{ type: "text", text: message }],
-            structuredContent: {
-              status: "error",
-              illustrationId,
-              svg: "",
-              layers: [],
-              subject: "",
+              reviewed: body.reviewed ?? false,
+              unseen: body.unseen ?? false,
+              reviewToken: body.reviewToken ?? "",
               message
             }
           };
+        } catch (err) {
+          return fail(
+            `Could not reach the review service: ${err instanceof Error ? err.message : String(err)}`
+          );
         }
-        const waiting = "Still drawing. Wait another thirty seconds and call this again.";
-        return {
-          content: [{ type: "text", text: waiting }],
-          structuredContent: {
-            status: "drawing",
-            illustrationId,
-            svg: "",
-            layers: [],
-            subject: "",
-            message: waiting
-          }
-        };
-      } catch (err) {
-        const message = `Could not reach the drawing service: ${err instanceof Error ? err.message : String(err)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          structuredContent: {
-            status: "error",
-            illustrationId,
-            svg: "",
-            layers: [],
-            subject: "",
-            message
-          }
-        };
       }
-    })
+    )
   );
   void track;
 }
-var STYLES, DRAW_OUTPUT_SCHEMA;
+var REVIEW_OUTPUT_SCHEMA;
 var init_illustration_tools = __esm({
   "../shared/src/mcp/tools/illustration-tools.ts"() {
     "use strict";
     init_shared();
-    STYLES = ["flat", "soft-depth", "glossy"];
-    DRAW_OUTPUT_SCHEMA = {
-      status: z7.enum(["drawing", "ready", "partial", "error"]),
-      illustrationId: z7.string(),
-      /** Present once ready. The complete svg element, ready to paste. */
-      svg: z7.string(),
+    REVIEW_OUTPUT_SCHEMA = {
+      /** Empty when nothing is visibly wrong. */
+      faults: z7.array(z7.string()),
       /** Group ids in paint order, the parts an animation can target. */
       layers: z7.array(z7.string()),
-      subject: z7.string(),
+      /** False when the markup was refused; faults says why. */
+      reviewed: z7.boolean(),
+      /** True when the drawing could not be rendered, so only structure was checked. */
+      unseen: z7.boolean(),
+      /** Pass this back to review the same drawing again without spending another credit. */
+      reviewToken: z7.string(),
       message: z7.string()
     };
   }