effect-motion 0.2.0 → 0.3.0

package/dist/render/shapes.js

@@ -0,0 +1,310 @@
+import * as Tvg from "@effect-motion/thorvg";
+import * as Effect from "effect/Effect";
+import * as Color from "../Color.js";
+import { renderOpacity, renderSize } from "../particles/overLife.js";
+import { ParticleField } from "../particles/ParticleField.js";
+import * as Circle from "../shapes/Circle.js";
+import * as Ellipse from "../shapes/Ellipse.js";
+import * as Group from "../shapes/Group.js";
+import * as Hud from "../shapes/Hud.js";
+import * as Image from "../shapes/Image.js";
+import * as Line from "../shapes/Line.js";
+import * as Path from "../shapes/Path.js";
+import * as Rect from "../shapes/Rect.js";
+import * as Square from "../shapes/Square.js";
+import * as Text from "../shapes/Text.js";
+import { applyStyle, finishPaint } from "./paint.js";
+/**
+ * ThorVG paint functions for the built-in shapes — this file is the coverage
+ * manifest: `paints` is typed `PaintFunctions<...>`, so a built-in missing a
+ * paint function is a type error, not a runtime surprise.
+ */
+export const circle = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const shape = yield* Tvg.Shape.make();
+    yield* Tvg.Shape.appendCircle(shape, data.x, data.y, data.radius, data.radius);
+    yield* applyStyle(shape, data);
+    yield* finishPaint(shape, scene, projection);
+});
+export const rect = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const shape = yield* Tvg.Shape.make();
+    const quad = projection.quad;
+    if (quad !== undefined) {
+        // a tilted plane: the vertices are already projected to screen
+        // (near-plane-clipped, 3–5 points — true perspective foreshortening,
+        // not an affine), so paint the exact polygon and skip the billboard
+        // transform
+        for (const [i, p] of quad.entries()) {
+            yield* i === 0
+                ? Tvg.Shape.moveTo(shape, p.x, p.y)
+                : Tvg.Shape.lineTo(shape, p.x, p.y);
+        }
+        yield* Tvg.Shape.close(shape);
+        yield* applyStyle(shape, data);
+        yield* Tvg.Scene.add(scene, shape);
+        return;
+    }
+    // SVG lone-radius semantics: one set radius applies to both axes
+    yield* Tvg.Shape.appendRect(shape, data.x, data.y, data.width, data.height, data.rx ?? data.ry ?? 0, data.ry ?? data.rx ?? 0);
+    yield* applyStyle(shape, data);
+    yield* finishPaint(shape, scene, projection);
+});
+export const square = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const shape = yield* Tvg.Shape.make();
+    yield* Tvg.Shape.appendRect(shape, data.x, data.y, data.size, data.size);
+    yield* applyStyle(shape, data);
+    yield* finishPaint(shape, scene, projection);
+});
+export const ellipse = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const shape = yield* Tvg.Shape.make();
+    yield* Tvg.Shape.appendCircle(shape, data.x, data.y, data.rx, data.ry);
+    yield* applyStyle(shape, data);
+    yield* finishPaint(shape, scene, projection);
+});
+export const line = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const shape = yield* Tvg.Shape.make();
+    const segment = projection.segment;
+    if (segment !== undefined) {
+        // skeletal path: the endpoints are already projected to screen
+        // (near-plane-clipped, per-endpoint perspective), so draw the
+        // exact segment and skip the billboard transform — stroke width
+        // scales by the segment's midpoint perspective scale instead
+        yield* Tvg.Shape.moveTo(shape, segment[0].x, segment[0].y);
+        yield* Tvg.Shape.lineTo(shape, segment[1].x, segment[1].y);
+    }
+    else {
+        yield* Tvg.Shape.moveTo(shape, data.x, data.y);
+        yield* Tvg.Shape.lineTo(shape, data.x2, data.y2);
+    }
+    // a line has no fill; stroke defaults come from its schema
+    if (data.stroke !== undefined) {
+        const { r, g, b, a } = Color.bytes(data.stroke);
+        yield* Tvg.Shape.setStrokeColor(shape, r, g, b, a);
+    }
+    yield* Tvg.Shape.setStrokeWidth(shape, segment !== undefined
+        ? data.strokeWidth * projection.scale
+        : data.strokeWidth);
+    if (data.opacity !== 1) {
+        yield* Tvg.Paint.setOpacity(shape, Math.round(data.opacity * 255));
+    }
+    if (segment !== undefined) {
+        yield* Tvg.Scene.add(scene, shape);
+        return;
+    }
+    yield* finishPaint(shape, scene, projection);
+});
+export const path = ({ data, scene, projection, }) => Effect.gen(function* () {
+    // the flatten step already split, projected, and near-plane-clipped the
+    // command points (see Projection.projectPath) — geometry arrives in
+    // screen space, so emit it directly and apply no transform. A path with
+    // nothing visible was culled before paint, so subpaths is present here.
+    const subpaths = projection.subpaths;
+    if (subpaths === undefined) {
+        return;
+    }
+    const shape = yield* Tvg.Shape.make();
+    for (const subpath of subpaths) {
+        for (const [i, p] of subpath.points.entries()) {
+            yield* i === 0
+                ? Tvg.Shape.moveTo(shape, p.x, p.y)
+                : Tvg.Shape.lineTo(shape, p.x, p.y);
+        }
+        // ponytail: a near-clipped closed subpath strokes along the synthetic
+        // clip edge too — accepted; split stroke/fill geometry if it matters
+        if (subpath.closed) {
+            yield* Tvg.Shape.close(shape);
+        }
+    }
+    yield* applyStyle(shape, data);
+    // stroke width scales by the path's perspective scale (its mean visible
+    // depth), overriding the unscaled width applyStyle set
+    if (data.strokeWidth !== undefined) {
+        yield* Tvg.Shape.setStrokeWidth(shape, data.strokeWidth * projection.scale);
+    }
+    yield* Tvg.Scene.add(scene, shape);
+});
+// A group paints nothing itself: its position has already composed into its
+// children's world coordinates during flatten, and each child was emitted as
+// its own paintable. This is a no-op, present only so the coverage map is
+// exhaustive.
+export const group = () => Effect.void;
+// A Hud is a container like Group: it paints nothing itself — its meaning
+// (identity-camera projection, top-tier order) lives in the renderer's
+// flatten/sort, not in a paint.
+export const hud = () => Effect.void;
+export const image = ({ data, scene, projection, }) => Effect.gen(function* () {
+    // the session decoded the asset once at open; a missing name (never
+    // declared, or its fetch/decode failed) is a soft skip — this instance
+    // paints nothing and the rest of the frame renders
+    const { pictures } = yield* Tvg.RenderSession;
+    const source = pictures.get(data.image);
+    if (source === undefined) {
+        return;
+    }
+    // duplicates share the decoded surface (spike-verified ~42µs each), so
+    // per-frame cost is a handle copy, not a decode
+    const picture = yield* Tvg.Paint.duplicate(source);
+    // declared size scales per axis via the transform — NOT Picture.setSize,
+    // which preserves the source aspect (uniform min-factor scale, probe-
+    // verified: 8×8 sized to 40×20 renders 20×20). A lone dimension is
+    // ignored (aspect math would need the natural size, which frame data
+    // never sees).
+    let sx = 1;
+    let sy = 1;
+    if (data.width !== undefined && data.height !== undefined) {
+        const natural = yield* Tvg.Picture.getSize(picture);
+        if (natural.width > 0 && natural.height > 0) {
+            sx = data.width / natural.width;
+            sy = data.height / natural.height;
+        }
+    }
+    if (data.opacity !== 1) {
+        yield* Tvg.Paint.setOpacity(picture, Math.round(data.opacity * 255));
+    }
+    // a picture draws from its own origin, unlike shapes which bake
+    // data.x/y into geometry — compose scale-to-declared-size and the local
+    // anchor translate into the projection affine so (data.x, data.y) is
+    // the top-left, like Rect: screen ∘ translate(x, y) ∘ scale(sx, sy)
+    const m = projection.screen;
+    const composed = {
+        a: m.a * sx,
+        b: m.b * sx,
+        c: m.c * sy,
+        d: m.d * sy,
+        e: m.a * data.x + m.c * data.y + m.e,
+        f: m.b * data.x + m.d * data.y + m.f,
+    };
+    const isIdentity = composed.a === 1 &&
+        composed.b === 0 &&
+        composed.c === 0 &&
+        composed.d === 1 &&
+        composed.e === 0 &&
+        composed.f === 0;
+    if (!isIdentity) {
+        yield* Tvg.Paint.setTransform(picture, composed);
+    }
+    yield* Tvg.Scene.add(scene, picture);
+    // ponytail: billboard only — a tilted image needs a projective
+    // setTransform (full 3×3 bottom row) mapping the projected quad; add
+    // when a scene needs a tilted image.
+});
+export const text = ({ data, scene, projection, }) => Effect.gen(function* () {
+    const glyphs = yield* Tvg.Text.make();
+    // setFont fails ("insufficient condition") when the family isn't loaded
+    // into the engine yet — a missing/not-yet-fetched font. That must NOT
+    // abort the frame (it would blank every other paint too): swallow it so
+    // this one text simply doesn't draw and the rest of the frame renders.
+    yield* Tvg.Text.setFont(glyphs, data.fontFamily).pipe(Effect.ignore);
+    yield* Tvg.Text.setText(glyphs, data.text);
+    const { r, g, b } = Color.bytes(data.fill);
+    yield* Tvg.Text.setColor(glyphs, r, g, b);
+    if (data.opacity !== 1) {
+        yield* Tvg.Paint.setOpacity(glyphs, Math.round(data.opacity * 255));
+    }
+    // ThorVG QUIRK (verified against this build): text inside a nested scene
+    // renders ONLY when positioned by a plain `translate` — `set_transform`,
+    // `scale`, and `text_align` on a scene-child text all produce nothing. So
+    // text can't use the projection's full affine or ThorVG's align. Instead:
+    //  - fold the perspective scale into the FONT SIZE (setTextSize scales the
+    //    glyphs; scale-transform doesn't work),
+    //  - apply textAnchor/baseline as a local offset from an ESTIMATED box,
+    //  - position with translate(screenX, screenY).
+    // ponytail: this handles translate+uniform-scale cameras (the common
+    // case). A rotated/sheared camera on text isn't expressed (text stays
+    // axis-aligned); revisit if a scene tilts text in 3D.
+    const scale = projection.scale > 0 ? projection.scale : 1;
+    const size = data.fontSize * scale;
+    yield* Tvg.Text.setSize(glyphs, size);
+    // estimated text box (proportional font, ~0.6 advance/size; ascent/cap
+    // factors) — used because ThorVG align doesn't work on scene-child text
+    const estWidth = size * data.text.length * AVG_CHAR_WIDTH;
+    const dx = data.textAnchor === "middle"
+        ? -estWidth / 2
+        : data.textAnchor === "end"
+            ? -estWidth
+            : 0;
+    // text origin y is the baseline (bottom of glyphs); shift UP by ~half cap
+    // height to center (middle), or up by the full ascent so the given point
+    // is the TOP (hanging); leave the baseline at y (auto)
+    const dy = data.baseline === "middle"
+        ? -size * CAP_CENTER
+        : data.baseline === "hanging"
+            ? -size * ASCENT
+            : 0;
+    // where the anchor point (data.x, data.y) lands on screen under the camera
+    const m = projection.screen;
+    const screenX = m.a * data.x + m.c * data.y + m.e;
+    const screenY = m.b * data.x + m.d * data.y + m.f;
+    yield* Tvg.Paint.translate(glyphs, screenX + dx, screenY + dy);
+    yield* Tvg.Scene.add(scene, glyphs);
+});
+// Text-box estimates (see the `text` paint fn): mean advance / cap-center /
+// ascent as fractions of font size, for the default sans. Used because ThorVG's
+// text align/transform don't work on scene-child text in this build.
+const AVG_CHAR_WIDTH = 0.6;
+const CAP_CENTER = 0.35;
+const ASCENT = 0.8;
+/**
+ * ParticleField: live particles batched into one shape PER (color, opacity)
+ * bucket — ThorVG fills a shape uniformly, so particles that share a color and
+ * (quantized) over-life opacity are appended into the same shape and filled
+ * once. Sized/faded by the over-life curves; dead slots emit nothing.
+ * ponytail: one shape per distinct (color, opacity-bucket) — far fewer than one
+ * per particle, but a fully instanced path is the upgrade if this is a wall.
+ */
+export const particleField = ({ data, scene, projection, }) => Effect.gen(function* () {
+    // group live particles by fill color + quantized opacity (24 buckets), so
+    // each bucket is one uniformly-filled shape. Circles are appended in the
+    // field's local coords (data.x/y offsets the whole field).
+    const buckets = new Map();
+    for (const p of data.buffer) {
+        if (!p.alive) {
+            continue;
+        }
+        const r = renderSize(p, data.sizeOverLife);
+        if (r <= 0) {
+            continue;
+        }
+        const o = renderOpacity(p, data.opacityOverLife) *
+            data.opacity;
+        const alpha = Math.max(0, Math.min(255, Math.round(o * 255)));
+        if (alpha === 0) {
+            continue;
+        }
+        // quantize alpha to keep the bucket count bounded (~24 steps)
+        const qAlpha = Math.round(alpha / 11) * 11;
+        const key = `${Color.toHex(p.color)}\0${qAlpha}`;
+        let bucket = buckets.get(key);
+        if (bucket === undefined) {
+            bucket = { color: p.color, alpha: qAlpha, circles: [] };
+            buckets.set(key, bucket);
+        }
+        bucket.circles.push([data.x + p.x, data.y + p.y, r]);
+    }
+    for (const { color, alpha, circles } of buckets.values()) {
+        const shape = yield* Tvg.Shape.make();
+        for (const [cx, cy, r] of circles) {
+            yield* Tvg.Shape.appendCircle(shape, cx, cy, r, r);
+        }
+        const { r, g, b } = Color.bytes(color);
+        yield* Tvg.Shape.setFillColor(shape, r, g, b, alpha);
+        yield* finishPaint(shape, scene, projection);
+    }
+});
+/**
+ * The exhaustive paint-function map for every built-in entity. Typed
+ * `PaintFunctions<...>` so a missing built-in fails to type-check (the old
+ * "coverage manifest" guarantee, without a Context registry).
+ */
+export const builtinPaints = {
+    [Circle.Circle.name]: circle,
+    [Rect.Rect.name]: rect,
+    [Square.Square.name]: square,
+    [Ellipse.Ellipse.name]: ellipse,
+    [Line.Line.name]: line,
+    [Path.Path.name]: path,
+    [Group.Group.name]: group,
+    [Hud.Hud.name]: hud,
+    [Text.Text.name]: text,
+    [Image.Image.name]: image,
+    [ParticleField.name]: particleField,
+};

package/dist/shapes/Circle.d.ts

@@ -1,37 +1,32 @@
-import * as Entity from "../Entity";
+import * as Entity from "../Entity.js";
 export declare const Circle: Entity.Entity<"shapes/Circle", import("effect/Schema").Struct<{
     x: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
     y: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
+    z: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
     opacity: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
-    fill: import("effect/Schema").withConstructorDefault<import("effect/Schema").String>;
-    stroke: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    fill: import("effect/Schema").withConstructorDefault<typeof import("../Color.js").Color>;
+    stroke: import("effect/Schema").optionalKey<typeof import("../Color.js").Color>;
     strokeWidth: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
     radius: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
 }>, {
     readonly "~position": Entity.TraitLens<{
         readonly x: number;
         readonly y: number;
+        readonly z: number;
         readonly opacity: number;
-        readonly fill: string;
-        readonly stroke?: string;
+        readonly fill: import("../Color.js").Color;
+        readonly stroke?: import("../Color.js").Color;
         readonly strokeWidth?: number;
         readonly radius: number;
     }, Entity.Position>;
     readonly "~opacity": Entity.TraitLens<{
         readonly x: number;
         readonly y: number;
+        readonly z: number;
         readonly opacity: number;
-        readonly fill: string;
-        readonly stroke?: string;
+        readonly fill: import("../Color.js").Color;
+        readonly stroke?: import("../Color.js").Color;
         readonly strokeWidth?: number;
         readonly radius: number;
     }, number>;
-}, {
-    readonly x?: number;
-    readonly y?: number;
-    readonly opacity?: number;
-    readonly fill?: string;
-    readonly stroke?: string;
-    readonly strokeWidth?: number;
-    readonly radius?: number;
 }>;

package/dist/shapes/Circle.js

@@ -1,5 +1,5 @@
-import * as Entity from "../Entity";
-import * as Shape2D from "./Shape2D";
+import * as Entity from "../Entity.js";
+import * as Shape2D from "./Shape2D.js";
 export const Circle = Entity.make("shapes/Circle", {
     ...Shape2D.filled,
     radius: Shape2D.defaultedNumber(10),

package/dist/shapes/Ellipse.d.ts

@@ -1,10 +1,11 @@
-import * as Entity from "../Entity";
+import * as Entity from "../Entity.js";
 export declare const Ellipse: Entity.Entity<"shapes/Ellipse", import("effect/Schema").Struct<{
     x: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
     y: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
+    z: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
     opacity: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
-    fill: import("effect/Schema").withConstructorDefault<import("effect/Schema").String>;
-    stroke: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    fill: import("effect/Schema").withConstructorDefault<typeof import("../Color.js").Color>;
+    stroke: import("effect/Schema").optionalKey<typeof import("../Color.js").Color>;
     strokeWidth: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
     rx: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
     ry: import("effect/Schema").withConstructorDefault<import("effect/Schema").Number>;
@@ -12,9 +13,10 @@ export declare const Ellipse: Entity.Entity<"shapes/Ellipse", import("effect/Sch
     readonly "~position": Entity.TraitLens<{
         readonly x: number;
         readonly y: number;
+        readonly z: number;
         readonly opacity: number;
-        readonly fill: string;
-        readonly stroke?: string;
+        readonly fill: import("../Color.js").Color;
+        readonly stroke?: import("../Color.js").Color;
         readonly strokeWidth?: number;
         readonly rx: number;
         readonly ry: number;
@@ -22,20 +24,12 @@ export declare const Ellipse: Entity.Entity<"shapes/Ellipse", import("effect/Sch
     readonly "~opacity": Entity.TraitLens<{
         readonly x: number;
         readonly y: number;
+        readonly z: number;
         readonly opacity: number;
-        readonly fill: string;
-        readonly stroke?: string;
+        readonly fill: import("../Color.js").Color;
+        readonly stroke?: import("../Color.js").Color;
         readonly strokeWidth?: number;
         readonly rx: number;
         readonly ry: number;
     }, number>;
-}, {
-    readonly x?: number;
-    readonly y?: number;
-    readonly opacity?: number;
-    readonly fill?: string;
-    readonly stroke?: string;
-    readonly strokeWidth?: number;
-    readonly rx?: number;
-    readonly ry?: number;
 }>;

package/dist/shapes/Ellipse.js

@@ -1,5 +1,5 @@
-import * as Entity from "../Entity";
-import * as Shape2D from "./Shape2D";
+import * as Entity from "../Entity.js";
+import * as Shape2D from "./Shape2D.js";
 export const Ellipse = Entity.make("shapes/Ellipse", {
     ...Shape2D.filled,
     rx: Shape2D.defaultedNumber(20),

package/dist/shapes/Group.d.ts

@@ -1,5 +1,5 @@
 import * as Schema from "effect/Schema";
-import * as Entity from "../Entity";
+import * as Entity from "../Entity.js";
 export declare const TransformMatrix: Schema.Struct<{
     readonly a: Schema.Number;
     readonly b: Schema.Number;
@@ -36,24 +36,6 @@ export declare const TransformOperation: Schema.TaggedUnion<{
         readonly y: Schema.Number;
     }>;
 }>;
-declare const TransformOperations: Schema.$Array<Schema.TaggedUnion<{
-    readonly "transform/matrix": Schema.TaggedStruct<"transform/matrix", {
-        readonly a: Schema.Number;
-        readonly b: Schema.Number;
-        readonly c: Schema.Number;
-        readonly d: Schema.Number;
-        readonly e: Schema.Number;
-        readonly f: Schema.Number;
-    }>;
-    readonly "transform/scale": Schema.TaggedStruct<"transform/scale", {
-        readonly x: Schema.Number;
-        readonly y: Schema.Number;
-    }>;
-    readonly "transform/translate": Schema.TaggedStruct<"transform/translate", {
-        readonly x: Schema.Number;
-        readonly y: Schema.Number;
-    }>;
-}>>;
 export declare const Transform: Schema.decodeTo<Schema.Struct<{
     readonly a: Schema.Number;
     readonly b: Schema.Number;
@@ -79,27 +61,10 @@ export declare const Transform: Schema.decodeTo<Schema.Struct<{
         readonly y: Schema.Number;
     }>;
 }>>, never, never>;
-declare const fields: {
-    x: Schema.withConstructorDefault<Schema.Number>;
-    y: Schema.withConstructorDefault<Schema.Number>;
-    opacity: Schema.withConstructorDefault<Schema.Number>;
-    transform: Schema.withConstructorDefault<Schema.Struct<{
-        readonly a: Schema.Number;
-        readonly b: Schema.Number;
-        readonly c: Schema.Number;
-        readonly d: Schema.Number;
-        readonly e: Schema.Number;
-        readonly f: Schema.Number;
-    }>>;
-    children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
-};
-type StoredInput = Schema.Struct<typeof fields>["~type.make.in"];
-type GroupInput = Omit<StoredInput, "transform"> & {
-    readonly transform?: typeof TransformOperations.Type;
-};
 export declare const Group: Entity.Entity<"shapes/Group", Schema.Struct<{
     x: Schema.withConstructorDefault<Schema.Number>;
     y: Schema.withConstructorDefault<Schema.Number>;
+    z: Schema.withConstructorDefault<Schema.Number>;
     opacity: Schema.withConstructorDefault<Schema.Number>;
     transform: Schema.withConstructorDefault<Schema.Struct<{
         readonly a: Schema.Number;
@@ -114,6 +79,7 @@ export declare const Group: Entity.Entity<"shapes/Group", Schema.Struct<{
     "~position": Entity.TraitLens<Schema.Struct.ReadonlySide<{
         x: Schema.withConstructorDefault<Schema.Number>;
         y: Schema.withConstructorDefault<Schema.Number>;
+        z: Schema.withConstructorDefault<Schema.Number>;
         opacity: Schema.withConstructorDefault<Schema.Number>;
         transform: Schema.withConstructorDefault<Schema.Struct<{
             readonly a: Schema.Number;
@@ -128,6 +94,7 @@ export declare const Group: Entity.Entity<"shapes/Group", Schema.Struct<{
     "~opacity": Entity.TraitLens<Schema.Struct.ReadonlySide<{
         x: Schema.withConstructorDefault<Schema.Number>;
         y: Schema.withConstructorDefault<Schema.Number>;
+        z: Schema.withConstructorDefault<Schema.Number>;
         opacity: Schema.withConstructorDefault<Schema.Number>;
         transform: Schema.withConstructorDefault<Schema.Struct<{
             readonly a: Schema.Number;
@@ -139,7 +106,7 @@ export declare const Group: Entity.Entity<"shapes/Group", Schema.Struct<{
         }>>;
         children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
     }, "Type">, number>;
-}, GroupInput>;
+}>;
 /** The group's x/y position composed outside its normalized local transform. */
 export declare const resolvedTransform: (data: {
     readonly x: number;
@@ -147,4 +114,3 @@ export declare const resolvedTransform: (data: {
     readonly transform: TransformMatrix;
 }) => TransformMatrix;
 export declare const isIdentityTransform: (matrix: TransformMatrix) => boolean;
-export {};

package/dist/shapes/Group.js

@@ -1,8 +1,8 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as SchemaGetter from "effect/SchemaGetter";
-import * as Entity from "../Entity";
-import * as Shape2D from "./Shape2D";
+import * as Entity from "../Entity.js";
+import * as Shape2D from "./Shape2D.js";
 export const TransformMatrix = Schema.Struct({
     a: Schema.Number,
     b: Schema.Number,
@@ -60,7 +60,7 @@ const fields = {
     children: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.sync(() => []))),
 };
 const decodeTransform = Schema.decodeUnknownSync(Transform);
-const normalizeInput = (input) => Array.isArray(input.transform)
+const _normalizeInput = (input) => Array.isArray(input.transform)
     ? { ...input, transform: decodeTransform(input.transform) }
     : input;
 // A container: positions and structures its children, paints nothing.
@@ -71,7 +71,7 @@ const traits = {
     "~position": Shape2D.positionLens(),
     "~opacity": Shape2D.opacityLens(),
 };
-export const Group = Entity.make("shapes/Group", fields, traits, { normalize: normalizeInput });
+export const Group = Entity.make("shapes/Group", fields, traits);
 /** The group's x/y position composed outside its normalized local transform. */
 export const resolvedTransform = (data) => multiplyTransforms({ ...identityTransform, e: data.x, f: data.y }, data.transform);
 export const isIdentityTransform = (matrix) => matrix.a === 1 &&

package/dist/shapes/Hud.d.ts

@@ -0,0 +1,38 @@
+import * as Schema from "effect/Schema";
+import * as Entity from "../Entity.js";
+/**
+ * A screen-space container: its subtree is projected through the IDENTITY
+ * camera instead of the active one, so HUD content ignores camera movement,
+ * zoom, shake — and depth of field (the identity camera's aperture is 0).
+ * HUD content always paints on top of world content.
+ *
+ * `x`/`y` compose into the children in screen coordinates (slide a whole
+ * lower-third in with one tween). There is deliberately no `z`: the
+ * container has no world depth. Children may still use their own `z` for
+ * deliberate in-HUD depth; it defaults to 0 (flat, plain-2D placement).
+ *
+ * A Hud must be a top-level child of the root — nesting it inside world
+ * content would compose world offsets into screen coordinates and is a loud
+ * defect. A Hud inside a Hud behaves as a plain group.
+ */
+declare const fields: {
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+};
+type HudData = Schema.Struct<typeof fields>["Type"];
+export declare const Hud: Entity.Entity<"shapes/Hud", Schema.Struct<{
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+}>, {
+    readonly "~position": {
+        get: (data: HudData) => {
+            x: number;
+            y: number;
+            z: number;
+        };
+        set: (data: HudData, value: Entity.Position) => HudData;
+    };
+}>;
+export {};

package/dist/shapes/Hud.js

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Entity from "../Entity.js";
+import * as Shape2D from "./Shape2D.js";
+/**
+ * A screen-space container: its subtree is projected through the IDENTITY
+ * camera instead of the active one, so HUD content ignores camera movement,
+ * zoom, shake — and depth of field (the identity camera's aperture is 0).
+ * HUD content always paints on top of world content.
+ *
+ * `x`/`y` compose into the children in screen coordinates (slide a whole
+ * lower-third in with one tween). There is deliberately no `z`: the
+ * container has no world depth. Children may still use their own `z` for
+ * deliberate in-HUD depth; it defaults to 0 (flat, plain-2D placement).
+ *
+ * A Hud must be a top-level child of the root — nesting it inside world
+ * content would compose world offsets into screen coordinates and is a loud
+ * defect. A Hud inside a Hud behaves as a plain group.
+ */
+const fields = {
+    x: Shape2D.defaultedNumber(0),
+    y: Shape2D.defaultedNumber(0),
+    children: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.sync(() => []))),
+};
+export const Hud = Entity.make("shapes/Hud", fields, {
+    // screen-space position; z is pinned 0 (no world depth on the container)
+    "~position": {
+        get: (data) => ({ x: data.x, y: data.y, z: 0 }),
+        set: (data, value) => ({
+            ...data,
+            x: value.x,
+            y: value.y,
+        }),
+    },
+});

package/dist/shapes/Image.d.ts

@@ -0,0 +1,45 @@
+import * as Schema from "effect/Schema";
+import * as Entity from "../Entity.js";
+/**
+ * A raster/vector image leaf. `image` names an asset declared via the
+ * `Images` annotation; the render session decodes it once and every frame
+ * reuses the decoded picture. An undeclared or failed asset paints nothing
+ * (soft skip — the rest of the frame renders).
+ *
+ * `width`/`height` are optional and undefaulted: set BOTH to draw at that
+ * size (numeric, so they tween); leave both absent to draw at the source's
+ * natural size. A lone dimension is ignored (natural size used) — aspect
+ * math would need the natural size, which frame data never sees.
+ *
+ * Billboard only: no orientation fields. ponytail: tilting an image needs a
+ * projective setTransform (full 3×3, we hardcode the bottom row) mapping the
+ * projected quad; add when a scene needs a tilted image.
+ */
+export declare const Image: Entity.Entity<"shapes/Image", Schema.Struct<{
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    z: Schema.withConstructorDefault<Schema.Number>;
+    opacity: Schema.withConstructorDefault<Schema.Number>;
+    image: Schema.String;
+    width: Schema.optionalKey<Schema.Number>;
+    height: Schema.optionalKey<Schema.Number>;
+}>, {
+    readonly "~position": Entity.TraitLens<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly opacity: number;
+        readonly image: string;
+        readonly width?: number;
+        readonly height?: number;
+    }, Entity.Position>;
+    readonly "~opacity": Entity.TraitLens<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly opacity: number;
+        readonly image: string;
+        readonly width?: number;
+        readonly height?: number;
+    }, number>;
+}>;