@simpludify/web 0.1.7 → 0.2.0

package/README.md

@@ -1,11 +1,11 @@
 # @simpludify/web
 
-Experimental v0.1.7 browser SDK for Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. Includes Game, PixiJS rendering, browser input and Canvas/DOM UI adapters; re-exports the host-independent Core API. Core and PixiJS are installed as runtime dependencies, not bundled into this package.
+Experimental v0.2.0 browser SDK for Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. Includes Game, PixiJS rendering, browser input and Canvas/DOM UI adapters; re-exports the host-independent Core API. Core and PixiJS are installed as runtime dependencies, not bundled into this package.
 
-Registry installation (check availability with `npm view @simpludify/web@0.1.7 version`):
+Registry installation (check availability with `npm view @simpludify/web@0.2.0 version`):
 
 ```sh
-npm install @simpludify/web@0.1.7
+npm install @simpludify/web@0.2.0
 npm install --save-dev vite typescript
 ```
 

package/dist/asset-loaders.d.ts

@@ -0,0 +1,6 @@
+import type { AssetAdapter } from "./assets.js";
+import { type ImageResource, SharedImages } from "./shared-images.js";
+export declare function assetResponse(url: string, signal: AbortSignal, reload: boolean): Promise<Response>;
+export declare function loadImageResource(url: string, signal: AbortSignal, mode?: "explicit" | "reload"): Promise<ImageResource>;
+export declare function createImagePool(load?: typeof loadImageResource): SharedImages;
+export declare function browserAssetAdapter(images: SharedImages, decode: (data: ArrayBuffer) => Promise<AudioBuffer>): AssetAdapter;

package/dist/assets.d.ts

@@ -0,0 +1,158 @@
+import { type LifetimeOwner, type Logger } from "@simpludify/core";
+import type { ImageLease } from "./shared-images.js";
+export interface AssetData {
+    image: Readonly<{
+        width: number;
+        height: number;
+    }>;
+    audio: AudioBuffer | null;
+    font: string;
+    json: unknown;
+}
+export type AssetKind = keyof AssetData;
+export type AssetStatus = "loading" | "ready" | "fallback" | "failed" | "released";
+export interface AssetRetry {
+    /** One retry for a non-network failure. A promise can represent a caller-owned event. */
+    readonly once?: "immediate" | {
+        readonly delayMs: number;
+    } | {
+        readonly until: PromiseLike<unknown>;
+    };
+    /** Additional attempts after network failures, from zero to five. */
+    readonly network?: number;
+    readonly networkDelayMs?: number;
+}
+export interface AssetLoadOptions {
+    readonly retry?: AssetRetry;
+    /** Deadline for the load and its retries, including any wait for a signal. */
+    readonly timeoutMs?: number;
+}
+export interface AssetRequest<K extends AssetKind = AssetKind> extends AssetLoadOptions {
+    readonly kind: K;
+    readonly url: string | URL;
+}
+export interface AssetOptions {
+    /** Maximum number of idle, successfully loaded Assets per Game. */
+    readonly cacheEntries?: number;
+    readonly fallback?: Readonly<Partial<Record<Exclude<AssetKind, "json">, string | URL>>>;
+}
+export interface AssetProgress {
+    readonly total: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly fallback: number;
+    readonly loading: number;
+    readonly ratio: number;
+    readonly state: "idle" | "loading" | "complete";
+}
+export interface ImageAssetSource {
+    readonly kind: "image";
+    readonly url: string;
+}
+export interface AssetResource {
+    readonly value: unknown;
+    readonly image?: ImageLease;
+    release(): void;
+}
+export interface AssetAdapter {
+    load(kind: AssetKind, url: string, signal: AbortSignal, reload: boolean): Promise<AssetResource>;
+    fallback(kind: AssetKind, url: string | undefined, signal: AbortSignal): Promise<AssetResource | undefined>;
+}
+interface Entry {
+    readonly key: string;
+    readonly kind: AssetKind;
+    readonly url: string;
+    readonly id: string;
+    readonly listeners: Set<() => void>;
+    readonly validators: Set<(asset: AssetResource) => void>;
+    readonly users: Set<() => void>;
+    readonly first: Promise<void>;
+    usable(): void;
+    fail(error: unknown): void;
+    status: Exclude<AssetStatus, "released">;
+    asset: AssetResource | undefined;
+    task: Promise<void> | undefined;
+    controller: AbortController | undefined;
+    error: unknown;
+}
+export declare class AssetHandle<K extends AssetKind> {
+    readonly kind: K;
+    private readonly entry;
+    private readonly store;
+    private readonly remove;
+    readonly ready: Promise<this>;
+    private readonly cancelled;
+    private readonly imageSource;
+    /** @internal */
+    constructor(kind: K, entry: Entry, store: AssetStore, remove: () => void);
+    get id(): string;
+    get url(): string;
+    get status(): AssetStatus;
+    get loading(): boolean;
+    get value(): AssetData[K] | undefined;
+    get error(): unknown;
+    get progress(): AssetProgress;
+    /** Stable Renderable source. SpriteSheet accepts its URL. */
+    get source(): K extends "image" ? ImageAssetSource : undefined;
+    onChange(listener: (asset: this) => void): () => void;
+    /** @internal A playback or Game font owns a separate reference. */
+    retain(store: AssetStore): AssetHandle<K>;
+    reload(options?: AssetLoadOptions): Promise<this>;
+    release(): void;
+}
+export declare class AssetScope implements LifetimeOwner {
+    private readonly store;
+    private readonly global;
+    private readonly lifetime;
+    private readonly handles;
+    private readonly listeners;
+    private previous;
+    /** @internal */
+    constructor(store: AssetStore, owner?: LifetimeOwner, global?: boolean);
+    get disposed(): boolean;
+    onDispose(callback: () => void): () => void;
+    scope(owner?: LifetimeOwner): AssetScope;
+    load<K extends AssetKind>(request: AssetRequest<K>): AssetHandle<K>;
+    get progress(): AssetProgress;
+    onProgress(listener: (value: AssetProgress) => void): () => void;
+    private notify;
+    dispose(): void;
+}
+/** @internal One resource directory per Game. The adapter owns decoded resources. */
+export declare class AssetStore {
+    private readonly adapter;
+    private readonly logger;
+    private readonly base;
+    private readonly prefix;
+    private readonly entries;
+    private readonly images;
+    private readonly idle;
+    private readonly listeners;
+    private readonly scopes;
+    private notifying;
+    private notificationScheduled;
+    private readonly capacity;
+    private readonly customFallback;
+    private sequence;
+    private dead;
+    constructor(adapter: AssetAdapter, logger: Logger, base: string, options?: AssetOptions);
+    register(scope: AssetScope): () => void;
+    observe(listener: () => void): () => void;
+    deliver(listener: () => unknown): void;
+    changed(): void;
+    get progress(): AssetProgress;
+    entry<K extends AssetKind>(request: AssetRequest<K>): Entry;
+    retain(entry: Entry, dispose: () => void): () => void;
+    private release;
+    private evict;
+    ready(entry: Entry, signal: AbortSignal): Promise<void>;
+    start(entry: Entry, options: AssetLoadOptions, reload: boolean): Promise<void>;
+    private attempt;
+    private commit;
+    private fallback;
+    private load;
+    image(id: string, signal: AbortSignal): Promise<ImageLease>;
+    dispose(): void;
+}
+export declare function isAssetImage(url: string): boolean;
+export {};

package/dist/audio.d.ts

@@ -0,0 +1,97 @@
+import { type LifetimeOwner, type Logger } from "@simpludify/core";
+import type { AssetHandle, AssetStore } from "./assets.js";
+export interface AudioGroupOptions {
+    readonly parent?: string;
+    readonly volume?: number;
+    readonly maxVoices?: number;
+}
+export interface AudioPlayOptions {
+    readonly group?: string;
+    readonly owner?: LifetimeOwner;
+    readonly volume?: number;
+    readonly loop?: boolean;
+    /** Optional cap for simultaneous instances of this asset. */
+    readonly maxVoices?: number;
+}
+export type AudioEndReason = "ended" | "stopped" | "replaced" | "failed";
+export type AudioPlaybackState = "pending" | "playing" | "paused" | AudioEndReason;
+export declare class AudioGroup {
+    readonly name: string;
+    readonly parent: AudioGroup | undefined;
+    private gain;
+    private level;
+    readonly maxVoices: number | undefined;
+    /** @internal */
+    constructor(name: string, parent: AudioGroup | undefined, options?: AudioGroupOptions);
+    get volume(): number;
+    set volume(value: number);
+    /** @internal */
+    node(context: AudioContext): GainNode;
+    /** @internal */
+    disconnect(): void;
+}
+export declare class AudioPlayback {
+    private readonly audio;
+    private readonly use;
+    readonly group: AudioGroup;
+    readonly finished: Promise<AudioEndReason>;
+    readonly assetId: string;
+    private resolve;
+    private phase;
+    private done;
+    private source;
+    private gain;
+    private buffer;
+    private position;
+    private startedAt;
+    private level;
+    private looping;
+    private offOwner;
+    /** @internal */
+    constructor(audio: GameAudio, use: AssetHandle<"audio">, group: AudioGroup, options: AudioPlayOptions);
+    get state(): AudioPlaybackState;
+    get volume(): number;
+    set volume(value: number);
+    get loop(): boolean;
+    set loop(value: boolean);
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    /** @internal */
+    replace(): void;
+    /** @internal */
+    startIfReady(): void;
+    private clearSource;
+    private fail;
+    private finish;
+}
+/** One Web Audio context per Game, created only when audio is requested. */
+export declare class GameAudio {
+    private readonly assets;
+    private readonly logger;
+    private readonly shutdown;
+    private readonly groups;
+    private readonly voices;
+    private context;
+    readonly master: AudioGroup;
+    /** @internal */
+    constructor(host: HTMLElement, assets: AssetStore, logger: Logger);
+    get state(): AudioContextState | "idle";
+    group(name: string, options?: AudioGroupOptions): AudioGroup;
+    play(asset: AssetHandle<"audio">, options?: AudioPlayOptions): AudioPlayback;
+    private enforceLimit;
+    private assertAlive;
+    /** @internal */
+    device(): AudioContext;
+    /** @internal */
+    decode(bytes: ArrayBuffer): Promise<AudioBuffer>;
+    /** Call from a trusted user gesture to start pending playback. */
+    unlock(): Promise<boolean>;
+    private readonly drain;
+    /** @internal */
+    remove(voice: AudioPlayback): void;
+    /** @internal */
+    report(cause: unknown, message: string): void;
+    /** @internal */
+    dispose(): void;
+}

package/dist/canvas-visual.d.ts

@@ -16,6 +16,7 @@ export declare class CanvasVisual implements CanvasPresentation {
     private readonly entries;
     private readonly metrics;
     private dirty;
+    private defaultFont;
     private dead;
     private active;
     private cacheResolution;
@@ -42,6 +43,7 @@ export declare class CanvasVisual implements CanvasPresentation {
     private native;
     private button;
     private updateButton;
+    private fontFamily;
     update(width: number, height: number): void;
     private releaseEntry;
     dispose(): void;

package/dist/game.d.ts

@@ -1,9 +1,12 @@
 import type { CanvasNode } from "@simpludify/core";
-import { type ActionBindings, ActionController, type ActionSet, type Actor, Aspect, Camera, CanvasUI, type CanvasUIOptions, Engine, type FixedStepOptions, type FrameDriver, type InputCapture, type InputCaptureOptions, type JsonValue, type LogicalResolution, type RendererPort, type ReplayControllers, ReplayPlayer, Scene, ScenePointer, type ScreenPoint, type TweenScheduler, type Viewport, type ViewTransform, VirtualInput, type WorldPoint } from "@simpludify/core";
+import { type ActionBindings, ActionController, type ActionSet, type Actor, Aspect, Camera, CanvasUI, type CanvasUIOptions, Engine, type FixedStepOptions, type FrameDriver, type InputCapture, type InputCaptureOptions, type JsonValue, Logger, type LoggerOptions, type LogicalResolution, type RendererPort, type ReplayControllers, ReplayPlayer, Scene, ScenePointer, type SceneRetention, type ScreenPoint, type TweenScheduler, type Viewport, type ViewTransform, VirtualInput, type WorldPoint } from "@simpludify/core";
+import { type AssetHandle, type AssetOptions, AssetScope } from "./assets.js";
+import { GameAudio } from "./audio.js";
 import { GamepadInput } from "./gamepads.js";
 import { Theme, type ThemeTokens, type UINode } from "./ui.js";
 export interface SceneContext {
     readonly scene: Scene;
+    readonly assets: AssetScope;
     readonly signal: AbortSignal;
     readonly tweens: TweenScheduler;
     readonly presentationTweens: TweenScheduler;
@@ -19,6 +22,13 @@ export interface SceneContext {
     onDispose(callback: () => void): () => void;
 }
 export type SceneSetup = (context: SceneContext) => void | Promise<void>;
+export interface SceneOptions {
+    readonly retention?: SceneRetention;
+}
+export interface GameLoggingOptions extends Omit<LoggerOptions, "sink"> {
+    /** Controls Console output only. Diagnostic subscribers remain active. */
+    readonly console?: boolean;
+}
 export interface GameOptions {
     parent?: HTMLElement;
     resolution?: LogicalResolution;
@@ -33,6 +43,10 @@ export interface GameOptions {
     fixedStep?: FixedStepOptions;
     renderer?: (host: HTMLElement) => RendererPort;
     frames?: FrameDriver;
+    logging?: GameLoggingOptions;
+    assets?: AssetOptions;
+    sceneRetention?: SceneRetention;
+    /** @deprecated Subscribe to Game.logger for structured diagnostics. */
     onError?: (error: unknown) => void;
 }
 export declare class Game<SceneId extends string = string> {
@@ -40,6 +54,13 @@ export declare class Game<SceneId extends string = string> {
     readonly element: HTMLDivElement;
     readonly camera: Camera;
     readonly gamepads: GamepadInput;
+    readonly logger: Logger;
+    readonly assets: AssetScope;
+    readonly audio: GameAudio;
+    private readonly defaultFont;
+    private fontUse;
+    private readonly imagePool;
+    private readonly assetStore;
     private readonly renderer;
     private readonly keyboard;
     private readonly captures;
@@ -89,6 +110,10 @@ export declare class Game<SceneId extends string = string> {
     private height;
     private ratio;
     private readonly scenes;
+    private readonly retainedScenes;
+    private readonly sceneRetention;
+    private activeRetention;
+    private detachPresentation;
     private pendingScene;
     private readonly defaultUI;
     private ui;
@@ -105,6 +130,8 @@ export declare class Game<SceneId extends string = string> {
     private readonly shutdown;
     private readonly errorBox;
     constructor(options?: GameOptions);
+    /** Choose the Game default font for DOM and Canvas UI. */
+    setFont(asset?: AssetHandle<"font">): void;
     private assertAlive;
     get tweens(): TweenScheduler;
     get presentationTweens(): TweenScheduler;
@@ -124,11 +151,12 @@ export declare class Game<SceneId extends string = string> {
     remove(actor: Actor | string): boolean;
     canvasUI(root: CanvasNode, options?: CanvasUIOptions): CanvasUI;
     uiOverlay(...nodes: UINode[]): void;
-    scene(id: SceneId, setup: SceneSetup): this;
+    scene(id: SceneId, setup: SceneSetup, options?: SceneOptions): this;
     private wait;
     run(initialScene?: SceneId): Promise<void>;
     changeScene(id: SceneId): Promise<void>;
     private navigate;
+    private reportPreparation;
     private present;
     get viewport(): Viewport;
     get view(): ViewTransform;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import "./style.css";
 export * from "@simpludify/core";
+export type { AssetData, AssetHandle, AssetKind, AssetLoadOptions, AssetOptions, AssetProgress, AssetRequest, AssetRetry, AssetScope, AssetStatus, ImageAssetSource, } from "./assets.js";
+export type { AudioEndReason, AudioGroup, AudioGroupOptions, AudioPlayback, AudioPlaybackState, AudioPlayOptions, GameAudio, } from "./audio.js";
 export { browserAbortSignal, CanvasButton } from "./canvas-node.js";
 export type { CanvasPresentation } from "./canvas-visual.js";
 export * from "./game.js";