@flighthq/scene2d 0.3.0-next.1692.f1a7a9a → 0.3.0-next.1702.8973fda

package/dist/contract.d.ts

@@ -4,4 +4,5 @@ export * from './displayObject';
 export * from './displayObjectAnimation';
 export * from './htmlView';
 export * from './scene2d';
+export * from './sceneKindUsage';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC"}

package/dist/contract.js

@@ -4,4 +4,5 @@ export * from './displayObject';
 export * from './displayObjectAnimation';
 export * from './htmlView';
 export * from './scene2d';
+export * from './sceneKindUsage';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC"}

package/dist/sceneKindUsage.d.ts

@@ -0,0 +1,4 @@
+import type { Scene2D, Scene2DKindUsage } from '@flighthq/types/contract';
+export declare function createScene2DKindUsage(): Scene2DKindUsage;
+export declare function getScene2DKindUsage(out: Scene2DKindUsage, scene: Readonly<Scene2D>): void;
+//# sourceMappingURL=sceneKindUsage.d.ts.map

package/dist/sceneKindUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneKindUsage.d.ts","sourceRoot":"","sources":["../src/sceneKindUsage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAU,OAAO,EAAE,gBAAgB,EAAqB,MAAM,0BAA0B,CAAC;AAKrG,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AASD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAmCzF"}

package/dist/sceneKindUsage.js

@@ -0,0 +1,61 @@
+import { forEachNodeDescendant } from '@flighthq/node/contract';
+import { BlendMode } from '@flighthq/types/contract';
+// Allocates an empty usage record. Separate from the walk so a caller can reuse one across scenes or
+// frames without reallocating four arrays.
+export function createScene2DKindUsage() {
+    return { blendModes: [], materialKinds: [], nodeKinds: [], shapeCommandKeys: [] };
+}
+// Clears `out`, then fills it with every kind this scene uses. One walk, no registry, no backend, no
+// prose — it reads the fields the scene graph already carries, so it cannot itself be the thing you
+// forgot to wire.
+//
+// This answers only WHAT IS IN THE SCENE. Whether anything is registered to draw it is a question for
+// the package that owns the registry: each backend checks its own renderer, material, and shape-command
+// registries. Keeping those answers out of here is what lets a scene stay ignorant of rendering.
+export function getScene2DKindUsage(out, scene) {
+    out.blendModes.length = 0;
+    out.materialKinds.length = 0;
+    out.nodeKinds.length = 0;
+    out.shapeCommandKeys.length = 0;
+    const visit = (node) => {
+        addScene2DUsedKind(out.nodeKinds, node.kind);
+        // An unset node carries null and inherits its parent's mode; Normal is what every backend
+        // composites with no registration at all. Reporting either would send a caller looking for a
+        // realization it never needs, so only an explicit non-Normal mode counts as used.
+        if (node.blendMode !== null && node.blendMode !== BlendMode.Normal) {
+            addScene2DUsedKind(out.blendModes, node.blendMode);
+        }
+        if (node.material !== null)
+            addScene2DUsedKind(out.materialKinds, node.material.kind);
+        // Structural, like isMesh: any node family whose data carries a command stream is walked, including
+        // a custom kind, without a per-kind table that would drift as families are added. Shape, MorphShape
+        // and Scale9Shape all record into the same flat [key, argCount, ...args] buffer.
+        const commands = node.data?.commands;
+        if (commands === undefined)
+            return;
+        let i = 0;
+        while (i < commands.length) {
+            addScene2DUsedKind(out.shapeCommandKeys, commands[i]);
+            i += commands[i + 1] + 2;
+        }
+    };
+    visit(scene.root);
+    // forEachNodeDescendant yields Node<Node2DTraits>; the cast restores the trait fields the walk
+    // generic drops, which the visitor reads structurally.
+    forEachNodeDescendant(scene.root, (node) => visit(node));
+    out.blendModes.sort();
+    out.materialKinds.sort();
+    out.nodeKinds.sort();
+    out.shapeCommandKeys.sort();
+}
+// Linear scan rather than a Set: these lists are the handful of distinct kinds a document uses, where
+// scanning beats allocating four Sets per walk, and it keeps the result a plain array a C port can hold
+// without a hash container.
+function addScene2DUsedKind(kinds, kind) {
+    for (let i = 0; i < kinds.length; i++) {
+        if (kinds[i] === kind)
+            return;
+    }
+    kinds.push(kind);
+}
+//# sourceMappingURL=sceneKindUsage.js.map

package/dist/sceneKindUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneKindUsage.js","sourceRoot":"","sources":["../src/sceneKindUsage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,qGAAqG;AACrG,2CAA2C;AAC3C,MAAM,UAAU,sBAAsB;IACpC,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC;AACpF,CAAC;AAED,qGAAqG;AACrG,oGAAoG;AACpG,kBAAkB;AAClB,EAAE;AACF,sGAAsG;AACtG,wGAAwG;AACxG,iGAAiG;AACjG,MAAM,UAAU,mBAAmB,CAAC,GAAqB,EAAE,KAAwB;IACjF,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7B,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,GAAG,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC;IAEhC,MAAM,KAAK,GAAG,CAAC,IAAsB,EAAQ,EAAE;QAC7C,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,0FAA0F;QAC1F,6FAA6F;QAC7F,kFAAkF;QAClF,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;YACnE,kBAAkB,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YAAE,kBAAkB,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtF,oGAAoG;QACpG,oGAAoG;QACpG,iFAAiF;QACjF,MAAM,QAAQ,GAAI,IAAI,CAAC,IAA6E,EAAE,QAAQ,CAAC;QAC/G,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO;QACnC,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC3B,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC,CAAW,CAAC,CAAC;YAChE,CAAC,IAAK,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAY,GAAG,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,CAAC;IACF,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClB,+FAA+F;IAC/F,uDAAuD;IACvD,qBAAqB,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAwB,CAAC,CAAC,CAAC;IAE7E,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IACtB,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IACzB,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACrB,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,sGAAsG;AACtG,wGAAwG;AACxG,4BAA4B;AAC5B,SAAS,kBAAkB,CAAC,KAAe,EAAE,IAAY;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO;IAChC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/scene2d",
-  "version": "0.3.0-next.1692.f1a7a9a",
+  "version": "0.3.0-next.1702.8973fda",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,15 +36,15 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/adjustments": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/animation": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/entity": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/geometry": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/materials": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/node": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/signals": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/texture": "0.3.0-next.1692.f1a7a9a",
-    "@flighthq/types": "0.3.0-next.1692.f1a7a9a"
+    "@flighthq/adjustments": "0.3.0-next.1702.8973fda",
+    "@flighthq/animation": "0.3.0-next.1702.8973fda",
+    "@flighthq/entity": "0.3.0-next.1702.8973fda",
+    "@flighthq/geometry": "0.3.0-next.1702.8973fda",
+    "@flighthq/materials": "0.3.0-next.1702.8973fda",
+    "@flighthq/node": "0.3.0-next.1702.8973fda",
+    "@flighthq/signals": "0.3.0-next.1702.8973fda",
+    "@flighthq/texture": "0.3.0-next.1702.8973fda",
+    "@flighthq/types": "0.3.0-next.1702.8973fda"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/sceneKindUsage.test.ts

@@ -0,0 +1,119 @@
+import { createUnlitMaterial } from '@flighthq/materials/contract';
+import { addNodeChild } from '@flighthq/node/contract';
+import type { Node2D, Node2DData, ShapeCommandToken } from '@flighthq/types/contract';
+import { BlendMode, DisplayObjectKind, HtmlViewKind } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createDisplayObject } from './displayObject';
+import { createHtmlView } from './htmlView';
+import { createScene2D } from './scene2d';
+import { createScene2DKindUsage, getScene2DKindUsage } from './sceneKindUsage';
+
+// The walk detects a command stream structurally — any node whose `data` carries `commands` — rather
+// than by node kind, so the tests record streams directly. That also keeps @flighthq/shape out of this
+// package's dependencies, which it could not take anyway since shape depends on scene2d.
+function shapeLikeNode(...commands: ShapeCommandToken[]): Node2D {
+  const node = createDisplayObject();
+  node.data = { commands } as unknown as Node2DData;
+  return node;
+}
+
+function usageOf(build: (root: Node2D) => void) {
+  const scene = createScene2D();
+  build(scene.root);
+  const usage = createScene2DKindUsage();
+  getScene2DKindUsage(usage, scene);
+  return usage;
+}
+
+describe('createScene2DKindUsage', () => {
+  it('starts empty so a caller can reuse one record across scenes', () => {
+    expect(createScene2DKindUsage()).toEqual({
+      blendModes: [],
+      materialKinds: [],
+      nodeKinds: [],
+      shapeCommandKeys: [],
+    });
+  });
+});
+
+describe('getScene2DKindUsage', () => {
+  it('collects node kinds across the tree, deduped and sorted', () => {
+    const usage = usageOf((root) => {
+      addNodeChild(root, createHtmlView());
+      addNodeChild(root, createHtmlView());
+      addNodeChild(root, createDisplayObject());
+    });
+    expect(usage.nodeKinds).toEqual([DisplayObjectKind, HtmlViewKind]);
+  });
+
+  it('walks a nested child, not just the root generation', () => {
+    const usage = usageOf((root) => {
+      const group = createDisplayObject();
+      addNodeChild(group, createHtmlView());
+      addNodeChild(root, group);
+    });
+    expect(usage.nodeKinds).toContain(HtmlViewKind);
+  });
+
+  it('reads the command keys out of a recorded stream', () => {
+    const usage = usageOf((root) => {
+      addNodeChild(root, shapeLikeNode('beginFill', 2, 0xff0000, 1, 'drawRectangle', 4, 0, 0, 10, 10, 'endFill', 0));
+    });
+    expect(usage.shapeCommandKeys).toEqual(['beginFill', 'drawRectangle', 'endFill']);
+  });
+
+  it('dedupes a command key repeated within one stream and across nodes', () => {
+    const usage = usageOf((root) => {
+      addNodeChild(root, shapeLikeNode('drawRectangle', 4, 0, 0, 10, 10, 'drawRectangle', 4, 20, 0, 10, 10));
+      addNodeChild(root, shapeLikeNode('drawRectangle', 4, 0, 0, 5, 5));
+    });
+    expect(usage.shapeCommandKeys).toEqual(['drawRectangle']);
+  });
+
+  it('advances by the declared argument count, so arguments are never read as command keys', () => {
+    // The stream is [key, argCount, ...args]. Misreading the stride would report an argument value —
+    // here the string 'round' — as if it were a command key. That is the failure this pins.
+    const usage = usageOf((root) => {
+      addNodeChild(root, shapeLikeNode('lineStyle', 3, 2, 0x000000, 'round', 'moveTo', 2, 0, 0));
+    });
+    expect(usage.shapeCommandKeys).toEqual(['lineStyle', 'moveTo']);
+  });
+
+  it('ignores a node whose data carries no command stream', () => {
+    expect(usageOf((root) => addNodeChild(root, createHtmlView())).shapeCommandKeys).toEqual([]);
+  });
+
+  it('reports a non-default blend mode and omits Normal, which needs no realization', () => {
+    const usage = usageOf((root) => {
+      const plain = createDisplayObject();
+      const lit = createDisplayObject();
+      lit.blendMode = BlendMode.Multiply;
+      addNodeChild(root, plain);
+      addNodeChild(root, lit);
+    });
+    expect(usage.blendModes).toEqual([BlendMode.Multiply]);
+  });
+
+  it('reports the kind of a material a node carries', () => {
+    const usage = usageOf((root) => {
+      const node = createDisplayObject();
+      node.material = createUnlitMaterial();
+      addNodeChild(root, node);
+    });
+    expect(usage.materialKinds).toEqual(['UnlitMaterial']);
+  });
+
+  it('leaves material kinds empty when no node carries one', () => {
+    expect(usageOf((root) => addNodeChild(root, createDisplayObject())).materialKinds).toEqual([]);
+  });
+
+  it('clears every list, so a reused record does not accumulate', () => {
+    const scene = createScene2D();
+    addNodeChild(scene.root, createHtmlView());
+    const usage = createScene2DKindUsage();
+    getScene2DKindUsage(usage, scene);
+    getScene2DKindUsage(usage, scene);
+    expect(usage.nodeKinds).toEqual([DisplayObjectKind, HtmlViewKind]);
+  });
+});