gaesup-world 1.5.0 → 1.6.0

package/dist/core/gi/components/GiVolume/index.d.cts

@@ -1,8 +1,10 @@
 import type { GiVolumeProps } from './types.cjs';
 /**
  * 복셀 박스를 추적해 프로브 래디언스 캐시를 갱신하고 GPU 텍스처로 올린다.
- * 프로브 갱신은 wasm/gaesup_gi.wasm을 받을 수 있으면 WASM 커널로, 받을 수 없으면 같은 결과를 내는 JS로 수행한다.
+ * 프로브 추적은 기본으로 Web Worker에서 돌아 프레임이 기다리지 않는다. 워커를 쓸 수 없거나 멈추면 메인 스레드에서
+ * 같은 계산을 한다. 두 경우 모두 wasm/gaesup_gi.wasm을 받을 수 있으면 WASM 커널, 없으면 같은 결과의 JS로 갱신한다.
+ * 수렴한 캐시는 갱신 속도를 4분의 1로 낮추고(probeSchedule.ts), 장면이나 빛이 바뀌면 다시 올린다.
  * WebGPURenderer에서만 셰이더 모듈이 로드되며, 로드에 실패하면 children은 GI 없이 그대로 렌더링된다.
  * children은 useGi()로 받은 값의 applyToMaterial로 MeshStandardNodeMaterial에 간접광을 연결한다.
  */
-export declare function GiVolume({ boxes, environment, fineBounds, voxelSize, probeSpacing, raysPerProbe, probesPerFrame, padding, blend, uploadIntervalMs, children, }: GiVolumeProps): import("react").JSX.Element;
+export declare function GiVolume({ boxes, environment, fineBounds, voxelSize, probeSpacing, raysPerProbe, probesPerFrame, padding, blend, uploadIntervalMs, worker, children, }: GiVolumeProps): import("react").JSX.Element;

package/dist/core/gi/components/GiVolume/index.d.ts

@@ -1,8 +1,10 @@
 import type { GiVolumeProps } from './types.js';
 /**
  * 복셀 박스를 추적해 프로브 래디언스 캐시를 갱신하고 GPU 텍스처로 올린다.
- * 프로브 갱신은 wasm/gaesup_gi.wasm을 받을 수 있으면 WASM 커널로, 받을 수 없으면 같은 결과를 내는 JS로 수행한다.
+ * 프로브 추적은 기본으로 Web Worker에서 돌아 프레임이 기다리지 않는다. 워커를 쓸 수 없거나 멈추면 메인 스레드에서
+ * 같은 계산을 한다. 두 경우 모두 wasm/gaesup_gi.wasm을 받을 수 있으면 WASM 커널, 없으면 같은 결과의 JS로 갱신한다.
+ * 수렴한 캐시는 갱신 속도를 4분의 1로 낮추고(probeSchedule.ts), 장면이나 빛이 바뀌면 다시 올린다.
  * WebGPURenderer에서만 셰이더 모듈이 로드되며, 로드에 실패하면 children은 GI 없이 그대로 렌더링된다.
  * children은 useGi()로 받은 값의 applyToMaterial로 MeshStandardNodeMaterial에 간접광을 연결한다.
  */
-export declare function GiVolume({ boxes, environment, fineBounds, voxelSize, probeSpacing, raysPerProbe, probesPerFrame, padding, blend, uploadIntervalMs, children, }: GiVolumeProps): import("react").JSX.Element;
+export declare function GiVolume({ boxes, environment, fineBounds, voxelSize, probeSpacing, raysPerProbe, probesPerFrame, padding, blend, uploadIntervalMs, worker, children, }: GiVolumeProps): import("react").JSX.Element;

package/dist/core/gi/components/GiVolume/runtime.d.cts

@@ -1,5 +1,5 @@
 import type { GiRuntime, GiRuntimeParams } from './types.cjs';
-import type { Aabb, GiEnvironment, VoxelSourceBox } from '../../types.cjs';
+import type { Aabb, GiEnvironment, ProbeAtlasUpload, VoxelSourceBox } from '../../types.cjs';
 export declare function boundsKey(bounds: Aabb | null): string;
 /**
  * 박스 목록으로 GI 런타임을 만든다. 그리드 명세와 프로브 배치가 이전과 같으면 그리드만 다시 채우고
@@ -12,3 +12,8 @@ export declare function createGiRuntime(previous: GiRuntime | null, boxes: reado
  * 아무것도 하지 않으며 캐스케이드는 JS 경로로 계속 갱신된다.
  */
 export declare function attachGiWasm(runtime: GiRuntime, module: WebAssembly.Module): Promise<boolean>;
+/**
+ * Packs every level of the runtime's cascade into half-float atlases for GiIrradiance.updateAtlas, reusing arrays the
+ * renderer handed back (hand them back through `spareAtlases`).
+ */
+export declare function packRuntimeAtlases(runtime: GiRuntime): ProbeAtlasUpload[];

package/dist/core/gi/components/GiVolume/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { GiRuntime, GiRuntimeParams } from './types.js';
-import type { Aabb, GiEnvironment, VoxelSourceBox } from '../../types.js';
+import type { Aabb, GiEnvironment, ProbeAtlasUpload, VoxelSourceBox } from '../../types.js';
 export declare function boundsKey(bounds: Aabb | null): string;
 /**
  * 박스 목록으로 GI 런타임을 만든다. 그리드 명세와 프로브 배치가 이전과 같으면 그리드만 다시 채우고
@@ -12,3 +12,8 @@ export declare function createGiRuntime(previous: GiRuntime | null, boxes: reado
  * 아무것도 하지 않으며 캐스케이드는 JS 경로로 계속 갱신된다.
  */
 export declare function attachGiWasm(runtime: GiRuntime, module: WebAssembly.Module): Promise<boolean>;
+/**
+ * Packs every level of the runtime's cascade into half-float atlases for GiIrradiance.updateAtlas, reusing arrays the
+ * renderer handed back (hand them back through `spareAtlases`).
+ */
+export declare function packRuntimeAtlases(runtime: GiRuntime): ProbeAtlasUpload[];

package/dist/core/gi/components/GiVolume/types.d.cts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import type { ProbeCascade } from '../../core/probeCascade.cjs';
-import type { Aabb, GiEnvironment, ProbeFaceBuffers, VoxelGrid, VoxelSourceBox } from '../../types.cjs';
+import type { Aabb, GiEnvironment, VoxelGrid, VoxelSourceBox } from '../../types.cjs';
 export type GiVolumeProps = {
     boxes: readonly VoxelSourceBox[];
     environment: GiEnvironment;
@@ -12,6 +12,11 @@ export type GiVolumeProps = {
     padding?: number;
     blend?: number;
     uploadIntervalMs?: number;
+    /**
+     * Trace probes in a Web Worker so the frame never waits for them (default). Where a worker cannot start (no Worker,
+     * a content security policy without blob: workers) or it fails, the probes update on the main thread as before.
+     */
+    worker?: boolean;
     children?: ReactNode;
 };
 export type GiRuntimeParams = {
@@ -26,6 +31,7 @@ export type GiRuntime = {
     signature: string;
     grid: VoxelGrid;
     cascade: ProbeCascade;
-    exportBuffers: ProbeFaceBuffers[];
+    /** Atlas arrays the renderer has let go of, packed again for the next upload. */
+    spareAtlases: Uint16Array[];
     uploadedVersion: number;
 };

package/dist/core/gi/components/GiVolume/types.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import type { ProbeCascade } from '../../core/probeCascade.js';
-import type { Aabb, GiEnvironment, ProbeFaceBuffers, VoxelGrid, VoxelSourceBox } from '../../types.js';
+import type { Aabb, GiEnvironment, VoxelGrid, VoxelSourceBox } from '../../types.js';
 export type GiVolumeProps = {
     boxes: readonly VoxelSourceBox[];
     environment: GiEnvironment;
@@ -12,6 +12,11 @@ export type GiVolumeProps = {
     padding?: number;
     blend?: number;
     uploadIntervalMs?: number;
+    /**
+     * Trace probes in a Web Worker so the frame never waits for them (default). Where a worker cannot start (no Worker,
+     * a content security policy without blob: workers) or it fails, the probes update on the main thread as before.
+     */
+    worker?: boolean;
     children?: ReactNode;
 };
 export type GiRuntimeParams = {
@@ -26,6 +31,7 @@ export type GiRuntime = {
     signature: string;
     grid: VoxelGrid;
     cascade: ProbeCascade;
-    exportBuffers: ProbeFaceBuffers[];
+    /** Atlas arrays the renderer has let go of, packed again for the next upload. */
+    spareAtlases: Uint16Array[];
     uploadedVersion: number;
 };

package/dist/core/gi/components/GiVolume/workerClient.d.cts

@@ -0,0 +1,31 @@
+import type { GiRuntimeParams } from './types.cjs';
+import type { GiEnvironment, ProbeAtlasUpload, VoxelSourceBox } from '../../types.cjs';
+type Handlers = {
+    onAtlas: (levels: ProbeAtlasUpload[], usesWasm: boolean) => void;
+    onError: (error: unknown) => void;
+};
+/** Whether this page can run the GI worker at all (browsers; not SSR or plain test environments). */
+export declare function canUseGiWorker(): boolean;
+/**
+ * The page's side of the GI worker: forwards the voxel scene and the light, hands packed atlases to `onAtlas` and
+ * reports a worker that could not start or stopped. Construction throws when the worker cannot be created (for
+ * example a content security policy without blob: workers); callers then keep the main-thread path.
+ */
+export declare class GiWorkerClient {
+    private readonly worker;
+    private closed;
+    constructor(module: WebAssembly.Module | null, options: {
+        probesPerTick: number;
+        uploadIntervalMs: number;
+    }, handlers: Handlers);
+    setScene(boxes: readonly VoxelSourceBox[], params: GiRuntimeParams, environment: GiEnvironment): void;
+    setEnvironment(environment: GiEnvironment): void;
+    /** Stops tracing while nothing is drawn (a hidden page) and picks it up again. */
+    setPaused(paused: boolean): void;
+    /** Hands arrays the renderer stopped using back to the worker, which packs later uploads into them. */
+    recycle(atlases: Uint16Array[]): void;
+    dispose(): void;
+    private send;
+    private fail;
+}
+export {};

package/dist/core/gi/components/GiVolume/workerClient.d.ts

@@ -0,0 +1,31 @@
+import type { GiRuntimeParams } from './types.js';
+import type { GiEnvironment, ProbeAtlasUpload, VoxelSourceBox } from '../../types.js';
+type Handlers = {
+    onAtlas: (levels: ProbeAtlasUpload[], usesWasm: boolean) => void;
+    onError: (error: unknown) => void;
+};
+/** Whether this page can run the GI worker at all (browsers; not SSR or plain test environments). */
+export declare function canUseGiWorker(): boolean;
+/**
+ * The page's side of the GI worker: forwards the voxel scene and the light, hands packed atlases to `onAtlas` and
+ * reports a worker that could not start or stopped. Construction throws when the worker cannot be created (for
+ * example a content security policy without blob: workers); callers then keep the main-thread path.
+ */
+export declare class GiWorkerClient {
+    private readonly worker;
+    private closed;
+    constructor(module: WebAssembly.Module | null, options: {
+        probesPerTick: number;
+        uploadIntervalMs: number;
+    }, handlers: Handlers);
+    setScene(boxes: readonly VoxelSourceBox[], params: GiRuntimeParams, environment: GiEnvironment): void;
+    setEnvironment(environment: GiEnvironment): void;
+    /** Stops tracing while nothing is drawn (a hidden page) and picks it up again. */
+    setPaused(paused: boolean): void;
+    /** Hands arrays the renderer stopped using back to the worker, which packs later uploads into them. */
+    recycle(atlases: Uint16Array[]): void;
+    dispose(): void;
+    private send;
+    private fail;
+}
+export {};

package/dist/core/gi/core/probeAtlas.d.cts

@@ -0,0 +1,28 @@
+import type { ProbeFaceBuffers, VoxelDims } from '../types.cjs';
+/** Faces of an irradiance cube in atlas order: +x -x +y -y +z -z, laid side by side along the atlas x axis. */
+export declare const PROBE_ATLAS_FACES = 6;
+/** Channels per atlas texel (RGBA; alpha is always 1). */
+export declare const PROBE_ATLAS_CHANNELS = 4;
+/** Length of one level's atlas: every probe's six faces, four half floats each. */
+export declare function probeAtlasLength(counts: VoxelDims): number;
+/**
+ * Where probe `index`'s texel of `face` starts in the atlas. A probe row (fixed y and z) holds the six faces one after
+ * another, each `counts[0]` texels wide, so hardware filtering inside a face never reads its neighbour.
+ */
+export declare function probeAtlasOffset(counts: VoxelDims, index: number, face: number): number;
+/** The half-float bits of alpha 1, written into every texel. */
+export declare const PROBE_ATLAS_ALPHA = 15360;
+/**
+ * IEEE 754 half-float bits of `value`, rounded to nearest even. Irradiance is never negative or huge, but the
+ * conversion stays total: NaN becomes 0 and anything past the half range the largest finite half.
+ */
+export declare function toHalfFloat(value: number): number;
+/** Writes a level's six per-face RGBA float buffers (ProbeVolume.exportFaceData) into its half-float atlas. */
+export declare function writeFaceBuffersToAtlas(target: Uint16Array, counts: VoxelDims, faces: ProbeFaceBuffers): void;
+/**
+ * Writes every probe's irradiance cube (`cubeOf(index)`: six faces of RGB, ProbeVolume's layout) into a level's
+ * half-float atlas in one pass.
+ */
+export declare function packProbeAtlas(target: Uint16Array, counts: VoxelDims, cubeOf: (index: number) => ArrayLike<number>): void;
+/** An atlas array of `length` from `pool` (removed from it), or a new one; callers hand spent arrays back to the pool. */
+export declare function takeProbeAtlas(pool: Uint16Array[], length: number): Uint16Array;

package/dist/core/gi/core/probeAtlas.d.ts

@@ -0,0 +1,28 @@
+import type { ProbeFaceBuffers, VoxelDims } from '../types.js';
+/** Faces of an irradiance cube in atlas order: +x -x +y -y +z -z, laid side by side along the atlas x axis. */
+export declare const PROBE_ATLAS_FACES = 6;
+/** Channels per atlas texel (RGBA; alpha is always 1). */
+export declare const PROBE_ATLAS_CHANNELS = 4;
+/** Length of one level's atlas: every probe's six faces, four half floats each. */
+export declare function probeAtlasLength(counts: VoxelDims): number;
+/**
+ * Where probe `index`'s texel of `face` starts in the atlas. A probe row (fixed y and z) holds the six faces one after
+ * another, each `counts[0]` texels wide, so hardware filtering inside a face never reads its neighbour.
+ */
+export declare function probeAtlasOffset(counts: VoxelDims, index: number, face: number): number;
+/** The half-float bits of alpha 1, written into every texel. */
+export declare const PROBE_ATLAS_ALPHA = 15360;
+/**
+ * IEEE 754 half-float bits of `value`, rounded to nearest even. Irradiance is never negative or huge, but the
+ * conversion stays total: NaN becomes 0 and anything past the half range the largest finite half.
+ */
+export declare function toHalfFloat(value: number): number;
+/** Writes a level's six per-face RGBA float buffers (ProbeVolume.exportFaceData) into its half-float atlas. */
+export declare function writeFaceBuffersToAtlas(target: Uint16Array, counts: VoxelDims, faces: ProbeFaceBuffers): void;
+/**
+ * Writes every probe's irradiance cube (`cubeOf(index)`: six faces of RGB, ProbeVolume's layout) into a level's
+ * half-float atlas in one pass.
+ */
+export declare function packProbeAtlas(target: Uint16Array, counts: VoxelDims, cubeOf: (index: number) => ArrayLike<number>): void;
+/** An atlas array of `length` from `pool` (removed from it), or a new one; callers hand spent arrays back to the pool. */
+export declare function takeProbeAtlas(pool: Uint16Array[], length: number): Uint16Array;

package/dist/core/gi/core/probeCascade.d.cts

@@ -15,10 +15,16 @@ export declare class ProbeCascade {
     private readonly grid;
     private environment;
     private kernel;
+    private updatedSinceChange;
     constructor(grid: VoxelGrid, coarseConfig: ProbeVolumeConfig, fineConfig: ProbeVolumeConfig | null, environment: GiEnvironment);
     get probeCount(): number;
     get version(): number;
     get usesWasm(): boolean;
+    /**
+     * 복셀이나 빛이 마지막으로 바뀐 뒤 모든 프로브를 몇 번 돌았는지(갱신한 프로브 수 / 전체 수). 호출자는 이 값으로
+     * 수렴한 캐시의 갱신 속도를 낮춘다(probeSchedule.ts).
+     */
+    get passesSinceChange(): number;
     /**
      * 두 레벨의 프로브 갱신을 WASM 커널로 옮긴다. 현재 프로브 값은 WASM 메모리로 복사되어 이어진다.
      * 복셀 격자는 markAllDirty와 markDirtyBox, 환경은 setEnvironment에서 WASM 쪽으로 다시 복사된다.

package/dist/core/gi/core/probeCascade.d.ts

@@ -15,10 +15,16 @@ export declare class ProbeCascade {
     private readonly grid;
     private environment;
     private kernel;
+    private updatedSinceChange;
     constructor(grid: VoxelGrid, coarseConfig: ProbeVolumeConfig, fineConfig: ProbeVolumeConfig | null, environment: GiEnvironment);
     get probeCount(): number;
     get version(): number;
     get usesWasm(): boolean;
+    /**
+     * 복셀이나 빛이 마지막으로 바뀐 뒤 모든 프로브를 몇 번 돌았는지(갱신한 프로브 수 / 전체 수). 호출자는 이 값으로
+     * 수렴한 캐시의 갱신 속도를 낮춘다(probeSchedule.ts).
+     */
+    get passesSinceChange(): number;
     /**
      * 두 레벨의 프로브 갱신을 WASM 커널로 옮긴다. 현재 프로브 값은 WASM 메모리로 복사되어 이어진다.
      * 복셀 격자는 markAllDirty와 markDirtyBox, 환경은 setEnvironment에서 WASM 쪽으로 다시 복사된다.

package/dist/core/gi/core/probeSchedule.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Passes over every probe, after the voxels or the light changed, that run at the full rate. The running average moves
+ * 10% of the way per update at the default blend, so twelve passes leave under a third of the old light's noise; the
+ * adaptive blend already follows large changes within a pass or two.
+ */
+export declare const SETTLE_PASSES = 12;
+/** A settled cache keeps a quarter of the rate: enough to follow small changes, without a steady share of a core. */
+export declare const SETTLED_RATE_DIVISOR = 4;
+/**
+ * Probes to update in one frame (or one worker tick) `passes` passes after the cascade's last change: `perFrame` times
+ * `firstPass` until every probe has been traced once, so new light shows up quickly, `perFrame` while the cache
+ * converges, then a quarter of it.
+ */
+export declare function scheduledProbeBudget(perFrame: number, passes: number, firstPass?: number): number;

package/dist/core/gi/core/probeSchedule.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Passes over every probe, after the voxels or the light changed, that run at the full rate. The running average moves
+ * 10% of the way per update at the default blend, so twelve passes leave under a third of the old light's noise; the
+ * adaptive blend already follows large changes within a pass or two.
+ */
+export declare const SETTLE_PASSES = 12;
+/** A settled cache keeps a quarter of the rate: enough to follow small changes, without a steady share of a core. */
+export declare const SETTLED_RATE_DIVISOR = 4;
+/**
+ * Probes to update in one frame (or one worker tick) `passes` passes after the cascade's last change: `perFrame` times
+ * `firstPass` until every probe has been traced once, so new light shows up quickly, `perFrame` while the cache
+ * converges, then a quarter of it.
+ */
+export declare function scheduledProbeBudget(perFrame: number, passes: number, firstPass?: number): number;

package/dist/core/gi/core/probeVolume.d.cts

@@ -63,6 +63,10 @@ export declare class ProbeVolume {
      * 복셀 안에 묻힌 프로브는 이웃 유효 프로브 평균으로 채워 하드웨어 보간 시 어둡게 번지지 않게 한다.
      */
     exportFaceData(target?: ProbeFaceBuffers): ProbeFaceBuffers;
+    /** exportFaceData와 같은 값을 반정밀도 아틀라스(probeAtlas.ts)에 면별 float 버퍼 없이 바로 쓴다. */
+    packAtlas(target: Uint16Array): void;
+    /** 프로브의 조도 큐브(복셀 안에 묻힌 프로브는 이웃 평균). 다음 호출이 덮어쓰는 내부 버퍼다. */
+    private probeCube;
     private loadProbe;
     private loadDilated;
     private nextProbe;

package/dist/core/gi/core/probeVolume.d.ts

@@ -63,6 +63,10 @@ export declare class ProbeVolume {
      * 복셀 안에 묻힌 프로브는 이웃 유효 프로브 평균으로 채워 하드웨어 보간 시 어둡게 번지지 않게 한다.
      */
     exportFaceData(target?: ProbeFaceBuffers): ProbeFaceBuffers;
+    /** exportFaceData와 같은 값을 반정밀도 아틀라스(probeAtlas.ts)에 면별 float 버퍼 없이 바로 쓴다. */
+    packAtlas(target: Uint16Array): void;
+    /** 프로브의 조도 큐브(복셀 안에 묻힌 프로브는 이웃 평균). 다음 호출이 덮어쓰는 내부 버퍼다. */
+    private probeCube;
     private loadProbe;
     private loadDilated;
     private nextProbe;

package/dist/core/gi/hooks/useBuildingVoxelBoxes.d.cts

@@ -1,2 +1,6 @@
 import type { VoxelSourceBox } from '../types.cjs';
+/**
+ * The building store as GI voxel boxes: tiles, walls, blocks and fires, plus stand-ins for trees and placed models
+ * once their files' bounds are known.
+ */
 export declare function useBuildingVoxelBoxes(): VoxelSourceBox[];

package/dist/core/gi/hooks/useBuildingVoxelBoxes.d.ts

@@ -1,2 +1,6 @@
 import type { VoxelSourceBox } from '../types.js';
+/**
+ * The building store as GI voxel boxes: tiles, walls, blocks and fires, plus stand-ins for trees and placed models
+ * once their files' bounds are known.
+ */
 export declare function useBuildingVoxelBoxes(): VoxelSourceBox[];

package/dist/core/gi/index.d.cts

@@ -16,4 +16,4 @@ export { CUBE_CHANNELS, CUBE_FACE_COUNT, CUBE_STRIDE, accumulateAmbientCube, eva
 export { createVoxelHitScratch, traceVoxelRay, traceVoxelRayInto } from './core/traceVoxels.cjs';
 export { DEFAULT_MATERIAL_ID, MAX_MATERIAL_ID, clearVoxelGrid, createVoxelGrid, fillVoxelBox, isInsideVoxelGrid, isVoxelOccupied, registerVoxelMaterial, resetVoxelMaterials, voxelIndex, voxelMaterialId, } from './core/voxelGrid.cjs';
 export { alignedProbeLayout, computeBoxBounds, computeGridSpec, createGridForBounds, expandBounds, rebuildVoxelGrid, } from './core/voxelScene.cjs';
-export type { Aabb, FieldSampler, GiEnvironment, GiWasmExports, Mat3, MutableRgb, ProbeFaceBuffers, ProbeLevelUpload, ProbeVolumeConfig, Rgb, VoxelDims, VoxelGrid, VoxelHitScratch, VoxelMaterial, VoxelRayHit, VoxelSourceBox, } from './types.cjs';
+export type { Aabb, FieldSampler, GiEnvironment, GiWasmExports, Mat3, MutableRgb, ProbeAtlasUpload, ProbeFaceBuffers, ProbeLevelUpload, ProbeVolumeConfig, Rgb, VoxelDims, VoxelGrid, VoxelHitScratch, VoxelMaterial, VoxelRayHit, VoxelSourceBox, } from './types.cjs';

package/dist/core/gi/index.d.ts

@@ -16,4 +16,4 @@ export { CUBE_CHANNELS, CUBE_FACE_COUNT, CUBE_STRIDE, accumulateAmbientCube, eva
 export { createVoxelHitScratch, traceVoxelRay, traceVoxelRayInto } from './core/traceVoxels.js';
 export { DEFAULT_MATERIAL_ID, MAX_MATERIAL_ID, clearVoxelGrid, createVoxelGrid, fillVoxelBox, isInsideVoxelGrid, isVoxelOccupied, registerVoxelMaterial, resetVoxelMaterials, voxelIndex, voxelMaterialId, } from './core/voxelGrid.js';
 export { alignedProbeLayout, computeBoxBounds, computeGridSpec, createGridForBounds, expandBounds, rebuildVoxelGrid, } from './core/voxelScene.js';
-export type { Aabb, FieldSampler, GiEnvironment, GiWasmExports, Mat3, MutableRgb, ProbeFaceBuffers, ProbeLevelUpload, ProbeVolumeConfig, Rgb, VoxelDims, VoxelGrid, VoxelHitScratch, VoxelMaterial, VoxelRayHit, VoxelSourceBox, } from './types.js';
+export type { Aabb, FieldSampler, GiEnvironment, GiWasmExports, Mat3, MutableRgb, ProbeAtlasUpload, ProbeFaceBuffers, ProbeLevelUpload, ProbeVolumeConfig, Rgb, VoxelDims, VoxelGrid, VoxelHitScratch, VoxelMaterial, VoxelRayHit, VoxelSourceBox, } from './types.js';

package/dist/core/gi/types.d.cts

@@ -65,6 +65,11 @@ export type ProbeLevelUpload = {
     config: ProbeVolumeConfig;
     faces: ProbeFaceBuffers;
 };
+/** One level as its half-float atlas: six faces side by side along x, RGBA per probe (see ProbeVolume.packAtlas). */
+export type ProbeAtlasUpload = {
+    config: ProbeVolumeConfig;
+    atlas: Uint16Array;
+};
 export type GiWasmExports = {
     readonly memory: WebAssembly.Memory;
     readonly alloc_f32: (len: number) => number;

package/dist/core/gi/types.d.ts

@@ -65,6 +65,11 @@ export type ProbeLevelUpload = {
     config: ProbeVolumeConfig;
     faces: ProbeFaceBuffers;
 };
+/** One level as its half-float atlas: six faces side by side along x, RGBA per probe (see ProbeVolume.packAtlas). */
+export type ProbeAtlasUpload = {
+    config: ProbeVolumeConfig;
+    atlas: Uint16Array;
+};
 export type GiWasmExports = {
     readonly memory: WebAssembly.Memory;
     readonly alloc_f32: (len: number) => number;

package/dist/core/gi/utils/buildingVoxelBoxes.d.cts

@@ -1,9 +1,11 @@
 import type { BuildingWallKind } from '../../building/types/index.cjs';
-import type { VoxelSourceBox } from '../types.cjs';
+import type { Aabb, VoxelSourceBox } from '../types.cjs';
 import type { BuildingVoxelSource, WallPiece } from './types.cjs';
 export declare function wallPieces(kind: BuildingWallKind, width: number, height: number, depth: number): WallPiece[];
 /**
  * 건축 스토어의 타일, 블록, 벽, 불 오브젝트를 GI용 복셀 박스로 변환한다.
  * 문·창 벽은 개구부를 남기고 유리와 난간은 빛이 통과하도록 생략한다.
+ * `modelBounds`(모델 URL별 경계 상자)를 주면 나무·가구·바위 같은 배치 오브젝트도 대리 박스로 넣어 빛을 가리게 하고,
+ * 조명의 머리는 발광체로 넣는다(objectProxies.ts).
  */
-export declare function buildingToVoxelBoxes(source: BuildingVoxelSource): VoxelSourceBox[];
+export declare function buildingToVoxelBoxes(source: BuildingVoxelSource, modelBounds?: ReadonlyMap<string, Aabb | null>): VoxelSourceBox[];

package/dist/core/gi/utils/buildingVoxelBoxes.d.ts

@@ -1,9 +1,11 @@
 import type { BuildingWallKind } from '../../building/types/index.js';
-import type { VoxelSourceBox } from '../types.js';
+import type { Aabb, VoxelSourceBox } from '../types.js';
 import type { BuildingVoxelSource, WallPiece } from './types.js';
 export declare function wallPieces(kind: BuildingWallKind, width: number, height: number, depth: number): WallPiece[];
 /**
  * 건축 스토어의 타일, 블록, 벽, 불 오브젝트를 GI용 복셀 박스로 변환한다.
  * 문·창 벽은 개구부를 남기고 유리와 난간은 빛이 통과하도록 생략한다.
+ * `modelBounds`(모델 URL별 경계 상자)를 주면 나무·가구·바위 같은 배치 오브젝트도 대리 박스로 넣어 빛을 가리게 하고,
+ * 조명의 머리는 발광체로 넣는다(objectProxies.ts).
  */
-export declare function buildingToVoxelBoxes(source: BuildingVoxelSource): VoxelSourceBox[];
+export declare function buildingToVoxelBoxes(source: BuildingVoxelSource, modelBounds?: ReadonlyMap<string, Aabb | null>): VoxelSourceBox[];

package/dist/core/gi/utils/modelBounds.d.cts

@@ -0,0 +1,40 @@
+import type { Aabb } from '../types.cjs';
+type GltfAccessor = {
+    min?: number[];
+    max?: number[];
+    normalized?: boolean;
+    componentType?: number;
+};
+type GltfNode = {
+    children?: number[];
+    mesh?: number;
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+};
+type GltfJson = {
+    scene?: number;
+    scenes?: {
+        nodes?: number[];
+    }[];
+    nodes?: GltfNode[];
+    meshes?: {
+        primitives?: {
+            attributes?: {
+                POSITION?: number;
+            };
+        }[];
+    }[];
+    accessors?: GltfAccessor[];
+};
+/** Local bounding box of a glTF's default scene from the accessors' min/max; no geometry is decoded. */
+export declare function gltfBounds(json: GltfJson): Aabb | null;
+/** The same box for a binary glTF, read from its JSON chunk alone. */
+export declare function glbBounds(buffer: ArrayBuffer): Aabb | null;
+/**
+ * A model's local bounds, fetched once per URL (resolved like the engine's glTF loader, so the HTTP cache usually
+ * answers). null when the file cannot be read; GI then leaves that model out.
+ */
+export declare function loadModelBounds(uri: string): Promise<Aabb | null>;
+export {};

package/dist/core/gi/utils/modelBounds.d.ts

@@ -0,0 +1,40 @@
+import type { Aabb } from '../types.js';
+type GltfAccessor = {
+    min?: number[];
+    max?: number[];
+    normalized?: boolean;
+    componentType?: number;
+};
+type GltfNode = {
+    children?: number[];
+    mesh?: number;
+    matrix?: number[];
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+};
+type GltfJson = {
+    scene?: number;
+    scenes?: {
+        nodes?: number[];
+    }[];
+    nodes?: GltfNode[];
+    meshes?: {
+        primitives?: {
+            attributes?: {
+                POSITION?: number;
+            };
+        }[];
+    }[];
+    accessors?: GltfAccessor[];
+};
+/** Local bounding box of a glTF's default scene from the accessors' min/max; no geometry is decoded. */
+export declare function gltfBounds(json: GltfJson): Aabb | null;
+/** The same box for a binary glTF, read from its JSON chunk alone. */
+export declare function glbBounds(buffer: ArrayBuffer): Aabb | null;
+/**
+ * A model's local bounds, fetched once per URL (resolved like the engine's glTF loader, so the HTTP cache usually
+ * answers). null when the file cannot be read; GI then leaves that model out.
+ */
+export declare function loadModelBounds(uri: string): Promise<Aabb | null>;
+export {};

package/dist/core/gi/utils/objectProxies.d.cts

@@ -0,0 +1,8 @@
+import type { PlacedObject } from '../../building/types/index.cjs';
+import type { Aabb, VoxelSourceBox } from '../types.cjs';
+/**
+ * GI stand-ins for placed objects: procedural trees from their size, glTF models from their file's bounding box
+ * (`modelBounds`, keyed by model URL) cut into a few solid parts by what the model is (a table's top, a tree's trunk and
+ * crown, a lamp's glowing head). Models whose bounds are not known yet are skipped until they are.
+ */
+export declare function objectProxyBoxes(object: PlacedObject, modelBounds: ReadonlyMap<string, Aabb | null>): VoxelSourceBox[];

package/dist/core/gi/utils/objectProxies.d.ts

@@ -0,0 +1,8 @@
+import type { PlacedObject } from '../../building/types/index.js';
+import type { Aabb, VoxelSourceBox } from '../types.js';
+/**
+ * GI stand-ins for placed objects: procedural trees from their size, glTF models from their file's bounding box
+ * (`modelBounds`, keyed by model URL) cut into a few solid parts by what the model is (a table's top, a tree's trunk and
+ * crown, a lamp's glowing head). Models whose bounds are not known yet are skipped until they are.
+ */
+export declare function objectProxyBoxes(object: PlacedObject, modelBounds: ReadonlyMap<string, Aabb | null>): VoxelSourceBox[];

package/dist/core/gi/worker/giWorker.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/core/gi/worker/giWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/gi/worker/host.d.cts

@@ -0,0 +1,33 @@
+import type { GiWorkerRequest, GiWorkerResponse } from './protocol.cjs';
+/** One tick stands in for a 60 Hz frame, so `probesPerTick` keeps the meaning of GiVolume's probesPerFrame. */
+export declare const GI_WORKER_TICK_MS = 16;
+export type GiWorkerClock = {
+    now: () => number;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+};
+type Post = (message: GiWorkerResponse, transfer: Transferable[]) => void;
+/**
+ * The GI worker's state, kept apart from the worker global so tests can drive it: it owns the voxel grid and probe
+ * cascade (the same runtime GiVolume uses on the main thread), traces probes on a timer and posts packed atlases.
+ */
+export declare class GiWorkerHost {
+    private readonly post;
+    private readonly clock;
+    private runtime;
+    private module;
+    private probesPerTick;
+    private uploadIntervalMs;
+    private lastUpload;
+    private timer;
+    private disposed;
+    private paused;
+    constructor(post: Post, clock?: GiWorkerClock);
+    handle(message: GiWorkerRequest): void;
+    /** Runs one tick now; the timer calls it, and tests call it instead of waiting. */
+    tick(): void;
+    private restart;
+    private schedule;
+    private stop;
+}
+export {};

package/dist/core/gi/worker/host.d.ts

@@ -0,0 +1,33 @@
+import type { GiWorkerRequest, GiWorkerResponse } from './protocol.js';
+/** One tick stands in for a 60 Hz frame, so `probesPerTick` keeps the meaning of GiVolume's probesPerFrame. */
+export declare const GI_WORKER_TICK_MS = 16;
+export type GiWorkerClock = {
+    now: () => number;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+};
+type Post = (message: GiWorkerResponse, transfer: Transferable[]) => void;
+/**
+ * The GI worker's state, kept apart from the worker global so tests can drive it: it owns the voxel grid and probe
+ * cascade (the same runtime GiVolume uses on the main thread), traces probes on a timer and posts packed atlases.
+ */
+export declare class GiWorkerHost {
+    private readonly post;
+    private readonly clock;
+    private runtime;
+    private module;
+    private probesPerTick;
+    private uploadIntervalMs;
+    private lastUpload;
+    private timer;
+    private disposed;
+    private paused;
+    constructor(post: Post, clock?: GiWorkerClock);
+    handle(message: GiWorkerRequest): void;
+    /** Runs one tick now; the timer calls it, and tests call it instead of waiting. */
+    tick(): void;
+    private restart;
+    private schedule;
+    private stop;
+}
+export {};