@adobe/data-gpu 0.9.69

package/src/core/frame-time/frame-time-plugin.ts

@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import type { FrameTime } from "./frame-time.js";
+
+/**
+ * Largest per-frame delta (seconds) the clock reports. A backgrounded tab or
+ * the very first frame would otherwise produce a multi-second `dt` that throws
+ * every time-stepped system off; clamping here means no consumer has to.
+ */
+const MAX_DELTA = 0.1;
+
+/**
+ * Publishes per-frame wall-clock timing as the `frameTime` resource. Declares
+ * its system but does not extend the scheduler — so pure-data consumers (and
+ * their tests) can pull in the `frameTime` resource without dragging in
+ * `requestAnimationFrame`. Composed with a scheduler (via `core`), the system
+ * runs in the first tier (no dependencies), so every later phase — update,
+ * physics, render — reads a `dt`/`elapsed` already advanced for this frame.
+ */
+export const plugin = Database.Plugin.create({
+    resources: {
+        frameTime: {
+            default: { now: 0, dt: 0, elapsed: 0 } satisfies FrameTime as FrameTime,
+            transient: true,
+        },
+    },
+    systems: {
+        _frameTime: {
+            create: db => {
+                let last = 0;
+                return () => {
+                    const now = performance.now();
+                    // first frame (last === 0) reports dt 0 — no work has elapsed yet
+                    const raw = last === 0 ? 0 : (now - last) / 1000;
+                    last = now;
+                    const dt = raw < MAX_DELTA ? raw : MAX_DELTA;
+                    const elapsed = db.store.resources.frameTime.elapsed + dt;
+                    db.store.resources.frameTime = { now, dt, elapsed };
+                };
+            },
+        },
+    },
+});

package/src/core/frame-time/frame-time.ts

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * as FrameTime from "./public.js";
+
+/**
+ * Wall-clock timing for the current frame, published once per frame by
+ * `FrameTime.plugin`. Any system that advances state over time reads this
+ * instead of calling `performance.now()` and tracking its own `lastTime`.
+ */
+export interface FrameTime {
+    /** `performance.now()` (ms) sampled at the start of this frame. */
+    readonly now: number;
+    /**
+     * Seconds since the previous frame, clamped to a sane maximum so a
+     * stalled tab or the first frame can't inject a huge time jump. A solver
+     * that needs a tighter stability bound clamps `dt` further at its own seam.
+     */
+    readonly dt: number;
+    /** Seconds since the plugin started — the running sum of clamped `dt`. */
+    readonly elapsed: number;
+}

package/src/core/frame-time/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { plugin } from "./frame-time-plugin.js";

package/src/graphics/animation/animation-data-plugin.ts

@@ -0,0 +1,119 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { Boolean, F32, Time, True, type Schema } from "@adobe/data/schema";
+import { AnimationTrack } from "../animation/animation-track/animation-track.js";
+
+const animationBase = Database.Plugin.create({
+    components: {
+        animationClipTracks:   { default: [] as AnimationTrack[] },
+        animationClipDuration: Time.schema,
+        animationClipRef:      Entity.schema,
+        animationTargets:      { default: [] as Entity[] },
+        animationTime:         Time.schema,
+        animationSpeed:        { ...F32.schema, default: 1 },
+        animationLoop:         Boolean.schema,
+        animationPlaying:      Boolean.schema,
+        animationObservable:   True.schema,
+    },
+    archetypes: {
+        AnimationClip: ["animationClipTracks", "animationClipDuration"],
+        Animation: [
+            "animationClipRef",
+            "animationTargets",
+            "animationTime",
+            "animationSpeed",
+            "animationLoop",
+            "animationPlaying",
+        ],
+        AnimationObservable: [
+            "animationClipRef",
+            "animationTargets",
+            "animationTime",
+            "animationSpeed",
+            "animationLoop",
+            "animationPlaying",
+            "animationObservable",
+        ],
+    },
+});
+
+type AnimationStore = Database.Plugin.ToStore<typeof animationBase>;
+
+export const animationData = Database.Plugin.create({
+    extends: animationBase,
+    transactions: {
+        insertAnimationClip(t, args: { tracks: AnimationTrack[]; duration: number }): number {
+            return t.archetypes.AnimationClip.insert({
+                animationClipTracks: args.tracks,
+                animationClipDuration: args.duration,
+            });
+        },
+        insertAnimation(
+            t,
+            args: {
+                animationClipRef: number;
+                animationTargets: number[];
+                animationTime?: number;
+                animationSpeed?: number;
+                animationLoop?: boolean;
+                animationPlaying?: boolean;
+                observable?: boolean;
+            },
+        ): number {
+            const values = {
+                animationClipRef: args.animationClipRef,
+                animationTargets: args.animationTargets,
+                animationTime: args.animationTime ?? 0,
+                animationSpeed: args.animationSpeed ?? 1,
+                animationLoop: args.animationLoop ?? false,
+                animationPlaying: args.animationPlaying ?? true,
+            };
+            return args.observable
+                ? t.archetypes.AnimationObservable.insert({ ...values, animationObservable: true })
+                : t.archetypes.Animation.insert(values);
+        },
+        advanceAnimations(t: AnimationStore, args: { dt: number; observable: boolean }) {
+            const componentSchemas = t.componentSchemas as Record<string, Schema>;
+            const arch = args.observable ? t.archetypes.AnimationObservable : t.archetypes.Animation;
+            const ids = arch.columns.id;
+            const clipRefs = arch.columns.animationClipRef;
+            const targetsCol = arch.columns.animationTargets;
+            const times = arch.columns.animationTime;
+            const speeds = arch.columns.animationSpeed;
+            const loops = arch.columns.animationLoop;
+            const playings = arch.columns.animationPlaying;
+            const { dt } = args;
+            const rowCount = arch.rowCount;
+            for (let i = 0; i < rowCount; i++) {
+                if (!playings.get(i)) continue;
+                const playerId = ids.get(i);
+                const clipId = clipRefs.get(i);
+                const clip = t.read(clipId);
+                if (!clip?.animationClipTracks || !clip.animationClipDuration || clip.animationClipDuration <= 0) continue;
+                const speed = speeds.get(i);
+                const loop = loops.get(i);
+                const duration = clip.animationClipDuration;
+                let newTime = times.get(i) + dt * speed;
+                if (loop) {
+                    newTime = ((newTime % duration) + duration) % duration;
+                } else if (newTime >= duration) {
+                    newTime = duration;
+                    t.update(playerId, { animationPlaying: false });
+                } else if (newTime < 0) {
+                    newTime = 0;
+                }
+                t.update(playerId, { animationTime: newTime });
+                const targets = targetsCol.get(i);
+                for (const track of clip.animationClipTracks) {
+                    const target = targets[track.targetIndex];
+                    if (target === undefined || target === 0) continue;
+                    const schema = componentSchemas[track.component];
+                    if (!schema) continue;
+                    const value = AnimationTrack.sample(track, schema, newTime);
+                    t.update(target, { [track.component]: value });
+                }
+            }
+        },
+    },
+});

package/src/graphics/animation/animation-plugin.test.ts

@@ -0,0 +1,161 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Database, type Store } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/math";
+import { animation } from "./animation-plugin.js";
+import type { AnimationTrack } from "./animation-track/animation-track.js";
+
+function scalarTrack(component: string, points: readonly [time: number, value: number][]): AnimationTrack {
+    const times = new Float32Array(points.length);
+    const values = new Float32Array(points.length);
+    for (let i = 0; i < points.length; i++) {
+        times[i] = points[i][0];
+        values[i] = points[i][1];
+    }
+    return { targetIndex: 0, component, times, values, interpolation: "linear" };
+}
+
+function createTestDb() {
+    // The `placeholder` resource exists only to consume entity id 0, which the
+    // animation code treats as a sentinel "no target". In real scenes the
+    // first non-resource entity is never 0 either.
+    return Database.create(Database.Plugin.create({
+        extends: animation,
+        components: {
+            value: F32.schema,
+        },
+        resources: {
+            placeholder: { default: 0 as number },
+        },
+        archetypes: {
+            Target: ["value"],
+        },
+        transactions: {
+            insertTarget(t): number {
+                return t.archetypes.Target.insert({ value: 0 });
+            },
+        },
+    }));
+}
+
+const linearClip = (db: ReturnType<typeof createTestDb>) =>
+    db.transactions.insertAnimationClip({
+        tracks: [scalarTrack("value", [[0, 0], [1, 10]])],
+        duration: 1,
+    });
+
+describe("animation.advanceAnimations", () => {
+    it("advances time and writes the sampled value to the target", () => {
+        const db = createTestDb();
+        const targetId = db.transactions.insertTarget() as number;
+        const clipId = linearClip(db);
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [targetId],
+        });
+
+        db.transactions.advanceAnimations({ dt: 0.25, observable: false });
+
+        // 0.25s into a 1s clip linearly interpolating 0→10 → value = 2.5.
+        expect(db.read(targetId)?.value).toBeCloseTo(2.5, 5);
+    });
+
+    it("loops time within the clip duration", () => {
+        const db = createTestDb();
+        const targetId = db.transactions.insertTarget() as number;
+        const clipId = linearClip(db);
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [targetId],
+            animationLoop: true,
+        });
+
+        db.transactions.advanceAnimations({ dt: 2.25, observable: false });
+
+        // 2.25 % 1 = 0.25 → same sampled value as the first test.
+        expect(db.read(targetId)?.value).toBeCloseTo(2.5, 5);
+    });
+
+    it("stops a non-looping player when it reaches duration", () => {
+        const db = createTestDb();
+        const targetId = db.transactions.insertTarget() as number;
+        const clipId = linearClip(db);
+        const playerId = db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [targetId],
+            animationLoop: false,
+        }) as number;
+
+        db.transactions.advanceAnimations({ dt: 2, observable: false });
+
+        const player = db.read(playerId);
+        expect(player?.animationTime).toBe(1);
+        expect(player?.animationPlaying).toBe(false);
+    });
+
+    it("only touches players whose animationObservable flag matches the args", () => {
+        const db = createTestDb();
+        const observableTarget = db.transactions.insertTarget() as number;
+        const directTarget     = db.transactions.insertTarget() as number;
+        const clipId = linearClip(db);
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [observableTarget],
+            observable: true,
+        });
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [directTarget],
+        });
+
+        // observable: true touches only the flagged player.
+        db.transactions.advanceAnimations({ dt: 0.5, observable: true });
+        expect(db.read(observableTarget)?.value).toBeCloseTo(5, 5);
+        expect(db.read(directTarget)?.value).toBe(0);
+
+        // observable: false touches only the non-flagged player.
+        db.transactions.advanceAnimations({ dt: 0.5, observable: false });
+        expect(db.read(directTarget)?.value).toBeCloseTo(5, 5);
+    });
+
+    it("fires entity observers for the observable path and skips them for the direct path", () => {
+        const db = createTestDb();
+        const observableTarget = db.transactions.insertTarget() as number;
+        const directTarget     = db.transactions.insertTarget() as number;
+        const clipId = linearClip(db);
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [observableTarget],
+            observable: true,
+        });
+        db.transactions.insertAnimation({
+            animationClipRef: clipId,
+            animationTargets: [directTarget],
+        });
+
+        const observableNotifications: number[] = [];
+        const directNotifications: number[] = [];
+        db.observe.entity(observableTarget)(v => { if (v) observableNotifications.push(v.value as number); });
+        db.observe.entity(directTarget)(v => { if (v) directNotifications.push(v.value as number); });
+        // Drop the initial-value notifications.
+        observableNotifications.length = 0;
+        directNotifications.length = 0;
+
+        // Observable path: writes flow through the transaction → observers fire.
+        db.transactions.advanceAnimations({ dt: 0.5, observable: true });
+        expect(observableNotifications.length).toBeGreaterThan(0);
+        expect(directNotifications.length).toBe(0);
+
+        // Direct path: same `advanceAnimations` body, but with the raw store
+        // as `t`. Underlying value changes; observers must stay silent.
+        // (`db.store` is exposed at runtime but not on the public Database
+        // type — systems get a `Database & { store }` view; tests reach in.)
+        const directStore = (db as unknown as { store: Store<any, any, any> }).store;
+        const before = db.read(directTarget)?.value;
+        animation.transactions.advanceAnimations(directStore, { dt: 0.5, observable: false });
+        const after = db.read(directTarget)?.value;
+        expect(after).not.toBe(before);
+        expect(directNotifications.length).toBe(0);
+    });
+});

package/src/graphics/animation/animation-plugin.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { FrameTime } from "../../core/frame-time/frame-time.js";
+import { animationData } from "./animation-data-plugin.js";
+
+/**
+ * Full animation plugin — declarative data (from `scene/animation-plugin.ts`)
+ * plus the per-frame `animationSampleSystem` that advances all playing entities.
+ *
+ * Exported as `animation` from index.ts. The data-only part lives in
+ * `scene/animation-plugin.ts` and is included in the `scene` aggregator.
+ */
+export const animation = Database.Plugin.create({
+    extends: Database.Plugin.combine(animationData, FrameTime.plugin),
+    systems: {
+        animationSampleSystem: {
+            create: db => () => {
+                const dt = db.store.resources.frameTime.dt;
+                if (dt <= 0) return;
+                db.transactions.advanceAnimations({ dt, observable: true });
+                animationData.transactions.advanceAnimations(db.store, { dt, observable: false });
+            },
+        },
+    },
+});

package/src/graphics/animation/animation-track/animation-track.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { InterpolationMode } from "../interpolation-mode/interpolation-mode.js";
+
+export interface AnimationTrack {
+    /** Index into the AnimationPlayer's animationTargets array. */
+    readonly targetIndex: number;
+    /** Component name to write on the resolved target entity. */
+    readonly component: string;
+    /** Sorted keyframe timestamps. */
+    readonly times: Float32Array;
+    /** Packed keyframe values (componentsPerKey * times.length entries). */
+    readonly values: Float32Array;
+    readonly interpolation: InterpolationMode;
+}
+
+export * as AnimationTrack from "./public.js";

package/src/graphics/animation/animation-track/componentwise-lerp.ts

@@ -0,0 +1,24 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Schema } from "@adobe/data/schema";
+
+/**
+ * Default linear interpolation when a schema does not declare its own
+ * `interpolators.linear`. Walks the schema once and lerps numeric leaves.
+ * Supports `type: "number"` scalars and `type: "array"` of numbers.
+ */
+export function componentwiseLerp(schema: Schema, prev: any, next: any, t: number): any {
+    if (schema.type === "number") {
+        return prev + (next - prev) * t;
+    }
+    if (schema.type === "array") {
+        const n = prev.length;
+        const out = new Array(n);
+        const itemSchema = schema.items ?? { type: "number" };
+        for (let i = 0; i < n; i++) {
+            out[i] = componentwiseLerp(itemSchema, prev[i], next[i], t);
+        }
+        return out;
+    }
+    throw new Error(`componentwiseLerp: no default interpolator for schema type "${schema.type}"`);
+}

package/src/graphics/animation/animation-track/interpolate.ts

@@ -0,0 +1,24 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Schema } from "@adobe/data/schema";
+import type { InterpolationMode } from "../interpolation-mode/interpolation-mode.js";
+import { componentwiseLerp } from "./componentwise-lerp.js";
+
+/**
+ * Dispatches to a schema-declared interpolator if present, otherwise falls
+ * back to a sensible default: `step` returns `next`, `linear` walks the schema
+ * and lerps numeric leaves. `cubicSpline` requires a schema override.
+ */
+export function interpolate(
+    schema: Schema,
+    mode: InterpolationMode,
+    prev: any,
+    next: any,
+    t: number,
+): any {
+    const custom = schema.interpolators?.[mode];
+    if (custom) return custom(prev, next, t);
+    if (mode === "step") return prev;
+    if (mode === "linear") return componentwiseLerp(schema, prev, next, t);
+    throw new Error(`interpolate: schema type "${schema.type}" has no "${mode}" interpolator`);
+}

package/src/graphics/animation/animation-track/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { sample } from "./sample.js";

package/src/graphics/animation/animation-track/sample.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Schema } from "@adobe/data/schema";
+import type { AnimationTrack } from "./animation-track.js";
+import { interpolate } from "./interpolate.js";
+
+/**
+ * Samples a track at `time` and returns the interpolated component value.
+ * `time` must already be wrapped into the clip's [0, duration] range by the caller.
+ */
+export function sample(track: AnimationTrack, schema: Schema, time: number): number | number[] {
+    const { times, values } = track;
+    const keyCount = times.length;
+    const stride = values.length / keyCount;
+
+    if (keyCount === 1 || time <= times[0]) {
+        return readKey(values, 0, stride);
+    }
+    const last = keyCount - 1;
+    if (time >= times[last]) {
+        return readKey(values, last, stride);
+    }
+
+    let lo = 0;
+    let hi = last;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (times[mid] <= time) lo = mid;
+        else hi = mid;
+    }
+
+    const tPrev = times[lo];
+    const tNext = times[hi];
+    const span = tNext - tPrev;
+    const t = span > 0 ? (time - tPrev) / span : 0;
+
+    const prev = readKey(values, lo, stride);
+    const next = readKey(values, hi, stride);
+    return interpolate(schema, track.interpolation, prev, next, t);
+}
+
+function readKey(values: Float32Array, index: number, stride: number): number | number[] {
+    if (stride === 1) return values[index];
+    const out = new Array<number>(stride);
+    const base = index * stride;
+    for (let i = 0; i < stride; i++) out[i] = values[base + i];
+    return out;
+}

package/src/graphics/animation/interpolation-mode/interpolation-mode.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+export type InterpolationMode = Schema.ToType<typeof schema>;
+
+export * as InterpolationMode from "./public.js";

package/src/graphics/animation/interpolation-mode/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { schema } from "./schema.js";

package/src/graphics/animation/interpolation-mode/schema.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+
+export const schema = { type: "string", enum: ["linear", "step", "cubicSpline"] } as const satisfies Schema;

package/src/graphics/camera/camera-plugin.ts

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { graphics } from "../graphics-plugin.js";
+import { Camera } from "./camera.js";
+
+export const plugin = Database.Plugin.create({
+    extends: graphics,
+    resources: {
+        camera: {
+            default: {
+                aspect: 16 / 9,
+                fieldOfView: Math.PI / 4,
+                nearPlane: 0.1,
+                farPlane: 100.0,
+                position: [0, 0, 10],
+                target: [0, 0, 0],
+                up: [0, 1, 0],
+                orthographic: 0,
+            } satisfies Camera as Camera,
+        },
+    },
+    systems: {
+        updateCameraAspect: {
+            create: db => () => {
+                const { canvas } = db.store.resources;
+                let { camera: cam } = db.store.resources;
+                if (!canvas || !cam) return;
+                const aspect = canvas.width / canvas.height;
+                if (cam.aspect !== aspect) {
+                    db.store.resources.camera = { ...cam, aspect };
+                }
+            },
+            schedule: { during: ["preRender"] }
+        },
+    },
+});

package/src/graphics/camera/camera.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+export type Camera = Schema.ToType<typeof schema>;
+
+export * as Camera from "./public.js";

package/src/graphics/camera/orbit/attach-orbit-drag.ts

@@ -0,0 +1,62 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Minimal service interface required by attachOrbitDrag — just the two
+ * orbit transactions it calls. Any service that combines Orbit.plugin
+ * satisfies this.
+ */
+export interface OrbitDragService {
+    transactions: {
+        addOrbitAngle(delta: number): void;
+        resumeAutoSpin(): void;
+    };
+}
+
+/**
+ * Attaches pointer-drag listeners to `element` that drive orbit rotation.
+ * Returns a dispose function to remove the listeners.
+ *
+ * Framework-agnostic — pass the returned dispose to whatever cleanup
+ * mechanism your framework provides (useEffect return, onUnmount, etc.).
+ *
+ * @example
+ * // Vanilla JS
+ * const dispose = attachOrbitDrag(canvas, service);
+ * // later:
+ * dispose();
+ *
+ * @example
+ * // Lit (inside render())
+ * useEffect(() => attachOrbitDrag(canvas, service), [canvas, service]);
+ */
+export function attachOrbitDrag(
+    element: HTMLElement,
+    service: OrbitDragService,
+    options?: { sensitivity?: number },
+): () => void {
+    const sensitivity = options?.sensitivity ?? 0.01;
+    let lastX = 0;
+
+    const onDown = (e: PointerEvent) => {
+        lastX = e.clientX;
+        element.setPointerCapture(e.pointerId);
+    };
+    const onMove = (e: PointerEvent) => {
+        if (!e.buttons) return;
+        service.transactions.addOrbitAngle((lastX - e.clientX) * sensitivity);
+        lastX = e.clientX;
+    };
+    const onUp = () => service.transactions.resumeAutoSpin();
+
+    element.addEventListener("pointerdown",   onDown);
+    element.addEventListener("pointermove",   onMove);
+    element.addEventListener("pointerup",     onUp);
+    element.addEventListener("pointercancel", onUp);
+
+    return () => {
+        element.removeEventListener("pointerdown",   onDown);
+        element.removeEventListener("pointermove",   onMove);
+        element.removeEventListener("pointerup",     onUp);
+        element.removeEventListener("pointercancel", onUp);
+    };
+}