feat(transform): rewrite .map function closures to pass in any closed over cells

[seefeldb]

Resubmitting #1864 by @mathpirate , after applying a fix to support foo[bar] inside map function where both are cells.

---

Summary by cubic

Transforms reactive array .map callbacks to pass closed-over cells as explicit params, ensuring correct reactivity and schema generation. Adds mapWithPattern and unifies the map builtin; fixes element access cases like foo[bar] where both sides are cells.

• New Features

  • ClosureTransformer rewrites OpaqueRef/Cell .map(...) to mapWithPattern(recipe, params); runs first in the pipeline and handles nested/typed/destructured params.
  • API/Runner: adds OpaqueRefMethods.mapWithPattern; map builtin now supports both legacy and closure modes based on params.
  • Schema: supports Opaque unions (T | OpaqueRef), synthetic TypeNode schema generation, and exposes a transformer object with generateSchema and generateSchemaFromSyntheticTypeNode.
  • Tests/Docs: extensive closure fixtures; design and roadmap docs added.

• Bug Fixes

  • Correctly wraps element access like tagCounts[element] in derive when both sides are OpaqueRefs, including inside transformed map callbacks.
  • Improved handling of synthetic nodes and JSX traversal in dataflow and emitters; map chains (e.g., filter().map()) rewrite reliably.

[cubic-dev-ai]

9 issues found across 97 files

Prompt for AI agents (all 9 issues)

Understand the root cause of the following 9 issues and fix them.


<file name="packages/ts-transformers/src/ast/utils.ts">

<violation number="1" location="packages/ts-transformers/src/ast/utils.ts:205">
`visitEachChildWithJsx` is invoked with `undefined`, so this call into `ts.visitEachChild` will throw when `context` is missing. Default the context (e.g. `context ?? ts.nullTransformationContext`) before calling.</violation>
</file>

<file name="packages/ts-transformers/test/fixtures/closures/map-conditional-expression.expected.tsx">

<violation number="1" location="packages/ts-transformers/test/fixtures/closures/map-conditional-expression.expected.tsx:86">
Wrap the computed price in JSX braces instead of a template literal so the value renders correctly.</violation>
</file>

<file name="packages/ts-transformers/test/fixtures/closures/map-element-access-opaque.input.tsx">

<violation number="1" location="packages/ts-transformers/test/fixtures/closures/map-element-access-opaque.input.tsx:14">
Add a stable key to each &lt;span&gt; returned from sortedTags.map so React can reconcile the list correctly.</violation>
</file>

<file name="packages/ts-transformers/src/closures/transformer.ts">

<violation number="1" location="packages/ts-transformers/src/closures/transformer.ts:1006">
The rewritten map callback drops the original third parameter (the source array). If a callback uses that argument, the transformed version has no binding for it, so references like `array.some(...)` crash at runtime. Please preserve the third parameter when rebuilding the destructured signature.</violation>
</file>

<file name="packages/ts-transformers/test/fixtures/closures/map-import-reference.input.tsx">

<violation number="1" location="packages/ts-transformers/test/fixtures/closures/map-import-reference.input.tsx:24">
Add a stable key to each element returned from state.items.map so React can reconcile the list correctly.</violation>
</file>

<file name="packages/ts-transformers/test/fixtures/jsx-expressions/opaque-ref-cell-map.expected.tsx">

<violation number="1" location="packages/ts-transformers/test/fixtures/jsx-expressions/opaque-ref-cell-map.expected.tsx:119">
The goToCharm handler expects a `charm` property, but the new callback now calls it with `{ element }`, so the handler receives `undefined` and navigation will fail. Use the correct property name.</violation>
</file>

<file name="packages/ts-transformers/test/fixtures/closures/map-multiple-captures.input.tsx">

<violation number="1" location="packages/ts-transformers/test/fixtures/closures/map-multiple-captures.input.tsx:24">
Elements produced from state.items.map need a stable key to avoid React reconciliation issues; please add a key to the &lt;span&gt;.</violation>
</file>

<file name="packages/schema-generator/test/fixtures/schema/wrapper-aliases.input.ts">

<violation number="1" location="packages/schema-generator/test/fixtures/schema/wrapper-aliases.input.ts:3">
Dropping the `extends T` constraint makes this test fixture diverge from the actual Default wrapper and lets defaults that aren’t assignable to T slip through; please keep the constraint so the schema test stays faithful to production types.</violation>
</file>

<file name="packages/ts-transformers/src/ast/dataflow.ts">

<violation number="1" location="packages/ts-transformers/src/ast/dataflow.ts:995">
JSX attribute expressions are no longer analyzed because JsxAttribute/JsxSpreadAttribute are not Expressions, so the guard always fails; their initializers should be inspected instead.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

visitEachChildWithJsx is invoked with undefined, so this call into ts.visitEachChild will throw when context is missing. Default the context (e.g. context ?? ts.nullTransformationContext) before calling.

Prompt for AI agents

Address the following comment on packages/ts-transformers/src/ast/utils.ts at line 205:

<comment>`visitEachChildWithJsx` is invoked with `undefined`, so this call into `ts.visitEachChild` will throw when `context` is missing. Default the context (e.g. `context ?? ts.nullTransformationContext`) before calling.</comment>

<file context>
@@ -135,3 +165,66 @@ export function isFunctionParameter(
+
+  // Handle JSX self-closing elements
+  if (ts.isJsxSelfClosingElement(node)) {
+    return ts.visitEachChild(node, visitor, context);
+  }
+
</file context>

Suggested change

	return ts.visitEachChild(node, visitor, context);
	return ts.visitEachChild(node, visitor, context ?? ts.nullTransformationContext);

[seefeldb]

@mathpirate there are indeed a lot of places that do call this with undefined, but nullTransformationContext doesn't exist and i can't tell whether we should fix the call sites to pass context along or create one.

[jsantell]

Context can be undefined here

[cubic-dev-ai]

Dropping the extends T constraint makes this test fixture diverge from the actual Default wrapper and lets defaults that aren’t assignable to T slip through; please keep the constraint so the schema test stays faithful to production types.

Prompt for AI agents

Address the following comment on packages/schema-generator/test/fixtures/schema/wrapper-aliases.input.ts at line 3:

<comment>Dropping the `extends T` constraint makes this test fixture diverge from the actual Default wrapper and lets defaults that aren’t assignable to T slip through; please keep the constraint so the schema test stays faithful to production types.</comment>

<file context>
@@ -1,6 +1,6 @@
 // Test wrapper type aliases - both direct and aliased wrapper types
 // Using proper interface definitions that match actual CommonTools wrappers
-type Default&lt;T, V extends T = T&gt; = T;
+type Default&lt;T, V = T&gt; = T;
 interface Cell&lt;T&gt; {
   get(): T;
</file context>

Suggested change

	type Default<T, V = T> = T;
	type Default<T, V extends T = T> = T;

[cubic-dev-ai]

JSX attribute expressions are no longer analyzed because JsxAttribute/JsxSpreadAttribute are not Expressions, so the guard always fails; their initializers should be inspected instead.

Prompt for AI agents

Address the following comment on packages/ts-transformers/src/ast/dataflow.ts at line 995:

<comment>JSX attribute expressions are no longer analyzed because JsxAttribute/JsxSpreadAttribute are not Expressions, so the guard always fails; their initializers should be inspected instead.</comment>

<file context>
@@ -668,6 +987,31 @@ export function createDataFlowAnalyzer(
+      const analyses: InternalAnalysis[] = [];
+      // Analyze opening element attributes
+      if (expression.openingElement.attributes) {
+        expression.openingElement.attributes.properties.forEach((attr) =&gt; {
+          if (ts.isExpression(attr)) {
+            analyses.push(analyzeExpression(attr, scope, context));
</file context>

[seefeldb]

@mathpirate Can you take a look?