fresnel-icon 0.1.0 → 0.2.0

package/dist/cli.js

@@ -23,6 +23,8 @@ function appearanceKeys(a) {
     case "tinted-light":
     case "tinted-dark":
       return ["tinted"];
+    case "default":
+      return ["light"];
     default:
       return [];
   }
@@ -101,6 +103,9 @@ function normalizeColorInput(input) {
   const n2 = (i) => parseInt(hex.slice(i, i + 2), 16) / 255;
   return formatColor({ space: "srgb", c: [n2(0), n2(2), n2(4), hex.length === 8 ? n2(6) : 1] });
 }
+function luminance({ r, g, b }) {
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
 function mix(a, b, t) {
   return { r: a.r + (b.r - a.r) * t, g: a.g + (b.g - a.g) * t, b: a.b + (b.b - a.b) * t, a: a.a + (b.a - a.a) * t };
 }
@@ -275,9 +280,10 @@ var BlendModeSchema = z.enum(BLEND_MODES);
 var PositionSchema = z.object({ scale: z.number().positive(), "translation-in-points": z.tuple([z.number(), z.number()]) }).loose();
 var ShadowSchema = z.object({ kind: z.enum(["none", "neutral", "layer-color"]), opacity: z.number().min(0).max(1) }).loose();
 var TranslucencySchema = z.object({ enabled: z.boolean(), value: z.number().min(0).max(1) }).loose();
-var RefractivitySchema = z.object({ enabled: z.boolean(), strength: z.number().min(0).max(1), depth: z.number().min(0).max(1) }).loose();
+var RefractivitySchema = z.object({ enabled: z.boolean(), strength: z.number().min(-1).max(1), depth: z.number().min(-1).max(1) }).loose();
 var SupportedPlatformsSchema = z.object({
-  squares: z.union([z.literal("shared"), z.array(z.string())]).optional(),
+  // "shared", ["iOS"] or {"platforms": ["iOS"]} (both list forms appear in community tools)
+  squares: z.union([z.literal("shared"), z.array(z.string()), z.object({ platforms: z.array(z.string()) }).loose()]).optional(),
   circles: z.array(z.string()).optional()
 }).loose();
 var unit = z.number().min(0).max(1);
@@ -421,14 +427,29 @@ var DROP_ELEMENTS = /* @__PURE__ */ new Set([
   "animatecolor",
   "discard",
   "handler",
-  "listener",
-  "a"
+  "listener"
 ]);
+var UNWRAP_ELEMENTS = /* @__PURE__ */ new Set(["a"]);
+function decodeForCheck(v) {
+  return v.replace(/&#x([0-9a-f]+);?/gi, (_m, h) => String.fromCodePoint(parseInt(h, 16) % 1114112)).replace(/&#(\d+);?/g, (_m, d) => String.fromCodePoint(Number(d) % 1114112)).replace(/\\([0-9a-f]{1,6})\s?/gi, (_m, h) => String.fromCodePoint(parseInt(h, 16) % 1114112)).replace(/\\(.)/g, "$1").replace(/\s+/g, "").toLowerCase();
+}
+function expandInternalEntities(svg) {
+  const doctype = /<!DOCTYPE[^\[>]*\[([\s\S]*?)\]\s*>/i.exec(svg);
+  if (!doctype) return svg;
+  const ents = /* @__PURE__ */ new Map();
+  for (const m of doctype[1].matchAll(/<!ENTITY\s+([\w.-]+)\s+(?:"([^"]*)"|'([^']*)')\s*>/g)) {
+    const v = m[2] ?? m[3] ?? "";
+    if (v.length <= 2048 && !/[&<]/.test(v)) ents.set(m[1], v);
+  }
+  const body = svg.slice(0, doctype.index) + svg.slice(doctype.index + doctype[0].length);
+  return body.replace(/&([\w.-]+);/g, (m, name) => ents.get(name) ?? m);
+}
 function safeUrlRef(v) {
   const t = v.trim().replace(/^['"]|['"]$/g, "").trim();
   return t.startsWith("#") || /^data:image\/(png|jpe?g|gif|webp);base64,[a-z0-9+/=\s]*$/i.test(t);
 }
-function cleanCss(css) {
+function cleanCss(css0) {
+  const css = css0.replace(/\\([0-9a-f]{1,6})\s?/gi, (_m, h) => String.fromCodePoint(parseInt(h, 16) % 1114112)).replace(/\\(.)/g, "$1");
   return css.replace(/@import\b[^;]*;?/gi, "").replace(/url\s*\(([^)]*)\)/gi, (m, inner) => safeUrlRef(inner) ? m : "none").replace(/expression\s*\(/gi, "(").replace(/javascript\s*:/gi, "");
 }
 function cleanAttrs(raw) {
@@ -446,9 +467,13 @@ function cleanAttrs(raw) {
     if (lname === "href" || lname.endsWith(":href") || lname === "src") {
       if (!safeUrlRef(value)) continue;
     }
-    if (/javascript\s*:|vbscript\s*:/i.test(value)) continue;
+    const plain = decodeForCheck(value);
+    if (/javascript:|vbscript:/.test(plain) || lname === "xml:base") continue;
     let v = value;
-    if (lname === "style" || /url\s*\(/i.test(v)) v = cleanCss(v);
+    if (lname === "style" || /url\(/.test(plain)) {
+      v = cleanCss(v);
+      if (/url\((?!['"]?#)/.test(decodeForCheck(v).replace(/url\(['"]?data:image\/(png|jpe?g|gif|webp);base64,/g, "url(#"))) continue;
+    }
     out.push(`${name}="${v.replace(/"/g, "&quot;")}"`);
   }
   return out.length ? " " + out.join(" ") : "";
@@ -518,6 +543,7 @@ function sanitizeOnce(svg) {
     i = j + 1;
     const [, close, tag, attrs, selfClose] = m;
     const local = tag.toLowerCase().replace(/^.*:/, "");
+    if (UNWRAP_ELEMENTS.has(local) && !skip.length) continue;
     if (close) {
       if (skip.length) {
         if (skip[skip.length - 1] === local) skip.pop();
@@ -542,7 +568,7 @@ function sanitizeOnce(svg) {
   return out;
 }
 function sanitizeSvg(svg) {
-  let s = svg;
+  let s = expandInternalEntities(svg);
   for (let n2 = 0; n2 < 5; n2++) {
     const next = sanitizeOnce(s);
     if (next === s) break;
@@ -561,8 +587,9 @@ function svgFacts(svg) {
 function makeAsset(name, bytes) {
   const kind = sniffKind(name, bytes);
   if (kind === "svg") {
-    const text2 = sanitizeSvg(td.decode(bytes));
-    return { name, kind, bytes: te.encode(text2), ...svgSize(text2) };
+    const original = td.decode(bytes);
+    const text2 = sanitizeSvg(original);
+    return { name, kind, bytes, ...text2 !== original ? { display: te.encode(text2) } : {}, ...svgSize(text2) };
   }
   if (kind === "png") return { name, kind, bytes, ...pngSize(bytes) };
   if (kind === "jpg") return { name, kind, bytes, ...jpgSize(bytes) };
@@ -716,7 +743,28 @@ function encodePngRgb(width, height, rgba, bg = [0, 0, 0]) {
 }
 function flattenPng(png, bg = [0, 0, 0]) {
   const bmp = decodePng(png);
-  return bmp ? encodePngRgb(bmp.width, bmp.height, bmp.data, bg) : png;
+  if (!bmp) throw new Error("Could not flatten the PNG (unsupported encoding)");
+  return tagSrgb(encodePngRgb(bmp.width, bmp.height, bmp.data, bg));
+}
+function tagSrgb(png) {
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (png.length < 33 || sig.some((b, i) => png[i] !== b)) return png;
+  let o = 8;
+  const dv = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  while (o + 8 <= png.length) {
+    const len = dv.getUint32(o);
+    const type = String.fromCharCode(png[o + 4], png[o + 5], png[o + 6], png[o + 7]);
+    if (type === "sRGB" || type === "iCCP") return png;
+    if (type === "IDAT") break;
+    o += 12 + len;
+  }
+  const ihdrEnd = 8 + 12 + 13;
+  const srgb = chunk("sRGB", new Uint8Array([0]));
+  const out = new Uint8Array(png.length + srgb.length);
+  out.set(png.subarray(0, ihdrEnd), 0);
+  out.set(srgb, ihdrEnd);
+  out.set(png.subarray(ihdrEnd), ihdrEnd + srgb.length);
+  return out;
 }
 
 // ../core/src/bundle.ts
@@ -753,6 +801,10 @@ function serializeIconJson(doc) {
   const json = writeProps(doc.props, doc.order, { groups });
   return JSON.stringify(json, null, 2).replace(/^(\s*"[^"]*"):/gm, "$1 :") + "\n";
 }
+function isSafeBundlePath(rel) {
+  if (!rel || rel.length > 512 || rel.startsWith("/") || /[\\\u0000-\u001f:]/.test(rel)) return false;
+  return rel.split("/").every((p) => p !== "" && p !== "." && p !== ".." && !p.startsWith(".") && p.length <= 255);
+}
 function readBundle(files) {
   const jsonKey = Object.keys(files).find((k) => k === "icon.json" || k.endsWith("/icon.json"));
   if (!jsonKey) throw new IconFormatError("icon.json not found in the bundle");
@@ -763,10 +815,11 @@ function readBundle(files) {
   for (const [k, v] of Object.entries(files)) {
     if (!k.startsWith(prefix) || k === jsonKey || k.endsWith("/")) continue;
     const rel = k.slice(prefix.length);
+    if (!isSafeBundlePath(rel)) continue;
     if (rel.startsWith("Assets/") && rel.split("/").length === 2) {
       const name = rel.slice("Assets/".length);
-      if (name && !name.startsWith(".")) assets[name] = makeAsset(name, v);
-    } else if (!rel.split("/").some((p) => p === "__MACOSX" || p === ".DS_Store")) {
+      if (name) assets[name] = makeAsset(name, v);
+    } else if (!rel.split("/").some((p) => p === "__MACOSX")) {
       extra[rel] = v;
     }
   }
@@ -892,12 +945,7 @@ function uniqueName(existing, wanted0) {
   while (existing.includes(`${wanted} ${i}`)) i++;
   return `${wanted} ${i}`;
 }
-var MAX_GROUPS = 4;
-function assertGroupRoom(doc) {
-  if (doc.groups.length >= MAX_GROUPS) throw new OpError(`An icon can have up to ${MAX_GROUPS} groups. Add the layer to an existing group instead.`);
-}
 function addGroup(doc, opts = {}) {
-  assertGroupRoom(doc);
   const name = uniqueName(doc.groups.map(nameOf), opts.name ?? "Group");
   const g = { id: newId("g"), props: {}, order: [], layers: [] };
   setPropValue(g.props, "name", name);
@@ -935,7 +983,8 @@ function addLayer(doc, groupId, asset, opts = {}) {
   const l = { id: newId("l"), props: {}, order: [] };
   setPropValue(l.props, "image-name", imageName);
   setPropValue(l.props, "name", uniqueName(g.layers.map(nameOf), base));
-  l.order = ["image-name", "name"];
+  setPropValue(l.props, "glass", true);
+  l.order = ["glass", "image-name", "name"];
   for (const [k, v] of Object.entries(opts.props ?? {})) setProp(doc, { kind: "layer", id: l.id }, k, v, void 0, l);
   g.layers.splice(clampIndex(opts.index ?? 0, g.layers.length), 0, l);
   return l;
@@ -1022,9 +1071,20 @@ var RULES = {
   "V-06": { severity: "info", title: "Very thin strokes may disappear at small sizes" },
   "V-07": { severity: "info", title: "SVG contains text or custom effects" },
   "V-08": { severity: "warning", title: "Appearance is not customized" },
-  "V-09": { severity: "error", title: "More than 4 groups" },
+  "V-09": { severity: "warning", title: "More than 4 groups" },
   "V-10": { severity: "error", title: "Unsupported image format" }
 };
+function fillHasAlpha(fill) {
+  if (!fill || typeof fill !== "object") return false;
+  const f = fill;
+  const colors = [f.solid, f["automatic-gradient"], ...Array.isArray(f["linear-gradient"]) ? f["linear-gradient"] : []];
+  return colors.some((c) => {
+    const p = typeof c === "string" ? parseColor(c) : null;
+    if (!p) return false;
+    const a = p.space === "gray" || p.space === "extended-gray" ? p.c[1] : p.c[3];
+    return a !== void 0 && a < 1;
+  });
+}
 function validate(doc) {
   const out = [];
   const push = (id, message, target, ref) => out.push({ id, severity: RULES[id].severity, message, target, ...ref ? { ref } : {} });
@@ -1042,8 +1102,9 @@ function validate(doc) {
   checkProps("document", doc.props, "document", { kind: "document" });
   const fill = resolveProp(doc.props.fill, { appearance: "default" }, "automatic");
   if (fill === "none") push("V-05", 'The background fill is "none". Icons need an opaque, full-bleed background.', "document", { kind: "document" });
+  else if (fillHasAlpha(fill)) push("V-05", "The background color is partly transparent. App Store icons are flattened onto black.", "document", { kind: "document" });
   const visibleGroups = doc.groups.filter((g) => resolveProp(g.props.hidden, { appearance: "default" }, false) !== true).length;
-  if (visibleGroups > 4) push("V-09", `This icon has ${visibleGroups} visible groups. Icon Composer supports up to 4, and actool rejects icons with more.`, "document");
+  if (visibleGroups > 4) push("V-09", `This icon has ${visibleGroups} visible groups. Apple recommends at most 4, and Xcode's actool may reject icons with more.`, "document");
   let anyDark = false;
   let anyTinted = false;
   const scan = (props) => {
@@ -1147,7 +1208,27 @@ function summarizeIssues(issues) {
 
 // ../core/src/export.ts
 import { strToU8 as strToU82 } from "fflate";
+function targetsWatch(doc) {
+  const sp = baseValue(doc.props["supported-platforms"]);
+  return Array.isArray(sp?.circles) && sp.circles.includes("watchOS");
+}
+function unrenderableLayers(doc) {
+  const out = [];
+  for (const g of doc.groups) {
+    if (baseValue(g.props.hidden) === true) continue;
+    for (const l of g.layers) {
+      if (baseValue(l.props.hidden) === true) continue;
+      const name = baseValue(l.props["image-name"]);
+      const a = typeof name === "string" ? doc.assets[name] : void 0;
+      if (!a || a.kind === "pdf" || a.kind === "other") out.push(`${baseValue(g.props.name) ?? "Group"}/${baseValue(l.props.name) ?? name ?? "Layer"}`);
+    }
+  }
+  return out;
+}
+var MAC_INSET = 100;
 var ICNS_TYPES = [
+  ["icp4", 16],
+  ["icp5", 32],
   ["ic11", 32],
   // 16@2x
   ["ic12", 64],
@@ -1186,15 +1267,15 @@ function encodeIcns(pngBySize) {
 }
 async function buildIcns(rasterize, appearance = "default") {
   const pngs = {};
-  for (const s of ICNS_SIZES) pngs[s] = await rasterize(appearance, s);
+  for (const s of ICNS_SIZES) pngs[s] = tagSrgb(await rasterize(appearance, s, { mask: "squircle", idiom: "macOS", inset: MAC_INSET }));
   return encodeIcns(pngs);
 }
-async function buildAppIconSet(rasterize) {
+async function buildAppIconSet(rasterize, opts = {}) {
   const files = {};
   const images = [];
-  files["AppIcon.png"] = flattenPng(await rasterize("default", 1024, { mask: "none" }));
-  files["AppIcon-Dark.png"] = flattenPng(await rasterize("dark", 1024, { mask: "none" }));
-  files["AppIcon-Tinted.png"] = flattenPng(await rasterize("tinted-dark", 1024, { mask: "none", tint: "#FFFFFF" }));
+  files["AppIcon.png"] = flattenPng(await rasterize("default", 1024, { mask: "none", idiom: "iOS" }));
+  files["AppIcon-Dark.png"] = tagSrgb(await rasterize("dark", 1024, { mask: "none", idiom: "iOS", background: false }));
+  files["AppIcon-Tinted.png"] = flattenPng(await rasterize("tinted-dark", 1024, { mask: "none", idiom: "iOS", tint: "#FFFFFF" }));
   images.push({ filename: "AppIcon.png", idiom: "universal", platform: "ios", size: "1024x1024" });
   images.push({
     appearances: [{ appearance: "luminosity", value: "dark" }],
@@ -1214,19 +1295,124 @@ async function buildAppIconSet(rasterize) {
     for (const scale of [1, 2]) {
       const px = pt * scale;
       const name = `mac-${pt}@${scale}x.png`;
-      files[name] = await rasterize("default", px, { mask: "squircle" });
+      files[name] = tagSrgb(await rasterize("default", px, { mask: "squircle", idiom: "macOS", inset: MAC_INSET }));
       images.push({ filename: name, idiom: "mac", scale: `${scale}x`, size: `${pt}x${pt}` });
     }
   }
+  if (opts.watch) {
+    files["AppIcon-Watch.png"] = flattenPng(await rasterize("default", 1024, { mask: "none", idiom: "watchOS" }));
+    images.push({ filename: "AppIcon-Watch.png", idiom: "universal", platform: "watchos", size: "1024x1024" });
+  }
   files["Contents.json"] = strToU82(JSON.stringify({ images, info: { author: "fresnel", version: 1 } }, null, 2) + "\n");
   return files;
 }
 async function buildPngSet(rasterize, appearances, sizes) {
   const files = {};
-  for (const a of appearances) for (const s of sizes) files[`${a}/icon-${s}.png`] = await rasterize(a, s, { mask: "squircle" });
+  for (const a of appearances) for (const s of sizes) files[`${a}/icon-${s}.png`] = tagSrgb(await rasterize(a, s, { mask: "squircle" }));
   return files;
 }
 
+// ../core/src/arrange.ts
+var H = CANVAS / 2;
+function layoutBoxes(doc, ctx, opts = {}) {
+  const layers = [];
+  const groups = [];
+  for (const g of doc.groups) {
+    if (!opts.includeHidden && resolveProp(g.props.hidden, ctx, false)) continue;
+    const gp = resolveProp(g.props.position, ctx, null);
+    const gs = gp?.scale ?? 1;
+    const [gx, gy] = gp?.["translation-in-points"] ?? [0, 0];
+    const toCanvas = (x, y) => ({ x: H + gx + (x - H) * gs, y: H + gy + (y - H) * gs });
+    const inGroup = [];
+    for (const l of g.layers) {
+      if (!opts.includeHidden && resolveProp(l.props.hidden, ctx, false)) continue;
+      const img = resolveProp(l.props["image-name"], ctx, "");
+      const a = doc.assets[img];
+      if (!a) continue;
+      const p = resolveProp(l.props.position, ctx, null);
+      const s = p?.scale ?? 1;
+      const [tx, ty] = p?.["translation-in-points"] ?? [0, 0];
+      const w = a.width * s;
+      const h = a.height * s;
+      const tl = toCanvas(H + tx - w / 2, H + ty - h / 2);
+      const b = { kind: "layer", id: l.id, groupId: g.id, x: tl.x, y: tl.y, w: w * gs, h: h * gs };
+      inGroup.push(b);
+      layers.push(b);
+    }
+    if (inGroup.length) groups.push({ kind: "group", id: g.id, groupId: g.id, ...unionBox(inGroup) });
+  }
+  return { layers, groups };
+}
+function unionBox(boxes) {
+  if (!boxes.length) return null;
+  const x = Math.min(...boxes.map((b) => b.x));
+  const y = Math.min(...boxes.map((b) => b.y));
+  const x2 = Math.max(...boxes.map((b) => b.x + b.w));
+  const y2 = Math.max(...boxes.map((b) => b.y + b.h));
+  return { x, y, w: x2 - x, h: y2 - y };
+}
+function boxOf(doc, ref, ctx) {
+  if (ref.kind === "document") return void 0;
+  const geo = layoutBoxes(doc, ctx, { includeHidden: true });
+  return (ref.kind === "group" ? geo.groups : geo.layers).find((b) => b.id === ref.id);
+}
+function moveBy(doc, ref, dx, dy, ctx, variant) {
+  if (ref.kind === "document" || Math.abs(dx) < 1e-9 && Math.abs(dy) < 1e-9) return;
+  let props;
+  let scale = 1;
+  if (ref.kind === "group") {
+    const g = findGroup(doc, ref.id);
+    if (!g) throw new OpError("Group not found");
+    props = g.props;
+  } else {
+    const f = findLayer(doc, ref.id);
+    if (!f) throw new OpError("Layer not found");
+    props = f.layer.props;
+    scale = resolveProp(f.group.props.position, ctx, null)?.scale ?? 1;
+  }
+  const p = resolveProp(props.position, ctx, { scale: 1, "translation-in-points": [0, 0] }) ?? { scale: 1, "translation-in-points": [0, 0] };
+  const [x, y] = p["translation-in-points"] ?? [0, 0];
+  const round2 = (v) => Math.round(v * 100) / 100;
+  setProp(doc, ref, "position", { ...p, "translation-in-points": [round2(x + dx / scale), round2(y + dy / scale)] }, variant);
+}
+function alignNodes(doc, refs, how, ctx, opts = {}) {
+  const boxes = refs.map((r) => ({ ref: r, box: boxOf(doc, r, ctx) })).filter((x) => !!x.box);
+  if (!boxes.length) return 0;
+  const ref = opts.basis === "canvas" || boxes.length === 1 ? { x: 0, y: 0, w: CANVAS, h: CANVAS } : unionBox(boxes.map((b) => b.box));
+  let moved = 0;
+  for (const { ref: r, box: b } of boxes) {
+    let dx = 0;
+    let dy = 0;
+    if (how === "left") dx = ref.x - b.x;
+    else if (how === "right") dx = ref.x + ref.w - (b.x + b.w);
+    else if (how === "hcenter") dx = ref.x + ref.w / 2 - (b.x + b.w / 2);
+    else if (how === "top") dy = ref.y - b.y;
+    else if (how === "bottom") dy = ref.y + ref.h - (b.y + b.h);
+    else dy = ref.y + ref.h / 2 - (b.y + b.h / 2);
+    if (Math.abs(dx) < 1e-6 && Math.abs(dy) < 1e-6) continue;
+    moveBy(doc, r, dx, dy, ctx, opts.variant);
+    moved++;
+  }
+  return moved;
+}
+function distributeNodes(doc, refs, axis, ctx, opts = {}) {
+  const items = refs.map((r) => ({ ref: r, box: boxOf(doc, r, ctx) })).filter((x) => !!x.box);
+  if (items.length < 3) return 0;
+  const c = (b) => axis === "horizontal" ? b.x + b.w / 2 : b.y + b.h / 2;
+  items.sort((a, b) => c(a.box) - c(b.box));
+  const first = c(items[0].box);
+  const step = (c(items[items.length - 1].box) - first) / (items.length - 1);
+  let moved = 0;
+  items.forEach((it, i) => {
+    if (i === 0 || i === items.length - 1) return;
+    const d = first + step * i - c(it.box);
+    if (Math.abs(d) < 1e-6) return;
+    moveBy(doc, it.ref, axis === "horizontal" ? d : 0, axis === "vertical" ? d : 0, ctx, opts.variant);
+    moved++;
+  });
+  return moved;
+}
+
 // ../core/src/node.ts
 import { lstat, mkdir, readdir, readFile, rm, stat, writeFile, rename } from "fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
@@ -1281,22 +1467,75 @@ async function saveIcon(path, doc) {
   const keep = new Set(Object.keys(doc.assets));
   await assertNoSymlink(root, assetsDir);
   for (const e of await readdir(assetsDir, { withFileTypes: true })) {
-    if (e.isFile() && !keep.has(e.name) && e.name !== ".DS_Store") await rm(join(assetsDir, e.name));
+    if (e.isFile() && !keep.has(e.name) && !e.name.startsWith(".")) await rm(join(assetsDir, e.name));
   }
 }
 async function writeFiles(dir, files) {
   const written = [];
+  const root = resolve(dir);
   for (const [rel, bytes] of Object.entries(files)) {
-    const target = resolve(dir, ...rel.split("/"));
-    const r = relative(resolve(dir), target);
+    const target = resolve(root, ...rel.split("/"));
+    const r = relative(root, target);
     if (r.startsWith("..") || isAbsolute(r)) throw new Error(`Refusing to write outside ${dir}: ${rel}`);
+    await assertNoSymlink(root, target);
     await mkdir(dirname(target), { recursive: true });
+    await assertNoSymlink(root, target);
     await writeFile(target, bytes);
     written.push(target);
   }
   return written;
 }
 
+// ../render/src/content.ts
+var cache = /* @__PURE__ */ new WeakMap();
+function alphaBounds(width, height, rgba, threshold = 8) {
+  let x0 = width;
+  let y0 = height;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0; y < height; y++) {
+    const row = y * width * 4;
+    for (let x = 0; x < width; x++) {
+      if (rgba[row + x * 4 + 3] > threshold) {
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
+    }
+  }
+  if (x1 < 0) return null;
+  return { x: x0 / width, y: y0 / height, w: (x1 - x0 + 1) / width, h: (y1 - y0 + 1) / height };
+}
+function setContentBox(asset, box) {
+  cache.set(asset.bytes, box);
+}
+function contentBoxOf(asset) {
+  if (cache.has(asset.bytes)) return cache.get(asset.bytes) ?? void 0;
+  if (asset.kind === "png") {
+    const bmp = decodePng(asset.bytes);
+    const box = bmp ? alphaBounds(bmp.width, bmp.height, bmp.data) : null;
+    cache.set(asset.bytes, box);
+    return box ?? void 0;
+  }
+  if (asset.kind === "jpg") return { x: 0, y: 0, w: 1, h: 1 };
+  return void 0;
+}
+function svgAssetsNeedingBounds(doc) {
+  const out = /* @__PURE__ */ new Set();
+  const hasGradient = (p) => [p?.plain?.value, ...(p?.specs ?? []).map((s) => s.value)].some((v) => !!v && typeof v === "object" && "linear-gradient" in v);
+  for (const g of doc.groups)
+    for (const l of g.layers) {
+      if (!hasGradient(l.props.fill)) continue;
+      const names = [l.props["image-name"]?.plain?.value, ...(l.props["image-name"]?.specs ?? []).map((s) => s.value)];
+      for (const n2 of names) {
+        const a = typeof n2 === "string" ? doc.assets[n2] : void 0;
+        if (a && a.kind === "svg" && !cache.has(a.bytes)) out.add(a);
+      }
+    }
+  return [...out];
+}
+
 // ../render/src/mask.ts
 function squirclePath(size = CANVAS, exponent = 4.4, steps = 192) {
   const r = size / 2;
@@ -1314,14 +1553,78 @@ function squirclePath(size = CANVAS, exponent = 4.4, steps = 192) {
 var SQUIRCLE = squirclePath();
 var C = CANVAS;
 function maskPath(shape) {
-  if (shape === "circle") return `M${C / 2},0 A${C / 2},${C / 2} 0 1 1 ${C / 2},${C} A${C / 2},${C / 2} 0 1 1 ${C / 2},0Z`;
+  if (shape === "circle") {
+    const r = C / 2 + 32;
+    return `M${C / 2},${C / 2 - r} A${r},${r} 0 1 1 ${C / 2},${C / 2 + r} A${r},${r} 0 1 1 ${C / 2},${C / 2 - r}Z`;
+  }
   if (shape === "none") return `M0,0 H${C} V${C} H0Z`;
   return SQUIRCLE;
 }
 
+// ../render/src/luma.ts
+var lumaOf = (c) => {
+  const p = parseColor(c);
+  return p ? luminance(toRGBA(p)) : null;
+};
+function fillLuma(fill, dark) {
+  if (fill === "system-dark" || fill === "automatic" && dark) return 0.03;
+  if (fill === "system-light" || fill === "automatic") return 0.9;
+  if (!fill || typeof fill !== "object") return null;
+  const f = fill;
+  const colors = [f.solid, f["automatic-gradient"], ...Array.isArray(f["linear-gradient"]) ? f["linear-gradient"] : []].filter((x) => typeof x === "string");
+  const ls = colors.map(lumaOf).filter((x) => x !== null);
+  return ls.length ? ls.reduce((a, b) => a + b, 0) / ls.length : null;
+}
+var cache2 = /* @__PURE__ */ new WeakMap();
+function hexLuma(hex) {
+  let h = hex.replace("#", "");
+  if (h.length === 3) h = h.split("").map((x) => x + x).join("");
+  if (h.length !== 6 && h.length !== 8) return null;
+  const v = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+  return luminance({ r: v(0), g: v(2), b: v(4), a: 1 });
+}
+function assetLuma(a) {
+  const hit = cache2.get(a.bytes);
+  if (hit !== void 0) return hit;
+  let l = 1;
+  if (a.kind === "png") {
+    const bmp = decodePng(a.bytes);
+    if (bmp) {
+      let sum = 0;
+      let wsum = 0;
+      const step = Math.max(1, Math.floor(bmp.width * bmp.height / 4e4));
+      for (let i = 0; i < bmp.width * bmp.height; i += step) {
+        const al = bmp.data[i * 4 + 3] / 255;
+        if (al < 0.05) continue;
+        sum += luminance({ r: bmp.data[i * 4] / 255, g: bmp.data[i * 4 + 1] / 255, b: bmp.data[i * 4 + 2] / 255, a: 1 }) * al;
+        wsum += al;
+      }
+      if (wsum > 0) l = sum / wsum;
+    }
+  } else if (a.kind === "svg") {
+    const text2 = new TextDecoder().decode(a.display ?? a.bytes);
+    const found = [...text2.matchAll(/(?:fill|stop-color)\s*[:=]\s*["']?\s*(#[0-9a-f]{3,8})\b/gi)].map((m) => hexLuma(m[1])).filter((x) => x !== null);
+    const named = [...text2.matchAll(/(?:fill|stop-color)\s*[:=]\s*["']?\s*(white|black)\b/gi)].map((m) => m[1].toLowerCase() === "white" ? 1 : 0);
+    const all = [...found, ...named];
+    if (all.length) l = all.reduce((x, y) => x + y, 0) / all.length;
+  }
+  cache2.set(a.bytes, l);
+  return l;
+}
+
 // ../render/src/compose.ts
+function rasterRenderOptions(ro) {
+  if (!ro) return {};
+  return {
+    ...ro.mask ? { mask: ro.mask, rim: ro.mask !== "none" } : {},
+    ...ro.tint ? { tint: ro.tint } : {},
+    ...ro.idiom ? { idiom: ro.idiom } : {},
+    ...ro.background === false ? { background: false } : {},
+    ...ro.inset ? { inset: ro.inset } : {}
+  };
+}
 var C2 = CANVAS;
-var H = C2 / 2;
+var H2 = C2 / 2;
 var b64Cache = /* @__PURE__ */ new WeakMap();
 var b64 = (bytes) => {
   const hit = b64Cache.get(bytes);
@@ -1407,7 +1710,7 @@ function renderSvg(doc, opts = {}) {
   const isClear = appearance === "clear-light" || appearance === "clear-dark";
   const isTinted = appearance === "tinted-light" || appearance === "tinted-dark";
   const tint = hexToRGBA(opts.tint ?? "#3FA7A0");
-  const angle = (opts.lightAngle ?? -45) * Math.PI / 180;
+  const angle = (opts.lightAngle ?? 0) * Math.PI / 180;
   const toLight = { x: Math.sin(angle), y: -Math.cos(angle) };
   const defs = new Defs(opts.idPrefix ?? "");
   const body = [];
@@ -1417,7 +1720,8 @@ function renderSvg(doc, opts = {}) {
   let darken = 0;
   if (dark && !darkOverridden && bgFill !== "automatic" && bgFill !== "system-dark" && bgFill !== "none") darken = 0.62;
   let bgPaint;
-  const full = { x: 0, y: 0, w: C2, h: C2 };
+  const P = mask === "circle" ? 32 : 0;
+  const full = { x: -P, y: -P, w: C2 + 2 * P, h: C2 + 2 * P };
   const monoOverride = (isClear || isTinted) && !!fillProp?.specs?.some((s) => s.appearance === "tinted" || s.appearance === appearance);
   if (monoOverride) {
     bgPaint = paintFor(bgFill ?? "automatic", defs, full, dark);
@@ -1436,12 +1740,17 @@ function renderSvg(doc, opts = {}) {
     if (bgFill === void 0) bgFill = "automatic";
     bgPaint = paintFor(bgFill, defs, full, dark);
   }
+  if (opts.background === false) {
+    bgPaint = null;
+    darken = 0;
+  }
+  const backdropLuma = (fillLuma(isClear || isTinted ? dark ? "system-dark" : "system-light" : bgFill, dark) ?? 0.9) * (1 - darken);
   const groups = FRONT_FIRST ? [...doc.groups].reverse() : [...doc.groups];
   let stackId = defs.id("s");
   const bgStackId = stackId;
   const contentIds = [];
   defs.add(
-    `<g id="${stackId}">${bgPaint ? `<rect width="${C2}" height="${C2}" fill="${bgPaint}"/>` : ""}` + (darken ? `<rect width="${C2}" height="${C2}" fill="#000" opacity="${darken}"/>` : "") + `</g>`
+    `<g id="${stackId}">${bgPaint ? `<rect x="${-P}" y="${-P}" width="${C2 + 2 * P}" height="${C2 + 2 * P}" fill="${bgPaint}"/>` : ""}` + (darken ? `<rect x="${-P}" y="${-P}" width="${C2 + 2 * P}" height="${C2 + 2 * P}" fill="#000" opacity="${darken}"/>` : "") + `</g>`
   );
   let plainId = bgStackId;
   for (const g of groups) {
@@ -1469,19 +1778,20 @@ function renderSvg(doc, opts = {}) {
       const [tx, ty] = pos?.["translation-in-points"] ?? [0, 0];
       const w = asset.width * s;
       const h = asset.height * s;
-      placed.push({ layer: l, asset, x: H + tx - w / 2, y: H + ty - h / 2, w, h });
+      placed.push({ layer: l, asset, x: H2 + tx - w / 2, y: H2 + ty - h / 2, w, h });
     }
     if (!placed.length) return null;
     const imgId = /* @__PURE__ */ new Map();
     const layerEls = [];
     const glassEls = [];
+    const glassLumas = [];
     for (const p of placed) {
       let iid = imgId.get(p.asset.name);
       if (!iid) {
         iid = defs.id("img");
         imgId.set(p.asset.name, iid);
         defs.add(
-          `<image id="${iid}" width="${n(p.asset.width)}" height="${n(p.asset.height)}" preserveAspectRatio="none" href="data:${mimeOf(p.asset)};base64,${b64(p.asset.bytes)}"/>`
+          `<image id="${iid}" width="${n(p.asset.width)}" height="${n(p.asset.height)}" preserveAspectRatio="none" href="data:${mimeOf(p.asset)};base64,${b64(p.asset.display ?? p.asset.bytes)}"/>`
         );
       }
       const s = p.w / p.asset.width;
@@ -1489,7 +1799,9 @@ function renderSvg(doc, opts = {}) {
       const fill = resolveProp(p.layer.props.fill, ctx, null);
       const opacity = resolveProp(p.layer.props.opacity, ctx, 1);
       const blend = cssBlend(resolveProp(p.layer.props["blend-mode"], ctx, "normal"));
-      const paint = fill && fill !== "automatic" ? paintFor(fill, defs, { x: p.x, y: p.y, w: p.w, h: p.h }, dark) : null;
+      const cb = contentBoxOf(p.asset);
+      const fbox = cb ? { x: p.x + cb.x * p.w, y: p.y + cb.y * p.h, w: cb.w * p.w, h: cb.h * p.h } : { x: p.x, y: p.y, w: p.w, h: p.h };
+      const paint = fill && fill !== "automatic" ? paintFor(fill, defs, fbox, dark) : null;
       let el;
       if (paint) {
         const mid = defs.id("lm");
@@ -1500,9 +1812,12 @@ function renderSvg(doc, opts = {}) {
       }
       const wrapped = `<g${opacity < 1 ? ` opacity="${n(opacity)}"` : ""}${blend ? ` style="mix-blend-mode:${blend}"` : ""}>${el}</g>`;
       layerEls.push(wrapped);
-      if (resolveProp(p.layer.props.glass, ctx, false)) glassEls.push(`<use href="#${iid}" ${place}/>`);
+      if (resolveProp(p.layer.props.glass, ctx, false)) {
+        glassEls.push(`<use href="#${iid}" ${place}/>`);
+        glassLumas.push(fill && fill !== "automatic" ? fillLuma(fill, dark) ?? assetLuma(p.asset) : assetLuma(p.asset));
+      }
     }
-    const gTransform = gpos ? ` transform="translate(${n(H + (gpos["translation-in-points"]?.[0] ?? 0))} ${n(H + (gpos["translation-in-points"]?.[1] ?? 0))}) scale(${n(gpos.scale ?? 1)}) translate(${-H} ${-H})"` : "";
+    const gTransform = gpos ? ` transform="translate(${n(H2 + (gpos["translation-in-points"]?.[0] ?? 0))} ${n(H2 + (gpos["translation-in-points"]?.[1] ?? 0))}) scale(${n(gpos.scale ?? 1)}) translate(${-H2} ${-H2})"` : "";
     const contentId = defs.id("gc");
     defs.add(`<g id="${contentId}"${gTransform}>${layerEls.join("")}</g>`);
     contentIds.push(contentId);
@@ -1535,13 +1850,27 @@ function renderSvg(doc, opts = {}) {
       defs.add(`<filter id="${fid}" x="-10%" y="-10%" width="120%" height="120%"><feGaussianBlur stdDeviation="${n(blurPx)}"/></filter>`);
       const zoom = 1.02 + (refracts ? (refr.strength ?? 0) * 0.12 : 0.015);
       out.push(
-        `<g mask="url(#${mid})"><use href="#${backdropId}" filter="url(#${fid})" transform="translate(${H} ${H}) scale(${n(zoom)}) translate(${-H} ${-H})"/></g>`
+        `<g mask="url(#${mid})"><use href="#${backdropId}" filter="url(#${fid})" transform="translate(${H2} ${H2}) scale(${n(zoom)}) translate(${-H2} ${-H2})"/></g>`
+      );
+    }
+    const gOpacity = resolveProp(g.props.opacity, ctx, 1) * (refracts && !translucent ? 1 - (refr.strength ?? 0) * 0.3 : 1);
+    let fadeMask = "";
+    if (translucent) {
+      const v = Math.min(1, Math.max(0, tr.value));
+      const gid = defs.id("tg");
+      const mid = defs.id("tm");
+      defs.add(
+        `<linearGradient id="${gid}" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#fff" stop-opacity="${n(1 - v * 0.2)}"/><stop offset="1" stop-color="#fff" stop-opacity="${n(1 - v * 0.85)}"/></linearGradient><mask id="${mid}" maskUnits="objectBoundingBox" maskContentUnits="objectBoundingBox" x="0" y="0" width="1" height="1"><rect width="1" height="1" fill="url(#${gid})"/></mask>`
       );
+      fadeMask = ` mask="url(#${mid})"`;
     }
-    const gOpacity = resolveProp(g.props.opacity, ctx, 1) * (translucent ? 1 - tr.value * 0.55 : 1) * (refracts && !translucent ? 1 - (refr.strength ?? 0) * 0.3 : 1);
     const gBlend = cssBlend(resolveProp(g.props["blend-mode"], ctx, "normal"));
-    out.push(`<use href="#${contentId}"${gOpacity < 1 ? ` opacity="${n(gOpacity)}"` : ""}${gBlend ? ` style="mix-blend-mode:${gBlend}"` : ""}/>`);
-    const specular = resolveProp(g.props.specular, ctx, true);
+    out.push(
+      `<g${fadeMask}${gOpacity < 1 ? ` opacity="${n(gOpacity)}"` : ""}${gBlend ? ` style="mix-blend-mode:${gBlend}"` : ""}><use href="#${contentId}"/></g>`
+    );
+    const specularSetting = resolveProp(g.props.specular, ctx, true);
+    const fg = glassLumas.length ? glassLumas.reduce((a, b) => a + b, 0) / glassLumas.length : 1;
+    const specular = specularSetting === true ? fg < backdropLuma ? "inside" : "outside" : specularSetting;
     if (effects && specular && glassEls.length) {
       const k = 7;
       const dx = n(-toLight.x * k);
@@ -1587,17 +1916,24 @@ function renderSvg(doc, opts = {}) {
   const clipId = defs.id("clip");
   const shape = maskPath(mask);
   defs.add(`<clipPath id="${clipId}"><path d="${shape}"/></clipPath>`);
-  body.push(`<g clip-path="url(#${clipId})">${top}</g>`);
+  const M = Math.max(0, opts.inset ?? 0);
+  if (M > 0) {
+    const sid = defs.id("ish");
+    defs.add(
+      `<filter id="${sid}" x="-20%" y="-20%" width="140%" height="150%"><feGaussianBlur in="SourceAlpha" stdDeviation="${n(C2 * 0.012)}"/><feOffset dy="${n(C2 * 0.012)}" result="b"/><feFlood flood-color="#000" flood-opacity="0.3"/><feComposite in2="b" operator="in" result="s"/><feMerge><feMergeNode in="s"/><feMergeNode in="SourceGraphic"/></feMerge></filter>`
+    );
+    body.push(`<g filter="url(#${sid})"><g clip-path="url(#${clipId})">${top}</g></g>`);
+  } else body.push(`<g clip-path="url(#${clipId})">${top}</g>`);
   if (effects && opts.rim !== false && mask !== "none") {
     const rid = defs.id("rim");
-    const lx = H + toLight.x * H;
-    const ly = H + toLight.y * H;
+    const lx = H2 + toLight.x * H2;
+    const ly = H2 + toLight.y * H2;
     defs.add(
       `<linearGradient id="${rid}" gradientUnits="userSpaceOnUse" x1="${n(lx)}" y1="${n(ly)}" x2="${n(C2 - lx)}" y2="${n(C2 - ly)}"><stop offset="0" stop-color="#fff" stop-opacity="${dark ? 0.55 : 0.85}"/><stop offset="0.35" stop-color="#fff" stop-opacity="0.08"/><stop offset="0.7" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="${dark ? 0.2 : 0.3}"/></linearGradient>`
     );
     body.push(`<g clip-path="url(#${clipId})"><path d="${shape}" fill="none" stroke="url(#${rid})" stroke-width="10"/></g>`);
   }
-  return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${size}" height="${size}" viewBox="0 0 ${C2} ${C2}"><title>${esc(appearance)}</title><defs>${defs.toString()}</defs>${body.join("")}</svg>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${size}" height="${size}" viewBox="${-(P + M)} ${-(P + M)} ${C2 + 2 * (P + M)} ${C2 + 2 * (P + M)}"><title>${esc(appearance)}</title><defs>${defs.toString()}</defs>${body.join("")}</svg>`;
 }
 function cssBlend(mode) {
   if (!mode || mode === "normal") return null;
@@ -1610,11 +1946,11 @@ function cssBlend(mode) {
 var SHEET_ORDER = ["default", "clear-light", "tinted-light", "dark", "clear-dark", "tinted-dark"];
 function renderSheetSvg(doc, opts = {}) {
   const cell = opts.cell ?? 320;
-  const pad = Math.round(cell * 0.18);
+  const pad2 = Math.round(cell * 0.18);
   const label = opts.labels !== false ? Math.round(cell * 0.12) : 0;
   const w = cell * 3;
   const h = (cell + label) * 2;
-  const icon = cell - pad * 2;
+  const icon = cell - pad2 * 2;
   const parts = [];
   SHEET_ORDER.forEach((ap, i) => {
     const x = i % 3 * cell;
@@ -1622,7 +1958,7 @@ function renderSheetSvg(doc, opts = {}) {
     const darkBg = isDarkAppearance(ap);
     parts.push(`<rect x="${x}" y="${y}" width="${cell}" height="${cell + label}" fill="${darkBg ? "#14161F" : "#E3E8F0"}"/>`);
     const svg = renderSvg(doc, { ...opts, appearance: ap, size: icon, idPrefix: `a${i}_` });
-    parts.push(svg.replace("<svg ", `<svg x="${x + pad}" y="${y + pad}" `).replace(/ width="\d+" height="\d+"/, ` width="${icon}" height="${icon}"`));
+    parts.push(svg.replace("<svg ", `<svg x="${x + pad2}" y="${y + pad2}" `).replace(/ width="\d+" height="\d+"/, ` width="${icon}" height="${icon}"`));
     if (label)
       parts.push(
         `<text x="${x + cell / 2}" y="${y + cell + label * 0.15}" text-anchor="middle" font-family="Inter, Helvetica, Arial, sans-serif" font-size="${Math.round(label * 0.5)}" font-weight="600" fill="${darkBg ? "#F2F2F5" : "#1C1C1E"}">${APPEARANCE_LABEL[ap]}</text>`
@@ -1647,110 +1983,209 @@ async function svgToPng(svg, width) {
   const r = new Resvg(svg, { fitTo: { mode: "width", value: Math.round(width) }, font: { loadSystemFonts: true } });
   return new Uint8Array(r.render().asPng());
 }
+async function ensureContentBoxes(doc) {
+  const todo = svgAssetsNeedingBounds(doc);
+  if (!todo.length) return;
+  const { Resvg } = await resvg();
+  for (const a of todo) {
+    try {
+      const svg = new TextDecoder().decode(a.display ?? a.bytes);
+      const png = new Resvg(svg, { fitTo: { mode: "width", value: 256 } }).render().asPng();
+      const bmp = decodePng(new Uint8Array(png));
+      setContentBox(a, bmp ? alphaBounds(bmp.width, bmp.height, bmp.data) : null);
+    } catch {
+      setContentBox(a, null);
+    }
+  }
+}
 async function renderPng(doc, opts = {}) {
+  await ensureContentBoxes(doc);
   const size = opts.size ?? 1024;
   return svgToPng(renderSvg(doc, { ...opts, size }), size);
 }
 async function renderSheetPng(doc, opts = {}) {
+  await ensureContentBoxes(doc);
   const cell = opts.cell ?? 320;
   return svgToPng(renderSheetSvg(doc, opts), cell * 3);
 }
 function nodeRasterizer(doc, opts = {}) {
-  return (appearance, size, ro) => renderPng(doc, { ...opts, appearance, size, ...ro?.mask ? { mask: ro.mask, rim: ro.mask !== "none" } : {}, ...ro?.tint ? { tint: ro.tint } : {} });
+  return (appearance, size, ro) => renderPng(doc, { ...opts, appearance, size, ...rasterRenderOptions(ro) });
 }
 
-// ../mcp/src/tools.ts
-import { mkdir as mkdir2, readFile as readFile2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
-import { basename, dirname as dirname2, join as join2 } from "path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z2 } from "zod";
-
-// ../mcp/src/guide.ts
-var ICON_GUIDE = `# Designing Liquid Glass app icons (iOS, iPadOS, macOS, watchOS)
-
-Source: Apple Human Interface Guidelines, "App icons"
-https://developer.apple.com/design/human-interface-guidelines/app-icons
-
-## Structure
-- An icon is a background plus one or more foreground layers. The system adds Liquid Glass effects (specular highlights, refraction, translucency) and adapts them to size and system version.
-- Canvas: 1024\xD71024 for iOS/iPadOS/macOS (masked to a rounded rectangle) and 1088\xD71088 for watchOS (masked to a circle).
-- Appearances: Default, Dark, Clear light, Clear dark, Tinted light, Tinted dark. If you don't provide a variant, the system generates one.
-- Groups: Liquid Glass effects (mode, specular Off/Automatic/Inside/Outside, blur, refraction, translucency, shadow) are configured per group. Use at most 4 groups \u2014 actool rejects icons with more.
-- In Icon Composer the appearances are Default, Dark and Mono (Mono covers clear and tinted); icon.json stores Mono overrides under the "tinted" key.
-
-## Layers
-- Provide square, unmasked layers. Never bake in rounded corners; the system masks the icon, and pre-masked layers break the specular highlights and leave jagged edges.
-- Prefer clearly defined edges. Avoid soft or feathered shapes.
-- Import layers fully opaque and set transparency in the tool. Varying opacity across foreground layers adds depth.
-- Prefer vector art (SVG/PDF). Convert text to outlines. Use PNG for raster art and mesh gradients.
-- Don't bake in highlights, drop shadows, bevels, blurs or glows. The system draws dynamic effects.
-
-## Design
-- Keep it simple. Use one core idea expressed with a minimal number of filled, overlapping shapes.
-- Prefer a simple background, such as a solid color or gradient. A background image must be full-bleed and opaque.
-- Keep primary content centered so masking (especially circles on watchOS) doesn't truncate it.
-- Avoid text unless it's essential. Avoid photos, UI screenshots and replicas of Apple hardware.
-- Avoid very thin lines and sharp corners; they disappear at small sizes.
-
-## Appearances
-- Keep the same core features across all appearances. Don't swap elements in and out.
-- Base the dark icon on the light one, using complementary, less bright colors. Colored backgrounds give the most contrast in dark mode.
-- Dark, clear and tinted icons are more subdued. Check that the icon stays legible and recognizable in all of them.
-
-## fresnel workflow
-1. icon_create with a background (e.g. "gradient:#3D7BFF,#0E2A8A").
-2. Draw each foreground element as its own 1024\xD71024 SVG (transparent background, centered artwork) and add it with icon_add_layer.
-3. Use groups for depth: put elements that should share glass settings in one group. Index 0 is the frontmost.
-4. Set glass on layers that should catch highlights, then tune the group: translucency, blur-material, specular, shadow.
-5. Add Dark and Mono ("tinted") overrides with icon_set (appearance: "dark" or "tinted"), and platform variants (platform: "watchOS", \u2026) where layout differs.
-6. Check icon_render_sheet and icon_validate, then icon_export.
-`;
-function table(title, defs) {
-  const rows = Object.entries(defs).map(([k, d]) => `| \`${k}\` | ${d.description} | \`${JSON.stringify(d.default)}\` |`);
-  return `### ${title}
-
-| key | meaning | default when absent |
-|---|---|---|
-${rows.join("\n")}
+// ../mcp/src/cliargs.ts
+var LEGACY_COMMANDS = ["build", "inspect", "validate", "render", "export", "mcp"];
+var defOf = (s) => s._zod.def;
+function unwrap(s) {
+  let optional = false;
+  let cur = s;
+  for (; ; ) {
+    const d = defOf(cur);
+    if (d.type === "optional" || d.type === "default" || d.type === "nullable") {
+      optional = optional || d.type !== "nullable";
+      cur = d.innerType;
+    } else return { schema: cur, optional };
+  }
+}
+function argKind(s) {
+  const { schema } = unwrap(s);
+  const d = defOf(schema);
+  switch (d.type) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number", integer: !!d.checks?.some((c) => c._zod.def.format === "safeint" || c._zod.def.format === "int32") || !!schema.isInt };
+    case "boolean":
+      return { type: "boolean" };
+    case "enum":
+      return { type: "enum", values: Object.values(d.entries ?? {}) };
+    case "array":
+      return { type: "array", of: argKind(d.element) };
+    default:
+      return { type: "json" };
+  }
+}
+function argsOf(t) {
+  return Object.entries(t.input).map(([name, s]) => {
+    const schema = s;
+    const description = schema.description;
+    return {
+      name,
+      flag: `--${name.replace(/_/g, "-")}`,
+      kind: argKind(schema),
+      required: !unwrap(schema).optional,
+      ...description ? { description } : {}
+    };
+  });
+}
+var cliCommand = (t) => LEGACY_COMMANDS.includes(t.cli) ? `call ${t.id}` : t.cli;
+var kindHint = (k) => k.type === "enum" ? k.values.join("|") : k.type === "array" ? `${kindHint(k.of)},\u2026` : k.type === "json" ? "'<json>'" : k.type === "number" ? "<n>" : k.type === "boolean" ? "(flag)" : `<${k.type}>`;
+function usage(t) {
+  const pos = new Set(t.positional ?? []);
+  const parts = [`fresnel ${cliCommand(t)}`];
+  for (const a of argsOf(t)) {
+    if (pos.has(a.name)) parts.push(a.required ? `<${a.name}>` : `[<${a.name}>]`);
+  }
+  for (const a of argsOf(t)) {
+    if (pos.has(a.name)) continue;
+    const s = a.kind.type === "boolean" ? a.flag : `${a.flag} ${kindHint(a.kind)}`;
+    parts.push(a.required ? s : `[${s}]`);
+  }
+  return parts.join(" ");
+}
+function toolHelp(t) {
+  const lines = [`${t.title} (${t.id})`, "", t.description, "", `Usage: ${usage(t)}`, "", "Arguments:"];
+  const pos = new Set(t.positional ?? []);
+  for (const a of argsOf(t)) {
+    const name = pos.has(a.name) ? `<${a.name}>` : a.flag;
+    lines.push(`  ${name.padEnd(22)} ${kindHint(a.kind).padEnd(14)} ${a.required ? "required" : "optional"}${a.description ? `  ${a.description}` : ""}`);
+  }
+  lines.push(`  ${"--args".padEnd(22)} ${"'<json>'".padEnd(14)} all arguments as one JSON object (flags win)`);
+  if (t.examples.length) {
+    lines.push("", "Examples:");
+    for (const ex of t.examples) lines.push(`  # ${ex.note}`, `  ${exampleCommand(t, ex.args)}`);
+  }
+  lines.push("", `Output: JSON on stdout. Verify: ${t.verification.join("; ") || "\u2014"}`);
+  return `${lines.join("\n")}
 `;
 }
-var SCHEMA_GUIDE = `# icon.json attributes understood by fresnel
-
-The format isn't documented by Apple. This reference is reverse-engineered (glassmith, icon-composer-template, real Icon Composer files).
-Any attribute can be overridden per appearance with icon_set(..., appearance: "dark" | "tinted").
-Unknown attributes are accepted and preserved.
-
-${table("Document", DOCUMENT_ATTRS)}
-${table("Group", GROUP_ATTRS)}
-${table("Layer", LAYER_ATTRS)}
+var shellQuote = (s) => /^[\w@%+=:,./#-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+function exampleCommand(t, args) {
+  const pos = t.positional ?? [];
+  const parts = [`fresnel ${cliCommand(t)}`];
+  for (const p of pos) if (args[p] !== void 0) parts.push(shellQuote(String(args[p])));
+  for (const a of argsOf(t)) {
+    const v = args[a.name];
+    if (v === void 0 || pos.includes(a.name)) continue;
+    if (a.kind.type === "boolean") parts.push(v ? a.flag : `--no-${a.flag.slice(2)}`);
+    else if (a.kind.type === "array") parts.push(a.flag, shellQuote(v.join(",")));
+    else if (a.kind.type === "json") parts.push(a.flag, shellQuote(JSON.stringify(v)));
+    else parts.push(a.flag, shellQuote(String(v)));
+  }
+  return parts.join(" ");
+}
+function convert(k, raw, flag) {
+  switch (k.type) {
+    case "number": {
+      const n2 = Number(raw);
+      if (raw.trim() === "" || Number.isNaN(n2)) throw new Error(`${flag} expects a number, got "${raw}"`);
+      return n2;
+    }
+    case "array":
+      return raw === "" ? [] : raw.split(",").map((x) => convert(k.of, x.trim(), flag));
+    case "json":
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new Error(`${flag} expects JSON, got ${raw}`);
+      }
+    default:
+      return raw;
+  }
+}
+function parseToolArgv(t, argv) {
+  const infos = argsOf(t);
+  const byFlag = new Map(infos.map((a) => [a.flag, a]));
+  const out = {};
+  let base = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith("--") || tok === "--") {
+      positionals.push(tok);
+      continue;
+    }
+    const eq = tok.indexOf("=");
+    const flag = eq > 0 ? tok.slice(0, eq) : tok;
+    const inline = eq > 0 ? tok.slice(eq + 1) : void 0;
+    if (flag === "--args") {
+      const raw2 = inline ?? argv[++i];
+      if (raw2 === void 0) throw new Error("--args needs a JSON object");
+      const v = convert({ type: "json" }, raw2, "--args");
+      if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error("--args must be a JSON object");
+      base = v;
+      continue;
+    }
+    const neg = flag.startsWith("--no-") ? byFlag.get(`--${flag.slice(5)}`) : void 0;
+    if (neg && neg.kind.type === "boolean") {
+      out[neg.name] = false;
+      continue;
+    }
+    const info = byFlag.get(flag);
+    if (!info) throw new Error(`Unknown option ${flag} for ${t.id}. Run "fresnel ${cliCommand(t)} --help".`);
+    if (info.kind.type === "boolean") {
+      out[info.name] = inline === void 0 ? true : !/^(false|0|no)$/i.test(inline);
+      continue;
+    }
+    const raw = inline ?? argv[++i];
+    if (raw === void 0) throw new Error(`${flag} needs a value`);
+    out[info.name] = convert(info.kind, raw, flag);
+  }
+  const pos = t.positional ?? [];
+  if (positionals.length > pos.length) throw new Error(`Unexpected argument "${positionals[pos.length]}". Run "fresnel ${cliCommand(t)} --help".`);
+  positionals.forEach((v, i) => {
+    const info = infos.find((a) => a.name === pos[i]);
+    if (out[info.name] === void 0) out[info.name] = convert(info.kind, v, `<${info.name}>`);
+  });
+  return { ...base, ...out };
+}
 
-### Value formats
-- Color: "#RRGGBB" (stored as srgb) or Icon Composer strings: "display-p3:r,g,b,a", "srgb:r,g,b,a", "extended-gray:l,a"
-- Fill: "automatic" | "system-light" | "system-dark" | "none" | {"solid": color} | {"automatic-gradient": color} | {"linear-gradient": [color, color], "orientation": {"start": {"x","y"}, "stop": {"x","y"}}}
-  Shorthands: "#336699" \u2192 solid, "gradient:#top,#bottom" \u2192 linear-gradient, "auto-gradient:#color" \u2192 automatic-gradient
-- Position: {"scale": 1, "translation-in-points": [x, y]} (points on the 1024 canvas, y down, relative to center)
-- Shadow: {"kind": "none" | "neutral" | "layer-color", "opacity": 0\u20131}
-- Translucency: {"enabled": true, "value": 0\u20131}
-- Blend modes: normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, soft-light, hard-light, difference, exclusion, hue, saturation, color, luminosity, plus-darker, plus-lighter
-`;
+// ../mcp/src/contract.ts
+import { z as z3 } from "zod";
 
-// ../mcp/src/tools.ts
-var VERSION = "0.1.0";
+// ../mcp/src/spec.ts
+import { mkdir as mkdir2, readFile as readFile2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { basename, dirname as dirname2, join as join2 } from "path";
+import { z as z2 } from "zod";
+var CONTRACT_VERSION = "1.0";
+var tool = (def) => def;
 var appearanceEnum = z2.enum(APPEARANCES);
 var overrideEnum = z2.enum(["dark", "tinted"]);
+var platformEnum = z2.enum(["iOS", "macOS", "watchOS", "square"]);
 var maskEnum = z2.enum(["squircle", "circle", "none"]);
-var text = (v) => ({ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) });
-var ok = (...content) => ({ content });
-var fail = (e) => ({ content: [text(`Error: ${e.message}`)], isError: true });
-function safe(fn) {
-  return async (args) => {
-    try {
-      return await fn(args);
-    } catch (e) {
-      return fail(e);
-    }
-  };
-}
+var pathArg = z2.string().describe('Path to the .icon bundle (".icon" is added if missing)');
+var dryRunArg = z2.boolean().optional().describe("Validate and report the result without writing anything");
+var loose = (shape) => z2.looseObject(shape);
+var groupsOutline = z2.array(z2.looseObject({ group: z2.string(), layers: z2.array(z2.string()) }));
 function describeProps(props) {
   const base = {};
   const overrides = {};
@@ -1782,6 +2217,7 @@ function inspect(doc) {
     assets: Object.values(doc.assets).map((a) => ({ name: a.name, kind: a.kind, width: a.width, height: a.height }))
   };
 }
+var outline = (doc) => inspect(doc).groups.map((g) => ({ group: g.target, layers: g.layers.map((l) => l.target) }));
 function targetLabel(doc, ref) {
   if (ref.kind === "document") return "document";
   if (ref.kind === "group") return nameOf(findGroup(doc, ref.id));
@@ -1791,29 +2227,41 @@ function targetLabel(doc, ref) {
   }
   return "?";
 }
-var b642 = (u) => Buffer.from(u).toString("base64");
-function createServer(ws) {
-  const server = new McpServer(
-    { name: "fresnel", version: VERSION },
-    {
-      instructions: 'fresnel edits Apple Liquid Glass app icons stored as .icon bundles (the Icon Composer format). Typical flow: icon_create \u2192 icon_add_layer (one 1024\xD71024 SVG per element) \u2192 icon_set (glass, translucency, dark/tinted overrides) \u2192 icon_render_sheet to look at all appearances \u2192 icon_validate \u2192 icon_export. Read fresnel://guide/icon-design for Apple design rules. Targets are "document", "<Group>" or "<Group>/<Layer>" (names or #index; index 0 is frontmost). Previews are approximations of the system renderer.'
-    }
-  );
-  server.registerTool(
-    "icon_create",
-    {
-      title: "Create icon",
-      description: 'Creates a new .icon bundle (Icon Composer format). background accepts "#RRGGBB", "gradient:#top,#bottom", "auto-gradient:#color", "automatic", "system-light", "system-dark" or a color string like "display-p3:1,0.5,0,1".',
-      inputSchema: {
-        path: z2.string().describe('Bundle path, e.g. "MyApp.icon" (".icon" is added if missing). Relative paths are inside the first allowed root.'),
-        background: z2.string().optional().describe("Background fill for all appearances"),
-        dark_background: z2.string().optional().describe("Background override for the dark appearance"),
-        watch: z2.boolean().optional().describe("Also target watchOS (circular). Default true"),
-        overwrite: z2.boolean().optional().describe("Replace an existing bundle. Default false")
-      },
-      annotations: { destructiveHint: false, idempotentHint: false }
+async function saveFile(ws, out, bytes) {
+  const p = await ws.resolve(out);
+  await mkdir2(dirname2(p), { recursive: true });
+  await writeFile2(p, bytes);
+  return p;
+}
+var inspectOutput = loose({ order: z2.string(), document: z2.record(z2.string(), z2.unknown()), groups: z2.array(z2.looseObject({ target: z2.string(), index: z2.number() })), assets: z2.array(z2.looseObject({ name: z2.string() })) });
+var EX_STAR = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path d="M512 212 L594 420 L812 430 L640 566 L700 780 L512 660 L324 780 L384 566 L212 430 L430 420 Z" fill="#ffffff"/></svg>';
+var EX_DOT = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><circle cx="512" cy="512" r="300" fill="#7FB2FF"/></svg>';
+var TOOLS = [
+  tool({
+    id: "icon_create",
+    cli: "create",
+    positional: ["path"],
+    title: "Create icon",
+    summary: "Creates a new `.icon` with a background (color, gradient or system) and an optional dark background",
+    description: 'Creates a new .icon bundle (Icon Composer format). background accepts "#RRGGBB", "gradient:#top,#bottom", "auto-gradient:#color", "automatic", "system-light", "system-dark" or a color string like "display-p3:1,0.5,0,1".',
+    role: "create",
+    capabilities: ["bundle", "background", "appearance-overrides", "platforms"],
+    input: {
+      path: z2.string().describe('Bundle path, e.g. "MyApp.icon" (".icon" is added if missing). Relative paths are inside the first allowed root.'),
+      background: z2.string().optional().describe("Background fill for all appearances"),
+      dark_background: z2.string().optional().describe("Background override for the dark appearance"),
+      watch: z2.boolean().optional().describe("Also target watchOS (circular). Default true"),
+      overwrite: z2.boolean().optional().describe("Replace an existing bundle. Default false"),
+      dry_run: dryRunArg
     },
-    safe(async ({ path, background, dark_background, watch, overwrite }) => {
+    output: loose({ created: z2.string(), dry_run: z2.boolean().optional(), groups: z2.array(z2.unknown()) }),
+    mutates_input: true,
+    idempotency_hint: "not-idempotent",
+    supports_dry_run: true,
+    verification: ["icon_inspect shows the document fill", "icon_render_sheet shows the background in all appearances"],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon", background: "gradient:#3D7BFF,#0E2A8A", dark_background: "#101828" }, note: "New icon with a blue gradient and a dark-mode background" }],
+    async run(ws, { path, background, dark_background, watch, overwrite, dry_run }) {
       if (/\.zip$/i.test(path.trim())) throw new Error("icon_create writes an .icon folder; pass a path without .zip (use icon_export to make a zip)");
       const full = await ws.iconPath(path);
       const exists = await stat2(full).then(() => true, () => false);
@@ -1823,63 +2271,101 @@ function createServer(ws) {
         platforms: watch === false ? { squares: "shared" } : { circles: ["watchOS"], squares: "shared" }
       });
       if (dark_background) setProp(doc, { kind: "document" }, "fill", dark_background, "dark");
-      await ws.withLock(full, () => saveIcon(full, doc));
-      return ok(text({ created: full, ...inspect(doc) }));
-    })
-  );
-  server.registerTool(
-    "icon_inspect",
-    {
-      title: "Inspect icon",
-      description: "Shows the groups, layers, attributes and per-appearance overrides of an .icon bundle.",
-      inputSchema: { path: z2.string() },
-      annotations: { readOnlyHint: true }
-    },
-    safe(async ({ path }) => {
+      if (!dry_run) await ws.withLock(full, () => saveIcon(full, doc));
+      return { data: { created: full, ...dry_run ? { dry_run: true } : {}, ...inspect(doc) } };
+    }
+  }),
+  tool({
+    id: "icon_inspect",
+    cli: "inspect",
+    positional: ["path"],
+    title: "Inspect icon",
+    summary: "Lists groups, layers, attributes and every variant",
+    description: "Shows the groups, layers, attributes and per-appearance overrides of an .icon bundle.",
+    role: "inspect",
+    capabilities: ["read"],
+    input: { path: pathArg },
+    output: inspectOutput,
+    mutates_input: false,
+    idempotency_hint: "idempotent",
+    supports_dry_run: false,
+    verification: [],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon" }, note: "List everything in the bundle" }],
+    async run(ws, { path }) {
       const full = await ws.iconPath(path, { mustExist: true });
-      return ok(text(inspect(await ws.read(full))));
-    })
-  );
-  server.registerTool(
-    "icon_add_group",
-    {
-      title: "Add group",
-      description: "Adds a group. Groups carry the Liquid Glass settings (translucency, blur-material, specular, shadow, lighting).",
-      inputSchema: {
-        path: z2.string(),
-        name: z2.string(),
-        index: z2.number().int().min(0).optional().describe("0 = frontmost (default)"),
-        props: z2.record(z2.string(), z2.any()).optional().describe('Group attributes, e.g. {"translucency": {"enabled": true, "value": 0.5}, "blur-material": 0.3}')
-      }
+      return { data: inspect(await ws.read(full)) };
+    }
+  }),
+  tool({
+    id: "icon_add_group",
+    cli: "add-group",
+    positional: ["path"],
+    title: "Add group",
+    summary: "Adds a group (the unit that carries the glass settings)",
+    description: "Adds a group. Groups carry the Liquid Glass settings (translucency, blur-material, specular, shadow, lighting).",
+    role: "edit",
+    capabilities: ["groups", "glass"],
+    input: {
+      path: pathArg,
+      name: z2.string(),
+      index: z2.number().int().min(0).optional().describe("0 = frontmost (default)"),
+      props: z2.record(z2.string(), z2.any()).optional().describe('Group attributes, e.g. {"translucency": {"enabled": true, "value": 0.5}, "blur-material": 0.3}'),
+      dry_run: dryRunArg
     },
-    safe(async ({ path, name, index, props }) => {
+    output: loose({ added: z2.string(), groups: z2.array(z2.string()) }),
+    mutates_input: true,
+    idempotency_hint: "not-idempotent",
+    supports_dry_run: true,
+    verification: ["icon_inspect lists the new group"],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon", name: "Back", props: { "blur-material": 0.3 } }, note: "A back group with some blur" }],
+    async run(ws, { path, name, index, props, dry_run }) {
       const full = await ws.iconPath(path, { mustExist: true });
-      const res = await ws.edit(full, (doc) => {
-        const g = addGroup(doc, { name, ...index !== void 0 ? { index } : {} });
-        for (const [k, v] of Object.entries(props ?? {})) setProp(doc, { kind: "group", id: g.id }, k, v);
-        return { added: nameOf(g), groups: doc.groups.map(nameOf) };
-      });
-      return ok(text(res));
-    })
-  );
-  server.registerTool(
-    "icon_add_layer",
-    {
-      title: "Add layer",
-      description: "Adds an image layer to a group (the group is created if it does not exist). Provide either `svg` (inline SVG markup), `source` (path to an .svg/.png/.jpg file inside the allowed roots) or `png_base64`. Artwork should be a square, unmasked 1024\xD71024 canvas with a transparent background; it is placed at its natural size, centered.",
-      inputSchema: {
-        path: z2.string(),
-        group: z2.string().describe("Group name or #index. A missing group is created in front (index 0); use icon_move to reorder."),
-        svg: z2.string().optional().describe("Inline SVG markup"),
-        source: z2.string().optional().describe("Image file path"),
-        png_base64: z2.string().optional(),
-        file_name: z2.string().optional().describe('Name to store in Assets/, e.g. "star.svg"'),
-        name: z2.string().optional().describe("Layer name"),
-        index: z2.number().int().min(0).optional().describe("Position inside the group, 0 = frontmost (default)"),
-        props: z2.record(z2.string(), z2.any()).optional().describe('Layer attributes, e.g. {"glass": true, "opacity": 0.8, "fill": "#FFFFFF", "position": {"scale": 0.8, "translation-in-points": [0, -40]}}')
-      }
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          const g = addGroup(doc, { name, ...index !== void 0 ? { index } : {} });
+          for (const [k, v] of Object.entries(props ?? {})) setProp(doc, { kind: "group", id: g.id }, k, v);
+          return { added: nameOf(g), groups: doc.groups.map(nameOf) };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_add_layer",
+    cli: "add-layer",
+    positional: ["path"],
+    title: "Add layer",
+    summary: "Adds a layer from inline SVG, an image file or PNG data",
+    description: "Adds an image layer to a group (the group is created if it does not exist). Provide either `svg` (inline SVG markup), `source` (path to an .svg/.png/.jpg file inside the allowed roots) or `png_base64`. Artwork should be a square, unmasked 1024\xD71024 canvas with a transparent background; it is placed at its natural size, centered.",
+    role: "edit",
+    capabilities: ["layers", "images", "glass"],
+    input: {
+      path: pathArg,
+      group: z2.string().describe("Group name or #index. A missing group is created in front (index 0); use icon_move to reorder."),
+      svg: z2.string().optional().describe("Inline SVG markup"),
+      source: z2.string().optional().describe("Image file path"),
+      png_base64: z2.string().optional(),
+      file_name: z2.string().optional().describe('Name to store in Assets/, e.g. "star.svg"'),
+      name: z2.string().optional().describe("Layer name"),
+      index: z2.number().int().min(0).optional().describe("Position inside the group, 0 = frontmost (default)"),
+      props: z2.record(z2.string(), z2.any()).optional().describe('Layer attributes, e.g. {"glass": true, "opacity": 0.8, "fill": "#FFFFFF", "position": {"scale": 0.8, "translation-in-points": [0, -40]}}'),
+      dry_run: dryRunArg
     },
-    safe(async ({ path, group, svg, source, png_base64, file_name, name, index, props }) => {
+    output: loose({ added: z2.string(), size: z2.string(), warnings: z2.array(z2.string()) }),
+    mutates_input: true,
+    idempotency_hint: "not-idempotent",
+    supports_dry_run: true,
+    verification: ["Check `warnings` (V-01\u2026V-10)", "icon_render_sheet to see the layer in every appearance"],
+    requires_visual_verification: true,
+    examples: [
+      { args: { path: "Demo.icon", group: "Front", svg: EX_STAR, name: "Star" }, note: 'Inline SVG; the "Front" group is created in front' },
+      { args: { path: "Demo.icon", group: "Back", svg: EX_DOT, name: "Dot", props: { opacity: 0.8 } }, note: "A second layer behind it" }
+    ],
+    async run(ws, { path, group, svg, source, png_base64, file_name, name, index, props, dry_run }) {
       const given = [svg, source, png_base64].filter((x) => x !== void 0).length;
       if (given !== 1) throw new Error("Provide exactly one of svg, source or png_base64");
       let bytes;
@@ -1898,129 +2384,242 @@ function createServer(ws) {
       const asset = makeAsset(fname, bytes);
       if (asset.kind === "other") throw new Error("Unsupported image. Use SVG, PNG or JPEG.");
       const full = await ws.iconPath(path, { mustExist: true });
-      const res = await ws.edit(full, (doc) => {
-        let gid;
-        try {
-          const ref = resolvePath(doc, group);
-          if (ref.kind !== "group") throw new Error("`group` must name a group");
-          gid = ref.id;
-        } catch (e) {
-          const g = group.trim();
-          if (/^#\d+$/.test(g) || g.includes("/") || !/not found/i.test(e.message)) throw e;
-          gid = addGroup(doc, { name: g }).id;
-        }
-        const l = addLayer(doc, gid, asset, {
-          ...name ? { name } : {},
-          ...index !== void 0 ? { index } : {},
-          ...props ? { props } : {}
-        });
-        return {
-          added: targetLabel(doc, { kind: "layer", id: l.id }),
-          size: `${asset.width}\xD7${asset.height}`,
-          warnings: validate(doc).filter((i) => i.ref?.kind === "layer" && i.ref.id === l.id).map((i) => `${i.id}: ${i.message}`)
-        };
-      });
-      return ok(text(res));
-    })
-  );
-  server.registerTool(
-    "icon_set",
-    {
-      title: "Set attributes",
-      description: 'Sets attributes on the document, a group or a layer. Pass `appearance` ("dark", or "tinted" = Mono in Icon Composer) and/or `platform` ("iOS", "macOS", "watchOS", "square" = iOS+macOS) to write a variant for only that case. Set a value to null to remove it (or to remove the override when `appearance` is given). See fresnel://schema/icon-json for keys and formats.',
-      inputSchema: {
-        path: z2.string(),
-        target: z2.string().describe('"document", "<Group>" or "<Group>/<Layer>" (names or #index)'),
-        props: z2.record(z2.string(), z2.any()).describe('kebab-case keys, e.g. {"translucency": {"enabled": true, "value": 0.6}, "specular": true}'),
-        appearance: overrideEnum.optional(),
-        platform: z2.enum(["iOS", "macOS", "watchOS", "square"]).optional()
-      }
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          let gid;
+          try {
+            const ref = resolvePath(doc, group);
+            if (ref.kind !== "group") throw new Error("`group` must name a group");
+            gid = ref.id;
+          } catch (e) {
+            const g = group.trim();
+            if (/^#\d+$/.test(g) || g.includes("/") || !/not found/i.test(e.message)) throw e;
+            gid = addGroup(doc, { name: g }).id;
+          }
+          const l = addLayer(doc, gid, asset, {
+            ...name ? { name } : {},
+            ...index !== void 0 ? { index } : {},
+            ...props ? { props } : {}
+          });
+          return {
+            added: targetLabel(doc, { kind: "layer", id: l.id }),
+            size: `${asset.width}\xD7${asset.height}`,
+            warnings: validate(doc).filter((i) => i.ref?.kind === "layer" && i.ref.id === l.id).map((i) => `${i.id}: ${i.message}`)
+          };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_set",
+    cli: "set",
+    positional: ["path"],
+    title: "Set attributes",
+    summary: "Sets attributes for all appearances, or a dark / tinted / platform variant",
+    description: 'Sets attributes on the document, a group or a layer. Pass `appearance` ("dark", or "tinted" = Mono in Icon Composer) and/or `platform` ("iOS", "macOS", "watchOS", "square" = iOS+macOS) to write a variant for only that case. Set a value to null to remove it (or to remove the override when `appearance` is given). See fresnel://schema/icon-json for keys and formats.',
+    role: "edit",
+    capabilities: ["attributes", "appearance-overrides", "platform-variants", "glass"],
+    input: {
+      path: pathArg,
+      target: z2.string().describe('"document", "<Group>" or "<Group>/<Layer>" (names or #index)'),
+      props: z2.record(z2.string(), z2.any()).describe('kebab-case keys, e.g. {"translucency": {"enabled": true, "value": 0.6}, "specular": true}'),
+      appearance: overrideEnum.optional(),
+      platform: platformEnum.optional(),
+      dry_run: dryRunArg
     },
-    safe(async ({ path, target, props, appearance, platform }) => {
+    output: loose({ target: z2.string(), now: z2.record(z2.string(), z2.unknown()) }),
+    mutates_input: true,
+    idempotency_hint: "idempotent",
+    supports_dry_run: true,
+    verification: ["`now` shows the stored values", "icon_render_sheet for the appearances you changed"],
+    requires_visual_verification: true,
+    examples: [
+      { args: { path: "Demo.icon", target: "Front", props: { translucency: { enabled: true, value: 0.4 }, specular: true } }, note: "Glass settings on a group" },
+      { args: { path: "Demo.icon", target: "Front/Star", props: { fill: "#FFD60A" }, appearance: "dark" }, note: "A dark-mode color for one layer" }
+    ],
+    async run(ws, { path, target, props, appearance, platform, dry_run }) {
       const full = await ws.iconPath(path, { mustExist: true });
-      const res = await ws.edit(full, (doc) => {
-        const ref = resolvePath(doc, target);
-        const variant = appearance || platform ? { ...appearance ? { appearance } : {}, ...platform ? { idiom: platform } : {} } : void 0;
-        for (const [k, v] of Object.entries(props)) setProp(doc, ref, k, v, variant);
-        return { target: targetLabel(doc, ref), now: describeProps(nodeOf(doc, ref).props) };
-      });
-      return ok(text(res));
-    })
-  );
-  server.registerTool(
-    "icon_remove",
-    {
-      title: "Remove group or layer",
-      description: "Removes a group or a layer. Unused assets are deleted from Assets/.",
-      inputSchema: { path: z2.string(), target: z2.string() },
-      annotations: { destructiveHint: true }
-    },
-    safe(async ({ path, target }) => {
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          const ref = resolvePath(doc, target);
+          const variant = appearance || platform ? { ...appearance ? { appearance } : {}, ...platform ? { idiom: platform } : {} } : void 0;
+          for (const [k, v] of Object.entries(props)) setProp(doc, ref, k, v, variant);
+          return { target: targetLabel(doc, ref), now: describeProps(nodeOf(doc, ref).props) };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_move",
+    cli: "move",
+    positional: ["path"],
+    title: "Reorder",
+    summary: "Reorders groups and layers, or moves a layer to another group",
+    description: "Moves a group or layer to a new index (0 = frontmost). Layers can move to another group with to_group.",
+    role: "edit",
+    capabilities: ["groups", "layers", "order"],
+    input: { path: pathArg, target: z2.string(), index: z2.number().int().min(0), to_group: z2.string().optional(), dry_run: dryRunArg },
+    output: loose({ groups: groupsOutline }),
+    mutates_input: true,
+    idempotency_hint: "idempotent",
+    supports_dry_run: true,
+    verification: ["`groups` lists the new order (front to back)"],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon", target: "Back", index: 1 }, note: "Keep the Back group behind Front" }],
+    async run(ws, { path, target, index, to_group, dry_run }) {
       const full = await ws.iconPath(path, { mustExist: true });
-      const res = await ws.edit(full, (doc) => {
-        const ref = resolvePath(doc, target);
-        const label = targetLabel(doc, ref);
-        removeNode(doc, ref);
-        return { removed: label, groups: inspect(doc).groups.map((g) => ({ group: g.target, layers: g.layers.map((l) => l.target) })) };
-      });
-      return ok(text(res));
-    })
-  );
-  server.registerTool(
-    "icon_move",
-    {
-      title: "Reorder",
-      description: "Moves a group or layer to a new index (0 = frontmost). Layers can move to another group with to_group.",
-      inputSchema: { path: z2.string(), target: z2.string(), index: z2.number().int().min(0), to_group: z2.string().optional() }
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          const ref = resolvePath(doc, target);
+          let gid;
+          if (to_group) {
+            const g = resolvePath(doc, to_group);
+            if (g.kind !== "group") throw new Error("to_group must be a group");
+            gid = g.id;
+          }
+          moveNode(doc, ref, index, gid);
+          return { groups: outline(doc) };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_align",
+    cli: "align",
+    positional: ["path"],
+    title: "Align or distribute",
+    summary: "Aligns or distributes groups or layers (to each other or to the canvas)",
+    description: 'Aligns groups or layers by their bounding boxes (left, hcenter, right, top, vcenter, bottom), or spaces 3+ items evenly (distribute-horizontal, distribute-vertical). With one target, or basis "canvas", items align to the 1024 pt canvas. Only positions change.',
+    role: "edit",
+    capabilities: ["layout", "align", "distribute", "platform-variants"],
+    input: {
+      path: pathArg,
+      targets: z2.array(z2.string()).min(1).describe('"<Group>" or "<Group>/<Layer>" (names or #index); all of the same kind'),
+      how: z2.enum(["left", "hcenter", "right", "top", "vcenter", "bottom", "distribute-horizontal", "distribute-vertical"]),
+      basis: z2.enum(["selection", "canvas"]).optional().describe("Default: selection (canvas when there is one target)"),
+      platform: platformEnum.optional().describe("Write the positions as a platform variant"),
+      dry_run: dryRunArg
     },
-    safe(async ({ path, target, index, to_group }) => {
+    output: loose({ moved: z2.number(), positions: z2.array(z2.looseObject({ target: z2.string() })) }),
+    mutates_input: true,
+    idempotency_hint: "idempotent",
+    supports_dry_run: true,
+    verification: ["`positions` gives each bounding box in canvas points", "icon_render to look at the result"],
+    requires_visual_verification: true,
+    examples: [{ args: { path: "Demo.icon", targets: ["Front/Star"], how: "vcenter" }, note: "Center one layer vertically on the canvas" }],
+    async run(ws, { path, targets, how, basis, platform, dry_run }) {
       const full = await ws.iconPath(path, { mustExist: true });
-      const res = await ws.edit(full, (doc) => {
-        const ref = resolvePath(doc, target);
-        let gid;
-        if (to_group) {
-          const g = resolvePath(doc, to_group);
-          if (g.kind !== "group") throw new Error("to_group must be a group");
-          gid = g.id;
-        }
-        moveNode(doc, ref, index, gid);
-        return inspect(doc).groups.map((g) => ({ group: g.target, layers: g.layers.map((l) => l.target) }));
-      });
-      return ok(text(res));
-    })
-  );
-  server.registerTool(
-    "icon_validate",
-    {
-      title: "Validate",
-      description: "Checks the icon against the schema and Apple HIG recommendations (square unmasked layers, opaque background, no text, variants, \u2026).",
-      inputSchema: { path: z2.string() },
-      annotations: { readOnlyHint: true }
-    },
-    safe(async ({ path }) => {
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          const refs = targets.map((t) => resolvePath(doc, t));
+          if (refs.some((r) => r.kind === "document")) throw new Error("targets must be groups or layers");
+          if (new Set(refs.map((r) => r.kind)).size > 1) throw new Error("targets must all be groups or all be layers");
+          const ctx = { appearance: "default", idiom: platform === "square" || !platform ? "iOS" : platform };
+          const variant = platform ? { idiom: platform } : void 0;
+          const moved = how.startsWith("distribute-") ? distributeNodes(doc, refs, how === "distribute-horizontal" ? "horizontal" : "vertical", ctx, { variant }) : alignNodes(doc, refs, how, ctx, { ...basis ? { basis } : {}, variant });
+          return { moved, positions: refs.map((r, i) => ({ target: targets[i], box: boxOf(doc, r, ctx) })) };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_remove",
+    cli: "remove",
+    positional: ["path"],
+    title: "Remove group or layer",
+    summary: "Deletes a group or layer (unused assets go too)",
+    description: "Removes a group or a layer. Unused assets are deleted from Assets/.",
+    role: "edit",
+    capabilities: ["groups", "layers"],
+    input: { path: pathArg, target: z2.string(), dry_run: dryRunArg },
+    output: loose({ removed: z2.string(), groups: groupsOutline }),
+    mutates_input: true,
+    idempotency_hint: "not-idempotent",
+    destructive: true,
+    supports_dry_run: true,
+    verification: ["`groups` no longer lists the target"],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon", target: "Back/Dot", dry_run: true }, note: "Preview a removal without writing" }],
+    async run(ws, { path, target, dry_run }) {
+      const full = await ws.iconPath(path, { mustExist: true });
+      const data = await ws.edit(
+        full,
+        (doc) => {
+          const ref = resolvePath(doc, target);
+          const label = targetLabel(doc, ref);
+          removeNode(doc, ref);
+          return { removed: label, groups: outline(doc) };
+        },
+        { dryRun: !!dry_run }
+      );
+      return { data };
+    }
+  }),
+  tool({
+    id: "icon_validate",
+    cli: "validate",
+    positional: ["path"],
+    title: "Validate",
+    summary: "Runs the icon checks (schema and Apple HIG)",
+    description: "Checks the icon against the schema and Apple HIG recommendations (square unmasked layers, opaque background, no text, variants, \u2026).",
+    role: "check",
+    capabilities: ["validate", "hig"],
+    input: { path: pathArg },
+    output: loose({
+      summary: z2.looseObject({ errors: z2.number(), warnings: z2.number(), infos: z2.number() }),
+      issues: z2.array(z2.looseObject({ id: z2.string(), severity: z2.enum(["error", "warning", "info"]), message: z2.string() }))
+    }),
+    mutates_input: false,
+    idempotency_hint: "idempotent",
+    supports_dry_run: false,
+    verification: ['No issue with severity "error"'],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon" }, note: "Run the V-01\u2026V-10 checks" }],
+    async run(ws, { path }) {
       const full = await ws.iconPath(path, { mustExist: true });
       const issues = validate(await ws.read(full)).map(({ ref: _ref, ...i }) => i);
-      return ok(text({ summary: summarizeIssues(issues), issues }));
-    })
-  );
-  server.registerTool(
-    "icon_render",
-    {
-      title: "Render preview",
-      description: "Renders an approximate preview PNG of one appearance and returns it as an image. Optionally saves it with `out`.",
-      inputSchema: {
-        path: z2.string(),
-        appearance: appearanceEnum.optional().describe('Default: "default". Mono in Icon Composer = clear-light / clear-dark / tinted-light / tinted-dark'),
-        platform: z2.enum(["iOS", "macOS", "watchOS"]).optional().describe("Default: iOS. watchOS renders a circle"),
-        size: z2.number().int().min(16).max(2048).optional().describe("Pixels, default 512"),
-        mask: maskEnum.optional(),
-        tint: z2.string().optional().describe('Tint color for tinted appearances, "#RRGGBB"'),
-        light_angle: z2.number().min(-180).max(180).optional().describe("Light direction in degrees, 0 = top, -45 = top-left (default)"),
-        out: z2.string().optional().describe("Save the PNG to this path")
-      },
-      annotations: { readOnlyHint: true }
+      return { data: { summary: summarizeIssues(issues), issues } };
+    }
+  }),
+  tool({
+    id: "icon_render",
+    cli: "render",
+    positional: ["path"],
+    title: "Render preview",
+    summary: "Returns a PNG of one appearance as an image the model can see",
+    description: "Renders an approximate preview PNG of one appearance and returns it as an image. Optionally saves it with `out`.",
+    role: "render",
+    capabilities: ["preview", "appearances", "platforms"],
+    input: {
+      path: pathArg,
+      appearance: appearanceEnum.optional().describe('Default: "default". Mono in Icon Composer = clear-light / clear-dark / tinted-light / tinted-dark'),
+      platform: z2.enum(["iOS", "macOS", "watchOS"]).optional().describe("Default: iOS. watchOS renders a circle"),
+      size: z2.number().int().min(16).max(2048).optional().describe("Pixels, default 512"),
+      mask: maskEnum.optional(),
+      tint: z2.string().optional().describe('Tint color for tinted appearances, "#RRGGBB"'),
+      light_angle: z2.number().min(-180).max(180).optional().describe("Light direction in degrees, 0 = top (default), -45 = top-left"),
+      out: z2.string().optional().describe("Save the PNG to this path")
     },
-    safe(async ({ path, appearance, platform, size, mask, tint, light_angle, out }) => {
+    output: loose({ appearance: z2.string(), saved: z2.string().optional() }),
+    mutates_input: false,
+    idempotency_hint: "idempotent",
+    supports_dry_run: false,
+    verification: ["Look at the returned image"],
+    requires_visual_verification: true,
+    examples: [{ args: { path: "Demo.icon", appearance: "dark", size: 128, out: "Demo-dark.png" }, note: "Dark preview saved as a file" }],
+    async run(ws, { path, appearance, platform, size, mask, tint, light_angle, out }) {
       const full = await ws.iconPath(path, { mustExist: true });
       const doc = await ws.read(full);
       const png = await renderPng(doc, {
@@ -2032,52 +2631,75 @@ function createServer(ws) {
         ...light_angle !== void 0 ? { lightAngle: light_angle } : {}
       });
       const saved = out ? await saveFile(ws, out, png) : void 0;
-      return ok({ type: "image", data: b642(png), mimeType: "image/png" }, text({ appearance: appearance ?? "default", ...saved ? { saved } : {} }));
-    })
-  );
-  server.registerTool(
-    "icon_render_sheet",
-    {
-      title: "Render all appearances",
-      description: "Renders the six appearances (Default, Clear light, Tinted light / Dark, Clear dark, Tinted dark) side by side and returns the PNG.",
-      inputSchema: {
-        path: z2.string(),
-        cell: z2.number().int().min(96).max(600).optional().describe("Cell size in pixels, default 240"),
-        tint: z2.string().optional(),
-        out: z2.string().optional()
-      },
-      annotations: { readOnlyHint: true }
+      return { data: { appearance: appearance ?? "default", ...saved ? { saved } : {} }, image: png };
+    }
+  }),
+  tool({
+    id: "icon_render_sheet",
+    cli: "render-sheet",
+    positional: ["path"],
+    title: "Render all appearances",
+    summary: "Returns all six appearances side by side as one PNG",
+    description: "Renders the six appearances (Default, Clear light, Tinted light / Dark, Clear dark, Tinted dark) side by side and returns the PNG.",
+    role: "render",
+    capabilities: ["preview", "appearances"],
+    input: {
+      path: pathArg,
+      cell: z2.number().int().min(96).max(600).optional().describe("Cell size in pixels, default 240"),
+      tint: z2.string().optional(),
+      out: z2.string().optional()
     },
-    safe(async ({ path, cell, tint, out }) => {
+    output: loose({ appearances: z2.array(z2.string()), saved: z2.string().optional() }),
+    mutates_input: false,
+    idempotency_hint: "idempotent",
+    supports_dry_run: false,
+    verification: ["Look at the returned image: every appearance should stay legible"],
+    requires_visual_verification: true,
+    examples: [{ args: { path: "Demo.icon", cell: 120 }, note: "Compare all six appearances" }],
+    async run(ws, { path, cell, tint, out }) {
       const full = await ws.iconPath(path, { mustExist: true });
       const png = await renderSheetPng(await ws.read(full), { cell: cell ?? 240, ...tint ? { tint } : {} });
       const saved = out ? await saveFile(ws, out, png) : void 0;
-      return ok({ type: "image", data: b642(png), mimeType: "image/png" }, ...saved ? [text({ saved })] : []);
-    })
-  );
-  server.registerTool(
-    "icon_export",
-    {
-      title: "Export",
-      description: 'Exports the icon. Formats: "icon" (copy of the .icon bundle for Xcode 26+ / Icon Composer), "icns" (macOS), "appiconset" (Xcode asset catalog with Dark and Tinted variants), "png" (PNG set per appearance and size). Raster formats use fresnel\u2019s approximate renderer. Assets.car requires Apple\u2019s actool on macOS and is not produced here.',
-      inputSchema: {
-        path: z2.string(),
-        out_dir: z2.string(),
-        formats: z2.array(z2.enum(["icon", "icns", "appiconset", "png"])).min(1),
-        sizes: z2.array(z2.number().int().min(16).max(2048)).optional().describe("PNG sizes, default [1024, 512, 256, 128, 64, 32, 16]"),
-        appearances: z2.array(appearanceEnum).optional().describe("PNG appearances, default all six")
-      }
+      return { data: { appearances: [...APPEARANCES], ...saved ? { saved } : {} }, image: png };
+    }
+  }),
+  tool({
+    id: "icon_export",
+    cli: "export",
+    positional: ["path"],
+    title: "Export",
+    summary: "Writes `.icon`, `.icns`, `AppIcon.appiconset` and PNG sets",
+    description: 'Exports the icon. Formats: "icon" (copy of the .icon bundle for Xcode 26+ / Icon Composer), "icns" (macOS), "appiconset" (Xcode asset catalog with Dark and Tinted variants), "png" (PNG set per appearance and size). Raster formats use fresnel\u2019s approximate renderer. Assets.car requires Apple\u2019s actool on macOS and is not produced here.',
+    role: "export",
+    capabilities: ["export", "icns", "appiconset", "png"],
+    input: {
+      path: pathArg,
+      out_dir: z2.string(),
+      formats: z2.array(z2.enum(["icon", "icns", "appiconset", "png"])).min(1),
+      sizes: z2.array(z2.number().int().min(16).max(2048)).optional().describe("PNG sizes, default [1024, 512, 256, 128, 64, 32, 16]"),
+      appearances: z2.array(appearanceEnum).optional().describe("PNG appearances, default all six")
     },
-    safe(async ({ path, out_dir, formats, sizes, appearances }) => {
+    output: loose({ out_dir: z2.string(), files: z2.number(), written: z2.array(z2.string()) }),
+    mutates_input: false,
+    idempotency_hint: "idempotent",
+    supports_dry_run: false,
+    verification: ["`written` lists every file", "Open the .icon in Icon Composer / Xcode 26 on a Mac for the final check"],
+    requires_visual_verification: false,
+    examples: [{ args: { path: "Demo.icon", out_dir: "build", formats: ["icon", "icns", "appiconset"] }, note: "Everything Xcode needs" }],
+    async run(ws, { path, out_dir, formats, sizes, appearances }) {
       const full = await ws.iconPath(path, { mustExist: true });
       const outDir = await ws.resolve(out_dir);
       const doc = await ws.read(full);
       const name = basename(full).replace(/\.icon(\.zip)?$/, "");
       const raster = nodeRasterizer(doc);
+      const missing = unrenderableLayers(doc);
+      if (missing.length && formats.some((f) => f !== "icon"))
+        throw new Error(`These visible layers can't be rendered and would be missing from the images: ${missing.join(", ")}. Fix them first (icon_validate).`);
       const written = [];
       if (formats.includes("icon")) {
-        const files = writeBundle(doc, doc.extra);
-        written.push(...await writeFiles(join2(outDir, `${name}.icon`), files));
+        const dest = join2(outDir, `${name}.icon`);
+        await saveIcon(dest, doc);
+        written.push(join2(dest, "icon.json"), ...Object.keys(doc.assets).map((a) => join2(dest, "Assets", a)));
       }
       if (formats.includes("icns")) {
         const p = join2(outDir, `${name}.icns`);
@@ -2085,17 +2707,211 @@ function createServer(ws) {
         await writeFile2(p, await buildIcns(raster));
         written.push(p);
       }
-      if (formats.includes("appiconset")) written.push(...await writeFiles(join2(outDir, "AppIcon.appiconset"), await buildAppIconSet(raster)));
+      if (formats.includes("appiconset")) written.push(...await writeFiles(join2(outDir, "AppIcon.appiconset"), await buildAppIconSet(raster, { watch: targetsWatch(doc) })));
       if (formats.includes("png"))
         written.push(
-          ...await writeFiles(
-            join2(outDir, `${name}-png`),
-            await buildPngSet(raster, appearances ?? [...APPEARANCES], sizes ?? [1024, 512, 256, 128, 64, 32, 16])
-          )
+          ...await writeFiles(join2(outDir, `${name}-png`), await buildPngSet(raster, appearances ?? [...APPEARANCES], sizes ?? [1024, 512, 256, 128, 64, 32, 16]))
         );
-      return ok(text({ out_dir: outDir, files: written.length, written }));
-    })
+      return { data: { out_dir: outDir, files: written.length, written } };
+    }
+  })
+];
+var toolById = (id) => TOOLS.find((t) => t.id === id);
+var toolByCli = (name) => TOOLS.find((t) => t.cli === name);
+async function runTool(ws, t, args) {
+  const parsed = z2.object(t.input).strict().safeParse(args ?? {});
+  if (!parsed.success) throw new Error(`Invalid arguments for ${t.id}: ${z2.prettifyError(parsed.error)}`);
+  return t.run(ws, parsed.data);
+}
+
+// ../mcp/src/version.ts
+var VERSION = "0.2.0";
+
+// ../mcp/src/contract.ts
+var RESOURCES = [
+  { uri: "fresnel://guide/icon-design", title: "Liquid Glass icon design guide" },
+  { uri: "fresnel://schema/icon-json", title: "icon.json attribute reference" },
+  { uri: "fresnel://contract", title: "SPEC contract (this document)" }
+];
+var PROMPTS = [{ name: "design_app_icon", title: "Design an app icon" }];
+var LEGACY_HELP = {
+  build: "fresnel build <spec.json> -o <Name.icon> \u2014 build a bundle from a JSON spec (fixtures/sample.spec.json)",
+  inspect: "fresnel inspect <Name.icon> \u2014 same output as icon_inspect",
+  validate: "fresnel validate <Name.icon> [--json] [--strict] \u2014 exit 1 on errors (--strict: also warnings)",
+  render: "fresnel render <Name.icon> [-a <appearance>] [-s <px>] [--mask \u2026] [--tint \u2026] [--sheet] [-o out.png] \u2014 writes a PNG file",
+  export: "fresnel export <Name.icon> -o <dir> [--formats \u2026] [--sizes \u2026] [--appearances \u2026] [--tint \u2026] [--force]",
+  mcp: "fresnel mcp [--root <dir>]\u2026 \u2014 start the MCP server on stdio"
+};
+var jsonSchema = (s, io) => {
+  const { $schema: _drop, ...rest } = z3.toJSONSchema(s, { io, unrepresentable: "any" });
+  return rest;
+};
+function attrTable(attrs) {
+  return Object.fromEntries(
+    Object.entries(attrs).map(([k, a]) => [k, { schema: jsonSchema(a.schema, "input"), default: a.default ?? null, description: a.description }])
   );
+}
+function toolSpec(t) {
+  return {
+    id: t.id,
+    title: t.title,
+    summary: t.summary,
+    description: t.description,
+    role: t.role,
+    capabilities: t.capabilities,
+    input_schema: jsonSchema(z3.object(t.input).strict(), "input"),
+    output_schema: jsonSchema(t.output, "output"),
+    mutates_input: t.mutates_input,
+    idempotency_hint: t.idempotency_hint,
+    destructive: !!t.destructive,
+    supports_dry_run: t.supports_dry_run,
+    supports_json: true,
+    returns_image: t.role === "render",
+    verification: t.verification,
+    requires_visual_verification: t.requires_visual_verification,
+    cli: usage(t),
+    examples: t.examples.map((e) => ({ ...e, cli: exampleCommand(t, e.args) }))
+  };
+}
+function buildContract() {
+  const capability_map = {};
+  for (const t of TOOLS) for (const c of t.capabilities) (capability_map[c] ??= []).push(t.id);
+  return {
+    contract_version: CONTRACT_VERSION,
+    name: "fresnel",
+    version: VERSION,
+    description: "Create, edit, preview and export Apple Liquid Glass app icons (.icon bundles, the Icon Composer format).",
+    conventions: {
+      targets: '"document", "<Group>" or "<Group>/<Layer>" (names or #index; index 0 is frontmost)',
+      order: "groups and layers are listed front to back",
+      errors: "MCP: isError with a readable message. CLI: message on stderr, exit code 1",
+      cli: `argument names are the input names with "_" \u2192 "-"; arrays are comma separated; objects are JSON; --args '<json>' passes everything at once`,
+      previews: "approximations of Apple's renderer; the final check is Icon Composer / Xcode 26 on a Mac"
+    },
+    stability: {
+      compatible: ["new tools", "new optional arguments", "new output keys", "new enum values", "wording of descriptions, examples and verification"],
+      breaking: ["removing or renaming a tool or argument", "optional \u2192 required", "changing an argument type", "removing an enum value", "removing an output key"],
+      rule: "Breaking changes bump contract_version to the next major. The frozen surface (packages/mcp/spec/surface.json) makes CI fail otherwise."
+    },
+    tools: TOOLS.map(toolSpec),
+    capability_map: Object.fromEntries(Object.entries(capability_map).sort(([a], [b]) => a.localeCompare(b))),
+    resources: RESOURCES,
+    prompts: PROMPTS,
+    icon_json: { document: attrTable(DOCUMENT_ATTRS), group: attrTable(GROUP_ATTRS), layer: attrTable(LAYER_ATTRS) },
+    cli_legacy_commands: LEGACY_HELP
+  };
+}
+
+// ../mcp/src/tools.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z4 } from "zod";
+
+// ../mcp/src/guide.ts
+var ICON_GUIDE = `# Designing Liquid Glass app icons (iOS, iPadOS, macOS, watchOS)
+
+Source: Apple Human Interface Guidelines, "App icons"
+https://developer.apple.com/design/human-interface-guidelines/app-icons
+
+## Structure
+- An icon is a background plus one or more foreground layers. The system adds Liquid Glass effects (specular highlights, refraction, translucency) and adapts them to size and system version.
+- Canvas: 1024\xD71024 for iOS/iPadOS/macOS (masked to a rounded rectangle) and 1088\xD71088 for watchOS (masked to a circle).
+- Appearances: Default, Dark, Clear light, Clear dark, Tinted light, Tinted dark. If you don't provide a variant, the system generates one.
+- Groups: Liquid Glass effects (mode, specular Off/Automatic/Inside/Outside, blur, refraction, translucency, shadow) are configured per group. Use at most 4 groups (Apple's recommendation; some actool versions reject more).
+- In Icon Composer the appearances are Default, Dark and Mono (Mono covers clear and tinted); icon.json stores Mono overrides under the "tinted" key.
+
+## Layers
+- Provide square, unmasked layers. Never bake in rounded corners; the system masks the icon, and pre-masked layers break the specular highlights and leave jagged edges.
+- Prefer clearly defined edges. Avoid soft or feathered shapes.
+- Import layers fully opaque and set transparency in the tool. Varying opacity across foreground layers adds depth.
+- Prefer vector art (SVG/PDF). Convert text to outlines. Use PNG for raster art and mesh gradients.
+- Don't bake in highlights, drop shadows, bevels, blurs or glows. The system draws dynamic effects.
+
+## Design
+- Keep it simple. Use one core idea expressed with a minimal number of filled, overlapping shapes.
+- Prefer a simple background, such as a solid color or gradient. A background image must be full-bleed and opaque.
+- Keep primary content centered so masking (especially circles on watchOS) doesn't truncate it.
+- Avoid text unless it's essential. Avoid photos, UI screenshots and replicas of Apple hardware.
+- Avoid very thin lines and sharp corners; they disappear at small sizes.
+
+## Appearances
+- Keep the same core features across all appearances. Don't swap elements in and out.
+- Base the dark icon on the light one, using complementary, less bright colors. Colored backgrounds give the most contrast in dark mode.
+- Dark, clear and tinted icons are more subdued. Check that the icon stays legible and recognizable in all of them.
+
+## fresnel workflow
+1. icon_create with a background (e.g. "gradient:#3D7BFF,#0E2A8A").
+2. Draw each foreground element as its own 1024\xD71024 SVG (transparent background, centered artwork) and add it with icon_add_layer.
+3. Use groups for depth: put elements that should share glass settings in one group. Index 0 is the frontmost.
+4. Set glass on layers that should catch highlights, then tune the group: translucency, blur-material, specular, shadow.
+5. Add Dark and Mono ("tinted") overrides with icon_set (appearance: "dark" or "tinted"), and platform variants (platform: "watchOS", \u2026) where layout differs.
+6. Check icon_render_sheet and icon_validate, then icon_export.
+`;
+function table(title, defs) {
+  const rows = Object.entries(defs).map(([k, d]) => `| \`${k}\` | ${d.description} | \`${JSON.stringify(d.default)}\` |`);
+  return `### ${title}
+
+| key | meaning | default when absent |
+|---|---|---|
+${rows.join("\n")}
+`;
+}
+var SCHEMA_GUIDE = `# icon.json attributes understood by fresnel
+
+The format isn't documented by Apple. This reference is reverse-engineered (glassmith, icon-composer-template, real Icon Composer files).
+Any attribute can be overridden per appearance with icon_set(..., appearance: "dark" | "tinted").
+Unknown attributes are accepted and preserved.
+
+${table("Document", DOCUMENT_ATTRS)}
+${table("Group", GROUP_ATTRS)}
+${table("Layer", LAYER_ATTRS)}
+
+### Value formats
+- Color: "#RRGGBB" (stored as srgb) or Icon Composer strings: "display-p3:r,g,b,a", "srgb:r,g,b,a", "extended-gray:l,a"
+- Fill: "automatic" | "system-light" | "system-dark" | "none" | {"solid": color} | {"automatic-gradient": color} | {"linear-gradient": [color, color], "orientation": {"start": {"x","y"}, "stop": {"x","y"}}}
+  Shorthands: "#336699" \u2192 solid, "gradient:#top,#bottom" \u2192 linear-gradient, "auto-gradient:#color" \u2192 automatic-gradient
+- Position: {"scale": 1, "translation-in-points": [x, y]} (points on the 1024 canvas, y down, relative to center)
+- Shadow: {"kind": "none" | "neutral" | "layer-color", "opacity": 0\u20131}
+- Translucency: {"enabled": true, "value": 0\u20131}
+- Blend modes: normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, soft-light, hard-light, difference, exclusion, hue, saturation, color, luminosity, plus-darker, plus-lighter
+`;
+
+// ../mcp/src/tools.ts
+var text = (v) => ({ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) });
+var fail = (e) => ({ content: [text(`Error: ${e.message}`)], isError: true });
+var b642 = (u) => Buffer.from(u).toString("base64");
+function createServer(ws) {
+  const server = new McpServer(
+    { name: "fresnel", version: VERSION },
+    {
+      instructions: 'fresnel edits Apple Liquid Glass app icons stored as .icon bundles (the Icon Composer format). Typical flow: icon_create \u2192 icon_add_layer (one 1024\xD71024 SVG per element) \u2192 icon_set (glass, translucency, dark/tinted overrides) \u2192 icon_render_sheet to look at all appearances \u2192 icon_validate \u2192 icon_export. Read fresnel://guide/icon-design for Apple design rules. Targets are "document", "<Group>" or "<Group>/<Layer>" (names or #index; index 0 is frontmost). Previews are approximations of the system renderer.'
+    }
+  );
+  for (const t of TOOLS) {
+    server.registerTool(
+      t.id,
+      {
+        title: t.title,
+        description: t.description,
+        inputSchema: t.input,
+        outputSchema: t.output,
+        annotations: {
+          readOnlyHint: !t.mutates_input,
+          destructiveHint: !!t.destructive,
+          idempotentHint: t.idempotency_hint === "idempotent",
+          openWorldHint: false
+        }
+      },
+      async (args) => {
+        try {
+          const { data, image } = await runTool(ws, t, args);
+          const content = image ? [{ type: "image", data: b642(image), mimeType: "image/png" }, text(data)] : [text(data)];
+          return { content, structuredContent: data };
+        } catch (e) {
+          return fail(e);
+        }
+      }
+    );
+  }
   server.registerResource(
     "icon-design-guide",
     "fresnel://guide/icon-design",
@@ -2108,15 +2924,21 @@ function createServer(ws) {
     { title: "icon.json attribute reference", description: "Keys, value formats and defaults fresnel understands", mimeType: "text/markdown" },
     async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: SCHEMA_GUIDE }] })
   );
+  server.registerResource(
+    "contract",
+    "fresnel://contract",
+    { title: "SPEC contract", description: "Machine-readable contract: every tool with input/output JSON Schema, roles, verification and examples, plus the icon.json attribute table", mimeType: "application/json" },
+    async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(buildContract(), null, 2) }] })
+  );
   server.registerPrompt(
     "design_app_icon",
     {
       title: "Design an app icon",
       description: "Step-by-step workflow to design a Liquid Glass app icon from an app description",
       argsSchema: {
-        app: z2.string().describe("What the app does"),
-        path: z2.string().optional().describe("Where to save the .icon bundle"),
-        style: z2.string().optional().describe("Colors / mood / constraints")
+        app: z4.string().describe("What the app does"),
+        path: z4.string().optional().describe("Where to save the .icon bundle"),
+        style: z4.string().optional().describe("Colors / mood / constraints")
       }
     },
     ({ app, path, style }) => ({
@@ -2145,12 +2967,6 @@ Use the fresnel tools:
   );
   return server;
 }
-async function saveFile(ws, out, bytes) {
-  const p = await ws.resolve(out);
-  await mkdir2(dirname2(p), { recursive: true });
-  await writeFile2(p, bytes);
-  return p;
-}
 
 // ../mcp/src/workspace.ts
 import { realpath, stat as stat3 } from "fs/promises";
@@ -2158,8 +2974,11 @@ import { dirname as dirname3, isAbsolute as isAbsolute2, relative as relative2,
 var Workspace = class {
   roots;
   locks = /* @__PURE__ */ new Map();
-  constructor(roots) {
+  /** With `unrestricted` (the CLI without --root) any path is allowed; relative paths still start at the first root. */
+  unrestricted;
+  constructor(roots, opts = {}) {
     this.roots = (roots.length ? roots : [process.cwd()]).map((r) => resolve2(r));
+    this.unrestricted = !!opts.unrestricted;
   }
   /** Resolves a user path (relative paths are relative to the first root) and checks it's allowed. */
   async resolve(p, opts = {}) {
@@ -2185,6 +3004,7 @@ var Workspace = class {
     }
   }
   async allowed(full) {
+    if (this.unrestricted) return true;
     for (const r of this.roots) {
       let root = r;
       try {
@@ -2209,12 +3029,12 @@ var Workspace = class {
     return full;
   }
   /** Serializes edits per file so concurrent tool calls can't clobber each other. */
-  async edit(path, fn) {
+  async edit(path, fn, opts = {}) {
     return this.withLock(path, async () => {
       if (path.endsWith(".zip")) throw new Error("Editing .icon.zip is not supported; unzip it first or use the .icon folder");
       const doc = await loadIcon(path);
       const result = await fn(doc);
-      await saveIcon(path, doc);
+      if (!opts.dryRun) await saveIcon(path, doc);
       return result;
     });
   }
@@ -2234,7 +3054,8 @@ var Workspace = class {
 };
 
 // src/cli.ts
-var HELP = `fresnel ${VERSION} \u2014 Liquid Glass app icon tools
+var pad = (s, n2) => s.length >= n2 ? `${s}  ` : s.padEnd(n2);
+var HELP = `fresnel ${VERSION} \u2014 Liquid Glass app icon tools (contract ${CONTRACT_VERSION})
 
 Usage
   fresnel build <spec.json> -o <Name.icon>      Build an .icon bundle from a JSON spec
@@ -2245,14 +3066,42 @@ Usage
                                                  Render an approximate preview PNG
   fresnel export <Name.icon> -o <dir> [--formats icon,icns,appiconset,png]
                  [--sizes 1024,512,...] [--appearances default,dark,...]
-                 [--tint #RRGGBB]
+                 [--tint #RRGGBB] [--force]
   fresnel mcp [--root <dir>]...                  Start the MCP server on stdio
 
 Render options: --mask squircle|circle|none, --tint #RRGGBB (tinted appearances)
 
+Tools (same arguments as the MCP server; JSON on stdout; "fresnel <command> --help" for details)
+${TOOLS.map((t) => `  ${pad(`fresnel ${cliCommand(t)}`, 31)}${t.summary.replace(/`/g, "")}`).join("\n")}
+
+  fresnel contract [--json]                      Print the SPEC contract (every tool, its schemas, roles and examples)
+  Options for tools: --args '<json>' (all arguments at once), --root <dir> (limit file access)
+
 Appearances: ${APPEARANCES.join(", ")}
 Docs: https://github.com/kajisho5/fresnel
 `;
+async function callTool(t, argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(toolHelp(t));
+    return;
+  }
+  const roots = [];
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--root" || a === "-r") {
+      const v = argv[++i];
+      if (!v) throw new Error("--root needs a directory");
+      roots.push(v);
+    } else if (a.startsWith("--root=")) roots.push(a.slice(7));
+    else rest.push(a);
+  }
+  const ws = new Workspace(roots, { unrestricted: roots.length === 0 });
+  const { data, image } = await runTool(ws, t, parseToolArgv(t, rest));
+  if (image && !data.saved) process.stderr.write("fresnel: the PNG was not saved; pass --out <file.png> to keep it\n");
+  process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+}
 async function build(specPath, out) {
   const spec = JSON.parse(await readFile3(specPath, "utf8"));
   const base = dirname4(resolve3(specPath));
@@ -2311,6 +3160,30 @@ async function main() {
     console.log(VERSION);
     return;
   }
+  if (cmd === "contract") {
+    if (rest.some((a) => a !== "--json")) throw new Error("Usage: fresnel contract [--json]");
+    process.stdout.write(`${JSON.stringify(buildContract(), null, 2)}
+`);
+    return;
+  }
+  if (cmd === "call") {
+    const [id, ...args] = rest;
+    if (!id || id === "--help" || id === "-h") {
+      process.stdout.write(`Usage: fresnel call <tool_id> [args]
+Tools: ${TOOLS.map((t2) => t2.id).join(", ")}
+`);
+      return;
+    }
+    const t = toolById(id) ?? toolById(`icon_${id.replace(/-/g, "_")}`);
+    if (!t) throw new Error(`Unknown tool "${id}". Tools: ${TOOLS.map((x) => x.id).join(", ")}`);
+    await callTool(t, args);
+    return;
+  }
+  const short = toolByCli(cmd);
+  if (short && cliCommand(short) === short.cli) {
+    await callTool(short, rest);
+    return;
+  }
   const { values, positionals } = parseArgs({
     args: rest,
     allowPositionals: true,
@@ -2327,6 +3200,7 @@ async function main() {
       tint: { type: "string" },
       mask: { type: "string" },
       root: { type: "string", short: "r", multiple: true },
+      force: { type: "boolean" },
       help: { type: "boolean", short: "h" }
     }
   });
@@ -2381,14 +3255,19 @@ async function main() {
       const formats = (values.formats ?? "icon,icns,appiconset,png").split(",").map((s) => s.trim());
       const raster = nodeRasterizer(doc, values.tint ? { tint: values.tint } : {});
       const outDir = resolve3(values.out);
+      const missing = unrenderableLayers(doc);
+      if (missing.length && formats.some((f) => f !== "icon") && !values.force)
+        throw new Error(`These visible layers can't be rendered and would be missing from the images: ${missing.join(", ")}. Fix them, or pass --force.`);
       let n2 = 0;
       for (const f of formats) {
-        if (f === "icon") n2 += (await writeFiles(join3(outDir, `${name}.icon`), writeBundle(doc, doc.extra))).length;
-        else if (f === "icns") {
+        if (f === "icon") {
+          await saveIcon(join3(outDir, `${name}.icon`), doc);
+          n2 += 1 + Object.keys(doc.assets).length;
+        } else if (f === "icns") {
           await mkdir3(outDir, { recursive: true });
           await writeFile3(join3(outDir, `${name}.icns`), await buildIcns(raster));
           n2++;
-        } else if (f === "appiconset") n2 += (await writeFiles(join3(outDir, "AppIcon.appiconset"), await buildAppIconSet(raster))).length;
+        } else if (f === "appiconset") n2 += (await writeFiles(join3(outDir, "AppIcon.appiconset"), await buildAppIconSet(raster, { watch: targetsWatch(doc) }))).length;
         else if (f === "png") {
           const sizes = (values.sizes ?? "1024,512,256,128,64,32,16").split(",").map(Number);
           n2 += (await writeFiles(join3(outDir, `${name}-png`), await buildPngSet(raster, appearances(values.appearances), sizes))).length;