fix(engine): drop never-gated hidden array items instead of null holes (#1217)

* fix(engine): drop never-gated hidden array items instead of null holes

Hiding an array item wraps it in a multivariate flag gated by a `never`
matcher; flag.ts returns `undefined` when no variant matched. The engine
left that `undefined` as a hole in the resolved array, which serializes
to `null` in JSON and renders as an empty card (blank benefit rows,
etc.).

Compact `undefined` out of resolved arrays in resolvePropsWithHints. A
resolver returning `null` is a legitimate value and is kept — only the
`undefined` "not present" sentinel is filtered.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(engine): gate array compaction on includes + broaden tests

Address review feedback:
- Only reallocate when the array actually contains `undefined` (scan with
  `includes` first) so the common zero-undefined case skips the extra
  allocation on the hot resolve path.
- Reframe the comment around the generic invariant (object props already
  drop `undefined` under JSON.stringify; array `undefined` serializes to a
  `null` hole — compaction makes arrays consistent), citing the never-gated
  flag as the motivating case rather than the definition.
- Add tests: all-items-hidden -> [], and nested-array multi-depth (with a
  first-element drop to pin ordering).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: guitavano

engine/core/mod.test.ts

@@ -153,6 +153,87 @@ Deno.test("resolve", async (t) => {
     });
   });
 
+  await t.step(
+    "drops hidden array items (resolver -> undefined) but keeps null",
+    async () => {
+      // A hidden array item is a multivariate flag gated by a `never` matcher;
+      // flag.ts returns `undefined` when no variant matched. Such items must be
+      // dropped from the array, not left as holes (which serialize to `null`
+      // and render as empty cards). A resolver returning `null` is a legitimate
+      // value and is kept.
+      const resolverMap = {
+        resolve: (data: unknown) => context.resolve(data),
+        hiddenFlag: (): unknown => undefined,
+        nullFlag: (): unknown => null,
+        keep: (p: { label: string }) => p,
+      };
+      const result = await resolve<{ items: unknown[] }>(
+        {
+          items: [
+            { label: "A", __resolveType: "keep" },
+            { __resolveType: "hiddenFlag" },
+            { label: "B", __resolveType: "keep" },
+            { __resolveType: "nullFlag" },
+            { __resolveType: "hiddenFlag" },
+          ],
+          __resolveType: "resolve",
+        },
+        { ...context, resolvers: resolverMap as unknown as ResolverMap },
+      );
+      assertEquals(result, {
+        items: [{ label: "A" }, { label: "B" }, null],
+      });
+    },
+  );
+
+  await t.step(
+    "an array where every item is hidden becomes empty (not a hole array)",
+    async () => {
+      const resolverMap = {
+        resolve: (data: unknown) => context.resolve(data),
+        hiddenFlag: (): unknown => undefined,
+      };
+      const result = await resolve<{ items: unknown[] }>(
+        {
+          items: [
+            { __resolveType: "hiddenFlag" },
+            { __resolveType: "hiddenFlag" },
+          ],
+          __resolveType: "resolve",
+        },
+        { ...context, resolvers: resolverMap as unknown as ResolverMap },
+      );
+      assertEquals(result, { items: [] });
+    },
+  );
+
+  await t.step(
+    "hidden items are dropped at every array depth (nested arrays)",
+    async () => {
+      // The fix relies on the filter firing at each array level via recursion,
+      // and on ordering being preserved when the first element is dropped.
+      const resolverMap = {
+        resolve: (data: unknown) => context.resolve(data),
+        hiddenFlag: (): unknown => undefined,
+        keep: (p: { label: string }) => p,
+      };
+      const result = await resolve<{ groups: unknown[][] }>(
+        {
+          groups: [
+            [
+              { __resolveType: "hiddenFlag" },
+              { label: "A", __resolveType: "keep" },
+            ],
+            [{ __resolveType: "hiddenFlag" }],
+          ],
+          __resolveType: "resolve",
+        },
+        { ...context, resolvers: resolverMap as unknown as ResolverMap },
+      );
+      assertEquals(result, { groups: [[{ label: "A" }], []] });
+    },
+  );
+
   await t.step("resolves object with no resolvable fields", async () => {
     type TestType = {
       foo: string;

engine/core/resolver.ts

@@ -424,6 +424,19 @@ const resolvePropsWithHints = async <
   }
 
   if (!type) {
+    // Compact `undefined` out of resolved arrays. An array element that resolved
+    // to `undefined` is a "not present" value (the motivating case: a hidden
+    // item — a multivariate flag gated by a `never` matcher, which flag.ts
+    // resolves to `undefined` when no variant matched). Object properties that
+    // resolve to `undefined` already vanish under `JSON.stringify`, but an
+    // `undefined` array element serializes to a `null` hole that the consuming
+    // section renders as an empty card — so filter it, making arrays consistent
+    // with object props. A resolver returning `null` is a legitimate value and
+    // is kept. `includes` first so the common (nothing-to-drop) case skips the
+    // reallocation the surrounding hot path deliberately avoids.
+    if (Array.isArray(mutableProps) && mutableProps.includes(undefined)) {
+      return mutableProps.filter((item) => item !== undefined) as T;
+    }
     return mutableProps;
   }