v0.15 — physics dynamics, fixed-timestep, React/Aseprite/LDtk, docs-site polish

.github/workflows/_ci-checks.yml

@@ -108,7 +108,7 @@ jobs:
       # Root `pnpm typecheck` only covers src/**; the extension packages own a
       # separate tsconfig each, so typecheck them explicitly.
       - name: Typecheck extension packages
-        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" typecheck
+        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" --filter "@codexo/exojs-aseprite" --filter "@codexo/exojs-ldtk" --filter "@codexo/exojs-react" typecheck
 
   lint:
     name: Lint
@@ -368,11 +368,14 @@ jobs:
       - name: Build core
         run: pnpm build
 
+      - name: Check bundle sizes
+        run: pnpm size
+
       # The extension packages each have their own rollup build; pnpm runs them
       # in workspace-dependency order (tilemap before tiled). A broken package
       # build is now caught here instead of only at release time.
       - name: Build extension packages
-        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" build
+        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" --filter "@codexo/exojs-aseprite" --filter "@codexo/exojs-ldtk" --filter "@codexo/exojs-react" build
 
       - name: Verify core package exports
         run: pnpm verify:exports
@@ -392,7 +395,7 @@ jobs:
       # Pack each extension package (dry run) so a broken `files`/`exports` set in
       # a package manifest is caught here, not at release time.
       - name: Extension package dry runs
-        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" pack --dry-run
+        run: pnpm --filter "@codexo/exojs-particles" --filter "@codexo/exojs-tilemap" --filter "@codexo/exojs-tiled" --filter "@codexo/exojs-physics" --filter "@codexo/exojs-audio-fx" --filter "@codexo/exojs-aseprite" --filter "@codexo/exojs-ldtk" --filter "@codexo/exojs-react" pack --dry-run
 
       # publint validates the published package.json itself (exports map, files,
       # types resolution, module/main coherence) — the layer attw does NOT cover

.github/workflows/release.yml

@@ -102,6 +102,9 @@ jobs:
           pnpm --filter @codexo/exojs-tiled build
           pnpm --filter @codexo/exojs-physics build
           pnpm --filter @codexo/exojs-audio-fx build
+          pnpm --filter @codexo/exojs-aseprite build
+          pnpm --filter @codexo/exojs-ldtk build
+          pnpm --filter @codexo/exojs-react build
           pnpm site:build
 
       # The site build can regenerate tracked content with platform-dependent

.gitignore

@@ -36,6 +36,7 @@ codexo-bg-*
 !.gitmojirc.json
 !.prettierignore
 !.prettierrc
+!.size-limit.cjs
 
 # Allowlist tracked dot-directories. The directory itself plus all
 # non-dotfile contents (workflow YAMLs, husky hooks, etc.). Dotfiles

.size-limit.cjs

@@ -0,0 +1,14 @@
+module.exports = [
+  {
+    path: 'dist/exo.esm.js',
+    limit: '700 KB',
+    gzip: true,
+  },
+  {
+    path: 'dist/exo.iife.min.js',
+    limit: '250 KB',
+    gzip: true,
+  },
+  // The full bundle (dist/exo.full.iife.min.js) is opt-in (EXOJS_FULL_BUNDLE=1)
+  // and not produced by the default build, so it is not size-gated here.
+];

eslint.config.ts

@@ -492,11 +492,11 @@ export default defineConfig([
   // policy. Excludes create-exo-app (standalone scaffolding CLI, no ESLint
   // integration).
   {
-    files: ['packages/exojs-*/test/**/*.ts'],
+    files: ['packages/exojs-*/test/**/*.{ts,tsx}'],
     ...tseslint.configs.disableTypeChecked,
   },
   {
-    files: ['packages/exojs-*/test/**/*.ts'],
+    files: ['packages/exojs-*/test/**/*.{ts,tsx}'],
     languageOptions: {
       ecmaVersion: 'latest',
       sourceType: 'module',
@@ -554,7 +554,7 @@ export default defineConfig([
   // Site React components. Astro files are type-checked by `astro check`; this
   // block covers the TypeScript/TSX islands that ship browser interactivity.
   {
-    files: ['site/src/**/*.{ts,tsx}'],
+    files: ['site/src/**/*.{ts,tsx}', 'packages/exojs-react/src/**/*.{ts,tsx}'],
     languageOptions: {
       ecmaVersion: 'latest',
       sourceType: 'module',
@@ -655,6 +655,30 @@ export default defineConfig([
     },
   },
 
+  // The React integration package holds an imperative ExoJS `Application` handle
+  // in `useState` and mutates it by design (resize / clearColor / sizingMode),
+  // which the immutability rule cannot model. `@eslint-react/exhaustive-deps`
+  // duplicates `react-hooks/exhaustive-deps`; keep the latter as the single
+  // source so the in-code disables apply once.
+  {
+    files: ['packages/exojs-react/src/**/*.{ts,tsx}'],
+    rules: {
+      'react-hooks/immutability': 'off',
+      '@eslint-react/exhaustive-deps': 'off',
+      // Creating the imperative Application/Scene in an effect and exposing it
+      // as state is the defining pattern of this bridge, not a bug.
+      'react-hooks/set-state-in-effect': 'off',
+      '@eslint-react/set-state-in-effect': 'off',
+      // Targets React 18; `<Context.Provider>` / `useContext` are correct there
+      // (the `use()` and bare-`<Context>` forms are React 19+).
+      '@eslint-react/no-context-provider': 'off',
+      '@eslint-react/no-use-context': 'off',
+      // Reading declarative `<Scene>` config via Children.forEach is the
+      // intended pattern (mirrors react-three-fiber / react-router).
+      '@eslint-react/no-children-for-each': 'off',
+    },
+  },
+
   // ---------------------------------------------------------------------------
   // Per-subsystem overrides for src/. Scoped narrowly because these directories
   // either have hot-path lifecycle invariants, browser-API variance, or typed-
@@ -1067,7 +1091,7 @@ export default defineConfig([
   // structural test config above; covers both root and package test suites.
   {
     ...vitest.configs.recommended,
-    files: ['test/**/*.ts', 'packages/exojs-*/test/**/*.ts'],
+    files: ['test/**/*.ts', 'packages/exojs-*/test/**/*.{ts,tsx}'],
     rules: {
       ...vitest.configs.recommended.rules,
       // Primary value: block an accidentally committed `.only`.

examples/debug-layer/performance-overlay.js

@@ -1,5 +1,5 @@
 // Auto-generated from performance-overlay.ts — edit the .ts source, not this file.
-import { Application, Color, Keyboard, Scene, Sprite, Texture } from '@codexo/exojs';
+import { Application, Color, Container, Keyboard, Scene, Sprite, Texture } from '@codexo/exojs';
 import { DebugOverlay } from '@codexo/exojs/debug';
 const app = new Application({
     canvas: {
@@ -17,14 +17,21 @@ const debug = new DebugOverlay(app);
 debug.layers.performance.visible = true;
 class PerformanceOverlayScene extends Scene {
     sprites;
+    layer;
     async load(loader) {
         await loader.load(Texture, { bunny: 'image/ship-a.png' });
     }
     init(loader) {
         const { width, height } = this.app.canvas;
+        // All sprites share one texture, so adding them to a single container and
+        // rendering it once lets the renderer batch them into a single draw call.
+        // Rendering each sprite with its own `context.render(sprite)` call would
+        // instead emit one draw call per sprite and tank the frame rate.
+        this.layer = new Container();
         this.sprites = Array.from({ length: 1600 }, () => {
             const sprite = new Sprite(loader.get(Texture, 'bunny')).setAnchor(0.5).setScale(0.25);
             sprite.setPosition(Math.random() * width, Math.random() * height);
+            this.layer.addChild(sprite);
             return {
                 sprite,
                 vx: (Math.random() - 0.5) * 120,
@@ -47,8 +54,7 @@ class PerformanceOverlayScene extends Scene {
     }
     draw(context) {
         context.backend.clear();
-        for (const { sprite } of this.sprites)
-            context.render(sprite);
+        context.render(this.layer);
     }
 }
 app.start(new PerformanceOverlayScene());

examples/debug-layer/performance-overlay.ts

@@ -1,4 +1,4 @@
-import { Application, Color, Keyboard, Scene, Sprite, Texture } from '@codexo/exojs';
+import { Application, Color, Container, Keyboard, Scene, Sprite, Texture } from '@codexo/exojs';
 import { DebugOverlay } from '@codexo/exojs/debug';
 
 const app = new Application({
@@ -19,6 +19,7 @@ debug.layers.performance.visible = true;
 
 class PerformanceOverlayScene extends Scene {
     private sprites!: { sprite: Sprite; vx: number; vy: number }[];
+    private layer!: Container;
 
     override async load(loader): Promise<void> {
         await loader.load(Texture, { bunny: 'image/ship-a.png' });
@@ -27,9 +28,15 @@ class PerformanceOverlayScene extends Scene {
     override init(loader): void {
         const { width, height } = this.app.canvas;
 
+        // All sprites share one texture, so adding them to a single container and
+        // rendering it once lets the renderer batch them into a single draw call.
+        // Rendering each sprite with its own `context.render(sprite)` call would
+        // instead emit one draw call per sprite and tank the frame rate.
+        this.layer = new Container();
         this.sprites = Array.from({ length: 1600 }, () => {
             const sprite = new Sprite(loader.get(Texture, 'bunny')).setAnchor(0.5).setScale(0.25);
             sprite.setPosition(Math.random() * width, Math.random() * height);
+            this.layer.addChild(sprite);
             return {
                 sprite,
                 vx: (Math.random() - 0.5) * 120,
@@ -53,7 +60,7 @@ class PerformanceOverlayScene extends Scene {
 
     override draw(context): void {
         context.backend.clear();
-        for (const { sprite } of this.sprites) context.render(sprite);
+        context.render(this.layer);
     }
 }
 

examples/sprites-textures/blendmodes.js

@@ -20,8 +20,20 @@ const BLEND_MODES = [
     { mode: BlendModes.Subtract, name: 'Subtract' },
     { mode: BlendModes.Multiply, name: 'Multiply' },
     { mode: BlendModes.Screen, name: 'Screen' },
+    // Advanced (backdrop-aware) modes — correct coverage, work with alpha.
     { mode: BlendModes.Darken, name: 'Darken' },
     { mode: BlendModes.Lighten, name: 'Lighten' },
+    { mode: BlendModes.Overlay, name: 'Overlay' },
+    { mode: BlendModes.ColorDodge, name: 'Color Dodge' },
+    { mode: BlendModes.ColorBurn, name: 'Color Burn' },
+    { mode: BlendModes.HardLight, name: 'Hard Light' },
+    { mode: BlendModes.SoftLight, name: 'Soft Light' },
+    { mode: BlendModes.Difference, name: 'Difference' },
+    { mode: BlendModes.Exclusion, name: 'Exclusion' },
+    { mode: BlendModes.Hue, name: 'Hue' },
+    { mode: BlendModes.Saturation, name: 'Saturation' },
+    { mode: BlendModes.Color, name: 'Color' },
+    { mode: BlendModes.Luminosity, name: 'Luminosity' },
 ];
 class BlendmodesScene extends Scene {
     background;

examples/sprites-textures/blendmodes.ts

@@ -22,8 +22,20 @@ const BLEND_MODES: Array<{ mode: BlendModes; name: string }> = [
     { mode: BlendModes.Subtract, name: 'Subtract' },
     { mode: BlendModes.Multiply, name: 'Multiply' },
     { mode: BlendModes.Screen, name: 'Screen' },
+    // Advanced (backdrop-aware) modes — correct coverage, work with alpha.
     { mode: BlendModes.Darken, name: 'Darken' },
     { mode: BlendModes.Lighten, name: 'Lighten' },
+    { mode: BlendModes.Overlay, name: 'Overlay' },
+    { mode: BlendModes.ColorDodge, name: 'Color Dodge' },
+    { mode: BlendModes.ColorBurn, name: 'Color Burn' },
+    { mode: BlendModes.HardLight, name: 'Hard Light' },
+    { mode: BlendModes.SoftLight, name: 'Soft Light' },
+    { mode: BlendModes.Difference, name: 'Difference' },
+    { mode: BlendModes.Exclusion, name: 'Exclusion' },
+    { mode: BlendModes.Hue, name: 'Hue' },
+    { mode: BlendModes.Saturation, name: 'Saturation' },
+    { mode: BlendModes.Color, name: 'Color' },
+    { mode: BlendModes.Luminosity, name: 'Luminosity' },
 ];
 
 class BlendmodesScene extends Scene {

package.json

@@ -10,6 +10,10 @@
     "dist/exo.esm.js.map",
     "dist/exo.debug.esm.js",
     "dist/exo.debug.esm.js.map",
+    "dist/exo.iife.js",
+    "dist/exo.iife.js.map",
+    "dist/exo.iife.min.js",
+    "dist/exo.iife.min.js.map",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -75,6 +79,7 @@
     "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",
+    "create:package": "tsx scripts/create-package.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",
     "verify:quick": "pnpm typecheck && pnpm typecheck:guides && pnpm typecheck:examples && pnpm typecheck:packages && pnpm lint:all && pnpm format:check && pnpm docs:api:check",
     "verify:ci": "pnpm verify:quick && pnpm test",
@@ -90,11 +95,11 @@
     "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",
-    "typecheck:packages": "pnpm --filter \"@codexo/exojs-particles\" --filter \"@codexo/exojs-tilemap\" --filter \"@codexo/exojs-tiled\" --filter \"@codexo/exojs-physics\" --filter \"@codexo/exojs-audio-fx\" typecheck",
+    "typecheck:packages": "pnpm --filter \"@codexo/exojs-particles\" --filter \"@codexo/exojs-tilemap\" --filter \"@codexo/exojs-tiled\" --filter \"@codexo/exojs-physics\" --filter \"@codexo/exojs-audio-fx\" --filter \"@codexo/exojs-aseprite\" --filter \"@codexo/exojs-ldtk\" --filter \"@codexo/exojs-react\" typecheck",
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\" \"site/src/**/*.{ts,tsx}\"",
     "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.js\" \"site/src/**/*.{ts,tsx}\"",
     "site:lint": "eslint \"site/src/**/*.{ts,tsx}\"",
-    "lint:packages": "eslint \"packages/exojs-*/src/**/*.ts\" \"packages/exojs-*/test/**/*.ts\"",
+    "lint:packages": "eslint \"packages/exojs-*/src/**/*.{ts,tsx}\" \"packages/exojs-*/test/**/*.{ts,tsx}\"",
     "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\"",
@@ -131,6 +136,7 @@
     "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",
+    "size": "size-limit",
     "prepare": "husky",
     "commit": "gitmoji -c"
   },
@@ -154,6 +160,9 @@
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.3.0",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/css-font-loading-module": "0.0.14",
     "@types/jsdom": "^28.0.1",
     "@types/node": "^25.6.0",
@@ -179,6 +188,7 @@
     "rimraf": "^6.1.3",
     "rollup": "^4.60.3",
     "rollup-plugin-string": "^3.0.0",
+    "size-limit": "^11.2.0",
     "tslib": "^2.8.1",
     "tsx": "^4.21.0",
     "typescript": "~6.0.3",

packages/exojs-aseprite/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.