topotopo 0.1.0 → 0.3.0

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';
@@ -12,10 +12,13 @@ import { renderGeometry } from '../render/raster.js';
 import { renderArgs } from '../render/options.js';
 import { encodePNG } from '../render/png.js';
 import { EXPORT_FORMATS, exportFormatFromPath } from '../io/export.js';
-import { exportFilesAsync } from '../io/files.js';
+import { publishedOutputs } from '../io/targets.js';
+import { ArtifactStore } from '../host/artifacts.js';
+import { prepareTarget, serializeExport, writeExportFiles, writeTargets } from '../host/export-targets.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}` : '');
@@ -64,30 +67,19 @@ function pngContent(g, o) {
  * Landscape bundle, or the single file of other formats). Textures are read through the host; USD texture paths are
  * written relative to the output file. Returns the report text.
  */
-export async function writeExport(geo, format, p, a, host) {
-    const warnings = [];
-    const outDir = format === 'unreal_landscape' && !/\.json$/i.test(p) ? p : path.dirname(p);
-    const res = await exportFilesAsync(geo, format, p, {
-        upAxis: a.up_axis, scale: a.scale, splitByName: a.split_by_name ?? true, custom: a.custom_attribs,
-        materials: a.materials, compress: a.compress, quantize: a.quantize, attributes: a.attributes, pcg: a.pcg || a.pcg_struct, pcgStruct: a.pcg_struct,
-        precision: a.precision, instancing: a.instancing, instances: a.instances, meshes: a.meshes,
-        layer: a.layer, layers: a.layers, heightMin: a.height_min, heightMax: a.height_max, heightfield: a.heightfield, tile_size: a.tile_size,
-        deflate: (d) => zlib.deflateSync(d, { level: 6 }),
-        readFile: (t) => host.readFile(t),
-        texturePath: (t) => {
-            const abs = host.resolvePath(t);
-            return /^[a-z][a-z0-9+.-]*:\/\//i.test(abs) ? abs : path.relative(outDir, abs).split(path.sep).join('/');
-        },
-        warn: (m) => warnings.push(m),
-    });
-    for (const f of res.files) {
-        fs.mkdirSync(path.dirname(f.path), { recursive: true });
-        fs.writeFileSync(f.path, f.bytes);
-    }
-    const total = res.files.reduce((s, f) => s + f.bytes.byteLength, 0);
+export async function writeExport(geo, format, p, a, host, record) {
+    const res = await serializeExport(geo, format, p, a, host);
+    writeExportFiles(res.files);
+    if (res.files.length)
+        record?.(res.files.map((f) => f.path));
+    return exportReport(res.files, res.outDir, format, res.summary, res.warnings);
+}
+/** "wrote <file or N files in dir> (format, KB): summary", then any warnings. */
+function exportReport(files, outDir, format, summary, warnings) {
+    const total = files.reduce((s, f) => s + f.bytes.byteLength, 0);
     const rel = (f) => path.relative(outDir, f).split(path.sep).join('/');
-    const list = res.files.length === 1 ? res.files[0].path : `${res.files.length} files in ${outDir}: ${res.files.slice(0, 12).map((f) => rel(f.path)).join(', ')}${res.files.length > 12 ? ', …' : ''}`;
-    return `wrote ${list} (${format}, ${(total / 1024).toFixed(1)} KB): ${res.summary}${warnings.length ? '\nwarnings:\n  ' + [...new Set(warnings)].join('\n  ') : ''}`;
+    const list = files.length === 1 ? files[0].path : `${files.length} files in ${outDir}: ${files.slice(0, 12).map((f) => rel(f.path)).join(', ')}${files.length > 12 ? ', …' : ''}`;
+    return `wrote ${list} (${format}, ${(total / 1024).toFixed(1)} KB): ${summary}${warnings.length ? '\nwarnings:\n  ' + warnings.join('\n  ') : ''}`;
 }
 function renderOpts(a, g, label) {
     const ro = renderArgs(a); // views (presets, persp@az, section), overlays, shading, labels … (src/render/options.ts)
@@ -131,6 +123,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' },
@@ -146,22 +139,33 @@ const RENDER_PROPS = {
     texture: { type: 'string', description: 'adds the "texture" view and picks what it shows: an image name, "image/layer", or a material name (its maps as a labelled strip); "" = every image. A geometry holding only images renders as the texture view by default' },
 };
 export function makeTools(ws, opts = {}) {
+    // One file per graph node, overwritten by each render: agents render after most edits, so a new file per render
+    // would pile up in exports/renders (save_to keeps a copy elsewhere).
+    const renderDestination = (name, node) => path.join(ws.exportDir, 'renders', `${name}-${node}`.replace(/[^A-Za-z0-9_.-]/g, '_') + '.png');
     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)}`);
-            const { img, notes } = pngContent(r.geo, ro);
+            const { img, notes, png } = pngContent(r.geo, ro);
+            const renderPath = renderDestination(name, r.target);
+            fs.mkdirSync(path.dirname(renderPath), { recursive: true });
+            fs.writeFileSync(renderPath, png);
+            new ArtifactStore(ws.exportDir).record([renderPath], { graph: name, node: r.target, format: 'png' });
             content.push(img);
             if (notes.length)
                 content.push({ type: 'text', text: 'render: ' + notes.join('; ') });
         }
         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 });
@@ -169,10 +173,39 @@ export function makeTools(ws, opts = {}) {
             throw new Error(reportText(name, r));
         return { r, name, geo: r.geo };
     };
+    /** export without a path: the graph's targets (the default output's, a named one's, or all), inside exports/ */
+    const exportTargets = async (a) => {
+        const name = a.graph ?? a.name ?? 'main', spec = ws.getGraph(name);
+        const published = publishedOutputs(name, spec, engine.findOutput(spec).name);
+        const hint = (o) => `edit {ops:[{op:"export"${o === undefined ? '' : `, output:"${o}"`}, export:"glb"}]}`;
+        let chosen = published;
+        if (!a.all) {
+            const p = a.output === undefined ? published[0] : published.find((x) => x.output === a.output);
+            if (!p)
+                return text(`graph "${name}" publishes no output "${a.output}" (outputs: ${published.slice(1).map((x) => x.output).join(', ') || 'none'})`, true);
+            if (!p.target)
+                return text(`${a.output === undefined ? 'the default output' : `output "${a.output}"`} of "${name}" has no export target: set one with ${hint(a.output)}, or pass path`, true);
+            chosen = [p];
+        }
+        const targets = chosen.filter((p) => p.target);
+        if (!targets.length)
+            return text(`no output of "${name}" has an export target: set one with ${hint(undefined)}, or pass path`, true);
+        const prepared = [];
+        for (const p of targets) {
+            const r = await ws.cook(name, p.node, a.frame);
+            if (!r.ok || !r.geo)
+                return text(reportText(name, r), true);
+            prepared.push(await prepareTarget(r.geo, name, p, ws.exportDir, engine.host));
+        }
+        writeTargets(prepared, ws.exportDir);
+        const skipped = chosen.filter((p) => !p.target).map((p) => p.label);
+        return text(prepared.map((p) => exportReport(p.files, ws.exportDir, p.target.format, `${p.label}: ${p.summary}`, p.warnings)).join('\n')
+            + (skipped.length ? `\nno export target (skipped): ${skipped.join(', ')}` : ''));
+    };
     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 +214,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 +250,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, "outputs": {id: {"node": name, "label": "Published result", "export": "glb"}}, "export": "glb", "vars": {...}, "params": {var: {"type", "desc", "min", "max", "options", "label", "step"}}}. Publish intended deliverables in outputs; output remains the default. "export" (on the graph for the default output, or on a named output) is where it exports: a format, or {format, path?, ...export options}, written inside exports/ by the viewer\'s Export buttons and export {output} / {all:true}.' },
                     name: { type: 'string', description: 'graph name (default "main")' },
                     mode: { type: 'string', enum: ['replace', 'merge'] },
                     dry_run: { type: 'boolean' },
@@ -249,7 +286,7 @@ export function makeTools(ws, opts = {}) {
         },
         {
             name: 'edit',
-            description: 'Incrementally edit a graph, then re-cook (only affected nodes recompute). ops: {op:"set",node,params} (null removes a param) · {op:"add",node,type,in,params} · {op:"insert",node,type,params,after} (splice after a node) · {op:"remove",node} (rewires consumers) · {op:"connect",node,in:[...]} or {op:"connect",node,input:1,from:"x"} · {op:"rename",node,to} · {op:"replace",node,type?,params?,in?} · {op:"output",node} · {op:"vars",vars:{k:v}} · {op:"bypass",node,value}.',
+            description: 'Incrementally edit a graph, then re-cook (only affected nodes recompute). ops: {op:"set",node,params} (null removes a param) · {op:"add",node,type,in,params} · {op:"insert",node,type,params,after} (splice after a node) · {op:"remove",node} (rewires consumers) · {op:"connect",node,in:[...]} or {op:"connect",node,input:1,from:"x"} · {op:"rename",node,to} · {op:"replace",node,type?,params?,in?} · {op:"output",node} · {op:"vars",vars:{k:v}} · {op:"bypass",node,value} · {op:"export",output?,export} (the export target of a named output, or of the default output without "output": a format "glb" or {format, path?, ...export options}; null removes it).',
             inputSchema: {
                 type: 'object',
                 required: ['ops'],
@@ -262,12 +299,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 +341,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,
@@ -311,10 +352,11 @@ export function makeTools(ws, opts = {}) {
                 const { img, notes, png } = pngContent(geo, renderOpts(a, geo, `${name}/${r.target}${atFrame(r)}`));
                 const content = [img];
                 const info = [];
-                if (a.save_to) {
-                    const p = path.resolve(ws.dir, a.save_to);
+                {
+                    const p = a.save_to ? path.resolve(ws.dir, a.save_to) : renderDestination(name, r.target);
                     fs.mkdirSync(path.dirname(p), { recursive: true });
                     fs.writeFileSync(p, png);
+                    new ArtifactStore(ws.exportDir).record([p], { graph: name, node: r.target, format: 'png' });
                     info.push(`saved ${p}`);
                 }
                 if (notes.length)
@@ -329,10 +371,11 @@ export function makeTools(ws, opts = {}) {
             description: 'Write a node\'s output to a file: .glb/.gltf (glTF via gltf-transform: materials + texture maps, vertex colours, uv, custom attributes, EXT_mesh_gpu_instancing with per-instance attributes, meshopt compression; best for Unreal/Blender/web), .obj, .usda (PointInstancer with per-instance primvars, UsdPreviewSurface materials), .ply, .stl, .geo (Houdini JSON geometry, every attribute and group, packed prims as PackedGeometry), .csv (point stream; pcg:true for Unreal PCG columns; packed instances = one row per instance + Mesh column + .meshes.json sidecar + one GLB per source), .points.json, .json (lossless topotopo). Relative paths go into the workspace. help {topic:"export"} for details. Heightfields: png16 (.png, 16-bit Unreal Landscape heightmap) or r16 (.r16/.raw) plus a .json sidecar with the height range and the Unreal scale/location, mask_png (8-bit weight layers; param layers), unreal_landscape (a directory: heightmap, every layer, manifest with the exact Landscape import settings, objects.glb and the instance stream). Textures: glb/gltf embed the image textures of materials (texture_to_material) as PNG, usda writes them to <name>_textures/ next to the file, format textures writes every image as <path>/<image>.png (layers: extra layers, or ["*"]).',
             inputSchema: {
                 type: 'object',
-                required: ['path'],
                 properties: {
-                    graph: { type: 'string' }, node: { type: 'string' },
-                    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)' },
+                    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). Without path: the graph\'s export targets (output / all), written inside exports/' },
+                    output: { type: 'string', description: 'without path: export this named output (graph.outputs) to its target; omitted = the default output (graph.export)' },
+                    all: { type: 'boolean', description: 'without path: export every output of the graph that has an export target' },
                     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")' },
                     layers: { type: 'array', items: { type: 'string' }, description: 'mask_png: layers to write, one PNG each (name_<layer>.png); textures: extra image layers to write as <image>_<layer>.png ("*" = all)' },
@@ -358,13 +401,15 @@ export function makeTools(ws, opts = {}) {
                 },
             },
             run: async (a) => {
+                if (a.path === undefined)
+                    return exportTargets(a);
                 const { geo, name, r } = await resolveNodeGeo(a);
                 const p = path.resolve(ws.dir, a.path);
                 const fmt0 = String(a.format ?? exportFormatFromPath(p)).toLowerCase();
                 const ext = ({ png: 'png16', raw: 'r16' }[fmt0] ?? fmt0);
                 if (!EXPORT_FORMATS.includes(ext))
                     throw new Error(`unknown format "${ext}"; use ${EXPORT_FORMATS.map((f) => (f === 'pointsjson' ? '.points.json' : '.' + f)).join(' ')}`);
-                const report = await writeExport(geo, ext, p, a, engine.host);
+                const report = await writeExport(geo, ext, p, a, engine.host, (files) => new ArtifactStore(ws.exportDir).record(files, { graph: name, node: r.target, format: ext }));
                 return text(`${report}\n(from ${name}/${r.target}${atFrame(r)}: ${geo.numPoints} points, ${geo.numPrims} prims)`);
             },
         },
@@ -483,14 +528,36 @@ 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',
-            description: 'Start (or get the URL of) the live 3D preview web page for humans: orbit view of any graph/node that auto-refreshes after every build/edit. Returns the URL to open in a browser.',
+            description: 'Start (or get the URL of) the live viewer for humans: an editor viewport of the workspace (graph menu, an outliner with the graph\'s nodes, single and quad views, the graph\'s params as Controls, input layers and guides) that updates after every build/edit. Returns the URL to open in a browser.',
             inputSchema: { type: 'object', properties: {} },
-            run: async () => text(`live preview: ${await opts.onPreview()}  (updates automatically on every build/edit; click nodes in the sidebar to view intermediate results)`),
+            run: async () => text(`live preview: ${await opts.onPreview()}  (updates automatically on every build/edit; click a node in the outliner to see its result)`),
         });
     }
+    // A person can add files to inputs/ at any time (the viewer's Add input, a drop, the folder). The first answer says
+    // what is there, later answers what is new or changed since the last one; the inputs tool's own answer counts.
+    let heard = null;
+    const inputsNote = (tool) => {
+        const files = ws.listInputs(), now = new Map(files.map((f) => [f.path, `${f.size}:${f.mtime}`]));
+        const first = heard === null, fresh = files.filter((f) => heard?.get(f.path) !== now.get(f.path));
+        heard = now;
+        if (tool === 'inputs' || !fresh.length)
+            return '';
+        const shown = fresh.slice(0, 8).map((f) => `inputs/${f.path} (${f.kind}, ${(f.size / 1024).toFixed(0)} KB)`).join(', ') + (fresh.length > 8 ? `, and ${fresh.length - 8} more` : '');
+        return `${first ? `inputs/ holds ${files.length} file(s) from the person` : 'new or changed in inputs/ since your last call'}: ${shown}. inputs {action:"describe", path} tells what one holds.`;
+    };
+    for (const t of tools) {
+        const run = t.run;
+        t.run = async (args) => {
+            const result = await run(args);
+            const note = inputsNote(t.name);
+            if (note)
+                result.content.push({ type: 'text', text: note });
+            return result;
+        };
+    }
     return tools;
 }

package/dist/nodes/code.js

@@ -83,8 +83,9 @@ defineNode({
 function scriptLib(ctx, wake, run) {
     const engine = ctx.engine;
     // compiled in the script realm: a synchronous node's result resolves a realm promise, so `await lib.run(...)`
-    // continues inside the same time-limited call; only async nodes hand back an outside promise (then: wake)
-    const realmAsync = engine.host.compile('(function(f){ return async function run(...a) { return f(...a); }; })');
+    // continues inside the same time-limited call; an async node hands back its outcome (see run below), which the
+    // realm awaits and turns back into the node's value or error
+    const realmAsync = engine.host.compile('(function(f){ return async function run(...a) { const r = f(...a); if (r && r.libRunOutcome) { const o = await r.libRunOutcome; if (o.failed) throw o.error; return o.value; } return r; }; })');
     return {
         Geometry, GeoBuilder, math, topology, random,
         noise: { makeNoise, fractal, makeCurl },
@@ -127,15 +128,42 @@ 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,
                 input: (i) => inputs[i] ?? new Geometry(), hasInput: (i) => !!inputs[i], inputSigs: inputs.map(() => 'script'),
             });
-            const r = def.cook(sub);
-            if (r && typeof r.then === 'function')
-                r.then(wake, wake);
-            return r;
+            // The script's time limit can stop it anywhere, also between starting an async node and listening to it: that
+            // node's promise would then reject later with nobody listening, which ends the process (MCP server included).
+            // So an async node's promise is awaited right inside `outcome`, with no call in between that the limit could
+            // stop, and `outcome` never rejects. A synchronous node returns (or throws) here, as before.
+            let started, thrownNow = null;
+            const isAsync = () => !!started && typeof started.then === 'function';
+            const outcome = (async () => {
+                try {
+                    started = def.cook(sub);
+                    // property reads only from here to the await: a function call is where the limit could stop the script
+                    if (!started || typeof started.then !== 'function')
+                        return null;
+                    return { value: await started };
+                }
+                catch (error) {
+                    if (!isAsync()) {
+                        thrownNow = { error };
+                        return null;
+                    }
+                    return { failed: true, error };
+                }
+                finally {
+                    if (isAsync())
+                        wake();
+                }
+            })();
+            if (thrownNow)
+                throw thrownNow.error;
+            return isAsync() ? { libRunOutcome: outcome } : started;
         }),
         warn: (m) => ctx.warn(String(m)),
     };

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);