iterate_screen

Instructions

Implementation Reference

• src/server.ts:182-223 (handler)

  handleIterate function is the main handler for the 'iterate_screen' tool. It fetches the original screen by ID, reads its previous HTML, calls generateScreen with feedback to produce an iteration, renders the HTML to PNG, saves the new screen, and returns the image along with a summary.

  async function handleIterate(input: z.infer<typeof iterateInput>) {
    const original = await getScreen(input.screen_id);
    if (!original) throw new Error(`Screen not found: ${input.screen_id}`);
    const previousHtml = await readHtml(original);
  
    const result = await generateScreen({
      prompt: original.prompt,
      designSystem: original.designSystem,
      feedback: input.feedback,
      previousHtml,
    });
    const render = await renderHtml(result.html);
    const saved = await saveScreen({
      project: original.project,
      name: input.name ?? `${original.name} (v2)`,
      prompt: original.prompt,
      designSystem: original.designSystem,
      html: result.html,
      png: render.png,
      parentId: original.id,
      tokens: {
        input: result.inputTokens,
        output: result.outputTokens,
        cacheRead: result.cacheReadTokens,
      },
      model: result.model,
    });
  
    return {
      content: [
        {
          type: "image" as const,
          data: render.png.toString("base64"),
          mimeType: "image/png",
        },
        {
          type: "text" as const,
          text: summarize(saved, render, { iteratedFrom: original.id, result }),
        },
      ],
    };
  }

• src/server.ts:31-35 (schema)

  iterateInput Zod schema defining the input parameters for the iterate_screen tool: screen_id (string, required), feedback (string, required), and name (string, optional).

  const iterateInput = z.object({
    screen_id: z.string().describe("ID of the screen to iterate on (from generate_screen output)."),
    feedback: z.string().describe("What to change: 'make the hero card larger', 'use orange accent instead of blue', etc."),
    name: z.string().optional().describe("Optional new name for the iteration. Defaults to original name + ' (v2)'."),
  });

• src/server.ts:55-60 (registration)

  Tool registration entry for 'iterate_screen' with its description and inputSchema in the TOOLS array.

  {
    name: "iterate_screen",
    description:
      "Refine an existing generated screen based on feedback. Use this for follow-up edits like 'change color', 'add a section', 'make it more spacious'.",
    inputSchema: zodToJson(iterateInput),
  },

• src/server.ts:126-127 (registration)

  Switch-case dispatch routing 'iterate_screen' calls to the handleIterate function.

  case "iterate_screen":
    return await handleIterate(iterateInput.parse(args));

• src/system-prompt.ts:96-118 (helper)

  buildUserPrompt helper that constructs the prompt for iteration: includes previous HTML and revision feedback when feedback/previousHtml are provided.

  export function buildUserPrompt(input: {
    prompt: string;
    designSystem?: string;
    feedback?: string;
    previousHtml?: string;
  }): string {
    const parts: string[] = [];
  
    if (input.designSystem) {
      parts.push("## DESIGN SYSTEM\n\n" + input.designSystem.trim());
    }
  
    if (input.previousHtml && input.feedback) {
      parts.push("## PREVIOUS VERSION\n\n```html\n" + input.previousHtml.trim() + "\n```");
      parts.push("## REVISION FEEDBACK\n\n" + input.feedback.trim());
      parts.push("Output the revised HTML following the same scaffold. Apply the feedback precisely.");
    } else {
      parts.push("## SCREEN BRIEF\n\n" + input.prompt.trim());
      parts.push("Output the complete self-contained HTML for this screen.");
    }
  
    return parts.join("\n\n");
  }