feat: Initial attempt at wrapping Runtime in a worker within shell.

Author: jsantell

packages/charm/src/ops/charm-controller.ts

@@ -23,6 +23,7 @@ import {
 interface CharmCellIo {
   get(path?: CellPath): unknown;
   set(value: unknown, path?: CellPath): Promise<void>;
+  getCell(): Cell<unknown>;
 }
 
 type CharmPropIoType = "result" | "input";
@@ -40,6 +41,10 @@ class CharmPropIo implements CharmCellIo {
     return resolveCellPath(targetCell, path ?? []);
   }
 
+  getCell(): Cell<unknown> {
+    return this.#getTargetCell();
+  }
+
   async set(value: unknown, path?: CellPath) {
     const manager = this.#cc.manager();
 

packages/cli/lib/charm-render.ts

@@ -1,5 +1,6 @@
 import { render, vdomSchema, VNode } from "@commontools/html";
-import { Cell, UI } from "@commontools/runner";
+import { UI } from "@commontools/runner";
+import { type RemoteCell } from "@commontools/runner/worker";
 import { loadManager } from "./charm.ts";
 import { CharmsController } from "@commontools/charm/ops";
 import type { CharmConfig } from "./charm.ts";
@@ -53,7 +54,11 @@ export async function renderCharm(
   if (options.watch) {
     // 4a. Reactive rendering - pass the Cell directly
     const uiCell = cell.key(UI);
-    const cancel = render(container, uiCell as Cell<VNode>, renderOptions); // FIXME: types
+    const cancel = render(
+      container,
+      uiCell as unknown as RemoteCell<VNode>,
+      renderOptions,
+    ); // FIXME: types
 
     // 5a. Set up monitoring for changes
     let updateCount = 0;

packages/html/deno.jsonc

@@ -7,7 +7,8 @@
     ".": "./src/index.ts",
     "./utils": "./src/utils.ts",
     "./jsx-runtime": "./src/jsx-runtime.ts",
-    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts"
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts",
+    "./mock-doc": "./src/mock-doc.ts"
   },
   "imports": {
     "htmlparser2": "npm:htmlparser2",

packages/html/src/mock-doc.ts

@@ -80,6 +80,11 @@ export class MockDoc {
           return DomUtils.removeElement(this as any);
         },
       },
+      replaceWith: {
+        value(newNode: any) {
+          return DomUtils.replaceElement(this as any, newNode);
+        },
+      },
       innerHTML: {
         get() {
           return domserializer.render((this as any).children);

packages/html/src/render.ts

@@ -1,14 +1,13 @@
 import { isObject, isRecord } from "@commontools/utils/types";
 import {
   type Cancel,
-  type Cell,
   convertCellsToLinks,
   effect,
-  isCell,
   type JSONSchema,
   UI,
   useCancelGroup,
 } from "@commontools/runner";
+import { isRemoteCell, type RemoteCell } from "@commontools/runner/worker";
 import { isVNode, type Props, type RenderNode, type VNode } from "./jsx.ts";
 import * as logger from "./logger.ts";
 
@@ -22,7 +21,7 @@ export interface RenderOptions {
   setProp?: SetPropHandler;
   document?: Document;
   /** The root cell for auto-wrapping with ct-cell-context on [UI] traversal */
-  rootCell?: Cell;
+  rootCell?: RemoteCell<VNode>;
 }
 
 export const vdomSchema: JSONSchema = {
@@ -60,25 +59,32 @@ export const vdomSchema: JSONSchema = {
  */
 export const render = (
   parent: HTMLElement,
-  view: VNode | Cell<VNode>,
+  view: VNode | RemoteCell<VNode>,
   options: RenderOptions = {},
 ): Cancel => {
-  // Initialize visited set with the original cell for cycle detection
-  const visited = new Set<object>();
-  let rootCell: Cell | undefined;
-
-  if (isCell(view)) {
-    visited.add(view);
-    rootCell = view; // Capture the original cell for ct-cell-context wrapping
-    view = view.asSchema(vdomSchema);
+  let rootCell: RemoteCell<VNode> | undefined;
+
+  if (isRemoteCell(view)) {
+    rootCell = view as RemoteCell<VNode>; // Capture the original cell for ct-cell-context wrapping
+    // Don't apply vdomSchema to RemoteCell - it causes the worker to return
+    // cell references (SigilLinks) instead of actual values, which creates
+    // infinite chains of RemoteCells that need resolution.
   }
 
   // Pass rootCell through options if we have one
   const optionsWithCell = rootCell ? { ...options, rootCell } : options;
 
   return effect(
-    view,
-    (view: VNode) => renderImpl(parent, view, optionsWithCell, visited),
+    view as VNode,
+    (view: VNode) => {
+      // Create a fresh visited set for each render pass.
+      // This prevents false cycle detection when re-rendering with updated values.
+      const visited = new Set<object>();
+      if (rootCell) {
+        visited.add(rootCell);
+      }
+      return renderImpl(parent, view, optionsWithCell, visited);
+    },
   );
 };
 
@@ -131,7 +137,7 @@ const createCyclePlaceholder = (document: Document): HTMLSpanElement => {
 /** Check if a cell has been visited, using .equals() for cell comparison */
 const hasVisitedCell = (
   visited: Set<object>,
-  cell: Cell<unknown>,
+  cell: { equals(other: unknown): boolean },
 ): boolean => {
   for (const item of visited) {
     if (cell.equals(item)) {
@@ -207,7 +213,7 @@ const renderNode = (
   if (cellForContext && element) {
     const wrapper = document.createElement(
       "ct-cell-context",
-    ) as HTMLElement & { cell?: Cell };
+    ) as HTMLElement & { cell?: RemoteCell<VNode> };
     wrapper.cell = cellForContext;
     wrapper.appendChild(element);
     return [wrapper, cancel];
@@ -216,6 +222,35 @@ const renderNode = (
   return [element, cancel];
 };
 
+/**
+ * Recursively resolve RemoteCells to get actual values.
+ * This is needed when rendering with RuntimeWorker, where cell values
+ * may contain SigilLinks that get rehydrated to RemoteCells.
+ */
+const resolveRemoteCells = async (val: unknown): Promise<unknown> => {
+  if (isRemoteCell(val)) {
+    const cell = val as RemoteCell<unknown>;
+    await cell.sync();
+    const resolved = cell.get();
+    return resolveRemoteCells(resolved);
+  }
+  if (Array.isArray(val)) {
+    return Promise.all(val.map((item) => resolveRemoteCells(item)));
+  }
+  return val;
+};
+
+/**
+ * Check if a value contains RemoteCells that need resolution.
+ */
+const needsRemoteCellResolution = (val: unknown): boolean => {
+  if (isRemoteCell(val)) return true;
+  if (Array.isArray(val)) {
+    return val.some((item) => needsRemoteCellResolution(item));
+  }
+  return false;
+};
+
 const bindChildren = (
   element: HTMLElement,
   children: RenderNode,
@@ -235,25 +270,50 @@ const bindChildren = (
     const document = options.document ?? globalThis.document;
 
     // Check for cell cycle before setting up effect (using .equals() for comparison)
-    if (isCell(child) && hasVisitedCell(visited, child)) {
+    if (
+      isRenderableCell(child) &&
+      hasVisitedCell(visited, child as unknown as RemoteCell<unknown>)
+    ) {
       logger.warn("render", "Cycle detected in cell graph", child);
       return { node: createCyclePlaceholder(document), cancel: () => {} };
     }
 
     // Track if this child is a cell for the visited set
-    const childIsCell = isCell(child);
+    const childIsCell = isRenderableCell(child);
 
     let currentNode: ChildNode | null = null;
+
     const cancel = effect(child, (childValue) => {
+      // If the value contains RemoteCells (from worker rehydration), resolve them first
+      if (needsRemoteCellResolution(childValue)) {
+        resolveRemoteCells(childValue).then((value) => {
+          // If resolved to an array, render first item (shouldn't happen for single child)
+          if (Array.isArray(value)) {
+            if (value.length > 0) {
+              renderValue(value[0] as RenderNode);
+            }
+          } else {
+            renderValue(value as RenderNode);
+          }
+        }).catch((e) => {
+          logger.warn("render", "Failed to resolve RemoteCell", e);
+        });
+        // Render empty placeholder while waiting for resolution
+        return renderValue(undefined as unknown as RenderNode);
+      }
+      return renderValue(childValue as RenderNode);
+    });
+
+    function renderValue(value: RenderNode): Cancel | undefined {
       let newRendered: { node: ChildNode; cancel: Cancel };
-      if (isVNode(childValue)) {
+      if (isVNode(value)) {
         // Create visited set for this child's subtree (cloned to avoid sibling interference)
         const childVisited = new Set(visited);
         if (childIsCell) {
           childVisited.add(child);
         }
         const [childElement, childCancel] = renderNode(
-          childValue,
+          value,
           options,
           childVisited,
         );
@@ -262,17 +322,25 @@ const bindChildren = (
           cancel: childCancel ?? (() => {}),
         };
       } else {
+        let textValue: string | number | boolean = value as
+          | string
+          | number
+          | boolean;
         if (
-          childValue === null || childValue === undefined ||
-          childValue === false
+          textValue === null || textValue === undefined ||
+          textValue === false
         ) {
-          childValue = "";
-        } else if (typeof childValue === "object") {
-          console.warn("unexpected object when value was expected", childValue);
-          childValue = JSON.stringify(childValue);
+          textValue = "";
+        } else if (typeof textValue === "object") {
+          logger.warn(
+            "render",
+            "unexpected object when value was expected",
+            textValue,
+          );
+          textValue = JSON.stringify(textValue);
         }
         newRendered = {
-          node: document.createTextNode(childValue.toString()),
+          node: document.createTextNode(textValue.toString()),
           cancel: () => {},
         };
       }
@@ -289,7 +357,7 @@ const bindChildren = (
 
       currentNode = newRendered.node;
       return newRendered.cancel;
-    });
+    }
 
     return { node: currentNode!, cancel };
   };
@@ -340,10 +408,10 @@ const bindChildren = (
     for (let i = 0; i < newKeyOrder.length; i++) {
       const key = newKeyOrder[i];
       const desiredNode = newMapping.get(key)!.node;
-      // If there's no node at this position, or it’s different, insert desiredNode there.
+      // If there's no node at this position, or it's different, insert desiredNode there.
       if (domNodes[i] !== desiredNode) {
         // Using domNodes[i] (which may be undefined) is equivalent to appending
-        // if there’s no node at that index.
+        // if there's no node at that index.
         element.insertBefore(desiredNode, domNodes[i] ?? null);
       }
     }
@@ -356,7 +424,25 @@ const bindChildren = (
   // Set up a reactive effect so that changes to the children array are diffed and applied.
   const cancelArrayEffect = effect(
     children,
-    (childrenVal) => updateChildren(childrenVal),
+    (childrenVal) => {
+      // If the value contains RemoteCells (from worker rehydration), resolve them first
+      if (needsRemoteCellResolution(childrenVal)) {
+        resolveRemoteCells(childrenVal).then((resolved) => {
+          updateChildren(
+            resolved as RenderNode | RenderNode[] | undefined | null,
+          );
+        }).catch((e) => {
+          logger.warn("render", "Failed to resolve RemoteCell children", e);
+        });
+        // Render empty while waiting for resolution
+        updateChildren(undefined);
+        return undefined;
+      }
+      updateChildren(
+        childrenVal as RenderNode | RenderNode[] | undefined | null,
+      );
+      return undefined;
+    },
   );
 
   // Return a cancel function that tears down the effect and cleans up any rendered nodes.
@@ -377,7 +463,7 @@ const bindProps = (
   const setProperty = options.setProp ?? setProp;
   const [cancel, addCancel] = useCancelGroup();
   for (const [propKey, propValue] of Object.entries(props)) {
-    if (isCell(propValue)) {
+    if (isRenderableCell(propValue)) {
       // If prop is an event, we need to add an event listener
       if (isEventProp(propKey)) {
         const key = cleanEventProp(propKey);
@@ -538,10 +624,10 @@ const sanitizeScripts = (node: VNode): VNode | null => {
   if (node.name === "script") {
     return null;
   }
-  if (!isCell(node.props) && !isObject(node.props)) {
+  if (!isRenderableCell(node.props) && !isObject(node.props)) {
     node = { ...node, props: {} };
   }
-  if (!isCell(node.children) && !Array.isArray(node.children)) {
+  if (!isRenderableCell(node.children) && !Array.isArray(node.children)) {
     node = { ...node, children: [] };
   }
 
@@ -654,3 +740,12 @@ function isSelectElement(value: unknown): value is HTMLSelectElement {
     typeof value.tagName === "string" &&
     value.tagName.toUpperCase() === "SELECT");
 }
+
+type RenderableCell = {
+  send(value: unknown): void;
+};
+function isRenderableCell(value: unknown): value is RenderableCell {
+  // Check for any object with a send() method (Cell, RemoteCell, or Stream)
+  return !!value && typeof value === "object" && "send" in value &&
+    typeof (value as RenderableCell).send === "function";
+}

packages/html/test/html-recipes.test.ts

@@ -7,6 +7,7 @@ import {
   type IExtendedStorageTransaction,
   Runtime,
 } from "@commontools/runner";
+import { type RemoteCell } from "@commontools/runner/worker";
 import { StorageManager } from "@commontools/runner/storage/cache.deno";
 import * as assert from "./assert.ts";
 import { Identity } from "@commontools/identity";
@@ -167,7 +168,7 @@ describe("recipes with HTML", () => {
 
     const root = document.getElementById("root")!;
     const cell = result.key(UI);
-    render(root, cell, renderOptions);
+    render(root, cell as unknown as RemoteCell<VNode>, renderOptions);
     assert.equal(root.innerHTML, "<div><div>test</div></div>");
   });
 
@@ -277,7 +278,11 @@ describe("recipes with HTML", () => {
     await runtime.idle();
 
     const root = document.getElementById("root")!;
-    render(root, cell1.key("ui"), renderOptions);
+    render(
+      root,
+      cell1.key("ui") as unknown as RemoteCell<VNode>,
+      renderOptions,
+    );
 
     // Should detect the cycle and render placeholder, not infinite loop
     // MockDoc doesn't properly reflect textContent/title in innerHTML,