@jgengine/core 0.7.0 → 0.9.0

package/dist/time/stateSchedule.js

@@ -0,0 +1,121 @@
+export function createStateSchedule(config) {
+    if (config.phases.length === 0)
+        throw new Error("state schedule needs at least one phase");
+    const phases = config.phases.map((phase) => {
+        if (!(phase.durationSeconds > 0)) {
+            throw new Error(`schedule phase duration must be positive, got ${phase.durationSeconds}`);
+        }
+        return phase;
+    });
+    const loop = config.loop ?? true;
+    const offset = config.offsetSeconds ?? 0;
+    const starts = [];
+    let cycleSeconds = 0;
+    for (const phase of phases) {
+        starts.push(cycleSeconds);
+        cycleSeconds += phase.durationSeconds;
+    }
+    function localTime(t) {
+        const shifted = t + offset;
+        if (loop)
+            return ((shifted % cycleSeconds) + cycleSeconds) % cycleSeconds;
+        return Math.max(0, shifted);
+    }
+    function sampleAt(t) {
+        const local = localTime(t);
+        if (!loop && local >= cycleSeconds) {
+            const index = phases.length - 1;
+            const phase = phases[index];
+            return {
+                state: phase.state,
+                index,
+                elapsedSeconds: local - starts[index],
+                remainingSeconds: Number.POSITIVE_INFINITY,
+                fraction: 1,
+            };
+        }
+        let index = phases.length - 1;
+        for (let i = 0; i < phases.length; i += 1) {
+            if (local < starts[i] + phases[i].durationSeconds) {
+                index = i;
+                break;
+            }
+        }
+        const phase = phases[index];
+        const elapsed = local - starts[index];
+        return {
+            state: phase.state,
+            index,
+            elapsedSeconds: elapsed,
+            remainingSeconds: phase.durationSeconds - elapsed,
+            fraction: Math.max(0, Math.min(1, elapsed / phase.durationSeconds)),
+        };
+    }
+    function nextTransitionAt(t) {
+        const sample = sampleAt(t);
+        if (!Number.isFinite(sample.remainingSeconds))
+            return Number.POSITIVE_INFINITY;
+        return t + sample.remainingSeconds;
+    }
+    function windowsOf(match, fromT, horizonSeconds) {
+        const windows = [];
+        const end = fromT + horizonSeconds;
+        let cursor = fromT;
+        let open = null;
+        let guard = phases.length * (Math.ceil(horizonSeconds / cycleSeconds) + 2) + 2;
+        while (cursor < end && guard > 0) {
+            guard -= 1;
+            const sample = sampleAt(cursor);
+            const matches = match(sample.state);
+            if (matches && open === null)
+                open = cursor;
+            const boundary = Number.isFinite(sample.remainingSeconds) ? cursor + sample.remainingSeconds : end;
+            const stop = Math.min(boundary, end);
+            if (!matches && open !== null) {
+                windows.push({ start: open, end: cursor });
+                open = null;
+            }
+            cursor = stop;
+            if (!Number.isFinite(sample.remainingSeconds))
+                break;
+        }
+        if (open !== null)
+            windows.push({ start: open, end: Math.min(cursor, end) });
+        return windows;
+    }
+    return {
+        cycleSeconds,
+        stateAt: (t) => sampleAt(t).state,
+        sampleAt,
+        nextTransitionAt,
+        windowsOf,
+        nextWindow(match, fromT, horizonSeconds = cycleSeconds) {
+            const windows = windowsOf(match, fromT, horizonSeconds);
+            return windows.length > 0 ? windows[0] : null;
+        },
+    };
+}
+/**
+ * Forward-scan any predicate-of-time — a timetable mover's "is the crossing clear at `t`" — for the
+ * next open window. Sampling-based: pick `stepSeconds` at or below half the shortest gap that matters.
+ */
+export function nextClearWindow(isClear, scan) {
+    const minDuration = scan.minDurationSeconds ?? 0;
+    const end = scan.fromSeconds + scan.horizonSeconds;
+    let open = null;
+    for (let t = scan.fromSeconds; t <= end; t += scan.stepSeconds) {
+        if (isClear(t)) {
+            if (open === null)
+                open = t;
+            continue;
+        }
+        if (open !== null) {
+            if (t - open >= minDuration)
+                return { start: open, end: t };
+            open = null;
+        }
+    }
+    if (open !== null && end - open >= minDuration)
+        return { start: open, end };
+    return null;
+}

package/dist/turn/commit.d.ts

@@ -1,4 +1,4 @@
-export type CommitMode = "immediate" | "simultaneous" | "rewind";
+export type CommitMode = "immediate" | "simultaneous" | "resealable";
 export interface SubmittedAction<TAction> {
     participant: string;
     action: TAction;
@@ -21,7 +21,7 @@ export interface CommitController<TAction> {
     pending(): SubmittedAction<TAction>[];
     reveal(): SubmittedAction<TAction>[];
     commit(): SubmittedAction<TAction>[];
-    rewind(): SubmittedAction<TAction>[];
+    discard(): SubmittedAction<TAction>[];
     clear(): void;
 }
 export declare function createCommitController<TAction>(config: CommitControllerConfig): CommitController<TAction>;

package/dist/turn/commit.js

@@ -31,7 +31,7 @@ export function createCommitController(config) {
             if (mode === "immediate") {
                 return { status: "committed", committed: [{ participant, action }] };
             }
-            if (sealed.has(participant) && !(mode === "rewind")) {
+            if (sealed.has(participant) && mode !== "resealable") {
                 return { status: "rejected", committed: [], reason: "already-submitted" };
             }
             sealed.set(participant, action);
@@ -62,7 +62,7 @@ export function createCommitController(config) {
             clear();
             return out;
         },
-        rewind() {
+        discard() {
             const discarded = orderedSubmissions();
             clear();
             return discarded;

package/dist/turn/intent.d.ts

@@ -0,0 +1,14 @@
+export interface DeclaredIntent<TKind extends string = string> {
+    kind: TKind;
+    magnitude?: number;
+    targetId?: string;
+    note?: string;
+}
+export interface IntentBoard<TKind extends string = string> {
+    declare(participantId: string, intent: DeclaredIntent<TKind>): void;
+    peek(participantId: string): DeclaredIntent<TKind> | null;
+    all(): readonly [string, DeclaredIntent<TKind>][];
+    consume(participantId: string): DeclaredIntent<TKind> | null;
+    clear(participantId?: string): void;
+}
+export declare function createIntentBoard<TKind extends string = string>(): IntentBoard<TKind>;

package/dist/turn/intent.js

@@ -0,0 +1,29 @@
+export function createIntentBoard() {
+    const intents = new Map();
+    return {
+        declare(participantId, intent) {
+            intents.set(participantId, { ...intent });
+        },
+        peek(participantId) {
+            const intent = intents.get(participantId);
+            return intent === undefined ? null : { ...intent };
+        },
+        all() {
+            return [...intents.entries()].map(([participantId, intent]) => [participantId, { ...intent }]);
+        },
+        consume(participantId) {
+            const intent = intents.get(participantId);
+            if (intent === undefined)
+                return null;
+            intents.delete(participantId);
+            return intent;
+        },
+        clear(participantId) {
+            if (participantId === undefined) {
+                intents.clear();
+                return;
+            }
+            intents.delete(participantId);
+        },
+    };
+}

package/dist/turn/turnLoop.d.ts

@@ -12,6 +12,8 @@ export interface TurnLoopConfig {
     commit?: {
         mode: CommitMode;
     };
+    onTurnStart?(participantId: string): void;
+    onTurnEnd?(participantId: string): void;
 }
 export interface PoolState {
     id: string;

package/dist/turn/turnLoop.js

@@ -27,6 +27,8 @@ export function createTurnLoop(config) {
     }
     for (const id of order)
         resetPools(id);
+    if (activeIndex >= 0)
+        config.onTurnStart?.(order[activeIndex]);
     function active() {
         return activeIndex >= 0 && activeIndex < order.length ? order[activeIndex] : null;
     }
@@ -48,6 +50,7 @@ export function createTurnLoop(config) {
             activeIndex = -1;
             return state();
         }
+        const previous = active();
         phaseIndex = 0;
         if (activeIndex < 0) {
             activeIndex = 0;
@@ -59,9 +62,13 @@ export function createTurnLoop(config) {
         else {
             activeIndex += 1;
         }
+        if (previous !== null)
+            config.onTurnEnd?.(previous);
         const current = active();
-        if (current !== null)
+        if (current !== null) {
             resetPools(current);
+            config.onTurnStart?.(current);
+        }
         return state();
     }
     function advancePhase() {

package/dist/ui/hudLayout.d.ts

@@ -0,0 +1,58 @@
+export type HudAnchor = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
+export interface HudPlacement {
+    anchor: HudAnchor;
+    dx: number;
+    dy: number;
+}
+export interface HudRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface HudSize {
+    width: number;
+    height: number;
+}
+export interface HudPanelState {
+    id: string;
+    placement: HudPlacement;
+    z: number;
+    moved: boolean;
+}
+export interface HudLayoutState {
+    panels: Record<string, HudPanelState>;
+    locked: boolean;
+    editing: boolean;
+}
+export interface HudLayoutOptions {
+    snap?: number;
+    locked?: boolean;
+}
+export declare function isPanelDraggable(state: HudLayoutState, id: string): boolean;
+export interface HudLayoutStore {
+    getState(): HudLayoutState;
+    subscribe(listener: (state: HudLayoutState) => void): () => void;
+    register(id: string, placement: HudPlacement): void;
+    move(id: string, rect: HudRect, viewport: HudSize): void;
+    bringToFront(id: string): void;
+    setLocked(locked: boolean): void;
+    setEditing(editing: boolean): void;
+    reset(id?: string): void;
+    serialize(): string;
+    hydrate(raw: string | null | undefined): void;
+}
+export declare const HUD_ANCHOR_FRACTIONS: Record<HudAnchor, {
+    fx: number;
+    fy: number;
+}>;
+export declare function isHudAnchor(value: unknown): value is HudAnchor;
+export declare function anchoredPlacement(anchor: HudAnchor, inset: {
+    x: number;
+    y: number;
+}): HudPlacement;
+export declare function nearestAnchor(rect: HudRect, viewport: HudSize): HudAnchor;
+export declare function clampRect(rect: HudRect, viewport: HudSize): HudRect;
+export declare function placementFromRect(rect: HudRect, viewport: HudSize, snap?: number): HudPlacement;
+export declare function rectFromPlacement(placement: HudPlacement, size: HudSize, viewport: HudSize): HudRect;
+export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;

package/dist/ui/hudLayout.js

@@ -0,0 +1,207 @@
+export function isPanelDraggable(state, id) {
+    return state.panels[id] !== undefined && (state.editing || !state.locked);
+}
+export const HUD_ANCHOR_FRACTIONS = {
+    "top-left": { fx: 0, fy: 0 },
+    top: { fx: 0.5, fy: 0 },
+    "top-right": { fx: 1, fy: 0 },
+    left: { fx: 0, fy: 0.5 },
+    center: { fx: 0.5, fy: 0.5 },
+    right: { fx: 1, fy: 0.5 },
+    "bottom-left": { fx: 0, fy: 1 },
+    bottom: { fx: 0.5, fy: 1 },
+    "bottom-right": { fx: 1, fy: 1 },
+};
+const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+export function isHudAnchor(value) {
+    return typeof value === "string" && value in HUD_ANCHOR_FRACTIONS;
+}
+export function anchoredPlacement(anchor, inset) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    return {
+        anchor,
+        dx: fx === 1 ? -inset.x : inset.x,
+        dy: fy === 1 ? -inset.y : inset.y,
+    };
+}
+export function nearestAnchor(rect, viewport) {
+    const cx = viewport.width > 0 ? (rect.x + rect.width / 2) / viewport.width : 0.5;
+    const cy = viewport.height > 0 ? (rect.y + rect.height / 2) / viewport.height : 0.5;
+    let best = "center";
+    let bestDist = Infinity;
+    for (const anchor of HUD_ANCHORS) {
+        const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+        const dist = (cx - fx) * (cx - fx) + (cy - fy) * (cy - fy);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = anchor;
+        }
+    }
+    return best;
+}
+export function clampRect(rect, viewport) {
+    return {
+        x: Math.max(0, Math.min(rect.x, viewport.width - rect.width)),
+        y: Math.max(0, Math.min(rect.y, viewport.height - rect.height)),
+        width: rect.width,
+        height: rect.height,
+    };
+}
+export function placementFromRect(rect, viewport, snap = 1) {
+    const clamped = clampRect(rect, viewport);
+    const anchor = nearestAnchor(clamped, viewport);
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    const step = snap > 0 ? snap : 1;
+    const dx = clamped.x + fx * clamped.width - fx * viewport.width;
+    const dy = clamped.y + fy * clamped.height - fy * viewport.height;
+    return {
+        anchor,
+        dx: Math.round(dx / step) * step,
+        dy: Math.round(dy / step) * step,
+    };
+}
+export function rectFromPlacement(placement, size, viewport) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[placement.anchor];
+    return {
+        x: fx * viewport.width + placement.dx - fx * size.width,
+        y: fy * viewport.height + placement.dy - fy * size.height,
+        width: size.width,
+        height: size.height,
+    };
+}
+function parseSerialized(raw) {
+    const out = new Map();
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (typeof data !== "object" || data === null)
+        return out;
+    const panels = data.panels;
+    if (typeof panels !== "object" || panels === null)
+        return out;
+    for (const [id, value] of Object.entries(panels)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { anchor, dx, dy } = value;
+        if (!isHudAnchor(anchor))
+            continue;
+        if (typeof dx !== "number" || !Number.isFinite(dx))
+            continue;
+        if (typeof dy !== "number" || !Number.isFinite(dy))
+            continue;
+        out.set(id, { anchor, dx, dy });
+    }
+    return out;
+}
+export function createHudLayout(options) {
+    const snap = options?.snap ?? 1;
+    const defaults = new Map();
+    const pending = new Map();
+    let topZ = 0;
+    let state = { panels: {}, locked: options?.locked ?? true, editing: false };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of [...listeners])
+            listener(state);
+    };
+    const setPanel = (panel) => {
+        state = { ...state, panels: { ...state.panels, [panel.id]: panel } };
+    };
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        register(id, placement) {
+            defaults.set(id, placement);
+            if (state.panels[id] !== undefined)
+                return;
+            const override = pending.get(id);
+            setPanel({
+                id,
+                placement: override ?? placement,
+                z: ++topZ,
+                moved: override !== undefined,
+            });
+        },
+        move(id, rect, viewport) {
+            const panel = state.panels[id];
+            if (panel === undefined)
+                return;
+            const placement = placementFromRect(rect, viewport, snap);
+            setPanel({ ...panel, placement, moved: true });
+            emit();
+        },
+        bringToFront(id) {
+            const panel = state.panels[id];
+            if (panel === undefined || panel.z === topZ)
+                return;
+            setPanel({ ...panel, z: ++topZ });
+            emit();
+        },
+        setLocked(locked) {
+            if (state.locked === locked)
+                return;
+            state = { ...state, locked };
+            emit();
+        },
+        setEditing(editing) {
+            if (state.editing === editing)
+                return;
+            state = { ...state, editing };
+            emit();
+        },
+        reset(id) {
+            const ids = id === undefined ? Object.keys(state.panels) : [id];
+            let changed = false;
+            for (const panelId of ids) {
+                pending.delete(panelId);
+                const panel = state.panels[panelId];
+                const fallback = defaults.get(panelId);
+                if (panel === undefined || fallback === undefined || !panel.moved)
+                    continue;
+                setPanel({ ...panel, placement: fallback, moved: false });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+        serialize() {
+            const panels = {};
+            for (const panel of Object.values(state.panels)) {
+                if (panel.moved)
+                    panels[panel.id] = panel.placement;
+            }
+            for (const [id, placement] of pending) {
+                if (state.panels[id] === undefined)
+                    panels[id] = placement;
+            }
+            const data = { v: 1, panels };
+            return JSON.stringify(data);
+        },
+        hydrate(raw) {
+            if (raw === null || raw === undefined || raw === "")
+                return;
+            const parsed = parseSerialized(raw);
+            if (parsed.size === 0)
+                return;
+            let changed = false;
+            for (const [id, placement] of parsed) {
+                const panel = state.panels[id];
+                if (panel === undefined) {
+                    pending.set(id, placement);
+                    continue;
+                }
+                setPanel({ ...panel, placement, moved: true });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+    };
+}

package/dist/ui/hudScale.d.ts

@@ -0,0 +1,44 @@
+import type { HudRect, HudSize } from "./hudLayout.js";
+/** Where a game is meant to be played. `"web"` alone keeps today's desktop-first HUD; adding `"mobile"` turns on design-resolution fit scaling on compact displays. */
+export type HudPlatform = "web" | "mobile";
+/**
+ * Design-resolution fit for the HUD surface. The game authors its UI against
+ * `designSize`; on smaller viewports the whole HUD scales down by the limiting
+ * axis ratio, clamped to `[minScale, maxScale]`, so panels keep their layout
+ * and simply shrink instead of overflowing.
+ */
+export interface HudFitConfig {
+    designSize?: HudSize;
+    /** Floor for the computed scale — below this, shrinking further makes text unreadable. Default 0.4. */
+    minScale?: number;
+    /** Ceiling for the computed scale. Default 1 (never upscale past authored size). */
+    maxScale?: number;
+}
+/** Per-game HUD viewport declaration carried on `PlayableGame.hudFit`; `mobile` overrides the fit on compact displays so the owner can tune the phone layout separately. */
+export interface HudViewportConfig extends HudFitConfig {
+    mobile?: HudFitConfig;
+}
+export declare const DEFAULT_HUD_DESIGN_SIZE: HudSize;
+export declare const DEFAULT_HUD_MIN_SCALE = 0.4;
+export declare const DEFAULT_HUD_MAX_SCALE = 1;
+export declare function resolveHudFit(config: HudViewportConfig | undefined, mobile: boolean): Required<HudFitConfig>;
+/**
+ * The one scaling rule for every display: the ratio of the live viewport to
+ * the authored design size along the limiting axis, clamped. 1 on a viewport
+ * at or above design size; smoothly below 1 down to `minScale` on phones.
+ */
+export declare function hudScaleForViewport(fit: Required<HudFitConfig>, viewport: HudSize): number;
+export interface HudOverflow {
+    id: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
+export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
+/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+export declare function overflowingPanels(panels: readonly {
+    id: string;
+    rect: HudRect;
+}[], viewport: HudSize, tolerance?: number): HudOverflow[];

package/dist/ui/hudScale.js

@@ -0,0 +1,55 @@
+export const DEFAULT_HUD_DESIGN_SIZE = { width: 1600, height: 900 };
+export const DEFAULT_HUD_MIN_SCALE = 0.4;
+export const DEFAULT_HUD_MAX_SCALE = 1;
+export function resolveHudFit(config, mobile) {
+    const base = {
+        designSize: config?.designSize ?? DEFAULT_HUD_DESIGN_SIZE,
+        minScale: config?.minScale ?? DEFAULT_HUD_MIN_SCALE,
+        maxScale: config?.maxScale ?? DEFAULT_HUD_MAX_SCALE,
+    };
+    if (!mobile || config?.mobile === undefined)
+        return base;
+    return {
+        designSize: config.mobile.designSize ?? base.designSize,
+        minScale: config.mobile.minScale ?? base.minScale,
+        maxScale: config.mobile.maxScale ?? base.maxScale,
+    };
+}
+/**
+ * The one scaling rule for every display: the ratio of the live viewport to
+ * the authored design size along the limiting axis, clamped. 1 on a viewport
+ * at or above design size; smoothly below 1 down to `minScale` on phones.
+ */
+export function hudScaleForViewport(fit, viewport) {
+    if (!Number.isFinite(viewport.width) ||
+        !Number.isFinite(viewport.height) ||
+        viewport.width <= 0 ||
+        viewport.height <= 0 ||
+        fit.designSize.width <= 0 ||
+        fit.designSize.height <= 0) {
+        return 1;
+    }
+    const ratio = Math.min(viewport.width / fit.designSize.width, viewport.height / fit.designSize.height);
+    return Math.min(fit.maxScale, Math.max(fit.minScale, ratio));
+}
+/** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
+export function rectOverflow(rect, viewport, tolerance = 1.5) {
+    const left = Math.max(0, -rect.x);
+    const top = Math.max(0, -rect.y);
+    const right = Math.max(0, rect.x + rect.width - viewport.width);
+    const bottom = Math.max(0, rect.y + rect.height - viewport.height);
+    if (left <= tolerance && top <= tolerance && right <= tolerance && bottom <= tolerance)
+        return null;
+    const round = (n) => Math.round(n * 10) / 10;
+    return { left: round(left), top: round(top), right: round(right), bottom: round(bottom) };
+}
+/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+export function overflowingPanels(panels, viewport, tolerance = 1.5) {
+    const out = [];
+    for (const panel of panels) {
+        const overflow = rectOverflow(panel.rect, viewport, tolerance);
+        if (overflow !== null)
+            out.push({ id: panel.id, ...overflow });
+    }
+    return out;
+}

package/dist/visibility/assetStreaming.d.ts

@@ -0,0 +1,66 @@
+import type { StreamingSettings } from "./settings.js";
+import type { VisibilityStats } from "./diagnostics.js";
+export type AssetLoadState = "queued" | "loading" | "loaded" | "unloaded" | "error";
+export interface AssetLoadResult {
+    /** Approximate resident size, used for the memory budget and small-asset resident policy. */
+    readonly bytes?: number;
+    /** Opaque handle to the loaded resource (texture, mesh, buffer). */
+    readonly value?: unknown;
+}
+export interface CancelSignal {
+    readonly cancelled: boolean;
+}
+export interface AssetStreamingOptions {
+    /** Async loader. Must honor `signal.cancelled` and avoid committing work when it flips true. */
+    readonly load: (assetId: string, signal: CancelSignal) => Promise<AssetLoadResult>;
+    /** Release GPU/CPU resources for an asset. */
+    readonly unload?: (assetId: string) => void;
+    readonly settings?: Partial<StreamingSettings>;
+    readonly now?: () => number;
+}
+export interface AssetRecord {
+    readonly id: string;
+    state: AssetLoadState;
+    bytes: number;
+    priority: number;
+    refCount: number;
+    pinned: boolean;
+    lastActiveMs: number;
+    value: unknown;
+}
+export interface StreamingStats {
+    queued: number;
+    loading: number;
+    loaded: number;
+    unloaded: number;
+    errored: number;
+    inFlight: number;
+    cancelled: number;
+    bytes: number;
+}
+export interface AssetStreamingSystem {
+    /** Demand an asset (near/in view). Deduplicated — an already loaded/loading/queued asset is never re-fetched concurrently. */
+    request(assetId: string, priority?: number): void;
+    /** Shared ownership by an active object. A retained asset (refCount > 0) is never auto-unloaded. */
+    retain(assetId: string): void;
+    release(assetId: string): void;
+    /** Pin resident regardless of distance/refcount/scene. */
+    pin(assetId: string): void;
+    unpin(assetId: string): void;
+    /** Refresh the "last needed" timestamp used by the grace-period unload. */
+    markActive(assetId: string): void;
+    /** Advance one frame: start up to the load budget, evict past-grace assets up to the unload budget. */
+    tick(dt: number): void;
+    /** Cancel an in-flight or queued request that is no longer needed. */
+    cancel(assetId: string): void;
+    stateOf(assetId: string): AssetLoadState | undefined;
+    isLoaded(assetId: string): boolean;
+    record(assetId: string): AssetRecord | undefined;
+    stats(): StreamingStats;
+    /** Merge asset counters into a per-frame VisibilityStats. */
+    applyTo(stats: VisibilityStats): void;
+    /** Resolve once every in-flight load settles — for deterministic tests. */
+    settle(): Promise<void>;
+    clear(): void;
+}
+export declare function createAssetStreamingSystem(options: AssetStreamingOptions): AssetStreamingSystem;