Merge pull request #8 from jgphilpott/copilot/fix-d634d99a-353b-454a-b7e8-0f35fc8b4c0e

Convert Polyslice to universal Node.js/browser package with CoffeeScript-first development

Author: jgphilpott

.eslintrc.json

@@ -0,0 +1,23 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true,
+    "node": true,
+    "jest": true
+  },
+  "extends": [
+    "eslint:recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 12,
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "linebreak-style": ["error", "unix"],
+    "quotes": ["error", "single"],
+    "semi": ["error", "always"],
+    "no-unused-vars": "warn",
+    "no-console": "off"
+  }
+}

.github/FUNDING.yml

@@ -1,14 +1,4 @@
 # These are the supported funding platforms:
 
 github: [jgphilpott] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
-
-# More info: docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository#about-funding-files
+custom: ["https://www.buymeacoffee.com/jgphilpott"] # Custom sponsorship URLs for Buy Me a Coffee.

.github/ISSUE_TEMPLATE/BUG_REPORT.md

@@ -38,4 +38,4 @@ Please include the following information:
 
 ### Extra:
 
-Add any other information about the problem here.
+Add any other information about the problem here.

.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md

@@ -20,4 +20,4 @@ Add a clear and concise description of any alternative solutions or features you
 
 ### Additional Information:
 
-Add any extra information about your feature request here.
+Add any extra information about your feature request here.

.github/ISSUE_TEMPLATE/QUESTION.md

@@ -8,4 +8,4 @@ assignees: jgphilpott
 
 ### Question:
 
-Type your question here.
+Type your question here.

.github/WORKFLOWS/CHECKS.yml

@@ -0,0 +1,71 @@
+---
+applyTo: '*.coffee'
+---
+
+# CoffeeScript Contribution Instructions
+
+These guidelines apply to all CoffeeScript source edits in this repository.
+
+## Code Style: Indentation
+
+- Use 4-space indentation for all code blocks (consistent with `.editorconfig`).
+- All indentation must be multiples of 4 spaces (4, 8, 12, 16, etc.).
+
+## Code Style: Whitespace and Vertical Spacing
+
+- Preserve and prefer generous vertical whitespace for readability.
+- Insert a blank line after the following situations:
+  - function declarations/definitions
+  - if/else blocks
+  - loops
+  - any change in indentation level
+  - variable assignments before object creation/manipulation
+  - between logical groups within functions
+- Do not collapse existing blank lines when editing.
+- In helper functions, add blank lines to separate logical groups (geometry creation, mesh setup, return statements).
+- Remove trailing whitespace consistently.
+- Always insert final newline at the end of files (consistent with `.editorconfig`).
+
+If you are unsure, prefer the more spacious option to maintain consistency with the existing style.
+
+## Variable Naming Conventions
+
+- Follow standard JavaScript camelCase naming conventions for all variables.
+- **Do not use leading underscores** (`_variableName`) unless it's a true private convention.
+- **Use descriptive, full-form variable names** instead of cryptic abbreviations:
+  - ✅ Good: `for previousState in previousStates`
+  - ❌ Bad: `for s in previousStates`
+  - ✅ Good: `temporaryVertex`, `currentPolygon`
+  - ❌ Bad: `tmpV`, `curPoly`
+- Prefer clarity over brevity - code is read more often than written.
+
+## G-code Generation Guidelines
+
+- Maintain consistency with existing G-code command naming conventions.
+- Use descriptive method names like `codeLinearMovement`, `codeAutohome`.
+- Include proper G-code comments and references to Marlin documentation.
+- Ensure all temperature, speed, and coordinate parameters are validated.
+
+## Test Code Style Preferences
+
+- Add blank lines after geometry/material creation and before mesh creation.
+- Add blank lines after mesh setup and before return statements.
+- Align inline comments consistently using single space before # comment.
+- For comments explaining parameters, add period after comment for complete sentences.
+- Maintain consistent spacing around assignment operators.
+- Prefer single-line variable assignments with proper spacing.
+
+## Reserved Word Note (Project Convention)
+
+CoffeeScript reserves certain identifiers (e.g. `by` used in loop syntax). When needing coordinate component variables that might conflict, prefer capitalized suffix forms:
+
+- Use `aX, aY, aZ` / `bX, bY, bZ` instead of `ax, ay, az` / `bx, by, bz` when there is risk of `by` being parsed as the keyword.
+- This avoids accidental parse errors in inline multi-assignment statements.
+
+Adopt this naming in new geometry or test code when generating random coordinates.
+
+## Three.js Integration
+
+- When working with three.js objects, maintain clear separation between mesh processing and G-code generation.
+- Use proper three.js naming conventions for geometry manipulation.
+- Ensure mesh data extraction is compatible with both Node.js and browser environments.

.github/instructions/coffee.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: '**'
+---
+
+- Keep code DRY (Don't Repeat Yourself).
+- Use descriptive variable and function names.
+- Follow the existing code style and conventions.
+- Use double quotes on strings by default and single quotes inside strings.
+- Maintain compatibility with both Node.js and browser environments.
+- Preserve the existing G-code generation functionality.

.github/instructions/general.instructions.md

@@ -0,0 +1,29 @@
+# Refactoring Guidelines
+
+## Browser/Node.js Compatibility
+
+- Ensure all code works in both Node.js and browser environments
+- Use feature detection rather than environment detection where possible.
+- Avoid Node.js-specific APIs in core functionality.
+- Test exports work correctly in both CommonJS and browser global contexts.
+
+## G-code Generation
+
+- Maintain backward compatibility for existing G-code methods.
+- Keep G-code output format consistent with established standards.
+- Validate all numerical parameters before generating commands.
+- Include proper error handling for invalid inputs.
+
+## Three.js Integration
+
+- Keep three.js integration optional and modular.
+- Ensure mesh processing doesn't break existing functionality.
+- Support both geometry and buffer geometry where applicable.
+- Handle coordinate system conversions properly.
+
+## Performance Considerations
+
+- Minimize string concatenation in G-code generation loops.
+- Use efficient algorithms for mesh processing.
+- Consider memory usage when processing large geometries.
+- Profile critical paths and optimize as needed.

.github/instructions/refactoring.instructions.md

@@ -0,0 +1,123 @@
+# Testing Guidelines
+
+These notes define conventions and coverage expectations for the test suite.
+
+## Framework
+
+- Use Jest (already configured).
+- JavaScript test sources run directly with Jest.
+
+## File / Naming
+
+- Name pattern: `*.test.js`.
+- One logical unit per file (e.g. `polyslice.test.js`).
+- All helpers from the main class share a single consolidated test file (append new helper tests at bottom, do not create a separate file).
+
+## Structure
+
+- Use a small helper factory for repetitive data construction (e.g. `slicer()`).
+- Keep assertion helpers local (no global shared unless reused across 3+ files).
+- Avoid hidden magic numbers; define `EPS`, `TOL`, etc. at top of file.
+- Place any new shared helper functions (e.g. geometry builders, orientation wrappers) near the TOP of the consolidated test file so subsequent describe blocks can reuse them.
+- Formatting / Whitespace: Insert a blank line immediately after each `describe` declaration line and after each `it` line (before the body) to maintain generous vertical whitespace consistent with JavaScript style.
+
+## Assertions
+
+- Prefer strict equality expectations for G-code output validation.
+- When testing floating-point calculations (e.g., fan speeds), use appropriate precision handling.
+- Test both Node.js and browser environments when applicable.
+
+## Coverage Expectations (G-code Generation)
+
+Polyslice tests must include:
+
+1. **Constructor and Options**
+   - Default values initialization
+   - Custom options handling
+   - Invalid parameter rejection
+
+2. **Parameter Setters/Getters**
+   - Valid range checking
+   - Type validation
+   - Chaining behavior
+
+3. **G-code Command Generation**
+   - Basic movement commands (G0, G1)
+   - Temperature control (M104, M109, M140, M190)
+   - Fan control (M106, M107)
+   - Home commands (G28)
+   - Workspace plane setting (G17, G18, G19)
+   - Unit setting (G20, G21)
+   - Arc movements (G2, G3)
+   - Bézier curves (G5)
+   - Special commands (M117, M112, etc.)
+
+4. **Environment Compatibility**
+   - Node.js environment tests
+   - Browser environment compatibility (when applicable)
+   - Three.js integration tests
+
+5. **Edge Cases**
+   - Zero values handling
+   - Maximum/minimum parameter values
+   - Invalid parameter handling
+   - Floating-point precision
+
+Future (add later):
+
+- Random fuzz testing for parameter validation
+- Stress test with large coordinate values
+- Performance benchmarks for G-code generation
+- Integration tests with actual three.js meshes
+- Browser environment automated testing
+
+## Floating Point
+
+- Use tolerance constant (default `1e-6`) for floating-point comparisons.
+- Do not equality-compare raw floats except against `0` with documented intent.
+- For fan speed calculations, test the actual rounded output values.
+
+## Environment Testing
+
+- Test CommonJS imports (`require`)
+- Test ES module imports (`import`) when applicable
+- Verify browser global availability
+- Test three.js integration in both environments
+
+## DRY Principles
+
+- Shared helper naming: `slicer()`, `assertGCode()`.
+- Keep helpers minimal; do not abstract prematurely.
+- If helper exceeds ~30 LOC or becomes multi-purpose, split.
+
+## Test Output Clarity
+
+- Include descriptive test names that explain what is being tested.
+- Use meaningful variable names in test setup.
+- Include comments for non-obvious expectations (especially G-code format specifics).
+
+## Adding New G-code Tests
+
+When adding a new G-code command or feature:
+
+1. List expected G-code output format in comment header.
+2. Implement parameter validation tests first.
+3. Write "happy path" test with expected output.
+4. Test edge cases and invalid parameters.
+5. Add regression tests for any bugs fixed.
+
+## Performance / Stability
+
+- Long-running test suites should be opt-in via `process.env.LONG_TESTS`.
+- Default `npm test` must remain fast (< 5s typical).
+- Browser compatibility tests should be separate from core functionality tests.
+
+## Lint / Style
+
+- Follow JavaScript/ESLint formatting guidelines.
+- Keep tests readable over condensed.
+- Use descriptive assertion messages.
+
+## TODO Tags
+
+- Allowed only with issue reference: `# TODO(#123): add browser integration tests`.