cad-kernel-r3f

R3F/Three.js addon to render DAG payloads by calling kernel-api and displaying STL meshes.

Summary

This package provides:

• a typed kernel-api STL client (fetchKernelStl, compileDagToStl)
• STL-to-THREE.BufferGeometry conversion (createGeometryFromStlBytes)
• JSON mesh helpers for format: "json": createBufferGeometryFromKernelFaces, getOrCreateMeshGeometryByHash (cache by kernel mesh hash for repeated parts)
• a React hook (useKernelStl)
• a ready-to-use R3F component (KernelStlMesh)

Install

npm install @cadbuildr/cad-kernel-r3f

Peer dependencies:

• react
• three
• @react-three/fiber

Quick start

import { Canvas } from "@react-three/fiber";
import { KernelStlMesh, createKernelApiClient } from "@cadbuildr/cad-kernel-r3f";

const dag = {
  version: "1.0",
  rootNodeId: "root",
  DAG: {},
  serializableNodes: {},
};

const client = createKernelApiClient({ defaultKernel: "replicad" });

export function App() {
  return (
    <Canvas camera={{ position: [6, 5, 8], fov: 45 }}>
      <ambientLight intensity={1.2} />
      <directionalLight intensity={0.8} position={[10, 10, 10]} />
      <KernelStlMesh dag={dag} client={client} color="#f97316" />
    </Canvas>
  );
}

API

All render requests go to https://kernel-api.cadbuildr.com (see exported CADBUILDR_KERNEL_API_BASE_URL). The base URL is not configurable.

Apps that need per-instance colors call the same endpoint with format: "json", then build meshes from mesh.store / mesh.partInstances. Use getOrCreateMeshGeometryByHash(hash, faces) so identical topologies share one BufferGeometry.

• fetchKernelStl(args) -> fetches binary STL from POST /v1/kernels/:kernel/render
• compileDagToStl(args) -> same call with normalized response shape
• createGeometryFromStlBytes(bytes) -> converts binary STL to BufferGeometry
• createBufferGeometryFromKernelFaces(faces) / getOrCreateMeshGeometryByHash(hash, faces, options?) -> JSON mesh faces to BufferGeometry (cached)
• clearKernelJsonMeshGeometryCache() / getKernelJsonMeshGeometryCacheSize() / configureKernelJsonMeshGeometryCache(cap) -> cache control
• useKernelStl(options) -> hook returning { geometry, stlBytes, isLoading, error, requestId }
• KernelStlMesh -> opinionated render component over useKernelStl

Development

npm install
npm test
npm run type-check

Publishing

Ensure you are logged into npm with access to the @cadbuildr scope, then:

npm publish --access public

Browser pipeline (with cad-pyodide-runtime)

A typical static app combines @cadbuildr/cad-pyodide-runtime (run foundation Python in Pyodide and read the DAG) with this package (post the DAG to kernel-api and render STL in R3F). Keep that wiring in the consuming app; this package stays focused on the kernel STL client and mesh rendering.

KernelApiClient binds globalThis.fetch when calling the kernel: Pyodide replaces fetch, and an unbound reference would throw Illegal invocation in strict mode.