jac-client 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

jac_client/tests/test_it.py

@@ -1,4 +1,4 @@
-"""End-to-end tests for `jac serve` HTTP endpoints."""
+"""End-to-end tests for `jac start` HTTP endpoints."""
 
 from __future__ import annotations
 
@@ -7,9 +7,11 @@ import json
 import os
 import shutil
 import socket
+import sys
 import tempfile
 import time
 from http.client import RemoteDisconnected
+from pathlib import Path
 from subprocess import PIPE, Popen, run
 from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
@@ -19,6 +21,37 @@ import pytest
 from jaclang.pycore.runtime import JacRuntime as Jac
 
 
+def _get_jac_command() -> list[str]:
+    """Get the jac command with proper path handling."""
+    jac_path = shutil.which("jac")
+    if jac_path:
+        return [jac_path]
+    return [sys.executable, "-m", "jaclang"]
+
+
+def _get_env_with_npm() -> dict[str, str]:
+    """Get environment dict with npm in PATH."""
+    env = os.environ.copy()
+    npm_path = shutil.which("npm")
+    if npm_path:
+        npm_dir = str(Path(npm_path).parent)
+        current_path = env.get("PATH", "")
+        if npm_dir not in current_path:
+            env["PATH"] = f"{npm_dir}:{current_path}"
+    # Also check common nvm locations
+    nvm_dir = os.environ.get("NVM_DIR", os.path.expanduser("~/.nvm"))
+    nvm_node_bin = Path(nvm_dir) / "versions" / "node"
+    if nvm_node_bin.exists():
+        for version_dir in nvm_node_bin.iterdir():
+            bin_dir = version_dir / "bin"
+            if bin_dir.exists() and (bin_dir / "npm").exists():
+                current_path = env.get("PATH", "")
+                if str(bin_dir) not in current_path:
+                    env["PATH"] = f"{bin_dir}:{current_path}"
+                break
+    return env
+
+
 @pytest.fixture(autouse=True)
 def reset_jac_machine():
     """Reset Jac machine before and after each test."""
@@ -207,99 +240,84 @@ def test_all_in_one_app_endpoints() -> None:
                     f"STDERR:\n{jac_add_result.stderr}\n"
                 )
 
-            app_jac_path = os.path.join(project_path, "src", "app.jac")
+            app_jac_path = os.path.join(project_path, "app.jac")
             assert os.path.isfile(app_jac_path), "all-in-one src/app.jac file missing"
 
-            # 4. Start the server: `jac serve src/app.jac`
+            # 4. Start the server: `jac start src/app.jac`
             # NOTE: We don't use text mode here, so `Popen` defaults to bytes.
             # Use `Popen[bytes]` in the type annotation to keep mypy happy.
             server: Popen[bytes] | None = None
             try:
-                print("[DEBUG] Starting server with 'jac serve src/app.jac'")
+                print("[DEBUG] Starting server with 'jac start src/app.jac'")
                 server = Popen(
-                    ["jac", "serve", "src/app.jac"],
+                    ["jac", "start", "src/app.jac"],
                     cwd=project_path,
                 )
-
                 # Wait for localhost:8000 to become available
                 print("[DEBUG] Waiting for server to be available on 127.0.0.1:8000")
                 _wait_for_port("127.0.0.1", 8000, timeout=90.0)
                 print("[DEBUG] Server is now accepting connections on 127.0.0.1:8000")
 
-                # "/" – server up
+                # "/" – server up (serves client app HTML due to base_route_app="app")
+                # Note: The root endpoint may return 503 while the client bundle is building.
+                # We use _wait_for_endpoint to retry on 503 until it's ready.
                 try:
-                    print("[DEBUG] Sending GET request to root endpoint /")
-                    with urlopen(
+                    print("[DEBUG] Sending GET request to root endpoint / (with retry)")
+                    root_bytes = _wait_for_endpoint(
                         "http://127.0.0.1:8000",
-                        timeout=10,
-                    ) as resp_root:
-                        root_body = resp_root.read().decode("utf-8", errors="ignore")
-                        print(
-                            "[DEBUG] Received response from root endpoint /\n"
-                            f"Status: {resp_root.status}\n"
-                            f"Body (truncated to 500 chars):\n{root_body[:500]}"
-                        )
-                        assert resp_root.status == 200
-                        assert '"Jac API Server"' in root_body
-                        assert '"endpoints"' in root_body
-
-                        # Verify custom headers from jac.toml are present
-                        assert (
-                            resp_root.headers.get("Cross-Origin-Opener-Policy")
-                            == "same-origin"
-                        ), (
-                            "Expected Cross-Origin-Opener-Policy header to be 'same-origin'"
-                        )
-                        assert (
-                            resp_root.headers.get("Cross-Origin-Embedder-Policy")
-                            == "require-corp"
-                        ), (
-                            "Expected Cross-Origin-Embedder-Policy header to be 'require-corp'"
-                        )
-                        print(
-                            "[DEBUG] Custom headers verified: COOP and COEP are present"
-                        )
-                except (URLError, HTTPError) as exc:
+                        timeout=120.0,
+                        poll_interval=2.0,
+                        request_timeout=30.0,
+                    )
+                    root_body = root_bytes.decode("utf-8", errors="ignore")
+                    print(
+                        "[DEBUG] Received response from root endpoint /\n"
+                        f"Body (truncated to 500 chars):\n{root_body[:500]}"
+                    )
+                    # With base_route_app="app", root serves client HTML
+                    assert "<!DOCTYPE html>" in root_body or "<html" in root_body
+                    assert '<div id="root">' in root_body
+                except (URLError, HTTPError, TimeoutError) as exc:
                     print(f"[DEBUG] Error while requesting root endpoint: {exc}")
                     pytest.fail(f"Failed to GET root endpoint: {exc}")
 
-                # "/page/app" – main page is loading
+                # "/cl/app" – main page is loading
                 # Note: This endpoint may return 503 (temporary) while the page is being compiled,
                 # or 500 (permanent) if there's a compilation error. We use _wait_for_endpoint
                 # to retry on 503 until it's ready, but it will fail immediately on 500.
                 try:
                     print(
-                        "[DEBUG] Sending GET request to /page/app endpoint (with retry)"
+                        "[DEBUG] Sending GET request to /cl/app endpoint (with retry)"
                     )
                     page_bytes = _wait_for_endpoint(
-                        "http://127.0.0.1:8000/page/app",
+                        "http://127.0.0.1:8000/cl/app",
                         timeout=120.0,
                         poll_interval=2.0,
                         request_timeout=30.0,
                     )
                     page_body = page_bytes.decode("utf-8", errors="ignore")
                     print(
-                        "[DEBUG] Received response from /page/app endpoint\n"
+                        "[DEBUG] Received response from /cl/app endpoint\n"
                         f"Body (truncated to 500 chars):\n{page_body[:500]}"
                     )
                     assert "<html" in page_body.lower()
                 except (URLError, HTTPError, TimeoutError, RemoteDisconnected) as exc:
-                    print(f"[DEBUG] Error while requesting /page/app endpoint: {exc}")
-                    pytest.fail(f"Failed to GET /page/app endpoint: {exc}")
+                    print(f"[DEBUG] Error while requesting /cl/app endpoint: {exc}")
+                    pytest.fail(f"Failed to GET /cl/app endpoint: {exc}")
 
-                # "/page/app#/nested" – relative paths / nested route
+                # "/cl/app#/nested" – relative paths / nested route
                 # (hash fragment is client-side only but server should still serve the app shell)
                 try:
-                    print("[DEBUG] Sending GET request to /page/app#/nested endpoint")
+                    print("[DEBUG] Sending GET request to /cl/app#/nested endpoint")
                     with urlopen(
-                        "http://127.0.0.1:8000/page/app#/nested",
+                        "http://127.0.0.1:8000/cl/app#/nested",
                         timeout=200,
                     ) as resp_nested:
                         nested_body = resp_nested.read().decode(
                             "utf-8", errors="ignore"
                         )
                         print(
-                            "[DEBUG] Received response from /page/app#/nested endpoint\n"
+                            "[DEBUG] Received response from /cl/app#/nested endpoint\n"
                             f"Status: {resp_nested.status}\n"
                             f"Body (truncated to 500 chars):\n{nested_body[:500]}"
                         )
@@ -307,31 +325,12 @@ def test_all_in_one_app_endpoints() -> None:
                         assert "<html" in nested_body.lower()
                 except (URLError, HTTPError) as exc:
                     print(
-                        f"[DEBUG] Error while requesting /page/app#/nested endpoint: {exc}"
+                        f"[DEBUG] Error while requesting /cl/app#/nested endpoint: {exc}"
                     )
-                    pytest.fail("Failed to GET /page/app#/nested endpoint")
+                    pytest.fail("Failed to GET /cl/app#/nested endpoint")
 
-                # "/static/main.css" – CSS compiled and serving
-                # Note: CSS may be compiled asynchronously, so we retry if it's not ready
-                try:
-                    print(
-                        "[DEBUG] Sending GET request to /static/main.css (with retry)"
-                    )
-                    css_bytes = _wait_for_endpoint(
-                        "http://127.0.0.1:8000/static/main.css",
-                        timeout=60.0,
-                        poll_interval=2.0,
-                        request_timeout=20.0,
-                    )
-                    css_body = css_bytes.decode("utf-8", errors="ignore")
-                    print(
-                        "[DEBUG] Received response from /static/main.css\n"
-                        f"Body (truncated to 500 chars):\n{css_body[:500]}"
-                    )
-                    assert len(css_body.strip()) > 0, "CSS file should not be empty"
-                except (URLError, HTTPError, TimeoutError, RemoteDisconnected) as exc:
-                    print(f"[DEBUG] Error while requesting /static/main.css: {exc}")
-                    pytest.fail(f"Failed to GET /static/main.css after retries: {exc}")
+                # Note: CSS serving is tested separately in test_css_with_image
+                # The CSS is bundled into client.js so no separate /static/styles.css endpoint
 
                 # "/static/assets/burger.png" – static files are loading
                 try:
@@ -434,7 +433,7 @@ def test_all_in_one_app_endpoints() -> None:
                         assert resp_create.status == 200
                         # Basic sanity check: created Todo text should appear in the response payload.
                         assert "Sample todo from all-in-one app" in create_body
-                except (URLError, HTTPError) as exc:
+                except (URLError, HTTPError, RemoteDisconnected) as exc:
                     print(f"[DEBUG] Error while requesting /walker/create_todo: {exc}")
                     pytest.fail("Failed to POST /walker/create_todo")
 
@@ -463,7 +462,9 @@ def test_all_in_one_app_endpoints() -> None:
                             f"Body (truncated to 500 chars):\n{register_body[:500]}"
                         )
                         assert resp_register.status == 201
-                        register_data = json.loads(register_body)
+                        register_response = json.loads(register_body)
+                        # Handle new TransportResponse envelope format
+                        register_data = register_response.get("data", register_response)
                         assert "username" in register_data
                         assert "token" in register_data
                         assert "root_id" in register_data
@@ -475,7 +476,7 @@ def test_all_in_one_app_endpoints() -> None:
                             f"Token: {register_data['token'][:20]}...\n"
                             f"Root ID: {register_data['root_id']}"
                         )
-                except (URLError, HTTPError) as exc:
+                except (URLError, HTTPError, RemoteDisconnected) as exc:
                     print(f"[DEBUG] Error while requesting /user/register: {exc}")
                     pytest.fail("Failed to POST /user/register")
 
@@ -500,14 +501,16 @@ def test_all_in_one_app_endpoints() -> None:
                             f"Body (truncated to 500 chars):\n{login_body[:500]}"
                         )
                         assert resp_login.status == 200
-                        login_data = json.loads(login_body)
+                        login_response = json.loads(login_body)
+                        # Handle new TransportResponse envelope format
+                        login_data = login_response.get("data", login_response)
                         assert "token" in login_data
                         assert len(login_data["token"]) > 0
                         print(
                             f"[DEBUG] Successfully logged in user: {test_username}\n"
                             f"Token: {login_data['token'][:20]}..."
                         )
-                except (URLError, HTTPError) as exc:
+                except (URLError, HTTPError, RemoteDisconnected) as exc:
                     print(f"[DEBUG] Error while requesting /user/login: {exc}")
                     pytest.fail("Failed to POST /user/login")
 
@@ -552,14 +555,14 @@ def test_all_in_one_app_endpoints() -> None:
                         assert http_err.code in (400, 401, 403), (
                             f"Expected 400/401/403 for invalid login, got {http_err.code}"
                         )
-                except URLError as exc:
+                except (URLError, RemoteDisconnected) as exc:
                     print(
                         f"[DEBUG] Unexpected error while testing invalid login: {exc}"
                     )
                     pytest.fail("Unexpected error testing invalid login")
 
                 # Verify TypeScript component is working - check that page loads with TS component
-                # The /page/app endpoint should serve the app which includes the TypeScript Card component
+                # The /cl/app endpoint should serve the app which includes the TypeScript Card component
                 try:
                     print("[DEBUG] Verifying TypeScript component integration")
                     # The page should load successfully (already tested above)
@@ -570,12 +573,10 @@ def test_all_in_one_app_endpoints() -> None:
                     print(f"[DEBUG] Error verifying TypeScript component: {exc}")
                     pytest.fail("Failed to verify TypeScript component integration")
 
-                # Verify nested folder imports are working - /page/app#/nested route
+                # Verify nested folder imports are working - /cl/app#/nested route
                 # This route uses nested folder imports (components.button and button)
                 try:
-                    print(
-                        "[DEBUG] Verifying nested folder imports via /page/app#/nested"
-                    )
+                    print("[DEBUG] Verifying nested folder imports via /cl/app#/nested")
                     # The nested route should load successfully (already tested above)
                     # Nested imports are compiled and included in the bundle
                     assert "<html" in nested_body.lower(), (
@@ -607,3 +608,217 @@ def test_all_in_one_app_endpoints() -> None:
             os.chdir(original_cwd)
             # Final garbage collection to ensure all resources are released
             gc.collect()
+
+
+def test_default_client_app_renders() -> None:
+    """Test that a default `jac create --cl` app renders correctly when served.
+
+    This test validates the out-of-the-box experience:
+    1. Creates a new client app using `jac create --cl`
+    2. Installs packages
+    3. Starts the server
+    4. Validates that the default app renders with expected content
+    """
+    print("[DEBUG] Starting test_default_client_app_renders")
+
+    app_name = "e2e-default-app"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        print(f"[DEBUG] Created temporary directory at {temp_dir}")
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(temp_dir)
+            print(f"[DEBUG] Changed working directory to {temp_dir}")
+
+            # 1. Create a new default Jac client app
+            jac_cmd = _get_jac_command()
+            env = _get_env_with_npm()
+            print(f"[DEBUG] Running '{' '.join(jac_cmd)} create --cl {app_name}'")
+            process = Popen(
+                [*jac_cmd, "create", "--cl", app_name],
+                stdin=PIPE,
+                stdout=PIPE,
+                stderr=PIPE,
+                text=True,
+                env=env,
+            )
+            stdout, stderr = process.communicate()
+            returncode = process.returncode
+
+            print(
+                f"[DEBUG] 'jac create --cl' completed returncode={returncode}\n"
+                f"STDOUT:\n{stdout}\n"
+                f"STDERR:\n{stderr}\n"
+            )
+
+            if returncode != 0 and "unrecognized arguments: --cl" in stderr:
+                pytest.fail(
+                    "Test failed: installed `jac` CLI does not support `create --cl`."
+                )
+
+            assert returncode == 0, (
+                f"jac create --cl failed\nSTDOUT:\n{stdout}\nSTDERR:\n{stderr}\n"
+            )
+
+            project_path = os.path.join(temp_dir, app_name)
+            print(f"[DEBUG] Created default Jac client app at {project_path}")
+            assert os.path.isdir(project_path)
+
+            # Verify expected files were created (new structure: main.jac at root)
+            main_jac_path = os.path.join(project_path, "main.jac")
+            assert os.path.isfile(main_jac_path), (
+                "main.jac should exist at project root"
+            )
+
+            # Components are now at root level (not src/components)
+            button_jac_path = os.path.join(project_path, "components", "Button.cl.jac")
+            assert os.path.isfile(button_jac_path), (
+                "components/Button.cl.jac should exist"
+            )
+
+            jac_toml_path = os.path.join(project_path, "jac.toml")
+            assert os.path.isfile(jac_toml_path), "jac.toml should exist"
+
+            # 2. Ensure packages are installed (jac create --cl should have done this)
+            # If node_modules doesn't exist, run jac add --cl
+            node_modules_path = os.path.join(
+                project_path, ".jac", "client", "node_modules"
+            )
+            if not os.path.isdir(node_modules_path):
+                print("[DEBUG] node_modules not found, running 'jac add --cl'")
+                jac_add_result = run(
+                    [*jac_cmd, "add", "--cl"],
+                    cwd=project_path,
+                    capture_output=True,
+                    text=True,
+                    env=env,
+                )
+                print(
+                    f"[DEBUG] 'jac add --cl' completed returncode={jac_add_result.returncode}\n"
+                    f"STDOUT (truncated):\n{jac_add_result.stdout[:1000]}\n"
+                    f"STDERR (truncated):\n{jac_add_result.stderr[:1000]}\n"
+                )
+                if jac_add_result.returncode != 0:
+                    pytest.fail(
+                        f"jac add --cl failed\n"
+                        f"STDOUT:\n{jac_add_result.stdout}\n"
+                        f"STDERR:\n{jac_add_result.stderr}\n"
+                    )
+
+            # 3. Start the server (now uses main.jac at project root)
+            server: Popen[bytes] | None = None
+            try:
+                print("[DEBUG] Starting server with 'jac start main.jac'")
+                server = Popen(
+                    [*jac_cmd, "start", "main.jac"],
+                    cwd=project_path,
+                    env=env,
+                )
+
+                # Wait for server to be ready
+                print("[DEBUG] Waiting for server on 127.0.0.1:8000")
+                _wait_for_port("127.0.0.1", 8000, timeout=90.0)
+                print("[DEBUG] Server is accepting connections")
+
+                # 4. Test root endpoint - for client-only apps, root serves the HTML app
+                # Note: The root endpoint may return 503 while the client bundle is building.
+                # We use _wait_for_endpoint to retry on 503 until it's ready.
+                try:
+                    print("[DEBUG] Testing root endpoint / (with retry)")
+                    root_bytes = _wait_for_endpoint(
+                        "http://127.0.0.1:8000",
+                        timeout=120.0,
+                        poll_interval=2.0,
+                        request_timeout=30.0,
+                    )
+                    root_body = root_bytes.decode("utf-8", errors="ignore")
+                    print(
+                        f"[DEBUG] Root response:\nBody (truncated):\n{root_body[:500]}"
+                    )
+                    # For client-only apps, root returns HTML with the React app
+                    assert "<html" in root_body.lower(), (
+                        "Root should return HTML for client-only app"
+                    )
+                    assert "<script" in root_body.lower(), (
+                        "Root should include script tag for client bundle"
+                    )
+                except (URLError, HTTPError, TimeoutError) as exc:
+                    print(f"[DEBUG] Error at root endpoint: {exc}")
+                    pytest.fail(f"Failed to GET root endpoint: {exc}")
+
+                # 5. Test client app endpoint - the rendered React app
+                try:
+                    print("[DEBUG] Testing client app endpoint /cl/app")
+                    page_bytes = _wait_for_endpoint(
+                        "http://127.0.0.1:8000/cl/app",
+                        timeout=120.0,
+                        poll_interval=2.0,
+                        request_timeout=30.0,
+                    )
+                    page_body = page_bytes.decode("utf-8", errors="ignore")
+                    print(
+                        f"[DEBUG] Client app response:\n"
+                        f"Body (truncated):\n{page_body[:1000]}"
+                    )
+
+                    # Validate HTML structure
+                    assert "<html" in page_body.lower(), "Response should contain HTML"
+                    assert "<body" in page_body.lower(), "Response should contain body"
+
+                    # The page should include the bundled JavaScript
+                    # that will render "Hello, World!" client-side
+                    assert (
+                        "<script" in page_body.lower() or "src=" in page_body.lower()
+                    ), "Response should include script tags for React app"
+
+                except (URLError, HTTPError, TimeoutError) as exc:
+                    print(f"[DEBUG] Error at /cl/app endpoint: {exc}")
+                    pytest.fail(f"Failed to GET /cl/app endpoint: {exc}")
+
+                # 6. Test that static JS bundle is being served
+                try:
+                    print("[DEBUG] Testing that client.js bundle is served")
+                    # Extract the client.js path from the HTML
+                    import re
+
+                    script_match = re.search(
+                        r'src="(/static/client\.js[^"]*)"', root_body
+                    )
+                    if script_match:
+                        js_path = script_match.group(1)
+                        js_url = f"http://127.0.0.1:8000{js_path}"
+                        print(f"[DEBUG] Fetching JS bundle from {js_url}")
+                        with urlopen(js_url, timeout=30) as resp:
+                            js_body = resp.read().decode("utf-8", errors="ignore")
+                            assert resp.status == 200, "JS bundle should return 200"
+                            assert len(js_body) > 0, "JS bundle should not be empty"
+                            print(
+                                f"[DEBUG] JS bundle fetched successfully "
+                                f"({len(js_body)} bytes)"
+                            )
+                    else:
+                        print("[DEBUG] Warning: Could not find client.js in HTML")
+                except (URLError, HTTPError) as exc:
+                    print(f"[DEBUG] Warning: Could not verify static assets: {exc}")
+                    # Not a hard failure - the main page test is sufficient
+
+                print("[DEBUG] All default app tests passed!")
+
+            finally:
+                if server is not None:
+                    print("[DEBUG] Terminating server process")
+                    server.terminate()
+                    try:
+                        server.wait(timeout=15)
+                        print("[DEBUG] Server terminated cleanly")
+                    except Exception:
+                        print("[DEBUG] Server did not terminate cleanly, killing")
+                        server.kill()
+                        server.wait(timeout=5)
+                    time.sleep(1)
+                    gc.collect()
+
+        finally:
+            print(f"[DEBUG] Restoring working directory to {original_cwd}")
+            os.chdir(original_cwd)
+            gc.collect()

{jac_client-0.2.6.dist-info → jac_client-0.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jac-client
-Version: 0.2.6
+Version: 0.2.8
 Summary: Build full-stack web applications with Jac - one language for frontend and backend.
 Author-email: Jason Mars <jason@mars.ninja>
 Maintainer-email: Jason Mars <jason@mars.ninja>
@@ -11,7 +11,7 @@ Project-URL: Documentation, https://jac-lang.org
 Keywords: jac,jaclang,jaseci,frontend,full-stack,web-development
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: jaclang==0.9.6
+Requires-Dist: jaclang==0.9.8
 Provides-Extra: dev
 Requires-Dist: python-dotenv==1.0.1; extra == "dev"
 Requires-Dist: pytest==8.3.5; extra == "dev"
@@ -28,7 +28,7 @@ Jac Client enables you to write React-like components, manage state, and build i
 
 - **Single Language**: Write frontend and backend in Jac
 - **No HTTP Client**: Use `jacSpawn()` instead of fetch/axios
-- **React Hooks**: Use standard React `useState` and `useEffect` hooks
+- **React Hooks**: Use standard React `useState` and `useEffect` hooks (useState is auto-injected when using `has` variables)
 - **Component-Based**: Build reusable UI components with JSX
 - **Graph Database**: Built-in graph data model eliminates need for SQL/NoSQL
 - **Type Safety**: Type checking across frontend and backend
@@ -49,10 +49,12 @@ pip install jac-client
 ```bash
 jac create --cl my-app
 cd my-app
-jac serve src/app.jac
+jac start src/app.jac
 ```
 
-Visit `http://localhost:8000/page/app` to see your app!
+Visit `http://localhost:8000` to see your app! (The `app` component is served at the root by default.)
+
+You can also access the app at `http://localhost:8000/cl/app`.
 
 > **Note**: The `--cl` flag creates a client-side project with an organized folder structure. Without `--cl`, `jac create` creates a standard Jac project.
 
@@ -75,10 +77,13 @@ For detailed guides and tutorials, see the **[docs folder](jac_client/docs/)**:
 ### Simple Counter with React Hooks
 
 ```jac
-cl import from react { useState, useEffect }
+# Note: useState is auto-injected when using has variables in cl blocks
+# Only useEffect needs explicit import
+cl import from react { useEffect }
 
 cl {
     def Counter() -> any {
+        # useState is automatically available - no import needed!
         [count, setCount] = useState(0);
 
         useEffect(lambda -> None {
@@ -101,10 +106,13 @@ cl {
 }
 ```
 
+> **Note:** When using `has` variables in `cl {}` blocks or `.cl.jac` files, the `useState` import is automatically injected. You only need to explicitly import other hooks like `useEffect`.
+
 ### Full-Stack Todo App
 
 ```jac
-cl import from react { useState, useEffect }
+# useState is auto-injected, only import useEffect
+cl import from react { useEffect }
 cl import from '@jac-client/utils' { jacSpawn }
 
 # Backend: Jac nodes and walkers
@@ -130,6 +138,7 @@ walker read_todos {
 # Frontend: React component
 cl {
     def app() -> any {
+        # useState is automatically available - no import needed!
         [todos, setTodos] = useState([]);
 
         useEffect(lambda -> None {