From 2321b54d20ffe13bb6efe8949c9ccade0bbc766d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 18 Aug 2025 23:25:12 +0000
Subject: [PATCH 1/3] Initial plan


From 9f440705bcf0c5ad64f86c1fb6a5c869e5c43ec0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 18 Aug 2025 23:39:26 +0000
Subject: [PATCH 2/3] Add comprehensive GitHub Copilot instructions for ReactPy
 development

Co-authored-by: Archmonger <16909269+Archmonger@users.noreply.github.com>
---
 .github/copilot-instructions.md | 268 ++++++++++++++++++++++++++++++++
 1 file changed, 268 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..71fdc6cb6
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,268 @@
+# ReactPy Development Instructions
+
+ReactPy is a Python library for building user interfaces without JavaScript. It creates React-like components that render to web pages using a Python-to-JavaScript bridge.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap, Build, and Test the Repository
+
+**Prerequisites:**
+- Install Python 3.9+ from https://www.python.org/downloads/
+- Install Hatch: `pip install hatch`
+- Install Bun JavaScript runtime: `curl -fsSL https://bun.sh/install | bash && source ~/.bashrc`
+- Install Git
+
+**Initial Setup:**
+```bash
+git clone https://github.com/reactive-python/reactpy.git
+cd reactpy
+```
+
+**Install Dependencies for Development:**
+```bash
+# Install core ReactPy dependencies
+pip install fastjsonschema requests lxml anyio typing-extensions
+
+# Install ASGI dependencies for server functionality
+pip install orjson asgiref asgi-tools servestatic uvicorn fastapi
+
+# Optional: Install additional servers
+pip install flask sanic tornado
+```
+
+**Build JavaScript Packages:**
+- `hatch run javascript:build` -- takes 15 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
+- This builds three packages: event-to-object, @reactpy/client, and @reactpy/app
+
+**Build Python Package:**
+- `hatch build --clean` -- takes 10 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
+
+**Run Python Tests:**
+- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite.
+- `hatch test -k test_name` -- run specific tests
+- `hatch test tests/test_config.py` -- run specific test files
+- Note: Some tests require Playwright browser automation and may fail in headless environments
+
+**Run Python Linting and Formatting:**
+- `hatch fmt` -- Run all linters and formatters (~1 second)
+- `hatch fmt --check` -- Check formatting without making changes (~1 second)
+- `hatch fmt --linter` -- Run only linters
+- `hatch fmt --formatter` -- Run only formatters
+- `hatch run python:type_check` -- Run Python type checker (~10 seconds)
+
+**Run JavaScript Tasks:**
+- `hatch run javascript:check` -- Lint and type-check JavaScript (10 seconds). NEVER CANCEL. Set timeout to 30+ minutes.
+- `hatch run javascript:fix` -- Format JavaScript code
+- `hatch run javascript:test` -- Run JavaScript tests (note: may fail in headless environments due to DOM dependencies)
+
+## Validation
+
+Always manually validate any new code changes through these steps:
+
+**Basic Functionality Test:**
+```python
+# Add src to path if not installed
+import sys, os
+sys.path.insert(0, os.path.join("/path/to/reactpy", "src"))
+
+# Test that imports and basic components work
+import reactpy
+from reactpy import component, html, use_state
+
+@component
+def test_component():
+    return html.div([
+        html.h1("Test"),
+        html.p("ReactPy is working")
+    ])
+
+# Verify component renders
+vdom = test_component()
+print(f"Component rendered: {type(vdom)}")
+```
+
+**Server Functionality Test:**
+```python
+# Test ASGI server creation (most common deployment)
+from reactpy import component, html
+from reactpy.executors.asgi.standalone import ReactPy
+import uvicorn
+
+@component
+def hello_world():
+    return html.div([
+        html.h1("Hello, ReactPy!"),
+        html.p("Server is working!")
+    ])
+
+# Create ASGI app (don't run to avoid hanging)
+app = ReactPy(hello_world)
+print("✓ ASGI server created successfully")
+
+# To actually run: uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+**Hooks and State Test:**
+```python
+from reactpy import component, html, use_state
+
+@component
+def counter_component(initial=0):
+    count, set_count = use_state(initial)
+    
+    return html.div([
+        html.h1(f"Count: {count}"),
+        html.button({
+            "onClick": lambda event: set_count(count + 1)
+        }, "Increment")
+    ])
+
+# Test component with hooks
+counter = counter_component(5)
+print(f"✓ Hook-based component: {type(counter)}")
+```
+
+**Always run these validation steps before completing work:**
+- `hatch fmt --check` -- Ensure code is properly formatted
+- `hatch run python:type_check` -- Ensure no type errors  
+- `hatch run javascript:check` -- Ensure JavaScript passes linting
+- Test basic component creation and rendering as shown above
+- Test server creation if working on server-related features
+
+**Integration Testing:**
+- ReactPy can be deployed with FastAPI, Flask, Sanic, Tornado via ASGI
+- For browser testing, Playwright is used but requires additional setup
+- Test component VDOM rendering directly when browser testing isn't available
+- Validate that JavaScript builds are included in Python package after changes
+
+## Repository Structure
+
+### Key Directories:
+- `src/reactpy/` -- Main Python package source code
+- `src/js/` -- JavaScript packages that get bundled with Python
+- `src/build_scripts/` -- Build automation scripts
+- `tests/` -- Python test suite
+- `docs/` -- Documentation source (currently transitioning to MkDocs)
+
+### Important Files:
+- `pyproject.toml` -- Python project configuration and build scripts
+- `src/js/package.json` -- JavaScript development dependencies
+- `src/js/packages/` -- Individual JavaScript packages
+- `tests/conftest.py` -- Test configuration and fixtures
+
+### Key Components:
+- `src/reactpy/core/` -- Core ReactPy functionality (components, hooks, VDOM)
+- `src/reactpy/web/` -- Web module management and exports
+- `src/reactpy/widgets/` -- Built-in UI components
+- `src/reactpy/pyscript/` -- PyScript integration
+- `src/reactpy/_html.py` -- HTML element factory functions
+
+## Common Tasks
+
+### Build Time Expectations:
+- JavaScript build: 15 seconds
+- Python package build: 10 seconds  
+- Python linting: 1 second
+- JavaScript linting: 10 seconds
+- Type checking: 10 seconds
+- Full CI pipeline: 5-10 minutes
+
+### Development Workflow:
+1. Make code changes
+2. Run `hatch fmt` to format code (~1 second)
+3. Run `hatch run python:type_check` for type checking (~10 seconds)
+4. Run `hatch run javascript:check` if JavaScript was modified (~10 seconds)
+5. Run relevant tests with `hatch test`
+6. Validate component functionality manually using validation tests above
+
+### Running ReactPy Applications:
+
+**ASGI Standalone (Recommended):**
+```python
+from reactpy import component, html
+from reactpy.executors.asgi.standalone import ReactPy
+import uvicorn
+
+@component
+def my_app():
+    return html.h1("Hello World")
+
+app = ReactPy(my_app)
+uvicorn.run(app, host="127.0.0.1", port=8000)
+```
+
+**With FastAPI:**
+```python
+from fastapi import FastAPI
+from reactpy import component, html
+from reactpy.executors.asgi.middleware import ReactPyMiddleware
+
+@component 
+def my_component():
+    return html.h1("Hello from ReactPy!")
+
+app = FastAPI()
+app.add_middleware(ReactPyMiddleware, component=my_component)
+```
+
+### Creating Components:
+```python
+from reactpy import component, html, use_state
+
+@component
+def my_component(initial_value=0):
+    count, set_count = use_state(initial_value)
+    
+    return html.div([
+        html.h1(f"Count: {count}"),
+        html.button({
+            "onClick": lambda event: set_count(count + 1)
+        }, "Increment")
+    ])
+```
+
+### Working with JavaScript:
+- JavaScript packages are in `src/js/packages/`
+- Three main packages: event-to-object, @reactpy/client, @reactpy/app
+- Built JavaScript gets bundled into `src/reactpy/static/`
+- Always rebuild JavaScript after changes: `hatch run javascript:build`
+
+## Troubleshooting
+
+### Build Issues:
+- If JavaScript build fails, try: `hatch run "src/build_scripts/clean_js_dir.py"` then rebuild
+- If Python build fails, ensure all dependencies in pyproject.toml are available
+- Network timeouts during pip install are common in CI environments
+- Missing dependencies error: Install ASGI dependencies with `pip install orjson asgiref asgi-tools servestatic`
+
+### Test Issues:
+- Playwright tests may fail in headless environments -- this is expected
+- Tests requiring browser DOM should be marked appropriately  
+- Use `hatch test -k "not playwright"` to skip browser-dependent tests
+- JavaScript tests may fail with "window is not defined" in Node.js environment -- this is expected
+
+### Import Issues:
+- ReactPy must be installed or src/ must be in Python path
+- Main imports: `from reactpy import component, html, use_state`
+- Server imports: `from reactpy.executors.asgi.standalone import ReactPy`
+- Web functionality: `from reactpy.web import export, module_from_url`
+
+### Server Issues:
+- Missing ASGI dependencies: Install with `pip install orjson asgiref asgi-tools servestatic uvicorn`
+- For FastAPI integration: `pip install fastapi uvicorn`
+- For Flask integration: `pip install flask` (requires additional backend package)
+- For development servers, use ReactPy ASGI standalone for simplest setup
+
+## CI/CD Information
+
+The repository uses GitHub Actions with these key jobs:
+- `test-python-coverage` -- Python test coverage
+- `lint-python` -- Python linting and type checking
+- `test-python` -- Cross-platform Python testing
+- `lint-javascript` -- JavaScript linting and type checking
+
+The CI workflow is defined in `.github/workflows/check.yml` and uses the reusable workflow in `.github/workflows/.hatch-run.yml`.
+
+Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
\ No newline at end of file

From 8ea58684bbfb1de3869a6c1b5bfbd10b4e83247a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 00:29:33 +0000
Subject: [PATCH 3/3] Enhance GitHub Copilot instructions with django-dbbackup
 best practices

Co-authored-by: Archmonger <16909269+Archmonger@users.noreply.github.com>
---
 .github/copilot-instructions.md | 156 ++++++++++++++++++++++++++------
 1 file changed, 128 insertions(+), 28 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 71fdc6cb6..171fc9853 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -4,6 +4,10 @@ ReactPy is a Python library for building user interfaces without JavaScript. It
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+**IMPORTANT**: This package uses modern Python tooling with Hatch for all development workflows. Always use Hatch commands for development tasks.
+
+**BUG INVESTIGATION**: When investigating whether a bug was already resolved in a previous version, always prioritize searching through `docs/source/about/changelog.rst` first before using Git history. Only search through Git history when no relevant changelog entries are found.
+
 ## Working Effectively
 
 ### Bootstrap, Build, and Test the Repository
@@ -40,7 +44,8 @@ pip install flask sanic tornado
 - `hatch build --clean` -- takes 10 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
 
 **Run Python Tests:**
-- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite.
+- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite. **All tests must always pass - failures are never expected or allowed.**
+- `hatch test --cover` -- run tests with coverage reporting (used in CI)
 - `hatch test -k test_name` -- run specific tests
 - `hatch test tests/test_config.py` -- run specific test files
 - Note: Some tests require Playwright browser automation and may fail in headless environments
@@ -57,6 +62,11 @@ pip install flask sanic tornado
 - `hatch run javascript:fix` -- Format JavaScript code
 - `hatch run javascript:test` -- Run JavaScript tests (note: may fail in headless environments due to DOM dependencies)
 
+**Interactive Development Shell:**
+- `hatch shell` -- Enter an interactive shell environment with all dependencies installed
+- `hatch shell default` -- Enter the default development environment
+- Use the shell for interactive debugging and development tasks
+
 ## Validation
 
 Always manually validate any new code changes through these steps:
@@ -125,11 +135,12 @@ print(f"✓ Hook-based component: {type(counter)}")
 ```
 
 **Always run these validation steps before completing work:**
-- `hatch fmt --check` -- Ensure code is properly formatted
-- `hatch run python:type_check` -- Ensure no type errors  
-- `hatch run javascript:check` -- Ensure JavaScript passes linting
+- `hatch fmt --check` -- Ensure code is properly formatted (never expected to fail)
+- `hatch run python:type_check` -- Ensure no type errors (never expected to fail)
+- `hatch run javascript:check` -- Ensure JavaScript passes linting (never expected to fail)
 - Test basic component creation and rendering as shown above
 - Test server creation if working on server-related features
+- Run relevant tests with `hatch test` -- **All tests must always pass - failures are never expected or allowed**
 
 **Integration Testing:**
 - ReactPy can be deployed with FastAPI, Flask, Sanic, Tornado via ASGI
@@ -137,27 +148,31 @@ print(f"✓ Hook-based component: {type(counter)}")
 - Test component VDOM rendering directly when browser testing isn't available
 - Validate that JavaScript builds are included in Python package after changes
 
-## Repository Structure
+## Repository Structure and Navigation
 
 ### Key Directories:
 - `src/reactpy/` -- Main Python package source code
+  - `core/` -- Core ReactPy functionality (components, hooks, VDOM)
+  - `web/` -- Web module management and exports
+  - `executors/` -- Server integration modules (ASGI, etc.)
+  - `testing/` -- Testing utilities and fixtures
+  - `pyscript/` -- PyScript integration
+  - `static/` -- Bundled JavaScript files
+  - `_html.py` -- HTML element factory functions
 - `src/js/` -- JavaScript packages that get bundled with Python
+  - `packages/event-to-object/` -- Event serialization package
+  - `packages/@reactpy/client/` -- Client-side React integration
+  - `packages/@reactpy/app/` -- Application framework
 - `src/build_scripts/` -- Build automation scripts
-- `tests/` -- Python test suite
-- `docs/` -- Documentation source (currently transitioning to MkDocs)
+- `tests/` -- Python test suite with comprehensive coverage
+- `docs/` -- Documentation source (MkDocs-based, transitioning setup)
 
 ### Important Files:
-- `pyproject.toml` -- Python project configuration and build scripts
+- `pyproject.toml` -- Python project configuration and Hatch environments
 - `src/js/package.json` -- JavaScript development dependencies
-- `src/js/packages/` -- Individual JavaScript packages
 - `tests/conftest.py` -- Test configuration and fixtures
-
-### Key Components:
-- `src/reactpy/core/` -- Core ReactPy functionality (components, hooks, VDOM)
-- `src/reactpy/web/` -- Web module management and exports
-- `src/reactpy/widgets/` -- Built-in UI components
-- `src/reactpy/pyscript/` -- PyScript integration
-- `src/reactpy/_html.py` -- HTML element factory functions
+- `docs/source/about/changelog.rst` -- Version history and changes
+- `.github/workflows/check.yml` -- CI/CD pipeline configuration
 
 ## Common Tasks
 
@@ -169,14 +184,6 @@ print(f"✓ Hook-based component: {type(counter)}")
 - Type checking: 10 seconds
 - Full CI pipeline: 5-10 minutes
 
-### Development Workflow:
-1. Make code changes
-2. Run `hatch fmt` to format code (~1 second)
-3. Run `hatch run python:type_check` for type checking (~10 seconds)
-4. Run `hatch run javascript:check` if JavaScript was modified (~10 seconds)
-5. Run relevant tests with `hatch test`
-6. Validate component functionality manually using validation tests above
-
 ### Running ReactPy Applications:
 
 **ASGI Standalone (Recommended):**
@@ -229,6 +236,60 @@ def my_component(initial_value=0):
 - Built JavaScript gets bundled into `src/reactpy/static/`
 - Always rebuild JavaScript after changes: `hatch run javascript:build`
 
+## Common Hatch Commands
+
+The following are key commands for daily development:
+
+### Development Commands
+```bash
+hatch test                          # Run all tests (**All tests must always pass**)
+hatch test --cover                  # Run tests with coverage (used in CI)
+hatch test -k test_name             # Run specific tests
+hatch fmt                           # Format code with all formatters
+hatch fmt --check                   # Check formatting without changes
+hatch run python:type_check         # Run Python type checker
+hatch run javascript:build          # Build JavaScript packages (15 seconds)
+hatch run javascript:check          # Lint JavaScript code (10 seconds)
+hatch run javascript:fix            # Format JavaScript code
+hatch build --clean                 # Build Python package (10 seconds)
+```
+
+### Environment Management
+```bash
+hatch env show                      # Show all environments
+hatch shell                         # Enter default shell
+hatch shell default                 # Enter development shell
+```
+
+### Build Timing Expectations
+- **NEVER CANCEL**: All commands complete within 60 seconds in normal operation
+- **JavaScript build**: 15 seconds (hatch run javascript:build)
+- **Python package build**: 10 seconds (hatch build --clean)
+- **Python linting**: 1 second (hatch fmt)
+- **JavaScript linting**: 10 seconds (hatch run javascript:check)
+- **Type checking**: 10 seconds (hatch run python:type_check)
+- **Unit tests**: 10-30 seconds (varies by test selection)
+- **Full CI pipeline**: 5-10 minutes
+
+## Development Workflow
+
+Follow this step-by-step process for effective development:
+
+1. **Bootstrap environment**: Ensure you have Python 3.9+ and run `pip install hatch`
+2. **Make your changes** to the codebase
+3. **Run formatting**: `hatch fmt` to format code (~1 second)
+4. **Run type checking**: `hatch run python:type_check` for type checking (~10 seconds)
+5. **Run JavaScript linting** (if JavaScript was modified): `hatch run javascript:check` (~10 seconds)
+6. **Run relevant tests**: `hatch test` with specific test selection if needed. **All tests must always pass - failures are never expected or allowed.**
+7. **Validate component functionality** manually using validation tests above
+8. **Build JavaScript** (if modified): `hatch run javascript:build` (~15 seconds)
+9. **Update documentation** when making changes to Python source code (required)
+10. **Add changelog entry** for all significant changes to `docs/source/about/changelog.rst`
+
+**IMPORTANT**: Documentation must be updated whenever changes are made to Python source code. This is enforced as part of the development workflow.
+
+**IMPORTANT**: Significant changes must always include a changelog entry in `docs/source/about/changelog.rst` under the appropriate version section.
+
 ## Troubleshooting
 
 ### Build Issues:
@@ -255,14 +316,53 @@ def my_component(initial_value=0):
 - For Flask integration: `pip install flask` (requires additional backend package)
 - For development servers, use ReactPy ASGI standalone for simplest setup
 
+## Package Dependencies
+
+Modern dependency management via pyproject.toml:
+
+**Core Runtime Dependencies:**
+- `fastjsonschema >=2.14.5` -- JSON schema validation
+- `requests >=2` -- HTTP client library  
+- `lxml >=4` -- XML/HTML processing
+- `anyio >=3` -- Async I/O abstraction
+- `typing-extensions >=3.10` -- Type hints backport
+
+**Optional Dependencies (install via extras):**
+- `asgi` -- ASGI server support: `orjson`, `asgiref`, `asgi-tools`, `servestatic`, `pip`
+- `jinja` -- Template integration: `jinja2-simple-tags`, `jinja2 >=3`
+- `uvicorn` -- ASGI server: `uvicorn[standard]`
+- `testing` -- Browser automation: `playwright`
+- `all` -- All optional dependencies combined
+
+**Development Dependencies (managed by Hatch):**
+- **JavaScript tooling**: Bun runtime for building packages
+- **Python tooling**: Hatch environments handle all dev dependencies automatically
+
 ## CI/CD Information
 
 The repository uses GitHub Actions with these key jobs:
-- `test-python-coverage` -- Python test coverage
-- `lint-python` -- Python linting and type checking
-- `test-python` -- Cross-platform Python testing
+- `test-python-coverage` -- Python test coverage with `hatch test --cover`
+- `lint-python` -- Python linting and type checking via `hatch fmt --check` and `hatch run python:type_check`
+- `test-python` -- Cross-platform Python testing across Python 3.10-3.13 and Ubuntu/macOS/Windows
 - `lint-javascript` -- JavaScript linting and type checking
 
 The CI workflow is defined in `.github/workflows/check.yml` and uses the reusable workflow in `.github/workflows/.hatch-run.yml`.
 
-Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
\ No newline at end of file
+**Build Matrix:**
+- **Python versions**: 3.10, 3.11, 3.12, 3.13
+- **Operating systems**: Ubuntu, macOS, Windows
+- **Test execution**: Hatch-managed environments ensure consistency across platforms
+
+Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
+
+## Important Notes
+
+- **This is a Python-to-JavaScript bridge library**, not a traditional web framework - it enables React-like components in Python
+- **Component rendering uses VDOM** - components return virtual DOM objects that get serialized to JavaScript
+- **All builds and tests run quickly** - if something takes more than 60 seconds, investigate the issue
+- **Hatch environments provide full isolation** - no need to manage virtual environments manually  
+- **JavaScript packages are bundled into Python** - the build process combines JS and Python into a single distribution
+- **Browser automation tests may fail in headless environments** - this is expected behavior for Playwright tests
+- **Documentation updates are required** when making changes to Python source code
+- **Always update this file** when making changes to the development workflow, build process, or repository structure
+- **All tests must always pass** - failures are never expected or allowed in a healthy development environment
\ No newline at end of file