pulse-framework 0.1.44__py3-none-any.whl → 0.1.47__py3-none-any.whl

pulse/render_session.py

@@ -4,7 +4,7 @@ import traceback
 import uuid
 from asyncio import iscoroutine
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 from pulse.context import PulseContext
 from pulse.helpers import create_future_on_loop, create_task
@@ -14,6 +14,7 @@ from pulse.messages import (
 	ServerErrorMessage,
 	ServerErrorPhase,
 	ServerInitMessage,
+	ServerJsExecMessage,
 	ServerMessage,
 	ServerNavigateToMessage,
 	ServerUpdateMessage,
@@ -30,6 +31,9 @@ from pulse.routing import (
 	ensure_absolute_path,
 )
 from pulse.state import State
+from pulse.transpiler.context import interpreted_mode
+from pulse.transpiler.ids import generate_id
+from pulse.transpiler.nodes import JSExpr
 from pulse.vdom import Element
 
 if TYPE_CHECKING:
@@ -39,21 +43,46 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__file__)
 
 
+class JsExecError(Exception):
+	"""Raised when client-side JS execution fails."""
+
+
+# Module-level convenience wrapper
+@overload
+def run_js(expr: JSExpr | str, *, result: Literal[True]) -> asyncio.Future[Any]: ...
+
+
+@overload
+def run_js(expr: JSExpr | str, *, result: Literal[False] = ...) -> None: ...
+
+
+def run_js(expr: JSExpr | str, *, result: bool = False) -> asyncio.Future[Any] | None:
+	"""Execute JavaScript on the client. Convenience wrapper for RenderSession.run_js()."""
+	ctx = PulseContext.get()
+	if ctx.render is None:
+		raise RuntimeError("run_js() can only be called during callback execution")
+	return ctx.render.run_js(expr, result=result)
+
+
 class RouteMount:
 	render: "RenderSession"
 	route: RouteContext
 	tree: RenderTree
+	effect: Effect | None
+	_pulse_ctx: PulseContext | None
+	element: Element
+	rendered: bool
 
 	def __init__(
 		self, render: "RenderSession", route: Route | Layout, route_info: RouteInfo
 	) -> None:
 		self.render = render
 		self.route = RouteContext(route_info, route)
-		self.effect: Effect | None = None
-		self._pulse_ctx: PulseContext | None = None
-		self.element: Element = route.render()
+		self.effect = None
+		self._pulse_ctx = None
+		self.element = route.render()
 		self.tree = RenderTree(self.element)
-		self.rendered: bool = False
+		self.rendered = False
 
 
 class RenderSession:
@@ -62,6 +91,13 @@ class RenderSession:
 	channels: "ChannelsManager"
 	forms: "FormRegistry"
 	query_store: QueryStore
+	route_mounts: dict[str, RouteMount]
+	_server_address: str | None
+	_client_address: str | None
+	_send_message: Callable[[ServerMessage], Any] | None
+	_pending_api: dict[str, asyncio.Future[dict[str, Any]]]
+	_global_states: dict[str, State]
+	connected: bool
 
 	def __init__(
 		self,
@@ -76,22 +112,22 @@ class RenderSession:
 
 		self.id = id
 		self.routes = routes
-		self.route_mounts: dict[str, RouteMount] = {}
+		self.route_mounts = {}
 		# Base server address for building absolute API URLs (e.g., http://localhost:8000)
-		self._server_address: str | None = server_address
+		self._server_address = server_address
 		# Best-effort client address, captured at prerender or socket connect time
-		self._client_address: str | None = client_address
-		self._send_message: Callable[[ServerMessage], Any] | None = None
-		# Buffer messages emitted before a connection is established
-		self._message_buffer: list[ServerMessage] = []
-		self._pending_api: dict[str, asyncio.Future[dict[str, Any]]] = {}
+		self._client_address = client_address
+		self._send_message = None
+		self._pending_api = {}
 		# Registry of per-session global singletons (created via ps.global_state without id)
-		self._global_states: dict[str, State] = {}
+		self._global_states = {}
 		self.query_store = QueryStore()
 		# Connection state
-		self.connected: bool = False
+		self.connected = False
 		self.channels = ChannelsManager(self)
 		self.forms = FormRegistry(self)
+		# Pending JS execution results (for awaiting run_js().result())
+		self._pending_js_results: dict[str, asyncio.Future[Any]] = {}
 
 	@property
 	def server_address(self) -> str:
@@ -117,25 +153,28 @@ class RenderSession:
 	def connect(self, send_message: Callable[[ServerMessage], Any]):
 		self._send_message = send_message
 		self.connected = True
-		# Flush any buffered messages now that we can send
-		if self._message_buffer:
-			for msg in self._message_buffer:
-				self._send_message(msg)
-			self._message_buffer.clear()
+		# Don't flush buffer or resume effects here - mount() handles reconnection
+		# by resetting mount.rendered and resuming effects to send fresh vdom_init
+
+	def disconnect(self):
+		"""Called when client disconnects - pause render effects."""
+		self._send_message = None
+		self.connected = False
+		for mount in self.route_mounts.values():
+			if mount.effect:
+				mount.effect.pause()
 
 	def send(self, message: ServerMessage):
 		# If a sender is available (connected or during prerender capture), send immediately.
-		# Otherwise, buffer until a connection is established.
+		# Otherwise, drop the message - we'll send full VDOM state on reconnection.
 		if self._send_message:
 			self._send_message(message)
-		else:
-			self._message_buffer.append(message)
 
 	def report_error(
 		self,
 		path: str,
 		phase: ServerErrorPhase,
-		exc: Exception,
+		exc: BaseException,
 		details: dict[str, Any] | None = None,
 	):
 		error_msg: ServerErrorMessage = {
@@ -174,32 +213,24 @@ class RenderSession:
 				self.channels.dispose_channel(channel, reason="render.close")
 		# The effect will be garbage collected, and with it the dependencies
 		self._send_message = None
-		# Discard any buffered messages on close
-		self._message_buffer.clear()
 		self.connected = False
 
 	def execute_callback(self, path: str, key: str, args: list[Any] | tuple[Any, ...]):
 		mount = self.route_mounts[path]
-		try:
-			cb = mount.tree.callbacks[key]
-			fn, n_params = cb.fn, cb.n_args
-			res = fn(*args[:n_params])
-			if iscoroutine(res):
-
-				def _on_task_done(t: asyncio.Task[Any]):
-					try:
-						t.result()
-					except Exception as e:
-						self.report_error(
-							path,
-							"callback",
-							e,
-							{"callback": key, "async": True},
-						)
+		cb = mount.tree.callbacks[key]
+
+		def report(e: BaseException, is_async: bool = False):
+			self.report_error(path, "callback", e, {"callback": key, "async": is_async})
 
-				create_task(res, on_done=_on_task_done)
+		try:
+			with PulseContext.update(render=self, route=mount.route):
+				res = cb.fn(*args[: cb.n_args])
+				if iscoroutine(res):
+					create_task(
+						res, on_done=lambda t: (e := t.exception()) and report(e, True)
+					)
 		except Exception as e:
-			self.report_error(path, "callback", e, {"callback": key})
+			report(e)
 
 	async def call_api(
 		self,
@@ -262,6 +293,94 @@ class RenderSession:
 				}
 			)
 
+	# ---- JS Execution ----
+	@overload
+	def run_js(
+		self, expr: JSExpr | str, *, result: Literal[True]
+	) -> asyncio.Future[object]: ...
+
+	@overload
+	def run_js(self, expr: JSExpr | str, *, result: Literal[False] = ...) -> None: ...
+
+	def run_js(
+		self, expr: JSExpr | str, *, result: bool = False
+	) -> asyncio.Future[object] | None:
+		"""Execute JavaScript on the client.
+
+		Args:
+			expr: A JSExpr (e.g. from calling a @javascript function) or raw JS string.
+			result: If True, returns a Future that resolves with the JS return value.
+			        If False (default), returns None (fire-and-forget).
+
+		Returns:
+			None if result=False, otherwise a Future resolving to the JS result.
+
+		Example - Fire and forget:
+			@javascript
+			def focus_element(selector: str):
+				document.querySelector(selector).focus()
+
+			def on_save():
+				save_data()
+				run_js(focus_element("#next-input"))
+
+		Example - Await result:
+			@javascript
+			def get_scroll_position():
+				return {"x": window.scrollX, "y": window.scrollY}
+
+			async def on_click():
+				pos = await run_js(get_scroll_position(), result=True)
+				print(pos["x"], pos["y"])
+
+		Example - Raw JS string:
+			def on_click():
+				run_js("console.log('Hello from Python!')")
+		"""
+		ctx = PulseContext.get()
+		exec_id = generate_id()
+
+		if isinstance(expr, str):
+			code = expr
+		else:
+			with interpreted_mode():
+				code = expr.emit()
+
+		# Get path from route context, fallback to "/"
+		path = ctx.route.pathname if ctx.route else "/"
+
+		self.send(
+			ServerJsExecMessage(
+				type="js_exec",
+				path=path,
+				id=exec_id,
+				code=code,
+			)
+		)
+
+		if result:
+			loop = asyncio.get_running_loop()
+			future: asyncio.Future[object] = loop.create_future()
+			self._pending_js_results[exec_id] = future
+			return future
+
+		return None
+
+	def handle_js_result(self, data: dict[str, Any]) -> None:
+		"""Handle js_result message from client."""
+		exec_id = data.get("id")
+		if exec_id is None:
+			return
+		exec_id = str(exec_id)
+		fut = self._pending_js_results.pop(exec_id, None)
+		if fut is None or fut.done():
+			return
+		error = data.get("error")
+		if error is not None:
+			fut.set_exception(JsExecError(error))
+		else:
+			fut.set_result(data.get("result"))
+
 	def create_route_mount(self, path: str, route_info: RouteInfo | None = None):
 		route = self.routes.find(path)
 		mount = RouteMount(self, route, route_info or route.default_route_info())
@@ -290,14 +409,15 @@ class RenderSession:
 				if normalized_root is not None:
 					mount.element = normalized_root
 				mount.rendered = True
-				return ServerInitMessage(
+				msg = ServerInitMessage(
 					type="vdom_init",
 					path=path,
 					vdom=vdom,
 					callbacks=sorted(mount.tree.callbacks.keys()),
 					render_props=sorted(mount.tree.render_props),
-					css_refs=sorted(mount.tree.css_refs),
+					jsexpr_paths=sorted(mount.tree.jsexpr_paths),
 				)
+				return msg
 
 		captured: ServerInitMessage | ServerNavigateToMessage | None = None
 
@@ -313,7 +433,7 @@ class RenderSession:
 					vdom=msg.get("vdom"),
 					callbacks=msg.get("callbacks", []),
 					render_props=msg.get("render_props", []),
-					css_refs=msg.get("css_refs", []),
+					jsexpr_paths=msg.get("jsexpr_paths", []),
 				)
 			elif msg["type"] == "navigate_to":
 				captured = ServerNavigateToMessage(
@@ -341,14 +461,15 @@ class RenderSession:
 				if normalized_root is not None:
 					mount.element = normalized_root
 				mount.rendered = True
-			return ServerInitMessage(
+			msg = ServerInitMessage(
 				type="vdom_init",
 				path=path,
 				vdom=vdom,
 				callbacks=sorted(mount.tree.callbacks.keys()),
 				render_props=sorted(mount.tree.render_props),
-				css_refs=sorted(mount.tree.css_refs),
+				jsexpr_paths=sorted(mount.tree.jsexpr_paths),
 			)
+			return msg
 
 		return captured
 
@@ -392,8 +513,14 @@ class RenderSession:
 
 	def mount(self, path: str, route_info: RouteInfo):
 		if path in self.route_mounts:
-			# No logging, this is bound to happen with React strict mode
-			# logger.error(f"Route already mounted: '{path}'")
+			# Route already mounted - this is a reconnection case.
+			# Reset rendered flag so effect sends vdom_init, update route info,
+			# and resume the paused effect.
+			mount = self.route_mounts[path]
+			mount.rendered = False
+			mount.route.update(route_info)
+			if mount.effect and mount.effect.paused:
+				mount.effect.resume()
 			return
 
 		mount = self.create_route_mount(path, route_info)
@@ -412,16 +539,15 @@ class RenderSession:
 						if normalized_root is not None:
 							mount.element = normalized_root
 						mount.rendered = True
-						self.send(
-							ServerInitMessage(
-								type="vdom_init",
-								path=path,
-								vdom=vdom,
-								callbacks=sorted(mount.tree.callbacks.keys()),
-								render_props=sorted(mount.tree.render_props),
-								css_refs=sorted(mount.tree.css_refs),
-							)
+						msg = ServerInitMessage(
+							type="vdom_init",
+							path=path,
+							vdom=vdom,
+							callbacks=sorted(mount.tree.callbacks.keys()),
+							render_props=sorted(mount.tree.render_props),
+							jsexpr_paths=sorted(mount.tree.jsexpr_paths),
 						)
+						self.send(msg)
 					else:
 						ops = mount.tree.diff(mount.element)
 						normalized_root = getattr(mount.tree, "_normalized", None)