fui-studio-mcp 0.1.1 → 0.1.3

package/dist/{chunk-EFZHSV66.js → chunk-ZCNEK4RK.js}

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

package/dist/{dist-RTISZO3Q.js → dist-3XKU7BN6.js}

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

package/dist/index.js

@@ -4,11 +4,12 @@ import {
   allTtfBuffers,
   fontDefs,
   nodeOutliner
-} from "./chunk-EFZHSV66.js";
+} from "./chunk-ZCNEK4RK.js";
 import {
   DEFAULT_FONT_FAMILY,
   Keyframe,
   OgrafControl,
+  PRESETS,
   Param,
   ROOT_TYPES,
   adoptions,
@@ -16,6 +17,7 @@ import {
   emptyProject,
   envName,
   evaluate,
+  insertComposition,
   isExposable,
   layerDuration,
   layerLoop,
@@ -38,7 +40,7 @@ import {
   wouldCycle,
   yuvFrameBytes,
   yuvToRgb
-} from "./chunk-NDQB3ETD.js";
+} from "./chunk-NYLRWVKF.js";
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -782,6 +784,18 @@ var Session = class {
     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) {
     const abs = this.documentPath(path);
     if (!existsSync2(abs)) fail(`No file at ${abs}.${this.root ? " list_projects shows what the projects folder holds." : ""}`);
@@ -821,6 +835,75 @@ var Session = class {
     this.stamp = this.mtimeOf(target);
     return target;
   }
+  /**
+   * The elements in the projects folder: `elements/<name>.tui`, each a
+   * layer saved for reuse from the studio (its layers pane) — the shelf
+   * the studio's elements button shows. Newest first.
+   */
+  listElements() {
+    if (!this.root) fail("The server was started without a projects folder (--projects <dir> or FUI_PROJECTS), so there is no elements/ folder to list.");
+    const dir = join3(this.root, "elements");
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const file of entries) {
+      if (!file.endsWith(".tui")) continue;
+      const abs = join3(dir, file);
+      const at = this.mtimeOf(abs) ?? 0;
+      let description = "";
+      try {
+        const { project } = loadProject(JSON.parse(readFileSync3(abs, "utf8")));
+        const layer = project.graph.nodes.find((n) => n.type === "layer");
+        const members = project.graph.nodes.filter((n) => layer && n.layer === layer.id);
+        const kinds = [...new Set(members.map((n) => n.type))];
+        description = `${members.length} node${members.length === 1 ? "" : "s"}${kinds.length > 0 ? ` (${kinds.slice(0, 6).join(", ")}${kinds.length > 6 ? ", \u2026" : ""})` : ""}`;
+      } catch {
+        description = "unreadable";
+      }
+      out.push({ name: file.slice(0, -4), description, saved: new Date(at).toISOString(), at });
+    }
+    out.sort((a, b) => b.at - a.at);
+    return out.map(({ at: _at, ...rest }) => rest);
+  }
+  /**
+   * An element into the open project as a new Layer on top (the shared
+   * surgery in @fui/schema): its name counted up when taken, wired into the
+   * Canvas, its Tokens wires re-bound to this document's Tokens. Its
+   * pictures' bytes come along from `elements/<name>.assets/` and are
+   * written beside the project on save. The Layer and its drivers have no
+   * place here yet: the save lays them out, as it lays out any node added
+   * without a position.
+   */
+  insertElement(name) {
+    if (!this.root) fail("The server was started without a projects folder (--projects <dir> or FUI_PROJECTS), so there is no elements/ folder to insert from.");
+    const abs = join3(this.root, "elements", `${name.replace(/\.tui$/i, "")}.tui`);
+    if (!existsSync2(abs)) {
+      const have = this.listElements().map((e) => e.name);
+      fail(`No element "${name}".${have.length > 0 ? ` The elements: ${have.join(", ")}.` : " The elements/ folder is empty \u2014 save a layer as an element in the studio first."}`);
+    }
+    const { project: doc } = loadProject(JSON.parse(readFileSync3(abs, "utf8")));
+    const insertion = insertComposition(this.project, { ...doc, name: name.replace(/\.tui$/i, "") }, makeId, (n) => registry.forNode(n) !== void 0);
+    if (!insertion) fail(`${abs} is not an element: it has no Layer in it.`);
+    const dir = assetDirFor(abs);
+    for (const [key, record] of Object.entries(doc.assets)) {
+      if (record.video || this.held.has(key)) continue;
+      const found = assetFileIn(dir, key, record);
+      if (!found) continue;
+      const bytes = new Uint8Array(readFileSync3(found.path));
+      this.held.set(key, { href: `data:${record.mime};base64,${Buffer.from(bytes).toString("base64")}`, bytes, mime: record.mime });
+    }
+    this.project.graph.nodes.push(...insertion.nodes);
+    this.project.graph.edges.push(...insertion.edges);
+    this.project.groups.push(...insertion.groups);
+    this.project.assets = insertion.assets;
+    for (const n of insertion.nodes) if (n.layer === void 0) this.placed.add(n.id);
+    const layer = insertion.nodes.find((n) => n.id === insertion.layerId);
+    return { layer, nodes: insertion.nodes };
+  }
   /**
    * The projects folder's documents, loose and one folder deep — the shape
    * the studio's Open dialog shows. Newest first.
@@ -1323,14 +1406,20 @@ 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. 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.
 
+Elements: list_elements shows layers the user saved for reuse in the studio; insert_element puts one into the project as a new Layer, ready to change. When the user mentions something they have made before (their radar, their readout), look there first.
+
 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.
 
 The user is probably watching. When the user has the same projects folder open in FUI Studio (Choose folder in the browser) with this project loaded, every save_project appears there within a second. So save after each meaningful step, and say what changed. The user can edit in the studio too: if save_project refuses because the file changed, open_project it again, which picks up their edits, redo your change and save. Do not reach for overwrite unless the user asks for it.
@@ -1436,6 +1525,77 @@ 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_elements",
+  {
+    description: "The elements in the projects folder: layers the user saved for reuse from the studio (a radar, a readout, a panel), each a working composition with a picture. insert_element puts one into the open project as a new layer; prefer that to rebuilding what the user already has.",
+    inputSchema: {}
+  },
+  guard(() => text(session.listElements()))
+);
+server.registerTool(
+  "insert_element",
+  {
+    description: "Insert an element (list_elements) into the open project as a new Layer on top, wired into the Canvas, named after the element (counted up when the name is taken), taking the colours of this project\u2019s Style Tokens. Its nodes are ordinary nodes afterwards: list_nodes shows them, set_param changes them. Returns the new Layer and its nodes.",
+    inputSchema: { name: z2.string().describe("The element\u2019s name as list_elements gives it") }
+  },
+  guard(({ name }) => {
+    const { layer, nodes } = session.insertElement(name);
+    return text({ layer: { id: layer.id, name: layer.name, order: layer.params.order }, nodes: nodes.map((n) => ({ id: n.id, type: n.type, ...n.layer ? { layer: n.layer } : {} })) });
+  })
+);
 server.registerTool(
   "list_nodes",
   { description: "Every node in the graph, with params and incoming wires.", inputSchema: {} },
@@ -1630,8 +1790,8 @@ server.registerTool(
     const abs = session.resolvePath(path);
     mkdirSync2(dirname3(abs), { recursive: true });
     if (/\.(ograf|drfx)$/i.test(abs)) {
-      const { exportTemplate } = await import("./node-3VDUDD3U.js");
-      const { packDrfx, packOgraf } = await import("./dist-RTISZO3Q.js");
+      const { exportTemplate } = await import("./node-VANCEYKL.js");
+      const { packDrfx, packOgraf } = await import("./dist-3XKU7BN6.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("; ")}`);

package/dist/{node-3VDUDD3U.js → node-VANCEYKL.js}

@@ -2,10 +2,10 @@
 import {
   loadFaces,
   nodeOutliner
-} from "./chunk-EFZHSV66.js";
+} from "./chunk-ZCNEK4RK.js";
 import {
   buildTemplate
-} from "./chunk-NDQB3ETD.js";
+} from "./chunk-NYLRWVKF.js";
 
 // ../../packages/ograf/dist/node.js
 import { existsSync, readFileSync } from "fs";