pulse-framework 0.1.75__py3-none-any.whl → 0.1.76__py3-none-any.whl

pulse/__init__.py

@@ -1409,6 +1409,18 @@ from pulse.reactive_extensions import (
 from pulse.reactive_extensions import (
 	unwrap as unwrap,
 )
+from pulse.refs import (
+	RefHandle as RefHandle,
+)
+from pulse.refs import (
+	RefNotMounted as RefNotMounted,
+)
+from pulse.refs import (
+	RefTimeout as RefTimeout,
+)
+from pulse.refs import (
+	ref as ref,
+)
 
 # JavaScript execution
 from pulse.render_session import JsExecError as JsExecError

pulse/channel.py

@@ -81,7 +81,9 @@ class ChannelsManager:
 		self.pending_requests = {}
 
 	# ------------------------------------------------------------------
-	def create(self, identifier: str | None = None) -> "Channel":
+	def create(
+		self, identifier: str | None = None, *, bind_route: bool = True
+	) -> "Channel":
 		ctx = PulseContext.get()
 		render = ctx.render
 		session = ctx.session
@@ -93,7 +95,7 @@ class ChannelsManager:
 			raise ValueError(f"Channel id '{channel_id}' is already in use")
 
 		route_path: str | None = None
-		if ctx.route is not None:
+		if bind_route and ctx.route is not None:
 			# unique_path() returns absolute path, use as-is for keys
 			route_path = ctx.route.pulse_route.unique_path()
 
@@ -129,7 +131,8 @@ class ChannelsManager:
 		if not response_to:
 			return
 
-		if error := message.get("error") is not None:
+		error = message.get("error")
+		if error is not None:
 			self.resolve_pending_error(response_to, error)
 		else:
 			self._resolve_pending_success(response_to, message.get("payload"))

pulse/dom/props.py

@@ -68,6 +68,7 @@ from pulse.dom.events import (
 	TextAreaDOMEvents,
 )
 from pulse.helpers import CSSProperties
+from pulse.refs import RefHandle
 from pulse.transpiler.nodes import Expr
 
 Booleanish = Literal[True, False, "true", "false"]
@@ -82,6 +83,7 @@ class BaseHTMLProps(TypedDict, total=False):
 	defaultValue: str | int | list[str]
 	suppressContentEditableWarning: bool
 	suppressHydrationWarning: bool
+	ref: RefHandle[Any]
 
 	# Standard HTML Attributes
 	accessKey: str

pulse/refs.py

@@ -0,0 +1,893 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+import uuid
+from collections.abc import Callable
+from typing import Any, Generic, Literal, TypeVar, cast, overload, override
+
+from pulse.channel import Channel
+from pulse.context import PulseContext
+from pulse.helpers import Disposable
+from pulse.hooks.core import HookMetadata, HookState, hooks
+from pulse.hooks.state import collect_component_identity
+from pulse.scheduling import create_future, create_task
+
+T = TypeVar("T")
+Number = int | float
+
+_ATTR_ALIASES: dict[str, str] = {
+	"className": "class",
+	"htmlFor": "for",
+	"tabIndex": "tabindex",
+}
+
+_ATTR_NAME_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_:\-\.]*$")
+
+_GETTABLE_PROPS: set[str] = {
+	"value",
+	"checked",
+	"disabled",
+	"readOnly",
+	"selectedIndex",
+	"selectionStart",
+	"selectionEnd",
+	"selectionDirection",
+	"scrollTop",
+	"scrollLeft",
+	"scrollHeight",
+	"scrollWidth",
+	"clientWidth",
+	"clientHeight",
+	"offsetWidth",
+	"offsetHeight",
+	"innerText",
+	"textContent",
+	"className",
+	"id",
+	"name",
+	"type",
+	"tabIndex",
+}
+
+_SETTABLE_PROPS: set[str] = {
+	"value",
+	"checked",
+	"disabled",
+	"readOnly",
+	"selectedIndex",
+	"selectionStart",
+	"selectionEnd",
+	"selectionDirection",
+	"scrollTop",
+	"scrollLeft",
+	"className",
+	"id",
+	"name",
+	"type",
+	"tabIndex",
+}
+
+
+def _normalize_attr_name(name: str) -> str:
+	return _ATTR_ALIASES.get(name, name)
+
+
+def _validate_attr_name(name: str) -> str:
+	if not isinstance(name, str):
+		raise TypeError("ref attribute name must be a string")
+	trimmed = name.strip()
+	if not trimmed:
+		raise ValueError("ref attribute name must be non-empty")
+	normalized = _normalize_attr_name(trimmed)
+	if not _ATTR_NAME_PATTERN.match(normalized):
+		raise ValueError(f"Invalid attribute name: {normalized}")
+	if normalized.lower().startswith("on"):
+		raise ValueError("ref attribute name cannot start with 'on'")
+	return normalized
+
+
+def _validate_prop_name(name: str, *, settable: bool) -> str:
+	if not isinstance(name, str):
+		raise TypeError("ref property name must be a string")
+	trimmed = name.strip()
+	if not trimmed:
+		raise ValueError("ref property name must be non-empty")
+	if trimmed not in _GETTABLE_PROPS:
+		raise ValueError(f"Unsupported ref property: {trimmed}")
+	if settable and trimmed not in _SETTABLE_PROPS:
+		raise ValueError(f"Ref property is read-only: {trimmed}")
+	return trimmed
+
+
+class RefNotMounted(RuntimeError):
+	"""Raised when a ref operation is attempted before mount."""
+
+
+class RefTimeout(asyncio.TimeoutError):
+	"""Raised when waiting for a ref mount times out."""
+
+
+class RefHandle(Disposable, Generic[T]):
+	"""Server-side handle for a client DOM ref."""
+
+	__slots__: tuple[str, ...] = (
+		"_channel",
+		"id",
+		"_mounted",
+		"_mount_waiters",
+		"_mount_handlers",
+		"_unmount_handlers",
+		"_owns_channel",
+		"_remove_mount",
+		"_remove_unmount",
+	)
+
+	_channel: Channel
+	id: str
+	_mounted: bool
+	_mount_waiters: list[asyncio.Future[None]]
+	_mount_handlers: list[Callable[[], Any]]
+	_unmount_handlers: list[Callable[[], Any]]
+	_owns_channel: bool
+	_remove_mount: Callable[[], None] | None
+	_remove_unmount: Callable[[], None] | None
+
+	def __init__(
+		self,
+		channel: Channel,
+		*,
+		ref_id: str | None = None,
+		owns_channel: bool = True,
+	) -> None:
+		self._channel = channel
+		self.id = ref_id or uuid.uuid4().hex
+		self._mounted = False
+		self._mount_waiters = []
+		self._mount_handlers = []
+		self._unmount_handlers = []
+		self._owns_channel = owns_channel
+		self._remove_mount = self._channel.on("ref:mounted", self._on_mounted)
+		self._remove_unmount = self._channel.on("ref:unmounted", self._on_unmounted)
+
+	@property
+	def channel_id(self) -> str:
+		return self._channel.id
+
+	@property
+	def mounted(self) -> bool:
+		return self._mounted
+
+	def on_mount(self, handler: Callable[[], Any]) -> Callable[[], None]:
+		self._mount_handlers.append(handler)
+
+		def _remove() -> None:
+			try:
+				self._mount_handlers.remove(handler)
+			except ValueError:
+				return
+
+		return _remove
+
+	def on_unmount(self, handler: Callable[[], Any]) -> Callable[[], None]:
+		self._unmount_handlers.append(handler)
+
+		def _remove() -> None:
+			try:
+				self._unmount_handlers.remove(handler)
+			except ValueError:
+				return
+
+		return _remove
+
+	async def wait_mounted(self, timeout: float | None = None) -> None:
+		if self._mounted:
+			return
+		fut = create_future()
+		self._mount_waiters.append(fut)
+		try:
+			if timeout is None:
+				await fut
+			else:
+				await asyncio.wait_for(fut, timeout=timeout)
+		except asyncio.TimeoutError as exc:
+			raise RefTimeout("Timed out waiting for ref to mount") from exc
+		finally:
+			if fut in self._mount_waiters:
+				self._mount_waiters.remove(fut)
+
+	def focus(self, *, prevent_scroll: bool | None = None) -> None:
+		payload = None
+		if prevent_scroll is not None:
+			if not isinstance(prevent_scroll, bool):
+				raise TypeError("focus() prevent_scroll must be a bool")
+			payload = {"preventScroll": prevent_scroll}
+		self._emit("focus", payload)
+
+	def blur(self) -> None:
+		self._emit("blur")
+
+	def click(self) -> None:
+		self._emit("click")
+
+	def submit(self) -> None:
+		self._emit("submit")
+
+	def reset(self) -> None:
+		self._emit("reset")
+
+	def scroll_into_view(
+		self,
+		*,
+		behavior: str | None = None,
+		block: str | None = None,
+		inline: str | None = None,
+	) -> None:
+		payload = {
+			k: v
+			for k, v in {
+				"behavior": behavior,
+				"block": block,
+				"inline": inline,
+			}.items()
+			if v is not None
+		}
+		self._emit("scrollIntoView", payload if payload else None)
+
+	def scroll_to(
+		self,
+		*,
+		top: float | int | None = None,
+		left: float | int | None = None,
+		behavior: str | None = None,
+	) -> None:
+		if top is not None and not isinstance(top, (int, float)):
+			raise TypeError("scroll_to() top must be a number")
+		if left is not None and not isinstance(left, (int, float)):
+			raise TypeError("scroll_to() left must be a number")
+		if behavior is not None and not isinstance(behavior, str):
+			raise TypeError("scroll_to() behavior must be a string")
+		payload = {
+			k: v
+			for k, v in {
+				"top": top,
+				"left": left,
+				"behavior": behavior,
+			}.items()
+			if v is not None
+		}
+		self._emit("scrollTo", payload if payload else None)
+
+	def scroll_by(
+		self,
+		*,
+		top: float | int | None = None,
+		left: float | int | None = None,
+		behavior: str | None = None,
+	) -> None:
+		if top is not None and not isinstance(top, (int, float)):
+			raise TypeError("scroll_by() top must be a number")
+		if left is not None and not isinstance(left, (int, float)):
+			raise TypeError("scroll_by() left must be a number")
+		if behavior is not None and not isinstance(behavior, str):
+			raise TypeError("scroll_by() behavior must be a string")
+		payload = {
+			k: v
+			for k, v in {
+				"top": top,
+				"left": left,
+				"behavior": behavior,
+			}.items()
+			if v is not None
+		}
+		self._emit("scrollBy", payload if payload else None)
+
+	async def measure(self, *, timeout: float | None = None) -> dict[str, Any] | None:
+		result = await self._request("measure", timeout=timeout)
+		if result is None:
+			return None
+		if isinstance(result, dict):
+			return result
+		raise TypeError("measure() expected dict result")
+
+	async def get_value(self, *, timeout: float | None = None) -> Any:
+		return await self._request("getValue", timeout=timeout)
+
+	async def set_value(self, value: Any, *, timeout: float | None = None) -> Any:
+		return await self._request("setValue", {"value": value}, timeout=timeout)
+
+	async def get_text(self, *, timeout: float | None = None) -> str | None:
+		result = await self._request("getText", timeout=timeout)
+		if result is None:
+			return None
+		if isinstance(result, str):
+			return result
+		raise TypeError("get_text() expected string result")
+
+	async def set_text(self, text: str, *, timeout: float | None = None) -> str | None:
+		result = await self._request("setText", {"text": text}, timeout=timeout)
+		if result is None:
+			return None
+		if isinstance(result, str):
+			return result
+		raise TypeError("set_text() expected string result")
+
+	def select(self) -> None:
+		self._emit("select")
+
+	def set_selection_range(
+		self, start: int, end: int, *, direction: str | None = None
+	) -> None:
+		if not isinstance(start, int) or not isinstance(end, int):
+			raise TypeError("set_selection_range() requires integer start/end")
+		if direction is not None and not isinstance(direction, str):
+			raise TypeError("set_selection_range() direction must be a string")
+		payload: dict[str, Any] = {"start": start, "end": end}
+		if direction is not None:
+			payload["direction"] = direction
+		self._emit("setSelectionRange", payload)
+
+	@overload
+	async def get_attr(
+		self,
+		name: Literal[
+			"className",
+			"class",
+			"id",
+			"name",
+			"type",
+			"title",
+			"placeholder",
+			"role",
+			"href",
+			"src",
+			"alt",
+			"htmlFor",
+			"for",
+			"tabIndex",
+			"tabindex",
+			"aria-label",
+			"aria-hidden",
+			"data-test",
+			"value",
+		],
+		*,
+		timeout: float | None = None,
+	) -> str | None: ...
+
+	@overload
+	async def get_attr(
+		self, name: str, *, timeout: float | None = None
+	) -> str | None: ...
+
+	async def get_attr(self, name: str, *, timeout: float | None = None) -> str | None:
+		normalized = _validate_attr_name(name)
+		result = await self._request("getAttr", {"name": normalized}, timeout=timeout)
+		if result is None:
+			return None
+		if isinstance(result, str):
+			return result
+		raise TypeError("get_attr() expected string result")
+
+	@overload
+	async def set_attr(
+		self,
+		name: Literal[
+			"className",
+			"class",
+			"id",
+			"name",
+			"type",
+			"title",
+			"placeholder",
+			"role",
+			"href",
+			"src",
+			"alt",
+			"htmlFor",
+			"for",
+			"tabIndex",
+			"tabindex",
+			"aria-label",
+			"aria-hidden",
+			"data-test",
+			"value",
+		],
+		value: str | int | float | bool | None,
+		*,
+		timeout: float | None = None,
+	) -> str | None: ...
+
+	@overload
+	async def set_attr(
+		self,
+		name: str,
+		value: Any,
+		*,
+		timeout: float | None = None,
+	) -> str | None: ...
+
+	async def set_attr(
+		self, name: str, value: Any, *, timeout: float | None = None
+	) -> str | None:
+		normalized = _validate_attr_name(name)
+		result = await self._request(
+			"setAttr", {"name": normalized, "value": value}, timeout=timeout
+		)
+		if result is None:
+			return None
+		if isinstance(result, str):
+			return result
+		raise TypeError("set_attr() expected string result")
+
+	async def remove_attr(self, name: str, *, timeout: float | None = None) -> None:
+		normalized = _validate_attr_name(name)
+		await self._request("removeAttr", {"name": normalized}, timeout=timeout)
+
+	@overload
+	async def get_prop(
+		self, name: Literal["value"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["checked"], *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["disabled"], *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["readOnly"], *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["selectedIndex"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["selectionStart"], *, timeout: float | None = None
+	) -> Number | None: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["selectionEnd"], *, timeout: float | None = None
+	) -> Number | None: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["selectionDirection"], *, timeout: float | None = None
+	) -> str | None: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["scrollTop"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["scrollLeft"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["scrollHeight"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["scrollWidth"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["clientWidth"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["clientHeight"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["offsetWidth"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["offsetHeight"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["innerText"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["textContent"], *, timeout: float | None = None
+	) -> str | None: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["className"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["id"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["name"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["type"], *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def get_prop(
+		self, name: Literal["tabIndex"], *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def get_prop(self, name: str, *, timeout: float | None = None) -> Any: ...
+
+	async def get_prop(self, name: str, *, timeout: float | None = None) -> Any:
+		prop = _validate_prop_name(name, settable=False)
+		return await self._request("getProp", {"name": prop}, timeout=timeout)
+
+	@overload
+	async def set_prop(
+		self, name: Literal["value"], value: str, *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["checked"], value: bool, *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["disabled"], value: bool, *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["readOnly"], value: bool, *, timeout: float | None = None
+	) -> bool: ...
+
+	@overload
+	async def set_prop(
+		self,
+		name: Literal["selectedIndex"],
+		value: Number,
+		*,
+		timeout: float | None = None,
+	) -> Number: ...
+
+	@overload
+	async def set_prop(
+		self,
+		name: Literal["selectionStart"],
+		value: Number | None,
+		*,
+		timeout: float | None = None,
+	) -> Number | None: ...
+
+	@overload
+	async def set_prop(
+		self,
+		name: Literal["selectionEnd"],
+		value: Number | None,
+		*,
+		timeout: float | None = None,
+	) -> Number | None: ...
+
+	@overload
+	async def set_prop(
+		self,
+		name: Literal["selectionDirection"],
+		value: str | None,
+		*,
+		timeout: float | None = None,
+	) -> str | None: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["scrollTop"], value: Number, *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def set_prop(
+		self,
+		name: Literal["scrollLeft"],
+		value: Number,
+		*,
+		timeout: float | None = None,
+	) -> Number: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["className"], value: str, *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["id"], value: str, *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["name"], value: str, *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["type"], value: str, *, timeout: float | None = None
+	) -> str: ...
+
+	@overload
+	async def set_prop(
+		self, name: Literal["tabIndex"], value: Number, *, timeout: float | None = None
+	) -> Number: ...
+
+	@overload
+	async def set_prop(
+		self, name: str, value: Any, *, timeout: float | None = None
+	) -> Any: ...
+
+	async def set_prop(
+		self, name: str, value: Any, *, timeout: float | None = None
+	) -> Any:
+		prop = _validate_prop_name(name, settable=True)
+		return await self._request(
+			"setProp", {"name": prop, "value": value}, timeout=timeout
+		)
+
+	async def set_style(
+		self, styles: dict[str, Any], *, timeout: float | None = None
+	) -> None:
+		if not isinstance(styles, dict):
+			raise TypeError("set_style() requires a dict")
+		for key, value in styles.items():
+			if not isinstance(key, str) or not key:
+				raise ValueError("set_style() keys must be non-empty strings")
+			if isinstance(value, bool):
+				raise TypeError("set_style() values must be string, number, or None")
+			if value is not None and not isinstance(value, (str, int, float)):
+				raise TypeError("set_style() values must be string, number, or None")
+		await self._request("setStyle", {"styles": styles}, timeout=timeout)
+
+	def _emit(self, op: str, payload: Any = None) -> None:
+		self._ensure_mounted()
+		self._channel.emit(
+			"ref:call",
+			{"refId": self.id, "op": op, "payload": payload},
+		)
+
+	async def _request(
+		self,
+		op: str,
+		payload: Any = None,
+		*,
+		timeout: float | None = None,
+	) -> Any:
+		self._ensure_mounted()
+		return await self._channel.request(
+			"ref:request",
+			{"refId": self.id, "op": op, "payload": payload},
+			timeout=timeout,
+		)
+
+	def _ensure_mounted(self) -> None:
+		if not self._mounted:
+			raise RefNotMounted("Ref is not mounted")
+
+	def _on_mounted(self, payload: Any) -> None:
+		if isinstance(payload, dict):
+			ref_id = cast(dict[str, Any], payload).get("refId")
+			if ref_id is not None and str(ref_id) != self.id:
+				return
+		self._mounted = True
+		for fut in list(self._mount_waiters):
+			if not fut.done():
+				fut.set_result(None)
+		self._mount_waiters.clear()
+		self._run_handlers(self._mount_handlers, label="mount")
+
+	def _on_unmounted(self, payload: Any) -> None:
+		if isinstance(payload, dict):
+			ref_id = cast(dict[str, Any], payload).get("refId")
+			if ref_id is not None and str(ref_id) != self.id:
+				return
+		self._mounted = False
+		self._run_handlers(self._unmount_handlers, label="unmount")
+
+	def _run_handlers(self, handlers: list[Callable[[], Any]], *, label: str) -> None:
+		for handler in list(handlers):
+			try:
+				result = handler()
+			except Exception:
+				# Fail early: propagate on next render via error log if desired
+				raise
+			if inspect.isawaitable(result):
+				task = create_task(result, name=f"ref:{self.id}:{label}")
+
+				def _on_done(done_task: asyncio.Future[Any]) -> None:
+					if done_task.cancelled():
+						return
+					try:
+						done_task.result()
+					except asyncio.CancelledError:
+						return
+					except Exception as exc:
+						loop = done_task.get_loop()
+						loop.call_exception_handler(
+							{
+								"message": f"Unhandled exception in ref {label} handler",
+								"exception": exc,
+								"context": {"ref_id": self.id, "handler": label},
+							}
+						)
+
+				task.add_done_callback(_on_done)
+
+	@override
+	def dispose(self) -> None:
+		self._mounted = False
+		if self._remove_mount is not None:
+			self._remove_mount()
+			self._remove_mount = None
+		if self._remove_unmount is not None:
+			self._remove_unmount()
+			self._remove_unmount = None
+		for fut in list(self._mount_waiters):
+			if not fut.done():
+				fut.set_exception(RefNotMounted("Ref disposed"))
+		self._mount_waiters.clear()
+		self._mount_handlers.clear()
+		self._unmount_handlers.clear()
+		if self._owns_channel:
+			self._channel.close()
+
+	@override
+	def __repr__(self) -> str:
+		return f"RefHandle(id={self.id}, channel={self.channel_id})"
+
+
+class RefHookState(HookState):
+	__slots__: tuple[str, ...] = (
+		"instances",
+		"called_keys",
+		"_channel",
+	)
+	instances: dict[tuple[str, Any], RefHandle[Any]]
+	called_keys: set[tuple[str, Any]]
+	_channel: Channel | None
+
+	def __init__(self) -> None:
+		super().__init__()
+		self.instances = {}
+		self.called_keys = set()
+		self._channel = None
+
+	def _make_key(self, identity: Any, key: str | None) -> tuple[str, Any]:
+		if key is None:
+			return ("code", identity)
+		return ("key", key)
+
+	@override
+	def on_render_start(self, render_cycle: int) -> None:
+		super().on_render_start(render_cycle)
+		self.called_keys.clear()
+
+	def get_or_create(
+		self, identity: Any, key: str | None
+	) -> tuple[RefHandle[Any], bool]:
+		full_identity = self._make_key(identity, key)
+		if full_identity in self.called_keys:
+			if key is None:
+				raise RuntimeError(
+					"`pulse.ref` can only be called once per component render at the same location. "
+					+ "Use the `key` parameter to disambiguate: ps.ref(key=unique_value)"
+				)
+			raise RuntimeError(
+				f"`pulse.ref` can only be called once per component render with key='{key}'"
+			)
+		self.called_keys.add(full_identity)
+
+		existing = self.instances.get(full_identity)
+		if existing is not None:
+			if existing.__disposed__:
+				key_label = f"key='{key}'" if key is not None else "callsite"
+				raise RuntimeError(
+					"`pulse.ref` found a disposed cached RefHandle for "
+					+ key_label
+					+ ". Do not dispose handles returned by `pulse.ref`."
+				)
+			return existing, False
+
+		if self._channel is None or self._channel.closed:
+			ctx = PulseContext.get()
+			if ctx.render is None:
+				raise RuntimeError("ref() requires an active render session")
+			self._channel = ctx.render.get_ref_channel()
+		handle = RefHandle(self._channel, owns_channel=False)
+		self.instances[full_identity] = handle
+		return handle, True
+
+	@override
+	def dispose(self) -> None:
+		for handle in self.instances.values():
+			try:
+				handle.dispose()
+			except Exception:
+				pass
+		self._channel = None
+		self.instances.clear()
+
+
+ref_hook_state = hooks.create(
+	"pulse:core.ref",
+	factory=RefHookState,
+	metadata=HookMetadata(
+		owner="pulse.core",
+		description="Internal storage for pulse.ref handles",
+	),
+)
+
+
+def ref(
+	*,
+	key: str | None = None,
+	on_mount: Callable[[], Any] | None = None,
+	on_unmount: Callable[[], Any] | None = None,
+) -> RefHandle[Any]:
+	"""Create or retrieve a stable ref handle for a component.
+
+	Args:
+		key: Optional key to disambiguate multiple refs created at the same callsite.
+		on_mount: Optional handler called when the ref mounts.
+		on_unmount: Optional handler called when the ref unmounts.
+	"""
+	if key is not None and not isinstance(key, str):
+		raise TypeError("ref() key must be a string")
+	if key == "":
+		raise ValueError("ref() requires a non-empty string key")
+	if on_mount is not None and not callable(on_mount):
+		raise TypeError("ref() on_mount must be callable")
+	if on_unmount is not None and not callable(on_unmount):
+		raise TypeError("ref() on_unmount must be callable")
+
+	identity: Any
+	if key is None:
+		frame = inspect.currentframe()
+		assert frame is not None
+		caller = frame.f_back
+		assert caller is not None
+		identity = collect_component_identity(caller)
+	else:
+		identity = key
+
+	hook_state = ref_hook_state()
+	handle, created = hook_state.get_or_create(identity, key)
+	if created:
+		if on_mount is not None:
+			handle.on_mount(on_mount)
+		if on_unmount is not None:
+			handle.on_unmount(on_unmount)
+	return handle
+
+
+__all__ = ["RefHandle", "RefNotMounted", "RefTimeout", "ref"]

pulse/render_session.py

@@ -6,6 +6,7 @@ from asyncio import iscoroutine
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any, Literal, TypeVar, overload
 
+from pulse.channel import Channel
 from pulse.context import PulseContext
 from pulse.hooks.runtime import NotFoundInterrupt, RedirectInterrupt
 from pulse.messages import (
@@ -257,6 +258,8 @@ class RenderSession:
 	_send_message: Callable[[ServerMessage], Any] | None
 	_pending_api: dict[str, asyncio.Future[dict[str, Any]]]
 	_pending_js_results: dict[str, asyncio.Future[Any]]
+	_ref_channel: Channel | None
+	_ref_channels_by_route: dict[str, Channel]
 	_global_states: dict[str, State]
 	_global_queue: list[ServerMessage]
 	_tasks: TaskRegistry
@@ -290,6 +293,8 @@ class RenderSession:
 		self.forms = FormRegistry(self)
 		self._pending_api = {}
 		self._pending_js_results = {}
+		self._ref_channel = None
+		self._ref_channels_by_route = {}
 		self._tasks = TaskRegistry(name=f"render:{id}")
 		self._timers = TimerRegistry(tasks=self._tasks, name=f"render:{id}")
 		self.query_store = QueryStore()
@@ -479,6 +484,7 @@ class RenderSession:
 			return
 		try:
 			self.route_mounts.pop(path, None)
+			self._ref_channels_by_route.pop(path, None)
 			mount.dispose()
 		except Exception as e:
 			self.report_error(path, "unmount", e)
@@ -486,6 +492,7 @@ class RenderSession:
 	def detach(self, path: str, *, timeout: float | None = None):
 		"""Client no longer wants updates. Queue briefly, then dispose."""
 		path = ensure_absolute_path(path)
+		self._ref_channels_by_route.pop(path, None)
 		mount = self.route_mounts.get(path)
 		if not mount:
 			return
@@ -598,6 +605,8 @@ class RenderSession:
 			if not fut.done():
 				fut.cancel()
 		self._pending_js_results.clear()
+		self._ref_channel = None
+		self._ref_channels_by_route.clear()
 		# Close any timer that may have been scheduled during cleanup (ex: query GC)
 		self._timers.cancel_all()
 		self._global_queue = []
@@ -619,6 +628,24 @@ class RenderSession:
 			self._global_states[key] = inst
 		return inst
 
+	def get_ref_channel(self) -> Channel:
+		ctx = PulseContext.get()
+		if ctx.route is None:
+			if self._ref_channel is not None and not self._ref_channel.closed:
+				return self._ref_channel
+			self._ref_channel = self.channels.create(bind_route=False)
+			return self._ref_channel
+
+		route_path = ctx.route.pulse_route.unique_path()
+		channel = self._ref_channels_by_route.get(route_path)
+		if channel is not None and channel.closed:
+			self._ref_channels_by_route.pop(route_path, None)
+			channel = None
+		if channel is None:
+			channel = self.channels.create(bind_route=True)
+			self._ref_channels_by_route[route_path] = channel
+		return channel
+
 	def flush(self):
 		with PulseContext.update(render=self):
 			flush_effects()

pulse/renderer.py

@@ -9,6 +9,7 @@ from typing import Any, NamedTuple, TypeAlias, cast
 from pulse.debounce import Debounced
 from pulse.helpers import values_equal
 from pulse.hooks.core import HookContext
+from pulse.refs import RefHandle
 from pulse.transpiler import Import
 from pulse.transpiler.function import Constant, JsFunction, JsxFunction
 from pulse.transpiler.nodes import (
@@ -34,7 +35,7 @@ from pulse.transpiler.vdom import (
 	VDOMPropValue,
 )
 
-PropValue: TypeAlias = Node | Callable[..., Any] | Debounced[Any, Any]
+PropValue: TypeAlias = Node | Callable[..., Any] | Debounced[Any, Any] | RefHandle[Any]
 
 FRAGMENT_TAG = ""
 MOUNT_PREFIX = "$$"
@@ -405,6 +406,25 @@ class Renderer:
 					updated[key] = value.render()
 				continue
 
+			if isinstance(value, RefHandle):
+				if key != "ref":
+					raise TypeError("RefHandle can only be used as the 'ref' prop")
+				eval_keys.add(key)
+				if isinstance(old_value, (Element, PulseNode)):
+					unmount_element(old_value)
+				if normalized is None:
+					normalized = current.copy()
+				normalized[key] = value
+				if not (
+					isinstance(old_value, RefHandle) and values_equal(old_value, value)
+				):
+					updated[key] = {
+						"__pulse_ref__": {
+							"channelId": value.channel_id,
+							"refId": value.id,
+						}
+					}
+				continue
 			if isinstance(value, Debounced):
 				eval_keys.add(key)
 				if isinstance(old_value, (Element, PulseNode)):
@@ -499,6 +519,8 @@ def prop_requires_eval(value: PropValue) -> bool:
 		return True
 	if isinstance(value, Expr):
 		return True
+	if isinstance(value, RefHandle):
+		return True
 	if isinstance(value, Debounced):
 		return True
 	return callable(value)

pulse/transpiler/vdom.py

@@ -161,7 +161,18 @@ single sentinel string. Debounced callbacks use "$cb:<delay_ms>" in the wire for
 """
 
 
-VDOMPropValue: TypeAlias = "JsonValue | VDOMExpr | VDOMElement | CallbackPlaceholder"
+class PulseRefPayload(TypedDict):
+	channelId: str
+	refId: str
+
+
+class PulseRefSpec(TypedDict):
+	__pulse_ref__: PulseRefPayload
+
+
+VDOMPropValue: TypeAlias = (
+	"JsonValue | VDOMExpr | VDOMElement | CallbackPlaceholder | PulseRefSpec"
+)
 """Allowed prop value types.
 
 Hot path:

{pulse_framework-0.1.75.dist-info → pulse_framework-0.1.76.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.75
+Version: 0.1.76
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: fastapi>=0.128.0
 Requires-Dist: uvicorn>=0.24.0

{pulse_framework-0.1.75.dist-info → pulse_framework-0.1.76.dist-info}/RECORD

@@ -1,7 +1,7 @@
-pulse/__init__.py,sha256=GUPD8THGENBgHsZvixIP8wOiEtdEMtIVpr8N8MpuRL4,32675
+pulse/__init__.py,sha256=jFSqmTbDLp07bGVr8N7Pa6k0h7Ipq2pYn_tsrr2Ztu8,32881
 pulse/_examples.py,sha256=dFuhD2EVXsbvAeexoG57s4VuN4gWLaTMOEMNYvlPm9A,561
 pulse/app.py,sha256=Bi94rYG-MoldkGa-_CscLMstjTEV8BHVAgDbvapRGzI,36167
-pulse/channel.py,sha256=ePpvD2mDbddt_LMxxxDjNRgOLbVi8Ed6TmJFgkrALB0,15790
+pulse/channel.py,sha256=UkImBCIFr5sWdkpB3dFwwFa-nWyEnl1W3EaLv0BRsMU,15845
 pulse/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/cli/cmd.py,sha256=LQK_B6iANOAqcQCM0KMTfRbpqGYRaPDkEBvvaAS3qNI,15985
 pulse/cli/dependencies.py,sha256=qU-rF7QyP0Rl1Fl0YKQubrGNBzj84BAbH1uUT3ehxik,4283
@@ -33,7 +33,7 @@ pulse/decorators.py,sha256=Lskni9Keqfb-xmUliFQe5x-4AcNqrwdvoh0kuz2fXa0,9958
 pulse/dom/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/dom/elements.py,sha256=YHXkVpfMAC4-0o61fK-E0LGTOM3KMCtBfpHHAwLx7dw,23241
 pulse/dom/events.py,sha256=yHioH8Y-b7raOaZ43JuCxk2lUBryUAcDSc-5VhXtiSI,14699
-pulse/dom/props.py,sha256=WrPwOYSoJmn-VWxU2KvJC1j64L4tlT8X2JpabK94gYQ,26721
+pulse/dom/props.py,sha256=6F3dE_bShI2WdAVfFG0DbIQom2GcM0iF8B3FBE5bj14,26775
 pulse/dom/svg.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/dom/tags.py,sha256=U6mKmwB9JAFM6LTESMJcoIejNfnyxIdQo2-TLM5OaZ0,7585
 pulse/dom/tags.pyi,sha256=0BC7zTh22roPBuMQawL8hgI6IrfN8xJZuDIoKMd4QKc,14393
@@ -106,8 +106,9 @@ pulse/queries/store.py,sha256=iw05_EFpyfiXv5_FV_x4aHtCo00mk0dDPFD461cajcg,3850
 pulse/react_component.py,sha256=8RLg4Bi7IcjqbnbEnp4hJpy8t1UsE7mG0UR1Q655LDk,2332
 pulse/reactive.py,sha256=GSh9wSH3THCBjDTafwWttyx7djeKBWV_KqjaKRYUNsA,31393
 pulse/reactive_extensions.py,sha256=yQ1PpdAh4kMvll7R15T72FOg8NFdG_HGBsGc63dawYk,33754
-pulse/render_session.py,sha256=WKWDOqtIjy9n00HxMiViI-pBHw34QOEhLgZap28BCMg,23431
-pulse/renderer.py,sha256=a4gTEFZuhAc1V5uTcFFcsOREDg6ZU9-jf4Ic7qLo2CY,16902
+pulse/refs.py,sha256=-6QlzJwJ_lLgGGvJDl6OTOkoA6799TvBGla54ZTH_jA,22889
+pulse/render_session.py,sha256=bujJ0Ch7wUgCqjlq3Z0e8zlg6xpkMThCD-daUSCw-xc,24406
+pulse/renderer.py,sha256=xFjF9Ttv7M74BpHDHpAp32rTFztwyQDZcEWhOFLI5MU,17553
 pulse/request.py,sha256=N0oFOLiGxpbgSgxznjvu64lG3YyOcZPKC8JFyKx6X7w,6023
 pulse/requirements.py,sha256=nMnE25Uu-TUuQd88jW7m2xwus6fD-HvXxQ9UNb7OOGc,1254
 pulse/routing.py,sha256=oRfVaeIrsbDR9yW9BYwxVWV3HZI7wk21yZX69IVADIU,17279
@@ -139,12 +140,12 @@ pulse/transpiler/nodes.py,sha256=ObdCFIEvtKMVRO8iy1hIN4L-vC4yPqRvhPS6E344-bE,526
 pulse/transpiler/parse.py,sha256=uz_KDnjmjzFSjGtVKRznWg95P0NHM8CafWgvqrqJcOs,1622
 pulse/transpiler/py_module.py,sha256=um4BYLrbs01bpgv2LEBHTbhXXh8Bs174c3ygv5tHHOg,4410
 pulse/transpiler/transpiler.py,sha256=bu33-wGNqHGheT_ZqMnQgEARyPG6xyOvuLuixjxIZnI,42761
-pulse/transpiler/vdom.py,sha256=Bf1yw10hQl8BXa6rhr5byRa5ua3qgRsVGNgEtQneA2A,6460
+pulse/transpiler/vdom.py,sha256=5ooW9uoWoBEEKBSds27m6Birj3eOuWZ2Qh2nZ4f_kvo,6609
 pulse/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pulse/types/event_handler.py,sha256=psQCydj-WEtBcFU5JU4mDwvyzkW8V2O0g_VFRU2EOHI,1618
 pulse/user_session.py,sha256=nsnsMgqq2xGJZLpbHRMHUHcLrElMP8WcA4gjGMrcoBk,10208
 pulse/version.py,sha256=711vaM1jVIQPgkisGgKZqwmw019qZIsc_QTae75K2pg,1895
-pulse_framework-0.1.75.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-pulse_framework-0.1.75.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
-pulse_framework-0.1.75.dist-info/METADATA,sha256=Y2M3HpMari75ZADpqGSxEfyP5YGCnRS2AkZ3tE3lmpA,8299
-pulse_framework-0.1.75.dist-info/RECORD,,
+pulse_framework-0.1.76.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pulse_framework-0.1.76.dist-info/entry_points.txt,sha256=i7aohd3QaPu5IcuGKKvsQQEiMYMe5HcF56QEsaLVO64,46
+pulse_framework-0.1.76.dist-info/METADATA,sha256=NQtUswIWI_6HPwjmn9htpOBclmshDNxcXdPmhggApNQ,8299
+pulse_framework-0.1.76.dist-info/RECORD,,