리액티브 위젯 값 객체(UiValue) — 위젯을 변수로 담아 .value를 읽게

ui.slider/dropdown/number/checkbox가 bare descriptor 대신 UiValue를 반환한다. UiValue는 위치 기반
안정 id({blockId}#{index})로 워커 store에 값을 영속하고(.value가 live로 읽음, 셀 재실행에도 유지),
codaroDescriptor()로 기존 ui descriptor 형태(+elementId)를 내 프론트 렌더는 불변이다. analyzeCode가
slider.value를 use로 보므로 리액티브 그래프가 위젯→소비자 의존을 이미 포착한다.

워커: 블록 실행 시작 시 beginBlock으로 위치 카운터 리셋, _serializeUiValue로 셀 출력 렌더, layout 중첩
UiValue를 toDescriptor/_sanitizeValue/_sanitizeDescriptor가 descriptor로 변환, reset 시 store 초기화.
값-변경 리액티브 트리거는 다음 커밋(setUiValue 경로). widget-bridge 게이트 정합.

Author: eddmpython

src/codaro/outputDescriptor.py

@@ -4,6 +4,7 @@
 from typing import Any, Callable, Iterable, Mapping, Sequence
 
 from .uiCallbacks import registerCallback
+from .uiValue import UiValue
 
 
 DESCRIPTOR_TYPES = {
@@ -249,16 +250,14 @@ def number(
         max: int | float | None = None,
         step: int | float | None = None,
         onChange: Callable[..., Any] | None = None,
-    ) -> dict[str, Any]:
-        return _uiDescriptor(
-            "number",
-            value=value,
-            label=label,
-            min=min,
-            max=max,
-            step=step,
-            events=_bindEvents(change=onChange),
-        )
+    ) -> UiValue:
+        return UiValue("number", value, {
+            "label": label,
+            "min": min,
+            "max": max,
+            "step": step,
+            "events": _bindEvents(change=onChange),
+        })
 
     def slider(
         self,
@@ -269,30 +268,26 @@ def slider(
         step: int | float = 1,
         label: str = "",
         onChange: Callable[..., Any] | None = None,
-    ) -> dict[str, Any]:
-        return _uiDescriptor(
-            "slider",
-            value=start if value is None else value,
-            label=label,
-            min=start,
-            max=stop,
-            step=step,
-            events=_bindEvents(change=onChange),
-        )
+    ) -> UiValue:
+        return UiValue("slider", start if value is None else value, {
+            "label": label,
+            "min": start,
+            "max": stop,
+            "step": step,
+            "events": _bindEvents(change=onChange),
+        })
 
     def checkbox(
         self,
         value: bool = False,
         *,
         label: str = "",
         onChange: Callable[..., Any] | None = None,
-    ) -> dict[str, Any]:
-        return _uiDescriptor(
-            "checkbox",
-            value=bool(value),
-            label=label,
-            events=_bindEvents(change=onChange),
-        )
+    ) -> UiValue:
+        return UiValue("checkbox", bool(value), {
+            "label": label,
+            "events": _bindEvents(change=onChange),
+        })
 
     def dropdown(
         self,
@@ -301,16 +296,14 @@ def dropdown(
         value: object | None = None,
         label: str = "",
         onChange: Callable[..., Any] | None = None,
-    ) -> dict[str, Any]:
+    ) -> UiValue:
         normalizedOptions = [str(option) for option in options]
         selected = str(value) if value is not None else (normalizedOptions[0] if normalizedOptions else "")
-        return _uiDescriptor(
-            "dropdown",
-            value=selected,
-            label=label,
-            options=normalizedOptions,
-            events=_bindEvents(change=onChange),
-        )
+        return UiValue("dropdown", selected, {
+            "label": label,
+            "options": normalizedOptions,
+            "events": _bindEvents(change=onChange),
+        })
 
     def button(
         self,
@@ -439,6 +432,8 @@ def isDescriptorPayload(value: object) -> bool:
 def toDescriptor(value: object) -> object:
     if value is None:
         return {"type": "plain", "content": ""}
+    if isinstance(value, UiValue):
+        return _sanitizeValue(value.codaroDescriptor())
     if isDescriptorPayload(value):
         return _sanitizeValue(value)
     if isinstance(value, str):
@@ -487,6 +482,8 @@ def _uiDescriptor(component: str, **props: object) -> dict[str, Any]:
 
 
 def _sanitizeValue(value: object) -> Any:
+    if isinstance(value, UiValue):
+        return _sanitizeValue(value.codaroDescriptor())
     if isDescriptorPayload(value):
         payload = value if isinstance(value, dict) else {}
         return {key: _sanitizeValue(item) for key, item in payload.items()}

src/codaro/runtime/localWorker.py

@@ -26,6 +26,7 @@
 from ..document.analysis import analyzeCode
 from ..errorGuard import safeRepr
 from ..outputDescriptor import isDescriptorPayload
+from ..uiValue import beginBlock, resetStore
 
 
 def runLocalWorker(
@@ -119,6 +120,7 @@ def emitEvent(eventType: str, payload: Any = None) -> None:
             if action == "reset":
                 registry.clear()
                 cellDefinitions.clear()
+                resetStore()
                 executionCount = 0
                 _workerSend(connection, _buildStateResponse(registry, cellDefinitions, executionCount))
                 continue
@@ -181,6 +183,10 @@ def _executeCommand(
 
     emitEvent("started", {"status": "running"})
 
+    # 위젯 위치 카운터 리셋 + 현재 blockId 설정 — 이 블록에서 만드는 ui.* 위젯이
+    # {blockId}#{index} 안정 id를 받아 값이 셀 재실행에도 영속한다.
+    beginBlock(blockId)
+
     beforeVariables = _mapVariablesByName(_collectVariables(registry))
     stdoutBuf = _StreamingTextBuffer("stdout", emitEvent)
     stderrBuf = _StreamingTextBuffer("stderr", emitEvent)
@@ -521,6 +527,10 @@ def _normalizeResult(value: object) -> tuple[str, object]:
     if dataframePayload is not None:
         return "dataframe", dataframePayload
 
+    uiValuePayload = _serializeUiValue(value)
+    if uiValuePayload is not None:
+        return "layout", uiValuePayload
+
     descriptorPayload = _serializeDescriptor(value)
     if descriptorPayload is not None:
         return "layout", descriptorPayload
@@ -619,13 +629,32 @@ def _serializeDataFrame(value: object) -> dict[str, object] | None:
     return None
 
 
+def _serializeUiValue(value: object) -> dict[str, object] | None:
+    """UiValue(리액티브 위젯 값 객체)를 descriptor로 직렬화한다(없으면 None).
+
+    객체의 `codaroDescriptor()`가 기존 ui descriptor 형태({type:ui, component, value, elementId})를
+    내고, 그걸 표준 descriptor 직렬화에 태워 프론트 렌더를 불변으로 유지한다.
+    """
+    builder = getattr(value, "codaroDescriptor", None)
+    if not callable(builder):
+        return None
+    descriptor = builder()
+    if not isDescriptorPayload(descriptor):
+        return None
+    return _sanitizeDescriptor(descriptor)
+
+
 def _serializeDescriptor(value: object) -> dict[str, object] | None:
     if not isDescriptorPayload(value):
         return None
     return _sanitizeDescriptor(value)
 
 
 def _sanitizeDescriptor(value: object) -> object:
+    # layout(hstack/tabs/...) 안에 중첩된 UiValue(위젯 값 객체)를 descriptor로 변환.
+    builder = getattr(value, "codaroDescriptor", None)
+    if callable(builder):
+        return _sanitizeDescriptor(builder())
     if isinstance(value, dict):
         return {str(key): _sanitizeDescriptor(item) for key, item in value.items()}
     if isinstance(value, list):

src/codaro/uiValue.py

@@ -0,0 +1,81 @@
+"""리액티브 위젯 값 객체 + per-worker 값 store.
+
+위젯을 변수에 담으면(`slider = ui.slider(0, 100)`) 그 변수를 쓰는 셀이 자동 재실행되는
+marimo식 값-바인딩의 백엔드. `analyzeCode`가 `slider.value`를 `slider` use로 보므로 리액티브
+그래프가 위젯→소비자 의존을 이미 포착한다 — 여기서 빠진 *값 객체*와 *값 영속*만 채운다.
+
+값은 `elementId`(위치 기반 안정 id `{blockId}#{index}`)로 store에 영속하고 셀 재실행에도 유지된다.
+store/카운터는 워커 프로세스의 모듈 전역에 살아 per-session 격리된다(워커가 세션마다 1개).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# 워커 프로세스 전역 — 세션(=워커) 단위 격리.
+_store: dict[str, Any] = {}
+_currentBlockId: str = ""
+_counter: int = 0
+
+
+def beginBlock(blockId: str | None) -> None:
+    """블록 실행 시작 — 현재 blockId 설정 + 위젯 위치 카운터 리셋."""
+    global _currentBlockId, _counter
+    _currentBlockId = blockId or ""
+    _counter = 0
+
+
+def nextElementId() -> str:
+    """현재 블록 내에서 위젯 생성 순서대로 안정 id를 발급한다."""
+    global _counter
+    elementId = f"{_currentBlockId}#{_counter}"
+    _counter += 1
+    return elementId
+
+
+def storedValue(elementId: str, default: Any) -> Any:
+    return _store.get(elementId, default)
+
+
+def setStoredValue(elementId: str, value: Any) -> None:
+    _store[elementId] = value
+
+
+def resetStore() -> None:
+    """세션 reset 시 호출 — 값 store와 카운터를 비운다."""
+    global _currentBlockId, _counter
+    _store.clear()
+    _currentBlockId = ""
+    _counter = 0
+
+
+class UiValue:
+    """변수에 담겨 리액티브 의존을 형성하는 위젯 값 객체. `.value`는 store에서 live로 읽는다.
+
+    셀 출력으로 렌더될 때는 `codaroDescriptor()`(기존 `_uiDescriptor` 형태 + elementId)로
+    직렬화된다 — 프론트 위젯 렌더는 불변, elementId만 추가로 실어 값-변경 경로를 연다.
+    """
+
+    def __init__(self, kind: str, defaultValue: Any, meta: dict[str, Any] | None = None) -> None:
+        self.kind = kind
+        self.elementId = nextElementId()
+        self._default = defaultValue
+        self.meta = dict(meta or {})
+        if self.elementId not in _store:
+            _store[self.elementId] = defaultValue
+
+    @property
+    def value(self) -> Any:
+        return _store.get(self.elementId, self._default)
+
+    def codaroDescriptor(self) -> dict[str, Any]:
+        descriptor: dict[str, Any] = {
+            "type": "ui",
+            "component": self.kind,
+            "value": self.value,
+            "elementId": self.elementId,
+        }
+        descriptor.update(self.meta)
+        return descriptor
+
+    def __repr__(self) -> str:
+        return f"UiValue({self.kind}={self.value!r})"

tests/testUiValueBinding.py

@@ -0,0 +1,83 @@
+"""리액티브 위젯 값 객체(UiValue) + 위치 기반 id + 값 영속 + 세션 렌더 테스트."""
+from __future__ import annotations
+
+import asyncio
+
+from codaro.kernel.session import KernelSession
+from codaro.uiValue import (
+    UiValue,
+    beginBlock,
+    resetStore,
+    setStoredValue,
+)
+
+
+def _run(coro):
+    return asyncio.new_event_loop().run_until_complete(coro)
+
+
+def testPositionalElementId() -> None:
+    resetStore()
+    beginBlock("b1")
+    a = UiValue("slider", 5)
+    b = UiValue("slider", 7)
+    assert a.elementId == "b1#0"
+    assert b.elementId == "b1#1"
+
+
+def testValueReadsStoredDefault() -> None:
+    resetStore()
+    beginBlock("b1")
+    slider = UiValue("slider", 5)
+    assert slider.value == 5
+
+
+def testSetStoredValueUpdatesValue() -> None:
+    resetStore()
+    beginBlock("b1")
+    slider = UiValue("slider", 5)
+    setStoredValue(slider.elementId, 42)
+    assert slider.value == 42
+
+
+def testValuePersistsAcrossRerun() -> None:
+    # 위젯 셀 재실행 시 같은 위치 id → 값 유지(기본값으로 리셋 안 됨).
+    resetStore()
+    beginBlock("b1")
+    first = UiValue("slider", 5)
+    setStoredValue(first.elementId, 42)
+
+    beginBlock("b1")  # 재실행
+    second = UiValue("slider", 5)
+    assert second.elementId == "b1#0"
+    assert second.value == 42
+
+
+def testCodaroDescriptorShape() -> None:
+    resetStore()
+    beginBlock("b1")
+    slider = UiValue("slider", 0, {"label": "x", "min": 0, "max": 100, "step": 1, "events": {}})
+    descriptor = slider.codaroDescriptor()
+    assert descriptor["type"] == "ui"
+    assert descriptor["component"] == "slider"
+    assert descriptor["elementId"] == "b1#0"
+    assert descriptor["value"] == 0
+    assert descriptor["min"] == 0 and descriptor["max"] == 100
+
+
+def testSessionSliderRendersAndValueReadable() -> None:
+    session = KernelSession()
+    result = _run(session.execute(
+        "from codaro.outputDescriptor import ui\nslider = ui.slider(0, 100)\nslider",
+        blockId="b1",
+    ))
+    assert result.status == "done"
+    # 위젯이 ui descriptor로 렌더되고 elementId를 싣는다.
+    assert isinstance(result.data, dict)
+    assert result.data.get("component") == "slider"
+    assert result.data.get("elementId") == "b1#0"
+
+    # 다운스트림 셀에서 slider.value를 읽으면 기본값(0).
+    consumer = _run(session.execute("print(slider.value)", blockId="b2"))
+    assert "0" in consumer.stdout
+    session.dispose()

tests/testWidgetBridge.py

@@ -31,7 +31,8 @@ def testButtonRegistersClickCallback() -> None:
 def testCheckboxChangeCallbackReceivesPayload() -> None:
     setUp()
     received: list[object] = []
-    descriptor = ui.checkbox(False, label="동의", onChange=lambda value: received.append(value))
+    # 값 위젯은 이제 UiValue 객체 — 렌더 형태는 codaroDescriptor()로 본다.
+    descriptor = ui.checkbox(False, label="동의", onChange=lambda value: received.append(value)).codaroDescriptor()
 
     callbackId = descriptor["events"]["change"]
     invokeCallback(callbackId, True)
@@ -43,7 +44,7 @@ def testCheckboxChangeCallbackReceivesPayload() -> None:
 def testSliderEventsBindWithMinMaxStep() -> None:
     setUp()
     received: list[float] = []
-    descriptor = ui.slider(0, 200, value=10, step=5, onChange=lambda value: received.append(float(value)))
+    descriptor = ui.slider(0, 200, value=10, step=5, onChange=lambda value: received.append(float(value))).codaroDescriptor()
 
     assert descriptor["component"] == "slider"
     assert descriptor["min"] == 0
@@ -56,7 +57,7 @@ def testSliderEventsBindWithMinMaxStep() -> None:
 def testDropdownDefaultSelectsFirstOption() -> None:
     setUp()
     received: list[str] = []
-    descriptor = ui.dropdown(["red", "green", "blue"], onChange=lambda value: received.append(value))
+    descriptor = ui.dropdown(["red", "green", "blue"], onChange=lambda value: received.append(value)).codaroDescriptor()
 
     assert descriptor["value"] == "red"
     assert descriptor["options"] == ["red", "green", "blue"]