fluidcad 0.0.33 → 0.0.35

package/server/dist/fluidcad-server.js

@@ -1,91 +1,221 @@
+import { createHash } from 'crypto';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import { ViteManager } from "./vite-manager.js";
+import { LocalSceneHost } from "./host/local-scene-host.js";
 import { normalizePath } from "./normalize-path.js";
 import { BreakpointHit } from '../../lib/dist/common/breakpoint-hit.js';
+import { createParamRegistry, getParamRegistry } from '../../lib/dist/index.js';
+/**
+ * `sessionId` is the per-renderer state key. In desktop mode it equals the
+ * file path being edited (so per-file state survives switching files). In
+ * hub mode it's a WebSocket connection UUID (so concurrent viewers stay
+ * isolated). Map keys called `sessionId` accept either flavour.
+ */
 export class FluidCadServer {
-    viteManager = new ViteManager();
+    host;
     sceneManager;
+    // Per-session render output, scene cache, and param overrides. Desktop's
+    // sessionId is the normalized filePath; hub mode's sessionId is the WS
+    // connection UUID. Maps must be cleared via `destroySession` on hub-side
+    // disconnect to avoid leaks.
     previousScenes = new Map();
     renderingCache = new Map();
+    // Records the last successful render per session as `{ paramsHash, data }`.
+    // Any subsequent render request short-circuits when the new params hash to
+    // the same value — avoids redundant OCC work when desktop producers see the
+    // same code+params, or hub clients re-emit the same param mutation.
+    lastRendered = new Map();
+    paramOverrides = new Map();
+    // What file each session is rendering. For desktop, sessionId === filePath
+    // (set lazily on first processFile call). For hub, set explicitly via
+    // createSession with the bundle's manifest entry.
+    sessionFiles = new Map();
+    // Serializes OCC calls across all sessions. OCC isn't thread-safe and we
+    // share one engine instance per host process; concurrent param edits from
+    // multiple hub clients have to queue. Promise-chain pattern: each render
+    // awaits the previous one's settlement before starting.
+    renderMutex = Promise.resolve();
     currentFileName = '';
     currentFilePath = '';
+    lastRollbackStop = -1;
+    compileError = null;
+    constructor(host = new LocalSceneHost()) {
+        this.host = host;
+    }
+    getCurrentCode() {
+        if (!this.currentFileName)
+            return null;
+        return this.host.getBuffer(this.currentFileName);
+    }
     async init(workspacePath) {
-        await this.viteManager.init(workspacePath);
+        await this.host.init(workspacePath);
         const initFilePath = normalizePath(join(workspacePath, 'init.js'));
         if (existsSync(initFilePath)) {
-            const { default: _sceneManager } = await this.viteManager.loadModule(initFilePath);
+            const { default: _sceneManager } = await this.host.loadModule(initFilePath);
             this.sceneManager = await _sceneManager;
         }
     }
-    async processFile(filePath, ignoreCache = false) {
-        if (!this.sceneManager) {
-            return null;
+    /**
+     * Capture an already-initialized SceneManager. Used by the hub-mode entry
+     * after running the packed bundle once to materialize the engine globals.
+     */
+    setSceneManager(manager) {
+        this.sceneManager = manager;
+    }
+    /**
+     * Run `fn` with exclusive access to the OCC engine. The mutex is process-
+     * wide: in hub mode concurrent client sessions land here too. Order is
+     * first-come, first-served via Promise chain.
+     */
+    async serialized(fn) {
+        const prev = this.renderMutex;
+        let release = () => { };
+        const next = new Promise((resolve) => { release = resolve; });
+        this.renderMutex = next;
+        try {
+            await prev;
+            return await fn();
         }
-        filePath = normalizePath(filePath);
-        const normalizedFileName = filePath.replace('virtual:live-render:', '');
-        this.currentFileName = normalizedFileName;
-        this.currentFilePath = filePath;
-        if (!ignoreCache) {
-            const fromCache = this.renderingCache.get(normalizedFileName);
-            if (fromCache) {
-                return {
-                    absPath: normalizedFileName,
-                    result: fromCache,
-                    rollbackStop: fromCache.length - 1,
-                };
-            }
+        finally {
+            release();
         }
-        try {
-            let scene = this.sceneManager.startScene();
-            this.sceneManager.setCurrentFile(normalizedFileName);
-            this.viteManager.invalidateModule();
-            let breakpointHit = false;
-            try {
-                await this.viteManager.loadModule(filePath);
+    }
+    // ---------------------------------------------------------------------------
+    // Session lifecycle (hub mode)
+    // ---------------------------------------------------------------------------
+    createSession(sessionId, entryFilePath) {
+        this.sessionFiles.set(sessionId, normalizePath(entryFilePath));
+    }
+    destroySession(sessionId) {
+        this.previousScenes.delete(sessionId);
+        this.renderingCache.delete(sessionId);
+        this.lastRendered.delete(sessionId);
+        this.paramOverrides.delete(sessionId);
+        this.sessionFiles.delete(sessionId);
+    }
+    /**
+     * Re-render the session's entry, ignoring caches. Hub clients call this
+     * after editing a param. Returns the fresh render or null if no manager.
+     */
+    async recomputeForSession(sessionId) {
+        const filePath = this.sessionFiles.get(sessionId);
+        if (!filePath)
+            return null;
+        this.renderingCache.delete(sessionId);
+        this.lastRendered.delete(sessionId);
+        return this.processFileInternal(sessionId, filePath, true);
+    }
+    // ---------------------------------------------------------------------------
+    // Render — internal core used by both desktop and hub entry points
+    // ---------------------------------------------------------------------------
+    async processFileInternal(sessionId, filePath, ignoreCache) {
+        return this.serialized(async () => {
+            if (!this.sceneManager) {
+                return null;
             }
-            catch (e) {
-                if (e instanceof BreakpointHit) {
-                    breakpointHit = true;
-                }
-                else {
-                    throw e;
+            const normalizedFileName = filePath.replace('virtual:live-render:', '');
+            this.currentFileName = normalizedFileName;
+            this.currentFilePath = filePath;
+            if (!ignoreCache) {
+                const fromCache = this.renderingCache.get(sessionId);
+                if (fromCache) {
+                    this.lastRollbackStop = fromCache.length - 1;
+                    this.compileError = null;
+                    return {
+                        absPath: normalizedFileName,
+                        result: fromCache,
+                        rollbackStop: fromCache.length - 1,
+                    };
                 }
             }
-            if (this.previousScenes.has(normalizedFileName)) {
-                const previousScene = this.previousScenes.get(normalizedFileName);
-                scene = this.sceneManager.compare(previousScene, scene);
-            }
-            this.previousScenes.set(normalizedFileName, scene);
-            this.sceneManager.renderScene(scene);
-            const result = scene.getRenderedObjects();
-            for (const obj of result) {
-                if (obj.sourceLocation) {
-                    obj.sourceLocation.filePath = obj.sourceLocation.filePath.replace('virtual:live-render:', '');
+            try {
+                let scene = this.sceneManager.startScene();
+                this.sceneManager.setCurrentFile(normalizedFileName);
+                this.host.invalidateModule();
+                const registry = createParamRegistry();
+                const overrides = this.paramOverrides.get(sessionId);
+                if (overrides) {
+                    registry.setOverrides(overrides);
+                }
+                let breakpointHit = false;
+                try {
+                    await this.host.loadModule(filePath);
+                }
+                catch (e) {
+                    if (e instanceof BreakpointHit) {
+                        breakpointHit = true;
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+                const params = getParamRegistry().getDefinitions();
+                if (this.previousScenes.has(sessionId)) {
+                    const previousScene = this.previousScenes.get(sessionId);
+                    scene = this.sceneManager.compare(previousScene, scene);
+                }
+                this.previousScenes.set(sessionId, scene);
+                this.sceneManager.renderScene(scene);
+                const result = scene.getRenderedObjects();
+                for (const obj of result) {
+                    if (obj.sourceLocation) {
+                        obj.sourceLocation.filePath = obj.sourceLocation.filePath.replace('virtual:live-render:', '');
+                    }
                 }
+                if (!filePath.startsWith('virtual:live-render')) {
+                    this.renderingCache.set(sessionId, result);
+                }
+                this.lastRollbackStop = result.length - 1;
+                this.compileError = null;
+                return {
+                    absPath: normalizedFileName,
+                    result,
+                    rollbackStop: result.length - 1,
+                    breakpointHit,
+                    params,
+                };
             }
-            if (!filePath.startsWith('virtual:live-render')) {
-                this.renderingCache.set(normalizedFileName, result);
+            catch (error) {
+                this.host.invalidateModule();
+                console.log('Error processing file:', error);
+                throw error;
             }
-            return {
-                absPath: normalizedFileName,
-                result,
-                rollbackStop: result.length - 1,
-                breakpointHit,
-            };
-        }
-        catch (error) {
-            this.viteManager.invalidateModule();
-            console.log('Error processing file:', error);
-            throw error;
-        }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Desktop API — sessionId is implicit (filePath)
+    // ---------------------------------------------------------------------------
+    async processFile(filePath, ignoreCache = false) {
+        filePath = normalizePath(filePath);
+        const sessionId = filePath.replace('virtual:live-render:', '');
+        this.sessionFiles.set(sessionId, sessionId);
+        return this.processFileInternal(sessionId, filePath, ignoreCache);
     }
     async updateLiveCode(fileName, code) {
         fileName = normalizePath(fileName);
+        // Dedup against the last successful render. Multiple producers (editor
+        // live-update, save-triggered process-file, watcher, MCP /api/render)
+        // commonly hand us identical content; without this short-circuit each
+        // would trigger a redundant OCC pass. paramsHash mixes code content with
+        // current param overrides so a param change invalidates the cache.
+        const paramsHash = this.computeParamsHash(fileName, code);
+        const cached = this.lastRendered.get(fileName);
+        if (cached && cached.paramsHash === paramsHash) {
+            this.compileError = null;
+            this.currentFileName = fileName;
+            this.currentFilePath = `virtual:live-render:${fileName}`;
+            this.lastRollbackStop = cached.data.rollbackStop;
+            return cached.data;
+        }
         const id = `virtual:live-render:${fileName}`;
-        this.viteManager.setBuffer(id, code);
+        this.host.setBuffer(id, code);
         this.renderingCache.delete(fileName);
-        return this.processFile(id, true);
+        this.sessionFiles.set(fileName, fileName);
+        const result = await this.processFileInternal(fileName, id, true);
+        if (result) {
+            this.lastRendered.set(fileName, { paramsHash, data: result });
+        }
+        return result;
     }
     async rollbackFromUI(index) {
         return this.rollback(this.currentFileName, index);
@@ -94,9 +224,10 @@ export class FluidCadServer {
         if (!this.currentFilePath) {
             return null;
         }
-        this.previousScenes.delete(this.currentFileName);
-        this.renderingCache.delete(this.currentFileName);
-        return this.processFile(this.currentFilePath, true);
+        const sessionId = this.currentFileName;
+        this.renderingCache.delete(sessionId);
+        this.lastRendered.delete(sessionId);
+        return this.processFileInternal(sessionId, this.currentFilePath, true);
     }
     async rollback(fileName, index) {
         if (!this.sceneManager) {
@@ -110,6 +241,7 @@ export class FluidCadServer {
         const rollbackIndex = index >= totalObjects - 1 ? totalObjects - 1 : index;
         this.sceneManager.rollbackScene(scene, rollbackIndex);
         const result = scene.getRenderedObjects();
+        this.lastRollbackStop = index;
         return {
             absPath: fileName,
             result,
@@ -173,4 +305,160 @@ export class FluidCadServer {
         }
         return this.sceneManager.hitTest(scene, shapeId, rayOrigin, rayDir, edgeThreshold);
     }
+    hitTestForSession(sessionId, shapeId, rayOrigin, rayDir, edgeThreshold) {
+        if (!this.sceneManager) {
+            return null;
+        }
+        const scene = this.previousScenes.get(sessionId);
+        if (!scene) {
+            return null;
+        }
+        return this.sceneManager.hitTest(scene, shapeId, rayOrigin, rayDir, edgeThreshold);
+    }
+    setCompileError(err) {
+        this.compileError = err;
+    }
+    getCompileError() {
+        return this.compileError;
+    }
+    setParam(sessionId, label, value) {
+        sessionId = normalizePath(sessionId);
+        if (!this.paramOverrides.has(sessionId)) {
+            this.paramOverrides.set(sessionId, new Map());
+        }
+        this.paramOverrides.get(sessionId).set(label, value);
+        this.lastRendered.delete(sessionId);
+    }
+    resetParams(sessionId) {
+        sessionId = normalizePath(sessionId);
+        this.paramOverrides.delete(sessionId);
+        this.lastRendered.delete(sessionId);
+    }
+    getParamOverrides(sessionId) {
+        const map = this.paramOverrides.get(normalizePath(sessionId));
+        if (!map)
+            return {};
+        return Object.fromEntries(map);
+    }
+    getCurrentFileName() {
+        return this.currentFileName;
+    }
+    /**
+     * Test-only seam: stage a scene under the given file name so the inspection
+     * accessors can read it without running the vite pipeline. Production code
+     * never calls this — `processFile` populates the same map.
+     */
+    _setSceneForTesting(fileName, scene, rollbackStop = -1) {
+        this.currentFileName = fileName;
+        this.previousScenes.set(fileName, scene);
+        this.lastRollbackStop = rollbackStop;
+    }
+    getSceneSummary() {
+        if (!this.currentFileName) {
+            return null;
+        }
+        const scene = this.previousScenes.get(this.currentFileName);
+        if (!scene) {
+            return null;
+        }
+        const rendered = scene.getRenderedObjects();
+        const objects = rendered.map((r, index) => ({
+            index,
+            id: r.id,
+            kind: r.type,
+            uniqueKind: r.uniqueType,
+            name: r.name,
+            params: sanitizeParams(r.object),
+            sourceLocation: r.sourceLocation,
+            shapeIds: (r.sceneShapes ?? []).map((s) => s.shapeId),
+            fromCache: !!r.fromCache,
+            hasError: !!r.hasError,
+            errorMessage: r.errorMessage,
+            containerId: r.parentId ?? null,
+            isContainer: !!r.isContainer,
+            visible: r.visible !== false,
+        }));
+        return {
+            schemaVersion: 1,
+            file: this.currentFileName,
+            objects,
+            rollbackStop: this.lastRollbackStop,
+            compileError: this.compileError,
+        };
+    }
+    getShapesList() {
+        if (!this.currentFileName) {
+            return null;
+        }
+        const scene = this.previousScenes.get(this.currentFileName);
+        if (!scene) {
+            return null;
+        }
+        const rendered = scene.getRenderedObjects();
+        const shapes = [];
+        for (const r of rendered) {
+            const sceneShapes = (r.sceneShapes ?? []);
+            for (const s of sceneShapes) {
+                shapes.push({
+                    shapeId: s.shapeId,
+                    type: s.shapeType,
+                    sceneObjectId: r.id,
+                });
+            }
+        }
+        return { shapes };
+    }
+    /**
+     * Compose a stable cache key over the rendering inputs: the source bytes
+     * being rendered plus the param overrides currently in effect for the
+     * session. Param changes flip the hash so cached entries don't shadow a
+     * recompute, even when the code text is byte-identical.
+     */
+    computeParamsHash(sessionId, codeOrBundle) {
+        const overrides = this.paramOverrides.get(sessionId);
+        const sortedEntries = overrides ? [...overrides.entries()].sort(([a], [b]) => a.localeCompare(b)) : [];
+        const normalized = codeOrBundle.replace(/\r\n/g, '\n');
+        return createHash('sha1')
+            .update(normalized)
+            .update('\0')
+            .update(JSON.stringify(sortedEntries))
+            .digest('hex');
+    }
+}
+const MAX_PARAM_DEPTH = 6;
+function sanitizeParams(value, depth = 0) {
+    if (value === null || value === undefined) {
+        return value ?? null;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (depth >= MAX_PARAM_DEPTH) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => sanitizeParams(v, depth + 1));
+    }
+    if (typeof value === 'object') {
+        // A scene-object reference. Render as { ref: id } so the agent can chase
+        // it through other tools without us shipping the whole subtree.
+        const maybeId = value.id;
+        const isSceneObjectRef = typeof maybeId === 'string' &&
+            typeof value.getType === 'function';
+        if (isSceneObjectRef) {
+            return { ref: maybeId };
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === 'function') {
+                continue;
+            }
+            out[k] = sanitizeParams(v, depth + 1);
+        }
+        return out;
+    }
+    return null;
 }

package/server/dist/global-registry.d.ts

@@ -0,0 +1,30 @@
+export declare const REGISTRY_DIR_NAME = ".fluidcad";
+export declare const REGISTRY_FILE_NAME = "instances.json";
+export type RegistryEntry = {
+    workspacePath: string;
+    port: number;
+    pid: number;
+    version: string;
+    startedAt: string;
+};
+export declare function registryFilePath(): string;
+/**
+ * Add or replace an entry keyed by `workspacePath`. A new entry for an
+ * existing workspace (second window) supersedes the prior one.
+ */
+export declare function addInstance(entry: RegistryEntry): void;
+/**
+ * Remove the entry that matches both workspacePath and pid. Matching on pid
+ * prevents a clean shutdown from clobbering a freshly-restarted instance.
+ */
+export declare function removeInstance(workspacePath: string, pid: number): void;
+/**
+ * Read the registry, prune entries whose PIDs are no longer alive, and
+ * persist the pruned result. Returns the live entries.
+ *
+ * Liveness is `process.kill(pid, 0)` — sending signal 0 doesn't deliver
+ * anything but throws ESRCH if the process is gone. EPERM (running but owned
+ * by another user) counts as alive.
+ */
+export declare function readInstances(): RegistryEntry[];
+export declare function isPidAlive(pid: number): boolean;

package/server/dist/global-registry.js

@@ -0,0 +1,126 @@
+// Global instance registry at ~/.fluidcad/instances.json — lets a single MCP
+// process enumerate every running FluidCAD workspace on this machine.
+//
+// Read-modify-write is not crash-safe across multiple writers (we have no
+// file lock), but the worst case is a dropped registry entry that the next
+// successful write or stale-prune restores. Atomicity for the file itself is
+// via tmp + rename.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+export const REGISTRY_DIR_NAME = '.fluidcad';
+export const REGISTRY_FILE_NAME = 'instances.json';
+const EMPTY = { schemaVersion: 1, instances: [] };
+function registryDir() {
+    return path.join(os.homedir(), REGISTRY_DIR_NAME);
+}
+export function registryFilePath() {
+    return path.join(registryDir(), REGISTRY_FILE_NAME);
+}
+function readRaw() {
+    try {
+        const raw = fs.readFileSync(registryFilePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isRegistryFile(parsed)) {
+            return parsed;
+        }
+        return EMPTY;
+    }
+    catch {
+        return EMPTY;
+    }
+}
+function writeRaw(file) {
+    const dir = registryDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const destination = registryFilePath();
+    const tmp = path.join(dir, `${REGISTRY_FILE_NAME}.${process.pid}.tmp`);
+    const payload = JSON.stringify(file, null, 2) + '\n';
+    fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o644 });
+    fs.renameSync(tmp, destination);
+}
+/**
+ * Add or replace an entry keyed by `workspacePath`. A new entry for an
+ * existing workspace (second window) supersedes the prior one.
+ */
+export function addInstance(entry) {
+    const file = readRaw();
+    const filtered = file.instances.filter((e) => e.workspacePath !== entry.workspacePath);
+    filtered.push(entry);
+    writeRaw({ schemaVersion: 1, instances: filtered });
+}
+/**
+ * Remove the entry that matches both workspacePath and pid. Matching on pid
+ * prevents a clean shutdown from clobbering a freshly-restarted instance.
+ */
+export function removeInstance(workspacePath, pid) {
+    const file = readRaw();
+    const filtered = file.instances.filter((e) => !(e.workspacePath === workspacePath && e.pid === pid));
+    if (filtered.length === file.instances.length) {
+        return;
+    }
+    writeRaw({ schemaVersion: 1, instances: filtered });
+}
+/**
+ * Read the registry, prune entries whose PIDs are no longer alive, and
+ * persist the pruned result. Returns the live entries.
+ *
+ * Liveness is `process.kill(pid, 0)` — sending signal 0 doesn't deliver
+ * anything but throws ESRCH if the process is gone. EPERM (running but owned
+ * by another user) counts as alive.
+ */
+export function readInstances() {
+    const file = readRaw();
+    const alive = [];
+    const dead = [];
+    for (const entry of file.instances) {
+        if (isPidAlive(entry.pid)) {
+            alive.push(entry);
+        }
+        else {
+            dead.push(entry);
+        }
+    }
+    if (dead.length > 0) {
+        try {
+            writeRaw({ schemaVersion: 1, instances: alive });
+        }
+        catch {
+            // Pruning is best-effort; readers still get the live set.
+        }
+    }
+    return alive;
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err && err.code === 'EPERM') {
+            return true;
+        }
+        return false;
+    }
+}
+function isRegistryFile(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    if (v.schemaVersion !== 1 || !Array.isArray(v.instances)) {
+        return false;
+    }
+    return v.instances.every(isRegistryEntry);
+}
+function isRegistryEntry(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (typeof v.workspacePath === 'string' &&
+        typeof v.port === 'number' &&
+        typeof v.pid === 'number' &&
+        typeof v.version === 'string' &&
+        typeof v.startedAt === 'string');
+}

package/server/dist/host/blocked-imports.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Node built-in modules that user `.fluid.js` code must not import. Same set
+ * enforced by LocalSceneHost (at SSR transform time) and the model packer
+ * (at bundle time) so a packed model can't smuggle in capabilities a live
+ * workspace would have rejected.
+ */
+export declare const BLOCKED_NODE_MODULES: Set<string>;
+export declare function getBlockedNodeModule(id: string): string | null;

package/server/dist/host/blocked-imports.js

@@ -0,0 +1,30 @@
+/**
+ * Node built-in modules that user `.fluid.js` code must not import. Same set
+ * enforced by LocalSceneHost (at SSR transform time) and the model packer
+ * (at bundle time) so a packed model can't smuggle in capabilities a live
+ * workspace would have rejected.
+ */
+export const BLOCKED_NODE_MODULES = new Set([
+    'fs',
+    'child_process',
+    'net',
+    'dgram',
+    'tls',
+    'http',
+    'https',
+    'http2',
+    'os',
+    'worker_threads',
+    'vm',
+    'cluster',
+    'dns',
+    'module',
+]);
+export function getBlockedNodeModule(id) {
+    let name = id;
+    if (name.startsWith('node:')) {
+        name = name.slice(5);
+    }
+    const baseName = name.split('/')[0];
+    return BLOCKED_NODE_MODULES.has(baseName) ? baseName : null;
+}

package/server/dist/{vite-manager.d.ts → host/local-scene-host.d.ts}

@@ -1,10 +1,12 @@
 import { type ViteDevServer } from 'vite';
-export declare class ViteManager {
+import type { SceneHost } from './scene-host.ts';
+export declare class LocalSceneHost implements SceneHost {
     server: ViteDevServer;
     private rootPath;
     private buffers;
     init(rootPath: string): Promise<void>;
     setBuffer(id: string, code: string): void;
+    getBuffer(fileName: string): string | null;
     loadModule(filePath: string): Promise<Record<string, any>>;
     invalidateModule(): void;
 }