topotopo 0.2.0 → 0.3.0

package/dist/mcp/tools.d.ts

@@ -25,7 +25,7 @@ export interface ToolDef {
  * Landscape bundle, or the single file of other formats). Textures are read through the host; USD texture paths are
  * written relative to the output file. Returns the report text.
  */
-export declare function writeExport(geo: Geometry, format: ExportFormat, p: string, a: any, host: Host): Promise<string>;
+export declare function writeExport(geo: Geometry, format: ExportFormat, p: string, a: any, host: Host, record?: (files: string[]) => void): Promise<string>;
 export declare function makeTools(ws: Workspace, opts?: {
     onPreview?: () => Promise<string>;
 }): ToolDef[];

package/dist/mcp/tools.js

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

package/dist/nodes/code.js

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

package/dist/viewer/app/camera.js

@@ -37,6 +37,7 @@ class Cam {
     this.name = name;
     this.ortho = name !== 'persp';
     this.target = new THREE.Vector3();
+    this.pivot = new THREE.Vector3();
     this.quat = name === 'persp' ? perspQuat() : quatOf(AXIS_VIEWS[name].f, AXIS_VIEWS[name].u);
     this.dist = 12;
     this.halfH = 6;
@@ -45,12 +46,14 @@ class Cam {
   get right() { return new THREE.Vector3(1, 0, 0).applyQuaternion(this.quat); }
   get up() { return new THREE.Vector3(0, 1, 0).applyQuaternion(this.quat); }
   get eye() { return this.target.clone().addScaledVector(this.back, this.dist); }
-  toJSON() { return { ortho: this.ortho, target: this.target.toArray(), quat: this.quat.toArray(), dist: this.dist, halfH: this.halfH }; }
+  toJSON() { return { ortho: this.ortho, target: this.target.toArray(), pivot: this.pivot.toArray(), quat: this.quat.toArray(), dist: this.dist, halfH: this.halfH }; }
   load(j) {
     if (!j) return;
     const ok = (a, n) => Array.isArray(a) && a.length === n && a.every(Number.isFinite);
     if (typeof j.ortho === 'boolean') this.ortho = j.ortho;
     if (ok(j.target, 3)) this.target.fromArray(j.target);
+    this.pivot.copy(this.target);
+    if (ok(j.pivot, 3)) this.pivot.fromArray(j.pivot);
     if (ok(j.quat, 4)) this.quat.fromArray(j.quat).normalize();
     if (j.dist > 0) this.dist = Math.min(MAX_D, Math.max(MIN_D, j.dist));
     if (j.halfH > 0) this.halfH = Math.min(MAX_D, Math.max(MIN_D, j.halfH));
@@ -126,10 +129,10 @@ export function createViews(scene) {
       return { x: r.x + ((q.x + 1) / 2) * r.w, y: r.y + ((1 - q.y) / 2) * r.h };
     },
     /** The point under a viewport point on the plane through the slot's target facing the camera. */
-    targetPlanePoint(i, x, y) {
+    targetPlanePoint(i, x, y, at) {
       const c = v.cam(i), rc = v.ray(i, x, y), n = c.back;
       const p = new THREE.Vector3();
-      return rc.ray.intersectPlane(new THREE.Plane().setFromNormalAndCoplanarPoint(n, c.target), p) ? p : c.target.clone();
+      return rc.ray.intersectPlane(new THREE.Plane().setFromNormalAndCoplanarPoint(n, at ?? c.target), p) ? p : (at ?? c.target).clone();
     },
 
     // ---------------------------------------------------------------- navigation
@@ -149,11 +152,26 @@ export function createViews(scene) {
       return true;
     },
     /** Track: the point at the target's depth follows the mouse. */
-    track(i, dx, dy) {
-      const c = v.cam(i), k = v.worldPerPixel(i);
-      c.target.addScaledVector(c.right, -dx * k).addScaledVector(c.up, dy * k);
+    track(i, dx, dy, at) {
+      const c = v.cam(i);
+      const depth = at && !c.ortho ? Math.max(MIN_D, c.eye.clone().sub(at).dot(c.back)) : c.dist;
+      const k = v.worldPerPixel(i) * (c.ortho ? 1 : depth / c.dist);
+      const delta = c.right.multiplyScalar(-dx * k).addScaledVector(c.up, dy * k);
+      c.target.add(delta); c.pivot.add(delta);
       v.placed = true;
     },
+    /** Pick a navigation pivot without changing the camera's eye, aim or distance. */
+    anchor(i, hit) {
+      const c = v.cam(i);
+      if (hit && hit.toArray().every(Number.isFinite) && c.eye.clone().sub(hit).dot(c.back) > MIN_D) c.pivot.copy(hit);
+      return c.pivot.clone();
+    },
+    zoomAt(i, factor, at) {
+      const c = v.cam(i), before = c.ortho ? c.halfH : c.dist;
+      v.dolly(i, factor, at);
+      const scale = (c.ortho ? c.halfH : c.dist) / before;
+      c.pivot.sub(at).multiplyScalar(scale).add(at);
+    },
     /** Dolly by factor s (< 1 closer) towards `at` (a world point on the target plane; default the target). */
     dolly(i, s, at) {
       const c = v.cam(i);
@@ -171,6 +189,7 @@ export function createViews(scene) {
       const center = box.getCenter(new THREE.Vector3()), size = box.getSize(new THREE.Vector3());
       const radius = Math.max(size.length() / 2, 1e-3);
       c.target.copy(center);
+      c.pivot.copy(center);
       const half = (vfov(aspect) * Math.PI) / 360, halfW = Math.atan(Math.tan(half) * aspect);
       c.dist = Math.min(MAX_D, Math.max(MIN_D, (radius / Math.sin(Math.min(half, halfW))) * 1.05));
       // ortho: the box's extent across the view
@@ -201,6 +220,7 @@ export function createViews(scene) {
         // the new view looks at the same place at the same scale
         const n = cams.get(name);
         n.target.copy(c.target); n.halfH = c.ortho ? c.halfH : c.dist * 0.3;
+        n.pivot.copy(c.pivot);
         slots[i].cam = name;
       }
     },

package/dist/viewer/app/export-popover.js

@@ -0,0 +1,68 @@
+// The export target popover: a format and a file name inside exports/, opened by an output's Export button when it
+// has no target yet, or to change it. Submitting stores the target in the graph and exports.
+const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined) e.textContent = text; return e; };
+
+/** A file name stem like the server's (io/targets.ts fileStem). */
+export const fileStem = (s) => String(s).replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+|[. ]+$/g, '') || 'output';
+
+/** The path a format writes to by default: <stem><extension>, a folder for formats without one. */
+export function defaultPath(stem, format, formats) {
+  return fileStem(stem) + (formats.find((f) => f.format === format)?.extension ?? '');
+}
+
+/** The path with its extension swapped from one format's to another's (a custom name keeps its stem). */
+export function swapExtension(p, from, to, formats) {
+  const ext = (f) => formats.find((x) => x.format === f)?.extension ?? '';
+  const a = ext(from), b = ext(to);
+  const stem = a && p.toLowerCase().endsWith(a.toLowerCase()) ? p.slice(0, -a.length) : p;
+  return stem + b;
+}
+
+/**
+ * Open the popover under `anchor`. item: an output entry (label, kind, graph, output, target); formats: [{format, label,
+ * extension}] from /api/outputs; directory: the exports folder. Resolves to {format, path} or null (cancelled).
+ */
+export function exportPopover({ anchor, item, formats, directory }) {
+  document.querySelector('.export-popover')?.dispatchEvent(new Event('cancel'));
+  return new Promise((resolve) => {
+    const stem = item.output ?? item.graph ?? 'output';
+    const startFormat = item.target?.format ?? (item.kind === 'image' ? 'textures' : 'glb');
+    const box = el('form', 'export-popover');
+    box.setAttribute('role', 'dialog'); box.setAttribute('aria-label', `Export ${item.label}`);
+    const title = el('div', 'export-title', item.target ? `Export target of ${item.label}` : `Export ${item.label}`);
+    const format = el('select'); format.setAttribute('aria-label', 'Format');
+    for (const f of formats) format.append(new Option(f.label, f.format));
+    format.value = startFormat;
+    const file = el('input'); file.type = 'text'; file.spellcheck = false; file.setAttribute('aria-label', 'File in exports/');
+    file.value = item.target?.path ?? defaultPath(stem, startFormat, formats);
+    const where = el('div', 'export-where dim');
+    const error = el('div', 'export-error err');
+    const cancel = el('button', '', 'Cancel'), go = el('button', 'primary', 'Export');
+    cancel.type = 'button'; go.type = 'submit';
+    const field = (label, input) => { const l = el('label', 'export-field'); l.append(el('span', 'dim', label), input); return l; };
+    const actions = el('div', 'export-actions'); actions.append(cancel, go);
+    box.append(title, field('Format', format), field('File', file), where, error, actions);
+    let previous = format.value;
+    const sync = () => { where.textContent = `${directory}/${file.value.trim() || '…'}`; error.textContent = ''; };
+    format.onchange = () => { file.value = swapExtension(file.value.trim(), previous, format.value, formats); previous = format.value; sync(); };
+    file.oninput = sync;
+    const close = (value) => { box.remove(); removeEventListener('pointerdown', outside, true); anchor?.focus?.(); resolve(value); };
+    const outside = (e) => { if (!box.contains(e.target)) close(null); };
+    box.addEventListener('cancel', () => close(null));
+    cancel.onclick = () => close(null);
+    box.onkeydown = (e) => { if (e.key === 'Escape') { e.preventDefault(); close(null); } };
+    box.onsubmit = (e) => {
+      e.preventDefault();
+      const p = file.value.trim().replace(/\\/g, '/');
+      if (!p || p.startsWith('/') || /^[A-Za-z]:/.test(p) || p.split('/').some((s) => !s || s === '.' || s === '..')) { error.textContent = 'a path inside exports/, without ".." or a drive'; file.focus(); return; }
+      close({ format: format.value, path: p });
+    };
+    sync();
+    document.body.append(box);
+    const r = anchor.getBoundingClientRect();
+    box.style.left = Math.max(6, Math.min(r.left, innerWidth - box.offsetWidth - 6)) + 'px';
+    box.style.top = (r.bottom + 4 + box.offsetHeight < innerHeight ? r.bottom + 4 : Math.max(6, r.top - box.offsetHeight - 4)) + 'px';
+    addEventListener('pointerdown', outside, true);
+    format.focus();
+  });
+}

package/dist/viewer/app/image-view.js

@@ -0,0 +1,114 @@
+// A 2D image inspector, independent of the 3D camera. View state is remembered per output.
+export function channelPixels(source, mode) {
+  const pixels = new Uint8ClampedArray(source);
+  const c = ['R', 'G', 'B', 'A'].indexOf(mode);
+  for (let i = 0; i < pixels.length; i += 4) {
+    if (c >= 0) pixels[i] = pixels[i + 1] = pixels[i + 2] = source[i + c];
+    if (mode !== 'RGBA') pixels[i + 3] = 255;
+  }
+  return pixels;
+}
+export function zoomImage(state, x, y, factor) {
+  const scale = Math.max(0.01, Math.min(64, state.scale * factor)), ratio = scale / state.scale;
+  return { scale, x: x - (x - state.x) * ratio, y: y - (y - state.y) * ratio };
+}
+
+export function createImageView(host, message) {
+  const panel = document.createElement('section'); panel.id = 'image-view'; panel.hidden = true;
+  panel.innerHTML = `<div class="image-tools"><button data-act="fit">Fit</button><button data-act="actual">100%</button>
+    <select aria-label="Image channel">${['RGB', 'RGBA', 'R', 'G', 'B', 'A'].map((m) => `<option>${m}</option>`).join('')}</select>
+    <select aria-label="Image layer"></select><label><input type="checkbox" data-act="checker" checked> Checkerboard</label>
+    <label><input type="checkbox" data-act="uv"> UV</label><span class="image-dim"></span></div>
+    <div class="image-stage checker"><canvas aria-label="Image preview"></canvas><div class="image-error" hidden></div></div>`;
+  host.append(panel);
+  const stage = panel.querySelector('.image-stage'), canvas = panel.querySelector('canvas'), context = canvas.getContext('2d');
+  const mode = panel.querySelector('[aria-label="Image channel"]'), layers = panel.querySelector('[aria-label="Image layer"]');
+  const uvToggle = panel.querySelector('[data-act="uv"]'), dim = panel.querySelector('.image-dim'), error = panel.querySelector('.image-error');
+  const memory = new Map();
+  let item = null, bitmap = null, data = null, raster = document.createElement('canvas'), segments = [], sequence = 0;
+  let state = { scale: 1, x: 0, y: 0 }, drag = null, fitNew = true;
+  function remember() { if (item) memory.set(item.id, { ...state, mode: mode.value, layer: layers.value }); }
+  function draw() {
+    if (panel.hidden) return;
+    const dpr = Math.min(2, devicePixelRatio || 1), w = stage.clientWidth, h = stage.clientHeight;
+    canvas.width = Math.round(w * dpr); canvas.height = Math.round(h * dpr);
+    context.setTransform(dpr, 0, 0, dpr, 0, 0); context.clearRect(0, 0, w, h);
+    if (!bitmap) return;
+    context.save(); context.translate(state.x, state.y); context.scale(state.scale, state.scale);
+    context.imageSmoothingEnabled = state.scale < 1;
+    context.drawImage(raster, 0, 0);
+    if (uvToggle.checked && segments.length) {
+      context.beginPath();
+      for (const [u, v, s, t] of segments) { context.moveTo(u * raster.width, (1 - v) * raster.height); context.lineTo(s * raster.width, (1 - t) * raster.height); }
+      context.strokeStyle = '#f0a030'; context.lineWidth = 1 / state.scale; context.stroke();
+    }
+    context.restore(); dim.textContent = `${raster.width} × ${raster.height} · ${Math.round(state.scale * 100)}%`;
+  }
+  function fit() {
+    if (!bitmap) return;
+    state.scale = Math.min((stage.clientWidth - 32) / raster.width, (stage.clientHeight - 32) / raster.height);
+    state.scale = Math.max(0.01, state.scale);
+    state.x = (stage.clientWidth - raster.width * state.scale) / 2; state.y = (stage.clientHeight - raster.height * state.scale) / 2;
+    remember(); draw();
+  }
+  function applyChannels() {
+    if (!data) return;
+    raster.getContext('2d').putImageData(new ImageData(channelPixels(data.data, item.generated ? 'RGBA' : mode.value), data.width, data.height), 0, 0);
+    draw();
+  }
+  async function load() {
+    if (!item) return;
+    const seq = ++sequence, current = item;
+    error.hidden = true;
+    const q = new URLSearchParams({ id: current.id, layer: layers.value, mode: mode.value, rev: current.revision });
+    const url = current.sourceURL ?? (current.generated ? '/api/output/image?' + q : '/api/output/file?' + q);
+    try {
+      const response = await fetch(url);
+      if (!response.ok) throw new Error((await response.json()).error);
+      const next = await createImageBitmap(await response.blob(), { premultiplyAlpha: 'none' });
+      if (seq !== sequence) { next.close(); return; }
+      bitmap?.close(); bitmap = next;
+      raster.width = next.width; raster.height = next.height;
+      const c = raster.getContext('2d', { willReadFrequently: true }); c.drawImage(next, 0, 0);
+      data = c.getImageData(0, 0, next.width, next.height); applyChannels();
+      if (fitNew) { fitNew = false; fit(); }
+      if (uvToggle.checked) await loadUV();
+    } catch (e) { if (seq === sequence) { error.textContent = e.message; error.hidden = false; message(e.message, 'err'); } }
+  }
+  async function loadUV() {
+    if (!item?.generated || !uvToggle.checked) { segments = []; draw(); return; }
+    const id = item.id;
+    try {
+      const r = await fetch('/api/output/uv?' + new URLSearchParams({ id })), j = await r.json();
+      if (item?.id !== id) return;
+      if (!r.ok) throw new Error(j.error);
+      segments = j.segments; draw();
+    } catch (e) { message(e.message, 'err'); }
+  }
+  panel.querySelector('[data-act="fit"]').onclick = fit;
+  panel.querySelector('[data-act="actual"]').onclick = () => { state = zoomImage(state, stage.clientWidth / 2, stage.clientHeight / 2, 1 / state.scale); remember(); draw(); };
+  panel.querySelector('[data-act="checker"]').onchange = (e) => stage.classList.toggle('checker', e.target.checked);
+  mode.onchange = () => { remember(); if (item?.generated) load(); else applyChannels(); };
+  layers.onchange = () => { remember(); load(); };
+  uvToggle.onchange = loadUV;
+  canvas.onpointerdown = (e) => { if (![0, 1, 2].includes(e.button)) return; e.preventDefault(); canvas.setPointerCapture(e.pointerId); drag = { id: e.pointerId, x: e.clientX, y: e.clientY }; };
+  canvas.onpointermove = (e) => { if (!drag || e.pointerId !== drag.id) return; state.x += e.clientX - drag.x; state.y += e.clientY - drag.y; drag.x = e.clientX; drag.y = e.clientY; draw(); };
+  const end = () => { drag = null; remember(); };
+  canvas.onpointerup = end; canvas.onpointercancel = end; canvas.onlostpointercapture = end; addEventListener('blur', end);
+  canvas.oncontextmenu = (e) => e.preventDefault();
+  canvas.addEventListener('wheel', (e) => { e.preventDefault(); const r = canvas.getBoundingClientRect(); const delta = e.deltaY * (e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? 400 : 1); state = zoomImage(state, e.clientX - r.left, e.clientY - r.top, Math.exp(Math.max(-1, Math.min(1, -delta * 0.0015)))); remember(); draw(); }, { passive: false });
+  new ResizeObserver(draw).observe(stage);
+  return {
+    show(next) {
+      const same = item?.id === next.id; if (!same) remember(); item = next; panel.hidden = false; host.classList.add('image-mode');
+      if (!same) { bitmap?.close(); bitmap = null; data = null; segments = []; uvToggle.checked = false; dim.textContent = 'Loading…'; }
+      const saved = memory.get(next.id); if (!same) { state = saved ? { scale: saved.scale, x: saved.x, y: saved.y } : { scale: 1, x: 0, y: 0 }; fitNew = !saved; }
+      layers.replaceChildren(...(next.layers ?? ['Image']).map((l) => new Option(l, l)));
+      layers.value = next.layers?.includes(saved?.layer) ? saved.layer : next.layer ?? 'Image'; layers.hidden = !next.layers?.length;
+      mode.value = saved?.mode ?? (next.generated ? 'RGB' : 'RGBA'); uvToggle.disabled = !next.generated;
+      load();
+    },
+    hide() { remember(); sequence++; item = null; bitmap?.close(); bitmap = null; data = null; panel.hidden = true; host.classList.remove('image-mode'); },
+    get visible() { return !panel.hidden; },
+  };
+}

package/dist/viewer/app/keymap.js

@@ -1,14 +1,15 @@
-// The keymap of docs/design/viewer.md section 9: one table of actions, three presets (Maya, the default; Houdini;
-// Blender). Each row carries the text the overlay prints per preset and, for the actions phase 1 builds, the bindings:
+// The keymap of docs/design/viewer.md section 9: one table of actions, four presets (TopoTopo, the default;
+// Maya, Houdini, Blender). Each row carries the text the overlay prints per preset and the built actions' bindings:
 // chord → action. Transform and snapping rows (phase 2) ship their text but no bindings, so a preset never changes
 // shape later. Plain data and functions: the overlay is the only DOM code, and it runs only when called.
 
 export const PRESETS = [
+  { id: 'topotopo', label: 'TopoTopo' },
   { id: 'maya', label: 'Maya' },
   { id: 'houdini', label: 'Houdini' },
   { id: 'blender', label: 'Blender' },
 ];
-export const DEFAULT_PRESET = 'maya';
+export const DEFAULT_PRESET = 'topotopo';
 
 const place = { 'Shift+1': 'placeNull', 'Shift+2': 'placeCurve', 'Shift+3': 'placeArea', 'Shift+4': 'placeVolume' };
 const curve = { Enter: 'finish', Backspace: 'removeLast', Esc: 'cancel' };
@@ -57,6 +58,17 @@ export const ROWS = [
   { label: 'keymap overlay', maya: ['?', { keys: { '?': 'overlay' } }], houdini: ['?', { keys: { '?': 'overlay' } }], blender: ['?', { keys: { '?': 'overlay' } }] },
 ];
 
+// Editing shortcuts follow Maya; navigation is available without held modifiers.
+const topo = {
+  tumble: ['Right drag (pan in orthographic)', { drag: { R: 'tumble' } }],
+  track: ['Middle drag', { drag: { M: 'track' } }],
+  dolly: ['Wheel toward cursor'],
+  perspective: ['1', { keys: { 1: 'viewPersp' } }],
+  'top / front / right': ['2 / 3 / 4', { keys: { 2: 'viewTop', 3: 'viewFront', 4: 'viewRight' } }],
+  'wire / shaded / shaded + wire': ['5 / 6 / 7', { keys: { 5: 'displayWire', 6: 'displayShaded', 7: 'displayShadedWire' } }],
+};
+for (const row of ROWS) row.topotopo = topo[row.label] ?? row.maya;
+
 /** Every action a binding may name (main.js handles each). */
 export const ACTIONS = [
   'tumble', 'track', 'dolly', 'frameSelection', 'frameAll', 'quad', 'viewPersp', 'viewTop', 'viewFront', 'viewRight', 'ortho',