@adobe/ecs 0.1.0 → 0.2.0

package/src/samples/todo/shared/elements/define.ts

@@ -1,7 +0,0 @@
-/** Elements by their tag names, as a feature lists those it creates or finds on the page. */
-export type Elements = { readonly [name: string]: CustomElementConstructor };
-
-/** Defines each of `elements` not defined yet. */
-export const define = (elements: Elements): void => {
-    for (const [name, element] of Object.entries(elements)) if (customElements.get(name) === undefined) customElements.define(name, element);
-};

package/src/samples/todo/shared/elements/elements.test-helper.ts

@@ -1,28 +0,0 @@
-/** What tests of elements share: no world, only the DOM. */
-
-export type Recorded = { readonly type: string; readonly detail: unknown; readonly target: EventTarget | null };
-
-/** Records the events of `types` that reach `target`, in order. */
-export const record = (target: EventTarget, ...types: (keyof HTMLElementEventMap)[]): Recorded[] => {
-    const seen: Recorded[] = [];
-    for (const type of types) target.addEventListener(type, event => seen.push({ type, detail: event instanceof CustomEvent ? event.detail : undefined, target: event.target }));
-    return seen;
-};
-
-/** The part of `host`'s shadow root `selector` finds, of `type`. */
-export const part = <E extends Element>(host: Element, selector: string, type: abstract new () => E): E => {
-    const found = host.shadowRoot?.querySelector(selector);
-    if (!(found instanceof type)) throw new Error(`No ${selector}.`);
-    return found;
-};
-
-/** The mutations `change` makes to `host` and its shadow root. */
-export const mutationsOf = (host: Element, change: () => void): MutationRecord[] => {
-    const observer = new MutationObserver(() => {});
-    observer.observe(host, { attributes: true, childList: true, characterData: true, subtree: true });
-    if (host.shadowRoot !== null) observer.observe(host.shadowRoot, { attributes: true, childList: true, characterData: true, subtree: true });
-    change();
-    const records = observer.takeRecords();
-    observer.disconnect();
-    return records;
-};

package/src/samples/todo/shared/feature.ts

@@ -1,20 +0,0 @@
-import type { System, World } from "../../../index.js";
-import type { Connect } from "./connect.js";
-import type { Elements } from "./elements/define.js";
-
-/** Values resources start at, as a world takes them. */
-export type Resources = Exclude<Parameters<typeof World.create>[0], undefined>;
-
-/**
- * What the app needs of a feature to compose it with the others. Its components, resources, indexes, rules and
- * finalizers register as its modules load, so they aren't listed.
- */
-export type Feature = {
-    /** The elements it creates or finds on the page, by their tag names, which the app defines. */
-    readonly elements: Elements;
-    /** The fixed elements it drives, found within the page's root, as the resources it reads them from. */
-    readonly resources: (root: ParentNode) => Resources;
-    /** Its DOM systems, as one composite added to every tick; null for none. */
-    readonly system: System | null;
-    readonly connect: Connect;
-};

package/src/samples/todo/shared/ticks.test-helper.ts

@@ -1,25 +0,0 @@
-import { System, clock, type World } from "../../../index.js";
-
-const waiting: (() => void)[] = [];
-
-/** Passes after each tick, the only passes that change the clock, and on its first. */
-const ticked = System.create({ name: "test/ticked", observer: true, resources: { changed: [clock] } }, () => {
-    for (const resolve of waiting.splice(0)) resolve();
-});
-
-/** Lets `nextTick` resolve after `world`'s ticks: awaited once, before the world's first run. */
-export const watchTicks = async (world: World): Promise<void> => {
-    world.add(ticked);
-    // Its first pass, which isn't a tick's.
-    await world.run(ticked);
-};
-
-/** Resolves after the next tick's observer systems ran: the DOM shows what the runs before it changed. */
-export const nextTick = (): Promise<void> => new Promise(resolve => waiting.push(resolve));
-
-/** Waits for a run, then for the tick after it. */
-export const settled = async (run: Promise<number>): Promise<number> => {
-    const ran = await run;
-    await nextTick();
-    return ran;
-};

package/src/samples/transfers/build.test.ts

@@ -1,22 +0,0 @@
-/// <reference types="node" />
-import { mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterAll, expect, it } from "vitest";
-import { build, type Rollup } from "vite";
-
-const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
-const outDir = realpathSync(mkdtempSync(join(tmpdir(), "ecs-sample-")));
-afterAll(() => rmSync(outDir, { recursive: true, force: true }));
-
-it("the transfers sample builds as an application, with the world's worker and the loader's", async () => {
-    const output = await build({
-        configFile: join(packageRoot, "vite.sample.config.ts"), root: join(packageRoot, "src/samples/transfers"), logLevel: "silent",
-        build: { outDir, emptyOutDir: true },
-    });
-    const items = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : []);
-    const files = items.map(item => item.fileName);
-    expect(files.some(file => file.includes("world"))).toBe(true);
-    expect(files.some(file => file.includes("loader"))).toBe(true);
-}, 30000);

package/src/samples/transfers/index.html

@@ -1,18 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Transferred Sprites</title>
-    <style>
-        html, body { margin: 0; height: 100%; background: #111; color: #ddd; font: 13px/1.4 system-ui, sans-serif; }
-        canvas { display: block; width: 100%; height: 100%; }
-        #panel { position: fixed; top: 8px; left: 8px; padding: 6px 10px; background: rgb(0 0 0 / 0.7); border-radius: 6px; }
-    </style>
-</head>
-<body>
-    <canvas></canvas>
-    <div id="panel"><div id="stats">Starting…</div></div>
-    <script type="module" src="./main.ts"></script>
-</body>
-</html>

package/src/samples/transfers/loader.ts

@@ -1,42 +0,0 @@
-import { World } from '../../index.js';
-import { addSprite } from './sprites.js';
-
-// The loader, on a worker: it joins the world through the port main sends, then encodes textures as images and decodes
-// them, as it would images it fetched, moving each decoded bitmap to the world's thread in the run that adds its sprite.
-
-/** Textures loaded, one each `interval` milliseconds. */
-const count = 48;
-const interval = 120;
-
-/** An encoded image: a disc of a hue of its own, numbered. */
-const encoded = async (index: number): Promise<Blob> => {
-    const canvas = new OffscreenCanvas(48, 48);
-    const context = canvas.getContext("2d");
-    if (context !== null) {
-        context.fillStyle = `hsl(${(index * 47) % 360} 80% 60%)`;
-        context.beginPath();
-        context.arc(24, 24, 22, 0, Math.PI * 2);
-        context.fill();
-        context.fillStyle = "#000";
-        context.font = "bold 18px system-ui, sans-serif";
-        context.textAlign = "center";
-        context.textBaseline = "middle";
-        context.fillText(String(index + 1), 24, 25);
-    }
-    return canvas.convertToBlob({ type: "image/png" });
-};
-
-const load = async (port: MessagePort): Promise<void> => {
-    const world = World.join(port);
-    for (let index = 0; index < count; index++) {
-        const bitmap = await createImageBitmap(await encoded(index));
-        // Moved, not copied: `bitmap` is detached here once the run is posted.
-        await world.run(addSprite, { bitmap, seed: index * 4 });
-        await new Promise(resolve => setTimeout(resolve, interval));
-    }
-};
-
-self.onmessage = (event: MessageEvent<unknown>) => {
-    const port: unknown = typeof event.data === "object" && event.data !== null ? Reflect.get(event.data, "port") : null;
-    if (port instanceof MessagePort) void load(port);
-};

package/src/samples/transfers/main.ts

@@ -1,46 +0,0 @@
-import { System, World } from '../../index.js';
-import { attachSurface, stats } from './sprites.js';
-
-/**
- * The transfers sample's page. The world runs on a worker, drawing into the canvas this thread moves to it; a loader
- * worker decodes textures and moves each to the world's thread; this thread, where the DOM is, joins the world and
- * shows what it draws.
- */
-
-const overlay = (text: string): void => {
-    const element = document.querySelector("#stats");
-    if (element !== null) element.textContent = text;
-};
-
-let latest = { sprites: 0, frames: 0 };
-// Added on this thread, it runs here after each of the world's frames that changed stats.
-const show = System.create({ name: "transferSprites/show", observer: true, resources: { read: [stats], changed: [stats] } }, ({ resources }) => {
-    const { sprites, frames } = resources[stats];
-    latest = { sprites, frames };
-    overlay(`${sprites} sprites, each a texture the loader decoded and moved to the world's worker · frame ${frames}`);
-});
-
-const start = async (): Promise<void> => {
-    const canvas = document.querySelector("canvas");
-    if (canvas === null) return;
-    if (typeof canvas.transferControlToOffscreen !== "function") return overlay("This browser can't draw into a canvas from a worker.");
-    canvas.width = Math.floor(canvas.clientWidth * devicePixelRatio);
-    canvas.height = Math.floor(canvas.clientHeight * devicePixelRatio);
-    const world = new Worker(new URL("./world.ts", import.meta.url), { type: "module" });
-    const loader = new Worker(new URL("./loader.ts", import.meta.url), { type: "module" });
-    const forMain = new MessageChannel();
-    const forLoader = new MessageChannel();
-    world.postMessage({ ports: [forMain.port1, forLoader.port1] }, [forMain.port1, forLoader.port1]);
-    loader.postMessage({ port: forLoader.port2 }, [forLoader.port2]);
-    const joined = World.join(forMain.port2);
-    // Moved to the world's thread in the run's input: the canvas is drawn there from now on.
-    await joined.run(attachSurface, { canvas: canvas.transferControlToOffscreen() });
-    joined.add(show);
-    /** For automated checks. */
-    Reflect.set(globalThis, "sampleStats", async () => {
-        await joined.run(show);
-        return latest;
-    });
-};
-
-void start();

package/src/samples/transfers/sprites.ts

@@ -1,96 +0,0 @@
-import { Component, Resource, System, Vec2, clock } from '../../index.js';
-
-// The transfers sample's keys and systems, which every thread imports: the world, on a worker, draws sprites into the
-// canvas main moved to it, each with a texture a loader worker decoded and moved to it. Values move through runs whose
-// input holds them; an input field's schema `{ allOf: [] }` takes any value, typed `unknown`, which bodies narrow.
-
-export const texture = Symbol("transferSprites/texture");
-export const position = Symbol("transferSprites/position");
-export const velocity = Symbol("transferSprites/velocity");
-export const surface = Symbol("transferSprites/surface");
-export const stats = Symbol("transferSprites/stats");
-
-declare module '@adobe/ecs' {
-    interface Components {
-        [texture]: { type: ImageBitmap; transfer: true };
-        [position]: { type: Vec2 };
-        [velocity]: { type: Vec2 };
-    }
-    interface Resources {
-        [surface]: { type: OffscreenCanvas | null; transfer: true };
-        [stats]: { type: { readonly sprites: number; readonly frames: number } };
-    }
-}
-
-/** A decoded texture, moved to the world's thread, where sprites are drawn. */
-Component.register(texture, { transfer: true });
-/** In pixels, and pixels per second. */
-Component.register(position, { type: Vec2.schema });
-Component.register(velocity, { type: Vec2.schema });
-/** The canvas main moved to the world's thread. */
-Resource.register(surface, { transfer: true });
-Resource.register(stats, {
-    type: { type: "object", properties: { sprites: { type: "integer" }, frames: { type: "integer" } }, default: { sprites: 0, frames: 0 } },
-});
-
-const any = { allOf: [] } as const;
-
-/** From main: the canvas the world draws into. */
-export const attachSurface = System.create({ name: "transferSprites/attachSurface", input: { type: "object", properties: { canvas: any } }, resources: { write: [surface] } }, ({ input, resources }) => {
-    if (typeof OffscreenCanvas === "function" && input.canvas instanceof OffscreenCanvas) resources[surface] = input.canvas;
-});
-
-/** A deterministic number in [0, 1) for each seed. */
-const random = (seed: number): number => {
-    const value = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b) >>> 0;
-    return (Math.imul(value ^ (value >>> 13), 0xc2b2ae35) >>> 0) / 2 ** 32;
-};
-
-/** From the loader: a sprite with the texture it decoded, somewhere on the canvas, moving. */
-export const addSprite = System.create({
-    name: "transferSprites/addSprite", input: { type: "object", properties: { bitmap: any, seed: { type: "integer" } } }, resources: { read: [surface], write: [stats] },
-}, ({ input, resources, commands }) => {
-    const canvas = resources[surface];
-    if (canvas === null || typeof ImageBitmap !== "function" || !(input.bitmap instanceof ImageBitmap)) return;
-    const angle = random(input.seed) * Math.PI * 2;
-    const speed = 60 + random(input.seed + 1) * 120;
-    commands.spawn([texture, position, velocity])({
-        [texture]: input.bitmap,
-        [position]: [random(input.seed + 2) * (canvas.width - input.bitmap.width), random(input.seed + 3) * (canvas.height - input.bitmap.height)],
-        [velocity]: [Math.cos(angle) * speed, Math.sin(angle) * speed],
-    });
-    resources[stats] = { sprites: resources[stats].sprites + 1, frames: resources[stats].frames };
-});
-
-/** Clears the canvas, once a frame. */
-const clear = System.create({ name: "transferSprites/clear", resources: { read: [surface], write: [stats] } }, ({ resources }) => {
-    const canvas = resources[surface];
-    canvas?.getContext("2d")?.clearRect(0, 0, canvas.width, canvas.height);
-    resources[stats] = { sprites: resources[stats].sprites, frames: resources[stats].frames + 1 };
-});
-
-/** Moves each sprite, bouncing off the canvas's edges. */
-const move = System.create({
-    name: "transferSprites/move", components: { read: [texture], write: [position, velocity] }, resources: { read: [surface, clock] },
-}, (row, { resources }) => {
-    const canvas = resources[surface];
-    if (canvas === null) return;
-    const seconds = resources[clock].delta / 1000;
-    const [x, y] = row[position];
-    let [dx, dy] = row[velocity];
-    const right = canvas.width - row[texture].width;
-    const bottom = canvas.height - row[texture].height;
-    if ((x <= 0 && dx < 0) || (x >= right && dx > 0)) dx = -dx;
-    if ((y <= 0 && dy < 0) || (y >= bottom && dy > 0)) dy = -dy;
-    row[velocity] = [dx, dy];
-    row[position] = [Math.min(Math.max(x + dx * seconds, 0), right), Math.min(Math.max(y + dy * seconds, 0), bottom)];
-});
-
-/** Draws each sprite's texture where it is. */
-const draw = System.create({ name: "transferSprites/draw", components: { read: [texture, position] }, resources: { read: [surface] }, after: [clear, move] }, (row, { resources }) => {
-    const [x, y] = row[position];
-    resources[surface]?.getContext("2d")?.drawImage(row[texture], x, y);
-});
-
-/** Every frame on the world's thread. */
-export const frame = System.create({ name: "transferSprites/frame", systems: [clear, move, draw] });

package/src/samples/transfers/world.ts

@@ -1,11 +0,0 @@
-import { World, always } from '../../index.js';
-import { frame } from './sprites.js';
-
-// The world, on a worker: main and the loader join it through the ports main sends, and it draws every frame.
-
-const world = World.create({ [always]: true });
-world.add(frame);
-self.onmessage = (event: MessageEvent<unknown>) => {
-    const ports: unknown = typeof event.data === "object" && event.data !== null ? Reflect.get(event.data, "ports") : null;
-    if (Array.isArray(ports)) for (const port of ports) if (port instanceof MessagePort) world.share(port);
-};