topotopo 0.2.0 → 0.3.0

package/README.md

@@ -78,12 +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 graph.json --export-all                        # every output's export target, into exports/ beside it
 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
 ```
 
-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
+The current release is v0.3 ([release notes](docs/release/v0.3-release-notes.md)); v0.2 was the first tagged release
+([release notes](docs/release/v0.2-release-notes.md)). 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.
 
@@ -113,6 +114,22 @@ To browse the examples in the live 3D viewer without an MCP client:
 npm run preview
 ```
 
+The viewer's left panel has three tabs: **Scene** (the graph's nodes and guides), **Outputs** and **Inputs**.
+**Outputs**, the default, shows all graphs' main results, named deliverables and their textures; click one to
+inspect it alone, and **Scene** in the top bar restores the scene. Publish extra results in graph JSON with
+`"outputs": {"rotor": {"node": "rotor_final", "label": "Rotor"}}`, keeping `"output"` as the default. Each result
+has an **Export** button: the first click asks for a format and a file inside `exports/` and stores that target in
+the graph (`"export": "glb"`, or `{"format": "obj", "path": "parts/rotor.obj", "up_axis": "z"}`, on the graph or on an
+output); later clicks overwrite the same file, and **Export all** writes every target. MCP `export {output}` and the
+CLI's `--export-all` write the same targets. **Inputs** lists your files in `inputs/`, with **Add input** (or drop
+files anywhere on the page); the agent is told about new ones in its next tool answer. Images open in a 2D viewer
+with layers and channels (generated textures default to RGB; use A to inspect packed alpha/AO); JPEG/WebP are for
+viewing only. For `topotopo view graph.json`, `inputs/` and `exports/` are beside that graph.
+
+The default **TopoTopo** keymap uses right-drag orbit around the surface beneath the cursor, middle-drag pan and
+wheel zoom toward the cursor. F/A frame, 1–4 select cameras, 5–7 change shading, O toggles orthographic and Space
+toggles quad view. Maya, Houdini and Blender presets, including previously saved choices, remain available.
+
 **Threads.** Heavy per-element work (noise displacement, attribute noise, occlusion rays, point wrangles) runs in
 chunks on a pool of worker threads, and independent graph branches cook concurrently. The output is the same bit for
 bit with or without it. `TOPOTOPO_WORKERS` sets the number of threads (default: CPU threads − 1; `0` turns the pool

package/dist/cli.js

@@ -33,11 +33,16 @@ 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 { ArtifactStore } from './host/artifacts.js';
+import { prepareTarget, writeTargets } from './host/export-targets.js';
+import { publishedOutputs } from './io/targets.js';
 import { inspect } from './inspect.js';
 import { catalogText, nodeDoc } from './mcp/docs.js';
 const argv = process.argv.slice(2);
 const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
 const fail = (msg) => { console.error(msg); process.exit(1); };
+/** A graph file's name as a graph (view mode) and in receipts and default export file names. */
+const graphName = (file) => path.basename(file).replace(/\.json$/i, '').replace(/[^A-Za-z0-9_-]/g, '_').replace(/^[^A-Za-z]/, 'g$&') || 'graph';
 // 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')) {
@@ -50,6 +55,7 @@ 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]`,
         '         [--render out.png] [--views quad|quad_uv|turntable|persp|front,top|persp,uv|persp,section] [--checker] [--color-by attr] [--export out.glb] [--inspect all]',
+        '         [--export-all] (every output with an export target in the graph, into exports/ beside it)',
         '         render overlays: [--wireframe all|hard|boundary|groups] [--hard-angle 30] [--section y:0.5] [--clip x:0.5[:abs]]',
         '                          [--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]',
@@ -97,12 +103,12 @@ if (argv[0] === 'view') {
     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
+    // A scratch workspace holds the graph and assets: 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') });
+    const ws = new Workspace(fs.mkdtempSync(path.join(os.tmpdir(), 'topotopo-view-')), engine, { inputs: path.join(dir, 'inputs'), exports: path.join(dir, 'exports') });
     ws.load();
-    const name = path.basename(file).replace(/\.json$/i, '').replace(/[^A-Za-z0-9_-]/g, '_').replace(/^[^A-Za-z]/, 'g$&') || 'graph';
+    const name = graphName(file);
     const load = async () => {
         let spec;
         try {
@@ -118,7 +124,26 @@ if (argv[0] === 'view') {
         ws.bump(name);
     };
     await load();
-    const v = await startViewer(ws, opt('--port') !== undefined ? Number(opt('--port')) : undefined, { inputsWhere: `beside ${path.basename(file)}` });
+    // an export target set on the page goes into the graph file, the only source here: only "export" keys change
+    const persistGraph = (g) => {
+        if (g !== name)
+            return;
+        const spec = ws.getGraph(name), raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (spec.export === undefined)
+            delete raw.export;
+        else
+            raw.export = spec.export;
+        for (const [id, o] of Object.entries(spec.outputs ?? {})) {
+            if (!raw.outputs?.[id])
+                continue;
+            if (o.export === undefined)
+                delete raw.outputs[id].export;
+            else
+                raw.outputs[id].export = o.export;
+        }
+        fs.writeFileSync(file, JSON.stringify(raw, null, 2) + '\n');
+    };
+    const v = await startViewer(ws, opt('--port') !== undefined ? Number(opt('--port')) : undefined, { inputsWhere: `beside ${path.basename(file)}`, persistGraph });
     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); });
@@ -179,6 +204,8 @@ async function cook() {
     const frameArg = opt('--frame');
     if (framesArg && frameArg)
         fail('use either --frame or --frames, not both');
+    if (framesArg && argv.includes('--export-all'))
+        fail('--export-all writes one frame: use --frame N, not --frames');
     const single = frameArg !== undefined ? Number(frameArg) : undefined;
     if (single !== undefined && !Number.isFinite(single))
         fail(`--frame expects a number, got "${frameArg}"`);
@@ -223,6 +250,14 @@ async function cook() {
     async function writeOutputs(r, frame) {
         const geo = r.geo;
         const at = (p) => (frame === undefined ? p : framePath(p, frame));
+        // Receipts for the viewer's saved files, only for files inside exports/ beside the graph: a run whose output goes
+        // elsewhere leaves no exports/ folder behind (the viewer lists that folder's files without receipts too).
+        const exportsDir = path.join(path.dirname(path.resolve(file)), 'exports');
+        const record = (paths, format) => {
+            const inside = paths.every((p) => { const rel = path.relative(exportsDir, path.resolve(p)); return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel); });
+            if (inside)
+                new ArtifactStore(exportsDir).record(paths, { graph: graphName(file), node: r.target, format });
+        };
         for (const { out, get, has } of renders) {
             const ro = renderFlags(get, has);
             const v = get('--views');
@@ -236,6 +271,7 @@ async function cook() {
             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)));
+            record([p], 'png');
             console.log(`rendered ${p} (${img.width}x${img.height})${img.notes.length ? ' — ' + img.notes.join('; ') : ''}`);
         }
         const ex = opt('--export');
@@ -273,6 +309,8 @@ async function cook() {
                 fs.mkdirSync(path.dirname(path.resolve(f.path)), { recursive: true });
                 fs.writeFileSync(f.path, f.bytes);
             }
+            if (files.length)
+                record(files.map((f) => f.path), fmt);
             console.log(`exported ${files.length === 1 ? files[0].path : files.map((f) => f.path).join(', ')}${files.length > 1 || fmt !== 'glb' ? ` — ${summary}` : ''}`);
         }
     }
@@ -300,6 +338,31 @@ async function cook() {
         console.log(`cooked ${file} → ${r.target}${r.frame !== 1 ? ` at frame ${r.frame}` : ''} in ${r.ms.toFixed(0)} ms`);
         console.log(inspect(r.geo, { detail: opt('--inspect') ?? 'summary' }));
         await writeOutputs(r);
+        if (argv.includes('--export-all'))
+            await exportAll();
+    }
+    /** --export-all: every published output with an export target (io/targets.ts), into exports/ beside the graph. */
+    async function exportAll() {
+        const name = graphName(file), exportsDir = path.join(path.dirname(path.resolve(file)), 'exports');
+        const published = publishedOutputs(name, graph, engine.findOutput(graph).name);
+        if (!published.some((p) => p.target))
+            fail(`--export-all: no output of ${file} has an export target; add "export": "glb" to the graph (default output) or to an entry of "outputs"`);
+        const prepared = [];
+        for (const p of published) {
+            if (!p.target)
+                continue;
+            const r = await engine.cook(graph, { target: p.node, frame: single, fps });
+            report(r);
+            if (!r.ok || !r.geo)
+                fail(`--export-all: "${p.label}" did not cook; nothing was written`);
+            prepared.push(await prepareTarget(r.geo, name, p, exportsDir, engine.host));
+        }
+        writeTargets(prepared, exportsDir);
+        for (const p of prepared)
+            console.log(`exported ${p.label} → ${path.join('exports', ...p.target.path.split('/'))} — ${p.summary}`);
+        const skipped = published.filter((p) => !p.target).map((p) => p.label);
+        if (skipped.length)
+            console.log(`no export target (skipped): ${skipped.join(', ')}`);
     }
     // stop the kernel worker threads (idle ones would not hold the process, but a clean exit should not wait on them)
     await engine.host.pool?.close();

package/dist/graph/engine.js

@@ -26,6 +26,7 @@ import { Geometry, isGeometry } from '../core/geometry.js';
 import { DEFAULT_TRANSFER, expandPacked } from '../core/packed.js';
 import { splinesToPolylines } from '../core/splines.js';
 import { hashString } from '../core/random.js';
+import { targetError } from '../io/targets.js';
 import { allAliases, getNodeDef } from './registry.js';
 import { DeferredExpr, REF_FUNCS, didYouMean, hasRefs, resolveParamName, resolveParams, scanNodeRefs, scanValue, vecOut, } from './params.js';
 import { migrateGraphDetailed } from './migrate.js';
@@ -453,6 +454,19 @@ export class Engine {
             return { errors, warnings };
         }
         const names = Object.keys(graph.nodes);
+        if (graph.outputs !== undefined) {
+            if (!graph.outputs || typeof graph.outputs !== 'object' || Array.isArray(graph.outputs))
+                errors.push({ node: path || '(graph)', message: 'outputs must be a map of names to {node, label?}' });
+            else
+                for (const [id, out] of Object.entries(graph.outputs)) {
+                    if (!id || !out || typeof out !== 'object' || typeof out.node !== 'string' || !Object.hasOwn(graph.nodes, out.node) || (out.label !== undefined && typeof out.label !== 'string'))
+                        errors.push({ node: path || '(graph)', message: `named output "${id}" must reference an existing node and have an optional string label` });
+                    else if (out.export !== undefined && targetError(out.export))
+                        errors.push({ node: path || '(graph)', message: `named output "${id}": ${targetError(out.export)}` });
+                }
+        }
+        if (graph.export !== undefined && targetError(graph.export))
+            errors.push({ node: path || '(graph)', message: targetError(graph.export) });
         if (!names.length)
             errors.push({ node: path || '(graph)', message: 'graph has no nodes' });
         if (graph.output && !graph.nodes[graph.output])

package/dist/graph/types.d.ts

@@ -91,11 +91,28 @@ export interface VarDef {
 export interface GraphMeta {
     [key: string]: any;
 }
+/**
+ * Where a published output exports to: a format name ("glb"), written as exports/<output>.<ext>, or an object with
+ * the format, an optional path inside exports/ and the export tool's options ({format: "obj", up_axis: "z"}).
+ */
+export type ExportTarget = string | {
+    format: string;
+    path?: string;
+    [option: string]: unknown;
+};
 export interface GraphSpec {
     /** graph format version (see GRAPH_VERSION); missing = 0, migrated on load */
     version?: number;
     nodes: Record<string, NodeSpec>;
     output?: string;
+    /** where the default output exports to (io/targets.ts): a format ("glb"), or {format, path?, ...export options} */
+    export?: ExportTarget;
+    /** Named deliverables for the viewer. `output` remains the default cook target. */
+    outputs?: Record<string, {
+        node: string;
+        label?: string;
+        export?: ExportTarget;
+    }>;
     vars?: Record<string, any>;
     /** metadata for exposed vars: asset parameters, and the controls the live viewer shows for them */
     params?: Record<string, VarDef>;

package/dist/host/artifacts.d.ts

@@ -0,0 +1,21 @@
+export interface Artifact {
+    id: string;
+    label: string;
+    graph?: string;
+    node?: string;
+    format?: string;
+    sourceRevision?: string;
+    /** the published output a target export wrote ('' = the graph's default output) */
+    output?: string;
+    files: string[];
+}
+export declare const artifactId: (p: string) => string;
+export declare class ArtifactStore {
+    dir: string;
+    constructor(dir: string);
+    get manifest(): string;
+    records(): Artifact[];
+    record(files: string[], info?: Partial<Omit<Artifact, 'id' | 'files'>>): Artifact;
+    /** Discover unregistered agent-written files too. Never follow symlinks/junctions while scanning. */
+    list(): Artifact[];
+}

package/dist/host/artifacts.js

@@ -0,0 +1,58 @@
+// Persistent output receipts shared by the CLI, MCP and viewer. Paths are registered by trusted host code;
+// HTTP callers only receive identifiers, never a route that reads an arbitrary absolute path.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+export const artifactId = (p) => createHash('sha256').update(path.resolve(p)).digest('hex').slice(0, 24);
+export class ArtifactStore {
+    dir;
+    constructor(dir) { this.dir = path.resolve(dir); }
+    get manifest() { return path.join(this.dir, '.outputs.json'); }
+    records() {
+        try {
+            const j = JSON.parse(fs.readFileSync(this.manifest, 'utf8'));
+            return Array.isArray(j) ? j.filter((a) => a && typeof a.id === 'string' && Array.isArray(a.files) && a.files.every((p) => typeof p === 'string')) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    record(files, info = {}) {
+        if (!files.length)
+            throw new Error('an output needs at least one file');
+        files = files.map((p) => path.resolve(p));
+        const a = { id: artifactId(files[0]), label: path.basename(files[0]), ...info, files };
+        const all = this.records().filter((x) => x.id !== a.id);
+        all.push(a);
+        fs.mkdirSync(this.dir, { recursive: true });
+        const temp = this.manifest + '.part';
+        fs.writeFileSync(temp, JSON.stringify(all, null, 2) + '\n');
+        fs.renameSync(temp, this.manifest);
+        return a;
+    }
+    /** Discover unregistered agent-written files too. Never follow symlinks/junctions while scanning. */
+    list() {
+        const all = this.records().filter((a) => a.files.some((p) => fs.statSync(p, { throwIfNoEntry: false })?.isFile()));
+        const known = new Set(all.flatMap((a) => a.files.map((p) => path.resolve(p))));
+        const walk = (dir) => {
+            // a folder can be missing, or vanish between listing its parent and reading it
+            const entries = (() => { try {
+                return fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return [];
+            } })();
+            for (const e of entries.sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+                if (e.name.startsWith('.') || e.isSymbolicLink())
+                    continue;
+                const p = path.join(dir, e.name);
+                if (e.isDirectory())
+                    walk(p);
+                else if (e.isFile() && !known.has(p))
+                    all.push({ id: artifactId(p), label: path.relative(this.dir, p).split(path.sep).join('/'), files: [p] });
+            }
+        };
+        walk(this.dir);
+        return all;
+    }
+}

package/dist/host/export-targets.d.ts

@@ -0,0 +1,33 @@
+import type { Geometry } from '../core/geometry.ts';
+import type { ExportFormat } from '../io/export.ts';
+import type { ExportFile } from '../io/files.ts';
+import type { PublishedOutput, ResolvedTarget } from '../io/targets.ts';
+import type { Host } from './types.ts';
+/** The files an export writes, nothing written yet; `a` holds the export tool's snake_case options. */
+export declare function serializeExport(geo: Geometry, format: ExportFormat, p: string, a: Record<string, any>, host: Host): Promise<{
+    files: ExportFile[];
+    summary: string;
+    warnings: string[];
+    outDir: string;
+}>;
+/** `p` resolved inside `root`, crossing no symbolic link or junction on the way; throws otherwise. */
+export declare function insideRoot(root: string, p: string): string;
+/** Write files, each through a .part renamed into place; with `root`, each must stay inside it. Returns the count. */
+export declare function writeExportFiles(files: ExportFile[], root?: string): number;
+/** A published output serialized to its target, ready to write. */
+export interface PreparedTarget {
+    graph: string;
+    output: string | null;
+    label: string;
+    node: string;
+    target: ResolvedTarget;
+    files: ExportFile[];
+    summary: string;
+    warnings: string[];
+}
+/** Serialize one published output to its target inside `exportsDir` (nothing is written yet). */
+export declare function prepareTarget(geo: Geometry, graph: string, p: PublishedOutput & {
+    target: ResolvedTarget;
+}, exportsDir: string, host: Host): Promise<PreparedTarget>;
+/** Write prepared targets and record their receipts; two targets writing one file are refused before any write. */
+export declare function writeTargets(prepared: PreparedTarget[], exportsDir: string): number;

package/dist/host/export-targets.js

@@ -0,0 +1,84 @@
+// Writing exports for the CLI, the MCP server and the viewer: serialize with the export tool's options, then write
+// each file through a .part beside it, renamed into place. Published targets (io/targets.ts) write inside exports/
+// only, and every target is serialized before any file is written, so a failed cook or format changes nothing.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { exportFilesAsync } from '../io/files.js';
+import { ArtifactStore } from './artifacts.js';
+/** The files an export writes, nothing written yet; `a` holds the export tool's snake_case options. */
+export async function serializeExport(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),
+    });
+    return { files: res.files, summary: res.summary, warnings: [...new Set(warnings)], outDir };
+}
+/** `p` resolved inside `root`, crossing no symbolic link or junction on the way; throws otherwise. */
+export function insideRoot(root, p) {
+    const abs = path.resolve(p), rel = path.relative(path.resolve(root), abs);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        throw new Error(`${p} is outside ${root}`);
+    let current = path.resolve(root);
+    for (const part of rel.split(path.sep)) {
+        current = path.join(current, part);
+        if (fs.lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error(`export paths cannot pass through the link ${current}`);
+    }
+    return abs;
+}
+/** Write files, each through a .part renamed into place; with `root`, each must stay inside it. Returns the count. */
+export function writeExportFiles(files, root) {
+    let written = 0;
+    try {
+        for (const f of files) {
+            const abs = root ? insideRoot(root, f.path) : path.resolve(f.path);
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs + '.part', f.bytes);
+            fs.renameSync(abs + '.part', abs);
+            written++;
+        }
+    }
+    catch (e) {
+        throw new Error(`export stopped after writing ${written} of ${files.length} files: ${e.message}`);
+    }
+    return written;
+}
+/** Serialize one published output to its target inside `exportsDir` (nothing is written yet). */
+export async function prepareTarget(geo, graph, p, exportsDir, host) {
+    const dest = insideRoot(exportsDir, path.join(exportsDir, ...p.target.path.split('/')));
+    const r = await serializeExport(geo, p.target.format, dest, p.target.options, host);
+    for (const f of r.files)
+        insideRoot(exportsDir, f.path);
+    return { graph, output: p.output, label: p.label, node: p.node, target: p.target, files: r.files, summary: r.summary, warnings: r.warnings };
+}
+/** Write prepared targets and record their receipts; two targets writing one file are refused before any write. */
+export function writeTargets(prepared, exportsDir) {
+    const owner = new Map();
+    for (const p of prepared)
+        for (const f of p.files) {
+            const key = path.resolve(f.path).toLowerCase(), other = owner.get(key);
+            // status: the viewer answers 409 (the request conflicts with itself); the CLI and MCP print the message
+            if (other && other !== p)
+                throw Object.assign(new Error(`"${other.label}" (${other.graph}) and "${p.label}" (${p.graph}) both write ${path.relative(exportsDir, f.path)}: give one a different export path`), { status: 409 });
+            owner.set(key, p);
+        }
+    const store = new ArtifactStore(exportsDir);
+    let written = 0;
+    for (const p of prepared) {
+        written += writeExportFiles(p.files, exportsDir);
+        store.record(p.files.map((f) => f.path), { label: p.target.path, graph: p.graph, node: p.node, format: p.target.format, output: p.output ?? '' });
+    }
+    return written;
+}

package/dist/io/targets.d.ts

@@ -0,0 +1,31 @@
+import type { ExportFormat } from './export.ts';
+import type { ExportTarget, GraphSpec } from '../graph/types.ts';
+/** Every export format with the label the viewer shows, in the order it offers them (a Record, so none is missing). */
+export declare const FORMAT_LABELS: Record<ExportFormat, string>;
+export declare const TARGET_FORMATS: ExportFormat[];
+/** The extension a target's file gets: '' for unreal_landscape and textures, which write a folder. */
+export declare const targetExtension: (format: ExportFormat) => string;
+/** A format name in canonical form ("USD" → usda), or null. */
+export declare function targetFormat(f: unknown): ExportFormat | null;
+/** Why a target is invalid, or null when it is valid. */
+export declare function targetError(t: unknown): string | null;
+export interface ResolvedTarget {
+    format: ExportFormat;
+    /** posix path inside exports/: a file, or a folder for unreal_landscape and textures */
+    path: string;
+    /** the export tool's options (up_axis, scale, …) */
+    options: Record<string, unknown>;
+}
+/** A file name stem from an output id or graph name. */
+export declare const fileStem: (s: string) => string;
+/** A valid target with its path filled in: <stem><extension> unless it names one. */
+export declare function resolveTarget(t: ExportTarget, stem: string): ResolvedTarget;
+export interface PublishedOutput {
+    /** null for the graph's default output (graph.export), else the id in graph.outputs */
+    output: string | null;
+    node: string;
+    label: string;
+    target: ResolvedTarget | null;
+}
+/** A graph's default output (its files named after the graph) and its named outputs, each with its target if valid. */
+export declare function publishedOutputs(graph: string, spec: GraphSpec, defaultNode: string): PublishedOutput[];

package/dist/io/targets.js

@@ -0,0 +1,75 @@
+/** Every export format with the label the viewer shows, in the order it offers them (a Record, so none is missing). */
+export const FORMAT_LABELS = {
+    glb: 'GLB (one file, textures inside)', gltf: 'glTF + texture files', usda: 'USD (.usda)', obj: 'OBJ', geo: 'Houdini .geo',
+    unreal_landscape: 'Unreal Landscape bundle (folder)', csv: 'CSV points (Unreal PCG)', pointsjson: 'Points JSON',
+    textures: 'PNG textures (folder)', png16: 'Heightmap, 16-bit PNG', r16: 'Heightmap, RAW .r16', mask_png: 'Masks, PNG',
+    ply: 'PLY', stl: 'STL', json: 'TopoTopo JSON',
+};
+export const TARGET_FORMATS = Object.keys(FORMAT_LABELS);
+const EXTENSIONS = { unreal_landscape: '', textures: '', png16: '.png', mask_png: '.png', pointsjson: '.points.json' };
+/** The extension a target's file gets: '' for unreal_landscape and textures, which write a folder. */
+export const targetExtension = (format) => EXTENSIONS[format] ?? '.' + format;
+/** A format name in canonical form ("USD" → usda), or null. */
+export function targetFormat(f) {
+    const s = typeof f === 'string' ? f.trim().toLowerCase() : '';
+    const c = s === 'usd' ? 'usda' : s;
+    return Object.hasOwn(FORMAT_LABELS, c) ? c : null;
+}
+// the export tool's options (src/mcp/tools.ts), by value type
+const BOOLEAN = ['split_by_name', 'materials', 'custom_attribs', 'quantize', 'pcg', 'pcg_struct', 'meshes'];
+const CHOICES = { up_axis: ['y', 'z'], compress: ['none', 'meshopt', 'draco'], instancing: ['packed', 'expand'], instances: ['rows', 'expand'], precision: [32, 64] };
+const NUMBER = ['scale', 'height_min', 'height_max', 'tile_size', 'heightfield'];
+const NAMES = ['attributes', 'layers'];
+const OPTIONS = [...BOOLEAN, ...Object.keys(CHOICES), ...NUMBER, ...NAMES, 'layer'];
+/** A path segment Windows and POSIX both accept, and that cannot climb out of exports/. */
+const segmentOk = (s) => !!s && s !== '.' && s !== '..' && !/[<>:"|?*\x00-\x1f]/.test(s) && !/[. ]$/.test(s) && !/^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(s);
+const pathOk = (p) => typeof p === 'string' && p.length <= 240 && !/^[A-Za-z]:|^[\\/]/.test(p) && p.replace(/\\/g, '/').split('/').every(segmentOk);
+/** Why a target is invalid, or null when it is valid. */
+export function targetError(t) {
+    const o = typeof t === 'string' ? { format: t } : t;
+    if (!o || typeof o !== 'object' || Array.isArray(o))
+        return 'export must be a format name ("glb") or {format, path?, ...options}';
+    if (!targetFormat(o.format))
+        return `export format "${o.format}" is not one of ${TARGET_FORMATS.join(', ')} (or usd)`;
+    if (o.path !== undefined && !pathOk(o.path))
+        return `export path "${o.path}" must stay inside exports/: relative, without "..", a drive or a leading slash`;
+    for (const [k, v] of Object.entries(o)) {
+        if (k === 'format' || k === 'path')
+            continue;
+        if (!OPTIONS.includes(k))
+            return `unknown export option "${k}" (options: ${OPTIONS.join(', ')})`;
+        if (BOOLEAN.includes(k) && typeof v !== 'boolean')
+            return `export option ${k} must be true or false`;
+        if (k in CHOICES && !CHOICES[k].includes(v))
+            return `export option ${k} must be one of ${CHOICES[k].join(', ')}`;
+        if (NUMBER.includes(k) && !(typeof v === 'number' && Number.isFinite(v)))
+            return `export option ${k} must be a number`;
+        if (k === 'scale' && !(v > 0))
+            return 'export option scale must be positive';
+        if (NAMES.includes(k) && !(Array.isArray(v) && v.every((s) => typeof s === 'string')))
+            return `export option ${k} must be a list of names`;
+        if (k === 'layer' && typeof v !== 'string')
+            return 'export option layer must be a name';
+    }
+    return null;
+}
+/** A file name stem from an output id or graph name. */
+export const fileStem = (s) => s.replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+|[. ]+$/g, '') || 'output';
+/** A valid target with its path filled in: <stem><extension> unless it names one. */
+export function resolveTarget(t, stem) {
+    const { format, path, ...options } = typeof t === 'string' ? { format: t } : t;
+    const f = targetFormat(format);
+    return { format: f, path: (typeof path === 'string' ? path : fileStem(stem) + targetExtension(f)).replace(/\\/g, '/'), options };
+}
+/** A graph's default output (its files named after the graph) and its named outputs, each with its target if valid. */
+export function publishedOutputs(graph, spec, defaultNode) {
+    const valid = (t) => (t !== undefined && t !== null && !targetError(t) ? t : null);
+    const main = valid(spec.export);
+    return [
+        { output: null, node: defaultNode, label: 'Main output', target: main ? resolveTarget(main, graph) : null },
+        ...Object.entries(spec.outputs ?? {}).map(([id, o]) => {
+            const t = valid(o?.export);
+            return { output: id, node: o.node, label: o.label ?? id, target: t ? resolveTarget(t, id) : null };
+        }),
+    ];
+}

package/dist/mcp/docs.d.ts

@@ -1,5 +1,5 @@
 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\".\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\".";
+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.

package/dist/mcp/docs.js

@@ -10,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".
@@ -82,14 +83,24 @@ export const TOPICS = {
   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): meshes, guide
-curves and points drawn in Blender, Houdini or Unreal, placeholder blockouts, PNG masks and heightmaps. Before building a
+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"}}.
@@ -705,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)