@faicad/faijs 0.13.0

package/dist/vendored/brepjs/core/disposal.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Resource disposal system using Symbol.dispose (TC39 Explicit Resource Management).
+ *
+ * All kernel handles are wrapped in disposable objects:
+ *   using solid = createSolid(ocShape);
+ *   // auto-disposed at end of scope
+ *
+ * FinalizationRegistry serves as a safety net for handles not explicitly disposed.
+ */
+import type { KernelShape } from '../kernel/types.js';
+import type { BrepError } from './errors.js';
+import type { Result } from './result.js';
+/** Any object that can be cleaned up by calling `delete()` (kernel WASM objects). */
+export interface Deletable {
+    delete: () => void;
+}
+/** Statistics about WASM handle lifecycle. Zero overhead when not queried. */
+export interface DisposalStats {
+    /** Number of handles currently alive (not disposed). */
+    liveHandles: number;
+    /** Peak number of simultaneously live handles. */
+    peakHandles: number;
+    /** Number of handles reclaimed by FinalizationRegistry (GC safety net). */
+    gcCollected: number;
+    /** Number of DisposalScope.enter() calls. */
+    scopeEnters: number;
+    /** Number of DisposalScope.dispose() calls. */
+    scopeExits: number;
+}
+/** Get a snapshot of current disposal statistics. */
+export declare function getDisposalStats(): Readonly<DisposalStats>;
+/** Reset all disposal statistics to zero. */
+export declare function resetDisposalStats(): void;
+/** A shape wrapper with Symbol.dispose for auto-cleanup. */
+export interface ShapeHandle {
+    /** The raw kernel shape handle */
+    readonly wrapped: KernelShape;
+    /** Manually dispose the kernel handle */
+    [Symbol.dispose](): void;
+    /** Alias for Symbol.dispose — required for Deletable compatibility. */
+    delete(): void;
+    /** Check if this handle has been disposed */
+    readonly disposed: boolean;
+    /**
+     * Register a callback to run when this handle is disposed, before its kernel
+     * slot is released. Used to release dependent resources tied to this shape's
+     * lifetime (e.g. its cached sub-shape handles). Callbacks are invoked once,
+     * in registration order; a callback that throws is swallowed. Registering on
+     * an already-disposed handle runs the callback immediately.
+     */
+    onDispose(callback: () => void): void;
+}
+/** Create a disposable shape handle. */
+export declare function createHandle(ocShape: KernelShape): ShapeHandle;
+/**
+ * Wrap a raw kernel shape as a **non-owning** handle: `wrapped` exposes the same
+ * arena slot as an owning handle would, but `dispose`/`delete` are no-ops and the
+ * slot is never registered with the finalizer or the stats counters.
+ *
+ * Use for borrowed views into another owner's slot — e.g. the topology cache's
+ * adjacency handles. On occt-wasm >= 3.7.0 an identity `downcast` returns the
+ * *same* slot id (not a duplicate), so branding a cache slot as an owning handle
+ * would let the borrower's dispose free a slot the cache still points at. A
+ * borrowed handle keeps the slot's identity (`isSame`/`hashCode` still match the
+ * cache) while leaving ownership — and disposal — with the cache. The view is
+ * only valid while its owner lives; `clone()`/`copyShape` it to outlive that.
+ */
+export declare function createBorrowedHandle(ocShape: KernelShape): ShapeHandle;
+/**
+ * Run `fn` between an arena checkpoint and restore, reclaiming every slot it
+ * allocates — including kernel-internal query temporaries brepjs holds no handle
+ * for (e.g. `distance`/`boundingBox` scratch) — in a single `restoreCheckpoint`.
+ *
+ * **SAFE ONLY when `fn` returns plain data** (numbers, points, arrays): restore
+ * frees *every* slot allocated after the checkpoint, so a live shape handle in
+ * the return value would dangle. Use for data-returning batch analysis over many
+ * bodies; never to wrap a shape builder. Inputs allocated before the call are
+ * untouched (restore only frees from the mark forward).
+ *
+ * No-op wrapper on kernels without arena checkpoints (occt/manifold): `fn` runs
+ * directly and those kernels' own disposal applies.
+ */
+export declare function withArenaCheckpoint<T>(fn: () => T): T;
+/** A disposable wrapper for any kernel object. */
+export interface KernelHandle<T extends Deletable> {
+    readonly value: T;
+    readonly disposed: boolean;
+    [Symbol.dispose](): void;
+}
+/** Create a disposable handle for any kernel object. */
+export declare function createKernelHandle<T extends Deletable>(ocObj: T): KernelHandle<T>;
+/** Scope for tracking multiple disposable resources. */
+export declare class DisposalScope implements Disposable {
+    private readonly handles;
+    constructor();
+    /** Register a resource for disposal when scope ends. */
+    register<T extends Deletable>(resource: T): T;
+    /** Register a disposable for disposal when scope ends. */
+    track<T extends Disposable>(disposable: T): T;
+    [Symbol.dispose](): void;
+}
+/** Execute a function with a disposal scope. Resources registered with the scope
+ *  are automatically cleaned up when the function returns. */
+export declare function withScope<T>(fn: (scope: DisposalScope) => T): T;
+/** Register `deletable` for GC cleanup when `owner` is collected. */
+export declare function registerForCleanup(owner: object, deletable: Deletable): void;
+/** Unregister a previously-registered deletable (call before manual delete). */
+export declare function unregisterFromCleanup(deletable: Deletable): void;
+/**
+ * Run fn inside a DisposalScope. The scope is disposed on all exit paths:
+ * Ok return, Err return, and throw. Use in any function that allocates
+ * kernel objects and returns Result<T>.
+ *
+ * ```ts
+ * return withScopeResult((scope) => {
+ *   const axis = scope.register(makeKernelAx1(origin, dir));
+ *   return ok(castShape(getKernel().makeSomething(axis)) as Solid);
+ * });
+ * ```
+ */
+export declare function withScopeResult<T, E = BrepError>(fn: (scope: DisposalScope) => Result<T, E>): Result<T, E>;
+/**
+ * Async variant of withScopeResult. The scope is disposed after the
+ * returned promise settles (resolved or rejected).
+ */
+export declare function withScopeResultAsync<T, E = BrepError>(fn: (scope: DisposalScope) => Promise<Result<T, E>>): Promise<Result<T, E>>;
+/**
+ * Returns true if the handle has not been disposed.
+ * Provides a named alternative to checking `.disposed` directly.
+ *
+ * ```ts
+ * if (!isLive(handle)) return err(validationError('DISPOSED_HANDLE', '...'));
+ * ```
+ */
+export declare function isLive(handle: ShapeHandle | KernelHandle<Deletable>): boolean;
+//# sourceMappingURL=disposal.d.ts.map

package/dist/vendored/brepjs/core/disposal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposal.d.ts","sourceRoot":"","sources":["../../../../src/vendored/brepjs/core/disposal.ts"],"names":[],"mappings":"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"}

package/dist/vendored/brepjs/core/disposal.js

@@ -0,0 +1,441 @@
+/**
+ * Resource disposal system using Symbol.dispose (TC39 Explicit Resource Management).
+ *
+ * All kernel handles are wrapped in disposable objects:
+ *   using solid = createSolid(ocShape);
+ *   // auto-disposed at end of scope
+ *
+ * FinalizationRegistry serves as a safety net for handles not explicitly disposed.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { getKernel } from '../kernel/index.js';
+import { isUnsupportedKernelOperationError } from '../kernel/unsupported.js';
+// ---------------------------------------------------------------------------
+// Symbol.dispose polyfill — Safari and older browsers lack the well-known
+// symbol. esbuild's `using` transform falls back to Symbol.for("Symbol.dispose"),
+// but [Symbol.dispose]() property keys use the raw symbol. This polyfill
+// bridges the gap so both resolve to the same key.  (#326)
+// ---------------------------------------------------------------------------
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- patching global Symbol
+const S = Symbol;
+S.dispose ??= Symbol.for('Symbol.dispose');
+S.asyncDispose ??= Symbol.for('Symbol.asyncDispose');
+const globalWithRegistry = globalThis;
+if (!globalWithRegistry.FinalizationRegistry) {
+    console.warn('faijs: FinalizationRegistry unavailable — garbage collection will not work');
+    globalWithRegistry.FinalizationRegistry = class NoOpFinalizationRegistry {
+        register(_target, _heldValue, _unregisterToken) {
+            // no-op
+        }
+        unregister(_unregisterToken) {
+            return false;
+        }
+    };
+}
+const _stats = {
+    liveHandles: 0,
+    peakHandles: 0,
+    gcCollected: 0,
+    scopeEnters: 0,
+    scopeExits: 0,
+};
+/** Get a snapshot of current disposal statistics. */
+export function getDisposalStats() {
+    return { ..._stats };
+}
+/** Reset all disposal statistics to zero. */
+export function resetDisposalStats() {
+    _stats.liveHandles = 0;
+    _stats.peakHandles = 0;
+    _stats.gcCollected = 0;
+    _stats.scopeEnters = 0;
+    _stats.scopeExits = 0;
+}
+function trackHandleCreated() {
+    _stats.liveHandles++;
+    if (_stats.liveHandles > _stats.peakHandles) {
+        _stats.peakHandles = _stats.liveHandles;
+    }
+}
+function trackHandleDisposed() {
+    _stats.liveHandles--;
+}
+function trackGcCollected() {
+    _stats.gcCollected++;
+    _stats.liveHandles--;
+}
+const registry = new FinalizationRegistry((heldValue) => {
+    trackGcCollected();
+    try {
+        heldValue.delete();
+    }
+    catch {
+        // Already deleted or invalid — ignore
+    }
+});
+/** Create a disposable shape handle. */
+export function createHandle(ocShape) {
+    // Capture the owning kernel now: on the occt-wasm arena kernel a shape's own
+    // `delete()` is a no-op, so the slot is only reclaimed via `kernel.dispose()`
+    // (→ `k.release(id)`). Routing disposal through the kernel makes `using` free
+    // the slot on every kernel. Embind kernels keep their existing `.delete()`
+    // behaviour (`kernel.dispose` falls through to it). `k.release` is idempotent,
+    // so overlap with `disposeResultShape`/`disposeDowncastSource` is safe.
+    const kernel = getKernel();
+    let disposed = false;
+    let onDisposeCallbacks;
+    const runOnDispose = () => {
+        if (!onDisposeCallbacks)
+            return;
+        for (const cb of onDisposeCallbacks) {
+            try {
+                cb();
+            }
+            catch {
+                // A dependent-cleanup failure must not abort disposal.
+            }
+        }
+        onDisposeCallbacks = undefined;
+    };
+    const dispose = () => {
+        if (!disposed) {
+            disposed = true;
+            trackHandleDisposed();
+            registry.unregister(handle);
+            // Release dependents (e.g. cached sub-shapes) before this slot goes.
+            runOnDispose();
+            try {
+                kernel.dispose(ocShape);
+            }
+            catch {
+                // Already deleted — ignore
+            }
+        }
+    };
+    const handle = {
+        get wrapped() {
+            if (disposed)
+                throw new Error('Shape handle has been disposed');
+            return ocShape;
+        },
+        get disposed() {
+            return disposed;
+        },
+        [Symbol.dispose]() {
+            dispose();
+        },
+        delete() {
+            dispose();
+        },
+        onDispose(callback) {
+            if (disposed) {
+                callback();
+                return;
+            }
+            (onDisposeCallbacks ??= []).push(callback);
+        },
+    };
+    trackHandleCreated();
+    // GC safety net: route the finalizer through the kernel too, else arena slots
+    // survive collection on occt-wasm. The closure holds `ocShape`/`kernel` (not
+    // `handle`), so it never keeps the handle itself alive.
+    registry.register(handle, {
+        delete: () => {
+            kernel.dispose(ocShape);
+        },
+    }, handle);
+    return handle;
+}
+/**
+ * Wrap a raw kernel shape as a **non-owning** handle: `wrapped` exposes the same
+ * arena slot as an owning handle would, but `dispose`/`delete` are no-ops and the
+ * slot is never registered with the finalizer or the stats counters.
+ *
+ * Use for borrowed views into another owner's slot — e.g. the topology cache's
+ * adjacency handles. On occt-wasm >= 3.7.0 an identity `downcast` returns the
+ * *same* slot id (not a duplicate), so branding a cache slot as an owning handle
+ * would let the borrower's dispose free a slot the cache still points at. A
+ * borrowed handle keeps the slot's identity (`isSame`/`hashCode` still match the
+ * cache) while leaving ownership — and disposal — with the cache. The view is
+ * only valid while its owner lives; `clone()`/`copyShape` it to outlive that.
+ */
+export function createBorrowedHandle(ocShape) {
+    const noop = () => { };
+    return {
+        get wrapped() {
+            return ocShape;
+        },
+        get disposed() {
+            return false;
+        },
+        [Symbol.dispose]: noop,
+        delete: noop,
+        // Intentionally a no-op: a borrowed view never disposes, so a callback would
+        // never fire. Tie dependent lifetimes to the owning parent's handle instead.
+        onDispose: noop,
+    };
+}
+/**
+ * Run `fn` between an arena checkpoint and restore, reclaiming every slot it
+ * allocates — including kernel-internal query temporaries brepjs holds no handle
+ * for (e.g. `distance`/`boundingBox` scratch) — in a single `restoreCheckpoint`.
+ *
+ * **SAFE ONLY when `fn` returns plain data** (numbers, points, arrays): restore
+ * frees *every* slot allocated after the checkpoint, so a live shape handle in
+ * the return value would dangle. Use for data-returning batch analysis over many
+ * bodies; never to wrap a shape builder. Inputs allocated before the call are
+ * untouched (restore only frees from the mark forward).
+ *
+ * No-op wrapper on kernels without arena checkpoints (occt/manifold): `fn` runs
+ * directly and those kernels' own disposal applies.
+ */
+export function withArenaCheckpoint(fn) {
+    const kernel = getKernel();
+    let cp;
+    try {
+        cp = kernel.checkpoint();
+    }
+    catch (e) {
+        if (!isUnsupportedKernelOperationError(e))
+            throw e;
+        return fn();
+    }
+    let result;
+    try {
+        result = fn();
+    }
+    catch (e) {
+        // fn's error is primary: still restore, but never let a restore failure mask
+        // it (a plain `finally { restore() }` would swallow the original throw).
+        try {
+            kernel.restoreCheckpoint(cp);
+        }
+        catch {
+            /* surface fn's error instead */
+        }
+        throw e;
+    }
+    // Success path: a restore failure here is a genuine bug — let it surface.
+    kernel.restoreCheckpoint(cp);
+    return result;
+}
+/** Create a disposable handle for any kernel object. */
+export function createKernelHandle(ocObj) {
+    let disposed = false;
+    const handle = {
+        get value() {
+            if (disposed)
+                throw new Error('kernel handle has been disposed');
+            return ocObj;
+        },
+        get disposed() {
+            return disposed;
+        },
+        [Symbol.dispose]() {
+            if (!disposed) {
+                disposed = true;
+                trackHandleDisposed();
+                registry.unregister(handle);
+                try {
+                    ocObj.delete();
+                }
+                catch {
+                    // Already deleted
+                }
+            }
+        },
+    };
+    trackHandleCreated();
+    registry.register(handle, ocObj, handle);
+    return handle;
+}
+// ---------------------------------------------------------------------------
+// Scoped resource management
+// ---------------------------------------------------------------------------
+/** Scope for tracking multiple disposable resources. */
+export class DisposalScope {
+    handles = [];
+    constructor() {
+        _stats.scopeEnters++;
+    }
+    /** Register a resource for disposal when scope ends. */
+    register(resource) {
+        this.handles.push(() => {
+            try {
+                // A shape handle's `.delete()` is a no-op on arena kernels (occt-wasm);
+                // its slot is only reclaimed through `Symbol.dispose` → `kernel.dispose`.
+                // Prefer that when present, so a shape registered here is actually freed;
+                // raw WASM objects (no `Symbol.dispose`) fall back to `.delete()`.
+                const disposer = resource[Symbol.dispose];
+                if (typeof disposer === 'function')
+                    disposer.call(resource);
+                else
+                    resource.delete();
+            }
+            catch {
+                // Already deleted
+            }
+        });
+        return resource;
+    }
+    /** Register a disposable for disposal when scope ends. */
+    track(disposable) {
+        this.handles.push(() => {
+            try {
+                disposable[Symbol.dispose]();
+            }
+            catch {
+                // Already disposed or invalid — ignore
+            }
+        });
+        return disposable;
+    }
+    [Symbol.dispose]() {
+        _stats.scopeExits++;
+        // Dispose in reverse order (LIFO)
+        for (let i = this.handles.length - 1; i >= 0; i--) {
+            this.handles[i]?.();
+        }
+        this.handles.length = 0;
+    }
+}
+/** Execute a function with a disposal scope. Resources registered with the scope
+ *  are automatically cleaned up when the function returns. */
+export function withScope(fn) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const scope = __addDisposableResource(env_1, new DisposalScope(), false);
+        return fn(scope);
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+// ---------------------------------------------------------------------------
+// FinalizationRegistry helpers for non-branded wrappers (e.g. Curve2D)
+// ---------------------------------------------------------------------------
+/** Register `deletable` for GC cleanup when `owner` is collected. */
+export function registerForCleanup(owner, deletable) {
+    registry.register(owner, deletable, deletable);
+}
+/** Unregister a previously-registered deletable (call before manual delete). */
+export function unregisterFromCleanup(deletable) {
+    registry.unregister(deletable);
+}
+// ---------------------------------------------------------------------------
+// Result-aware scope helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run fn inside a DisposalScope. The scope is disposed on all exit paths:
+ * Ok return, Err return, and throw. Use in any function that allocates
+ * kernel objects and returns Result<T>.
+ *
+ * ```ts
+ * return withScopeResult((scope) => {
+ *   const axis = scope.register(makeKernelAx1(origin, dir));
+ *   return ok(castShape(getKernel().makeSomething(axis)) as Solid);
+ * });
+ * ```
+ */
+export function withScopeResult(fn) {
+    const env_2 = { stack: [], error: void 0, hasError: false };
+    try {
+        const scope = __addDisposableResource(env_2, new DisposalScope(), false);
+        return fn(scope);
+    }
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
+    }
+    finally {
+        __disposeResources(env_2);
+    }
+}
+/**
+ * Async variant of withScopeResult. The scope is disposed after the
+ * returned promise settles (resolved or rejected).
+ */
+export async function withScopeResultAsync(fn) {
+    const env_3 = { stack: [], error: void 0, hasError: false };
+    try {
+        const scope = __addDisposableResource(env_3, new DisposalScope(), false);
+        return await fn(scope);
+    }
+    catch (e_3) {
+        env_3.error = e_3;
+        env_3.hasError = true;
+    }
+    finally {
+        __disposeResources(env_3);
+    }
+}
+// ---------------------------------------------------------------------------
+// Lifecycle guard
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the handle has not been disposed.
+ * Provides a named alternative to checking `.disposed` directly.
+ *
+ * ```ts
+ * if (!isLive(handle)) return err(validationError('DISPOSED_HANDLE', '...'));
+ * ```
+ */
+export function isLive(handle) {
+    return !handle.disposed;
+}
+//# sourceMappingURL=disposal.js.map

package/dist/vendored/brepjs/core/disposal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposal.js","sourceRoot":"","sources":["../../../../src/vendored/brepjs/core/disposal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource disposal system using Symbol.dispose (TC39 Explicit Resource Management).\n *\n * All kernel handles are wrapped in disposable objects:\n *   using solid = createSolid(ocShape);\n *   // auto-disposed at end of scope\n *\n * FinalizationRegistry serves as a safety net for handles not explicitly disposed.\n */\n\nimport type { KernelShape } from '../kernel/types.js';\nimport { getKernel } from '../kernel/index.js';\nimport { isUnsupportedKernelOperationError } from '../kernel/unsupported.js';\nimport type { BrepError } from './errors.js';\nimport type { Result } from './result.js';\n\n// ---------------------------------------------------------------------------\n// Symbol.dispose polyfill — Safari and older browsers lack the well-known\n// symbol. esbuild's `using` transform falls back to Symbol.for(\"Symbol.dispose\"),\n// but [Symbol.dispose]() property keys use the raw symbol. This polyfill\n// bridges the gap so both resolve to the same key.  (#326)\n// ---------------------------------------------------------------------------\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- patching global Symbol\nconst S = Symbol as any;\nS.dispose ??= Symbol.for('Symbol.dispose');\nS.asyncDispose ??= Symbol.for('Symbol.asyncDispose');\n\n// ---------------------------------------------------------------------------\n// Deletable interface (same as before)\n// ---------------------------------------------------------------------------\n\n/** Any object that can be cleaned up by calling `delete()` (kernel WASM objects). */\nexport interface Deletable {\n  delete: () => void;\n}\n\n// ---------------------------------------------------------------------------\n// FinalizationRegistry safety net\n// ---------------------------------------------------------------------------\n\ninterface GlobalWithRegistry {\n  FinalizationRegistry?: typeof FinalizationRegistry;\n}\n\nconst globalWithRegistry = globalThis as GlobalWithRegistry;\n\nif (!globalWithRegistry.FinalizationRegistry) {\n  console.warn('faijs: FinalizationRegistry unavailable — garbage collection will not work');\n  globalWithRegistry.FinalizationRegistry = class NoOpFinalizationRegistry {\n    register(_target: object, _heldValue: unknown, _unregisterToken?: object): void {\n      // no-op\n    }\n\n    unregister(_unregisterToken: object): boolean {\n      return false;\n    }\n  } as unknown as typeof FinalizationRegistry;\n}\n\n// ---------------------------------------------------------------------------\n// DisposalStats — lightweight resource tracking for debugging WASM leaks\n// ---------------------------------------------------------------------------\n\n/** Statistics about WASM handle lifecycle. Zero overhead when not queried. */\nexport interface DisposalStats {\n  /** Number of handles currently alive (not disposed). */\n  liveHandles: number;\n  /** Peak number of simultaneously live handles. */\n  peakHandles: number;\n  /** Number of handles reclaimed by FinalizationRegistry (GC safety net). */\n  gcCollected: number;\n  /** Number of DisposalScope.enter() calls. */\n  scopeEnters: number;\n  /** Number of DisposalScope.dispose() calls. */\n  scopeExits: number;\n}\n\nconst _stats: DisposalStats = {\n  liveHandles: 0,\n  peakHandles: 0,\n  gcCollected: 0,\n  scopeEnters: 0,\n  scopeExits: 0,\n};\n\n/** Get a snapshot of current disposal statistics. */\nexport function getDisposalStats(): Readonly<DisposalStats> {\n  return { ..._stats };\n}\n\n/** Reset all disposal statistics to zero. */\nexport function resetDisposalStats(): void {\n  _stats.liveHandles = 0;\n  _stats.peakHandles = 0;\n  _stats.gcCollected = 0;\n  _stats.scopeEnters = 0;\n  _stats.scopeExits = 0;\n}\n\nfunction trackHandleCreated(): void {\n  _stats.liveHandles++;\n  if (_stats.liveHandles > _stats.peakHandles) {\n    _stats.peakHandles = _stats.liveHandles;\n  }\n}\n\nfunction trackHandleDisposed(): void {\n  _stats.liveHandles--;\n}\n\nfunction trackGcCollected(): void {\n  _stats.gcCollected++;\n  _stats.liveHandles--;\n}\n\nconst registry = new FinalizationRegistry<Deletable>((heldValue) => {\n  trackGcCollected();\n  try {\n    heldValue.delete();\n  } catch {\n    // Already deleted or invalid — ignore\n  }\n});\n\n// ---------------------------------------------------------------------------\n// Shape wrapper\n// ---------------------------------------------------------------------------\n\n/** A shape wrapper with Symbol.dispose for auto-cleanup. */\nexport interface ShapeHandle {\n  /** The raw kernel shape handle */\n  readonly wrapped: KernelShape;\n\n  /** Manually dispose the kernel handle */\n  [Symbol.dispose](): void;\n\n  /** Alias for Symbol.dispose — required for Deletable compatibility. */\n  delete(): void;\n\n  /** Check if this handle has been disposed */\n  readonly disposed: boolean;\n\n  /**\n   * Register a callback to run when this handle is disposed, before its kernel\n   * slot is released. Used to release dependent resources tied to this shape's\n   * lifetime (e.g. its cached sub-shape handles). Callbacks are invoked once,\n   * in registration order; a callback that throws is swallowed. Registering on\n   * an already-disposed handle runs the callback immediately.\n   */\n  onDispose(callback: () => void): void;\n}\n\n/** Create a disposable shape handle. */\nexport function createHandle(ocShape: KernelShape): ShapeHandle {\n  // Capture the owning kernel now: on the occt-wasm arena kernel a shape's own\n  // `delete()` is a no-op, so the slot is only reclaimed via `kernel.dispose()`\n  // (→ `k.release(id)`). Routing disposal through the kernel makes `using` free\n  // the slot on every kernel. Embind kernels keep their existing `.delete()`\n  // behaviour (`kernel.dispose` falls through to it). `k.release` is idempotent,\n  // so overlap with `disposeResultShape`/`disposeDowncastSource` is safe.\n  const kernel = getKernel();\n  let disposed = false;\n  let onDisposeCallbacks: (() => void)[] | undefined;\n\n  const runOnDispose = () => {\n    if (!onDisposeCallbacks) return;\n    for (const cb of onDisposeCallbacks) {\n      try {\n        cb();\n      } catch {\n        // A dependent-cleanup failure must not abort disposal.\n      }\n    }\n    onDisposeCallbacks = undefined;\n  };\n\n  const dispose = () => {\n    if (!disposed) {\n      disposed = true;\n      trackHandleDisposed();\n      registry.unregister(handle);\n      // Release dependents (e.g. cached sub-shapes) before this slot goes.\n      runOnDispose();\n      try {\n        kernel.dispose(ocShape);\n      } catch {\n        // Already deleted — ignore\n      }\n    }\n  };\n\n  const handle: ShapeHandle = {\n    get wrapped() {\n      if (disposed) throw new Error('Shape handle has been disposed');\n      return ocShape;\n    },\n\n    get disposed() {\n      return disposed;\n    },\n\n    [Symbol.dispose]() {\n      dispose();\n    },\n\n    delete() {\n      dispose();\n    },\n\n    onDispose(callback: () => void) {\n      if (disposed) {\n        callback();\n        return;\n      }\n      (onDisposeCallbacks ??= []).push(callback);\n    },\n  };\n\n  trackHandleCreated();\n  // GC safety net: route the finalizer through the kernel too, else arena slots\n  // survive collection on occt-wasm. The closure holds `ocShape`/`kernel` (not\n  // `handle`), so it never keeps the handle itself alive.\n  registry.register(\n    handle,\n    {\n      delete: () => {\n        kernel.dispose(ocShape);\n      },\n    },\n    handle\n  );\n  return handle;\n}\n\n/**\n * Wrap a raw kernel shape as a **non-owning** handle: `wrapped` exposes the same\n * arena slot as an owning handle would, but `dispose`/`delete` are no-ops and the\n * slot is never registered with the finalizer or the stats counters.\n *\n * Use for borrowed views into another owner's slot — e.g. the topology cache's\n * adjacency handles. On occt-wasm >= 3.7.0 an identity `downcast` returns the\n * *same* slot id (not a duplicate), so branding a cache slot as an owning handle\n * would let the borrower's dispose free a slot the cache still points at. A\n * borrowed handle keeps the slot's identity (`isSame`/`hashCode` still match the\n * cache) while leaving ownership — and disposal — with the cache. The view is\n * only valid while its owner lives; `clone()`/`copyShape` it to outlive that.\n */\nexport function createBorrowedHandle(ocShape: KernelShape): ShapeHandle {\n  const noop = () => {};\n  return {\n    get wrapped() {\n      return ocShape;\n    },\n    get disposed() {\n      return false;\n    },\n    [Symbol.dispose]: noop,\n    delete: noop,\n    // Intentionally a no-op: a borrowed view never disposes, so a callback would\n    // never fire. Tie dependent lifetimes to the owning parent's handle instead.\n    onDispose: noop,\n  };\n}\n\n/**\n * Run `fn` between an arena checkpoint and restore, reclaiming every slot it\n * allocates — including kernel-internal query temporaries brepjs holds no handle\n * for (e.g. `distance`/`boundingBox` scratch) — in a single `restoreCheckpoint`.\n *\n * **SAFE ONLY when `fn` returns plain data** (numbers, points, arrays): restore\n * frees *every* slot allocated after the checkpoint, so a live shape handle in\n * the return value would dangle. Use for data-returning batch analysis over many\n * bodies; never to wrap a shape builder. Inputs allocated before the call are\n * untouched (restore only frees from the mark forward).\n *\n * No-op wrapper on kernels without arena checkpoints (occt/manifold): `fn` runs\n * directly and those kernels' own disposal applies.\n */\nexport function withArenaCheckpoint<T>(fn: () => T): T {\n  const kernel = getKernel();\n  let cp: number;\n  try {\n    cp = kernel.checkpoint();\n  } catch (e) {\n    if (!isUnsupportedKernelOperationError(e)) throw e;\n    return fn();\n  }\n  let result: T;\n  try {\n    result = fn();\n  } catch (e) {\n    // fn's error is primary: still restore, but never let a restore failure mask\n    // it (a plain `finally { restore() }` would swallow the original throw).\n    try {\n      kernel.restoreCheckpoint(cp);\n    } catch {\n      /* surface fn's error instead */\n    }\n    throw e;\n  }\n  // Success path: a restore failure here is a genuine bug — let it surface.\n  kernel.restoreCheckpoint(cp);\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Generic kernel object wrapper\n// ---------------------------------------------------------------------------\n\n/** A disposable wrapper for any kernel object. */\nexport interface KernelHandle<T extends Deletable> {\n  readonly value: T;\n  readonly disposed: boolean;\n  [Symbol.dispose](): void;\n}\n\n/** Create a disposable handle for any kernel object. */\nexport function createKernelHandle<T extends Deletable>(ocObj: T): KernelHandle<T> {\n  let disposed = false;\n\n  const handle: KernelHandle<T> = {\n    get value() {\n      if (disposed) throw new Error('kernel handle has been disposed');\n      return ocObj;\n    },\n\n    get disposed() {\n      return disposed;\n    },\n\n    [Symbol.dispose]() {\n      if (!disposed) {\n        disposed = true;\n        trackHandleDisposed();\n        registry.unregister(handle);\n        try {\n          ocObj.delete();\n        } catch {\n          // Already deleted\n        }\n      }\n    },\n  };\n\n  trackHandleCreated();\n  registry.register(handle, ocObj, handle);\n  return handle;\n}\n\n// ---------------------------------------------------------------------------\n// Scoped resource management\n// ---------------------------------------------------------------------------\n\n/** Scope for tracking multiple disposable resources. */\nexport class DisposalScope implements Disposable {\n  private readonly handles: (() => void)[] = [];\n\n  constructor() {\n    _stats.scopeEnters++;\n  }\n\n  /** Register a resource for disposal when scope ends. */\n  register<T extends Deletable>(resource: T): T {\n    this.handles.push(() => {\n      try {\n        // A shape handle's `.delete()` is a no-op on arena kernels (occt-wasm);\n        // its slot is only reclaimed through `Symbol.dispose` → `kernel.dispose`.\n        // Prefer that when present, so a shape registered here is actually freed;\n        // raw WASM objects (no `Symbol.dispose`) fall back to `.delete()`.\n        const disposer = (resource as Partial<Disposable>)[Symbol.dispose];\n        if (typeof disposer === 'function') disposer.call(resource);\n        else resource.delete();\n      } catch {\n        // Already deleted\n      }\n    });\n    return resource;\n  }\n\n  /** Register a disposable for disposal when scope ends. */\n  track<T extends Disposable>(disposable: T): T {\n    this.handles.push(() => {\n      try {\n        disposable[Symbol.dispose]();\n      } catch {\n        // Already disposed or invalid — ignore\n      }\n    });\n    return disposable;\n  }\n\n  [Symbol.dispose](): void {\n    _stats.scopeExits++;\n    // Dispose in reverse order (LIFO)\n    for (let i = this.handles.length - 1; i >= 0; i--) {\n      this.handles[i]?.();\n    }\n    this.handles.length = 0;\n  }\n}\n\n/** Execute a function with a disposal scope. Resources registered with the scope\n *  are automatically cleaned up when the function returns. */\nexport function withScope<T>(fn: (scope: DisposalScope) => T): T {\n  using scope = new DisposalScope();\n  return fn(scope);\n}\n\n// ---------------------------------------------------------------------------\n// FinalizationRegistry helpers for non-branded wrappers (e.g. Curve2D)\n// ---------------------------------------------------------------------------\n\n/** Register `deletable` for GC cleanup when `owner` is collected. */\nexport function registerForCleanup(owner: object, deletable: Deletable): void {\n  registry.register(owner, deletable, deletable);\n}\n\n/** Unregister a previously-registered deletable (call before manual delete). */\nexport function unregisterFromCleanup(deletable: Deletable): void {\n  registry.unregister(deletable);\n}\n\n// ---------------------------------------------------------------------------\n// Result-aware scope helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Run fn inside a DisposalScope. The scope is disposed on all exit paths:\n * Ok return, Err return, and throw. Use in any function that allocates\n * kernel objects and returns Result<T>.\n *\n * ```ts\n * return withScopeResult((scope) => {\n *   const axis = scope.register(makeKernelAx1(origin, dir));\n *   return ok(castShape(getKernel().makeSomething(axis)) as Solid);\n * });\n * ```\n */\nexport function withScopeResult<T, E = BrepError>(\n  fn: (scope: DisposalScope) => Result<T, E>\n): Result<T, E> {\n  using scope = new DisposalScope();\n  return fn(scope);\n}\n\n/**\n * Async variant of withScopeResult. The scope is disposed after the\n * returned promise settles (resolved or rejected).\n */\nexport async function withScopeResultAsync<T, E = BrepError>(\n  fn: (scope: DisposalScope) => Promise<Result<T, E>>\n): Promise<Result<T, E>> {\n  using scope = new DisposalScope();\n  return await fn(scope);\n}\n\n// ---------------------------------------------------------------------------\n// Lifecycle guard\n// ---------------------------------------------------------------------------\n\n/**\n * Returns true if the handle has not been disposed.\n * Provides a named alternative to checking `.disposed` directly.\n *\n * ```ts\n * if (!isLive(handle)) return err(validationError('DISPOSED_HANDLE', '...'));\n * ```\n */\nexport function isLive(handle: ShapeHandle | KernelHandle<Deletable>): boolean {\n  return !handle.disposed;\n}\n"]}