@holoscript/std 2.1.0 → 3.1.1

package/src/collections.ts

@@ -825,10 +825,16 @@ export class PriorityQueue<T> {
       const rightChild = 2 * index + 2;
       let smallest = index;
 
-      if (leftChild < this.heap.length && this.compareFn(this.heap[leftChild].priority, this.heap[smallest].priority) < 0) {
+      if (
+        leftChild < this.heap.length &&
+        this.compareFn(this.heap[leftChild].priority, this.heap[smallest].priority) < 0
+      ) {
         smallest = leftChild;
       }
-      if (rightChild < this.heap.length && this.compareFn(this.heap[rightChild].priority, this.heap[smallest].priority) < 0) {
+      if (
+        rightChild < this.heap.length &&
+        this.compareFn(this.heap[rightChild].priority, this.heap[smallest].priority) < 0
+      ) {
         smallest = rightChild;
       }
 

package/src/events.ts

@@ -0,0 +1,88 @@
+/**
+ * @holoscript/std — Events Module
+ *
+ * Provides a typed event bus for HoloScript compositions.
+ * Supports emit, on, once, off, and wildcard listeners.
+ *
+ * @version 0.2.0
+ * @module @holoscript/std/events
+ */
+
+export type EventHandler<T = any> = (data: T) => void;
+
+interface Listener {
+  handler: EventHandler;
+  once: boolean;
+}
+
+export class EventBus {
+  private listeners: Map<string, Listener[]> = new Map();
+  private wildcardListeners: Listener[] = [];
+
+  /** Register an event listener. */
+  on<T = any>(event: string, handler: EventHandler<T>): () => void {
+    if (!this.listeners.has(event)) this.listeners.set(event, []);
+    const listener: Listener = { handler, once: false };
+    this.listeners.get(event)!.push(listener);
+    return () => this.off(event, handler);
+  }
+
+  /** Register a one-time event listener. */
+  once<T = any>(event: string, handler: EventHandler<T>): () => void {
+    if (!this.listeners.has(event)) this.listeners.set(event, []);
+    const listener: Listener = { handler, once: true };
+    this.listeners.get(event)!.push(listener);
+    return () => this.off(event, handler);
+  }
+
+  /** Remove an event listener. */
+  off(event: string, handler: EventHandler): void {
+    const list = this.listeners.get(event);
+    if (!list) return;
+    this.listeners.set(
+      event,
+      list.filter((l) => l.handler !== handler)
+    );
+  }
+
+  /** Emit an event to all registered listeners. */
+  emit<T = any>(event: string, data?: T): void {
+    // Fire specific listeners
+    const list = this.listeners.get(event);
+    if (list) {
+      const remaining: Listener[] = [];
+      for (const l of list) {
+        l.handler(data);
+        if (!l.once) remaining.push(l);
+      }
+      this.listeners.set(event, remaining);
+    }
+    // Fire wildcard listeners
+    for (const l of this.wildcardListeners) {
+      l.handler({ event, data });
+    }
+  }
+
+  /** Listen to all events. */
+  onAny(handler: EventHandler<{ event: string; data: any }>): () => void {
+    const listener: Listener = { handler, once: false };
+    this.wildcardListeners.push(listener);
+    return () => {
+      this.wildcardListeners = this.wildcardListeners.filter((l) => l !== listener);
+    };
+  }
+
+  /** Remove all listeners. */
+  clear(): void {
+    this.listeners.clear();
+    this.wildcardListeners = [];
+  }
+
+  /** Get count of listeners for an event (or all events). */
+  listenerCount(event?: string): number {
+    if (event) return (this.listeners.get(event) || []).length;
+    let total = this.wildcardListeners.length;
+    for (const [, list] of this.listeners) total += list.length;
+    return total;
+  }
+}

package/src/index.ts

@@ -2,25 +2,62 @@
  * @holoscript/std - Standard Library for HoloScript Plus
  *
  * Provides core types, math utilities, collections, string operations,
- * and time management for HoloScript Plus programs.
+ * time management, spatial math, physics primitives, materials, and events
+ * for HoloScript Plus programs.
  *
  * @example
  * ```hsplus
- * import { Vec3, List, sleep } from "@holoscript/std";
+ * import { Vec3, createPBRMaterial, EventBus } from "@holoscript/std";
  *
  * let position = Vec3(0, 1, 0);
- * let items = List.of(1, 2, 3).map(n => n * 2);
- *
- * async fn main() {
- *   await sleep(1000);
- *   print("Done!");
- * }
+ * let steel = createPBRMaterial("Steel", "metal");
+ * let bus = new EventBus();
  * ```
  */
 
 // Re-export everything from types.js
 export * from './types.js';
 
+// Spatial math (v4.2)
+export {
+  Vec3,
+  Quaternion,
+  Transform,
+  Ray,
+  AABB,
+  distance,
+  lerp as spatialLerp,
+  clamp as spatialClamp,
+  degToRad as spatialDegToRad,
+  radToDeg as spatialRadToDeg,
+} from './spatial.js';
+
+// Physics primitives (v4.2)
+export {
+  createBoxCollider,
+  createSphereCollider,
+  createCapsuleCollider,
+  createRigidbody,
+} from './physics.js';
+export type {
+  ColliderConfig,
+  ColliderShapeType,
+  RigidbodyConfig,
+  ForceFieldConfig,
+  ForceFieldType,
+  JointConfig,
+  JointType,
+  RaycastHit,
+} from './physics.js';
+
+// Materials (v4.2)
+export { MATERIAL_PRESETS, createPBRMaterial } from './materials.js';
+export type { PBRMaterial, UnlitMaterial, TextureMapType, TextureConfig } from './materials.js';
+
+// Events (v4.2)
+export { EventBus } from './events.js';
+export type { EventHandler } from './events.js';
+
 // Math utilities - export objects from math.ts
 export {
   // Constants
@@ -120,8 +157,114 @@ export {
   wordWrap,
   levenshtein,
   similarity,
+  extractTraits,
 } from './string.js';
 
+// Economic primitives (v4.3)
+export {
+  // Tradeable
+  generateTxHash,
+  executeTrade,
+  // Depreciation
+  calculateDepreciation,
+  depreciatedValue,
+  isDestroyed,
+  calculateRepairCost,
+  DEFAULT_DEPRECIATION,
+  // Bonding curves
+  bondingCurvePrice,
+  bondingCurveBuyCost,
+  bondingCurveSellRefund,
+  spatialPrice,
+  DEFAULT_BONDING_CURVE,
+  // Wealth taxation
+  calculateTaxRate,
+  calculateTaxAmount,
+  calculateRedistribution,
+  DEFAULT_WEALTH_TAX,
+  // PID control
+  createPIDState,
+  updatePID,
+  createDualLoopPIDState,
+  updateDualLoopPID,
+  DEFAULT_PID,
+  // Faucet-sink tracking
+  createFaucetSinkMetrics,
+  recordFaucet,
+  recordSink,
+  resetMetricsPeriod,
+} from './traits/EconomicPrimitives.js';
+export type {
+  Currency,
+  AgentID,
+  EconomicResult,
+  EconomicError,
+  EconomicPermission,
+  OwnershipRecord,
+  TransferRecord,
+  DepreciationConfig,
+  BondingCurveType,
+  BondingCurveConfig,
+  WealthTaxConfig,
+  PIDConfig,
+  PIDState,
+  DualLoopPIDConfig,
+  DualLoopPIDState,
+  FaucetSinkMetrics,
+} from './traits/EconomicPrimitives.js';
+
+// Economic traits (v4.3)
+export {
+  EconomicTraits,
+  getEconomicTraitNames,
+  getEconomicTrait,
+  validateTraitComposition,
+  getRequiredPermissions,
+} from './traits/EconomicTraits.js';
+export type { EconomicTraitDefinition } from './traits/EconomicTraits.js';
+
+// SimulationLab primitives (v4.3)
+export {
+  // Statistics
+  mean,
+  variance,
+  standardDeviation,
+  standardError,
+  cohensD,
+  // Statistical tests
+  tTest,
+  oneSampleTTest,
+  mannWhitneyU,
+  chiSquaredTest,
+  // Parameter sweeps
+  expandSweep,
+  generateSweepCombinations,
+  isParameterRange,
+  // Metric aggregation
+  extractMetric,
+  groupByParameter,
+  summarizeMetrics,
+} from './traits/SimulationLabPrimitives.js';
+export type {
+  Hypothesis,
+  HypothesisDirection,
+  SimulationStatus,
+  ParameterRange,
+  ParameterSet,
+  ParameterSweep,
+  SimulationMetrics,
+  StatisticalResult,
+  ExperimentResult,
+} from './traits/SimulationLabPrimitives.js';
+
+// SimulationLab traits (v4.3)
+export {
+  SimulationLabTraits,
+  getSimulationTraitNames,
+  getSimulationTrait,
+} from './traits/SimulationLabTraits.js';
+export type { SimulationTraitDefinition } from './traits/SimulationLabTraits.js';
+
 // Time utilities
 export {
   now,
@@ -178,7 +321,10 @@ export function assert(condition: boolean, message?: string): asserts condition
 /**
  * Assert a value is not null or undefined
  */
-export function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T {
+export function assertDefined<T>(
+  value: T | null | undefined,
+  message?: string
+): asserts value is T {
   if (value === null || value === undefined) {
     throw new Error(message ?? 'Value is null or undefined');
   }
@@ -266,7 +412,7 @@ export function equals(a: unknown, b: unknown): boolean {
     return true;
   }
 
-  const keysA = Object.keys(a as object);
+  const keysA = Object.keys(a);
   const keysB = Object.keys(b as object);
   if (keysA.length !== keysB.length) return false;
 
@@ -299,7 +445,11 @@ export function pipe(value: unknown, ...fns: ((x: unknown) => unknown)[]): unkno
 export function compose<A>(): (a: A) => A;
 export function compose<A, B>(fn1: (a: A) => B): (a: A) => B;
 export function compose<A, B, C>(fn2: (b: B) => C, fn1: (a: A) => B): (a: A) => C;
-export function compose<A, B, C, D>(fn3: (c: C) => D, fn2: (b: B) => C, fn1: (a: A) => B): (a: A) => D;
+export function compose<A, B, C, D>(
+  fn3: (c: C) => D,
+  fn2: (b: B) => C,
+  fn1: (a: A) => B
+): (a: A) => D;
 export function compose(...fns: ((x: unknown) => unknown)[]): (x: unknown) => unknown {
   return (value: unknown) => fns.reduceRight((acc, fn) => fn(acc), value);
 }

package/src/materials.ts

@@ -0,0 +1,109 @@
+/**
+ * @holoscript/std — Materials Module
+ *
+ * Provides PBR material types, texture map definitions, and material presets.
+ * Maps directly to HoloScript material_block grammar constructs.
+ *
+ * @version 0.2.0
+ * @module @holoscript/std/materials
+ */
+
+// =============================================================================
+// PBR Material
+// =============================================================================
+
+export interface PBRMaterial {
+  name: string;
+  baseColor: string; // hex color
+  roughness: number; // 0.0 - 1.0
+  metallic: number; // 0.0 - 1.0
+  emissiveColor?: string;
+  emissiveIntensity?: number;
+  opacity?: number; // 0.0 - 1.0
+  ior?: number; // Index of refraction (glass ~1.5, water ~1.33)
+  subsurface?: number;
+  clearcoat?: number;
+  clearcoatRoughness?: number;
+  // Texture maps
+  albedoMap?: string;
+  normalMap?: string;
+  roughnessMap?: string;
+  metallicMap?: string;
+  emissionMap?: string;
+  aoMap?: string;
+  heightMap?: string;
+  opacityMap?: string;
+  displacementMap?: string;
+}
+
+export interface UnlitMaterial {
+  name: string;
+  color: string;
+  emissiveColor?: string;
+  emissiveIntensity?: number;
+  opacity?: number;
+  texture?: string;
+}
+
+// =============================================================================
+// Material Presets
+// =============================================================================
+
+export const MATERIAL_PRESETS: Record<string, Partial<PBRMaterial>> = {
+  metal: { roughness: 0.2, metallic: 1.0 },
+  wood: { roughness: 0.85, metallic: 0.0, baseColor: '#8B6914' },
+  glass: { roughness: 0.05, metallic: 0.0, opacity: 0.3, ior: 1.5 },
+  plastic: { roughness: 0.4, metallic: 0.0 },
+  concrete: { roughness: 0.95, metallic: 0.0, baseColor: '#808080' },
+  fabric: { roughness: 0.9, metallic: 0.0, subsurface: 0.2 },
+  water: { roughness: 0.05, metallic: 0.0, opacity: 0.7, ior: 1.33 },
+  rubber: { roughness: 0.95, metallic: 0.0, baseColor: '#222222' },
+  marble: { roughness: 0.3, metallic: 0.0, baseColor: '#f0f0f0' },
+  skin: { roughness: 0.6, metallic: 0.0, subsurface: 0.5 },
+  foliage: { roughness: 0.8, metallic: 0.0, baseColor: '#2d5a27', subsurface: 0.3 },
+  chrome: { roughness: 0.05, metallic: 1.0, baseColor: '#cccccc' },
+  gold: { roughness: 0.2, metallic: 1.0, baseColor: '#ffd700' },
+  copper: { roughness: 0.3, metallic: 1.0, baseColor: '#b87333' },
+  ice: { roughness: 0.1, metallic: 0.0, opacity: 0.8, ior: 1.31 },
+};
+
+export function createPBRMaterial(
+  name: string,
+  preset?: keyof typeof MATERIAL_PRESETS,
+  overrides?: Partial<PBRMaterial>
+): PBRMaterial {
+  const base = preset ? MATERIAL_PRESETS[preset] : {};
+  return {
+    name,
+    baseColor: '#ffffff',
+    roughness: 0.5,
+    metallic: 0.0,
+    ...base,
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Texture Map Types
+// =============================================================================
+
+export type TextureMapType =
+  | 'albedo_map'
+  | 'normal_map'
+  | 'roughness_map'
+  | 'metallic_map'
+  | 'emission_map'
+  | 'ao_map'
+  | 'height_map'
+  | 'opacity_map'
+  | 'displacement_map'
+  | 'specular_map'
+  | 'clearcoat_map';
+
+export interface TextureConfig {
+  source: string;
+  tiling?: [number, number];
+  offset?: [number, number];
+  filter?: 'linear' | 'nearest';
+  wrap?: 'repeat' | 'clamp' | 'mirror';
+}

package/src/math.ts

@@ -4,7 +4,7 @@
  * Vector math, quaternion operations, interpolation, and noise functions.
  */
 
-import type { Vec2, Vec3, Vec4, Quat, EulerAngles, AABB, Ray, RaycastHit } from './types.js';
+import type { Vec2, Vec3, Quat, EulerAngles, AABB } from './types.js';
 import { vec3, quat } from './types.js';
 
 // =============================================================================
@@ -34,7 +34,13 @@ export function inverseLerp(a: number, b: number, value: number): number {
   return (value - a) / (b - a);
 }
 
-export function remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number {
+export function remap(
+  value: number,
+  inMin: number,
+  inMax: number,
+  outMin: number,
+  outMax: number
+): number {
   return lerp(outMin, outMax, inverseLerp(inMin, inMax, value));
 }
 
@@ -153,10 +159,7 @@ export const vec3Math = {
     const dot = clamp(vec3Math.dot(a, b), -1, 1);
     const theta = Math.acos(dot) * t;
     const relative = vec3Math.normalize(vec3Math.sub(b, vec3Math.mul(a, dot)));
-    return vec3Math.add(
-      vec3Math.mul(a, Math.cos(theta)),
-      vec3Math.mul(relative, Math.sin(theta))
-    );
+    return vec3Math.add(vec3Math.mul(a, Math.cos(theta)), vec3Math.mul(relative, Math.sin(theta)));
   },
 
   negate: (v: Vec3): Vec3 => ({ x: -v.x, y: -v.y, z: -v.z }),
@@ -406,17 +409,23 @@ export const quatMath = {
 export const aabbMath = {
   contains: (aabb: AABB, point: Vec3): boolean => {
     return (
-      point.x >= aabb.min.x && point.x <= aabb.max.x &&
-      point.y >= aabb.min.y && point.y <= aabb.max.y &&
-      point.z >= aabb.min.z && point.z <= aabb.max.z
+      point.x >= aabb.min.x &&
+      point.x <= aabb.max.x &&
+      point.y >= aabb.min.y &&
+      point.y <= aabb.max.y &&
+      point.z >= aabb.min.z &&
+      point.z <= aabb.max.z
     );
   },
 
   intersects: (a: AABB, b: AABB): boolean => {
     return (
-      a.min.x <= b.max.x && a.max.x >= b.min.x &&
-      a.min.y <= b.max.y && a.max.y >= b.min.y &&
-      a.min.z <= b.max.z && a.max.z >= b.min.z
+      a.min.x <= b.max.x &&
+      a.max.x >= b.min.x &&
+      a.min.y <= b.max.y &&
+      a.max.y >= b.min.y &&
+      a.min.z <= b.max.z &&
+      a.max.z >= b.min.z
     );
   },
 
@@ -508,7 +517,14 @@ export const noise = {
   /**
    * Fractal Brownian Motion (fBm)
    */
-  fbm: (x: number, y: number, z: number, octaves: number = 6, lacunarity: number = 2, gain: number = 0.5): number => {
+  fbm: (
+    x: number,
+    y: number,
+    z: number,
+    octaves: number = 6,
+    lacunarity: number = 2,
+    gain: number = 0.5
+  ): number => {
     let value = 0;
     let amplitude = 1;
     let frequency = 1;
@@ -550,7 +566,7 @@ export const noise = {
 
           // Pseudo-random point in cell
           const hash = perm[(perm[(perm[cellX & 255] + cellY) & 255] + cellZ) & 255];
-          const px = cellX + (hash / 255);
+          const px = cellX + hash / 255;
           const py = cellY + ((hash * 7) % 255) / 255;
           const pz = cellZ + ((hash * 13) % 255) / 255;
 

package/src/physics.ts

@@ -0,0 +1,141 @@
+/**
+ * @holoscript/std — Physics Module
+ *
+ * Provides physics primitives: ColliderShape, RigidbodyConfig, ForceField, Joint.
+ * Runtime representations for HoloScript physics blocks.
+ *
+ * @version 0.2.0
+ * @module @holoscript/std/physics
+ */
+
+import type { Vec3 } from './spatial.js';
+
+// =============================================================================
+// Collider Shapes
+// =============================================================================
+
+export type ColliderShapeType =
+  | 'box'
+  | 'sphere'
+  | 'capsule'
+  | 'mesh'
+  | 'convex'
+  | 'cylinder'
+  | 'heightfield';
+
+export interface ColliderConfig {
+  shape: ColliderShapeType;
+  isTrigger: boolean;
+  friction: number;
+  restitution: number;
+  // Shape-specific
+  radius?: number;
+  halfExtents?: Vec3;
+  height?: number;
+  meshAsset?: string;
+}
+
+export function createBoxCollider(
+  halfExtents: Vec3,
+  options?: Partial<ColliderConfig>
+): ColliderConfig {
+  return {
+    shape: 'box',
+    isTrigger: false,
+    friction: 0.5,
+    restitution: 0.0,
+    halfExtents,
+    ...options,
+  };
+}
+
+export function createSphereCollider(
+  radius: number,
+  options?: Partial<ColliderConfig>
+): ColliderConfig {
+  return { shape: 'sphere', isTrigger: false, friction: 0.5, restitution: 0.0, radius, ...options };
+}
+
+export function createCapsuleCollider(
+  radius: number,
+  height: number,
+  options?: Partial<ColliderConfig>
+): ColliderConfig {
+  return {
+    shape: 'capsule',
+    isTrigger: false,
+    friction: 0.5,
+    restitution: 0.0,
+    radius,
+    height,
+    ...options,
+  };
+}
+
+// =============================================================================
+// Rigidbody
+// =============================================================================
+
+export interface RigidbodyConfig {
+  mass: number;
+  useGravity: boolean;
+  linearDamping: number;
+  angularDamping: number;
+  freezePosition: [boolean, boolean, boolean];
+  freezeRotation: [boolean, boolean, boolean];
+  isKinematic: boolean;
+}
+
+export function createRigidbody(mass: number, options?: Partial<RigidbodyConfig>): RigidbodyConfig {
+  return {
+    mass,
+    useGravity: true,
+    linearDamping: 0.0,
+    angularDamping: 0.05,
+    freezePosition: [false, false, false],
+    freezeRotation: [false, false, false],
+    isKinematic: false,
+    ...options,
+  };
+}
+
+// =============================================================================
+// Force Fields
+// =============================================================================
+
+export type ForceFieldType = 'directional' | 'radial' | 'vortex' | 'buoyancy';
+
+export interface ForceFieldConfig {
+  type: ForceFieldType;
+  strength: number;
+  direction?: Vec3;
+  falloff: 'none' | 'linear' | 'quadratic';
+  turbulence: number;
+}
+
+// =============================================================================
+// Joints
+// =============================================================================
+
+export type JointType = 'hinge' | 'slider' | 'ball_socket' | 'fixed' | 'd6' | 'spring';
+
+export interface JointConfig {
+  type: JointType;
+  connectedBody?: string;
+  axis?: Vec3;
+  limits?: [number, number];
+  damping: number;
+  springForce?: number;
+  breakForce?: number;
+}
+
+// =============================================================================
+// Raycast Utility
+// =============================================================================
+
+export interface RaycastHit {
+  point: Vec3;
+  normal: Vec3;
+  distance: number;
+  objectName: string;
+}