dsh-cad 0.2.0

package/lib/image/profile.js

@@ -0,0 +1,218 @@
+/** Otsu's threshold for a luma image. */
+export function otsuThreshold(gray) {
+    const histogram = new Array(256).fill(0);
+    for (const value of gray)
+        histogram[value]++;
+    const total = gray.length;
+    let sum = 0;
+    for (let t = 0; t < 256; t++)
+        sum += t * histogram[t];
+    let sumB = 0;
+    let countB = 0;
+    let best = 0;
+    let bestThreshold = 127;
+    for (let t = 0; t < 256; t++) {
+        countB += histogram[t];
+        if (countB === 0)
+            continue;
+        const countF = total - countB;
+        if (countF === 0)
+            break;
+        sumB += t * histogram[t];
+        const meanB = sumB / countB;
+        const meanF = (sum - sumB) / countF;
+        const between = countB * countF * (meanB - meanF) * (meanB - meanF);
+        if (between > best) {
+            best = between;
+            bestThreshold = t;
+        }
+    }
+    return bestThreshold;
+}
+/** Connected components over a binary mask (4-connectivity, iterative flood). */
+function components(mask, width, height) {
+    const labels = new Int32Array(mask.length).fill(-1);
+    const groups = [];
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] !== 1 || labels[start] !== -1)
+            continue;
+        const group = [];
+        const stack = [start];
+        labels[start] = groups.length;
+        while (stack.length > 0) {
+            const index = stack.pop();
+            group.push(index);
+            const x = index % width;
+            const y = (index - x) / width;
+            if (x > 0 && mask[index - 1] === 1 && labels[index - 1] === -1) {
+                labels[index - 1] = groups.length;
+                stack.push(index - 1);
+            }
+            if (x < width - 1 && mask[index + 1] === 1 && labels[index + 1] === -1) {
+                labels[index + 1] = groups.length;
+                stack.push(index + 1);
+            }
+            if (y > 0 && mask[index - width] === 1 && labels[index - width] === -1) {
+                labels[index - width] = groups.length;
+                stack.push(index - width);
+            }
+            if (y < height - 1 && mask[index + width] === 1 && labels[index + width] === -1) {
+                labels[index + width] = groups.length;
+                stack.push(index + width);
+            }
+        }
+        groups.push(group);
+    }
+    return groups;
+}
+/** Moore-neighbor boundary trace of one labeled component (outer contour). */
+function traceBoundary(labels, width, height, label, start) {
+    // 8 neighbors clockwise starting from east; backtrack is tracked as pixel
+    // coordinates and re-expressed relative to the current pixel each step.
+    const dirs = [[1, 0], [1, 1], [0, 1], [-1, 1], [-1, 0], [-1, -1], [0, -1], [1, -1]];
+    const at = (x, y) => {
+        if (x < 0 || y < 0 || x >= width || y >= height)
+            return -1;
+        return labels[y * width + x];
+    };
+    const dirIndex = (dx, dy) => {
+        for (let i = 0; i < 8; i++)
+            if (dirs[i][0] === dx && dirs[i][1] === dy)
+                return i;
+        return 0;
+    };
+    const sy = Math.floor(start / width);
+    const sx = start - sy * width;
+    // The scan found the leftmost foreground pixel of its row, so west is background.
+    let bx = sx - 1;
+    let by = sy;
+    const boundary = [sx, sy];
+    let px = sx;
+    let py = sy;
+    for (let step = 0, maxSteps = 8 * width * height + 16; step < maxSteps; step++) {
+        const origin = dirIndex(bx - px, by - py);
+        let found = -1;
+        for (let k = 1; k <= 8; k++) {
+            const d = (origin + k) % 8;
+            if (at(px + dirs[d][0], py + dirs[d][1]) === label) {
+                found = d;
+                break;
+            }
+        }
+        if (found === -1)
+            break; // isolated single pixel
+        const previous = (found + 7) % 8;
+        bx = px + dirs[previous][0];
+        by = py + dirs[previous][1];
+        px += dirs[found][0];
+        py += dirs[found][1];
+        if (px === sx && py === sy)
+            break;
+        boundary.push(px, py);
+    }
+    return boundary;
+}
+function perpendicularDistance(point, index, ax, ay, bx, by) {
+    const px = point[index];
+    const py = point[index + 1];
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lengthSquared = dx * dx + dy * dy;
+    if (lengthSquared === 0)
+        return Math.hypot(px - ax, py - ay);
+    const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / lengthSquared));
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+/** RDP over [from, to]; returns kept indices (inclusive). */
+function rdpRange(boundary, from, to, tolerance) {
+    const keep = [];
+    const stack = [[from, to]];
+    keep.push(from, to);
+    while (stack.length > 0) {
+        const [start, end] = stack.pop();
+        let maxDistance = -1;
+        let split = -1;
+        const ax = boundary[start * 2];
+        const ay = boundary[start * 2 + 1];
+        const bx = boundary[end * 2];
+        const by = boundary[end * 2 + 1];
+        for (let i = start + 1; i < end; i++) {
+            const distance = perpendicularDistance(boundary, i * 2, ax, ay, bx, by);
+            if (distance > maxDistance) {
+                maxDistance = distance;
+                split = i;
+            }
+        }
+        if (maxDistance > tolerance && split !== -1) {
+            keep.push(split);
+            stack.push([start, split], [split, end]);
+        }
+    }
+    return keep.sort((a, b) => a - b);
+}
+/**
+ * Simplify a closed boundary: anchor RDP at the start and its farthest point
+ * (a mid-edge start anchor alone would let a nearby corner slip through).
+ */
+function simplify(boundary, tolerance) {
+    // Close the ring explicitly so the second RDP range ends on the start point.
+    const closed = boundary.concat([boundary[0], boundary[1]]);
+    const count = closed.length / 2;
+    let far = 0;
+    let maxDistance = -1;
+    for (let i = 1; i < count - 1; i++) {
+        const distance = Math.hypot(closed[i * 2] - closed[0], closed[i * 2 + 1] - closed[1]);
+        if (distance > maxDistance) {
+            maxDistance = distance;
+            far = i;
+        }
+    }
+    const first = rdpRange(closed, 0, far, tolerance);
+    const second = rdpRange(closed, far, count - 1, tolerance);
+    const indices = [...first, ...second.filter((index) => index !== far && index !== count - 1)];
+    const out = [];
+    for (const index of indices)
+        out.push(closed[index * 2], closed[index * 2 + 1]);
+    return out;
+}
+/** Extract simplified outer contours from a luma image, largest first. */
+export function extractProfiles(image, options = {}) {
+    const { width, height, gray } = image;
+    const threshold = options.threshold ?? otsuThreshold(gray);
+    const invert = options.invert ?? false;
+    const tolerance = options.tolerance ?? 1.5;
+    const scale = options.scale ?? 1;
+    const minArea = options.minArea ?? 24;
+    const mask = new Uint8Array(gray.length);
+    for (let i = 0; i < gray.length; i++) {
+        // Otsu's class split is "≤ T vs > T", so dark uses <=.
+        const dark = gray[i] <= threshold;
+        mask[i] = (invert ? !dark : dark) ? 1 : 0;
+    }
+    const labels = new Int32Array(mask.length).fill(-1);
+    const profiles = [];
+    for (const group of components(mask, width, height)) {
+        if (group.length < minArea)
+            continue;
+        const label = profiles.length + 1;
+        for (const index of group)
+            labels[index] = label;
+        const boundary = traceBoundary(labels, width, height, label, group[0]);
+        for (const index of group)
+            labels[index] = -1;
+        if (boundary.length < 6)
+            continue;
+        const points = simplify(boundary, tolerance);
+        if (points.length < 6)
+            continue;
+        // px (y down) → mm (y up)
+        const mm = new Array(points.length);
+        for (let i = 0; i < points.length; i += 2) {
+            mm[i] = points[i] * scale;
+            mm[i + 1] = (height - 1 - points[i + 1]) * scale;
+        }
+        profiles.push({ points: mm, area: group.length });
+    }
+    profiles.sort((a, b) => b.area - a.area);
+    return profiles;
+}

package/lib/index.js

@@ -0,0 +1,77 @@
+import { SceneStore } from './store.js';
+import { BinarySceneStore } from './modeling/bin-store.js';
+import { registerSceneRoute, registerBinRoute, registerDemoRoute } from './routes.js';
+import { createCadViewTool } from './tools/cad-view.js';
+import { createCadInfoTool } from './tools/cad-info.js';
+import { createModelTools } from './tools/cad-model.js';
+import { createFreeCadTool } from './tools/cad-freecad.js';
+import { createFusionTool } from './tools/cad-fusion.js';
+import { createCadImageTool } from './tools/cad-image.js';
+export const name = 'dsh-cad';
+/** Hard dependencies: the tool registry. */
+export const inject = ['tools'];
+export function apply(ctx, config = {}) {
+    const root = config.root ?? process.cwd();
+    const store = new SceneStore(root);
+    const binStore = new BinarySceneStore(root);
+    const workspaceRoot = process.cwd();
+    let routeRegistered = false;
+    /** Idempotently register the scene routes; returns the JSON base or null. */
+    const ensureSceneRoute = () => {
+        if (routeRegistered)
+            return '/dsh-cad/scene';
+        const scope = ctx;
+        const server = (scope.get?.('webServer') ?? scope.get?.('httpServer'));
+        if (server === undefined)
+            return null;
+        registerSceneRoute(server, store);
+        registerBinRoute(server, binStore);
+        registerDemoRoute(server);
+        routeRegistered = true;
+        return '/dsh-cad/scene';
+    };
+    // The demo route backs the CAD editor's startup fetch (before any tool
+    // call), so registration must not wait for the first tool use. The web
+    // composition may provide the HTTP server after our activation, so retry
+    // briefly; fiber ordering decides the exact moment.
+    let attempts = 0;
+    const retry = setInterval(() => {
+        if (routeRegistered || ++attempts > 200) {
+            clearInterval(retry);
+            return;
+        }
+        try {
+            ensureSceneRoute();
+        }
+        catch {
+            /* the lazy path (first tool use) still covers late availability */
+        }
+    }, 100);
+    try {
+        ensureSceneRoute();
+    }
+    catch {
+        /* registers lazily at first tool use */
+    }
+    const cadView = createCadViewTool({ store, workspaceRoot, ensureSceneRoute });
+    const cadInfo = createCadInfoTool({ workspaceRoot });
+    const modelTools = createModelTools({ store: binStore, sceneStore: store, workspaceRoot, ensureSceneRoute });
+    const cadFreeCad = createFreeCadTool({ store: binStore, workspaceRoot, ensureSceneRoute });
+    const cadFusion = createFusionTool({ store: binStore, workspaceRoot, ensureSceneRoute });
+    const cadImage = createCadImageTool({ store, workspaceRoot, ensureSceneRoute });
+    const disposers = [
+        ctx.tools.register(cadView),
+        ctx.tools.register(cadInfo),
+        ...modelTools.map((tool) => ctx.tools.register(tool)),
+        ctx.tools.register(cadFreeCad),
+        ctx.tools.register(cadFusion),
+        ctx.tools.register(cadImage),
+    ];
+    ctx.effect(() => {
+        return () => {
+            clearInterval(retry);
+            for (const dispose of disposers)
+                dispose();
+        };
+    });
+}

package/lib/modeling/assembly.js

@@ -0,0 +1,63 @@
+function rotationMatrix(rotate) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const [rx, ry, rz] = rotate.map(toRad);
+    const cx = Math.cos(rx), sx = Math.sin(rx);
+    const cy = Math.cos(ry), sy = Math.sin(ry);
+    const cz = Math.cos(rz), sz = Math.sin(rz);
+    // Row-major 3×3: Rx·Ry·Rz
+    return new Float64Array([
+        cy * cz, -cy * sz, sy,
+        cx * sz + sx * sy * cz, cx * cz - sx * sy * sz, -sx * cy,
+        sx * sz - cx * sy * cz, sx * cz + cx * sy * sz, cx * cy,
+    ]);
+}
+function transformMesh(mesh, translate, rotate) {
+    const isIdentity = translate.every((v) => v === 0) && rotate.every((v) => v === 0);
+    if (isIdentity)
+        return mesh;
+    const m = rotationMatrix(rotate);
+    const [tx, ty, tz] = translate;
+    const positions = new Float32Array(mesh.positions.length);
+    for (let i = 0; i + 2 < mesh.positions.length; i += 3) {
+        const x = mesh.positions[i];
+        const y = mesh.positions[i + 1];
+        const z = mesh.positions[i + 2];
+        positions[i] = m[0] * x + m[1] * y + m[2] * z + tx;
+        positions[i + 1] = m[3] * x + m[4] * y + m[5] * z + ty;
+        positions[i + 2] = m[6] * x + m[7] * y + m[8] * z + tz;
+    }
+    // Normals rotate with the same linear part (translation never applies).
+    let normals;
+    if (mesh.normals !== undefined) {
+        normals = new Float32Array(mesh.normals.length);
+        for (let i = 0; i + 2 < mesh.normals.length; i += 3) {
+            const x = mesh.normals[i];
+            const y = mesh.normals[i + 1];
+            const z = mesh.normals[i + 2];
+            normals[i] = m[0] * x + m[1] * y + m[2] * z;
+            normals[i + 1] = m[3] * x + m[4] * y + m[5] * z;
+            normals[i + 2] = m[6] * x + m[7] * y + m[8] * z;
+        }
+    }
+    return { ...mesh, positions, normals };
+}
+/**
+ * Compose the assembly scene: one transformed mesh copy per instance.
+ * Instances referencing bodies missing from `bodies` (consumed by a later
+ * boolean) are skipped — the worker's live list already filters them, this is
+ * the replay-side double guard. Duplicate names get a ·N suffix.
+ */
+export function composeAssemblyMeshes(bodies, instances) {
+    const meshes = [];
+    const nameUse = new Map();
+    for (const instance of instances) {
+        const body = bodies.get(instance.bodyId);
+        if (body === undefined)
+            continue;
+        const seen = nameUse.get(instance.name) ?? 0;
+        nameUse.set(instance.name, seen + 1);
+        const name = seen === 0 ? instance.name : `${instance.name}·${seen + 1}`;
+        meshes.push(transformMesh({ ...body, name }, instance.translate, instance.rotate));
+    }
+    return meshes;
+}

package/lib/modeling/bin-format.js

@@ -0,0 +1,80 @@
+/**
+ * Binary scene format: the direct worker→three.js transport. One packed
+ * buffer (JSON header + raw f32/u32 payloads) that the browser decodes with
+ * typed-array views — no base64, no JSON number arrays, no intermediate file
+ * unless the debounced disk mirror or an explicit cad_export happens.
+ *
+ * Layout (little-endian):
+ *   [4B magic "DCB1"][4B headerByteLength][header JSON utf8][payload bytes]
+ * Header: { meshes: [{ name, color?, vertexCount, triangleCount,
+ *            posOffset, posBytes, nrmOffset?, nrmBytes, idxOffset, idxBytes }],
+ *           bounds: { min: [x,y,z], max: [x,y,z] }, units }
+ * Offsets/lengths are byte counts relative to the payload start.
+ */
+const MAGIC = 0x31424344; // "DCB1" little-endian
+/** Pack meshes into the binary transport buffer. */
+export function packBinaryScene(meshes) {
+    const header = {
+        meshes: [],
+        bounds: { min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] },
+        units: 'mm',
+    };
+    let payloadBytes = 0;
+    for (const mesh of meshes) {
+        const posBytes = mesh.positions.byteLength;
+        const nrmBytes = mesh.normals === undefined ? 0 : mesh.normals.byteLength;
+        const idxBytes = mesh.indices.byteLength;
+        const desc = {
+            name: mesh.name,
+            ...(mesh.color === undefined ? {} : { color: mesh.color }),
+            vertexCount: mesh.positions.length / 3,
+            triangleCount: mesh.indices.length / 3,
+            posOffset: payloadBytes,
+            posBytes,
+            ...(mesh.normals === undefined ? {} : { nrmOffset: payloadBytes + posBytes, nrmBytes }),
+            idxOffset: payloadBytes + posBytes + nrmBytes,
+            idxBytes,
+        };
+        header.meshes.push(desc);
+        payloadBytes += posBytes + nrmBytes + idxBytes;
+        for (let i = 0; i < mesh.positions.length; i += 3) {
+            const x = mesh.positions[i] ?? 0;
+            const y = mesh.positions[i + 1] ?? 0;
+            const z = mesh.positions[i + 2] ?? 0;
+            if (x < header.bounds.min[0])
+                header.bounds.min[0] = x;
+            if (y < header.bounds.min[1])
+                header.bounds.min[1] = y;
+            if (z < header.bounds.min[2])
+                header.bounds.min[2] = z;
+            if (x > header.bounds.max[0])
+                header.bounds.max[0] = x;
+            if (y > header.bounds.max[1])
+                header.bounds.max[1] = y;
+            if (z > header.bounds.max[2])
+                header.bounds.max[2] = z;
+        }
+    }
+    if (!Number.isFinite(header.bounds.min[0])) {
+        header.bounds = { min: [0, 0, 0], max: [1, 1, 1] };
+    }
+    const headerBuffer = Buffer.from(JSON.stringify(header), 'utf8');
+    // Pad the header so the payload starts 8-byte aligned (typed-array views).
+    const paddedHeaderLength = Math.ceil(headerBuffer.length / 8) * 8;
+    const out = Buffer.alloc(8 + paddedHeaderLength + payloadBytes);
+    out.writeUInt32LE(MAGIC, 0);
+    out.writeUInt32LE(paddedHeaderLength, 4);
+    headerBuffer.copy(out, 8);
+    let cursor = 8 + paddedHeaderLength;
+    for (const mesh of meshes) {
+        Buffer.from(mesh.positions.buffer, mesh.positions.byteOffset, mesh.positions.byteLength).copy(out, cursor);
+        cursor += mesh.positions.byteLength;
+        if (mesh.normals !== undefined) {
+            Buffer.from(mesh.normals.buffer, mesh.normals.byteOffset, mesh.normals.byteLength).copy(out, cursor);
+            cursor += mesh.normals.byteLength;
+        }
+        Buffer.from(mesh.indices.buffer, mesh.indices.byteOffset, mesh.indices.byteLength).copy(out, cursor);
+        cursor += mesh.indices.byteLength;
+    }
+    return out;
+}

package/lib/modeling/bin-store.js

@@ -0,0 +1,67 @@
+/**
+ * In-memory binary scene store: viewId → packed buffer + version. The binary
+ * route serves straight from memory; a debounced disk mirror keeps restart
+ * replay working without paying a file write on every modeling step.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { packBinaryScene } from './bin-format.js';
+const DISK_MIRROR_DELAY_MS = 1500;
+export class BinarySceneStore {
+    root;
+    memory = new Map();
+    diskTimers = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    get directory() {
+        return path.join(this.root, '.dsh-cad', 'bins');
+    }
+    /** Publish a new version under a stable viewId; returns the version. */
+    async publish(viewId, meshes) {
+        const previous = this.memory.get(viewId);
+        const version = (previous?.version ?? 0) + 1;
+        const buffer = packBinaryScene(meshes);
+        const etag = `"v${version}-${buffer.length}"`;
+        this.memory.set(viewId, { buffer, version, etag });
+        this.scheduleDiskMirror(viewId, buffer);
+        return version;
+    }
+    /** Fetch for serving: memory first, disk mirror as the restart fallback. */
+    async get(viewId) {
+        if (!/^[0-9a-zA-Z_-]{1,64}$/.test(viewId))
+            return null;
+        const memoryHit = this.memory.get(viewId);
+        if (memoryHit !== undefined)
+            return memoryHit;
+        try {
+            const buffer = await readFile(path.join(this.directory, `${viewId}.bin`));
+            // Mirror entries serve replay; the version rides in the etag only.
+            const entry = { buffer, version: 1, etag: `"d${buffer.length}"` };
+            this.memory.set(viewId, entry);
+            return entry;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Debounced disk mirror: one write after modeling quiesces, not per step. */
+    scheduleDiskMirror(viewId, buffer) {
+        const existing = this.diskTimers.get(viewId);
+        if (existing !== undefined)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.diskTimers.delete(viewId);
+            void (async () => {
+                try {
+                    await mkdir(this.directory, { recursive: true });
+                    await writeFile(path.join(this.directory, `${viewId}.bin`), buffer);
+                }
+                catch {
+                    // The mirror is best-effort; the in-memory copy keeps serving.
+                }
+            })();
+        }, DISK_MIRROR_DELAY_MS);
+        this.diskTimers.set(viewId, timer);
+    }
+}

package/lib/modeling/client.js

@@ -0,0 +1,117 @@
+/**
+ * Main-thread modeling client: one lazily spawned OCCT worker per client,
+ * job correlation, and transferable buffers — the same shape as
+ * convert/step.ts. The module default is a shared singleton (the live
+ * modeling session); isolated conversions (e.g. .dcprt replay) spawn their
+ * own client via createModelClient() and dispose() it when done, so they
+ * never clobber the session state.
+ */
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+export function createModelClient() {
+    let worker = null;
+    let ready = null;
+    let disposed = false;
+    let nextJobId = 1;
+    const pending = new Map();
+    function spawn() {
+        const spawned = new Worker(new URL('./modeling-worker.cjs', import.meta.url));
+        const readyPromise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error('modeling kernel startup timed out')), 60_000);
+            const onReady = (message) => {
+                clearTimeout(timer);
+                if (message.ok)
+                    resolve();
+                else
+                    reject(new Error(message.error ?? 'modeling kernel init failed'));
+            };
+            spawned.once('message', onReady);
+        });
+        spawned.on('message', (response) => {
+            const job = pending.get(response.jobId);
+            if (job === undefined)
+                return;
+            pending.delete(response.jobId);
+            clearTimeout(job.timer);
+            if (response.ok && response.result !== undefined)
+                job.resolve(response.result);
+            else
+                job.reject(new Error(response.error ?? 'modeling operation failed'));
+        });
+        spawned.on('error', (error) => failAll(error));
+        spawned.on('exit', (code) => {
+            if (code !== 0)
+                failAll(new Error(`the modeling worker exited unexpectedly (code ${code})`));
+            worker = null;
+            ready = null;
+        });
+        return { worker: spawned, ready: readyPromise };
+    }
+    function failAll(error) {
+        for (const [jobId, job] of pending) {
+            pending.delete(jobId);
+            clearTimeout(job.timer);
+            job.reject(error);
+        }
+    }
+    async function ensureWorker() {
+        if (worker !== null && ready !== null) {
+            await ready;
+            return worker;
+        }
+        const spawned = spawn();
+        worker = spawned.worker;
+        ready = spawned.ready;
+        await ready;
+        return worker;
+    }
+    return {
+        async run(op, timeoutMs = 180_000) {
+            if (disposed)
+                throw new Error('modeling client has been disposed');
+            const active = await ensureWorker();
+            const jobId = nextJobId++;
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(jobId);
+                    reject(new Error(`modeling operation timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                pending.set(jobId, { resolve, reject, timer });
+                active.postMessage({ jobId, op });
+            });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            failAll(new Error('modeling client disposed'));
+            if (worker !== null)
+                void worker.terminate();
+            worker = null;
+            ready = null;
+        },
+    };
+}
+const sharedClient = createModelClient();
+/**
+ * Monotonic count of `reset` ops posted through the shared worker. Any
+ * out-of-band replay (e.g. opening a .dcprt) resets the worker and bumps the
+ * epoch, so the modeling session owner can detect staleness and re-replay
+ * its document before the next op.
+ */
+let resetEpoch = 0;
+/** Run one modeling operation on the shared session worker. */
+export async function runModelOp(op, timeoutMs = 180_000) {
+    const result = await sharedClient.run(op, timeoutMs);
+    if (op.kind === 'reset')
+        resetEpoch += 1;
+    return result;
+}
+/** Current reset epoch of the shared worker (see above). */
+export function workerResetEpoch() {
+    return resetEpoch;
+}
+/** Test/Dev helper: hard worker file path (used by the vitest suite). */
+export function workerEntryPath() {
+    return fileURLToPath(new URL('./modeling-worker.cjs', import.meta.url));
+}

package/lib/modeling/document.js

@@ -0,0 +1,55 @@
+/**
+ * Modeling document: an operation log (JSON) per workspace that both persists
+ * across restarts and is the unit of replay — restart recovery re-applies the
+ * log to a fresh worker, which is what makes the worker's in-memory shapes
+ * disposable.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export class ModelDocument {
+    root;
+    doc = { docId: randomUUID(), version: 0, ops: [], bodyNames: {} };
+    constructor(root) {
+        this.root = root;
+    }
+    get directory() {
+        return path.join(this.root, '.dsh-cad');
+    }
+    get file() {
+        return path.join(this.directory, 'model.json');
+    }
+    /** Load the persisted document if one exists. */
+    async restore() {
+        try {
+            const text = await readFile(this.file, 'utf8');
+            const parsed = JSON.parse(text);
+            if (typeof parsed.docId === 'string' && Array.isArray(parsed.ops)) {
+                this.doc = { ...parsed, version: parsed.version ?? 0, bodyNames: parsed.bodyNames ?? {} };
+            }
+        }
+        catch {
+            // No document yet — a fresh one stays in memory until the first op.
+        }
+    }
+    /** Append an applied operation and persist. */
+    async record(op, bodyName) {
+        this.doc.ops.push(op);
+        this.doc.version += 1;
+        if (bodyName !== null)
+            this.doc.bodyNames[bodyName.bodyId] = bodyName.name;
+        if (op.kind === 'delete' || op.kind === 'boolean') {
+            const removed = op.kind === 'delete' ? [op.target] : op.tools;
+            for (const id of removed)
+                delete this.doc.bodyNames[id];
+        }
+        await mkdir(this.directory, { recursive: true });
+        await writeFile(this.file, JSON.stringify(this.doc));
+    }
+    /** Clear the document (cad_new / tests). */
+    async clear() {
+        this.doc = { docId: randomUUID(), version: 0, ops: [], bodyNames: {} };
+        await mkdir(this.directory, { recursive: true });
+        await writeFile(this.file, JSON.stringify(this.doc));
+    }
+}