topotopo 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,11 @@
-# TopoTopo
+# <img src="docs/brand/mark.svg" alt="" width="44" height="44" align="top"> TopoTopo
 
 *Formerly Polyforge; renamed before the first tagged release. Files written as `polyforge-*` still load.*
 
-A procedural geometry engine: Houdini-style node graphs, headless, deterministic, exports to Unreal, Blender and
-Houdini. You build JSON node graphs; the engine cooks them into geometry. It runs on Node and WebAssembly with no
-GPU, every cook is reproducible from the graph and its seeds, and the core is browser-ready.
+TopoTopo is an open-source procedural geometry engine. You describe geometry as a node graph in JSON; the engine
+cooks it headless and deterministic, and exports it to Unreal, Blender and Houdini. Built for LLM agents through MCP,
+and for people through the CLI. It runs on Node and WebAssembly with no GPU, every cook is reproducible from the
+graph and its seeds, and the core is browser-ready.
 
 - **200+ node types**: generators, curves and splines (Bezier/NURBS), sweeps, deformers, attributes and groups, polygon
   modelling (bevel, knife, bridge, quad fill), UVs (xatlas unwrap, LSCM), remeshing (isotropic, quad, voxel) and LOD,
@@ -13,6 +14,8 @@ GPU, every cook is reproducible from the graph and its seeds, and the core is br
   cloth draping and inflation (XPBD), L-systems, text, loops, a frame solver, in-graph checks, and code nodes. A shelf of ready-made graph assets (walls,
   roofs, stairs, props, trees, rocks, PCG helpers) is used like nodes. Every node documents its params and carries an
   example that is cooked in the tests.
+- **Familiar to Houdini users**: SOP-style nodes, attributes, groups and `.geo` export; Houdini node names work as
+  aliases. Blender Geometry Nodes and Unreal PCG users will recognise the rest.
 - **Rust/WASM kernels**: a straight skeleton (pitched roofs and polygon offsets from any footprint, holes included),
   sampled SDF grids with CSG, morphology and sharp dual contouring (`voxel_remesh`), field-aligned quad remeshing
   (`remesh_quad`), and heightfield erosion and drainage (virtual-pipe and stream-power models, D8/D-infinity flow) are
@@ -29,6 +32,13 @@ GPU, every cook is reproducible from the graph and its seeds, and the core is br
   with Unreal PCG columns, points JSON, USDA (UsdPreviewSurface materials), OBJ, PLY, STL and lossless JSON, with
   Y/Z-up and scale. Mesh splitting follows the `name` attribute, for Unreal, Blender and Houdini. The `file` node reads
   the same formats back (glTF with meshopt and external buffers, `.geo` and uncompressed `.bgeo`, CSV).
+
+  **Scene and folder import.** Give the `file` node a GLB/glTF scene, a `.blend` file, or a folder of models.
+  Scene empties become points, shared meshes stay packed, and object names, hierarchy paths and custom properties
+  arrive as attributes. `.blend` uses Blender's own headless exporter (install Blender; `TOPOTOPO_BLENDER` selects
+  the executable). Folders load supported files in name order; `name` is the file stem, or `<stem>/<name>` for files
+  with multiple object names, ready for `copy_to_points {variants: 'name'}`.
+
 - **Instancing**: packed primitives (Houdini's packed prims) keep a million copies as a million points plus one shared
   mesh: `copy_to_points {pack: true}` (with variants), `pack`, `unpack`. Transforms, merges, deletes and attribute nodes
   work on the instances; other nodes unpack them automatically with a warning. GLB export writes
@@ -41,9 +51,15 @@ GPU, every cook is reproducible from the graph and its seeds, and the core is br
   with the exact Landscape import settings, the meshes and the instance stream.
 - **Textures**: a Substance-Designer-style image node family (noise, patterns, cells, shapes, blends, levels, warps,
   normal and AO from height, channel packing) and bakes from meshes in uv space (AO, curvature, thickness, normals and
-  height from a high-res mesh, island ids, masks, vertex colour). Images travel with the geometry, materials reference
-  them as `image:<name>`, and glTF/USD exports carry them, so assets ship with textures whose licence is the graph's.
-- **Live preview**: a local three.js page that refreshes whenever a graph changes. Click any node to see its result.
+  height from a high-res mesh, island ids, masks, vertex colour). Your own PNGs (8 or 16 bit, grey or colour) load as
+  images with `image_file` and go through the same nodes. Images travel with the geometry, materials reference them as
+  `image:<name>`, and glTF/USD exports carry them, so assets ship with textures whose licence is the graph's.
+- **Live preview and controls**: a local three.js page that refreshes whenever a graph changes. Click any node to
+  see its result. A graph's exposed `params` appear as sliders, checkboxes, selects and colour pickers; dragging one
+  re-cooks only the nodes that read it. Drop your own files
+  anywhere on the page: they land in the workspace `inputs/` folder (with `topotopo view`, the `inputs/` folder beside
+  the graph file), show as grey reference layers (a PNG as a flat picture), and `file` nodes read them as
+  `inputs/<name>`.
 
 **Documentation:** [topotopo.dev](https://topotopo.dev) has the node reference, the shelf and example galleries, the
 design notes and the release notes, generated from this repository (`npm run site`).
@@ -62,11 +78,13 @@ Requires Node ≥ 22.18.
 npx topotopo --catalog                                      # node types by category
 npx topotopo --help-node scatter                            # one node's params, defaults and example
 npx topotopo graph.json --render out.png --export out.glb   # cook, render, export
+npx topotopo view graph.json                                # live 3D viewer, re-cooks on save; drops go to inputs/ beside it
 npx topotopo mcp --workspace /absolute/path/to/workspace    # the MCP server over stdio
 ```
 
-The package is not on npm yet. Until it is, build the tarball from a clone and install that:
-`npm pack`, then `npm install -g ./topotopo-0.1.0.tgz` (or into a project), and run `topotopo …`.
+v0.2 is the first tagged release ([release notes](docs/release/v0.2-release-notes.md)); `topotopo@0.1.0` was an untagged
+preview. To try unreleased changes, build the tarball from a clone: `npm pack`, then
+`npm install -g ./topotopo-<version>.tgz` (or into a project).
 `import { Engine } from 'topotopo'` gives the engine API (`src/index.ts`) with its type declarations.
 
 **From a clone.** Development runs the TypeScript sources directly (Node type stripping); there is no build step for
@@ -133,14 +151,21 @@ From a clone, run the sources instead: `"command": "node"`, `"args": ["C:/path/t
 Options: `--viewer` (start the live preview immediately), or set `TOPOTOPO_PORT`, `TOPOTOPO_WORKSPACE`,
 `TOPOTOPO_SCRIPT_TIMEOUT_MS`, `TOPOTOPO_SIM_TIMEOUT_MS` and `TOPOTOPO_WORKERS`. The server exits when the client closes its stdin.
 
+The workspace folder holds `graphs/` (one JSON file per graph), `assets/` (saved assets), `inputs/` and `exports/`.
+`inputs/` is where you put your own material: meshes, guide curves and points, blockouts and PNG masks from Blender,
+Houdini or Unreal (glTF, OBJ, STL, PLY, .geo, CSV, PNG). The agent's `inputs` tool lists and describes them, and a
+`file` node reads one as `inputs/<file>` (a PNG as an image for the texture nodes). Naming objects `path.river`, `zone.park`, `site.well`, `volume.no_trees` or
+`blockout.house` tells the agent what they mean (help topic `inputs`).
+
 ## MCP tools
 
 | tool | purpose |
 |---|---|
 | `catalog` | node types by category (filter/search) |
-| `help` | exact node docs (params, defaults, ranges, aliases, examples) and topics: graph, expressions, time, wrangle, groups, attributes, sdf, heightfield, textures, loops, instancing, rbd, pcg, curves, particles, assets, uv, render, export, verify, recipes |
-| `build` | create/replace a graph and cook it; `dry_run`, `mode: "merge"`, optional `render`, `frame` (also on edit, inspect, render, export) |
+| `help` | exact node docs (params, defaults, ranges, aliases, examples) and topics: graph, inputs, expressions, time, wrangle, groups, attributes, sdf, heightfield, textures, loops, instancing, rbd, pcg, curves, particles, assets, uv, render, export, verify, cloth, recipes |
+| `build` | create/replace a graph and cook it; `dry_run`, `mode: "merge"`, optional `render`, `frame` (also on edit, inspect, render, export); `params` declare the vars a person tunes (type, desc, min, max, options, label, step), shown as controls in the viewer |
 | `edit` | incremental ops: set, add, insert-after, remove (auto-rewire), connect, rename, replace, output, vars, bypass |
+| `inputs` | `list` the files in the workspace `inputs/` folder (kind, size, date, counts, bbox, object names; PNG size and bit depth) and `describe` one: polygons vs open polylines vs loose points vs packed prims, bbox, attributes, groups, every `name` / `role` value, materials |
 | `inspect` | summary, attribute stats, topology health (watertight, pieces, volume, genus), element listings, images (size and per-layer ranges) |
 | `render` | PNG with persp/front/right/top views, `turntable`, a `uv` view (`quad_uv`), uv checker, a `texture` view of images and `textures: true` for base colour maps on meshes, colour by attribute (+ `legend`), group highlight, flipped normals in blue; opt-in overlays: `section` view and `clip` plane with filled caps, edge overlays (`wireframe` all / hard / boundary / groups), `glyphs` (N, up, orient, v), group / piece / attribute labels and point / prim numbers, `shading` flat / matcap / ao, `scale: 2`, `view_labels: false` (no view labels or axis gizmo, as in the shelf thumbnails); a footer line names what is shown (help topic `render`) |
 | `export` | glb / gltf / obj / usda / ply / stl / json / geo / csv / points.json (packed instances: instance rows + meshes sidecar + one GLB per source); heightfields: png16 / r16 (+ JSON sidecar with the Unreal import numbers) / mask_png / unreal_landscape (a directory bundle); images: textures (one PNG per image; glb/gltf embed and usda writes the textures materials use) |
@@ -217,7 +242,7 @@ boundary. Do not cook graphs from untrusted sources in a privileged process.
 | sdf | `sdf_shape` `sdf_expr` `sdf_combine` `sdf_modify` `sdf_from_mesh` `sdf_to_mesh` (implicit, lazily sampled); sampled grids (Rust/WASM): `sdf_grid` `grid_combine` `grid_offset` `grid_blur` `grid_dilate` `grid_erode` `grid_resample` `grid_to_mesh` (sharp dual contouring or marching cubes) `grid_to_sdf` `voxel_remesh` |
 | heightfield | `heightfield` `heightfield_noise` `heightfield_from_mesh` `heightfield_from_image` `heightfield_to_mesh` `heightfield_to_sdf` `heightfield_remap` `heightfield_blur` `heightfield_terrace` `heightfield_clip` `heightfield_cutout` `heightfield_layer` `heightfield_mask_by_feature` `heightfield_mask_by_object` `heightfield_mask_noise` `heightfield_mask_blur` `heightfield_mask_expand` `heightfield_erode` `heightfield_fill_sinks` `heightfield_flow` `heightfield_project` `heightfield_path` `heightfield_scatter` `heightfield_resample` `heightfield_transform` (grids in XZ with named layers; export `png16`/`r16`/`mask_png` for Unreal Landscape) |
 | uv | `uv_project` `uv_transform` `uv_unwrap` (xatlas) `uv_flatten` (LSCM) `uv_layout` `uv_autoseam` |
-| texture | generators `tex_noise` `tex_pattern` `tex_cells` `tex_gradient` `tex_shape` `tex_splatter` `tex_scratches` `tex_text`; filters `tex_blend` `tex_levels` `tex_curves` `tex_blur` `tex_warp` `tex_transform` `tex_edge_detect` `tex_invert` `tex_threshold` `tex_histogram_scan` `tex_normal_from_height` `tex_height_to_ao` `tex_channel` (ORM packing) `tex_colorize` `tex_tile_sampler` `tex_output`; bakes in uv space `bake_ao` `bake_curvature` `bake_thickness` `bake_position` `bake_normal` `bake_world_normal` `bake_height` `bake_island_id` `bake_mask` `bake_vertex_color`; `texture_to_material` `tex_to_heightfield` `heightfield_to_tex` (images are 2D float layers carried on the geometry; glb/usda embed them, export format `textures` writes PNGs) |
+| texture | generators `tex_noise` `tex_pattern` `tex_cells` `tex_gradient` `tex_shape` `tex_splatter` `tex_scratches` `tex_text`; PNG files `image_file`; filters `tex_blend` `tex_levels` `tex_curves` `tex_blur` `tex_warp` `tex_transform` `tex_edge_detect` `tex_invert` `tex_threshold` `tex_histogram_scan` `tex_normal_from_height` `tex_height_to_ao` `tex_channel` (ORM packing) `tex_colorize` `tex_tile_sampler` `tex_output`; bakes in uv space `bake_ao` `bake_curvature` `bake_thickness` `bake_position` `bake_normal` `bake_world_normal` `bake_height` `bake_island_id` `bake_mask` `bake_vertex_color`; `texture_to_material` `tex_to_heightfield` `heightfield_to_tex` (images are 2D float layers carried on the geometry; glb/usda embed them, export format `textures` writes PNGs) |
 | sim | `particles` (Houdini POPs in one node: emission from points, gravity, drag, wind, curl noise, point/heightfield/SDF fields, attraction, floor and mesh collisions with die/slide/bounce, trails as polylines; steps with the frame, each frame's state cached; bit-identical on the worker pool) `rbd_settle` (drop pieces onto a terrain, container or ground until they rest; Rapier rigid bodies, packed instances stay packed) `rbd_stack` (drop them one at a time into piles) `drape` (XPBD cloth: colliders, floor, pins, wind, self collision) `inflate` (pressure: cushions, balloons) |
 | code | `wrangle` `script` |
 | flow | `merge` `switch` `null` `input` `foreach` `solver` `graph_ref` (plus saved assets) |
@@ -263,6 +288,7 @@ node src/cli.ts examples/csg_bracket.json --render out/bracket.png --section x:0
 node src/cli.ts examples/terrain_erosion.json --node road --export out/terrain.png   # 16-bit heightmap + terrain.json (Unreal)
 node src/cli.ts examples/unreal_demo.json --node landscape --format unreal_landscape --export out/level   # Landscape bundle
 node src/cli.ts examples/forest.json --node forest --export out/trees.csv --pcg   # instance rows + trees.meshes.json + trees_meshes/*.glb
+node src/cli.ts view examples/unreal_demo.json   # live viewer at http://127.0.0.1:7341: node list, per-node geometry, re-cook on save
 ```
 
 Animated graphs cook at a frame (`--frame 40`) or over a range. With `--frames`, output paths may contain `{frame}` or
@@ -412,6 +438,12 @@ the node library. The renderer is in `src/render`, import/export in `src/io`, an
 described in [docs/DESIGN.md](docs/DESIGN.md). `dist/` (not in git) is the compiled package: `npm run build` mirrors
 `src/` there one to one, so the shelf, fonts, kernels and worker entry are found relative to either.
 
+## Support
+
+TopoTopo is free and stays free. If it saves you time, you can sponsor its maintenance through
+[GitHub Sponsors](https://github.com/sponsors/faxlab). Sponsorship funds maintainer time and comes with no
+obligations either way.
+
 ## Licence
 
 Apache-2.0 (see [LICENSE](LICENSE)). Third-party components and their licence texts are listed in [NOTICE](NOTICE).

package/dist/cli.js

@@ -15,8 +15,10 @@
 //                 instance stream).
 //   With --frames, --render/--export paths may contain {frame} or {frame:04} (zero-padded);
 //   without a pattern a .0001-style frame number is inserted before the extension.
-//   node src/cli.ts --catalog | --help-node scatter
+//   node src/cli.ts --catalog | --help-node scatter | --version
 //   node src/cli.ts mcp [--workspace dir] [--viewer]   the MCP server (src/mcp/server.ts) over stdio
+//   node src/cli.ts view <graph.json> [--port 7341]      live 3D viewer in the browser, re-cooks on every save;
+//                                                         files dropped on the page go to inputs/ beside the graph file
 // Installed from npm the same commands are `topotopo …` (package.json bin → dist/cli.js, built by npm run build).
 import fs from 'node:fs';
 import path from 'node:path';
@@ -38,6 +40,12 @@ const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : un
 const fail = (msg) => { console.error(msg); process.exit(1); };
 // the command as the user typed it: the sources from a clone, or the package's bin (dist/cli.js)
 const prog = import.meta.url.endsWith('.ts') ? 'node src/cli.ts' : 'topotopo';
+if (argv.includes('-v') || argv.includes('-V') || argv.includes('--version')) {
+    // package.json sits one level above both src/cli.ts and dist/cli.js
+    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(`topotopo ${pkg.version}`);
+    process.exit(0);
+}
 if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
     console.log([
         `usage: ${prog} <graph.json> [--node n] [--frame N | --frames A-B[:step]] [--fps 24]`,
@@ -46,6 +54,9 @@ if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
         '                          [--glyphs N|up|orient|v] [--glyph-attrib a] [--labels groups,pieces,points,prims,attrib:name] [--legend] [--points]',
         '                          [--shading flat|matcap|ao] [--size 800] [--render-scale 2] [--azimuth 35] [--elevation 25] [--zoom 1] [--look-at x,y,z] [--ortho-scale w]',
         '                          [--textures] (base colour maps on meshes) [--texture name|image/layer|material] (adds the texture view)',
+        '                          [--max-triangles 600000] (packed instances drawn; above it an evenly spread subset)',
+        '         several renders per cook: repeat --render; options after a --render apply to it, options before the first apply to all',
+        '           e.g. --views top --render h.png --color-by height --render r.png --color-by river',
         '                          [--no-view-labels] (no view name labels or axis gizmo, e.g. for thumbnails)',
         '         export options: [--compress none|meshopt|draco] [--quantize] [--pcg | --pcg-struct] [--attributes P,N,pscale] [--up-axis y|z] [--scale 100]',
         '                         [--instancing packed|expand] (packed instances: glb/usda/geo keep them by default)',
@@ -54,21 +65,65 @@ if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
         '                       --format mask_png --layers a,b, --format unreal_landscape (a directory bundle; --tile-size 1008 for tiled Landscape);',
         '                       images: --format textures --export out/maps (one PNG per image; --layers a,b or * for extra layers)',
         '       with --frames, output paths may use {frame} or {frame:04}; otherwise out.0001.png style names are written',
-        `       ${prog} --catalog | --help-node <type>`,
+        `       ${prog} --catalog | --help-node <type> | --version`,
         `       ${prog} mcp [--workspace dir] [--viewer]   (the MCP server over stdio, for MCP clients)`,
+        `       ${prog} view <graph.json> [--port 7341]   (live 3D viewer in the browser; re-cooks when the file is saved; files dropped on the page go to inputs/ beside it)`,
     ].join('\n'));
     process.exit(0);
 }
-if (argv.includes('--catalog')) {
-    console.log(catalogText(allNodeDefs()));
+if (argv.includes('--catalog') || opt('--help-node')) {
+    // node types plus the shelf assets (house, stairs, …), which the engine registers when it starts
+    const engine = new Engine(createNodeHost({ baseDir: process.cwd() }));
+    await engine.init();
+    const defs = [...allNodeDefs(), ...[...engine.assets.values()].map((x) => x.def)];
+    if (argv.includes('--catalog'))
+        console.log(catalogText(defs));
+    else {
+        const d = defs.find((x) => x.type === opt('--help-node'));
+        console.log(d ? nodeDoc(d) : `unknown node "${opt('--help-node')}" (see --catalog)`);
+    }
     process.exit(0);
 }
-if (opt('--help-node')) {
-    const d = allNodeDefs().find((x) => x.type === opt('--help-node'));
-    console.log(d ? nodeDoc(d) : 'unknown node');
-    process.exit(0);
+if (argv[0] === 'view') {
+    // `topotopo view <graph.json> [--port 7341]`: cook the file, serve the live 3D viewer, re-cook on every save
+    const file = argv[1];
+    if (!file || file.startsWith('-'))
+        fail(`usage: ${prog} view <graph.json> [--port 7341]`);
+    if (!fs.existsSync(file))
+        fail(`${prog}: no such graph file "${file}"`);
+    const os = await import('node:os');
+    const { Workspace } = await import('./workspace.js');
+    const { startViewer } = await import('./viewer/server.js');
+    const dir = path.dirname(path.resolve(file));
+    const engine = new Engine(createNodeHost({ baseDir: dir }));
+    await engine.init();
+    // A scratch workspace holds the graph, assets and exports: the graph file stays the only source. Files dropped on the
+    // page go to inputs/ beside the graph file instead, made on the first drop: its file nodes read them as
+    // "inputs/<name>" (the path an MCP workspace uses too), and they outlive the viewer.
+    const ws = new Workspace(fs.mkdtempSync(path.join(os.tmpdir(), 'topotopo-view-')), engine, { inputs: path.join(dir, 'inputs') });
+    ws.load();
+    const name = path.basename(file).replace(/\.json$/i, '').replace(/[^A-Za-z0-9_-]/g, '_').replace(/^[^A-Za-z]/, 'g$&') || 'graph';
+    const load = async () => {
+        let spec;
+        try {
+            spec = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            console.error(`${file}: ${e.message} (keeping the last good version)`);
+            return;
+        }
+        ws.setGraph(name, spec);
+        const r = await ws.cook(name);
+        console.log(`${r.ok ? 'cooked' : 'FAILED'} ${name} in ${r.ms.toFixed(0)} ms${r.ok ? '' : ': ' + r.errors.map((e) => `${e.node}: ${e.message}`).join('; ')}`);
+        ws.bump(name);
+    };
+    await load();
+    const v = await startViewer(ws, opt('--port') !== undefined ? Number(opt('--port')) : undefined, { inputsWhere: `beside ${path.basename(file)}` });
+    console.log(`view: ${v.url}  (watching ${file}; files dropped on the page go to ${path.join(path.dirname(file), 'inputs') + path.sep}; Ctrl+C to stop)`);
+    let timer;
+    fs.watch(file, () => { clearTimeout(timer); timer = setTimeout(() => { load().catch((e) => console.error(String(e))); }, 150); });
 }
-if (argv[0] === 'mcp') {
+else if (argv[0] === 'mcp') {
     // `topotopo mcp [--workspace dir] [--viewer]`: the MCP server over stdio; src/mcp/server.ts reads the remaining
     // arguments from process.argv and runs until the client closes stdin
     process.argv.splice(2, 1);
@@ -105,7 +160,17 @@ async function cook() {
         return p.slice(0, p.length - ext.length) + '.' + frameText(frame, 4) + ext;
     }
     const file = argv[0];
-    const graph = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (file.startsWith('-'))
+        fail(`${prog}: unknown option "${file}" (the first argument is the graph file; see --help)`);
+    if (!fs.existsSync(file))
+        fail(`${prog}: no such graph file "${file}"`);
+    let graph;
+    try {
+        graph = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail(`${prog}: ${file} is not valid JSON: ${e.message}`);
+    }
     const engine = new Engine(createNodeHost({ baseDir: path.dirname(path.resolve(file)) }));
     await engine.init();
     const target = opt('--node');
@@ -124,18 +189,18 @@ async function cook() {
             console.error(`warning [${w.node}] ${w.message}`);
     }
     /** Render overlay flags → render tool arguments → RenderOptions (src/render/options.ts). */
-    function renderFlags() {
+    function renderFlags(get, has) {
         const a = {};
         for (const [f, k] of [['--wireframe', 'wireframe'], ['--hard-angle', 'hard_angle'], ['--section', 'section'], ['--clip', 'clip'], ['--glyphs', 'glyphs'],
             ['--glyph-attrib', 'glyph_attrib'], ['--glyph-scale', 'glyph_scale'], ['--max-glyphs', 'max_glyphs'], ['--labels', 'labels'], ['--max-labels', 'max_labels'],
             ['--shading', 'shading'], ['--ao-radius', 'ao_radius'], ['--size', 'size'], ['--render-scale', 'scale'], ['--azimuth', 'azimuth'], ['--elevation', 'elevation'],
-            ['--zoom', 'zoom'], ['--look-at', 'look_at'], ['--ortho-scale', 'ortho_scale'], ['--texture', 'texture']])
-            if (opt(f) !== undefined)
-                a[k] = opt(f);
+            ['--zoom', 'zoom'], ['--look-at', 'look_at'], ['--ortho-scale', 'ortho_scale'], ['--texture', 'texture'], ['--max-triangles', 'max_triangles']])
+            if (get(f) !== undefined)
+                a[k] = get(f);
         for (const [f, k] of [['--legend', 'legend'], ['--points', 'points'], ['--annotate', 'annotate'], ['--textures', 'textures']])
-            if (argv.includes(f))
+            if (has(f))
                 a[k] = true;
-        if (argv.includes('--no-view-labels'))
+        if (has('--no-view-labels'))
             a.view_labels = false;
         try {
             return renderArgs(a);
@@ -144,20 +209,30 @@ async function cook() {
             return fail(e.message);
         }
     }
+    // Several renders per run (one cook): every --render takes the render options that follow it, up to the next
+    // --render; options before the first --render apply to all of them. With one --render this is the old behaviour.
+    const renderAt = argv.flatMap((x, i) => (x === '--render' ? [i] : []));
+    const sharedArgs = argv.slice(0, renderAt.length ? renderAt[0] : argv.length);
+    const renders = renderAt.map((start, n) => {
+        const seg = argv.slice(start, n + 1 < renderAt.length ? renderAt[n + 1] : argv.length);
+        if (!seg[1] || seg[1].startsWith('--'))
+            fail('--render needs an output path (e.g. --render out.png)');
+        const from = (args, f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+        return { out: seg[1], get: (f) => from(seg, f) ?? from(sharedArgs, f), has: (f) => seg.includes(f) || sharedArgs.includes(f) };
+    });
     async function writeOutputs(r, frame) {
         const geo = r.geo;
-        const out = opt('--render');
         const at = (p) => (frame === undefined ? p : framePath(p, frame));
-        if (out) {
-            const ro = renderFlags();
-            const v = opt('--views');
+        for (const { out, get, has } of renders) {
+            const ro = renderFlags(get, has);
+            const v = get('--views');
             let views = v === undefined || v === 'quad' ? undefined : parseViews(v);
-            if (opt('--section') !== undefined)
+            if (get('--section') !== undefined)
                 views = !views && v === undefined ? ro.views : views && views.includes('section') ? views : [...(views ?? parseViews('quad')), 'section'];
-            if (opt('--texture') !== undefined)
+            if (get('--texture') !== undefined)
                 views = !views && v === undefined ? ro.views : views && views.includes('texture') ? views : [...(views ?? parseViews('quad')), 'texture'];
             const title = path.basename(file, '.json') + (r.frame !== 1 ? ` @ frame ${r.frame}` : '');
-            const img = renderGeometry(geo, { ...ro, views, colorBy: opt('--color-by') ?? null, checker: argv.includes('--checker'), title });
+            const img = renderGeometry(geo, { ...ro, views, colorBy: get('--color-by') ?? null, checker: has('--checker'), title });
             const p = at(out);
             fs.mkdirSync(path.dirname(path.resolve(p)), { recursive: true });
             fs.writeFileSync(p, encodePNG(img.rgba, img.width, img.height, (d) => zlib.deflateSync(d)));

package/dist/graph/engine.js

@@ -620,6 +620,8 @@ export class Engine {
                 for (const e of r.errors)
                     if (!e.startsWith('unknown param'))
                         v.errors.push({ node: name, message: e });
+                for (const w of r.warnings)
+                    v.warnings.push({ node: name, message: w });
                 for (const n of r.notes)
                     notes.push(`${name}: ${n}`);
                 if (r.deferred.length)
@@ -762,7 +764,7 @@ export class Engine {
             return { rp, refSig: '', usesTime: rp.usesTime, depsTimeDependent: false };
         }
         const fail = (error, upstream = false) => ({
-            rp: { values: {}, errors: [], notes: [], usesTime: false, deferred: [] }, refSig: '', usesTime: false, depsTimeDependent: false, error, upstream,
+            rp: { values: {}, errors: [], notes: [], warnings: [], usesTime: false, deferred: [] }, refSig: '', usesTime: false, depsTimeDependent: false, error, upstream,
         });
         const geo = new Map();
         const parts = [];
@@ -859,6 +861,7 @@ export class Engine {
             result.error = { node: name, message: rp.errors.join('; ') };
             return result;
         }
+        result.warnings.push(...rp.warnings); // values clamped to a param range: said every cook, cache hits included
         depTime ||= np.depsTimeDependent;
         if (spec.bypass) {
             result.geo = inputs[0] ?? new Geometry();

package/dist/graph/params.d.ts

@@ -34,11 +34,17 @@ export declare function vecOut<T extends any[]>(a: T): T;
 export declare function parseColor(v: any): [number, number, number] | null;
 export declare class ParamError extends Error {
 }
-export declare function coerce(name: string, pd: ParamDef, v: any): any;
+/**
+ * Coerce a raw value to the param's type. Numbers outside the declared min/max are clamped, and `note` (when given)
+ * is told, so a cook can warn: a silent clamp hides mistakes such as an asset range narrower than its caller's.
+ */
+export declare function coerce(name: string, pd: ParamDef, v: any, note?: (msg: string) => void): any;
 export interface ResolvedParams {
     values: Record<string, any>;
     errors: string[];
     notes: string[];
+    /** values changed on the way in (clamped to the param range); a cook reports them as node warnings */
+    warnings: string[];
     /** an expression read frame, time, fps or timeInc */
     usesTime: boolean;
     /** params whose value is only known at cook time (dry run with reference functions) */

package/dist/graph/params.js

@@ -192,8 +192,13 @@ function toNum(v) {
 }
 export class ParamError extends Error {
 }
-export function coerce(name, pd, v) {
+/**
+ * Coerce a raw value to the param's type. Numbers outside the declared min/max are clamped, and `note` (when given)
+ * is told, so a cook can warn: a silent clamp hides mistakes such as an asset range narrower than its caller's.
+ */
+export function coerce(name, pd, v, note) {
     const bad = (expect) => new ParamError(`param "${name}" expects ${expect}, got ${JSON.stringify(v)?.slice(0, 80)}`);
+    const range = () => `${pd.min ?? '…'}..${pd.max ?? '…'}`;
     switch (pd.type) {
         case 'float':
         case 'int': {
@@ -201,10 +206,14 @@ export function coerce(name, pd, v) {
             if (n === null)
                 throw bad(pd.type === 'int' ? 'an integer' : 'a number');
             let x = pd.type === 'int' ? Math.round(n) : n;
-            if (pd.min !== undefined && x < pd.min)
+            if (pd.min !== undefined && x < pd.min) {
+                note?.(`param "${name}" ${x} clamped to ${pd.min} (range ${range()})`);
                 x = pd.min;
-            if (pd.max !== undefined && x > pd.max)
+            }
+            if (pd.max !== undefined && x > pd.max) {
+                note?.(`param "${name}" ${x} clamped to ${pd.max} (range ${range()})`);
                 x = pd.max;
+            }
             return x;
         }
         case 'bool': {
@@ -278,10 +287,14 @@ export function coerce(name, pd, v) {
                 if (nn === null)
                     throw new ParamError(`param "${name}"[${i}] is not a number: ${JSON.stringify(x)}`);
                 let r = isInt ? Math.round(nn) : nn;
-                if (pd.min !== undefined && r < pd.min)
+                if (pd.min !== undefined && r < pd.min) {
+                    note?.(`param "${name}"[${i}] ${r} clamped to ${pd.min} (range ${range()})`);
                     r = pd.min;
-                if (pd.max !== undefined && r > pd.max)
+                }
+                if (pd.max !== undefined && r > pd.max) {
+                    note?.(`param "${name}"[${i}] ${r} clamped to ${pd.max} (range ${range()})`);
                     r = pd.max;
+                }
                 return r;
             });
         }
@@ -312,7 +325,7 @@ export function coerce(name, pd, v) {
 /** Validate names, evaluate expressions and coerce types. */
 export function resolveParams(def, raw, vars, env = {}) {
     const values = {};
-    const errors = [], notes = [], deferred = [];
+    const errors = [], notes = [], warnings = [], deferred = [];
     let usesTime = false;
     const ev = { ...env, onTime: () => { usesTime = true; env.onTime?.(); } };
     let scope;
@@ -351,7 +364,7 @@ export function resolveParams(def, raw, vars, env = {}) {
         try {
             if (pd.type !== 'code' && pd.type !== 'graph')
                 v = evalValue(v, getScope, `"${name}"`);
-            values[name] = v === undefined ? undefined : coerce(name, pd, v);
+            values[name] = v === undefined ? undefined : coerce(name, pd, v, (m) => warnings.push(m));
         }
         catch (e) {
             if (e instanceof DeferredExpr)
@@ -361,7 +374,7 @@ export function resolveParams(def, raw, vars, env = {}) {
             values[name] = pd.default;
         }
     }
-    return { values, errors, notes, usesTime, deferred };
+    return { values, errors, notes, warnings, usesTime, deferred };
 }
 /** Evaluate a ramp at t. Values may be numbers or arrays. */
 export function evalRamp(keys, t) {

package/dist/graph/types.d.ts

@@ -74,6 +74,7 @@ export interface NodeSpec {
     note?: string;
     ui?: any;
 }
+/** An exposed var: asset parameter docs and range, and the control the live viewer draws for it. */
 export interface VarDef {
     type?: string;
     default?: any;
@@ -81,6 +82,14 @@ export interface VarDef {
     min?: number;
     max?: number;
     options?: string[];
+    /** control label for humans (default: the var name) */
+    label?: string;
+    /** slider step (default: 1 for ints, else derived from the range) */
+    step?: number;
+}
+/** Free-form graph metadata (showcase render presets, editor layout, …). */
+export interface GraphMeta {
+    [key: string]: any;
 }
 export interface GraphSpec {
     /** graph format version (see GRAPH_VERSION); missing = 0, migrated on load */
@@ -88,10 +97,10 @@ export interface GraphSpec {
     nodes: Record<string, NodeSpec>;
     output?: string;
     vars?: Record<string, any>;
-    /** metadata for exposed vars when the graph is used as an asset */
+    /** metadata for exposed vars: asset parameters, and the controls the live viewer shows for them */
     params?: Record<string, VarDef>;
     description?: string;
-    meta?: any;
+    meta?: GraphMeta;
 }
 export interface CookContext {
     node: string;