@gamedevland/engine 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.0.10 — 2026-11-07
+
+### Localization and text
+
+- Expand `LocaleCatalog` with Spanish, Brazilian Portuguese, German, French, Italian,
+  Turkish, Simplified Chinese, Japanese, and Korean, including regional-code normalization.
+- Add `LocalesService.initialize()` with an explicit supported subset and default language.
+  Resolve saved manual preferences before device/platform hints, browser preferences, and
+  the configured default. Automatic detection does not write a manual preference.
+- Persist explicit `setLang()` choices when storage is configured, tolerate unavailable
+  browser storage, and expose locale revisions and disposable change subscriptions.
+- Preserve the English/Russian default subset for existing consumers and support partial
+  locale-specific text-style maps.
+- Add measured `Text.fitTo(width, height?)` font fitting without changing node transforms,
+  including proportional line-height adjustment and validation of fitting bounds.
+
+### Audio
+
+- Attempt music autoplay and recover blocked playback on the first trusted canvas
+  pointer/touch interaction or eligible keyboard interaction. Engine-owned capture listeners
+  run before scene input, work during boot, and are removed on audio disposal.
+- Retry Web Audio resume on each user gesture even if an earlier automatic attempt remains
+  pending. Verify context state and handle rejected resume attempts and unavailable audio.
+- Retain blocked HTML media music requests and reuse their sound IDs on native activation
+  or Howler unlock. Report confirmed playback separately from pending handles.
+- Deduplicate active/loading music in both `AudioManager` and the default backend. Repeated
+  requests and scene changes preserve the handle and playback position; replacing a pending
+  track cancels its old Howler queue to prevent stale stops and orphaned playback.
+- Preserve manual pause/stop, music/SFX preferences, channel/platform/background mute gates,
+  and terminal listener cleanup. Drop blocked one-shot SFX rather than replaying a backlog.
+- Add optional `AudioBackend.isHandlePlaying()` and `isPlaybackReady()` hooks; existing
+  custom backends remain compatible.
+- Reject unknown `channel.*` keys in the existing `system.audio.volumeConfigId` JSON contract.
+  Document centrally editable music/SFX channel and per-asset volumes in engine guidelines.
+
+### Verification
+
+- Add deterministic locale preference/text fitting and browser audio activation regressions,
+  plus tests using real Howler queue/event code with a simulated HTML media device.
+- Run these checks in the npm publishing workflow. Simulated browser/media tests do not
+  constitute physical iOS/Android or portal-device verification.
+
+## 0.0.9 — 2026-11-05
+
+- Add opt-in `screen.dpr: 'native'` to target the viewport's physical pixels.
+- Add `screen.render.maxCanvasPixels` to limit the backing canvas area.
+- Apply size and resolution in one renderer resize. Existing numeric and `'auto'` DPR defaults stay the same.
+
 ## 0.0.8 — 2026-11-04
 
 - Publish the SDK source and package under MIT with public repository metadata.
@@ -14,4 +62,21 @@
 
 ## 0.0.7
 
+- Expose runtime activity and native pointer metadata.
 - Dispose spawned prefab logical children idempotently and release their registry entries.
+
+## 0.0.5
+
+- Prepare automated npm publishing.
+
+## 0.0.4
+
+- Update package homepage and issue-tracker metadata.
+
+## 0.0.3
+
+- Update repository metadata.
+
+## 0.0.2
+
+- Add drag-end reasons and renderer-independent local node bounds.

package/README.md

@@ -10,6 +10,14 @@ The npm package intentionally ships a compact public distribution:
 
 Source files are available in [the SDK repository](https://github.com/gamedevland/sdk/tree/main/packages/engine/src); the npm archive contains the compiled distribution.
 
+## Changelog
+
+**0.0.10** adds configurable language preferences, observable locale changes,
+measured text fitting, automatic audio activation recovery, and music deduplication
+across loading, user gestures, and scene changes. The default locale subset and
+existing custom audio backends remain compatible.
+[Full engine changelog](https://github.com/gamedevland/sdk/blob/main/packages/engine/CHANGELOG.md).
+
 ## Install
 
 ```bash
@@ -44,6 +52,20 @@ For `dragend` input events, `InputEventBase.dragEndReason` distinguishes a norma
 
 Layout nodes expose `getLocalBounds()` for renderer-independent local geometry queries.
 
+## Screen resolution
+
+Logical landscape and portrait profiles define the game's coordinate system.
+Set `system.screen.dpr: 'native'` to scale the backing canvas to the physical
+pixels of the viewport, including when the game is embedded in an iframe.
+For this mode, `maxDpr` caps the display density relative to CSS pixels.
+Existing numeric `dpr` values and `'auto'` still multiply the logical canvas size.
+
+Set `system.screen.render.maxCanvasPixels` to a positive integer to limit the
+backing canvas area. The engine scales both axes together and preserves the
+logical layout and pointer coordinates. Extremely small budgets may be exceeded
+when required to keep both axes at least one pixel. This option caps the main
+canvas independently of the optional `render.scaleFactor` pass.
+
 ## TypeScript
 
 ### Platform packaging and boot (0.0.8)
@@ -112,3 +134,70 @@ type declarations may conflict with newer TypeScript DOM library declarations in
 MIT. See [LICENSE](./LICENSE). Source code and contributions: [gamedevland/sdk](https://github.com/gamedevland/sdk).
 
 Earlier npm releases retain the license included in their respective archives. Third-party dependencies retain their own licenses.
+
+## Language preferences
+
+`LocaleCatalog` recognizes `en`, `ru`, `es`, `pt-BR`, `de`, `fr`, `it`, `tr`,
+`zh-CN`, `ja`, and `ko`, including regional browser codes. Games opt into their
+own subset with `LocalesService.initialize({ supportedLocales, defaultLocale,
+deviceLocale, storageKey })`. Existing games retain their English/Russian subset.
+The priority is a saved manual choice, a device/platform hint, browser language
+preferences, then the configured default. Initialization never persists an
+automatic choice. `setLang()` persists manual choices, including selection of the
+current language; unavailable browser storage does not prevent play. Dictionaries
+must already be present in ConfigStore. `getRevision()` and `subscribe()` support
+live UI updates; `subscribe()` returns an unsubscribe function. Text-style locale
+overrides accept partial maps of supported languages.
+
+`Text.fitTo(width, height?)` shrinks the current font to fit measured local bounds
+without changing node transforms. Set the desired font, wrapping and content
+before fitting; invoke it again after a language/content change.
+
+### Autoplay and first-interaction recovery
+
+Request music normally with `audio.playMusic(id)` when assets and player preferences
+are ready. Do not wait for a scene-specific tap. Engine initialization attaches
+native capture listeners to its canvas before scene input is routed. The audio
+manager attempts Web Audio context resume automatically; a rejected or pending
+attempt is retained for the first trusted pointer/touch interaction or keyboard
+interaction while game/body has focus. Gesture retries call `resume()` before any
+await, independently of any pending automatic attempt. Synthetic events, secondary
+pointers/buttons, repeated/modifier key input, and hidden documents do not activate
+recovery. Listeners belong to `AudioManager` and are removed by `audio.dispose()`.
+
+The Howler backend checks the actual context state. HTML media `playerror` preserves
+requested music and retries its existing sound id from native activation or Howler's
+`unlock` event. Repeated taps cannot create layered music. `isMusicPlaying()` reports
+confirmed playback rather than a queued handle. Stale blocked one-shot SFX are
+suppressed/dropped, not replayed after unlock. User/channel disabled flags, manual
+pause/stop, and platform/background mute remain authoritative.
+
+`AudioBackend` optionally exposes `isHandlePlaying(handle)` and `isPlaybackReady()`
+for precise state and one-shot suppression; existing custom backends remain compatible.
+The default backend implements both. `AudioManager.attachInteractionTarget(element)`
+is idempotent and is called by Engine; standalone AudioManager hosts should attach
+it to their own game canvas and dispose the manager on teardown.
+
+All authored levels belong in a manually editable JSON file selected by
+`system.audio.volumeConfigId`, including `channel.music`, `channel.sfx`, and per-asset
+levels. The SDK validates finite values in `[0, 1]` and rejects unknown channel keys.
+Do not duplicate these values in consumer playback calls. Per-play volume options
+remain available for deliberate runtime envelopes/custom backend integrations.
+
+Run `node scripts/verify-audio-activation.mjs` from the SDK workspace to exercise the
+real audio classes with simulated browser contexts/media events. These are deterministic
+unit checks; they do not replace Safari/iOS/Android and embedded-portal device checks.
+
+### Music request idempotency
+
+Repeated `playMusic()` requests for the same active or loading track preserve its
+handle and seek position. The backend independently deduplicates pending/playing
+music and limits its music channel to one source. Music is engine-scoped and does
+not restart when changing scenes. Source-wide stops must not be queued ahead of
+an undecoded play: Howler can reuse a sound id and later stop the newer request.
+Cancelling undecoded music unloads the old Howl queue and recreates a clean source.
+
+Run `node scripts/verify-music-single-instance.mjs` to check the actual bundled
+Howler queue/events against a simulated HTML media device, including cold load,
+boot/main duplicates, unlock races, preserved seek, mute/unmute during decoding,
+and cancellation. This supplements `verify-audio-activation.mjs`.

package/dist/sdk.d.ts

@@ -343,6 +343,10 @@ export interface AudioBackend {
 	createSource(source: AudioSourceDescriptor): void;
 	hasSource(id: AudioId): boolean;
 	isHandleActive(handle: AudioHandle): boolean;
+	/** Actual playback state, excluding queued/blocked requests. */
+	isHandlePlaying?(handle: AudioHandle): boolean;
+	/** False while Web Audio is suspended; used to discard stale one-shot SFX. */
+	isPlaybackReady?(): boolean;
 	play(id: AudioId, options?: PlayAudioOptions): AudioHandle;
 	pause(handle: AudioHandle): void;
 	stop(handle: AudioHandle): void;
@@ -371,16 +375,13 @@ export interface IStateStore<T> {
 	save(value: T): void;
 	clear(): void;
 }
-export type SupportedLocaleCode = "en" | "ru";
-/**
- * Canonical supported locale codes used by runtime, build validation, and platform hints.
- */
+export type SupportedLocaleCode = "en" | "ru" | "es" | "pt-BR" | "de" | "fr" | "it" | "tr" | "zh-CN" | "ja" | "ko";
+/** Canonical locale codes shared by runtime, configs and build tools. */
 export declare class LocaleCatalog {
-	static readonly EN: SupportedLocaleCode;
-	static readonly RU: SupportedLocaleCode;
-	static readonly DEFAULT: SupportedLocaleCode;
+	static readonly EN = "en";
+	static readonly RU = "ru";
+	static readonly DEFAULT = "en";
 	private static readonly SUPPORTED_LIST;
-	private static readonly SUPPORTED;
 	static isSupported(locale: string): locale is SupportedLocaleCode;
 	static getSupportedList(): ReadonlyArray<SupportedLocaleCode>;
 	static normalize(input: string | null | undefined): SupportedLocaleCode | null;
@@ -418,7 +419,7 @@ export interface TextStyleDef {
 	readonly dropShadow?: TextStyleDropShadowDef;
 	readonly wordWrap?: boolean;
 	readonly wordWrapWidth?: number;
-	readonly byLocale?: Readonly<Record<"en" | "ru", TextStyleDef>>;
+	readonly byLocale?: Readonly<Partial<Record<SupportedLocaleCode, TextStyleDef>>>;
 }
 /** Map of style name to definition. */
 export type TextStylesConfig = Record<string, TextStyleDef>;
@@ -556,14 +557,32 @@ export declare class IndexedDbStorageAdapter {
 	private openDatabase;
 	private logStorageError;
 }
-/** Simple localization access service. */
+export interface LocalePreferences {
+	readonly supportedLocales: readonly SupportedLocaleCode[];
+	readonly defaultLocale?: SupportedLocaleCode;
+	readonly deviceLocale?: string | null;
+	readonly preferredLocales?: readonly string[];
+	readonly storage?: IStorageAdapter;
+	readonly storageKey?: string;
+}
+/** Dictionary lookup and persistent, observable language preferences. */
 export declare class LocalesService {
 	private readonly configStore;
 	private current;
+	private supported;
+	private defaultLocale;
+	private storage;
+	private storageKey;
+	private revision;
+	private readonly listeners;
 	private readonly fallback;
 	private readonly loadedDictionaries;
 	constructor(configStore: ConfigStore, fallback?: readonly string[]);
+	initialize(options: LocalePreferences): void;
 	setLang(lang: string): void;
+	getRevision(): number;
+	subscribe(listener: (locale: SupportedLocaleCode) => void): () => void;
+	private apply;
 	getLang(): SupportedLocaleCode;
 	private hasKey;
 	t(key: string, params?: Readonly<Record<string, string | number>>): string;
@@ -867,8 +886,12 @@ export declare class AudioManager {
 	private musicVolumeInitialized;
 	private musicVolumeOverridden;
 	private disposed;
+	private autoplayAttempt;
+	private readonly interactionUnlock;
 	static createDefault(assets: AssetManager, options?: AudioManagerOptions): AudioManager;
 	constructor(assets: AssetManager, backend: AudioBackend, options?: AudioManagerOptions);
+	/** Engine-owned, scene-independent activation on the game's native input target. */
+	attachInteractionTarget(target: HTMLElement): void;
 	playMusic(assetId: AudioId, options?: PlayAudioOptions): AudioHandle | undefined;
 	playSfx(assetId: AudioId, options?: PlayAudioOptions): AudioHandle | undefined;
 	preloadInBackground(assetId: AudioId): void;
@@ -902,6 +925,7 @@ export declare class AudioManager {
 	private rememberMusicRequest;
 	private restoreRememberedMusicIfNeeded;
 	private clearActiveMusic;
+	private tryAutomaticUnlock;
 	private clearRememberedMusicRequest;
 	private ensureRememberedMusicSourceInBackground;
 	private isChannelEnabled;
@@ -1587,6 +1611,8 @@ declare class Text$1 extends NodeBase implements TextNode {
 	}): DisplayNode;
 	get view(): PIXI.Text;
 	setText(value: string): this;
+	/** Shrink the current font to fit local bounds, preserving node transforms. */
+	fitTo(width: number, height?: number): this;
 	protected applyAnchor(anchorX: number, anchorY: number): this;
 }
 export declare abstract class BaseComponent<TNode extends NodeBase = NodeBase> {
@@ -2216,16 +2242,20 @@ export interface ScreenProfile {
 }
 export interface ScreenRenderConfig {
 	scaleFactor?: number;
+	/** Maximum backing canvas area in physical pixels. Independent of scaleFactor. */
+	maxCanvasPixels?: number;
 }
 /**
  * Main configuration for screen behavior.
  * - `land`/`port`: virtual profiles for each orientation.
- * - `dpr`: renderer resolution; 'auto' or a fixed number. Default is 1.
+ * - `dpr`: fixed renderer resolution, 'auto' for browser DPR in virtual units,
+ *   or 'native' to target physical viewport pixels. Default is 1.
+ * - `maxDpr`: caps the browser DPR in 'auto' and 'native' modes.
  */
 export interface ScreenConfig {
 	land: ScreenProfile;
 	port: ScreenProfile;
-	dpr?: "auto" | number;
+	dpr?: "auto" | "native" | number;
 	maxDpr?: number;
 	render?: ScreenRenderConfig;
 }
@@ -2246,7 +2276,7 @@ export interface VirtualSize {
 export interface ScreenStateSnapshot {
 	orientation: Orientation;
 	viewport: ViewportSize;
-	/** Internal canvas size (the <canvas width/height> attributes), px. */
+	/** Logical canvas size, before renderer resolution is applied. */
 	canvas: {
 		width: number;
 		height: number;
@@ -2319,8 +2349,7 @@ export declare class ScreenManager {
 	private applySnapshot;
 	/**
 	 * Applies the current snapshot to the PIXI renderer and stage:
-	 * - Sets device pixel ratio (renderer.resolution)
-	 * - Resizes the internal canvas to the computed virtual size
+	 * - Resizes the renderer using the virtual size and backing canvas resolution
 	 * - Does NOT scale the stage: scaling is expected to be done via CSS size of the canvas
 	 */
 	private applyToStage;
@@ -2331,12 +2360,7 @@ export declare class ScreenManager {
 	onChange(handler: (snapshot: ScreenStateSnapshot) => void): () => void;
 	/** Notifies subscribers with a cloned snapshot to prevent outside mutation. */
 	private notifyChange;
-	/**
-	 * Resolves the device pixel ratio to use for the renderer's resolution.
-	 * - `dpr: 'auto'` uses the browser DPR (retina-aware).
-	 * - numeric `dpr` uses the provided fixed value.
-	 * - missing/invalid values fall back to 1.
-	 */
+	private resolveResolution;
 	private resolveDpr;
 	/**
 	 * Returns the center point of the virtual canvas in virtual coordinates.
@@ -4906,7 +4930,7 @@ export declare abstract class BaseTypedCommand<TPayload> extends BaseCommand {
 	protected abstract execute(payload: TPayload): Promise<void> | void;
 	run(data?: Record<string, unknown>): Promise<void> | void;
 }
-export type EngineErrorCodeValue = "CORE_INVALID_ARGUMENT" | "CORE_MISSING_REQUIRED" | "CORE_INVALID_CONFIG" | "CORE_INVARIANT_VIOLATION" | "SCENE_INVALID_ARGUMENT" | "SCENE_INVALID_STATE" | "SCENE_LIFECYCLE_FAILURE" | "DI_INVALID_CONFIG" | "DI_PROVIDER_NOT_FOUND" | "DI_INVALID_PROVIDER" | "DI_DUPLICATE_PROVIDER" | "DI_FORBIDDEN_OVERRIDE" | "DI_UNRESOLVABLE_TOKEN" | "ASSET_MISSING_REQUIRED" | "ASSET_INVALID_CONFIG" | "ASSET_CONFLICT" | "ASSET_LOAD_FAILURE" | "LAYOUT_MISSING_REQUIRED" | "LAYOUT_INVALID_CONFIG" | "LAYOUT_CONFLICT" | "LAYOUT_INVARIANT_VIOLATION" | "AUDIO_MISSING_REQUIRED" | "AUDIO_INVALID_ARGUMENT" | "AUDIO_INVALID_CONFIG" | "AUDIO_CONFLICT" | "PARTICLE_MISSING_REQUIRED" | "PARTICLE_INVALID_ARGUMENT" | "PARTICLE_INVALID_CONFIG" | "PARTICLE_INVARIANT_VIOLATION" | "PARTICLE_RUNTIME_FAILURE" | "PREFAB_MISSING_REQUIRED" | "PREFAB_INVALID_CONFIG" | "PREFAB_CONFLICT" | "PREFAB_INVARIANT_VIOLATION" | "FSM_INVALID_CONFIG" | "FSM_INVALID_STATE" | "COMMAND_MISSING_REQUIRED" | "COMMAND_INVALID_PAYLOAD" | "CONFIG_MISSING_REQUIRED" | "CONFIG_INVALID_ARGUMENT" | "CONFIG_INVALID_SCHEMA";
+export type EngineErrorCodeValue = "CORE_INVALID_ARGUMENT" | "CORE_MISSING_REQUIRED" | "CORE_INVALID_CONFIG" | "CORE_INVARIANT_VIOLATION" | "SCENE_INVALID_ARGUMENT" | "SCENE_INVALID_STATE" | "SCENE_LIFECYCLE_FAILURE" | "DI_INVALID_CONFIG" | "DI_PROVIDER_NOT_FOUND" | "DI_INVALID_PROVIDER" | "DI_DUPLICATE_PROVIDER" | "DI_FORBIDDEN_OVERRIDE" | "DI_UNRESOLVABLE_TOKEN" | "ASSET_MISSING_REQUIRED" | "ASSET_INVALID_CONFIG" | "ASSET_CONFLICT" | "ASSET_LOAD_FAILURE" | "LAYOUT_MISSING_REQUIRED" | "LAYOUT_INVALID_CONFIG" | "LAYOUT_CONFLICT" | "LAYOUT_INVARIANT_VIOLATION" | "AUDIO_MISSING_REQUIRED" | "AUDIO_INVALID_ARGUMENT" | "AUDIO_INVALID_CONFIG" | "AUDIO_CONFLICT" | "AUDIO_PLAYBACK_BLOCKED" | "PARTICLE_MISSING_REQUIRED" | "PARTICLE_INVALID_ARGUMENT" | "PARTICLE_INVALID_CONFIG" | "PARTICLE_INVARIANT_VIOLATION" | "PARTICLE_RUNTIME_FAILURE" | "PREFAB_MISSING_REQUIRED" | "PREFAB_INVALID_CONFIG" | "PREFAB_CONFLICT" | "PREFAB_INVARIANT_VIOLATION" | "FSM_INVALID_CONFIG" | "FSM_INVALID_STATE" | "COMMAND_MISSING_REQUIRED" | "COMMAND_INVALID_PAYLOAD" | "CONFIG_MISSING_REQUIRED" | "CONFIG_INVALID_ARGUMENT" | "CONFIG_INVALID_SCHEMA";
 export declare class EngineErrorCode {
 	static readonly CoreInvalidArgument = "CORE_INVALID_ARGUMENT";
 	static readonly CoreMissingRequired = "CORE_MISSING_REQUIRED";
@@ -4933,6 +4957,7 @@ export declare class EngineErrorCode {
 	static readonly AudioInvalidArgument = "AUDIO_INVALID_ARGUMENT";
 	static readonly AudioInvalidConfig = "AUDIO_INVALID_CONFIG";
 	static readonly AudioConflict = "AUDIO_CONFLICT";
+	static readonly AudioPlaybackBlocked = "AUDIO_PLAYBACK_BLOCKED";
 	static readonly ParticleMissingRequired = "PARTICLE_MISSING_REQUIRED";
 	static readonly ParticleInvalidArgument = "PARTICLE_INVALID_ARGUMENT";
 	static readonly ParticleInvalidConfig = "PARTICLE_INVALID_CONFIG";