@toolpath/viewer 0.2.0

package/dist/engine/index.d.ts

@@ -0,0 +1,118 @@
+import { P as PartModel, a as PartMeshRefs } from '../normalize-B0HBvzGu.js';
+export { E as EnginePart, b as EnginePartProps, M as MIN_KERNEL_VERSION, c as assertSupportedKernelVersion, n as normalizePartReport, s as smoothRegionNormals } from '../normalize-B0HBvzGu.js';
+import { BufferGeometry } from 'three';
+import 'react';
+
+/** What the cache needs of a part: the artifact to fetch, and how to shade it. */
+type CacheablePart = Pick<PartModel, 'mesh' | 'regions'>;
+interface EngineGeometryResource {
+    status: 'pending' | 'fulfilled' | 'rejected';
+    promise: Promise<void>;
+    geometry?: BufferGeometry;
+    error?: Error;
+    references: number;
+    lastAccess: number;
+}
+interface EngineGeometryCache {
+    get(part: CacheablePart): EngineGeometryResource;
+    retain(resource: EngineGeometryResource): void;
+    release(resource: EngineGeometryResource): void;
+    clear(): void;
+}
+/**
+ * The cache key.
+ *
+ * Deliberately not the presigned URL: those carry a signature and an expiry, so
+ * two reports of the same part fetched a minute apart would miss every time.
+ * The path is the artifact's identity and the query string is not.
+ */
+declare function engineGeometryResourceKey(mesh: PartMeshRefs): string;
+/**
+ * A small reference-aware LRU cache for Engine mesh artifacts. Rendered parts
+ * retain their source geometry; released entries are evicted and disposed once
+ * the cache exceeds its capacity.
+ */
+declare function createEngineGeometryCache(loadGeometry?: (part: CacheablePart) => Promise<BufferGeometry>, maximumEntries?: number): EngineGeometryCache;
+declare const engineGeometryCache: EngineGeometryCache;
+
+/**
+ * A mesh that cannot be paired with its report.
+ *
+ * Every case is a contract mismatch caught at load, which is the whole point:
+ * the alternative is a report and a mesh that disagree about which triangle is
+ * which, and that surfaces as *the wrong surface highlighting* — a shader bug
+ * to anyone debugging it, hours from its cause.
+ */
+declare class PartMeshError extends Error {
+    readonly name = "PartMeshError";
+}
+/** What the report says the mesh contains. Checked, never trusted. */
+type PartMeshExpectation = Pick<PartMeshRefs, 'pointCount' | 'triangleCount'>;
+type MeshFormat = 'glb' | 'stl';
+interface MeshAsset {
+    format: MeshFormat;
+    url: string;
+}
+type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<Response>;
+interface LoadPartGeometryOptions {
+    /** Inject to route through a backend, or to serve a fixture in a test. */
+    readonly fetch?: FetchLike;
+    readonly signal?: AbortSignal;
+}
+/** The mesh artifacts to try, in order: GLB first, STL as a fallback. */
+declare function partMeshAssets(mesh: Pick<PartMeshRefs, 'glbUrl' | 'stlUrl'>): MeshAsset[];
+/**
+ * Fetches a part's mesh and prepares it for rendering and picking.
+ *
+ * The URL is passed separately rather than read off `PartMeshRefs` because it
+ * is the one field that goes stale: presigns live fifteen minutes, so the
+ * caller decides what to fetch and when.
+ */
+declare function loadPartGeometry(url: string, mesh: PartMeshExpectation, options?: LoadPartGeometryOptions & {
+    format?: MeshFormat;
+}): Promise<BufferGeometry>;
+/**
+ * Loads whichever mesh artifact a report actually carries, preferring GLB.
+ *
+ * The STL fallback is not redundancy for its own sake: a report can carry one
+ * URL and not the other, and an STL still satisfies the triangle-order contract
+ * the region ranges depend on. Every attempt's failure is kept, because "the
+ * GLB 403'd and the STL was not a mesh" is two different problems and a caller
+ * shown only the second would chase the wrong one.
+ */
+declare function loadPartMesh(mesh: PartMeshRefs, options?: LoadPartGeometryOptions): Promise<BufferGeometry>;
+/**
+ * Parses a mesh into the geometry the renderer and the region index share.
+ *
+ * Three things happen here, and each one is load-bearing:
+ *
+ * - **De-index, always.** The Engine writes an indexed GLB with shared vertices
+ *   (the cube: 8 vertices, 36 indices). The region highlight is a *per-vertex*
+ *   attribute, and a shared corner vertex belongs to three regions at once, so
+ *   there is no value to write into it. Non-indexed is not an optimization
+ *   here, it is what makes region attributes expressible.
+ * - **Compute normals, if the mesh ships none.** The GLB currently ships
+ *   `POSITION` only. Doing this *after* de-indexing is what gives faceted CAD
+ *   shading; the other order smooth-shades a cube, which reads as a rendering
+ *   bug rather than the data-handling one it is.
+ * - **Check the counts.** The report's region ranges index this triangle
+ *   buffer. If the two disagree about how many triangles there are, they are
+ *   not the same artifact and nothing downstream can be trusted.
+ *
+ * Coordinates are passed through untouched: the Engine emits millimetres, Z-up,
+ * usually with a corner at the origin, and `GLTFLoader` does not rotate a scene
+ * to the glTF Y-up convention. Centring and framing are the camera's business,
+ * not the loader's — region geometry is quoted in part space, so part space is
+ * what gets rendered.
+ *
+ * `toNonIndexed()` renumbers nothing at the triangle level: it walks the index
+ * buffer in order, three vertices at a time, so triangle `i` stays triangle
+ * `i`. That is what makes it safe to apply before region ranges, and it is
+ * asserted against the real cube in `geometry.test.ts` because it looks
+ * dangerous and is not.
+ */
+declare function parsePartGeometry(data: ArrayBuffer, mesh: PartMeshExpectation, format?: MeshFormat): Promise<BufferGeometry>;
+
+export { type CacheablePart, type EngineGeometryCache, type EngineGeometryResource, type FetchLike, type LoadPartGeometryOptions, type MeshAsset, type MeshFormat, PartMeshError, type PartMeshExpectation, createEngineGeometryCache, engineGeometryCache, engineGeometryResourceKey, loadPartGeometry, loadPartMesh, parsePartGeometry, partMeshAssets };

package/dist/engine/index.js

@@ -0,0 +1,30 @@
+import {
+  EnginePart,
+  MIN_KERNEL_VERSION,
+  PartMeshError,
+  assertSupportedKernelVersion,
+  createEngineGeometryCache,
+  engineGeometryCache,
+  engineGeometryResourceKey,
+  loadPartGeometry,
+  loadPartMesh,
+  normalizePartReport,
+  parsePartGeometry,
+  partMeshAssets,
+  smoothRegionNormals
+} from "../chunk-7NQBV7EQ.js";
+export {
+  EnginePart,
+  MIN_KERNEL_VERSION,
+  PartMeshError,
+  assertSupportedKernelVersion,
+  createEngineGeometryCache,
+  engineGeometryCache,
+  engineGeometryResourceKey,
+  loadPartGeometry,
+  loadPartMesh,
+  normalizePartReport,
+  parsePartGeometry,
+  partMeshAssets,
+  smoothRegionNormals
+};