dom-sync-gl 0.0.1

package/dist/DomPlane.d.ts

@@ -0,0 +1,130 @@
+import { default as GUI } from 'lil-gui';
+import { CreatePlaneOptions } from './types';
+import { DomPositionCalculator } from './DomPositionCalculator';
+import { BaseEffect } from './effects/BaseEffect';
+import * as THREE from "three";
+export declare class DomPlane {
+    element: HTMLElement | null;
+    texture: THREE.Texture | null;
+    mesh: THREE.Mesh;
+    geometry: THREE.PlaneGeometry;
+    material: THREE.ShaderMaterial;
+    scene: THREE.Scene;
+    clock: THREE.Clock;
+    positionCalculator: DomPositionCalculator | null;
+    canvasRect: DOMRect;
+    isVisible: boolean;
+    private updateRectEveryFrame;
+    private observer;
+    private destroyed;
+    private planeComposer;
+    private renderer;
+    private effects;
+    /**
+     * effect.update に渡す mouse UV のスクラッチ。
+     * `material.uniforms.uMouseUV.value` を直接渡すと effect 側で `.set()` 等の破壊的操作で
+     * plane の uniform が書き換わる事故が起きうるため、毎フレ copy したスクラッチを渡す。
+     */
+    private readonly _effectMouseUV;
+    /**
+     * effect の `setupGUI` 呼び出し時に root GUI を渡すための provider。
+     * WebGLApp.createPlane() でセットされる。null の時は GUI を作らない（showGUI: false 等）。
+     *
+     * lil-gui は optional peer の dynamic import なので Promise を返す。
+     * @internal
+     */
+    private guiProvider;
+    /** 自前で load した texture かどうか。destroy() で dispose してよいか判定する。 */
+    private ownsTexture;
+    /**
+     * options.crossOrigin を指定された場合のみ生成する per-instance loader。
+     * 指定なしの場合は sharedTextureLoader をそのまま使う。
+     */
+    private crossOrigin;
+    constructor(el: HTMLElement | null, scene: THREE.Scene, canvasRect: DOMRect, renderer: THREE.WebGLRenderer, options?: CreatePlaneOptions, sharedClock?: THREE.Clock);
+    /**
+     * Phase B-read (DOM read): getBoundingClientRect 等のレイアウト読み取りのみを行う。
+     * Core.animate では paint 直前にまとめて呼ばれ、その直後に _tickApply が走る。
+     *
+     * **更新条件**: `updateRectEveryFrame: true` のときのみ毎フレ更新する。
+     * static 要素は document 座標で固定 / fixed 要素は viewport 座標で固定なので、
+     * 自身の CSS animation 等で動的に位置が変わるケースのみフラグを true に。
+     * (旧仕様では isFixed のとき自動的に毎フレ更新していたが、多くの場合不要な
+     *  layout 強制になっていたため明示フラグ駆動に変更)
+     * @internal Core.animate から呼ばれる。
+     */
+    _tickRead(): void;
+    /**
+     * Phase B-apply: mesh.position と uniforms の書き込み。DOM には触れない。
+     * @internal Core.animate から呼ばれる。
+     */
+    _tickApply(elapsedTime: number, scrollX: number, scrollY: number): void;
+    /**
+     * Phase C (PlaneComposer render): main scene レンダリング前に
+     * 自前の plane をローカル FBO に焼いてエフェクトを通す。
+     * @internal Core.animate から呼ばれる。
+     */
+    _tickRenderComposer(): void;
+    private init;
+    private loadTexture;
+    private updateSize;
+    private setPosition;
+    setCanvasRect(canvasRect: DOMRect): void;
+    resize(): void;
+    getMesh(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    /**
+     * テクスチャを差し替える。
+     * 直接 `material.uniforms.uTexture.value = tex` する代わりに使うと、
+     * 旧テクスチャの所有権（自前 load かどうか）を考慮して安全に dispose してくれる。
+     *
+     * @param texture 新しい texture
+     * @param takeOwnership true なら destroy() 時にこの texture も dispose する。
+     *                      他で使い回す texture を渡すときは false。
+     */
+    /**
+     * 現在の `data-texture` 属性を再読込してマテリアルに反映する。
+     * SPA で plane を貼ったまま画像 URL だけ差し替えたいケース用。
+     * 旧 texture が自前 load の場合は dispose する。属性が無ければ何もしない。
+     */
+    reloadTexture(): void;
+    setTexture(texture: THREE.Texture, takeOwnership?: boolean): void;
+    /**
+     * 紐づけられたエフェクトに update を流す。Core.animate から呼ばれる。
+     *
+     * 引数 `globalMouse` は canvas 全体の UV（0〜1, Y-up）。これを **plane ローカルの UV** に変換して
+     * effect.update に渡す。これで FluidEffect 等が plane の中の座標として mouse を扱える。
+     *
+     * - フルスクリーン plane（element 無し）: そのまま globalMouse を渡す
+     * - DOM 配置 plane: 自分の DOM rect と canvasRect から local UV を算出
+     * - マウスが plane の外にいる時は **last value を据え置き**（uv 更新せず）。
+     *   これにより solver 側で delta が 0 になり force が立たない、自然な挙動になる。
+     *
+     * 注意: raycast には依存しない。PlaneComposer が sourceMesh を main scene から外すと
+     * raycast が思った通り当たらないケースがあるため。
+     *
+     * scrollX/Y は Core.animate が 1 rAF tick 上で 1 回確定したスナップショット値を渡す。
+     * ここで `window.scrollX/Y` を直接読むと
+     *（同一 frame で全コンポーネントが同じ scroll 値を共有する）を壊すため必ず引数経由。
+     * 後方互換のため省略可能だが、その場合は window から読む (= 古い挙動)。
+     */
+    updateEffects(time: number, globalMouse?: THREE.Vector2, scrollX?: number, scrollY?: number): void;
+    /** 直近の plane ローカル UV を取得（updateEffects 内で算出された値、0〜1）。 */
+    getMouseUV(): THREE.Vector2;
+    /** マウスが現在 plane の上に乗っているかどうか。 */
+    isHovered(): boolean;
+    setHoverInfo(isHovered: boolean, uv: THREE.Vector2 | null): void;
+    private enableEffects;
+    addEffect<T extends BaseEffect>(effect: T): T;
+    /**
+     * `addEffect()` で登録した effect を取り除き、pass material を dispose する。
+     * 登録されていない effect を渡した時は何もしない（戻り値 false）。
+     */
+    removeEffect(effect: BaseEffect): boolean;
+    /**
+     * WebGLApp.createPlane() から呼ばれる。GUI lazy 取得関数を渡す。
+     * null を渡すと GUI 統合を無効化（showGUI: false 相当）。
+     * @internal
+     */
+    _setGuiProvider(provider: (() => Promise<GUI>) | null): void;
+    destroy(): void;
+}

package/dist/DomPositionCalculator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * DOM要素の位置計算を担当するユーティリティクラス
+ */
+export declare class DomPositionCalculator {
+    private element;
+    private canvasRect;
+    private positionInfo;
+    rect: DOMRect;
+    private readonly _outPosition;
+    constructor(element: HTMLElement, canvasRect: DOMRect);
+    /**
+     * DOM要素の位置情報を更新（毎フレーム呼ばれる）
+     */
+    updatePositionInfo(): void;
+    /**
+     * position: fixed または sticky かどうかを再チェック（初期化・リサイズ時のみ呼ぶ）。
+     * fixed / sticky 要素は document 上で位置が固定されないため、毎フレーム rect.top を
+     * viewport 座標として扱う isFixed branch を使う。
+     */
+    refreshPositionType(): void;
+    /**
+     * WebGL座標系での位置を計算。
+     * 戻り値は内部バッファを使い回すため、保持する場合は呼び出し側でコピーすること。
+     */
+    calculateWebGLPosition(scrollX?: number, scrollY?: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Canvas矩形を更新
+     */
+    setCanvasRect(canvasRect: DOMRect): void;
+    /**
+     * position: fixedかどうか
+     */
+    get isFixed(): boolean;
+    /**
+     * ページトップ位置
+     */
+    get pageTop(): number;
+    /**
+     * ページレフト位置
+     */
+    get pageLeft(): number;
+}

package/dist/EffectComposer.d.ts

@@ -0,0 +1,72 @@
+import * as THREE from 'three';
+/**
+ * `WebGLApp.setPostEffect()` で差し込めるポストエフェクトの最小契約。
+ * `EffectComposer` は実装している。自前で差し込みたい場合は構造的にこれを満たせばよい。
+ */
+export interface EffectLike {
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    resize(width: number, height: number): void;
+    dispose(): void;
+}
+export interface EffectOptions {
+    fragmentShader: string;
+    uniforms?: {
+        [key: string]: THREE.IUniform;
+    };
+}
+export interface EffectTarget {
+    addEffect(options: EffectOptions): EffectPass;
+}
+/**
+ * addEffect() で返されるハンドル。uniform の更新に使う。
+ */
+export declare class EffectPass {
+    readonly material: THREE.ShaderMaterial;
+    /** false の時、EffectComposer はこのパスをスキップする（パススルー扱い）。 */
+    enabled: boolean;
+    constructor(material: THREE.ShaderMaterial);
+    setUniform(key: string, value: unknown): void;
+    getUniform(key: string): THREE.IUniform | undefined;
+}
+/**
+ * 複数のポストエフェクトをチェーンで適用するクラス。
+ *
+ * RenderTarget はピンポン方式で2つのみ使用。
+ * エフェクト数に関わらずメモリ使用量は一定。
+ *
+ * render flow (エフェクト3つの場合):
+ *   scene → TargetA
+ *   pass1: A → B
+ *   pass2: B → A
+ *   pass3: A → canvas (null)
+ */
+export declare class EffectComposer implements EffectTarget, EffectLike {
+    private renderer;
+    private passes;
+    private targetA;
+    private targetB;
+    private postScene;
+    private postCamera;
+    private postMesh;
+    private geometry;
+    /**
+     * dispose 後の API 呼び出しを no-op にするフラグ。
+     * dispose 済みの RT に render すると INVALID_OPERATION になるため。
+     */
+    private _disposed;
+    constructor(renderer: THREE.WebGLRenderer, width: number, height: number);
+    addEffect(options: EffectOptions): EffectPass;
+    /**
+     * 登録済みパスを 1 つ取り除いて material を dispose する。
+     * `addEffect()` の戻り値か、`BaseEffect.getPass()` の値を渡す。
+     * 存在しない pass を渡した時は何もしない。
+     */
+    removeEffect(pass: EffectPass): boolean;
+    /**
+     * シーンをレンダリングし、登録されたエフェクトを順に適用する。
+     * エフェクトが0個の場合は通常レンダリング。
+     */
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    resize(width: number, height: number): void;
+    dispose(): void;
+}

package/dist/Light.d.ts

@@ -0,0 +1,18 @@
+import * as THREE from "three";
+/**
+ * シンプルな環境光 + 平行光の組み合わせを scene に追加するクラス。
+ *
+ * **制約**:
+ * - shadow（影）は無効。`castShadow` / `receiveShadow` を有効化したい場合は
+ *   `directionalLight.castShadow = true` を外から設定し、別途 shadow map 設定が必要。
+ *
+ * 簡易ライティングで十分なケースを想定。複雑なライト設計が必要なら、
+ * `WebGLApp.getLight()` から内部 light を取り出して直接操作するか、
+ * `WebGLApp.getScene()` に独自ライトを追加する。
+ */
+export declare class Light {
+    readonly ambientLight: THREE.AmbientLight;
+    readonly directionalLight: THREE.DirectionalLight;
+    private readonly scene;
+    constructor(scene: THREE.Scene);
+}

package/dist/PlaneComposer.d.ts

@@ -0,0 +1,70 @@
+import { EffectOptions, EffectTarget, EffectPass } from './EffectComposer';
+import * as THREE from 'three';
+/**
+ * DomPlane 単体にエフェクトチェーンを適用するクラス。
+ *
+ * render flow:
+ *   plane.mesh (local scene) → targetA
+ *   pass1: A → B
+ *   pass2: B → A
+ *   ...
+ *   final target → proxyMesh.material.map (main scene に表示)
+ *
+ * plane.mesh はコンストラクト時に main scene から取り出し local scene へ移動。
+ * proxyMesh がその位置に差し替わり、エフェクト適用後のテクスチャを表示する。
+ *
+ * **制約・落とし穴**:
+ * - main scene に置く `proxyMesh` は固定で `MeshBasicMaterial({ transparent: true })`。
+ *   `DomPlane` 本体の `ShaderMaterial` の depthWrite / depthTest / blending 設定は反映されない。
+ *   不透明背景のシーンに混ぜると z 順がおかしく見えることがある（透過レイヤ前提のデザイン推奨）。
+ * - `localMesh` は `sourceMesh.geometry` / `material` を**共有**して描画する。
+ *   `DomPlane.setHoverInfo()` 等で uniform を更新すれば自動でこちらにも反映される。
+ *   ただし raycast の hit ターゲットは main scene にある `proxyMesh`（material が違う）に
+ *   なるため、`uv` 結果は plane の物理位置に対して正しく出る。
+ * - `addEffect` を 0 回しか呼ばないケースでも `render()` は targetA 経由でプロキシに焼く。
+ *   この場合 proxy はエフェクトなしの sourceMesh の見た目をそのまま表示する。
+ */
+export declare class PlaneComposer implements EffectTarget {
+    private renderer;
+    private sourceMesh;
+    private passes;
+    private targetA;
+    private targetB;
+    private localScene;
+    private localCamera;
+    private localMesh;
+    private postScene;
+    private postCamera;
+    private postMesh;
+    private postGeo;
+    private proxyMesh;
+    private proxyMaterial;
+    private proxyGeo;
+    private mainScene;
+    /**
+     * 全 effect が enabled=false の時、PlaneComposer をスキップして sourceMesh を
+     * 直接 main scene で描画する状態（bypass）。 fullscreen pass 1 回ぶんを丸ごと
+     * 削減できる。effect が再度 enable された時は通常レンダリングに復帰する。
+     */
+    private _bypassed;
+    /** dispose 済みフラグ。dispose 後の render / addEffect を no-op にする。 */
+    private _disposed;
+    constructor(renderer: THREE.WebGLRenderer, sourceMesh: THREE.Mesh, mainScene: THREE.Scene, width: number, height: number);
+    addEffect(options: EffectOptions): EffectPass;
+    /**
+     * 登録済みパスを 1 つ取り除いて material を dispose する。
+     * 存在しない pass を渡した時は何もしない。
+     */
+    removeEffect(pass: EffectPass): boolean;
+    /**
+     * bypass 状態に切り替える: sourceMesh を main scene に戻し proxyMesh を隠す。
+     * 全 effect が disabled の時に呼ばれ、PlaneComposer.render の fullscreen pass を
+     * まるごと省く (= 1 pass / 6.35M フラグメント分の節約)。
+     */
+    private enterBypass;
+    /** bypass 状態から通常レンダリングへ復帰する。 */
+    private exitBypass;
+    render(): void;
+    resize(width: number, height: number): void;
+    dispose(): void;
+}

package/dist/RafScroll.d.ts

@@ -0,0 +1,104 @@
+/**
+ * RafScroll — rAF 同期 virtual scroll の最小実装。
+ *
+ * wheel / touch を `preventDefault` で受け取り、内部 accumulator に加算した値を
+ * 毎 rAF tick で `window.scrollTo()` に流す。
+ *
+ * これにより:
+ * - `window.scrollY` が **rAF tick 上でのみ更新**される
+ * - JS rAF 時の `window.scrollY` と paint 時の actual scroll が同一フレームで揃う
+ * - ScrollSync の cancel (container.transform と sceneY 計算で同じ scrollY を
+ *   共有する不変条件) が paint 時まで厳密に成立する
+ *
+ * Lenis から「rAF 同期に必要な最小機能」だけ抜き出した実装。wheel/drag 中の smoothing
+ * は無し (`lerp: 1` 相当)、accessibility (キーボードスクロール) や programmatic scroll
+ * (`window.scrollTo` 外部呼び出し) との同期は対応しない。
+ *
+ * **touch 慣性 (momentum)**: ネイティブ touch scroll を `preventDefault` で抑止する以上、
+ * OS が提供する慣性も失われる。代わりに自前で実装する:
+ * - `touchmove` で指の速度 (px/ms) を EMA 平滑化しつつ追跡
+ * - `touchend` 時点の velocity を初速として rAF tick 上で指数減衰させて scrollY に積む
+ * - 端到達 (clamp) / 次の touchstart / wheel 入力で慣性は即キャンセル
+ *
+ * @see https://github.com/darkroomengineering/lenis (元設計)
+ */
+export interface RafScrollOptions {
+    /**
+     * `WheelEvent.deltaMode === DOM_DELTA_LINE` のとき 1 行あたりの pixel 数。
+     * Firefox の wheel が deltaMode=1 を返すケースで使われる。
+     * @default 16
+     */
+    lineHeight?: number;
+    /**
+     * touch リリース後の慣性減衰率。16.67ms 換算 1 フレームあたり velocity に乗算される値。
+     * 1 に近いほど慣性が長く続き、0 に近いほどすぐ止まる。0 で慣性無効 (即時停止)。
+     * @default 0.95
+     */
+    touchFriction?: number;
+}
+export declare class RafScroll {
+    private _scrollY;
+    /**
+     * 直近 `window.scrollTo` に渡した値。scrollY が変わっていないフレで
+     * scrollTo を no-op で呼ぶと scroll event が連発して page 側 listener を
+     * 無駄に叩くので、差分があるときだけ呼び出すための diff キャッシュ。
+     */
+    private _lastAppliedY;
+    private _maxScroll;
+    private _rafId;
+    private _enabled;
+    private _lineHeight;
+    private _friction;
+    private _touchPrevY;
+    private _touchPrevTime;
+    /** 直近の touch velocity (px/ms)。touchend 後はこの値を初速に慣性が走る。 */
+    private _velocityY;
+    private _isTouching;
+    /** tick() の dt 計算用。0 のとき初回 tick (dt は FRAME_MS で初期化)。 */
+    private _lastTickTime;
+    private _eventAbort;
+    private _resizeObserver;
+    private _destroyed;
+    constructor(options?: RafScrollOptions);
+    private calcMaxScroll;
+    private setupEventListeners;
+    /**
+     * document の scrollHeight が動的に変わる場合 (画像 lazy load、SPA でのコンテンツ追加 等)
+     * に maxScroll を追従させる。ResizeObserver で `<html>` を観察する。
+     */
+    private setupResizeObserver;
+    private onWheel;
+    private onTouchStart;
+    private onTouchMove;
+    private onTouchEnd;
+    private onResize;
+    private clamp;
+    /**
+     * 毎 rAF で `window.scrollTo` を呼ぶ。これが Lenis 方式の核心:
+     * scrollY の更新タイミングを「JS rAF tick 上だけ」に集約することで、
+     * paint 時に見える scrollY と JS が知る scrollY が完全一致する。
+     *
+     * 同値時は no-op で呼ばない (scroll event の連発で page 側 listener を
+     * 叩くのを避ける)。
+     *
+     * touch リリース後の慣性: `_velocityY` が閾値以上ある間、毎 tick で
+     * `scrollY += velocity * dt` を積みつつ `velocity *= friction^(dt/FRAME_MS)` で減衰。
+     */
+    private tick;
+    /** 現在の virtual scrollY。 */
+    get scrollY(): number;
+    /**
+     * 入力受付の有効/無効。
+     *
+     * disable 中は wheel/touch ハンドラが **preventDefault する前に** early-return するため、
+     * native スクロールが復活する（virtual scroll を一時停止して通常スクロールに戻したい
+     * ケース用）。accumulator (`_scrollY`) も更新されず、慣性も止まる。
+     *
+     * 再 enable 時は `_scrollY` / `_lastAppliedY` を現在の `window.scrollY` に再同期して
+     * disable 中の native scroll とのズレを吸収する（同期しないと次の wheel/touch 入力で
+     * 古い `_scrollY` からの delta になり巨大ジャンプする）。
+     */
+    set enabled(value: boolean);
+    get enabled(): boolean;
+    destroy(): void;
+}

package/dist/ScrollSync.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ScrollSync — WebGL スクロール同期。
+ *
+ * container 要素を `position: absolute; top: 0; left: 0` で document に貼り、毎 rAF で
+ * 1 回読んだ `scrollX/Y` を transform に流す。**同じ scrollX/Y を DomPlane の sceneY 計算
+ * にも渡してもらう**ことで、paint 時に scroll が進んで rAF↔paint Δ が出ても container と
+ * plane が一緒にズレる → 視覚的に DOM ↔ mesh は完璧に一致する。
+ *
+ * **scrollHeight 非侵襲**:
+ * 単純に `height = viewport * (1 + 2*padding)` を貼ると、container の layout box が
+ * `1 + 2*padding` 倍の高さを占有し、body の scrollHeight を底上げしてしまう
+ * （コンテンツが短いページや、スクロール末尾で「実コンテンツを越えて余白までスクロール」
+ *  できる現象）。
+ *
+ * 対策として **毎フレ effective padding を `body.scrollHeight - scrollY - viewport`
+ * でクランプ**する（`#updateCanvasSize` と同じ formula）。
+ *   - 長いページ + 上の方にいる: requested = effective（フル padding）
+ *   - 末尾に近づく: max が縮み effective も縮む → container も縮む
+ *   - 末尾ぴったり: effective = 0 → container = viewport ぴったり
+ *
+ * canvas drawing buffer も同期して resize する必要があるため、resize 通知 callback を
+ * `setResizeCallback()` で受け取る。Core 側でこの callback に `renderer.setSize` /
+ * `camera.resize` / `postEffect.resize` を繋ぐ。
+ *
+ */
+export interface ScrollSyncOptions {
+    /**
+     * 上下パディング比率（0〜1）。canvas の高さを viewport * (1 + padding * 2) にし、
+     * rAF↔paint 間の scroll 進行で canvas が viewport から欠ける現象を吸収する。
+     * 末尾に近づくと effective 値は自動でクランプされ、body.scrollHeight を底上げしない。
+     * @default 0
+     */
+    padding?: number;
+    /**
+     * スクロール強度（速度）を strength getter で提供するか。
+     * @default false
+     */
+    trackStrength?: boolean;
+    /**
+     * strength の減衰速度。
+     * @default 10
+     */
+    strengthDecay?: number;
+}
+export declare class ScrollSync {
+    private container;
+    private _padding;
+    private _trackStrength;
+    private _strengthDecay;
+    private _strength;
+    private _prevScrollY;
+    private _prevTime;
+    private _viewportWidth;
+    private _viewportHeight;
+    private _enabled;
+    /**
+     * container の **元 CSS 指定** を window に対する比率として保持する。
+     *
+     * 例: container の CSS が `width: 100vw; height: 110vh` なら
+     *   _widthRatio = 1.0, _heightRatio = 1.1
+     *
+     * `applyContainerStyles()` で container は `position: absolute; width/height = JS制御`
+     * に書き換えられて以降「元の CSS による intrinsic size」は測れなくなる。よって
+     * **constructor 進入時** に getBoundingClientRect から ratio を snapshot し、以降の
+     * resize ではこの ratio を window 寸法に掛けて canvas 物理サイズを決める。
+     *
+     * これにより `#canvas { width: 100vw; height: 110vh; }` のような CSS が
+     * window resize / orientation 変更後も「100vw × 110vh」相当を保ち続ける。
+     */
+    private _widthRatio;
+    private _heightRatio;
+    /**
+     * 現在 transform / canvas 寸法に反映している padding 値（px）。
+     * クランプの出力。`_padding * viewportHeight` の上限と、document の余り
+     * 領域の最小から決まる。
+     */
+    private _effectivePaddingPx;
+    /** 計算用の canvas rect（scroll transform を含まない論理 rect、effective padding 基準） */
+    private _logicalRect;
+    /**
+     * effective padding が変わって canvas drawing buffer の resize が必要な時に呼ぶ callback。
+     * 引数は `{ width, height }`（drawing buffer の新サイズ = container の新サイズ）。
+     * Core 側でこれに `renderer.setSize` / `camera.resize` / `postEffect.resize` をぶら下げる。
+     */
+    private _onResize;
+    /**
+     * destroy 時の復元用に、constructor 進入時の inline style を退避しておく。
+     * ユーザーが先に `container.style.position = 'relative'` などを当てていた場合に、
+     * destroy で「空文字に潰す」ではなく元の値に戻すために必要。
+     */
+    private _originalStyles;
+    constructor(container: HTMLElement, options?: ScrollSyncOptions);
+    private applyContainerStyles;
+    /**
+     * ビューポートサイズが変わった時に呼ぶ。effective padding は requested で初期化し、
+     * 次の update() 呼び出しでクランプが効く。
+     *
+     * 引数を省略した場合は、constructor で snapshot した container の CSS ratio を
+     * window 寸法に掛けて自動算出する。明示的に値を渡せば override 可能（scrollbar を
+     * 差し引いた幅にしたい等のケース）。
+     */
+    updateSize(wrapperWidth?: number, wrapperHeight?: number): void;
+    /**
+     * 毎 rAF で呼ぶ。**plane の sceneY 計算と同一の scrollX/Y を渡すこと**。
+     * これが cancel の不変条件。
+     *
+     * padding clamp:
+     *   maxPaddingY = body.scrollHeight - scrollY - viewportHeight
+     *   effective   = clamp(requested, 0, maxPaddingY)
+     * effective が変わったら canvas drawing buffer も同期して resize する。
+     */
+    update(scrollX: number, scrollY: number): void;
+    private applyTransform;
+    /** スクロール速度ベースの strength 値を更新。 */
+    private updateStrength;
+    /**
+     * canvas drawing buffer の resize が必要な時に呼ばれる callback を登録する。
+     * @internal Core 側で renderer.setSize / camera.resize / postEffect.resize を繋ぐ。
+     */
+    setResizeCallback(cb: (size: {
+        width: number;
+        height: number;
+    }) => void): void;
+    /**
+     * DomPositionCalculator 用の **論理** rect。
+     *
+     * **注意**: これは「ブラウザ上での canvas の getBoundingClientRect」ではない。
+     * `top = -effectivePadding`, `height = viewport + 2 * effectivePadding` で、
+     * scroll に追従して動く container 内のローカル座標系を表す。effective padding は
+     * 末尾近くで自動的に縮む。
+     */
+    get logicalRect(): DOMRect;
+    /** 現在の effective padding（px）。テスト・デバッグ用。 */
+    get effectivePadding(): number;
+    /**
+     * 現在のスクロール速度（0〜1 にクランプ）。
+     *
+     * **`trackStrength: false` で構築している場合は常に 0 を返す**。値を使いたい場合は
+     * options で trackStrength を true にして構築すること。DEV では誤用防止のため
+     * 1 度だけ console.warn を出す。
+     */
+    get strength(): number;
+    private _warnedStrength;
+    get padding(): number;
+    /**
+     * 入力受付の有効/無効。
+     *
+     * disable 中は `update()` が no-op になり container の transform は触らない（disable 直前の
+     * 位置で固定される）。enable に戻したフレから transform 更新が再開する。
+     *
+     * disable で「container を素の状態に戻したい」場合は `destroy()` を呼ぶこと。
+     */
+    set enabled(value: boolean);
+    get enabled(): boolean;
+    destroy(): void;
+}

package/dist/constants.d.ts

@@ -0,0 +1,27 @@
+export declare const CAMERA_FOV = 60;
+export declare const CAMERA_NEAR = 0.1;
+/**
+ * Camera の far plane。座標系は「DOM 1px = WebGL 1unit」。
+ * カメラ距離は `viewport高 / 2 / tan(fov/2)` で ~519px (viewport=600px) 前後になるため
+ * far=10000 はかなり余裕がある（カメラ距離の ~20 倍）。
+ *
+ * **注意**: near=0.1 / far=10000 で精度レンジが 5 桁開いており、z 軸を奥行きに
+ * 積極的に使うと z-fighting / shadow map の精度劣化が出やすい。
+ * 奥行き表現を多用する場合は near/far をユースケースに合わせて絞ること。
+ */
+export declare const CAMERA_FAR = 10000;
+export declare const DEFAULT_SCALE = 1;
+export declare const DEFAULT_OFFSET: {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare const AMBIENT_LIGHT_COLOR = 16777215;
+export declare const AMBIENT_LIGHT_INTENSITY = 0.5;
+export declare const DIRECTIONAL_LIGHT_COLOR = 16777215;
+export declare const DIRECTIONAL_LIGHT_INTENSITY = 1;
+export declare const DIRECTIONAL_LIGHT_POSITION: {
+    x: number;
+    y: number;
+    z: number;
+};