dom-sync-gl 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 izumitetsuya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# domSyncGL
+
+[![npm](https://img.shields.io/npm/v/dom-sync-gl.svg)](https://www.npmjs.com/package/dom-sync-gl)
+[![license](https://img.shields.io/npm/l/dom-sync-gl.svg)](./LICENSE)
+
+DOM 要素にロックした Three.js plane / 3D オブジェクト、スクロール同期、チェーン可能なポストエフェクト、touch 慣性付きの virtual scroll を、Three.js を peer dependency にした単一パッケージにまとめたもの。
+
+> npm パッケージ名は **`dom-sync-gl`** (kebab-case)、display 名は **`domSyncGL`** (camelCase)。
+
+## Features
+
+- **DOM-locked rendering** — 任意の DOM 要素の bbox に追従する `DomPlane` / `Dom3DObject`。CSS で動かしてもピクセル単位で追従。
+- **rAF↔paint scroll sync** — `ScrollSync` + `RafScroll` で paint 時にも desync しない。
+- **Touch inertia** — `RafScroll` がモバイル touch に対して native と同等の慣性スクロールを自前で再現 (`touchFriction` で減衰率カスタマイズ可)。
+- **Composable post effects** — `BaseEffect` を継承して `fragmentShader` を返すだけで ping-pong チェーンに自動配線。`enabled` で個別に on/off。
+- **iOS Safari friendly** — `100lvh` / `visualViewport.resize` 対応で動的アドレスバーに canvas 高が引きずられない。
+- **Mobile tier-ing pattern** — `maxPixelRatio` で renderer のピクセル密度を絞れる。fbm オクターブ等の shader 軽量化はアプリ側で template literal 分岐 (example 参照)。
+
+## Install
+
+```bash
+npm install dom-sync-gl three
+# 任意 (GUI panel / FPS panel を使う時だけ)
+npm install lil-gui stats.js
+```
+
+`three` のみ必須 peer。`lil-gui` / `stats.js` は **`peerDependenciesMeta` で optional 宣言** + 内部で **dynamic import** なので、`showGUI: false` / `showStats: false`（または未指定）のときは追加 install 不要、bundle にも入りません。
+
+`showGUI: true` で effect を addEffect すると、初回だけ lil-gui を async load してから `setupGUI()` を呼ぶ流れになります (load 中に effect を複数 addEffect しても load promise を共有して 1 インスタンスにまとまる)。
+
+## Quick start
+
+最低限のセットアップ:
+
+```ts
+import { WebGLApp } from "dom-sync-gl";
+
+const app = new WebGLApp("#canvas", {
+  scrollSync: true,
+});
+
+// DOM 要素にロックした plane
+app.createPlane(".hero-card", {
+  fragmentShader: /* glsl */ `
+    precision highp float;
+    varying vec2 vUv;
+    uniform float uTime;
+    void main() {
+      gl_FragColor = vec4(vUv, 0.5 + 0.5 * sin(uTime), 1.0);
+    }
+  `,
+});
+
+// element=null で全画面 plane (背景レイヤ)
+app.createPlane(null, {
+  fragmentShader: /* ... */,
+});
+```
+
+HTML 側に canvas slot を置く:
+
+```html
+<div id="canvas" style="position: absolute; top: 0; left: 0; width: 100vw; height: 100svh;"></div>
+```
+
+`ScrollSync` が container の元 CSS rect を snapshot して以降の resize でも比率を保つので、`height: 100svh` (アドレスバー込みの小さい viewport) のような指定がそのまま尊重される。
+
+## Concepts
+
+### 1. DOM-locked plane
+
+`createPlane(selector)` で渡した DOM 要素の `getBoundingClientRect()` を毎フレーム読み、対応する Three.js mesh の world 位置とスケールを更新する。**transform で動く要素** (CSS animation, GSAP 等) は `updateRectEveryFrame: true` を指定すると毎フレ取り直す。
+
+```ts
+const plane = app.createPlane(".card", {
+  fragmentShader,
+  updateRectEveryFrame: true,
+  uniforms: {
+    // 組み込み uniform (uTime / uResolution / uMouseUV / uIsHovered) は
+    // 宣言不要で shader 側に届く。ここに書くのはユーザー定義 uniform のみ。
+    uTexture: { value: texture },
+    uIntensity: { value: 0.5 },
+  },
+  onInView: (p) => p.material.uniforms.uIntensity.value = 1,
+});
+```
+
+組み込み uniform (shader 側で `uniform xxx` と書くだけで使える、宣言・更新不要):
+- `uTime` (`float`, 秒) — `clock.getElapsedTime()` を毎フレ書き込み
+- `uResolution` (`vec2`) — plane の pixel 寸法 (resize / rect 更新時に追従)
+- `uMouseUV` (`vec2`, 0..1) — hover 中の plane-local UV 座標
+- `uIsHovered` (`bool`) — raycast hit 中か
+
+### 2. Scroll sync
+
+`scrollSync: true` を有効にすると、canvas container が `position: absolute; top:0; left:0` に置き換わり、毎 rAF で 1 回読んだ `window.scrollY` を:
+- container 自身の `transform: translate3d(0, scrollY, 0)`
+- 各 `DomPlane` の sceneY 計算
+
+の両方に **同じ値で配る**。paint と JS rAF の間で scrollY が変わっても、container も plane も同じ「古い値」で揃ってズレるので、視覚上は DOM ↔ mesh が完璧に一致する。
+
+`RafScroll` を併用すると `window.scrollY` の更新自体が rAF tick 上だけになり、native scroll の rAF↔paint Δ も消える:
+
+```ts
+import { RafScroll } from "dom-sync-gl";
+
+const rafScroll = new RafScroll({
+  touchFriction: 0.95,  // touch リリース後の慣性減衰 (0 = 慣性なし)
+});
+// rafScroll は constructor で wheel/touch を listen 開始する
+```
+
+### 3. Post effects
+
+`BaseEffect` を継承し `getConfig()` で fragment shader を返すだけ:
+
+```ts
+import { BaseEffect, type BaseEffectConfig } from "dom-sync-gl";
+
+class GrainEffect extends BaseEffect {
+  protected getConfig(): BaseEffectConfig {
+    return {
+      fragmentShader: /* glsl */ `
+        precision highp float;
+        uniform sampler2D tDiffuse;
+        uniform float uTime;
+        varying vec2 vUv;
+        void main() {
+          vec4 src = texture2D(tDiffuse, vUv);
+          float g = fract(sin(dot(vUv + uTime, vec2(12.9898, 78.233))) * 43758.5453);
+          gl_FragColor = vec4(src.rgb + (g - 0.5) * 0.06, src.a);
+        }
+      `,
+      uniforms: { uTime: { value: 0 } },
+    };
+  }
+  update(time: number) { this.setUniform("uTime", time); }
+}
+
+app.addEffect(new GrainEffect());
+```
+
+`app.addEffect()` でフルスクリーンチェーンに追加、`plane.addEffect()` で per-plane に追加できる (同じインスタンスは片方だけ)。
+
+`setupGUI(gui)` を実装すると `showGUI: true` のとき lil-gui パネルに自動で controls が出る。
+
+## API reference
+
+### `new WebGLApp(selector, options?)`
+
+| option | type | default | 説明 |
+|---|---|---|---|
+| `scrollSync` | `boolean \| ScrollSyncOptions` | `false` | `true`  ON、object でパラメータ指定 |
+| `enableMouseTracking` | `boolean` | `true` | mousemove で uMouseUV / raycast を更新 |
+| `maxPixelRatio` | `number` | `2` | `renderer.setPixelRatio` の上限 (モバイルは `1.5` 推奨) |
+| `outputColorSpace` | `THREE.ColorSpace` | `SRGBColorSpace` | renderer の出力色空間 |
+| `showStats` | `boolean` | `false` | stats.js FPS パネル表示 |
+| `statsParent` | `HTMLElement` | `document.body` | パネル append 先 |
+| `showGUI` | `boolean` | `true` | effect の `setupGUI()` を自動呼び出し |
+| `guiTitle` | `string` | `'Effects'` | lil-gui ルートタイトル |
+
+#### Main methods
+
+- `createPlane(selector, options?)` → `DomPlane`。`selector` が `null` だと全画面背景 plane。
+- `create3DObject(selector, options)` → `Dom3DObject` (GLTF を DOM bbox に fit)。
+- `addEffect(effect)` / `removeEffect(effect)` — フルスクリーンチェーン
+- `addObject(obj3d)` / `removeObject(obj3d)` — Three.js scene に直接追加
+- `addUpdateCallback(fn)` → unsubscribe 関数。rAF tick ごとに呼ばれる。
+- `addResizeCallback(fn)` → unsubscribe 関数
+- `setMouseTrackingEnabled(bool)` — 動的に on/off
+- `getScene() / getCamera() / getRenderer() / getMouse()`
+- `destroy()` — 全 listener / RT / scene を解放
+
+### `ScrollSyncOptions`
+
+| option | type | default | 説明 |
+|---|---|---|---|
+| `padding` | `number` | `0` | 上下パディング比率 (canvas 高 = viewport × (1 + 2·padding))。`0` で CSS rect そのまま |
+| `trackStrength` | `boolean` | `false` | スクロール強度 getter を有効化 |
+| `strengthDecay` | `number` | `10` | strength の指数減衰係数 |
+
+### `RafScrollOptions`
+
+| option | type | default | 説明 |
+|---|---|---|---|
+| `lineHeight` | `number` | `16` | `WheelEvent.deltaMode=LINE` 時の 1 行 px |
+| `touchFriction` | `number` | `0.95` | touch リリース後の慣性減衰率 (16.67ms 換算 1 フレあたりの velocity 乗算値、`0` で慣性無効) |
+
+### `CreatePlaneOptions`
+
+| option | type | default | 説明 |
+|---|---|---|---|
+| `vertexShader` / `fragmentShader` | `string` | (default passthrough) | shader ソース |
+| `uniforms` | `{ [key]: IUniform }` | `{}` | 追加 uniform。組み込み (`uTime` 等) と衝突しないよう |
+| `updateRectEveryFrame` | `boolean` | `false` | 毎フレ bbox 取り直し (CSS animation で動く要素用) |
+| `segments` | `number` | `1` | PlaneGeometry セグメント数 (頂点 displacement する場合のみ増やす) |
+| `onInView` / `onOutView` | `(plane) => void` | — | IntersectionObserver コールバック |
+| `inViewRootMargin` | `string` | `'100%'` | IO の rootMargin |
+| `inViewRepeat` | `boolean` | `false` | 出入りのたびに onInView を発火 |
+| `crossOrigin` | `string` | `'anonymous'` | `data-texture` 読み込み時の CORS 属性 |
+
+### Exports
+
+```ts
+// Core
+export { WebGLApp, Camera, Light, DomPlane, Dom3DObject };
+
+// Scroll
+export { ScrollSync, RafScroll };
+
+// Post effects
+export { EffectComposer, EffectPass, PlaneComposer, BaseEffect };
+
+// Extension base
+export { BaseScene };
+
+// Utility
+export { DomPositionCalculator };
+
+// Types
+export type {
+  WebGLAppOptions,
+  CreatePlaneOptions,
+  Create3DObjectOptions,
+  Dom3DObjectFitMode,
+  Offset3D,
+  DOMPositionInfo,
+  ScrollSyncOptions,
+  RafScrollOptions,
+  BaseEffectConfig,
+  EffectOptions,
+  EffectTarget,
+  EffectLike,
+};
+
+// Re-export THREE (利用側で `import * as THREE from "three"` する代わりに使える)
+export { THREE };
+```
+
+## Browser support
+
+- Modern evergreen (Chrome / Edge / Firefox / Safari の各最新 2 バージョン)
+- **iOS Safari 15.4+** (`100lvh` / `visualViewport` を使う)
+- WebGL2 は不要 (WebGL1 で動く)
+- IE11 等のレガシーブラウザは対象外
+
+## Bundle
+
+| 形式 | ファイル | minified | gzipped |
+|---|---|---:|---:|
+| ESM | `dist/index.js` | 73.1 kB | **20.2 kB** |
+| CJS | `dist/index.cjs` | 39.4 kB | **10.1 kB** |
+
+- 型定義: `dist/index.d.ts` + 各ファイル `*.d.ts` をそのまま投影 (`rollupTypes: false`)
+- `sideEffects: false` で tree-shaking 可
+- `three` / `lil-gui` / `stats.js` はバンドルに含まれない (peer + dynamic import)
+- `three` 本体 (~600 kB) は利用側で持ち込み
+
+## Develop
+
+```bash
+npm install
+npm run dev      # examples/basic/ を vite で立ち上げる
+npm run build    # dist/ にビルド
+npm run test     # vitest 実行
+npm run typecheck
+```
+
+`examples/` は npm publish 物には含まれない (`files: ["dist"]`)。
+
+## License
+
+MIT

package/dist/Camera.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+export declare class Camera {
+    rect: DOMRect;
+    /**
+     * 内部 THREE.PerspectiveCamera。外部から `lookAt` 等の操作は可能。
+     *
+     * **注意**: `position.z` は「DOM 1px = WebGL 1unit」を成立させるための値で、
+     * `resize()` のたびに `rect.height / 2 / tan(fov/2)` で**上書きされる**。
+     * 外から position.z を書き換えても resize で消えるので、ズームや視点調整を
+     * 永続化したい場合は別途 update ループで再設定するか、座標系が変わってもよい
+     * 設計にすること。
+     */
+    instance: THREE.PerspectiveCamera;
+    constructor(rect: DOMRect);
+    resize(rect: DOMRect): void;
+}

package/dist/Core.d.ts

@@ -0,0 +1,205 @@
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { default as GUI } from 'lil-gui';
+import { Camera } from './Camera';
+import { Light } from './Light';
+import { DomPlane } from './DomPlane';
+import { Dom3DObject } from './Dom3DObject';
+import { ScrollSync } from './ScrollSync';
+import { EffectLike } from './EffectComposer';
+import { BaseEffect } from './effects/BaseEffect';
+import { CreatePlaneOptions, Create3DObjectOptions, WebGLAppOptions } from './types';
+import * as THREE from 'three';
+export declare class WebGLApp {
+    container: HTMLElement;
+    canvas: HTMLCanvasElement;
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer;
+    camera: Camera;
+    light: Light;
+    controls: OrbitControls | null;
+    updateCallbacks: (() => void)[];
+    resizeCallbacks: (() => void)[];
+    rect: DOMRect;
+    domPlanes: DomPlane[];
+    dom3DObjects: Dom3DObject[];
+    clock: THREE.Clock;
+    scrollSync: ScrollSync | null;
+    private options;
+    private rafId;
+    private resizeTimer;
+    private eventAbort;
+    /**
+     * mousemove listener 専用の AbortController。`setMouseTrackingEnabled()` で動的に
+     * detach 可能にするため `eventAbort` とは別に持つ。null の時は attach 済みでない。
+     */
+    private _mouseAbort;
+    /**
+     * canvas の viewport 上の矩形をキャッシュ。mousemove ごとに `getBoundingClientRect`
+     * を呼ぶと layout 強制が走るため、resize 時 + (ScrollSync 無効時の) scroll 時に
+     * invalidate する形にしてフィールドアクセスで済むようにする。
+     * ScrollSync 有効時は canvas viewport rect が固定 (RafScroll が同 rAF tick で
+     * scrollTo するため paint 時 actual と JS rAF が一致 → 動かない) なので
+     * scroll 時の invalidate は不要。
+     */
+    private _canvasRect;
+    private mouse;
+    private prevMouse;
+    /**
+     * マウスが canvas 矩形の内側に居るか。mousemove イベントごとに更新し、
+     * rAF tick 内の raycaster はこのフラグで実行を決める。
+     * (uMouseUV の更新を完全に rAF 駆動にすることで paint と同期させ、
+     *  「mousemove 非同期発火による uniform のちらつき」を消す)
+     */
+    private _mouseInside;
+    /** raycaster で使う NDC バッファ (毎フレ allocate を避ける) */
+    private _ndcBuf;
+    /** getMouseDelta の戻り値スクラッチ (毎フレ clone を避ける) */
+    private _mouseDeltaBuf;
+    private raycaster;
+    private hoveredPlane;
+    private domPlaneMeshes;
+    private postEffect;
+    private internalComposer;
+    private effects;
+    private stats;
+    /**
+     * lil-gui の root インスタンス。
+     * showGUI が false なら null のまま。最初の `setupGUI` を持つ effect が
+     * `addEffect()` 経由で登録された瞬間に生成する（lazy + dynamic import）。
+     */
+    private gui;
+    /**
+     * lil-gui の dynamic import promise。複数 effect の addEffect が同時に来た時、
+     * 二重 load を防ぐ。一度 resolve したら次回以降は `this.gui` を直接返す。
+     */
+    private _guiLoadPromise;
+    /**
+     * destroy 済みフラグ。animate() 実行中に user callback から destroy() が
+     * 呼ばれると、renderer.dispose() 後の続きで renderer.render() を呼んで
+     * WebGL エラーになる。各段階の冒頭で見て早期 return する。
+     */
+    private destroyed;
+    constructor(selector: string | HTMLElement, options?: WebGLAppOptions);
+    private init;
+    getScene(): THREE.Scene<THREE.Object3DEventMap>;
+    getCamera(): Camera;
+    getRenderer(): THREE.WebGLRenderer;
+    getLight(): Light;
+    getViewPort(): DOMRect;
+    getMouse(): THREE.Vector2;
+    getPrevMouse(): THREE.Vector2;
+    getMouseDelta(): THREE.Vector2;
+    getScrollSync(): ScrollSync | null;
+    addObject(object: THREE.Object3D): void;
+    removeObject(object: THREE.Object3D): void;
+    createPlane(selector: string | HTMLElement | null, options?: CreatePlaneOptions): DomPlane;
+    removePlane(domPlane: DomPlane): void;
+    create3DObject(selector: string | HTMLElement | null, options: Create3DObjectOptions): Dom3DObject;
+    remove3DObject(dom3DObject: Dom3DObject): void;
+    addUpdateCallback(callback: () => void): () => void;
+    addResizeCallback(callback: () => void): () => void;
+    enableOrbitControls(): OrbitControls;
+    getControls(): OrbitControls | null;
+    /**
+     * canvas 全体にエフェクトを追加する。
+     * 内部で EffectComposer を自動生成するため、別途 setPostEffect は不要。
+     *
+     * **注意**: `setPostEffect()` でカスタム postEffect を入れている状態でこれを呼ぶと、
+     * 自動生成された EffectComposer で上書きされる（カスタム postEffect の dispose は
+     * 呼ばれない＝呼び出し側の責務）。両 API の併用は避けること。
+     */
+    addEffect<T extends BaseEffect>(effect: T): T;
+    /**
+     * lil-gui を dynamic import で読み込み、root インスタンスを lazy 生成して返す。
+     * 同時に複数 effect から呼ばれても load promise を共有して 1 インスタンスにまとめる。
+     * @internal DomPlane.addEffect / WebGLApp.addEffect から呼ばれる。
+     */
+    _ensureGUIAsync(): Promise<GUI>;
+    /**
+     * root の lil-gui インスタンスを取得 (sync)。
+     *
+     * **注意**: lil-gui は dynamic import で読み込むため、初回 effect 登録直後など
+     * load 中の段階では `null` を返す。確実にインスタンスを得たい場合は
+     * `getGUIAsync()` を使う。`showGUI: false` の場合は常に `null`。
+     */
+    getGUI(): GUI | null;
+    /**
+     * lil-gui を必要に応じて load し、インスタンスを返す。
+     * `showGUI: false` の場合は `null` を resolve する。
+     */
+    getGUIAsync(): Promise<GUI | null>;
+    /**
+     * ポストエフェクトを設定（低レベル API）。
+     * 自前で `EffectLike`（render/resize/dispose）を実装したオブジェクトを差し込みたい場合のみ使用。
+     * 通常は `addEffect()` を使うこと。
+     *
+     * **注意**: `addEffect()` で追加済みのエフェクトがある状態で呼ぶと、
+     * 自動 EffectComposer を捨てて引数の postEffect に差し替える。既存 effect の
+     * dispose は呼ばれない（必要なら先に `clearEffects()` を呼ぶこと）。
+     */
+    setPostEffect(postEffect: EffectLike): void;
+    /**
+     * `addEffect()` で登録した effect を 1 つ取り除く。
+     *
+     * - 内部 EffectComposer から該当 pass を外し、material を dispose する
+     * - effect 自体の `dispose()` も呼ぶ（FluidEffect 等の RT も解放）
+     * - 全 effect が空になった場合、internalComposer はそのまま残す（次の addEffect で再利用）
+     *
+     * 登録されていない effect を渡した時は `false` を返して何もしない。
+     */
+    removeEffect(effect: BaseEffect): boolean;
+    /**
+     * 登録されたエフェクトとポストエフェクトをすべて解除して破棄する。
+     * addEffect で追加した全 effect の dispose() を呼び、内部 EffectComposer も解放する。
+     */
+    clearEffects(): void;
+    /**
+     * @deprecated `clearEffects()` を使ってください。挙動は同一です。
+     */
+    removePostEffect(): void;
+    private setupEventListeners;
+    /**
+     * mousemove tracking の動的な ON/OFF。
+     * - true: 未 attach なら mousemove listener を追加する
+     * - false: attach 済みなら detach する（hover も解除）
+     *
+     * `destroy()` 時は eventAbort と一緒に自動 detach される（_mouseAbort 個別 abort も呼ぶ）。
+     */
+    setMouseTrackingEnabled(enabled: boolean): void;
+    private invalidateCanvasRect;
+    /**
+     * ScrollSync の動的 padding clamp で canvas 寸法が変わった時に呼ばれる。
+     *
+     * window resize（onResize）と違い、DOM の位置や element 側の bbox は変わっていない。
+     * 必要なのは「canvas drawing buffer のサイズに依存するもの」だけ:
+     *   - renderer.setSize（drawing buffer + canvas.style.{width,height}）
+     *   - camera の aspect / distance（rect.height に応じて変わる）
+     *   - postEffect の RT サイズ
+     *   - 各 effect の RT サイズ
+     *
+     * DomPlane の DOM 連動 plane は positionCalculator の bbox に依存していて canvas 高さに
+     * 依存しないので触らない（calculateWebGLPosition の数式が padding を相殺するため不変）。
+     * フルスクリーン plane（element=null）は canvasRect.width/height をスケールに使うので、
+     * その分だけ canvasRect 参照を更新する。
+     */
+    private _onScrollSyncResize;
+    /** mousemove 等で頻繁に必要な canvas viewport rect を遅延 + キャッシュで返す。 */
+    private getCanvasRect;
+    private onResize;
+    /**
+     * mousemove は **mouse 座標と canvas 内外フラグだけ** 更新する。
+     * raycaster / setHoverInfo は呼ばない (= uMouseUV を直接書かない)。
+     * uniform 更新は `_updateHoverFromMouse` 経由で rAF tick 内に集約することで、
+     * paint と完全同期させ「mousemove 非同期発火による uMouseUV のちらつき」を防ぐ。
+     */
+    private onMouseMove;
+    /**
+     * rAF tick 内の Phase A で呼ばれる。最新の `this.mouse` を使って raycaster を投げ、
+     * hover 中の plane を判定 + `setHoverInfo` (= uMouseUV / uIsHovered の更新) する。
+     * mousemove イベントから切り離すことで全 plane の uniform が 1 tick = 1 確定値で
+     * 揃い、paint と同期する。
+     */
+    private _updateHoverFromMouse;
+    destroy(): void;
+    private animate;
+}

package/dist/Dom3DObject.d.ts

@@ -0,0 +1,74 @@
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { Create3DObjectOptions } from './types';
+import * as THREE from "three";
+/**
+ * DOM 要素の位置・サイズに合わせて GLTF モデルを配置するクラス。
+ *
+ * **element の扱い**:
+ * - `HTMLElement` 指定: DOM 要素位置に追従。bbox 正規化と DOM サイズに対する scale
+ *   フィットを行う。
+ * - `null` 指定: scene 原点に固定（モデル本来のサイズ × userScale）。
+ *   ScrollSync 無効時はそのまま viewport 中心に固定される。
+ *   ScrollSync 有効時でも Lenis 等で JS rAF と paint の scrollY が同一に揃っていれば
+ *   container が viewport に厳密固定され、scene 原点固定 obj も viewport 上で
+ *   ズレなく見える。
+ *
+ * **エフェクトについて**: `DomPlane` と異なり `addEffect()` API は持たない。
+ * 任意 3D モデル単体に局所ポストエフェクトを当てるのは Plane と違って
+ * 1) 任意視点からの再投影が必要、2) 透視テクスチャ再貼り付けでクオリティが落ちる
+ * といった問題があり、汎用化が難しいため意図的に提供していない。
+ *
+ * モデル全体に効くエフェクトを掛けたい場合は `WebGLApp.addEffect()` で
+ * 画面全体のポストエフェクトとして適用する。
+ * モデル個別にエフェクトが必要な場合は `getModel()` で `THREE.Group` を取り出し、
+ * カスタムマテリアル/シェーダーで対応すること。
+ *
+ * **IntersectionObserver について**: `DomPlane` と違い `onInView` / `onOutView` /
+ * `inViewRepeat` / `inViewRootMargin` は提供していない。Dom3DObject は GLTF を
+ * scene に置く性質上「画面外で非表示にして無駄な描画を避ける」用途に絞られ、
+ * 進行状況通知やリセット系のコールバックは Plane より使い所が薄いため。
+ * 必要なら利用側で `getModel()` を取り出して自前で IntersectionObserver を組む。
+ * element=null の場合は IntersectionObserver は作らない（常に表示）。
+ */
+export declare class Dom3DObject {
+    element: HTMLElement | null;
+    model: THREE.Group | null;
+    loader: GLTFLoader;
+    mainScene: THREE.Scene;
+    canvasRect: DOMRect;
+    options: Create3DObjectOptions;
+    isVisible: boolean;
+    private positionCalculator;
+    private updateRectEveryFrame;
+    private observer;
+    private destroyed;
+    constructor(element: HTMLElement | null, mainScene: THREE.Scene, canvasRect: DOMRect, options: Create3DObjectOptions);
+    /**
+     * Phase B-read (DOM read): getBoundingClientRect のみ。
+     * Core.animate で paint 直前にまとめて呼ばれる。
+     * element=null の場合は何もしない（scene 原点固定で DOM 追従不要）。
+     *
+     * **更新条件**: `updateRectEveryFrame: true` のときのみ毎フレ更新。
+     * 自身の CSS animation で動的に位置が変わるケースのみ true に。
+     * (旧仕様では isFixed で自動毎フレ更新していたが、多くの場合不要な layout 強制
+     *  になっていたため明示フラグ駆動に変更)
+     * @internal Core.animate から呼ばれる。
+     */
+    _tickRead(): void;
+    /**
+     * Phase B-apply: model.position の書き込み。
+     * DOM あり/なしどちらでも `setPosition` を呼ぶ。setPosition 内部で positionCalculator の
+     * null を扱うため、DOM なしは offset のみ反映される（後から options.offset を書き換えても
+     * 毎フレ反映される一貫性を担保）。
+     * @internal Core.animate から呼ばれる。
+     */
+    _tickApply(scrollX: number, scrollY: number): void;
+    private loadModel;
+    private setupModel;
+    private applyScale;
+    private setPosition;
+    setCanvasRect(canvasRect: DOMRect): void;
+    resize(): void;
+    getModel(): THREE.Group<THREE.Object3DEventMap> | null;
+    destroy(): void;
+}