fix(runtime): off-spec display value hides, aligning Ink (drop A21 divergence) (#128)

Ink's applyDisplayStyles hides any present `display` that isn't 'flex'
(DISPLAY_NONE); vue-tui hid only on exact 'none', leaving off-spec values
(reachable via TS-bypass — the prop type is 'flex'|'none') visible. Align: the
yoga display setter now hides any present (non-null) value except 'flex',
matching Ink even for non-string junk (display={5}). The blessed A19 divergence
is preserved — a removed/undefined display (null) still resets to the visible
default (Vue can't distinguish display={undefined} from an omitted prop).

Removes the now-obsolete A21 entry from .agents/docs/ink-divergences.md (the
A19 "removed display resets to visible" entry remains).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/docs/ink-divergences.md

@@ -302,17 +302,6 @@ unsubscribe(){}}`) — a `useAnimation` rendered outside an Ink tree never ticks
   diverge from Ink in the _opposite_ (unrelated-sibling) direction, where Ink drops the cursor.
   Keep the reactivity-tied behavior. Maintainer decision (2026-06-01): KEEP.
 
-### An off-spec `display` value stays visible instead of hiding
-
-- **Ink:** `applyDisplayStyles` sets `DISPLAY_NONE` for **any** present `display` that isn't
-  `'flex'` — so a typo or off-spec value (`display="block"`, `display=""`, reachable via a
-  TS-bypass) **hides** the box.
-- **vue-tui:** `toDisplay` hides only on the exact value `'none'`; every other value (including
-  off-spec) falls back to the visible default `DISPLAY_FLEX`.
-- **Why:** an unknown/typo `display` shouldn't silently delete content — failing visible is the
-  safer default. It's also consistent with the removal-reset above: a withdrawn `display` returns
-  to visible, and so does an unrecognized one. (The only honored hide is the documented `'none'`.)
-
 ### Out-of-type style values are forwarded, not defensively coerced
 
 - **Ink:** several flex/align setters coerce a runtime junk value to a default — `flexShrink`

packages/runtime-tests/integration/layout/display.test.tsx

@@ -80,3 +80,46 @@ test("display none box does not paint its border", async () => {
   );
   expect(lastFrame({ trimLines: true })).toBe("AAAZZ");
 });
+
+// A21: an off-spec PRESENT `display` value (anything that isn't 'flex') must HIDE,
+// matching Ink's applyDisplayStyles (styles.ts): `display === 'flex' ? FLEX : NONE`.
+// The public prop type is 'flex' | 'none', so an off-spec value is only reachable
+// via a TS bypass; it must still align with Ink and hide.
+test("display off-spec present value (block) hides like Ink", async () => {
+  const { lastFrame } = await render(
+    defineComponent(() => () => (
+      <Box flexDirection="column">
+        <Box display={"block" as never}>
+          <Text>Kitty!</Text>
+        </Box>
+        <Text>Doggo</Text>
+      </Box>
+    )),
+    { columns: 100 },
+  );
+  expect(lastFrame({ trimLines: true })).toBe("Doggo");
+});
+
+// A21 (non-string variant): a PRESENT non-string `display` value (e.g. a number,
+// reachable only via a TS bypass — the public prop type is 'flex' | 'none') must
+// HIDE, matching Ink's `display === 'flex' ? FLEX : NONE` where `5 === 'flex'` is
+// false → DISPLAY_NONE. This pins the guard change from `typeof v === "string" && …`
+// to `v != null && v !== "flex"`: under the old typeof guard a number stays VISIBLE
+// (RED), under the current null-check guard it hides like Ink (GREEN). null/undefined
+// (removed) still resets to visible (A19), exercised by prop-reset.test.tsx.
+test("display non-string present value (number) hides like Ink", async () => {
+  const { lastFrame } = await render(
+    defineComponent(() => () => (
+      <Box flexDirection="column">
+        <Box display={5 as never}>
+          <Text>Kitty!</Text>
+        </Box>
+        <Text>Doggo</Text>
+      </Box>
+    )),
+    { columns: 100 },
+  );
+  // Child text must NOT appear: the present number value hides the box.
+  expect(lastFrame({ trimLines: true })).not.toContain("Kitty!");
+  expect(lastFrame({ trimLines: true })).toBe("Doggo");
+});

packages/runtime/src/host/yoga.ts

@@ -308,7 +308,18 @@ const YOGA_PROP_SETTERS: Record<string, (n: YogaNode, v: unknown) => void> = {
   borderLeft: (n, v) => n.setBorder(Yoga.EDGE_LEFT, v ? 1 : 0),
   borderRight: (n, v) => n.setBorder(Yoga.EDGE_RIGHT, v ? 1 : 0),
 
-  display: (n, v) => n.setDisplay(v === "none" ? Yoga.DISPLAY_NONE : Yoga.DISPLAY_FLEX),
+  // Ink styles.ts applyDisplayStyles: `display === 'flex' ? DISPLAY_FLEX : DISPLAY_NONE`,
+  // so ANY present value that isn't 'flex' (incl. off-spec strings reachable via a TS
+  // bypass — the public prop type is 'flex' | 'none') hides (A21). A19 carve-out: a
+  // removed/undefined `display` (value is null/undefined) must reset to the visible
+  // default DISPLAY_FLEX — Vue can't tell `display={undefined}` from an omitted prop, so
+  // it falls under the declarative render = f(current props) reset, NOT Ink's hide-on-
+  // present-undefined. Hence the `v != null` guard: ANY present (non-null) value except
+  // 'flex' hides — matching Ink, which hides non-string present junk too (`display={5}`,
+  // a deep TS-bypass: `5 === 'flex'` is false → DISPLAY_NONE) — while null/undefined
+  // (removed) → DISPLAY_FLEX (A19).
+  display: (n, v) =>
+    n.setDisplay(v != null && v !== "flex" ? Yoga.DISPLAY_NONE : Yoga.DISPLAY_FLEX),
   // Ink does NOT call setOverflow on yoga — it only clips visually in paint.
   // Calling setOverflow(HIDDEN) would prevent nodes from expanding beyond
   // their bounds during layout, which differs from Ink's behavior.