topotopo 0.1.0 → 0.3.0

package/dist/io/textures.d.ts

@@ -7,8 +7,37 @@ import type { PngImage } from './png-decode.ts';
  * per channel). deflate compresses (Node: zlib.deflateSync); without it the PNG uses stored (uncompressed) blocks.
  */
 export declare function imagePNG(img: Image, layer?: string, deflate?: (d: Uint8Array) => Uint8Array): Uint8Array;
-/** An image volume from a decoded PNG: grey → 1 channel, grey+alpha / RGB / RGBA → RGBA; samples / maxValue. */
-export declare function imageFromPNG(png: PngImage, name: string): Image;
+/** How a PNG's channels become layers: see ImageFromPNGOptions. */
+export declare const PNG_LAYERS: readonly ['auto', 'grey', 'rgba'];
+export type PngLayers = (typeof PNG_LAYERS)[number];
+export interface ImageFromPNGOptions {
+    /**
+     * 'auto' (default): grey files (1 or 2 channels) give a grey layer C, colour files an RGBA one; 'grey': a grey C
+     * (Rec. 709 luminance of a colour file); 'rgba': an RGBA C (grey g as g, g, g). A grey C puts the file's alpha, when
+     * it has one, in the grey layer "A" (Houdini's alpha plane).
+     */
+    layers?: PngLayers;
+    /**
+     * true (default): the samples are display (sRGB-encoded) values, which colour layers hold too, so they are kept as
+     * they are; false: they are linear light, and grey and RGB are encoded to display values (alpha never is).
+     */
+    srgb?: boolean;
+}
+/** An image volume from a decoded PNG: values = samples / maxValue (16-bit files keep their precision). */
+export declare function imageFromPNG(png: PngImage, name: string, o?: ImageFromPNGOptions): Image;
+/** The image name a file gives: its name without folders and extension ("inputs/brick.png" → "brick"). */
+export declare function imageNameOf(path: string): string;
+/**
+ * An image volume from the bytes of the PNG file `path` (the image_file node and the file node's .png path), named
+ * `name` or after the file (imageNameOf). Errors name the file; images over MAX_PIXELS are refused before decoding.
+ */
+export declare function imageFromPNGFile(bytes: Uint8Array, path: string, o?: ImageFromPNGOptions & {
+    name?: string;
+}): Image;
+/** imageFromPNGFile on a file read through `readFile` (usually Host.readFile). */
+export declare function readImageFile(readFile: (path: string) => Promise<Uint8Array>, path: string, o?: ImageFromPNGOptions & {
+    name?: string;
+}): Promise<Image>;
 /** A file-name-safe version of an image name ("" → "image"). */
 export declare function safeFileName(name: string): string;
 /** The images a material table references ("image:<name>"), with the slots using each. */

package/dist/io/textures.js

@@ -1,7 +1,8 @@
-import { Image, channelsOf, imageRef, imageToBytes, opaque, referenceableImages } from '../core/image.js';
+import { Image, LUMA, MAX_PIXELS, channelsOf, imageRef, imageToBytes, opaque, referenceableImages } from '../core/image.js';
 import { TEXTURE_SLOTS, mergeMaterialTables } from '../core/materials.js';
 import { encodePNG } from '../render/png.js';
 import { encodeGreyPNG, zlibStored } from './heightmap.js';
+import { decodePNG } from './png-decode.js';
 import { baseOf, dirOf, joinPath } from './common.js';
 /**
  * PNG bytes of an image layer ("" = the main layer): 8-bit grey for 1-channel layers, RGBA for 4-channel ones (8 bits
@@ -13,32 +14,79 @@ export function imagePNG(img, layer = '', deflate) {
         return encodeGreyPNG(bytes, img.width, img.height, 8, deflate);
     return encodePNG(bytes, img.width, img.height, deflate ?? zlibStored);
 }
-/** An image volume from a decoded PNG: grey → 1 channel, grey+alpha / RGB / RGBA → RGBA; samples / maxValue. */
-export function imageFromPNG(png, name) {
-    const n = png.width * png.height, ch = png.channels, d = png.data, k = 1 / (png.maxValue || 255);
+/** How a PNG's channels become layers: see ImageFromPNGOptions. */
+export const PNG_LAYERS = ['auto', 'grey', 'rgba'];
+/** Display (sRGB-encoded) value of a linear one (io/gltf.ts converts back and forth for glTF's linear factors). */
+const toDisplay = (c) => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+/** An image volume from a decoded PNG: values = samples / maxValue (16-bit files keep their precision). */
+export function imageFromPNG(png, name, o = {}) {
+    const n = png.width * png.height, ch = png.channels, d = png.data, max = png.maxValue || 255, k = 1 / max;
+    // samples are integers 0..max: tables give every value once (alpha is never converted)
+    const lin = new Float32Array(max + 1);
+    for (let s = 0; s <= max; s++)
+        lin[s] = s * k;
+    const col = o.srgb === false ? Float32Array.from(lin, (_, s) => toDisplay(s * k)) : lin;
     const img = new Image(png.width, png.height, name);
-    if (ch === 1) {
-        const a = new Float32Array(n);
-        for (let i = 0; i < n; i++)
-            a[i] = d[i] * k;
-        return img.set('C', a);
+    const mode = o.layers ?? 'auto';
+    if (mode === 'grey' || (mode === 'auto' && ch <= 2)) {
+        const C = new Float32Array(n);
+        if (ch <= 2)
+            for (let i = 0; i < n; i++)
+                C[i] = col[d[i * ch]];
+        else
+            for (let i = 0; i < n; i++) {
+                const p = i * ch;
+                C[i] = col[d[p]] * LUMA[0] + col[d[p + 1]] * LUMA[1] + col[d[p + 2]] * LUMA[2];
+            }
+        img.set('C', C);
+        if (ch === 2 || ch === 4) {
+            const A = new Float32Array(n);
+            for (let i = 0; i < n; i++)
+                A[i] = lin[d[i * ch + ch - 1]];
+            img.set('A', A);
+        }
+        return img;
     }
     const a = new Float32Array(n * 4);
     for (let i = 0; i < n; i++) {
-        const o = i * ch;
-        if (ch === 2) {
-            a[i * 4] = a[i * 4 + 1] = a[i * 4 + 2] = d[o] * k;
-            a[i * 4 + 3] = d[o + 1] * k;
-        }
+        const p = i * ch, q = i * 4;
+        if (ch <= 2)
+            a[q] = a[q + 1] = a[q + 2] = col[d[p]];
         else {
-            a[i * 4] = d[o] * k;
-            a[i * 4 + 1] = d[o + 1] * k;
-            a[i * 4 + 2] = d[o + 2] * k;
-            a[i * 4 + 3] = ch === 4 ? d[o + 3] * k : 1;
+            a[q] = col[d[p]];
+            a[q + 1] = col[d[p + 1]];
+            a[q + 2] = col[d[p + 2]];
         }
+        a[q + 3] = ch === 2 || ch === 4 ? lin[d[p + ch - 1]] : 1;
     }
     return img.set('C', a);
 }
+/** The image name a file gives: its name without folders and extension ("inputs/brick.png" → "brick"). */
+export function imageNameOf(path) {
+    let p = String(path);
+    if (/^\w+:\/\//.test(p))
+        p = p.split(/[?#]/)[0];
+    return baseOf(p.replace(/[\\/]+$/, '')).replace(/\.[^.]*$/, '') || 'image';
+}
+/**
+ * An image volume from the bytes of the PNG file `path` (the image_file node and the file node's .png path), named
+ * `name` or after the file (imageNameOf). Errors name the file; images over MAX_PIXELS are refused before decoding.
+ */
+export function imageFromPNGFile(bytes, path, o = {}) {
+    let png;
+    try {
+        png = decodePNG(bytes, MAX_PIXELS);
+    }
+    catch (e) {
+        throw new Error(`"${path}" cannot be read as a PNG image: ${e?.message ?? e}`);
+    }
+    return imageFromPNG(png, o.name || imageNameOf(path), o);
+}
+/** imageFromPNGFile on a file read through `readFile` (usually Host.readFile). */
+export async function readImageFile(readFile, path, o = {}) {
+    const bytes = await readFile(path).catch((e) => { throw new Error(`cannot read "${path}": ${e?.message ?? e}`); });
+    return imageFromPNGFile(bytes, path, o);
+}
 /** A file-name-safe version of an image name ("" → "image"). */
 export function safeFileName(name) {
     return String(name).replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+/, '') || 'image';

package/dist/io/unreal.js

@@ -4,12 +4,14 @@
 //                            component count, scale, location for the New Landscape panel and for the actor), the
 //                            files below and the manual import steps
 //   heightmap.png / .json    16-bit heightmap and its sidecar (io/heightmap.ts; the manifest repeats its numbers)
-//   layers/<layer>.png       every other heightfield layer as an 8-bit weight map (0..1 layers as they are, other
+//   layers/<layer>.png       every other heightfield layer (or only `layers` when given) as an 8-bit weight map (0..1 layers as they are, other
 //                            ranges normalised, the range recorded in the manifest)
 //   objects.glb              the geometry's meshes and packed instances (EXT_mesh_gpu_instancing), when it has prims
 //   objects_expanded.glb     the same with the instances as real geometry (for importers without the extension;
 //                            written up to EXPANDED_TRIANGLE_LIMIT triangles)
-//   instances.csv            the instance stream as Unreal PCG rows (one row per packed instance, Mesh column)
+//   objects_static.glb       only the ordinary (non-instanced) meshes, at any instance count: what the Unreal plugin
+//                            places as level geometry next to the instance stream (buildings, roads)
+//   instances.csv           the instance stream as Unreal PCG rows (one row per packed instance, Mesh column)
 //   instances.meshes.json    Mesh → meshes/<Mesh>.glb, one GLB per packed source (metres, Y-up, at the origin)
 //   tiles/<x>_<y>/          opt-in tile_size (quads): overlapping heightmaps, weight layers and instance CSVs;
 //                            version 2 adds tiles and tile_grid; root source files and shared meshes are retained
@@ -25,7 +27,7 @@ import { encodeGreyPNG, heightmapExport } from './heightmap.js';
 import { exportGLB } from './gltf.js';
 import { exportCSV, instanceMeshesJSON } from './points.js';
 import { safeName } from './common.js';
-import { expandedTriangles, flattenSource } from '../core/packed.js';
+import { expandedTriangles, flattenSource, stripPacked } from '../core/packed.js';
 import { packedPrims, packedSourceNames } from './common.js';
 /** objects_expanded.glb is written while the expanded instances stay below this many triangles. */
 export const EXPANDED_TRIANGLE_LIMIT = 2_000_000;
@@ -100,9 +102,15 @@ export async function unrealLandscapeBundle(g, o = {}) {
     const layers = [];
     const usedNames = new Set();
     const weightBytes = new Map();
+    if (o.layers)
+        for (const want of o.layers)
+            if (!hf.layers.has(want))
+                throw new Error(`export unreal_landscape: layer "${want}" not found (layers: ${[...hf.layers.keys()].join(', ')})`);
     for (const [name, a] of hf.layers) {
         if (name === heightLayer)
             continue;
+        if (o.layers && !o.layers.includes(name))
+            continue; // --layers a,b: only these weight maps
         const st = layerStats(a);
         if (!st)
             continue;
@@ -127,8 +135,9 @@ export async function unrealLandscapeBundle(g, o = {}) {
         });
     }
     // meshes and instances of the same geometry
-    let objects = null, expanded = null, instances = null;
-    const glbOpts = { materials: o.materials, readFile: o.readFile, warn: o.warn, custom: o.custom };
+    let objects = null, expanded = null, statics = null, instances = null;
+    // Unreal's default glTF materials ignore vertex colours: the material colour must be the factor
+    const glbOpts = { materials: o.materials, readFile: o.readFile, warn: o.warn, custom: o.custom, materialColorWins: true };
     if (g.numPrims > 0) {
         files.push({ path: 'objects.glb', bytes: await exportGLB(g, glbOpts) });
         objects = 'objects.glb';
@@ -136,6 +145,13 @@ export async function unrealLandscapeBundle(g, o = {}) {
             files.push({ path: 'objects_expanded.glb', bytes: await exportGLB(g, { ...glbOpts, instancing: 'expand' }) });
             expanded = 'objects_expanded.glb';
         }
+        // the ordinary meshes alone (buildings, roads): small at any instance count, so an importer can place them as
+        // level geometry next to the instance stream even when objects_expanded.glb is skipped for size
+        const plain = stripPacked(g);
+        if (plain.numPrims > 0) {
+            files.push({ path: 'objects_static.glb', bytes: await exportGLB(plain, glbOpts) });
+            statics = 'objects_static.glb';
+        }
     }
     if (g.hasPacked()) {
         files.push({ path: 'instances.csv', bytes: new TextEncoder().encode(exportCSV(g, { pcg: true, scale: 100, warn: (m) => { if (!/other point/.test(m))
@@ -171,6 +187,7 @@ export async function unrealLandscapeBundle(g, o = {}) {
         layers,
         objects,
         objects_expanded: expanded,
+        objects_static: statics,
         instances,
         manual_import: LANDSCAPE_IMPORT_STEPS,
     };

package/dist/mcp/docs.d.ts

@@ -1,5 +1,12 @@
-import type { NodeDef } from '../graph/types.ts';
-export declare const INSTRUCTIONS = "TopoTopo: a procedural geometry engine (Houdini-SOP style) you drive with JSON node graphs.\n\nWORKFLOW\n1. catalog \u2192 see node types (100+, Houdini names work as aliases: copytopoints, attribwrangle, polyextrude, mountain\u2026).\n2. help {nodes:[...]} for exact params before using unfamiliar nodes; help {topic:\"wrangle\"|\"graph\"|\"recipes\"\u2026} for concepts.\n3. build {graph} the WHOLE network in one call (dry_run:true validates without cooking). Every response reports errors per node with did-you-mean hints.\n4. render to SEE it (quad view: persp/front/right/top; backfaces are tinted blue = flipped normals; views \"quad_uv\" + checker:true for UVs; overlays for specific questions: wireframe \"hard\"/\"boundary\", views \"section\", glyphs \"N\", label_groups, shading \"matcap\", see help topic \"render\"). inspect for numbers (bbox, attributes, watertightness).\n5. edit {ops} for incremental changes (set params, insert nodes, rewire) \u2014 only downstream nodes re-cook.\n6. export to glb/gltf (materials, textures, meshopt), geo (Houdini), csv (Unreal PCG points / instance rows), points.json, usda, obj/ply/stl/json for Unreal, Blender, Houdini; unreal_landscape = a whole terrain scene for Unreal.\n7. verify: assert nodes guard invariants in the graph (watertight, counts, bbox, expr); explain {graph} reads a result in words; diff {a, b} shows what an edit changed. See help topic \"verify\".\nINSTANCING: copy_to_points {pack:true} / pack make packed instances (millions stay cheap; glb, usda and geo export them as instances, csv/points.json as one row per instance). See help topic \"instancing\".\nPCG: mask \u2192 scatter {density_mask} \u2192 orient \u2192 prune \u2192 copy_to_points {pack, variants, variant_weights}; points_along_curve, cluster, attribute_from_map. See help topic \"pcg\".\nCURVES: bezier / nurbs make spline prims (CVs + order, exact everywhere); convert_curve, resample, fillet_curve, offset_curve_3d, project_curve (roads on terrain), spline_fit, curve_attribs (curveu, frames, ramps). See help topic \"curves\".\nCLOTH: drape {steps} simulates a mesh as cloth over a collider (input 1) and the floor, from pins (pin_group / input 2) and in wind; inflate {pressure} puffs a closed mesh into a cushion or balloon. See help topic \"cloth\".\n\nCONVENTIONS: Y-up, metres, angles in degrees (wrangle trig uses radians). Houdini attribute names (P N Cd uv pscale orient up scale width name class piece). Polygons are closed prims, polylines are open prims.\nGRAPH: {\"nodes\": {\"name\": {\"type\": \"...\", \"in\": [\"upstream\", ...], \"params\": {...}}}, \"output\": \"name\", \"vars\": {\"k\": 1}}. Params accept \"=expr\" using vars (e.g. \"=height*0.5\"), time (frame, time) and other nodes (npoints('pts'), bbox('base').size.y, ch('box1/size')).\nTIME: build/edit/render/inspect/export take \"frame\" (default 1). solver = per-frame feedback (growth, accumulation). See help topic \"time\".\nPARTICLES: particles(emitter points, collision mesh, field) = Houdini POPs in one node: emission, gravity/drag/wind, curl noise, fields, floor and mesh collisions, trails as polylines; steps with the frame. See help topic \"particles\".\nESCAPE HATCHES: wrangle (per-element JS with @P/@Cd syntax), script (whole-geometry JS with the engine library), sdf_expr (signed distance functions). If a node is missing, write it with these.\nTERRAIN: heightfield \u2192 heightfield_noise \u2192 heightfield_erode \u2192 masks / heightfield_path \u2192 heightfield_scatter + copy_to_points, heightfield_to_mesh; export png16 for an Unreal Landscape, or unreal_landscape for the landscape + layers + instances bundle. See help topic \"heightfield\".\nPHYSICS: rbd_settle drops pieces (packed instances) onto a terrain/container/ground until they rest, so scattered rocks and props sit in contact; rbd_stack drops them one at a time into piles. See help topic \"rbd\".";
+import type { GraphSpec, NodeDef } from '../graph/types.ts';
+export declare const INSTRUCTIONS = "TopoTopo: a procedural geometry engine (Houdini-SOP style) you drive with JSON node graphs.\n\nWORKFLOW\n0. inputs {action:\"list\"} \u2192 the person's own files in the workspace inputs/ folder (guide curves, sites, zones, blockouts, PNG masks). Building a landscape or scene: look there first and build on them (help topic \"inputs\").\n1. catalog \u2192 see node types (100+, Houdini names work as aliases: copytopoints, attribwrangle, polyextrude, mountain\u2026).\n2. help {nodes:[...]} for exact params before using unfamiliar nodes; help {topic:\"wrangle\"|\"graph\"|\"recipes\"\u2026} for concepts.\n3. build {graph} the WHOLE network in one call (dry_run:true validates without cooking). Every response reports errors per node with did-you-mean hints.\n4. render to SEE it (quad view: persp/front/right/top; backfaces are tinted blue = flipped normals; views \"quad_uv\" + checker:true for UVs; overlays for specific questions: wireframe \"hard\"/\"boundary\", views \"section\", glyphs \"N\", label_groups, shading \"matcap\", see help topic \"render\"). inspect for numbers (bbox, attributes, watertightness).\n5. edit {ops} for incremental changes (set params, insert nodes, rewire) \u2014 only downstream nodes re-cook.\n6. export to glb/gltf (materials, textures, meshopt), geo (Houdini), csv (Unreal PCG points / instance rows), points.json, usda, obj/ply/stl/json for Unreal, Blender, Houdini; unreal_landscape = a whole terrain scene for Unreal.\n7. verify: assert nodes guard invariants in the graph (watertight, counts, bbox, expr); explain {graph} reads a result in words; diff {a, b} shows what an edit changed. See help topic \"verify\".\nOUTPUTS: publish intended deliverables in graph.outputs: {\"rotor\":{\"node\":\"rotor_final\",\"label\":\"Rotor\"}}. The default graph.output stays unchanged. The viewer lists every graph and named result, its generated textures and image layers; clicking a result isolates it. Rendered images and exports are saved and visible too. Use descriptive names; keep intermediate work in the node outliner. Rename/remove edits maintain published references.\nINSTANCING: copy_to_points {pack:true} / pack make packed instances (millions stay cheap; glb, usda and geo export them as instances, csv/points.json as one row per instance). See help topic \"instancing\".\nPCG: mask \u2192 scatter {density_mask} \u2192 orient \u2192 prune \u2192 copy_to_points {pack, variants, variant_weights}; points_along_curve, cluster, attribute_from_map. See help topic \"pcg\".\nCURVES: bezier / nurbs make spline prims (CVs + order, exact everywhere); convert_curve, resample, fillet_curve, offset_curve_3d, project_curve (roads on terrain), spline_fit, curve_attribs (curveu, frames, ramps). See help topic \"curves\".\nCLOTH: drape {steps} simulates a mesh as cloth over a collider (input 1) and the floor, from pins (pin_group / input 2) and in wind; inflate {pressure} puffs a closed mesh into a cushion or balloon. See help topic \"cloth\".\n\nCONVENTIONS: Y-up, metres, angles in degrees (wrangle trig uses radians). Houdini attribute names (P N Cd uv pscale orient up scale width name class piece). Polygons are closed prims, polylines are open prims.\nGRAPH: {\"nodes\": {\"name\": {\"type\": \"...\", \"in\": [\"upstream\", ...], \"params\": {...}}}, \"output\": \"name\", \"vars\": {\"k\": 1}}. Params accept \"=expr\" using vars (e.g. \"=height*0.5\"), time (frame, time) and other nodes (npoints('pts'), bbox('base').size.y, ch('box1/size')).\nHUMANS TUNE VARS: declare \"params\" for the 3\u20138 vars a person would tune ({\"k\": {type, desc, min, max, options, label, step}}); the live viewer (preview) shows them as sliders and menus. People change vars at any time, so read the graph (graphs {action:\"get\"}) before assuming a var's value. See help topic \"graph\".\nTIME: build/edit/render/inspect/export take \"frame\" (default 1). solver = per-frame feedback (growth, accumulation). See help topic \"time\".\nPARTICLES: particles(emitter points, collision mesh, field) = Houdini POPs in one node: emission, gravity/drag/wind, curl noise, fields, floor and mesh collisions, trails as polylines; steps with the frame. See help topic \"particles\".\nESCAPE HATCHES: wrangle (per-element JS with @P/@Cd syntax), script (whole-geometry JS with the engine library), sdf_expr (signed distance functions). If a node is missing, write it with these.\nTERRAIN: heightfield \u2192 heightfield_noise \u2192 heightfield_erode \u2192 masks / heightfield_path \u2192 heightfield_scatter + copy_to_points, heightfield_to_mesh; export png16 for an Unreal Landscape, or unreal_landscape for the landscape + layers + instances bundle. See help topic \"heightfield\".\nPHYSICS: rbd_settle drops pieces (packed instances) onto a terrain/container/ground until they rest, so scattered rocks and props sit in contact; rbd_stack drops them one at a time into piles. See help topic \"rbd\".";
+/**
+ * The complete example of help topic "inputs": guides.glb's path.* curves cut roads into a heightfield and its zone.*
+ * areas mask a tree scatter; the vars a person tunes are exposed as params. test/mcp.ts cooks it on a real guides.glb.
+ */
+export declare const INPUTS_EXAMPLE: GraphSpec;
+/** A graph as JSON with one node (and one param) per line: readable in a topic page, and JSON.parse gives it back. */
+export declare function graphLines(g: GraphSpec): string;
 export declare const TOPICS: Record<string, string>;
 export declare function topicList(): string[];
 export declare function nodeDoc(def: NodeDef): string;

package/dist/mcp/docs.js

@@ -2,6 +2,7 @@ import { CATEGORY_ORDER } from '../graph/registry.js';
 export const INSTRUCTIONS = `TopoTopo: a procedural geometry engine (Houdini-SOP style) you drive with JSON node graphs.
 
 WORKFLOW
+0. inputs {action:"list"} → the person's own files in the workspace inputs/ folder (guide curves, sites, zones, blockouts, PNG masks). Building a landscape or scene: look there first and build on them (help topic "inputs").
 1. catalog → see node types (100+, Houdini names work as aliases: copytopoints, attribwrangle, polyextrude, mountain…).
 2. help {nodes:[...]} for exact params before using unfamiliar nodes; help {topic:"wrangle"|"graph"|"recipes"…} for concepts.
 3. build {graph} the WHOLE network in one call (dry_run:true validates without cooking). Every response reports errors per node with did-you-mean hints.
@@ -9,6 +10,7 @@ WORKFLOW
 5. edit {ops} for incremental changes (set params, insert nodes, rewire) — only downstream nodes re-cook.
 6. export to glb/gltf (materials, textures, meshopt), geo (Houdini), csv (Unreal PCG points / instance rows), points.json, usda, obj/ply/stl/json for Unreal, Blender, Houdini; unreal_landscape = a whole terrain scene for Unreal.
 7. verify: assert nodes guard invariants in the graph (watertight, counts, bbox, expr); explain {graph} reads a result in words; diff {a, b} shows what an edit changed. See help topic "verify".
+OUTPUTS: publish intended deliverables in graph.outputs: {"rotor":{"node":"rotor_final","label":"Rotor"}}. The default graph.output stays unchanged. The viewer lists every graph and named result, its generated textures and image layers; clicking a result isolates it. Rendered images and exports are saved and visible too. Use descriptive names; keep intermediate work in the node outliner. Rename/remove edits maintain published references.
 INSTANCING: copy_to_points {pack:true} / pack make packed instances (millions stay cheap; glb, usda and geo export them as instances, csv/points.json as one row per instance). See help topic "instancing".
 PCG: mask → scatter {density_mask} → orient → prune → copy_to_points {pack, variants, variant_weights}; points_along_curve, cluster, attribute_from_map. See help topic "pcg".
 CURVES: bezier / nurbs make spline prims (CVs + order, exact everywhere); convert_curve, resample, fillet_curve, offset_curve_3d, project_curve (roads on terrain), spline_fit, curve_attribs (curveu, frames, ramps). See help topic "curves".
@@ -16,31 +18,144 @@ CLOTH: drape {steps} simulates a mesh as cloth over a collider (input 1) and the
 
 CONVENTIONS: Y-up, metres, angles in degrees (wrangle trig uses radians). Houdini attribute names (P N Cd uv pscale orient up scale width name class piece). Polygons are closed prims, polylines are open prims.
 GRAPH: {"nodes": {"name": {"type": "...", "in": ["upstream", ...], "params": {...}}}, "output": "name", "vars": {"k": 1}}. Params accept "=expr" using vars (e.g. "=height*0.5"), time (frame, time) and other nodes (npoints('pts'), bbox('base').size.y, ch('box1/size')).
+HUMANS TUNE VARS: declare "params" for the 3–8 vars a person would tune ({"k": {type, desc, min, max, options, label, step}}); the live viewer (preview) shows them as sliders and menus. People change vars at any time, so read the graph (graphs {action:"get"}) before assuming a var's value. See help topic "graph".
 TIME: build/edit/render/inspect/export take "frame" (default 1). solver = per-frame feedback (growth, accumulation). See help topic "time".
 PARTICLES: particles(emitter points, collision mesh, field) = Houdini POPs in one node: emission, gravity/drag/wind, curl noise, fields, floor and mesh collisions, trails as polylines; steps with the frame. See help topic "particles".
 ESCAPE HATCHES: wrangle (per-element JS with @P/@Cd syntax), script (whole-geometry JS with the engine library), sdf_expr (signed distance functions). If a node is missing, write it with these.
 TERRAIN: heightfield → heightfield_noise → heightfield_erode → masks / heightfield_path → heightfield_scatter + copy_to_points, heightfield_to_mesh; export png16 for an Unreal Landscape, or unreal_landscape for the landscape + layers + instances bundle. See help topic "heightfield".
 PHYSICS: rbd_settle drops pieces (packed instances) onto a terrain/container/ground until they rest, so scattered rocks and props sit in contact; rbd_stack drops them one at a time into piles. See help topic "rbd".`;
+/**
+ * The complete example of help topic "inputs": guides.glb's path.* curves cut roads into a heightfield and its zone.*
+ * areas mask a tree scatter; the vars a person tunes are exposed as params. test/mcp.ts cooks it on a real guides.glb.
+ */
+export const INPUTS_EXAMPLE = {
+    nodes: {
+        guides: { type: 'file', params: { path: 'inputs/guides.glb' } },
+        roles: { type: 'wrangle', in: ['guides'], params: { run_over: 'prims', code: "s@role = s@role || @name.split('.')[0].toLowerCase();" } },
+        paths: { type: 'delete', in: ['roles'], params: { group: '@role=path', keep: true } },
+        zones: { type: 'delete', in: ['roles'], params: { group: '@role=zone', keep: true } },
+        areas: { type: 'ends', in: ['zones'], params: { mode: 'close' } },
+        ground: { type: 'heightfield', params: { size: '=extent', resolution: 1 } },
+        hills: { type: 'heightfield_noise', in: ['ground'], params: { amplitude: '=relief', element_size: 60 } },
+        road: { type: 'heightfield_path', in: ['hills', 'paths'], params: { width: '=road_width' } },
+        zone_mask: { type: 'heightfield_mask_by_object', in: ['road', 'areas'], params: { by: 'footprint', distance: 0, falloff: 3 } },
+        off_road: { type: 'heightfield_layer', in: ['zone_mask'], params: { layer: 'mask', expression: 'mask * (1 - path)' } },
+        spots: { type: 'heightfield_scatter', in: ['off_road'], params: { density: '=tree_density', align: 'upright', seed: 3 } },
+        tree: { type: 'tree_lowpoly', params: { height: 7 } },
+        trees: { type: 'copy_to_points', in: ['tree', 'spots'], params: { pack: true } },
+        land: { type: 'heightfield_to_mesh', in: ['off_road'], params: { color: 'terrain' } },
+        out: { type: 'merge', in: ['land', 'trees'] },
+    },
+    output: 'out',
+    vars: { extent: 200, relief: 6, road_width: 5, tree_density: 0.02 },
+    params: {
+        relief: { type: 'float', min: 0, max: 30, step: 0.5, label: 'Hill height (m)', desc: 'terrain relief in metres' },
+        road_width: { type: 'float', min: 2, max: 12, label: 'Road width (m)', desc: 'flat width of the roads drawn as path.*' },
+        tree_density: { type: 'float', min: 0, max: 0.1, step: 0.005, label: 'Trees per m²', desc: 'tree density inside the zone.* areas' },
+    },
+};
+/** A graph as JSON with one node (and one param) per line: readable in a topic page, and JSON.parse gives it back. */
+export function graphLines(g) {
+    const rows = (o) => Object.entries(o).map(([k, v]) => `   ${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(',\n');
+    const parts = Object.entries(g).map(([k, v]) => (k === 'nodes' || k === 'params') && v && typeof v === 'object' ? `${JSON.stringify(k)}: {\n${rows(v)}\n }` : `${JSON.stringify(k)}: ${JSON.stringify(v)}`);
+    return `{${parts.join(',\n ')}}`;
+}
 export const TOPICS = {
     graph: `GRAPH FORMAT
 {
   "nodes": {
     "ground": {"type": "grid", "params": {"size": [10, 10], "divisions": [20, 20]}},
-    "pts":    {"type": "scatter", "in": ["ground"], "params": {"count": 200, "seed": 1}},
+    "pts":    {"type": "scatter", "in": ["ground"], "params": {"count": "=rock_count", "seed": 1}},
     "rock":   {"type": "sphere", "params": {"type": "ico", "level": 2, "radius": 0.2}},
     "rocks":  {"type": "copy_to_points", "in": ["rock", "pts"]},
     "out":    {"type": "merge", "in": ["ground", "rocks"]}
   },
   "output": "out",
-  "vars": {"density": 200}
+  "vars": {"rock_count": 200},
+  "params": {"rock_count": {"type": "int", "min": 0, "max": 2000, "label": "Rocks", "desc": "number of rocks"}}
 }
+- "vars": graph constants that "=expr" params read. "params": one entry per var a person would tune (3–8 of them):
+  {type (float int bool string enum), desc, min, max, options (enum), label (control name), step (slider step)}.
+  The live viewer (preview) renders them as controls: sliders for numbers with a range, menus for options, checkboxes
+  for bools. They are also the parameters when the graph is saved as an asset.
+- People change vars at any time (the viewer's controls edit the stored graph): read it with graphs {action:"get"}
+  before assuming a var's value, and edit {op:"vars"} rather than rebuilding to change one. When a person asks to
+  keep a value, keep it.
 - "in": ordered input list (null = unconnected), a single name, or {"inputName": node} (names from help).
 - Output node: "output", else a node named out/OUT, else the last unconnected node.
+- Optional "outputs": {"rotor":{"node":"rotor_final","label":"Rotor"}} publishes additional deliverables beside
+  the default. Publish complete assets and useful separate parts; the viewer isolates each on click and lists
+  its textures/layers. Rename/remove edits maintain references. The latest render of each graph node is saved as
+  exports/renders/<graph>-<node>.png (each render overwrites it) unless save_to is supplied; explicit render/export
+  destinations are registered in the viewer too.
+- Optional "export" (on the graph for the default output, or on an entry of "outputs") is where that output
+  exports: a format ("glb" → exports/<graph or output id>.glb) or {"format":"obj","path":"parts/a.obj","up_axis":"z"}
+  (the export tool's options), always inside exports/. The person's Export buttons in the viewer, export {output} /
+  export {all:true} and the CLI's --export-all write these targets; set one with edit {op:"export", output?, export}.
 - Node names: letters, digits, _ . -  Node types & params are case/underscore-insensitive and accept Houdini-style aliases.
 - "bypass": true passes input 0 through. "note": free text. "ui": {x,y} reserved for the future GUI.
 - Vectors: a single number broadcasts ("size": 2 → [2,2,2]). Colours accept [r,g,b], "#ff8800" or names.
 - build mode "merge" upserts nodes into the existing graph; edit ops: set, add, remove (auto-rewires), connect, rename, output, vars, bypass, replace, insert (after a node, rewiring its consumers).
 - Several graphs can coexist (name param); graph_ref composes them. Graphs persist as JSON in the workspace.`,
+    inputs: `HUMAN INPUT (guides, blockouts and masks in the workspace inputs/ folder)
+People feed in their own material by dropping files into <workspace>/inputs/ (or onto the live viewer, or with its Add
+input button): meshes, guide curves and points drawn in Blender, Houdini or Unreal, placeholder blockouts, PNG masks and
+heightmaps. Every tool answer ends with a note when inputs/ has files new or changed since your last call. Before building a
+landscape or scene, call inputs {action:"list"}; inputs {action:"describe", path} tells what one holds (polygons, open
+polylines, loose points, packed prims; bbox in metres; attributes; every name and role value; materials). Read a file
+with a file node, the path relative to the workspace: {"type":"file","params":{"path":"inputs/guides.glb"}}.
+MARKERS: what a person places by clicking in the live viewer (Site / Path / Zone / Volume modes) is written as
+  inputs/markers.json with the same name and role attributes (sites: points with pscale and orient; paths open and
+  zones closed polylines; volumes closed boxes), so describe it and read it like any other input.
+FORMATS: glb/gltf (+Y up already; object names → prim "name", materials → "material"), obj/stl/ply (no up axis:
+  Unreal exports and Blender exports with Up = Z are Z-up, so add "up_axis":"z"), geo/bgeo (Houdini), csv and
+  points.json (one point per row; columns such as name, role, pscale become point attributes), blend (needs Blender
+  installed; it converts the file headlessly). Images: png (8/16-bit grey or colour).
+CONVENTIONS: only Houdini attributes and groups, all optional, no add-on to install.
+  name  string: the object name (the glTF importer writes it on prims; csv/points.json name columns land on points)
+  role  string on points or prims: what a guide means: site, path, zone, volume, blockout (below)
+  People mark roles with a name prefix on their objects: site.well, path.river, zone.park, volume.no_trees,
+  blockout.house (Blender's .001 suffixes do no harm), or with a custom property "role" on the object (it arrives as an
+  attribute once the importer keeps glTF extras).
+  Derive role from the prefix, keeping a role the file brought (run_over "points" for point guides):
+    {"type":"wrangle","in":["guides"],"params":{"run_over":"prims","code":"s@role = s@role || @name.split('.')[0].toLowerCase();"}}
+  Select with group patterns: "@role=path", or straight by name prefix "@name=path.*" (a glob; space-separated tokens
+  are a union: "@name=path.* @name=zone.*"), e.g. {"type":"delete","in":["guides"],"params":{"group":"@name=path.*","keep":true}}.
+ROLES AND RECIPES
+  site      a point marks a location (a well, a lone tree, a house spot); pscale = radius in metres, orient or N = heading.
+            copy_to_points(asset, sites) {pack:true} puts a copy on every site (scaled by pscale, turned by orient/N);
+            foreach {mode:"points"} builds one per site ("=attr.pscale", "=attr.name" in the body). A site drawn as a
+            small mesh: pack {by:"name", pivot:"bbox_center_bottom"} gives one anchor point per object.
+  path      an open polyline: road, river, wall, fence line. project_curve(paths, terrain mesh) {spacing:1} drapes it on
+            a mesh; heightfield_path(terrain, paths) {width, shoulder} cuts a road into a heightfield (layer "path");
+            points_along_curve {spacing, side_offset, both_sides} for posts, lamps or trees along it; sweep
+            {shape:"ribbon", radius} for a road surface or a wall; heightfield_mask_by_object {by:"distance"} for a river bed.
+  zone      a closed polyline or a filled polygon is an area: a park, a field, a no-build zone. Loops drawn as edges
+            arrive as polylines ending on their first point: ends {mode:"close"} makes them polygons.
+            On a heightfield, heightfield_mask_by_object(terrain, zones) {by:"footprint", falloff} rasterises the polygons
+            into the mask layer (mode add / max / subtract / multiply combines several): heightfield_scatter reads it, and
+            heightfield_noise, heightfield_remap, heightfield_blur, heightfield_terrace and heightfield_layer blend their
+            effect by it (mask_layer:"mask").
+            Points inside a zone (top view), as point group in_zone:
+            {"type":"wrangle","in":["pts","zones"],"params":{"run_over":"points","code":"@group_in_zone = intersect(1, [@P.x, 1e6, @P.z], [0, -1, 0]).prim >= 0 ? 1 : 0;"}}
+            then delete {group:"in_zone"} or {group:"in_zone", keep:true}.
+  volume    a closed mesh or box: a region where scatter thins out or thickens. prune(pts, volumes) {mode:"near_geometry",
+            distance:0} removes the points inside; mask(ground mesh, volumes) {by:"inside", falloff} → scatter
+            {density_mask:"mask"} scatters there (invert:true for a hole); group {class:"point", pattern:"@mask>0.5"} groups
+            them. Let volumes reach below the ground. On a heightfield use heightfield_mask_by_object {by:"footprint"}.
+  blockout  a placeholder mesh to replace: bound {per_piece:true} gives each piece's box; foreach {mode:"pieces",
+            piece_attrib:"name"} runs a body per object, where a shelf asset takes its size from the piece
+            ("width": "=bbox('piece').size.x", piece = the body's input node) and match_size(asset, piece) moves it in
+            place. A footprint polygon feeds the house asset directly (its input 0).
+IMAGES: PNG masks and heightmaps. heightfield_from_image {path:"inputs/height.png", size:[x, z], height_min, height_max}
+  makes a terrain (16-bit greys keep the detail); with a heightfield connected it writes into layer (e.g. "mask",
+  height_min 0, height_max 1). attribute_from_map {path, projection:"xz", size, center, name:"mask"} samples it onto
+  points (scatter density_mask, prune {mode:"density"}). Textures: image_file {path:"inputs/albedo.png"} (or a file
+  node) loads it as an image named "albedo" for the texture nodes and texture_to_material {base_color:"albedo"}.
+EXAMPLE: inputs/guides.glb holds path.* curves and zone.* areas: roads cut into hills, trees in the zones off the road,
+the vars a person would tune exposed as params:
+${graphLines(INPUTS_EXAMPLE)}
+Afterwards render it, and tell the person which of their guides you used for what.`,
     expressions: `PARAM EXPRESSIONS
 Any non-code param can be a string starting with "=": a JS expression evaluated with graph vars.
   "vars": {"floors": 6, "h": 3}   →   "height": "=floors*h",  "count": "=floors*4"
@@ -243,6 +358,9 @@ WORKFLOW
   → heightfield_erode {iterations: 60} (gullies and sediment fans; writes flow, sediment, debris, water)
   → heightfield_path (road along a curve, writes "path") · heightfield_project (stamp meshes/curves: plateaus, ridges)
   → heightfield_mask_by_feature (slope/height/curvature/direction/flow/occlusion) → heightfield_scatter → copy_to_points
+    (heightfield_scatter {align: "upright"} for trees and buildings, {align: "slope"} for rocks that follow the ground;
+    without align, copy_to_points aims each copy's +Z along N, which lays Y-up models down;
+    {min_distance: 12} for lots that never overlap; heightfield_project {level: "mean"} levels the pads under them)
   → heightfield_to_mesh {color: "terrain"} for polygons (layers become point attributes), or export png16.
   Other sources: heightfield_from_mesh (project polygons along Y), heightfield_from_image (8/16-bit PNG).
   Layer tools: heightfield_layer (expression over layers "height * mask + 2", or copy/rename/delete/fill), remap, blur,
@@ -300,6 +418,10 @@ GENERATORS (no input, resolution [w, h], name): tex_noise (perlin/simplex/value/
   hex, dots, grid; gap = mortar, bevel, variation; layer "id" = random per cell) · tex_cells (Voronoi distance / edges /
   id / crackle) · tex_gradient · tex_shape (disc, square, polygon, star, ring; falloff; tile) · tex_splatter (blobs) ·
   tex_scratches (strokes) · tex_text.
+FILES: image_file {path:"inputs/brick.png"} loads a PNG (8/16-bit, grey or colour; the file node reads .png the same way)
+  as an image named after the file ("brick"; name sets another); layers auto/grey/rgba; srgb (default on) keeps the stored
+  values, which suits colour and data maps alike (off only for linear-light colour). Input 0 = a geometry to add it to,
+  so image_file nodes chain. People drop their own textures and masks into inputs/.
 FILTERS (input 0 = an image; image/layer pick what to process, the result replaces that layer; name renames; every
   other image and the mesh pass through): tex_blend (normal, add, subtract, multiply, screen, overlay, min, max,
   difference, divide; opacity; input 2 = mask) · tex_levels · tex_curves (ramp) · tex_blur (gaussian/box, tileable
@@ -594,6 +716,8 @@ Examples: render {views:["persp","section"], section_axis:"z", wireframe:"hard",
 CLI: --wireframe all --section y:0.5 --clip x:0.5 --glyphs N --labels groups,pieces --shading matcap --legend --size 1600 --scale 2
   --no-view-labels`,
     export: `EXPORT
+export {output:"crate"} / export {} (the default output) / export {all:true}: the graph's export targets (help topic
+  "graph": "export" on the graph or an output), written inside exports/, the same files the viewer's Export buttons write.
 export {path:"exports/thing.glb"} — format from the extension:
   glb / gltf    glTF 2.0 via gltf-transform (recommended for Unreal, Blender, web)
   geo           Houdini JSON geometry: every attribute (all classes), group and polyline, lossless (precision 64 or 32)

package/dist/mcp/inputs.d.ts

@@ -0,0 +1,28 @@
+import type { Workspace, InputFile } from '../workspace.ts';
+import type { ToolDef } from './tools.ts';
+/** name prefixes that mark a guide's role (help topic "inputs") */
+export declare const ROLES: readonly ['site', 'path', 'zone', 'volume', 'blockout'];
+interface Described {
+    /** one line for inputs list */
+    short: string;
+    /** the full inputs describe text (without the header line) */
+    long: string;
+    failed: boolean;
+}
+/** inputs/ file → its description, keyed by path and invalidated by the host's file stamp (mtime + size). */
+export declare class InputDescriber {
+    ws: Workspace;
+    private cache;
+    constructor(ws: Workspace);
+    /** Describe one file (cached while its stamp holds). */
+    describe(f: InputFile): Promise<Described>;
+    /** Whether describe() would answer from the cache. */
+    cached(f: InputFile): boolean;
+    /** Forget files that are gone. */
+    prune(keep: InputFile[]): void;
+    /** Cook the one-node graph a file node would be (never a workspace graph) and read the result. */
+    private geometry;
+    private image;
+}
+export declare function inputsTool(ws: Workspace): ToolDef;
+export {};