feat(resources)!: asset-access redesign — Asset.kind, kind discriminator, idle/awaitBackground, Assets.one/group + lifecycle merge

examples/application-scenes/camera-basic.js

@@ -1,5 +1,5 @@
 // Auto-generated from camera-basic.ts — edit the .ts source, not this file.
-import { Application, Color, Graphics, Scene, Sprite, Texture } from '@codexo/exojs';
+import { Application, Color, Graphics, Scene, Sprite } from '@codexo/exojs';
 const app = new Application({
     canvas: {
         width: 1280,
@@ -17,11 +17,9 @@ class CameraBasicScene extends Scene {
     grid;
     uiBar;
     zoom = 1;
-    async load(loader) {
-        this.bunny = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
     init() {
         const { width, height } = this.app.canvas;
+        this.bunny = new Sprite(this.loader.get('image/ship-a.png'));
         this.bunny.setAnchor(0.5).setPosition(width / 2, height / 2);
         this.grid = new Graphics();
         this.grid.lineWidth = 1;

examples/application-scenes/camera-basic.ts

@@ -1,4 +1,4 @@
-import { Application, Color, Graphics, Scene, Sprite, Texture } from '@codexo/exojs';
+import { Application, Color, Graphics, Scene, Sprite } from '@codexo/exojs';
 
 const app = new Application({
     canvas: {
@@ -19,13 +19,10 @@ class CameraBasicScene extends Scene {
     private uiBar!: Graphics;
     private zoom = 1;
 
-    override async load(loader): Promise<void> {
-        this.bunny = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
-
     override init(): void {
         const { width, height } = this.app.canvas;
 
+        this.bunny = new Sprite(this.loader.get('image/ship-a.png'));
         this.bunny.setAnchor(0.5).setPosition(width / 2, height / 2);
 
         this.grid = new Graphics();

examples/application-scenes/multi-view-split-screen.js

@@ -1,5 +1,5 @@
 // Auto-generated from multi-view-split-screen.ts — edit the .ts source, not this file.
-import { Application, Color, Graphics, Keyboard, Scene, Sprite, Texture, View } from '@codexo/exojs';
+import { Application, Color, Graphics, Keyboard, Scene, Sprite, View } from '@codexo/exojs';
 const app = new Application({
     canvas: {
         width: 1280,
@@ -29,11 +29,9 @@ class SplitScreenScene extends Scene {
         up: 0,
         down: 0,
     };
-    async load(loader) {
-        this.texture = await loader.load(Texture, 'image/ship-a.png');
-    }
     init() {
         const { width, height } = this.app.canvas;
+        this.texture = this.loader.get('image/ship-a.png');
         this.leftView = new View(0, 0, width / 2, height).setViewport(0, 0, 0.5, 1);
         this.rightView = new View(0, 0, width / 2, height).setViewport(0.5, 0, 0.5, 1);
         this.divider = new Graphics();

examples/application-scenes/multi-view-split-screen.ts

@@ -31,13 +31,11 @@ class SplitScreenScene extends Scene {
         down: 0,
     };
 
-    override async load(loader): Promise<void> {
-        this.texture = await loader.load(Texture, 'image/ship-a.png');
-    }
-
     override init(): void {
         const { width, height } = this.app.canvas;
 
+        this.texture = this.loader.get('image/ship-a.png');
+
         this.leftView = new View(0, 0, width / 2, height).setViewport(0, 0, 0.5, 1);
         this.rightView = new View(0, 0, width / 2, height).setViewport(0.5, 0, 0.5, 1);
 

examples/application-scenes/pause-and-resume.js

@@ -1,5 +1,5 @@
 // Auto-generated from pause-and-resume.ts — edit the .ts source, not this file.
-import { Application, Color, Keyboard, Scene, Sprite, Text, Texture } from '@codexo/exojs';
+import { Application, Color, Keyboard, Scene, Sprite, Text } from '@codexo/exojs';
 const app = new Application({
     canvas: {
         width: 1280,
@@ -15,11 +15,9 @@ const app = new Application({
 class PauseResumeScene extends Scene {
     sprite;
     label;
-    async load(loader) {
-        this.sprite = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
     init() {
         const { width, height } = this.app.canvas;
+        this.sprite = new Sprite(this.loader.get('image/ship-a.png'));
         this.sprite.setAnchor(0.5);
         this.sprite.setPosition(width / 2, height / 2);
         this.label = new Text('Space or click: pause update', { fillColor: Color.white, fontSize: 16 });

examples/application-scenes/pause-and-resume.ts

@@ -1,4 +1,4 @@
-import { Application, Color, Keyboard, Scene, Sprite, Text, Texture } from '@codexo/exojs';
+import { Application, Color, Keyboard, Scene, Sprite, Text } from '@codexo/exojs';
 
 const app = new Application({
     canvas: {
@@ -17,13 +17,10 @@ class PauseResumeScene extends Scene {
     private sprite!: Sprite;
     private label!: Text;
 
-    override async load(loader): Promise<void> {
-        this.sprite = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
-
     override init(): void {
         const { width, height } = this.app.canvas;
 
+        this.sprite = new Sprite(this.loader.get('image/ship-a.png'));
         this.sprite.setAnchor(0.5);
         this.sprite.setPosition(width / 2, height / 2);
 

examples/application-scenes/picture-in-picture.js

@@ -1,5 +1,5 @@
 // Auto-generated from picture-in-picture.ts — edit the .ts source, not this file.
-import { Application, Color, Graphics, Scene, Sprite, Texture, View } from '@codexo/exojs';
+import { Application, Color, Graphics, Scene, Sprite, View } from '@codexo/exojs';
 const app = new Application({
     canvas: {
         width: 1280,
@@ -18,11 +18,9 @@ class PictureInPictureScene extends Scene {
     sprite;
     velocity = 220;
     frame;
-    async load(loader) {
-        this.sprite = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
     init() {
         const { width, height } = this.app.canvas;
+        this.sprite = new Sprite(this.loader.get('image/ship-a.png'));
         this.mainView = new View(0, 0, width, height);
         this.pipView = new View(0, 0, width * 0.3, height * 0.3).setViewport(0.68, 0.04, 0.28, 0.28);
         // Zoom < 1 zooms OUT (a larger visible world area maps into the same

examples/application-scenes/picture-in-picture.ts

@@ -1,4 +1,4 @@
-import { Application, Color, Graphics, Scene, Sprite, Texture, View } from '@codexo/exojs';
+import { Application, Color, Graphics, Scene, Sprite, View } from '@codexo/exojs';
 
 const app = new Application({
     canvas: {
@@ -20,13 +20,11 @@ class PictureInPictureScene extends Scene {
     private velocity = 220;
     private frame!: Graphics;
 
-    override async load(loader): Promise<void> {
-        this.sprite = new Sprite(await loader.load(Texture, 'image/ship-a.png'));
-    }
-
     override init(): void {
         const { width, height } = this.app.canvas;
 
+        this.sprite = new Sprite(this.loader.get('image/ship-a.png'));
+
         this.mainView = new View(0, 0, width, height);
         this.pipView = new View(0, 0, width * 0.3, height * 0.3).setViewport(0.68, 0.04, 0.28, 0.28);
         // Zoom < 1 zooms OUT (a larger visible world area maps into the same

examples/application-scenes/scene-lifecycle.js

@@ -12,18 +12,38 @@ const app = new Application({
         basePath: 'assets/',
     },
 });
+// The scene lifecycle has two hooks:
+//   - `init(loader)`  — one-shot async setup, called once before the first frame.
+//                        Fetch/await assets here (`this.loader.get(...)` for
+//                        seamless resources, `await this.loader.load(...)` for
+//                        value assets), then build the scene graph.
+//   - `destroy()`     — one-shot teardown, called once when the scene is
+//                        finally popped off the stack.
+// `update`/`draw` run every frame in between. Two signals bracket the same
+// span from the outside: `onLoad` fires right after `init()` resolves (the
+// scene is about to become active) and `onUnload` fires right before
+// `destroy()` runs (the scene is about to deactivate) — a hook point for
+// cross-cutting concerns (audio cues, analytics, HUD toggles) that shouldn't
+// live inside `init`/`destroy` themselves.
 class LifecycleScene extends Scene {
     events;
     counter = 0;
     drawCount = 0;
     timer;
     text;
-    async load() {
-        this.events = ['load'];
-    }
-    init() {
+    async init() {
         const { width, height } = this.app.canvas;
-        this.events.push('init');
+        // This scene is procedural — nothing to fetch — but a real scene would
+        // resolve its assets here before touching the scene graph, e.g.:
+        //   const texture = this.loader.get('ship.png');
+        //   const data = (await this.loader.load(Asset.kind('json', 'level.json'))) as LevelData;
+        this.events = ['init'];
+        this.onLoad.add(() => {
+            this.events.push('onLoad');
+        });
+        this.onUnload.add(() => {
+            this.events.push('onUnload');
+        });
         this.timer = new Timer(Time.fromSeconds(1), true);
         this.text = new Text('', { fillColor: Color.white, fontSize: 18 });
         this.text.setAnchor(0.5);
@@ -43,6 +63,7 @@ class LifecycleScene extends Scene {
         context.render(this.text);
     }
     destroy() {
+        // destroy() is the single teardown hook — no separate unload() step.
         this.events.push('destroy');
         super.destroy();
     }

examples/application-scenes/scene-lifecycle.ts

@@ -1,4 +1,4 @@
-import { Application, Color, Scene, Text, Time, Timer } from '@codexo/exojs';
+import { Application, Asset, Color, Scene, Text, Time, Timer } from '@codexo/exojs';
 
 const app = new Application({
     canvas: {
@@ -13,21 +13,42 @@ const app = new Application({
     },
 });
 
+// The scene lifecycle has two hooks:
+//   - `init(loader)`  — one-shot async setup, called once before the first frame.
+//                        Fetch/await assets here (`this.loader.get(...)` for
+//                        seamless resources, `await this.loader.load(...)` for
+//                        value assets), then build the scene graph.
+//   - `destroy()`     — one-shot teardown, called once when the scene is
+//                        finally popped off the stack.
+// `update`/`draw` run every frame in between. Two signals bracket the same
+// span from the outside: `onLoad` fires right after `init()` resolves (the
+// scene is about to become active) and `onUnload` fires right before
+// `destroy()` runs (the scene is about to deactivate) — a hook point for
+// cross-cutting concerns (audio cues, analytics, HUD toggles) that shouldn't
+// live inside `init`/`destroy` themselves.
 class LifecycleScene extends Scene {
     private events!: string[];
     private counter = 0;
     private drawCount = 0;
     private timer!: Timer;
     private text!: Text;
 
-    override async load(): Promise<void> {
-        this.events = ['load'];
-    }
-
-    override init(): void {
+    override async init(): Promise<void> {
         const { width, height } = this.app.canvas;
 
-        this.events.push('init');
+        // This scene is procedural — nothing to fetch — but a real scene would
+        // resolve its assets here before touching the scene graph, e.g.:
+        //   const texture = this.loader.get('ship.png');
+        //   const data = (await this.loader.load(Asset.kind('json', 'level.json'))) as LevelData;
+        this.events = ['init'];
+
+        this.onLoad.add(() => {
+            this.events.push('onLoad');
+        });
+
+        this.onUnload.add(() => {
+            this.events.push('onUnload');
+        });
 
         this.timer = new Timer(Time.fromSeconds(1), true);
 
@@ -52,6 +73,7 @@ class LifecycleScene extends Scene {
     }
 
     override destroy(): void {
+        // destroy() is the single teardown hook — no separate unload() step.
         this.events.push('destroy');
         super.destroy();
     }

examples/audio-basics/audio-buses.js

@@ -1,5 +1,5 @@
 // Auto-generated from audio-buses.ts — edit the .ts source, not this file.
-import { Application, AudioStream, Color, Graphics, Scene, Sound, Text } from '@codexo/exojs';
+import { Application, Asset, Assets, Color, Graphics, Scene, Text } from '@codexo/exojs';
 import { mountControls } from '@examples/runtime';
 const app = new Application({
     canvas: {
@@ -32,20 +32,22 @@ class AudioBusesScene extends Scene {
     rowY = [];
     sfxButton = { x: 0, y: 0, w: 0, h: 0 };
     hud;
-    async load(loader) {
-        await loader.load(AudioStream, { music: assets.demo.audio.musicLoop });
-        await loader.load(Sound, { sfx: assets.demo.audio.uiClick });
-    }
-    init(loader) {
+    async init() {
         const { width, height } = this.app.canvas;
         // Centre the bus mixer horizontally and spread the bars across the wide
         // 16:9 canvas.
         this.trackW = width * 0.5;
         this.trackX = (width - this.trackW) / 2;
         this.rowY = rows.map((_, i) => height * 0.34 + i * 90);
         this.sfxButton = { x: width / 2 - 150, y: height * 0.74, w: 300, h: 36 };
-        this.music = loader.get(AudioStream, 'music');
-        this.sfx = loader.get(Sound, 'sfx');
+        // AudioStream has no seamless adapter — await it explicitly.
+        const { music } = await this.loader.load(Assets.from({ music: Asset.kind('music', assets.demo.audio.musicLoop) }));
+        this.music = music;
+        // Path-only get() infers Sound from the .ogg extension — sidesteps a
+        // compile-time overload ambiguity between Sound and the Json token form
+        // (both have zero-arg-constructible instance types) when passing the
+        // Sound token explicitly.
+        this.sfx = this.loader.get(assets.demo.audio.uiClick);
         this.graphics = new Graphics();
         this.labels = rows.map((_, i) => new Text('', { fillColor: Color.white, fontSize: 18 }).setPosition(this.trackX - 50, this.rowY[i] - 34));
         this.sfxLabel = new Text('Play SFX  ▶', { fillColor: new Color(20, 20, 20), fontSize: 20 }).setPosition(this.sfxButton.x + 92, this.sfxButton.y + 7);

examples/audio-basics/audio-buses.ts

@@ -1,4 +1,4 @@
-import { Application, AudioStream, Color, Graphics, Scene, Sound, Text } from '@codexo/exojs';
+import { Application, Asset, Assets, AudioStream, Color, Graphics, Scene, Sound, Text } from '@codexo/exojs';
 import { mountControls } from '@examples/runtime';
 
 const app = new Application({
@@ -35,12 +35,7 @@ class AudioBusesScene extends Scene {
     private sfxButton = { x: 0, y: 0, w: 0, h: 0 };
     private hud!: ReturnType<typeof mountControls>;
 
-    override async load(loader): Promise<void> {
-        await loader.load(AudioStream, { music: assets.demo.audio.musicLoop });
-        await loader.load(Sound, { sfx: assets.demo.audio.uiClick });
-    }
-
-    override init(loader): void {
+    override async init(): Promise<void> {
         const { width, height } = this.app.canvas;
 
         // Centre the bus mixer horizontally and spread the bars across the wide
@@ -50,8 +45,14 @@ class AudioBusesScene extends Scene {
         this.rowY = rows.map((_, i) => height * 0.34 + i * 90);
         this.sfxButton = { x: width / 2 - 150, y: height * 0.74, w: 300, h: 36 };
 
-        this.music = loader.get(AudioStream, 'music');
-        this.sfx = loader.get(Sound, 'sfx');
+        // AudioStream has no seamless adapter — await it explicitly.
+        const { music } = await this.loader.load(Assets.from({ music: Asset.kind('music', assets.demo.audio.musicLoop) }));
+        this.music = music;
+        // Path-only get() infers Sound from the .ogg extension — sidesteps a
+        // compile-time overload ambiguity between Sound and the Json token form
+        // (both have zero-arg-constructible instance types) when passing the
+        // Sound token explicitly.
+        this.sfx = this.loader.get(assets.demo.audio.uiClick);
 
         this.graphics = new Graphics();
         this.labels = rows.map((_, i) => new Text('', { fillColor: Color.white, fontSize: 18 }).setPosition(this.trackX - 50, this.rowY[i] - 34));

examples/audio-basics/crossfade-tracks.js

@@ -1,5 +1,5 @@
 // Auto-generated from crossfade-tracks.ts — edit the .ts source, not this file.
-import { Application, AudioStream, Color, crossFade, Graphics, Scene, Text } from '@codexo/exojs';
+import { Application, Asset, Assets, Color, crossFade, Graphics, Scene, Text } from '@codexo/exojs';
 import { mountControls } from '@examples/runtime';
 const app = new Application({
     canvas: {
@@ -34,19 +34,18 @@ class CrossfadeTracksScene extends Scene {
     meterBX = 0;
     meterBaseY = 0;
     hud;
-    async load(loader) {
-        await loader.load(AudioStream, { a: assets.demo.audio.musicA, b: assets.demo.audio.musicB });
-    }
-    init(loader) {
+    async init() {
         const { width, height } = this.app.canvas;
         // Spread the two meters across the wide canvas: each sits a third of the
         // way in from its side, centred on the meter width.
         this.meterAX = width * 0.33 - METER_W / 2;
         this.meterBX = width * 0.67 - METER_W / 2;
         this.meterBaseY = height * 0.82;
-        // Both tracks loop; the crossfade only swaps which one is audible.
-        this.trackA = loader.get(AudioStream, 'a');
-        this.trackB = loader.get(AudioStream, 'b');
+        // AudioStream has no seamless adapter — await it explicitly. Both tracks
+        // loop; the crossfade only swaps which one is audible.
+        const tracks = await this.loader.load(Assets.from({ a: Asset.kind('music', assets.demo.audio.musicA), b: Asset.kind('music', assets.demo.audio.musicB) }));
+        this.trackA = tracks.a;
+        this.trackB = tracks.b;
         this.graphics = new Graphics();
         this.labelA = new Text('Track A', { fillColor: Color.white, fontSize: 22, align: 'center' })
             .setAnchor(0.5, 0.5)