django-hilo 0.1.0__tar.gz

django_hilo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

django_hilo-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} / Django ${{ matrix.django }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+        django: ['4.2', '5.0', '5.1', '6.0']
+        exclude:
+          - python: '3.10'
+            django: '6.0'
+          - python: '3.11'
+            django: '6.0'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]" 2>/dev/null || pip install -e .
+          pip install "Django~=${{ matrix.django }}.0"
+          pip install pytest pytest-django
+      - name: Run tests
+        run: pytest tests/ -v
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install ruff
+        run: pip install ruff
+      - name: Check format
+        run: ruff format --check src/ tests/
+      - name: Check lint
+        run: ruff check src/ tests/

django_hilo-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.tox/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.env
+.venv/

django_hilo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ERPlora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_hilo-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: django-hilo
+Version: 0.1.0
+Summary: SPA framework for Django — one script tag turns Django templates into a full SPA
+Project-URL: Homepage, https://github.com/ERPlora/django-hilo
+Project-URL: Repository, https://github.com/ERPlora/django-hilo
+Project-URL: Issues, https://github.com/ERPlora/django-hilo/issues
+Project-URL: Changelog, https://github.com/ERPlora/django-hilo/blob/main/CHANGELOG.md
+Author-email: Ioan Beilic <ioanbeilic@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-hilo
+
+SPA framework for Django. One `<script>` tag turns Django templates into a full SPA.
+
+Works with [Hilo.js](https://github.com/ERPlora/hilo) — the client-side library that handles navigation, DOM morphing, signals, and real-time communication.
+
+## Installation
+
+```bash
+pip install django-hilo
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'hilo',
+]
+
+MIDDLEWARE = [
+    ...
+    'hilo.middleware.HiloMiddleware',
+]
+```
+
+## Quick Start
+
+### 1. Base template
+
+```html
+{% load hilo %}
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{% block title %}My App{% endblock %}</title>
+</head>
+<body>
+    <nav data-permanent>
+        <a href="/">Home</a>
+        <a href="/products/">Products</a>
+    </nav>
+
+    {% hilo_content %}
+        {% block content %}{% endblock %}
+    {% endhilo_content %}
+
+    {% hilo_scripts %}
+</body>
+</html>
+```
+
+### 2. Views with `@fragment`
+
+```python
+from hilo.decorators import fragment
+
+@fragment('products/list.html')
+def product_list(request):
+    return {'products': Product.objects.all()}
+```
+
+That's it. Links are intercepted automatically. No `hx-get`, no `hx-target`, no attributes needed.
+
+## Features
+
+### Middleware
+
+`HiloMiddleware` handles:
+- **Redirect conversion** — Django redirects become `X-Hilo-Redirect` headers (no full page reload)
+- **Asset versioning** — `X-Hilo-Version` header for cache busting
+- **Request detection** — `request.is_hilo` boolean available in views
+
+### `@fragment` decorator
+
+Renders the appropriate template based on request type:
+- **Hilo request** → renders only the partial template (fragment)
+- **Normal request** → renders the full page (with base layout)
+
+```python
+@fragment('products/list.html', 'products/page.html')
+def product_list(request):
+    return {'products': Product.objects.all()}
+```
+
+### Response helpers
+
+```python
+from hilo.response import hilo_redirect, hilo_trigger, hilo_title, hilo_url
+
+# Redirect via Hilo (no full reload)
+return hilo_redirect('/products/')
+
+# Trigger client-side events
+response = render(request, 'template.html', context)
+return hilo_trigger(response, {'showMessage': {'message': 'Saved!', 'type': 'success'}})
+
+# Set page title
+return hilo_title(response, 'Products')
+```
+
+### Streaming actions (like Turbo Streams)
+
+```python
+from hilo.response import HiloStreamResponse
+
+def add_message(request):
+    response = HiloStreamResponse()
+    response.append('#messages', '<div class="message">New message!</div>')
+    response.update('#counter', '<span>42</span>')
+    response.remove('#typing-indicator')
+    return response
+```
+
+### Template tags
+
+```html
+{% load hilo %}
+
+{% hilo_scripts %}                              {# Inject hilo.min.js + config #}
+{% hilo_content %}...{% endhilo_content %}       {# Main content area #}
+{% hilo_permanent %}...{% endhilo_permanent %}   {# Never morphed #}
+
+{# Streaming actions in templates #}
+{% hilo_stream "append" "#messages" %}
+  <div class="message">{{ message.text }}</div>
+{% endhilo_stream %}
+```
+
+## Configuration
+
+```python
+# settings.py
+HILO = {
+    'VERSION': 'auto',           # Asset version ('auto', fixed string, or '')
+    'JS_PATH': 'js/hilo.min.js', # Path to hilo.min.js in STATIC_URL
+    'PREFIX': 'h',               # Behavior prefix (data-h="toggle")
+    'DEBUG': False,               # Enable debug logging
+    'NAV': True,                  # Enable SPA navigation (True, False, or dict)
+}
+```
+
+## License
+
+MIT

django_hilo-0.1.0/README.md

@@ -0,0 +1,144 @@
+# django-hilo
+
+SPA framework for Django. One `<script>` tag turns Django templates into a full SPA.
+
+Works with [Hilo.js](https://github.com/ERPlora/hilo) — the client-side library that handles navigation, DOM morphing, signals, and real-time communication.
+
+## Installation
+
+```bash
+pip install django-hilo
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'hilo',
+]
+
+MIDDLEWARE = [
+    ...
+    'hilo.middleware.HiloMiddleware',
+]
+```
+
+## Quick Start
+
+### 1. Base template
+
+```html
+{% load hilo %}
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{% block title %}My App{% endblock %}</title>
+</head>
+<body>
+    <nav data-permanent>
+        <a href="/">Home</a>
+        <a href="/products/">Products</a>
+    </nav>
+
+    {% hilo_content %}
+        {% block content %}{% endblock %}
+    {% endhilo_content %}
+
+    {% hilo_scripts %}
+</body>
+</html>
+```
+
+### 2. Views with `@fragment`
+
+```python
+from hilo.decorators import fragment
+
+@fragment('products/list.html')
+def product_list(request):
+    return {'products': Product.objects.all()}
+```
+
+That's it. Links are intercepted automatically. No `hx-get`, no `hx-target`, no attributes needed.
+
+## Features
+
+### Middleware
+
+`HiloMiddleware` handles:
+- **Redirect conversion** — Django redirects become `X-Hilo-Redirect` headers (no full page reload)
+- **Asset versioning** — `X-Hilo-Version` header for cache busting
+- **Request detection** — `request.is_hilo` boolean available in views
+
+### `@fragment` decorator
+
+Renders the appropriate template based on request type:
+- **Hilo request** → renders only the partial template (fragment)
+- **Normal request** → renders the full page (with base layout)
+
+```python
+@fragment('products/list.html', 'products/page.html')
+def product_list(request):
+    return {'products': Product.objects.all()}
+```
+
+### Response helpers
+
+```python
+from hilo.response import hilo_redirect, hilo_trigger, hilo_title, hilo_url
+
+# Redirect via Hilo (no full reload)
+return hilo_redirect('/products/')
+
+# Trigger client-side events
+response = render(request, 'template.html', context)
+return hilo_trigger(response, {'showMessage': {'message': 'Saved!', 'type': 'success'}})
+
+# Set page title
+return hilo_title(response, 'Products')
+```
+
+### Streaming actions (like Turbo Streams)
+
+```python
+from hilo.response import HiloStreamResponse
+
+def add_message(request):
+    response = HiloStreamResponse()
+    response.append('#messages', '<div class="message">New message!</div>')
+    response.update('#counter', '<span>42</span>')
+    response.remove('#typing-indicator')
+    return response
+```
+
+### Template tags
+
+```html
+{% load hilo %}
+
+{% hilo_scripts %}                              {# Inject hilo.min.js + config #}
+{% hilo_content %}...{% endhilo_content %}       {# Main content area #}
+{% hilo_permanent %}...{% endhilo_permanent %}   {# Never morphed #}
+
+{# Streaming actions in templates #}
+{% hilo_stream "append" "#messages" %}
+  <div class="message">{{ message.text }}</div>
+{% endhilo_stream %}
+```
+
+## Configuration
+
+```python
+# settings.py
+HILO = {
+    'VERSION': 'auto',           # Asset version ('auto', fixed string, or '')
+    'JS_PATH': 'js/hilo.min.js', # Path to hilo.min.js in STATIC_URL
+    'PREFIX': 'h',               # Behavior prefix (data-h="toggle")
+    'DEBUG': False,               # Enable debug logging
+    'NAV': True,                  # Enable SPA navigation (True, False, or dict)
+}
+```
+
+## License
+
+MIT

django_hilo-0.1.0/conftest.py

@@ -0,0 +1,5 @@
+import sys
+import os
+
+# Add project root to Python path so 'tests' package is importable
+sys.path.insert(0, os.path.dirname(__file__))

django_hilo-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "django-hilo"
+version = "0.1.0"
+description = "SPA framework for Django — one script tag turns Django templates into a full SPA"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Ioan Beilic", email = "ioanbeilic@gmail.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 6.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["Django>=4.2"]
+
+[project.urls]
+Homepage = "https://github.com/ERPlora/django-hilo"
+Repository = "https://github.com/ERPlora/django-hilo"
+Issues = "https://github.com/ERPlora/django-hilo/issues"
+Changelog = "https://github.com/ERPlora/django-hilo/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hilo"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]

django_hilo-0.1.0/src/hilo/__init__.py

@@ -0,0 +1,10 @@
+"""
+django-hilo — SPA framework for Django
+
+One script tag turns Django templates into a full SPA.
+Navigation, DOM morphing, signals, real-time communication.
+"""
+
+__version__ = "0.1.0"
+
+default_app_config = "hilo.apps.HiloConfig"

django_hilo-0.1.0/src/hilo/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class HiloConfig(AppConfig):
+    name = "hilo"
+    verbose_name = "Hilo SPA Framework"
+    default_auto_field = "django.db.models.BigAutoField"

django_hilo-0.1.0/src/hilo/decorators.py

@@ -0,0 +1,107 @@
+"""
+Hilo view decorators for Django.
+
+@fragment — The core decorator that makes Django views SPA-ready.
+Renders a full page for normal requests, or just the fragment for Hilo requests.
+"""
+
+import functools
+from typing import Any, Callable
+
+from django.http import HttpRequest, HttpResponse
+from django.shortcuts import render
+from django.template.response import TemplateResponse
+
+
+def fragment(
+    partial_template: str,
+    full_template: str | None = None,
+    *,
+    title: str | None = None,
+    status: int = 200,
+):
+    """
+    View decorator that renders a partial template for Hilo (AJAX) requests
+    and a full template for normal browser requests.
+
+    Usage:
+        @fragment('products/list.html')
+        def product_list(request):
+            return {'products': Product.objects.all()}
+
+        @fragment('products/list.html', 'products/page.html')
+        def product_list(request):
+            return {'products': Product.objects.all()}
+
+    How it works:
+    - Hilo request (X-Hilo: true) → renders partial_template only
+    - HTMX request (HX-Request: true) → renders partial_template only (backward compat)
+    - Normal request → renders full_template (wraps partial in base layout)
+    - If full_template is None, tries to find it automatically:
+      - Looks for the partial name without 'partials/' prefix
+      - Falls back to rendering the partial directly
+
+    The view function should return:
+    - A dict (context) → rendered with the appropriate template
+    - An HttpResponse → returned as-is (for redirects, errors, etc.)
+    """
+
+    def decorator(view_func: Callable) -> Callable:
+        @functools.wraps(view_func)
+        def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+            result = view_func(request, *args, **kwargs)
+
+            # If the view returns an HttpResponse, pass it through
+            if isinstance(result, (HttpResponse, TemplateResponse)):
+                # Add Hilo headers if it's a Hilo request
+                if is_hilo_request(request):
+                    _add_hilo_headers(result, title=title)
+                return result
+
+            # Result should be a dict (context)
+            context = result if isinstance(result, dict) else {}
+
+            if is_hilo_request(request):
+                # Hilo/HTMX request → render partial only
+                response = render(request, partial_template, context, status=status)
+                _add_hilo_headers(response, title=title)
+                return response
+            else:
+                # Normal request → render full page
+                template = full_template or _infer_full_template(partial_template)
+                # Pass partial template name so the full template can include it
+                context.setdefault("partial_template", partial_template)
+                return render(request, template, context, status=status)
+
+        return wrapper
+
+    return decorator
+
+
+def is_hilo_request(request: HttpRequest) -> bool:
+    """Check if this is a Hilo SPA navigation request."""
+    return (
+        request.headers.get("X-Hilo") == "true"
+        or request.headers.get("HX-Request") == "true"  # backward compat with HTMX
+        or request.headers.get("X-Requested-With") == "XMLHttpRequest"
+    )
+
+
+def _add_hilo_headers(response: HttpResponse, title: str | None = None) -> None:
+    """Add Hilo response headers."""
+    if title:
+        response["X-Hilo-Title"] = title
+
+
+def _infer_full_template(partial_template: str) -> str:
+    """
+    Try to infer the full template path from the partial template.
+    'app/partials/list.html' → 'app/list.html'
+    'app/list_partial.html' → 'app/list.html'
+    """
+    if "/partials/" in partial_template:
+        return partial_template.replace("/partials/", "/")
+    if "_partial." in partial_template:
+        return partial_template.replace("_partial.", ".")
+    # Fallback: use the partial as the full template
+    return partial_template

django_hilo-0.1.0/src/hilo/middleware/__init__.py

@@ -0,0 +1,3 @@
+from .hilo import HiloMiddleware
+
+__all__ = ["HiloMiddleware"]

django_hilo-0.1.0/src/hilo/middleware/hilo.py

@@ -0,0 +1,137 @@
+"""
+Hilo Middleware for Django.
+
+Detects Hilo SPA requests and adds appropriate response headers.
+Handles redirects, page titles, asset versioning, and trigger events.
+"""
+
+import hashlib
+import json
+from typing import Any, Callable
+
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse
+
+
+class HiloMiddleware:
+    """
+    Middleware that integrates Hilo.js SPA navigation with Django.
+
+    Features:
+    - Detects Hilo requests (X-Hilo: true header)
+    - Converts Django redirects to X-Hilo-Redirect headers (prevents full page reload)
+    - Adds X-Hilo-Version header for asset cache busting
+    - Passes X-Hilo-Title from response context
+    - Supports X-Hilo-Trigger for server-initiated events
+
+    Usage in settings.py:
+        MIDDLEWARE = [
+            ...
+            'hilo.middleware.HiloMiddleware',
+        ]
+
+        # Optional settings
+        HILO = {
+            'VERSION': 'auto',  # 'auto' generates from static files, or set a fixed string
+        }
+    """
+
+    def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
+        self.get_response = get_response
+        self._version: str | None = None
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        # Mark request as Hilo
+        request.is_hilo = self._is_hilo(request)  # type: ignore[attr-defined]
+
+        response = self.get_response(request)
+
+        if not request.is_hilo:  # type: ignore[attr-defined]
+            return response
+
+        # Convert redirects to Hilo redirect headers
+        if response.status_code in (301, 302, 303, 307, 308):
+            redirect_url = response.get("Location", "")
+            if redirect_url:
+                # Return a 200 with X-Hilo-Redirect instead
+                new_response = HttpResponse(status=200)
+                new_response["X-Hilo-Redirect"] = redirect_url
+                # Copy any trigger headers
+                for header in ("X-Hilo-Trigger", "X-Hilo-Title"):
+                    if header in response:
+                        new_response[header] = response[header]
+                return new_response
+
+        # Add version header for cache busting
+        version = self._get_version()
+        if version:
+            response["X-Hilo-Version"] = version
+
+        return response
+
+    def _is_hilo(self, request: HttpRequest) -> bool:
+        """Check if request comes from Hilo.js navigation."""
+        return request.headers.get("X-Hilo") == "true"
+
+    def _get_version(self) -> str:
+        """Get the asset version string."""
+        if self._version:
+            return self._version
+
+        hilo_settings = getattr(settings, "HILO", {})
+        version = hilo_settings.get("VERSION", "")
+
+        if version == "auto":
+            # Generate version from Django's STATIC_URL or a hash
+            static_url = getattr(settings, "STATIC_URL", "/static/")
+            self._version = hashlib.md5(static_url.encode()).hexdigest()[:8]
+        elif version:
+            self._version = str(version)
+        else:
+            self._version = ""
+
+        return self._version
+
+
+# --- Helper functions for views ---
+
+
+def hilo_redirect(url: str) -> HttpResponse:
+    """
+    Return a response that tells Hilo to navigate to the given URL.
+    Use this instead of Django's redirect() when you want Hilo
+    to handle the navigation without a full page reload.
+    """
+    response = HttpResponse(status=200)
+    response["X-Hilo-Redirect"] = url
+    return response
+
+
+def hilo_trigger(response: HttpResponse, events: dict[str, Any] | str) -> HttpResponse:
+    """
+    Add trigger events to a Hilo response.
+    These events will be dispatched as CustomEvents on the client.
+
+    Usage:
+        response = render(request, 'template.html', context)
+        return hilo_trigger(response, {'showMessage': {'message': 'Saved!', 'type': 'success'}})
+        # or simple event:
+        return hilo_trigger(response, 'refreshList')
+    """
+    if isinstance(events, str):
+        response["X-Hilo-Trigger"] = events
+    else:
+        response["X-Hilo-Trigger"] = json.dumps(events)
+    return response
+
+
+def hilo_title(response: HttpResponse, title: str) -> HttpResponse:
+    """Set the page title for Hilo navigation."""
+    response["X-Hilo-Title"] = title
+    return response
+
+
+def hilo_url(response: HttpResponse, url: str) -> HttpResponse:
+    """Override the URL that Hilo pushes to browser history."""
+    response["X-Hilo-URL"] = url
+    return response

django_hilo-0.1.0/src/hilo/response.py

@@ -0,0 +1,92 @@
+"""
+Hilo response helpers.
+
+Convenience functions for building Hilo-aware responses from Django views.
+"""
+
+from django.http import HttpResponse, JsonResponse
+
+from .middleware.hilo import hilo_redirect, hilo_title, hilo_trigger, hilo_url
+
+__all__ = [
+    "hilo_redirect",
+    "hilo_trigger",
+    "hilo_title",
+    "hilo_url",
+    "HiloStreamResponse",
+]
+
+
+class HiloStreamResponse(HttpResponse):
+    """
+    Response that sends streaming DOM actions to Hilo.js.
+
+    Usage:
+        response = HiloStreamResponse()
+        response.append('#messages', '<div>New message</div>')
+        response.update('#counter', '<span>42</span>')
+        response.remove('#old-item')
+        return response
+    """
+
+    def __init__(self, **kwargs):
+        kwargs.setdefault("content_type", "text/html")
+        super().__init__(**kwargs)
+        self._actions: list[str] = []
+
+    def append(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="append" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def prepend(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="prepend" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def replace(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="replace" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def update(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="update" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def remove(self, target: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="remove" data-target="{target}"></div>'
+        )
+        return self
+
+    def before(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="before" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def after(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="after" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    def morph(self, target: str, html: str) -> "HiloStreamResponse":
+        self._actions.append(
+            f'<div data-stream="morph" data-target="{target}">{html}</div>'
+        )
+        return self
+
+    @property
+    def content(self) -> bytes:
+        return "\n".join(self._actions).encode()
+
+    @content.setter
+    def content(self, value):
+        # Allow Django internals to set content
+        pass

django_hilo-0.1.0/src/hilo/templatetags/hilo.py

@@ -0,0 +1,207 @@
+"""
+Hilo template tags for Django.
+
+{% load hilo %}
+{% hilo_scripts %}                    — Inject hilo.min.js + auto-config
+{% hilo_content %}...{% endhilo_content %} — Mark the main content area
+{% hilo_permanent %}...{% endhilo_permanent %} — Mark permanent elements (not morphed)
+{% hilo_stream action target_id %}...{% endhilo_stream %} — Stream action element
+"""
+
+from django import template
+from django.conf import settings
+from django.utils.safestring import mark_safe
+
+register = template.Library()
+
+
+@register.simple_tag(takes_context=True)
+def hilo_scripts(context):
+    """
+    Inject Hilo.js script tag and auto-configuration.
+
+    Usage:
+        {% load hilo %}
+        {% hilo_scripts %}
+
+    Renders:
+        <script src="/static/js/hilo.min.js" defer nonce="..."></script>
+        <script nonce="...">
+        Hilo.config({ csrf: '...', prefix: 'h' });
+        </script>
+    """
+    request = context.get("request")
+    nonce = ""
+
+    # Get CSP nonce if available
+    csp_nonce = context.get("csp_nonce", "")
+    if not csp_nonce and request:
+        csp_nonce = getattr(request, "csp_nonce", "")
+    if csp_nonce:
+        nonce = f' nonce="{csp_nonce}"'
+
+    # Get CSRF token
+    csrf_token = context.get("csrf_token", "")
+
+    # Get Hilo settings
+    hilo_settings = getattr(settings, "HILO", {})
+    static_url = getattr(settings, "STATIC_URL", "/static/")
+    js_path = hilo_settings.get("JS_PATH", "js/hilo.min.js")
+    prefix = hilo_settings.get("PREFIX", "h")
+    debug = hilo_settings.get("DEBUG", getattr(settings, "DEBUG", False))
+    nav_config = hilo_settings.get("NAV", True)
+
+    # Build config options
+    config_parts = [f"csrf: '{csrf_token}'"]
+    config_parts.append(f"prefix: '{prefix}'")
+
+    if isinstance(nav_config, dict):
+        nav_items = []
+        for key, val in nav_config.items():
+            if isinstance(val, bool):
+                nav_items.append(f"{key}: {'true' if val else 'false'}")
+            elif isinstance(val, str):
+                nav_items.append(f"{key}: '{val}'")
+            elif isinstance(val, (int, float)):
+                nav_items.append(f"{key}: {val}")
+        config_parts.append(f"nav: {{ {', '.join(nav_items)} }}")
+    elif nav_config is False:
+        config_parts.append("nav: false")
+
+    if debug:
+        config_parts.append("debug: true")
+
+    config_str = ", ".join(config_parts)
+
+    html = (
+        f'<script src="{static_url}{js_path}" defer{nonce}></script>\n'
+        f"<script{nonce}>\n"
+        f"document.addEventListener('DOMContentLoaded', function() {{\n"
+        f"  Hilo.config({{ {config_str} }});\n"
+        f"}});\n"
+        f"</script>"
+    )
+
+    return mark_safe(html)
+
+
+@register.tag("hilo_content")
+def do_hilo_content(parser, token):
+    """
+    Mark the main content area that Hilo will swap during navigation.
+
+    Usage:
+        {% hilo_content %}
+          {% block content %}{% endblock %}
+        {% endhilo_content %}
+
+    Renders:
+        <div data-hilo-content>
+          ...content...
+        </div>
+    """
+    nodelist = parser.parse(("endhilo_content",))
+    parser.delete_first_token()
+
+    # Parse optional id argument
+    bits = token.split_contents()
+    element_id = bits[1] if len(bits) > 1 else "main-content-area"
+
+    return HiloContentNode(nodelist, element_id)
+
+
+class HiloContentNode(template.Node):
+    def __init__(self, nodelist, element_id):
+        self.nodelist = nodelist
+        self.element_id = element_id
+
+    def render(self, context):
+        content = self.nodelist.render(context)
+        return f'<div id="{self.element_id}" data-hilo-content>{content}</div>'
+
+
+@register.tag("hilo_permanent")
+def do_hilo_permanent(parser, token):
+    """
+    Mark an element as permanent — it won't be touched during DOM morphing.
+
+    Usage:
+        {% hilo_permanent %}
+          <nav id="sidebar">...</nav>
+        {% endhilo_permanent %}
+
+    Renders:
+        <div data-permanent>
+          <nav id="sidebar">...</nav>
+        </div>
+    """
+    nodelist = parser.parse(("endhilo_permanent",))
+    parser.delete_first_token()
+    return HiloPermanentNode(nodelist)
+
+
+class HiloPermanentNode(template.Node):
+    def __init__(self, nodelist):
+        self.nodelist = nodelist
+
+    def render(self, context):
+        content = self.nodelist.render(context)
+        return f'<div data-permanent>{content}</div>'
+
+
+@register.tag("hilo_stream")
+def do_hilo_stream(parser, token):
+    """
+    Create a streaming action element (like Turbo Streams).
+
+    Usage:
+        {% hilo_stream "append" "#messages" %}
+          <div class="message">New message!</div>
+        {% endhilo_stream %}
+
+    Renders:
+        <div data-stream="append" data-target="#messages">
+          <div class="message">New message!</div>
+        </div>
+    """
+    bits = token.split_contents()
+    if len(bits) < 3:
+        raise template.TemplateSyntaxError(
+            f"'{bits[0]}' tag requires at least 2 arguments: action and target"
+        )
+
+    action = bits[1].strip("'\"")
+    target = bits[2].strip("'\"")
+
+    nodelist = parser.parse(("endhilo_stream",))
+    parser.delete_first_token()
+    return HiloStreamNode(nodelist, action, target)
+
+
+class HiloStreamNode(template.Node):
+    def __init__(self, nodelist, action, target):
+        self.nodelist = nodelist
+        self.action = action
+        self.target = target
+
+    def render(self, context):
+        content = self.nodelist.render(context)
+        return f'<div data-stream="{self.action}" data-target="{self.target}">{content}</div>'
+
+
+@register.simple_tag
+def hilo_oob(element_id):
+    """
+    Helper to create an OOB (out-of-band) wrapper.
+    The content inside will be swapped into the element with the given ID.
+
+    Usage:
+        {% hilo_oob "notification-count" %}
+    """
+    return mark_safe(f'<div data-oob id="{element_id}">')
+
+
+@register.simple_tag
+def endhilo_oob():
+    """Close an OOB wrapper."""
+    return mark_safe("</div>")

django_hilo-0.1.0/tests/settings.py

@@ -0,0 +1,30 @@
+SECRET_KEY = "test-secret-key-for-hilo-django"
+DEBUG = True
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "hilo",
+]
+MIDDLEWARE = [
+    "hilo.middleware.HiloMiddleware",
+]
+ROOT_URLCONF = "tests.urls"
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.request",
+            ],
+        },
+    },
+]
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": ":memory:",
+    },
+}
+STATIC_URL = "/static/"

django_hilo-0.1.0/tests/test_decorators.py

@@ -0,0 +1,52 @@
+"""Tests for Hilo decorators."""
+
+from django.http import HttpResponse
+from django.test import RequestFactory, TestCase
+
+from hilo.decorators import fragment, is_hilo_request
+
+
+class IsHiloRequestTest(TestCase):
+    """Test is_hilo_request detection."""
+
+    def setUp(self):
+        self.factory = RequestFactory()
+
+    def test_normal_request(self):
+        request = self.factory.get("/")
+        assert not is_hilo_request(request)
+
+    def test_hilo_header(self):
+        request = self.factory.get("/", headers={"X-Hilo": "true"})
+        assert is_hilo_request(request)
+
+    def test_htmx_header_backward_compat(self):
+        request = self.factory.get("/", headers={"HX-Request": "true"})
+        assert is_hilo_request(request)
+
+    def test_xhr_header(self):
+        request = self.factory.get(
+            "/", headers={"X-Requested-With": "XMLHttpRequest"}
+        )
+        assert is_hilo_request(request)
+
+
+class FragmentDecoratorTest(TestCase):
+    """Test @fragment decorator."""
+
+    def test_fragment_returns_httpresponse_passthrough(self):
+        @fragment("partial.html")
+        def view(request):
+            return HttpResponse("direct response")
+
+        request = RequestFactory().get("/")
+        response = view(request)
+        assert response.status_code == 200
+        assert response.content == b"direct response"
+
+    def test_infer_full_template(self):
+        from hilo.decorators import _infer_full_template
+
+        assert _infer_full_template("app/partials/list.html") == "app/list.html"
+        assert _infer_full_template("app/list_partial.html") == "app/list.html"
+        assert _infer_full_template("app/list.html") == "app/list.html"

django_hilo-0.1.0/tests/test_middleware.py

@@ -0,0 +1,120 @@
+"""Tests for Hilo middleware."""
+
+import pytest
+from django.test import RequestFactory, TestCase, override_settings
+
+
+class HiloMiddlewareTest(TestCase):
+    """Test HiloMiddleware behavior."""
+
+    def test_normal_request_passthrough(self):
+        """Normal requests are not modified."""
+        response = self.client.get("/destination/")
+        assert response.status_code == 200
+        assert "X-Hilo-Redirect" not in response
+
+    def test_hilo_request_detected(self):
+        """Hilo requests are detected via X-Hilo header."""
+        response = self.client.get(
+            "/destination/",
+            headers={"X-Hilo": "true"},
+        )
+        assert response.status_code == 200
+
+    def test_redirect_converted_for_hilo(self):
+        """Django redirects become X-Hilo-Redirect for Hilo requests."""
+        response = self.client.get(
+            "/redirect/",
+            headers={"X-Hilo": "true"},
+        )
+        assert response.status_code == 200
+        assert response["X-Hilo-Redirect"] == "/destination/"
+
+    def test_redirect_normal_for_browser(self):
+        """Normal browser requests get standard redirects."""
+        response = self.client.get("/redirect/")
+        assert response.status_code == 302
+        assert response["Location"] == "/destination/"
+
+    @override_settings(HILO={"VERSION": "abc123"})
+    def test_version_header(self):
+        """X-Hilo-Version header is sent for Hilo requests."""
+        response = self.client.get(
+            "/destination/",
+            headers={"X-Hilo": "true"},
+        )
+        assert response["X-Hilo-Version"] == "abc123"
+
+
+class HiloResponseHelpersTest(TestCase):
+    """Test response helper functions."""
+
+    def test_hilo_redirect(self):
+        from hilo.response import hilo_redirect
+
+        response = hilo_redirect("/new-url/")
+        assert response.status_code == 200
+        assert response["X-Hilo-Redirect"] == "/new-url/"
+
+    def test_hilo_trigger(self):
+        from django.http import HttpResponse
+        from hilo.response import hilo_trigger
+
+        response = HttpResponse("ok")
+        hilo_trigger(response, {"showMessage": {"message": "Saved!", "type": "success"}})
+        assert "showMessage" in response["X-Hilo-Trigger"]
+
+    def test_hilo_trigger_simple(self):
+        from django.http import HttpResponse
+        from hilo.response import hilo_trigger
+
+        response = HttpResponse("ok")
+        hilo_trigger(response, "refreshList")
+        assert response["X-Hilo-Trigger"] == "refreshList"
+
+    def test_hilo_title(self):
+        from django.http import HttpResponse
+        from hilo.response import hilo_title
+
+        response = HttpResponse("ok")
+        hilo_title(response, "Products")
+        assert response["X-Hilo-Title"] == "Products"
+
+    def test_hilo_url(self):
+        from django.http import HttpResponse
+        from hilo.response import hilo_url
+
+        response = HttpResponse("ok")
+        hilo_url(response, "/products/")
+        assert response["X-Hilo-URL"] == "/products/"
+
+
+class HiloStreamResponseTest(TestCase):
+    """Test HiloStreamResponse."""
+
+    def test_append(self):
+        from hilo.response import HiloStreamResponse
+
+        response = HiloStreamResponse()
+        response.append("#list", "<li>New item</li>")
+        content = response.content.decode()
+        assert 'data-stream="append"' in content
+        assert 'data-target="#list"' in content
+        assert "<li>New item</li>" in content
+
+    def test_remove(self):
+        from hilo.response import HiloStreamResponse
+
+        response = HiloStreamResponse()
+        response.remove("#old-item")
+        content = response.content.decode()
+        assert 'data-stream="remove"' in content
+        assert 'data-target="#old-item"' in content
+
+    def test_chaining(self):
+        from hilo.response import HiloStreamResponse
+
+        response = HiloStreamResponse()
+        response.append("#list", "<li>1</li>").update("#counter", "42").remove("#old")
+        content = response.content.decode()
+        assert content.count("data-stream=") == 3

django_hilo-0.1.0/tests/urls.py

@@ -0,0 +1,25 @@
+from django.http import HttpResponse
+from django.urls import path
+
+from hilo.decorators import fragment
+
+
+@fragment("tests/partial.html")
+def test_view(request):
+    return {"message": "Hello from Hilo"}
+
+
+def redirect_view(request):
+    from django.shortcuts import redirect
+    return redirect("/destination/")
+
+
+def destination_view(request):
+    return HttpResponse("Destination reached")
+
+
+urlpatterns = [
+    path("test/", test_view, name="test"),
+    path("redirect/", redirect_view, name="redirect"),
+    path("destination/", destination_view, name="destination"),
+]