@gamedevland/engine 0.0.9 → 0.0.10

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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.

package/README.md

@@ -12,8 +12,10 @@ Source files are available in [the SDK repository](https://github.com/gamedevlan
 
 ## Changelog
 
-**0.0.9** adds opt-in viewport-native rendering and a configurable canvas pixel
-budget. Existing DPR defaults stay the same.
+**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
@@ -132,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> {
@@ -4904,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";
@@ -4931,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";