@moon791017/neo-skills 1.0.41 → 1.0.42

package/AGENTS.md

@@ -1,9 +1,6 @@
 # Neo Skills Extension (agents.md)
 
-**Neo Skills** 是一個專為 **Antigravity CLI (AGY)** 設計的擴充外掛，旨在將 Agent 轉化為**全方位專家代理 (Universal Expert Agent)**。它利用 Model Context Protocol (MCP) 提供特定領域的專業知識 (Skills)。目前配備了專業的 **DevOps** 模組（Azure Pipelines），其架構設計可託管任何領域的技能。
-
-## 核心約束
-- 所有 MCP 指令必須由使用者手動執行，不可自動化！
+**Neo Skills** 是一個專為 **Antigravity CLI (AGY)** 設計的擴充外掛，旨在將 Agent 轉化為**全方位專家代理 (Universal Expert Agent)**。它利用 Model Context Protocol (MCP) 提供特定領域的專業知識 (Skills)。目前配備了專業的 **DevOps**（Azure Pipelines）與 **Frontend/Backend** 多語系（.NET, Python, Swift, TypeScript/JavaScript, Rust, Vue）等領域的模組，其架構設計可託管任何領域的技能。
 
 ## 回應風格
 使用「繁體中文 (台灣)」
@@ -49,7 +46,7 @@ Do not commit secrets, sample credentials, or unsafe prompts. If you change secr
 *   **載入邏輯：**
     *   **全域技能**: 載入自 `~/.gemini/antigravity-cli/plugins/`。
     *   **專案專屬技能**: 載入自專案根目錄下的 `.agents/skills/`（遷移自舊有的 `.gemini/skills/`）。
-*   **範例：** `skills/neo-azure-pipelines/` 包含設計 CI/CD 管線的邏輯。
+*   **範例：** `skills/neo-azure-pipelines/` 包含設計 CI/CD 管線的邏輯，`skills/neo-typescript/` 包含 TypeScript 強型別與互通性最佳實踐。
 
 ### 3. 安全層 (`src/hooks/`)
 確保操作安全與數據隱私的機制。

package/README.md

@@ -34,11 +34,11 @@
 
 * **智能審查**：針對程式碼變更進行多面向 (正確性、安全性、效能、可讀性) 的深度審查。
 
-### 4. 程式碼解釋助手
+### 3. 程式碼解釋助手
 
 * **技術解析**：深入分析原始碼或專案結構，提供高階用途摘要、邏輯流程分解以及核心元件說明。
 
-### 5. .NET / C# 開發專家
+### 4. .NET / C# 開發專家
 
 * **C# 現代語法專家 (`skills/neo-csharp`)**：跨版本 C# 專家 (10-14+)，專注於現代化語法、強型別與高效能開發模式。
 * **.NET 核心路由 (`skills/neo-dotnet`)**：環境偵測與統一入口，自動將任務委派給最合適的子領域專家。
@@ -49,20 +49,27 @@
 * **.NET Tag Helper 專家 (`skills/neo-dotnet-tag-helper`)**：開發 ASP.NET Core 自定義 Tag Helper 的專家指引，專注於純 C# 實作與異步渲染最佳實踐。
 * **Interface 生成器**：針對 C# Class 自動生成符合規範的 Interface，並支援智慧檔案覆蓋功能。
 
-### 6. Python 開發與環境管理專家
+### 5. Python 開發與環境管理專家
 
 * **Python 3.10+ 專家 (`skills/neo-python`)**：專注於 Python 3.10 至 3.14 的現代語法特性、型別安全與非同步開發。
 * **環境管理專家 (`skills/neo-python-manager`)**：智慧偵測與管理 Python 專案環境，支援 uv, Poetry, venv/pip 並提供自動化安裝建議。
 
-### 7. Swift 開發專家
+### 6. Swift 開發專家
 
 * **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. JavaScript 開發專家
+### 7. JavaScript 開發專家
 
 * **JavaScript 現代語法專家 (`skills/neo-javascript`)**：跨版本 JavaScript 專家 (ES6 - ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
 
+### 8. TypeScript 開發專家
+
+* **TypeScript 現代語法與型別安全 (`skills/neo-typescript`)**：專注於極致的型別安全、高可維護性與進階元程式設計（Meta-programming）。
+  * **型別系統防線**：涵蓋進階條件型別 (Conditional Types)、映射型別 (Mapped Types) 與樣板字面值型別。
+  * **互通性與配置最佳化**：深入調校 `tsconfig.json` 編譯選項，並徹底解決複雜的 ESM/CJS 互通性陷阱與執行期崩潰問題。
+  * **泛型約束設計**：引導設計高靈活度的泛型與變量 (Variance) 處理。
+
 ### 9. Vue 開發專家
 
 * **Vue 3 現代開發專家 (`skills/neo-vue`)**：專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4。嚴格遵循官方 Style Guide 與最佳實踐，並提供反模式 (Anti-Patterns) 的避坑指引。
@@ -237,6 +244,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | **需求釐清與規格化** | `我想做一個電商網站` |
 | **全方位程式碼審查** | `幫我 code review 剛才的修改` |
 | **生成 C# Interface** | `幫我針對這個 class 產生介面` |
+| **TypeScript 型別設計與互通性** | `解決 tsconfig 還有 ESM/CJS 互通性的問題`、`幫我寫一個強型別的泛型工具` |
 | **技術解析與架構洞察** | `分析這個專案的架構` |
 | **AI 開發流程健檢** | `幫我檢查這個專案怎麼讓 AI 助手開發得更穩、更安全` |
 

package/package.json

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

package/skills/neo-typescript/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: neo-typescript
+description: >
+  Use this skill when asked to write, review, debug, or architect TypeScript code, configure tsconfig.json compiler options, resolve ESM/CJS interop issues, optimize generics, or apply advanced conditional, mapped, and template literal type operators. Trigger even if the user just asks generic TS compiler or type compatibility questions.
+license: MIT
+metadata:
+  author: ant-gravity-devs
+  version: "1.0.0"
+---
+
+# Neo TypeScript Expert Skill
+
+This skill guides the AI Agent to write code that adheres to the strictest type safety, high maintainability, and advanced meta-programming flexibility, while thoroughly preventing runtime issues such as ESM/CJS interoperability pitfalls.
+
+## 💡 Gotchas
+*   **Aliasing Writable Reference Bypasses Readonly**: In TypeScript, `readonly` only restricts the assignment to the property itself. The internal members of the referenced object/array remain mutable. Furthermore, a readonly object can be assigned to a writable alias, which completely bypasses compiler readonly checks.
+*   **Fatal Crash via Partial esModuleInterop**: Enabling `allowSyntheticDefaultImports` without `esModuleInterop` allows code to pass compile-time type checks but causes an immediate runtime crash (TypeError: default is not a function) due to the lack of `__importDefault` emit helpers in transpile output.
+*   **Double Default Trap for Library Creators**: Using `export default` in libraries forces Node.js ESM consumers to call `.default()` to access the module. The golden standard is to completely abandon `export default` and adopt `export =` or named exports instead.
+
+## 📋 Static Code & Type Safety Review SOP
+
+When asked to write, modify, refactor, or review TypeScript code, strictly execute the following workflow:
+
+### Step 1 — Project Environment Perception (Perceive)
+1. Inspect the project's `tsconfig.json` settings, focusing specifically on the configuration of `"strict": true`, `"strictNullChecks"`, and `"strictFunctionTypes"`.
+2. Identify the target module format and resolution mechanism (`"moduleResolution"`).
+
+### Step 2 — Core Type Routing (Reason)
+Based on the specific technical domain of the task, **progressively disclose** and load the corresponding reference files in the skill. Do not load all files at once to save context token space:
+*   **Basics, Narrowing, Classes, & Function Design** ➡️ Load [type-system-basics.md](references/type-system-basics.md)
+*   **Generic Constraints, Variance, & Advanced Types from Types** ➡️ Load [advanced-meta-types.md](references/advanced-meta-types.md)
+*   **Structural Compatibility, Decorators, & ESM/CJS Interop** ➡️ Load [compatibility-and-interop.md](references/compatibility-and-interop.md)
+
+### Step 3 — Precise Code Generation & Review (Act)
+1. Ensure all generated or modified code strictly adheres to the loaded reference guidelines (e.g., never declare optional callback parameters, ensure generic type parameters appear at least twice to establish correlation).
+2. For advanced type generation, recommend clear unit test assertions based on the evals configuration.
+
+---
+
+## 🛠️ Available Resources (Relative Paths)
+*   [Type System Basics Guide](references/type-system-basics.md)
+*   [Advanced Meta Types Guide](references/advanced-meta-types.md)
+*   [Compatibility and Interop Guide](references/compatibility-and-interop.md)

package/skills/neo-typescript/evals/eval_queries.json

@@ -0,0 +1,66 @@
+[
+  {
+    "query": "How do distributive conditional types work in TypeScript?",
+    "should_trigger": true
+  },
+  {
+    "query": "My Node project crashes with TypeError: default is not a function when loading a CJS library in ESM. How do I fix esModuleInterop?",
+    "should_trigger": true
+  },
+  {
+    "query": "Can you review my TypeScript code for type compatibility and bivariance issues?",
+    "should_trigger": true
+  },
+  {
+    "query": "Explain how to remove readonly modifiers from all keys in a mapped type.",
+    "should_trigger": true
+  },
+  {
+    "query": "I am configuring my tsconfig.json compilerOptions, what moduleResolution should I choose for Webpack/Vite?",
+    "should_trigger": true
+  },
+  {
+    "query": "How to design a type-safe event listener using template literal types for a watched object?",
+    "should_trigger": true
+  },
+  {
+    "query": "Why does my readonly property get mutated through an aliased writable reference?",
+    "should_trigger": true
+  },
+  {
+    "query": "How do I implement a nominal type simulation using private properties in TypeScript classes?",
+    "should_trigger": true
+  },
+  {
+    "query": "How to write a fibonacci function in JavaScript?",
+    "should_trigger": false
+  },
+  {
+    "query": "What is the weather today in Taipei?",
+    "should_trigger": false
+  },
+  {
+    "query": "Can you design a simple React component that renders a button with styled-components?",
+    "should_trigger": false
+  },
+  {
+    "query": "What is the difference between let and const in plain JS?",
+    "should_trigger": false
+  },
+  {
+    "query": "How to center a div horizontally and vertically using CSS flexbox?",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a python script that parses a CSV and sends it to database.",
+    "should_trigger": false
+  },
+  {
+    "query": "What is the difference between null and undefined in JavaScript?",
+    "should_trigger": false
+  },
+  {
+    "query": "Can you explain how ECMAScript decorators Stage 3 standard works in plain JS?",
+    "should_trigger": false
+  }
+]

package/skills/neo-typescript/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "neo-typescript",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "How do I write a Mapped Type that iterates over T, converts all its properties to readonly, and capitalizes key names prefixed with 'get'? For example, converting { name: string } to { readonly getName: () => string }.",
+      "expected_output": "Provide an advanced meta-programming solution using Mapped Types combined with Key Remapping `as` and `Capitalize`, including complete type code and validation examples.",
+      "assertions": [
+        "Output contains Mapped Type code using 'as' to rename property keys",
+        "Type expressions correctly use both 'readonly' and 'Capitalize' modifiers",
+        "Provide a concrete Example structure to validate the mapped type",
+        "The solution explicitly points out the gotcha of needing '& string' during key remapping"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "My project is an npm library that needs to support both CommonJS and ESM consumers. How do I safely export my main entry point to prevent users from encountering Double Default or default is not a function runtime crashes?",
+      "expected_output": "Explain the underlying cause of CommonJS and ESM dual-module loading conflicts, strongly recommend completely abandoning `export default`, and provide the golden solution of using `export =` and Named Exports.",
+      "assertions": [
+        "The solution explicitly mentions the magic emit helpers injected by esModuleInterop",
+        "Explicitly warn about the fatal runtime crash risk of enabling allowSyntheticDefaultImports alone",
+        "Provide clear code examples of TypeScript-specific 'export =' or Named Exports",
+        "Explain that library creators must avoid export default to prevent Double Default traps"
+      ]
+    }
+  ]
+}

package/skills/neo-typescript/references/advanced-meta-types.md

@@ -0,0 +1,124 @@
+# TypeScript Advanced Meta-Programming Reference
+
+This document serves as the advanced meta-programming and type manipulation guide for the `neo-typescript` skill, covering generic variance, keyof/typeof, indexed access, conditional types, mapped types, and template literal type operations.
+
+---
+
+## 1. Generic Variance (Variance Annotations)
+
+Type variance describes the relationship between `Box<Cat>` and `Box<Animal>` when `Cat` is a subtype of `Animal`.
+
+*   **Covariance (out modifier)**:
+    If `Box<T>` only acts as a **Producer** (e.g., only has `make(): T`), the relationship is co-directional (`Box<Cat>` is assignable to `Box<Animal>`). Declare with `out T`.
+*   **Contravariance (in modifier)**:
+    If `Box<T>` only acts as a **Consumer** (e.g., only has `consume(x: T): void`), the relationship is reversed (a consumer that handles all Animals can safely handle Cats). Declare with `in T`.
+*   **Invariance (in out modifier)**:
+    If a type acts as both producer and consumer, the relationship is bi-directionally locked.
+*   > [!IMPORTANT]
+     > TypeScript is a structural type system and automatically infers structural variance. **Manual `in`/`out` annotations are purely for compiler optimization and circular type debugging; they never alter basic structural comparison behavior**.
+
+---
+
+## 2. keyof & typeof Operators
+
+*   **`keyof` Index Signature Behavior**:
+    Returns a union of literal keys. Note that if an object contains an index signature, such as `Mapish = { [k: string]: boolean }`, `keyof Mapish` returns **`string | number`** (because JavaScript keys are coerced to strings).
+*   **`typeof` Physical Limitations**:
+    Captures the precise type of a value or property identifier. **Can only be used on identifiers (variable names, property paths)**. Never use `typeof` on function execution calls or dynamic expressions (e.g., `typeof func()` is invalid; use `typeof func` with `ReturnType` instead).
+
+---
+
+## 3. Indexed Access Types
+
+*   `T[K]` lookup allows precise type querying in the type space.
+*   **Element Capture**: Use `MyArray[number]` to extract the exact element object type from array or tuple literals.
+*   **Lookup Limitations**: The index `K` **must be a type**. Never pass a runtime variable value. If you need to refer to a variable name, extract its type using `typeof` first: `Person[typeof key]`.
+
+---
+
+## 4. Conditional Types & infer Inference
+
+Enables delayed type resolution and conditional branches via `T extends U ? X : Y`.
+
+### Declarative Inference via `infer`:
+Declare a new variable in the true branch of an `extends` comparison, allowing the compiler to automatically capture the type:
+```ts
+// Extract the resolved type of a Promise
+type Await<T> = T extends Promise<infer U> ? U : T;
+
+// Extract return type of a function
+type GetReturnType<T> = T extends (...args: any[]) => infer R ? R : any;
+```
+> [!WARNING]
+> When using `infer` to extract return types from overloaded functions, **TypeScript will infer from the very last overload signature (which is typically the most permissive, catch-all implementation)**.
+
+### Distributive Conditional Types:
+*   **Trigger Condition**: When a conditional type acts on a **bare type parameter** and a **union type** is passed as the argument, the conditional type automatically distributes across the union:
+    `ToArray<string | number>` ➡️ `string[] | number[]`.
+*   **Blocking Distribution (Non-distributive wrapping)**:
+    To preserve the union as a whole, **wrap both sides of the comparison in square brackets `[]`**, which disrupts the bare type parameter status:
+    ```ts
+    type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
+    // ToArrayNonDist<string | number> infers as (string | number)[]
+    ```
+
+---
+
+## 5. Mapped Types & Modifier Operations
+
+Mapped types construct new object types by iterating over a set of keys: `[P in keyof T]: T[P]`.
+
+### Mapping Modifiers:
+Add or remove `readonly` and `?` modifiers using `+` (optional) or `-` prefixes:
+```ts
+// Remove readonly, turning a readonly object into writable
+type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+// Remove optionality, forcing all properties to be implemented
+type Concrete<T> = {
+  [P in keyof T]-?: T[P];
+};
+```
+
+### Key Remapping via `as`:
+Use `as` to rename keys, exclude properties with `Exclude` and `never`, or iterate over arbitrary configuration unions:
+```ts
+// Rename keys: prefix with 'get' and capitalize the property name
+type Getters<T> = {
+  [P in keyof T as `get${Capitalize<string & P>}`]: () => T[P];
+};
+
+// Filter properties: exclude the 'kind' property
+type OmitKind<T> = {
+  [P in keyof T as Exclude<P, "kind">]: T[P];
+};
+```
+
+---
+
+## 6. Template Literal Types
+
+Template literal types allow string interpolation. If a union type is placed inside the interpolation slot, TypeScript automatically performs a **Cartesian product expansion**:
+```ts
+type Lang = "en" | "ja";
+type Event = "welcome" | "footer";
+type LocaleID = `${Lang}_${Event}_id`;
+```
+
+### Strong-Typed Event Listener (Watched Object Pattern):
+Combining template literals, generics, and indexed access enables a 100% type-safe event subscription source:
+```ts
+type PropEventSource<T> = {
+  on<K extends string & keyof T>
+    (eventName: `${K}Changed`, callback: (newValue: T[K]) => void): void;
+};
+
+// Used with makeWatchedObject to automatically infer newValue in callbacks
+declare function makeWatchedObject<T>(obj: T): T & PropEventSource<T>;
+```
+
+### Intrinsic String Manipulation Types:
+Built-in compiler helper types:
+*   `Uppercase<T>`, `Lowercase<T>`, `Capitalize<T>`, `Uncapitalize<T>`.

package/skills/neo-typescript/references/compatibility-and-interop.md

@@ -0,0 +1,82 @@
+# TypeScript Compatibility & Module Interoperability Reference
+
+This document serves as the guide for type compatibility rules and module loading interoperability for the `neo-typescript` skill, covering structural compatibility, function parameter variance, decorator standards, and ESM/CJS interop rules.
+
+---
+
+## 1. Structural Compatibility & Parameter Variance (Type Compatibility)
+
+TypeScript's type checking is based on a **structural type system**—compatibility is determined solely by the shape of the members.
+
+### Function Parameter Bivariance:
+*   *Type Theory*: Function parameter comparison should be **contravariant**. However, to support common JavaScript patterns (like event handlers and array covariance), TypeScript historically allows parameters to be bivariant by default.
+*   **`strictFunctionTypes` Safety Valve**:
+    Enabling `strictFunctionTypes: true` forces function parameters to undergo strict **contravariant** checks, eliminating runtime crashes where a parameter is too specialized.
+*   **The Single Exemption: Method Shorthand**:
+    > [!IMPORTANT]
+    > To maintain compatibility with common OOP patterns, **under `strictFunctionTypes: true`, shorthand method declarations (e.g., `method(arg: T): void`) remain bivariant**.
+    > Only property-based function signatures (e.g., `method: (arg: T) => void`) are subjected to strict contravariant checks!
+    > For maximum type safety in libraries, prefer property-based function signatures.
+
+---
+
+## 2. New Stage 3 Decorators vs. Experimental
+
+TypeScript 5.0 introduced native support for ECMAScript Stage 3 decorators, which differ fundamentally in architecture from the old legacy decorators:
+
+### Core Comparison:
+
+| Feature | Legacy Experimental Decorators (`experimentalDecorators: true`) | New Stage 3 Standard Decorators (TS 5.0+ Native) |
+| :--- | :--- | :--- |
+| **Parameters** | Receives `(target, propertyKey, descriptor)` | Receives `(value, context)` |
+| **Mutation Behavior** | Directly **mutates** the passed descriptor object | **No mutation**. Returns a **brand new replacement function or value** |
+| **Private Members** | **No support** for JavaScript private fields (`#field`) | **Full support** for private fields and private methods |
+| **Metadata Dependency** | Relies heavily on `reflect-metadata` reflection | Relies on the TC39 standard context without metadata coupling |
+
+*Standard Method Decorator Example*:
+```ts
+function loggedMethod<This, Args extends any[], Return>(
+  target: (this: This, ...args: Args) => Return,
+  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
+) {
+  return function (this: This, ...args: Args): Return {
+    console.log(`Calling method: ${String(context.name)}`);
+    return target.call(this, ...args);
+  };
+}
+```
+
+---
+
+## 3. ESM/CJS Interoperability & Dual Module Issues (Interop)
+
+The most notorious and difficult-to-debug pain point in modern Node.js and bundler toolchains.
+
+### 1. The Real Impact of `moduleResolution`:
+*   `node16` / `nodenext`:
+    Enforces strict Node.js native ESM rules: **relative ESM imports must include file extensions (e.g., `import "./add.js"` even if the source is `.ts`)**, and package.json exports conditional queries are strictly verified.
+*   `bundler`:
+    Designed for bundlers like Vite, Webpack, or esbuild. Allows omitting file extensions and resolving modules using bundler rules, bypassing strict Node.js runtime resolution limits.
+
+### 2. `esModuleInterop` & `allowSyntheticDefaultImports` Emit Helpers:
+Conflicts arise when an ES module attempts to `import` a pure CommonJS module (which lacks a `default` export and exposes a flat `module.exports` object).
+*   **The Magic of `esModuleInterop: true`**:
+    Enabling this flag causes `tsc` to inject `__importDefault` and `__importStar` emit helper wrappers in transpiled JS output.
+    `__importDefault` checks if the imported module has `__esModule: true`. If not, it **automatically generates a `{ default: exports }` wrapper object**, enabling `import x from "x"` to successfully grab the CJS module.
+*   **The Danger of Standalone `allowSyntheticDefaultImports`**:
+    This flag only tells the **type checker** to assume the target has a synthetic default export.
+    > [!CAUTION]
+    > Enabling `allowSyntheticDefaultImports` without `esModuleInterop` is **extremely dangerous**!
+    > The project will compile successfully, but it will **crash at runtime** with `TypeError: default is not a function` because the actual transpile output lacks the essential emit helpers. Always enable `esModuleInterop`.
+
+---
+
+## 4. Legacy Compatibility Features
+
+*   **Enum Tree-Shaking Issues**:
+    *   Standard Enums compile into immediate IIFE double-mapped objects. Bundlers cannot statically verify if the IIFE has side-effects, so **standard enums are never tree-shaken**.
+    *   **Golden Solution**: Unless you need reverse mapping (value to key), **always prefer `const enum`**, which erases the IIFE and inlines constant values directly.
+*   **Namespaces**:
+    Legacy internal modules predating ES Modules. They compile into global scope mutations and should be avoided in modern codebases in favor of standard `import`/`export`.
+*   **Mixins**:
+    Emulated using generic class factory patterns `function Scale<TBase extends Constructor>(Base: TBase)` to simulate multiple inheritance behavior.

package/skills/neo-typescript/references/type-system-basics.md

@@ -0,0 +1,75 @@
+# TypeScript Type System Basics Reference
+
+This document serves as the foundational guide for the `neo-typescript` skill, covering type system basics, everyday types, control flow analysis for narrowing, and fundamental function and class design specifications.
+
+---
+
+## 1. Static Compilation & Core Mechanics (The Basics)
+
+*   **Non-exception Failures**: TypeScript elevates runtime-silent JavaScript failures (such as typos, uncalled functions like `Math.random < 0.5`, or dead logic) to compile-time errors.
+*   **Type Erasure**: All type annotations, interfaces, and type aliases are **100% erased** during transpilation to JavaScript. The type system has absolutely zero footprint or effect on runtime behavior.
+*   **Downleveling**: `tsc` automatically transpiles modern ECMAScript features to older versions (e.g., ES5, ES6) based on the `"target"` configuration in `tsconfig.json`.
+*   **Strictness Flags**: Enabling `"strict": true` turns on core defensive flags, including `noImplicitAny` (disallows implicit any) and `strictNullChecks` (treats Null and Undefined as independent types).
+
+---
+
+## 2. Everyday Type Guidelines (Everyday Types)
+
+*   **Primitive Types**: Always use lowercase `string`, `number`, and `boolean`. **Never** use uppercase wrapper objects like `String`, `Number`, or `Boolean` as they represent wrapper objects and invite type compatibility bugs.
+*   **Contextual Typing**: Anonymous functions placed in positions where TypeScript can infer their usage automatically type their arguments without manual annotations (e.g., `names.forEach(s => ...)` infers `s` as string).
+*   **Type Alias vs. Interface Decision**:
+    *   `interface`: Supports **declaration merging**. It features better compiler caching and is the preferred choice for defining object shapes.
+    *   `type`: Cannot be merged once declared, but is ideal for union types, tuples, and mapped types.
+*   **Literal Inference & `as const`**: Object literal properties are widened to their base types by default. To lock them as readonly and exact literal types, suffix the object with `as const`:
+    ```ts
+    const req = { url: "https://example.com", method: "GET" } as const;
+    // req.method is strictly typed as "GET"
+    ```
+
+---
+
+## 3. Control Flow Analysis & Narrowing
+
+Type narrowing is the control flow analysis where the compiler traces program paths to deduce the most precise types at specific locations.
+
+### Core Type Guards:
+*   `typeof` guard: Beware of the historical JS quirk where `typeof null === "object"`.
+*   Truthiness narrowing: Use `&&` or `!!` to filter out `null` or `undefined`.
+*   Equality narrowing: Perform `===` or `!==` comparisons. *Tip*: `x != null` (loose inequality) filters out both `null` and `undefined` in one step.
+*   `in` guard: Checks if a property exists on an object. Note that optional properties will still appear in both branches after narrowing.
+*   `instanceof` guard: Checks instance constructors.
+
+### User-Defined Type Predicates:
+To encapsulate narrowing logic in helper functions, declare the return type as `parameterName is Type`:
+```ts
+function isFish(pet: Fish | Bird): pet is Fish {
+  return (pet as Fish).swim !== undefined;
+}
+```
+
+### Discriminated Unions & Exhaustiveness Checking:
+Use a shared literal tag property (e.g., `kind`) across union members and perform exhaustiveness checking in `switch` blocks using `never` to ensure compiler warnings are raised when new members are added to the union:
+```ts
+const _exhaustiveCheck: never = shape;
+```
+
+---
+
+## 4. High-Quality Function Design Rules (Functions)
+
+*   **Call & Construct Signatures**: Parameter names are **mandatory** in function type expressions. Writing `(string) => void` creates a parameter named `string` with type `any`.
+*   **Three Rules for Excellent Generics**:
+    1.  **Push Type Parameters Down**: Use the type parameter directly in the signature to preserve the exactness of the return type.
+    2.  **Ensure Type Parameters Appear at Least Twice**: If a parameter appears only once, it does not establish a correlation between values and should be replaced with a regular type annotation.
+    3.  **Minimize Type Parameters**: Avoid introducing redundant type parameters that add no distinct constraints.
+*   **Optional Parameter Callback Ban**:
+    **Never** declare callback parameters as optional (e.g., `callback: (arg: T, index?: number) => void`). This forces callback implementors to write redundant `undefined` checks. Keep them required; JavaScript automatically discards extra arguments anyway.
+*   **Relaxed void Assignability**: A callback function whose contextual type expects a `void` return is **allowed to return any other value** (which is safely ignored). This enables callbacks like `src.forEach(el => dst.push(el))` to compile successfully.
+
+---
+
+## 5. Classes & Nominal Simulation Basics (Classes)
+
+*   **Parameter Properties**: Suffixing constructor arguments with access modifiers (like `public readonly x`) automatically declares them as instance fields and performs initialization, eliminating boilerplate code.
+*   **this Parameter Annotation**: Declaring the first parameter as `this: ClassName` statically binds the call context, preventing runtime bugs when methods are assigned to variables and lose their `this` context.
+*   **Nominal Simulation**: Structural typing only compares instance member shapes. However, if a class contains `private` or `protected` members, assignment compatibility strictly requires those members to originate from **"the exact same class declaration inheritance tree"**. Classes with identical shapes but different roots are rejected, simulating nominal safety.