@moon791017/neo-skills 1.0.24 → 1.0.25

package/GEMINI.md

@@ -107,3 +107,5 @@ When interacting with this codebase or using the extension, the agent follows th
 *   **Swift 專家:** 支援 Swift 5.0 至 6.0+ 的現代開發模式，涵蓋 SwiftUI、Structured Concurrency 與記憶體安全。
 
 *   **SwiftUI 專家:** 支援 iOS 16.0+ 與 Swift 5.0+ 的現代開發模式，專注於 NavigationStack、Observation 框架、資料流架構及高效能視圖設計。
+
+*   **JavaScript 現代語法專家:** 跨版本 JavaScript 專家 (ES6-ES2025+)，專注於現代化語法、模組系統與高效能開發模式。

package/README.md

@@ -1,6 +1,7 @@
 # Neo Skills
 
 [![test-on-develop](https://github.com/Benknightdark/neo-skills/actions/workflows/test-on-develop.yml/badge.svg)](https://github.com/Benknightdark/neo-skills/actions/workflows/test-on-develop.yml)
+[![npm version](https://img.shields.io/npm/v/@moon791017/neo-skills.svg)](https://www.npmjs.com/package/@moon791017/neo-skills)
 
 ![Neo Skills banner](https://raw.githubusercontent.com/Benknightdark/neo-skills/refs/heads/develop/images/banner.png)
 
@@ -52,10 +53,13 @@
 *   **Swift 5.0+ 專家 (`skills/neo-swift`)**：支援從基礎語法到 Swift 6 的現代開發模式，涵蓋 SwiftUI、Structured Concurrency、記憶體安全以及高效能 App 開發指引。
 *   **SwiftUI 專家 (`skills/neo-swift-ui`)**：支援 iOS 16.0+ 與 Swift 5.0+ 的現代開發模式，專注於 NavigationStack、Observation 框架、資料流架構及高效能視圖設計。
 
-### 8. 需求釐清助手
+### 8. JavaScript 開發專家
+*   **JavaScript 現代語法專家 (`skills/neo-javascript`)**：跨版本 JavaScript 專家 (ES6 - ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
+
+### 9. 需求釐清助手
 *   **需求釐清**：系統化引導用戶釐清模糊需求，並將其轉化為結構化的規格文件（背景、功能、約束、驗收標準）。
 
-### 9. 安全守衛 (Security Guard)
+### 10. 安全守衛 (Security Guard)
 *   **主動防護 (`secret-guard.ts`)**：作為 CLI 的中介軟體 (Hook)，自動攔截並掃描所有工具執行的參數。若偵測到敏感資訊（如環境設定檔、私鑰、雲端憑證等）將強制阻擋執行，防止機密外洩。
 
 ## 📂 系統架構

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-javascript/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: neo-javascript
+version: "1.0.0"
+category: "Core"
+description: "跨版本 JavaScript 專家技能 (ES6 - ES2025+)。支援現代前端與純 JavaScript 開發模式，涵蓋 Arrow Functions 到 Iterator Helpers 的全方位演進。"
+compatibility: "Supports ES6 (ES2015) through ES2025 and Stage 3+ proposals. Adaptive to modern browser environments and pure JS runtimes."
+---
+
+# Modern JavaScript (ES6+) Expert Skill
+
+## Trigger On
+- The user asks to write, debug, refactor, or review JavaScript code.
+- The project directory contains `*.js`, `*.mjs`, or JavaScript configuration files (e.g., `eslint.config.js`, `vite.config.js`).
+- HTML files (`*.html`) or Razor views (`*.cshtml`) contain inline `<script>` blocks or reference external `.js` files via `<script src="...">`.
+- The target runtime is a modern browser (Chrome 80+, Firefox 78+, Safari 14+) or a pure JS environment.
+- Code modernization is needed (e.g., converting `var` to `const`/`let`, callbacks to `async`/`await`, legacy scripts to ESM).
+
+## Workflow
+1. **Perceive (Environment Awareness):**
+   - Inspect ESLint / Biome configuration to identify the project's `ecmaVersion` and coding conventions.
+   - Determine runtime target: browser (check for DOM APIs, bundler config like `vite.config.js`, `webpack.config.js`).
+   - Detect JavaScript embedded in HTML (`*.html`) or Razor views (`*.cshtml`): identify inline `<script>` blocks and external `<script src="...">` references. For `.cshtml` files, note the interplay with Razor syntax (`@` directives, `@section Scripts`).
+   - Identify the effective ES version upper limit based on the runtime/transpiler configuration (e.g., Babel targets, TypeScript `target`, browserslist). For inline scripts without a build pipeline, default to the browser's native ES support.
+2. **Reason (Planning Phase):**
+   - Evaluate the modernization level of the current code to determine the refactoring strategy.
+   - In environments targeting older runtimes (e.g., IE11 via Babel), avoid using features without polyfill support, but prioritize using `const`/`let`, arrow functions, and template literals.
+   - In modern environments (modern browsers), actively adopt new features to reduce boilerplate code.
+   - Be aware of browser-specific concerns (DOM manipulation, Web APIs, rendering performance).
+3. **Act (Execution Phase):**
+   - Write high-quality code using modern syntax to improve readability and maintainability.
+   - Implement immutable data patterns (spread operators, `Object.freeze`, `structuredClone`, immutable array methods).
+   - Utilize `async`/`await` and `Promise` composition for asynchronous operations.
+   - Prefer ESM (`import`/`export`) as the standard module system.
+4. **Validate (Standard Validation):**
+   - Validate strict equality (`===`) usage and absence of `var` declarations.
+   - Check if asynchronous operations correctly handle errors (`try`/`catch` around `await`, `.catch()` on Promises).
+   - Ensure code avoids common security pitfalls (no `eval()`, no prototype pollution, no `innerHTML` with unsanitized input).
+   - Verify naming conventions follow community standards (camelCase for variables/functions, PascalCase for classes).
+
+## Feature Roadmap (ES6 - ES2025+)
+
+### ES6 & ES2016-ES2019 (Origin)
+- **Arrow Functions:** `(a, b) => a + b` concise function syntax with lexical `this` binding.
+- **`let` / `const`:** Block-scoped variable declarations replacing `var`.
+- **Template Literals:** `` `Hello, ${name}!` `` for string interpolation and multi-line strings.
+- **Destructuring:** `const { id, name } = user;` extract values from objects and arrays.
+- **Default / Rest / Spread:** Default parameters, `...rest` parameters, and `...spread` for arrays/objects.
+- **Classes:** `class` syntax for prototype-based inheritance with `constructor`, `extends`, and `super`.
+- **Promises:** `new Promise((resolve, reject) => ...)` for asynchronous flow control.
+- **Modules:** `import` / `export` for modular code organization (ES Modules).
+- **Symbol / Map / Set:** New primitive type and collection data structures.
+- **String Methods (ES6):** `includes()`, `startsWith()`, `endsWith()` for easier string searching.
+- **Array Methods (ES6):** `Array.from()`, `Array.of()`, `find()`, `findIndex()` for enhanced array manipulation.
+- **Number/Math Methods (ES6):** `Number.isInteger()`, `Number.isNaN()`, `Math.trunc()`, `Math.sign()`.
+- **Generators & Iterators:** `function*` and `for...of` for lazy iteration.
+- **`async` / `await` (ES2017):** Syntactic sugar for Promise-based asynchronous code.
+- **Object.values / Object.entries (ES2017):** Iterate over object values and key-value pairs.
+- **Rest / Spread Properties (ES2018):** `{ ...obj }` for object shallow cloning and rest extraction.
+- **`Promise.finally` (ES2018):** Execute cleanup logic regardless of fulfillment or rejection.
+- **Async Iteration (ES2018):** `for await...of` for consuming async iterables.
+- **`Array.flat` / `flatMap` (ES2019):** Flatten nested arrays and map-then-flatten in one step.
+- **`Object.fromEntries` (ES2019):** Convert key-value pairs back into an object.
+- **Optional Catch Binding (ES2019):** `catch { }` without requiring the error parameter.
+
+### ES2020 & ES2021 (Foundation)
+- **Optional Chaining (`?.`):** Safely access deeply nested properties without manual null checks.
+- **Nullish Coalescing (`??`):** Provide defaults only for `null`/`undefined`, unlike `||` which also catches `0`, `""`, `false`.
+- **`BigInt`:** Arbitrary-precision integer arithmetic via `123n` literal syntax.
+- **`Promise.allSettled()`:** Wait for all promises to complete regardless of rejection.
+- **`globalThis`:** Universal reference to the global object across all environments.
+- **Dynamic `import()`:** Load modules conditionally or lazily at runtime.
+- **Logical Assignment (`&&=`, `||=`, `??=`):** Combine logical operators with assignment for concise state updates.
+- **`String.prototype.replaceAll()`:** Replace all occurrences without regex.
+- **`Promise.any()`:** Resolve with the first fulfilled promise, reject only if all reject.
+- **Numeric Separators:** `1_000_000` for readable large numbers.
+
+### ES2022 & ES2023 (Productivity)
+- **Top-level `await`:** Use `await` directly in ESM modules without wrapping in an async function.
+- **Error Cause (`{ cause }`):** Chain errors to preserve root cause context.
+- **`Array.at()`:** Negative indexing for arrays, e.g., `arr.at(-1)` for the last element.
+- **`Object.hasOwn()`:** Safer, prototype-independent property check replacing `hasOwnProperty`.
+- **Class Fields:** Public and private (`#field`) instance fields and methods.
+- **RegExp Match Indices (`/d` flag):** Get start/end positions of captured groups.
+- **Immutable Array Methods:** `toSorted()`, `toReversed()`, `toSpliced()`, `with()` — return new arrays without mutation.
+- **`Array.findLast()` / `findLastIndex()`:** Search arrays from the end.
+
+### ES2024 & ES2025+ (Cutting Edge)
+- **`Promise.withResolvers()`:** Destructure `{ promise, resolve, reject }` for cleaner deferred patterns.
+- **`Object.groupBy()` / `Map.groupBy()`:** Group array elements by a classifier function.
+- **Set Methods:** `union()`, `intersection()`, `difference()`, `symmetricDifference()`, `isSubsetOf()`, `isSupersetOf()`, `isDisjointFrom()`.
+- **Iterator Helpers:** `.map()`, `.filter()`, `.take()`, `.drop()`, `.flatMap()`, `.toArray()` on iterators.
+- **`RegExp.escape()`:** Safely escape special characters for use in RegExp construction.
+- **Import Attributes:** `import data from './data.json' with { type: 'json' }`.
+- **Decorators (Stage 3):** Class and method decorators for cross-cutting concerns.
+- **`Promise.try()`:** Safely start a promise chain from a synchronous or asynchronous function.
+- **Well-formed Unicode Strings:** `String.prototype.isWellFormed()` and `toWellFormed()`.
+- **Temporal API (Stage 3):** A modern replacement for the `Date` object, providing robust date/time arithmetic.
+- **Explicit Resource Management (Stage 3):** `using` keyword with `Symbol.dispose` for deterministic cleanup.
+
+## Coding Standards
+- **Variable Declarations:** Always use `const` by default; use `let` only when reassignment is necessary. Never use `var`.
+- **Modules:** Use ESM (`import`/`export`) as the default module system. Use `import()` for dynamic/lazy loading.
+- **Immutability:** Prefer non-mutating array methods (`toSorted`, `toReversed`, `with`), spread operators, and `structuredClone` for deep copies.
+- **Async Safety:** Always wrap `await` in `try`/`catch` or chain `.catch()`. Never leave Promises unhandled. Use `AbortController` for cancellable operations.
+
+## Deliver
+- **Runtime-Optimized Code:** Provide the most appropriate modern syntax code based on the target runtime and ES version.
+- **Modernization Insights:** Provide specific refactoring suggestions for upgrading from older JavaScript syntax to new features (e.g., from callbacks to `async`/`await`, from `var` to `const`/`let`).
+- **Syntax Explanations:** Clearly explain the design intent and advantages behind the modern JavaScript features used.
+
+## Validate
+- Ensure the provided code complies with the syntax specifications of the target ES version and runtime.
+- Validate whether the code follows JavaScript best practices for error handling, null safety, and immutability.
+- Confirm the code has good readability and modern conventions (e.g., proper use of destructuring, template literals, ESM).
+
+## Documentation
+### Official References
+- [ECMAScript 2025 Language Specification](https://tc39.es/ecma262/)
+- [TC39 Proposals (Stage 3+)](https://github.com/tc39/proposals/blob/main/README.md)
+- [MDN Web Docs - JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+
+### Internal References
+- [JavaScript Coding Style and Naming Conventions Guide](reference/coding-style.md)
+- [JavaScript Anti-Patterns and Best Practices](reference/anti-patterns.md)
+- [Modern JavaScript Patterns Guide](reference/patterns.md)

package/skills/neo-javascript/reference/anti-patterns.md

@@ -0,0 +1,296 @@
+# JavaScript Anti-Patterns & Best Practices
+
+This document lists common mistakes (Anti-Patterns) in JavaScript development and their corresponding correct practices (Best Practices).
+
+## 1. Variable Declarations and Scoping
+
+### 1.1 Avoid `var` — Use `const` and `let`
+
+**Problem**: `var` is function-scoped and hoisted, leading to unexpected behavior and bugs in loops and closures.
+
+- **Bad**:
+
+  ```javascript
+  for (var i = 0; i < 5; i++) {
+    setTimeout(() => console.log(i), 100); // Prints 5, 5, 5, 5, 5
+  }
+  ```
+
+- **Good**:
+
+  ```javascript
+  for (let i = 0; i < 5; i++) {
+    setTimeout(() => console.log(i), 100); // Prints 0, 1, 2, 3, 4
+  }
+  ```
+
+### 1.2 Avoid Loose Equality (`==`)
+
+**Problem**: `==` performs type coercion, leading to surprising comparisons (e.g., `0 == ''` is `true`, `null == undefined` is `true`).
+
+- **Bad**:
+
+  ```javascript
+  if (value == null) { ... }  // Catches both null and undefined — unclear intent
+  if (count == '0') { ... }   // true due to type coercion
+  ```
+
+- **Good**:
+
+  ```javascript
+  if (value === null || value === undefined) { ... }  // Explicit intent
+  if (count === 0) { ... }  // No coercion surprises
+  ```
+
+---
+
+## 2. Asynchronous Programming
+
+### 2.1 Avoid Callback Hell
+
+**Problem**: Deeply nested callbacks make code unreadable and error handling fragile.
+
+- **Bad**:
+
+  ```javascript
+  getUser(id, (err, user) => {
+    if (err) return handleError(err);
+    getOrders(user.id, (err, orders) => {
+      if (err) return handleError(err);
+      getDetails(orders[0].id, (err, details) => {
+        // Deeply nested...
+      });
+    });
+  });
+  ```
+
+- **Good**:
+
+  ```javascript
+  try {
+    const user = await getUser(id);
+    const orders = await getOrders(user.id);
+    const details = await getDetails(orders[0].id);
+  } catch (err) {
+    handleError(err);
+  }
+  ```
+
+### 2.2 Avoid Unhandled Promise Rejections
+
+**Problem**: A Promise without `.catch()` or `try`/`catch` around `await` causes unhandled rejection warnings and unpredictable application states.
+
+- **Bad**:
+
+  ```javascript
+  async function fetchData() {
+    const data = await api.get('/data'); // No error handling
+    return data;
+  }
+  ```
+
+- **Good**:
+
+  ```javascript
+  async function fetchData() {
+    try {
+      const data = await api.get('/data');
+      return data;
+    } catch (err) {
+      throw new Error('Failed to fetch data', { cause: err });
+    }
+  }
+  ```
+
+---
+
+## 3. Memory & Performance
+
+### 3.1 Avoid Event Listener and Timer Leaks
+
+**Problem**: Adding event listeners or `setInterval` without cleanup leads to memory leaks, especially in single-page applications.
+
+- **Bad**:
+
+  ```javascript
+  function setup() {
+    window.addEventListener('resize', handleResize);
+    // Never removed — leaks when component is destroyed
+  }
+  ```
+
+- **Good**:
+
+  ```javascript
+  const controller = new AbortController();
+  window.addEventListener('resize', handleResize, { signal: controller.signal });
+  // Cleanup: controller.abort();
+  ```
+
+### 3.2 Avoid Blocking the Main Thread
+
+**Problem**: CPU-intensive synchronous operations (huge loops, massive DOM updates, or heavy JSON parsing) block the main thread, freezing the UI and making the browser unresponsive.
+
+- **Bad**:
+
+  ```javascript
+  function processLargeData(items) {
+    // Blocks the UI thread completely for a long time
+    return items.map(item => expensiveComputation(item)); 
+  }
+  ```
+
+- **Good**:
+
+  ```javascript
+  // Use Web Workers for heavy computation, or chunking via setTimeout/requestAnimationFrame
+  function processDataInChunks(items) {
+    let index = 0;
+    function chunk() {
+      const end = Math.min(index + 100, items.length);
+      for (; index < end; index++) {
+        expensiveComputation(items[index]);
+      }
+      if (index < items.length) {
+        requestAnimationFrame(chunk); // Yield back to the browser
+      }
+    }
+    chunk();
+  }
+  ```
+
+---
+
+## 4. Security
+
+### 4.1 Avoid `eval()` and `innerHTML` with Untrusted Input
+
+**Problem**: `eval()` executes arbitrary code; `innerHTML` with user input enables XSS attacks.
+
+- **Bad**:
+
+  ```javascript
+  element.innerHTML = userComment; // XSS vulnerability
+  eval(userInput); // Remote code execution
+  ```
+
+- **Good**:
+
+  ```javascript
+  element.textContent = userComment; // Safe
+  // For HTML rendering, use a sanitization library (e.g., DOMPurify)
+  ```
+
+### 4.2 Avoid Mutating Function Parameters (Immutability)
+
+**Problem**: Directly mutating input arguments causes hard-to-trace side effects. The caller's data is changed unexpectedly.
+
+- **Bad**:
+
+  ```javascript
+  const addNewTag = (tags, newTag) => {
+    tags.push(newTag); // Mutates the original array
+    return tags;
+  };
+  ```
+
+- **Good**:
+
+  ```javascript
+  const addNewTag = (tags, newTag) => {
+    return [...tags, newTag]; // Returns a new array, keeps original data intact
+  };
+  ```
+
+### 4.3 Avoid Prototype Pollution
+
+**Problem**: Merging untrusted objects into existing objects can overwrite `Object.prototype` properties, leading to security vulnerabilities.
+
+- **Bad**:
+
+  ```javascript
+  function merge(target, source) {
+    for (const key in source) {
+      target[key] = source[key]; // '__proto__' can be injected
+    }
+  }
+  ```
+
+- **Good**:
+
+  ```javascript
+  function merge(target, source) {
+    for (const key of Object.keys(source)) {
+      if (key === '__proto__' || key === 'constructor') continue;
+      target[key] = source[key];
+    }
+  }
+  // Or use structuredClone / Object.assign with null-prototype objects
+  ```
+
+---
+
+## 5. Modern JavaScript Patterns
+
+### 5.1 Variable Declarations (ES6+)
+
+- **Legacy**: `var name = 'Alice';`
+- **Modern**: `const name = 'Alice';` (Block-scoped, no hoisting surprises)
+
+### 5.2 Async Flow (ES2017+)
+
+- **Legacy**:
+
+  ```javascript
+  fetch('/api/data')
+    .then(res => res.json())
+    .then(data => console.log(data))
+    .catch(err => console.error(err));
+  ```
+
+- **Modern**:
+
+  ```javascript
+  try {
+    const res = await fetch('/api/data');
+    const data = await res.json();
+    console.log(data);
+  } catch (err) {
+    console.error(err);
+  }
+  ```
+
+### 5.3 Default Values (ES2020+)
+
+- **Legacy**: `const name = obj && obj.user && obj.user.name || 'default';`
+- **Modern**: `const name = obj?.user?.name ?? 'default';` (Optional chaining + nullish coalescing)
+
+### 5.4 Array Mutation (ES2023+)
+
+- **Legacy**: `const sorted = [...arr].sort(compareFn);` (Manual copy to avoid mutation)
+- **Modern**: `const sorted = arr.toSorted(compareFn);` (Returns a new sorted array)
+
+### 5.5 Object Property Checking (ES2022+)
+
+- **Legacy**: `if (obj.hasOwnProperty('key'))` (Can be overridden on the object)
+- **Modern**: `if (Object.hasOwn(obj, 'key'))` (Static method, safe from prototype overriding)
+
+### 5.6 Module System (ES6+)
+
+- **Legacy**: `var cloneDeep = require('lodash/cloneDeep');` (CommonJS / Script tags)
+- **Modern**: `import { cloneDeep } from 'lodash-es';` (ESM)
+
+### 5.7 Logical Assignment (ES2021+)
+
+- **Legacy**: `if (!obj.prop) { obj.prop = value; }` (Verbose and repetitive)
+- **Modern**: `obj.prop ??= value;` (Concise nullish assignment)
+
+### 5.8 String & Array Searching (ES6+)
+
+- **Legacy**: `if (str.indexOf('text') !== -1)` (Returns index, requires `!== -1` check)
+- **Modern**: `if (str.includes('text'))` (Returns boolean directly, clearer intent)
+
+### 5.9 Object Grouping (ES2024+)
+
+- **Legacy**: `users.reduce((acc, user) => { (acc[user.role] ||= []).push(user); return acc; }, {});` (Verbose reduce logic)
+- **Modern**: `Object.groupBy(users, user => user.role);` (Clear intent, native support)

package/skills/neo-javascript/reference/coding-style.md

@@ -0,0 +1,112 @@
+# JavaScript Coding Conventions
+
+This guide follows community-established conventions from [MDN JavaScript Guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide), [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript), and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html), aimed at improving development efficiency and maintaining project consistency.
+
+## 1. Naming Conventions
+
+Good naming is the core of self-documenting code and reduces communication overhead.
+
+### 1.1 camelCase
+Used for **variables**, **functions**, and **object properties**.
+- **Variable**: `const userName = 'Alice';`
+- **Function**: `function getUserById(id) { ... }`
+- **Object Property**: `{ firstName: 'Bob', lastName: 'Smith' }`
+
+### 1.2 PascalCase
+Used for **classes**, **constructors**, and **components**.
+- **Class**: `class UserManager { ... }`
+- **React/UI Component**: `function NavBar() { ... }`
+
+### 1.3 UPPER_SNAKE_CASE
+Used for **module-level constants** and **configuration values**.
+- **Constant**: `const MAX_RETRIES = 3;`
+- **Config**: `const API_BASE_URL = 'https://api.example.com';`
+
+### 1.4 Private Fields
+Use the `#` prefix for **private class fields** (ES2022+).
+- **Private field**: `#count = 0;`
+- **Private method**: `#validate() { ... }`
+
+---
+
+## 2. File Organization
+
+- **File naming**: Use `kebab-case` for file names (e.g., `user-service.js`, `auth-utils.mjs`).
+- **Module type**: Use `.mjs` extension or `"type": "module"` in `package.json` for ESM.
+- **Single responsibility**: One primary export per module file to facilitate tree-shaking and code navigation.
+- **Import order**: External packages first, then internal modules. Separate groups with blank lines.
+```javascript
+// 1. External packages
+import React, { useState } from 'react';
+import { debounce } from 'lodash-es';
+
+// 2. Internal modules
+import { validateInput } from './utils/validation.js';
+import { UserCard } from './components/user-card.js';
+```
+
+---
+
+## 3. Formatting
+
+### 3.1 K&R Style (Opening brace on same line)
+The opening brace `{` stays on the same line as the statement. This is the standard JavaScript style.
+```javascript
+// Correct approach
+function process() {
+  if (isReady) {
+    doWork();
+  }
+}
+```
+
+### 3.2 Indentation and Spacing
+- **Indentation**: Fixed at **2 spaces**. The use of Tab characters is prohibited to ensure consistent display across platforms.
+- **Semicolons**: Be consistent within a project. If using semicolons, use them everywhere. If omitting (relying on ASI), do so consistently and understand the pitfalls.
+- **Blank lines**: Leave one blank line between function declarations; use a single blank line to separate logical blocks within a function.
+
+---
+
+## 4. Asynchronous Programming
+
+- **Async/Await**: Prefer `async`/`await` over `.then()` chains for readability.
+- **Error Handling**: Always wrap `await` calls in `try`/`catch` or use a utility wrapper.
+- **AbortController**: Use `AbortController` for cancellable fetch requests, timers, and event listeners.
+```javascript
+async function getUserById(id, signal) {
+  const response = await fetch(`/api/users/${id}`, { signal });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`, { cause: response });
+  }
+  return response.json();
+}
+```
+
+---
+
+## 5. Modern JavaScript Best Practices
+
+- **Variable Declarations (`const`/`let`)**: Use `const` by default. Use `let` only when the binding will be reassigned. Never use `var`.
+  - Recommended: `const users = [];`
+- **Null/Undefined Checks**: Use nullish coalescing (`??`) and optional chaining (`?.`) instead of `||` and manual checks.
+  - Recommended: `const name = user?.profile?.name ?? 'Anonymous';`
+- **Object/Array Initialization**: Use destructuring, spread operators, and shorthand property names.
+  - Recommended: `const { id, name } = user;`
+- **Equality**: Always use `===` and `!==`. Never use `==` or `!=`.
+
+---
+
+## 6. Commenting Conventions
+
+- **JSDoc**: Public APIs and exported functions should use `/** ... */` JSDoc comments for IDE IntelliSense and documentation generation.
+```javascript
+/**
+ * Fetches a user by their unique identifier.
+ * @param {number} id - The user's ID.
+ * @param {AbortSignal} [signal] - Optional signal to cancel the request.
+ * @returns {Promise<User>} The user object.
+ */
+export async function getUserById(id, signal) { ... }
+```
+- **Logical Comments**: Comments should explain "Why" the processing is done this way, not repeat "What" the code does.
+- **TODO/FIXME**: Use `// TODO:` for planned improvements and `// FIXME:` for known issues.

package/skills/neo-javascript/reference/patterns.md

@@ -0,0 +1,280 @@
+# Modern JavaScript Patterns Guide
+
+This document introduces recommended development patterns in ES6 through ES2025+, aiming to simplify code and improve reliability using modern syntax.
+
+## 1. Module and Declaration Patterns
+
+### 1.1 ESM Modules (ES6+)
+**Recommendation**: Use `import`/`export` with named exports for tree-shaking compatibility.
+```javascript
+// Named exports (preferred for libraries)
+export function formatDate(date) { ... }
+export function parseDate(str) { ... }
+
+// Default export (preferred for single-purpose modules)
+export default class UserService { ... }
+```
+
+### 1.2 Dynamic Import (ES2020+)
+**Recommendation**: Lazy-load modules for code splitting and conditional loading.
+```javascript
+const { Chart } = await import('./chart.js');
+```
+
+### 1.3 Arrow Functions vs Function Declarations
+**Recommendation**: Use arrow functions for callbacks and short expressions. Use function declarations for top-level named functions that benefit from hoisting.
+```javascript
+// Arrow functions for callbacks
+const doubled = numbers.map(n => n * 2);
+
+// Function declarations for top-level definitions
+function processOrder(order) {
+  // ...
+}
+```
+
+### 1.4 Logical Assignment (ES2021+)
+**Recommendation**: Use logical assignment operators (`??=`, `||=`, `&&=`) to concisely update variables only when specific conditions are met.
+```javascript
+// ??= (Nullish coalescing assignment)
+user.role ??= 'viewer'; // Assigns 'viewer' only if user.role is null or undefined
+
+// ||= (Logical OR assignment)
+config.timeout ||= 5000; // Assigns 5000 if config.timeout is falsy (e.g., 0, '', null)
+
+// &&= (Logical AND assignment)
+state.isReady &&= verifyStatus(); // Updates state.isReady only if it is already truthy
+```
+
+---
+
+## 2. Data Structures and Immutability
+
+### 2.1 Destructuring and Spread (ES6+)
+**Recommendation**: Use destructuring to extract values and spread to create shallow copies.
+```javascript
+// Object destructuring with renaming and defaults
+const { name: userName, role = 'viewer' } = user;
+
+// Shallow clone with override
+const updated = { ...config, timeout: 5000 };
+
+// Array spread
+const combined = [...listA, ...listB];
+```
+
+### 2.2 Immutable Array Operations (ES2023+)
+**Recommendation**: Use non-mutating array methods to avoid side effects.
+```javascript
+const sorted = items.toSorted((a, b) => a.name.localeCompare(b.name));
+const reversed = items.toReversed();
+const updated = items.with(2, 'newValue');
+```
+
+### 2.3 Object Grouping (ES2024+)
+**Recommendation**: Use `Object.groupBy()` instead of manual reduce-based grouping.
+```javascript
+const grouped = Object.groupBy(users, user => user.role);
+// { admin: [...], editor: [...], viewer: [...] }
+```
+
+### 2.4 Structured Cloning
+**Recommendation**: Use `structuredClone()` for deep copies instead of `JSON.parse(JSON.stringify())`.
+```javascript
+const deepCopy = structuredClone(originalObject);
+```
+
+### 2.5 Modern Iterables & Array Creation (ES6+)
+**Recommendation**: Use `Array.from()` to convert iterable objects (like NodeList or arguments) into true arrays, and utilize its built-in mapping capability.
+```javascript
+// Convert NodeList to Array and extract text content
+const elements = document.querySelectorAll('.item');
+const texts = Array.from(elements, el => el.textContent);
+
+// Create an array of a specific length filled with values
+const range = Array.from({ length: 5 }, (_, i) => i + 1); // [1, 2, 3, 4, 5]
+```
+
+### 2.6 String & Array Searching (ES6+)
+**Recommendation**: Replace verbose `indexOf()` checks with `includes()`, `startsWith()`, `endsWith()`, and replace `filter()[0]` with `find()`.
+```javascript
+// String checking
+const url = 'https://example.com';
+const isHttps = url.startsWith('https'); // Preferred over url.indexOf('https') === 0
+
+// Array searching
+const targetUser = users.find(u => u.id === 123); // Preferred over users.filter(...)[0]
+const hasAdmin = users.some(u => u.role === 'admin'); // Checking existence
+```
+
+---
+
+## 3. Async Patterns and Promise Composition
+
+### 3.1 async/await (ES2017+)
+**Recommendation**: Prefer `async`/`await` over `.then()` chains for readability and maintainability.
+```javascript
+async function loadUserProfile(id) {
+  try {
+    const user = await fetchUser(id);
+    const posts = await fetchPosts(user.id);
+    return { user, posts };
+  } catch (err) {
+    throw new Error('Failed to load profile', { cause: err });
+  }
+}
+```
+
+### 3.2 Promise Composition
+**Recommendation**: Choose the right Promise combinator for the use case.
+```javascript
+// All must succeed
+const [users, posts] = await Promise.all([fetchUsers(), fetchPosts()]);
+
+// All settle, handle individually
+const results = await Promise.allSettled([taskA(), taskB()]);
+
+// First to succeed
+const fastest = await Promise.any([mirrorA(), mirrorB()]);
+```
+
+### 3.3 Deferred Promise (ES2024+)
+**Recommendation**: Use `Promise.withResolvers()` for externally controlled promises.
+```javascript
+const { promise, resolve, reject } = Promise.withResolvers();
+setTimeout(() => resolve('done'), 1000);
+const result = await promise;
+```
+
+### 3.4 Async Generators and Iteration (ES2018+)
+**Recommendation**: Use async generators for streaming data processing.
+```javascript
+async function* fetchPages(url) {
+  let nextUrl = url;
+  while (nextUrl) {
+    const response = await fetch(nextUrl);
+    const data = await response.json();
+    yield data.items;
+    nextUrl = data.nextPage;
+  }
+}
+
+for await (const page of fetchPages('/api/users')) {
+  processItems(page);
+}
+```
+
+---
+
+## 4. Class Patterns and Encapsulation
+
+### 4.1 ES6 Classes
+**Recommendation**: Use `class` syntax with clear inheritance and `super` calls.
+```javascript
+class Animal {
+  constructor(name) {
+    this.name = name;
+  }
+
+  speak() {
+    return `${this.name} makes a sound.`;
+  }
+}
+
+class Dog extends Animal {
+  speak() {
+    return `${this.name} barks.`;
+  }
+}
+```
+
+### 4.2 Private Fields and Methods (ES2022+)
+**Recommendation**: Use `#` prefix for true encapsulation, replacing the underscore convention.
+```javascript
+class Counter {
+  #count = 0;
+
+  increment() { this.#count++; }
+  get value() { return this.#count; }
+}
+```
+
+### 4.3 Error Cause Chaining (ES2022+)
+**Recommendation**: Preserve error context with the `cause` option.
+```javascript
+try {
+  await initializeService();
+} catch (err) {
+  throw new Error('Service initialization failed', { cause: err });
+}
+```
+
+### 4.4 Explicit Resource Management (ES2025+)
+**Recommendation**: Use the `using` keyword for automatic and deterministic cleanup of resources (like file handles, database connections, or subscriptions).
+```javascript
+function processFile() {
+  using file = openFile('data.txt'); // Automatically closed when function exits
+  const data = file.read();
+  return data;
+}
+
+// Async disposal
+async function fetchAndProcess() {
+  await using connection = await db.connect();
+  return connection.query('SELECT * FROM users');
+}
+```
+
+---
+
+## 5. Set and Iterator Patterns (ES2025+)
+
+### 5.1 Set Operations
+**Recommendation**: Use native Set methods instead of manual implementations.
+```javascript
+const setA = new Set([1, 2, 3]);
+const setB = new Set([2, 3, 4]);
+
+const union = setA.union(setB);               // Set {1, 2, 3, 4}
+const intersection = setA.intersection(setB); // Set {2, 3}
+const difference = setA.difference(setB);     // Set {1}
+```
+
+### 5.2 Iterator Helpers
+**Recommendation**: Use lazy iterator methods for memory-efficient data processing.
+```javascript
+const firstFiveEven = Iterator.from(hugeArray)
+  .filter(n => n % 2 === 0)
+  .take(5)
+  .toArray();
+```
+
+---
+
+## 6. Security and Performance
+
+### 6.1 Input Sanitization
+**Recommendation**: Never use `eval()`, `innerHTML` with unsanitized input, or `new Function()` with user input.
+```javascript
+// Safe DOM manipulation
+element.textContent = userInput; // not element.innerHTML
+```
+
+### 6.2 AbortController for Resource Management
+**Recommendation**: Use `AbortController` to cancel fetch requests, timers, and event listeners.
+```javascript
+const controller = new AbortController();
+const response = await fetch(url, { signal: controller.signal });
+// Cancel if needed: controller.abort();
+```
+
+### 6.3 Avoiding Memory Leaks
+**Recommendation**: Use `WeakRef` and `WeakMap` for caches, and always clean up event listeners and intervals.
+```javascript
+// Use AbortController signal for automatic listener cleanup
+const controller = new AbortController();
+window.addEventListener('resize', handleResize, { signal: controller.signal });
+
+// Cleanup all listeners at once
+controller.abort();
+```