topotopo 0.1.0 → 0.2.0

package/dist/mcp/inputs.js

@@ -0,0 +1,377 @@
+// The human-input layer for agents: the files people drop into <workspace>/inputs (meshes, guide curves and points,
+// PNG masks and heightmaps) and what each one holds: curves vs meshes vs points, bbox, names and roles, attributes,
+// materials. Registered by makeTools in tools.ts; help topic "inputs" (docs.ts) explains the guide conventions.
+import fs from 'node:fs';
+import path from 'node:path';
+import { inputExt, inputKind } from '../workspace.js';
+import { decodePNG } from '../io/png-decode.js';
+import { imageNameOf } from '../io/textures.js';
+import { readMaterials, MATERIAL_ATTRIB } from '../core/materials.js';
+import { didYouMean } from '../graph/params.js';
+import { fmtNum } from '../render/raster.js';
+const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError } : {}) });
+/** Most distinct values of `name` / `role` listed per class. */
+const MAX_VALUES = 50;
+/** `inputs list` stops describing files it has not seen before after this long (the rest say so). */
+const LIST_BUDGET_MS = 15_000;
+/** name prefixes that mark a guide's role (help topic "inputs") */
+export const ROLES = ['site', 'path', 'zone', 'volume', 'blockout'];
+const n = (x) => x.toLocaleString('en-US');
+const plural = (k, one, many = one + 's') => `${n(k)} ${k === 1 ? one : many}`;
+const sizeText = (b) => (b < 1024 ? `${b} B` : b < 1024 * 1024 ? `${(b / 1024).toFixed(1)} KB` : `${(b / 1024 / 1024).toFixed(1)} MB`);
+const dateText = (ms) => {
+    const d = new Date(ms), p = (x) => String(x).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+};
+const typeText = (a) => (a.isArray ? a.type : a.size === 1 ? a.type : `${a.type}${a.size}`);
+/** where people get a readable file from formats we do not read */
+const OTHER_HINTS = {
+    fbx: 'FBX is not read: export glTF (.glb) instead', dae: 'export glTF (.glb) instead', '3ds': 'export glTF (.glb) instead',
+    abc: 'Alembic is not read: export glTF (.glb) or .geo', usd: 'USD is written, not read: export glTF (.glb)', usda: 'USD is written, not read: export glTF (.glb)',
+    usdc: 'USD is written, not read: export glTF (.glb)', usdz: 'USD is written, not read: export glTF (.glb)',
+    jpg: 'only PNG images are read: save it as PNG', jpeg: 'only PNG images are read: save it as PNG', tif: 'only PNG images are read: save it as PNG (16-bit grey for heightmaps)',
+    tiff: 'only PNG images are read: save it as PNG (16-bit grey for heightmaps)', exr: 'only PNG images are read: save it as 16-bit PNG', hdr: 'only PNG images are read',
+    webp: 'only PNG images are read: save it as PNG', sc: 'compressed Houdini geometry is not read: save .geo or uncompressed .bgeo', gz: 'compressed files are not read: unpack it first',
+    blend1: 'a Blender backup file (the .blend next to it is the current one)',
+};
+const READABLE = 'geometry: obj stl ply glb gltf geo bgeo csv json points.json, and blend with Blender installed; images: png';
+/** inputs/ file → its description, keyed by path and invalidated by the host's file stamp (mtime + size). */
+export class InputDescriber {
+    ws;
+    cache = new Map();
+    constructor(ws) { this.ws = ws; }
+    /** Describe one file (cached while its stamp holds). */
+    describe(f) {
+        const rel = `inputs/${f.path}`;
+        const stamp = this.ws.engine.host.fileStamp(rel);
+        const hit = this.cache.get(f.path);
+        if (hit && hit.stamp === stamp)
+            return hit.d;
+        const d = (f.kind === 'geometry' ? this.geometry(rel, f.ext) : f.kind === 'image' ? this.image(rel) : Promise.resolve(other(f.ext)))
+            .catch((e) => ({ short: `cannot read: ${e?.message ?? e}`, long: `cannot read: ${e?.message ?? e}`, failed: true }));
+        this.cache.set(f.path, { stamp, d });
+        return d;
+    }
+    /** Whether describe() would answer from the cache. */
+    cached(f) {
+        const hit = this.cache.get(f.path);
+        return !!hit && hit.stamp === this.ws.engine.host.fileStamp(`inputs/${f.path}`);
+    }
+    /** Forget files that are gone. */
+    prune(keep) {
+        const live = new Set(keep.map((f) => f.path));
+        for (const k of [...this.cache.keys()])
+            if (!live.has(k))
+                this.cache.delete(k);
+    }
+    /** Cook the one-node graph a file node would be (never a workspace graph) and read the result. */
+    async geometry(rel, ext) {
+        const r = await this.ws.engine.cook({ nodes: { f: { type: 'file', params: { path: rel } } }, output: 'f' });
+        const warnings = r.warnings.map((w) => w.message);
+        if (!r.ok || !r.geo) {
+            const err = r.errors.map((e) => e.message + (e.hint ? ` (hint: ${e.hint})` : '')).join('; ') || 'no geometry';
+            let why = ext === 'blend' ? '\n.blend files are converted by a headless Blender: it must be installed (and found) for the file node to read them.' : '';
+            if (ext === 'json') {
+                try {
+                    const j = JSON.parse(new TextDecoder().decode(await this.ws.engine.host.readFile(rel)));
+                    if (j && typeof j === 'object' && !Array.isArray(j) && j.nodes && typeof j.nodes === 'object')
+                        why = '\nThis JSON is a topotopo graph, not geometry: build it (build {graph}) instead of reading it with a file node.';
+                }
+                catch { /* not JSON at all: the error says so */ }
+            }
+            return { short: `cook failed: ${err}`, long: `the file node failed: ${err}${why}${warnings.length ? '\nwarnings:\n  ' + warnings.join('\n  ') : ''}`, failed: true };
+        }
+        return geometryText(r.geo, rel, ext, warnings);
+    }
+    async image(rel) {
+        const img = decodePNG(await this.ws.engine.host.readFile(rel));
+        const ch = img.channels, names = ['grey', 'grey + alpha', 'RGB', 'RGBA'][ch - 1];
+        const lo = new Array(ch).fill(Infinity), hi = new Array(ch).fill(-Infinity), sum = new Array(ch).fill(0);
+        const d = img.data, px = img.width * img.height;
+        for (let i = 0; i < px; i++)
+            for (let c = 0; c < ch; c++) {
+                const v = d[i * ch + c];
+                if (v < lo[c])
+                    lo[c] = v;
+                if (v > hi[c])
+                    hi[c] = v;
+                sum[c] += v;
+            }
+        const label = (c) => (ch <= 2 ? ['grey', 'alpha'][c] : 'rgba'[c]);
+        const ranges = lo.map((_, c) => `${label(c)} ${fmtNum(lo[c] / img.maxValue)}..${fmtNum(hi[c] / img.maxValue)} (mean ${fmtNum(sum[c] / px / img.maxValue)})`);
+        const short = `${img.width} × ${img.height} px, ${img.bitDepth}-bit ${names} (${plural(ch, 'channel')})`;
+        const [w, h] = [img.width, img.height];
+        const long = [
+            `image: ${short}`,
+            `values (0..1): ${ranges.join(', ')}`,
+            'read it as:',
+            `  a heightmap  {"type":"heightfield_from_image","params":{"path":"${rel}","size":[${w - 1},${h - 1}],"height_min":0,"height_max":20}}`,
+            '               (size = the extent in metres in X and Z; height_min/max = the heights of black and white; 16-bit greys keep the detail)',
+            `  a mask layer {"type":"heightfield_from_image","in":["terrain"],"params":{"path":"${rel}","layer":"mask","height_min":0,"height_max":1}}`,
+            '               (stretched over the connected heightfield; then heightfield_scatter, mask_layer, …)',
+            `  on points    {"type":"attribute_from_map","in":["pts"],"params":{"path":"${rel}","projection":"xz","size":[100,100],"name":"mask"}}`,
+            '               (top view: column along +X, row 0 at min Z; then scatter density_mask, prune, copy_to_points scale_attrib)',
+            `  a texture    {"type":"image_file","params":{"path":"${rel}"}}`,
+            `               (an image "${imageNameOf(rel)}" for the texture nodes and texture_to_material; a file node reads it the same way)`,
+        ].join('\n');
+        return { short, long, failed: false };
+    }
+}
+function other(ext) {
+    const hint = OTHER_HINTS[ext];
+    const what = ext ? `.${ext}` : 'a file without an extension';
+    return {
+        short: `not read${hint ? `: ${hint}` : ''}`,
+        long: `${what} is not a format topotopo reads${hint ? `: ${hint}` : ''}. Readable: ${READABLE}.`,
+        failed: false,
+    };
+}
+/** Distinct values of a string attribute with counts, sorted by value. */
+function stringValues(a, count) {
+    const freq = new Map();
+    for (let i = 0; i < count; i++) {
+        const v = String(a.get(i));
+        freq.set(v, (freq.get(v) ?? 0) + 1);
+    }
+    return [...freq].sort((x, y) => (x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : 0));
+}
+/** Prim kinds: 0 polygon, 1 open polyline, 2 packed, 3 spline curve. */
+function primKinds(g) {
+    const k = new Uint8Array(g.numPrims);
+    for (let p = 0; p < g.numPrims; p++) {
+        const pk = g.primKind ? g.primKind[p] : 0;
+        k[p] = pk === 1 ? 2 : pk === 2 || pk === 3 ? 3 : g.primClosed[p] ? 0 : 1;
+    }
+    return k;
+}
+const KIND_NAMES = [['polygon', 'polygons'], ['polyline', 'polylines'], ['packed prim', 'packed prims'], ['spline curve', 'spline curves']];
+const kindsText = (c) => c.map((x, i) => (x ? plural(x, KIND_NAMES[i][0], KIND_NAMES[i][1]) : '')).filter(Boolean).join(' + ');
+/** A role value, or the role of a name by its prefix like the wrangle of help topic "inputs" ("Path.River.001" → path). */
+const roleOf = (s, isName) => {
+    const r = (isName ? s.split('.')[0] : s).toLowerCase();
+    return ROLES.includes(r) ? r : null;
+};
+/** What a guide of this role should be made of, given the prims carrying it (counts per kind, see primKinds). */
+function roleChecks(role, v, k) {
+    const curves = k[1] + k[3], what = kindsText(k);
+    if (role === 'path' && !curves)
+        return [`${v} is ${what}: a path is an open polyline (in Blender a curve, or a mesh of edges only)`];
+    if (role === 'zone' && !k[0] && curves)
+        return [`${v} is ${what}: a zone is a closed area; ends {mode:"close"} turns closed loops into polygons`];
+    if (role === 'site' && (k[0] || curves))
+        return [`${v} is ${what}: a site is a point; pack {by:"name", pivot:"bbox_center_bottom"} gives one anchor point per object`];
+    if ((role === 'volume' || role === 'blockout') && !k[0] && !k[2])
+        return [`${v} is ${what}: a ${role} is a mesh (a box or a closed solid)`];
+    return [];
+}
+function geometryText(g, rel, ext, warnings) {
+    const kinds = primKinds(g);
+    const counts = [0, 0, 0, 0];
+    for (let p = 0; p < g.numPrims; p++)
+        counts[kinds[p]]++;
+    const used = new Uint8Array(g.numPoints);
+    for (let v = 0; v < g.numVertices; v++)
+        used[g.vertexPoint[v]] = 1;
+    let loose = 0;
+    for (let i = 0; i < g.numPoints; i++)
+        if (!used[i])
+            loose++;
+    const lines = [];
+    const elems = [kindsText(counts), loose ? plural(loose, 'loose point') : ''].filter(Boolean).join(' + ') || 'empty';
+    lines.push(`elements: ${plural(g.numPoints, 'point')}, ${plural(g.numPrims, 'prim')} = ${elems}`);
+    lines.push(`  (polygons are closed faces, polylines open curves, loose points belong to no prim, packed prims are instances${counts[3] ? ', spline curves Bezier/NURBS' : ''})`);
+    const vols = g.volumes.length ? g.volumes.map((v) => `${v.kind} "${v.name}"`).join(', ') : '';
+    if (vols)
+        lines.push(`volumes: ${vols}`);
+    const b = g.bbox(true);
+    const size = [0, 1, 2].map((a) => b.max[a] - b.min[a]);
+    const v3 = (a) => `(${a.map(fmtNum).join(', ')})`;
+    const bboxShort = b.empty ? 'no bbox' : `bbox ${size.map(fmtNum).join(' × ')} m`;
+    if (!b.empty)
+        lines.push(`bbox (metres, as read, Y up): min ${v3(b.min)} max ${v3(b.max)} size ${size.map(fmtNum).join(' × ')}`);
+    // attributes and groups
+    const attrs = [];
+    for (const cls of ['point', 'vertex', 'prim', 'detail']) {
+        const t = g.table(cls);
+        if (t.map.size)
+            attrs.push(`  ${cls}: ${[...t.map].map(([k, a]) => `${k} ${typeText(a)}`).join(', ')}`);
+    }
+    if (attrs.length)
+        lines.push('attributes:', ...attrs);
+    const grp = [];
+    for (const cls of ['point', 'prim', 'vertex']) {
+        const m = g.groups(cls);
+        if (m.size)
+            grp.push(`${cls}: ${[...m].map(([k, mask]) => `${k} ${n(mask.reduce((s, x) => s + x, 0))}`).join(', ')}`);
+    }
+    if (g.edgeGroups.size)
+        grp.push(`edge: ${[...g.edgeGroups].map(([k, set]) => `${k} ${n(set.size)}`).join(', ')}`);
+    lines.push(grp.length ? `groups: ${grp.join('  ')}` : 'groups: none');
+    // name and role values, with the kind of prims that carry each
+    const isStr = (a) => !!a && a.type === 'string' && !a.isArray;
+    const kindsOf = (a) => {
+        const m = new Map();
+        for (let p = 0; p < g.numPrims; p++) {
+            const v = String(a.get(p));
+            let c = m.get(v);
+            if (!c)
+                m.set(v, (c = [0, 0, 0, 0]));
+            c[kinds[p]]++;
+        }
+        return m;
+    };
+    const shortNames = [];
+    for (const attr of ['name', 'role'])
+        for (const cls of ['prim', 'point']) {
+            const a = g.table(cls).get(attr);
+            if (!isStr(a))
+                continue;
+            const vals = stringValues(a, cls === 'prim' ? g.numPrims : g.numPoints);
+            const per = cls === 'prim' ? kindsOf(a) : null;
+            lines.push(`${cls} ${attr} (${plural(vals.length, 'value')}):`);
+            for (const [v, c] of vals.slice(0, MAX_VALUES))
+                lines.push(`  ${JSON.stringify(v)}  ${per ? kindsText(per.get(v)) : plural(c, 'point')}`);
+            if (vals.length > MAX_VALUES)
+                lines.push(`  … ${plural(vals.length - MAX_VALUES, 'more value')}`);
+            if (attr === 'name' && !shortNames.length)
+                shortNames.push(...vals.map(([v]) => v));
+        }
+    // roles, per element as the wrangle of help topic "inputs" derives them: the role attribute, else the name prefix
+    const objects = new Map(), points = new Map(), checks = [];
+    let fromAttr = false, fromName = false;
+    for (const cls of ['prim', 'point']) {
+        const ra = g.table(cls).get('role'), na = g.table(cls).get('name');
+        const roleA = isStr(ra) ? ra : null, nameA = isStr(na) ? na : null;
+        if (!roleA && !nameA)
+            continue;
+        for (let i = 0, count = cls === 'prim' ? g.numPrims : g.numPoints; i < count; i++) {
+            const rv = roleA ? String(roleA.get(i)) : '', nv = nameA ? String(nameA.get(i)) : '';
+            const role = rv ? roleOf(rv, false) : roleOf(nv, true);
+            if (!role)
+                continue;
+            if (rv)
+                fromAttr = true;
+            else
+                fromName = true;
+            if (cls === 'point') {
+                points.set(role, (points.get(role) ?? 0) + 1);
+                continue;
+            }
+            let objs = objects.get(role);
+            if (!objs)
+                objects.set(role, (objs = new Map()));
+            const label = nv || rv;
+            let k = objs.get(label);
+            if (!k)
+                objs.set(label, (k = [0, 0, 0, 0]));
+            k[kinds[i]]++;
+        }
+    }
+    const roleNames = ROLES.filter((r) => objects.has(r) || points.has(r));
+    if (roleNames.length) {
+        const src = fromAttr && fromName ? 'the role attribute and name prefixes' : fromAttr ? 'the role attribute' : 'name prefixes';
+        lines.push(`roles (from ${src}): ${roleNames.map((r) => `${r} ${[objects.has(r) ? plural(objects.get(r).size, 'object') : '', points.has(r) ? plural(points.get(r), 'point') : ''].filter(Boolean).join(' + ')}`).join(', ')}`);
+        for (const [role, objs] of objects)
+            for (const [label, k] of objs)
+                checks.push(...roleChecks(role, JSON.stringify(label), k));
+    }
+    else
+        lines.push('roles: none marked (name objects site.* path.* zone.* volume.* blockout.*, or give them a string attribute "role"; help topic "inputs")');
+    for (const m of checks)
+        lines.push(`  check: ${m}`);
+    // materials
+    const mat = g.table('prim').get(MATERIAL_ATTRIB);
+    const table = Object.keys(readMaterials(g));
+    if ((mat && mat.type === 'string') || table.length) {
+        const used = mat && mat.type === 'string' ? stringValues(mat, g.numPrims).filter(([v]) => v !== '') : [];
+        const unused = table.filter((t) => !used.some(([v]) => v === t));
+        lines.push(`materials: ${used.length ? used.slice(0, MAX_VALUES).map(([v, c]) => `${JSON.stringify(v)} ${plural(c, 'prim')}`).join(', ') : 'none assigned'}${used.length > MAX_VALUES ? `, … ${used.length - MAX_VALUES} more` : ''}${unused.length ? `; in the table only: ${unused.join(', ')}` : ''}`);
+    }
+    else
+        lines.push('materials: none');
+    if (warnings.length)
+        lines.push('warnings:', ...warnings.map((w) => `  ${w}`));
+    // up axis: OBJ/STL/PLY carry none
+    const flatY = !b.empty && size[2] < 0.1 * Math.max(size[0], size[1]) && size[1] > 0.5 * size[0] && size[1] > 0;
+    if (['obj', 'stl', 'ply'].includes(ext) && flatY)
+        lines.push(`up axis: this looks Z-up (flat in Z, spread in X and Y): read it with "up_axis":"z" if it should lie on the ground.`);
+    lines.push('up axis: OBJ/STL/PLY exports from Blender (with Up = Z) and from Unreal are Z-up and need "up_axis":"z" on the file node; glTF is +Y up already.');
+    lines.push(`read it: {"type":"file","params":{"path":"${rel}"}}`);
+    const names = shortNames.length ? `; name: ${shortNames.slice(0, 6).join(', ')}${shortNames.length > 6 ? ` (+${shortNames.length - 6})` : ''}` : '';
+    const short = `${plural(g.numPoints, 'point')}, ${plural(g.numPrims, 'prim')} = ${elems}; ${bboxShort}${names}${warnings.length ? `; ${plural(warnings.length, 'warning')}` : ''}`;
+    return { short, long: lines.join('\n'), failed: false };
+}
+/** "inputs/a.obj", "./a.obj", "a.obj" → "a.obj" (posix, inside inputs/), or an Error naming the files there. */
+function resolveInput(ws, p, files) {
+    if (typeof p !== 'string' || !p.trim())
+        throw new Error('"path" is required: a file under inputs/ (inputs {action:"list"} lists them)');
+    const rel = p.trim().replace(/\\/g, '/').replace(/^(\.\/)+/, '');
+    if (path.isAbsolute(rel) || /^[a-z]:\//i.test(rel) || rel.split('/').includes('..'))
+        throw new Error(`"${p}": give a path inside inputs/, relative to it (e.g. "guides.glb")`);
+    const byPath = new Map(files.map((f) => [f.path, f]));
+    const hit = byPath.get(rel) ?? (rel.startsWith('inputs/') ? byPath.get(rel.slice(7)) : undefined);
+    if (hit)
+        return hit;
+    // a file the walk skipped (dot-file) or that just arrived: describe it if it is there
+    const abs = path.join(ws.inputDir, rel.startsWith('inputs/') && !fs.existsSync(path.join(ws.inputDir, rel)) ? rel.slice(7) : rel);
+    try {
+        const st = fs.statSync(abs);
+        if (st.isFile()) {
+            const r = path.relative(ws.inputDir, abs).split(path.sep).join('/'), ext = inputExt(r);
+            return { path: r, kind: inputKind(ext), ext, size: st.size, mtime: Math.round(st.mtimeMs) };
+        }
+    }
+    catch { /* not there */ }
+    const s = didYouMean(rel.replace(/^inputs\//, ''), files.map((f) => f.path));
+    throw new Error(`no input "${rel}"${s.length ? ` — did you mean ${s.join(', ')}?` : ''}. ${files.length ? `Files: ${files.slice(0, 20).map((f) => f.path).join(', ')}${files.length > 20 ? ', …' : ''}` : `inputs/ is empty (${ws.inputDir})`}`);
+}
+export function inputsTool(ws) {
+    const describer = new InputDescriber(ws);
+    return {
+        name: 'inputs',
+        description: 'The human\'s own material: files people drop into the workspace inputs/ folder (meshes, guide curves and points from Blender/Houdini/Unreal, blockouts, PNG masks and heightmaps). list: every file with kind (geometry/image/other), size, date and a summary (counts, curves vs meshes, bbox, object names; PNG size and bit depth). describe {path}: what a file node reads from it: polygons vs open polylines vs loose points vs packed prims, bbox in metres, attributes, groups, every name and role value, materials, warnings. Call list FIRST when building a landscape or scene: guides mark sites, paths, zones, volumes and blockouts (help topic "inputs"). Read a file with {type:"file", params:{path:"inputs/<path>"}}.',
+        inputSchema: {
+            type: 'object',
+            required: ['action'],
+            properties: {
+                action: { type: 'string', enum: ['list', 'describe'] },
+                path: { type: 'string', description: 'describe: the file, relative to inputs/ (as list prints it)' },
+            },
+        },
+        run: async (a) => {
+            const files = ws.listInputs();
+            describer.prune(files);
+            if (a.action === 'describe') {
+                const f = resolveInput(ws, a.path, files);
+                const d = await describer.describe(f);
+                const head = `inputs/${f.path}: ${f.kind}${f.ext ? ` (.${f.ext})` : ''}, ${sizeText(f.size)}, modified ${dateText(f.mtime)}`;
+                return text(`${head}\n${d.long}`, d.failed);
+            }
+            if (a.action !== 'list')
+                return text(`unknown action "${a.action}": use list or describe {path}`, true);
+            if (!files.length)
+                return text(`no input files yet. People drop meshes, guide curves and points, blockouts and PNG masks into ${ws.inputDir} (or onto the live viewer); then inputs list shows them. Readable: ${READABLE}.`);
+            const t0 = Date.now();
+            const rows = [];
+            let skipped = 0;
+            for (const f of files) {
+                let summary;
+                if (f.kind === 'other' || describer.cached(f) || Date.now() - t0 < LIST_BUDGET_MS)
+                    summary = (await describer.describe(f)).short;
+                else {
+                    summary = 'not summarised yet (list time budget): inputs describe reads it';
+                    skipped++;
+                }
+                rows.push(`  ${f.path}  ${f.kind}  ${sizeText(f.size)}  ${dateText(f.mtime)}  ${summary}`);
+            }
+            const kinds = ['geometry', 'image', 'other'].map((k) => [k, files.filter((f) => f.kind === k).length]).filter(([, c]) => c);
+            return text([
+                `inputs/ (${ws.inputDir}): ${plural(files.length, 'file')} (${kinds.map(([k, c]) => `${c} ${k}`).join(', ')})`,
+                ...rows,
+                ...(skipped ? [`${plural(skipped, 'file')} not summarised within ${LIST_BUDGET_MS / 1000} s; list again (summaries are cached) or describe them one by one.`] : []),
+                'A file node reads one: {"type":"file","params":{"path":"inputs/<path>"}} (paths are relative to the workspace). inputs {action:"describe", path} shows curves vs meshes, every name and role, attributes and materials; help {topic:"inputs"} explains the guide roles (site, path, zone, volume, blockout) and recipes.',
+                'OBJ/STL from Blender (Up = Z) and Unreal are Z-up: add "up_axis":"z". A .blend needs Blender installed (converted headlessly).',
+            ].join('\n'));
+        },
+    };
+}

package/dist/mcp/server.js

@@ -4,6 +4,7 @@
 //   topotopo mcp [--workspace <dir>] [--viewer]   (installed package: src/cli.ts dispatches here)
 // Env: TOPOTOPO_WORKSPACE, TOPOTOPO_VIEWER=1, TOPOTOPO_PORT, TOPOTOPO_SCRIPT_TIMEOUT_MS, TOPOTOPO_SIM_TIMEOUT_MS, TOPOTOPO_WORKERS
 // stdout carries the MCP protocol — log only to stderr.
+import fs from 'node:fs';
 import path from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -41,7 +42,9 @@ const ensureViewer = async () => {
 if (argv.includes('--viewer') || process.env.TOPOTOPO_VIEWER === '1')
     await ensureViewer();
 const tools = makeTools(ws, { onPreview: ensureViewer });
-const server = new Server({ name: 'topotopo', version: '0.1.0' }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+// package.json sits two levels above both src/mcp/server.ts and dist/mcp/server.js
+const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const server = new Server({ name: 'topotopo', version: pkg.version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
 }));

package/dist/mcp/tools.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import zlib from 'node:zlib';
-import { Workspace } from '../workspace.js';
+import { Workspace, EditRejected } from '../workspace.js';
 import { allNodeDefs } from '../graph/registry.js';
 import { didYouMean } from '../graph/params.js';
 import { migrateGraph } from '../graph/migrate.js';
@@ -16,6 +16,7 @@ import { exportFilesAsync } from '../io/files.js';
 import { evalGroup } from '../core/groups.js';
 import { Geometry } from '../core/geometry.js';
 import { verifyTools } from './verify.js';
+import { inputsTool } from './inputs.js';
 const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError } : {}) });
 /** " at frame N" when the cook was not at frame 1. */
 const atFrame = (r) => (r.frame !== 1 ? ` at frame ${r.frame}` : '');
@@ -131,6 +132,7 @@ const RENDER_PROPS = {
     glyph_attrib: { type: 'string', description: 'attribute for glyphs "custom": 3 floats = vector, 4 floats = quaternion' },
     glyph_scale: { type: 'number', description: 'glyph length in world units (default 5% of the bbox diagonal)' },
     max_glyphs: { type: 'number', description: 'evenly subsample to at most this many glyphs (default 400)' },
+    max_triangles: { type: 'number', description: 'packed instances: draw up to this many expanded triangles (default 600000, max 50M); above it an evenly spread subset is drawn and a note says so' },
     label_groups: { type: 'boolean', description: 'name each point/prim group on a visible member near its centroid, outline prim groups / mark group points in the label colour, legend with counts' },
     label_pieces: { type: 'boolean', description: 'number connected pieces (#0, #1, … in connectivity order)' },
     label_attrib: { type: 'string', description: 'label each distinct value of a string/int attribute (e.g. "name") on its elements; colours match color_by' },
@@ -147,9 +149,8 @@ const RENDER_PROPS = {
 };
 export function makeTools(ws, opts = {}) {
     const engine = ws.engine;
-    const cookAndReport = async (name, a, extraNotes = []) => {
-        const r = await ws.cook(name, undefined, a.frame);
-        ws.bump(name);
+    /** The text (+ optional render) of a cook report. */
+    const reportResult = (name, r, a, extraNotes = []) => {
         const content = [{ type: 'text', text: reportText(name, r, extraNotes) }];
         if (r.geo && a.render) {
             const ro = renderOpts(typeof a.render === 'object' ? a.render : {}, r.geo, `${name}/${r.target}${atFrame(r)}`);
@@ -160,8 +161,13 @@ export function makeTools(ws, opts = {}) {
         }
         return { content, isError: !r.ok };
     };
+    const cookAndReport = async (name, a, extraNotes = []) => {
+        const r = await ws.cook(name, undefined, a.frame);
+        ws.bump(name);
+        return reportResult(name, r, a, extraNotes);
+    };
     const resolveNodeGeo = async (a) => {
-        const name = a.graph ?? 'main';
+        const name = a.graph ?? a.name ?? 'main'; // `name` is what build/edit call it; accept both
         const g = ws.getGraph(name);
         const target = a.node || undefined;
         const r = await engine.cook(g, { target, frame: a.frame });
@@ -172,7 +178,7 @@ export function makeTools(ws, opts = {}) {
     const tools = [
         {
             name: 'catalog',
-            description: 'List available node types grouped by category (generate, curve, transform, deform, attribute, measure, group, topology, copy, solid, sdf, heightfield, uv, code, flow, io, pcg, shelf = shipped graph assets such as stairs or fence, asset = workspace assets). Optional filter by category or search text.',
+            description: 'List available node types grouped by category (generate, curve, transform, deform, attribute, measure, group, topology, copy, solid, sdf, heightfield, uv, code, flow, io, pcg, shelf = shipped graph assets such as stairs or fence, asset = workspace assets). Optional filter by category or search text. Building a landscape or scene for a person? Call inputs {action:"list"} first: the meshes, guide curves and masks they dropped into the workspace.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -181,7 +187,11 @@ export function makeTools(ws, opts = {}) {
                     include_deprecated: { type: 'boolean', description: 'also list deprecated node types (hidden by default)' },
                 },
             },
-            run: async (a) => text(catalogText([...allNodeDefs(), ...[...engine.assets.values()].map((x) => x.def)], { category: a.category, search: a.search, deprecated: a.include_deprecated })),
+            run: async (a) => {
+                const cat = catalogText([...allNodeDefs(), ...[...engine.assets.values()].map((x) => x.def)], { category: a.category, search: a.search, deprecated: a.include_deprecated });
+                const nIn = ws.listInputs().length;
+                return text(`${cat}\nHUMAN INPUT: ${nIn ? `${nIn} file${nIn === 1 ? '' : 's'} in` : 'nothing yet in'} the workspace inputs/ folder (meshes, guide curves and points, blockouts, PNG masks people drop in). Building a landscape or scene: inputs {action:"list"} first, then read them with file nodes (help topic "inputs").`);
+            },
         },
         {
             name: 'help',
@@ -213,12 +223,12 @@ export function makeTools(ws, opts = {}) {
         },
         {
             name: 'build',
-            description: 'Create or replace a whole node graph and cook it. Returns per-node errors with hints, warnings, and a summary of the output geometry (counts, bbox, attributes, groups). mode "merge" upserts nodes into the existing graph. dry_run validates and resolves params without cooking. render:true (or render options) also returns an image.',
+            description: 'Create or replace a whole node graph and cook it. Returns per-node errors with hints, warnings, and a summary of the output geometry (counts, bbox, attributes, groups). mode "merge" upserts nodes into the existing graph. dry_run validates and resolves params without cooking. render:true (or render options) also returns an image. Expose the 3–8 vars a human would tune: declare "params": {var: {type, desc, min, max, options, label, step}}; the live viewer shows them as controls. Humans may change vars at any time, so read the graph (graphs {action:"get"}) before assuming a var\'s value.',
             inputSchema: {
                 type: 'object',
                 required: ['graph'],
                 properties: {
-                    graph: { type: 'object', description: '{"nodes": {name: {"type", "in", "params"}}, "output": name, "vars": {...}}' },
+                    graph: { type: 'object', description: '{"nodes": {name: {"type", "in", "params"}}, "output": name, "vars": {...}, "params": {var: {"type", "desc", "min", "max", "options", "label", "step"}}}' },
                     name: { type: 'string', description: 'graph name (default "main")' },
                     mode: { type: 'string', enum: ['replace', 'merge'] },
                     dry_run: { type: 'boolean' },
@@ -262,12 +272,16 @@ export function makeTools(ws, opts = {}) {
             },
             run: async (a) => {
                 const name = a.name ?? 'main';
-                const { graph, notes } = ws.applyEdits(name, a.ops);
-                const v = engine.validate(graph);
-                if (v.errors.length)
-                    return text(`✗ edits rejected (graph unchanged) — ${v.errors.length} error(s):\n` + v.errors.map((e) => `  [${e.node}] ${e.message}`).join('\n'), true);
-                ws.setGraph(name, graph);
-                return cookAndReport(name, a, notes);
+                let res;
+                try {
+                    res = await ws.edit(name, a.ops, { frame: a.frame });
+                }
+                catch (e) {
+                    if (e instanceof EditRejected)
+                        return text(e.message, true);
+                    throw e;
+                }
+                return reportResult(name, res.report, a, res.notes);
             },
         },
         {
@@ -300,7 +314,7 @@ export function makeTools(ws, opts = {}) {
             inputSchema: {
                 type: 'object',
                 properties: {
-                    graph: { type: 'string' }, node: { type: 'string' },
+                    graph: { type: 'string', description: 'graph name (default "main")' }, node: { type: 'string', description: 'node to look at (default: the graph output)' },
                     ...RENDER_PROPS,
                     save_to: { type: 'string', description: 'also write the PNG to this path (relative to the workspace)' },
                     ...FRAME_PROP,
@@ -331,7 +345,7 @@ export function makeTools(ws, opts = {}) {
                 type: 'object',
                 required: ['path'],
                 properties: {
-                    graph: { type: 'string' }, node: { type: 'string' },
+                    graph: { type: 'string', description: 'graph name (default "main")' }, node: { type: 'string', description: 'node to look at (default: the graph output)' },
                     path: { type: 'string', description: 'e.g. "exports/rock.glb", "exports/trees.csv", "exports/pts.points.json", "exports/terrain.png" (heightmap), "exports/level" (unreal_landscape: a directory), "exports/maps" (textures: a directory)' },
                     format: { type: 'string', enum: EXPORT_FORMATS, description: 'default: from the extension (.points.json = pointsjson)' },
                     layer: { type: 'string', description: 'heightmaps: layer to write (png16/r16 default "height", mask_png default "mask")' },
@@ -483,7 +497,7 @@ export function makeTools(ws, opts = {}) {
             },
         },
     ];
-    tools.push(...verifyTools(ws)); // explain, diff
+    tools.push(...verifyTools(ws), inputsTool(ws)); // explain, diff; the human's input files
     if (opts.onPreview) {
         tools.push({
             name: 'preview',

package/dist/nodes/code.js

@@ -127,6 +127,8 @@ function scriptLib(ctx, wake, run) {
             const rp = resolveParams(def, params, ctx.vars, { time: ctx, host: engine.host, timeoutMs: engine.scriptTimeoutMs });
             if (rp.errors.length)
                 throw new Error(`lib.run(${type}): ${rp.errors.join('; ')}`);
+            for (const w of rp.warnings)
+                ctx.warn(`lib.run(${type}): ${w}`);
             // inherit from ctx through the prototype so its time getters stay lazy
             const sub = Object.assign(Object.create(ctx), {
                 node: `${ctx.node}/${type}`, type: def.type, p: rp.values, inputs,

package/dist/nodes/copy.js

@@ -950,7 +950,7 @@ defineNode({
         variants: { type: 'enum', options: ['none', 'name', 'piece'], default: 'none', desc: 'split the source into variants: name = by prim "name", piece = by connectivity (none = only when piece_attrib is set)' },
         piece_attrib: { type: 'string', default: '', desc: 'variants: source prim attribute that splits the geometry into pieces (e.g. "name" or "class")' },
         variant_attrib: { type: 'string', default: 'variant', desc: 'variants: template point attribute choosing a piece (int index into sorted piece values, or the exact value)' },
-        variant_weights: { type: 'json', default: [], desc: 'variants: weights per piece (in piece order) for a seeded weighted random pick when the template has no variant_attrib attribute, e.g. [3, 1, 1]; missing weights are 0', aliases: ['weights', 'variant_probabilities'] },
+        variant_weights: { type: 'json', default: [], desc: 'variants: weights for a seeded weighted random pick when the template has no variant_attrib attribute: by piece value, e.g. {"tree": 3, "bush": 1}, or a list in piece order (names sorted alphabetically, connectivity pieces in prim order), e.g. [3, 1, 1]; missing weights are 0', aliases: ['weights', 'variant_probabilities'] },
         seed: { type: 'float', default: 0, desc: 'variant_weights: random seed' },
         scale_attrib: { type: 'string', default: '', desc: 'template point attribute multiplying the copy scale (float = uniform, vec3 = per axis), on top of pscale and scale', aliases: ['scale_by'] },
         rotate_attrib: { type: 'string', default: '', desc: 'template point attribute adding a local rotation after orient/N/rot: float = degrees about +Y (yaw), vec3 = Euler degrees (XYZ), vec4 = quaternion', aliases: ['rotate_by'] },
@@ -1010,12 +1010,22 @@ defineNode({
                     subsets.set(v, src.subsetPrims(Uint8Array.from({ length: src.numPrims }, (_, i) => (pa.get(i) === v ? 1 : 0))));
             }
             const va = p.variant_attrib ? t.points.get(p.variant_attrib) : undefined;
-            const wts = Array.isArray(p.variant_weights) ? p.variant_weights.map((x) => Math.max(0, Number(x) || 0)) : [];
+            const wv = p.variant_weights;
+            // {piece value: weight} (dogfood 2026-10-15: a list follows the sorted piece order, which surprised a user) or a list
+            const byValue = wv && typeof wv === 'object' && !Array.isArray(wv) ? wv : null;
+            const wts = byValue
+                ? values.map((v) => Math.max(0, Number(byValue[String(v)]) || 0))
+                : Array.isArray(wv) ? wv.map((x) => Math.max(0, Number(x) || 0)) : [];
+            if (byValue) {
+                const unknown = Object.keys(byValue).filter((k) => !values.some((v) => String(v) === k));
+                if (unknown.length)
+                    warn(`variant_weights: no variant named ${unknown.map((k) => `"${k}"`).join(', ')} (variants: ${values.join(', ')})`);
+            }
             let wcdf = null;
             if (wts.length && va)
                 warn(`variant_weights ignored: the template points have "${p.variant_attrib}", which picks the variants`);
             else if (wts.length && values.length) {
-                if (wts.length !== values.length)
+                if (!byValue && wts.length !== values.length)
                     warn(`variant_weights has ${wts.length} weight(s) for ${values.length} variant(s) (${values.join(', ')}); missing weights are 0`);
                 wcdf = new Float64Array(values.length);
                 let acc = 0;
@@ -1047,7 +1057,7 @@ defineNode({
             };
             pieceOf = (i) => subsets.get(pieceKey(i)) ?? new Geometry();
         }
-        else if (Array.isArray(p.variant_weights) && p.variant_weights.length)
+        else if (p.variant_weights && typeof p.variant_weights === 'object' && Object.keys(p.variant_weights).length)
             warn('variant_weights needs variants ("name" or "piece") or piece_attrib to split the source into variants');
         const copyNames = new Set();
         const pats = String(p.copy_attribs).split(/[\s,]+/).filter(Boolean);