@mpgd/game-runtime 0.4.0 → 0.6.0

package/README.md

@@ -471,3 +471,43 @@ while preserving original key history and any live native lease. Foreign keys,
 purchase actions, pending results and grant-shaped results cannot be unlocked
 through this path. Positive grants continue through the authoritative ledger
 reconciliation port. This method never updates a disposed view or opens UI.
+
+## Scene-owned DOM banners
+
+`@mpgd/game-runtime/dom` is an opt-in browser entrypoint. It consumes the canonical
+`PlatformGateway.ads` banner methods and imports no platform SDK. The root and
+other headless entrypoints retain their engine- and DOM-free declaration contracts.
+
+```ts
+import { createInlineBannerManager } from '@mpgd/game-runtime/dom';
+
+const banner = createInlineBannerManager({
+  gameRoot, ads: gateway.ads, enabled: bannerEnabled,
+  placementId: 'FOOTER', surfaceId: 'footer-ad', label: 'Advertisement',
+  layoutClassName: 'banner-layout', surfaceClassName: 'banner-surface',
+  stateDataKey: 'bannerState',
+});
+const release = banner.acquire({ onLayoutChange: resizeGame });
+// Scene shutdown: release(); final game teardown: banner.destroy();
+```
+
+Each mount adds an opaque unique suffix to the supplied surface namespace. The
+provider receives that actual DOM ID. A newer acquisition replaces the parent
+slot's previous owner (disposing a displaced manager), and a stale release or provider response only cleans up
+its own native surface. Layout is `loading` until the provider confirms `mounted`;
+style only the mounted state to reserve banner height. Unavailable/failed results
+collapse the surface and rely on the provider's terminal cleanup contract. The
+helper never selects placements, enables a target, supplies fallback advertising,
+or grants rewards.
+
+Page restoration renews the current acquisition, including hosts that do not use
+BFCache. Lifecycle listeners and elements use the game root's own document/window
+so embedded surfaces work independently. Release and destroy are idempotent;
+layout observer errors cannot interrupt cleanup and can be observed through
+`onObserverError`. The consumer owns CSS, banner dimensions, eligibility, and
+scene shutdown wiring. Importing the module creates no DOM or lifecycle listeners.
+
+## Impact feedback
+
+The opt-in `./impact` and `./phaser/impact` entries provide deterministic recipe
+matching and scene-owned pooled rendering. See [configuration and gotchas](docs/impact-feedback.md).

package/dist/ads/index.d.ts

@@ -1,4 +1,4 @@
-import type { PlatformEvidenceEnvelope, PlatformGateway, PurchaseResult } from '@mpgd/platform';
+import type { PlatformEvidenceEnvelope, PlatformGateway, PlatformPurchasePresentationEvent, PurchaseResult } from '@mpgd/platform';
 import type { GameServicesRewardedAdResult } from '@mpgd/game-services/operations';
 import { type AdPlacementInput, type AdProvider, type AdShowInput, type AdShowResult } from '@mpgd/platform/ads';
 import { type ObserverErrorHandler } from '../observers.js';
@@ -44,11 +44,7 @@ export declare function createCoordinatedAdProvider(input: {
     readonly result: AdShowResult;
   }) => void | Promise<void>;
 }): CoordinatedAdProvider;
-export interface PurchasePresentationEvent {
-  readonly idempotencyKey: string;
-  readonly sequence: number;
-  readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
-}
+export type PurchasePresentationEvent = PlatformPurchasePresentationEvent;
 export interface CoordinatedPlatformGateway extends PlatformGateway {
   dispose(): void;
 }

package/dist/ads/index.js

@@ -475,7 +475,8 @@ export function createCoordinatedPlatformGateway(input) {
         }
         maybeDetach();
     }
-    const unsubscribe = input.purchasePresentation?.subscribe((event) => {
+    const purchasePresentation = input.purchasePresentation ?? input.gateway.commerce.presentation;
+    const unsubscribe = purchasePresentation?.subscribe((event) => {
         observe(() => {
             const flight = purchases.get(event.idempotencyKey);
             if (flight === undefined || !flight.called || flight.closed) {

package/dist/dom/index.d.ts

@@ -0,0 +1 @@
+export { createInlineBannerManager, mountInlineBanner, type InlineBannerAds, type InlineBannerOptions, type InlineBannerController, type InlineBannerManager, } from './inline-banner.js';

package/dist/dom/index.js

@@ -0,0 +1 @@
+export { createInlineBannerManager, mountInlineBanner, } from './inline-banner.js';

package/dist/dom/inline-banner.d.ts

@@ -0,0 +1,31 @@
+import type { PlatformGateway } from '@mpgd/platform';
+import { type ObserverErrorHandler } from '../observers.js';
+export type InlineBannerAds = Pick<PlatformGateway['ads'], 'mountBanner' | 'unmountBanner'>;
+export interface InlineBannerOptions {
+  readonly gameRoot: HTMLElement;
+  readonly ads: InlineBannerAds;
+  readonly enabled: boolean;
+  readonly placementId: string;
+  /** Game-owned namespace; each mount appends a unique opaque suffix. */
+  readonly surfaceId: string;
+  readonly label: string;
+  readonly layoutClassName: string;
+  readonly surfaceClassName: string;
+  readonly stateDataKey: string;
+  readonly onObserverError?: ObserverErrorHandler;
+}
+export interface InlineBannerController {
+  readonly destroy: () => void;
+}
+export interface InlineBannerManager {
+  readonly acquire: (input?: {
+    readonly onLayoutChange?: () => void;
+  }) => () => void;
+  readonly destroy: () => void;
+}
+/** Scene-owned acquisition over the canonical gateway, with page-restore renewal. */
+export declare function createInlineBannerManager(input: InlineBannerOptions): InlineBannerManager;
+/** Reserve layout only after provider confirmation; asynchronous cleanup keeps its own ID. */
+export declare function mountInlineBanner(input: InlineBannerOptions & {
+  readonly onLayoutChange?: () => void;
+}): InlineBannerController;

package/dist/dom/inline-banner.js

@@ -0,0 +1,221 @@
+import { observe } from '../observers.js';
+// A parent represents one layout slot. A newer mount releases the previous owner.
+const parentOwners = new WeakMap();
+const parentManagers = new WeakMap();
+let nextSurfaceSequence = 0;
+/** Scene-owned acquisition over the canonical gateway, with page-restore renewal. */
+export function createInlineBannerManager(input) {
+    assertOptions(input);
+    let active = null;
+    let destroyed = false;
+    let acquisitionRevision = 0;
+    let restorePending = false;
+    let ownedParent = null;
+    const lifecycle = input.gameRoot.ownerDocument.defaultView;
+    const mount = (owner, onLayoutChange) => {
+        const controller = mountBannerSurface({
+            ...input,
+            ...(onLayoutChange === undefined ? {} : { onLayoutChange }),
+        }, destroyManager);
+        if (destroyed || owner.released || active !== null) {
+            controller.destroy();
+            return;
+        }
+        active = {
+            owner,
+            controller,
+            ...(onLayoutChange === undefined ? {} : { onLayoutChange }),
+        };
+    };
+    const onHide = () => {
+        restorePending = true;
+    };
+    const onShow = () => {
+        if (!restorePending) {
+            return;
+        }
+        restorePending = false;
+        if (destroyed || active === null) {
+            return;
+        }
+        const revision = acquisitionRevision;
+        const previous = active;
+        active = null;
+        previous.controller.destroy();
+        if (destroyed || previous.owner.released || acquisitionRevision !== revision) {
+            return;
+        }
+        mount(previous.owner, previous.onLayoutChange);
+    };
+    lifecycle?.addEventListener('pagehide', onHide);
+    lifecycle?.addEventListener('pageshow', onShow);
+    return {
+        acquire(acquisition = {}) {
+            if (destroyed) {
+                return () => { };
+            }
+            const revision = ++acquisitionRevision;
+            const parent = input.gameRoot.parentElement;
+            if (ownedParent !== null && ownedParent !== parent && parentManagers.get(ownedParent) === destroyManager) {
+                parentManagers.delete(ownedParent);
+            }
+            ownedParent = parent;
+            if (parent !== null) {
+                const previousManager = parentManagers.get(parent);
+                parentManagers.set(parent, destroyManager);
+                if (previousManager !== destroyManager) {
+                    previousManager?.();
+                }
+            }
+            if (destroyed || acquisitionRevision !== revision) {
+                return () => { };
+            }
+            const previous = active;
+            active = null;
+            previous?.controller.destroy();
+            if (destroyed || acquisitionRevision !== revision) {
+                return () => { };
+            }
+            const owner = { released: false };
+            mount(owner, acquisition.onLayoutChange);
+            let released = false;
+            return () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                owner.released = true;
+                if (active?.owner === owner) {
+                    const previous = active;
+                    active = null;
+                    previous.controller.destroy();
+                }
+            };
+        },
+        destroy: destroyManager,
+    };
+    function destroyManager() {
+        if (destroyed) {
+            return;
+        }
+        destroyed = true;
+        lifecycle?.removeEventListener('pagehide', onHide);
+        lifecycle?.removeEventListener('pageshow', onShow);
+        const previous = active;
+        active = null;
+        previous?.controller.destroy();
+        if (ownedParent !== null && parentManagers.get(ownedParent) === destroyManager) {
+            parentManagers.delete(ownedParent);
+        }
+        ownedParent = null;
+    }
+}
+/** Reserve layout only after provider confirmation; asynchronous cleanup keeps its own ID. */
+export function mountInlineBanner(input) {
+    return mountBannerSurface(input);
+}
+function mountBannerSurface(input, managerOwner) {
+    assertOptions(input);
+    const parent = input.gameRoot.parentElement;
+    const mountBanner = input.ads.mountBanner?.bind(input.ads);
+    const unmountBanner = input.ads.unmountBanner?.bind(input.ads);
+    if (!input.enabled || mountBanner === undefined || parent === null) {
+        return { destroy() { } };
+    }
+    const layoutParent = parent;
+    const doc = input.gameRoot.ownerDocument;
+    const random = doc.defaultView?.crypto ?? globalThis.crypto;
+    if (random === undefined) {
+        throw new Error('Inline banner surfaces require a crypto random source.');
+    }
+    const suffix = Array.from(random.getRandomValues(new Uint32Array(4)), (value) => value.toString(16).padStart(8, '0')).join('');
+    nextSurfaceSequence += 1;
+    const surfaceId = `${input.surfaceId}-${suffix}-${nextSurfaceSequence}`;
+    const surface = doc.createElement('aside');
+    surface.id = surfaceId;
+    surface.className = input.surfaceClassName;
+    surface.setAttribute('aria-label', input.label);
+    surface.dataset.adPlacement = input.placementId;
+    let destroyed = false;
+    let promise = null;
+    const notifyLayout = () => observe(() => input.onLayoutChange?.(), input.onObserverError);
+    const onHide = (event) => {
+        if (!event.persisted) {
+            destroy();
+        }
+    };
+    const lifecycle = doc.defaultView;
+    function destroy() {
+        if (destroyed) {
+            return;
+        }
+        destroyed = true;
+        surface.remove();
+        if (parentOwners.get(layoutParent) === destroy) {
+            parentOwners.delete(layoutParent);
+            layoutParent.classList.remove(input.layoutClassName);
+            delete layoutParent.dataset[input.stateDataKey];
+        }
+        lifecycle?.removeEventListener('pagehide', onHide);
+        if (unmountBanner !== undefined && promise !== null) {
+            void promise.then((result) => result.status === 'mounted' ? unmountBanner({ surfaceId }) : undefined, () => undefined).catch((error) => observe(() => { throw error; }, input.onObserverError));
+        }
+        notifyLayout();
+    }
+    const manager = parentManagers.get(layoutParent);
+    if (manager !== undefined && manager !== managerOwner) {
+        manager();
+    }
+    const previousOwner = parentOwners.get(layoutParent);
+    parentOwners.set(layoutParent, destroy);
+    previousOwner?.();
+    if (destroyed) {
+        return { destroy };
+    }
+    layoutParent.classList.add(input.layoutClassName);
+    layoutParent.dataset[input.stateDataKey] = 'loading';
+    layoutParent.append(surface);
+    lifecycle?.addEventListener('pagehide', onHide);
+    try {
+        const mounted = Promise.resolve(mountBanner({ placementId: input.placementId, surfaceId }));
+        promise = mounted;
+        void mounted.then((result) => {
+            if (destroyed) {
+                return;
+            }
+            if (result.status === 'mounted') {
+                layoutParent.dataset[input.stateDataKey] = 'mounted';
+                notifyLayout();
+            }
+            else {
+                destroy();
+            }
+        }, () => destroy());
+    }
+    catch {
+        destroy();
+    }
+    return { destroy };
+}
+function assertOptions(input) {
+    for (const name of [
+        'placementId',
+        'surfaceId',
+        'label',
+        'layoutClassName',
+        'surfaceClassName',
+        'stateDataKey',
+    ]) {
+        const value = input[name];
+        if (typeof value !== 'string' || !value.trim() || value.length > (name === 'surfaceId' ? 128 : 256)
+            || /[\u0000-\u001f\u007f]/u.test(value)) {
+            throw new TypeError(`Inline banner ${name} is invalid.`);
+        }
+    }
+    if (/\s/u.test(input.layoutClassName) || !/^[a-z][a-zA-Z0-9]*$/u.test(input.stateDataKey)) {
+        throw new TypeError('Inline banner layoutClassName must be a CSS token and stateDataKey a camel-case key.');
+    }
+    if (typeof input.enabled !== 'boolean') {
+        throw new TypeError('Inline banner enabled must be a boolean.');
+    }
+}

package/dist/game/index.d.ts

@@ -27,6 +27,9 @@ export interface GamePlatformRuntime<T extends PlatformGateway = PlatformGateway
   readonly services: S;
   readonly actions?: GameActionCoordinator;
   createGameplayScope(): GameGameplayScope;
+  setLoadingProgress(progress: number): void;
+  /** Complete host loading before opening a play scene. Rejected starts remain blocked. */
+  completeLoading(): Promise<void>;
   /** Reconcile existing journal entries only; this method never opens platform UI. */
   reconcile(): Promise<void>;
   /** Game teardown; native observers and application-owned late recovery may continue. */
@@ -44,4 +47,6 @@ export declare function createGamePlatformRuntime<T extends PlatformGateway, S e
     subscribe(listener: (event: PurchasePresentationEvent) => void): () => void;
   };
   readonly onObserverError?: ObserverErrorHandler;
+  /** Must complete synchronously; asynchronous uploads belong at earlier checkpoints. */
+  readonly onExit?: () => void;
 }): GamePlatformRuntime<T, S>;

package/dist/game/index.js

@@ -39,6 +39,47 @@ export function createGamePlatformRuntime(input) {
     let actions;
     let unsubscribeResume;
     let disposed = false;
+    let unsubscribeExit;
+    let startupBlock = input.gateway.gameLoading === undefined
+        ? undefined
+        : execution.acquireBlock({
+            reason: 'game-runtime:loading',
+            channels: ['simulation', 'gameplay-input', 'audio'],
+        });
+    let loadingCompletion;
+    const setLoadingProgress = (progress) => {
+        if (!disposed && loadingCompletion === undefined) {
+            observe(() => gateway.gameLoading?.setProgress(Math.max(0, Math.min(100, Number(progress) || 0))), input.onObserverError);
+        }
+    };
+    const completeLoading = () => {
+        if (disposed) {
+            return Promise.reject(new Error('Game runtime is disposed.'));
+        }
+        if (loadingCompletion !== undefined) {
+            return loadingCompletion;
+        }
+        const attempt = Promise.resolve().then(async () => {
+            if (disposed) {
+                throw new Error('Game runtime is disposed.');
+            }
+            gateway.gameLoading?.setProgress(100);
+            await gateway.gameLoading?.complete();
+            if (disposed) {
+                throw new Error('Game runtime was disposed during loading.');
+            }
+            const owned = startupBlock;
+            startupBlock = undefined;
+            owned?.release();
+        });
+        loadingCompletion = attempt;
+        void attempt.catch(() => {
+            if (loadingCompletion === attempt) {
+                loadingCompletion = undefined;
+            }
+        });
+        return attempt;
+    };
     let hostAudio;
     let unsubscribeHostAudio;
     const gameplayScopes = new Map();
@@ -108,6 +149,7 @@ export function createGamePlatformRuntime(input) {
             }, input.onObserverError);
         }
         unsubscribeActivity?.();
+        unsubscribeExit?.();
         gameplayScopes.clear();
         execution.destroy();
         if (unsubscribeHostAudio !== undefined) {
@@ -156,6 +198,14 @@ export function createGamePlatformRuntime(input) {
             ...(input.onObserverError === undefined ? {} : { onError: input.onObserverError }),
         });
         unsubscribeResume = gateway.lifecycle.onResume(() => { observe(reconcile, input.onObserverError); });
+        unsubscribeExit = gateway.lifecycle.onExit?.(() => {
+            observe(() => input.onExit?.(), input.onObserverError);
+            dispose();
+        });
+        if (disposed) {
+            unsubscribeExit?.();
+            throw new Error('Game exited during runtime initialization.');
+        }
         const settings = gateway.gameSettings;
         if (settings !== undefined) {
             const updateMute = (muted) => {
@@ -182,6 +232,8 @@ export function createGamePlatformRuntime(input) {
             presentation,
             services,
             createGameplayScope,
+            setLoadingProgress,
+            completeLoading,
             ...(actions === undefined ? {} : { actions }),
             reconcile,
             dispose,

package/dist/impact/index.d.ts

@@ -0,0 +1,85 @@
+export interface ImpactParticipant {
+  readonly id?: number | string;
+  readonly kind: string;
+  readonly tags?: readonly string[];
+}
+export interface ImpactContact {
+  readonly atMs: number;
+  readonly intensity: number;
+  readonly normalX: number;
+  readonly normalY: number;
+  readonly source: ImpactParticipant;
+  readonly target: ImpactParticipant;
+  readonly x: number;
+  readonly y: number;
+}
+export interface CreateImpactContactInput {
+  readonly atMs: number;
+  readonly intensity?: number;
+  readonly normalX?: number;
+  readonly normalY?: number;
+  readonly source: ImpactParticipant;
+  readonly target: ImpactParticipant;
+  readonly x: number;
+  readonly y: number;
+}
+export interface ImpactParticipantSelector {
+  readonly kinds?: readonly string[];
+  readonly tags?: readonly string[];
+}
+export interface ImpactFeedbackRule {
+  readonly id: string;
+  readonly priority?: number;
+  readonly recipeId: string;
+  readonly source?: ImpactParticipantSelector;
+  readonly target?: ImpactParticipantSelector;
+}
+export interface ImpactRingRecipe {
+  readonly color: number;
+  readonly endAlpha?: number;
+  readonly endRadius: number;
+  readonly lineWidth?: number;
+  readonly startAlpha?: number;
+  readonly startRadius: number;
+}
+export interface ImpactSparkRecipe {
+  /** Local geometry, oriented along the contact normal and the authored spread. */
+  readonly shape?: 'line' | 'chevron' | 'bracket' | 'cross';
+  readonly color: number;
+  readonly count: number;
+  readonly endDistance: number;
+  readonly length: number;
+  readonly spreadRadians: number;
+  readonly startDistance?: number;
+  readonly width: number;
+}
+export interface ImpactFlashRecipe {
+  readonly color: number;
+  readonly durationMs: number;
+}
+export interface ImpactFeedbackRecipe {
+  readonly durationMs: number;
+  readonly flash?: ImpactFlashRecipe;
+  readonly id: string;
+  readonly ring?: ImpactRingRecipe;
+  readonly sparks?: ImpactSparkRecipe;
+}
+export interface ImpactFeedbackCatalogInput {
+  readonly recipes: readonly ImpactFeedbackRecipe[];
+  readonly rules: readonly ImpactFeedbackRule[];
+}
+export interface ImpactFeedbackCatalog {
+  readonly recipes: ReadonlyMap<string, ImpactFeedbackRecipe>;
+  readonly rules: readonly ImpactFeedbackRule[];
+}
+export interface ImpactFeedbackCarrier {
+  readonly impact: ImpactContact;
+}
+export declare const MAX_IMPACT_RECIPES = 256;
+export declare const MAX_IMPACT_RULES = 1024;
+export declare function createImpactContact(input: CreateImpactContactInput): ImpactContact;
+export declare function defineImpactFeedbackCatalog(input: ImpactFeedbackCatalogInput): ImpactFeedbackCatalog;
+export declare function resolveImpactFeedbackRecipe(catalog: ImpactFeedbackCatalog, contact: ImpactContact): ImpactFeedbackRecipe | undefined;
+export declare function hasImpactFeedback(value: unknown): value is ImpactFeedbackCarrier;
+export declare function assertImpactFeedbackRecipe(recipe: ImpactFeedbackRecipe): void;
+export declare function assertImpactContact(contact: ImpactContact): void;

package/dist/impact/index.js

@@ -0,0 +1,229 @@
+export const MAX_IMPACT_RECIPES = 256;
+export const MAX_IMPACT_RULES = 1_024;
+const sparkShapes = ['line', 'chevron', 'bracket', 'cross'];
+const DEFAULT_NORMAL_X = 0;
+const DEFAULT_NORMAL_Y = -1;
+export function createImpactContact(input) {
+    assertNonNegative('atMs', input.atMs);
+    assertParticipant(input.source);
+    assertParticipant(input.target);
+    assertFinite('x', input.x);
+    assertFinite('y', input.y);
+    const intensity = input.intensity ?? 1;
+    assertFinite('intensity', intensity);
+    if (intensity < 0) {
+        throw new Error('Impact intensity must be greater than or equal to zero.');
+    }
+    const normalX = input.normalX ?? DEFAULT_NORMAL_X;
+    const normalY = input.normalY ?? DEFAULT_NORMAL_Y;
+    assertFinite('normalX', normalX);
+    assertFinite('normalY', normalY);
+    const scale = Math.max(Math.abs(normalX), Math.abs(normalY));
+    const length = scale === 0 ? 0 : Math.hypot(normalX / scale, normalY / scale);
+    return {
+        atMs: input.atMs,
+        intensity,
+        normalX: length > 0 ? (normalX / scale) / length : DEFAULT_NORMAL_X,
+        normalY: length > 0 ? (normalY / scale) / length : DEFAULT_NORMAL_Y,
+        source: input.source,
+        target: input.target,
+        x: input.x,
+        y: input.y,
+    };
+}
+export function defineImpactFeedbackCatalog(input) {
+    if (!Array.isArray(input.recipes) || input.recipes.length > MAX_IMPACT_RECIPES
+        || !Array.isArray(input.rules) || input.rules.length > MAX_IMPACT_RULES) {
+        throw new Error('Impact catalog exceeds recipe or rule bounds.');
+    }
+    const recipes = new Map();
+    for (const recipe of input.recipes) {
+        assertIdentifier('recipe', recipe.id);
+        if (recipes.has(recipe.id)) {
+            throw new Error(`Duplicate impact feedback recipe id: ${recipe.id}`);
+        }
+        assertImpactFeedbackRecipe(recipe);
+        recipes.set(recipe.id, Object.freeze({
+            ...recipe,
+            ...(recipe.ring === undefined ? {} : { ring: Object.freeze({ ...recipe.ring }) }),
+            ...(recipe.sparks === undefined ? {} : { sparks: Object.freeze({ ...recipe.sparks }) }),
+            ...(recipe.flash === undefined ? {} : { flash: Object.freeze({ ...recipe.flash }) }),
+        }));
+    }
+    const ruleIds = new Set();
+    for (const rule of input.rules) {
+        assertIdentifier('rule', rule.id);
+        assertFinite('rule.priority', rule.priority ?? 0);
+        assertSelector(rule.source);
+        assertSelector(rule.target);
+        if (ruleIds.has(rule.id)) {
+            throw new Error(`Duplicate impact feedback rule id: ${rule.id}`);
+        }
+        if (!recipes.has(rule.recipeId)) {
+            throw new Error(`Impact feedback rule ${rule.id} references unknown recipe: ${rule.recipeId}`);
+        }
+        ruleIds.add(rule.id);
+    }
+    const rules = input.rules
+        .map((rule, index) => ({ index, rule }))
+        .sort((left, right) => (right.rule.priority ?? 0) - (left.rule.priority ?? 0) || left.index - right.index)
+        .map(({ rule }) => Object.freeze({
+        ...rule,
+        ...(rule.source === undefined ? {} : { source: cloneSelector(rule.source) }),
+        ...(rule.target === undefined ? {} : { target: cloneSelector(rule.target) }),
+    }));
+    return Object.freeze({ recipes, rules: Object.freeze(rules) });
+}
+export function resolveImpactFeedbackRecipe(catalog, contact) {
+    for (const rule of catalog.rules) {
+        if (participantMatches(contact.source, rule.source)
+            && participantMatches(contact.target, rule.target)) {
+            return catalog.recipes.get(rule.recipeId);
+        }
+    }
+    return undefined;
+}
+export function hasImpactFeedback(value) {
+    if (typeof value !== 'object' || value === null || !('impact' in value)) {
+        return false;
+    }
+    try {
+        assertImpactContact(value.impact);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function participantMatches(participant, selector) {
+    if (selector === undefined) {
+        return true;
+    }
+    if (selector.kinds !== undefined && !selector.kinds.includes(participant.kind)) {
+        return false;
+    }
+    if (selector.tags === undefined) {
+        return true;
+    }
+    const tags = participant.tags ?? [];
+    return selector.tags.every((tag) => tags.includes(tag));
+}
+export function assertImpactFeedbackRecipe(recipe) {
+    assertPositive('durationMs', recipe.durationMs);
+    if (recipe.ring !== undefined) {
+        assertColor('ring.color', recipe.ring.color);
+        assertNonNegative('ring.startRadius', recipe.ring.startRadius);
+        assertNonNegative('ring.endRadius', recipe.ring.endRadius);
+        assertNonNegative('ring.lineWidth', recipe.ring.lineWidth ?? 2);
+        assertUnitInterval('ring.startAlpha', recipe.ring.startAlpha ?? 1);
+        assertUnitInterval('ring.endAlpha', recipe.ring.endAlpha ?? 0);
+    }
+    if (recipe.sparks !== undefined) {
+        if (recipe.sparks.shape !== undefined
+            && !sparkShapes.includes(recipe.sparks.shape)) {
+            throw new Error('Impact recipe sparks.shape must be line, chevron, bracket or cross.');
+        }
+        assertColor('sparks.color', recipe.sparks.color);
+        if (!Number.isInteger(recipe.sparks.count) || recipe.sparks.count < 0 || recipe.sparks.count > 64) {
+            throw new Error('Impact recipe sparks.count must be a non-negative integer.');
+        }
+        assertNonNegative('sparks.startDistance', recipe.sparks.startDistance ?? 0);
+        assertNonNegative('sparks.endDistance', recipe.sparks.endDistance);
+        assertPositive('sparks.length', recipe.sparks.length);
+        assertPositive('sparks.width', recipe.sparks.width);
+        assertFinite('sparks.spreadRadians', recipe.sparks.spreadRadians);
+    }
+    if (recipe.flash !== undefined) {
+        assertColor('flash.color', recipe.flash.color);
+        assertPositive('flash.durationMs', recipe.flash.durationMs);
+    }
+    if (recipe.ring === undefined && recipe.sparks === undefined && recipe.flash === undefined) {
+        throw new Error(`Impact feedback recipe ${recipe.id} must define at least one effect.`);
+    }
+}
+function assertIdentifier(kind, value) {
+    if (typeof value !== 'string' || value.trim().length === 0 || value.length > 256) {
+        throw new Error(`Impact feedback ${kind} id must not be empty.`);
+    }
+}
+function assertColor(name, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffff) {
+        throw new Error(`Impact recipe ${name} must be an integer between 0x000000 and 0xffffff.`);
+    }
+}
+function assertFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`Impact ${name} must be finite.`);
+    }
+}
+function assertNonNegative(name, value) {
+    assertFinite(name, value);
+    if (value < 0) {
+        throw new Error(`Impact recipe ${name} must be greater than or equal to zero.`);
+    }
+}
+function assertPositive(name, value) {
+    assertFinite(name, value);
+    if (value <= 0) {
+        throw new Error(`Impact recipe ${name} must be greater than zero.`);
+    }
+}
+function assertUnitInterval(name, value) {
+    assertFinite(name, value);
+    if (value < 0 || value > 1) {
+        throw new Error(`Impact recipe ${name} must be between zero and one.`);
+    }
+}
+export function assertImpactContact(contact) {
+    if (typeof contact !== 'object' || contact === null) {
+        throw new Error('Impact contact must be an object.');
+    }
+    assertNonNegative('atMs', contact.atMs);
+    assertNonNegative('intensity', contact.intensity);
+    assertFinite('x', contact.x);
+    assertFinite('y', contact.y);
+    assertFinite('normalX', contact.normalX);
+    assertFinite('normalY', contact.normalY);
+    assertParticipant(contact.source);
+    assertParticipant(contact.target);
+}
+function assertParticipant(participant) {
+    if (typeof participant !== 'object' || participant === null) {
+        throw new Error('Impact participant must be an object.');
+    }
+    assertIdentifier('participant kind', participant.kind);
+    if (participant.id !== undefined && typeof participant.id !== 'string' && typeof participant.id !== 'number') {
+        throw new Error('Impact participant id must be a string or number.');
+    }
+    if (typeof participant.id === 'number') {
+        assertFinite('participant id', participant.id);
+    }
+    assertLabels(participant.tags);
+}
+function assertLabels(labels) {
+    if (labels === undefined) {
+        return;
+    }
+    if (!Array.isArray(labels) || labels.length > 64) {
+        throw new Error('Impact selectors and tags are limited to 64 labels.');
+    }
+    for (const label of labels) {
+        assertIdentifier('label', label);
+    }
+}
+function assertSelector(selector) {
+    if (selector === undefined) {
+        return;
+    }
+    if (typeof selector !== 'object' || selector === null) {
+        throw new Error('Impact selector must be an object.');
+    }
+    assertLabels(selector.kinds);
+    assertLabels(selector.tags);
+}
+function cloneSelector(selector) {
+    return Object.freeze({
+        ...(selector.kinds === undefined ? {} : { kinds: Object.freeze([...selector.kinds]) }),
+        ...(selector.tags === undefined ? {} : { tags: Object.freeze([...selector.tags]) }),
+    });
+}

package/dist/phaser/impact.d.ts

@@ -0,0 +1,50 @@
+import type Phaser from 'phaser';
+import { type ImpactContact, type ImpactFeedbackRecipe } from '../impact/index.js';
+export interface PhaserImpactFeedbackPoolOptions {
+  readonly capacity?: number;
+  readonly depth?: number;
+  readonly maxSparksPerEffect?: number;
+  readonly rasterRings?: {
+    readonly textureKey: string;
+    /** A static frame or a registered strip sampled using the existing effect clock. */
+    readonly recipeFrames: Readonly<Record<string, string | readonly string[]>>;
+  };
+}
+export interface PhaserImpactFeedbackPoolDiagnostics {
+  readonly activeEffects: number;
+  readonly availableEffects: number;
+  readonly capacity: number;
+  readonly emittedEffects: number;
+  readonly peakActiveEffects: number;
+  readonly recycledEffects: number;
+}
+export declare const MAX_IMPACT_POOL_CAPACITY = 1024;
+export declare const MAX_IMPACT_POOL_SPARKS = 64;
+export declare class PhaserImpactFeedbackPool {
+  private readonly scene;
+  private activeSparkEffects;
+  private readonly activeSlots;
+  private destroyed;
+  private emittedEffects;
+  private flashEndsAtMs;
+  private nextSlotIndex;
+  private peakActiveEffects;
+  private recycledEffects;
+  private readonly slots;
+  private readonly availableSlots;
+  private readonly sparkBatch;
+  private sparkBatchVisible;
+  private readonly rasterRings;
+  constructor(scene: Phaser.Scene, options?: PhaserImpactFeedbackPoolOptions);
+  emit(contact: ImpactContact, recipe: ImpactFeedbackRecipe): void;
+  update(nowMs: number): void;
+  diagnostics(): PhaserImpactFeedbackPoolDiagnostics;
+  /** Release every live effect without destroying the prewarmed pool. */
+  clear(): void;
+  readonly destroy: () => void;
+  private activateRecipe;
+  private updateRecipe;
+  private renderSparkBatch;
+  private hideSparkBatch;
+  private release;
+}

package/dist/phaser/impact.js

@@ -0,0 +1,406 @@
+import { assertImpactContact, assertImpactFeedbackRecipe, } from '../impact/index.js';
+export const MAX_IMPACT_POOL_CAPACITY = 1_024;
+export const MAX_IMPACT_POOL_SPARKS = 64;
+const DEFAULT_CAPACITY = 48;
+const DEFAULT_MAX_SPARKS = 6;
+const DEFAULT_DEPTH = 40;
+export class PhaserImpactFeedbackPool {
+    scene;
+    activeSparkEffects = 0;
+    activeSlots = [];
+    destroyed = false;
+    emittedEffects = 0;
+    flashEndsAtMs = Number.NEGATIVE_INFINITY;
+    nextSlotIndex = 0;
+    peakActiveEffects = 0;
+    recycledEffects = 0;
+    slots;
+    availableSlots;
+    sparkBatch;
+    sparkBatchVisible = false;
+    rasterRings;
+    constructor(scene, options = {}) {
+        this.scene = scene;
+        const capacity = requirePositiveInteger('capacity', options.capacity ?? DEFAULT_CAPACITY);
+        const maxSparks = requireNonNegativeInteger('maxSparksPerEffect', options.maxSparksPerEffect ?? DEFAULT_MAX_SPARKS);
+        const depth = options.depth ?? DEFAULT_DEPTH;
+        if (!Number.isFinite(depth)) {
+            throw new Error('Impact depth must be finite.');
+        }
+        this.rasterRings = copyRasterRings(options.rasterRings);
+        if (this.rasterRings !== undefined) {
+            if (Object.keys(this.rasterRings.recipeFrames).length > 256) {
+                throw new Error('Impact art mappings are limited to 256 recipes.');
+            }
+            const texture = scene.textures.get(this.rasterRings.textureKey);
+            for (const entry of Object.values(this.rasterRings.recipeFrames)) {
+                const frames = typeof entry === 'string' ? [entry] : entry;
+                if (frames.length === 0 || frames.length > 64) {
+                    throw new Error('Impact art sequence must not be empty.');
+                }
+                for (const frame of frames) {
+                    if (!texture.has(frame)) {
+                        throw new Error(`Impact art frame is unavailable: ${frame}`);
+                    }
+                }
+            }
+        }
+        this.slots = Array.from({ length: capacity }, (_, index) => {
+            const ring = scene.add
+                .circle(0, 0, 1, 0xffffff, 0)
+                .setStrokeStyle(2, 0xffffff, 1)
+                .setDepth(depth)
+                .setActive(false)
+                .setVisible(false);
+            return {
+                index,
+                active: false,
+                activeIndex: -1,
+                endsAtMs: 0,
+                intensity: 1,
+                ring,
+                rasterRing: options.rasterRings === undefined ? undefined : scene.add
+                    .image(0, 0, options.rasterRings.textureKey)
+                    .setDepth(depth).setActive(false).setVisible(false),
+                rasterRingVisible: false,
+                rasterFrames: undefined,
+                rasterFrameIndex: 0,
+                ringAlphaDelta: 0,
+                ringRadiusDelta: 0,
+                ringStartAlpha: 0,
+                ringStartRadius: 0,
+                ringVisible: false,
+                sparkAlpha: 0,
+                sparkColor: 0xffffff,
+                sparkCount: 0,
+                sparkDistance: 0,
+                sparkDistanceDelta: 0,
+                sparkDirectionX: Array.from({ length: maxSparks }, () => 0),
+                sparkDirectionY: Array.from({ length: maxSparks }, () => -1),
+                sparkLength: 0,
+                sparkRenderedLength: 0,
+                sparkStartDistance: 0,
+                sparkWidth: 0,
+                sparkShape: 'line',
+                startsAtMs: 0,
+                x: 0,
+                y: 0,
+            };
+        });
+        this.availableSlots = [...this.slots].reverse();
+        this.sparkBatch = scene.add
+            .graphics()
+            .setDepth(depth)
+            .setActive(false)
+            .setVisible(false);
+        scene.events.once('shutdown', this.destroy);
+        scene.events.once('destroy', this.destroy);
+    }
+    emit(contact, recipe) {
+        if (this.destroyed) {
+            return;
+        }
+        assertImpactContact(contact);
+        assertImpactFeedbackRecipe(recipe);
+        if (!Number.isFinite(contact.atMs + recipe.durationMs)
+            || (recipe.flash !== undefined && !Number.isFinite(contact.atMs + recipe.flash.durationMs))) {
+            throw new Error('Impact end time must be finite.');
+        }
+        const slot = this.availableSlots.pop() ?? this.slots[this.nextSlotIndex];
+        this.nextSlotIndex = (slot.index + 1) % this.slots.length;
+        if (slot.active) {
+            this.recycledEffects += 1;
+        }
+        else {
+            slot.active = true;
+            slot.activeIndex = this.activeSlots.length;
+            this.activeSlots.push(slot);
+            this.peakActiveEffects = Math.max(this.peakActiveEffects, this.activeSlots.length);
+        }
+        slot.endsAtMs = contact.atMs + recipe.durationMs;
+        slot.intensity = Math.max(0.35, Math.min(2.5, contact.intensity));
+        slot.startsAtMs = contact.atMs;
+        slot.x = contact.x;
+        slot.y = contact.y;
+        this.emittedEffects += 1;
+        this.activateRecipe(slot, contact, recipe);
+        if (recipe.flash !== undefined
+            && contact.atMs >= this.flashEndsAtMs) {
+            const { color, durationMs } = recipe.flash;
+            this.flashEndsAtMs = contact.atMs + durationMs;
+            this.scene.cameras.main.flash(durationMs, (color >> 16) & 0xff, (color >> 8) & 0xff, color & 0xff, false);
+        }
+    }
+    update(nowMs) {
+        if (this.destroyed || !Number.isFinite(nowMs)) {
+            return;
+        }
+        for (let index = this.activeSlots.length - 1; index >= 0; index -= 1) {
+            const slot = this.activeSlots[index];
+            const durationMs = slot.endsAtMs - slot.startsAtMs;
+            if (nowMs >= slot.endsAtMs || durationMs <= 0) {
+                this.release(slot);
+                continue;
+            }
+            const progress = Math.max(0, Math.min(1, (nowMs - slot.startsAtMs) / durationMs));
+            this.updateRecipe(slot, easeOutCubic(progress), progress);
+        }
+        this.renderSparkBatch();
+    }
+    diagnostics() {
+        return {
+            activeEffects: this.activeSlots.length,
+            availableEffects: this.slots.length - this.activeSlots.length,
+            capacity: this.slots.length,
+            emittedEffects: this.emittedEffects,
+            peakActiveEffects: this.peakActiveEffects,
+            recycledEffects: this.recycledEffects,
+        };
+    }
+    /** Release every live effect without destroying the prewarmed pool. */
+    clear() {
+        if (this.destroyed) {
+            return;
+        }
+        while (this.activeSlots.length > 0) {
+            const slot = this.activeSlots[this.activeSlots.length - 1];
+            this.release(slot);
+        }
+        this.activeSparkEffects = 0;
+        if (this.sparkBatchVisible) {
+            this.hideSparkBatch();
+        }
+        this.flashEndsAtMs = Number.NEGATIVE_INFINITY;
+    }
+    destroy = () => {
+        if (this.destroyed) {
+            return;
+        }
+        this.clear();
+        this.destroyed = true;
+        this.scene.events.off('shutdown', this.destroy);
+        this.scene.events.off('destroy', this.destroy);
+        for (const slot of this.slots) {
+            slot.ring.destroy();
+            slot.rasterRing?.destroy();
+            slot.active = false;
+            slot.activeIndex = -1;
+        }
+        this.sparkBatch.destroy();
+        this.activeSparkEffects = 0;
+        this.activeSlots.length = 0;
+        this.availableSlots.length = 0;
+    };
+    activateRecipe(slot, contact, recipe) {
+        const { intensity } = slot;
+        const hadSparks = slot.sparkCount > 0;
+        const ring = recipe.ring;
+        const rasterEntry = this.rasterRings?.recipeFrames[recipe.id];
+        slot.rasterFrames = typeof rasterEntry === 'string' ? undefined : rasterEntry;
+        slot.rasterFrameIndex = 0;
+        const rasterFrame = typeof rasterEntry === 'string' ? rasterEntry : rasterEntry?.[0];
+        slot.rasterRingVisible = ring !== undefined && rasterFrame !== undefined;
+        slot.rasterRing?.setActive(slot.rasterRingVisible).setVisible(slot.rasterRingVisible);
+        if (slot.rasterRingVisible && rasterFrame !== undefined) {
+            slot.rasterRing?.setFrame(rasterFrame).setPosition(slot.x, slot.y);
+        }
+        if (ring === undefined) {
+            slot.ringVisible = false;
+            slot.ring.setActive(false).setVisible(false);
+        }
+        else {
+            slot.ringStartAlpha = ring.startAlpha ?? 1;
+            slot.ringAlphaDelta = (ring.endAlpha ?? 0) - slot.ringStartAlpha;
+            slot.ringStartRadius = ring.startRadius * intensity;
+            slot.ringRadiusDelta = (ring.endRadius - ring.startRadius) * intensity;
+            slot.ringVisible = true;
+            slot.ring
+                .setPosition(slot.x, slot.y)
+                .setRadius(slot.ringStartRadius)
+                .setFillStyle(ring.color, 0.12)
+                .setStrokeStyle(ring.lineWidth ?? 2, ring.color, 1)
+                .setAlpha(slot.ringStartAlpha)
+                .setActive(!slot.rasterRingVisible)
+                .setVisible(!slot.rasterRingVisible);
+            slot.rasterRing?.setDisplaySize(slot.ringStartRadius * 2, slot.ringStartRadius * 2)
+                .setAlpha(slot.ringStartAlpha);
+        }
+        const recipeSparks = recipe.sparks;
+        const sparkCount = Math.min(recipeSparks?.count ?? 0, slot.sparkDirectionX.length);
+        slot.sparkCount = sparkCount;
+        if (hadSparks !== (sparkCount > 0)) {
+            this.activeSparkEffects += sparkCount > 0 ? 1 : -1;
+        }
+        if (recipeSparks !== undefined) {
+            slot.sparkShape = recipeSparks.shape ?? 'line';
+            slot.sparkAlpha = 1;
+            slot.sparkColor = recipeSparks.color;
+            slot.sparkDistance = (recipeSparks.startDistance ?? 0) * intensity;
+            slot.sparkStartDistance = (recipeSparks.startDistance ?? 0) * intensity;
+            slot.sparkDistanceDelta =
+                (recipeSparks.endDistance - (recipeSparks.startDistance ?? 0)) * intensity;
+            slot.sparkLength = recipeSparks.length * intensity;
+            slot.sparkRenderedLength = slot.sparkLength;
+            slot.sparkWidth = recipeSparks.width;
+        }
+        const normalAngle = sparkCount > 0 ? Math.atan2(contact.normalY, contact.normalX) : 0;
+        for (let index = 0; recipeSparks !== undefined && index < sparkCount; index += 1) {
+            const angleRatio = sparkCount <= 1 ? 0.5 : index / (sparkCount - 1);
+            const angle = normalAngle + (angleRatio - 0.5) * recipeSparks.spreadRadians;
+            slot.sparkDirectionX[index] = Math.cos(angle);
+            slot.sparkDirectionY[index] = Math.sin(angle);
+        }
+    }
+    updateRecipe(slot, progress, frameProgress) {
+        if (slot.ringVisible) {
+            const radius = slot.ringStartRadius + slot.ringRadiusDelta * progress;
+            const alpha = slot.ringStartAlpha + slot.ringAlphaDelta * progress;
+            if (slot.rasterRingVisible) {
+                if (slot.rasterFrames !== undefined) {
+                    const count = slot.rasterFrames.length;
+                    const index = Math.min(count - 1, Math.floor(frameProgress * count));
+                    const frame = slot.rasterFrames[index];
+                    if (index !== slot.rasterFrameIndex && frame !== undefined) {
+                        slot.rasterRing?.setFrame(frame);
+                        slot.rasterFrameIndex = index;
+                    }
+                }
+                slot.rasterRing?.setDisplaySize(radius * 2, radius * 2).setAlpha(alpha);
+            }
+            else {
+                slot.ring.setRadius(radius).setAlpha(alpha);
+            }
+        }
+        const distance = slot.sparkStartDistance + slot.sparkDistanceDelta * progress;
+        const linearAlpha = 1 - (slot.sparkShape === 'line' ? progress : frameProgress);
+        slot.sparkAlpha = linearAlpha * linearAlpha;
+        slot.sparkDistance = distance;
+        slot.sparkRenderedLength = slot.sparkShape === 'bracket' || slot.sparkShape === 'cross'
+            ? slot.sparkLength
+            : slot.sparkLength * (1 - progress * 0.45);
+    }
+    renderSparkBatch() {
+        if (this.activeSparkEffects === 0) {
+            if (this.sparkBatchVisible) {
+                this.hideSparkBatch();
+            }
+            return;
+        }
+        this.sparkBatch.clear();
+        for (const slot of this.activeSlots) {
+            if (slot.sparkCount === 0 || slot.sparkAlpha <= 0 || slot.sparkRenderedLength <= 0) {
+                continue;
+            }
+            const halfLength = slot.sparkRenderedLength / 2;
+            this.sparkBatch.lineStyle(slot.sparkWidth, slot.sparkColor, slot.sparkAlpha);
+            this.sparkBatch.beginPath();
+            for (let index = 0; index < slot.sparkCount; index += 1) {
+                const directionX = slot.sparkDirectionX[index] ?? 0;
+                const directionY = slot.sparkDirectionY[index] ?? 0;
+                const centerX = slot.x + directionX * slot.sparkDistance;
+                const centerY = slot.y + directionY * slot.sparkDistance;
+                if (slot.sparkShape !== 'line') {
+                    // Reuse the same Graphics batch and precomputed directions: no per-hit objects.
+                    const motion = slot.sparkDistanceDelta < 0 ? -1 : 1;
+                    const dx = directionX * halfLength;
+                    const dy = directionY * halfLength;
+                    const px = -dy;
+                    const py = dx;
+                    if (slot.sparkShape === 'chevron') {
+                        this.sparkBatch.moveTo(centerX - dx * motion + px, centerY - dy * motion + py);
+                        this.sparkBatch.lineTo(centerX + dx * motion, centerY + dy * motion);
+                        this.sparkBatch.lineTo(centerX - dx * motion - px, centerY - dy * motion - py);
+                    }
+                    else if (slot.sparkShape === 'bracket') {
+                        this.sparkBatch.moveTo(centerX + dx - px, centerY + dy - py);
+                        this.sparkBatch.lineTo(centerX + dx + px, centerY + dy + py);
+                        this.sparkBatch.lineTo(centerX - dx + px, centerY - dy + py);
+                    }
+                    else {
+                        this.sparkBatch.moveTo(centerX - dx, centerY - dy);
+                        this.sparkBatch.lineTo(centerX + dx, centerY + dy);
+                        this.sparkBatch.moveTo(centerX - px, centerY - py);
+                        this.sparkBatch.lineTo(centerX + px, centerY + py);
+                    }
+                    continue;
+                }
+                this.sparkBatch.moveTo(centerX - directionX * halfLength, centerY - directionY * halfLength);
+                this.sparkBatch.lineTo(centerX + directionX * halfLength, centerY + directionY * halfLength);
+            }
+            this.sparkBatch.strokePath();
+        }
+        if (!this.sparkBatchVisible) {
+            this.sparkBatch.setActive(true).setVisible(true);
+            this.sparkBatchVisible = true;
+        }
+    }
+    hideSparkBatch() {
+        this.sparkBatch.clear().setActive(false).setVisible(false);
+        this.sparkBatchVisible = false;
+    }
+    release(slot) {
+        slot.active = false;
+        slot.ring.setActive(false).setVisible(false);
+        slot.rasterRing?.setActive(false).setVisible(false);
+        slot.rasterRingVisible = false;
+        slot.rasterFrames = undefined;
+        slot.rasterFrameIndex = 0;
+        if (slot.sparkCount > 0) {
+            this.activeSparkEffects -= 1;
+            slot.sparkCount = 0;
+        }
+        const activeIndex = slot.activeIndex;
+        const lastSlot = this.activeSlots.pop();
+        if (lastSlot !== undefined && lastSlot !== slot) {
+            this.activeSlots[activeIndex] = lastSlot;
+            lastSlot.activeIndex = activeIndex;
+        }
+        slot.activeIndex = -1;
+        this.availableSlots.push(slot);
+    }
+}
+function easeOutCubic(value) {
+    return 1 - (1 - value) ** 3;
+}
+function requireNonNegativeInteger(name, value) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_IMPACT_POOL_SPARKS) {
+        throw new Error(`Phaser impact feedback ${name} must be a non-negative integer.`);
+    }
+    return value;
+}
+function requirePositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value <= 0 || value > MAX_IMPACT_POOL_CAPACITY) {
+        throw new Error(`Phaser impact feedback ${name} must be a positive integer.`);
+    }
+    return value;
+}
+function copyRasterRings(input) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (typeof input.textureKey !== 'string' || input.textureKey.length === 0
+        || input.textureKey.length > 256) {
+        throw new Error('Impact texture key is invalid.');
+    }
+    const keys = Object.keys(input.recipeFrames);
+    if (keys.length > 256) {
+        throw new Error('Impact art mappings are limited to 256 recipes.');
+    }
+    const frames = Object.create(null);
+    for (const key of keys) {
+        const entry = input.recipeFrames[key];
+        if (key.length === 0 || key.length > 256 || entry === undefined
+            || (typeof entry !== 'string' && (!Array.isArray(entry) || entry.length === 0
+                || entry.length > 64))) {
+            throw new Error('Impact art sequence is invalid.');
+        }
+        const names = typeof entry === 'string' ? [entry] : entry;
+        for (const name of names) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > 256) {
+                throw new Error('Impact art frame name is invalid.');
+            }
+        }
+        frames[key] = typeof entry === 'string' ? entry : Object.freeze([...entry]);
+    }
+    return Object.freeze({ textureKey: input.textureKey, recipeFrames: Object.freeze(frames) });
+}

package/docs/impact-feedback.manifest.json

@@ -0,0 +1,35 @@
+{
+  "id": "feedback.impact.pool",
+  "kind": "presentation",
+  "capabilities": [
+    "feedback.impact.contact",
+    "feedback.impact.recipe",
+    "feedback.impact.pool"
+  ],
+  "entry": "@mpgd/game-runtime/phaser/impact",
+  "config": {
+    "capacity": {
+      "default": 48,
+      "min": 1,
+      "max": 1024
+    },
+    "maxSparksPerEffect": {
+      "default": 6,
+      "min": 0,
+      "max": 64
+    }
+  },
+  "tests": [
+    "src/impact/index.test.ts",
+    "src/phaser/impact.test.ts"
+  ],
+  "gotchas": [
+    "Emit after authoritative collision resolution.",
+    "Use the same simulation clock for emit and update.",
+    "Full pools recycle slots; clear resets retained state.",
+    "Raster rings require registered texture frames.",
+    "Graphics rebuilds its command buffer while sparks are active.",
+    "Scene shutdown destroys pool-owned objects."
+  ],
+  "acceptance": "pnpm --dir packages/game-runtime test"
+}

package/docs/impact-feedback.md

@@ -0,0 +1,35 @@
+# Pooled impact feedback
+
+Capability: `feedback.impact.pool`. Kind: presentation.
+
+Use `@mpgd/game-runtime/impact` for validated contacts, authored recipe catalogs
+and ordered rule matching without importing Phaser. Use
+`@mpgd/game-runtime/phaser/impact` for `PhaserImpactFeedbackPool`.
+The renderer takes only contact scalars; damage, rewards and collision authority
+remain in the simulation.
+
+```ts
+const feedback = new PhaserImpactFeedbackPool(scene, { capacity: 48 });
+feedback.emit(contact, recipe);
+feedback.update(scene.time.now);
+// Shutdown/destroy automatically disposes the pool; destroy() is idempotent.
+```
+
+Config: capacity 1–1024 (default 48), maxSparksPerEffect 0–64 (default 6),
+optional finite depth and rasterRings with an already registered texture and
+recipe-to-frame mappings. Catalogs allow 256 recipes and 1024 rules. Higher
+priority wins; authored order breaks ties. Inputs are copied at catalog/pool
+construction. Construct once per scene; do not recreate for every contact.
+
+Gotchas: emit and update must use the same nonnegative simulation clock.
+Emit after authoritative collision resolution. Full pools recycle the next
+slot and completely reset visible state. Sparks share one Graphics batch;
+no GameObjects or tweens are created per hit, but Graphics rebuilds its command
+buffer each active frame. The caller owns recipes, texture loading and memory
+budgets; this helper does not certify device FPS. Frame strips contain 1–64
+registered names and run on the effect clock. Scene teardown destroys owned
+objects and detaches event listeners. Input devices have no role in this API.
+
+Tests: `src/impact/index.test.ts`, `src/phaser/impact.test.ts`, headless and
+packed consumer fixtures. Acceptance: `pnpm --dir packages/game-runtime test`;
+visually playtest rings/spark variants with the application's authored recipes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-runtime",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Gameplay execution, scoped UI and action coordination with optional Phaser scene bindings.",
   "license": "MIT",
   "keywords": [
@@ -50,6 +50,18 @@
     "./game": {
       "types": "./dist/game/index.d.ts",
       "default": "./dist/game/index.js"
+    },
+    "./dom": {
+      "types": "./dist/dom/index.d.ts",
+      "default": "./dist/dom/index.js"
+    },
+    "./impact": {
+      "types": "./dist/impact/index.d.ts",
+      "default": "./dist/impact/index.js"
+    },
+    "./phaser/impact": {
+      "types": "./dist/phaser/impact.d.ts",
+      "default": "./dist/phaser/impact.js"
     }
   },
   "files": [
@@ -64,8 +76,8 @@
     "@types/node": "^24.0.0"
   },
   "dependencies": {
-    "@mpgd/game-services": "0.18.1",
-    "@mpgd/platform": "0.16.0"
+    "@mpgd/game-services": "0.19.0",
+    "@mpgd/platform": "0.17.0"
   },
   "repository": {
     "type": "git",
@@ -90,7 +102,7 @@
   "scripts": {
     "build": "cd ../.. && node tools/run-ttsx.mjs tools/package/build-packages.ts @mpgd/game-runtime",
     "check": "ttsc --noEmit && ttsc --noEmit -p tsconfig.headless.json",
-    "test": "pnpm build && vitest run && node test/dist-import.mjs && node test/phaser-dist-import.mjs && ttsc --noEmit -p test/tsconfig.json && ttsc --noEmit -p test/tsconfig.phaser.json && node test/package-import.mjs",
+    "test": "pnpm build && vitest run && node test/dist-import.mjs && node test/phaser-dist-import.mjs && ttsc --noEmit -p test/tsconfig.json && ttsc --noEmit -p test/tsconfig.phaser.json && ttsc --noEmit -p test/tsconfig.dom.json && node test/package-import.mjs",
     "lint": "pnpm check",
     "format": "ttsc format",
     "fix": "ttsc fix"