@flighthq/scene2d 0.2.1-next.840.857425c

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@flighthq/scene2d",
+  "version": "0.2.1-next.840.857425c",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/scene2d"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.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/adjustments": "0.2.1-next.840.857425c",
+    "@flighthq/animation": "0.2.1-next.840.857425c",
+    "@flighthq/entity": "0.2.1-next.840.857425c",
+    "@flighthq/geometry": "0.2.1-next.840.857425c",
+    "@flighthq/materials": "0.2.1-next.840.857425c",
+    "@flighthq/node": "0.2.1-next.840.857425c",
+    "@flighthq/signals": "0.2.1-next.840.857425c",
+    "@flighthq/types": "0.2.1-next.840.857425c"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Display object tree for composited 2D rendering: bitmaps, shapes, text, masks, blend modes",
+  "sideEffects": false
+}

package/src/bitmap.test.ts

@@ -0,0 +1,131 @@
+import { getEntityRuntime } from '@flighthq/entity';
+import { createRectangle } from '@flighthq/geometry';
+import { getNodeLocalBoundsRevision, getNodeLocalContentRevision, getNodeLocalTransformRevision } from '@flighthq/node';
+import type { Bitmap, BitmapRuntime, ImageResource, Node } from '@flighthq/types';
+import { BitmapKind } from '@flighthq/types';
+
+import {
+  computeBitmapLocalBoundsRectangle,
+  createBitmap,
+  createBitmapData,
+  createBitmapRuntime,
+  getBitmapRuntime,
+  setBitmapImage,
+} from './bitmap';
+
+describe('computeBitmapLocalBoundsRectangle', () => {
+  it('sets out dimensions from image when image is present', () => {
+    const bitmap = createBitmap({ data: { image: { width: 100, height: 200 } as ImageResource } });
+    const out = createRectangle();
+    computeBitmapLocalBoundsRectangle(out, bitmap as unknown as Node);
+    expect(out.width).toBe(100);
+    expect(out.height).toBe(200);
+  });
+
+  it('does not modify out when image is null', () => {
+    const bitmap = createBitmap();
+    const out = createRectangle(0, 0, 50, 60);
+    computeBitmapLocalBoundsRectangle(out, bitmap as unknown as Node);
+    expect(out.width).toBe(50);
+    expect(out.height).toBe(60);
+  });
+});
+
+describe('createBitmap', () => {
+  let bitmap: Bitmap;
+
+  beforeEach(() => {
+    bitmap = createBitmap();
+  });
+
+  it('initializes default values', () => {
+    expect(bitmap.data.image).toBeNull();
+    expect(bitmap.data.smoothing).toBe(true);
+    expect(bitmap.kind).toBe(BitmapKind);
+  });
+
+  it('allows pre-defined values', () => {
+    const image = {} as ImageResource;
+    const base = {
+      data: {
+        image: image,
+        smoothing: false,
+      },
+    };
+    const obj = createBitmap(base);
+    expect(obj.data.image).toBe(image);
+    expect(obj.data.smoothing).toBe(false);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createBitmap(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('createBitmapData', () => {
+  it('returns default values', () => {
+    const data = createBitmapData();
+    expect(data.image).toBeNull();
+    expect(data.smoothing).toBe(true);
+  });
+
+  it('allows pre-defined values', () => {
+    const image = { width: 10, height: 10 } as ImageResource;
+    const data = createBitmapData({ image, smoothing: false });
+    expect(data.image).toBe(image);
+    expect(data.smoothing).toBe(false);
+  });
+});
+
+describe('createBitmapRuntime', () => {
+  it('returns a non-null runtime', () => {
+    const runtime = createBitmapRuntime();
+    expect(runtime).not.toBeNull();
+  });
+
+  it('uses computeBitmapLocalBoundsRectangle', () => {
+    const runtime = createBitmapRuntime();
+    expect(runtime.computeLocalBoundsRectangle).toStrictEqual(computeBitmapLocalBoundsRectangle);
+  });
+});
+
+describe('getBitmapRuntime', () => {
+  it('returns the runtime of the given Bitmap', () => {
+    const bitmap = createBitmap();
+    const runtime = getBitmapRuntime(bitmap);
+    expect(runtime).not.toBeNull();
+  });
+});
+
+describe('setBitmapImage', () => {
+  it('sets the image', () => {
+    const bitmap = createBitmap();
+    const image = { width: 64, height: 64 } as ImageResource;
+    setBitmapImage(bitmap, image);
+    expect(bitmap.data.image).toBe(image);
+  });
+
+  it('accepts null', () => {
+    const bitmap = createBitmap({ data: { image: { width: 1, height: 1 } as ImageResource } });
+    setBitmapImage(bitmap, null);
+    expect(bitmap.data.image).toBeNull();
+  });
+
+  it('invalidates local bounds', () => {
+    const bitmap = createBitmap();
+    const runtime = getEntityRuntime(bitmap) as BitmapRuntime;
+    const idBefore = runtime.localBoundsId;
+    setBitmapImage(bitmap, { width: 64, height: 64 } as ImageResource);
+    expect(runtime.localBoundsId).not.toBe(idBefore);
+  });
+
+  it('invalidates local content', () => {
+    const bitmap = createBitmap();
+    const runtime = getEntityRuntime(bitmap) as BitmapRuntime;
+    const idBefore = runtime.localContentId;
+    setBitmapImage(bitmap, { width: 64, height: 64 } as ImageResource);
+    expect(runtime.localContentId).not.toBe(idBefore);
+  });
+});

package/src/displayContainer.test.ts

@@ -0,0 +1,37 @@
+import type { DisplayObject } from '@flighthq/types';
+import { DisplayObjectKind } from '@flighthq/types';
+
+import { createDisplayObject, createDisplayObjectRuntime, getDisplayObjectRuntime } from './displayContainer';
+
+describe('createDisplayObject', () => {
+  let displayContainer: DisplayObject;
+
+  beforeEach(() => {
+    displayContainer = createDisplayObject();
+  });
+
+  it('initializes default values', () => {
+    expect(displayContainer.kind).toStrictEqual(DisplayObjectKind);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createDisplayObject(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('createDisplayObjectRuntime', () => {
+  it('returns a non-null runtime', () => {
+    const runtime = createDisplayObjectRuntime();
+    expect(runtime).not.toBeNull();
+  });
+});
+
+describe('getDisplayObjectRuntime', () => {
+  it('returns the runtime for a DisplayObject', () => {
+    const container = createDisplayObject();
+    const runtime = getDisplayObjectRuntime(container);
+    expect(runtime).not.toBeNull();
+  });
+});

package/src/displayObject.test.ts

@@ -0,0 +1,241 @@
+import { getEntityRuntime } from '@flighthq/entity';
+import { createColorTransform } from '@flighthq/materials';
+import type { BoundsNode, Node2D, Node2DData, Node2DRuntime, PartialNode, Rectangle } from '@flighthq/types';
+import { BlendMode, DisplayObjectKind, Node2DTraitsKey } from '@flighthq/types';
+
+import {
+  addNode2DColorAdjustment,
+  createDisplayObject,
+  createNode2D,
+  createNode2DRuntime,
+  getNode2DColorAdjustments,
+  getNode2DRuntime,
+  isNode2D,
+  setNode2DClip,
+  setNode2DColorAdjustments,
+  setNode2DColorTransform,
+} from './displayObject';
+
+function getRuntime_(obj: Node2D): Node2DRuntime {
+  return getEntityRuntime(obj) as Node2DRuntime;
+}
+
+describe('addNode2DColorAdjustment', () => {
+  let obj: Node2D;
+  beforeEach(() => {
+    obj = createDisplayObject();
+  });
+
+  it('appends to a fresh (null) stack and invalidates appearance', () => {
+    const idBefore = getRuntime_(obj).appearanceId;
+    const adjustment = { kind: 'ColorTransformAdjustment' } as never;
+    addNode2DColorAdjustment(obj, adjustment);
+    expect(getNode2DColorAdjustments(obj)).toEqual([adjustment]);
+    expect(getRuntime_(obj).appearanceId).not.toBe(idBefore);
+  });
+
+  it('appends to an existing stack without mutating the previous array', () => {
+    const a = { kind: 'A' } as never;
+    const b = { kind: 'B' } as never;
+    addNode2DColorAdjustment(obj, a);
+    const first = getNode2DColorAdjustments(obj);
+    addNode2DColorAdjustment(obj, b);
+    expect(getNode2DColorAdjustments(obj)).toEqual([a, b]);
+    expect(first).toEqual([a]); // the earlier array was not mutated
+  });
+});
+
+describe('createDisplayObject', () => {
+  let displayObject: Node2D;
+
+  beforeEach(() => {
+    displayObject = createDisplayObject();
+  });
+
+  it('initializes default values', () => {
+    expect(displayObject.alpha).toBe(1);
+    expect(displayObject.blendMode).toBeNull();
+    expect(displayObject.name).toBeNull();
+    expect(displayObject.visible).toBe(true);
+    expect(displayObject.kind).toBe(DisplayObjectKind);
+  });
+
+  it('allows pre-defined values', () => {
+    const base = {
+      alpha: 2,
+      blendMode: BlendMode.Darken,
+      name: 'foo',
+      rotation: 45,
+      scaleX: 2,
+      scaleY: 3,
+      visible: false,
+      x: 100,
+      y: 200,
+    };
+    const obj = createDisplayObject(base);
+    expect(obj.alpha).toStrictEqual(base.alpha);
+    expect(obj.blendMode).toStrictEqual(base.blendMode);
+    expect(obj.name).toStrictEqual(base.name);
+    expect(obj.rotation).toStrictEqual(base.rotation);
+    expect(obj.scaleX).toStrictEqual(base.scaleX);
+    expect(obj.scaleY).toStrictEqual(base.scaleY);
+    expect(obj.visible).toStrictEqual(base.visible);
+    expect(obj.x).toStrictEqual(base.x);
+    expect(obj.y).toStrictEqual(base.y);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createDisplayObject(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('createNode2D', () => {
+  it('allows creation of a type without a data field', () => {
+    const displayObject = createNode2D(DisplayObjectKind);
+    expect(displayObject).not.toBeNull();
+  });
+
+  it('allows a custom type', () => {
+    const data: PartialNode<Node2DTest> = {
+      x: 100,
+    };
+    const displayObject = createNode2D(DisplayObjectKind, data);
+    expect(displayObject.x).toBe(data.x);
+  });
+
+  it('returns a new object', () => {
+    const data: PartialNode<Node2DTest> = {};
+    const displayObject = createNode2D(DisplayObjectKind, data);
+    expect(displayObject).not.toStrictEqual(data);
+  });
+
+  it('allows use of a data initializer', () => {
+    const data: PartialNode<Node2DTest> = {};
+    const displayObject = createNode2D(DisplayObjectKind, data, createNode2DTestData);
+    expect((displayObject.data as Node2DTestData).foo).toBe('bar');
+  });
+});
+
+describe('createNode2DRuntime', () => {
+  it('returns a graph runtime object', () => {
+    const runtime = createNode2DRuntime();
+    expect(runtime).not.toBeNull();
+  });
+
+  it('sets traits to Node2DTraitsKey', () => {
+    const runtime = createNode2DRuntime();
+    expect(runtime.traits).toBe(Node2DTraitsKey);
+  });
+
+  it('allows a custom bounds calculation', () => {
+    const func = (_out: Rectangle, _source: Readonly<BoundsNode<any>>) => {};
+    const runtime = createNode2DRuntime({ computeLocalBoundsRectangle: func });
+    expect(runtime.computeLocalBoundsRectangle).toStrictEqual(func);
+  });
+});
+
+describe('getNode2DColorAdjustments', () => {
+  it('defaults to null on a fresh node', () => {
+    expect(getNode2DColorAdjustments(createDisplayObject())).toBeNull();
+  });
+});
+
+describe('getNode2DRuntime', () => {
+  it('returns the runtime for a Node2D', () => {
+    const obj = createDisplayObject();
+    const runtime = getNode2DRuntime(obj);
+    expect(runtime).not.toBeNull();
+  });
+});
+
+describe('isNode2D', () => {
+  it('returns true for display objects', () => {
+    expect(isNode2D(createDisplayObject())).toBe(true);
+  });
+});
+
+describe('setNode2DClip', () => {
+  let obj: Node2D;
+  beforeEach(() => {
+    obj = createDisplayObject();
+  });
+
+  it('sets clip', () => {
+    const clip = {
+      contours: null,
+      rect: { x: 0, y: 0, width: 100, height: 50 } as Rectangle,
+      winding: 'nonZero' as const,
+      version: 0,
+    };
+    setNode2DClip(obj, clip);
+    expect(obj.clip).toBe(clip);
+  });
+
+  it('accepts null', () => {
+    setNode2DClip(obj, null);
+    expect(obj.clip).toBeNull();
+  });
+
+  it('invalidates appearance', () => {
+    const idBefore = getRuntime_(obj).appearanceId;
+    setNode2DClip(obj, {
+      contours: null,
+      rect: { x: 0, y: 0, width: 10, height: 10 } as Rectangle,
+      winding: 'nonZero',
+      version: 0,
+    });
+    expect(getRuntime_(obj).appearanceId).not.toBe(idBefore);
+  });
+});
+
+describe('setNode2DColorAdjustments', () => {
+  let obj: Node2D;
+  beforeEach(() => {
+    obj = createDisplayObject();
+  });
+
+  it('sets the stack and invalidates appearance', () => {
+    const idBefore = getRuntime_(obj).appearanceId;
+    const stack = [{ kind: 'ColorTransformAdjustment' }] as never;
+    setNode2DColorAdjustments(obj, stack);
+    expect(getNode2DColorAdjustments(obj)).toBe(stack);
+    expect(getRuntime_(obj).appearanceId).not.toBe(idBefore);
+  });
+
+  it('accepts null', () => {
+    setNode2DColorAdjustments(obj, [{ kind: 'ColorTransformAdjustment' }] as never);
+    setNode2DColorAdjustments(obj, null);
+    expect(getNode2DColorAdjustments(obj)).toBeNull();
+  });
+});
+
+describe('setNode2DColorTransform', () => {
+  it('wraps a color transform as one ColorTransformAdjustment on the stack', () => {
+    const obj = createDisplayObject();
+    setNode2DColorTransform(obj, createColorTransform({ redMultiplier: 0.5 }));
+    const stack = getNode2DColorAdjustments(obj);
+    expect(stack?.length).toBe(1);
+    expect(stack?.[0].kind).toBe('ColorTransformAdjustment');
+  });
+
+  it('clears with null', () => {
+    const obj = createDisplayObject();
+    setNode2DColorTransform(obj, createColorTransform({ redMultiplier: 0.5 }));
+    setNode2DColorTransform(obj, null);
+    expect(getNode2DColorAdjustments(obj)).toBeNull();
+  });
+});
+
+interface Node2DTest extends Node2D {}
+
+interface Node2DTestData extends Node2DData {
+  foo: string;
+}
+
+function createNode2DTestData(data?: Partial<Node2DTestData>): Node2DTestData {
+  return {
+    foo: data?.foo ?? 'bar',
+  };
+}

package/src/displayObjectAnimation.test.ts

@@ -0,0 +1,69 @@
+import { createAnimationChannel, createAnimationClip, createAnimationTrack } from '@flighthq/animation';
+import { getNodeLocalTransformRevision } from '@flighthq/node';
+import type { Node2DAnimationPath, Node2DAnimationTarget } from '@flighthq/types';
+
+import { createDisplayObject } from './displayObject';
+import { applyAnimationClipToNode2D } from './displayObjectAnimation';
+
+describe('applyAnimationClipToNode2D', () => {
+  it.each([
+    { expected: { x: 5, y: 10 }, path: 'Position', values: [0, 0, 10, 20] },
+    { expected: { pivotX: 5, pivotY: 10 }, path: 'Pivot', values: [0, 0, 10, 20] },
+    { expected: { scaleX: 2, scaleY: 3 }, path: 'Scale', values: [1, 1, 3, 5] },
+    { expected: { skewX: 0.25, skewY: 0.5 }, path: 'Skew', values: [0, 0, 0.5, 1] },
+  ] as const)('applies the $path vector path and invalidates transform', ({ expected, path, values }) => {
+    const node = createDisplayObject();
+    const before = getNodeLocalTransformRevision(node);
+    const clip = createBoundClip(node, path, 2, values);
+
+    applyAnimationClipToNode2D(clip, 0.5);
+
+    expect(node).toMatchObject(expected);
+    expect(getNodeLocalTransformRevision(node)).toBeGreaterThan(before);
+  });
+
+  it('applies scalar rotation, alpha, and visibility channels', () => {
+    const node = createDisplayObject();
+    const clip = createAnimationClip([
+      createAnimationChannel(createAnimationTrack({ times: [0, 1], values: [0, 2] }), {
+        node,
+        path: 'Rotation',
+      } satisfies Node2DAnimationTarget),
+      createAnimationChannel(createAnimationTrack({ times: [0, 1], values: [1, 0.5] }), {
+        node,
+        path: 'Alpha',
+      } satisfies Node2DAnimationTarget),
+      createAnimationChannel(createAnimationTrack({ interpolation: 'Step', times: [0, 1], values: [0, 1] }), {
+        node,
+        path: 'Visible',
+      } satisfies Node2DAnimationTarget),
+    ]);
+
+    applyAnimationClipToNode2D(clip, 0.5);
+
+    expect(node.rotation).toBe(1);
+    expect(node.alpha).toBe(0.75);
+    expect(node.visible).toBe(false);
+  });
+
+  it('ignores foreign target refs', () => {
+    const clip = createAnimationClip([
+      createAnimationChannel(createAnimationTrack({ times: [0, 1], values: [0, 1] }), {}),
+    ]);
+    expect(() => applyAnimationClipToNode2D(clip, 0.5)).not.toThrow();
+  });
+});
+
+function createBoundClip(
+  node: ReturnType<typeof createDisplayObject>,
+  path: Node2DAnimationPath,
+  components: number,
+  values: ReadonlyArray<number>,
+) {
+  return createAnimationClip([
+    createAnimationChannel(createAnimationTrack({ components, times: [0, 1], values }), {
+      node,
+      path,
+    } satisfies Node2DAnimationTarget),
+  ]);
+}

package/src/htmlView.test.ts

@@ -0,0 +1,111 @@
+import { createRectangle } from '@flighthq/geometry';
+import type { HtmlView, Node } from '@flighthq/types';
+import { HtmlViewKind } from '@flighthq/types';
+
+import {
+  computeHtmlViewLocalBoundsRectangle,
+  createHtmlView,
+  createHtmlViewData,
+  createHtmlViewRuntime,
+  getHtmlViewRuntime,
+  setHtmlViewSize,
+} from './htmlView';
+
+describe('computeHtmlViewLocalBoundsRectangle', () => {
+  it('sets out dimensions from data width and height', () => {
+    const htmlView = createHtmlView({ data: { width: 320, height: 240 } });
+    const out = createRectangle();
+    computeHtmlViewLocalBoundsRectangle(out, htmlView as unknown as Node);
+    expect(out.width).toBe(320);
+    expect(out.height).toBe(240);
+  });
+});
+
+describe('createHtmlView', () => {
+  let htmlView: HtmlView;
+
+  beforeEach(() => {
+    htmlView = createHtmlView();
+  });
+
+  it('initializes default values', () => {
+    expect(htmlView.data.element).toBeNull();
+    expect(htmlView.data.width).toBe(100);
+    expect(htmlView.data.height).toBe(100);
+    expect(htmlView.kind).toStrictEqual(HtmlViewKind);
+  });
+
+  it('allows pre-defined values', () => {
+    const element = {} as HTMLImageElement;
+    const base = {
+      data: {
+        element: element,
+        width: 640,
+        height: 480,
+      },
+    };
+    const obj = createHtmlView(base);
+    expect(obj.data.element).toStrictEqual(element);
+    expect(obj.data.width).toBe(640);
+    expect(obj.data.height).toBe(480);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createHtmlView(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('createHtmlViewData', () => {
+  it('returns default values', () => {
+    const data = createHtmlViewData();
+    expect(data.element).toBeNull();
+    expect(data.width).toBe(100);
+    expect(data.height).toBe(100);
+  });
+
+  it('allows pre-defined values', () => {
+    const element = {} as HTMLImageElement;
+    const data = createHtmlViewData({ element, width: 200, height: 150 });
+    expect(data.element).toBe(element);
+    expect(data.width).toBe(200);
+    expect(data.height).toBe(150);
+  });
+});
+
+describe('createHtmlViewRuntime', () => {
+  it('returns a non-null runtime', () => {
+    const runtime = createHtmlViewRuntime();
+    expect(runtime).not.toBeNull();
+  });
+
+  it('uses computeHtmlViewLocalBoundsRectangle', () => {
+    const runtime = createHtmlViewRuntime();
+    expect(runtime.computeLocalBoundsRectangle).toStrictEqual(computeHtmlViewLocalBoundsRectangle);
+  });
+});
+
+describe('getHtmlViewRuntime', () => {
+  it('returns the runtime for an HtmlView', () => {
+    const htmlView = createHtmlView();
+    const runtime = getHtmlViewRuntime(htmlView);
+    expect(runtime).not.toBeNull();
+  });
+});
+
+describe('setHtmlViewSize', () => {
+  it('updates width and height', () => {
+    const htmlView = createHtmlView();
+    setHtmlViewSize(htmlView, 320, 240);
+    expect(htmlView.data.width).toBe(320);
+    expect(htmlView.data.height).toBe(240);
+  });
+
+  it('is a no-op when dimensions are unchanged', () => {
+    const htmlView = createHtmlView({ data: { width: 200, height: 150 } });
+    setHtmlViewSize(htmlView, 200, 150);
+    expect(htmlView.data.width).toBe(200);
+    expect(htmlView.data.height).toBe(150);
+  });
+});