pulse-framework 0.1.53__py3-none-any.whl → 0.1.55__py3-none-any.whl

pulse/renderer.py

@@ -65,48 +65,43 @@ class RenderPropTask(NamedTuple):
 
 
 class RenderTree:
-	root: Node
+	element: Node
 	callbacks: Callbacks
-	operations: list[VDOMOperation]
-	_normalized: Node | None
+	rendered: bool
 
-	def __init__(self, root: Node) -> None:
-		self.root = root
+	def __init__(self, element: Node) -> None:
+		self.element = element
 		self.callbacks = {}
-		self.operations = []
-		self._normalized = None
+		self.rendered = False
 
 	def render(self) -> VDOM:
+		"""First render. Returns VDOM."""
 		renderer = Renderer()
-		vdom, normalized = renderer.render_tree(self.root)
-		self.root = normalized
+		vdom, self.element = renderer.render_tree(self.element)
 		self.callbacks = renderer.callbacks
-		self._normalized = normalized
+		self.rendered = True
 		return vdom
 
-	def diff(self, new_tree: Node) -> list[VDOMOperation]:
-		if self._normalized is None:
-			raise RuntimeError("RenderTree.render must be called before diff")
+	def rerender(self, new_element: Node | None = None) -> list[VDOMOperation]:
+		"""Re-render and return update operations.
 
+		If new_element is provided, reconciles against it (for testing).
+		Otherwise, reconciles against the current element (production use).
+		"""
+		if not self.rendered:
+			raise RuntimeError("render() must be called before rerender()")
+		target = new_element if new_element is not None else self.element
 		renderer = Renderer()
-		normalized = renderer.reconcile_tree(self._normalized, new_tree, path="")
-
+		self.element = renderer.reconcile_tree(self.element, target, path="")
 		self.callbacks = renderer.callbacks
-		self._normalized = normalized
-		self.root = normalized
-
 		return renderer.operations
 
 	def unmount(self) -> None:
-		if self._normalized is not None:
-			unmount_element(self._normalized)
-			self._normalized = None
+		if self.rendered:
+			unmount_element(self.element)
+			self.rendered = False
 		self.callbacks.clear()
 
-	@property
-	def normalized(self) -> Node | None:
-		return self._normalized
-
 
 class Renderer:
 	def __init__(self) -> None:
@@ -123,13 +118,11 @@ class Renderer:
 		if isinstance(node, Element):
 			return self.render_node(node, path)
 		if isinstance(node, Value):
-			json_value = coerce_json(node.value, path)
-			return json_value, json_value
+			return node.value, node.value
 		if isinstance(node, Expr):
 			return node.render(), node
-		if is_json_primitive(node):
-			return node, node
-		raise TypeError(f"Unsupported node type: {type(node).__name__}")
+		# Pass through any other value - serializer will validate
+		return node, node
 
 	def render_component(
 		self, component: PulseNode, path: str
@@ -148,7 +141,7 @@ class Renderer:
 		if (key_val := key_value(element)) is not None:
 			vdom_node["key"] = key_val
 
-		props = element.props or {}
+		props = element.props_dict()
 		props_result = self.diff_props({}, props, path, prev_eval=set())
 		if props_result.delta_set:
 			vdom_node["props"] = props_result.delta_set
@@ -188,9 +181,9 @@ class Renderer:
 		path: str = "",
 	) -> Node:
 		if isinstance(current, Value):
-			current = coerce_json(current.value, path)
+			current = current.value
 		if isinstance(previous, Value):
-			previous = coerce_json(previous.value, path)
+			previous = previous.value
 		if not same_node(previous, current):
 			unmount_element(previous)
 			new_vdom, normalized = self.render_tree(current, path)
@@ -239,8 +232,8 @@ class Renderer:
 		current: Element,
 		path: str,
 	) -> Element:
-		prev_props = previous.props or {}
-		new_props = current.props or {}
+		prev_props = previous.props_dict()
+		new_props = current.props_dict()
 		prev_eval = eval_keys_for_props(prev_props)
 		props_result = self.diff_props(prev_props, new_props, path, prev_eval)
 
@@ -389,14 +382,14 @@ class Renderer:
 				continue
 
 			if isinstance(value, Value):
-				json_value = coerce_json(value.value, prop_path)
+				unwrapped = value.value
 				if normalized is None:
 					normalized = current.copy()
-				normalized[key] = json_value
+				normalized[key] = unwrapped
 				if isinstance(old_value, (Element, PulseNode)):
 					unmount_element(old_value)
-				if key not in previous or not values_equal(json_value, old_value):
-					updated[key] = cast(VDOMPropValue, json_value)
+				if key not in previous or not values_equal(unwrapped, old_value):
+					updated[key] = cast(VDOMPropValue, unwrapped)
 				continue
 
 			if isinstance(value, Expr):
@@ -422,16 +415,11 @@ class Renderer:
 					updated[key] = CALLBACK_PLACEHOLDER
 				continue
 
-			json_value = coerce_json(value, prop_path)
 			if isinstance(old_value, (Element, PulseNode)):
 				unmount_element(old_value)
-			if normalized is not None:
-				normalized[key] = json_value
-			elif json_value is not value:
-				normalized = current.copy()
-				normalized[key] = json_value
-			if key not in previous or not values_equal(json_value, old_value):
-				updated[key] = cast(VDOMPropValue, json_value)
+			# No normalization needed - value passes through unchanged
+			if key not in previous or not values_equal(value, old_value):
+				updated[key] = cast(VDOMPropValue, value)
 
 		for key in removed_keys:
 			old_value = previous.get(key)
@@ -488,31 +476,6 @@ def registry_ref(expr: Expr) -> RegistryRef | None:
 	return None
 
 
-def is_json_primitive(value: Any) -> bool:
-	return value is None or isinstance(value, (str, int, float, bool))
-
-
-def coerce_json(value: Any, path: str) -> Any:
-	"""Convert Python value to JSON-compatible structure.
-
-	Performs runtime conversions:
-	- tuple → list
-	- validates dict keys are strings
-	"""
-	if is_json_primitive(value):
-		return value
-	if isinstance(value, (list, tuple)):
-		return [coerce_json(v, path) for v in value]
-	if isinstance(value, dict):
-		out: dict[str, Any] = {}
-		for k, v in value.items():
-			if not isinstance(k, str):
-				raise TypeError(f"Non-string prop key at {path}: {k!r}")
-			out[k] = coerce_json(v, path)
-		return out
-	raise TypeError(f"Unsupported JSON value at {path}: {type(value).__name__}")
-
-
 def prop_requires_eval(value: PropValue) -> bool:
 	if isinstance(value, Value):
 		return False
@@ -611,7 +574,7 @@ def unmount_element(element: Node) -> None:
 		return
 
 	if isinstance(element, Element):
-		props = element.props or {}
+		props = element.props_dict()
 		for value in props.values():
 			if isinstance(value, (Element, PulseNode)):
 				unmount_element(value)

pulse/serializer.py

@@ -86,8 +86,11 @@ def serialize(data: Any) -> Serialized:
 		if isinstance(value, dict):
 			result_dict: dict[str, PlainJSON] = {}
 			for key, entry in value.items():
-				key_str = str(key)  # pyright: ignore[reportUnknownArgumentType]
-				result_dict[key_str] = process(entry)
+				if not isinstance(key, str):
+					raise TypeError(
+						f"Dict keys must be strings, got {type(key).__name__}: {key!r}"  # pyright: ignore[reportUnknownArgumentType]
+					)
+				result_dict[key] = process(entry)
 			return result_dict
 
 		if isinstance(value, (list, tuple)):

pulse/transpiler/__init__.py

@@ -3,10 +3,23 @@
 # Ensure built-in Python modules (e.g., math) are registered on import.
 from pulse.transpiler import modules as _modules  # noqa: F401
 
+# Asset registry (unified for Import and DynamicImport)
+from pulse.transpiler.assets import LocalAsset as LocalAsset
+from pulse.transpiler.assets import clear_asset_registry as clear_asset_registry
+from pulse.transpiler.assets import get_registered_assets as get_registered_assets
+from pulse.transpiler.assets import register_local_asset as register_local_asset
+
 # Builtins
 from pulse.transpiler.builtins import BUILTINS as BUILTINS
 from pulse.transpiler.builtins import emit_method as emit_method
 
+# Dynamic import primitive
+from pulse.transpiler.dynamic_import import DynamicImport as DynamicImport
+from pulse.transpiler.dynamic_import import import_ as import_
+
+# Emit context
+from pulse.transpiler.emit_context import EmitContext as EmitContext
+
 # Errors
 from pulse.transpiler.errors import TranspileError as TranspileError
 

pulse/transpiler/assets.py

@@ -0,0 +1,66 @@
+"""Unified asset registry for local files that need copying.
+
+Used by both Import (static imports) and DynamicImport (inline dynamic imports)
+to track local files that should be copied to the assets folder during codegen.
+"""
+
+from __future__ import annotations
+
+import posixpath
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.transpiler.emit_context import EmitContext
+from pulse.transpiler.id import next_id
+
+
+@dataclass(slots=True)
+class LocalAsset:
+	"""A local file registered for copying to assets."""
+
+	source_path: Path
+	id: str
+
+	@property
+	def asset_filename(self) -> str:
+		"""Filename in assets folder: stem_id.ext"""
+		return f"{self.source_path.stem}_{self.id}{self.source_path.suffix}"
+
+	def import_path(self) -> str:
+		"""Get import path for this asset.
+
+		If EmitContext is set, returns path relative to route file.
+		Otherwise returns the absolute source path (useful for tests/debugging).
+		"""
+		ctx = EmitContext.get()
+		if ctx is None:
+			return str(self.source_path)
+		# Compute relative path from route file directory to asset
+		# route_file_path is like "routes/users/index.tsx"
+		# asset is in "assets/{asset_filename}"
+		route_dir = posixpath.dirname(ctx.route_file_path)
+		asset_path = f"assets/{self.asset_filename}"
+		return posixpath.relpath(asset_path, route_dir)
+
+
+# Registry keyed by resolved source_path (dedupes same file)
+_ASSET_REGISTRY: dict[Path, LocalAsset] = {}
+
+
+def register_local_asset(source_path: Path) -> LocalAsset:
+	"""Register a local file for copying. Returns existing if already registered."""
+	if source_path in _ASSET_REGISTRY:
+		return _ASSET_REGISTRY[source_path]
+	asset = LocalAsset(source_path, next_id())
+	_ASSET_REGISTRY[source_path] = asset
+	return asset
+
+
+def get_registered_assets() -> list[LocalAsset]:
+	"""Get all registered local assets."""
+	return list(_ASSET_REGISTRY.values())
+
+
+def clear_asset_registry() -> None:
+	"""Clear asset registry (for tests)."""
+	_ASSET_REGISTRY.clear()

pulse/transpiler/builtins.py

@@ -21,7 +21,6 @@ from pulse.transpiler.nodes import (
 	Literal,
 	Member,
 	New,
-	Object,
 	Spread,
 	Subscript,
 	Template,
@@ -173,25 +172,6 @@ def emit_dict(*args: Any, ctx: Transpiler) -> Expr:
 	raise TranspileError("dict() expects at most one argument")
 
 
-@transformer("obj")
-def obj(*args: Any, ctx: Transpiler, **kwargs: Any) -> Expr:
-	"""obj(key=value, ...) -> { key: value, ... }
-
-	Creates a plain JavaScript object literal.
-	Use this instead of dict() when you need a plain object (e.g., for React props).
-
-	Example:
-		style=obj(display="block", color="red")
-		-> style={{ display: "block", color: "red" }}
-	"""
-	if args:
-		raise TranspileError("obj() only accepts keyword arguments")
-	props: list[tuple[str, Expr]] = []
-	for key, value in kwargs.items():
-		props.append((key, ctx.emit_expr(value)))
-	return Object(props)
-
-
 @transformer("filter")
 def emit_filter(*args: Any, ctx: Transpiler) -> Expr:
 	"""filter(func, iterable) -> iterable.filter(func)"""

pulse/transpiler/dynamic_import.py

@@ -0,0 +1,131 @@
+"""Dynamic import primitive for code-splitting.
+
+Provides `import_` for inline dynamic imports in @javascript functions:
+
+    @javascript
+    def load_chart():
+        return import_("./Chart").then(lambda m: m.default)
+
+For lazy-loaded React components, use Import(lazy=True) with React.lazy:
+
+    from pulse.js.react import React, lazy
+
+    # Low-level: Import(lazy=True) creates a factory, wrap with React.lazy
+    factory = Import("Chart", "./Chart", kind="default", lazy=True)
+    LazyChart = Jsx(React.lazy(factory))
+
+    # High-level: lazy() helper combines both
+    LazyChart = lazy("./Chart")
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pulse.transpiler.assets import LocalAsset, register_local_asset
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.imports import is_local_path, resolve_local_path
+from pulse.transpiler.nodes import Expr, Member
+from pulse.transpiler.vdom import VDOMNode
+
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+
+@dataclass(slots=True)
+class DynamicImport(Expr):
+	"""Represents a dynamic import() expression.
+
+	Emits as: import("src")
+
+	Supports method chaining for .then():
+	    import_("./foo").then(lambda m: m.bar)
+	    -> import("./foo").then(m => m.bar)
+	"""
+
+	src: str
+	asset: LocalAsset | None = None
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		if self.asset:
+			out.append(f'import("{self.asset.import_path()}")')
+		else:
+			out.append(f'import("{self.src}")')
+
+	@override
+	def render(self) -> VDOMNode:
+		raise TypeError("DynamicImport cannot be rendered to VDOM")
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		"""Allow .then() and other method chaining."""
+		return Member(self, attr)
+
+
+class DynamicImportFn(Expr):
+	"""Sentinel expr that intercepts import_() calls.
+
+	When used in a @javascript function:
+	    import_("./module")
+
+	Transpiles to:
+	    import("./module")
+
+	For local paths, resolves the file and registers it for asset copying.
+	"""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		raise TypeError(
+			"import_ cannot be emitted directly - call it with a source path"
+		)
+
+	@override
+	def render(self) -> VDOMNode:
+		raise TypeError("import_ cannot be rendered to VDOM")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		"""Handle import_("source") calls."""
+		if keywords:
+			raise TranspileError("import_() does not accept keyword arguments")
+		if len(args) != 1:
+			raise TranspileError("import_() takes exactly 1 argument")
+
+		# Extract string literal from AST
+		src_node = args[0]
+		if not isinstance(src_node, ast.Constant) or not isinstance(
+			src_node.value, str
+		):
+			raise TranspileError("import_() argument must be a string literal")
+
+		src = src_node.value
+		asset: LocalAsset | None = None
+
+		# Resolve local paths and register asset
+		if is_local_path(src):
+			if ctx.source_file is None:
+				raise TranspileError(
+					"Cannot resolve relative import_() path: source file unknown"
+				)
+			source_path = resolve_local_path(src, ctx.source_file)
+			if source_path:
+				asset = register_local_asset(source_path)
+			else:
+				raise TranspileError(
+					f"import_({src!r}) references a local path that does not exist"
+				)
+
+		return DynamicImport(src, asset)
+
+
+# Singleton for use in deps
+import_ = DynamicImportFn()

pulse/transpiler/emit_context.py

@@ -0,0 +1,49 @@
+"""Emit context for code generation."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Literal
+
+
+@dataclass
+class EmitContext:
+	"""Context for emit operations during route code generation.
+
+	Stores information about the current route file being generated,
+	allowing emit methods to compute correct relative paths.
+
+	Usage:
+		with EmitContext(route_file_path="routes/users/index.tsx"):
+			js_code = emit(fn.transpile())
+	"""
+
+	route_file_path: str
+	"""Path to route file from pulse folder root, e.g. 'routes/users/index.tsx'"""
+
+	_token: Token[EmitContext | None] | None = field(default=None, repr=False)
+
+	@classmethod
+	def get(cls) -> EmitContext | None:
+		"""Get current emit context, or None if not set."""
+		return _EMIT_CONTEXT.get()
+
+	def __enter__(self) -> EmitContext:
+		self._token = _EMIT_CONTEXT.set(self)
+		return self
+
+	def __exit__(
+		self,
+		exc_type: type[BaseException] | None = None,
+		exc_val: BaseException | None = None,
+		exc_tb: TracebackType | None = None,
+	) -> Literal[False]:
+		if self._token is not None:
+			_EMIT_CONTEXT.reset(self._token)
+			self._token = None
+		return False
+
+
+_EMIT_CONTEXT: ContextVar[EmitContext | None] = ContextVar("emit_context", default=None)

pulse/transpiler/errors.py

@@ -13,6 +13,7 @@ class TranspileError(Exception):
 	source: str | None
 	filename: str | None
 	func_name: str | None
+	source_start_line: int | None
 
 	def __init__(
 		self,
@@ -22,12 +23,14 @@ class TranspileError(Exception):
 		source: str | None = None,
 		filename: str | None = None,
 		func_name: str | None = None,
+		source_start_line: int | None = None,
 	) -> None:
 		self.message = message
 		self.node = node
 		self.source = source
 		self.filename = filename
 		self.func_name = func_name
+		self.source_start_line = source_start_line
 		super().__init__(self._format_message())
 
 	def _format_message(self) -> str:
@@ -38,25 +41,38 @@ class TranspileError(Exception):
 			loc_parts: list[str] = []
 			if self.func_name:
 				loc_parts.append(f"in {self.func_name}")
+			display_lineno = self.node.lineno
+			if self.source_start_line is not None:
+				display_lineno = self.source_start_line + self.node.lineno - 1
 			if self.filename:
-				loc_parts.append(f"at {self.filename}:{self.node.lineno}")
+				loc_parts.append(f"at {self.filename}:{display_lineno}")
 			else:
-				loc_parts.append(f"at line {self.node.lineno}")
-			if hasattr(self.node, "col_offset"):
-				loc_parts[-1] += f":{self.node.col_offset}"
-
-			if loc_parts:
-				parts.append(" ".join(loc_parts))
+				loc_parts.append(f"at line {display_lineno}")
 
-			# Show the source line if available
+			display_line = None
+			display_col = None
 			if self.source:
 				lines = self.source.splitlines()
 				if 0 < self.node.lineno <= len(lines):
 					source_line = lines[self.node.lineno - 1]
-					parts.append(f"\n  {source_line}")
-					# Add caret pointing to column
+					display_line = source_line.expandtabs(4)
 					if hasattr(self.node, "col_offset"):
-						parts.append("  " + " " * self.node.col_offset + "^")
+						prefix = source_line[: self.node.col_offset]
+						display_col = len(prefix.expandtabs(4))
+
+			if hasattr(self.node, "col_offset"):
+				col = display_col if display_col is not None else self.node.col_offset
+				loc_parts[-1] += f":{col}"
+
+			if loc_parts:
+				parts.append(" ".join(loc_parts))
+
+			# Show the source line if available
+			if display_line is not None:
+				parts.append(f"\n  {display_line}")
+				# Add caret pointing to column
+				if display_col is not None:
+					parts.append("  " + " " * display_col + "^")
 
 		return "\n".join(parts) if len(parts) > 1 else parts[0]
 
@@ -67,6 +83,7 @@ class TranspileError(Exception):
 		source: str | None = None,
 		filename: str | None = None,
 		func_name: str | None = None,
+		source_start_line: int | None = None,
 	) -> TranspileError:
 		"""Return a new TranspileError with additional context."""
 		return TranspileError(
@@ -75,4 +92,5 @@ class TranspileError(Exception):
 			source=source or self.source,
 			filename=filename or self.filename,
 			func_name=func_name or self.func_name,
+			source_start_line=source_start_line or self.source_start_line,
 		)