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

pulse/code_analysis.py

@@ -0,0 +1,38 @@
+"""Code analysis utilities for inspecting Python source."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+from collections.abc import Callable
+from typing import Any
+
+
+def is_stub_function(fn: Callable[..., Any]) -> bool:
+	"""Check if function body is just ... or pass (no real implementation)."""
+	try:
+		source = inspect.getsource(fn)
+		tree = ast.parse(textwrap.dedent(source))
+		func_def = tree.body[0]
+		if not isinstance(func_def, ast.FunctionDef):
+			return False
+		body = func_def.body
+		# Skip docstring
+		if body and isinstance(body[0], ast.Expr):
+			if isinstance(body[0].value, ast.Constant) and isinstance(
+				body[0].value.value, str
+			):
+				body = body[1:]
+		if not body:
+			return True
+		if len(body) == 1:
+			stmt = body[0]
+			if isinstance(stmt, ast.Pass):
+				return True
+			if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant):
+				if stmt.value.value is ...:
+					return True
+		return False
+	except (OSError, TypeError, SyntaxError):
+		return False

pulse/codegen/codegen.py

@@ -14,7 +14,7 @@ from pulse.codegen.templates.routes_ts import (
 )
 from pulse.env import env
 from pulse.routing import Layout, Route, RouteTree
-from pulse.transpiler import get_registered_imports
+from pulse.transpiler.assets import get_registered_assets
 
 if TYPE_CHECKING:
 	from pulse.app import ConnectionStatusConfig
@@ -123,7 +123,7 @@ class Codegen:
 		self._copied_files = set()
 
 		# Copy all registered local files to the assets directory
-		asset_import_paths = self._copy_local_files()
+		self._copy_local_files()
 
 		# Keep track of all generated files
 		generated_files = set(
@@ -137,11 +137,7 @@ class Codegen:
 				self.generate_routes_ts(),
 				self.generate_routes_runtime_ts(),
 				*(
-					self.generate_route(
-						route,
-						server_address=server_address,
-						asset_import_paths=asset_import_paths,
-					)
+					self.generate_route(route, server_address=server_address)
 					for route in self.routes.flat_tree.values()
 				),
 			]
@@ -157,52 +153,27 @@ class Codegen:
 				except Exception as e:
 					logger.warning(f"Could not remove stale file {path}: {e}")
 
-	def _copy_local_files(self) -> dict[str, str]:
-		"""Copy all registered local files to the assets directory.
+	def _copy_local_files(self) -> None:
+		"""Copy all registered local assets to the assets directory.
 
-		Collects all Import objects with is_local=True and copies their
-		source files to the assets folder, returning an import path mapping.
+		Uses the unified asset registry which tracks local files from both
+		Import objects and DynamicImport expressions.
 		"""
-		imports = get_registered_imports()
-		local_imports = [imp for imp in imports if imp.is_local]
+		assets = get_registered_assets()
 
-		if not local_imports:
-			return {}
+		if not assets:
+			return
 
 		self.assets_folder.mkdir(parents=True, exist_ok=True)
-		asset_import_paths: dict[str, str] = {}
-
-		for imp in local_imports:
-			if imp.source_path is None:
-				continue
 
-			asset_filename = imp.asset_filename()
-			dest_path = self.assets_folder / asset_filename
+		for asset in assets:
+			dest_path = self.assets_folder / asset.asset_filename
 
 			# Copy file if source exists
-			if imp.source_path.exists():
-				shutil.copy2(imp.source_path, dest_path)
+			if asset.source_path.exists():
+				shutil.copy2(asset.source_path, dest_path)
 				self._copied_files.add(dest_path)
-				logger.debug(f"Copied {imp.source_path} -> {dest_path}")
-
-			# Store just the asset filename - the relative path is computed per-route
-			asset_import_paths[imp.src] = asset_filename
-
-		return asset_import_paths
-
-	def _compute_asset_prefix(self, route_file_path: str) -> str:
-		"""Compute the relative path prefix from a route file to the assets folder.
-
-		Args:
-			route_file_path: The route's file path (e.g., "users/_id_xxx.jsx")
-
-		Returns:
-			The relative path prefix (e.g., "../assets/" or "../../assets/")
-		"""
-		# Count directory depth: each "/" in the path adds one level
-		depth = route_file_path.count("/")
-		# Add 1 for the routes/ or layouts/ folder itself
-		return "../" * (depth + 1) + "assets/"
+				logger.debug(f"Copied {asset.source_path} -> {dest_path}")
 
 	def generate_layout_tsx(
 		self,
@@ -281,21 +252,18 @@ class Codegen:
 		self,
 		route: Route | Layout,
 		server_address: str,
-		asset_import_paths: dict[str, str],
 	):
 		route_file_path = route.file_path()
 		if isinstance(route, Layout):
 			output_path = self.output_folder / "layouts" / route_file_path
+			full_route_path = f"layouts/{route_file_path}"
 		else:
 			output_path = self.output_folder / "routes" / route_file_path
-
-		# Compute asset prefix based on route depth
-		asset_prefix = self._compute_asset_prefix(route_file_path)
+			full_route_path = f"routes/{route_file_path}"
 
 		content = generate_route(
 			path=route.unique_path(),
-			asset_filenames=asset_import_paths,
-			asset_prefix=asset_prefix,
+			route_file_path=full_route_path,
 		)
 		return write_file_if_changed(output_path, content)
 

pulse/codegen/templates/route.py

@@ -10,24 +10,29 @@ from pulse.transpiler import (
 	collect_function_graph,
 	emit,
 	get_registered_imports,
+	registered_constants,
 	registered_functions,
 )
+from pulse.transpiler.emit_context import EmitContext
 from pulse.transpiler.function import AnyJsFunction
 
 
+def _get_import_src(imp: Import) -> str:
+	"""Get the import source path, remapping to asset path for local imports."""
+	if imp.asset:
+		return imp.asset.import_path()
+	return imp.src
+
+
 def _generate_import_statement(
 	src: str,
 	imports: list[Import],
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
 ) -> str:
 	"""Generate import statement(s) for a source module.
 
 	Args:
 		src: The original source path (may be remapped for local imports)
 		imports: List of Import objects for this source
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
 	"""
 	default_imports: list[Import] = []
 	namespace_imports: list[Import] = []
@@ -53,8 +58,10 @@ def _generate_import_statement(
 
 	# Remap source path if this is a local import
 	import_src = src
-	if asset_filenames and src in asset_filenames:
-		import_src = asset_prefix + asset_filenames[src]
+	for imp in imports:
+		if imp.asset:
+			import_src = imp.asset.import_path()
+			break
 
 	lines: list[str] = []
 
@@ -98,17 +105,11 @@ def _generate_import_statement(
 	return "\n".join(lines)
 
 
-def _generate_imports_section(
-	imports: Sequence[Import],
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
-) -> str:
+def _generate_imports_section(imports: Sequence[Import]) -> str:
 	"""Generate the full imports section with deduplication and topological ordering.
 
 	Args:
-		imports: List of Import objects to generate
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
+		imports: List of Import objects to generate (should be eager imports only)
 	"""
 	if not imports:
 		return ""
@@ -163,15 +164,46 @@ def _generate_imports_section(
 
 	lines: list[str] = []
 	for src in ordered:
-		stmt = _generate_import_statement(
-			src, grouped[src], asset_filenames, asset_prefix
-		)
+		stmt = _generate_import_statement(src, grouped[src])
 		if stmt:
 			lines.append(stmt)
 
 	return "\n".join(lines)
 
 
+def _generate_lazy_imports_section(imports: Sequence[Import]) -> str:
+	"""Generate lazy import factories for code-splitting.
+
+	Lazy imports are emitted as factory functions compatible with React.lazy.
+	React.lazy requires factories that return { default: Component }.
+
+	For default imports: () => import("./Chart")
+	For named imports: () => import("./Chart").then(m => ({ default: m.LineChart }))
+
+	Args:
+		imports: List of lazy Import objects
+	"""
+	if not imports:
+		return ""
+
+	lines: list[str] = ["// Lazy imports"]
+	for imp in imports:
+		import_src = _get_import_src(imp)
+
+		if imp.is_default or imp.is_namespace:
+			# Default/namespace: () => import("module") - already has { default }
+			factory = f'() => import("{import_src}")'
+		else:
+			# Named: wrap in { default } for React.lazy compatibility
+			factory = (
+				f'() => import("{import_src}").then(m => ({{ default: m.{imp.name} }}))'
+			)
+
+		lines.append(f"const {imp.js_name} = {factory};")
+
+	return "\n".join(lines)
+
+
 def _generate_constants_section(constants: Sequence[Constant]) -> str:
 	"""Generate the constants section."""
 	if not constants:
@@ -232,64 +264,76 @@ def _generate_registry_section(
 
 def generate_route(
 	path: str,
-	asset_filenames: dict[str, str] | None = None,
-	asset_prefix: str = "../assets/",
+	route_file_path: str,
 ) -> str:
 	"""Generate a route file with all registered imports, functions, and components.
 
 	Args:
 		path: The route path (e.g., "/users/:id")
-		asset_filenames: Mapping of original source paths to asset filenames
-		asset_prefix: Relative path prefix from route file to assets folder
+		route_file_path: Path from pulse root (e.g., "routes/users/index.tsx")
 	"""
-	# Note: Lazy component support is not yet implemented.
-	# Components now register via the unified registry.
+	with EmitContext(route_file_path=route_file_path):
+		# Add core Pulse imports
+		pulse_view_import = Import("PulseView", "pulse-ui-client")
+
+		# Collect function graph (constants + functions in dependency order)
+		fn_constants, funcs = collect_function_graph(registered_functions())
+
+		# Include all registered constants (not just function dependencies)
+		# This ensures constants used as component tags are included
+		fn_const_ids = {c.id for c in fn_constants}
+		all_constants = list(fn_constants)
+		for const in registered_constants():
+			if const.id not in fn_const_ids:
+				all_constants.append(const)
+		constants = all_constants
+
+		# Get all registered imports and split by lazy flag
+		all_imports = list(get_registered_imports())
+		eager_imports = [imp for imp in all_imports if not imp.lazy]
+		lazy_imports = [imp for imp in all_imports if imp.lazy]
+
+		# Generate output sections
+		output_parts: list[str] = []
+
+		# Eager imports (ES6 import statements)
+		imports_section = _generate_imports_section(eager_imports)
+		if imports_section:
+			output_parts.append(imports_section)
 
-	# Add core Pulse imports
-	pulse_view_import = Import("PulseView", "pulse-ui-client")
-
-	# Collect function graph (constants + functions in dependency order)
-	constants, funcs = collect_function_graph(registered_functions())
-
-	# Get all registered imports
-	all_imports = list(get_registered_imports())
+		output_parts.append("")
 
-	# Generate output sections
-	output_parts: list[str] = []
+		# Lazy imports (factory functions)
+		lazy_section = _generate_lazy_imports_section(lazy_imports)
+		if lazy_section:
+			output_parts.append(lazy_section)
+			output_parts.append("")
 
-	imports_section = _generate_imports_section(
-		all_imports, asset_filenames, asset_prefix
-	)
-	if imports_section:
-		output_parts.append(imports_section)
+		if constants:
+			output_parts.append(_generate_constants_section(constants))
+			output_parts.append("")
 
-	output_parts.append("")
+		if funcs:
+			output_parts.append(_generate_functions_section(funcs))
+			output_parts.append("")
 
-	if constants:
-		output_parts.append(_generate_constants_section(constants))
+		# Generate the unified registry including all imports, constants and functions
+		output_parts.append(_generate_registry_section(all_imports, constants, funcs))
 		output_parts.append("")
 
-	if funcs:
-		output_parts.append(_generate_functions_section(funcs))
-		output_parts.append("")
-
-	# Generate the unified registry including all imports, constants and functions
-	output_parts.append(_generate_registry_section(all_imports, constants, funcs))
-	output_parts.append("")
-
-	# Route component
-	pulse_view_js = pulse_view_import.js_name
-	output_parts.append(f'''const path = "{path}";
+		# Route component
+		pulse_view_js = pulse_view_import.js_name
+		output_parts.append(f'''const path = "{path}";
 
 export default function RouteComponent() {{
   return (
     <{pulse_view_js} key={{path}} registry={{__registry}} path={{path}} />
   );
 }}''')
-	output_parts.append("")
+		output_parts.append("")
 
-	# Headers function
-	output_parts.append("""// Action and loader headers are not returned automatically
+		# Headers function
+		output_parts.append("""// Action and loader headers are not returned automatically
 function hasAnyHeaders(headers) {
   return [...headers].length > 0;
 }
@@ -298,4 +342,4 @@ export function headers({ actionHeaders, loaderHeaders }) {
   return hasAnyHeaders(actionHeaders) ? actionHeaders : loaderHeaders;
 }""")
 
-	return "\n".join(output_parts)
+		return "\n".join(output_parts)

pulse/component.py

@@ -4,6 +4,7 @@ from collections.abc import Callable
 from inspect import Parameter, signature
 from typing import Any, Generic, ParamSpec, TypeVar, overload, override
 
+from pulse.code_analysis import is_stub_function
 from pulse.hooks.init import rewrite_init_blocks
 from pulse.transpiler.nodes import (
 	Children,
@@ -20,21 +21,38 @@ _T = TypeVar("_T")
 
 
 class Component(Generic[P]):
-	fn: Callable[P, Any]
+	_raw_fn: Callable[P, Any]
+	_fn: Callable[P, Any] | None
 	name: str
-	_takes_children: bool
+	_takes_children: bool | None
 
 	def __init__(self, fn: Callable[P, Any], name: str | None = None) -> None:
-		self.fn = rewrite_init_blocks(fn)
+		self._raw_fn = fn
 		self.name = name or _infer_component_name(fn)
-		self._takes_children = _takes_children(fn)
+		# Only lazy-init for stubs (avoid heavy work for JS module bindings)
+		# Real components need immediate rewrite for early error detection
+		if is_stub_function(fn):
+			self._fn = None
+			self._takes_children = None
+		else:
+			self._fn = rewrite_init_blocks(fn)
+			self._takes_children = _takes_children(fn)
+
+	@property
+	def fn(self) -> Callable[P, Any]:
+		if self._fn is None:
+			self._fn = rewrite_init_blocks(self._raw_fn)
+			self._takes_children = _takes_children(self._raw_fn)
+		return self._fn
 
 	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> PulseNode:
 		key = kwargs.get("key")
 		if key is not None and not isinstance(key, str):
 			raise ValueError("key must be a string or None")
 
-		if self._takes_children and args:
+		# Access self.fn to trigger lazy init (sets _takes_children)
+		_ = self.fn
+		if self._takes_children is True and args:
 			flattened = flatten_children(
 				args,  # pyright: ignore[reportArgumentType]
 				parent_name=f"<{self.name}>",
@@ -46,7 +64,7 @@ class Component(Generic[P]):
 
 	@override
 	def __repr__(self) -> str:
-		return f"Component(name={self.name!r}, fn={_callable_qualname(self.fn)!r})"
+		return f"Component(name={self.name!r}, fn={_callable_qualname(self._raw_fn)!r})"
 
 	@override
 	def __str__(self) -> str:

pulse/js/__init__.py

@@ -39,7 +39,6 @@ _MODULE_EXPORTS_NAMESPACE: dict[str, str] = {
 	"JSON": "pulse.js.json",
 	"Math": "pulse.js.math",
 	"React": "pulse.js.react",
-	"ReactDOM": "pulse.js.react_dom",
 	"console": "pulse.js.console",
 	"window": "pulse.js.window",
 	"document": "pulse.js.document",
@@ -54,6 +53,7 @@ _MODULE_EXPORTS_ATTRIBUTE: dict[str, str] = {
 	"Map": "pulse.js.map",
 	"Object": "pulse.js.object",
 	"Promise": "pulse.js.promise",
+	"React": "pulse.js.react",
 	"RegExp": "pulse.js.regexp",
 	"Set": "pulse.js.set",
 	"String": "pulse.js.string",

pulse/js/react.py

@@ -12,12 +12,27 @@ Usage:
     React.useState(0)                     # -> React.useState(0)
 """
 
+import ast as _ast
 from collections.abc import Callable as _Callable
+from typing import TYPE_CHECKING as _TYPE_CHECKING
 from typing import Any as _Any
 from typing import Protocol as _Protocol
 from typing import TypeVar as _TypeVar
+from typing import override as _override
 
+from pulse.component import component as _component
+from pulse.transpiler import Import as _Import
+from pulse.transpiler.errors import TranspileError as _TranspileError
+from pulse.transpiler.function import Constant as _Constant
 from pulse.transpiler.js_module import JsModule
+from pulse.transpiler.nodes import Call as _Call
+from pulse.transpiler.nodes import Expr as _Expr
+from pulse.transpiler.nodes import Jsx as _Jsx
+from pulse.transpiler.nodes import Node as _PulseNode
+from pulse.transpiler.vdom import VDOMNode as _VDOMNode
+
+if _TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler as _Transpiler
 
 # Type variables for hooks
 T = _TypeVar("T")
@@ -321,9 +336,99 @@ def forwardRef(
 	...
 
 
-def lazy(load: _Callable[[], _Any]) -> _Any:
-	"""Lets you defer loading a component's code until it is rendered."""
-	...
+class _LazyComponentFactory(_Expr):
+	"""React.lazy binding that works both at definition time and in @javascript.
+
+	This Expr represents React's lazy function. It can be:
+	- Called at Python definition time: lazy(factory) → Jsx(Constant(...))
+	- Used as a reference in @javascript: some_fn(lazy) → some_fn(lazy)
+	- Called inside @javascript: lazy(factory) → creates Constant+Jsx
+
+	Usage:
+		# At definition time (Python executes this)
+		LazyChart = lazy(Import("Chart", "./Chart", lazy=True))
+
+		# As reference in transpiled code
+		@javascript
+		def foo():
+			return higher_order_fn(lazy)  # → higher_order_fn(lazy)
+
+		# Called in transpiled code
+		@javascript
+		def bar():
+			LazyComp = lazy(factory)  # → const LazyComp_1 = lazy(factory)
+			return LazyComp()
+	"""
+
+	__slots__: tuple[str, ...] = ("_lazy_import",)
+	_lazy_import: _Import | None
+
+	def __init__(self) -> None:
+		# Defer Import creation to avoid polluting global import registry at module load
+		self._lazy_import = None
+
+	@property
+	def _import(self) -> _Import:
+		"""Lazily create the React.lazy import."""
+		if self._lazy_import is None:
+			self._lazy_import = _Import("lazy", "react")
+		return self._lazy_import
+
+	def _create_lazy_component(self, factory: _Expr) -> _Jsx:
+		"""Create a lazy-loaded component from a factory expression.
+
+		Args:
+			factory: An Expr that evaluates to a dynamic import factory
+
+		Returns:
+			A Jsx-wrapped lazy component
+		"""
+		lazy_call = _Call(self._import, [factory])
+		const = _Constant(lazy_call, lazy_call)
+		return _Jsx(const)
+
+	@_override
+	def emit(self, out: list[str]) -> None:
+		"""Emit as reference to the lazy import."""
+		self._import.emit(out)
+
+	@_override
+	def render(self) -> _VDOMNode:
+		raise TypeError("lazy cannot be rendered to VDOM")
+
+	@_override
+	def transpile_call(
+		self,
+		args: list[_ast.expr],
+		keywords: list[_ast.keyword],
+		ctx: "_Transpiler",
+	) -> _Expr:
+		"""Handle lazy(factory) calls in @javascript functions."""
+		if keywords:
+			raise _TranspileError("lazy() does not accept keyword arguments")
+		if len(args) != 1:
+			raise _TranspileError("lazy() takes exactly 1 argument")
+
+		factory = ctx.emit_expr(args[0])
+		return self._create_lazy_component(factory)
+
+	@_override
+	def __call__(self, factory: _Import) -> _Jsx:  # pyright: ignore[reportIncompatibleMethodOverride]
+		"""Python-time call: create a lazy-loaded component.
+
+		Args:
+			factory: An Import with lazy=True that generates a dynamic import factory
+
+		Returns:
+			A Jsx-wrapped lazy component that can be used as LazyChart(props)[children]
+		"""
+		return self._create_lazy_component(factory)
+
+
+# Singleton instance - use as: lazy(Import(...))
+lazy: _LazyComponentFactory = _LazyComponentFactory()
+# Register so transpiler can resolve it from closure
+_Expr.register(lazy, lazy)
 
 
 def createContext(default_value: T) -> Context[T]:
@@ -332,13 +437,15 @@ def createContext(default_value: T) -> Context[T]:
 
 
 # =============================================================================
-# Fragments
+# Components (stub declarations become Jsx-wrapped imports)
 # =============================================================================
 
 
-class Fragment:
-	"""Lets you group elements without a wrapper node."""
-
+@_component
+def Suspense(
+	*, fallback: ReactNode | _PulseNode | None = None, name: str | None = None
+) -> ReactElement:
+	"""Lets you display a fallback while its children are loading."""
 	...
 
 

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