@codexo/exojs 0.11.0 → 0.13.0

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@codexo/exojs",
   "description": "A TypeScript-first browser 2D runtime for games and interactive apps.",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
-  "packageManager": "pnpm@11.4.0",
   "files": [
     "dist/esm/",
     "dist/exo.esm.js",
     "dist/exo.esm.js.map",
+    "dist/exo.debug.esm.js",
+    "dist/exo.debug.esm.js.map",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "main": "./dist/exo.esm.js",
   "module": "./dist/esm/index.js",
   "browser": "./dist/exo.esm.js",
   "types": "./dist/esm/index.d.ts",
-  "sideEffects": [
-    "./dist/esm/rendering/sprite/Sprite.js"
-  ],
+  "sideEffects": false,
   "keywords": [
     "2d",
     "browser",
@@ -34,6 +34,16 @@
       "import": "./dist/esm/index.js",
       "default": "./dist/esm/index.js"
     },
+    "./extensions": {
+      "types": "./dist/esm/extensions/index.d.ts",
+      "import": "./dist/esm/extensions/index.js",
+      "default": "./dist/esm/extensions/index.js"
+    },
+    "./rendering": {
+      "types": "./dist/esm/rendering.d.ts",
+      "import": "./dist/esm/rendering.js",
+      "default": "./dist/esm/rendering.js"
+    },
     "./debug": {
       "types": "./dist/esm/debug/index.d.ts",
       "import": "./dist/esm/debug/index.js",
@@ -41,55 +51,14 @@
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "bootstrap": "pnpm install --frozen-lockfile --ignore-scripts",
-    "clean": "rimraf dist",
-    "build": "pnpm clean && tsx node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:production",
-    "build:dev": "pnpm clean && tsx node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:development",
-    "build:watch": "tsx node_modules/rollup/dist/bin/rollup -cw --environment EXOJS_ENV:development",
-    "verify:exports": "tsx ./scripts/verify-exports.ts",
-    "verify:package": "pnpm build && pnpm verify:exports && pnpm pack",
-    "sync:example-capabilities": "tsx ./scripts/sync-example-capabilities.ts",
-    "verify:release": "pnpm typecheck && pnpm lint:strict && pnpm format:check && pnpm test && pnpm verify:package",
-    "release": "tsx ./scripts/release.ts",
-    "release:notes": "tsx ./scripts/generate-release-notes.ts",
-    "prepack": "pnpm build",
-    "typecheck": "tsc --noEmit",
-    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
-    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\"",
-    "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\"",
-    "lint:strict": "eslint --max-warnings=0 \"src/**/*.ts\"",
-    "lint:strict:fast": "eslint --cache --cache-location .cache/eslintcache --max-warnings=0 \"src/**/*.ts\"",
-    "lint:strict:fix": "eslint --fix --max-warnings=0 \"src/**/*.ts\"",
-    "lint:strict:fast:fix": "eslint --cache --cache-location .cache/eslintcache --fix --max-warnings=0 \"src/**/*.ts\"",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "test": "vitest run --project=exojs",
-    "test:coverage": "vitest run --coverage --project=exojs",
-    "test:watch": "vitest --project=exojs",
-    "test:browser": "pnpm run test:browser:webgl && pnpm run test:browser:webgpu && pnpm run test:browser:webgl:firefox && pnpm run test:browser:webgpu:firefox",
-    "test:browser:webgl": "vitest run --project=browser-webgl-chromium",
-    "test:browser:webgl:chromium": "pnpm run test:browser:webgl",
-    "test:browser:webgl:firefox": "vitest run --project=browser-webgl-firefox",
-    "test:browser:webgpu": "vitest run --project=browser-webgpu",
-    "test:browser:webgpu:chromium": "pnpm run test:browser:webgpu",
-    "test:browser:webgpu:firefox": "vitest run --project=browser-webgpu-firefox",
-    "bench": "vitest bench",
-    "bench:run": "vitest bench --run",
-    "site:install": "pnpm bootstrap",
-    "site:build": "pnpm --filter @codexo/exojs-examples build",
-    "site:build:api": "pnpm --filter @codexo/exojs-examples build:api",
-    "test:examples:smoke": "pnpm --filter @codexo/exojs-examples examples:smoke",
-    "perf:bench:rendering": "tsx test/perf/rendering-benchmark.ts",
-    "perf:bench:audio": "tsx test/perf/audio-benchmark.ts",
-    "perf:bench:collision": "tsx test/perf/collision-benchmark.ts",
-    "perf:bench:scene-graph": "tsx test/perf/scene-graph-benchmark.ts",
-    "perf:bench:interaction": "tsx test/perf/interaction-benchmark.ts",
-    "perf:bench:all": "pnpm perf:bench:rendering && pnpm perf:bench:audio && pnpm perf:bench:collision && pnpm perf:bench:scene-graph && pnpm perf:bench:interaction",
-    "perf:profile": "tsx test/perf/profile-benchmark.ts",
-    "perf:profile:gc": "node --expose-gc --import tsx/esm test/perf/profile-benchmark.ts",
-    "prepare": "husky",
-    "commit": "gitmoji -c"
+  "imports": {
+    "#*.vert": "./src/*.vert",
+    "#*.frag": "./src/*.frag",
+    "#*": {
+      "@codexo/source": "./src/*.ts",
+      "types": "./dist/esm/*.d.ts",
+      "default": "./dist/esm/*.js"
+    }
   },
   "license": "MIT",
   "publishConfig": {
@@ -127,7 +96,7 @@
     "jiti": "^2.7.0",
     "jsdom": "^29.1.1",
     "playwright": "^1.50.0",
-    "prettier": "^3.8.3",
+    "prettier": "3.8.3",
     "rimraf": "^6.1.3",
     "rollup": "^4.60.3",
     "rollup-plugin-string": "^3.0.0",
@@ -135,6 +104,72 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.7",
+    "@codexo/exojs-config": "0.0.0"
+  },
+  "scripts": {
+    "bootstrap": "pnpm install --frozen-lockfile --ignore-scripts",
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsx node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:production",
+    "build:dev": "pnpm clean && tsx node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:development",
+    "build:watch": "tsx node_modules/rollup/dist/bin/rollup -cw --environment EXOJS_ENV:development",
+    "verify:exports": "tsx ./scripts/verify-exports.ts",
+    "verify:package-policy": "tsx ./scripts/verify-package-policy.ts",
+    "verify:package": "pnpm build && pnpm verify:exports && pnpm pack",
+    "verify:lockstep": "tsx ./scripts/verify-lockstep-versions.ts",
+    "verify:release-matrix": "tsx ./scripts/verify-release-matrix.ts",
+    "verify:create-exo-app": "tsx ./scripts/verify-create-exo-app.ts",
+    "sync:example-capabilities": "tsx ./scripts/sync-example-capabilities.ts",
+    "verify:release": "pnpm verify:lockstep && pnpm typecheck && pnpm typecheck:guides && pnpm typecheck:examples && pnpm lint:strict && pnpm format:check && pnpm test && pnpm verify:package && pnpm verify:create-exo-app && pnpm site:build",
+    "release": "tsx ./scripts/release.ts",
+    "release:prepare": "tsx ./scripts/release/run.ts prepare",
+    "release:full-zip": "tsx ./scripts/release/run.ts full-zip",
+    "release:publish": "tsx ./scripts/release/run.ts publish",
+    "verify:external-consumers": "tsx ./scripts/release/external-consumers.ts",
+    "release:notes": "tsx ./scripts/generate-release-notes.ts",
+    "docs:api:generate": "pnpm site:build:api",
+    "docs:api:check": "tsx scripts/check-api-docs-sync.ts",
+    "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
+    "typecheck:guides": "tsx scripts/extract-guide-snippets.ts && tsc --noEmit -p tsconfig.guides.json",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\"",
+    "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\"",
+    "lint:packages": "eslint \"packages/exojs-*/src/**/*.ts\" \"packages/exojs-*/test/**/*.ts\"",
+    "lint:all": "pnpm lint && pnpm lint:packages",
+    "lint:strict": "eslint --max-warnings=0 \"src/**/*.ts\"",
+    "lint:strict:fast": "eslint --cache --cache-location .cache/eslintcache --max-warnings=0 \"src/**/*.ts\"",
+    "lint:strict:fix": "eslint --fix --max-warnings=0 \"src/**/*.ts\"",
+    "lint:strict:fast:fix": "eslint --cache --cache-location .cache/eslintcache --fix --max-warnings=0 \"src/**/*.ts\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --project=exojs --project=exojs-particles --project=exojs-tilemap --project=exojs-tiled --project=rendering-perf",
+    "test:core": "vitest run --project=exojs",
+    "test:coverage": "vitest run --coverage --project=exojs --project=exojs-particles --project=exojs-tilemap --project=exojs-tiled --project=rendering-perf",
+    "test:watch": "vitest --project=exojs",
+    "test:browser": "pnpm run test:browser:webgl && pnpm run test:browser:webgpu && pnpm run test:browser:webgl:firefox && pnpm run test:browser:webgpu:firefox",
+    "test:browser:webgl": "vitest run --project=browser-webgl-chromium",
+    "test:browser:webgl:chromium": "pnpm run test:browser:webgl",
+    "test:browser:webgl:firefox": "vitest run --project=browser-webgl-firefox",
+    "test:browser:webgpu": "vitest run --project=browser-webgpu",
+    "test:browser:webgpu:chromium": "pnpm run test:browser:webgpu",
+    "test:browser:webgpu:firefox": "vitest run --project=browser-webgpu-firefox",
+    "bench": "vitest bench",
+    "bench:run": "vitest bench --run",
+    "site:install": "pnpm bootstrap",
+    "site:build": "pnpm --filter @codexo/exojs-examples build",
+    "site:build:api": "pnpm --filter @codexo/exojs-examples build:api",
+    "test:examples:smoke": "pnpm --filter @codexo/exojs-examples examples:smoke",
+    "perf:renderers": "tsx test/perf/rendering/run-sweep.ts full",
+    "perf:renderers:quick": "tsx test/perf/rendering/run-sweep.ts quick",
+    "perf:renderers:browser": "vitest run --project=browser-webgl-chromium webgl2-renderer-perf",
+    "perf:bench:rendering": "tsx test/perf/rendering-benchmark.ts",
+    "perf:bench:audio": "tsx test/perf/audio-benchmark.ts",
+    "perf:bench:collision": "tsx test/perf/collision-benchmark.ts",
+    "perf:bench:scene-graph": "tsx test/perf/scene-graph-benchmark.ts",
+    "perf:bench:interaction": "tsx test/perf/interaction-benchmark.ts",
+    "perf:bench:all": "pnpm perf:bench:rendering && pnpm perf:bench:audio && pnpm perf:bench:collision && pnpm perf:bench:scene-graph && pnpm perf:bench:interaction",
+    "perf:profile": "tsx test/perf/profile-benchmark.ts",
+    "perf:profile:gc": "node --expose-gc --import tsx/esm test/perf/profile-benchmark.ts",
+    "commit": "gitmoji -c"
   }
-}
+}

package/dist/esm/particles/ParticleSystem.d.ts

@@ -1,212 +0,0 @@
-import type { Time } from '@/core/Time';
-import { Rectangle } from '@/math/Rectangle';
-import { Drawable } from '@/rendering/Drawable';
-import type { RenderPlanBuilder } from '@/rendering/plan/RenderPlanBuilder';
-import { Spritesheet } from '@/rendering/sprite/Spritesheet';
-import { Texture } from '@/rendering/texture/Texture';
-import { ParticleGpuState } from './gpu/ParticleGpuState';
-import type { DeathModule } from './modules/DeathModule';
-import type { SpawnModule } from './modules/SpawnModule';
-import type { UpdateModule } from './modules/UpdateModule';
-/**
- * Options for {@link ParticleSystem}'s constructor — orthogonal config
- * that's independent of the texture source. Texture / frames / spritesheet
- * live in positional arguments to enforce mutual exclusivity at the type
- * level (you can't pass both a texture and a spritesheet by accident).
- */
-export interface ParticleSystemOptions {
-    /** Maximum particle count. Fixed at construction. Default 4096. */
-    capacity?: number;
-    /**
-     * Direct GPU device. Lets advanced consumers wire a `GPUDevice` owned
-     * outside an `Application` (or a mock device in tests). When omitted,
-     * the backend reference is captured automatically on the first
-     * {@link ParticleSystem.render} call — `WebGpuBackend` ⇒ GPU mode,
-     * anything else (incl. WebGL2) ⇒ CPU mode.
-     */
-    device?: GPUDevice;
-}
-/**
- * The central coordinator of the particle pipeline. `ParticleSystem` is a
- * {@link Drawable} that owns:
- *
- * - **SoA particle storage** — one typed array per attribute (position,
- *   velocity, scale, rotation, color, lifetime, ...), sized to a fixed
- *   capacity at construction. User code reads/writes via
- *   `system.posX[slot]`, `system.velX[slot]`, etc.
- * - **Spawn modules** — write new particles into freshly allocated slots.
- * - **Update modules** — mutate the live range each frame (forces, color
- *   blends, scale curves, drag, ...). Built-in modules ship both CPU and
- *   WGSL implementations; custom modules can opt into GPU acceleration by
- *   implementing `wgsl()`.
- * - **Death modules** — fire once per dying particle, before its slot is
- *   recycled (sub-emitters, event hooks).
- *
- * **Auto-routing CPU vs GPU:** at first {@link update}, the system checks:
- * if a `WebGpuBackend` was supplied AND every registered update module has
- * `wgsl()`, the GPU path engages — a composite compute pipeline runs
- * integration plus all module bodies in one dispatch and writes directly
- * into the renderer's instance buffer (no CPU readback). Otherwise the CPU
- * path runs the existing per-module `apply()` loops.
- *
- * **Per-frame order in {@link update} (CPU mode):**
- * 1. Run every spawn module.
- * 2. Integrate position from velocity, rotation from rotationSpeed, advance `elapsed`.
- * 3. Run every update module on the live range.
- * 4. Compact: scan `[0, liveCount)` forward, fire death modules on expired
- *    slots, copy survivors down. `liveCount` shrinks to the survivor count.
- *
- * **Per-frame order in {@link update} (GPU mode):**
- * 1. Run every spawn module (CPU writes initial values into the spawn slot).
- * 2. Detect expiries on CPU (via `elapsed >= lifetime`); fire death modules;
- *    set `lifetime[slot] = -1` sentinel + clear `alive[slot]` so the GPU
- *    shader skips them. **No compaction** — slots are recycled on next spawn.
- * 3. Dispatch the composite compute pipeline. Integration + update modules
- *    + pack-instances run in one pass; the instance buffer is written
- *    directly. CPU SoA stays as-is for spawn writes.
- *
- * **Coordinate space:** particle positions are LOCAL to the system. The
- * system's `getGlobalTransform()` is applied on top during rendering — both
- * the WebGL2 and WebGPU shaders multiply `projection * translation * rotated`.
- * Setting world-space positions on individual particles double-translates.
- * Position the system itself via `system.setPosition(...)` and emit relative
- * to `(0, 0)`.
- *
- * @example
- * // Backend-agnostic — runs CPU on WebGL2, GPU on WebGPU automatically.
- * const system = new ParticleSystem(loader.get(Texture, 'spark'), {
- *     capacity: 8192,
- *     backend: app.backend,
- * });
- *
- * system.addSpawnModule(new RateSpawn({ rate: new Constant(60), ... }));
- * system.addUpdateModule(new ApplyForce(0, 980));     // gravity, GPU-eligible
- * system.addUpdateModule(new ColorOverLifetime(fireGradient));
- * scene.addChild(system);
- */
-export declare class ParticleSystem extends Drawable {
-    /** Maximum particle count this system will store. Fixed at construction. */
-    readonly capacity: number;
-    readonly posX: Float32Array;
-    readonly posY: Float32Array;
-    readonly velX: Float32Array;
-    readonly velY: Float32Array;
-    readonly scaleX: Float32Array;
-    readonly scaleY: Float32Array;
-    readonly rotations: Float32Array;
-    readonly rotationSpeeds: Float32Array;
-    readonly color: Uint32Array;
-    readonly elapsed: Float32Array;
-    readonly lifetime: Float32Array;
-    readonly textureIndex: Uint16Array;
-    /**
-     * Number of currently live particles. In CPU mode this is exact: slots
-     * `[0, liveCount)` are all alive after each `update()`. In GPU mode
-     * this is a high-water mark — slots `[0, liveCount)` may contain dead
-     * holes (filled in by future spawns); use {@link aliveCount} for the
-     * actual alive count.
-     */
-    liveCount: number;
-    /**
-     * Per-slot alive flag (1 = alive, 0 = dead). Maintained in both CPU
-     * and GPU mode. Custom modules iterating the live range should check
-     * this to skip dead slots in GPU mode.
-     */
-    readonly alive: Uint8Array;
-    private readonly _spawnModules;
-    private readonly _updateModules;
-    private readonly _deathModules;
-    private _backend;
-    private readonly _device;
-    private _gpuState;
-    private _gpuMode;
-    private _compiled;
-    private _spawnHint;
-    /**
-     * In GPU mode, slots whose CPU SoA values need re-uploading to the GPU
-     * (newly spawned, or just-expired with lifetime sentinel). Cleared
-     * after each compute dispatch. CPU never overwrites integrated GPU
-     * state — only dirty slots flow CPU → GPU.
-     */
-    private readonly _gpuDirtySlots;
-    private _texture;
-    private readonly _frames;
-    private readonly _textureFrame;
-    private readonly _vertices;
-    private readonly _texCoords;
-    private _updateTexCoords;
-    private _updateVertices;
-    /** No texture — particles render as solid-color quads on a 1×1 white default. */
-    constructor(options?: ParticleSystemOptions);
-    /** Single texture, no atlas — every particle uses the full texture as one frame. */
-    constructor(texture: Texture, options?: ParticleSystemOptions);
-    /** Multi-frame atlas — each particle's `textureIndex` selects a frame. */
-    constructor(texture: Texture, frames: readonly Rectangle[], options?: ParticleSystemOptions);
-    /** Spritesheet shorthand — texture + frames pulled from the sheet. */
-    constructor(spritesheet: Spritesheet, options?: ParticleSystemOptions);
-    get texture(): Texture;
-    set texture(texture: Texture);
-    get textureFrame(): Rectangle;
-    set textureFrame(frame: Rectangle);
-    /**
-     * Atlas frames declared on this system, or empty when the texture is
-     * used as a single frame. Each particle's `textureIndex[i]` selects
-     * an entry from this list; out-of-range indices are clamped to 0.
-     */
-    get frames(): readonly Rectangle[];
-    /** `true` when the system declares more than one atlas frame. */
-    get hasAtlas(): boolean;
-    get vertices(): Float32Array;
-    get texCoords(): Uint32Array;
-    /** `true` when the system is running on the GPU compute pipeline. */
-    get gpuMode(): boolean;
-    /** GPU-side state, or `null` in CPU mode. */
-    get gpuState(): ParticleGpuState | null;
-    /** Actual count of live particles (slots with `alive[i] === 1`). May differ from `liveCount` in GPU mode. */
-    get aliveCount(): number;
-    get spawnModules(): readonly SpawnModule[];
-    get updateModules(): readonly UpdateModule[];
-    get deathModules(): readonly DeathModule[];
-    setTexture(texture: Texture): this;
-    setTextureFrame(frame: Rectangle): this;
-    resetTextureFrame(): this;
-    addSpawnModule(mod: SpawnModule): this;
-    addUpdateModule(mod: UpdateModule): this;
-    addDeathModule(mod: DeathModule): this;
-    clearSpawnModules(): this;
-    clearUpdateModules(): this;
-    clearDeathModules(): this;
-    /**
-     * Allocates a particle slot and returns its index. Returns `-1` when
-     * the system is at {@link capacity}.
-     *
-     * **CPU mode:** slots are dense in `[0, liveCount)`. `spawn()` returns
-     * the next sequential slot; `liveCount++`.
-     *
-     * **GPU mode:** slots may have dead holes. `spawn()` finds the first
-     * `alive[i] === 0` slot via a round-robin hint pointer (amortised O(1),
-     * worst case O(capacity) on full systems).
-     */
-    spawn(): number;
-    /** Resets the system to zero live particles without destroying it. */
-    clearParticles(): this;
-    /**
-     * @internal
-     *
-     * Collect-hook: captures the active backend before this node is emitted so
-     * the next `update()` can compile a GPU pipeline if the backend turned out
-     * to be `WebGpuBackend`. Re-captures and rebuilds when the backend
-     * reference changes (e.g. after device-loss recovery).
-     */
-    /** @internal */
-    _collect(builder: RenderPlanBuilder, seq?: number): void;
-    /** Per-frame entry point. Routes to CPU or GPU pipeline based on auto-detection at first call. */
-    update(delta: Time): this;
-    destroy(): void;
-    private _compile;
-    private _spawnCpu;
-    private _spawnGpu;
-    private _updateCpu;
-    private _updateGpu;
-    private _copySlot;
-}