@aura3d/engine 3.0.0 → 4.0.0

package/dist/engine/contracts/flags.js

@@ -0,0 +1,205 @@
+/**
+ * §1.1 / §5.2 — flag resolution (CONTRACTS.md). Custodian: PRD 15.
+ *
+ * Sources in precedence order; the first source that sets a flag wins:
+ *   1. explicit `qualityRebuild: { flags }` option
+ *   2. URL `?a3d-qr=<list>` (ignored by callers when allowUrlFlags is false)
+ *   3. environment `A3D_QR=<list>` / `import.meta.env.VITE_A3D_QR`
+ *   4. per-flag `A3D_QR_<AREA>=1|0|value`
+ *   5. the registry default (all flags off while every flag is `dev`, §5.3)
+ */
+import { QR_FLAG_STATES, REMOVED_QR_FLAGS } from "../../rendering/contracts/flags.state.js";
+const SHORT_NAMES = {
+    core: "A3D_QR_CORE",
+    lighting: "A3D_QR_LIGHTING",
+    post: "A3D_QR_POST",
+    materials: "A3D_QR_MATERIALS",
+    assets: "A3D_QR_ASSETS",
+    animation: "A3D_QR_ANIMATION",
+    vfx: "A3D_QR_VFX",
+    camera: "A3D_QR_CAMERA",
+    game: "A3D_QR_GAME",
+    world: "A3D_QR_WORLD",
+    tiers: "A3D_QR_TIERS",
+    webgpu: "A3D_QR_WEBGPU",
+    looks: "A3D_QR_LOOKS",
+    compiler: "A3D_QR_COMPILER",
+    strict: "A3D_QR_STRICT"
+};
+const LANE_FLAGS = Object.values(SHORT_NAMES);
+/**
+ * #266 (Q-15-6) — sub-flags whose PRD declares them ON BY DEFAULT under their
+ * lane flag; they exist as kill switches (`-world.biome`), not opt-ins. `all`
+ * expands them like lane flags, and a lane flag resolved on from any source
+ * fills its unset sub-flags after every source applied (explicit values win).
+ * PRD-10 §13 (`worldSubflagOn`) already reads these parent-defaulted, so the
+ * expansion matches it and makes direct `flags.on(sub)` / registry `flag:`
+ * gates agree. Not listed: PRD-01's `A3D_QR_CORE_{GENERATOR,OUTPUT}` (lane 01
+ * resolves them through `qrCoreGeneratorOn`/`qrCoreOutputOn` and pins the raw
+ * value unset under `core`), and opt-in/default-off sub-flags (e.g.
+ * `A3D_QR_POST_VELOCITY_MRT`), which stay explicit-only. Flag states live in
+ * `flags.state.ts`; this table only records parent→sub defaults.
+ */
+const DEFAULT_ON_SUB_FLAGS = {
+    A3D_QR_WORLD: ["A3D_QR_WORLD_TERRAIN", "A3D_QR_WORLD_WATER", "A3D_QR_WORLD_BIOME"]
+};
+function flagValueOn(v) {
+    return v !== undefined && v !== false && v !== "0" && v !== "off" && v !== "";
+}
+/** #266: fill unset default-on sub-flags of every lane flag that resolved on. */
+/**
+ * Promotion (§5.3, owner decision 2026-10-11): a flag whose state is
+ * `default-on` in flags.state.ts is on unless some source set it explicitly.
+ * Runs after every source, so `none`, `-x` and `A3D_QR_X=0` still turn it off.
+ */
+function applyDefaultOnStates(out) {
+    for (const [name, state] of Object.entries(QR_FLAG_STATES)) {
+        if (state === "default-on")
+            setEntry(out, name, true);
+    }
+}
+function propagateSubFlags(out) {
+    for (const [parent, subs] of Object.entries(DEFAULT_ON_SUB_FLAGS)) {
+        if (!flagValueOn(out[parent]) || !subs)
+            continue;
+        for (const sub of subs)
+            setEntry(out, sub, true);
+    }
+}
+function flagNameFor(short) {
+    const lower = short.toLowerCase();
+    if (lower in SHORT_NAMES)
+        return SHORT_NAMES[lower];
+    const sub = lower.split(/[._]/).filter((s) => s.length > 0);
+    // #72: multi-segment names — `core.shadows.cascade` →
+    // `A3D_QR_CORE_SHADOWS_CASCADE`; `route.demo.alpha` → `A3D_QR_ROUTE_DEMO_ALPHA`.
+    if (sub.length >= 2 && sub[0] in SHORT_NAMES) {
+        return `A3D_QR_${sub[0].toUpperCase()}_${sub.slice(1).join("_").toUpperCase()}`;
+    }
+    if (sub.length >= 2 && sub[0] === "route") {
+        return `A3D_QR_ROUTE_${sub.slice(1).join("_").toUpperCase()}`;
+    }
+    return null;
+}
+function setEntry(out, name, value) {
+    if (!(name in out))
+        out[name] = value;
+}
+/** `all` | `none` | comma list of short names with `-name` exclusions and `name=value` values. */
+function applyList(out, list) {
+    const tokens = list.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        for (const flag of LANE_FLAGS)
+            setEntry(out, flag, false);
+        return;
+    }
+    // #625: `all` / `none` are positional tokens too (`route_bank_shot,all`).
+    // First write wins, so explicit tokens apply before the blanket one: in
+    // `all,-world` the explicit `-world` still turns world off. Sub-flags are
+    // filled by propagateSubFlags after every source applied.
+    let blanket = null;
+    for (const t of tokens) {
+        if (t === "all" || t === "none") {
+            blanket ??= t;
+            continue;
+        }
+        const negated = t.startsWith("-");
+        const body = negated ? t.slice(1) : t;
+        const eq = body.indexOf("=");
+        const name = flagNameFor(eq >= 0 ? body.slice(0, eq) : body);
+        if (!name)
+            continue;
+        const value = negated ? false : eq >= 0 ? body.slice(eq + 1) : true;
+        setEntry(out, name, value);
+    }
+    if (blanket !== null)
+        for (const flag of LANE_FLAGS)
+            setEntry(out, flag, blanket === "all");
+}
+function applyInput(out, input) {
+    // Any string ("all", "none", "camera,-post") is a flag list. Before this, "none"
+    // fell through to Object.entries(string), set nothing, and default-on flags won.
+    if (typeof input === "string") {
+        applyList(out, input);
+        return;
+    }
+    if (Array.isArray(input)) {
+        for (const token of input)
+            applyList(out, token);
+        return;
+    }
+    for (const [name, value] of Object.entries(input)) {
+        if (value !== undefined)
+            setEntry(out, name, value);
+    }
+}
+function applyPerFlagEnv(out, env) {
+    for (const [name, raw] of Object.entries(env)) {
+        if (!name.startsWith("A3D_QR_") || name === "A3D_QR" || raw === undefined)
+            continue;
+        const value = raw === "0" || raw === "off" || raw === "false" ? false : raw === "1" || raw === "on" || raw === "true" ? true : raw;
+        setEntry(out, name, value);
+    }
+}
+/**
+ * T1.11 (PRD-06 §10): `animation.mixer: "pose"` is the documented alias for
+ * the `A3D_QR_ANIMATION_POSE_MIXER` sub-flag. Compose it onto a resolved
+ * `QrFlags`; an explicit value already resolved for the sub-flag wins, so a
+ * caller can still turn it off through `qualityRebuild.flags`.
+ */
+export function qrFlagsWithAnimationMixer(flags, mixer) {
+    if (mixer !== "pose" || flags.values.A3D_QR_ANIMATION_POSE_MIXER !== undefined) {
+        return flags;
+    }
+    const values = Object.freeze({
+        ...flags.values,
+        A3D_QR_ANIMATION_POSE_MIXER: true
+    });
+    return {
+        values,
+        on(name) {
+            const v = values[name];
+            return v !== undefined && v !== false && v !== "0" && v !== "off" && v !== "";
+        }
+    };
+}
+export function resolveQrFlags(input) {
+    const values = {};
+    // Precedence (first write wins): URL `a3d-qr` > env (A3D_QR list, then A3D_QR_X) >
+    // programmatic options > flags.state default-on. Runtime overrides must beat
+    // values baked into app code, or `-x` / `none` can't measure a flag (#1232).
+    if (input.url !== undefined) {
+        const url = typeof input.url === "string" ? new URL(input.url, "http://localhost/") : input.url;
+        const list = url.searchParams.get("a3d-qr");
+        if (list !== null)
+            applyList(values, list);
+    }
+    if (input.env !== undefined) {
+        const list = input.env.A3D_QR ?? input.env.VITE_A3D_QR;
+        if (list !== undefined)
+            applyList(values, list);
+        applyPerFlagEnv(values, input.env);
+    }
+    if (input.options !== undefined)
+        applyInput(values, input.options);
+    applyDefaultOnStates(values);
+    propagateSubFlags(values);
+    for (const removed of REMOVED_QR_FLAGS) {
+        if (values[removed] !== undefined) {
+            delete values[removed];
+            if (typeof console !== "undefined")
+                console.warn(`QR_FLAG_REMOVED:${removed}`);
+        }
+    }
+    const frozen = Object.freeze({ ...values });
+    return {
+        values: frozen,
+        on(name) {
+            const v = frozen[name];
+            return v !== undefined && v !== false && v !== "0" && v !== "off" && v !== "";
+        }
+    };
+}
+// createAuraApp/createGameApp option (C-38):
+//   qualityRebuild?: { readonly flags?: QrFlagInput; readonly allowUrlFlags?: boolean /* default true */ }
+//# sourceMappingURL=flags.js.map

package/dist/engine/contracts/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/flags.ts"],"names":[],"mappings":"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"}

package/dist/engine/contracts/game.d.ts

@@ -0,0 +1,178 @@
+/**
+ * C-24 — GameShell, Session, HUD, Touch, capture context (CONTRACTS.md). Provider: PRD 09.
+ * Flag: A3D_QR_GAME. The stub lives in `./stubs/game.ts`.
+ */
+import type { AuraVec3, AuraSceneSnapshot, AuraApp } from "../agent-api/index.js";
+import type { GameAudio } from "../game/GameAudio.js";
+export type GameSessionState = "booting" | "loading" | "title" | "playing" | "paused" | "results" | "transitioning" | "context-lost" | "disposed";
+export type PauseReason = "user" | "blur" | "visibility" | "menu" | "context-lost";
+export interface TransitionSpec {
+    readonly kind: "fade" | "cut" | "wipe";
+    readonly ms?: number;
+    readonly color?: string;
+}
+export interface GameSession {
+    readonly state: GameSessionState;
+    readonly paused: boolean;
+    readonly timeScale: number;
+    readonly simTime: number;
+    readonly seed: number;
+    readonly reducedMotion: boolean;
+    readonly reducedFlash: boolean;
+    readonly highContrast: boolean;
+    pause(reason?: PauseReason): void;
+    resume(): void;
+    setTimeScale(scale: number, o?: {
+        rampMs?: number;
+    }): void;
+    hitStop(seconds: number, o?: {
+        actors?: readonly string[];
+    }): void;
+    slowMo(scale: number, ms: number, o?: {
+        ease?: string;
+    }): void;
+    scaledDt(rawDt: number, actorId?: string): number;
+    isFrozen(actorId?: string): boolean;
+    on(event: "state" | "pause" | "resume" | "settings", cb: (s: GameSession) => void): () => void;
+}
+export interface GameShell {
+    readonly state: GameSessionState;
+    showResults(values: Readonly<Record<string, number>>): Promise<"retry" | "title" | "next">;
+    transition<T>(run: () => T | Promise<T>, spec?: TransitionSpec): Promise<T>;
+    openMenu(id: "pause" | "settings" | "about"): void;
+    closeMenus(): void;
+    setLoadingProgress(fraction: number, label?: string): void;
+    track(promise: Promise<unknown>, weight: number): void;
+}
+export type GameShellLayout = "full-bleed" | "letterbox-16x9" | "letterbox-4x3";
+export interface HudWidgetSpec {
+    readonly id: string;
+    readonly kind: string;
+    readonly anchor: "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
+    readonly label?: string;
+}
+export interface Hud {
+    set(id: string, value: unknown): void;
+    banner(text: string, o?: {
+        holdMs?: number;
+        style?: string;
+    }): Promise<void>;
+    toast(text: string, o?: {
+        ms?: number;
+    }): void;
+    damageNumber(value: number, world: AuraVec3, o?: {
+        color?: string;
+        crit?: boolean;
+    }): void;
+    setVisible(v: boolean): void;
+    snapshot(): {
+        readonly widgets: readonly {
+            readonly id: string;
+            readonly value: unknown;
+            readonly screenFraction: number;
+        }[];
+    };
+    dispose(): void;
+}
+export interface HudMountOptions {
+    readonly theme?: "arcade-neon" | "motorsport" | "sports-broadcast" | "sci-fi-telemetry" | "fighting" | "tabletop" | "plain" | Readonly<Record<`--a3g-${string}`, string>>;
+    readonly widgets: readonly HudWidgetSpec[];
+    readonly maxScreenFraction?: number;
+}
+export type TouchPreset = "twin-stick" | "dpad-2btn" | "dpad-4btn" | "steer-pedals" | "aim-drag" | "flight" | "lane-swipe" | "flippers";
+export interface TouchControls {
+    readonly visible: boolean;
+    setVisible(v: boolean): void;
+    dispose(): void;
+}
+export type GameFxKind = "spark" | "dust" | "debris" | "ring" | "streak" | "pickup" | "explosion-small" | "muzzle" | "splash" | "bubble";
+export interface GameFxLayer {
+    burst(kind: GameFxKind, position: AuraVec3, o?: {
+        count?: number;
+        speed?: number;
+        color?: string;
+        normal?: AuraVec3;
+        seed?: number;
+    }): void;
+    trail(target: string, o: {
+        width: number;
+        life: number;
+        color?: string;
+    }): {
+        stop(): void;
+    };
+    readonly liveCount: number;
+    readonly backend: "primitive-pool" | "particle-pass";
+}
+export interface CaptureContext {
+    readonly mode: "play" | "scenario";
+    readonly scenario?: string;
+    readonly seed?: number;
+    readonly freezeAt?: number;
+    readonly cameraPose?: string;
+}
+export interface GameScenario {
+    readonly description: string;
+    setup(game: unknown): void | Promise<void>;
+}
+export interface GameBeacon {
+    readonly route: string;
+    readonly state: GameSessionState;
+    readonly frame: number;
+    readonly firstFrameAt: number | null;
+    readonly sessionStartedAt: number; /** Live mounted app (snapshotForAudit + budget lanes read app.scene / app.diagnostics()); absent before mount. */
+    readonly app?: {
+        readonly scene?: unknown;
+        diagnostics?: () => Record<string, unknown>;
+    };
+    readonly scene?: unknown;
+    readonly session?: unknown;
+}
+export interface CreateGameOptions<TCue extends string, TEvent extends string> {
+    readonly id: string;
+    readonly target: HTMLElement;
+    readonly scene: () => unknown;
+    readonly layout?: GameShellLayout;
+    readonly hud?: HudMountOptions;
+    readonly touch?: {
+        readonly preset: TouchPreset;
+        readonly bindings: Readonly<Record<string, string>>;
+    };
+    readonly sound?: unknown;
+    readonly juice?: Readonly<Record<TEvent, unknown>>;
+    readonly qualityRebuild?: {
+        readonly flags?: readonly string[];
+    };
+}
+/** Juice driver facade (PRD-09 §7.6): `fire(event)` maps a game event to synchronized fx/audio/rumble. */
+export interface GameJuice<TEvent extends string = string> {
+    fire(event: TEvent, at?: {
+        position?: AuraVec3;
+        strength?: number;
+        actors?: readonly string[];
+    }): void;
+}
+export interface Game<TCue extends string = string, TEvent extends string = string> {
+    readonly id: string;
+    readonly app: AuraApp;
+    readonly session: GameSession;
+    readonly shell: GameShell;
+    readonly hud: Hud;
+    readonly touch: TouchControls | null;
+    readonly fx: GameFxLayer;
+    readonly capture: CaptureContext; /** Juice driver built from `options.juice`. */
+    readonly juice: GameJuice<TEvent>; /** C-25 audio facade; present only when `options.sound` was provided. */
+    readonly sound?: GameAudio<TCue>;
+    ready(): Promise<void>;
+    start(): void;
+    setScene(scene: AuraSceneSnapshot, o?: {
+        transition?: TransitionSpec | false;
+    }): Promise<void>;
+    dispose(): Promise<void>;
+}
+export { createGame } from "./stubs/game.js";
+/** PR 0a: real — pure URL parsing. `?capture=review|overview` warns and is ignored. */
+export declare function captureFromUrl(url?: URL): CaptureContext;
+export { createFrameLoop } from "../agent-api/FrameLoop.js";
+export type { FrameLoopCallback, FrameLoopFrame, FrameLoopOptions, FrameLoopSnapshot, FrameLoopSource } from "../agent-api/FrameLoop.js";
+//# sourceMappingURL=game.d.ts.map

package/dist/engine/contracts/game.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/game.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,eAAe,GAAG,cAAc,GAAG,UAAU,CAAC;AAClJ,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,CAAC;AACnF,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAAE;AAC1H,MAAM,WAAW,WAAW;IAAG,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,MAAM,IAAI,IAAI,CAAC;IAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAAE;AACrrB,MAAM,WAAW,SAAS;IAAG,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;IAAC,UAAU,IAAI,IAAI,CAAC;IAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAAE;AACra,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAChF,MAAM,WAAW,aAAa;IAAG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAAE;AACpO,MAAM,WAAW,GAAG;IAAG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,QAAQ,IAAI;QAAE,QAAQ,CAAC,OAAO,EAAE,SAAS;YAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;YAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAAC,OAAO,IAAI,IAAI,CAAC;CAAE;AACxc,MAAM,WAAW,eAAe;IAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAAE;AAChS,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AACxI,MAAM,WAAW,aAAa;IAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,OAAO,IAAI,IAAI,CAAC;CAAE;AAC5G,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACzI,MAAM,WAAW,WAAW;IAAG,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAAC;CAAE;AAC5V,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAAE;AACrL,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,IAAI,EAAE,OAAO,GAAc,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAAE;AACtH,MAAM,WAAW,UAAU;IAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,kHAAkH;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAAE;AAG7b,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IAAI,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAmC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAAE;AACjgB,0GAA0G;AAC1G,MAAM,WAAW,SAAS,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CAAE;AACtK,MAAM,WAAW,IAAI,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,SAAS,MAAM,GAAG,MAAM;IAAI,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,+CAA+C;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,yEAAyE;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,IAAI,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,cAAc,GAAG,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAAE;AAClpB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,cAAc,CAqBxD;AAID,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/engine/contracts/game.js

@@ -0,0 +1,34 @@
+/**
+ * C-24 — GameShell, Session, HUD, Touch, capture context (CONTRACTS.md). Provider: PRD 09.
+ * Flag: A3D_QR_GAME. The stub lives in `./stubs/game.ts`.
+ */
+export { createGame } from "./stubs/game.js";
+/** PR 0a: real — pure URL parsing. `?capture=review|overview` warns and is ignored. */
+export function captureFromUrl(url) {
+    if (url === undefined || typeof URL === "undefined")
+        return { mode: "play" };
+    const captureMatch = /(?:^\?|&)capture=(review|overview)(?:&|$)/.exec(url.search);
+    if (captureMatch !== null) {
+        if (typeof console !== "undefined")
+            console.warn(`capture:${captureMatch[1]} is ignored`);
+        return { mode: "play" };
+    }
+    const scenario = url.searchParams.get("scenario") ?? undefined;
+    const seedRaw = url.searchParams.get("seed");
+    const freezeAtRaw = url.searchParams.get("freezeAt");
+    const cameraPose = url.searchParams.get("cameraPose") ?? undefined;
+    if (scenario === undefined && seedRaw === null && freezeAtRaw === null && cameraPose === undefined) {
+        return { mode: "play" };
+    }
+    return {
+        mode: "scenario",
+        scenario,
+        seed: seedRaw !== null ? Number(seedRaw) : undefined,
+        freezeAt: freezeAtRaw !== null ? Number(freezeAtRaw) : undefined,
+        cameraPose
+    };
+}
+// T0-32: bf1789b0 dropped `createFrameLoop` from "." — re-export under C-24
+// (the game/frame-loop entry lane-08 owns) so scaffold keeps it live.
+export { createFrameLoop } from "../agent-api/FrameLoop.js";
+//# sourceMappingURL=game.js.map

package/dist/engine/contracts/game.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.js","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/game.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,GAAS;IACtC,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,WAAW;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC7E,MAAM,YAAY,GAAG,2CAA2C,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClF,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,OAAO,OAAO,KAAK,WAAW;YAAE,OAAO,CAAC,IAAI,CAAC,WAAW,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;QAC1F,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC;IAC/D,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC;IACnE,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,WAAW,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACnG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,QAAQ;QACR,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QACpD,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;QAChE,UAAU;KACX,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/engine/contracts/gameSound.d.ts

@@ -0,0 +1,3 @@
+import type { createGameSoundEngine } from "../../audio/index.js";
+export declare const gameSoundSlot: import("../../rendering/contracts/index.js").ContractSlot<typeof createGameSoundEngine>;
+//# sourceMappingURL=gameSound.d.ts.map

package/dist/engine/contracts/gameSound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameSound.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/gameSound.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAM3D,eAAO,MAAM,aAAa,kFAKzB,CAAC"}

package/dist/engine/contracts/gameSound.js

@@ -0,0 +1,12 @@
+/**
+ * C-25 — game sound contract slot (CONTRACTS.md). Provider: PRD 09.
+ * Flag: A3D_QR_GAME. `createGameAudio` resolves through `gameSoundSlot.get()`:
+ * flag-off callers get the silent C-25 stub, flag-on callers get the real
+ * `game-sound` engine once lane prd09's barrel has provided it.
+ */
+import { defineContractSlot } from "../../rendering/contracts/index.js";
+import { createStubGameSoundEngine } from "../../audio/index.js";
+// The contract stub has a narrower options type than the real factory
+// (context/buses are real-engine concerns); both honour the same call shape.
+export const gameSoundSlot = defineContractSlot("C-25", "prd09", "A3D_QR_GAME", createStubGameSoundEngine);
+//# sourceMappingURL=gameSound.js.map

package/dist/engine/contracts/gameSound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameSound.js","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/gameSound.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAK1D,sEAAsE;AACtE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAC7C,MAAM,EACN,OAAO,EACP,aAAa,EACb,yBAA8D,CAC/D,CAAC"}

package/dist/engine/contracts/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Aura3D Quality Rebuild — engine contracts barrel (CONTRACTS.md §3.9 item 2).
+ */
+export * from "./flags.js";
+export * from "./output.js";
+export * from "./sceneGraph.js";
+export * from "./environment.js";
+export * from "./lighting.js";
+export * from "./post.js";
+export * from "./materials.js";
+export * from "./assets.js";
+export * from "./animation.js";
+export * from "./effects.js";
+export * from "./atmosphere.js";
+export * from "./camera.js";
+export * from "./time.js";
+export * from "./game.js";
+export * from "./world.js";
+export * from "./diagnostics.js";
+export * from "./looks.js";
+export * from "./art.js";
+export * from "./compiler.js";
+export * from "./runtimeNodes.js";
+export * from "./app.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,OAAO,CAAC"}

package/dist/engine/contracts/index.js

@@ -0,0 +1,25 @@
+/**
+ * Aura3D Quality Rebuild — engine contracts barrel (CONTRACTS.md §3.9 item 2).
+ */
+export * from "./flags.js";
+export * from "./output.js";
+export * from "./sceneGraph.js";
+export * from "./environment.js";
+export * from "./lighting.js";
+export * from "./post.js";
+export * from "./materials.js";
+export * from "./assets.js";
+export * from "./animation.js";
+export * from "./effects.js";
+export * from "./atmosphere.js";
+export * from "./camera.js";
+export * from "./time.js";
+export * from "./game.js";
+export * from "./world.js";
+export * from "./diagnostics.js";
+export * from "./looks.js";
+export * from "./art.js";
+export * from "./compiler.js";
+export * from "./runtimeNodes.js";
+export * from "./app.js";
+//# sourceMappingURL=index.js.map

package/dist/engine/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,OAAO,CAAC"}

package/dist/engine/contracts/lighting.d.ts

@@ -0,0 +1,89 @@
+/**
+ * C-10 — lighting model and lights API (engine side, CONTRACTS.md). Provider: PRD 02.
+ * Flag: A3D_QR_LIGHTING. AuraLightType gains "hemisphere" in PR 0a (index.ts:1542).
+ */
+import type { AuraColor, AuraVec3, AuraNodeBuilder, AuraLightNode } from "../agent-api/index.js";
+import type { AuraQualityTier } from "../../rendering/contracts/index.js";
+export type AuraLightingModel = "physical" | "legacy-3.0";
+export interface AuraLightingOptions {
+    readonly model?: AuraLightingModel;
+    readonly autoSunShadow?: boolean;
+    readonly quality?: AuraQualityTier | "auto";
+    readonly maxShadowedLights?: number;
+}
+export interface AuraShadowOptions {
+    readonly intensity?: number;
+    readonly mapSize?: 512 | 1024 | 2048 | 4096;
+    readonly bias?: number;
+    readonly normalBias?: number;
+    readonly filter?: "hard" | "pcf" | "pcss";
+    readonly softness?: number;
+    readonly lightSize?: number;
+}
+export interface AuraDirectionalShadowOptions extends AuraShadowOptions {
+    readonly cascades?: 1 | 2 | 3 | 4 | "auto";
+    readonly maxDistance?: number;
+    readonly splitLambda?: number;
+    readonly blend?: number;
+    readonly fit?: "camera" | {
+        readonly center: AuraVec3;
+        readonly extent: number;
+        readonly depth?: number;
+    };
+}
+export interface AuraLocalShadowOptions extends AuraShadowOptions {
+}
+export interface AuraLightsApiAdditions {
+    hemisphere(o?: {
+        name?: string;
+        skyColor?: AuraColor;
+        groundColor?: AuraColor;
+        intensity?: number;
+        position?: AuraVec3;
+    }): AuraNodeBuilder<AuraLightNode>;
+}
+export interface AuraLightingDiagnostics {
+    readonly environment: {
+        readonly source: string;
+        readonly faceSize: number;
+        readonly mipCount: number;
+        readonly format: string;
+        readonly shBound: boolean;
+        readonly backgroundDrawn: boolean;
+        readonly pmremGpuMs: number | null;
+    };
+    readonly shadows: readonly {
+        readonly light: string;
+        readonly filter: string;
+        readonly casterVariants: readonly string[];
+        readonly sampled: boolean;
+    }[];
+    readonly droppedFeatures: readonly string[];
+    readonly contactShadows: {
+        readonly passExecuted: boolean;
+    };
+    readonly programCompileCount: number;
+    readonly readPixelsCalls: number;
+}
+export interface AuraLightingRuntime {
+    updateProbe(name: string): Promise<void>;
+    rebakeIrradiance(name?: string): Promise<void>;
+    setEnvironmentRotation(radians: number): void;
+    setEnvironmentIntensity(value: number): void;
+    diagnostics(): AuraLightingDiagnostics;
+}
+/**
+ * PR 0a stub runtime: hemisphere lowers to two directional fills at 0.5
+ * intensity each (sky above, ground below) with a `capability-degraded`
+ * degradation; diagnostics reports observed values with unknown fields null.
+ */
+export declare class StubLightingRuntime implements AuraLightingRuntime {
+    private rotation;
+    private intensity;
+    updateProbe(_name: string): Promise<void>;
+    rebakeIrradiance(_name?: string): Promise<void>;
+    setEnvironmentRotation(radians: number): void;
+    setEnvironmentIntensity(value: number): void;
+    diagnostics(): AuraLightingDiagnostics;
+}
+//# sourceMappingURL=lighting.d.ts.map

package/dist/engine/contracts/lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighting.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/contracts/lighting.ts"],"names":[],"mappings":"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"}