V2

.github/copilot-instructions.md

@@ -0,0 +1,38 @@
+# GitHub Copilot Instructions for THREE Utils
+
+This file contains coding conventions and guidelines for the THREE Utils project to help GitHub Copilot generate consistent and appropriate code suggestions.
+
+## TypeScript Conventions
+
+- Use `type` instead of `interface` for object type definitions
+- Import types with `import type { ... }` syntax
+- Place complex type definitions in `src/types/` directory
+- Export types with descriptive names
+
+## Code Style Guidelines
+
+- Follow existing project patterns and naming conventions
+- Ensure all exported functions have JSDoc documentation
+- Use strict TypeScript settings and explicit return types
+- Prefer functional programming patterns where appropriate
+
+## Three.js Specific Guidelines
+
+- Always clone Three.js objects (Vector3, Matrix4, Quaternion) before modification
+- Implement proper dispose patterns for Three.js resources (geometries, materials, textures)
+- Use namespace-based exports for utility modules (e.g., `CallbackUtils`, `GeomUtils`)
+- Maintain performance considerations for animation loops and real-time rendering
+
+## Testing Requirements
+
+- Write unit tests for all new functionality using Jest
+- Place test files in `src/__tests__/` directory
+- Aim for minimum 80% code coverage
+- Include both positive and negative test cases
+
+## Module Organization
+
+- Keep utilities in separate files by functionality
+- Use modular exports to support tree-shaking
+- Maintain separate entry points for `assets` and `audio` modules
+- Follow the existing file naming pattern (kebab-case)

.github/workflows/bundle-size-check.yml

@@ -0,0 +1,43 @@
+name: Bundle Size Check
+
+on:
+  pull_request:
+    branches:
+      - master
+      - v2
+
+jobs:
+  analyze-bundle:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build project
+      run: npm run build
+
+    - name: Generate bundle report
+      run: |
+        cat bundle-report.json
+
+    - name: Post bundle size comment
+      uses: marocchino/sticky-pull-request-comment@v2
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        header: bundle-size
+        message: |
+          ## Bundle Size Report
+
+          ```json
+          $(cat bundle-report.json)
+          ```

.github/workflows/circular-dependencies.yml

@@ -0,0 +1,28 @@
+name: Circular Dependencies Testing
+
+on:
+  pull_request:
+    branches:
+      - master
+      - v2
+
+jobs:
+  check-circular:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Check circular dependencies
+        run: npx madge --circular src

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,39 @@
+name: CodeQL Analysis
+
+on:
+  pull_request:
+    branches:
+      - master
+      - v2
+  push:
+    branches:
+      - master
+      - v2
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      matrix:
+        language: [ 'javascript' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+name: Lint Testing
+
+on:
+  pull_request:
+    branches:
+      - master
+      - v2
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run ESLint
+        run: npm run lint

.github/workflows/publish-npm.yml

@@ -0,0 +1,35 @@
+name: Publish Package to npm
+
+on:
+  release:
+    types: [published] # Trigger only when a release is published
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest # Use the latest Ubuntu runner
+    permissions:
+      contents: read # Allow reading repository content
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4 # Action to check out the repository code
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20' # Updated Node.js version
+          registry-url: 'https://registry.npmjs.org/' # Point to the npm registry
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci # Use 'ci' for clean installs in CI
+
+      - name: Run tests
+        run: npm test # Ensure tests pass before publishing
+
+      - name: Build package
+        run: npm run build # Run your build script
+
+      - name: Publish to npm
+        run: npm publish --access public # Publish with public access for scoped packages
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # Use the secret token for authentication

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Run Tests
+
+on:
+  push:
+    branches:
+      - master
+      - v2
+  pull_request:
+    branches:
+      - master
+      - v2
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+      - run: npm run build

.github/workflows/typedoc.yml

@@ -0,0 +1,41 @@
+name: Generate and Deploy Typedoc
+
+on:
+  push:
+    branches:
+      - master
+      - v2
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Typedoc documentation
+        run: npm run docs
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/v2'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          enable_jekyll: false
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

.gitignore

@@ -1 +1,59 @@
+# Dependencies
 node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Documentation (generated)
+docs/
+
+# Testing
+coverage/
+.nyc_output
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Webpack bundle analyzer
+bundle-report.json

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit ${1}

.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint && npm run test