@holoscript/std 2.1.0 → 3.1.1

package/src/spatial.ts

@@ -0,0 +1,320 @@
+/**
+ * @holoscript/std — Spatial Module
+ *
+ * Provides spatial math utilities: Vec3, Quaternion, Transform, Ray, AABB, distance.
+ * Used by the HoloScript runtime for spatial computing operations.
+ *
+ * @version 0.2.0
+ * @module @holoscript/std/spatial
+ */
+
+// =============================================================================
+// Vec3
+// =============================================================================
+
+export class Vec3 {
+  constructor(
+    public x: number = 0,
+    public y: number = 0,
+    public z: number = 0
+  ) {}
+
+  static zero(): Vec3 {
+    return new Vec3(0, 0, 0);
+  }
+  static one(): Vec3 {
+    return new Vec3(1, 1, 1);
+  }
+  static up(): Vec3 {
+    return new Vec3(0, 1, 0);
+  }
+  static down(): Vec3 {
+    return new Vec3(0, -1, 0);
+  }
+  static forward(): Vec3 {
+    return new Vec3(0, 0, -1);
+  }
+  static right(): Vec3 {
+    return new Vec3(1, 0, 0);
+  }
+
+  add(other: Vec3): Vec3 {
+    return new Vec3(this.x + other.x, this.y + other.y, this.z + other.z);
+  }
+  sub(other: Vec3): Vec3 {
+    return new Vec3(this.x - other.x, this.y - other.y, this.z - other.z);
+  }
+  mul(s: number): Vec3 {
+    return new Vec3(this.x * s, this.y * s, this.z * s);
+  }
+  div(s: number): Vec3 {
+    return new Vec3(this.x / s, this.y / s, this.z / s);
+  }
+
+  dot(other: Vec3): number {
+    return this.x * other.x + this.y * other.y + this.z * other.z;
+  }
+  cross(other: Vec3): Vec3 {
+    return new Vec3(
+      this.y * other.z - this.z * other.y,
+      this.z * other.x - this.x * other.z,
+      this.x * other.y - this.y * other.x
+    );
+  }
+
+  length(): number {
+    return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
+  }
+  lengthSquared(): number {
+    return this.x * this.x + this.y * this.y + this.z * this.z;
+  }
+  normalize(): Vec3 {
+    const l = this.length();
+    return l > 0 ? this.div(l) : Vec3.zero();
+  }
+
+  distanceTo(other: Vec3): number {
+    return this.sub(other).length();
+  }
+  lerp(other: Vec3, t: number): Vec3 {
+    return this.add(other.sub(this).mul(t));
+  }
+
+  toArray(): [number, number, number] {
+    return [this.x, this.y, this.z];
+  }
+  static fromArray(arr: number[]): Vec3 {
+    return new Vec3(arr[0] || 0, arr[1] || 0, arr[2] || 0);
+  }
+
+  equals(other: Vec3, epsilon = 1e-6): boolean {
+    return (
+      Math.abs(this.x - other.x) < epsilon &&
+      Math.abs(this.y - other.y) < epsilon &&
+      Math.abs(this.z - other.z) < epsilon
+    );
+  }
+
+  toString(): string {
+    return `Vec3(${this.x}, ${this.y}, ${this.z})`;
+  }
+}
+
+// =============================================================================
+// Quaternion
+// =============================================================================
+
+export class Quaternion {
+  constructor(
+    public x = 0,
+    public y = 0,
+    public z = 0,
+    public w = 1
+  ) {}
+
+  static identity(): Quaternion {
+    return new Quaternion(0, 0, 0, 1);
+  }
+
+  static fromEuler(x: number, y: number, z: number): Quaternion {
+    const cx = Math.cos(x * 0.5),
+      sx = Math.sin(x * 0.5);
+    const cy = Math.cos(y * 0.5),
+      sy = Math.sin(y * 0.5);
+    const cz = Math.cos(z * 0.5),
+      sz = Math.sin(z * 0.5);
+    return new Quaternion(
+      sx * cy * cz - cx * sy * sz,
+      cx * sy * cz + sx * cy * sz,
+      cx * cy * sz - sx * sy * cz,
+      cx * cy * cz + sx * sy * sz
+    );
+  }
+
+  static fromAxisAngle(axis: Vec3, angle: number): Quaternion {
+    const half = angle * 0.5;
+    const s = Math.sin(half);
+    const n = axis.normalize();
+    return new Quaternion(n.x * s, n.y * s, n.z * s, Math.cos(half));
+  }
+
+  multiply(other: Quaternion): Quaternion {
+    return new Quaternion(
+      this.w * other.x + this.x * other.w + this.y * other.z - this.z * other.y,
+      this.w * other.y - this.x * other.z + this.y * other.w + this.z * other.x,
+      this.w * other.z + this.x * other.y - this.y * other.x + this.z * other.w,
+      this.w * other.w - this.x * other.x - this.y * other.y - this.z * other.z
+    );
+  }
+
+  rotateVec3(v: Vec3): Vec3 {
+    const u = new Vec3(this.x, this.y, this.z);
+    const s = this.w;
+    return u
+      .mul(2 * u.dot(v))
+      .add(v.mul(s * s - u.dot(u)))
+      .add(u.cross(v).mul(2 * s));
+  }
+
+  slerp(other: Quaternion, t: number): Quaternion {
+    let dot = this.x * other.x + this.y * other.y + this.z * other.z + this.w * other.w;
+    const neg = dot < 0;
+    if (neg) dot = -dot;
+    if (dot > 0.9995) {
+      // Linear interpolation for very close quaternions
+      const r = new Quaternion(
+        this.x + t * ((neg ? -other.x : other.x) - this.x),
+        this.y + t * ((neg ? -other.y : other.y) - this.y),
+        this.z + t * ((neg ? -other.z : other.z) - this.z),
+        this.w + t * ((neg ? -other.w : other.w) - this.w)
+      );
+      const len = Math.sqrt(r.x * r.x + r.y * r.y + r.z * r.z + r.w * r.w);
+      return new Quaternion(r.x / len, r.y / len, r.z / len, r.w / len);
+    }
+    const theta = Math.acos(dot);
+    const sinTheta = Math.sin(theta);
+    const a = Math.sin((1 - t) * theta) / sinTheta;
+    const b = (Math.sin(t * theta) / sinTheta) * (neg ? -1 : 1);
+    return new Quaternion(
+      a * this.x + b * other.x,
+      a * this.y + b * other.y,
+      a * this.z + b * other.z,
+      a * this.w + b * other.w
+    );
+  }
+
+  normalize(): Quaternion {
+    const len = Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z + this.w * this.w);
+    return new Quaternion(this.x / len, this.y / len, this.z / len, this.w / len);
+  }
+
+  toEuler(): Vec3 {
+    const sinr = 2 * (this.w * this.x + this.y * this.z);
+    const cosr = 1 - 2 * (this.x * this.x + this.y * this.y);
+    const sinp = 2 * (this.w * this.y - this.z * this.x);
+    const siny = 2 * (this.w * this.z + this.x * this.y);
+    const cosy = 1 - 2 * (this.y * this.y + this.z * this.z);
+    return new Vec3(
+      Math.atan2(sinr, cosr),
+      Math.abs(sinp) >= 1 ? (Math.sign(sinp) * Math.PI) / 2 : Math.asin(sinp),
+      Math.atan2(siny, cosy)
+    );
+  }
+}
+
+// =============================================================================
+// Transform
+// =============================================================================
+
+export class Transform {
+  constructor(
+    public position: Vec3 = Vec3.zero(),
+    public rotation: Quaternion = Quaternion.identity(),
+    public scale: Vec3 = Vec3.one()
+  ) {}
+
+  static identity(): Transform {
+    return new Transform();
+  }
+
+  transformPoint(point: Vec3): Vec3 {
+    const scaled = new Vec3(point.x * this.scale.x, point.y * this.scale.y, point.z * this.scale.z);
+    return this.rotation.rotateVec3(scaled).add(this.position);
+  }
+
+  transformDirection(dir: Vec3): Vec3 {
+    return this.rotation.rotateVec3(dir);
+  }
+}
+
+// =============================================================================
+// Ray & AABB
+// =============================================================================
+
+export class Ray {
+  constructor(
+    public origin: Vec3,
+    public direction: Vec3
+  ) {}
+
+  pointAt(t: number): Vec3 {
+    return this.origin.add(this.direction.mul(t));
+  }
+}
+
+export class AABB {
+  constructor(
+    public min: Vec3,
+    public max: Vec3
+  ) {}
+
+  contains(point: Vec3): boolean {
+    return (
+      point.x >= this.min.x &&
+      point.x <= this.max.x &&
+      point.y >= this.min.y &&
+      point.y <= this.max.y &&
+      point.z >= this.min.z &&
+      point.z <= this.max.z
+    );
+  }
+
+  intersects(other: AABB): boolean {
+    return (
+      this.min.x <= other.max.x &&
+      this.max.x >= other.min.x &&
+      this.min.y <= other.max.y &&
+      this.max.y >= other.min.y &&
+      this.min.z <= other.max.z &&
+      this.max.z >= other.min.z
+    );
+  }
+
+  center(): Vec3 {
+    return this.min.add(this.max).div(2);
+  }
+  size(): Vec3 {
+    return this.max.sub(this.min);
+  }
+
+  intersectsRay(ray: Ray): number | null {
+    let tmin = (this.min.x - ray.origin.x) / ray.direction.x;
+    let tmax = (this.max.x - ray.origin.x) / ray.direction.x;
+    if (tmin > tmax) [tmin, tmax] = [tmax, tmin];
+
+    let tymin = (this.min.y - ray.origin.y) / ray.direction.y;
+    let tymax = (this.max.y - ray.origin.y) / ray.direction.y;
+    if (tymin > tymax) [tymin, tymax] = [tymax, tymin];
+
+    if (tmin > tymax || tymin > tmax) return null;
+    tmin = Math.max(tmin, tymin);
+    tmax = Math.min(tmax, tymax);
+
+    let tzmin = (this.min.z - ray.origin.z) / ray.direction.z;
+    let tzmax = (this.max.z - ray.origin.z) / ray.direction.z;
+    if (tzmin > tzmax) [tzmin, tzmax] = [tzmax, tzmin];
+
+    if (tmin > tzmax || tzmin > tmax) return null;
+    return Math.max(tmin, tzmin);
+  }
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+export function distance(a: Vec3, b: Vec3): number {
+  return a.distanceTo(b);
+}
+export function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+export function clamp(v: number, min: number, max: number): number {
+  return Math.min(Math.max(v, min), max);
+}
+export function degToRad(deg: number): number {
+  return deg * (Math.PI / 180);
+}
+export function radToDeg(rad: number): number {
+  return rad * (180 / Math.PI);
+}

package/src/string.basic.test.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Basic test to verify formatBytes function
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatBytes } from './string.js';
+
+describe('formatBytes basic test', () => {
+  it('should format bytes correctly', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(1024)).toBe('1 KB');
+    expect(formatBytes(1048576)).toBe('1 MB');
+  });
+});

package/src/string.test.ts

@@ -0,0 +1,335 @@
+/**
+ * @fileoverview Comprehensive tests for @holoscript/std string utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  isBlank,
+  isNotBlank,
+  capitalize,
+  titleCase,
+  camelCase,
+  pascalCase,
+  snakeCase,
+  kebabCase,
+  constantCase,
+  padLeft,
+  padRight,
+  center,
+  truncate,
+  truncateMiddle,
+  repeat,
+  reverse,
+  count,
+  containsIgnoreCase,
+  startsWithIgnoreCase,
+  endsWithIgnoreCase,
+  removeWhitespace,
+  collapseWhitespace,
+  removePrefix,
+  removeSuffix,
+  wrap,
+  unwrap,
+  lines,
+  words,
+  chars,
+  join,
+  format,
+  formatNumber,
+  numberWithCommas,
+  formatBytes,
+  formatDuration,
+  escapeHtml,
+  unescapeHtml,
+  escapeRegex,
+  slugify,
+  isValidIdentifier,
+  isNumeric,
+  isAlphanumeric,
+  isAlpha,
+  randomString,
+  uuid,
+  indent,
+  dedent,
+  wordWrap,
+  levenshtein,
+  similarity,
+  extractTraits
+} from './string.js';
+
+describe('@holoscript/std string utilities', () => {
+  describe('formatBytes', () => {
+    it('should format bytes correctly with default 2 decimals', () => {
+      expect(formatBytes(0)).toBe('0 B');
+      expect(formatBytes(100)).toBe('100 B');
+      expect(formatBytes(1023)).toBe('1023 B');
+      expect(formatBytes(1024)).toBe('1 KB');
+      expect(formatBytes(1536)).toBe('1.5 KB');
+      expect(formatBytes(1048576)).toBe('1 MB');
+      expect(formatBytes(1073741824)).toBe('1 GB');
+      expect(formatBytes(1099511627776)).toBe('1 TB');
+    });
+
+    it('should respect custom decimal precision', () => {
+      expect(formatBytes(1536, 0)).toBe('2 KB');
+      expect(formatBytes(1536, 1)).toBe('1.5 KB');
+      expect(formatBytes(1536, 3)).toBe('1.5 KB');
+      expect(formatBytes(1677721, 3)).toBe('1.6 MB');
+    });
+
+    it('should handle edge cases', () => {
+      expect(formatBytes(1)).toBe('1 B');
+      expect(formatBytes(1025)).toBe('1 KB');
+      expect(formatBytes(-100)).toBe('-100 B');
+    });
+
+    it('should handle very large numbers', () => {
+      expect(formatBytes(1125899906842624)).toBe('1 PB'); // 1 petabyte
+      expect(formatBytes(2251799813685248)).toBe('2 PB');
+    });
+  });
+
+  describe('formatDuration', () => {
+    it('should format milliseconds correctly', () => {
+      expect(formatDuration(0)).toBe('0ms');
+      expect(formatDuration(100)).toBe('100ms');
+      expect(formatDuration(999)).toBe('999ms');
+    });
+
+    it('should format seconds correctly', () => {
+      expect(formatDuration(1000)).toBe('1.0s');
+      expect(formatDuration(1500)).toBe('1.5s');
+      expect(formatDuration(59999)).toBe('60.0s');
+    });
+
+    it('should format minutes correctly', () => {
+      expect(formatDuration(60000)).toBe('1.0m');
+      expect(formatDuration(90000)).toBe('1.5m');
+      expect(formatDuration(3599999)).toBe('60.0m');
+    });
+
+    it('should format hours correctly', () => {
+      expect(formatDuration(3600000)).toBe('1.0h');
+      expect(formatDuration(5400000)).toBe('1.5h');
+    });
+  });
+
+  describe('case conversion', () => {
+    const testString = 'hello world test';
+
+    it('capitalize should capitalize first letter', () => {
+      expect(capitalize('')).toBe('');
+      expect(capitalize('hello')).toBe('Hello');
+      expect(capitalize(testString)).toBe('Hello world test');
+    });
+
+    it('titleCase should capitalize each word', () => {
+      expect(titleCase(testString)).toBe('Hello World Test');
+      expect(titleCase('')).toBe('');
+      expect(titleCase('a')).toBe('A');
+    });
+
+    it('camelCase should convert to camelCase', () => {
+      expect(camelCase(testString)).toBe('helloWorldTest');
+      expect(camelCase('Hello World')).toBe('helloWorld');
+      expect(camelCase('')).toBe('');
+    });
+
+    it('pascalCase should convert to PascalCase', () => {
+      expect(pascalCase(testString)).toBe('HelloWorldTest');
+      expect(pascalCase('hello world')).toBe('HelloWorld');
+      expect(pascalCase('')).toBe('');
+    });
+
+    it('snakeCase should convert to snake_case', () => {
+      expect(snakeCase(testString)).toBe('hello_world_test');
+      expect(snakeCase('HelloWorld')).toBe('hello_world');
+      expect(snakeCase('')).toBe('');
+    });
+
+    it('kebabCase should convert to kebab-case', () => {
+      expect(kebabCase(testString)).toBe('hello-world-test');
+      expect(kebabCase('HelloWorld')).toBe('hello-world');
+      expect(kebabCase('')).toBe('');
+    });
+
+    it('constantCase should convert to CONSTANT_CASE', () => {
+      expect(constantCase(testString)).toBe('HELLO_WORLD_TEST');
+      expect(constantCase('HelloWorld')).toBe('HELLO_WORLD');
+      expect(constantCase('')).toBe('');
+    });
+  });
+
+  describe('padding and alignment', () => {
+    it('padLeft should pad on the left', () => {
+      expect(padLeft('test', 8)).toBe('    test');
+      expect(padLeft('test', 8, '*')).toBe('****test');
+      expect(padLeft('test', 2)).toBe('test'); // No padding if already long enough
+    });
+
+    it('padRight should pad on the right', () => {
+      expect(padRight('test', 8)).toBe('test    ');
+      expect(padRight('test', 8, '*')).toBe('test****');
+      expect(padRight('test', 2)).toBe('test');
+    });
+
+    it('center should center text', () => {
+      expect(center('test', 8)).toBe('  test  ');
+      expect(center('test', 9)).toBe('  test   ');
+      expect(center('test', 8, '*')).toBe('**test**');
+    });
+  });
+
+  describe('validation functions', () => {
+    describe('isBlank/isNotBlank', () => {
+      it('should detect blank strings', () => {
+        expect(isBlank('')).toBe(true);
+        expect(isBlank('   ')).toBe(true);
+        expect(isBlank('\t\n')).toBe(true);
+        expect(isBlank('test')).toBe(false);
+        
+        expect(isNotBlank('')).toBe(false);
+        expect(isNotBlank('   ')).toBe(false);
+        expect(isNotBlank('test')).toBe(true);
+      });
+    });
+
+    it('isValidIdentifier should validate identifiers', () => {
+      expect(isValidIdentifier('validName')).toBe(true);
+      expect(isValidIdentifier('_validName')).toBe(true);
+      expect(isValidIdentifier('$validName')).toBe(true);
+      expect(isValidIdentifier('123invalid')).toBe(false);
+      expect(isValidIdentifier('invalid-name')).toBe(false);
+      expect(isValidIdentifier('')).toBe(false);
+    });
+
+    it('isNumeric should validate numeric strings', () => {
+      expect(isNumeric('123')).toBe(true);
+      expect(isNumeric('123.45')).toBe(true);
+      expect(isNumeric('-123')).toBe(true);
+      expect(isNumeric('abc')).toBe(false);
+      expect(isNumeric('')).toBe(false);
+    });
+
+    it('isAlphanumeric should validate alphanumeric strings', () => {
+      expect(isAlphanumeric('abc123')).toBe(true);
+      expect(isAlphanumeric('ABC')).toBe(true);
+      expect(isAlphanumeric('123')).toBe(true);
+      expect(isAlphanumeric('abc-123')).toBe(false);
+      expect(isAlphanumeric('')).toBe(false);
+    });
+
+    it('isAlpha should validate alphabetic strings', () => {
+      expect(isAlpha('abc')).toBe(true);
+      expect(isAlpha('ABC')).toBe(true);
+      expect(isAlpha('abc123')).toBe(false);
+      expect(isAlpha('')).toBe(false);
+    });
+  });
+
+  describe('string manipulation', () => {
+    it('truncate should truncate with ellipsis', () => {
+      expect(truncate('hello world', 5)).toBe('he...');
+      expect(truncate('hello', 10)).toBe('hello');
+      expect(truncate('hello world', 8, '---')).toBe('hello---');
+    });
+
+    it('truncateMiddle should truncate in middle', () => {
+      expect(truncateMiddle('hello world test', 10)).toBe('hel...test');
+      expect(truncateMiddle('short', 10)).toBe('short');
+    });
+
+    it('repeat should repeat strings', () => {
+      expect(repeat('abc', 3)).toBe('abcabcabc');
+      expect(repeat('x', 0)).toBe('');
+      expect(repeat('', 5)).toBe('');
+    });
+
+    it('reverse should reverse strings', () => {
+      expect(reverse('hello')).toBe('olleh');
+      expect(reverse('')).toBe('');
+      expect(reverse('a')).toBe('a');
+    });
+  });
+
+  describe('HTML utilities', () => {
+    it('escapeHtml should escape HTML entities', () => {
+      expect(escapeHtml('<div>test</div>')).toBe('&lt;div&gt;test&lt;/div&gt;');
+      expect(escapeHtml('a & b')).toBe('a &amp; b');
+      expect(escapeHtml('"quoted"')).toBe('&quot;quoted&quot;');
+    });
+
+    it('unescapeHtml should unescape HTML entities', () => {
+      expect(unescapeHtml('&lt;div&gt;test&lt;/div&gt;')).toBe('<div>test</div>');
+      expect(unescapeHtml('a &amp; b')).toBe('a & b');
+      expect(unescapeHtml('&quot;quoted&quot;')).toBe('"quoted"');
+    });
+  });
+
+  describe('utility functions', () => {
+    it('count should count substring occurrences', () => {
+      expect(count('hello world hello', 'hello')).toBe(2);
+      expect(count('aaa', 'aa')).toBe(2); // Overlapping matches
+      expect(count('test', 'xyz')).toBe(0);
+    });
+
+    it('uuid should generate valid UUIDs', () => {
+      const id1 = uuid();
+      const id2 = uuid();
+      expect(id1).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+      expect(id2).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+      expect(id1).not.toBe(id2); // Should be unique
+    });
+
+    it('randomString should generate random strings', () => {
+      const str1 = randomString(10);
+      const str2 = randomString(10);
+      expect(str1.length).toBe(10);
+      expect(str2.length).toBe(10);
+      expect(str1).not.toBe(str2); // Should be different
+      
+      const customStr = randomString(5, 'ABC');
+      expect(customStr.length).toBe(5);
+      expect(customStr).toMatch(/^[ABC]+$/);
+    });
+
+    it('levenshtein should calculate edit distance', () => {
+      expect(levenshtein('', '')).toBe(0);
+      expect(levenshtein('hello', 'hello')).toBe(0);
+      expect(levenshtein('hello', 'helo')).toBe(1);
+      expect(levenshtein('kitten', 'sitting')).toBe(3);
+    });
+
+    it('similarity should calculate similarity score', () => {
+      expect(similarity('hello', 'hello')).toBe(1);
+      expect(similarity('', '')).toBe(1);
+      expect(similarity('hello', 'world')).toBeLessThan(0.5);
+      expect(similarity('hello', 'helo')).toBeGreaterThan(0.8);
+    });
+  });
+
+  describe('format utilities', () => {
+    it('numberWithCommas should add commas to numbers', () => {
+      expect(numberWithCommas(1000)).toBe('1,000');
+      expect(numberWithCommas(1234567)).toBe('1,234,567');
+      expect(numberWithCommas(100)).toBe('100');
+    });
+
+    it('format should template strings', () => {
+      expect(format('Hello {name}!', { name: 'World' })).toBe('Hello World!');
+      expect(format('{a} + {b} = {sum}', { a: 1, b: 2, sum: 3 })).toBe('1 + 2 = 3');
+    });
+  });
+
+  describe('extractTraits', () => {
+    it('should extract trait syntax from code', () => {
+      const code = `
+        <Entity position="[1,2,3]" rotation="[0,0,0,1]">
+          <Cube color="#ff0000" />
+        </Entity>
+      `;
+      const traits = extractTraits(code);
+      expect(traits).toEqual(['Entity', 'Cube']);
+    });
+  });
+});

package/src/string.ts

@@ -329,7 +329,10 @@ export function unescapeHtml(s: string): string {
     ''': "'",
     '/': '/',
   };
-  return s.replace(/&(?:amp|lt|gt|quot|#39|#x27|#x2F);/g, (entity) => htmlEntities[entity] || entity);
+  return s.replace(
+    /&(?:amp|lt|gt|quot|#39|#x27|#x2F);/g,
+    (entity) => htmlEntities[entity] || entity
+  );
 }
 
 /**
@@ -382,7 +385,10 @@ export function isAlpha(s: string): boolean {
 /**
  * Generate a random string
  */
-export function randomString(length: number, charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'): string {
+export function randomString(
+  length: number,
+  charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+): string {
   let result = '';
   for (let i = 0; i < length; i++) {
     result += charset[Math.floor(Math.random() * charset.length)];
@@ -497,3 +503,14 @@ export function similarity(a: string, b: string): number {
   if (maxLen === 0) return 1;
   return 1 - levenshtein(a, b) / maxLen;
 }
+
+/**
+ * Extract HoloScript traits (e.g., @grabbable) from a code string
+ */
+export function extractTraits(code: string): string[] {
+  const re = /@([a-zA-Z_]\w*)/g;
+  const traits = new Set<string>();
+  let m;
+  while ((m = re.exec(code)) !== null) traits.add(`@${m[1]}`);
+  return [...traits];
+}