@flighthq/gui 0.4.1-edge.28.7f8e221

package/dist/windowController.js

@@ -0,0 +1,119 @@
+import { getNodeHeight, getNodeWidth } from '@flighthq/node/contract';
+import { createSignal, emitSignal } from '@flighthq/signals/contract';
+import { getButtonControllerSignals } from './buttonController';
+import { connectGuiInteraction, connectGuiSignal, createGuiController, createGuiControllerRuntime, disposeGuiController, getGuiControllerRuntime, setGuiVisualProperty, } from './guiController';
+export function createWindowController(options) {
+    const width = getNodeWidth(options.frame);
+    const height = getNodeHeight(options.frame);
+    const runtime = createGuiControllerRuntime({
+        closeButton: options.closeButton ?? null,
+        content: options.content ?? null,
+        dragPointer: -1,
+        dragStartFrameX: 0,
+        dragStartFrameY: 0,
+        dragStartWorldX: 0,
+        dragStartWorldY: 0,
+        draggable: options.draggable ?? true,
+        frame: options.frame,
+        frameBaseHeight: height,
+        frameBaseScaleX: options.frame.scaleX,
+        frameBaseScaleY: options.frame.scaleY,
+        frameBaseWidth: width,
+        minimumHeight: Math.max(0, options.minimumHeight ?? 0),
+        minimumWidth: Math.max(0, options.minimumWidth ?? 0),
+        resizeHandle: options.resizeHandle ?? null,
+        resizePointer: -1,
+        resizeStartHeight: 0,
+        resizeStartWidth: 0,
+        resizeStartWorldX: 0,
+        resizeStartWorldY: 0,
+        resizable: options.resizable ?? true,
+        signals: { onClose: createSignal(), onMove: createSignal(), onResize: createSignal() },
+        titleBar: options.titleBar ?? null,
+    }, options.transition);
+    const controller = createGuiController(runtime);
+    if (runtime.closeButton !== null) {
+        connectGuiSignal(runtime, getButtonControllerSignals(runtime.closeButton).onClick, () => emitSignal(runtime.signals.onClose));
+    }
+    if (runtime.titleBar !== null) {
+        connectGuiInteraction(runtime, runtime.titleBar, 'onPointerDown', (data) => {
+            if (!runtime.draggable || runtime.frame === null)
+                return;
+            runtime.dragPointer = data.pointerId;
+            runtime.dragStartWorldX = data.worldX;
+            runtime.dragStartWorldY = data.worldY;
+            runtime.dragStartFrameX = runtime.frame.x;
+            runtime.dragStartFrameY = runtime.frame.y;
+        });
+        connectGuiInteraction(runtime, runtime.titleBar, 'onPointerMove', (data) => {
+            if (data.pointerId !== runtime.dragPointer)
+                return;
+            setWindowControllerPosition(controller, runtime.dragStartFrameX + data.worldX - runtime.dragStartWorldX, runtime.dragStartFrameY + data.worldY - runtime.dragStartWorldY);
+        });
+        const endDrag = (data) => {
+            if (data.pointerId === runtime.dragPointer)
+                runtime.dragPointer = -1;
+        };
+        connectGuiInteraction(runtime, runtime.titleBar, 'onPointerUp', endDrag);
+        connectGuiInteraction(runtime, runtime.titleBar, 'onPointerCancel', endDrag);
+        connectGuiInteraction(runtime, runtime.titleBar, 'onReleaseOutside', endDrag);
+    }
+    if (runtime.resizeHandle !== null) {
+        connectGuiInteraction(runtime, runtime.resizeHandle, 'onPointerDown', (data) => {
+            if (!runtime.resizable || runtime.frame === null)
+                return;
+            runtime.resizePointer = data.pointerId;
+            runtime.resizeStartWorldX = data.worldX;
+            runtime.resizeStartWorldY = data.worldY;
+            runtime.resizeStartWidth = getNodeWidth(runtime.frame);
+            runtime.resizeStartHeight = getNodeHeight(runtime.frame);
+        });
+        connectGuiInteraction(runtime, runtime.resizeHandle, 'onPointerMove', (data) => {
+            if (data.pointerId !== runtime.resizePointer)
+                return;
+            setWindowControllerSize(controller, runtime.resizeStartWidth + data.worldX - runtime.resizeStartWorldX, runtime.resizeStartHeight + data.worldY - runtime.resizeStartWorldY);
+        });
+        const endResize = (data) => {
+            if (data.pointerId === runtime.resizePointer)
+                runtime.resizePointer = -1;
+        };
+        connectGuiInteraction(runtime, runtime.resizeHandle, 'onPointerUp', endResize);
+        connectGuiInteraction(runtime, runtime.resizeHandle, 'onPointerCancel', endResize);
+        connectGuiInteraction(runtime, runtime.resizeHandle, 'onReleaseOutside', endResize);
+    }
+    return controller;
+}
+export function disposeWindowController(controller) {
+    const runtime = getGuiControllerRuntime(controller);
+    disposeGuiController(controller, () => {
+        runtime.closeButton = null;
+        runtime.content = null;
+        runtime.frame = null;
+        runtime.resizeHandle = null;
+        runtime.titleBar = null;
+    });
+}
+export function getWindowControllerSignals(controller) {
+    return getGuiControllerRuntime(controller).signals;
+}
+export function setWindowControllerPosition(controller, x, y) {
+    const runtime = getGuiControllerRuntime(controller);
+    if (runtime.frame === null || runtime.disposed || (runtime.frame.x === x && runtime.frame.y === y))
+        return;
+    setGuiVisualProperty(runtime, runtime.frame, 'x', x);
+    setGuiVisualProperty(runtime, runtime.frame, 'y', y);
+    emitSignal(runtime.signals.onMove, x, y);
+}
+export function setWindowControllerSize(controller, width, height) {
+    const runtime = getGuiControllerRuntime(controller);
+    if (runtime.frame === null || runtime.disposed)
+        return;
+    const nextWidth = Math.max(runtime.minimumWidth, width);
+    const nextHeight = Math.max(runtime.minimumHeight, height);
+    if (runtime.frameBaseWidth > 0)
+        setGuiVisualProperty(runtime, runtime.frame, 'scaleX', (runtime.frameBaseScaleX * nextWidth) / runtime.frameBaseWidth);
+    if (runtime.frameBaseHeight > 0)
+        setGuiVisualProperty(runtime, runtime.frame, 'scaleY', (runtime.frameBaseScaleY * nextHeight) / runtime.frameBaseHeight);
+    emitSignal(runtime.signals.onResize, nextWidth, nextHeight);
+}
+//# sourceMappingURL=windowController.js.map

package/dist/windowController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windowController.js","sourceRoot":"","sources":["../src/windowController.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@flighthq/gui",
+  "version": "0.4.1-edge.28.7f8e221",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/gui"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/interaction": "0.4.1-edge.28.7f8e221",
+    "@flighthq/node": "0.4.1-edge.28.7f8e221",
+    "@flighthq/signals": "0.4.1-edge.28.7f8e221",
+    "@flighthq/text": "0.4.1-edge.28.7f8e221",
+    "@flighthq/textinput": "0.4.1-edge.28.7f8e221",
+    "@flighthq/types": "0.4.1-edge.28.7f8e221"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Controller-only behavior for caller-authored 2D interface visuals",
+  "sideEffects": false
+}

package/src/buttonController.test.ts

@@ -0,0 +1,90 @@
+import { connectSignal } from '@flighthq/signals/contract';
+
+import {
+  createButtonController,
+  disposeButtonController,
+  getButtonControllerSignals,
+  isButtonControllerDisabled,
+  setButtonControllerDisabled,
+} from './buttonController';
+import { createGuiTestNode, emitGuiPointer } from './guiTestHelper';
+
+describe('createButtonController', () => {
+  it('drives optional states and emits the complete pointer lifecycle', () => {
+    const up = createGuiTestNode();
+    const over = createGuiTestNode();
+    const down = createGuiTestNode();
+    const controller = createButtonController({ downState: down, overState: over, upState: up });
+    const events: string[] = [];
+    const signals = getButtonControllerSignals(controller);
+    connectSignal(signals.onPress, () => events.push('press'));
+    connectSignal(signals.onRelease, () => events.push('release'));
+    connectSignal(signals.onClick, () => events.push('click'));
+
+    emitGuiPointer(up, 'onPointerOver');
+    expect([up.visible, over.visible, down.visible]).toEqual([false, true, false]);
+    emitGuiPointer(up, 'onPointerDown');
+    expect([up.visible, over.visible, down.visible]).toEqual([false, false, true]);
+    emitGuiPointer(up, 'onPointerUp');
+    emitGuiPointer(up, 'onClick');
+    expect(events).toEqual(['press', 'release', 'click']);
+  });
+
+  it('delegates property assignment only when a transition is supplied', () => {
+    const up = createGuiTestNode();
+    const over = createGuiTestNode();
+    const applies: Array<() => void> = [];
+    createButtonController({
+      overState: over,
+      transition: { run: (request) => applies.push(() => request.apply()) },
+      upState: up,
+    });
+    for (const apply of applies.splice(0)) apply();
+    expect([up.visible, over.visible]).toEqual([true, false]);
+
+    emitGuiPointer(up, 'onPointerOver');
+    expect([up.visible, over.visible]).toEqual([true, false]);
+    for (const apply of applies.splice(0)) apply();
+    expect([up.visible, over.visible]).toEqual([false, true]);
+  });
+});
+
+describe('disposeButtonController', () => {
+  it('detaches listeners idempotently', () => {
+    const up = createGuiTestNode();
+    const controller = createButtonController({ upState: up });
+    let clicks = 0;
+    connectSignal(getButtonControllerSignals(controller).onClick, () => clicks++);
+    disposeButtonController(controller);
+    disposeButtonController(controller);
+    emitGuiPointer(up, 'onClick');
+    expect(clicks).toBe(0);
+  });
+});
+
+describe('getButtonControllerSignals', () => {
+  it('returns a stable signal group', () => {
+    const controller = createButtonController({ upState: createGuiTestNode() });
+    expect(getButtonControllerSignals(controller)).toBe(getButtonControllerSignals(controller));
+  });
+});
+
+describe('isButtonControllerDisabled', () => {
+  it('reads the configured state', () => {
+    expect(isButtonControllerDisabled(createButtonController({ disabled: true, upState: createGuiTestNode() }))).toBe(
+      true,
+    );
+  });
+});
+
+describe('setButtonControllerDisabled', () => {
+  it('blocks click emission', () => {
+    const up = createGuiTestNode();
+    const controller = createButtonController({ upState: up });
+    let clicks = 0;
+    connectSignal(getButtonControllerSignals(controller).onClick, () => clicks++);
+    setButtonControllerDisabled(controller, true);
+    emitGuiPointer(up, 'onClick');
+    expect(clicks).toBe(0);
+  });
+});

package/src/comboBoxController.test.ts

@@ -0,0 +1,71 @@
+import { connectSignal } from '@flighthq/signals/contract';
+
+import { createButtonController } from './buttonController';
+import {
+  createComboBoxController,
+  disposeComboBoxController,
+  getComboBoxControllerSignals,
+  isComboBoxControllerOpen,
+  setComboBoxControllerOpen,
+} from './comboBoxController';
+import { createGuiTestNode, emitGuiPointer } from './guiTestHelper';
+import { createListController } from './listController';
+
+function parts() {
+  const buttonNode = createGuiTestNode();
+  const viewport = createGuiTestNode();
+  const item = createGuiTestNode();
+  return {
+    button: createButtonController({ upState: buttonNode }),
+    buttonNode,
+    item,
+    list: createListController({ content: createGuiTestNode(), items: [item], viewport }),
+    viewport,
+  };
+}
+
+describe('createComboBoxController', () => {
+  it('opens from its button and closes on list selection', () => {
+    const p = parts();
+    const controller = createComboBoxController(p);
+    emitGuiPointer(p.buttonNode, 'onClick');
+    expect(isComboBoxControllerOpen(controller)).toBe(true);
+    emitGuiPointer(p.item, 'onClick');
+    expect(isComboBoxControllerOpen(controller)).toBe(false);
+  });
+});
+
+describe('disposeComboBoxController', () => {
+  it('detaches composed controller signals', () => {
+    const p = parts();
+    const controller = createComboBoxController(p);
+    disposeComboBoxController(controller);
+    emitGuiPointer(p.buttonNode, 'onClick');
+    expect(isComboBoxControllerOpen(controller)).toBe(false);
+  });
+});
+
+describe('getComboBoxControllerSignals', () => {
+  it('emits open-state transitions', () => {
+    const controller = createComboBoxController(parts());
+    const values: boolean[] = [];
+    connectSignal(getComboBoxControllerSignals(controller).onOpenChange, (open) => values.push(open));
+    setComboBoxControllerOpen(controller, true);
+    expect(values).toEqual([true]);
+  });
+});
+
+describe('isComboBoxControllerOpen', () => {
+  it('reads initial open state', () => {
+    expect(isComboBoxControllerOpen(createComboBoxController({ ...parts(), open: true }))).toBe(true);
+  });
+});
+
+describe('setComboBoxControllerOpen', () => {
+  it('updates list visibility', () => {
+    const p = parts();
+    const controller = createComboBoxController(p);
+    setComboBoxControllerOpen(controller, true);
+    expect(p.viewport.visible).toBe(true);
+  });
+});

package/src/guiController.test.ts

@@ -0,0 +1,162 @@
+import { getNodeHitArea, isNodeHitTestEnabled } from '@flighthq/interaction/contract';
+import { createSignal, emitSignal } from '@flighthq/signals/contract';
+import type { Entity } from '@flighthq/types/contract';
+
+import {
+  clampGuiValue,
+  configureGuiHitArea,
+  connectGuiInteraction,
+  connectGuiSignal,
+  createGuiController,
+  createGuiControllerRuntime,
+  disposeGuiController,
+  getGuiControllerRuntime,
+  getGuiLength,
+  getGuiPosition,
+  setGuiPosition,
+  setGuiScale,
+  setGuiVisible,
+  setGuiVisualProperty,
+  snapGuiValue,
+} from './guiController';
+import { createGuiTestNode, emitGuiPointer } from './guiTestHelper';
+
+describe('clampGuiValue', () => {
+  it('clamps finite values and normalizes reversed bounds', () => {
+    expect(clampGuiValue(8, 0, 5)).toBe(5);
+    expect(clampGuiValue(2, 5, 0)).toBe(2);
+    expect(clampGuiValue(NaN, 2, 5)).toBe(2);
+  });
+});
+
+describe('configureGuiHitArea', () => {
+  it('restores a caller hit area on disposal', () => {
+    const target = createGuiTestNode();
+    const area = createGuiTestNode();
+    const runtime = createGuiControllerRuntime({});
+    const controller = createGuiController<Entity, typeof runtime>(runtime);
+    configureGuiHitArea(runtime, target, area);
+    expect(getNodeHitArea(target)).toBe(area);
+    disposeGuiController(controller, () => {});
+    expect(getNodeHitArea(target)).toBeNull();
+  });
+});
+
+describe('connectGuiInteraction', () => {
+  it('connects input and restores hit-test state', () => {
+    const target = createGuiTestNode();
+    const runtime = createGuiControllerRuntime({});
+    const controller = createGuiController<Entity, typeof runtime>(runtime);
+    let calls = 0;
+    connectGuiInteraction(runtime, target, 'onClick', () => calls++);
+    emitGuiPointer(target, 'onClick');
+    expect(calls).toBe(1);
+    disposeGuiController(controller, () => {});
+    expect(isNodeHitTestEnabled(target)).toBe(false);
+  });
+});
+
+describe('connectGuiSignal', () => {
+  it('disconnects a generic signal on disposal', () => {
+    const signal = createSignal<() => void>();
+    const runtime = createGuiControllerRuntime({});
+    const controller = createGuiController<Entity, typeof runtime>(runtime);
+    let calls = 0;
+    connectGuiSignal(runtime, signal, () => calls++);
+    disposeGuiController(controller, () => {});
+    emitSignal(signal);
+    expect(calls).toBe(0);
+  });
+});
+
+describe('createGuiController', () => {
+  it('stores the supplied runtime', () => {
+    const runtime = createGuiControllerRuntime({ value: 4 });
+    const controller = createGuiController<Entity, typeof runtime>(runtime);
+    expect(getGuiControllerRuntime<{ value: number }>(controller).value).toBe(4);
+  });
+});
+
+describe('createGuiControllerRuntime', () => {
+  it('starts undisposed with no transition', () => {
+    const runtime = createGuiControllerRuntime({});
+    expect([runtime.disposed, runtime.transition]).toEqual([false, null]);
+  });
+});
+
+describe('disposeGuiController', () => {
+  it('runs clear once', () => {
+    const runtime = createGuiControllerRuntime({});
+    const controller = createGuiController<Entity, typeof runtime>(runtime);
+    let clears = 0;
+    disposeGuiController(controller, () => clears++);
+    disposeGuiController(controller, () => clears++);
+    expect(clears).toBe(1);
+  });
+});
+
+describe('getGuiControllerRuntime', () => {
+  it('returns the exact runtime identity', () => {
+    const runtime = createGuiControllerRuntime({});
+    expect(getGuiControllerRuntime(createGuiController<Entity, typeof runtime>(runtime))).toBe(runtime);
+  });
+});
+
+describe('getGuiLength', () => {
+  it('reads the requested bounded axis', () => {
+    const node = createGuiTestNode(30, 40);
+    expect([getGuiLength(node, 'horizontal'), getGuiLength(node, 'vertical')]).toEqual([30, 40]);
+  });
+});
+
+describe('getGuiPosition', () => {
+  it('reads the requested transform axis', () => {
+    const node = createGuiTestNode();
+    node.x = 3;
+    node.y = 4;
+    expect([getGuiPosition(node, 'horizontal'), getGuiPosition(node, 'vertical')]).toEqual([3, 4]);
+  });
+});
+
+describe('setGuiPosition', () => {
+  it('sets one axis', () => {
+    const runtime = createGuiControllerRuntime({});
+    const node = createGuiTestNode();
+    setGuiPosition(runtime, node, 'vertical', 5);
+    expect(node.y).toBe(5);
+  });
+});
+
+describe('setGuiScale', () => {
+  it('sets one scale axis', () => {
+    const runtime = createGuiControllerRuntime({});
+    const node = createGuiTestNode();
+    setGuiScale(runtime, node, 'horizontal', 0.5);
+    expect(node.scaleX).toBe(0.5);
+  });
+});
+
+describe('setGuiVisible', () => {
+  it('sets visibility directly by default', () => {
+    const runtime = createGuiControllerRuntime({});
+    const node = createGuiTestNode();
+    setGuiVisible(runtime, node, false);
+    expect(node.visible).toBe(false);
+  });
+});
+
+describe('setGuiVisualProperty', () => {
+  it('offers intermediate writes to an opt-in transition', () => {
+    const node = createGuiTestNode();
+    const runtime = createGuiControllerRuntime({}, { run: (request) => request.apply(0.5) });
+    setGuiVisualProperty(runtime, node, 'alpha', 0);
+    expect(node.alpha).toBe(0.5);
+  });
+});
+
+describe('snapGuiValue', () => {
+  it('snaps around the minimum', () => {
+    expect(snapGuiValue(3.1, 1, 2)).toBe(3);
+    expect(snapGuiValue(3.1, 1, null)).toBe(3.1);
+  });
+});

package/src/guiTreeShaking.test.ts

@@ -0,0 +1,35 @@
+// @vitest-environment node
+
+import { build } from 'esbuild';
+
+describe('GUI controller tree shaking', () => {
+  it('does not pull the catalog or tween runtime into a Button-only bundle', async () => {
+    const result = await build({
+      bundle: true,
+      format: 'esm',
+      logLevel: 'silent',
+      minify: true,
+      packages: 'external',
+      stdin: {
+        contents: `export { createButtonController } from './contract.ts';`,
+        resolveDir: fileUrlDirectory(import.meta.url),
+        sourcefile: 'tree-shake-button.ts',
+      },
+      treeShaking: true,
+      write: false,
+    });
+    const output = result.outputFiles[0].text;
+    expect(output).toContain('createButtonController');
+    expect(output).not.toContain('setInterval');
+    expect(output).not.toContain('onExpandChange');
+    expect(output).not.toContain('createTextInputManager');
+    expect(output).not.toContain('@flighthq/tween');
+  });
+});
+
+function fileUrlDirectory(url: string): string {
+  const directory = new URL('.', url);
+  const pathname = decodeURIComponent(directory.pathname);
+  if (directory.hostname !== '') return `//${directory.hostname}${pathname}`;
+  return /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+}

package/src/listController.test.ts

@@ -0,0 +1,96 @@
+import { connectSignal } from '@flighthq/signals/contract';
+
+import { createGuiTestNode, emitGuiKeyboard, emitGuiPointer } from './guiTestHelper';
+import {
+  createListController,
+  disposeListController,
+  getListControllerSelectedIndex,
+  getListControllerSignals,
+  setListControllerSelectedIndex,
+  setListControllerVisible,
+} from './listController';
+
+describe('createListController', () => {
+  it('selects and activates item visuals', () => {
+    const items = [createGuiTestNode(), createGuiTestNode()];
+    const controller = createListController({ content: createGuiTestNode(), items, viewport: createGuiTestNode() });
+    const activations: number[] = [];
+    connectSignal(getListControllerSignals(controller).onActivate, (index) => activations.push(index));
+    emitGuiPointer(items[1], 'onClick');
+    emitGuiPointer(items[1], 'onDoubleClick');
+    expect(getListControllerSelectedIndex(controller)).toBe(1);
+    expect(activations).toEqual([1]);
+  });
+
+  it('supports hierarchical-independent flat keyboard navigation', () => {
+    const viewport = createGuiTestNode();
+    const controller = createListController({
+      content: createGuiTestNode(),
+      items: [createGuiTestNode(), createGuiTestNode()],
+      viewport,
+    });
+    emitGuiKeyboard(viewport, 'onKeyDown', 'ArrowDown');
+    expect(getListControllerSelectedIndex(controller)).toBe(0);
+  });
+});
+
+describe('disposeListController', () => {
+  it('detaches item input', () => {
+    const item = createGuiTestNode();
+    const controller = createListController({
+      content: createGuiTestNode(),
+      items: [item],
+      viewport: createGuiTestNode(),
+    });
+    disposeListController(controller);
+    emitGuiPointer(item, 'onClick');
+    expect(getListControllerSelectedIndex(controller)).toBe(-1);
+  });
+});
+
+describe('getListControllerSelectedIndex', () => {
+  it('normalizes invalid initial values', () => {
+    expect(
+      getListControllerSelectedIndex(
+        createListController({
+          content: createGuiTestNode(),
+          items: [],
+          selectedIndex: 2,
+          viewport: createGuiTestNode(),
+        }),
+      ),
+    ).toBe(-1);
+  });
+});
+
+describe('getListControllerSignals', () => {
+  it('returns stable signals', () => {
+    const controller = createListController({ content: createGuiTestNode(), items: [], viewport: createGuiTestNode() });
+    expect(getListControllerSignals(controller)).toBe(getListControllerSignals(controller));
+  });
+});
+
+describe('setListControllerSelectedIndex', () => {
+  it('emits only real changes', () => {
+    const controller = createListController({
+      content: createGuiTestNode(),
+      items: [createGuiTestNode()],
+      viewport: createGuiTestNode(),
+    });
+    const values: number[] = [];
+    connectSignal(getListControllerSignals(controller).onSelect, (index) => values.push(index));
+    setListControllerSelectedIndex(controller, 0);
+    setListControllerSelectedIndex(controller, 0);
+    expect(values).toEqual([0]);
+  });
+});
+
+describe('setListControllerVisible', () => {
+  it('changes both list-owned references without creating visuals', () => {
+    const content = createGuiTestNode();
+    const viewport = createGuiTestNode();
+    const controller = createListController({ content, items: [], viewport });
+    setListControllerVisible(controller, false);
+    expect([content.visible, viewport.visible]).toEqual([false, false]);
+  });
+});