@holoscript/plugin-film3d-volumetrics 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @holoscript/plugin-film3d-volumetrics
+
+## 2.0.2
+
+### Patch Changes
+
+- Updated dependencies [c64fc1a]
+  - @holoscript/core@8.0.6
+
+## 2.0.0
+
+### Patch Changes
+
+- @holoscript/core@6.1.0
+- @holoscript/crdt-spatial@1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@holoscript/plugin-film3d-volumetrics",
+  "version": "2.0.2",
+  "main": "src/index.ts",
+  "dependencies": {
+    "@holoscript/crdt-spatial": "^1.0.2"
+  },
+  "peerDependencies": {
+    "loro-crdt": "^1.0.0",
+    "@holoscript/core": "8.0.6"
+  },
+  "peerDependenciesMeta": {
+    "loro-crdt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "loro-crdt": "^1.0.0",
+    "typescript": "~5.9.3"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  }
+}

package/src/crdt-spatial-augment.ts

@@ -0,0 +1,17 @@
+/**
+ * Merges volumetric CRDT helpers into `@holoscript/crdt-spatial` typings.
+ * The package bundled `index.d.ts` can omit string re-exports; runtime `dist/index.js` includes them.
+ */
+import type { LoroDoc, LoroMap } from 'loro-crdt';
+
+declare module '@holoscript/crdt-spatial' {
+  // @ts-ignore -- augmenting an already-exported const from the runtime module
+  export const FILM3D_VOLUMETRICS_ROOT: 'film3d_volumetrics';
+  export function ensureFilm3dVolumetricsRoot(doc: LoroDoc): LoroMap<Record<string, unknown>>;
+  export function registerVolumetricNode(doc: LoroDoc, nodeId: string, meta: { format: string }): void;
+  export function setVolumetricChunk(doc: LoroDoc, nodeId: string, chunkIndex: number, data: Uint8Array): void;
+  export function setVolumetricVoxelPayload(doc: LoroDoc, nodeId: string, data: Uint8Array): void;
+  export function unregisterVolumetricNode(doc: LoroDoc, nodeId: string): void;
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,66 @@
+import './crdt-spatial-augment';
+
+export { createVolumetricHandler, type VolumetricConfig, type VolumetricFormat } from './traits/VolumetricTrait';
+export { createGaussianSplatHandler, type GaussianSplatConfig } from './traits/GaussianSplatTrait';
+export { createNeRFHandler, type NeRFConfig, type NeRFMethod } from './traits/NeRFTrait';
+export { createCinematicCameraHandler, type CinematicCameraConfig, type CameraMovement } from './traits/CinematicCameraTrait';
+export {
+  createGCodeSlicerHandler,
+  type GCodeSlicerConfig,
+  type GCodeSlicerState,
+  type GCodeSemanticParams,
+  type MeshSliceInput,
+  type AdhesionLayerPlanEntry,
+  type TraversalLayerPlan,
+  buildAdhesionLayerPlan,
+  buildInsetPerimeterTraversal,
+  buildSemanticGCodePreamble,
+  buildTraversalStackFromMesh
+} from './traits/GCodeSlicerTrait';
+export * from './traits/types';
+
+import {
+  FILM3D_VOLUMETRICS_ROOT,
+  ensureFilm3dVolumetricsRoot,
+  registerVolumetricNode,
+  setVolumetricChunk,
+  setVolumetricVoxelPayload,
+  unregisterVolumetricNode
+} from '@holoscript/crdt-spatial';
+import { createVolumetricHandler } from './traits/VolumetricTrait';
+import { createGaussianSplatHandler } from './traits/GaussianSplatTrait';
+import { createNeRFHandler } from './traits/NeRFTrait';
+import { createCinematicCameraHandler } from './traits/CinematicCameraTrait';
+import { createGCodeSlicerHandler } from './traits/GCodeSlicerTrait';
+
+export {
+  FILM3D_VOLUMETRICS_ROOT,
+  ensureFilm3dVolumetricsRoot,
+  registerVolumetricNode,
+  setVolumetricChunk,
+  setVolumetricVoxelPayload,
+  unregisterVolumetricNode
+};
+
+import type { LoroDoc } from 'loro-crdt';
+
+/**
+ * Eagerly registers the volumetrics root map on the provided Loro doc so that
+ * the LoroWebRTCProvider includes VDB / voxel payloads in every `export({ mode: 'update' })`
+ * emitted to peers — guaranteeing zero-data-loss volumetric sync from connection start.
+ *
+ * Call once after constructing `MeshNodeIntegrator` and before the first
+ * `registerVolumetricNode` / `setVolumetricVoxelPayload` invocation.
+ */
+export function registerVolumetricsWithProvider(doc: LoroDoc): void {
+  ensureFilm3dVolumetricsRoot(doc);
+}
+
+export const pluginMeta = {
+  name: '@holoscript/plugin-film3d-volumetrics',
+  version: '1.0.0',
+  traits: ['volumetric', 'gaussian_splat', 'nerf', 'cinematic_camera', 'gcode_slicer'],
+  /** Root map on the shared Loro doc replicated by LoroWebRTCProvider */
+  crdtVolumetricsRoot: FILM3D_VOLUMETRICS_ROOT
+};
+export const traitHandlers = [createVolumetricHandler(), createGaussianSplatHandler(), createNeRFHandler(), createCinematicCameraHandler(), createGCodeSlicerHandler()];

package/src/traits/CinematicCameraTrait.ts

@@ -0,0 +1,25 @@
+/** @cinematic_camera Trait — Film-grade virtual camera control. @trait cinematic_camera */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type CameraMovement = 'static' | 'dolly' | 'truck' | 'pedestal' | 'pan' | 'tilt' | 'roll' | 'crane' | 'steadicam' | 'drone' | 'handheld';
+export interface CinematicCameraConfig { focalLengthMm: number; sensorWidth: number; sensorHeight: number; tStop: number; focusDistanceM: number; movement: CameraMovement; shutterAngle: number; iso: number; whiteBalanceK: number; anamorphic: boolean; }
+
+const defaultConfig: CinematicCameraConfig = { focalLengthMm: 50, sensorWidth: 36, sensorHeight: 24, tStop: 2.8, focusDistanceM: 3, movement: 'static', shutterAngle: 180, iso: 800, whiteBalanceK: 5600, anamorphic: false };
+
+export function createCinematicCameraHandler(): TraitHandler<CinematicCameraConfig> {
+  return { name: 'cinematic_camera', defaultConfig,
+    onAttach(n: HSPlusNode, c: CinematicCameraConfig, ctx: TraitContext) {
+      const fovDeg = 2 * Math.atan(c.sensorWidth / (2 * c.focalLengthMm)) * (180 / Math.PI);
+      n.__camState = { fovDeg, isRecording: false, frameCount: 0, dofBlurRadius: c.focalLengthMm / (2 * c.tStop) };
+      ctx.emit?.('camera:configured', { focal: c.focalLengthMm, fov: fovDeg, movement: c.movement });
+    },
+    onDetach(n: HSPlusNode, _c: CinematicCameraConfig, ctx: TraitContext) { delete n.__camState; ctx.emit?.('camera:removed'); },
+    onUpdate(n: HSPlusNode, _c: CinematicCameraConfig, _ctx: TraitContext, _d: number) { const s = n.__camState as Record<string, unknown> | undefined; if (s?.isRecording) (s.frameCount as number)++; },
+    onEvent(n: HSPlusNode, _c: CinematicCameraConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__camState as Record<string, unknown> | undefined; if (!s) return;
+      if (e.type === 'camera:record') { s.isRecording = true; ctx.emit?.('camera:recording'); }
+      if (e.type === 'camera:cut') { s.isRecording = false; ctx.emit?.('camera:cut', { frames: s.frameCount }); s.frameCount = 0; }
+      if (e.type === 'camera:rack_focus') { ctx.emit?.('camera:focus_pulling', { to: e.payload?.distance }); }
+    },
+  };
+}

package/src/traits/GCodeSlicerTrait.ts

@@ -0,0 +1,273 @@
+/** @gcode_slicer Trait — Volumetric extraction to GCode for 3D printing. @trait gcode_slicer */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+/**
+ * Semantic @GCodeSlicer parameters (Studio / HS+ binding surface).
+ * Maps volumetric → print planning: nozzle/bed thermal policy, adhesion stack, and XY traversal.
+ */
+export interface GCodeSemanticParams {
+  /** Primary extruder / nozzle temperature (°C) — `M104 S` */
+  nozzleTempC: number;
+  /** Heated bed setpoint (°C) — `M140` / `M190` */
+  bedTempC: number;
+  /** Extra °C on the nozzle for the first adhesion layers */
+  firstLayerNozzleBoostC: number;
+  /** Count of slower / hotter adhesion layers above the bed */
+  adhesionLayerCount: number;
+  /** Layer height used for the adhesion raft stack (often ≥ normal layer height) */
+  adhesionLayerHeightMm: number;
+  /** Brim / raft outline inset from mesh XY bounds (mm) */
+  adhesionBrimMm: number;
+}
+
+export interface GCodeSlicerConfig extends GCodeSemanticParams {
+  layerHeightMm: number;
+  infillPercent: number;
+  printSpeedMmS: number;
+}
+
+export interface MeshSliceInput {
+  /** Mesh vertices in millimeters (world or object space). */
+  verticesMm: [number, number, number][];
+  /** Optional triangle corner indices (multiple of 3). */
+  indices?: number[];
+}
+
+export interface AdhesionLayerPlanEntry {
+  layerIndex: number;
+  zMm: number;
+  nozzleTempC: number;
+}
+
+export interface TraversalLayerPlan {
+  layerZMm: number;
+  /** Tool-center polyline in mm (XY with implicit Z = layerZMm). */
+  pointsMm: [number, number, number][];
+}
+
+export interface GCodeSlicerState {
+  isSlicing: boolean;
+  progressPercent: number;
+  estimatedPrintTimeMs: number;
+  outputGCodePath?: string;
+  /** Last bound mesh + derived semantic plans */
+  mesh?: MeshSliceInput;
+  adhesionPlan?: AdhesionLayerPlanEntry[];
+  traversal?: TraversalLayerPlan[];
+  /** Short G-code preamble reflecting current semantic params */
+  gcodePreamble?: string;
+}
+
+const defaultConfig: GCodeSlicerConfig = {
+  layerHeightMm: 0.2,
+  infillPercent: 20,
+  nozzleTempC: 210,
+  bedTempC: 60,
+  firstLayerNozzleBoostC: 10,
+  adhesionLayerCount: 3,
+  adhesionLayerHeightMm: 0.25,
+  adhesionBrimMm: 2,
+  printSpeedMmS: 50
+};
+
+function bbox2D(vertices: [number, number, number][]): { minX: number; maxX: number; minY: number; maxY: number } {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of vertices) {
+    minX = Math.min(minX, x);
+    maxX = Math.max(maxX, x);
+    minY = Math.min(minY, y);
+    maxY = Math.max(maxY, y);
+  }
+  if (!Number.isFinite(minX)) {
+    return { minX: 0, maxX: 10, minY: 0, maxY: 10 };
+  }
+  return { minX, maxX, minY, maxY };
+}
+
+/** Bed adhesion layer Z offsets and per-layer nozzle targets. */
+export function buildAdhesionLayerPlan(c: GCodeSlicerConfig): AdhesionLayerPlanEntry[] {
+  const out: AdhesionLayerPlanEntry[] = [];
+  let z = 0;
+  for (let i = 0; i < c.adhesionLayerCount; i++) {
+    const temp = c.nozzleTempC + (i === 0 ? c.firstLayerNozzleBoostC : Math.max(0, c.firstLayerNozzleBoostC - i * 3));
+    out.push({ layerIndex: i, zMm: z + c.adhesionLayerHeightMm, nozzleTempC: Math.round(temp) });
+    z += c.adhesionLayerHeightMm;
+  }
+  return out;
+}
+
+/**
+ * Approximate traversal polyline for a layer: inset rectangle perimeter in XY at fixed Z.
+ * Sufficient as a structural placeholder until full slice-to-path is wired.
+ */
+export function buildInsetPerimeterTraversal(
+  verticesMm: [number, number, number][],
+  layerZMm: number,
+  insetMm: number,
+  segmentsPerEdge = 8
+): [number, number, number][] {
+  const { minX, maxX, minY, maxY } = bbox2D(verticesMm);
+  const ix0 = minX + insetMm;
+  const ix1 = maxX - insetMm;
+  const iy0 = minY + insetMm;
+  const iy1 = maxY - insetMm;
+  if (ix1 <= ix0 || iy1 <= iy0) {
+    return [
+      [minX, minY, layerZMm],
+      [maxX, minY, layerZMm],
+      [maxX, maxY, layerZMm],
+      [minX, maxY, layerZMm],
+      [minX, minY, layerZMm]
+    ];
+  }
+  const edge = (x0: number, y0: number, x1: number, y1: number): [number, number, number][] => {
+    const pts: [number, number, number][] = [];
+    for (let i = 0; i <= segmentsPerEdge; i++) {
+      const t = i / segmentsPerEdge;
+      pts.push([x0 + (x1 - x0) * t, y0 + (y1 - y0) * t, layerZMm]);
+    }
+    return pts;
+  };
+  return [
+    ...edge(ix0, iy0, ix1, iy0),
+    ...edge(ix1, iy0, ix1, iy1).slice(1),
+    ...edge(ix1, iy1, ix0, iy1).slice(1),
+    ...edge(ix0, iy1, ix0, iy0).slice(1)
+  ];
+}
+
+/** G-code header: thermal + units + adhesion-aware first moves (semantic binding). */
+export function buildSemanticGCodePreamble(c: GCodeSlicerConfig, mesh?: MeshSliceInput): string {
+  const lines: string[] = [
+    '; @GCodeSlicer — semantic preamble (HoloScript)',
+    'G21 ; millimeters',
+    'G90 ; absolute positioning',
+    `M140 S${Math.round(c.bedTempC)} ; bed target`,
+    `M104 S${Math.round(c.nozzleTempC)} ; nozzle standby → target`,
+    `M190 S${Math.round(c.bedTempC)} ; wait for bed`,
+    `M109 S${Math.round(c.nozzleTempC + c.firstLayerNozzleBoostC)} ; first layer nozzle (boosted)`
+  ];
+  const adhesion = buildAdhesionLayerPlan(c);
+  for (const layer of adhesion) {
+    lines.push(
+      `; adhesion layer ${layer.layerIndex} @ Z=${layer.zMm.toFixed(3)}mm T=${layer.nozzleTempC}°C`,
+      `G0 Z${layer.zMm.toFixed(3)} F6000`
+    );
+  }
+  if (mesh?.verticesMm?.length) {
+    const bb = bbox2D(mesh.verticesMm);
+    lines.push(
+      `; mesh XY bounds X[${bb.minX.toFixed(2)},${bb.maxX.toFixed(2)}] Y[${bb.minY.toFixed(2)},${bb.maxY.toFixed(2)}]`,
+      `; vertices=${mesh.verticesMm.length}`
+    );
+  }
+  lines.push(`; layerHeight=${c.layerHeightMm} infill=${c.infillPercent}% F=${c.printSpeedMmS}mm/s`);
+  return lines.join('\n');
+}
+
+export function buildTraversalStackFromMesh(c: GCodeSlicerConfig, mesh: MeshSliceInput): TraversalLayerPlan[] {
+  if (!mesh.verticesMm.length) return [];
+  const plans: TraversalLayerPlan[] = [];
+  const adhesion = buildAdhesionLayerPlan(c);
+  for (const layer of adhesion) {
+    plans.push({
+      layerZMm: layer.zMm,
+      pointsMm: buildInsetPerimeterTraversal(mesh.verticesMm, layer.zMm, c.adhesionBrimMm)
+    });
+  }
+  let z = adhesion.length ? adhesion[adhesion.length - 1]!.zMm : 0;
+  const topZ = z + c.layerHeightMm * 4;
+  while (z < topZ - 1e-6) {
+    z += c.layerHeightMm;
+    plans.push({
+      layerZMm: z,
+      pointsMm: buildInsetPerimeterTraversal(mesh.verticesMm, z, c.adhesionBrimMm + c.layerHeightMm * 2)
+    });
+  }
+  return plans;
+}
+
+export function createGCodeSlicerHandler(): TraitHandler<GCodeSlicerConfig> {
+  return {
+    name: 'gcode_slicer',
+    defaultConfig,
+    onAttach(n: HSPlusNode, c: GCodeSlicerConfig, ctx: TraitContext) {
+      const mesh = (n.__gcodeMesh as MeshSliceInput | undefined) ?? { verticesMm: [] };
+      const adhesionPlan = buildAdhesionLayerPlan(c);
+      const traversal = mesh.verticesMm.length ? buildTraversalStackFromMesh(c, mesh) : [];
+      n.__slicerState = {
+        isSlicing: false,
+        progressPercent: 0,
+        estimatedPrintTimeMs: 0,
+        mesh,
+        adhesionPlan,
+        traversal,
+        gcodePreamble: buildSemanticGCodePreamble(c, mesh.verticesMm.length ? mesh : undefined)
+      };
+      ctx.emit?.('gcode_slicer:ready', { semantic: { adhesionPlan, traversalLayers: traversal.length } });
+    },
+    onDetach(n: HSPlusNode, _c: GCodeSlicerConfig, ctx: TraitContext) {
+      delete n.__slicerState;
+      delete n.__gcodeMesh;
+      ctx.emit?.('gcode_slicer:removed');
+    },
+    onUpdate(n: HSPlusNode, c: GCodeSlicerConfig, ctx: TraitContext) {
+      const s = n.__slicerState as GCodeSlicerState | undefined;
+      if (!s) return;
+      const mesh = s.mesh ?? { verticesMm: [] };
+      s.adhesionPlan = buildAdhesionLayerPlan(c);
+      s.traversal = mesh.verticesMm.length ? buildTraversalStackFromMesh(c, mesh) : [];
+      s.gcodePreamble = buildSemanticGCodePreamble(c, mesh.verticesMm.length ? mesh : undefined);
+      ctx.emit?.('gcode_slicer:semantic_updated', {
+        adhesionPlan: s.adhesionPlan,
+        traversalLayers: s.traversal?.length ?? 0
+      });
+    },
+    onEvent(n: HSPlusNode, c: GCodeSlicerConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__slicerState as GCodeSlicerState | undefined;
+      if (!s) return;
+
+      if (e.type === 'gcode_slicer:bind_mesh' && e.payload?.verticesMm) {
+        const verts = e.payload.verticesMm as [number, number, number][];
+        const indices = e.payload.indices as number[] | undefined;
+        const mesh: MeshSliceInput = { verticesMm: verts, indices };
+        n.__gcodeMesh = mesh;
+        s.mesh = mesh;
+        s.adhesionPlan = buildAdhesionLayerPlan(c);
+        s.traversal = buildTraversalStackFromMesh(c, mesh);
+        s.gcodePreamble = buildSemanticGCodePreamble(c, mesh);
+        ctx.emit?.('gcode_slicer:mesh_bound', { vertexCount: verts.length, layers: s.traversal?.length ?? 0 });
+      }
+
+      if (e.type === 'gcode_slicer:slice' && !s.isSlicing) {
+        s.isSlicing = true;
+        s.progressPercent = 0;
+        ctx.emit?.('gcode_slicer:started');
+
+        const meshVol = s.mesh?.verticesMm.length
+          ? bbox2D(s.mesh.verticesMm)
+          : { minX: 0, maxX: 50, minY: 0, maxY: 50 };
+        const xyArea = Math.max(1, meshVol.maxX - meshVol.minX) * Math.max(1, meshVol.maxY - meshVol.minY);
+        const volumeEstimate = xyArea * (c.adhesionLayerCount * c.adhesionLayerHeightMm + c.layerHeightMm * 12);
+        s.estimatedPrintTimeMs = (volumeEstimate / Math.max(0.01, c.printSpeedMmS * c.layerHeightMm)) * 1000;
+
+        setTimeout(() => {
+          s.isSlicing = false;
+          s.progressPercent = 100;
+          s.outputGCodePath = '/tmp/holoscript_output.gcode';
+          const preamble = s.gcodePreamble ?? buildSemanticGCodePreamble(c, s.mesh);
+          ctx.emit?.('gcode_slicer:completed', {
+            path: s.outputGCodePath,
+            estimatedTimeMs: s.estimatedPrintTimeMs,
+            preamble,
+            adhesionPlan: s.adhesionPlan,
+            traversal: s.traversal
+          });
+        }, 1500);
+      }
+    }
+  };
+}

package/src/traits/GaussianSplatTrait.ts

@@ -0,0 +1,22 @@
+/** @gaussian_splat Trait — 3D Gaussian Splatting rendering. @trait gaussian_splat */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface GaussianSplatConfig { splatCount: number; shDegree: number; sortMethod: 'radix' | 'bitonic' | 'cpu'; enableAntialiasing: boolean; opacityThreshold: number; maxSplatSize: number; lodLevels: number; }
+
+const defaultConfig: GaussianSplatConfig = { splatCount: 0, shDegree: 3, sortMethod: 'radix', enableAntialiasing: true, opacityThreshold: 0.005, maxSplatSize: 0.1, lodLevels: 4 };
+
+export function createGaussianSplatHandler(): TraitHandler<GaussianSplatConfig> {
+  return { name: 'gaussian_splat', defaultConfig,
+    onAttach(n: HSPlusNode, c: GaussianSplatConfig, ctx: TraitContext) { n.__gsplatState = { loaded: false, visibleSplats: 0, sortTimeMs: 0, lodLevel: 0 }; ctx.emit?.('gsplat:initialized', { count: c.splatCount, sort: c.sortMethod }); },
+    onDetach(n: HSPlusNode, _c: GaussianSplatConfig, ctx: TraitContext) { delete n.__gsplatState; ctx.emit?.('gsplat:disposed'); },
+    onUpdate(n: HSPlusNode, _c: GaussianSplatConfig, ctx: TraitContext, _d: number) {
+      const s = n.__gsplatState as Record<string, unknown> | undefined;
+      if (s?.loaded) ctx.emit?.('gsplat:frame', { visible: s.visibleSplats, sortMs: s.sortTimeMs });
+    },
+    onEvent(n: HSPlusNode, _c: GaussianSplatConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__gsplatState as Record<string, unknown> | undefined; if (!s) return;
+      if (e.type === 'gsplat:load') { s.loaded = true; ctx.emit?.('gsplat:loaded'); }
+      if (e.type === 'gsplat:set_lod') { s.lodLevel = e.payload?.level; ctx.emit?.('gsplat:lod_changed', { level: s.lodLevel }); }
+    },
+  };
+}

package/src/traits/NeRFTrait.ts

@@ -0,0 +1,20 @@
+/** @nerf Trait — Neural Radiance Field rendering. @trait nerf */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type NeRFMethod = 'instant_ngp' | 'nerfacto' | 'tensorf' | 'mip_nerf' | 'zip_nerf';
+export interface NeRFConfig { method: NeRFMethod; resolution: number; nearPlane: number; farPlane: number; samplesPerRay: number; batchSize: number; enableDeformation: boolean; }
+
+const defaultConfig: NeRFConfig = { method: 'instant_ngp', resolution: 512, nearPlane: 0.01, farPlane: 100, samplesPerRay: 64, batchSize: 4096, enableDeformation: false };
+
+export function createNeRFHandler(): TraitHandler<NeRFConfig> {
+  return { name: 'nerf', defaultConfig,
+    onAttach(n: HSPlusNode, c: NeRFConfig, ctx: TraitContext) { n.__nerfState = { isRendering: false, fps: 0, trainStep: 0, psnr: 0 }; ctx.emit?.('nerf:loaded', { method: c.method }); },
+    onDetach(n: HSPlusNode, _c: NeRFConfig, ctx: TraitContext) { delete n.__nerfState; ctx.emit?.('nerf:unloaded'); },
+    onUpdate(n: HSPlusNode, _c: NeRFConfig, _ctx: TraitContext, _d: number) { const s = n.__nerfState as Record<string, unknown> | undefined; if (s?.isRendering) { (s.trainStep as number)++; } },
+    onEvent(n: HSPlusNode, _c: NeRFConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__nerfState as Record<string, unknown> | undefined; if (!s) return;
+      if (e.type === 'nerf:render') { s.isRendering = true; ctx.emit?.('nerf:rendering'); }
+      if (e.type === 'nerf:stop') { s.isRendering = false; ctx.emit?.('nerf:stopped', { steps: s.trainStep }); }
+    },
+  };
+}

package/src/traits/VolumetricTrait.ts

@@ -0,0 +1,55 @@
+/** @volumetric Trait — Volumetric video capture and playback. @trait volumetric */
+import {
+  registerVolumetricNode,
+  setVolumetricVoxelPayload,
+  unregisterVolumetricNode
+} from '@holoscript/crdt-spatial';
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type VolumetricFormat = 'point_cloud' | 'voxel' | 'mesh_sequence' | 'depth_map' | 'holographic';
+export interface VolumetricConfig { format: VolumetricFormat; resolution: number; frameRate: number; compressionLevel: number; streamingEnabled: boolean; boundingBoxM: [number, number, number]; colorDepth: 8 | 10 | 12; }
+
+const defaultConfig: VolumetricConfig = { format: 'point_cloud', resolution: 1024, frameRate: 30, compressionLevel: 5, streamingEnabled: false, boundingBoxM: [2, 2, 2], colorDepth: 8 };
+
+export function createVolumetricHandler(): TraitHandler<VolumetricConfig> {
+  return { name: 'volumetric', defaultConfig,
+    onAttach(n: HSPlusNode, c: VolumetricConfig, ctx: TraitContext) {
+      if (!n.id) {
+        n.id = `vol_${Math.random().toString(36).slice(2, 11)}`;
+      }
+      n.__volState = { isPlaying: false, currentFrame: 0, totalFrames: 0, loadedPercent: 0 };
+      ctx.emit?.('volumetric:loaded', { format: c.format, resolution: c.resolution });
+      const doc = ctx.spatialSync?.doc;
+      if (doc) {
+        registerVolumetricNode(doc, n.id, { format: c.format });
+      }
+    },
+    onDetach(n: HSPlusNode, _c: VolumetricConfig, ctx: TraitContext) {
+      const doc = ctx.spatialSync?.doc;
+      const id = n.id;
+      if (doc && id) {
+        unregisterVolumetricNode(doc, id);
+      }
+      delete n.__volState;
+      ctx.emit?.('volumetric:unloaded');
+    },
+    onUpdate(n: HSPlusNode, c: VolumetricConfig, ctx: TraitContext, delta: number) {
+      const s = n.__volState as Record<string, unknown> | undefined; if (!s || !s.isPlaying) return;
+      (s.currentFrame as number) += c.frameRate * (delta / 1000);
+      if ((s.currentFrame as number) >= (s.totalFrames as number)) { s.currentFrame = 0; ctx.emit?.('volumetric:loop'); }
+    },
+    onEvent(n: HSPlusNode, _c: VolumetricConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__volState as Record<string, unknown> | undefined; if (!s) return;
+      if (e.type === 'volumetric:play') { s.isPlaying = true; ctx.emit?.('volumetric:playing'); }
+      if (e.type === 'volumetric:pause') { s.isPlaying = false; ctx.emit?.('volumetric:paused'); }
+      const doc = ctx.spatialSync?.doc;
+      const id = n.id;
+      if (e.type === 'volumetric:sync_bytes' && doc && id) {
+        const data = e.payload?.data;
+        if (data instanceof Uint8Array) {
+          setVolumetricVoxelPayload(doc, id, data);
+        }
+      }
+    },
+  };
+}

package/src/traits/types.ts

@@ -0,0 +1,11 @@
+import type { LoroDoc } from 'loro-crdt';
+
+export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitContext {
+  emit?: (event: string, payload?: unknown) => void;
+  /** Injected by HoloLand / spatial host so volumetric payloads sync on the shared Loro + WebRTC doc. */
+  spatialSync?: { doc: LoroDoc };
+  [key: string]: unknown;
+}
+export interface TraitEvent { type: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<T = unknown> { name: string; defaultConfig: T; onAttach(n: HSPlusNode, c: T, ctx: TraitContext): void; onDetach(n: HSPlusNode, c: T, ctx: TraitContext): void; onUpdate(n: HSPlusNode, c: T, ctx: TraitContext, d: number): void; onEvent(n: HSPlusNode, c: T, ctx: TraitContext, e: TraitEvent): void; }

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});