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

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/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/function.py

@@ -12,6 +12,7 @@ import textwrap
 import types as pytypes
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import (
 	Any,
 	Generic,
@@ -57,11 +58,13 @@ CONSTANT_REGISTRY: dict[int, "Constant"] = {}
 
 def clear_function_cache() -> None:
 	"""Clear function/constant/ref caches and reset the shared ID counters."""
+	from pulse.transpiler.assets import clear_asset_registry
 	from pulse.transpiler.imports import clear_import_registry
 
 	FUNCTION_CACHE.clear()
 	CONSTANT_REGISTRY.clear()
 	clear_import_registry()
+	clear_asset_registry()
 	reset_id_counter()
 
 
@@ -156,7 +159,7 @@ def _transpile_function_body(
 		raise TranspileError("No function definition found in source")
 	fndef = fndefs[-1]
 
-	# Get filename for error messages
+	# Get filename for error messages and source file resolution
 	try:
 		filename = inspect.getfile(fn)
 	except (TypeError, OSError):
@@ -164,7 +167,8 @@ def _transpile_function_body(
 
 	# Transpile with source context for errors
 	try:
-		transpiler = Transpiler(fndef, deps, jsx=jsx)
+		source_file = Path(filename) if filename else None
+		transpiler = Transpiler(fndef, deps, jsx=jsx, source_file=source_file)
 		result = transpiler.transpile()
 	except TranspileError as e:
 		# Re-raise with source context if not already present

pulse/transpiler/imports.py

@@ -15,6 +15,8 @@ from typing import (
 from typing import Literal as Lit
 
 from pulse.cli.packages import pick_more_specific
+from pulse.transpiler.assets import LocalAsset, register_local_asset
+from pulse.transpiler.errors import TranspileError
 from pulse.transpiler.id import next_id
 from pulse.transpiler.nodes import Call, Expr, to_js_identifier
 from pulse.transpiler.vdom import VDOMNode
@@ -122,10 +124,10 @@ def resolve_local_path(path: str, caller: Path | None = None) -> Path | None:
 	return base_path
 
 
-# Registry key depends on kind:
-# - named: (name, src, "named")
-# - default/namespace/side_effect: ("", src, kind) - only one per src
-_ImportKey: TypeAlias = tuple[str, str, str]
+# Registry key depends on kind and lazy:
+# - named: (name, src, "named", lazy)
+# - default/namespace/side_effect: ("", src, kind, lazy) - only one per src
+_ImportKey: TypeAlias = tuple[str, str, str, bool]
 _IMPORT_REGISTRY: dict[_ImportKey, "Import"] = {}
 
 
@@ -171,17 +173,22 @@ class Import(Expr):
 		Import("", "./styles.css", kind="side_effect")  # Local CSS
 		utils = Import("utils", "./utils", kind="namespace")  # Local JS (resolves extension)
 		config = Import("config", "/absolute/path/config", kind="default")  # Absolute path
+
+		# Lazy import (generates factory for code-splitting)
+		Chart = Import("Chart", "./Chart", kind="default", lazy=True)
+		# Generates: const Chart_1 = () => import("./Chart")
 	"""
 
 	name: str
 	src: str
 	kind: ImportKind
 	is_type: bool
+	lazy: bool
 	before: tuple[str, ...]
 	id: str
 	version: str | None = None
-	source_path: Path | None = (
-		None  # Resolved local file path (for copying during codegen)
+	asset: LocalAsset | None = (
+		None  # Registered local asset (for copying during codegen)
 	)
 
 	def __init__(
@@ -191,12 +198,17 @@ class Import(Expr):
 		*,
 		kind: ImportKind | None = None,
 		is_type: bool = False,
+		lazy: bool = False,
 		version: str | None = None,
 		before: tuple[str, ...] | list[str] = (),
 		_caller_depth: int = 2,
 	) -> None:
+		# Validate: lazy imports cannot be type-only
+		if lazy and is_type:
+			raise TranspileError("Import cannot be both lazy and type-only")
+
 		# Auto-resolve local paths (relative or absolute) to actual files
-		source_path: Path | None = None
+		asset: LocalAsset | None = None
 		import_src = src
 
 		if is_local_path(src):
@@ -204,7 +216,8 @@ class Import(Expr):
 			caller = caller_file(depth=_caller_depth) if is_relative_path(src) else None
 			resolved = resolve_local_path(src, caller)
 			if resolved is not None:
-				source_path = resolved
+				# Register with unified asset registry
+				asset = register_local_asset(resolved)
 				import_src = str(resolved)
 
 		# Default kind to "named" if not specified
@@ -215,16 +228,16 @@ class Import(Expr):
 		self.src = import_src
 		self.kind = kind
 		self.version = version
-		self.source_path = source_path
+		self.lazy = lazy
+		self.asset = asset
 
 		before_tuple = tuple(before) if isinstance(before, list) else before
 
-		# Dedupe key: for named imports use (name, src, "named")
-		# For default/namespace/side_effect, only one per src: ("", src, kind)
+		# Dedupe key: includes lazy flag to keep lazy and eager imports separate
 		if kind == "named":
-			key: _ImportKey = (name, import_src, "named")
+			key: _ImportKey = (name, import_src, "named", lazy)
 		else:
-			key = ("", import_src, kind)
+			key = ("", import_src, kind, lazy)
 
 		if key in _IMPORT_REGISTRY:
 			existing = _IMPORT_REGISTRY[key]
@@ -260,8 +273,13 @@ class Import(Expr):
 
 	@property
 	def is_local(self) -> bool:
-		"""Check if this is a local file import (has resolved source_path)."""
-		return self.source_path is not None
+		"""Check if this is a local file import (has registered asset)."""
+		return self.asset is not None
+
+	@property
+	def is_lazy(self) -> bool:
+		"""Check if this is a lazy import."""
+		return self.lazy
 
 	# Convenience properties for kind checks
 	@property
@@ -276,18 +294,6 @@ class Import(Expr):
 	def is_side_effect(self) -> bool:
 		return self.kind == "side_effect"
 
-	def asset_filename(self) -> str:
-		"""Get the filename for this import when copied to assets folder.
-
-		Uses the import ID for uniqueness and preserves the original extension.
-		For JS-like files, uses the resolved extension.
-		"""
-		if self.source_path is None:
-			raise ValueError("Cannot get asset filename for non-local import")
-		stem = self.source_path.stem
-		suffix = self.source_path.suffix
-		return f"{stem}_{self.id}{suffix}"
-
 	# -------------------------------------------------------------------------
 	# Expr.emit: outputs the unique identifier
 	# -------------------------------------------------------------------------

pulse/transpiler/js_module.py

@@ -10,13 +10,15 @@ import ast
 import inspect
 import sys
 from dataclasses import dataclass, field
-from typing import Literal, override
+from typing import Any, Literal, override
 
+from pulse.code_analysis import is_stub_function
 from pulse.transpiler.errors import TranspileError
 from pulse.transpiler.imports import Import
 from pulse.transpiler.nodes import (
 	Expr,
 	Identifier,
+	Jsx,
 	Member,
 	New,
 )
@@ -91,6 +93,7 @@ class JsModule(Expr):
 			- "member": Access as property (e.g., React.useState)
 			- "named_import": Each attribute is a named import (e.g., import { useState } from "react")
 		constructors: Set of names that are constructors (emit with 'new')
+		components: Set of names that are components (wrapped with Jsx)
 	"""
 
 	name: str | None
@@ -99,6 +102,7 @@ class JsModule(Expr):
 	kind: Literal["default", "namespace"] = "namespace"
 	values: Literal["member", "named_import"] = "named_import"
 	constructors: frozenset[str] = field(default_factory=frozenset)
+	components: frozenset[str] = field(default_factory=frozenset)
 
 	@override
 	def emit(self, out: list[str]) -> None:
@@ -159,7 +163,7 @@ class JsModule(Expr):
 		import_kind = "default" if self.kind == "default" else "named"
 		return Import(self.name, self.src, kind=import_kind)
 
-	def get_value(self, name: str) -> Member | Class | Identifier | Import:
+	def get_value(self, name: str) -> Member | Class | Jsx | Identifier | Import:
 		"""Get a member of this module as an expression.
 
 		For global-identifier modules (name=None): returns Identifier directly (e.g., Set -> Set)
@@ -169,6 +173,7 @@ class JsModule(Expr):
 		For external modules with "named_import" style: returns a named Import
 
 		If name is in constructors, returns a Class that emits `new ...(...)`.
+		If name is in components, returns a Jsx-wrapped expression.
 		"""
 		# Convention: trailing underscore escapes Python keywords (e.g. from_ -> from, is_ -> is).
 		# We keep the original `name` for constructor detection, but emit the JS name.
@@ -188,6 +193,8 @@ class JsModule(Expr):
 
 		if name in self.constructors:
 			return Class(expr, name=name)
+		if name in self.components:
+			return Jsx(expr)
 		return expr
 
 	@override
@@ -226,28 +233,74 @@ class JsModule(Expr):
 		Example (inside pulse/js/set.py):
 			JsModule.register(name=None)  # global identifier builtin (no module binding)
 		"""
+		from pulse.component import Component  # Import here to avoid cycles
+
 		# Get the calling module from the stack frame
 		frame = inspect.currentframe()
 		assert frame is not None and frame.f_back is not None
 		module_name = frame.f_back.f_globals["__name__"]
 		module = sys.modules[module_name]
 
-		# Collect locally defined names and clean up module namespace
+		# Collect locally defined names and clean up module namespace.
+		# Priority order for categorization:
+		#   1. Overrides: real functions (with body), Exprs, real @components → returned directly
+		#   2. Components: stub @component functions → wrapped as Jsx(Import(...))
+		#   3. Constructors: classes → emitted with 'new' keyword
+		#   4. Regular imports: stub functions → standard named imports
 		constructors: set[str] = set()
+		components: set[str] = set()
 		local_names: set[str] = set()
+		overrides: dict[str, Any] = {}
 
 		for attr_name in list(vars(module)):
-			if attr_name in _MODULE_DUNDERS:
+			if attr_name in _MODULE_DUNDERS or attr_name.startswith("_"):
 				continue
 
 			obj = getattr(module, attr_name)
+
+			# Component-wrapped function - check the raw function's module
+			if isinstance(obj, Component):
+				raw_fn = obj._raw_fn  # pyright: ignore[reportPrivateUsage]
+				fn_module = getattr(raw_fn, "__module__", None)
+				if fn_module != module_name:
+					delattr(module, attr_name)
+					continue
+				if is_stub_function(raw_fn):
+					# Stub component → becomes Jsx(Import(...))
+					components.add(attr_name)
+					local_names.add(attr_name)
+				else:
+					# Real component → preserve as override
+					overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
 			is_local = not hasattr(obj, "__module__") or obj.__module__ == module_name
+			if not is_local:
+				delattr(module, attr_name)
+				continue
 
-			if is_local and not attr_name.startswith("_"):
+			# Existing Expr (e.g., manually created Jsx)
+			if isinstance(obj, Expr):
+				overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
+			# Real function with body → preserve as override
+			if inspect.isfunction(obj) and not is_stub_function(obj):
+				overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
+			# Class → constructor (existing behavior)
+			if inspect.isclass(obj):
+				constructors.add(attr_name)
 				local_names.add(attr_name)
-				if inspect.isclass(obj):
-					constructors.add(attr_name)
+				delattr(module, attr_name)
+				continue
 
+			# Stub function → regular import (existing behavior)
+			local_names.add(attr_name)
 			delattr(module, attr_name)
 
 		# Add annotated constants to local_names
@@ -268,11 +321,14 @@ class JsModule(Expr):
 			kind=kind,
 			values=values,
 			constructors=frozenset(constructors),
+			components=frozenset(components),
 		)
 		# Register the module object itself so `import pulse.js.math as Math` resolves via EXPR_REGISTRY.
 		Expr.register(module, js_module)
 
-		def __getattr__(name: str) -> Member | Class | Identifier | Import:
+		def __getattr__(name: str) -> Member | Class | Jsx | Identifier | Import | Any:
+			if name in overrides:
+				return overrides[name]
 			if name.startswith("_") or name not in local_names:
 				raise AttributeError(name)
 			return js_module.get_value(name)

pulse/transpiler/py_module.py

@@ -124,13 +124,7 @@ class PyModule(Expr):
 		elif hasattr(transpilation, "_transpiler"):
 			transpiler_dict = transpilation._transpiler
 		else:
-			# Legacy: class namespace without PyModule inheritance
-			items = (
-				(name, getattr(transpilation, name))
-				for name in dir(transpilation)
-				if not name.startswith("_")
-			)
-			transpiler_dict = PyModule._build_transpiler(items)
+			raise TypeError("PyModule.register expects a PyModule subclass or dict")
 
 		# Register individual values for lookup by id
 		for attr_name, expr in transpiler_dict.items():

pulse/transpiler/transpiler.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import ast
 import re
 from collections.abc import Callable, Mapping
+from pathlib import Path
 from typing import Any, cast
 
 from pulse.transpiler.builtins import BUILTINS, emit_method
@@ -94,6 +95,7 @@ class Transpiler:
 	deps: Mapping[str, Expr]
 	locals: set[str]
 	jsx: bool
+	source_file: Path | None
 	_temp_counter: int
 
 	def __init__(
@@ -102,8 +104,10 @@ class Transpiler:
 		deps: Mapping[str, Expr],
 		*,
 		jsx: bool = False,
+		source_file: Path | None = None,
 	) -> None:
 		self.fndef = fndef
+		self.source_file = source_file
 		# Collect all argument names (regular, vararg, kwonly, kwarg)
 		args: list[str] = [arg.arg for arg in fndef.args.args]
 		if fndef.args.vararg: