pulse-framework 0.1.46__py3-none-any.whl → 0.1.48__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,6 +43,27 @@ 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
@@ -101,6 +126,8 @@ class RenderSession:
 		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:
@@ -147,7 +174,7 @@ class RenderSession:
 		self,
 		path: str,
 		phase: ServerErrorPhase,
-		exc: Exception,
+		exc: BaseException,
 		details: dict[str, Any] | None = None,
 	):
 		error_msg: ServerErrorMessage = {
@@ -190,26 +217,20 @@ class RenderSession:
 
 	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]
 
-				create_task(res, on_done=_on_task_done)
+		def report(e: BaseException, is_async: bool = False):
+			self.report_error(path, "callback", e, {"callback": key, "async": is_async})
+
+		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,
@@ -272,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())
@@ -300,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
 
@@ -323,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(
@@ -351,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
 
@@ -428,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)

pulse/renderer.py

@@ -1,17 +1,12 @@
 import inspect
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
-from typing import (
-	Any,
-	Literal,
-	NamedTuple,
-	TypeAlias,
-	TypedDict,
-	cast,
-)
+from typing import Any, NamedTuple, TypeAlias, cast
 
-from pulse.css import CssReference
 from pulse.helpers import values_equal
+from pulse.transpiler.context import interpreted_mode
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import JSExpr
 from pulse.vdom import (
 	VDOM,
 	Callback,
@@ -19,79 +14,33 @@ from pulse.vdom import (
 	ComponentNode,
 	Element,
 	Node,
+	PathDelta,
 	Props,
+	ReconciliationOperation,
+	ReplaceOperation,
+	UpdateCallbacksOperation,
+	UpdateJsExprPathsOperation,
+	UpdatePropsDelta,
+	UpdatePropsOperation,
+	UpdateRenderPropsOperation,
 	VDOMNode,
+	VDOMOperation,
 )
 
 
-class ReplaceOperation(TypedDict):
-	type: Literal["replace"]
-	path: str
-	data: VDOM
-
-
-# This payload makes it easy for the client to rebuild an array of React nodes
-# from the previous children array:
-# - Allocate array of size N
-# - For i in 0..N-1, check the following scenarios
-#   - i matches the next index in `new` -> use provided tree
-#   - i matches the next index in `reuse` -> reuse previous child
-#   - otherwise, reuse the element at the same index
-class ReconciliationOperation(TypedDict):
-	type: Literal["reconciliation"]
-	path: str
-	N: int
-	new: tuple[list[int], list[VDOM]]
-	reuse: tuple[list[int], list[int]]
-
-
-class UpdatePropsDelta(TypedDict, total=False):
-	# Only send changed/new keys under `set` and removed keys under `remove`
-	set: Props
-	remove: list[str]
-
-
-class UpdatePropsOperation(TypedDict):
-	type: Literal["update_props"]
-	path: str
-	data: UpdatePropsDelta
+def is_jsexpr(value: object) -> bool:
+	"""Check if a value is a JSExpr or Import."""
+	return isinstance(value, (JSExpr, Import))
 
 
-class PathDelta(TypedDict, total=False):
-	add: list[str]
-	remove: list[str]
+def emit_jsexpr(value: "JSExpr | Import") -> str:
+	"""Emit a JSExpr in interpreted mode (for client-side evaluation)."""
+	with interpreted_mode():
+		if isinstance(value, Import):
+			return value.emit()
+		return value.emit()
 
 
-class UpdateCallbacksOperation(TypedDict):
-	type: Literal["update_callbacks"]
-	path: str
-	data: PathDelta
-
-
-class UpdateCssRefsOperation(TypedDict):
-	type: Literal["update_css_refs"]
-	path: str
-	data: PathDelta
-
-
-class UpdateRenderPropsOperation(TypedDict):
-	type: Literal["update_render_props"]
-	path: str
-	data: PathDelta
-
-
-VDOMOperation: TypeAlias = (
-	# InsertOperation,
-	# RemoveOperation,
-	ReplaceOperation
-	| UpdatePropsOperation
-	# | MoveOperation,
-	| ReconciliationOperation
-	| UpdateCallbacksOperation
-	| UpdateCssRefsOperation
-	| UpdateRenderPropsOperation
-)
-
 RenderPath: TypeAlias = str
 
 
@@ -99,13 +48,13 @@ class RenderTree:
 	root: Element
 	callbacks: Callbacks
 	render_props: set[str]
-	css_refs: set[str]
+	jsexpr_paths: set[str]  # paths containing JS expressions
 
 	def __init__(self, root: Element) -> None:
 		self.root = root
 		self.callbacks = {}
 		self.render_props = set()
-		self.css_refs = set()
+		self.jsexpr_paths = set()
 		self.normalized: Element | None = None
 
 	def render(self) -> VDOM:
@@ -114,7 +63,7 @@ class RenderTree:
 		self.root = normalized
 		self.callbacks = renderer.callbacks
 		self.render_props = renderer.render_props
-		self.css_refs = renderer.css_refs
+		self.jsexpr_paths = renderer.jsexpr_paths
 		self.normalized = normalized
 		return vdom
 
@@ -135,23 +84,8 @@ class RenderTree:
 		render_props_add = sorted(render_props_next - render_props_prev)
 		render_props_remove = sorted(render_props_prev - render_props_next)
 
-		css_prev = self.css_refs
-		css_next = renderer.css_refs
-		css_add = sorted(css_next - css_prev)
-		css_remove = sorted(css_prev - css_next)
-
 		prefix: list[VDOMOperation] = []
 
-		if css_add or css_remove:
-			css_delta: PathDelta = {}
-			if css_add:
-				css_delta["add"] = css_add
-			if css_remove:
-				css_delta["remove"] = css_remove
-			prefix.append(
-				UpdateCssRefsOperation(type="update_css_refs", path="", data=css_delta)
-			)
-
 		if callback_add or callback_remove:
 			callback_delta: PathDelta = {}
 			if callback_add:
@@ -176,11 +110,27 @@ class RenderTree:
 				)
 			)
 
+		jsexpr_prev = self.jsexpr_paths
+		jsexpr_next = renderer.jsexpr_paths
+		jsexpr_add = sorted(jsexpr_next - jsexpr_prev)
+		jsexpr_remove = sorted(jsexpr_prev - jsexpr_next)
+		if jsexpr_add or jsexpr_remove:
+			jsexpr_delta: PathDelta = {}
+			if jsexpr_add:
+				jsexpr_delta["add"] = jsexpr_add
+			if jsexpr_remove:
+				jsexpr_delta["remove"] = jsexpr_remove
+			prefix.append(
+				UpdateJsExprPathsOperation(
+					type="update_jsexpr_paths", path="", data=jsexpr_delta
+				)
+			)
+
 		ops = prefix + renderer.operations if prefix else renderer.operations
 
 		self.callbacks = renderer.callbacks
 		self.render_props = renderer.render_props
-		self.css_refs = renderer.css_refs
+		self.jsexpr_paths = renderer.jsexpr_paths
 		self.normalized = normalized
 		self.root = normalized
 
@@ -192,7 +142,11 @@ class RenderTree:
 			self.normalized = None
 		self.callbacks.clear()
 		self.render_props.clear()
-		self.css_refs.clear()
+		self.jsexpr_paths.clear()
+
+
+# Prefix for JSExpr values - code is embedded after the colon
+JSEXPR_PREFIX = "$js:"
 
 
 @dataclass(slots=True)
@@ -214,7 +168,7 @@ class Renderer:
 	def __init__(self) -> None:
 		self.callbacks: Callbacks = {}
 		self.render_props: set[str] = set()
-		self.css_refs: set[str] = set()
+		self.jsexpr_paths: set[str] = set()
 		self.operations: list[VDOMOperation] = []
 
 	# ------------------------------------------------------------------
@@ -226,6 +180,13 @@ class Renderer:
 			return self.render_component(node, path)
 		if isinstance(node, Node):
 			return self.render_node(node, path)
+		# Handle JSExpr as children - emit JS code with $js: prefix
+		if is_jsexpr(node):
+			# Safe cast: is_jsexpr() ensures node is JSExpr | Import
+			node_as_jsexpr = cast("JSExpr | Import", cast(object, node))
+			js_code = emit_jsexpr(node_as_jsexpr)
+			self.jsexpr_paths.add(path)
+			return f"{JSEXPR_PREFIX}{js_code}", cast(Element, node)
 		return node, node
 
 	def render_component(
@@ -453,28 +414,23 @@ class Renderer:
 			old_value = previous.get(key)
 			prop_path = join_path(path, key)
 
-			if callable(value):
-				if isinstance(old_value, (Node, ComponentNode)):
-					unmount_element(old_value)
-				if normalized is None:
-					normalized = current.copy()
-				normalized[key] = "$cb"
-				register_callback(
-					self.callbacks, prop_path, cast(Callable[..., Any], value)
-				)
-				if old_value != "$cb":
-					updated[key] = "$cb"
-				continue
-
-			if isinstance(value, CssReference):
+			if is_jsexpr(value):
 				if isinstance(old_value, (Node, ComponentNode)):
 					unmount_element(old_value)
 				if normalized is None:
 					normalized = current.copy()
 				normalized[key] = value
-				self.css_refs.add(prop_path)
-				if not isinstance(old_value, CssReference) or old_value != value:
-					updated[key] = _css_ref_token(value)
+				# Emit the JSExpr with $js: prefix - code is embedded in the value
+				js_code = emit_jsexpr(cast("JSExpr | Import", value))
+				self.jsexpr_paths.add(prop_path)
+				js_value = f"{JSEXPR_PREFIX}{js_code}"
+				old_js_code = (
+					emit_jsexpr(cast("JSExpr | Import", old_value))
+					if is_jsexpr(old_value)
+					else None
+				)
+				if old_js_code != js_code:
+					updated[key] = js_value
 				continue
 
 			if isinstance(value, (Node, ComponentNode)):
@@ -497,6 +453,19 @@ class Renderer:
 					updated[key] = vdom_value
 				continue
 
+			if callable(value):
+				if isinstance(old_value, (Node, ComponentNode)):
+					unmount_element(old_value)
+				if normalized is None:
+					normalized = current.copy()
+				normalized[key] = "$cb"
+				register_callback(
+					self.callbacks, prop_path, cast(Callable[..., Any], value)
+				)
+				if old_value != "$cb":
+					updated[key] = "$cb"
+				continue
+
 			if isinstance(old_value, (Node, ComponentNode)):
 				unmount_element(old_value)
 
@@ -558,10 +527,6 @@ def same_node(left: Element, right: Element) -> bool:
 	return False
 
 
-def _css_ref_token(ref: CssReference) -> str:
-	return f"{ref.module.id}:{ref.name}"
-
-
 def unmount_element(element: Element) -> None:
 	if isinstance(element, ComponentNode):
 		if element.contents is not None:

pulse/routing.py

@@ -3,7 +3,6 @@ from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import TypedDict, cast, override
 
-from pulse.css import CssImport, CssModule
 from pulse.env import env
 from pulse.react_component import ReactComponent
 from pulse.reactive_extensions import ReactiveDict
@@ -160,8 +159,6 @@ class Route:
 	render: Component[[]]
 	children: Sequence["Route | Layout"]
 	components: Sequence[ReactComponent[...]] | None
-	css_modules: Sequence[CssModule] | None
-	css_imports: Sequence[CssImport] | None
 	is_index: bool
 	is_dynamic: bool
 	dev: bool
@@ -172,8 +169,6 @@ class Route:
 		render: Component[[]],
 		children: "Sequence[Route | Layout] | None" = None,
 		components: "Sequence[ReactComponent[...]] | None" = None,
-		css_modules: Sequence[CssModule] | None = None,
-		css_imports: Sequence[CssImport] | None = None,
 		dev: bool = False,
 	):
 		self.path = ensure_relative_path(path)
@@ -182,8 +177,6 @@ class Route:
 		self.render = render
 		self.children = children or []
 		self.components = components
-		self.css_modules = css_modules
-		self.css_imports = css_imports
 		self.dev = dev
 		self.parent: Route | Layout | None = None
 
@@ -208,7 +201,7 @@ class Route:
 		path = "/".join(self._path_list(include_layouts=False))
 		if self.is_index:
 			path += "index"
-		path += ".tsx"
+		path += ".jsx"
 		# Replace Windows-invalid characters in filenames
 		return _sanitize_filename(path)
 
@@ -257,8 +250,6 @@ class Layout:
 	render: Component[...]
 	children: Sequence["Route | Layout"]
 	components: Sequence[ReactComponent[...]] | None
-	css_modules: Sequence[CssModule] | None
-	css_imports: Sequence[CssImport] | None
 	dev: bool
 
 	def __init__(
@@ -266,15 +257,11 @@ class Layout:
 		render: "Component[...]",
 		children: "Sequence[Route | Layout] | None" = None,
 		components: "Sequence[ReactComponent[...]] | None" = None,
-		css_modules: Sequence[CssModule] | None = None,
-		css_imports: Sequence[CssImport] | None = None,
 		dev: bool = False,
 	):
 		self.render = render
 		self.children = children or []
 		self.components = components
-		self.css_modules = css_modules
-		self.css_imports = css_imports
 		self.dev = dev
 		self.parent: Route | Layout | None = None
 		# 1-based sibling index assigned by RouteTree at each level
@@ -366,8 +353,6 @@ def filter_dev_routes(routes: Sequence[Route | Layout]) -> list[Route | Layout]:
 					render=route.render,
 					children=filtered_children,
 					components=route.components,
-					css_modules=route.css_modules,
-					css_imports=route.css_imports,
 					dev=route.dev,
 				)
 			else:  # Layout
@@ -375,8 +360,6 @@ def filter_dev_routes(routes: Sequence[Route | Layout]) -> list[Route | Layout]:
 					render=route.render,
 					children=filtered_children,
 					components=route.components,
-					css_modules=route.css_modules,
-					css_imports=route.css_imports,
 					dev=route.dev,
 				)
 			filtered.append(filtered_route)