Merge release v1.10.0 into main

.agents/AGENTS.md

@@ -0,0 +1,52 @@
+# Agent Guidelines for `xulbux`
+
+When working on this repository, any AI agent or automated assistant must adhere strictly to the following rules to maintain the codebase's integrity, performance, and correctness.
+
+## 1. Strict Typing (MyPyC Compatibility)
+
+This library is compiled using **MyPyC**. Therefore, **EVERYTHING** must be meticulously and strictly type-hinted. Do not ever use `Any` unless it is fundamentally impossible to type-hint otherwise. All changes must be fully statically analyzable to compile correctly.
+
+## 2. Validation & Testing
+
+After making any changes, you must validate them by running the full suite of formatters, linters, type checkers, and tests. Fix all problems until they are completely resolved.
+
+**On Windows:**
+
+CD into the project root, then run:
+
+```powershell
+ruff format .; if ($?) { ruff check . --fix }; if ($?) { pyright --pythonpath "$(py -c 'import sys; print(sys.executable)')" . }; if ($?) { mypy . }; if ($?) { pytest --basetemp .pytest_tmp }
+```
+
+**On Unix:**
+
+CD into the project root, activate the `.venv` virtual environment, then run:
+
+```bash
+ruff format . && ruff check . --fix && pyright . && mypy . && pytest
+```
+
+## 3. Ask, Don't Assume
+
+If you run into anything you are not sure about (ambiguous requirements, complex architectural decisions, edge cases), **ask first**. Do not make assumptions about the desired behavior.
+
+## 4. Performance & Idioms
+
+-   **Performance First:** This library prioritizes modernity and speed. Avoid eager imports for heavy operations. Utilize lazy loading via PEP 562 (`__getattr__` in `__init__.py`) and lazy compiled regular expressions (`LazyRegex`).
+-   **MyPyC Optimization (CRITICAL):** Because the library is compiled to C via MyPyC, standard Python performance advice doesn't always apply. You must strictly follow these rules:
+    -   **Generators:** NEVER pass generator expressions to functions like `any()`, `all()`, `sum()`, `max()`, `min()`, `join()`, `tuple()`, etc.
+        -   For full iterations (`join`, `sum`, `tuple`, `max`), ALWAYS wrap them in brackets `[]` to force an optimized list comprehension.
+        -   For short-circuiting functions (`any`, `all`, `next`), write explicit unrolled native `for`-loops with `break` or `return`.
+    -   **Membership Testing:** Always use `set`s for `in` checks instead of lists or tuples (e.g., `if x in {"a", "b"}:` instead of `if x in ("a", "b"):`).
+    -   **String Concatenation:** Avoid using `+=` for string concatenation inside loops; prefer `.join()` with list comprehensions.
+    -   **Map & Filter:** Do not use the `map()` or `filter()` builtins. List comprehensions are strictly faster and type-safer in MyPyC.
+-   **DRY Principle (Don't Repeat Yourself):** Always strive to prevent redundant code and duplicate logic. Abstract repeated patterns into reusable helper functions or classes.
+-   **Internal Module Aliasing:** When importing internal modules, use the `_module` suffix pattern (e.g., `from . import data as _data_module`). This prevents naming collisions and variable shadowing, and keeps the public API completely clean of internal clutter.
+-   **Docstrings & Syntax:** Maintain the current comment/docstring styling (which makes use of formatting elements like `<br>`). Always use backticks (`` ` ``) instead of quotes when mentioning literals, expressions, types, or variables within comments/docstrings.
+
+## 5. Code Structure & Readability
+
+-   **Logical Placement:** Do not mindlessly append new code (variables, constants, functions, classes, etc.) to the end of a file. Always insert new code in a logical location that groups related functionality together.
+-   **Spacing & Formatting:** Keep the code "spacy" and readable, matching the current formatting conventions of the repository.
+-   **Naming Conventions:** Single-letter variables (e.g., `x`, `c`, `r`) are strictly banned. The ONLY exceptions are `i` (and rarely `j`) for loop indices, and `n` for mathematical counts/parameters. Always use fully descriptive variable names (e.g., `ch` or `channel`, `red`, `modifier`).
+-   **Organization:** When introducing large data structures (like hardcoded iterables or dictionaries), keep them strictly organized and structured. Default to sorting elements alphabetically unless a specific logical order is required.

.agents/skills/build-xulbux/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: build-xulbux
+description: Compiles and builds the xulbux MyPyC library, and generates PYI stubs.
+---
+
+# build-xulbux
+
+Use this skill to verify that the `xulbux` library fully compiles via MyPyC, generates the correct `.pyi` stub files, and packages/installs successfully.
+
+## 1. Verify Stub Generation
+
+Run the following command to only generate the `.pyi` stub files to the project root without clearing them. This allows you to inspect them and verify they are generated correctly.
+
+**On Windows:**
+
+CD into the project root, then run:
+
+```powershell
+py setup.py --gen-stubs
+```
+
+**On Unix:**
+
+CD into the project root, activate the `.venv` virtual environment, then run:
+
+```bash
+python setup.py --gen-stubs
+```
+
+## 2. Full Compile and Install Test
+
+Run the following command to force pip to completely compile the MyPyC extensions and reinstall the package from the local source directory without caching. This verifies the full build pipeline.
+
+**On Windows:**
+
+CD into the project root, then run:
+
+```powershell
+py -m pip install . --no-deps --no-cache-dir --force-reinstall -vv
+```
+
+**On Unix:**
+
+CD into the project root, activate the `.venv` virtual environment, then run:
+
+```bash
+pip install . --no-deps --no-cache-dir --force-reinstall -vv
+```
+
+If any of these commands fail, inspect the verbose (`-vv`) output to debug MyPyC compilation errors or stub generation issues.

.github/workflows/build-and-publish.yml → .github/workflows/build-and-publish.yaml

@@ -1,12 +1,13 @@
-# THIS WORKFLOW WILL BUILD WHEELS FOR ALL MAJOR PLATFORMS AND UPLOAD THEM TO PYPI
+# This workflow will build wheels for all major platforms and upload them to PyPI.
 
-# TO BUILD AND INSTALL LOCALLY FOR TESTING, RUN THE FOLLOWING COMMAND:
+# To build and install locally for testing, run the following command:
 # py -m pip install "/path/to/python-lib-xulbux" --no-deps --no-cache-dir --force-reinstall -vv
 
-# TO CREATE A NEW RELEASE, TAG A COMMIT WITH THE FOLLOWING FORMAT:
+# To create a new release, tag a commit with the following format:
 # git tag v1.X.Y
 # git push origin v1.X.Y
-# IF THE TAG v1.X.Y ALREADY EXISTS, RUN THE FOLLOWING COMMANDS FIRST:
+
+# If the tag `v1.X.Y` already exists, run the following commands first:
 # git tag -d v1.X.Y
 # git push origin :refs/tags/v1.X.Y
 
@@ -17,8 +18,8 @@ permissions:
 on:
   push:
     tags:
-      - "v1.[0-9]+.[0-9]+"
-  workflow_dispatch: # ALLOW MANUAL TRIGGER
+      - 'v1.[0-9]+.[0-9]+'
+  workflow_dispatch: # Allow manual trigger.
 
 jobs:
   build_wheels:
@@ -29,13 +30,13 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.3.0
+        uses: pypa/cibuildwheel@v4.2
         env:
-          CIBW_BUILD: cp310-* cp311-* cp312-* cp313-* cp314-*
-          CIBW_SKIP: "*-musllinux_*"
+          CIBW_BUILD: cp312-* cp313-* cp314-*
+          CIBW_SKIP: '*-musllinux_*'
           CIBW_BUILD_FRONTEND: pip
           CIBW_ENVIRONMENT: XULBUX_USE_MYPYC=1
 
@@ -49,7 +50,7 @@ jobs:
           echo "[SUCCESS] Built $(ls ./wheelhouse/*.whl | wc -l) wheels."
         shell: bash
 
-      - uses: actions/upload-artifact@v6
+      - uses: actions/upload-artifact@v7
         with:
           name: wheels-${{ matrix.os }}
           path: ./wheelhouse/*.whl
@@ -58,12 +59,12 @@ jobs:
     name: Build source distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Build sdist
         run: pipx run build --sdist
 
-      - uses: actions/upload-artifact@v6
+      - uses: actions/upload-artifact@v7
         with:
           name: sdist
           path: dist/*.tar.gz
@@ -76,9 +77,9 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v7
+      - uses: actions/download-artifact@v8
         with:
-          pattern: "*"
+          pattern: '*'
           merge-multiple: true
           path: dist
 

.github/workflows/test-and-lint.yml → .github/workflows/ci.yaml

@@ -1,35 +1,38 @@
-# THIS WORKFLOW WILL INSTALL PYTHON DEPENDENCIES, RUN TESTS AND LINT WITH A VARIETY OF PYTHON VERSIONS
-# FOR MORE INFORMATION SEE: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+# This workflow will install Python dependencies, run tests and lint with all supported Python versions.
+# See: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
 
-name: Test & Lint
+name: CI
 permissions:
   contents: read
 
 on:
   push:
-    branches: ["main"]
+    branches: [main]
   pull_request:
-    branches: ["main"]
+    branches: [main]
 
 jobs:
   build:
     runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ['3.12', '3.13', '3.14']
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Cache pip packages
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/pyproject.toml') }}
@@ -40,17 +43,17 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install .[dev]
-          pip install flake8 flake8-pyproject pyright pytest
+          pip install ruff pyright pytest
 
-      - name: Lint with flake8
+      - name: Validate code with Ruff
         run: |
-          python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          python -m flake8 . --exit-zero --max-complexity=12 --statistics
+          python -m ruff check .
+          python -m ruff format --check .
 
-      - name: Type check with pyright
+      - name: Type check with PyRight
         run: |
-          pyright
+          python -m pyright
 
-      - name: Test with pytest
+      - name: Test with PyTest
         run: |
           python -m pytest --verbose

.github/workflows/deploy-docs.yml

@@ -0,0 +1,66 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches: ['main']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install xulbux dependencies
+        run: |
+          pip install -e .
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 11
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 26
+          cache: 'pnpm'
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Install docs dependencies
+        working-directory: ./docs
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: python docs/build.py
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          # Upload the dist folder generated by VitePress:
+          path: './docs/.build/.vitepress/dist'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -1,15 +1,23 @@
-# COMPILED FILES & CACHES
+# Compiled files & caches
 __pycache__/
 __pypackages__/
 .mypy_cache/
 .pytest_cache/
+.pytest_tmp/
+.ruff_cache/
 *.py[cdio]
 *$py.class
 
-# BUILD ARTIFACTS
+# Build artifacts
 *.egg-info/
 build/
 dist/
 
-# TESTING
+# Virtual environments
 .venv/
+
+# Documentation
+docs/.build/
+docs/node_modules/
+docs/src/.vitepress/cache/
+docs/src/.vitepress/dist/