initial commit

This commit is contained in:
2026-02-12 00:45:31 -08:00
commit 5f168f370b
3024 changed files with 804889 additions and 0 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,264 @@
<?xml version="1.0" encoding="UTF-8"?>
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.11.0 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="topics" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro="">
<tab type="modulelist" visible="yes" title="" intro=""/>
<tab type="modulemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="concepts" visible="yes" title="">
</tab>
<tab type="interfaces" visible="yes" title="">
<tab type="interfacelist" visible="yes" title="" intro=""/>
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="structs" visible="yes" title="">
<tab type="structlist" visible="yes" title="" intro=""/>
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
</tab>
<tab type="exceptions" visible="yes" title="">
<tab type="exceptionlist" visible="yes" title="" intro=""/>
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<detaileddescription title=""/>
<includes visible="$SHOW_HEADERFILE"/>
<inheritancegraph visible="yes"/>
<collaborationgraph visible="yes"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<services title=""/>
<interfaces title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>
<privatemethods title=""/>
<privatestaticmethods title=""/>
<privateattributes title=""/>
<privatestaticattributes title=""/>
<friends title=""/>
<related title="" subtitle=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<enums title=""/>
<services title=""/>
<interfaces title=""/>
<constructors title=""/>
<functions title=""/>
<related title=""/>
<variables title=""/>
<properties title=""/>
<events title=""/>
</memberdef>
<allmemberslink visible="yes"/>
<usedfiles visible="$SHOW_USED_FILES"/>
<authorsection visible="yes"/>
</class>
<!-- Layout definition for a namespace page -->
<namespace>
<detaileddescription title=""/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<interfaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<concepts visible="yes" title=""/>
<structs visible="yes" title=""/>
<exceptions visible="yes" title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
</memberdef>
<authorsection visible="yes"/>
</namespace>
<!-- Layout definition for a concept page -->
<concept>
<detaileddescription title=""/>
<includes visible="$SHOW_HEADERFILE"/>
<definition visible="yes" title=""/>
<authorsection visible="yes"/>
</concept>
<!-- Layout definition for a file page -->
<file>
<detaileddescription title=""/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<includegraph visible="yes"/>
<includedbygraph visible="yes"/>
<sourcelink visible="yes"/>
<memberdecl>
<interfaces visible="yes" title=""/>
<classes visible="yes" title=""/>
<structs visible="yes" title=""/>
<exceptions visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<concepts visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<functions title=""/>
<variables title=""/>
<properties title=""/>
</memberdef>
<authorsection/>
</file>
<!-- Layout definition for a group page -->
<group>
<detaileddescription title=""/>
<groupgraph visible="yes"/>
<memberdecl>
<nestedgroups visible="yes" title=""/>
<modules visible="yes" title=""/>
<dirs visible="yes" title=""/>
<files visible="yes" title=""/>
<namespaces visible="yes" title=""/>
<concepts visible="yes" title=""/>
<classes visible="yes" title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
<membergroups visible="yes"/>
</memberdecl>
<memberdef>
<pagedocs/>
<inlineclasses title=""/>
<defines title=""/>
<typedefs title=""/>
<sequences title=""/>
<dictionaries title=""/>
<enums title=""/>
<enumvalues title=""/>
<functions title=""/>
<variables title=""/>
<signals title=""/>
<publicslots title=""/>
<protectedslots title=""/>
<privateslots title=""/>
<events title=""/>
<properties title=""/>
<friends title=""/>
</memberdef>
<authorsection visible="yes"/>
</group>
<!-- Layout definition for a C++20 module page -->
<module>
<briefdescription visible="yes"/>
<exportedmodules visible="yes"/>
<memberdecl>
<concepts visible="yes" title=""/>
<classes visible="yes" title=""/>
<enums title=""/>
<typedefs title=""/>
<functions title=""/>
<variables title=""/>
<membergroups title=""/>
</memberdecl>
<detaileddescription title=""/>
<memberdecl>
<files visible="yes"/>
</memberdecl>
</module>
<!-- Layout definition for a directory page -->
<directory>
<briefdescription visible="yes"/>
<directorygraph visible="yes"/>
<memberdecl>
<dirs visible="yes"/>
<files visible="yes"/>
</memberdecl>
<detaileddescription title=""/>
</directory>
</doxygenlayout>

View File

@@ -0,0 +1,11 @@
/**
FastLED Doxygen Stylesheet
https://github.com/FastLED/FastLED/
*/
/** Hide "Detailed UIDescription" sub-header when the
* detailed description is at the top of a page.
*/
.contents a#details + h2.groupheader {
display:none;
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB

View File

@@ -0,0 +1,18 @@
<!-- HTML footer for doxygen 1.9.3-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
$navpath
<li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
</ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
</small></address>
<!--END !GENERATE_TREEVIEW-->
<!-- ... -->
</body>
</html>

View File

@@ -0,0 +1,76 @@
<!-- HTML header for doxygen 1.9.3-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN FULL_SIDEBAR-->
<script type="text/javascript">var page_layout=1;</script>
<!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
<link href="$relpath^fastled_logo.png" type="image/svg+xml" rel="shortcut icon" />
$extrastylesheet
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">DoxygenAwesomeDarkModeToggle.init()</script>
</head>
<body>
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN FULL_SIDEBAR-->
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
<!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<!--BEGIN PROJECT_LOGO-->
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
<!--END PROJECT_LOGO-->
<!--BEGIN PROJECT_NAME-->
<td id="projectalign">
<div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
</div>
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
</td>
<!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME-->
<!--BEGIN PROJECT_BRIEF-->
<td>
<div id="projectbrief">$projectbrief</div>
</td>
<!--END PROJECT_BRIEF-->
<!--END !PROJECT_NAME-->
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN SEARCHENGINE-->
<!--BEGIN !FULL_SIDEBAR-->
<td>$searchbox</td>
<!--END !FULL_SIDEBAR-->
<!--END SEARCHENGINE-->
<!--END DISABLE_INDEX-->
</tr>
<!--BEGIN SEARCHENGINE-->
<!--BEGIN FULL_SIDEBAR-->
<tr><td colspan="2">$searchbox</td></tr>
<!--END FULL_SIDEBAR-->
<!--END SEARCHENGINE-->
</tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->

View File

@@ -0,0 +1,184 @@
# FastLED JavaScript Linting & Type Safety Strategy
## 📊 Current Status
### Codebase Overview
- **8 JavaScript files** in `src/platforms/wasm/`
- **5,713 lines of code** total
- **714 lines average** per file
- **Comprehensive JSDoc coverage** (100% of files documented)
- **Modern JavaScript features** (ES2022, async/await, classes)
### Current Linting Configuration
- **Fast Node.js + ESLint linting** with critical issue detection
- **Speed-optimized approach** - fast linting or no linting at all
- **Critical runtime issues only** - no style enforcement
- **Browser environment compatibility** (DOM, WebAssembly, Web Audio API)
## 🎯 Fast-Only Linting Strategy
### Current Configuration (Critical Issues Only)
The fast linter only checks for **critical runtime issues**:
- `no-debugger` - Prevents debugger statements in production
- `no-eval` - Prevents eval() security vulnerabilities
**No style enforcement** - focuses on critical issues only for maximum speed.
### Performance Results
- **JavaScript linting**: ~0.9 seconds (53x faster than previous solution)
- **Total lint time**: ~1.6 seconds (Python + C++ + JavaScript)
### Philosophy: Fast Only
**JavaScript linting follows a "fast only" policy:**
-**Fast linting available**: Uses Node.js + ESLint (~0.9 seconds)
- ⚠️ **Fast linting unavailable**: Skips JavaScript linting entirely
-**No slow fallback**: Fast linting or no linting at all
## 🛠️ Available Tools
### Setup (Automatic)
Fast JavaScript linting is automatically installed during project setup:
```bash
# Installs everything including fast JS linting
./install
# Or manually install just JavaScript linting
uv run ci/setup-js-linting-fast.py
```
### Direct Linting Commands
```bash
# Fast JavaScript linting (recommended)
bash .cache/js-tools/lint-js-fast
# Full project linting (includes JavaScript when available)
bash lint
```
### Enhancement Analysis Script
```bash
# Comprehensive codebase analysis
uv run scripts/enhance-js-typing.py --approach summary
# Detailed linting issue breakdown
uv run scripts/enhance-js-typing.py --approach linting
# Performance issue identification
uv run scripts/enhance-js-typing.py --approach performance
# Add JSDoc type annotations to file
uv run scripts/enhance-js-typing.py --approach types --file src/platforms/wasm/compiler/index.js
# Generate ESLint configuration variants
uv run scripts/enhance-js-typing.py --approach configs
```
## 📈 Configuration Variants
### Current Configuration (Fast & Minimal)
```javascript
module.exports = {
env: {
browser: true,
es2022: true,
worker: true
},
parserOptions: {
ecmaVersion: 2022,
sourceType: "module"
},
rules: {
// Only critical runtime issues
"no-debugger": "error",
"no-eval": "error"
}
};
```
### Strict Configuration (Available via configs script)
```javascript
module.exports = {
env: {
browser: true,
es2022: true,
worker: true
},
parserOptions: {
ecmaVersion: 2022,
sourceType: "module"
},
rules: {
// Critical issues
"no-debugger": "error",
"no-eval": "error",
// Code quality
"eqeqeq": "error",
"prefer-const": "error",
"no-var": "error",
"no-await-in-loop": "error",
"guard-for-in": "error",
"camelcase": "warn",
"default-param-last": "warn"
}
};
```
## 🚀 Implementation Roadmap
### Immediate Actions (Week 1)
1. **Use fast linting** - Integrated into `bash lint` by default
2. **Fix critical issues** - Only debugger and eval() usage
3. **Document changes** - Update code comments
### Short-term Goals (Month 1)
1. **Add @ts-check** to one file as pilot
2. **Enhance JSDoc** for complex functions
3. **Create type definitions** for WebAssembly interfaces
4. **Set up CI integration** for automatic linting
### Long-term Vision (Quarter 1)
1. **Gradual enhancement** - Add more rules incrementally
2. **Performance optimization** - Identify and fix await-in-loop issues
3. **Type safety** - Comprehensive JSDoc annotations
4. **Automated enforcement** - CI/CD integration
## 🔧 Troubleshooting
### Fast Linting Not Available
If you see "JavaScript linting tools not found":
```bash
# Install fast linting
uv run ci/setup-js-linting-fast.py
# Verify installation
bash .cache/js-tools/lint-js-fast
```
### Performance Issues
If linting is slow:
- Fast linting should complete in ~0.9 seconds
- If slower, check Node.js installation in `.js-tools/`
- Consider regenerating setup: `rm -rf .js-tools && uv run ci/setup-js-linting-fast.py`
### Configuration Issues
If linting fails:
- Check ESLint configuration: `.js-tools/.eslintrc.js`
- Verify Node.js modules: `.js-tools/node_modules/.bin/eslint`
- Test manually: `bash .cache/js-tools/lint-js-fast`
## 📝 Files Created
The fast linting setup creates:
- `.js-tools/node/` - Node.js binary
- `.js-tools/node_modules/` - ESLint installation
- `.js-tools/.eslintrc.js` - ESLint configuration
- `.js-tools/package.json` - Node.js package definition
- `.cache/js-tools/lint-js-fast` - Fast linting script
## 🎯 Best Practices
1. **Use `bash lint`** for comprehensive project linting
2. **Fix critical issues immediately** - debugger and eval() usage
3. **Use enhancement script** for deeper analysis
4. **Add JSDoc gradually** - enhance type safety over time
5. **Test before committing** - ensure linting passes

View File

@@ -0,0 +1,15 @@
img {
max-height: 70%;
height: auto;
width: auto;
max-width: 70%;
object-fit: contain;
}
svg {
max-height: 70%;
height: auto;
width: auto;
max-width: 70%;
object-fit: contain;
}