tina4-python 3.12.10__tar.gz → 3.12.13__tar.gz

{tina4_python-3.12.10 → tina4_python-3.12.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.12.10
+Version: 3.12.13
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -208,7 +208,7 @@ Visit `http://localhost:7146/api/hello` -- routes are auto-discovered, no import
 Edit `.env`:
 
 ```bash
-DATABASE_URL=sqlite:///data/app.db
+TINA4_DATABASE_URL=sqlite:///data/app.db
 ```
 
 Create and run a migration:
@@ -695,7 +695,7 @@ Frond.clear_cache()
 
 ```bash
 SECRET=your-jwt-secret
-DATABASE_URL=sqlite:///data/app.db
+TINA4_DATABASE_URL=sqlite:///data/app.db
 TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
 TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LOCALE=en                      # en, fr, af, zh, ja, es

{tina4_python-3.12.10 → tina4_python-3.12.13}/README.md

@@ -176,7 +176,7 @@ Visit `http://localhost:7146/api/hello` -- routes are auto-discovered, no import
 Edit `.env`:
 
 ```bash
-DATABASE_URL=sqlite:///data/app.db
+TINA4_DATABASE_URL=sqlite:///data/app.db
 ```
 
 Create and run a migration:
@@ -663,7 +663,7 @@ Frond.clear_cache()
 
 ```bash
 SECRET=your-jwt-secret
-DATABASE_URL=sqlite:///data/app.db
+TINA4_DATABASE_URL=sqlite:///data/app.db
 TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
 TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LOCALE=en                      # en, fr, af, zh, ja, es

{tina4_python-3.12.10 → tina4_python-3.12.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.12.10"
+version = "3.12.13"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/CLAUDE.md

@@ -287,7 +287,7 @@ Queue(topic="tasks").push({"action": "send_email"})
     - Other methods: `.to_json()`, `.to_array()`, `.to_csv()`, `.to_paginate()`
 4. **fetch_one()**: Returns a plain dict (or None), NOT a DatabaseResult
 5. **Dict access**: All query results use dict access `row["column"]` not attribute access `row.column`
-6. **Connection strings**: v3 uses standard URL format: `driver://host:port/database` with separate `username` and `password` parameters. Example: `Database("firebird://localhost:3050//path/to/db", "SYSDBA", "masterkey")`. Environment variable: `DATABASE_URL`.
+6. **Connection strings**: v3 uses standard URL format: `driver://host:port/database` with separate `username` and `password` parameters. Example: `Database("firebird://localhost:3050//path/to/db", "SYSDBA", "masterkey")`. Environment variable: `TINA4_DATABASE_URL`.
 7. **Running the app**: `uv run python app.py <port> <name>` — port and name are CLI args handled by tina4_python
 8. **SCSS**: Files in `src/scss/` are auto-compiled to `src/public/css/` on startup
 12. **Background tasks**: Use `background(fn, interval)` from `tina4_python.core.server` — never use `threading.Thread` for periodic work. The `background()` function runs tasks cooperatively in the asyncio event loop with proper shutdown handling.
@@ -408,7 +408,7 @@ Set `TINA4_DEBUG=true` in `.env` to enable development features:
 - **CSS hot-reload** — SCSS/CSS changes refresh stylesheets without full page reload
 - **SCSS auto-compile** — `.scss` files in `src/scss/` are compiled to `src/public/css/` on save
 - **Error overlay** — Runtime errors display a rich, syntax-highlighted overlay in the browser
-- **Hot-patching** — Python code changes are live-patched via jurigged (no server restart)
+- **Route re-discovery** — `POST /__dev/api/reload` re-runs auto-discover, so new files in `src/routes/`, `src/orm/`, or `src/app/` register without a server restart. Existing modules are NOT re-imported — for code changes inside an already-loaded file, restart the server.
 
 DevReload connects via WebSocket at `/__dev_reload`. No configuration needed.
 
@@ -741,7 +741,7 @@ db = Database("postgresql://localhost:5432/mydb", "user", "password")     # Post
 db = Database("mysql://localhost:3306/mydb", "user", "password")          # MySQL
 db = Database("firebird://localhost:3050//path/to/db", "SYSDBA", "masterkey")  # Firebird
 db = Database("mssql://localhost:1433/mydb", "sa", "password")            # MSSQL
-db = Database()                                                           # Uses DATABASE_URL env var
+db = Database()                                                           # Uses TINA4_DATABASE_URL env var
 ```
 
 ### MongoDB support
@@ -1565,9 +1565,9 @@ TINA4_API_KEY=your-api-key        # Static bearer token for API auth (API_KEY fa
 TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 
 # Database
-DATABASE_URL=sqlite:///app.db     # Connection URL (driver://host:port/database)
-DATABASE_USERNAME=                 # DB username (for PostgreSQL, MySQL, etc.)
-DATABASE_PASSWORD=                 # DB password
+TINA4_DATABASE_URL=sqlite:///app.db     # Connection URL (driver://host:port/database)
+TINA4_DATABASE_USERNAME=                 # DB username (for PostgreSQL, MySQL, etc.)
+TINA4_DATABASE_PASSWORD=                 # DB password
 
 # Framework
 TINA4_DEBUG=true                  # Enable dev mode (toolbar, live reload, error overlay)

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.12.10"
+__version__ = "3.12.13"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/cli/__init__.py

@@ -258,7 +258,7 @@ def _console(args=None):
     from tina4_python.api import Api
     from tina4_python.core.events import on, emit
 
-    # Try to connect database from DATABASE_URL
+    # Try to connect database from TINA4_DATABASE_URL
     db = None
     db_url = os.environ.get("TINA4_DATABASE_URL")
     if db_url:
@@ -345,15 +345,17 @@ def _init(args):
             encoding="utf-8",
         )
 
-    # Create .env
+    # Create .env — every framework env var is TINA4_-prefixed since v3.12.
+    # The boot guard refuses to start with bare DATABASE_URL / SECRET set,
+    # so a fresh project MUST get the prefixed names.
     env_file = target / ".env"
     if not env_file.exists():
         env_file.write_text(
             "# Tina4 Configuration\n"
             "TINA4_DEBUG=true\n"
             "TINA4_LOG_LEVEL=ALL\n"
-            "DATABASE_URL=sqlite:///data/app.db\n"
-            'SECRET=change-me-in-production\n',
+            "TINA4_DATABASE_URL=sqlite:///data/app.db\n"
+            'TINA4_SECRET=change-me-in-production\n',
             encoding="utf-8",
         )
 

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/core/request.py

@@ -19,7 +19,7 @@ class Request:
     """Parsed HTTP request — everything a route handler needs."""
 
     __slots__ = (
-        "method", "path", "query_string", "params", "query", "headers",
+        "method", "path", "url", "query_string", "params", "query", "headers",
         "body", "raw_body", "cookies", "files", "ip",
         "content_type", "session", "_route_params",
     )
@@ -27,6 +27,7 @@ class Request:
     def __init__(self):
         self.method: str = "GET"
         self.path: str = "/"
+        self.url: str = "/"
         self.query_string: str = ""
         self.params: dict = {}          # Query string + route params merged
         self.query: dict = {}           # Query string params only (separate from route params)
@@ -56,6 +57,24 @@ class Request:
         req.content_type = req.headers.get("content-type", "")
         req.ip = _extract_ip(scope, req.headers)
 
+        # Reconstruct the full absolute URL — scheme://host[:port]/path[?query].
+        # Honours x-forwarded-proto and x-forwarded-host so apps behind a proxy
+        # still see the URL the client used. Matches PHP/Ruby/Node parity.
+        scheme = (
+            req.headers.get("x-forwarded-proto")
+            or scope.get("scheme")
+            or "http"
+        )
+        host = (
+            req.headers.get("x-forwarded-host")
+            or req.headers.get("host")
+            or "localhost"
+        )
+        url = f"{scheme}://{host}{req.path}"
+        if req.query_string:
+            url = f"{url}?{req.query_string}"
+        req.url = url
+
         # Check upload size limit
         content_length = int(req.headers.get("content-length", 0) or 0)
         if content_length > TINA4_MAX_UPLOAD_SIZE or len(body) > TINA4_MAX_UPLOAD_SIZE:

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/core/router.py

@@ -246,6 +246,33 @@ class Router:
         """Register a DELETE route (imperative, non-decorator style)."""
         return cls.add("DELETE", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
 
+    @classmethod
+    def head(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
+        """Register an explicit HEAD route.
+
+        By default the framework auto-handles HEAD by falling back to the GET
+        route and stripping the body (RFC 9110 §9.3.2). Use this method only
+        when you need a HEAD handler that does something different from GET —
+        e.g. cheaper existence-check logic, custom validator headers without
+        the cost of building the body.
+
+        The framework still strips the response body for you on the way out —
+        HEAD MUST NOT return content, even if your handler does, so we
+        enforce that unconditionally rather than relying on developer care.
+        """
+        return cls.add("HEAD", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
+
+    @classmethod
+    def options(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
+        """Register an explicit OPTIONS route.
+
+        By default the framework auto-handles OPTIONS by building an Allow
+        header from every method registered for the path and returning 204
+        (RFC 9110 §9.3.7). Use this method to take over that behaviour —
+        e.g. to return a richer OPTIONS payload describing the resource.
+        """
+        return cls.add("OPTIONS", path, handler, middleware=middleware, swagger_meta=swagger_meta, template=template, **options)
+
     @classmethod
     def any(cls, path: str, handler, middleware: list = None, swagger_meta: dict = None, template: str = None, **options) -> "RouteRef":
         """Register a route for any HTTP method (imperative, non-decorator style)."""
@@ -291,7 +318,11 @@ class Router:
             # Route has custom middleware — developer handles auth themselves
             auth_required = False
         else:
-            auth_required = m not in ("GET", "ANY")
+            # GET, HEAD, OPTIONS, and ANY are public by default. HEAD and
+            # OPTIONS are safe/idempotent introspection methods (RFC 9110
+            # §9.2.1) — requiring auth on them breaks cache validators
+            # and CORS preflight probes.
+            auth_required = m not in ("GET", "HEAD", "OPTIONS", "ANY")
 
         route = {
             "method": m,
@@ -312,9 +343,18 @@ class Router:
 
     @staticmethod
     def match(method: str, path: str) -> tuple[dict | None, dict]:
-        """Find a route matching method + path. Returns (route, params)."""
+        """Find a route matching method + path. Returns (route, params).
+
+        RFC 9110 §9.3.2: HEAD is identical to GET except the response carries
+        no body. If the app didn't register a dedicated HEAD route, we
+        transparently match the GET route; the dispatcher strips the body on
+        the way out, so the handler doesn't need to know HEAD even happened.
+        """
+        method_upper = method.upper()
+
+        # First pass: exact method match (covers HEAD → explicit HEAD route too)
         for route in _routes:
-            if route["method"] not in (method.upper(), "ANY"):
+            if route["method"] not in (method_upper, "ANY"):
                 continue
             m = route["pattern"].match(path)
             if m:
@@ -323,8 +363,58 @@ class Router:
                     params[name] = m.group(i + 1)
                 return route, params
 
+        # Second pass: HEAD auto-fallback to GET when no HEAD route registered
+        if method_upper == "HEAD":
+            for route in _routes:
+                if route["method"] not in ("GET", "ANY"):
+                    continue
+                m = route["pattern"].match(path)
+                if m:
+                    params = {}
+                    for i, name in enumerate(route["param_names"]):
+                        params[name] = m.group(i + 1)
+                    return route, params
+
         return None, {}
 
+    @staticmethod
+    def methods_allowed_for_path(path: str) -> list[str]:
+        """Return the list of HTTP methods registered for ``path``, in the
+        order GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by
+        the dispatcher to build the ``Allow:`` header on 405 / OPTIONS
+        responses (RFC 9110 §10.2.1, §9.3.7).
+
+        If GET is registered, HEAD is appended implicitly (the framework
+        auto-falls-back HEAD to GET). OPTIONS is appended whenever the
+        path has any registered method (the framework auto-handles OPTIONS).
+        """
+        # ANY routes count for every method but we don't enumerate them
+        # individually — flag whether ANY matched and union it with the
+        # concrete-method matches.
+        method_order = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+        seen: set[str] = set()
+        any_matched = False
+
+        for route in _routes:
+            if not route["pattern"].match(path):
+                continue
+            m = route["method"]
+            if m == "ANY":
+                any_matched = True
+            elif m in method_order:
+                seen.add(m)
+
+        if any_matched:
+            seen.update(method_order)
+
+        # GET implies HEAD; any registered method implies OPTIONS.
+        if seen:
+            if "GET" in seen:
+                seen.add("HEAD")
+            seen.add("OPTIONS")
+
+        return [m for m in method_order if m in seen]
+
     @staticmethod
     def get_routes() -> list[dict]:
         """Return all registered routes."""

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/core/server.py

@@ -49,19 +49,45 @@ def background(callback, interval: float = 1.0):
 
 
 def _auto_discover(root_dir: str = "src"):
-    """Auto-import all .py files in src/ to trigger route decorators."""
+    """Auto-import all .py files in ``root_dir`` to trigger route decorators.
+
+    Idempotent and re-runnable: skips modules already in ``sys.modules`` so
+    re-discovery on /__dev/api/reload is cheap. New files added after server
+    boot get picked up on the next reload signal.
+
+    Import failures are recorded to ``data/.broken/`` so /health surfaces them
+    instead of swallowing them into a console line nobody reads.
+    """
     root = Path(root_dir).resolve()
     if not root.is_dir():
         return
 
+    # Folders to skip — non-Python sub-trees inside src/.
     skip = {"public", "templates", "scss", "locales", "icons"}
+    # Routes folder is special-cased so the user gets a clear warning when
+    # it exists but contains zero discoverable Python files.
+    routes_dir = root / "routes"
+    found_route_files = 0
 
     for py_file in sorted(root.rglob("*.py")):
-        if any(part.startswith("_") for part in py_file.parts):
+        # Only filter on parts INSIDE src/, not the absolute path. Previously
+        # `py_file.parts` included every ancestor, so a project living under
+        # something like /Users/me/_archive/myapp would silently skip every
+        # file. Compute the relative parts first and filter on those.
+        try:
+            rel_to_root = py_file.relative_to(root)
+        except ValueError:
+            continue
+
+        rel_parts = rel_to_root.parts
+        if any(part.startswith("_") for part in rel_parts):
             continue
-        if any(s in py_file.parts for s in skip):
+        if any(s in rel_parts for s in skip):
             continue
 
+        if routes_dir in py_file.parents:
+            found_route_files += 1
+
         try:
             rel = py_file.relative_to(Path.cwd()).with_suffix("")
             module_name = ".".join(rel.parts)
@@ -70,6 +96,39 @@ def _auto_discover(root_dir: str = "src"):
                 Log.debug(f"Loaded: {module_name}")
         except Exception as e:
             Log.error(f"Failed to load {py_file}: {e}")
+            _record_broken_import(py_file, e)
+
+    # User-friendly hint: routes folder has Python files but the router is
+    # still empty. They almost certainly forgot the @get/@post decorator.
+    if found_route_files > 0:
+        try:
+            from tina4_python.core.router import Router
+            if not Router.get_routes():
+                Log.warning(
+                    f"Auto-discover found {found_route_files} .py file(s) in "
+                    f"{routes_dir} but no routes registered. Did you forget "
+                    f"@get / @post / @put / @delete on your handler?"
+                )
+        except Exception:
+            pass
+
+
+def _record_broken_import(py_file: Path, error: Exception) -> None:
+    """Write a .broken sentinel so /health and the dev dashboard surface
+    auto-discover failures instead of burying them in the console."""
+    try:
+        broken_dir = Path("data/.broken")
+        broken_dir.mkdir(parents=True, exist_ok=True)
+        import json
+        slug = str(py_file).replace("/", "_").replace("\\", "_")
+        (broken_dir / f"discover_{slug}.broken").write_text(json.dumps({
+            "type": "auto_discover_failure",
+            "file": str(py_file),
+            "error": f"{type(error).__name__}: {error}",
+        }))
+    except Exception:
+        # If even the .broken write fails we already logged the original error.
+        pass
 
 
 def _ensure_folders():
@@ -932,10 +991,35 @@ async def _handle_dev_admin(request: Request, response: Response) -> Response:
 <html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>Tina4 Dev Admin</title></head>
 <body><div id="app" data-framework="python" data-color="#3b82f6"></div>
 <script src="/js/tina4-dev-admin.min.js"></script></body></html>""")
+        # Never cache the dev admin shell — otherwise old HTML can
+        # keep loading stale widget references / outdated bundle URLs
+        # after we ship UX changes, leaving the user staring at
+        # phantoms that no longer exist server-side.
+        response.header("cache-control", "no-store, must-revalidate")
+        response.header("pragma", "no-cache")
     else:
         handlers = get_api_handlers()
         handler_info = handlers.get(request.path)
-        if handler_info and request.method == handler_info[0]:
+        if not handler_info:
+            # Fallback: longest-prefix wildcard match. Routes registered
+            # with a trailing "/*" (e.g. "/__dev/api/threads/*") catch
+            # everything under that namespace — used for parameterised
+            # resources like /threads/{id} that don't fit exact-match.
+            best_prefix = ""
+            for key, info in handlers.items():
+                if key.endswith("/*"):
+                    prefix = key[:-1]  # keep the trailing slash
+                    if request.path.startswith(prefix) and len(prefix) > len(best_prefix):
+                        best_prefix = prefix
+                        handler_info = info
+        # Allow "*" as a method wildcard for handlers that switch on
+        # request.method themselves (REST resources with GET+POST+PATCH
+        # on the same path).
+        method_ok = (
+            handler_info is not None
+            and (handler_info[0] == "*" or request.method == handler_info[0])
+        )
+        if method_ok:
             try:
                 def _resp(data, code=200, content_type=None):
                     # content_type overrides the auto-detected MIME —
@@ -955,6 +1039,14 @@ async def _handle_dev_admin(request: Request, response: Response) -> Response:
                         response.status(code).json(data)
                     return data
                 _resp.render = response.render
+                # Expose .stream() so handlers can return an SSE/chunked
+                # response — used by the dev_admin supervisor proxy to
+                # forward the agent server's text/event-stream live
+                # (instead of buffering the whole multi-agent run).
+                _resp.stream = response.stream
+                # Expose .header() so handlers can set custom headers
+                # (e.g. Cache-Control on the feedback widget bundle).
+                _resp.header = response.header
                 import inspect
                 _tsig = inspect.signature(handler_info[1])
                 _tpcount = len(_tsig.parameters)
@@ -1306,12 +1398,17 @@ async def handle(request: Request) -> Response:
         canonical = request.path.rstrip("/") or "/"
         return response.status(301).header("location", canonical)
 
-    # Dev admin — also catches /ai/api/chat (SPA's ollama proxy) and the
+    # Dev admin — also catches /ai/api/chat (SPA's ollama proxy), the
     # bare /ai /vision /embed /image /rag service-health probes that
-    # drive the "SERVICES ●●●●●" dots in the dev-admin UI.
+    # drive the "SERVICES ●●●●●" dots in the dev-admin UI, and the
+    # /__feedback/* routes used by the customer feedback widget. The
+    # feedback paths live OUTSIDE /__dev because the widget is for
+    # whitelisted END USERS of the shipped app — they shouldn't see
+    # any /__dev URL in their network tab.
     _dev_extra_paths = {"/ai/api/chat", "/ai", "/vision", "/embed", "/image", "/rag"}
     if _is_dev and (
         request.path.startswith("/__dev")
+        or request.path.startswith("/__feedback")
         or request.path in _dev_extra_paths
     ):
         return await _handle_dev_admin(request, response)
@@ -1338,7 +1435,43 @@ async def handle(request: Request) -> Response:
         except Exception as e:
             response = _handle_route_error(e, request, response, request_id, _is_dev)
     else:
-        response = _handle_no_route(request, response, request_id)
+        # RFC 9110 conformance — before falling through to 404 / static / template,
+        # check whether the PATH is known to the router under any OTHER method.
+        # If yes:
+        #   - OPTIONS request → 204 No Content with Allow listing the methods
+        #     (RFC 9110 §9.3.7). Generic OPTIONS handler.
+        #   - Any other method (PUT on GET-only route, TRACE, CONNECT, etc.)
+        #     → 405 Method Not Allowed with Allow header (§15.5.6 + §10.2.1).
+        allowed = Router.methods_allowed_for_path(request.path)
+        if allowed:
+            allow_header = ", ".join(allowed)
+            if request.method.upper() == "OPTIONS":
+                response.header("Allow", allow_header)
+                response.status(204)
+            else:
+                response.header("Allow", allow_header)
+                response.status(405).json({
+                    "error": "Method Not Allowed",
+                    "path": request.path,
+                    "method": request.method,
+                    "allow": allowed,
+                    "status": 405,
+                })
+        else:
+            response = _handle_no_route(request, response, request_id)
+
+    # RFC 9110 §9.3.2: a HEAD response MUST NOT include content. Strip the
+    # body unconditionally (even for explicit Router.head() handlers that
+    # accidentally returned one) and record what Content-Length the GET
+    # would have sent — cache validators / link checkers / monitoring
+    # probes rely on that header to size estimates.
+    if request.method.upper() == "HEAD":
+        body = response.content if response.content is not None else b""
+        if isinstance(body, str):
+            body = body.encode("utf-8")
+        if body:
+            response.header("Content-Length", str(len(body)))
+            response.content = b""
 
     return _finalize_response(request, response, route, request_id, _is_dev, _req_start)
 
@@ -1407,6 +1540,22 @@ async def app(scope: dict, receive, send):
         await send({"type": "http.response.body", "body": b"", "more_body": False})
         return
 
+    # Customer feedback widget injection — adds <script src="/__feedback/widget.js">
+    # to HTML responses for whitelisted users. No-op if the feature is
+    # off (TINA4_FEEDBACK_WHITELIST empty) or the user isn't whitelisted
+    # or the body isn't HTML. Done BEFORE ETag/header build so the
+    # injected bytes are included in the ETag hash + Content-Length.
+    try:
+        if (
+            response.content
+            and isinstance(response.content, (bytes, bytearray))
+            and "text/html" in (response.content_type or "").lower()
+        ):
+            from tina4_python.dev_admin import inject_feedback_widget
+            response.content = inject_feedback_widget(request, bytes(response.content))
+    except Exception:
+        pass  # Injection is best-effort — never break the response.
+
     # ETag check — 304 Not Modified
     if_none_match = request.headers.get("if-none-match", "")
     accept_encoding = request.headers.get("accept-encoding", "")

{tina4_python-3.12.10 → tina4_python-3.12.13}/tina4_python/debug/error_overlay.py

@@ -79,9 +79,31 @@ def _format_source_block(filename: str, lineno: int) -> str:
     )
 
 
-def _format_frame(frame: traceback.FrameSummary) -> str:
-    """Render one stack frame."""
+def _format_frame(frame: traceback.FrameSummary, captured_at: float = 0.0) -> str:
+    """Render one stack frame.
+
+    When the file was modified AFTER `captured_at`, append a
+    "(file modified since)" badge so a stale browser-cached overlay
+    can't lie about what the source looks like now. The AI coder
+    often rewrites files in place between page loads, leaving the
+    overlay's source view showing different code than what raised
+    the error.
+    """
     source = _format_source_block(frame.filename, frame.lineno) if frame.filename and frame.lineno else ""
+    stale_badge = ""
+    if captured_at and frame.filename:
+        try:
+            mtime = os.path.getmtime(frame.filename)
+            if mtime > captured_at + 0.5:  # 0.5s margin for fs noise
+                from datetime import datetime, timezone
+                mtime_iso = datetime.fromtimestamp(mtime, tz=timezone.utc).strftime("%H:%M:%S")
+                stale_badge = (
+                    f' <span style="background:{_PEACH};color:{_BG};padding:1px 8px;'
+                    f'border-radius:3px;font-size:11px;font-weight:700;margin-left:6px;">'
+                    f'FILE MODIFIED @ {mtime_iso} — source may not match what failed</span>'
+                )
+        except OSError:
+            pass
     return (
         f'<div style="margin-bottom:16px;">'
         f'<div style="margin-bottom:4px;">'
@@ -90,6 +112,7 @@ def _format_frame(frame: traceback.FrameSummary) -> str:
         f'<span style="color:{_YELLOW};">{frame.lineno}</span>'
         f'<span style="color:{_SUBTEXT};"> in </span>'
         f'<span style="color:{_GREEN};">{_escape(frame.name)}</span>'
+        f"{stale_badge}"
         f"</div>"
         f"{source}"
         f"</div>"
@@ -131,14 +154,23 @@ def render_error_overlay(exception: BaseException, request: Any = None) -> str:
     Returns:
         A complete HTML page string.
     """
+    import time as _time
+    captured_at = _time.time()
+    captured_iso = _time.strftime("%H:%M:%S UTC", _time.gmtime(captured_at))
+
     exc_type = type(exception).__qualname__
     exc_msg = str(exception)
     tb = traceback.extract_tb(exception.__traceback__)
 
     # ── Stack trace ──
+    # Each frame compares its source file's mtime to captured_at and
+    # flags itself if the file has been modified since — protects
+    # against the "browser cached an old overlay, then the AI rewrote
+    # the file" confusion where displayed source no longer matches
+    # what actually raised the error.
     frames_html = ""
     for frame in reversed(tb):
-        frames_html += _format_frame(frame)
+        frames_html += _format_frame(frame, captured_at=captured_at)
 
     # ── Request info ──
     request_pairs: list[tuple[str, str]] = []
@@ -192,6 +224,7 @@ body{{background:{_BG};color:{_TEXT};font-family:-apple-system,BlinkMacSystemFon
     <div style="display:flex;align-items:center;gap:12px;margin-bottom:12px;">
       <span style="background:{_RED};color:{_BG};padding:4px 12px;border-radius:4px;font-weight:700;font-size:13px;text-transform:uppercase;">Error</span>
       <span style="color:{_SUBTEXT};font-size:14px;">Tina4 Debug Overlay</span>
+      <span style="color:{_SUBTEXT};font-size:12px;margin-left:auto;font-family:'SF Mono',Menlo,monospace;">captured {captured_iso}</span>
     </div>
     <h1 style="color:{_RED};font-size:28px;font-weight:700;margin-bottom:8px;">{_escape(exc_type)}</h1>
     <p style="color:{_TEXT};font-size:18px;font-family:'SF Mono','Fira Code','Consolas',monospace;background:{_SURFACE};padding:12px 16px;border-radius:6px;border-left:4px solid {_RED};">{_escape(exc_msg)}</p>