@jgengine/core 0.14.0 → 0.15.0

package/dist/ui/radialMenu.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Arc the slices span. Omit for a full wheel (index 0 at the top). A partial
+ * `sweep` (e.g. `Math.PI` for a bottom half, `Math.PI / 2` for a quarter) packs
+ * the slices evenly inside `[startAngle, startAngle + sweep]` — the arc/quick-bar
+ * forms. Angles are radians from "up" (−Y), clockwise.
+ */
+export interface RadialArc {
+    startAngle?: number;
+    sweep?: number;
+}
+/** One wedge of a radial menu — geometry for rendering a slice. Angles are radians from "up" (−Y), clockwise. */
+export interface RadialSlice {
+    index: number;
+    /** Angle at the slice's center. */
+    centerAngle: number;
+    /** Leading edge angle. */
+    startAngle: number;
+    /** Trailing edge angle. */
+    endAngle: number;
+}
+/**
+ * Divide a ring (or `arc`) into `count` wedges — the geometry a radial/quick
+ * menu (weapon wheel, emote arc, ping bar) renders. A full wheel centers index 0
+ * at the top; a partial `arc` packs the slices inside its sweep.
+ */
+export declare function radialSlices(count: number, arc?: RadialArc): RadialSlice[];
+/** Map an angle to a slice index; returns -1 when the angle falls outside a partial `arc`. */
+export declare function radialIndexFromAngle(angle: number, count: number, arc?: RadialArc): number;
+/** Options for {@link radialIndexFromVector}. */
+export interface RadialVectorOptions extends RadialArc {
+    /** Minimum vector magnitude to register a selection; shorter vectors return null (the neutral center). Default 0. */
+    deadZone?: number;
+}
+/**
+ * Pick the slice a pointer/stick vector points at. `dx`/`dy` are screen-space
+ * (y down): up is `(0, -1)`. Returns null inside `deadZone` or (for a partial
+ * `arc`) outside the arc, so a centered stick or a click off the arc selects
+ * nothing.
+ *
+ * @capability radial-select map a pointer/stick vector to a radial-menu slice index, with a neutral dead zone and optional arc bounds
+ */
+export declare function radialIndexFromVector(dx: number, dy: number, count: number, options?: RadialVectorOptions): number | null;
+/** Unit-circle position of a slice center (up = `(0, -1)`), scaled by `radius` — where to place a wedge's icon/label. */
+export declare function radialSlicePosition(index: number, count: number, radius: number, arc?: RadialArc): {
+    x: number;
+    y: number;
+};

package/dist/ui/radialMenu.js

@@ -0,0 +1,74 @@
+const TWO_PI = Math.PI * 2;
+function normalize(angle) {
+    let value = angle % TWO_PI;
+    if (value < 0)
+        value += TWO_PI;
+    return value;
+}
+function arcConfig(count, arc) {
+    const startAngle = arc?.startAngle ?? 0;
+    const sweep = arc?.sweep ?? TWO_PI;
+    const full = sweep >= TWO_PI - 1e-6;
+    const size = full ? (count > 0 ? TWO_PI / count : 0) : (count > 0 ? sweep / count : 0);
+    // Full wheels wrap, so a slice sits exactly on the start angle (index 0 = top).
+    // Partial arcs offset by half a slice so wedges fit inside the arc.
+    const centerOf = (index) => startAngle + (full ? index : index + 0.5) * size;
+    return { startAngle, sweep, full, size, centerOf };
+}
+/**
+ * Divide a ring (or `arc`) into `count` wedges — the geometry a radial/quick
+ * menu (weapon wheel, emote arc, ping bar) renders. A full wheel centers index 0
+ * at the top; a partial `arc` packs the slices inside its sweep.
+ */
+export function radialSlices(count, arc) {
+    if (count <= 0)
+        return [];
+    const { size, centerOf } = arcConfig(count, arc);
+    const slices = [];
+    for (let index = 0; index < count; index += 1) {
+        const centerAngle = centerOf(index);
+        slices.push({
+            index,
+            centerAngle: normalize(centerAngle),
+            startAngle: normalize(centerAngle - size / 2),
+            endAngle: normalize(centerAngle + size / 2),
+        });
+    }
+    return slices;
+}
+/** Map an angle to a slice index; returns -1 when the angle falls outside a partial `arc`. */
+export function radialIndexFromAngle(angle, count, arc) {
+    if (count <= 0)
+        return -1;
+    const { full, size, startAngle, sweep } = arcConfig(count, arc);
+    if (full)
+        return Math.round(normalize(angle - startAngle) / size) % count;
+    const rel = normalize(angle - startAngle);
+    if (rel > sweep)
+        return -1;
+    return Math.max(0, Math.min(count - 1, Math.floor(rel / size)));
+}
+/**
+ * Pick the slice a pointer/stick vector points at. `dx`/`dy` are screen-space
+ * (y down): up is `(0, -1)`. Returns null inside `deadZone` or (for a partial
+ * `arc`) outside the arc, so a centered stick or a click off the arc selects
+ * nothing.
+ *
+ * @capability radial-select map a pointer/stick vector to a radial-menu slice index, with a neutral dead zone and optional arc bounds
+ */
+export function radialIndexFromVector(dx, dy, count, options = {}) {
+    if (count <= 0)
+        return null;
+    const magnitude = Math.hypot(dx, dy);
+    if (magnitude < (options.deadZone ?? 0))
+        return null;
+    // atan2(dx, -dy): 0 = up, increasing clockwise toward +x (right).
+    const index = radialIndexFromAngle(Math.atan2(dx, -dy), count, options);
+    return index < 0 ? null : index;
+}
+/** Unit-circle position of a slice center (up = `(0, -1)`), scaled by `radius` — where to place a wedge's icon/label. */
+export function radialSlicePosition(index, count, radius, arc) {
+    const { centerOf } = arcConfig(count, arc);
+    const angle = count <= 0 ? 0 : centerOf(index);
+    return { x: Math.sin(angle) * radius, y: -Math.cos(angle) * radius };
+}

package/dist/ui/screenMarkers.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A world position projected to screen space by the caller's camera. This is the
+ * minimal shape {@link layoutScreenMarker} consumes — deliberately a structural
+ * subset of `@jgengine/react`'s `EntityScreenProjection` (and what its
+ * `ProjectEntity`/`useWorldProjection` produce), mirrored here because `core`
+ * imports nothing higher. Feed it straight from a world→screen projector.
+ */
+export interface ScreenProjection {
+    /** CSS px from the viewport's left edge. */
+    x: number;
+    /** CSS px from the viewport's top edge. */
+    y: number;
+    /** Optional depth key (larger = farther); carried through untouched, unused by the math. */
+    depth?: number;
+    /**
+     * `true` when the point is behind the camera. Such a projection's `x`/`y` are
+     * mirrored through the origin, so the layout flips the bearing to point at the
+     * real off-screen direction rather than trusting the raw coordinates.
+     */
+    behind?: boolean;
+}
+/** The `{ width, height }` of the viewport the marker is laid out within (CSS px). */
+export interface ScreenMarkerViewport {
+    width: number;
+    height: number;
+}
+/** Options for {@link layoutScreenMarker}. */
+export interface ScreenMarkerOptions {
+    /**
+     * Inset (px) from each viewport edge that an off-screen/behind marker is
+     * clamped inside, so a directional arrow sits fully on-frame rather than half
+     * off the edge. Default `24`.
+     */
+    margin?: number;
+    /**
+     * Optional result object to write into and return, so a per-frame layout over
+     * many waypoints allocates nothing. Omit to get a fresh object each call.
+     */
+    out?: ScreenMarkerLayout;
+}
+/** Where and how to draw one marker, from {@link layoutScreenMarker}. */
+export interface ScreenMarkerLayout {
+    /**
+     * `true` when the target projects inside the viewport in front of the camera —
+     * draw an on-screen pin at `(x, y)`. `false` when it is off-screen or behind —
+     * draw a directional arrow clamped to the edge, rotated by `angle`.
+     */
+    onScreen: boolean;
+    /** Screen x to place the marker (px). On-screen: the projection; else clamped to the edge. */
+    x: number;
+    /** Screen y to place the marker (px). On-screen: the projection; else clamped to the edge. */
+    y: number;
+    /**
+     * Bearing from the viewport center toward the target, in radians (`atan2`
+     * convention: `0` = +x/right, `PI/2` = +y/down). Rotate an arrow glyph by this
+     * so it points at the target; also meaningful for an on-screen pin.
+     */
+    angle: number;
+}
+/**
+ * Pure, allocation-aware screen-marker math: given a projected target point, the
+ * viewport, and a `margin`, decide whether the target is on-screen and where to
+ * draw its marker. An on-screen point passes straight through (`onScreen: true`).
+ * An off-screen — or behind-camera — point is CLAMPED to the viewport edge (inset
+ * by `margin`) with `angle` set to the bearing from screen center toward the
+ * target, so a caller can pin an arrow to the frame edge and rotate it to point
+ * the way. Behind-camera projections have mirrored coordinates, so the bearing is
+ * flipped to face the true direction. This is the edge-clamp/arrow half that
+ * `layoutEntityFrames` lacks (it culls off-screen entries instead). No allocation
+ * when an `out` object is supplied — reuse one across a whole frame's waypoints.
+ *
+ * @capability offscreen-markers pure edge-clamp + bearing math turning a projected point into an on-screen pin or an off-screen directional arrow clamped to the viewport edge
+ */
+export declare function layoutScreenMarker(projection: ScreenProjection, viewport: ScreenMarkerViewport, options?: ScreenMarkerOptions): ScreenMarkerLayout;
+/** A tracked objective/waypoint the game wants a screen marker for. */
+export interface Waypoint {
+    /** Stable id — the key for `set`/`remove` and React lists. */
+    id: string;
+    /** World-space anchor `[x, y, z]` the caller projects to screen space. */
+    position: readonly [number, number, number];
+    /**
+     * Free-string label the game owns and styles ("objective", "loot", "ally", …).
+     * The model never interprets it — it only carries it through so a game can
+     * color/skin per kind.
+     */
+    kind: string;
+    /** Optional display label ("Extraction", "Ammo cache", …). */
+    label?: string;
+}
+/** Serializable state of a {@link WaypointTracker}, for save/restore. */
+export interface WaypointSnapshot {
+    /** Every tracked waypoint, in insertion order. */
+    waypoints: readonly Waypoint[];
+}
+/** An observable, serializable set of world waypoints keyed by id. */
+export interface WaypointTracker {
+    /** Add or replace the waypoint with this id. Notifies subscribers. */
+    set(waypoint: Waypoint): void;
+    /** Remove the waypoint with this id, if present. Notifies when it existed. */
+    remove(id: string): void;
+    /** Remove every waypoint. Notifies when the set was non-empty. */
+    clear(): void;
+    /** The tracked waypoint with this id, or `undefined`. */
+    get(id: string): Waypoint | undefined;
+    /** Every tracked waypoint, in insertion order (a fresh array — safe to retain). */
+    all(): readonly Waypoint[];
+    /** How many waypoints are tracked. */
+    size(): number;
+    /** Observe changes (set, remove, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): WaypointSnapshot;
+    /** Restore from a {@link WaypointSnapshot}, replacing the current set. */
+    restore(snapshot: WaypointSnapshot): void;
+}
+/**
+ * A serializable, observable tracker of world waypoints — the objective/point-of-
+ * interest half of offscreen markers. A game `set`s waypoints by id (each an
+ * `{ id, position, kind, label? }`, where `kind` is a free string the game styles
+ * and the model never branches on), and a React host projects each to screen space
+ * and lays it out with {@link layoutScreenMarker}: an on-screen pin, or an
+ * off-screen directional arrow clamped to the viewport edge with a distance the
+ * caller computes. Purely a model — no camera, projection, or renderer here.
+ * `snapshot`/`restore` round-trips the set through a save.
+ *
+ * @capability offscreen-markers serializable waypoint tracker + pure edge-clamp/bearing math for on-screen pins and off-screen directional arrows with distance
+ */
+export declare function createWaypointTracker(): WaypointTracker;

package/dist/ui/screenMarkers.js

@@ -0,0 +1,118 @@
+/**
+ * Pure, allocation-aware screen-marker math: given a projected target point, the
+ * viewport, and a `margin`, decide whether the target is on-screen and where to
+ * draw its marker. An on-screen point passes straight through (`onScreen: true`).
+ * An off-screen — or behind-camera — point is CLAMPED to the viewport edge (inset
+ * by `margin`) with `angle` set to the bearing from screen center toward the
+ * target, so a caller can pin an arrow to the frame edge and rotate it to point
+ * the way. Behind-camera projections have mirrored coordinates, so the bearing is
+ * flipped to face the true direction. This is the edge-clamp/arrow half that
+ * `layoutEntityFrames` lacks (it culls off-screen entries instead). No allocation
+ * when an `out` object is supplied — reuse one across a whole frame's waypoints.
+ *
+ * @capability offscreen-markers pure edge-clamp + bearing math turning a projected point into an on-screen pin or an off-screen directional arrow clamped to the viewport edge
+ */
+export function layoutScreenMarker(projection, viewport, options = {}) {
+    const margin = options.margin ?? 24;
+    const out = options.out ?? { onScreen: false, x: 0, y: 0, angle: 0 };
+    const { width, height } = viewport;
+    const cx = width / 2;
+    const cy = height / 2;
+    const behind = projection.behind === true;
+    // Direction from screen center to the target; flip it when the point is behind
+    // the camera (its projected coords are mirrored through the origin).
+    let dx = projection.x - cx;
+    let dy = projection.y - cy;
+    if (behind) {
+        dx = -dx;
+        dy = -dy;
+    }
+    // Degenerate: target sits exactly at center — pick a stable downward bearing.
+    if (dx === 0 && dy === 0)
+        dy = 1;
+    const angle = Math.atan2(dy, dx);
+    const onScreen = !behind &&
+        projection.x >= 0 &&
+        projection.x <= width &&
+        projection.y >= 0 &&
+        projection.y <= height;
+    if (onScreen) {
+        out.onScreen = true;
+        out.x = projection.x;
+        out.y = projection.y;
+        out.angle = angle;
+        return out;
+    }
+    // Clamp along the center→target ray to the rectangle inset by `margin`.
+    const hx = Math.max(0, width / 2 - margin);
+    const hy = Math.max(0, height / 2 - margin);
+    // Scale the direction so the longer axis just reaches its half-extent.
+    const scaleX = dx === 0 ? Infinity : hx / Math.abs(dx);
+    const scaleY = dy === 0 ? Infinity : hy / Math.abs(dy);
+    const scale = Math.min(scaleX, scaleY);
+    const safeScale = Number.isFinite(scale) ? scale : 0;
+    out.onScreen = false;
+    out.x = cx + dx * safeScale;
+    out.y = cy + dy * safeScale;
+    out.angle = angle;
+    return out;
+}
+/**
+ * A serializable, observable tracker of world waypoints — the objective/point-of-
+ * interest half of offscreen markers. A game `set`s waypoints by id (each an
+ * `{ id, position, kind, label? }`, where `kind` is a free string the game styles
+ * and the model never branches on), and a React host projects each to screen space
+ * and lays it out with {@link layoutScreenMarker}: an on-screen pin, or an
+ * off-screen directional arrow clamped to the viewport edge with a distance the
+ * caller computes. Purely a model — no camera, projection, or renderer here.
+ * `snapshot`/`restore` round-trips the set through a save.
+ *
+ * @capability offscreen-markers serializable waypoint tracker + pure edge-clamp/bearing math for on-screen pins and off-screen directional arrows with distance
+ */
+export function createWaypointTracker() {
+    // Insertion-ordered map keeps `all()`/snapshot stable across sets.
+    const waypoints = new Map();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        set(waypoint) {
+            waypoints.set(waypoint.id, waypoint);
+            notify();
+        },
+        remove(id) {
+            if (waypoints.delete(id))
+                notify();
+        },
+        clear() {
+            if (waypoints.size === 0)
+                return;
+            waypoints.clear();
+            notify();
+        },
+        get(id) {
+            return waypoints.get(id);
+        },
+        all() {
+            return [...waypoints.values()];
+        },
+        size() {
+            return waypoints.size;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { waypoints: [...waypoints.values()] };
+        },
+        restore(snapshot) {
+            waypoints.clear();
+            for (const waypoint of snapshot.waypoints)
+                waypoints.set(waypoint.id, waypoint);
+            notify();
+        },
+    };
+}

package/dist/ui.d.ts

@@ -1,16 +1,24 @@
 export { formatDistance } from "./format/distance.js";
 export { formatDelta, formatDuration, formatOrdinal } from "./format/duration.js";
 export { formatSpeed } from "./format/speed.js";
+export { createI18n, interpolate, type Catalog, type I18n, type I18nOptions, type Locale, type Messages, type TParams, } from "./i18n/i18n.js";
 export { resolveGameLook, type LookPreset } from "./render/lookPreset.js";
 export { STUDIO_STAGE_POST, type GradeConfig, type PostProcessingConfig, type ToneMappingMode, } from "./render/postProcessing.js";
 export { BUILT_IN_SETTING_CATEGORIES, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, busVolumeSettingId, createSettingsStore, type GameSettingDef, type GameSettingsConfig, type GraphicsQuality, type SettingCategory, type SettingCategoryDef, type SettingKind, type SettingOption, type SettingValue, type SettingsActionDef, type SettingsStore, type SettingsSurface, type SettingsVariant, } from "./settings/settingsModel.js";
+export { COLORBLIND_MATRICES, DEFAULT_ACCESSIBILITY, TEXT_SCALE_MAX, TEXT_SCALE_MIN, clampTextScale, createAccessibilityStore, reducedMotionDuration, type AccessibilityState, type AccessibilityStore, type ColorblindMode, } from "./ui/accessibility.js";
 export { actionByHotkey, actionCooldown, actionCooldownFromFraction, actionCost, moveGridFocus, resolveAction, resolveActionCollection, type ActionCooldown, type ActionCost, type ActionDef, type ActionReason, type FocusDirection, type GridFocusOptions, type ResolvedAction, } from "./ui/actionModel.js";
+export { createCoachMarkSequence, type CoachMarkPlacement, type CoachMarkSequence, type CoachMarkSequenceOptions, type CoachMarkSnapshot, type CoachMarkStep, type CoachMarkView, } from "./ui/coachMarks.js";
 export { type GameLayoutMode, type GameViewportLayout, type HudPriority, type Insets, type LayoutCollision, type LayoutCollisionPolicy, type LayoutRect, type LayoutRegion, type MobileHudBehavior, } from "./ui/gameLayout.js";
 export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPanelLayout, type EditorUiDocument, type EditorUiPanelLayout, type HudResizeAxes, } from "./ui/hudDocument.js";
 export { HUD_ANCHOR_FRACTIONS, type HudAnchor, type HudLayoutStore, type HudPlacement, type HudSize, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, type HudPlatform, type HudViewportConfig, } from "./ui/hudScale.js";
+export { MODAL_CANCEL, MODAL_CONFIRM, createModalStack, type ModalInput, type ModalRecord, type ModalResolution, type ModalStack, type ModalStackEntry, type ModalStackOptions, type ModalStackSnapshot, } from "./ui/modalStack.js";
+export { createObjectiveBanner, type ObjectiveBannerAnnouncement, type ObjectiveBannerController, type ObjectiveBannerOptions, type ObjectiveBannerPhase, type ObjectiveBannerSnapshot, type ObjectiveBannerView, type StoredObjectiveBanner, } from "./ui/objectiveBanner.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, type LayoutOrientation, } from "./ui/orientation.js";
 export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, type PanelDef, type PanelPosition, type PanelState, } from "./ui/panelModel.js";
+export { DEFAULT_PHOTO_MODE, createPhotoModeStore, type PhotoModeState, type PhotoModeStore } from "./ui/photoMode.js";
+export { radialIndexFromAngle, radialIndexFromVector, radialSlicePosition, radialSlices, type RadialArc, type RadialSlice, type RadialVectorOptions, } from "./ui/radialMenu.js";
+export { createWaypointTracker, layoutScreenMarker, type ScreenMarkerLayout, type ScreenMarkerOptions, type ScreenMarkerViewport, type ScreenProjection, type Waypoint, type WaypointSnapshot, type WaypointTracker, } from "./ui/screenMarkers.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, type EntitySummaryDef, type EntityVital, type SelectionFocusDirection, type SelectionGroup, type SelectionView, type SelectionWindow, type SummarizeSelectionOptions, } from "./ui/selectionModel.js";
 export { swingTimerState, type SwingTargetInput } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, type PopoverOptions, type PopoverPlacement, type PopoverSide, type TooltipContent, type UiRect, type UiSize, } from "./ui/tooltipModel.js";

package/dist/ui.js

@@ -1,16 +1,24 @@
 export { formatDistance } from "./format/distance.js";
 export { formatDelta, formatDuration, formatOrdinal } from "./format/duration.js";
 export { formatSpeed } from "./format/speed.js";
+export { createI18n, interpolate, } from "./i18n/i18n.js";
 export { resolveGameLook } from "./render/lookPreset.js";
 export { STUDIO_STAGE_POST, } from "./render/postProcessing.js";
 export { BUILT_IN_SETTING_CATEGORIES, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, busVolumeSettingId, createSettingsStore, } from "./settings/settingsModel.js";
+export { COLORBLIND_MATRICES, DEFAULT_ACCESSIBILITY, TEXT_SCALE_MAX, TEXT_SCALE_MIN, clampTextScale, createAccessibilityStore, reducedMotionDuration, } from "./ui/accessibility.js";
 export { actionByHotkey, actionCooldown, actionCooldownFromFraction, actionCost, moveGridFocus, resolveAction, resolveActionCollection, } from "./ui/actionModel.js";
+export { createCoachMarkSequence, } from "./ui/coachMarks.js";
 export {} from "./ui/gameLayout.js";
 export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPanelLayout, } from "./ui/hudDocument.js";
 export { HUD_ANCHOR_FRACTIONS, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, } from "./ui/hudScale.js";
+export { MODAL_CANCEL, MODAL_CONFIRM, createModalStack, } from "./ui/modalStack.js";
+export { createObjectiveBanner, } from "./ui/objectiveBanner.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "./ui/orientation.js";
 export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, } from "./ui/panelModel.js";
+export { DEFAULT_PHOTO_MODE, createPhotoModeStore } from "./ui/photoMode.js";
+export { radialIndexFromAngle, radialIndexFromVector, radialSlicePosition, radialSlices, } from "./ui/radialMenu.js";
+export { createWaypointTracker, layoutScreenMarker, } from "./ui/screenMarkers.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, } from "./ui/selectionModel.js";
 export { swingTimerState } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, } from "./ui/tooltipModel.js";

package/dist/vfx/cameraShake.d.ts

@@ -0,0 +1,97 @@
+/** A per-frame camera shake offset: three positional axes plus three rotational axes (radians). */
+export interface CameraShakeOffset {
+    /** Positional kick along camera-space X. */
+    x: number;
+    /** Positional kick along camera-space Y. */
+    y: number;
+    /** Positional kick along camera-space Z. */
+    z: number;
+    /** Rotational kick about the pitch axis (radians). */
+    pitch: number;
+    /** Rotational kick about the yaw axis (radians). */
+    yaw: number;
+    /** Rotational kick about the roll axis (radians). */
+    roll: number;
+}
+/** Configuration for {@link createCameraShake}. Every field has a game-feel default. */
+export interface CameraShakeConfig {
+    /** Trauma bled off per second while `update` runs. Default `1.6`. */
+    decayPerSecond?: number;
+    /**
+     * Exponent applied to trauma before it drives the offset (`shake = trauma^exp`),
+     * so small hits stay subtle and big hits dominate. Default `2` (the classic
+     * "trauma squared" curve).
+     */
+    traumaExponent?: number;
+    /** Peak positional offset at full shake, per `[x, y, z]` axis (world units). Default `[0.6, 0.6, 0.4]`. */
+    maxTranslation?: readonly [number, number, number];
+    /** Peak rotational offset at full shake, per `[pitch, yaw, roll]` axis (radians). Default `[0.06, 0.06, 0.12]`. */
+    maxRotation?: readonly [number, number, number];
+    /** Base noise frequency (oscillations per second) sampled along the time cursor. Default `18`. */
+    frequency?: number;
+    /** Deterministic seed for the value noise; same seed + dt sequence reproduces the same offsets. Default `"camera-shake"`. */
+    seed?: string | number;
+    /** Injected clock (ms) used when `update` is called with no explicit dt. Default `Date.now`. */
+    now?: () => number;
+}
+/** Serializable state for save/restore and deterministic replay. */
+export interface CameraShakeSnapshot {
+    /** Current trauma in `[0, 1]`. */
+    trauma: number;
+    /** Advancing time cursor (seconds) the noise is sampled along. */
+    time: number;
+    /** The base value-noise seed as a plain integer. */
+    seed: number;
+    /** The last free-string `kind` label handed to `add`, or `null`. */
+    kind: string | null;
+}
+/** A live, dt-driven, trauma-based camera shake controller. */
+export interface CameraShakeController {
+    /**
+     * Add trauma (clamped into `[0, 1]`). `kind` is a free string the model never
+     * interprets — it only carries it through so a game can style/label impacts
+     * ("hit", "explosion", "landing", …). Larger hits raise the ceiling toward 1.
+     */
+    add(amount: number, kind?: string): void;
+    /**
+     * Advance the shake: bleed trauma by `decayPerSecond` and move the noise time
+     * cursor forward. Pass explicit `dt` seconds to drive deterministically, else
+     * the injected clock supplies the delta since the last call.
+     */
+    update(dt?: number): void;
+    /**
+     * The shake to apply this frame — a POOLED object reused across calls (read it,
+     * don't retain it). Each axis is `trauma^traumaExponent * max[axis] * noise`,
+     * where the noise is deterministic seeded value-noise sampled at the time cursor.
+     */
+    offset(): CameraShakeOffset;
+    /** Current trauma in `[0, 1]`. */
+    trauma(): number;
+    /** The last free-string `kind` handed to `add`, or `undefined` if none yet. */
+    kind(): string | undefined;
+    /** Patch the config in place (e.g. retune decay or amplitudes at runtime). */
+    configure(patch: Partial<CameraShakeConfig>): void;
+    /** Reset trauma to 0 (keeps the seed and time cursor). */
+    clear(): void;
+    /** Observe changes (add, update, configure, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): CameraShakeSnapshot;
+    /** Restore from a {@link CameraShakeSnapshot}. */
+    restore(snapshot: CameraShakeSnapshot): void;
+}
+/**
+ * A seeded, serializable, trauma-based camera shake / impulse controller. A game
+ * calls `add(amount, kind?)` on impacts (a hit, an explosion, a landing) to raise
+ * trauma in `[0, 1]`; `update(dt)` bleeds it off over time; and `offset()` returns
+ * a pooled `{ x, y, z, pitch, yaw, roll }` kick equal to `trauma^exponent` times
+ * per-axis maxima times deterministic seeded value-noise sampled along an internal
+ * time cursor. A shell consumer applies that offset to the active camera each frame
+ * so the view visibly shakes. Nothing here is genre-specific: `kind` is a free
+ * label the game styles, all amplitudes/decay are parameters, and `snapshot`/
+ * `restore` round-trips the shake through a save. Deterministic from `seed`: the
+ * same seed and dt sequence reproduce the same offsets.
+ *
+ * @capability camera-shake seeded serializable trauma-based camera shake/impulse controller (hit/explosion/landing juice) with pooled per-frame translation+rotation offset and snapshot/restore
+ */
+export declare function createCameraShake(config?: CameraShakeConfig): CameraShakeController;

package/dist/vfx/cameraShake.js

@@ -0,0 +1,136 @@
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** A stable pseudo-random value in `[-1, 1]` for integer lattice point `i` off a base seed. */
+function latticeValue(seed, i) {
+    const mixed = randomSeedFrom((seed ^ Math.imul(i | 0, 0x9e3779b1)) | 0);
+    const [value] = stepRandomSeed(mixed);
+    return value * 2 - 1;
+}
+/**
+ * 1-D smoothstep value noise: hash the two integer lattice points bracketing `t`
+ * and interpolate. Continuous and deterministic — no per-frame RNG, so the same
+ * seed and time reproduce the same value.
+ */
+function valueNoise(seed, t) {
+    const i0 = Math.floor(t);
+    const f = t - i0;
+    const a = latticeValue(seed, i0);
+    const b = latticeValue(seed, i0 + 1);
+    const u = f * f * (3 - 2 * f);
+    return a + (b - a) * u;
+}
+// Per-axis frequency multipliers decorrelate the six channels so the shake never
+// looks like a single sine sweep. Fixed constants (not tunable) — pure feel.
+const AXIS_FREQ = [1, 1.17, 0.83, 1.31, 0.91, 1.09];
+/**
+ * A seeded, serializable, trauma-based camera shake / impulse controller. A game
+ * calls `add(amount, kind?)` on impacts (a hit, an explosion, a landing) to raise
+ * trauma in `[0, 1]`; `update(dt)` bleeds it off over time; and `offset()` returns
+ * a pooled `{ x, y, z, pitch, yaw, roll }` kick equal to `trauma^exponent` times
+ * per-axis maxima times deterministic seeded value-noise sampled along an internal
+ * time cursor. A shell consumer applies that offset to the active camera each frame
+ * so the view visibly shakes. Nothing here is genre-specific: `kind` is a free
+ * label the game styles, all amplitudes/decay are parameters, and `snapshot`/
+ * `restore` round-trips the shake through a save. Deterministic from `seed`: the
+ * same seed and dt sequence reproduce the same offsets.
+ *
+ * @capability camera-shake seeded serializable trauma-based camera shake/impulse controller (hit/explosion/landing juice) with pooled per-frame translation+rotation offset and snapshot/restore
+ */
+export function createCameraShake(config = {}) {
+    const cfg = {
+        decayPerSecond: config.decayPerSecond ?? 1.6,
+        traumaExponent: config.traumaExponent ?? 2,
+        maxTranslation: config.maxTranslation ?? [0.6, 0.6, 0.4],
+        maxRotation: config.maxRotation ?? [0.06, 0.06, 0.12],
+        frequency: config.frequency ?? 18,
+    };
+    const now = config.now ?? Date.now;
+    let seed = randomSeedFrom(typeof config.seed === "number" ? config.seed : hashString(String(config.seed ?? "camera-shake")));
+    let trauma = 0;
+    let time = 0;
+    let kind;
+    let lastNow = null;
+    const listeners = new Set();
+    // Pooled offset — reused across offset() calls, never per-frame allocated.
+    const out = { x: 0, y: 0, z: 0, pitch: 0, yaw: 0, roll: 0 };
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        add(amount, impactKind) {
+            if (impactKind !== undefined)
+                kind = impactKind;
+            trauma = clamp01(trauma + amount);
+            notify();
+        },
+        update(dt) {
+            let seconds;
+            if (dt === undefined) {
+                const t = now();
+                seconds = lastNow === null ? 0 : Math.max(0, (t - lastNow) / 1000);
+                lastNow = t;
+            }
+            else {
+                seconds = Math.max(0, dt);
+            }
+            if (seconds <= 0)
+                return;
+            time += seconds;
+            trauma = clamp01(trauma - cfg.decayPerSecond * seconds);
+            notify();
+        },
+        offset() {
+            const shake = Math.pow(trauma, cfg.traumaExponent);
+            if (shake <= 0) {
+                out.x = out.y = out.z = out.pitch = out.yaw = out.roll = 0;
+                return out;
+            }
+            const [mtx, mty, mtz] = cfg.maxTranslation;
+            const [mrp, mry, mrr] = cfg.maxRotation;
+            const f = cfg.frequency;
+            // Each axis samples an independent seed offset + frequency so channels decorrelate.
+            out.x = mtx * shake * valueNoise(randomSeedFrom((seed ^ 0x0100) | 0), time * f * AXIS_FREQ[0]);
+            out.y = mty * shake * valueNoise(randomSeedFrom((seed ^ 0x0200) | 0), time * f * AXIS_FREQ[1]);
+            out.z = mtz * shake * valueNoise(randomSeedFrom((seed ^ 0x0300) | 0), time * f * AXIS_FREQ[2]);
+            out.pitch = mrp * shake * valueNoise(randomSeedFrom((seed ^ 0x0400) | 0), time * f * AXIS_FREQ[3]);
+            out.yaw = mry * shake * valueNoise(randomSeedFrom((seed ^ 0x0500) | 0), time * f * AXIS_FREQ[4]);
+            out.roll = mrr * shake * valueNoise(randomSeedFrom((seed ^ 0x0600) | 0), time * f * AXIS_FREQ[5]);
+            return out;
+        },
+        trauma() {
+            return trauma;
+        },
+        kind() {
+            return kind;
+        },
+        configure(patch) {
+            Object.assign(cfg, patch);
+            if (patch.seed !== undefined) {
+                seed = randomSeedFrom(typeof patch.seed === "number" ? patch.seed : hashString(String(patch.seed)));
+            }
+            notify();
+        },
+        clear() {
+            trauma = 0;
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { trauma, time, seed: seed, kind: kind ?? null };
+        },
+        restore(snapshot) {
+            trauma = clamp01(snapshot.trauma);
+            time = snapshot.time;
+            seed = randomSeedFrom(snapshot.seed | 0);
+            kind = snapshot.kind ?? undefined;
+            lastNow = null;
+            notify();
+        },
+    };
+}