fui-studio-mcp 0.1.0 → 0.1.2

package/dist/{chunk-RAHWGTHJ.js → chunk-U3VXQSCB.js}

@@ -11,7 +11,7 @@ import {
   localFontBytes,
   parseBdf,
   resolveFace
-} from "./chunk-W7L36Z34.js";
+} from "./chunk-S3AUIOGZ.js";
 
 // ../../packages/fonts/dist/chunk-MTHRWFM6.js
 import * as opentype from "opentype.js";

package/dist/{dist-3URVYEPT.js → dist-LUAYBAOC.js}

@@ -28,7 +28,7 @@ import {
   stripPost,
   templateFiles,
   usedFonts
-} from "./chunk-W7L36Z34.js";
+} from "./chunk-S3AUIOGZ.js";
 export {
   OGRAF_KINDS,
   SCHEMA_URL,

package/dist/index.js

@@ -4,11 +4,12 @@ import {
   allTtfBuffers,
   fontDefs,
   nodeOutliner
-} from "./chunk-RAHWGTHJ.js";
+} from "./chunk-U3VXQSCB.js";
 import {
   DEFAULT_FONT_FAMILY,
   Keyframe,
   OgrafControl,
+  PRESETS,
   Param,
   ROOT_TYPES,
   adoptions,
@@ -38,7 +39,7 @@ import {
   wouldCycle,
   yuvFrameBytes,
   yuvToRgb
-} from "./chunk-W7L36Z34.js";
+} from "./chunk-S3AUIOGZ.js";
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -46,6 +47,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z as z2 } from "zod";
 import { createRequire as createRequire3 } from "module";
 import { homedir } from "os";
+import { dirname as dirname3, join as join4 } from "path";
 
 // src/session.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync, statSync, writeFileSync, mkdirSync } from "fs";
@@ -755,6 +757,14 @@ var Session = class {
    * come from that folder instead.
    */
   held = /* @__PURE__ */ new Map();
+  /**
+   * Nodes added this session without a position. A save lays them out —
+   * columns by wire depth, as the studio's L does — so the graph reads in
+   * the studio instead of arriving as one endless row. Nodes with a
+   * position of their own (the model's, or the person's in a file that
+   * was opened) never move.
+   */
+  placed = /* @__PURE__ */ new Set();
   bumpIds() {
     for (const n of this.project.graph.nodes) {
       const m = /(\d+)$/.exec(n.id);
@@ -770,6 +780,19 @@ var Session = class {
     this.path = void 0;
     this.stamp = void 0;
     this.held.clear();
+    this.placed.clear();
+    return this.project;
+  }
+  /** A preset's document as the open project — a clean start, like newProject. */
+  newFromPreset(name) {
+    const preset = PRESETS.find((p) => p.name === name);
+    if (!preset) fail(`No preset "${name}". The presets: ${PRESETS.map((p) => p.name).join(", ")}.`);
+    this.project = preset.build();
+    this.path = void 0;
+    this.stamp = void 0;
+    this.held.clear();
+    this.placed.clear();
+    this.bumpIds();
     return this.project;
   }
   open(path) {
@@ -781,6 +804,7 @@ var Session = class {
     this.path = abs;
     this.stamp = stamp;
     this.held.clear();
+    this.placed.clear();
     this.bumpIds();
     return { project, warnings };
   }
@@ -802,6 +826,7 @@ var Session = class {
         );
       }
     }
+    this.arrange();
     mkdirSync(dirname2(target), { recursive: true });
     this.writeHeldAssets(target);
     writeFileSync(target, serializeProject(this.project));
@@ -923,6 +948,7 @@ var Session = class {
       }
     }
     this.project.graph.nodes.push(node);
+    if (!options.position) this.placed.add(id);
     return node;
   }
   /**
@@ -943,9 +969,47 @@ var Session = class {
     const last = nodes[nodes.length - 1];
     return last ? { x: last.position.x + 260, y: last.position.y } : { x: 0, y: 0 };
   }
+  /**
+   * Lay out the nodes this session placed, page by page (the root, and each
+   * Layer's own). A page of nothing but such nodes is arranged whole, every
+   * save, so it stays tidy as it grows; on a page that also holds nodes with
+   * positions of their own, the new ones are arranged among themselves and
+   * set below what is already there.
+   */
+  arrange() {
+    const pages = /* @__PURE__ */ new Map();
+    for (const n of this.project.graph.nodes) {
+      const key = n.layer ?? "";
+      const list = pages.get(key);
+      if (list) list.push(n);
+      else pages.set(key, [n]);
+    }
+    for (const nodes of pages.values()) {
+      const moving = nodes.filter((n) => this.placed.has(n.id));
+      if (moving.length === 0) continue;
+      const staying = nodes.filter((n) => !this.placed.has(n.id));
+      const ids = new Set(moving.map((n) => n.id));
+      const edges = this.project.graph.edges.filter((e) => ids.has(e.from) && ids.has(e.to));
+      const origin = staying.length === 0 ? { x: 0, y: 0 } : {
+        x: Math.min(...staying.map((n) => n.position.x)),
+        y: Math.max(...staying.map((n) => n.position.y + nodeSize(n, registry.forNode(n)).height)) + 120
+      };
+      const at = columnLayout(moving, edges, origin);
+      for (const n of moving) n.position = at.get(n.id) ?? n.position;
+    }
+  }
+  /**
+   * Root-page nodes that draw straight onto the page because nothing takes
+   * their shapes — valid, but in the studio they read as forgotten wires.
+   */
+  looseDrawers() {
+    const feeding = new Set(this.project.graph.edges.map((e) => e.from));
+    return this.project.graph.nodes.filter((n) => n.layer === void 0 && !feeding.has(n.id)).filter((n) => registry.forNode(n)?.outputs.some((o) => o.type === "shapes")).map((n) => n.id);
+  }
   removeNode(id) {
     this.node(id);
     this.project.graph.nodes = this.project.graph.nodes.filter((n) => n.id !== id);
+    this.placed.delete(id);
     this.project.graph.edges = this.project.graph.edges.filter((e) => e.from !== id && e.to !== id);
   }
   setParam(nodeId, key, value) {
@@ -987,7 +1051,12 @@ var Session = class {
     }
     if (paramDef && !isExposable(paramDef)) fail(`${toNode.type}.${toPort} is not wireable.`);
     if (wouldCycle(this.project.graph, from, to, fromPort, toPort)) fail(`Connecting ${from} \u2192 ${to} would make a loop.`);
-    this.project.graph.edges = this.project.graph.edges.filter((e) => !(e.to === to && e.toPort === toPort));
+    if (toDef.inputs.find((i) => i.name === toPort)?.multi) {
+      const same = this.project.graph.edges.find((e) => e.from === from && e.fromPort === fromPort && e.to === to && e.toPort === toPort);
+      if (same) return same;
+    } else {
+      this.project.graph.edges = this.project.graph.edges.filter((e) => !(e.to === to && e.toPort === toPort));
+    }
     const edge = { id: makeId("edge"), from, fromPort, to, toPort };
     this.project.graph.edges.push(edge);
     const outType = fromDef.outputs.find((o) => o.name === fromPort)?.type;
@@ -997,10 +1066,13 @@ var Session = class {
     }
     return edge;
   }
-  disconnect(to, toPort) {
+  /** Remove the wires into a socket — only the one from `from`, when given (a Merge's `in` holds several). */
+  disconnect(to, toPort, from) {
     const before = this.project.graph.edges.length;
-    this.project.graph.edges = this.project.graph.edges.filter((e) => !(e.to === to && e.toPort === toPort));
-    if (this.project.graph.edges.length === before) fail(`Nothing is wired into ${to}.${toPort}.`);
+    this.project.graph.edges = this.project.graph.edges.filter(
+      (e) => !(e.to === to && e.toPort === toPort && (from === void 0 || e.from === from))
+    );
+    if (this.project.graph.edges.length === before) fail(`Nothing${from ? ` from ${from}` : ""} is wired into ${to}.${toPort}.`);
   }
   /**
    * Keyframes write into the same param model everything else uses — a track
@@ -1140,12 +1212,113 @@ var Session = class {
     return svgToPng(await this.renderSvgString(t, false), { scale });
   }
 };
+function nodeSize(node, def) {
+  if (node.micro) return { width: 80, height: 24 };
+  const width = def?.wide ? 456 : 228;
+  const outputs = def?.outputs.filter((o) => !o.hideWhen?.(node.params ?? {})).length ?? 0;
+  const height = node.collapsed ? 44 : 66 + Math.max(def?.inputs.length ?? 0, outputs) * 20 + (def?.params.length ?? 0) * 24;
+  return { width, height };
+}
+var COLUMN_HEIGHT = 1600;
+var ROW_GAP = 28;
+var COLUMN_GAP = 70;
+var BLOCK_GAP = 160;
+function columnLayout(nodes, edges, origin) {
+  const root = new Map(nodes.map((n) => [n.id, n.id]));
+  const find = (id) => {
+    let r = id;
+    while (root.get(r) !== r) r = root.get(r);
+    root.set(id, r);
+    return r;
+  };
+  for (const e of edges) if (root.has(e.from) && root.has(e.to)) root.set(find(e.from), find(e.to));
+  const wired = new Set(edges.flatMap((e) => [e.from, e.to]));
+  const blocks = /* @__PURE__ */ new Map();
+  const loose = [];
+  for (const n of nodes) {
+    if (!wired.has(n.id)) {
+      loose.push(n);
+      continue;
+    }
+    const key = find(n.id);
+    const list = blocks.get(key);
+    if (list) list.push(n);
+    else blocks.set(key, [n]);
+  }
+  const placed = /* @__PURE__ */ new Map();
+  let y = origin.y;
+  for (const block of [...blocks.values(), ...loose.length ? [loose] : []]) {
+    const bottom = layoutBlock(block, edges, { x: origin.x, y }, placed);
+    y = bottom + BLOCK_GAP;
+  }
+  return placed;
+}
+function layoutBlock(nodes, allEdges, origin, placed) {
+  const ids = new Set(nodes.map((n) => n.id));
+  const edges = allEdges.filter((e) => ids.has(e.from) && ids.has(e.to));
+  const incoming = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const list = incoming.get(e.to);
+    if (list) list.push(e.from);
+    else incoming.set(e.to, [e.from]);
+  }
+  const colOf = /* @__PURE__ */ new Map();
+  const visiting = /* @__PURE__ */ new Set();
+  const col = (id) => {
+    const known = colOf.get(id);
+    if (known !== void 0) return known;
+    if (visiting.has(id)) return 0;
+    visiting.add(id);
+    const ins = incoming.get(id) ?? [];
+    const c = ins.length === 0 ? 0 : Math.max(...ins.map(col)) + 1;
+    visiting.delete(id);
+    colOf.set(id, c);
+    return c;
+  };
+  const columns = /* @__PURE__ */ new Map();
+  nodes.forEach((n) => {
+    const c = col(n.id);
+    const list = columns.get(c);
+    if (list) list.push(n);
+    else columns.set(c, [n]);
+  });
+  const order = new Map(nodes.map((n, i) => [n.id, i]));
+  const rowOf = /* @__PURE__ */ new Map();
+  let x = origin.x;
+  let bottom = origin.y;
+  for (const c of [...columns.keys()].sort((a, b) => a - b)) {
+    const list = columns.get(c);
+    const key = (n) => {
+      const ins = (incoming.get(n.id) ?? []).map((id) => rowOf.get(id) ?? 0);
+      return ins.length > 0 ? ins.reduce((sum, v) => sum + v, 0) / ins.length : -1;
+    };
+    list.sort((a, b) => key(a) - key(b) || order.get(a.id) - order.get(b.id));
+    let y = origin.y;
+    let widest = 0;
+    list.forEach((n, i) => {
+      const { width, height } = nodeSize(n, registry.forNode(n));
+      if (y > origin.y && y + height > origin.y + COLUMN_HEIGHT) {
+        x += widest + ROW_GAP;
+        y = origin.y;
+        widest = 0;
+      }
+      rowOf.set(n.id, i);
+      placed.set(n.id, { x, y });
+      y += height + ROW_GAP;
+      widest = Math.max(widest, width);
+      bottom = Math.max(bottom, y - ROW_GAP);
+    });
+    x += widest + COLUMN_GAP;
+  }
+  return bottom;
+}
 
 // src/index.ts
+var DEFAULT_PROJECTS = "FUI-Studio";
 function projectsFolder() {
   const at = process.argv.indexOf("--projects");
   const given = at >= 0 && process.argv[at + 1] ? process.argv[at + 1] : process.env.FUI_PROJECTS || void 0;
-  return given?.replace(/^~(?=$|[\\/])/, homedir());
+  return given?.replace(/^~(?=$|[\\/])/, homedir()) ?? join4(homedir(), DEFAULT_PROJECTS);
 }
 function version() {
   try {
@@ -1163,11 +1336,17 @@ var session = new Session({ root: projectsFolder() });
 var INSTRUCTIONS = `FUI Studio builds animated HUD and FUI graphics (rings, ticks, readouts, crosshairs, scanning bars) as a node graph that renders to SVG, PNG and DaVinci Resolve titles. These tools edit one open project at a time.
 
 How to work:
-1. Start: new_project (name, width, height), or list_projects then open_project to continue one.
-2. Learn the library once: list_node_types, optionally by category. Generators draw shapes; modifiers change them; layout repeats and arranges; drivers (value, lfo, noise, time\u2026) produce numbers; post nodes are pixel effects.
-3. Build: add_node with params, then connect. Every param is also an input socket: connect(from: "lfo1", to: "ring1", toPort: "radius") makes the radius move. That is how things animate; set_keyframe is the other way, and params also take expressions ({"base": 5, "expr": "sin(t) * 10"}).
+1. Start: list_presets and new_from_preset when one is near what is asked (a radar, a dial, a boot sequence, panels in depth) \u2014 a working graph to change beats an empty one. Else new_project (name, width, height), or list_projects then open_project to continue one.
+2. Learn the library once: list_node_types, optionally by category. Generators draw shapes; modifiers change them; layout repeats and arranges; drivers (value, lfo, noise, time\u2026) produce numbers; post nodes are pixel effects. describe_node(type) tells what each param means, its unit and range \u2014 read it before using a node whose params are not obvious.
+3. Build: add_node with params, then connect. Every param is also an input socket: connect(from: "lfo1", to: "ring1", toPort: "radius") makes the radius move. That is how things animate; set_keyframe is the other way. A param's long form carries more: {"base": 5, "expr": "sin(t) * 10"} for an expression (t is time; in a node that handles several shapes, i is the shape's index, n the count, v the base value; sin, cos, rad, PI, TAU are there), {"base": 0, "stagger": {"amount": 30}} for a ramp across the shapes (shape i gets base + i \xD7 amount), {"base": 5, "jitter": {"amount": 2, "mode": "frozen"}} for seeded variation.
 4. Look: render_preview after each few edits and actually check the picture. Pass t (seconds) to see a moment of the animation.
-5. Save: save_project with a bare name ("radar") saves radar.tui in the projects folder.
+5. Save: save_project with a bare name ("radar") saves radar.tui in the projects folder. The first time you save, tell the user the full path the save reports, and that the studio shows the project live once they choose that same folder there (folder\u2026 in the toolbar, then Open).
+
+Pixels: shapes are vectors until a rasterize node draws them; post nodes (blur, bloom, glitch, depth-of-field\u2026) take and give textures, never shapes. The chain is shapes \u2192 rasterize \u2192 post nodes \u2192 a Layer's "in". A Layer draws one picture among its shapes.
+
+3D: a transform3d node poses the shapes it gets as a plane under the camera (x right, y down, z away from the camera: positive Pos. Z draws smaller). Plane "shape" with a stagger on posZ or rotY poses an array's copies one by one; Order "depth" draws the nearer over the farther. The canvas's perspective is the lens (0 = orthographic). A Layer's own 3D group poses the whole layer the same way. Strokes stay screen pixels on a plane: put outline-stroke before the pose for strokes that thin with distance. depth-of-field wants the picture on "in" and the same shapes that made it on "depth"; shapes a transform3d posed remember their depth, so pose inside the layer, before rasterize.
+
+Keep the graph readable, because the user opens it in the studio. A node whose output is wired to nothing draws straight onto the page. That works, but a page of loose nodes looks like a graph with its wires missing. Gather the parts of one element (a radar's rings, ticks, labels and crosshair) into a Merge node: add_node merge, then connect each part to its "in" port. Merge draws in connection order, so the first wire is at the bottom. Give the Merge a name ("radar", "readout") so the studio shows what it is. Leave position out of add_node: on save, nodes without one are laid out in columns that follow the wires.
 
 Layers: a Layer node is a self-contained composition with its own page and its own clock. add_node with layer: "<layer id>" puts a node inside it. Arrange Layers in time with add_clip; a document with no clips plays every Layer all the time. list_layers explains the rules.
 
@@ -1223,7 +1402,15 @@ server.registerTool(
     description: 'Save the project. Without a path, writes back to where it was opened from. A relative path or bare name (".tui" is added) saves into the projects folder, where an open studio shows it at once. Writing back over a file someone saved since you opened it is refused unless overwrite is true.',
     inputSchema: { path: z2.string().optional(), overwrite: z2.boolean().default(false) }
   },
-  guard(({ path, overwrite }) => text(`saved ${session.save(path, { overwrite })}`))
+  guard(({ path, overwrite }) => {
+    const saved = session.save(path, { overwrite });
+    const loose = session.looseDrawers();
+    const nudge = loose.length > 3 ? `
+${loose.length} nodes draw with nothing wired to their output (${loose.join(", ")}). In the studio that reads as missing wires: gather each element's parts into a named Merge (connect in drawing order, first at the bottom) and save again.` : "";
+    const folder = session.root && dirname3(saved).startsWith(session.root) ? session.root : dirname3(saved);
+    return text(`saved ${saved}
+In FUI Studio, choose the folder ${folder} (folder\u2026 in the toolbar, or change folder\u2026 under Open) and open it from Open.${nudge}`);
+  })
 );
 server.registerTool(
   "list_projects",
@@ -1266,6 +1453,58 @@ server.registerTool(
     )
   )
 );
+server.registerTool(
+  "describe_node",
+  {
+    description: "One node type in full: what every param means, its unit, range, group and choices, and which inputs it takes. Read this before using a node whose params are not obvious \u2014 the 3D nodes, the post effects, the arrays.",
+    inputSchema: { type: z2.string() }
+  },
+  guard(({ type }) => {
+    const d = registry.list().find((n) => n.type === type && !n.hidden);
+    if (!d) throw new SessionError(`No node type "${type}". list_node_types has every type.`);
+    return text({
+      type: d.type,
+      label: d.label,
+      category: d.category,
+      description: d.description,
+      ...d.keywords ? { keywords: d.keywords } : {},
+      inputs: d.inputs.map((i) => ({ name: i.name, type: i.type, ...i.multi ? { multi: true } : {}, ...i.accepts ? { accepts: i.accepts } : {} })),
+      outputs: d.outputs.map((o) => ({ name: o.name, type: o.type })),
+      params: d.params.map((p) => ({
+        key: p.key,
+        label: p.label,
+        type: p.type,
+        default: p.default,
+        ...p.description ? { description: p.description } : {},
+        ...p.group ? { group: p.group } : {},
+        ..."unit" in p && p.unit ? { unit: p.unit } : {},
+        ..."min" in p && p.min !== void 0 ? { min: p.min } : {},
+        ..."max" in p && p.max !== void 0 ? { max: p.max } : {},
+        ...isExposable(p) ? {} : { wireable: false },
+        ..."options" in p ? { options: p.options.map((o) => ({ value: o.value, label: o.label })) } : {}
+      }))
+    });
+  })
+);
+server.registerTool(
+  "list_presets",
+  {
+    description: "The starter documents the studio\u2019s Presets menu offers: complete, working graphs, each a worked example of one subsystem (post chain, tokens, drivers, 3D). Start from the nearest one and change it, rather than building from nothing.",
+    inputSchema: {}
+  },
+  guard(() => text(PRESETS.map((p) => ({ name: p.name, label: p.label, description: p.description }))))
+);
+server.registerTool(
+  "new_from_preset",
+  {
+    description: "Open a preset as the project, replacing whatever is open \u2014 like new_project, but with a working graph in it. list_nodes then shows what there is to change.",
+    inputSchema: { name: z2.string() }
+  },
+  guard(async ({ name }) => {
+    session.newFromPreset(name);
+    return text(await session.summary());
+  })
+);
 server.registerTool(
   "list_nodes",
   { description: "Every node in the graph, with params and incoming wires.", inputSchema: {} },
@@ -1377,10 +1616,13 @@ server.registerTool(
 );
 server.registerTool(
   "disconnect",
-  { description: "Remove the wire feeding a socket.", inputSchema: { to: z2.string(), toPort: z2.string() } },
-  guard(({ to, toPort }) => {
-    session.disconnect(to, toPort);
-    return text(`disconnected ${to}.${toPort}`);
+  {
+    description: `Remove the wire feeding a socket. A multi input (a Merge's or Layer's "in") holds several: pass from to remove just that one, or leave it out to remove them all.`,
+    inputSchema: { to: z2.string(), toPort: z2.string(), from: z2.string().optional() }
+  },
+  guard(({ to, toPort, from }) => {
+    session.disconnect(to, toPort, from);
+    return text(`disconnected ${from ? `${from} \u2192 ` : ""}${to}.${toPort}`);
   })
 );
 server.registerTool(
@@ -1454,12 +1696,11 @@ server.registerTool(
   },
   guard(async ({ path, t, scale }) => {
     const { writeFileSync: writeFileSync2, mkdirSync: mkdirSync2 } = await import("fs");
-    const { dirname: dirname3 } = await import("path");
     const abs = session.resolvePath(path);
     mkdirSync2(dirname3(abs), { recursive: true });
     if (/\.(ograf|drfx)$/i.test(abs)) {
-      const { exportTemplate } = await import("./node-4RLELQ7B.js");
-      const { packDrfx, packOgraf } = await import("./dist-3URVYEPT.js");
+      const { exportTemplate } = await import("./node-XJJEAAN7.js");
+      const { packDrfx, packOgraf } = await import("./dist-LUAYBAOC.js");
       const template = exportTemplate(session.project, void 0, session.assetResolver());
       const errors = template.lint.filter((i) => i.level === "error");
       if (errors.length > 0) throw new SessionError(`The manifest has errors: ${errors.map((i) => `${i.where}: ${i.message}`).join("; ")}`);
@@ -1489,7 +1730,6 @@ server.registerTool(
   guard(async ({ dir, from, to, fps, scale }) => {
     if (to <= from) throw new SessionError("`to` must be after `from`.");
     const { writeFileSync: writeFileSync2, mkdirSync: mkdirSync2 } = await import("fs");
-    const { join: join4 } = await import("path");
     const abs = session.resolvePath(dir);
     mkdirSync2(abs, { recursive: true });
     const frames = Math.round((to - from) * fps);
@@ -1502,3 +1742,6 @@ server.registerTool(
   })
 );
 await server.connect(new StdioServerTransport());
+export {
+  DEFAULT_PROJECTS
+};

package/dist/{node-4RLELQ7B.js → node-XJJEAAN7.js}

@@ -2,10 +2,10 @@
 import {
   loadFaces,
   nodeOutliner
-} from "./chunk-RAHWGTHJ.js";
+} from "./chunk-U3VXQSCB.js";
 import {
   buildTemplate
-} from "./chunk-W7L36Z34.js";
+} from "./chunk-S3AUIOGZ.js";
 
 // ../../packages/ograf/dist/node.js
 import { existsSync, readFileSync } from "fs";