@jgengine/core 0.9.0 → 0.11.0

package/dist/anim/oscillator.js

@@ -0,0 +1,25 @@
+/** Sawtooth ramp: rises 0→1 over each `period` then resets, for looping sweeps and scrolls.
+ * @internal
+ */
+export function sawWave(time, period) {
+    if (!(period > 0))
+        return 0;
+    const phase = ((time % period) + period) % period;
+    return phase / period;
+}
+/** Triangle wave: ramps 0→1→0 across each `period`, for patrols, searchlights, and pulsing glows.
+ * @internal
+ */
+export function triangleWave(time, period) {
+    const up = sawWave(time, period);
+    return up < 0.5 ? up * 2 : 2 - up * 2;
+}
+/** Ping-pong a value across `[0, length]`, bouncing at each edge — the index/position analog of {@link triangleWave}.
+ * @internal
+ */
+export function pingPong(value, length) {
+    if (!(length > 0))
+        return 0;
+    const t = ((value % (length * 2)) + length * 2) % (length * 2);
+    return t <= length ? t : length * 2 - t;
+}

package/dist/area/areaEffectField.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Continuous area-effect membership: moving sources emit an area that follows them each tick,
+ * receivers that move in and out get enter / refresh / leave edges, and membership is cleaned up
+ * when a source is removed, disabled, or the field is cleared. A pure lifecycle machine — it never
+ * applies damage, heals, or stat changes itself; the caller routes each edge through its own
+ * effect pipeline (see `combat/effects`, `combat/dotField`, `stats/statModifiers`). This is the
+ * dynamic, source-following counterpart to `scene/authoredTriggers` (static document volumes).
+ *
+ * Bounded by design: the caller supplies a broad-phase `candidates(shape)` query (e.g.
+ * `visibility/spatialIndex`'s `querySphere`) plus a `positionOf` lookup, so a step visits only
+ * receivers near each source — never the whole world. Serializable: `serialize()` captures the
+ * membership set and each member's refresh phase so cadence and enter/leave edges survive save/load.
+ */
+import type { EntityPosition } from "../scene/entityStore.js";
+/**
+ * The area a source occupies this tick. `sphere` is first-class; `custom` leaves a seam for authored
+ * volumes and other shapes while still exposing a bounding sphere (`center`/`radius`) for the caller's
+ * broad-phase candidate query.
+ */
+export type AreaShape = {
+    readonly kind: "sphere";
+    readonly center: EntityPosition;
+    readonly radius: number;
+} | {
+    readonly kind: "custom";
+    /** Bounding-sphere center the caller's broad-phase `candidates` query is built from. */
+    readonly center: EntityPosition;
+    /** Bounding-sphere radius the caller's broad-phase `candidates` query is built from. */
+    readonly radius: number;
+    /** Authoritative containment test applied to each broad-phase candidate. */
+    readonly contains: (point: EntityPosition) => boolean;
+};
+/** Descriptor for one continuous area source; re-supplied each tick so its shape follows the emitter. */
+export interface AreaSourceSpec<P> {
+    /** Stable source id (the emitter). Re-using an id updates the descriptor and preserves membership. */
+    readonly id: string;
+    /** The source's area this tick — pass the emitter's live position so membership follows it. */
+    readonly shape: AreaShape;
+    /** Caller data describing what this source does (damage amount, heal, buff key, capture rate…). */
+    readonly payload: P;
+    /** Milliseconds between `refresh` edges emitted for each member; omit for enter/leave only. */
+    readonly refreshMs?: number;
+    /** Aggregation group key for stacking policies; defaults to the source id. */
+    readonly stackKey?: string;
+    /** When false the source keeps its descriptor but holds no members (current members `leave`). Default true. */
+    readonly enabled?: boolean;
+}
+/** Why a `leave` edge fired. */
+export type AreaLeaveReason = "exit" | "source-removed" | "disabled" | "cleared";
+/** The three membership edges a step can emit. */
+export type AreaEventKind = "enter" | "refresh" | "leave";
+/** One membership edge emitted by `step`, `removeSource`, or `clear`. */
+export interface AreaEffectEvent<P> {
+    readonly kind: AreaEventKind;
+    readonly sourceId: string;
+    readonly receiverId: string;
+    readonly stackKey: string;
+    readonly payload: P;
+    /** Number of refresh cadences crossed this step (>= 1 on `refresh`; a large dt can cross several). */
+    readonly ticks?: number;
+    /** Present only on `leave`. */
+    readonly reason?: AreaLeaveReason;
+}
+/** One active (source, receiver) membership — feed a receiver's list to a stacking policy. */
+export interface AreaMembership<P> {
+    readonly sourceId: string;
+    readonly receiverId: string;
+    readonly stackKey: string;
+    readonly payload: P;
+}
+/** Per-tick inputs the field needs to reconcile membership without scanning the world. */
+export interface AreaStepInput {
+    /** Milliseconds since the previous step; negative values are clamped to 0. */
+    readonly dtMs: number;
+    /** Bounded broad-phase: receiver ids possibly inside `shape` (e.g. `spatialIndex.querySphere`). */
+    readonly candidates: (shape: AreaShape) => Iterable<string>;
+    /** Precise receiver position; `undefined` means the receiver is gone (removed/dead) and is dropped. */
+    readonly positionOf: (receiverId: string) => EntityPosition | undefined;
+    /** Optional per-pair gate (team filter, immunity, line-of-sight already resolved by the caller). */
+    readonly eligible?: (sourceId: string, receiverId: string, payload: unknown) => boolean;
+}
+/** Serialized field state: source descriptors (minus their transient shape) and per-member refresh phase. */
+export interface AreaFieldState<P> {
+    readonly sources: {
+        readonly id: string;
+        readonly payload: P;
+        readonly refreshMs?: number;
+        readonly stackKey: string;
+        readonly enabled: boolean;
+    }[];
+    readonly memberships: {
+        readonly sourceId: string;
+        readonly receiverId: string;
+        readonly sinceRefreshMs: number;
+    }[];
+}
+/** Runtime handle tracking continuous area membership across ticks. */
+export interface AreaEffectField<P> {
+    /** Register or update a source (upsert by id); an update preserves existing membership and refresh phase. */
+    setSource(spec: AreaSourceSpec<P>): void;
+    /** Remove a source and return a `leave` (reason `source-removed`) for each of its members. */
+    removeSource(id: string): AreaEffectEvent<P>[];
+    hasSource(id: string): boolean;
+    sourceIds(): string[];
+    /** Reconcile every source against the receivers its `candidates` query returns; emit enter/refresh/leave. */
+    step(input: AreaStepInput): AreaEffectEvent<P>[];
+    /** Receiver ids currently inside `sourceId`. */
+    members(sourceId: string): string[];
+    isMember(sourceId: string, receiverId: string): boolean;
+    /** Every active membership across all sources. */
+    memberships(): AreaMembership<P>[];
+    /** Active memberships affecting a single receiver — the input to a stacking policy. */
+    membershipsOf(receiverId: string): AreaMembership<P>[];
+    /** Drop all sources and members; returns a `leave` (reason `cleared`) for each member. */
+    clear(): AreaEffectEvent<P>[];
+    /** Snapshot the persistent membership lifecycle for save/load; shapes are transient and re-supplied via `setSource`. */
+    serialize(): AreaFieldState<P>;
+}
+/**
+ * Build a continuous area-effect field. Drive it with `setSource` (once per live source per tick, so
+ * shapes follow their emitters) and `step` (to reconcile membership and drain enter/refresh/leave edges).
+ * Optionally restore prior membership by passing a `serialize()` snapshot; re-`setSource` live shapes
+ * before the first `step` after restore, since shapes are transient.
+ *
+ * @capability area-effect-field source-following area membership with enter/refresh/leave edges, stacking, and cleanup
+ */
+export declare function createAreaEffectField<P = unknown>(state?: AreaFieldState<P>): AreaEffectField<P>;

package/dist/area/areaEffectField.js

@@ -0,0 +1,175 @@
+/**
+ * Continuous area-effect membership: moving sources emit an area that follows them each tick,
+ * receivers that move in and out get enter / refresh / leave edges, and membership is cleaned up
+ * when a source is removed, disabled, or the field is cleared. A pure lifecycle machine — it never
+ * applies damage, heals, or stat changes itself; the caller routes each edge through its own
+ * effect pipeline (see `combat/effects`, `combat/dotField`, `stats/statModifiers`). This is the
+ * dynamic, source-following counterpart to `scene/authoredTriggers` (static document volumes).
+ *
+ * Bounded by design: the caller supplies a broad-phase `candidates(shape)` query (e.g.
+ * `visibility/spatialIndex`'s `querySphere`) plus a `positionOf` lookup, so a step visits only
+ * receivers near each source — never the whole world. Serializable: `serialize()` captures the
+ * membership set and each member's refresh phase so cadence and enter/leave edges survive save/load.
+ */
+const SENTINEL_SHAPE = { kind: "sphere", center: [0, 0, 0], radius: 0 };
+function shapeContains(shape, point) {
+    if (shape.kind === "custom")
+        return shape.contains(point);
+    const dx = point[0] - shape.center[0];
+    const dy = point[1] - shape.center[1];
+    const dz = point[2] - shape.center[2];
+    return dx * dx + dy * dy + dz * dz <= shape.radius * shape.radius;
+}
+/**
+ * Build a continuous area-effect field. Drive it with `setSource` (once per live source per tick, so
+ * shapes follow their emitters) and `step` (to reconcile membership and drain enter/refresh/leave edges).
+ * Optionally restore prior membership by passing a `serialize()` snapshot; re-`setSource` live shapes
+ * before the first `step` after restore, since shapes are transient.
+ *
+ * @capability area-effect-field source-following area membership with enter/refresh/leave edges, stacking, and cleanup
+ */
+export function createAreaEffectField(state) {
+    const sources = new Map();
+    if (state !== undefined) {
+        for (const source of state.sources) {
+            sources.set(source.id, {
+                shape: SENTINEL_SHAPE,
+                payload: source.payload,
+                refreshMs: source.refreshMs,
+                stackKey: source.stackKey,
+                enabled: source.enabled,
+                members: new Map(),
+            });
+        }
+        for (const membership of state.memberships) {
+            sources.get(membership.sourceId)?.members.set(membership.receiverId, {
+                sinceRefreshMs: membership.sinceRefreshMs,
+            });
+        }
+    }
+    function leaveAll(rec, sourceId, reason) {
+        const events = [];
+        for (const receiverId of rec.members.keys()) {
+            events.push({ kind: "leave", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, reason });
+        }
+        rec.members.clear();
+        return events;
+    }
+    return {
+        setSource(spec) {
+            const stackKey = spec.stackKey ?? spec.id;
+            const enabled = spec.enabled ?? true;
+            const existing = sources.get(spec.id);
+            if (existing !== undefined) {
+                existing.shape = spec.shape;
+                existing.payload = spec.payload;
+                existing.refreshMs = spec.refreshMs;
+                existing.stackKey = stackKey;
+                existing.enabled = enabled;
+                return;
+            }
+            sources.set(spec.id, {
+                shape: spec.shape,
+                payload: spec.payload,
+                refreshMs: spec.refreshMs,
+                stackKey,
+                enabled,
+                members: new Map(),
+            });
+        },
+        removeSource(id) {
+            const rec = sources.get(id);
+            if (rec === undefined)
+                return [];
+            const events = leaveAll(rec, id, "source-removed");
+            sources.delete(id);
+            return events;
+        },
+        hasSource: (id) => sources.has(id),
+        sourceIds: () => [...sources.keys()],
+        step(input) {
+            const dtMs = Math.max(0, input.dtMs);
+            const events = [];
+            for (const [sourceId, rec] of sources) {
+                if (!rec.enabled) {
+                    events.push(...leaveAll(rec, sourceId, "disabled"));
+                    continue;
+                }
+                const seen = new Set();
+                for (const receiverId of input.candidates(rec.shape)) {
+                    if (seen.has(receiverId))
+                        continue;
+                    const position = input.positionOf(receiverId);
+                    if (position === undefined)
+                        continue;
+                    if (!shapeContains(rec.shape, position))
+                        continue;
+                    if (input.eligible !== undefined && !input.eligible(sourceId, receiverId, rec.payload))
+                        continue;
+                    seen.add(receiverId);
+                    const member = rec.members.get(receiverId);
+                    if (member === undefined) {
+                        rec.members.set(receiverId, { sinceRefreshMs: 0 });
+                        events.push({ kind: "enter", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                        continue;
+                    }
+                    if (rec.refreshMs !== undefined && rec.refreshMs > 0) {
+                        member.sinceRefreshMs += dtMs;
+                        let ticks = 0;
+                        while (member.sinceRefreshMs >= rec.refreshMs) {
+                            member.sinceRefreshMs -= rec.refreshMs;
+                            ticks += 1;
+                        }
+                        if (ticks > 0) {
+                            events.push({ kind: "refresh", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, ticks });
+                        }
+                    }
+                }
+                for (const receiverId of [...rec.members.keys()]) {
+                    if (seen.has(receiverId))
+                        continue;
+                    rec.members.delete(receiverId);
+                    events.push({ kind: "leave", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, reason: "exit" });
+                }
+            }
+            return events;
+        },
+        members: (sourceId) => [...(sources.get(sourceId)?.members.keys() ?? [])],
+        isMember: (sourceId, receiverId) => sources.get(sourceId)?.members.has(receiverId) ?? false,
+        memberships() {
+            const out = [];
+            for (const [sourceId, rec] of sources) {
+                for (const receiverId of rec.members.keys()) {
+                    out.push({ sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                }
+            }
+            return out;
+        },
+        membershipsOf(receiverId) {
+            const out = [];
+            for (const [sourceId, rec] of sources) {
+                if (rec.members.has(receiverId)) {
+                    out.push({ sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                }
+            }
+            return out;
+        },
+        clear() {
+            const events = [];
+            for (const [sourceId, rec] of sources)
+                events.push(...leaveAll(rec, sourceId, "cleared"));
+            sources.clear();
+            return events;
+        },
+        serialize() {
+            const out = { sources: [], memberships: [] };
+            for (const [id, rec] of sources) {
+                out.sources.push({ id, payload: rec.payload, refreshMs: rec.refreshMs, stackKey: rec.stackKey, enabled: rec.enabled });
+                for (const [receiverId, member] of rec.members) {
+                    out.memberships.push({ sourceId: id, receiverId, sinceRefreshMs: member.sinceRefreshMs });
+                }
+            }
+            return out;
+        },
+    };
+}

package/dist/area/stackPolicy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Overlap aggregation for {@link AreaMembership} lists: when several area sources cover the same
+ * receiver, a policy decides which memberships actually apply. Genre-agnostic and pure — policies
+ * are `(memberships) => memberships` reducers over one receiver's memberships, so the caller stays
+ * in control of magnitude and meaning. Pair with `createAreaEffectField().membershipsOf(receiverId)`.
+ */
+import type { AreaMembership } from "./areaEffectField.js";
+/** Reduce one receiver's overlapping memberships to the subset that applies under a stacking rule. */
+export type AreaStackPolicy<P> = (memberships: readonly AreaMembership<P>[]) => AreaMembership<P>[];
+/** Read a comparable magnitude from a membership (e.g. buff strength, damage per tick). */
+export type MagnitudeOf<P> = (membership: AreaMembership<P>) => number;
+/**
+ * Every overlapping membership applies independently (no deduplication) — the default for hazards,
+ * fields, and lights where two sources genuinely stack.
+ *
+ * @capability area-stack-independent apply every overlapping area membership independently
+ */
+export declare function independentStacks<P>(): AreaStackPolicy<P>;
+/**
+ * Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties
+ * broken by `sourceId` for determinism); without it the first-seen per key wins. Use for
+ * unique-by-key buffs where reapplying the same aura should not stack.
+ *
+ * @capability area-stack-unique keep one area membership per stack key, strongest wins
+ */
+export declare function uniqueByStackKey<P>(magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P>;
+/**
+ * Keep at most `limit` memberships per `stackKey` (the highest-magnitude ones when `magnitudeOf` is
+ * given, else the first-seen). Models capped stacks — e.g. a poison that stacks up to 5 times.
+ *
+ * @capability area-stack-capped cap area memberships per stack key at a maximum count
+ */
+export declare function cappedStacks<P>(limit: number, magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P>;
+/**
+ * Reduce to the single strongest membership overall (`weakest = false` picks the weakest); ties broken
+ * by `sourceId`. Use when only the best or worst overlapping source should apply.
+ *
+ * @capability area-stack-extremum keep only the strongest or weakest overlapping area membership
+ */
+export declare function extremumStack<P>(magnitudeOf: MagnitudeOf<P>, weakest?: boolean): AreaStackPolicy<P>;
+/**
+ * Sum a numeric magnitude across memberships — additive aggregation for a total field strength
+ * (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
+ *
+ * @capability area-stack-additive sum a magnitude across overlapping area memberships
+ */
+export declare function sumMagnitude<P>(memberships: readonly AreaMembership<P>[], magnitudeOf: MagnitudeOf<P>): number;

package/dist/area/stackPolicy.js

@@ -0,0 +1,99 @@
+/**
+ * Overlap aggregation for {@link AreaMembership} lists: when several area sources cover the same
+ * receiver, a policy decides which memberships actually apply. Genre-agnostic and pure — policies
+ * are `(memberships) => memberships` reducers over one receiver's memberships, so the caller stays
+ * in control of magnitude and meaning. Pair with `createAreaEffectField().membershipsOf(receiverId)`.
+ */
+function byMagnitudeDesc(magnitudeOf) {
+    return (a, b) => {
+        const diff = magnitudeOf(b) - magnitudeOf(a);
+        if (diff !== 0)
+            return diff;
+        return a.sourceId < b.sourceId ? -1 : a.sourceId > b.sourceId ? 1 : 0;
+    };
+}
+function groupByStackKey(memberships) {
+    const groups = new Map();
+    for (const membership of memberships) {
+        const list = groups.get(membership.stackKey);
+        if (list === undefined)
+            groups.set(membership.stackKey, [membership]);
+        else
+            list.push(membership);
+    }
+    return groups;
+}
+/**
+ * Every overlapping membership applies independently (no deduplication) — the default for hazards,
+ * fields, and lights where two sources genuinely stack.
+ *
+ * @capability area-stack-independent apply every overlapping area membership independently
+ */
+export function independentStacks() {
+    return (memberships) => [...memberships];
+}
+/**
+ * Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties
+ * broken by `sourceId` for determinism); without it the first-seen per key wins. Use for
+ * unique-by-key buffs where reapplying the same aura should not stack.
+ *
+ * @capability area-stack-unique keep one area membership per stack key, strongest wins
+ */
+export function uniqueByStackKey(magnitudeOf) {
+    return (memberships) => {
+        const out = [];
+        for (const group of groupByStackKey(memberships).values()) {
+            if (magnitudeOf === undefined) {
+                out.push(group[0]);
+            }
+            else {
+                out.push([...group].sort(byMagnitudeDesc(magnitudeOf))[0]);
+            }
+        }
+        return out;
+    };
+}
+/**
+ * Keep at most `limit` memberships per `stackKey` (the highest-magnitude ones when `magnitudeOf` is
+ * given, else the first-seen). Models capped stacks — e.g. a poison that stacks up to 5 times.
+ *
+ * @capability area-stack-capped cap area memberships per stack key at a maximum count
+ */
+export function cappedStacks(limit, magnitudeOf) {
+    const cap = Math.max(0, Math.floor(limit));
+    return (memberships) => {
+        const out = [];
+        for (const group of groupByStackKey(memberships).values()) {
+            const ordered = magnitudeOf === undefined ? group : [...group].sort(byMagnitudeDesc(magnitudeOf));
+            for (const membership of ordered.slice(0, cap))
+                out.push(membership);
+        }
+        return out;
+    };
+}
+/**
+ * Reduce to the single strongest membership overall (`weakest = false` picks the weakest); ties broken
+ * by `sourceId`. Use when only the best or worst overlapping source should apply.
+ *
+ * @capability area-stack-extremum keep only the strongest or weakest overlapping area membership
+ */
+export function extremumStack(magnitudeOf, weakest = false) {
+    return (memberships) => {
+        if (memberships.length === 0)
+            return [];
+        const ordered = [...memberships].sort(byMagnitudeDesc(magnitudeOf));
+        return [weakest ? ordered[ordered.length - 1] : ordered[0]];
+    };
+}
+/**
+ * Sum a numeric magnitude across memberships — additive aggregation for a total field strength
+ * (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
+ *
+ * @capability area-stack-additive sum a magnitude across overlapping area memberships
+ */
+export function sumMagnitude(memberships, magnitudeOf) {
+    let total = 0;
+    for (const membership of memberships)
+        total += magnitudeOf(membership);
+    return total;
+}

package/dist/audio/audioFalloff.d.ts

@@ -1,3 +1,4 @@
+import type { SynthPatch } from "./synth.js";
 export type AudioBusId = string;
 export type FalloffCurve = "linear" | "inverse" | "none";
 export interface AudioFalloffConfig {
@@ -15,8 +16,10 @@ export interface AudioBusDef {
 }
 export interface SoundDef {
     id: string;
-    /** Playable source — a URL/data URI the shell's Web Audio glue fetches and decodes. */
-    url: string;
+    /** Sample source — a URL/data URI the shell's Web Audio glue fetches and decodes. Provide exactly one of `url` or `synth`. */
+    url?: string;
+    /** Procedural source — a pure synth patch the shell realises on Web Audio, no file fetch. Provide exactly one of `url` or `synth`. */
+    synth?: SynthPatch;
     bus: AudioBusId;
     /** Base gain before bus/falloff multipliers. Default 1. */
     gain?: number;

package/dist/audio/music.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Named synthesised instrument. Each maps to a voice in the shell's instrument
+ * library (`@jgengine/shell/audio/musicVoices`); an unknown name falls back to a
+ * plain sine voice so a theme is never silent.
+ */
+export type MusicInstrument = "strings" | "flute" | "harp" | "horn" | "choir" | "bell" | "timpani" | "bass" | "stacc" | "pad" | "lute" | "dulcimer" | "frameDrum" | "warDrum" | "reed" | "pipe" | "squareLead" | "woodBlock" | "tinyBell" | "piano" | "shaker" | "brassStab" | "cymSwell" | "oboe";
+/** One scheduled note in a theme, positioned on the loop's quarter-note grid. */
+export interface NoteEvent {
+    /** Quarter-note position within the loop (0-based). */
+    beat: number;
+    /** MIDI note number (60 = middle C). */
+    midi: number;
+    /** Sounding length in quarter-note beats. */
+    dur: number;
+    /** Velocity 0..1. */
+    vel: number;
+    /** Which instrument voice plays it. */
+    inst: MusicInstrument;
+}
+/**
+ * A through-composed, looping music track. `events` need not be sorted; the
+ * director schedules them ahead against a fixed anchor so loops are seamless.
+ */
+export interface MusicTheme {
+    id: string;
+    /** Tempo in beats (quarter notes) per minute. */
+    bpm: number;
+    /** Loop length in 4/4 bars; the loop is `bars * 4` beats long. */
+    bars: number;
+    events: readonly NoteEvent[];
+    /**
+     * Per-theme loudness normalisation multiplied into the crossfade target, so
+     * dense and sparse themes sit at the same perceived level. Default 1.
+     */
+    trim?: number;
+}
+/** A resolved note occurrence: the source note plus its absolute onset in seconds. */
+export interface ScheduledNote {
+    event: NoteEvent;
+    /** Absolute onset in seconds, on the timeline of the `anchorSec`/window args. */
+    when: number;
+}
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export declare function mtof(midi: number): number;
+/** Loop length of a theme in seconds. */
+export declare function themeLoopSeconds(theme: MusicTheme): number;
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export declare function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[];

package/dist/audio/music.js

@@ -0,0 +1,34 @@
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export function mtof(midi) {
+    return 440 * 2 ** ((midi - 69) / 12);
+}
+/** Loop length of a theme in seconds. */
+export function themeLoopSeconds(theme) {
+    return (theme.bars * 4 * 60) / theme.bpm;
+}
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export function notesInWindow(theme, anchorSec, fromSec, toSec) {
+    const loop = themeLoopSeconds(theme);
+    if (loop <= 0 || toSec <= fromSec)
+        return [];
+    const spb = 60 / theme.bpm;
+    const out = [];
+    for (const event of theme.events) {
+        const onset = event.beat * spb;
+        let k = Math.max(0, Math.floor((fromSec - anchorSec - onset) / loop));
+        for (;;) {
+            const when = anchorSec + onset + k * loop;
+            if (when > toSec)
+                break;
+            if (when > fromSec)
+                out.push({ event, when });
+            k += 1;
+        }
+    }
+    return out;
+}

package/dist/audio/synth.d.ts

@@ -0,0 +1,60 @@
+/** Oscillator waveform available to a pitched synth voice. */
+export type SynthWave = "sine" | "square" | "sawtooth" | "triangle";
+/** Biquad filter shape a noise voice is coloured through. */
+export type SynthFilter = "lowpass" | "highpass" | "bandpass";
+/**
+ * A pitched oscillator voice: a 12ms linear attack to `gain`, then an
+ * exponential decay to silence across `duration`, with an optional
+ * exponential pitch slide from `freq` to `slideTo`.
+ */
+export interface ToneVoice {
+    kind: "tone";
+    /** Start frequency in Hz. */
+    freq: number;
+    /** Total voice length in seconds (the decay spans this). */
+    duration: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Oscillator waveform. Default "sine". */
+    wave?: SynthWave;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+    /** When set, pitch ramps exponentially from `freq` to this Hz across `duration`. */
+    slideTo?: number;
+    /** Attack ramp in seconds. Default 0.012. */
+    attack?: number;
+}
+/**
+ * A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised
+ * from a shared 1s noise buffer at a randomised playback rate and start offset,
+ * decaying exponentially to silence at `duration * decay`.
+ */
+export interface NoiseVoice {
+    kind: "noise";
+    /** Total voice length in seconds. */
+    duration: number;
+    /** Biquad cutoff/centre in Hz. */
+    filterFreq: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Filter shape. Default "lowpass". */
+    filterType?: SynthFilter;
+    /** Fraction of `duration` over which the burst decays to silence. Default 0.9. */
+    decay?: number;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+}
+/** One layered voice of a synth cue. */
+export type SynthVoice = ToneVoice | NoiseVoice;
+/**
+ * A procedural sound cue: a set of voices triggered together, each with its own
+ * `delay`, summed into one one-shot. Pure serialisable data — the shell realises
+ * it on Web Audio, so the same catalog runs headless in tests with no `AudioContext`.
+ */
+export interface SynthPatch {
+    voices: readonly SynthVoice[];
+    /** Overall cue gain multiplier applied to every voice. Default 1. */
+    gain?: number;
+}
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export declare function patchDuration(patch: SynthPatch): number;

package/dist/audio/synth.js

@@ -0,0 +1,8 @@
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export function patchDuration(patch) {
+    let end = 0;
+    for (const voice of patch.voices) {
+        end = Math.max(end, (voice.delay ?? 0) + voice.duration);
+    }
+    return end;
+}

package/dist/authoring.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Task-first JGEngine authoring surface.
+ *
+ * Game code should begin here. Domain and runtime deep imports remain available for
+ * advanced composition, but this module intentionally exposes common authored
+ * concepts without requiring callers to understand the repository layout.
+ */
+export { defineGame, type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
+export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";
+export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, type WorldFeature, } from "./world/features.js";
+export { seededRng, seededStreams } from "./random/rng.js";
+export { selectSpawnPoint, type SpawnPointSelectionOptions, type SpawnPointDistanceBias, } from "./ai/spawnPoint.js";
+export { contextVerb } from "./interaction/contextMenu.js";
+export { type ActionCodesMap } from "./input/actionBindings.js";
+export { classifyOwnership, collectOwnershipDiagnostics, auditManifest, ownershipKey, isSceneOwnershipManifest, SCENE_OWNERSHIP_MANIFEST_VERSION, type SceneProvenance, type SceneProvenanceKind, type AuthoredProvenance, type GeneratedProvenance, type RuntimeProvenance, type TransientProvenance, type ProviderCapabilities, type SceneOwnershipDeclaration, type OwnershipDecision, type OwnershipVerdict, type OwnershipDiagnostic, type SceneOwnershipManifest, } from "./scene/sceneOwnership.js";