ct-cell-context debugging tool (commontoolsinc#2164)

* Implement `ct-cell-context` component and basic debug feature

* Watch cells

* Working-end-to-end

* Format pass

* Wrap interesting use-sites in `ct-cell-context` for testing

* Add `label` to `jsx.d.ts`

* Fix lint

* Auto-insert into ct-render?

* Automatically wrap anything with [UI] in cell-context

* Format pass

* Remove beads files

* Write to `$cell`

* Action cubic review

* Add missing jsx.d.ts definition

Author: bfollington

packages/html/src/jsx.d.ts

@@ -2888,6 +2888,7 @@ interface CTToolbarElement extends CTHTMLElement {}
 interface CTKbdElement extends CTHTMLElement {}
 interface CTKeybindElement extends CTHTMLElement {}
 interface CTRenderElement extends CTHTMLElement {}
+interface CTCellContextElement extends CTHTMLElement {}
 interface CTChatMessageElement extends CTHTMLElement {}
 interface CTMarkdownElement extends CTHTMLElement {}
 interface CTVScrollElement extends CTHTMLElement {}
@@ -3156,6 +3157,12 @@ interface CTRenderAttributes<T> extends CTHTMLAttributes<T> {
   "$cell": CellLike<any>;
 }
 
+interface CTCellContextAttributes<T> extends CTHTMLAttributes<T> {
+  "$cell": CellLike<any>;
+  "label"?: string;
+  "inline"?: boolean;
+}
+
 interface CTListAttributes<T> extends CTHTMLAttributes<T> {
   "$value": CellLike<CtListItem[]>;
   /** setting this allows editing items inline */
@@ -3879,6 +3886,10 @@ declare global {
         CTRenderAttributes<CTRenderElement>,
         CTRenderElement
       >;
+      "ct-cell-context": CTDOM.DetailedHTMLProps<
+        CTCellContextAttributes<CTCellContextElement>,
+        CTCellContextElement
+      >;
       "ct-vscroll": CTDOM.DetailedHTMLProps<
         CTScrollAttributes<CTVScrollElement>,
         CTVScrollElement

packages/html/src/render.ts

@@ -21,6 +21,8 @@ export type SetPropHandler = <T>(
 export interface RenderOptions {
   setProp?: SetPropHandler;
   document?: Document;
+  /** The root cell for auto-wrapping with ct-cell-context on [UI] traversal */
+  rootCell?: Cell;
 }
 
 export const vdomSchema: JSONSchema = {
@@ -63,13 +65,20 @@ export const render = (
 ): 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);
   }
+
+  // Pass rootCell through options if we have one
+  const optionsWithCell = rootCell ? { ...options, rootCell } : options;
+
   return effect(
     view,
-    (view: VNode) => renderImpl(parent, view, options, visited),
+    (view: VNode) => renderImpl(parent, view, optionsWithCell, visited),
   );
 };
 
@@ -141,6 +150,10 @@ const renderNode = (
 
   const document = options.document ?? globalThis.document;
 
+  // Check if we should wrap with ct-cell-context (when traversing [UI] with a rootCell)
+  const shouldWrapWithContext = node[UI] && options.rootCell;
+  const cellForContext = shouldWrapWithContext ? options.rootCell : undefined;
+
   // Follow `[UI]` to actual vdom. Do this before otherwise parsing the vnode,
   // so that if there are both, the `[UI]` annotation takes precedence (avoids
   // accidental collision with the otherwise quite generic property names)
@@ -190,6 +203,16 @@ const renderNode = (
     addCancel(cancelChildren);
   }
 
+  // Wrap with ct-cell-context if we traversed [UI] with a rootCell
+  if (cellForContext && element) {
+    const wrapper = document.createElement(
+      "ct-cell-context",
+    ) as HTMLElement & { cell?: Cell };
+    wrapper.cell = cellForContext;
+    wrapper.appendChild(element);
+    return [wrapper, cancel];
+  }
+
   return [element, cancel];
 };
 

packages/patterns/chatbot.tsx

@@ -241,7 +241,9 @@ export default pattern<ChatInput, ChatOutput>(
 
     const attachmentsAndTools = (
       <ct-hstack align="center" gap="1">
-        <ct-attachments-bar pinnedCells={pinnedCells} />
+        <ct-cell-context $cell={pinnedCells}>
+          <ct-attachments-bar pinnedCells={pinnedCells} />
+        </ct-cell-context>
         <ct-tools-chip tools={flattenedTools} />
         <ct-button
           variant="pill"

packages/patterns/compiler.tsx

@@ -58,21 +58,25 @@ export default recipe<Input>(
       [NAME]: "My First Compiler",
       [UI]: (
         <div>
-          <ct-code-editor
-            value={code}
-            language="text/x.typescript"
-            onChange={updateCode({ code })}
-            //errors={errors}
-          />
-          {ifElse(
-            error,
-            <b>fix the error: {error}</b>,
-            <ct-button
-              onClick={visit({ result })}
-            >
-              Navigate To Charm
-            </ct-button>,
-          )}
+          <ct-cell-context $cell={code} label="Source Code">
+            <ct-code-editor
+              value={code}
+              language="text/x.typescript"
+              onChange={updateCode({ code })}
+              //errors={errors}
+            />
+          </ct-cell-context>
+          <ct-cell-context $cell={result} label="Compile Result">
+            {ifElse(
+              error,
+              <b>fix the error: {error}</b>,
+              <ct-button
+                onClick={visit({ result })}
+              >
+                Navigate To Charm
+              </ct-button>,
+            )}
+          </ct-cell-context>
         </div>
       ),
       code,

packages/patterns/counter.tsx

@@ -20,9 +20,11 @@ export default recipe<RecipeState, RecipeOutput>((state) => {
         <ct-button onClick={decrement(state)}>
           dec to {previous(state.value)}
         </ct-button>
-        <span id="counter-result">
-          Counter is the {nth(state.value)} number
-        </span>
+        <ct-cell-context $cell={state.value} inline>
+          <span id="counter-result">
+            Counter is the {nth(state.value)} number
+          </span>
+        </ct-cell-context>
         <ct-button onClick={increment({ value: state.value })}>
           inc to {(state.value ?? 0) + 1}
         </ct-button>

packages/patterns/default-app.tsx

@@ -33,7 +33,7 @@ interface CharmsListOutput {
   fabUI: unknown;
 }
 
-const visit = handler<
+const _visit = handler<
   Record<string, never>,
   { charm: Cell<MinimalCharm> }
 >((_, state) => {
@@ -177,12 +177,9 @@ export default recipe<CharmsListInput, CharmsListOutput>(
                   {allCharms.map((charm) => (
                     <tr>
                       <td>
-                        <a
-                          className="pattern-link"
-                          onClick={visit({ charm })}
-                        >
-                          {charm?.[NAME] || "Untitled Charm"}
-                        </a>
+                        <ct-cell-context $cell={charm}>
+                          <ct-cell-link $cell={charm} />
+                        </ct-cell-context>
                       </td>
                       <td>
                         <ct-button

packages/patterns/favorites-manager.tsx

@@ -20,18 +20,20 @@ export default pattern<Record<string, never>>((_) => {
     [UI]: (
       <div>
         {wishResult.result.map((item) => (
-          <div>
-            <ct-cell-link $cell={item.cell} />
-            <ct-button
-              onClick={onRemoveFavorite({
-                favorites: wishResult.result,
-                item: item.cell,
-              })}
-            >
-              Remove
-            </ct-button>
-            <pre>{item.description}</pre>
-          </div>
+          <ct-cell-context $cell={item.cell}>
+            <div>
+              <ct-cell-link $cell={item.cell} />
+              <ct-button
+                onClick={onRemoveFavorite({
+                  favorites: wishResult.result,
+                  item: item.cell,
+                })}
+              >
+                Remove
+              </ct-button>
+              <pre>{item.description}</pre>
+            </div>
+          </ct-cell-context>
         ))}
       </div>
     ),

packages/patterns/fetch-data.tsx

@@ -203,37 +203,39 @@ export default recipe<
             />
           </div>
 
-          <div>
-            <h3 id="github-title">
-              {validData.name}
-            </h3>
-            <p>
-              by {validData.owner.login}
-            </p>
-            <p>{validData.description}</p>
+          <ct-cell-context $cell={validData}>
             <div>
+              <h3 id="github-title">
+                {validData.name}
+              </h3>
+              <p>
+                by {validData.owner.login}
+              </p>
+              <p>{validData.description}</p>
               <div>
-                <span>⭐</span>
-                <strong>{validData.stargazers_count}</strong> stars
-              </div>
-              <div>
-                <span>🍴</span>
-                <strong>{validData.forks_count}</strong> forks
-              </div>
-              <div>
-                <span>🔤</span>
-                <strong>{validData.language}</strong>
-              </div>
-              <div>
-                <a
-                  href={validData.html_url}
-                  target="_blank"
-                >
-                  View on GitHub →
-                </a>
+                <div>
+                  <span>⭐</span>
+                  <strong>{validData.stargazers_count}</strong> stars
+                </div>
+                <div>
+                  <span>🍴</span>
+                  <strong>{validData.forks_count}</strong> forks
+                </div>
+                <div>
+                  <span>🔤</span>
+                  <strong>{validData.language}</strong>
+                </div>
+                <div>
+                  <a
+                    href={validData.html_url}
+                    target="_blank"
+                  >
+                    View on GitHub →
+                  </a>
+                </div>
               </div>
             </div>
-          </div>
+          </ct-cell-context>
         </div>
       ),
       repo: validData,