htag_mode cookie

Author: manatlan

.agent/skills/htag-development/SKILL.md

@@ -401,6 +401,21 @@ If you are migrating legacy htag v1 components, be aware of these core framework
 **3. Move to Composition & Tailwind**:
 - Replace heavy Python wrapper components (like `b.VBox`, `b.Progress()`) with native CSS composition (e.g., `Tag.div(_class="flex flex-col")`, `Tag.div(_class="animate-spin")`) leveraging the `.statics` injection of modern CSS frameworks like Tailwind.
 
+### 15. Forcing Interaction Mode (`htag_mode` cookie)
+
+In some network environments (e.g., restrictive corporate proxies), WebSockets or SSE might be technically "available" but extremely slow to time out, causing a frustrating delay before falling back to a working mode.
+
+htag supports a special cookie `htag_mode` to manually force a specific transport protocol, bypassing the standard auto-detection/timeout logic:
+
+- **`htag_mode=http`**: Forces the application into pure HTTP mode immediately. Both WebSocket and EventSource are mocked to fail instantly.
+- **`htag_mode=sse`**: Forces the application to use SSE (Server-Sent Events) by making the initial WebSocket connection fail immediately.
+- **(Absent)**: Default behavior (WebSocket -> SSE -> HTTP fallback).
+
+**How to use**:
+- Users can set this cookie via browser developer tools (`document.cookie="htag_mode=http;path=/"`).
+- It can be used by external load balancers or scripts to pre-configure the best transport for a specific environment.
+- The server detects this cookie during the initial `GET /` request and injects a specialized JS bootstrap patch into the page.
+
 ## Best Practices
 
 ### Layout & Styling

README.md

@@ -18,6 +18,7 @@
 
 **htag** is a Python3 GUI toolkit for building "beautiful" applications for mobile, web, and desktop from a single codebase
 
+
 Here is a full rewrite of **htag 1.0.0**, using only antigravity and prompts/intentions. It's the future of **htag**.
 
 Currently, it works ...
@@ -120,6 +121,13 @@ To tests them in live (debugging):
 - 2/ **sse** : in devtools/console : type `fallback();`
 - 3/ **http-pure**: in devtools/console : `fallback_pure_http();` (should always work!)
 
+### Forcing Interaction Mode (htag_mode cookie)
+
+To manually test or force a specific mode (bypassing auto-detection), set the `htag_mode` cookie:
+- `document.cookie="htag_mode=http;path=/"` -> Force pure HTTP
+- `document.cookie="htag_mode=sse;path=/"` -> Force SSE
+- `document.cookie="htag_mode=;Max-Age=0;path=/"` -> Back to default (WS)
+
 ## History
 
 At the beginning, there was [guy](https://github.com/manatlan/guy), which was/is the same concept as [python-eel](https://github.com/ChrisKnott/Eel), but more advanced.

docs/runners.md

@@ -66,6 +66,21 @@ if __name__ == "__main__":
 
 This ensures your application remains functional even behind the strictest corporate firewalls or unstable mobile connections.
 
+## Forcing Protocol via Cookie (`htag_mode`)
+
+In some restricted network environments (e.g., corporate proxies), WebSockets or SSE might be technically "available" but extremely slow to time out, causing a long delay before falling back to a working mode.
+
+`htag` supports forcing a specific protocol via the `htag_mode` cookie, bypassing the standard auto-detection:
+
+- **`htag_mode=http`**: Forces the application into pure HTTP mode (Level 3) immediately.
+- **`htag_mode=sse`**: Forces the application into SSE mode (Level 2).
+- **(Absent)**: Default behavior (WebSocket -> SSE -> HTTP).
+
+**Usage**:
+You can set this cookie manually in the browser console:
+`document.cookie="htag_mode=http;path=/"`
+Refresh the page to apply the change.
+
 ## Session & Cookie Path
 
 When using `WebApp`, `htag` manages sessions using a `htag_sid` cookie. 

htag/runner.py

@@ -19,6 +19,7 @@
 from .core import GTag, App as BaseApp
 from .tag import Tag
 from .utils import _obf_dumps, _obf_loads
+from .context import current_request
 from .client_js import CLIENT_JS
 
 logger = logging.getLogger("htag")
@@ -178,6 +179,16 @@ def _render_page(self) -> str:
         self.sent_statics.update(all_statics)
         statics_html = "".join(all_statics)
 
+        # Force protocol via cookie if present
+        protocol_patch = ""
+        request = current_request.get()
+        if request and hasattr(request, "cookies"):
+            mode = request.cookies.get("htag_mode")
+            if mode == "http":
+                protocol_patch = "window.WebSocket=window.EventSource=function(){var self=this;setTimeout(function(){if(self.onerror)self.onerror(new Error('Forced HTTP mode'))},0)};"
+            elif mode == "sse":
+                protocol_patch = "window.WebSocket=function(){var self=this;setTimeout(function(){if(self.onerror)self.onerror(new Error('Forced SSE mode'))},0)};"
+
         html_content = f"""
         <!DOCTYPE html>
         <html>
@@ -186,6 +197,7 @@ def _render_page(self) -> str:
                 <title>{title}</title>
                 <meta name="viewport" content="width=device-width, initial-scale=1">
                 <link rel="icon" href="/logo.png">
+                {f"<script>{protocol_patch}</script>" if protocol_patch else ""}
                 <script>{CLIENT_JS}</script>
                 <script>
                     window.HTAG_RELOAD = {"true" if getattr(self, "_reload", False) else "false"};

tests/test_htag_mode.py

@@ -0,0 +1,46 @@
+from starlette.testclient import TestClient
+from htag import App
+from htag.web import WebApp
+
+class MyApp(App):
+    def init(self):
+        self += "Hello World"
+
+def test_htag_mode_default():
+    """Verify that by default, no protocol mocking is injected."""
+    webapp = WebApp(MyApp)
+    client = TestClient(webapp.app)
+    response = client.get("/")
+    assert response.status_code == 200
+    assert "window.WebSocket=window.EventSource" not in response.text
+    assert "Hello World" in response.text
+
+def test_htag_mode_http():
+    """Verify protocol mocking for 'http' mode."""
+    webapp = WebApp(MyApp)
+    client = TestClient(webapp.app)
+    response = client.get("/", cookies={"htag_mode": "http"})
+    assert response.status_code == 200
+    # Both WebSocket and EventSource should be mocked
+    assert "window.WebSocket=window.EventSource=function()" in response.text
+    assert "Forced HTTP mode" in response.text
+
+def test_htag_mode_sse():
+    """Verify protocol mocking for 'sse' mode."""
+    webapp = WebApp(MyApp)
+    client = TestClient(webapp.app)
+    response = client.get("/", cookies={"htag_mode": "sse"})
+    assert response.status_code == 200
+    # Only WebSocket should be mocked
+    assert "window.WebSocket=function()" in response.text
+    assert "window.EventSource=function()" not in response.text
+    assert "Forced SSE mode" in response.text
+
+def test_htag_mode_invalid():
+    """Verify that invalid cookie values are ignored."""
+    webapp = WebApp(MyApp)
+    client = TestClient(webapp.app)
+    response = client.get("/", cookies={"htag_mode": "invalid"})
+    assert response.status_code == 200
+    assert "window.WebSocket=function()" not in response.text
+    assert "window.EventSource=function()" not in response.text