topotopo 0.1.0 → 0.3.0

package/dist/graph/types.d.ts

@@ -74,6 +74,7 @@ export interface NodeSpec {
     note?: string;
     ui?: any;
 }
+/** An exposed var: asset parameter docs and range, and the control the live viewer draws for it. */
 export interface VarDef {
     type?: string;
     default?: any;
@@ -81,17 +82,42 @@ export interface VarDef {
     min?: number;
     max?: number;
     options?: string[];
+    /** control label for humans (default: the var name) */
+    label?: string;
+    /** slider step (default: 1 for ints, else derived from the range) */
+    step?: number;
 }
+/** Free-form graph metadata (showcase render presets, editor layout, …). */
+export interface GraphMeta {
+    [key: string]: any;
+}
+/**
+ * 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 when the graph is used as an asset */
+    /** metadata for exposed vars: asset parameters, and the controls the live viewer shows for them */
     params?: Record<string, VarDef>;
     description?: string;
-    meta?: any;
+    meta?: GraphMeta;
 }
 export interface CookContext {
     node: string;

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/host/export_scene.py

@@ -0,0 +1,200 @@
+"""Headless .blend -> static GLB for TopoTopo. Never saves or overwrites the .blend."""
+import json
+import os
+import copy
+import struct
+import sys
+import traceback
+from collections import Counter
+
+import bpy
+
+
+def static_copies():
+    """Bake evaluated geometry/transforms into copies; keep linked, unmodified meshes shared."""
+    scenes = list(bpy.data.scenes)
+    original_scene = bpy.context.window.scene
+    objects = list(dict.fromkeys(obj for scene in scenes for obj in scene.objects))
+    print("TopoTopo objects before export: " + json.dumps(dict(sorted(Counter(o.type for o in objects).items()))), flush=True)
+
+    # Excluded collections must be evaluated too, even though visibility is not an export filter.
+    def enable(layer):
+        layer.exclude = False
+        layer.hide_viewport = False
+        for child in layer.children:
+            enable(child)
+
+    for collection in bpy.data.collections:
+        collection.hide_viewport = False
+    for scene in scenes:
+        for layer in scene.view_layers:
+            enable(layer.layer_collection)
+    for obj in objects:
+        obj.hide_viewport = False
+        obj.hide_render = False
+        obj.hide_set(False)
+
+    copies, worlds, names, data_copies = {}, {}, {}, {}
+    for scene in scenes:
+        bpy.context.window.scene = scene
+        bpy.context.view_layer.update()
+        depsgraph = bpy.context.evaluated_depsgraph_get()
+        for obj in list(scene.objects):
+            if obj in copies:
+                continue
+            evaluated = obj.evaluated_get(depsgraph)
+            worlds[obj] = evaluated.matrix_world.copy()
+            names[obj] = obj.name
+            if obj.type in {'MESH', 'CURVE', 'SURFACE', 'FONT'}:
+                if obj.type == 'MESH' and not obj.modifiers and not obj.data.shape_keys:
+                    if obj.data not in data_copies:
+                        data_copies[obj.data] = obj.data.copy()
+                    mesh = data_copies[obj.data]
+                else:
+                    # Unlike the exporter’s curve path, this also retains unbevelled curve edges.
+                    mesh = bpy.data.meshes.new_from_object(evaluated, preserve_all_data_layers=True, depsgraph=depsgraph)
+                    if mesh is None:
+                        raise RuntimeError("Could not evaluate " + obj.name + " as a mesh")
+                    for key in obj.data.keys():
+                        if key not in mesh:
+                            mesh[key] = obj.data[key]
+                copy = bpy.data.objects.new(obj.name, mesh)
+                for key in obj.keys():
+                    copy[key] = obj[key]
+                for index, slot in enumerate(obj.material_slots):
+                    if index < len(copy.material_slots) and slot.link == 'OBJECT':
+                        copy.material_slots[index].link = 'OBJECT'
+                        copy.material_slots[index].material = slot.material
+            else:
+                copy = obj.copy()
+                copy.animation_data_clear()
+                copy.constraints.clear()
+            copies[obj] = copy
+
+    # Relink copies in the existing collection hierarchy; originals are removed only from this process's memory.
+    parents = {obj: obj.parent for obj in objects}
+    for obj, copy in copies.items():
+        for collection in obj.users_collection:
+            collection.objects.link(copy)
+        copy.parent = copies.get(parents[obj])
+        copy.parent_type = 'OBJECT'
+        copy.matrix_parent_inverse.identity()
+    def depth(obj):
+        return 0 if parents[obj] not in parents else 1 + depth(parents[obj])
+    for obj in sorted(objects, key=depth):
+        copies[obj].matrix_world = worlds[obj]
+    desired_names = [(copies[obj], names[obj]) for obj in objects]
+    for obj in objects:
+        bpy.data.objects.remove(obj, do_unlink=True)
+    for copy, name in desired_names:
+        copy.name = name
+    for scene in scenes:
+        scene.unit_settings.scale_length = 1.0  # apply units once to the exported roots, including collection instances
+    bpy.context.window.scene = original_scene
+    bpy.context.view_layer.update()
+    print("TopoTopo objects after conversion: " + json.dumps(dict(sorted(Counter(o.type for o in copies.values()).items()))), flush=True)
+
+
+def apply_scene_units(output, units):
+    """Scale GLB roots, never prototypes: a collection instance must not apply the unit factor twice."""
+    if all(value == 1.0 for value in units.values()):
+        return
+    with open(output, 'rb') as stream:
+        data = stream.read()
+    magic, version, length = struct.unpack_from('<4sII', data)
+    if magic != b'glTF' or version != 2 or length != len(data):
+        raise RuntimeError('Exporter did not produce a valid GLB container')
+    chunks, offset = [], 12
+    while offset < length:
+        size, kind = struct.unpack_from('<II', data, offset)
+        chunks.append((kind, data[offset + 8:offset + 8 + size]))
+        offset += 8 + size
+    document = json.loads(chunks[0][1])
+    nodes = document.get('nodes', [])
+    originals = copy.deepcopy(nodes)
+    requests = {}
+    for scene in document.get('scenes', []):
+        factor = units.get(scene.get('name'), 1.0)
+        for index, root in enumerate(scene.get('nodes', [])):
+            requests.setdefault(root, {}).setdefault(factor, []).append((scene, index))
+
+    def clone_tree(index):
+        node = copy.deepcopy(originals[index])
+        if 'children' in node:
+            node['children'] = [clone_tree(child) for child in node['children']]
+        nodes.append(node)
+        return len(nodes) - 1
+
+    for root, factors in requests.items():
+        for variant, (factor, references) in enumerate(factors.items()):
+            # Usually roots are unique per scene. If scenes share a root but use different units, share meshes
+            # and copy only the node hierarchy so one scene's conversion cannot alter the other.
+            target = root if variant == 0 else clone_tree(root)
+            for scene, index in references:
+                scene['nodes'][index] = target
+            node = nodes[target]
+            if 'matrix' in node:
+                node['matrix'] = [value * factor if i % 4 != 3 else value for i, value in enumerate(node['matrix'])]
+            else:
+                node['translation'] = [value * factor for value in node.get('translation', [0, 0, 0])]
+                node['scale'] = [value * factor for value in node.get('scale', [1, 1, 1])]
+    payload = json.dumps(document, separators=(',', ':'), ensure_ascii=False).encode('utf8')
+    chunks[0] = (chunks[0][0], payload + b' ' * (-len(payload) % 4))
+    body = b''.join(struct.pack('<II', len(payload), kind) + payload for kind, payload in chunks)
+    with open(output, 'wb') as stream:
+        stream.write(struct.pack('<4sII', b'glTF', 2, 12 + len(body)) + body)
+    print('TopoTopo scene unit scales: ' + json.dumps(units, sort_keys=True), flush=True)
+
+
+def main():
+    args = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else []
+    if len(args) != 1:
+        raise RuntimeError("Expected one output .glb path after --")
+    output = os.path.abspath(args[0])
+    units = {scene.name: scene.unit_settings.scale_length for scene in bpy.data.scenes}
+    static_copies()
+    properties = bpy.ops.export_scene.gltf.get_rna_type().properties
+    kwargs, missing = {}, []
+
+    def option(identifiers, value):
+        # Option identifiers come from RNA, not a version assumption. Aliases cover older exporters.
+        for identifier in identifiers:
+            if identifier in properties:
+                kwargs[identifier] = value
+                return
+        missing.append('/'.join(identifiers))
+
+    for identifiers, value in [
+        (('filepath',), output), (('export_format',), 'GLB'), (('check_existing',), False),
+        (('export_yup',), True), (('export_apply',), True),
+        (('use_mesh_edges', 'export_loose_edges'), True),
+        (('use_mesh_vertices', 'export_loose_points'), True),
+        (('export_extras',), True), (('export_materials',), 'EXPORT'),
+        (('export_image_format',), 'AUTO'), (('export_keep_originals',), False),
+        (('export_cameras',), False), (('export_lights',), False),
+        (('export_animations',), False), (('export_morph',), False), (('export_skins',), False),
+        (('use_selection',), False), (('use_visible',), False), (('use_renderable',), False),
+        (('use_active_collection',), False), (('use_active_collection_with_nested',), False),
+        (('use_active_scene',), False), (('collection',), ''),
+        (('export_hierarchy_full_collections',), True), (('export_hierarchy_flatten_objs',), False),
+        (('export_gpu_instances',), False), (('will_save_settings',), False),
+    ]:
+        option(identifiers, value)
+    print("TopoTopo exporter options set: " + json.dumps(kwargs, sort_keys=True), flush=True)
+    print("TopoTopo exporter options missing: " + json.dumps(missing), flush=True)
+    result = bpy.ops.export_scene.gltf(**kwargs)
+    if 'FINISHED' not in result or not os.path.isfile(output):
+        raise RuntimeError("glTF export did not finish: " + str(result))
+    apply_scene_units(output, units)
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception:
+        traceback.print_exc()
+        print("TopoTopo .blend conversion failed", file=sys.stderr, flush=True)
+        # Blender otherwise reports many Python errors with exit code zero.
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os._exit(1)

package/dist/host/node.d.ts

@@ -5,6 +5,8 @@ import type { NodePoolOptions } from './pool.ts';
  * sources (src/host) and for the built package (dist/host): both sit two levels below the package root.
  */
 export declare const SHELF_DIR: string;
+/** Executable lookup shared by conversion and integration tests. An unavailable installation returns null. */
+export declare function findBlender(): Promise<string | null>;
 export interface NodeHostOptions {
     baseDir?: string;
     /** shelf directory (default SHELF_DIR), or false for an engine without the shelf */
@@ -16,5 +18,11 @@ export interface NodeHostOptions {
     workers?: number;
     /** further pool settings for a host with its own pool (idleMs, minElements) */
     pool?: Partial<NodePoolOptions>;
+    /** Optional diagnostics for actual Blender conversions (not version probes or cache hits). */
+    onBlenderRun?: (result: {
+        executable: string;
+        durationMs: number;
+        output: string;
+    }) => void;
 }
 export declare function createNodeHost(opts?: NodeHostOptions): Host;

package/dist/host/node.js

@@ -3,6 +3,8 @@ import vm from 'node:vm';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { createNodePool, poolOptionsFromEnv } from './pool.js';
 import { REALM_CONTROL, SCRIPT_REALM_SETUP } from '../core/snippet-lib.js';
@@ -33,11 +35,55 @@ function filterRealmRejections() {
  * sources (src/host) and for the built package (dist/host): both sit two levels below the package root.
  */
 export const SHELF_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../shelf');
+/** No shell: executable paths and file names are passed as separate arguments on every platform. */
+function runBlender(executable, args, timeout) {
+    return new Promise((resolve, reject) => {
+        execFile(executable, args, { timeout, windowsHide: true, maxBuffer: 16 * 1024 * 1024, killSignal: 'SIGKILL' }, (error, stdout, stderr) => {
+            const output = `${stdout}\n${stderr}`.trim();
+            if (error) {
+                const tail = output.split(/\r?\n/).slice(-40).join('\n');
+                const reason = error.message.split(/\r?\n/)[0]; // execFile's message may itself contain all of stderr
+                reject(new Error(`Blender failed (exit code ${error.code ?? 'none'}${error.signal ? `, signal ${error.signal}` : ''}${error.killed ? ', timed out or killed' : ''}): ${reason}\n${tail}`));
+            }
+            else
+                resolve(output);
+        });
+    });
+}
+/** Executable lookup shared by conversion and integration tests. An unavailable installation returns null. */
+export async function findBlender() {
+    const candidates = [process.env.TOPOTOPO_BLENDER, 'blender'].filter((p) => !!p);
+    const foundation = path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Blender Foundation');
+    try {
+        const versions = fs.readdirSync(foundation, { withFileTypes: true }).filter((e) => e.isDirectory() && /^Blender /i.test(e.name));
+        versions.sort((a, b) => b.name.localeCompare(a.name, 'en', { numeric: true }));
+        candidates.push(...versions.map((e) => path.join(foundation, e.name, 'blender.exe')));
+    }
+    catch { /* normal on non-Windows hosts, or without a Foundation install */ }
+    candidates.push('C:\\Program Files (x86)\\Steam\\steamapps\\common\\Blender\\blender.exe', '/Applications/Blender.app/Contents/MacOS/Blender', '/usr/bin/blender', '/snap/bin/blender');
+    for (const candidate of new Set(candidates)) {
+        try {
+            await runBlender(candidate, ['--version'], 10_000);
+            return candidate;
+        }
+        catch { /* try the next installation */ }
+    }
+    return null;
+}
+function blenderScript() {
+    for (const relative of ['./export_scene.py', '../../integrations/blender/export_scene.py']) {
+        const file = fileURLToPath(new URL(relative, import.meta.url));
+        if (fs.existsSync(file))
+            return file;
+    }
+    throw new Error('Blender conversion script export_scene.py is missing from this TopoTopo installation');
+}
 /** opts.shelf: shelf directory (default SHELF_DIR), or false for an engine without the shelf. */
 /** The process-wide pool of hosts created with the environment's settings (created lazily: no thread until used). */
 let envPool = null;
 export function createNodeHost(opts = {}) {
     const baseDir = opts.baseDir ?? process.cwd();
+    const conversions = new Map();
     let pool;
     if (opts.workers === undefined && !opts.pool) {
         if (envPool === null)
@@ -202,6 +248,74 @@ export function createNodeHost(opts = {}) {
                 return 'missing';
             }
         },
+        isDirectory(p) {
+            try {
+                return fs.statSync(this.resolvePath(p)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        listDir(p) {
+            const dir = this.resolvePath(p);
+            return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() || (e.isSymbolicLink() && fs.statSync(path.join(dir, e.name)).isFile()))
+                .map((e) => e.name).sort((a, b) => a.localeCompare(b, 'en'));
+        },
+        async convertFile(p, target) {
+            if (target !== 'glb')
+                throw new Error(`unsupported conversion target "${target}"`);
+            const absolute = this.resolvePath(p);
+            if (/^https?:\/\//.test(absolute))
+                throw new Error('.blend conversion needs a local file path');
+            const stamp = this.fileStamp(absolute);
+            if (stamp === 'missing')
+                throw new Error(`cannot read "${absolute}": file is missing`);
+            const key = createHash('sha256').update(JSON.stringify([absolute, stamp])).digest('hex');
+            const cacheDir = path.resolve(baseDir, '.cache', 'blend');
+            const cached = path.join(cacheDir, `${key}.glb`);
+            // In-flight conversions of the same source share a process, including concurrent file nodes.
+            let job = conversions.get(key);
+            if (!job) {
+                job = (async () => {
+                    try {
+                        return new Uint8Array(await fs.promises.readFile(cached));
+                    }
+                    catch (e) {
+                        if (e.code !== 'ENOENT')
+                            throw e;
+                    }
+                    const executable = await findBlender();
+                    if (!executable)
+                        throw new Error('Blender was not found. Set TOPOTOPO_BLENDER to its executable, or install Blender from https://www.blender.org/download/');
+                    const seconds = Number(process.env.TOPOTOPO_BLENDER_TIMEOUT ?? 300);
+                    if (!Number.isFinite(seconds) || seconds <= 0 || seconds * 1000 > 2_147_483_647)
+                        throw new Error('TOPOTOPO_BLENDER_TIMEOUT must be a positive number of seconds (default 300)');
+                    await fs.promises.mkdir(cacheDir, { recursive: true });
+                    const tempDir = await fs.promises.mkdtemp(path.join(cacheDir, 'convert-'));
+                    try {
+                        const outputFile = path.join(tempDir, 'scene.glb');
+                        const start = performance.now();
+                        // Factory settings keep user add-ons/startup handlers out of deterministic batch conversions.
+                        const output = await runBlender(executable, ['--factory-startup', '--disable-autoexec', '-b', absolute, '--python', blenderScript(), '--', outputFile], Math.ceil(seconds * 1000));
+                        opts.onBlenderRun?.({ executable, durationMs: performance.now() - start, output });
+                        const bytes = new Uint8Array(await fs.promises.readFile(outputFile));
+                        await fs.promises.rename(outputFile, cached);
+                        return bytes;
+                    }
+                    finally {
+                        await fs.promises.rm(tempDir, { recursive: true, force: true });
+                    }
+                })();
+                conversions.set(key, job);
+            }
+            try {
+                return await job;
+            }
+            finally {
+                if (conversions.get(key) === job)
+                    conversions.delete(key);
+            }
+        },
         compile(source) {
             if (source === 'globalThis')
                 return realmGlobal;

package/dist/host/types.d.ts

@@ -95,6 +95,11 @@ export interface Host {
     /** A string that changes when the file changes (mtime+size), for cache keys. */
     fileStamp(path: string): string;
     resolvePath(path: string): string;
+    /** Optional local-directory support. listDir returns immediate file names only (no subdirectories). */
+    isDirectory?(path: string): boolean;
+    listDir?(path: string): string[];
+    /** Convert a local source file to GLB (Node: .blend through headless Blender). Absent in browser/kernel hosts. */
+    convertFile?(path: string, target: 'glb'): Promise<Uint8Array>;
     /**
      * Compile JS source inside the scripting realm (which has the snippet library
      * installed) and return the resulting value (usually a function). The realm is set up with

package/dist/inspect.js

@@ -130,8 +130,11 @@ export function summarize(g) {
         if (!t.map.size)
             continue;
         const items = [...t.map].map(([k, a]) => {
-            if (cls === 'detail')
-                return `${k} ${typeCode(a)} = ${fmtAttr(a, 0)}`;
+            if (cls === 'detail') {
+                // the summary stays readable: long values (e.g. the materials JSON) are cut; detail "attributes" shows them whole
+                const v = fmtAttr(a, 0);
+                return `${k} ${typeCode(a)} = ${v.length > 120 ? `${v.slice(0, 100)}… (${v.length} chars)` : v}`;
+            }
             if (a.isArray)
                 return `${k} ${a.type} (${arrayLens(a, t.count)})`;
             if (a.type === 'string') {

package/dist/io/common.d.ts

@@ -22,6 +22,12 @@ export interface ExportOptions {
     quantize?: boolean;
     /** glTF: write materials from the prim "material" attribute and the detail table (default true) */
     materials?: boolean;
+    /**
+     * glTF: a named material's base colour is the factor even where Cd varies (COLOR_0 is still written). For engines
+     * whose default materials ignore vertex colours (Unreal Interchange), where glTF's white factor × COLOR_0 imports
+     * white; spec viewers then show factor × COLOR_0. The unreal_landscape bundle sets it. Default false.
+     */
+    materialColorWins?: boolean;
     /** glTF: polylines as one LINE_STRIP per curve ('strip', default) or one LINES primitive ('lines') */
     lineMode?: 'strip' | 'lines';
     /** csv / points JSON: point attributes to write (names or a comma/space separated list; default all) */