jac-coder 0.2.2__tar.gz → 0.2.3__tar.gz

{jac_coder-0.2.2 → jac_coder-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jac-coder
-Version: 0.2.2
+Version: 0.2.3
 Summary: AI coding agent backend for Jac, powered by jac-byllm
 Requires-Python: >=3.12
 Requires-Dist: python-dotenv>=1.0.0

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/api.impl.jac

@@ -524,6 +524,28 @@ impl api_get_model() -> dict {
     return _get_model();
 }
 
+impl api_check_local_setup(alias: str) -> dict {
+    runtime: bool = False;
+    try {
+        import llama_cpp;
+        runtime = True;
+    } except ImportError { }
+
+    model: bool = False;
+    valid_alias: bool = False;
+    try {
+        import from byllm.local_runtime { LOCAL_MODELS }
+        import from byllm.model_cache { is_downloaded }
+        spec = LOCAL_MODELS.get(alias);
+        if spec is not None {
+            valid_alias = True;
+            model = is_downloaded(alias, spec);
+        }
+    } except Exception { }
+
+    return {"runtime": runtime, "model": model, "valid_alias": valid_alias};
+}
+
 
 # ---------------------------------------------------------------------------
 # MCP management API

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/api.jac

@@ -78,6 +78,9 @@ def api_set_model(model: str) -> dict;
 """Get current model info."""
 def api_get_model() -> dict;
 
+"""Check if local model runtime and model weights are ready for a given alias."""
+def api_check_local_setup(alias: str) -> dict;
+
 # --- MCP management API ---
 """Add or update an MCP server."""
 def api_mcp_add(name: str, config: dict) -> dict;

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/core/nodes.impl.jac

@@ -140,11 +140,19 @@ Build breadth-first — get all files written and app running before polishing.
 ## Workflow
 1. Read .jaccoder/progress.md if it exists, update it as you go.
 2. analyze_project(dir) for existing projects.
-3. jac.toml needs `[plugins.client.vite]` with tailwindcss. Run `jac install` after toml changes.
-4. Build bottom-up: services → styles/global.css → hooks → components → layout.
-5. styles/global.css: `@import "tailwindcss"`, @theme tokens. In main.jac: `cl import ".styles.global.css";`
-6. After all files: jac start --dev main.jac (background=True).
-7. browser_validate(url) → follow FAIL action instructions.
+3. Build bottom-up: services → hooks → components → layout.
+4. **If `components/ui/` exists AND jac.toml has `[jac-shadcn]` (jac-shadcn project):**
+   - Load `jac-shadcn-components` skill BEFORE writing any UI.
+   - Load `jac-cl-styling` for conditional class and cn() patterns.
+   - `styles/global.css` and `jac.toml` are pre-configured — do NOT recreate or modify them.
+   - Import UI from `components/ui/` instead of writing raw primitive components. No inline styles.
+   **Otherwise (standard project):**
+   - jac.toml needs `[plugins.client.vite]` with tailwindcss. Run `jac install` after toml changes.
+   - styles/global.css: `@import "tailwindcss"`, @theme tokens. In main.jac: `cl import ".styles.global.css";`
+   - Load `jac-cl-styling` when writing Tailwind classes or dynamic styles.
+   - Load `jac-npm-packages` when adding third-party npm packages.
+5. After all files: jac start --dev main.jac (background=True).
+6. browser_validate(url) → follow FAIL action instructions.
 
 Load the relevant `load_jac_skill(name)` from `<jac-skills-available>` BEFORE writing Jac. Tools catch obvious anti-patterns — trust BLOCKED messages.
 """;

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/infra/config.impl.jac

@@ -99,6 +99,7 @@ impl set_model(model: str) -> dict {
     }
     model_name = model;
     llm.model_name = model;
+    llm.postinit();
     _config.default_model = model;
     return {"status": "ok", "model": model};
 }

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/infra/config.jac

@@ -87,4 +87,5 @@ with entry {
     # with the hardcoded default before load_config() runs.
     model_name = _config.default_model;
     llm.model_name = model_name;
+    llm.postinit();
 }

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/infra/mcp_manager.impl.jac

@@ -73,7 +73,13 @@ def _get_registry() -> Any {
             target_anchor = edge_anchor.target;
             target_anchor.populate();
             if isinstance(target_anchor.archetype, McpRegistry) {
-                return target_anchor.archetype;
+                reg = target_anchor.archetype;
+                # Migration guard: nodes persisted before disconnected_servers was
+                # added to the schema won't have this attribute after deserialization.
+                if not hasattr(reg, "disconnected_servers") {
+                    reg.disconnected_servers = [];
+                }
+                return reg;
             }
         } except Exception { }
     }

jac_coder-0.2.3/jac_coder/runtime/file_logger.jac

@@ -0,0 +1,235 @@
+"""Shared file-based structured logger for JacCoder.
+
+Enabled via JACCODER_LOG=1. Writes JSON lines to
+.jaccoder/logs/<branch>_<timestamp>.log in the working directory.
+
+Used by both cli.jac (single session, session_id="") and server.jac
+(multiple concurrent sessions, keyed by session_id). Thread-safe.
+"""
+
+import os;
+import sys;
+import json;
+import threading;
+import from datetime { datetime }
+
+
+glob _log_file_path: str = "";
+glob _log_file_handle: object = None;
+glob _log_iteration: dict = {};    # int counter per session_id
+glob _log_turn_cost: dict = {};    # float accumulator per session_id
+glob _log_lock: threading.Lock = threading.Lock();
+
+
+"""True when JACCODER_LOG=1 is set and logger is initialized."""
+def is_logging_enabled() -> bool {
+    return bool(_log_file_handle);
+}
+
+
+"""Initialize the file logger. No-op if JACCODER_LOG is not set.
+
+Call once at startup. Safe to call multiple times — only initializes once.
+model_name is written to the session_start record.
+"""
+def init_file_logger(model_name: str = "") -> None {
+    global _log_file_path, _log_file_handle;
+
+    if _log_file_handle {
+        return;
+    }
+    if not os.environ.get("JACCODER_LOG", "") {
+        return;
+    }
+
+    ts = datetime.now().strftime("%Y-%m-%d_%H-%M-%S");
+    branch = "";
+    try {
+        import subprocess;
+        r = subprocess.run(["git", "branch", "--show-current"], capture_output=True, text=True);
+        branch = r.stdout.strip().replace("/", "-") if r.returncode == 0 else "";
+    } except Exception {
+        branch = "";
+    }
+
+    log_dir = os.path.join(os.getcwd(), ".jaccoder", "logs");
+    os.makedirs(log_dir, exist_ok=True);
+
+    name = f"{branch}_{ts}.log" if branch else f"{ts}.log";
+    _log_file_path = os.path.join(log_dir, name);
+
+    try {
+        _log_file_handle = open(_log_file_path, "w", buffering=1);
+    } except OSError as e {
+        sys.stderr.write(f"[JacCoder] Could not open log file: {e}\n");
+        return;
+    }
+
+    import from jac_coder.runtime.cost_tracker { enable_cost_tracking }
+    enable_cost_tracking();
+
+    _log_file_handle.write(json.dumps({
+        "event": "session_start",
+        "branch": branch,
+        "timestamp": ts,
+        "model": model_name
+    }) + "\n");
+    _log_file_handle.flush();
+    sys.stderr.write(f"[JacCoder] Log: {_log_file_path}\n");
+}
+
+
+"""Write one structured event. Thread-safe. No-op if logger not initialized.
+
+session_id: use "" for CLI (single session), or actual session UUID for server.
+"""
+def file_log_event(session_id: str, event_type: str, data: dict) -> None {
+    global _log_file_handle, _log_iteration, _log_turn_cost, _log_lock;
+
+    if not _log_file_handle {
+        return;
+    }
+
+    with _log_lock {
+        try {
+            ts = data.get("timestamp", 0.0);
+            record: dict = {"event": event_type, "ts": ts};
+            if session_id {
+                record["session"] = session_id;
+            }
+
+            it: int = _log_iteration.get(session_id, 0);
+            tc: float = _log_turn_cost.get(session_id, 0.0);
+            try {
+                import from jac_coder.infra.config { llm as _llm }
+                _current_model: str = str(_llm.model_name);
+            } except Exception {
+                _current_model: str = "";
+            }
+
+            if event_type == "llm_tool_call" {
+                it += 1;
+                _log_iteration[session_id] = it;
+                record["iteration"] = it;
+                record["tool"] = data.get("tool", "");
+                record["args"] = data.get("args", {});
+
+            } elif event_type == "llm_tool_result" {
+                record["iteration"] = it;
+                record["tool"] = data.get("tool", "");
+                result_str = str(data.get("result", ""));
+                record["ok"] = (
+                    not result_str.startswith("Error")
+                    and "BLOCKED" not in result_str
+                    and "LOOP DETECTED" not in result_str
+                );
+                record["error"] = not record["ok"];
+                record["result_preview"] = result_str[:1000];
+                if "LOOP DETECTED" in result_str {
+                    record["loop_detected"] = True;
+                }
+
+            } elif event_type == "llm_usage" {
+                total = data.get("total") or {};
+                inp = int(total.get("prompt_tokens") or total.get("input_tokens") or 0);
+                out = int(total.get("completion_tokens") or total.get("output_tokens") or 0);
+                cached = int(
+                    total.get("cache_read_input_tokens")
+                    or (total.get("prompt_tokens_details") or {}).get("cached_tokens")
+                    or 0
+                );
+                req_cost = float(data.get("request_cost") or 0.0);
+                tc += req_cost;
+                _log_turn_cost[session_id] = tc;
+                record["iteration"] = it;
+                record["model"] = _current_model;
+                record["input_tokens"] = inp;
+                record["output_tokens"] = out;
+                record["cached_tokens"] = cached;
+                record["effective_input_tokens"] = inp - cached;
+                record["cost_usd"] = round(req_cost, 6);
+
+            } elif event_type == "llm_steps_done" {
+                record["iterations"] = data.get("iterations", 0);
+                record["reason"] = data.get("reason", "");
+
+            } elif event_type == "turn_summary" {
+                record["tools_count"] = data.get("tools_count", 0);
+                record["files_modified"] = data.get("files_modified", []);
+                record["errors"] = data.get("errors", 0);
+                record["duration_s"] = data.get("duration_s", 0.0);
+                record["turn_cost_usd"] = round(tc, 6);
+                record["model"] = _current_model;
+                _log_turn_cost[session_id] = 0.0;
+                _log_iteration[session_id] = 0;
+
+            } elif event_type == "llm_thought" {
+                record["iteration"] = it;
+                record["thought_preview"] = str(data.get("content", ""))[:500];
+
+            } elif event_type == "tool_end" {
+                record["iteration"] = it;
+                record["tool"] = data.get("tool", "");
+                record["step"] = data.get("step", 0);
+                record["status"] = data.get("status", "done");
+                record["duration_ms"] = data.get("duration_ms", 0);
+                record["result_preview"] = str(data.get("result_preview", ""));
+
+            } elif event_type == "file_written" {
+                record["iteration"] = it;
+                record["path"] = data.get("path", "");
+                record["lines"] = data.get("lines", 0);
+
+            } elif event_type == "file_edited" {
+                record["iteration"] = it;
+                record["path"] = data.get("path", "");
+                record["replacements"] = data.get("replacements", 0);
+
+            } elif event_type == "context_compaction" {
+                record["status"] = data.get("status", "");
+                if data.get("turns_to_summarize") is not None {
+                    record["turns_to_summarize"] = data.get("turns_to_summarize");
+                }
+                if data.get("summary_length") is not None {
+                    record["summary_length"] = data.get("summary_length");
+                }
+
+            } else {
+                return;
+            }
+
+            _log_file_handle.write(json.dumps(record) + "\n");
+
+        } except Exception as e {
+            sys.stderr.write(f"[JacCoder] log write error: {e}\n");
+        }
+    }
+}
+
+
+"""Write session_end summary and close the log file. Safe to call multiple times."""
+def close_file_logger() -> None {
+    global _log_file_handle, _log_file_path, _log_lock;
+
+    with _log_lock {
+        if not _log_file_handle {
+            return;
+        }
+
+        try {
+            import from jac_coder.runtime.cost_tracker { get_summary, get_per_call_data }
+            _log_file_handle.write(json.dumps({
+                "event": "session_end",
+                "summary": get_summary(),
+                "per_call": get_per_call_data()
+            }) + "\n");
+            _log_file_handle.flush();
+            _log_file_handle.close();
+            sys.stderr.write(f"[JacCoder] Log saved: {_log_file_path}\n");
+        } except Exception as e {
+            sys.stderr.write(f"[JacCoder] log close error: {e}\n");
+        } finally {
+            _log_file_handle = None;
+        }
+    }
+}

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/server.jac

@@ -24,6 +24,7 @@ Message format (JSON-RPC 2.0):
     api.validate      → validate the configured API key
     model.get         → get the currently active model
     model.set         → switch the active model
+    model.local.check → check if local runtime + model weights are ready
 
   Inbound notification (extension → server, no "id", no reply):
     chat.cancel         → abort the running agent turn
@@ -46,6 +47,7 @@ import logging;
 import threading;
 import from typing { Any, IO }
 import from importlib.metadata { version as _pkg_version, PackageNotFoundError }
+import from jac_coder.runtime.file_logger { init_file_logger, file_log_event, close_file_logger }
 
 import from jac_coder.tool.run.guarded { _permission_events, _permission_decisions }
 
@@ -63,7 +65,8 @@ import from jac_coder.api {
     api_mcp_delete as _api_mcp_delete,
     api_mcp_list as _api_mcp_list,
     api_set_model as _api_set_model,
-    api_get_model as _api_get_model
+    api_get_model as _api_get_model,
+    api_check_local_setup as _api_check_local_setup
 }
 import from jac_coder.runtime.events { request_abort_thread }
 import from jac_coder.runtime.cost_tracker { get_summary as _get_usage_summary, is_cost_tracking_enabled, reset as _reset_usage }
@@ -92,6 +95,8 @@ glob _reply_flags: dict = {};
 glob _reply_lock: threading.Lock = threading.Lock();
 
 
+
+
 """Return installed jac-coder version, or 'unknown' if not installed as a package."""
 def _get_server_version() -> str {
     try {
@@ -196,6 +201,7 @@ def _handle_chat(req_id: Any, params: dict) -> None {
             raise KeyboardInterrupt("cancelled");  # unwinds the agent immediately
         }
         _write(_notify("chat.event", {"type": event_type, "session_id": session_id, **data}));
+        file_log_event(session_id, event_type, data);
     }
 
     try {
@@ -369,6 +375,9 @@ async def _dispatch(req_id: Any, method: str, params: dict) -> None {
                 _write(_ok(req_id, _api_set_model(model=model)));
             }
 
+        } elif method == "model.local.check" {
+            _write(_ok(req_id, _api_check_local_setup(alias=params.get("alias", ""))));
+
         } else {
             _write(_err(req_id, -32601, f"Method not found: {method}"));
         }
@@ -395,6 +404,9 @@ async def _dispatch(req_id: Any, method: str, params: dict) -> None {
 async def _main() -> None {
     loop: asyncio.AbstractEventLoop = asyncio.get_event_loop();
 
+    # Initialize file logger if JACCODER_LOG=1 is set.
+    init_file_logger(model_name=str(llm.model_name));
+
     # Tell the extension we are ready to receive requests.
     _write(_notify("server.ready", {"service": "jac-coder", "version": _get_server_version()}));
 
@@ -410,6 +422,7 @@ async def _main() -> None {
 
         if not line {
             # Empty string = EOF = extension disconnected. Exit cleanly.
+            close_file_logger();
             break;
         }
 

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/skills/ROADMAP.md

@@ -27,6 +27,7 @@ Check off with `✅` when shipped, `🟡` when in-progress, `⬜` when planned.
 - ✅ `jac-cl-routing` — Router, Routes, Route, Navigate, useNavigate, Link
 - ✅ `jac-cl-auth` — jacLogin, jacSignup, jacLogout, jacIsLoggedIn, protected routes
 - ✅ `jac-cl-organization` — file layout, component reuse discipline, hook pattern, when to extract
+- ✅ `jac-shadcn-components` — using pre-installed jac-shadcn primitives (components/ui/), import patterns, composition rules, styling, icons
 - ⬜ `jac-cl-forms` (maybe) — controlled inputs, submit handlers, validation patterns
 
 ### Server (`.sv.jac`)

jac_coder-0.2.3/jac_coder/skills/jac-cl-auth/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: jac-cl-auth
+description: Client-side authentication — signing up, logging in, logging out, and protecting pages behind login. Load when adding any auth UI or guarding pages from unauthenticated users. Pair with `jac-sv-auth` (server side of the auth loop), `jac-cl-routing` (post-login navigation).
+---
+
+Client auth uses four helpers from `@jac/runtime`. **Return types differ — get them wrong and the file fails `jac check` with E1001:**
+
+| Helper | Async? | Returns | Pre-declare as |
+|---|---|---|---|
+| `jacSignup(email, password)` | yes | `dict` (account info) | `result: dict \| None = None` |
+| `jacLogin(email, password)` | yes | `bool` | `ok: bool = False` |
+| `jacLogout()` | no | `None` | — (call it, no assign) |
+| `jacIsLoggedIn()` | no | `bool` | — (use inline) |
+
+Both async helpers' return values are truthy on success / falsy on failure, so `if not result { ... }` works for both. But the **types** differ — typing a `jacSignup` result as `bool` fails `jac check` with `E1001: Cannot assign dict to bool`.
+
+## ⚠ Read first — signup + first `def:priv` call must be 3 awaited steps
+
+When the same form that signs a user up also calls a `def:priv` endpoint (saving the new user's profile, preferences, default workspace), the call order is **fixed and each step MUST be awaited**:
+
+1. `await jacSignup(email, password)` — creates the account; **no session yet**
+2. `await jacLogin(email, password)` — establishes the session cookie
+3. `await save_profile(...)` — only NOW does the `def:priv` call have an authenticated session
+
+```jac
+# `save_profile` here is YOUR server function (def:priv) — imported from a .sv.jac module.
+async def handle_register(name: str, email: str, password: str) -> str {
+    # Pre-declare every var that holds an `await` result. `let` scoping in the
+    # generated JS can otherwise leave them undefined at the if-check.
+    # Note the per-helper types: jacSignup -> dict, jacLogin -> bool.
+    signup_result: dict | None = None;
+    login_ok: bool = False;
+    profile_result: Any = None;
+
+    signup_result = await jacSignup(email, password);
+    if not signup_result { return "registration failed"; }
+
+    login_ok = await jacLogin(email, password);
+    if not login_ok { return "login after signup failed"; }
+
+    profile_result = await save_profile(name, email);
+    if profile_result is None { return "save failed"; }
+    if not profile_result.success { return profile_result.message; }
+
+    return "success";
+}
+```
+
+**Why every `await` matters:** all three are async (return Promises). Skipping any `await` fires that call as a background Promise and lets the next line execute immediately. If `save_profile` fires before `jacLogin` completes, the session cookie isn't set yet → server gets the request without auth → `401 Unauthorized`. **Silent at compile time — only surfaces at runtime on first registration.**
+
+**Why pre-declare:** in `.cl.jac`, `var = await fn()` can compile to a JS `let var = ...` that is scoped tighter than the surrounding function (especially around `try`/`except` and certain async patterns), so `if not var { ... }` on the next line throws `ReferenceError: var is not defined`. Declaring `var: T = default;` at the top forces a function-scope `let` that the if-check can see.
+
+---
+
+```jac
+import from "@jac/runtime" { jacLogin, jacSignup, jacLogout, jacIsLoggedIn, Navigate }
+
+# Login attempt — call from a submit handler or effect. Returns a status string.
+# Pre-declare `ok` at the top — see "Why pre-declare" above.
+async def try_login(email: str, password: str) -> str {
+    ok: bool = False;
+    try {
+        ok = await jacLogin(email, password);
+        if ok {
+            return "success";
+        }
+        return "invalid credentials";
+    } except Exception as e {
+        return "error";
+    }
+}
+
+# Signup is usually followed by a login to establish the session.
+async def try_signup(email: str, password: str) -> str {
+    signup_result: dict | None = None;       # jacSignup returns dict
+    login_ok: bool = False;                  # jacLogin returns bool
+    try {
+        signup_result = await jacSignup(email, password);
+        if not signup_result {
+            return "signup failed (email may be in use)";
+        }
+        login_ok = await jacLogin(email, password);
+        if login_ok {
+            return "success";
+        }
+        return "login after signup failed";
+    } except Exception as e {
+        return "error";
+    }
+}
+
+# Logout is synchronous — no await.
+def perform_logout() -> None {
+    jacLogout();
+}
+
+# Typical protected page — inline guard at the top.
+def:pub Dashboard() -> JsxElement {
+    if not jacIsLoggedIn() {
+        return <Navigate to="/login" replace={True} />;
+    }
+    return <div className="p-4">Welcome to the dashboard</div>;
+}
+```
+
+## Auth-relevant `@jac/runtime` exports
+
+`jacLogin`, `jacSignup`, `jacLogout`, `jacIsLoggedIn`, plus `Navigate` / `useNavigate` for post-auth redirects. For the full client export list and the "compile-passes-build-fails" rule, see `jac-cl-components`.
+
+## Pitfalls
+
+- Import auth helpers from `@jac/runtime` — see `jac-core-cheatsheet` for import form rules.
+- Post-logout pattern: `jacLogout(); nav("/login");` — synchronous call, then navigate.
+- Post-login navigation uses `useNavigate()` from `jac-cl-routing` — `nav = useNavigate(); ... nav("/dashboard");` after a successful login.
+- **`jacSignup` does NOT establish a session.** ALWAYS follow with a `jacLogin` call using the same credentials — signup alone leaves the user unauthenticated.
+- **`jacLogin` and `jacSignup` are `async` — always `await`. `jacLogout` and `jacIsLoggedIn` are sync — NEVER `await` them.** `await jacLogout()` type-errors; missing `await` on `jacLogin` silently returns a coroutine instead of the result.
+- **Pre-declare any var that holds an `await` result before the assignment.** In `.cl.jac`, `var = await fn()` can compile to a JS `let var = ...` whose scope is tighter than the surrounding function, so a later `if not var { ... }` throws `ReferenceError: var is not defined` at runtime. Compile passes; the page just blanks. Fix: declare the var with a default at the top, then assign.
+
+```jac
+# FRAGILE — runtime ReferenceError on the if-check
+async def handle_login(email: str, password: str) -> str {
+    ok = await jacLogin(email, password);
+    if not ok { return "failed"; }      # ReferenceError: ok is not defined
+    return "success";
+}
+
+# CORRECT — function-scope let, visible to the if-check
+async def handle_login(email: str, password: str) -> str {
+    ok: bool = False;
+    ok = await jacLogin(email, password);
+    if not ok { return "failed"; }
+    return "success";
+}
+```

{jac_coder-0.2.2 → jac_coder-0.2.3}/jac_coder/skills/jac-cl-components/SKILL.md

@@ -3,7 +3,7 @@ name: jac-cl-components
 description: Writing a client-side UI component — shape, reactive state, mount effects, rendering, event handlers. Load when creating or editing any `.cl.jac` file. Pair with `jac-cl-routing` (multi-page apps), `jac-cl-organization` (file layout & hooks), `jac-cl-auth` (protected pages).
 ---
 
-`.cl.jac` files are client-side Jac. A component is a `def:pub` function returning `JsxElement`. State = `has` fields (assign directly, UI re-renders; NO `useState`/`setX`). Mount effects = `async can with entry`. Event handlers = `def` methods typed with ambient DOM events (`MouseEvent`, `ChangeEvent`, `FormEvent`, `KeyboardEvent`). No `to cl:` header — the extension sets client context.
+`.cl.jac` files are client-side Jac. A component is a `def:pub` function returning `JsxElement`. State = `has` fields, which compile 1:1 to React `useState` — assign directly (`x = x + 1` re-renders; no `setX(...)` call) but all `useState` semantics apply: writes are async, the closure stays stale until the next render. Mount effects = `async can with entry` (compiles to `useEffect`). Event handlers = `def` methods typed with ambient DOM events (`MouseEvent`, `ChangeEvent`, `FormEvent`, `KeyboardEvent`). No `to cl:` header — the extension sets client context.
 
 ```jac
 def:pub Counter() -> JsxElement {
@@ -72,15 +72,39 @@ Fall back to `Any` (capital, built-in) only when you don't read `e`.
 - **Validation / error boundary:** `JacSchema`, `JacClientErrorBoundary`
 - **DO NOT use:** `useState`, `useEffect` (aliases exist but `has` + `async can with entry` are idiomatic)
 
+## ⚠ Critical gotchas (silent runtime bugs — read every time)
+
+- **Hooks + `has` BEFORE any conditional return.** React hooks must fire in the same order every render. `if not jacIsLoggedIn() { return <Navigate />; } has x: int = 0;` → white screen, no compile error.
+- **Mount effects (`async can with entry`) fire even when the component returns `<Navigate>`.** Guard the EFFECT body with `if jacIsLoggedIn() { ... }`, not just the render — otherwise `def:priv` calls fire and return 401 silently.
+
 ## Rules
 
 - **`has` fields are reactive state — assign directly.** `count = count + 1` re-renders. No `setCount`. Non-default fields come before defaulted ones (E2004 — see `jac-has-fields`).
-- **Hooks + `has` BEFORE any conditional return.** React hooks must fire in the same order every render. `if not jacIsLoggedIn() { return <Navigate />; } has x: int = 0;` → white screen, no compile error.
-- **Mount effects (`async can with entry`) fire even when the component returns `<Navigate>`.** Guard the EFFECT body with `if jacIsLoggedIn() { ... }`, not just the render — otherwise `def:priv` calls fire and return 401.
-- **Server RPC import uses `sv import from ...services.X { fn, Types }`** (prefix required). Plain `import from` to a `.sv.jac` breaks the Vite build. Include obj/node types too. See `jac-fullstack-patterns`.
+- **Derived values are locals, not `has` fields.** Anything computable from props/params/hook results gets recomputed every render — so it's a local. Putting it in `has` forces a top-level write to keep it in sync, which can cascade to React error #301. Rule: `has` is only for event-driven or async values (user input, fetch results, server data).
+
+```jac
+# FRAGILE
+has has_filter: bool = False;
+if useParams()["category"] is not None { has_filter = True; }
+
+# CORRECT
+has_filter: bool = useParams()["category"] is not None;
+```
+- **Server RPC import uses `sv import from ...services.X { fn, Types }`** (prefix required). Plain `import from` to a `.sv.jac` breaks the Vite build. Include obj/node types too — they're needed to type your `has` state (next rule). See `jac-fullstack-patterns`.
+- **Type `has` state with the imported `sv` types — `list[Any]` loses the element type.** Store data from `sv import` calls in fields typed with the actual node/obj. Without it, attribute access in loops fails `E1032: Type is Unknown`.
+
+```jac
+sv import from .services.linkedin { Post };
+
+# FRAGILE
+has posts: list[Any] = [];           # E1032 on p.title in any loop
+
+# CORRECT
+has posts: list[Post] = [];          # `p` in `for p in posts` is typed Post
+```
 - **Call server endpoints POSITIONAL, not kwargs.** `save(a, b)` works; `save(a=a, b=b)` sends empty body → 422. Also: the caller's variable names become the JSON keys - they must match the server parameter names exactly. See `jac-fullstack-patterns`.
 - **JSX ternary is Python-style:** `{X if cond else Y}`. NOT `{cond ? X : Y}` (parse error even inside JSX). Short-circuit also works: `{cond and <X />}`.
-- **Iterate with comprehensions, NOT `.map()`.** `items.map(...)` on a Jac list fails E1030. Use `[<li>...</li> for i in items]` inside JSX.
+- **Iterate with comprehensions, NOT `.map()`.** `items.map(...)` on a Jac list fails E1030. Use `[<li>...</li> for i in items]` inside JSX. `for i, x in enumerate(items)` parse-fails E0001 — use a single loop var, or `range(len(items))` with index access: `[<li key={str(i)}>{items[i]}</li> for i in range(len(items))]`.
 - **Dict access uses `[key]`, NOT `.get()`.** `params.get("id")` runtime-fails in browser (`useParams` returns plain JS object). Use `val = params["id"]; if val is None { ... }`.
 - **Guard None/null/undefined when iterating or dotting into server data.** Runtime-only failure (`Cannot read properties of null/undefined`), nothing at compile. Four hot spots — single-level access is the most common:
 
@@ -91,10 +115,10 @@ status = result.recipe.status;                         # result.recipe is None
 rows = [<Card title={s["title"]} /> for s in songs];  # any s is None in list → crash
 first = songs[0]["title"];                             # empty list → crash
 
-# SAFE — narrow, filter, or length-check first (use `!= None`, NOT `is not None` in .cl.jac)
-if result != None { total = result.total_posts; }
-if result.recipe != None { status = result.recipe.status; }
-rows = [<Card ... /> for s in songs if s != None];
+# SAFE — narrow, filter, or length-check first
+if result is not None { total = result.total_posts; }
+if result.recipe is not None { status = result.recipe.status; }
+rows = [<Card ... /> for s in songs if s is not None];
 if len(songs) > 0 { first = songs[0]["title"]; }
 ```
 
@@ -102,11 +126,10 @@ Also works: short-circuit in JSX — `{result and <X total={result.total_posts}
 
 **For server response objects (dicts/lists from `sv import` calls), prefer truthy checks (`if result {`) over `!= None`.** The `!=` operator uses deep equality which calls `Object.keys()` — crashes with `"Cannot convert undefined or null to object"` if the value is `null`/`undefined`. `!= None` is safe for primitives (strings, ints, bools) but not for complex objects returned from server calls.
 - **Event params are typed — `MouseEvent`/`ChangeEvent`/etc.** `e: any` (lowercase) is the Python `any()` builtin, fails E1103. Use capital `Any` (no import) for untyped.
+- **`style` prop takes a `dict[str, object]`, not a CSS string.** `<div style="color: red">` fails E1103. Use inline dict `<div style={{"color": "red"}}>` or move styling to `className` + a CSS file.
 - **JSX uses `className`, curly-brace interpolation `{expr}`, camelCase events** (`onClick`, `onChange`).
 - **No `to cl:` / `cl def:pub` / `cl { }` in `.cl.jac` files.** Extension already sets context. Braced blocks are deprecated (W0064).
 - **Top-level component name is `def:pub app()`** — lowercase. Runtime mounts the literal name.
-- **No JSX comments — `{/* ... */}` is INVALID Jac syntax.** Never write JSX-style comments. Use `# comment` on lines outside JSX blocks, or just delete the comment.
-- **`is not None` is a `.cl.jac` compiler bug — use `!= None`.** Both `x is None` and `x is not None` compile to `x === null` in the generated JS — the `not` is silently dropped. Your guard runs the OPPOSITE of what you wrote (a `for ... if x is not None` comprehension keeps only the nulls). Use `!= None` / `== None` in client code. (Server `.sv.jac` compiles to Python normally and is unaffected.)
 
 ## See also